5.3 KiB
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 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.
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.
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.
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.