base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Simplify ADRs and relax premature constraints

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-07 02:45:09 +00:00
parent 984d159676
commit 7e453a2df2
9 changed files with 165 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/adr/0006-command-grammar.md
View File

@@ -11,16 +11,10 @@ Proposed
## Context
CommandKit owns routing, parsing, and help for standard and registered application
commands. The selected registry and typed-input model supply a shared source for
syntax metadata. A concrete grammar makes option placement, operands, repetition, and
commands. A concrete grammar makes option placement, operands, repetition, and
help predictable across the application suite. Shared vocabulary also reduces
the need to remember different verbs for equivalent operations.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes namespace-first
ownership, typed bindings, explicit presence, and fresh invocation inputs.
The remaining choices concern option placement, operand handling, repetition,
and discovery behavior across registered commands.
## Decision
CommandKit's standard grammar and vocabulary are part of the contract for
@@ -36,25 +30,23 @@ Applications are encouraged to use standard verbs such as `help`, `list`, and
[ADR 0004](0004-standard-inspection-surface.md).
CommandKit parses options after the complete registered command path. Within the
selected command, options and declared operands may be interspersed. Operand counts
and types come from registration; custom operand domain meaning belongs to the
handler.
selected command, options and declared operands may be interspersed. Operand
counts and types come from registration.
Standard options use lowercase names with hyphen-separated words and the `--`
prefix. Value options accept `--name value` and `--name=value`. Boolean options
accept their documented presence form and explicit values such as `--name=false`.
The `--` token ends option parsing; subsequent tokens are operands.
Registered metadata identifies each flag as singleton or repeatable. A singleton
accepts one occurrence per invocation. Repetition across either supported spelling
is a usage error. A repeatable flag accumulates values in invocation order.
Presence is recorded independently of defaults and values, preserving supplied
empty strings, false, and zero under the existing typed-input decision.
Registered metadata identifies each flag as singleton or repeatable. For a
singleton, the last occurrence supplies its value, including when the invocation
mixes supported spellings. A repeatable flag accumulates values in invocation order.
Presence follows the typed-input contract in
[ADR 0001](0001-command-dispatch-and-inputs.md).
CommandKit validates paths, flag names, conversions, operand counts, and declared
input combinations through the shared parser. Those failures use the usage
classification in [ADR 0005](0005-invocation-outcomes.md). Registered domain value
parsers and handlers receive values through the typed binding contract.
classification in [ADR 0005](0005-invocation-outcomes.md).
Root help is available through `app`, `app help`, `app --help`, and `app -h`.
Invoking a command group with no registered execution handler displays group help.
@@ -62,21 +54,8 @@ A runnable command follows its registered handler and operand requirements,
including when it also has subcommands. CommandKit-owned groups such as `config`
display help on bare invocation. `app help COMMAND ...` and a resolved command's
`--help` display the same registered help. Required execution operands are checked
for execution requests; help uses resolved command and flag
metadata. Invalid paths and flag names receive usage diagnostics.
`app version` and the root-only `app --version` shortcut report application version.
The version command also accepts explicit component selection under
[ADR 0004](0004-standard-inspection-surface.md).
Standard configuration operations have declared flag inputs. PromptKit collection
and definition commands declare their resource and ID operands. The registry
generates help, including supported formats and selector applicability, from
those declarations.
The internal Cobra/pflag adapter implements this grammar using registered
metadata and backend parsing mechanisms. Flag values beginning with `-` follow
their registered type and supported value syntax. Parser adaptation is centralized
at that boundary, following [ADR 0002](0002-cobra-backend.md).
for execution requests; help uses registered metadata. Invalid paths and flag
names receive usage diagnostics.
## Alternatives considered
@@ -84,21 +63,16 @@ at that boundary, following [ADR 0002](0002-cobra-backend.md).
| --- | --- |
| Flags before all operands | Gives argument order a simple positional rule. Operators organize values around that rule when assembling commands. |
| Common flags before or between command-path components | Supports familiar global-option styles. Routing and help need rules for options across several command levels. |
| Last singleton occurrence wins | Supports layered argv construction. Repeated assignments become an override mechanism requiring separate presence and precedence interpretation. |
| Reject repeated singleton flags | Detects repeated assignments, but prevents callers from assembling defaults followed by explicit overrides. |
| Application-selected parser conventions | Supports existing CLI implementations. Operators and shared help need per-application syntax knowledge. |
## Consequences
Operators learn one option placement and repetition policy for adopting
commands using CommandKit. Custom handlers retain their operand domain contracts.
Typed bindings and metadata support consistent parsing and generated help.
Shared vocabulary guidance encourages consistent names for equivalent
application-owned operations.
commands using CommandKit. Shared vocabulary guidance encourages consistent
names for equivalent application-owned operations.
The adapter carries the work needed to preserve the grammar across dependency
updates. Contract evidence must cover repetition, mixed spellings, explicit
presence, interspersed operands, `--`, help, and fresh state. Backend replacement
preserves the selected grammar under the release compatibility policy.
The CLI reference owns detailed command signatures and examples when implemented.
This record owns the common rules that apply across those signatures.
The internal adapter must preserve the selected grammar across backend changes.
The [CLI roadmap](../roadmap/01-cli-plan.md) tracks operation-specific syntax;
the CLI reference will own detailed command signatures and examples when
implemented.