Pipeline Plan 204

Now I have a complete picture. Let me write the implementation plan.

---

Implementation Plan: GitHub Actions Quick-Start Generator

Current State Analysis

Two previous iterations have already built significant infrastructure:

1. Commit 9a30ea9 — Created scripts/sw-ci.sh (725 lines), scripts/lib/ci-quickstart.sh (257 lines), scripts/sw-ci-test.sh (311 lines), modified scripts/sw-init.sh (--ci flag), modified scripts/sw-doctor.sh (--ci flag), and scripts/sw-doctor-test.sh
2. Commit 85f0ee3 — Deleted 13 old hardcoded shipwright-*.yml workflow files (2,927 lines removed)

What's Already Working

• shipwright ci quickstart generates workflow YAML from pipeline templates
• shipwright init --ci delegates to shipwright ci quickstart
• shipwright doctor --ci validates workflow files (structure, label trigger, artifact upload)
• Project type detection (node/python/go/rust/ruby/java) with correct setup steps
• --template, --test-cmd, --force flags
• README section generation with badges
• NO_GITHUB support in generated workflows (${{ vars.NO_GITHUB }})
• 29 CI tests + 4 doctor --ci tests — all passing
• Additional commands: generate, analyze, matrix, cache, secrets, reusable, badges, runners, validate

Alternatives Considered

Approach A (current): Bash-based generator with heredoc YAML templates

• Pros: Consistent with codebase (all shell), no new dependencies, Bash 3.2 compatible
• Cons: YAML generation in bash is fragile, harder to test edge cases
• Blast radius: Only new files + small modifications to init/doctor

Approach B: Template files with variable substitution

• Pros: Cleaner separation of template vs logic, easier to maintain YAML
• Cons: More files to manage, more complex template engine in bash
• Not chosen: Current approach already works and is tested

Chosen: Approach A — it's already implemented, tested, and follows codebase conventions.

Gaps Against Acceptance Criteria

Acceptance Criteria	Status	Gap
shipwright init --ci generates workflows	Done	—
Issue label trigger, secrets check, artifact upload, status reporting	Done	—
Auto-detects project type with test commands	Done	—
README section auto-generated with badges	Done	—
shipwright doctor --ci validates workflows	Done	—
Works with NO_GITHUB=1 for air-gapped testing	Partial	Generated workflows check vars.NO_GITHUB, but sw-ci.sh itself doesn't guard GitHub API calls
Bash 3.2 compatibility	Bug	cmd_generate() uses ${var^} (Bash 4+ uppercase) at line 183
Secrets check in workflow	Done	—
All templates supported (fast/standard/full/autonomous)	Partial	Default is fast,standard; all templates work but --template all isn't supported

Files to Modify

File	Action	Purpose
scripts/sw-ci.sh	Modify	Fix Bash 3.2 compat bug in cmd_generate(), add NO_GITHUB guard
scripts/lib/ci-quickstart.sh	Modify	Add secrets check validation, improve NO_GITHUB air-gapped support
scripts/sw-ci-test.sh	Modify	Add tests for NO_GITHUB mode, Bash 3.2 compat, edge cases
scripts/sw-doctor-test.sh	Modify	Add test for --ci with missing YAML sections
scripts/sw-doctor.sh	Modify	Add secrets reference validation to --ci check

Implementation Steps

1. Fix Bash 3.2 compatibility bug in sw-ci.sh:183 — replace ${workflow_name^} with tr uppercase (same pattern used in ci-quickstart.sh:77-79)

2. Add NO_GITHUB guard to sw-ci.sh — ensure cmd_quickstart() and cmd_generate() work fully offline without GitHub API calls; add NO_GITHUB=1 test case

3. Add --template all support to cmd_quickstart() — allow generating workflows for all available templates at once

4. Enhance doctor --ci validation — add checks for: secrets references (${{ secrets.* }}), workflow_dispatch trigger, permissions block

