feat: give clap usage errors a runnable next command - #7
Merged
Conversation
The previous help pass made runtime errors (not-a-git-repo, dirty tree, stale plan) actionable, but clap's own parse errors -- unknown command, missing argument, bad flag -- still ended at the default "For more information, try '--help'" footer with no next step. Parse via try_parse and handle usage errors ourselves: - Append a 'Try:' line with a copy-pasteable command for whichever subcommand the user was reaching for (e.g. 'rep scan' missing its token -> 'Try: rep scan old_name'). clap's own "did you mean" tips are kept. - Under --json, emit the standard rep.error.v1 envelope instead, so an agent on the primary interface never gets a non-JSON failure. - Exit usage errors with code 10 (invalid_arguments) rather than clap's default 2, which rep already publishes as "no matches" -- agents must distinguish a clean empty scan from a mistyped command. - --help/--version remain untouched (rendered by clap, exit 0). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Closes the last remaining gap from the CLI help re-evaluation (rep 9.5/10 → aiming for full marks on Rule 13).
The previous PR (#6) made runtime errors actionable (not-a-git-repo, dirty tree, stale plan), but clap's parse errors — unknown subcommand, missing argument, bad flag — still ended at clap's default
For more information, try '--help'with no runnable next step.What changed
Parse via
try_parse()and handle usage errors ourselves:Try:line, contextual to the subcommand the user was reaching for:--jsonstays JSON: under--jsona usage error emits the standardrep.error.v1envelope (kind: invalid_arguments), so an agent on the primary interface never hits a non-JSON failure.2as "no matches" (a successful empty scan), so usage errors now use10(invalid_arguments) — agents can distinguish a clean empty scan from a mistyped command.--help/--versionuntouched — still rendered by clap, exit 0.repwith no args still prints full help (which now carries the EXAMPLE on-ramp).Testing
mise run rep:verifypasses. Added 3 tests: unrecognized subcommand → 10, missing required arg → 10, and usage error under--json→ validrep.error.v1envelope.🤖 Generated with Claude Code