Skip to content

Pipeline Design 6

Jump to bottom
Seth Ford edited this page Feb 12, 2026 · 2 revisions

Design: shipwright doctor should validate dashboard dependencies and port availability

Context

shipwright doctor (scripts/sw-doctor.sh) validates the entire Shipwright setup across 13 numbered sections (tmux, Claude Code, GitHub, etc.) but has no checks for the dashboard subsystem. Users who run shipwright dashboard without Bun installed, without dashboard files present, or with port 8767 already occupied get opaque failures. The doctor command should catch these issues proactively.

Constraints:

  • Bash 3.2 compatible (no associative arrays, readarray, ${var,,})
  • set -euo pipefail throughout
  • Dashboard is optional — all checks must use check_warn, never check_fail
  • Default dashboard port is 8767 (confirmed in dashboard/server.ts:18 and scripts/sw-dashboard.sh:43)
  • Doctor currently defines _DOCTOR_SCRIPT_DIR (line ~864) which can be reused for relative path resolution
  • Existing test harness pattern: mock binaries in sandboxed $PATH, PASS/FAIL counters, ERR trap

Decision

Add a new Section 14: Dashboard to sw-doctor.sh between the GitHub Integration section (13) and the Summary block. The section performs three checks:

  1. Bun runtime — command -v bun with version display; warn with install URL if missing
  2. Dashboard files — Search repo-relative dashboard/server.ts first, then fallback to ~/.local/share/shipwright/dashboard and ~/.shipwright/dashboard; separately check public/index.html for frontend assets
  3. Port 8767 availability — Use lsof -iTCP:8767 -sTCP:LISTEN if available; skip gracefully if lsof not found

All checks emit check_warn on failure (not check_fail) since the dashboard is an optional feature. This matches how Section 13 (GitHub) uses warns for missing gh CLI.

The test suite follows the established pattern from sw-connect-test.sh: sandboxed HOME, mock binaries directory prepended to PATH, full doctor invocation with output capture and string matching.

Alternatives Considered

  1. Add checks inside sw-dashboard.sh startup — Pros: checks run only when dashboard is actually needed / Cons: doesn't provide proactive diagnosis; doctor is the canonical "is everything set up?" command; users expect doctor to surface all issues
  2. Use check_fail for missing Bun — Pros: stronger signal / Cons: dashboard is optional; a failing doctor check for an optional feature frustrates users who never use the dashboard; check_warn is correct severity
  3. Check port via ss instead of lsof — Pros: ss is standard on Linux / Cons: macOS (primary target) ships lsof but not ss; lsof is the better cross-platform choice; we already skip gracefully if neither is available
  4. Use nc -z for port check — Pros: widely available / Cons: behavior varies across BSD vs GNU netcat; lsof directly queries the kernel socket table which is more reliable for checking listener state

Implementation Plan

  • Files to create:

    • scripts/sw-doctor-test.sh — New test suite (~12 test cases)

  • Files to modify:

    • scripts/sw-doctor.sh — Insert Section 14 (~45 lines) between Section 13 and Summary
    • package.json — Append && bash scripts/sw-doctor-test.sh to "test" script (suite #23)

  • Dependencies: None new. Bun is checked-for, not required.

  • Risk areas:

    • _DOCTOR_SCRIPT_DIR must already be defined before Section 14 runs (it is — set in Section 13 at line ~864)
    • lsof flag syntax differs slightly across platforms; -iTCP:8767 -sTCP:LISTEN is POSIX-compatible and works on both macOS and Linux
    • Mock environment for tests must include all prerequisite mocks (tmux, jq, claude, git, gh, node) since doctor runs all 14 sections — a missing mock causes early set -e exit before reaching Section 14

Validation Criteria

  • shipwright doctor outputs a "DASHBOARD" section header with Bun, file, and port checks
  • Bun check shows version when installed, shows bun.sh/install URL when missing
  • Dashboard file search covers repo-relative path + two fallback locations
  • Port check uses 8767, warns when in use, skips gracefully without lsof
  • All dashboard checks use check_warn/check_pass — never check_fail
  • sw-doctor-test.sh contains 10+ tests covering all positive and negative branches
  • sw-doctor-test.sh registered in package.json as test suite #23
  • All 23 test suites pass (npm test)
  • Script is Bash 3.2 compatible — no associative arrays, no readarray, no ${var,,}
  • No regressions in existing doctor sections 1-13

Clone this wiki locally