5. Add edge case tests — empty template list, invalid template name, missing templates/ directory, NO_GITHUB mode quickstart

6. Verify full test suite passes — run npm test and sw-ci-test.sh

Task Checklist

• Task 1: Fix Bash 3.2 ${var^} bug in cmd_generate() — use tr pattern
• Task 2: Add NO_GITHUB guards to sw-ci.sh for air-gapped operation
• Task 3: Add --template all shorthand to cmd_quickstart()
• Task 4: Enhance doctor --ci with secrets and permissions validation
• Task 5: Add NO_GITHUB test in sw-ci-test.sh
• Task 6: Add Bash 3.2 compat test for cmd_generate()
• Task 7: Add edge case tests (invalid template, missing templates dir)
• Task 8: Run full test suite and verify all tests pass

Testing Approach

Test Pyramid Breakdown

• Unit tests (8 existing + 4 new): Test individual commands (quickstart, generate, validate, etc.) in isolation with mocked binaries
• Integration tests (4 existing + 2 new): Test init --ci delegation, doctor --ci validation with generated workflows
• E2E tests (0): Not applicable — would require real GitHub Actions runner; covered by NO_GITHUB mode

Coverage Targets

• All cmd_* functions in sw-ci.sh: 100% happy path, key error paths
• ci-quickstart.sh functions: all 3 functions (detect_project_for_ci, generate_quickstart_workflow, generate_readme_section)
• Doctor --ci validation: all check branches (pass/warn/fail)

Critical Paths to Test

• Happy path: quickstart generates valid YAML with correct structure for detected project type
• Error: invalid template: quickstart --template nonexistent fails gracefully with available template list
• Error: no jq: detect_project_for_ci returns "unknown" without jq
• Edge: NO_GITHUB=1: All commands work without GitHub API access
• Edge: empty repo: Detection returns "unknown", workflow uses placeholder test command

Risk Analysis

Risk	Impact	Mitigation
Bash 3.2 ${var^} bug breaks macOS	cmd_generate() fails on default macOS bash	Fix with tr pattern (Task 1)
Generated YAML has syntax errors	Workflows fail to parse on GitHub	Existing validate command + test coverage
Template path resolution breaks in installed vs dev mode	Quickstart can't find templates	ci-quickstart.sh already handles path resolution via _CI_QS_DIR
Old deleted workflows cause confusion	Users on main still have old files	Deletion is in the branch; clean break

Definition of Done

• shipwright init --ci generates valid workflow YAML for all supported templates
• shipwright ci quickstart works with --template, --test-cmd, --force flags
• shipwright doctor --ci validates generated workflow configuration
• All generated YAML includes: issue label trigger, secrets check, artifact upload, status reporting
• Auto-detects project type (node/python/go/rust/ruby/java) with correct setup steps
• README section generated with badges and usage instructions
• Works with NO_GITHUB=1 for air-gapped testing
• Bash 3.2 compatible (no ${var^}, no declare -A, no readarray)
• All existing tests pass (sw-ci-test.sh: 29 tests, sw-doctor-test.sh: 24 tests)
• New tests cover NO_GITHUB mode and edge cases

CLI Interface Specification

shipwright init --ci

shipwright init --ci [--template <list>] [--test-cmd <cmd>] [--force]

Delegates to shipwright ci quickstart with all remaining args.

shipwright ci quickstart

shipwright ci quickstart [--template <csv|all>] [--test-cmd <cmd>] [--force]

• --template: Comma-separated list or all (default: fast,standard)
• --test-cmd: Override auto-detected test command
• --force: Overwrite existing workflow files

shipwright doctor --ci

shipwright doctor --ci

Validates: YAML structure, label trigger, artifact upload, secrets references, permissions block.

Error Codes

• Exit 0: Success
• Exit 1: Template not found, missing config, validation failure

Versioning

CLI follows VERSION="3.2.4" in all scripts. No API versioning needed (CLI tool, not HTTP API).

Rate Limiting

Not applicable (local CLI tool).