fix(cli): print per-subcommand help instead of launching the UI#974
Merged
Conversation
`plannotator review --help` (and other subcommands) fell through to their command branch because only top-level `--help` was handled. For `review`, `--help` was parsed as a non-URL positional, dropping into local review mode and opening a browser tab. When Claude Code probes the CLI with `--help`, that stray tab's close injects a bogus "no feedback → proceed" signal into the session. Handle `--help`/`-h` for every user-facing subcommand (review, annotate, annotate-last/last, setup-goal, archive, sessions) before any subcommand branch can run: print command-specific usage on stdout and exit 0. Also accept `-h` at the top level and advertise per-command help there. Fixes #964
The top-level help advertises `plannotator <command> --help`, but `improve-context` (the only internal hook command listed there) had no help entry, so `improve-context --help` fell through to the hook branch and emitted additionalContext JSON instead of usage. Add a help entry so every advertised command responds to --help.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
plannotator review --helplaunches the review UI instead of printing help. Only top-level--helpwas handled; for a subcommand,args[0]is the command name, so the invocation fell through to the command branch. Inreview,parseReviewArgs(["--help"])treats--helpas a non-URL positional →prUrlundefined → local review mode → opens a browser tab.The real sting (per the issue's follow-up): when Claude Code drives the CLI it runs
--helpfirst to probe. That opens a duplicate tab, and closing it injects a bogus "no feedback → proceed" signal into the CC session — wasteful and unpredictable in the agent-driven flow. The same class of bug affectedannotate,annotate-last/last,setup-goal,archive, andsessions.Fix
Handle
--help/-hfor every user-facing subcommand before any subcommand branch can run — print command-specific usage on stdout andexit 0, so a help probe never starts a server or opens a tab.apps/hook/server/cli.ts:hasHelpFlag(),isSubcommandHelpInvocation(),formatSubcommandHelp(), plus aSUBCOMMAND_HELPmap and alast → annotate-lastalias.isTopLevelHelpInvocationnow also accepts-h, and top-level help advertisesplannotator <command> --help.opencode-*,copilot-*,improve-context,install-runtime) are intentionally excluded — they're not user-facing.Testing
apps/hook/server/cli.test.ts): help-flag detection, per-subcommand detection (incl. flag-after-args, thelastalias, all six user-facing subcommands), rejection of real invocations (review --git, PR URLs) and internal/unknown subcommands, and the rendered usage text.plannotator review --help/-h,annotate --help,sessions --help,last --help→ print usage, exit 0, no browser tab.plannotator reviewstill launches the server (not intercepted).--help/--versionintact.Fixes #964