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

Record proposed CLI decisions and clarify CommandKit boundaries

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 23:36:06 +00:00
parent 6a0467148e
commit 84234275eb
15 changed files with 1243 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/adr/0001-command-dispatch-and-inputs.md
View File

@@ -41,23 +41,22 @@ inspection uses the single `promptkit` namespace; root `prompt` and `profile`
names remain available to applications. This provides a clear family ownership
boundary without spreading a namespace across root verbs.
Applications register commands outside reserved families. They cannot replace
standard handlers or add private operations underneath a reserved family.
Standard-family context selectors and typed overrides use the defined input
extension mechanism rather than introducing application-owned operations there.
CommandKit accepts custom commands outside its reserved standard families and
reports registration errors for attempts to replace standard handlers or add
private operations beneath them. Its input extension mechanism accepts context
selectors and typed overrides for standard operations.
Applications retain `main`, signal handling, context creation, stream selection,
runtime construction, and final process exit. CommandKit returns invocation
outcomes and does not terminate the process. Configuration schemas, acquisition,
domain resolution and validation, and provider construction remain application
integration responsibilities. ConfigKit and PromptKit retain their own
configuration, provenance, safe inspection, and native rendering semantics.
CommandKit accepts caller-supplied context, streams, handlers, and inspection
providers and returns invocation outcomes. It leaves process termination to the
caller. Executable startup, signals, runtime construction, schemas, acquisition,
and domain resolution remain application choices. CommandKit integrates ConfigKit
and PromptKit through their supported public semantics.
### Explicit registry and capability installation
Each explicitly constructed application instance owns a registry. Applications
register individual commands and composable groups. There is no package-global
registry or import-time `init` registration.
Each explicitly constructed CommandKit instance owns a registry. Its API accepts
individual commands and composable groups. Registration uses explicit instance
state with caller-controlled construction and composition.
Definitions provide paths, descriptions, flags and defaults, repetition and
presence metadata, operand requirements, and execution handlers. One definition
@@ -65,41 +64,49 @@ supplies routing, parsing, and help. Duplicate paths and attempts to replace
reserved commands return registration errors; order does not select a winner.
Help and version are installed automatically using supplied application identity
and build metadata. Configuration and PromptKit families are installed when the
application supplies their providers. Supplying a capability installs its complete
standard family, not a collection requiring manual operation-by-operation wiring.
and build metadata. CommandKit assembles standard families from declared provider
capabilities, installing their supported handlers and metadata together. Each
family defines its own resource model, supported verbs, and per-operation data
contracts. Configuration scopes declare their available inspection operations.
Registering providers does not execute them. Construction may diagnose missing
or invalid wiring without reading configuration, resolving credentials, or
building engines. Invalid configuration is an invocation-time failure. Command
declarations, help, and version remain available independently of application
initialization. The selected handler acquires dependencies when it needs them.
The API allows supported capabilities to be integrated independently. Adding
comparison, catalogs, or other inspection features extends the installed surface
according to the supplied providers. Shared verbs have consistent purposes across
families, while the available subsets reflect their resources and capabilities.
Help and discovery expose those subsets. Registration validates the wiring of
declared capabilities and reports unsupported selections before acquisition.
Do not install placeholder commands. Omitting the configuration provider does
not make a partial integration a complete core adopter. PromptKit is optional;
its selected family is installed as a complete capability. The CLI roadmap owns
the proposed command inventory and the remaining choices for that standard.
CommandKit registration validates declarations with acquisition callbacks left
uninvoked. Its construction, help, and version paths use metadata. The selected
handler requests dependencies when its operation needs them. Invalid configuration
returned by an acquisition callback is an invocation-time failure. Caller code
executed before registration and effects inside callbacks remain caller-owned.
CommandKit installs handlers for supplied capabilities and describes actual
availability. Each enabled operation retains its standard meaning and output
contract. The exact operation inventory and remaining command contracts are
separate design decisions.
### Typed inputs with explicit bindings
Use application-defined input structs for custom commands and CommandKit-defined
inputs for standard handlers. Explicit registration binds flags and operands to
their input fields. The declarations also supply parsing and help metadata.
Handlers do not retrieve primitive values by flag name or parse the complete argv.
The public binding contract accepts application-defined input structs for custom
commands and uses CommandKit-defined inputs for standard handlers. Explicit
registration binds flags and operands to fields and supplies parsing and help
metadata. CommandKit delivers parsed typed inputs to registered handlers.
Use ordinary typed fields where omission has no separate meaning. Where it does,
keep supplied/not-supplied state beside the value in a presence-aware field.
Defaults do not mark input as explicitly supplied. Preserve explicit empty,
false, and zero values.
Bindings support ordinary typed fields and presence-aware fields where omission
has a separate meaning. CommandKit records supplied state independently of values
and defaults, preserving explicitly supplied empty, false, and zero values.
Create fresh input storage per invocation. Registered commands must not capture
one mutable input permanently or retain prior values, collections, or presence.
This decision addresses lifetime without establishing concurrent dispatch.
CommandKit creates fresh input storage per invocation and keeps its previous
parsed values, collections, and presence out of subsequent invocations. Handler
closures and application state retain their own lifecycle. Fresh CommandKit state
addresses invocation lifetime; concurrent dispatch is a separate contract.
Supply context and stream access separately from CLI inputs. Input declarations
and binding setup must not construct execution dependencies. Applications perform
domain validation and may interpret parsed domain values or supply a custom value
parser through the binding system.
The invocation API supplies context and streams separately from CLI inputs.
CommandKit creates its declarations and bindings from metadata and defers its
acquisition calls to the selected handler. The binding system accepts domain value
parsers; domain interpretation and validation belong to registered callbacks.
The public factory, binding, registration, and handler signatures and presence
type names remain API design choices. No illustrative declaration establishes
@@ -111,17 +118,35 @@ Resolve the command and handle help/version before loading application state.
For execution, allocate fresh inputs, apply shared parsing and operand checks,
then invoke the typed handler. Return its invocation outcome to the application.
Shared usage errors and standard-family outcomes belong to CommandKit. Custom
handlers must communicate application-specific outcomes without silent generic
reclassification. For example, Scriptorium output validation and Notarius artifact
outcomes remain application concerns. Do not classify domain errors by matching
message strings or print usage unconditionally for runtime failures.
CommandKit classifies shared usage errors and standard-family outcomes. Its
handler result contract accepts application-specific outcomes and preserves their
supplied classification. Scriptorium output validation and Notarius artifact
outcomes, for example, remain domain results. CommandKit translates results from
explicit classification and emits usage guidance for usage failures.
Common mechanics do not require a common success-report format for custom
commands. The application owns its artifact and operational output contracts.
Exact result/error interfaces and unresolved grammar choices are separate design
work, not approvals implied by this decision.
### Contract scope and consumer guidance
This decision governs CommandKit's public contracts and implemented behavior.
Each operation specifies the inputs, result semantics, callback lifetimes, and
metadata its provider supplies. Consumers choose how to implement those callbacks
and how to structure loading, execution, startup, and process status mapping.
Sharing acquisition and resolution between inspection and execution, and keeping
acquisition focused on producing inspection views, are recommended practices.
CommandKit supports those patterns through reusable inputs and lazy provider
hooks. Its API preserves declared results and coordinates its own calls; arbitrary
application internals remain application-owned.
Cobra isolation applies to CommandKit's exports and internal adapter. Independent
consumer use of another CLI library remains an application choice. Additional
families and source models can use capability contracts appropriate to their
resources, with standard meanings preserved for operations that are installed.
## Alternatives considered
### Dispatcher and ownership
@@ -132,7 +157,7 @@ work, not approvals implied by this decision.
| Standard definitions mounted into an application's framework | Reuses routing infrastructure, but application configuration can preserve inconsistent behavior outside mounted families. Internal framework reuse remains compatible with this decision. |
| Shared metadata/help with separate routing | Unifies discovery but adds synchronization among metadata, routing, and parsing. One dispatcher avoids it. |
| Both full dispatch and embeddable family handlers | Serves established external CLI architectures but adds integration surfaces and maintenance. Add embedding only for a concrete need. |
| Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter needs explicit limitations and is not full adoption. |
| Raw-argument handlers for custom commands | Eases migration but leaves parsing and help responsibilities with applications. A future transition adapter would need to describe its separate parsing and help contract. |
| Universal application runtime framework | Could absorb startup and operational services, but expands beyond the demonstrated CLI boundary and domain ownership. |
| Verb-first standard paths | Groups actions but distributes namespace ownership among individual routes. Namespace/resource-first paths keep family ownership clear. |
| Reserve root `prompt` and `profile` | Provides short resource paths but consumes application namespaces. A single `promptkit` family gives the library one ownership boundary. |
@@ -152,7 +177,7 @@ work, not approvals implied by this decision.
| Parsed-value accessor object | Uniform handlers, but string-based lookup, runtime type errors, and repeated assembly remain. |
| Individual typed parameters | Clear for small commands; grows into long signatures and adapter machinery. Typed structs scale more naturally. |
| Reflection and struct tags | Compact declarations, but adds a tag language, field-discovery rules, and runtime declaration validation. Explicit bindings keep declarations visible. |
| Typed command objects | Can organize complex handlers; must separate fresh input from dependency and execution lifetimes. Applications may use objects without making them mandatory. |
| Typed command objects | Can organize complex handlers. CommandKit's fresh input contract remains separate from caller-owned object lifetimes; objects are an application option. |
| Generated bindings/adapters | Can combine compact authoring and typing, but adds tooling and generated-file maintenance without demonstrated need. |
| Raw arguments | Simple routing integration, but returns common parsing and help to applications. |
@@ -169,11 +194,10 @@ support consistent mechanics without requiring reflection or generated code.
Shared parsing defects can affect every adopter. Consumer and backend integration
evidence must protect selected semantics, including ownership conflicts, help
without configuration, presence, fresh input, cancellation, and domain outcomes.
Intentional migration changes require coordinated application documentation and
subprocess-consumer updates.
CommandKit releases document intentional compatibility changes. Coordinated
application documentation and subprocess-caller updates are recommended migration
practices.
The [architecture policy](../policy/architecture.md) owns normative boundaries.
The [dispatcher roadmap](../roadmap/02-dispatch.md) owns implementation status and
pending API design. The [CLI roadmap](../roadmap/01-cli-plan.md) retains command
proposals and their approval status. [ADR 0002](0002-cobra-backend.md) selects the
backend, and [ADR 0003](0003-public-facade.md) defines its public/internal boundary.
[ADR 0002](0002-cobra-backend.md) selects the backend, and
[ADR 0003](0003-public-facade.md) defines its public/internal boundary.

