100 lines
5.6 KiB
Markdown
100 lines
5.6 KiB
Markdown
# 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.
|