4.3 KiB
ADR 0009: Select named configuration scopes with declared inspection capabilities
Status
Accepted.
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 scope targets configuration; a family defines operations on its own resources. A library integration can expose either or both.
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. CommandKit validates declared wiring and registers operations supplied by at least one scope under ADR 0004. Help and scope discovery report actual capabilities from metadata, independently of file loading.
Define narrow integration contracts, reusing upstream public types where useful and introducing CommandKit-owned abstractions where they simplify integration. Preserve supported upstream values, provenance, and confidentiality. Select provider representations against concrete integration needs; exact Go declarations remain API design work under ADR 0003.
--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, diff, and validate default to app. Explicit
--scope all requests aggregate validation or display.
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. ADR 0007 defines combined
presentation. The CLI reference owns implemented selector syntax;
the consumer guide explains acquisition integration.
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. |
Validation defaults to all |
Checks every scope implicitly, but adding a scope without validation support can make bare validation unavailable. |
| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of all become less apparent. |
| Require CommandKit-owned provider types throughout | Gives a uniform abstraction boundary, but can duplicate upstream APIs and require unnecessary adapters. |
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.
An all request can report unsupported coverage; default application inspection
remains independent of other scopes' capabilities. Provider design must balance
simple wiring against dependency coupling as concrete integrations are developed.