feat(commands): discoverable flags, per-command --help, strict validation#373
Merged
Conversation
…tion
The `:command` palette had no flag discoverability: `:cmd --help` silently
ran the command and unknown/misspelled flags were silently ignored.
Add an optional `registry.CommandWithSpec` capability (same type-assertion
pattern as `Aliaser`) carrying a declarative `CommandSpec{Usage, Flags,
Examples, Passthrough}`. `api.ParseInput` is now the single chokepoint
that: short-circuits Passthrough specs, intercepts `--help`/`-h`/`-help`
(and `:help <cmd>`) into a per-command help screen reusing the existing
detailed help view, then enforces global-strict unknown-flag rejection
with a "did you mean --x?" suggestion.
Every command declares a spec; the OSS bootstrap stub uses Passthrough
so it keeps its Business-Edition notice and no Pro flag internals enter
the OSS repo. Docs updated in CLAUDE.md.
BREAKING: previously-ignored unknown flags are now rejected. The two
parse_test cases that fed `node --verbose` are repointed at the
passthrough `bootstrap` command (flag/positional separation still
covered; strict rejection covered by new cases).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
The detailed help view renders categories as side-by-side columns with a 15-char key column — built for short keybinding cheat-sheets. Long usage/flag strings overflowed and collided (reported on :bootstrap --help). Add a distinct CommandHelp payload routed to a new vertical renderer: sections stacked top-to-bottom, short-key sections (flags) in an aligned key/description column, long-key sections (usage/examples) stacked with word-wrapped lines. The columnar keybinding cheat-sheet path (NewDetailed / `?`) is untouched — no regression to existing views. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
…help Two UX fixes on top of the flag-spec work: 1. The parser only understood `--host=localhost`; `--host localhost` left `host=true` and dropped the value as a positional. parseArgs is now spec-aware: a flag declared TakesValue consumes the next token (`--host localhost`), the `=` form still works, and a value flag with no following token is a clear error. ParseInput resolves the spec before parsing to build the value-flag set. 2. Add an optional CommandSpec.Detail prose field, rendered as a wrapped paragraph under USAGE (author newlines preserved as paragraph breaks). Lets a command explain non-obvious modes — e.g. that running with no flags starts an interactive flow. The USAGE block now always stacks command-line then description as a header. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- :help page header gains a dim second line: "Tip: <command> --help (or -h) for flags, usage & examples". Command-list path only (FrameHeader) — absent from per-command and ? keybinding screens, filter-proof. - Behavior-only Detail added to every OSS command spec (help, quit, contexts, stack, node, network, secret, config). OSS bootstrap stub stays Passthrough (no Detail by design). - Tests: FrameHeader hint placement; guard that every non-passthrough registered command ships a Detail. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
The two-line FrameHeader broke the box border (ui.RenderFramedBox treats the header as one bordered line; RenderFramedBoxHeight assumes headerLines=1). Revert FrameHeader to the single styled "Available Commands" line and render the discoverability tip as the first body line in the default terminal colour, followed by a blank line before the table header. Filter rebuild keeps the tip. Box border is intact. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
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
2 participants
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.
Context
The
:commandpalette (Bubble Tea TUI, not a shell CLI) had no flag discoverability::bootstrap --upgradeworked but was documented nowhere in-app,:bootstrap --helpsilently ran bootstrap (the--helpflag was parsed then never read), and any misspelled/unknown flag was silently swallowed byparseArgs.What changed
registry/spec.go(new): optionalCommandWithSpeccapability (Spec() CommandSpec), discovered by type assertion exactly like the existingAliaser.CommandSpec{Usage, Flags, Examples, Passthrough}, plusSpecOf(alias-resolving) and aDistance(Levenshtein) helper.commands/api/parse.go: single chokepoint — short-circuitsPassthroughspecs, intercepts--help/-h/-helpinto the newErrHelpRequestedsentinel (error.go), then runs global strict unknown-flag validation (validate.go) with adid you mean --x?suggestion.commands/command/help.go:CommandHelpCategories/CommandHelpCmdbuild a per-command screen reusing the existing detailed help view ([]HelpCategory→NewDetailed);:help <cmd>routes through the same builder with a typo suggestion. No help-view rendering changes.app/update.go: recoversErrHelpRequestedviaerrors.Asand renders the per-command help.Spec(). The OSSbootstrapstub usesPassthrough:trueso:bootstrap/--help/Pro flags still yield the Business-Edition notice and no Pro flag internals enter the OSS repo (respects the Pro Feature Boundary).CLAUDE.md: documented the Command Spec pattern and the new-command requirement.Behaviour
:bootstrap --helpand:help bootstrap-> Usage/Flags/Examples screen.:bootstrap --upgrad-> inlineunknown flag --upgrad for :bootstrap, did you mean --upgrade?:quit --xyz-> rejected (global strict applies to zero-flag commands too).Breaking
Previously-ignored unknown flags are now rejected. The two existing
parse_test.gocases that fednode --verboseare intentionally repointed at the passthroughbootstrapcommand — flag/positional separation is still covered, and strict rejection is covered by new cases.Cross-repo
This OSS change defines
registry.CommandSpec; the companionswarmcli-bePR (bootstrap/license specs) must merge after this one or pro CI fails withundefined: registry.CommandSpec.Tests
go build,go test ./..., andgolangci-lint run ./...all green. Added:registry/spec_test.go,commands/command/help_test.go, parse_test extensions.🤖 Generated with Claude Code