fix(cli): intercept --help on every subcommand (#1201)

[tamirdresher]

What

Fixes squad <command> --help (and -h) silently running the command instead of showing help text. The flag is now intercepted in one place for every subcommand and routed to a centralized per-command help registry.

Why

Closes #1201.

Before this PR, --help and -h were intercepted only when the first argument (squad --help / squad -h / squad help). After a subcommand, the flag was silently dropped and the command would execute for real — sometimes with destructive side effects:

Command	Before this PR
squad init --help	Scaffolded .squad/, .github/, .gitignore, .gitattributes, .copilot/ into the cwd
squad triage --help / watch --help	Started a 10-minute polling loop
squad doctor --help	Ran the doctor health check
squad status --help	Printed active squad path
squad roles --help, upgrade --help, hire --help, …all the rest	Just ran the command, ignoring the flag

Only squad loop --help and squad state-mcp --help were checking for the flag.

This actively trained users out of using --help on this CLI, and init --help writing files in the cwd was outright destructive. Related (closed but unfixed): #757.

How

One place, one registry.

• New packages/squad-cli/src/cli/core/command-help.ts exports:

  • printCommandHelp(cmd, version): boolean — looks cmd up in a record of per-command help printers, prints the matching help block, returns true. Returns false if no dedicated block exists.
  • printGenericCommandHelp(cmd): void — friendly fallback that names the command and points at squad help.
  • commandsWithHelp(): readonly string[] — test helper that lists registered commands (used by a regression-guard test).

• In cli-entry.ts, immediately after the existing top-level --help block and before the per-command routes, intercept any --help/-h that appears after a subcommand:

  s if (cmd && cmd !== 'help' && cmd !== '--help' && cmd !== '-h' && cmd !== 'version' && cmd !== '--version' && cmd !== '-v' && (args.includes('--help') || args.includes('-h'))) { if (!printCommandHelp(cmd, VERSION)) { printGenericCommandHelp(cmd); } return; }

• The previously-existing inline --help blocks inside the state-mcp and loop routes are now redundant (the early intercept fires first) and have been removed. Their help text moved into the new registry, so help stays centralized.

Help text covers every routed command. Every command in the existing cmd === '...' switch has a dedicated entry: init, upgrade, migrate, status, roles, cost, triage, watch, loop, hire, copilot, plugin, export, import, scrub-emails, start, nap, memory, state-mcp, doctor, consult, extract, subsquads, link, build, aspire, schedule, personal, preset, cast, rc, remote-control, copilot-bridge, init-remote, rc-tunnel, discover, delegate, upstream, economy, externalize, internalize, config. A unit test (commandsWithHelp() equality) guards against regression when a new command is added.

Behavior is preserved for cases that already worked. squad --help, squad -h, squad help, squad (no args), squad --version, squad -v, squad version all still route exactly as before.

Verification

Manual repro after the fix (cwd is empty after each call — no scaffolding):

`
$ node packages/squad-cli/dist/cli-entry.js init --help

squad init v0.9.7-preview — Initialize Squad in the current project
Usage: squad init [options]
squad init --mode remote
...

$ node packages/squad-cli/dist/cli-entry.js doctor --help

squad doctor v0.9.7-preview — Validate squad setup
Usage: squad doctor
...
`

Automated:

• npm run build — passes
• npm run lint — passes (tsc --noEmit clean on both packages)
• npm run lint:eslint — 0 errors (only the existing pre-existing warnings; the new file is tagged /* eslint-disable no-console */ since it's a help printer, matching the style of the top-level help in cli-entry.ts)
• npx vitest run test/cli/command-help.test.ts — 11/11 pass
• npx vitest run test/acceptance/acceptance.test.ts — all 33 scenarios pass, including the 4 new ones from subcommand-help.feature
• npx vitest run test/cli/loop.test.ts test/cli/state-mcp.test.ts test/cli/init.test.ts test/cli/doctor.test.ts test/acceptance/acceptance.test.ts test/cli/command-help.test.ts — 100% pass

---

⚠️ Quick Check

• If SDK/CLI source files changed: completed the applicable Changeset step below (.changeset/fix-subcommand-help.md added)

PR Readiness Checklist

Branch & Commit

• Branch created from dev (not main)
• Branch is up to date with dev
• Verified diff contains only intended changes
• PR is not in draft mode (will mark ready once CI is green)
• Commit history is clean (single commit)

Build & Test

• npm run build passes
• npm test passes (all directly-affected suites; full npm test run shows a small number of pre-existing flakes on Windows tied to ~/.squad presence and cli-packaging-smoke npm pack collisions under parallel workers — none touched by this PR)
• npm run lint passes
• npm run lint:eslint passes

Changeset

• Changeset added via direct file: .changeset/fix-subcommand-help.md (@bradygaster/squad-cli: patch)

Docs

• No new user-facing capability — help text additions only. README is unchanged.

Exports

• N/A — no new public modules; the new helper is internal to squad-cli.

---

Breaking Changes

None. Public CLI surface (existing commands and their semantics) is unchanged. Only behavior change is that squad <cmd> --help now exits cleanly with help text instead of executing the command.

Waivers

None.

[Copilot]

Pull request overview

This PR fixes a long-standing CLI routing bug where squad <subcommand> --help / -h would silently run the subcommand (sometimes with destructive side effects). It centralizes per-command help text in a registry and adds an early router intercept so help is printed and the command exits before any real execution.

Changes:

• Added a centralized per-command help registry (command-help.ts) with a generic fallback and a test helper (commandsWithHelp()).
• Updated cli-entry.ts to intercept --help/-h after any subcommand and route help output through the registry.
• Added unit + acceptance coverage to prevent regressions for subcommand help interception.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/squad-cli/src/cli/core/command-help.ts	Adds per-command help registry, generic fallback, and command list helper for tests.
packages/squad-cli/src/cli-entry.ts	Adds early subcommand help intercept; removes redundant inline --help handling from specific routes.
test/cli/command-help.test.ts	Adds unit tests for the help registry plus optional CLI-level E2E checks when dist/ is present.
test/acceptance/features/subcommand-help.feature	Adds acceptance scenarios verifying subcommand --help/-h produces help output and exits cleanly.
test/acceptance/acceptance.test.ts	Registers the new acceptance feature.
.changeset/fix-subcommand-help.md	Publishes a patch changeset for the CLI behavior fix.