base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 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

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.