Repository navigation
refactor: derive flags, help and completions from one command spec - #427
Merged
Merged
Conversation
) The command surface was written out by hand in six places and had already drifted: bash completion offered --dry-run for `use` (which rejects it) and --repo/--slug (which exist nowhere), `check-updates` had no completion entry, and `init --description/--agents` were accepted but undocumented. src/commands/spec.js is now the single description: every command, its flags, their descriptions, subcommands and aliases. From it: - `bin/rolecraft.js` validates flags in one place in main() instead of 18 hand-written lists per handler, and generates both the root help and focused per-command help (`install --help` is 16 lines, not 204) - `completions.js` generates bash, zsh and fish from the same table - `docs/reference.md`'s common-flags table is generated from it `--verbose` and `--help` are now accepted by every command, so UserError.detail and .code actually reach users. Exit codes split: 2 for a usage error (unknown command, subcommand or flag), 1 for a failed operation. A missing required argument is a usage error too, and no longer gets reported as exit 1. The 87 per-agent flags stay accepted and completed but are not listed in `install --help`, which points at `rolecraft agents` instead. Behavior changes are deliberate and listed in the issue: unknown flags exit 2 rather than 1, previously-rejected flags now work, and `-v` is no longer ambiguous between `test --verbose` and `--version`.
sametcelikbicak
changed the title
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 #410. Addresses #296's premise (the generators move, they are not deleted) without touching that issue's
src/api/move.The drift this fixes
Also gone:
--repo/--slug(never existed),check-updates(no completion entry in any shell),init --description/--agents(accepted but undocumented),--dry-runonmcp remove(tracked separately in #410's notes).What changed
src/commands/spec.jsis the one description — every command, its flags, their descriptions, subcommands and aliases. From it:validateFlagscall inmain()replaces 18 hand-written lists inside handlersinstall --helpwent from 204 lines to 16;mcp --helpwas unreachable dead text and now workscompletions.js: 416 → 206 lines)docs/reference.md's common-flags table is generated, with a test that fails if it goes stale--verboseand--helpare accepted by every command now. That was the point of theUserError.detail/.codefields: they could never reach a user before, because every command buttestrejected the flag.Exit codes
2for a usage error — unknown command, subcommand or flag, or a missing required argument.1for a failed operation. Previously everything was1, so a typo was indistinguishable from a failed install.Deliberate behavior changes
Flagged in the issue as not-a-bugfix, kept separate so a bisect stays clean:
--verbosenow works everywhere (previously an error on 24 of 25 commands)-vis no longer ambiguous — it was--versionat top level andtest --verboseinsidetestLeft out
The 87 per-agent flags stay accepted and completed but are not listed in
install --help, which points atrolecraft agentsinstead. 87 lines of--claude Also install to ~/.claude/skills/is not a help page.Tests
spec.test.jschecks the spec's own invariants and that the generated docs table is current.cli-contract.test.jsspawns the real CLI to check that every non-passthrough command rejects an unknown flag with exit 2, that every spec flag appears in its own--help, and that every word bash completes is a word the CLI accepts — the check that would have caught--repo.