shipwright-cli 1.7.0

package/docs/patterns/test-generation.md

@@ -0,0 +1,173 @@
+# Pattern: Test Generation
+
+Build comprehensive test coverage using parallel agents that discover, generate, and validate tests iteratively.
+
+---
+
+## When to Use
+
+- **Coverage campaigns** — systematically adding tests to a poorly-tested codebase
+- **New feature testing** — generating unit + integration tests for freshly-built features
+- **Edge case hunting** — finding and testing boundary conditions, error paths, race conditions
+- **Test suite modernization** — upgrading old test patterns to current conventions
+
+**Don't use** for writing a single test file, or when coverage is already good and you just need one more test.
+
+---
+
+## Recommended Team Composition
+
+| Role | Agent Name | Focus |
+|------|-----------|-------|
+| **Team Lead** | `lead` | Orchestration, runs test suite, tracks coverage gaps |
+| **Test Writer 1** | `unit-tests` | Unit tests for core business logic |
+| **Test Writer 2** | `integration-tests` | Integration tests, API tests, cross-module tests |
+| **Test Writer 3** *(optional)* | `edge-cases` | Edge cases, error paths, boundary conditions |
+
+> **Tip:** For smaller projects, 2 agents (unit + integration) is enough. The team lead handles edge cases.
+
+---
+
+## Wave Breakdown
+
+### Wave 1: Discover
+
+**Goal:** Find what needs testing and understand existing test patterns.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: scanner    │  Agent: patterns  │
+│  Find all testable │  Analyze existing │
+│  functions, map    │  test patterns,   │
+│  current coverage  │  fixtures, mocks  │
+└──────────────────┴──────────────────┘
+         ↓ Team lead identifies coverage gaps
+```
+
+**Scanner agent:** "Run the test suite with coverage reporting. List all files/functions below the coverage threshold. Identify untested public API surface."
+
+**Patterns agent:** "Read existing test files. Document the patterns used — test runner, assertion style, mock strategy, fixture patterns. List file locations of good examples."
+
+### Wave 2: Generate (Parallel Batches)
+
+**Goal:** Write tests in parallel, partitioned by module or test type.
+
+```
+┌──────────────────┬──────────────────┬──────────────────┐
+│  Agent: unit-tests│  Agent: int-tests │  Agent: edge-cases│
+│  Unit tests for   │  Integration tests│  Edge cases for   │
+│  src/services/     │  for src/api/      │  auth + payments   │
+│  src/models/       │  routes             │  error paths       │
+└──────────────────┴──────────────────┴──────────────────┘
+         ↓ Team lead runs full test suite
+```
+
+**Critical:** Each agent writes tests in **different files**. Partition by directory or module:
+- Unit tests agent → `src/services/__tests__/`, `src/models/__tests__/`
+- Integration agent → `src/api/__tests__/`, `tests/integration/`
+- Edge cases agent → `tests/edge-cases/`
+
+### Wave 3: Validate & Fix
+
+**Goal:** Run all tests, fix failures, fill remaining gaps.
+
+```
+┌──────────────────┬──────────────────┐
+│  Agent: fixer-1    │  Agent: fixer-2    │
+│  Fix failing unit  │  Fix failing       │
+│  tests from Wave 2 │  integration tests │
+└──────────────────┴──────────────────┘
+         ↓ Team lead runs suite again
+```
+
+### Wave 4+: Iterate Until Green
+
+Repeat Wave 3 until:
+- All tests pass
+- Coverage meets the target threshold
+- No test failures remain
+
+> **Set a wave limit.** 5-6 waves is typical for test generation. If tests aren't passing after 6 waves, the issue is likely in the code under test, not the tests themselves.
+
+---
+
+## File-Based State Example
+
+`.claude/team-state.local.md`:
+
+```markdown
+---
+wave: 3
+status: in_progress
+goal: "Achieve 80% test coverage for src/api/ and src/services/"
+started_at: 2026-02-07T14:00:00Z
+---
+
+## Coverage Baseline
+- src/api/: 32% → target 80%
+- src/services/: 45% → target 80%
+- src/models/: 71% → target 80%
+
+## Completed
+- [x] Scanned coverage, identified 23 untested functions (wave-1-scanner.md)
+- [x] Documented test patterns: vitest, vi.mock(), factory fixtures (wave-1-patterns.md)
+- [x] Generated 14 unit tests for src/services/ (wave-2-unit.md)
+- [x] Generated 8 integration tests for src/api/ (wave-2-integration.md)
+- [x] Generated 6 edge case tests for auth flows (wave-2-edge.md)
+
+## In Progress (Wave 3)
+- [ ] Fix 3 failing unit tests (mock setup issues)
+- [ ] Fix 2 failing integration tests (missing test DB seed)
+
+## Coverage After Wave 2
+- src/api/: 32% → 61%
+- src/services/: 45% → 74%
+- src/models/: 71% → 78%
+
+## Agent Outputs
+- wave-1-scanner.md
+- wave-1-patterns.md
+- wave-2-unit.md
+- wave-2-integration.md
+- wave-2-edge.md
+```
+
+---
+
+## Example Commands
+
+```bash
+# Create a 3-agent test generation team
+shipwright session test-coverage
+
+# Between waves, run the test suite from the lead pane:
+#   pnpm test --coverage
+
+# Watch agents writing tests in parallel across panes
+# Use prefix + Ctrl-t for status dashboard
+
+# After all waves complete
+shipwright cleanup --force
+```
+
+---
+
+## Tips
+
+- **Always discover patterns first (Wave 1).** Agents that don't know the existing test conventions will write tests that look nothing like the rest of the suite.
+- **Partition test files, not test cases.** Each agent should own entire test files, not individual test cases within a shared file. This prevents write conflicts.
+- **Run the test suite between every wave.** The team lead should run tests after each wave and feed failure details into the next wave's agent prompts.
+- **Include test file paths in prompts.** Don't say "write tests for the auth service." Say "write tests in `src/services/__tests__/auth.test.ts` for functions exported from `src/services/auth.ts`, using the vitest patterns shown in `src/services/__tests__/user.test.ts`."
+- **Wave 3+ agents need failure context.** Copy-paste the actual test failure output into the agent's prompt so it can fix the specific issue.
+
+---
+
+## Anti-Patterns
+
+| Don't | Why |
+|-------|-----|
+| Have two agents write to the same test file | File conflict — one agent's tests will be lost |
+| Skip running tests between waves | You'll compound errors across waves |
+| Generate tests without reading existing patterns | Tests will be stylistically inconsistent |
+| Set coverage target at 100% | Diminishing returns — edge case tests past 85% are often brittle |
+| Keep iterating past 6 waves | If tests still fail, the problem is in the code, not the tests |

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "shipwright-cli",
+  "version": "1.7.0",
+  "description": "Orchestrate autonomous Claude Code agent teams in tmux",
+  "bin": {
+    "shipwright": "./scripts/cct",
+    "sw": "./scripts/cct"
+  },
+  "files": [
+    "scripts/",
+    "!scripts/*-test.sh",
+    "!scripts/build-release.sh",
+    "!scripts/update-version.sh",
+    "!scripts/install-remote.sh",
+    "!scripts/install-completions.sh",
+    "templates/",
+    "tmux/templates/",
+    "tmux/tmux.conf",
+    "tmux/claude-teams-overlay.conf",
+    "claude-code/",
+    "completions/",
+    "docs/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "test": "bash scripts/cct-pipeline-test.sh && bash scripts/cct-daemon-test.sh && bash scripts/cct-prep-test.sh && bash scripts/cct-fleet-test.sh && bash scripts/cct-fix-test.sh && bash scripts/cct-memory-test.sh"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tmux",
+    "agent-teams",
+    "autonomous",
+    "pipeline",
+    "ai"
+  ],
+  "author": "Seth Ford",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sethdford/shipwright.git"
+  },
+  "homepage": "https://sethdford.github.io/shipwright",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/adapters/docker-deploy.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  docker-deploy.sh — Deploy adapter for Docker / Docker Compose          ║
+# ║                                                                          ║
+# ║  Sourced by shipwright init --deploy to generate platform-specific commands.   ║
+# ║  Exports: staging_cmd, production_cmd, rollback_cmd, detect_platform    ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+adapter_name="docker"
+
+detect_platform() {
+    # Docker: look for Dockerfile or docker-compose.yml/yaml
+    [[ -f "Dockerfile" ]] || [[ -f "docker-compose.yml" ]] || [[ -f "docker-compose.yaml" ]]
+}
+
+get_staging_cmd() {
+    if [[ -f "docker-compose.yml" ]] || [[ -f "docker-compose.yaml" ]]; then
+        echo "docker compose build && docker compose up -d"
+    else
+        echo "docker build -t \$(basename \$(pwd)):staging . && docker run -d --name \$(basename \$(pwd))-staging \$(basename \$(pwd)):staging"
+    fi
+}
+
+get_production_cmd() {
+    if [[ -f "docker-compose.yml" ]] || [[ -f "docker-compose.yaml" ]]; then
+        echo "docker compose -f docker-compose.yml -f docker-compose.prod.yml build && docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d"
+    else
+        echo "docker build -t \$(basename \$(pwd)):latest . && docker run -d --name \$(basename \$(pwd)) \$(basename \$(pwd)):latest"
+    fi
+}
+
+get_rollback_cmd() {
+    if [[ -f "docker-compose.yml" ]] || [[ -f "docker-compose.yaml" ]]; then
+        echo "docker compose down && docker compose up -d --force-recreate"
+    else
+        echo "docker stop \$(basename \$(pwd)) && docker rm \$(basename \$(pwd)) && docker run -d --name \$(basename \$(pwd)) \$(basename \$(pwd)):previous"
+    fi
+}
+
+get_health_url() {
+    echo "http://localhost:3000/health"
+}
+
+get_smoke_cmd() {
+    if [[ -f "docker-compose.yml" ]] || [[ -f "docker-compose.yaml" ]]; then
+        echo "docker compose ps --format json | jq -e 'all(.State == \"running\")'"
+    else
+        echo "docker inspect --format='{{.State.Running}}' \$(basename \$(pwd)) | grep -q true"
+    fi
+}

package/scripts/adapters/fly-deploy.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  fly-deploy.sh — Deploy adapter for Fly.io                             ║
+# ║                                                                          ║
+# ║  Sourced by shipwright init --deploy to generate platform-specific commands.   ║
+# ║  Exports: staging_cmd, production_cmd, rollback_cmd, detect_platform    ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+adapter_name="fly"
+
+detect_platform() {
+    # Fly.io: look for fly.toml
+    [[ -f "fly.toml" ]]
+}
+
+get_staging_cmd() {
+    echo "fly deploy --strategy canary --wait-timeout 120"
+}
+
+get_production_cmd() {
+    echo "fly deploy --strategy rolling --wait-timeout 300"
+}
+
+get_rollback_cmd() {
+    echo "fly releases list --json | jq -r '.[1].version' | xargs -I{} fly deploy --image-ref {}"
+}
+
+get_health_url() {
+    # Extract app name from fly.toml for health URL
+    local app_name
+    app_name=$(grep '^app\s*=' fly.toml 2>/dev/null | head -1 | sed 's/.*=\s*"\?\([^"]*\)"\?/\1/' | tr -d ' ')
+    if [[ -n "$app_name" ]]; then
+        echo "https://${app_name}.fly.dev/health"
+    else
+        echo ""
+    fi
+}
+
+get_smoke_cmd() {
+    echo "fly status --json | jq -e '.Status == \"running\"'"
+}

package/scripts/adapters/iterm2-adapter.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  iterm2-adapter.sh — Terminal adapter for iTerm2 tab management         ║
+# ║                                                                          ║
+# ║  Uses AppleScript (osascript) to create iTerm2 tabs with named titles   ║
+# ║  and working directories. macOS only.                                    ║
+# ║  Sourced by cct-session.sh — exports: spawn_agent, list_agents,         ║
+# ║  kill_agent, focus_agent.                                                ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+# Verify we're on macOS and iTerm2 is available
+if [[ "$(uname)" != "Darwin" ]]; then
+    echo -e "\033[38;2;248;113;113m\033[1m✗\033[0m iTerm2 adapter requires macOS." >&2
+    exit 1
+fi
+
+# Track created tab IDs for agent management
+declare -a _ITERM2_TAB_NAMES=()
+
+spawn_agent() {
+    local name="$1"
+    local working_dir="${2:-$PWD}"
+    local command="${3:-}"
+
+    # Resolve working_dir — tmux format #{pane_current_path} won't work here
+    if [[ "$working_dir" == *"pane_current_path"* || "$working_dir" == "." ]]; then
+        working_dir="$PWD"
+    fi
+
+    osascript <<APPLESCRIPT
+tell application "iTerm2"
+    tell current window
+        -- Create a new tab
+        set newTab to (create tab with default profile)
+        tell current session of newTab
+            -- Set the name/title
+            set name to "${name}"
+            -- Change to the working directory
+            write text "cd '${working_dir}' && clear"
+        end tell
+    end tell
+end tell
+APPLESCRIPT
+
+    # Run the command if provided
+    if [[ -n "$command" ]]; then
+        sleep 0.3
+        osascript <<APPLESCRIPT
+tell application "iTerm2"
+    tell current window
+        tell current session of current tab
+            write text "${command}"
+        end tell
+    end tell
+end tell
+APPLESCRIPT
+    fi
+
+    _ITERM2_TAB_NAMES+=("$name")
+}
+
+list_agents() {
+    # List all tabs in the current iTerm2 window
+    osascript <<'APPLESCRIPT'
+tell application "iTerm2"
+    tell current window
+        set output to ""
+        set tabIndex to 0
+        repeat with aTab in tabs
+            set tabIndex to tabIndex + 1
+            tell current session of aTab
+                set sessionName to name
+                set output to output & tabIndex & ": " & sessionName & linefeed
+            end tell
+        end repeat
+        return output
+    end tell
+end tell
+APPLESCRIPT
+}
+
+kill_agent() {
+    local name="$1"
+
+    osascript <<APPLESCRIPT
+tell application "iTerm2"
+    tell current window
+        repeat with aTab in tabs
+            tell current session of aTab
+                if name is "${name}" then
+                    close
+                    return "closed"
+                end if
+            end tell
+        end repeat
+    end tell
+end tell
+return "not found"
+APPLESCRIPT
+}
+
+focus_agent() {
+    local name="$1"
+
+    osascript <<APPLESCRIPT
+tell application "iTerm2"
+    tell current window
+        set tabIndex to 1
+        repeat with aTab in tabs
+            tell current session of aTab
+                if name is "${name}" then
+                    select aTab
+                    return "focused"
+                end if
+            end tell
+            set tabIndex to tabIndex + 1
+        end repeat
+    end tell
+end tell
+return "not found"
+APPLESCRIPT
+}

package/scripts/adapters/railway-deploy.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  railway-deploy.sh — Deploy adapter for Railway                         ║
+# ║                                                                          ║
+# ║  Sourced by shipwright init --deploy to generate platform-specific commands.   ║
+# ║  Exports: staging_cmd, production_cmd, rollback_cmd, detect_platform    ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+adapter_name="railway"
+
+detect_platform() {
+    # Railway: look for railway.toml or .railway/ directory
+    [[ -f "railway.toml" ]] || [[ -d ".railway" ]] || [[ -f "railway.json" ]]
+}
+
+get_staging_cmd() {
+    echo "railway up --environment staging --detach"
+}
+
+get_production_cmd() {
+    echo "railway up --environment production --detach"
+}
+
+get_rollback_cmd() {
+    echo "railway rollback --yes"
+}
+
+get_health_url() {
+    echo ""
+}
+
+get_smoke_cmd() {
+    echo "railway status --json 2>/dev/null | jq -e '.status == \"running\"'"
+}

package/scripts/adapters/tmux-adapter.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  tmux-adapter.sh — Terminal adapter for tmux pane management            ║
+# ║                                                                          ║
+# ║  Default adapter. Creates tmux panes within a named window.             ║
+# ║  Sourced by cct-session.sh — exports: spawn_agent, list_agents,         ║
+# ║  kill_agent, focus_agent.                                                ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+# Track spawned panes by agent name
+declare -A _TMUX_AGENT_PANES
+
+spawn_agent() {
+    local name="$1"
+    local working_dir="${2:-#{pane_current_path}}"
+    local command="${3:-}"
+
+    # If no window exists yet, create one
+    if ! tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
+        tmux new-window -n "$WINDOW_NAME" -c "$working_dir"
+    else
+        # Split the current window to add a pane
+        tmux split-window -t "$WINDOW_NAME" -c "$working_dir"
+    fi
+
+    sleep 0.1
+
+    # Set the pane title
+    tmux send-keys -t "$WINDOW_NAME" "printf '\\033]2;${name}\\033\\\\'" Enter
+    sleep 0.1
+    tmux send-keys -t "$WINDOW_NAME" "clear" Enter
+
+    # Run the command if provided
+    if [[ -n "$command" ]]; then
+        sleep 0.1
+        tmux send-keys -t "$WINDOW_NAME" "$command" Enter
+    fi
+
+    # Re-tile after adding each pane
+    tmux select-layout -t "$WINDOW_NAME" tiled 2>/dev/null || true
+}
+
+list_agents() {
+    # List all panes in the window with their titles
+    if tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
+        tmux list-panes -t "$WINDOW_NAME" -F '#{pane_index}: #{pane_title} (#{pane_current_command})' 2>/dev/null
+    fi
+}
+
+kill_agent() {
+    local name="$1"
+
+    if ! tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
+        return 1
+    fi
+
+    # Find the pane with the matching title
+    local pane_id
+    pane_id=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_id} #{pane_title}' 2>/dev/null \
+        | grep " ${name}$" | head -1 | cut -d' ' -f1)
+
+    if [[ -n "$pane_id" ]]; then
+        tmux kill-pane -t "$pane_id"
+        return 0
+    fi
+    return 1
+}
+
+focus_agent() {
+    local name="$1"
+
+    if ! tmux list-windows -F '#W' 2>/dev/null | grep -qx "$WINDOW_NAME"; then
+        return 1
+    fi
+
+    # Find the pane with the matching title
+    local pane_index
+    pane_index=$(tmux list-panes -t "$WINDOW_NAME" -F '#{pane_index} #{pane_title}' 2>/dev/null \
+        | grep " ${name}$" | head -1 | cut -d' ' -f1)
+
+    if [[ -n "$pane_index" ]]; then
+        tmux select-window -t "$WINDOW_NAME"
+        tmux select-pane -t "$WINDOW_NAME.$pane_index"
+        return 0
+    fi
+    return 1
+}

package/scripts/adapters/vercel-deploy.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  vercel-deploy.sh — Deploy adapter for Vercel                           ║
+# ║                                                                          ║
+# ║  Sourced by shipwright init --deploy to generate platform-specific commands.   ║
+# ║  Exports: staging_cmd, production_cmd, rollback_cmd, detect_platform    ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+
+adapter_name="vercel"
+
+detect_platform() {
+    # Vercel: look for vercel.json or .vercel/ directory
+    [[ -f "vercel.json" ]] || [[ -d ".vercel" ]]
+}
+
+get_staging_cmd() {
+    echo "vercel deploy --yes 2>&1 | tee .claude/pipeline-artifacts/deploy-staging.log"
+}
+
+get_production_cmd() {
+    echo "vercel deploy --prod --yes 2>&1 | tee .claude/pipeline-artifacts/deploy-prod.log"
+}
+
+get_rollback_cmd() {
+    echo "vercel rollback --yes"
+}
+
+get_health_url() {
+    # Vercel provides a preview URL from the deploy output
+    echo ""
+}
+
+get_smoke_cmd() {
+    echo "curl -sf \$(vercel ls --json 2>/dev/null | jq -r '.[0].url // empty') > /dev/null"
+}