Skip to content

Pipeline Plan 4

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

The plan has been developed. Here's the implementation plan for adding --json output flag to shipwright status:

Files to Modify

# File Action Purpose
1 scripts/sw-status.sh Modify Add --json flag, JSON collection, jq output
2 scripts/sw-status-test.sh Create Test suite with mock environment
3 completions/shipwright.bash Modify Bash tab completion for --json
4 completions/_shipwright Modify Zsh tab completion for --json
5 completions/shipwright.fish Modify Fish tab completion for --json
6 package.json Modify Register test suite

Architecture Decision: Separate Code Path (Early Exit)

Following the pattern from sw-cost.sh:550-670 and sw-daemon.sh:5119-5300, the --json flag triggers an entirely separate code path that collects data, builds JSON via jq -n, and exits before the display code runs. The existing 600-line display code remains completely untouched — zero regression risk.

JSON Schema

{
  "version": "1.10.0",
  "timestamp": "2026-02-12T...",
  "tmux_windows": [...],
  "teams": [...],
  "task_lists": [...],
  "daemon": { "running": bool, "pid": N, "active_jobs": [...], "queued": [...], "recent_completions": [...] },
  "issue_tracker": { "provider": "linear", "url": null },
  "heartbeats": [...],
  "remote_machines": [...],
  "connected_developers": { "reachable": bool, "total_online": N, "developers": [...] }
}

Empty/missing sections use null or [].

Task Checklist (15 tasks)

  • Task 1: Add --json flag parsing to sw-status.sh
  • Task 2: JSON collection for tmux windows
  • Task 3: JSON collection for team configs
  • Task 4: JSON collection for task lists
  • Task 5: JSON collection for daemon pipelines (active, queued, completions)
  • Task 6: JSON collection for issue tracker
  • Task 7: JSON collection for heartbeats
  • Task 8: JSON collection for remote machines
  • Task 9: JSON collection for connected developers
  • Task 10: Assemble final JSON with jq -n and exit
  • Task 11: Update bash completions
  • Task 12: Update zsh completions
  • Task 13: Update fish completions
  • Task 14: Create sw-status-test.sh (mock env, 10+ test cases)
  • Task 15: Register test in package.json

Definition of Done

  • shipwright status unchanged (no regression)
  • shipwright status --json outputs valid, ANSI-free JSON
  • All 8 dashboard sections represented in JSON
  • Empty state produces valid JSON with nulls/empty arrays
  • jq required check with clear error message
  • Tab completions for bash/zsh/fish
  • Test suite passes, registered in package.json
  • Bash 3.2 compatible, set -euo pipefail collected data into a single JSON object:
if [[ "$JSON_OUTPUT" == "true" ]]; then
    jq -n \
        --argjson tmux_windows "$WINDOWS_JSON" \
        --argjson teams "$TEAMS_JSON" \
        --argjson tasks "$TASKS_JSON" \
        --argjson daemon "$DAEMON_JSON" \
        --argjson tracker "$TRACKER_JSON" \
        --argjson heartbeats "$HEARTBEATS_JSON" \
        --argjson machines "$MACHINES_JSON" \
        --argjson developers "$DEVELOPERS_JSON" \
        --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
        --arg version "$VERSION" \
        '{
            version: $version,
            timestamp: $timestamp,
            tmux_windows: $tmux_windows,
            teams: $teams,
            tasks: $tasks,
            daemon: $daemon,
            tracker: $tracker,
            heartbeats: $heartbeats,
            remote_machines: $machines,
            connected_developers: $developers
        }'
    exit 0
fi

6. Update CLI router help text in scripts/sw

Change line 70:

  ${CYAN}status${RESET} [--json]        Show dashboard of running teams and agents

7. Create test suite scripts/sw-status-test.sh

Following the existing test harness pattern (mock environment, PASS/FAIL counters, ERR trap):

  • Mock tmux, jq, curl, kill binaries
  • Create fixture data (daemon-state.json, team configs, task files, heartbeat files, machines.json)
  • Test cases:
    • --json produces valid JSON
    • JSON contains all expected top-level keys
    • Human-readable output (no --json) contains expected section headers
    • Empty state (no teams, no daemon) produces empty arrays in JSON
    • Active daemon with jobs renders correctly in JSON
    • Heartbeat data appears in JSON output
    • --help shows usage

8. Register test suite in package.json

Add && bash scripts/sw-status-test.sh to the npm test script.

Task Checklist

  • Task 1: Add argument parsing for --json and --help flags to sw-status.sh
  • Task 2: Refactor tmux windows section into collect_tmux_windows + render_tmux_windows
  • Task 3: Refactor team configs section into collect_team_configs + render_team_configs
  • Task 4: Refactor task lists section into collect_task_lists + render_task_lists
  • Task 5: Refactor daemon pipelines section into collect_daemon + render_daemon
  • Task 6: Refactor issue tracker section into collect_tracker + render_tracker
  • Task 7: Refactor heartbeats section into collect_heartbeats + render_heartbeats
  • Task 8: Refactor remote machines section into collect_machines + render_machines
  • Task 9: Refactor connected developers section into collect_developers + render_developers
  • Task 10: Add JSON assembly and output when --json flag is set
  • Task 11: Update CLI help text in scripts/sw for the status subcommand
  • Task 12: Create sw-status-test.sh test suite with mock environment
  • Task 13: Register sw-status-test.sh in package.json test script
  • Task 14: Run test suite and verify all tests pass

Testing Approach

  1. Unit tests (sw-status-test.sh): Mock tmux, curl, kill, create fixture JSON files under a temp directory, override HOME and DAEMON_DIR to point at fixtures. Validate:

    • --json output parses as valid JSON via jq empty
    • All top-level keys present: version, timestamp, tmux_windows, teams, tasks, daemon, tracker, heartbeats, remote_machines, connected_developers
    • Correct counts (e.g., 2 tmux windows → JSON array length 2)
    • Empty state → empty arrays, not missing keys
    • Human-readable output contains expected section headers (TMUX WINDOWS, TEAM CONFIGS, etc.)

  2. Manual verification: Run shipwright status (no flag) to confirm existing output is unchanged. Run shipwright status --json and pipe through jq . to verify valid, well-structured JSON.

  3. Integration: Run shipwright status --json | jq .tmux_windows to verify subsections are independently queryable.

Definition of Done

  • shipwright status produces identical output to current (no regression)
  • shipwright status --json outputs valid JSON to stdout with zero ANSI escape codes
  • JSON schema includes all 8 dashboard sections as top-level keys
  • Empty state (no daemon, no teams, etc.) produces [] / {} — not errors
  • shipwright status --help shows usage with --json documented
  • sw CLI help mentions --json for the status command
  • Test suite sw-status-test.sh passes with all tests green
  • Test suite registered in package.json
  • Bash 3.2 compatible (no associative arrays, no readarray, no ${var,,})
  • set -euo pipefail maintained throughout
  • Pattern matches existing --json implementations (sw-cost.sh, sw-fleet.sh, sw-pipeline-vitals.sh)

Clone this wiki locally