17
docs/adr/0002-cobra-backend.md
View File

@@ -33,9 +33,11 @@ Reuse their routing, option parsing, help, context, and stream mechanisms and ad
adaptation where selected CommandKit semantics require it.
CommandKit retains its own public registration API, typed inputs, standard
families, and observable contracts. Applications do not construct Cobra commands
or use pflag getters in handlers. [ADR 0003](0003-public-facade.md) isolates the
backend behind an internal adapter and root-owned public contracts.
families, and observable contracts. Its public registration and handler APIs
use CommandKit-owned definitions and typed inputs. Cobra commands and pflag
getters stay within CommandKit's internal adapter. Independent consumer framework
use remains application-owned. [ADR 0003](0003-public-facade.md) records the
adapter and root-owned public contracts.
Applications retain process lifecycle and domain execution. ConfigKit and
PromptKit retain configuration and inspection semantics. Framework selection
@@ -43,7 +45,9 @@ does not transfer those responsibilities to Cobra or CommandKit.
Build fresh backend command/flag state and input storage per invocation. A fresh
command tree constructed from registered definitions is the initial approach.
Tree construction must not load configuration or create application runtime.
CommandKit's tree construction uses registered metadata and leaves acquisition
callbacks uninvoked. Application startup and callback effects retain their own
lifecycle.
Implement one concrete backend. There is no initial public backend selector or
pluggable framework. A future replacement can change internal implementation
@@ -81,10 +85,9 @@ incorporated. Meaningful integration evidence must exercise the real adapter
against selected contracts. A dependency update or replacement can change CLI
behavior even with unchanged Go signatures and is subject to compatibility policy.
The [architecture policy](../policy/architecture.md) owns normative boundaries;
the [backend roadmap](../roadmap/03-backend.md) owns implementation tasks and status.
The [architecture policy](../policy/architecture.md) owns normative boundaries.
[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher and input
model. Remaining command and grammar proposals belong to the CLI roadmap.
model.
Reviewed primary references from the selection:

10
docs/adr/0003-public-facade.md
View File

@@ -45,8 +45,8 @@ method sets must not reveal internal or Cobra/pflag structures. Loosely typed
values and returned errors must not provide indirect backend-object access.
Standard contracts such as `context.Context` and `io.Writer` remain appropriate.
ConfigKit or PromptKit public types may be selected as deliberate integration
dependencies. Application input types remain application-owned. Go declarations
Public types from integration libraries, such as ConfigKit and PromptKit, may
be selected as deliberate dependencies. Application input types remain application-owned. Go declarations
and GoDoc own exact exported contracts.
Confine Cobra/pflag types and operations to an internal adapter. Registry logic,
@@ -103,7 +103,5 @@ CLI behavior or follow the release policy for intentional incompatibilities.
Backend defaults do not independently establish new CommandKit contracts.
The [architecture policy](../policy/architecture.md) owns normative boundaries.
The [facade roadmap](../roadmap/04-facade.md) owns implementation status, package
layout illustrations, and pending work. [ADR 0001](0001-command-dispatch-and-inputs.md)
records the dispatcher/input model, and [ADR 0002](0002-cobra-backend.md) selects
the initial backend. The CLI roadmap retains individual command approval status.
[ADR 0001](0001-command-dispatch-and-inputs.md) records the dispatcher/input model,
and [ADR 0002](0002-cobra-backend.md) selects the initial backend.

99
docs/adr/0004-standard-inspection-surface.md Normal file
View File

@@ -0,0 +1,99 @@
# ADR 0004: Define standard inspection operations by family and capability
## Status
Proposed
## Date
2026-10-06
## Context
CommandKit serves applications with shared configuration and PromptKit inspection
needs. A defined operator surface establishes the infrastructure CommandKit
provides. Different integrations expose different resources and inspection
capabilities, while shared verbs benefit from consistent meanings.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes dispatch, registration,
capability-based installation, and the boundary of CommandKit policy. The remaining
decisions are the operator questions the initial standard answers.
## Decision
CommandKit supplies help and version reporting and defines configuration and
PromptKit inspection operations. Each family defines its own supported set of
operations. Registration installs handlers for the capabilities supplied by the
integration and exposes their availability through help and discovery metadata.
| Standard operation | Responsibility |
| --- | --- |
| `help` | Describe registered standard and application commands. |
| `version` | Report application version by default; report embedded CommandKit version when explicitly selected. |
| `config scopes` | List registered configuration scopes and supported operations. |
| `config validate` | Validate the selected configuration and its configured definitions. |
| `config show` | Display final effective configuration. |
| `config sources` | Describe the acquired and synthetic input source inventory. |
| `config explain` | Explain effective or historical values and provenance at a selected path. |
| `config diff` | Compare effective configuration selections semantically. |
The optional PromptKit suite supplies `promptkit list prompts`,
`promptkit list profiles`, `promptkit show prompt`, and `promptkit show profile`.
These operations expose captured definition catalogs, prompt metadata, and
backend-completed named execution targets. PromptKit definition capabilities and
its configuration scope are registered according to their available provider
operations. Either can be integrated independently.
CommandKit assembles each installed family from its declared capabilities, keeping
standard handlers and metadata together. The inventory describes available
standard operations; adoption can use the supported subset. Semantic diff depends
on safe comparison snapshots for its selected scope. Its availability is
independent of display, validation, and other inspection capabilities.
Shared verbs keep consistent purposes: `list` enumerates resources, `show`
displays a selected resource, and `diff` compares supported representations. Each
family specializes those purposes for its own resources. For example, a future
FeedKit family could supply `list` and `show` as its intended operation set.
`app version` and root `app --version` report application version. The version
command defaults to `--scope app`; `app version --scope commandkit` reports the
embedded CommandKit release version. `--format` selects presentation of the same
subject. Future component identities can use registered version metadata. Version
subjects are independent of configuration scopes and loading providers.
CommandKit owns vocabulary and observable contracts within its standard families.
Custom execution, rendering, serving, sessions, and artifact workflows retain
their application-owned meanings. Additional shared operations enter through
versioned CommandKit releases under the
[release policy](../policy/release.md#versioning-and-compatibility).
The CLI reference owns exact flags, operands, defaults, and report schemas when
implemented. This record owns operation purposes and capability-based availability.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Initial operations limited to validation and display | Accelerates first integrations. Source explanation, comparison, and discovery remain repeated application infrastructure. |
| Require every operation for every integration | Gives a uniform inventory. One unavailable capability blocks other useful operations and future resource families. |
| Definition inspection through configuration operations alone | Source values and provenance share one path. Captured catalogs and completed execution targets require additional interpretation. |
| Standardize execution and mutation alongside inspection | Expands shared vocabulary to more workflows. Additional domain and state-management contracts require their own evidence and design. |
| Display dependency identities in ordinary application version output | Makes dependency information immediately visible. Application identity becomes coupled to dependency reporting. |
| A combined dependency-version option | Gives a useful diagnostic inventory. Scoped version reporting also supports selecting one identity. |
## Consequences
CommandKit supplies shared handlers with predictable meanings and discovers their
availability from registration. Each enabled operation needs its own data
contract: comparison needs safe snapshots, catalogs need enumeration, and profile
display needs safe execution-target inspection.
Shared operations retain clear purposes. CommandKit release notes describe changes
to its published operations. Coordinated application documentation and caller
updates are recommended migration practices.
Help and discovery describe actual supported capabilities. The
[scope model](0009-configuration-scopes.md),
[inspection lifecycle](0008-inspection-lifecycle.md), and
[comparison policy](0011-semantic-configuration-diff.md) describe the proposed
provider and behavioral contracts supporting this surface.

94
docs/adr/0005-invocation-outcomes.md Normal file
View File

@@ -0,0 +1,94 @@
# ADR 0005: Return explicit outcomes and deliver reports through defined channels
## Status
Proposed
## Date
2026-10-06
## Context
An invocation crosses routing, parsing, provider acquisition, a standard or
application handler, report writing, and the application entry point. Operators
and subprocess consumers need consistent classifications for those stages.
Applications also have meaningful domain outcomes of their own.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes process and domain
ownership. [ADR 0003](0003-public-facade.md) establishes public error and backend
boundaries. The remaining decisions concern the public outcome model, report
and diagnostic channels, and standard process-status mappings.
## Decision
CommandKit returns an invocation outcome with an explicit classification and
recommended process status. The public model distinguishes successful operation,
usage error, operational failure, and application domain outcome. Failures retain
their consumer-facing cause and supported `errors.Is`/`errors.As` identity.
Exact Go declarations remain part of facade API design.
Use these mappings for CommandKit-owned commands:
| Status | Meaning |
| --- | --- |
| `0` | The requested operation completed successfully, including help and completed comparison. |
| `1` | A syntactically valid operation failed during loading, validation, lookup, inspection, cancellation, diagnostics delivery, or report writing. |
| `2` | The invocation failed command, flag, scope, format, operand, repetition, or input-combination validation. |
CommandKit's handler result contract accepts domain classifications and suggested
process statuses supplied by the caller. CommandKit preserves that classification
when returning the handler's result.
A custom domain status and a shared usage status may have the same numeric value;
their explicit classifications retain their distinct meanings. The application
entry point controls final process termination and status mapping.
CommandKit writes standard reports to the supplied report stream, conventionally
stdout, and its warnings and errors to the supplied diagnostic stream,
conventionally stderr. Callers choose the streams. Each CommandKit diagnostic has
one delivery owner and one emission through the selected channel. The provider
contract carries acquisition diagnostics and their delivery state so CommandKit
can present pending diagnostics once. CommandKit adapts backend
syntax failures into its public classification and safe diagnostic presentation.
Usage guidance accompanies usage errors; operational failures receive diagnostics
appropriate to the failed operation.
Warning severity alone permits a successful operation. A diagnostic writer
failure is an operational failure. Source coordinates and source-ID legends are
preserved where supplied by the owning library.
Report writers use the application's supplied streams. Shell redirection provides
file output for the initial standard. A writer failure can leave a partial report
and returns operational failure. The outcome identifies incomplete delivery;
checking it before interpreting reports is recommended caller practice. Custom
handler output remains application-owned. Multi-scope loading and ordering follow
[the YAML report policy](0007-native-yaml-reports.md).
A completed semantic comparison returns success with its differences and coverage
gaps recorded in the report. Its outcome describes successful inspection; the
application or consuming script can interpret differences according to its task.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| A single failure classification | Simplifies outcome handling. Callers derive syntax, operational, and domain distinctions through additional interpretation. |
| Backend errors and output as the public outcome model | Reuses framework machinery directly. Backend conventions become dependencies for applications and subprocess consumers. |
| One common mapping for application domain failures | Produces uniform numeric statuses. Applications adapt existing artifact and execution outcomes to shared categories. |
| Handler-owned diagnostics for every failure | Gives each handler full presentation control. Shared diagnostic consistency requires repeated ownership and formatting coordination. |
| Dedicated file-output options | Adds direct file targeting. The standard acquires creation, replacement, and retention responsibilities alongside report writing. |
## Consequences
The outcome model supports both Go callers and executable entry points. Explicit
classification keeps domain identity intact through adapter and facade conversion.
Single diagnostic ownership supports predictable presentation.
CommandKit handlers and writers coordinate cause propagation and delivery
responsibility. Output failures may produce partial bytes; callers receive an
outcome describing delivery failure. The public result/error design preserves
these semantics
through fresh invocation state and private adapter callbacks.
Acceptance establishes the compatibility meaning of these status values and
delivery rules across standard commands.

104
docs/adr/0006-command-grammar.md Normal file
View File

@@ -0,0 +1,104 @@
# ADR 0006: Apply common command grammar and recommend shared vocabulary
## Status
Proposed
## Date
2026-10-06
## 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
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
CommandKit-owned commands. Its shared dispatcher and binding APIs implement that
grammar, so application-owned commands registered through those APIs receive the
same parsing mechanics. Applications retain ownership of their command names,
operand meanings, and domain behavior.
CommandKit's documentation recommends the same grammar and vocabulary for
application-owned commands, including commands implemented outside its dispatcher.
Applications are encouraged to use standard verbs such as `help`, `list`, and
`show` where their operations have the corresponding purposes described in
[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.
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.
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.
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.
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).
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| 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. |
| 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.
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.

110
docs/adr/0007-native-yaml-reports.md Normal file
View File

@@ -0,0 +1,110 @@
# ADR 0007: Use native YAML and ordered documents for inspection reports
## Status
Proposed
## Date
2026-10-06
## Context
ConfigKit and PromptKit provide native YAML configuration inspection. Reusing
their writers preserves captured value semantics, ordering, and redaction. YAML
also supports automated consumption of structured reports.
The agreed initial direction is YAML-based structured inspection with JSON
deferred, and separate native documents for `config show --scope all`. The
remaining choices concern report defaults, document framing, and when output
begins relative to configuration loading.
## Decision
The initial standard uses text for concise operator reports and YAML for
structured consumption. JSON retains deferred status; a future format extension
is evaluated against a concrete consumer need.
| Operation | Default report | Available initial formats |
| --- | --- | --- |
| `help` | Text | Text |
| `version` | Text | Text, YAML |
| `config scopes`, `validate`, `sources`, `explain`, `diff` | Text | Text, YAML |
| `config show` | Native YAML | YAML |
| `promptkit list/show` | Text | Text, YAML |
These format choices govern initial configuration and PromptKit reports and
version reporting. Additional families select formats appropriate to their own
resources through their command contracts. Custom handler formats remain
application-owned. Version format selection preserves the selected subject under
[ADR 0004](0004-standard-inspection-surface.md).
Operations with a format choice use `--format text|yaml`. Format names are
lowercase. YAML-only display uses its native writer directly. Help presents its
registered text form. Format validation follows the usage outcome policy in
[ADR 0005](0005-invocation-outcomes.md).
A single-scope `config show` writes the owning library's complete native redacted
YAML. Its output consists of the inspection document itself. The native writer
preserves effective presence, null and container distinctions, stable mapping
order, and sequence order according to its public contract.
`config show --scope all` emits one native document per registered scope in the
order defined by [ADR 0009](0009-configuration-scopes.md): application first,
PromptKit next when registered, followed by additional scopes in identifier order.
Each document begins with `---` and a `# scope: NAME` comment. A one-scope `all`
selection uses the same labeled document form.
CommandKit writes the separators and comments around the native writer output.
Comments label scopes for operators; document order follows the registered scope
inventory. That framing offers callers an association between documents and
scopes. Each scope retains its own value namespace and native rendering.
The combined stream is an inspection report whose documents can be decoded
individually.
CommandKit checks operation availability for selected scopes before acquisition.
It acquires their views and completes validation required by those provider
contracts before report output begins. A failure returns its diagnostic outcome
before report writing. After writing begins, a writer failure may leave partial
bytes and returns operational failure under ADR 0005.
Other structured reports use operation-specific YAML schemas and selection
metadata. They contain one document and a trailing newline. Native explanation
snapshots retain their safe YAML text and presence/redaction metadata when
projected into structured reports. The CLI reference owns exact schemas and
field names after implementation.
Report confidentiality follows the owning libraries' sensitivity classifications.
Their safe writers and records supply redacted content. CommandKit preserves
those confidentiality semantics; arbitrary caller content retains the caller's
disclosure policy.
Report delivery uses the supplied streams and the channel policy in ADR 0005.
Configuration path syntax follows ConfigKit's JSON Pointer contract independently
of serialization format.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| A scope-keyed YAML wrapper | Carries scope identity as parsed mapping keys. Rendering needs an additional wrapper representation and indentation of native documents. |
| JSON alongside YAML initially | Serves JSON-specific tools. The library maintains another serializer and representation contract. |
| YAML as every report's default | Provides uniform structured output. Interactive help, tables, and explanation workflows use structured documents for routine discovery. |
| Output each scope as acquisition finishes | Starts reporting earlier. A later acquisition failure can leave a successful prefix representing only part of the selection. |
| Marshal application runtime structs | Reuses application data types. Presence, captured resolution, ordering, and safe historical inspection need a separate rendering lifecycle. |
## Consequences
Native display preserves owning-library behavior and keeps rendering focused.
Combined inspection requires multi-document YAML consumption and an ordered scope
contract. The comments label documents, and the ordered inventory supports
identification.
Loading all scopes before output adds preparation time and allows a failure in
one selected scope to prevent combined output. Explicit single-scope inspection
remains available for a narrower view. Writer failures remain visible through
outcomes and may leave partial output.
Additional structured schemas are compatibility contracts owned by CommandKit.
Native concatenation can use existing writers; semantic comparison separately
requires the safe structured data described in
[ADR 0011](0011-semantic-configuration-diff.md).

114
docs/adr/0008-inspection-lifecycle.md Normal file
View File

@@ -0,0 +1,114 @@
# ADR 0008: Coordinate inspection through provider-supplied captured views
## Status
Proposed
## Date
2026-10-06
## Context
Operators use inspection to understand effective configuration and definitions.
An owning library's captured view gives values, provenance, and definition
metadata a coherent source. Application callbacks provide acquisition and domain
resolution that CommandKit cannot independently implement or audit.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes lazy registration and
the boundary between library contracts and application guidance. This decision
covers CommandKit's use of loaded views and its invocation-local coordination.
## Decision
### CommandKit behavior
CommandKit invokes the registered provider when an inspection operation needs
its data. Standard handlers consume the provider's captured inspection views
through supported public contracts. Effective display uses final values supplied
by that view; source inventory and explanation use its provenance; definition
operations use its catalogs and resolved targets.
CommandKit coordinates declared dependencies and reuses compatible provider
results within an invocation. It requests each distinct resolved selection once
through that coordination path. Semantic diff requests independently resolved
left and right captures under [ADR 0011](0011-semantic-configuration-diff.md).
Provider-internal loading remains outside this coordination boundary.
`config validate` invokes the registered validation capability for each selected
scope and propagates its result. The PromptKit integration requests its public
configuration-validation operation, whose intended coverage is all configured
definitions. CommandKit uses the upstream operation's documented semantics;
additional upstream capabilities are needed where the public API lacks that
coverage.
CommandKit's inspection handlers acquire views, query them, validate through the
registered capability, and write reports. Model execution, request preparation,
capacity admission, artifact production, and operational preflight are domain
handler responsibilities outside the standard inspection family.
Help, version, and scope discovery use registration metadata independently of
inspection capture. Construction and those metadata operations leave acquisition
callbacks uninvoked.
### Provider contract
An inspection provider supplies views with the semantics required by its declared
operation. For the ConfigKit and PromptKit integrations, CommandKit consumes their
supported public inspection results and native writers. It preserves supplied
presence, resolution, provenance, and confidentiality semantics.
The provider boundary communicates selection identity, declared dependencies,
applicable operations, loading failures, and acquisition diagnostics. Loading and
validation steps are those required to produce the owning API's inspection result.
CommandKit requires the corresponding result contract, while the callback's
internal organization remains application-owned.
Acquisition can read files, environment values, or credentials and can perform
application-selected bootstrap work. CommandKit propagates supplied diagnostics
under [ADR 0005](0005-invocation-outcomes.md) and exposes supplied requirements in
help. Its coordination contract governs its own calls; callbacks retain their own
effects. CommandKit's API offers acquisition and inspection hooks independently
of application runtime construction.
CommandKit integrations adopt upstream capabilities through supported public
APIs. Secret classification and native rendering follow those APIs. New catalog,
comparison, or profile inspection support is an integration dependency for its
respective operation.
### Recommended application practice
Sharing loading and domain-resolution code between inspection and execution is
recommended: equivalent inputs can then produce equivalent effective values and
provenance. Acquisition callbacks are best kept focused on producing those views,
with application work performed by execution handlers.
These recommendations describe useful consumer structure. Applications control
their execution pipeline, callback implementation, credential lifecycle, and
bootstrap policy. CommandKit's decisions govern the hooks it offers and how its
handlers use the results.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Render mutable runtime configuration structs | Gives direct access to application values. Captured provenance, presence, and resolution need additional synchronization. |
| Reparse effective YAML for catalogs and queries | Uses available serialized data. CommandKit assumes upstream schemas and reconstructs definition semantics. |
| Include operational preflight in standard inspection | Adds readiness information. Inspection acquires provider-execution and state-management responsibilities. |
| Prescribe one consumer loading implementation | Encourages equivalent reports and execution. CommandKit has no authority over arbitrary callback or application internals. |
| Promise credential-independent acquisition | Simplifies an operator expectation. Actual upstream and callback loading requirements may require credentials. |
## Consequences
CommandKit reports describe provider-supplied captured state and preserve its
supported semantics. Dependency coordination reduces repeated provider calls
within an invocation. Shared loading is available as integration guidance.
The API needs clear result ownership, callback lifetime, dependency identity,
and diagnostic delivery. Report accuracy depends on the registered provider's
contract. Acquisition requirements and effects remain visible as supplied
integration metadata.
The [scope model](0009-configuration-scopes.md) and
[selection contract](0010-configuration-selection.md) define related target and
input behavior. Application execution remains outside these library decisions.

102
docs/adr/0009-configuration-scopes.md Normal file
View File

@@ -0,0 +1,102 @@
# ADR 0009: Select named configuration scopes with declared inspection capabilities
## Status
Proposed
## Date
2026-10-06
## Context
An application can expose its own configuration, PromptKit engine configuration,
and other independently meaningful configurations through the `config` family.
A scope identifies the configuration targeted by an operation. Different
providers may support different inspection operations.
Configuration scopes and command families are distinct: a future `feedkit`
family can inspect feeds through its own verbs, independently of whether FeedKit
configuration is also exposed as a configuration scope.
[ADR 0004](0004-standard-inspection-surface.md) defines initial operation purposes.
[ADR 0001](0001-command-dispatch-and-inputs.md) records
installation from declared capabilities.
## Decision
Use stable semantic scope identifiers. The `app` scope describes application
configuration; an optional `promptkit` scope describes captured engine
configuration. Registration also accepts additional independently meaningful
configuration scopes with unique identifiers.
Each scope declares its available inspection operations and their providers.
Capabilities can include validation, native effective YAML, source inventory,
path explanation, and safe semantic comparison data. Scope metadata describes
identity, supported operations, applicable selectors, and dependencies.
CommandKit checks the wiring needed by each declared capability. Additional
operations can be supported as their upstream data becomes available.
Expose scope operations through CommandKit-owned public provider contracts.
Adapters preserve supported upstream values, provenance, and confidentiality.
Exact Go declarations remain API design work under
[ADR 0003](0003-public-facade.md). Separate capability contracts allow new
operations to evolve independently of existing provider implementations.
`--scope NAME` selects one configuration. `all` denotes all registered scopes for
`config validate` and `config show`; `sources`, `explain`, and `diff` select one.
An aggregate selection retains its all-scope meaning. CommandKit checks operation
availability across the requested selection before acquiring views. An unavailable
operation yields a usage diagnostic identifying the scope and available choices,
so an aggregate result accurately describes the requested coverage.
`show`, `sources`, `explain`, and `diff` default to `app`; `validate` defaults to
`all`. Explicit selection remains available for narrower validation. These
selection defaults operate against the registered inventory and capabilities.
Scope order is `app` first when registered, `promptkit` next when registered,
then additional scopes sorted by identifier. `config scopes` and combined YAML
show use that order. The inventory reports identity, description, supported
operations, and selection defaults entirely from metadata. Discovery is available
independently of file loading.
CommandKit validates scope collisions, operation wiring, selector applicability,
and supported selections. It registers the standard operations supplied by at
least one scope, alongside metadata discovery. Help identifies their applicable
scopes; selection of an unsupported scope-operation pair yields a usage diagnostic.
Declared dependencies are coordinated under
[ADR 0008](0008-inspection-lifecycle.md). An inspection operation acquires its
selected scope and required prerequisites through that provider boundary.
A command family defines its own resources, supported verbs, and data contracts.
The configuration provider contract applies to configuration inspection. FeedKit
resource listing or display, for example, can use separate capabilities with
meanings consistent with shared verbs. A library integration can expose a command
family, configuration scope, or both, according to the provided capabilities.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Require every configuration inspection operation per scope | Gives one capability set. Missing comparison or provenance blocks other useful inspection operations. |
| A separate command tree for each configuration | Makes the target part of the path. Repeats common operations and help. |
| One verb set for every library family | Gives a uniform inventory. Resource domains acquire operations with little useful meaning. |
| Executable names as scope identifiers | Relates scopes to application branding. Shared scripts need application-specific identifiers. |
| Every operation defaults to `app` | Gives one selection default. Integrated validation becomes an explicit aggregate request. |
| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of `all` become less apparent. |
| Public upstream result types as the provider API | Simplifies direct wiring. CommandKit acquires those type identities and release dependencies. |
## Consequences
A shared configuration family serves multiple configurations while help and
inventory make operation availability explicit. Individual capabilities can be
integrated before other upstream inspection APIs exist. Default and ordering
rules remain observable CommandKit behavior.
Scoped operations validate availability before loading. An `all` request can
report unsupported coverage; an explicit supported scope remains available.
The same verb purpose can serve different families with different operation sets.
[Selection inputs](0010-configuration-selection.md) define parsing and propagation;
[native YAML reporting](0007-native-yaml-reports.md) defines combined presentation.

100
docs/adr/0010-configuration-selection.md Normal file
View File

@@ -0,0 +1,100 @@
# ADR 0010: Parse and propagate standardized inspection selection inputs
## Status
Proposed
## Date
2026-10-06
## Context
Configuration inspection needs explicit selection inputs and domain context, such
as Narratio's campaign selectors. Shared flag meanings and presence tracking make
those inputs understandable. Source discovery, acquisition, and resolution are
implemented by application integration callbacks.
[ADR 0001](0001-command-dispatch-and-inputs.md) establishes typed bindings and the
standard-family extension boundary and limits policy to CommandKit's contracts
and behavior.
## Decision
CommandKit parses registered selection inputs, preserves explicit values and
presence, and passes them to the selected inspection provider. It offers reusable
bindings so custom execution handlers can receive equivalent selection inputs.
Provider capture follows [ADR 0008](0008-inspection-lifecycle.md).
For integrations based on application configuration, `--config PATH` selects the
application root, including when targeting its PromptKit engine. CommandKit passes
that selection and applicable context to the registered provider. `--scope NAME`
selects the inspected configuration under [ADR 0009](0009-configuration-scopes.md).
An explicit empty root path receives a usage error. An explicit relative CLI path
is interpreted against the invocation working directory. When the selector is
omitted, CommandKit delegates discovery to the registered acquisition callback.
It preserves explicit selection and returns source-loading failures from that
callback as operational failures. CommandKit adds no discovery retry after a
failed explicit selection. File-relative resource resolution belongs to the
owning upstream API or provider.
The ConfigKit overlay integration uses `--overlay NAME`. Omission, an empty name,
and the exact name `default` select the base according to ConfigKit semantics;
other values select a named overlay. This selector describes configuration
composition. PromptKit execution-profile selection has its own resource identity.
Selector registration describes applicable operations and scopes. CommandKit
exposes supported selectors and validates their applicability before loading.
Root selection applies to providers using the application root; ConfigKit
overlay selection applies to providers supporting that composition model.
Other integrations can declare their own source selectors through the same
extension mechanism, keeping shared names consistent where applicable.
The binding API accepts typed configuration overrides and domain context selectors
with help, conversion, applicability, and domain-mapping metadata. Parsing
preserves explicitly supplied empty, false, and zero values, as well as the
registered type semantics of nullable inputs. Registration detects collisions
with standard flags. Parsing validates declared combinations and reports usage
errors under [ADR 0005](0005-invocation-outcomes.md).
CommandKit propagates supplied discovery descriptions, environment requirements,
and defaults-only behavior into help. The provider implements those conventions.
The API passes typed override and context values to integration callbacks; field
mapping and recorded domain resolution are outside CommandKit's implementation.
PromptKit definition operations use the applicable selectors registered for their
provider and target the engine's definition-inspection capabilities.
### Recommended application practice
Sharing discovery, acquisition, and domain-resolution code between inspection and
execution helps equivalent inputs produce equivalent effective values. Reusing
these bindings and using ConfigKit's recorded override and resolution mechanisms
helps preserve provenance. Describing discovery and callback effects in help
helps operators understand acquisition requirements.
These are consumer recommendations. Execution loading, source policies, and
internal application structure remain application choices. CommandKit's decision
covers parsing, validation of declared inputs, metadata, and callback propagation.
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Require an explicit root for every operation | Gives visible selection. Limits discovered, defaults-only, and independently sourced configurations. |
| Define a universal filesystem discovery policy | Gives identical locations. Deployment and packaging become library policy. |
| Require one loading function for every consumer | Encourages inspection/execution parity. Prescribes application internals outside CommandKit's authority. |
| Offer only root, overlay, and scope selectors | Keeps declarations small. Domain context and additional source models need another entry path. |
| Generic `--set path=value` overrides | Supports arbitrary edits. Requires another value language, conversion contract, and discovery model. |
## Consequences
CommandKit supplies consistent input mechanics and extension points. Provider
metadata determines selector relevance, allowing future source models to fit
without implementing ConfigKit-specific composition. Callbacks receive enough
selection information to produce useful captured inspection results.
Shared loading is recommended integration guidance. CommandKit can preserve and
propagate inputs; parity with actual application execution depends on consumer
implementation. Exact selectors and field mappings belong to their implemented
command contracts.

101
docs/adr/0011-semantic-configuration-diff.md Normal file
View File

@@ -0,0 +1,101 @@
# ADR 0011: Compare semantic snapshots with explicit sensitivity gaps
## Status
Proposed
## Date
2026-10-06
## Context
Configuration comparison helps operators understand changes in final effective
values across roots and overlays. Formatting, authored file layout, and provenance
identifiers are different properties from effective-value equality. Sensitivity
classification also limits the values available for inspection.
Meaningful comparison requires structured effective snapshots with per-path
sensitivity data from the owning libraries. The comparison policy must preserve
value semantics while making limited coverage visible to operators.
## Decision
For a scope declaring safe comparison support, `config diff` compares two
independently resolved effective configurations. CommandKit checks that capability
before acquisition. Registered root, overlay, context, and override selectors
define the left side where applicable. The initial application-root/ConfigKit
integration uses `--against-config PATH`, `--against-overlay NAME`, or both to
select the right side. Other comparison
source models can declare applicable paired selectors through the input extension
contract under [ADR 0010](0010-configuration-selection.md).
Unspecified right selectors inherit the resolved left selection. Discovery is
resolved for the left selection once. An omitted right overlay inherits the left
overlay; the explicit overlay name `default` selects the base. Domain selectors
and typed overrides apply identically to both sides for the initial operation.
CommandKit requests each resolved side through the inspection provider under
[ADR 0008](0008-inspection-lifecycle.md). The provider supplies the captured result
according to its public loading and validation contract.
Compare values using the owning library's safe structured inspection semantics,
including defaults and recorded domain resolution. Preserve the distinctions
among absent values, null, empty mappings, and empty sequences. Mappings are
compared recursively; ordered sequences are compared as whole values. A container
replacement produces one change at the replaced path.
Changes are classified as `added`, `removed`, or `changed` and sorted by JSON
Pointer configuration paths, consistent with the ConfigKit integration. Reports
contain safe before/after snapshots and resolved selection metadata. Presentation
and source identity retain their own metadata roles, while value comparison
operates on the effective semantic representation.
CommandKit's comparison provider contract accepts effective values and
sensitivity metadata through supported public inspection APIs. The comparison
handler consumes inspection-safe data and uses supplied redaction classifications.
Secret resolution remains part of the upstream or callback loading lifecycle.
For each path, use the union of the two sides' sensitivity classifications to
protect both before and after presentation. A value classified on either side
receives the corresponding safe treatment in both snapshots. Hidden values
produce explicit comparison gaps with their paths and supported reasons.
Equality conclusions cover the comparable data. A comparison with gaps reports
its limited coverage alongside observed differences. A complete comparison with
an empty difference set supports an equality conclusion for the inspected
selection. Redaction masks are presentation data; classification metadata
determines comparison coverage.
Text and YAML reports include differences and coverage gaps. The exact report
schema belongs in the CLI reference when implemented. A completed comparison
returns success whether it finds differences or gaps; load, comparison, and
writer failures use the operational failure classification in
[ADR 0005](0005-invocation-outcomes.md).
## Alternatives considered
| Alternative | Analysis |
| --- | --- |
| Rendered YAML line comparison | Reuses native display output. Formatting and masking become part of change interpretation. |
| Compare masks as literal strings | Uses visible snapshot bytes directly. Equal masks express equal presentation while hidden values remain uncertain. |
| Use one side's sensitivity policy | Simplifies classification selection. A value's disclosure treatment depends on which snapshot supplies that policy. |
| Fetch secret values for comparison | Gives access to additional equality evidence. Comparison acquires sensitive material and additional confidentiality responsibilities. |
| Element-by-element sequence diff | Gives detailed collection changes. Stable element identity and alignment need another comparison contract. |
| Independent domain selectors for each side | Supports broader context comparison. The operation acquires duplicated selector sets and pairing rules. |
| A distinct status for observed differences | Supports assertion-oriented scripts. Inspection completion and change detection share an outcome signal. |
## Consequences
Operators receive meaningful effective-value changes with explicit uncertainty
where sensitivity limits comparison. Stable path ordering and whole-sequence
comparison keep reports understandable and implementation scope focused.
Diff support depends on safe snapshots preserving value semantics and sensitivity.
CommandKit applies this comparison policy to scopes declaring that capability.
Other operations and families can be integrated independently under
[ADR 0004](0004-standard-inspection-surface.md).
Applications can use the successful report as input to domain decisions or future
assertion workflows. Separate left/right loading and safe union classification
need evidence for presence, container replacement, sensitivity changes, and
coverage gaps.