Pipeline Plan 6

The file is protected as sensitive. Let me output the plan directly instead.

Here is the implementation plan:

---

Implementation Plan: Dashboard Validation in shipwright doctor

Summary

Add a new Section 14: Dashboard to scripts/sw-doctor.sh that validates Bun runtime availability, dashboard file existence, and port availability. Create a corresponding test suite scripts/sw-doctor-test.sh and register it in package.json.

Files to Modify

File	Action	Purpose
scripts/sw-doctor.sh	Modify	Add Section 14 (Dashboard) before the Summary block
scripts/sw-doctor-test.sh	Create	New test suite for the dashboard validation checks
package.json	Modify	Register sw-doctor-test.sh in the test script chain

Implementation Steps

1. Add Section 14 to sw-doctor.sh

Insert between GitHub Integration (Section 13, ends ~line 886) and the Summary block (~line 888).

1a. Bun Runtime Check

• command -v bun — if found, check_pass "bun <version>"
• If missing, check_warn with install hint (curl -fsSL https://bun.sh/install | bash)
• Use check_warn (not check_fail) — Bun is optional, only needed for the dashboard feature

1b. Dashboard Files Check

• Look for dashboard/server.ts relative to the script's repo dir (same logic as sw-dashboard.sh's find_server())
• Fallback locations: ~/.local/share/shipwright/dashboard/ and ~/.shipwright/dashboard/
• Check dashboard/public/index.html at the same resolved location
• check_pass if found, check_warn if missing
• Note: _DOCTOR_SCRIPT_DIR is already defined on line 864; derive _DOCTOR_REPO_DIR from it

1c. Port Availability Check

• Default port: 8767 (from SHIPWRIGHT_DASHBOARD_PORT env var, matching dashboard/server.ts)
• Use lsof -i :<port> -sTCP:LISTEN to detect listening processes
• If port in use AND ~/.shipwright/dashboard.pid matches a running process → check_pass (our dashboard is already running)
• If port in use by something else → check_warn with hint to set SHIPWRIGHT_DASHBOARD_PORT
• If lsof unavailable → info skip message (no fail/warn)

2. Create scripts/sw-doctor-test.sh

Follow existing test harness pattern (PASS/FAIL counters, run_test(), mock binaries in $TEMP_DIR/bin, sandboxed HOME).

13 test cases:

Group	Test	What it verifies
Bun	test_bun_detected_when_present	Mock bun in PATH → pass output
Bun	test_bun_missing_shows_warning	No bun → warn + install hint
Bun	test_bun_version_displayed	Mock bun prints version → appears in output
Files	test_dashboard_server_ts_found	server.ts in repo → pass
Files	test_dashboard_server_ts_missing	No server.ts → warn
Files	test_dashboard_index_html_found	index.html in repo → pass
Files	test_dashboard_fallback_locations	server.ts in ~/.local/share/shipwright/dashboard/ → found
Port	test_port_available_when_free	Mock lsof exits 1 → pass "available"
Port	test_port_in_use_shows_warning	Mock lsof exits 0 → warn
Port	test_port_in_use_by_dashboard_shows_pass	Mock lsof exits 0 + PID file → pass
Port	test_port_check_skipped_without_lsof	No lsof → "skipping" info
Port	test_custom_port_from_env	SHIPWRIGHT_DASHBOARD_PORT=9999 → checks 9999
Integration	test_section_header_appears	"DASHBOARD" section header in output

Tests run the full doctor script as a subprocess with HOME=$TEMP_DIR/home and PATH prepended with mock bin dir.

3. Register Test Suite in package.json

Append && bash scripts/sw-doctor-test.sh to the end of the test script.

Task Checklist

• Task 1: Add Section 14 header and Bun runtime check to sw-doctor.sh
• Task 2: Add dashboard file existence checks to sw-doctor.sh
• Task 3: Add port availability check to sw-doctor.sh
• Task 4: Create sw-doctor-test.sh with test harness boilerplate
• Task 5: Write Bun detection tests (present, missing, version display)
• Task 6: Write dashboard file tests (server.ts, index.html, fallback locations)
• Task 7: Write port availability tests (free, in-use, dashboard-running, no-lsof, custom port)
• Task 8: Write integration test (section header appears)
• Task 9: Register sw-doctor-test.sh in package.json
• Task 10: Run sw-doctor-test.sh and verify all tests pass
• Task 11: Run full npm test and verify no regressions

Testing Approach

1. Unit tests via sw-doctor-test.sh — each check tested in isolation with mock binaries and sandboxed HOME
2. Manual smoke test — run shipwright doctor and verify the new DASHBOARD section renders correctly
3. Regression — run npm test to ensure all 23 test suites pass

Definition of Done

• shipwright doctor displays a "DASHBOARD" section with Bun check + install hint if missing
• Dashboard file existence (server.ts, public/index.html) verified with fallback location support
• Port 8767 (or SHIPWRIGHT_DASHBOARD_PORT) availability checked; gracefully skips if lsof unavailable
• Port occupied by our own dashboard process shows as pass, not warning
• New sw-doctor-test.sh test suite with 13+ tests, all passing
• Test suite registered in package.json
• All 23 test suites pass (npm test)
• No Bash 3.2 compatibility issues (no associative arrays, readarray, etc.)
• Follows existing code conventions (colors, check_pass/check_warn/check_fail, DIM hints)