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

Record ConfigKit adoption scope and deferred inspection work

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-04 14:32:02 +00:00
parent ce8ab3be38
commit 16584084b1
2 changed files with 139 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
docs/roadmap/configkit-v1.1.0.md
View File

@@ -1,9 +1,9 @@
# ConfigKit v1.1.0 adoption # ConfigKit v1.1.0 adoption
Status: proposed; dependency and report changes are not implemented. This Status: recommended adoption scope recorded; implementation has not begun.
roadmap covers the embedded `ckconfig` integration, the API coverage review, This roadmap covers the embedded `ckconfig` dependency and source-report
and recommended extensions. Release coordination and capability scope have migration. [Recommended scope decisions](#recommended-scope-decisions) record
recommendations under [Open Decisions](#open-decisions). the first sprint and the extensions deferred to later work.
## Purpose and authority ## Purpose and authority
@@ -138,40 +138,20 @@ link to the owning inspection contract for their semantics. Describe the report
migration plainly in the release note. The target uses the new field names migration plainly in the release note. The target uses the new field names
without duplicate legacy report fields. without duplicate legacy report fields.
ConfigKit's source inventory also supplies `EmptyImportSelections`, with Include `EmptyImportSelections` as `empty_import_selections` in both text and
declaration path, location, and selector. OD-2 addresses including this evidence YAML source reports under OD-2. Project each declaration path, location, and
in the existing source report; it is not yet a selected report-schema addition. native selector in the returned record order. Emit `empty_import_selections: []`
when there are no records. These are planned report changes; update the owning
CLI contract when implemented.
### Recommended inspection expansion ### Deferred inspection expansion
After the dependency and source-report adoption, prioritize an optional Metadata inspection and path discovery are recommended as the next functional
metadata capability for field inspection, path discovery, and provenance sprint after adoption (OD-3). Failed-load source inventory, detailed comparison,
history. A narrow provider facet could expose ConfigKit's public `Metadata` and structured diagnostics remain separate later proposals (OD-4 through OD-6).
value directly. `FromConfigKit` can supply it from the loaded result; custom The [configuration inspection extensions](deferred.md#configuration-inspection-extensions)
scopes can declare the operations for which they provide the capability. record owns their proposed capabilities and design considerations. None is part
This is a proposed extension, not a new requirement on existing providers. of this adoption sprint or a new requirement on existing providers.
Use upstream `Lookup` and `IsExplicit` for effective field metadata,
`HistoricalPaths` for observed-path enumeration, and `History` for definition,
inheritance, and resolution records. `HistoricalPaths` includes effective and
removed paths; it is not simply a list of current fields. Scope the report to
the returned upstream evidence rather than inferring an independent provenance
model. Command names, selectors, and report shapes need a focused design once
this extension is selected; this roadmap does not establish their grammar.
Field-origin inventories are currently among the
[deferred proposals](deferred.md#other-deferred-proposals). OD-3 proposes
reconsidering that scope based on the reviewed public API. If selected, update
that record and the owning CLI/API documentation with implementation. Retaining
the proposal here does not by itself mark the extension accepted or implemented.
Failed-load source inspection, detailed comparison reports, and structured
diagnostics remain separately considered additions under OD-4 through OD-6.
They use existing upstream evidence, but each changes CommandKit's presentation
or outcome coordination and needs its own scope choice. In particular, source
inventory output on an acquisition error would retain the failed outcome;
additional comparison detail would expose the native left/right snapshots,
presence/redaction fields, and `HiddenChanged` already returned to the provider.
### Consumer migration and module coordination ### Consumer migration and module coordination
@@ -192,54 +172,72 @@ compatibility loader or impose new configuration restrictions.
ckprompt's current ConfigKit types come from the old package identity. It cannot ckprompt's current ConfigKit types come from the old package identity. It cannot
simply select the new ckconfig release while retaining that wiring. Its later simply select the new ckconfig release while retaining that wiring. Its later
adoption needs a coordinated ConfigKit/PromptKit migration and review of its adoption needs a coordinated ConfigKit/PromptKit migration and review of its
own adapters and composed example. OD-1 determines scheduling; this roadmap does own adapters and composed example. Under OD-1, prepare ckconfig independently
not select an unreviewed PromptKit release or claim a new matched integration set. first and review ckprompt next. This roadmap does not select an unreviewed
PromptKit release or claim a new matched integration set.
### Interim workspace guidance
Once local ckconfig uses the vanity ConfigKit types, the usual three-module
`go.work` selects it for local ckprompt as well. Until ckprompt migrates, its
old-path ConfigKit inspection and comparison types cannot satisfy the new
ckconfig contracts. This is a temporary composition mismatch, even though each
module can be validated independently against its own dependencies.
During that interval, preserve the ignored local workspace and use `GOWORK=off`
for dependency preparation, tests, and example runs. From the repository root,
with the selected Go 1.27 toolchain on `PATH` and dependencies prepared:
```sh
GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...
(cd integrations/ckconfig && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
(cd integrations/ckprompt && GOWORK=off GOTOOLCHAIN=local go test -mod=readonly ./...)
```
The unchanged ckprompt suite and composed example then use published ckconfig
v0.2.0 and their existing upstream dependencies. Their success does not validate
composition with the migrated local ckconfig. Keep local replacements and
workspace files out of the adoption commit. Resume three-module workspace and
composed-consumer validation after ckprompt's migration; update the ignored
workspace's Go version as needed for its member modules at that point.
When the dependency change lands, update the development guide's workspace
instructions to explain this interval. Restore the aligned-workspace guidance
when ckprompt adopts the new dependencies. Until implementation, the existing
development instructions describe the current compatible baseline.
## Work from the baseline ## Work from the baseline
1. **Confirm scope choices and prepare module metadata.** Resolve OD-1 and 1. **Prepare module metadata for the recommended scope.** Follow OD-1 and
OD-2 and record which proposed extensions, if any, join the adoption release. OD-2; OD-3 through OD-6 remain deferred. Select the
Deferred extensions need not block the dependency migration. Select the
Go 1.27 maintainer toolchain, update ckconfig's requirement, Go 1.27 maintainer toolchain, update ckconfig's requirement,
imports, and minimum, and regenerate authentic sums with workspace discovery imports, and minimum, and regenerate authentic sums with workspace discovery
off. Inspect the resulting dependency graph; do not commit local replacements off. Inspect the resulting dependency graph; do not commit local replacements
or environment files as an adoption mechanism. or environment files as an adoption mechanism.
2. **Adapt APIs and source reports.** Update the native source field accesses, 2. **Adapt APIs and source reports.** Update the native source field accesses,
DTOs, text/YAML output, affected tests, and example code. Apply the selected DTOs, text/YAML output, affected tests, and example code. Add empty-import
empty-import-evidence choice. Preserve current coordination and outcomes evidence, including empty lists and record order. Preserve
except where an explicitly selected extension changes presentation, such as current coordination and outcomes. Adapt upstream results rather than
retaining a failure alongside returned source evidence. Adapt upstream adding domain validation.
results rather than adding domain validation. 3. **Update canonical documentation and notices.** Revise the ckconfig README
3. **Design and implement selected extensions.** Treat metadata inspection and
path discovery as the next functional work item under OD-3, whether included
here or scheduled next. Define its optional provider capability, CLI usage,
and report projection together. For any OD-4 through OD-6 feature selected,
specify its report delivery and outcome behavior before implementation.
Reuse native records and rendering where suitable; avoid a second domain
implementation or a generic framework solely to mirror upstream APIs.
4. **Update canonical documentation and notices.** Revise the ckconfig README
and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources), and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources),
consumer guide, and release toolchain instructions with the implemented consumer guide, release toolchain instructions, and development workspace
changes. Review the selected graph and upstream notices, then update guidance with the implemented changes. Review the selected graph and
ckconfig attribution with the vanity identity, selected versions, and pinned upstream notices, then update ckconfig attribution with the vanity identity,
source links. Update other module notices only when their actual selections selected versions, and pinned source links. Update other module notices only when their actual selections
change. Preserve published release history. change. Preserve published release history.
5. **Validate the selected end state.** Run the ckconfig suite, including its 4. **Validate the selected end state.** Run the ckconfig suite, including its
maintained example, independently with `GOWORK=off` and read-only module maintained example, independently with `GOWORK=off` and read-only module
metadata on the selected Go 1.27 toolchain. Update focused adapter/report metadata on the selected Go 1.27 toolchain. Update focused adapter/report
assertions for the new vocabulary and faithful projection of returned assertions for the new vocabulary and faithful projection of returned
evidence. Preserve coverage of request forwarding, diagnostics, cancellation, evidence. Preserve coverage of request forwarding, diagnostics, cancellation,
output failures, and supported error identity. Assertions establish output failures, and supported error identity. Assertions establish
CommandKit adaptation; ConfigKit owns tests of its domain correctness. CommandKit adaptation; ConfigKit owns tests of its domain correctness.
For selected metadata capabilities, verify query forwarding and returned Review changed Markdown links, fragments, and examples. Use the interim
field/history projection. For failed-load inventory or detailed comparison, workspace guidance for unchanged modules; record that their independent
verify the selected report and outcome coordination without re-establishing checks do not establish compatibility with the migrated ckconfig. Full
upstream acquisition, provenance matching, or sensitivity behavior. composed-workspace validation belongs to the later ckprompt migration.
Review changed Markdown links, fragments, and examples. If coordinated 5. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the
ckprompt work is selected, also validate that module and the composed consumer
against the proposed dependency set; local-workspace success alone does not
establish independent module compatibility.
6. **Prepare the integration release.** Propose ckconfig v0.3.0, subject to the
existing fresh-version guards, with tag `integrations/ckconfig/v0.3.0`. existing fresh-version guards, with tag `integrations/ckconfig/v0.3.0`.
Explain changed ConfigKit type identity, Go minimum, report fields, and Explain changed ConfigKit type identity, Go minimum, report fields, and
consumer migration in its checked-in note with the usual licensing footer. consumer migration in its checked-in note with the usual licensing footer.
@@ -254,107 +252,35 @@ Implementation is complete when ckconfig's actual module metadata and imports
select the new dependency, the selected report changes faithfully expose its select the new dependency, the selected report changes faithfully expose its
returned evidence, the module suite and maintained consumer pass independently, returned evidence, the module suite and maintained consumer pass independently,
and current documentation, notices, and release preparation describe that state. and current documentation, notices, and release preparation describe that state.
Record resolved scope choices, final validation evidence, and the status of Record final validation evidence and the temporary workspace composition
each proposed extension. Features selected for this implementation need their status. OD-3 through OD-6 remain in deferred work; their implementation is not
own provider/report evidence; recording a deferred proposal does not demonstrate a completion condition for this sprint. A future source release is reported
its implementation. A future source release is reported separately from separately from implementation completion; preparing this roadmap does not publish a version
implementation completion; preparing this roadmap does not publish a version
or migrate external applications. or migrate external applications.
## Open Decisions ## Recommended scope decisions
### OD-1: Release ckconfig first or coordinate both integrations? These dispositions record the review recommendations for the adoption sprint.
They define its planned scope, not implemented contracts or authorization to
publish. Deferred features still need focused API and CLI design.
**Recommendation:** implement and release ckconfig independently first, and | Decision | Recommended disposition | Reason |
review ckprompt's upstream migration as the next integration task. This keeps | --- | --- | --- |
the current scope concrete and uses the established independent module releases. | OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep this sprint focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. |
Existing ckprompt v0.2.0 consumers retain their published dependency set; document | OD-2: Empty-import evidence | Include `empty_import_selections`, with `[]` when empty, in text and YAML source reports. | Exposes existing upstream evidence alongside the other report-schema changes. |
that moving them to the new ckconfig needs the corresponding ckprompt migration. | OD-3: Metadata and path discovery | Defer to the next functional sprint after adoption. | A coherent optional capability needs its own field/history report and command design. |
The tradeoff is an interval with no newly aligned release pair. | OD-4: Failed-load source inventory | Defer to a separate source-inspection enhancement. | Requires source evidence on error and deliberate report/failure coordination. |
| OD-5: Detailed comparison | Defer; retain the existing reduced report in this sprint. | A richer form needs a report-selection and compatibility decision. |
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering in this sprint. | Coordinate machine-readable records with shared reporting and outcome delivery. |
**Viable alternative:** complete the ConfigKit/PromptKit review and both The first sprint therefore covers dependency and API migration, source-report
integration migrations before releasing the next pair, publishing ckconfig first terminology and empty-import evidence, documentation and notices, independent
in dependency order. This gives composed consumers a coordinated adoption path module validation, and ckconfig release preparation. Core retains its own Go
and validates the shared type boundaries together. It expands this work into minimum. Application loaders continue to own discovery and loading policy.
PromptKit adoption and delays ckconfig availability while that review and
implementation proceed. No simultaneous tag publication is needed.
### OD-2: Include empty-import-selection evidence in this adoption? Coordinating both integrations before release remains an alternative if a
matched adoption path becomes necessary. It would expand the sprint to include
**Recommendation:** add `empty_import_selections` to the existing text/YAML PromptKit review and ckprompt migration; publication would still proceed in
source report, projecting ConfigKit's declaration path, location, selector, and dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions)
record order. This exposes structured source evidence already available retains the capability proposals and unresolved design choices for OD-3 through
upstream without a new command or a second explanation engine. It adds report OD-6, plus the possible source-ID filter.
mapping and focused projection coverage alongside the other schema changes;
the exact empty-list presentation should be settled with the implemented report.
**Viable alternative:** limit this release to migrating the evidence already
reported, and defer this additive field to a later inspection enhancement. That
reduces the immediate report change and test scope, and still makes the native
metadata available to Go consumers of ConfigKit. CLI consumers would continue
to lack this upstream evidence, and a later release would need another report
and documentation update.
### OD-3: When and how should metadata inspection and path discovery land?
**Recommendation:** make optional metadata inspection and path discovery the
next functional expansion after adoption. Expose the upstream metadata queries
through an optional facet, and design field and history reports together. This
adds explicitness, path discovery, and provenance information that current
explanations do not fully expose, while keeping existing providers usable.
It requires a focused CLI/API design and a later release if staged separately.
**Viable alternative:** include that coherent expansion in the adoption release.
This gives consumers the broader inspection surface with one migration and
documentation update. It increases the current release's API, report, and
validation scope and can delay the dependency upgrade. Either schedule can use
the same upstream-owned query semantics; final command grammar remains a design
choice rather than a contract selected by this roadmap.
### OD-4: Expose acquired sources when a configuration load fails?
**Recommendation:** evaluate this as a separate source-inspection enhancement,
presenting `LoadError`'s returned inventory while retaining the load failure and
diagnostics. It makes upstream acquisition evidence available for troubleshooting
without treating the operation as successful. The design must account for
returning the source facet on error and delivering a report before terminal
failure presentation; that coordination is additional to mechanical adoption.
**Viable alternative:** include this behavior in the adoption release alongside
the source-report changes. It delivers successful and failed-load inventory
inspection together and avoids another source-report release. It broadens the
current adapter and outcome changes and requires focused coverage of report
delivery failures as well as acquisition failure. Retaining current diagnostic
context alone until that work is selected remains viable.
### OD-5: Add a detailed native comparison report?
**Recommendation:** consider an additional report form in a later comparison
enhancement, retaining the current reduced form for its established operator
use. The detailed form would project `Path`, both snapshots, and `HiddenChanged`
from native records, making already-returned evidence available to CLI consumers.
Supporting two forms adds selection, presentation, and documentation work;
choose the interface when the feature is selected.
**Viable alternative:** replace the reduced report with native-record projection
in a pre-v1 minor release. One report form is simpler to maintain and exposes
all current comparison fields directly. It requires deliberate migration of
published report consumers and changes the concise additions/changes/deletions
workflow. Keeping only the current form is also viable when that workflow meets
consumer needs; richer reporting is a capability proposal, not a correctness fix.
### OD-6: Where should structured diagnostic reporting be introduced?
**Recommendation:** retain native diagnostic rendering for this adoption and
consider structured records with CommandKit's shared reporting design. That
keeps result and diagnostic delivery consistent across integrations and custom
commands. It defers machine-readable native codes, paths, severities, and
locations until their report channel and outcome behavior are designed.
**Viable alternative:** add an optional ckconfig-specific diagnostic report that
projects ConfigKit's records directly. This could deliver useful structured
evidence sooner without redesigning the shared reporting API. It introduces a
separate presentation path whose interaction with ordinary results, warnings,
and terminal failures needs definition and may later need alignment with other
families. It is a lower-priority extension rather than a dependency-adoption
requirement.

49
docs/roadmap/deferred.md
View File

@@ -25,6 +25,50 @@ unselected extensions to the delivered ConfigKit comparison. Consider them only
for a concrete consumer need and a deliberate API/behavior decision under the for a concrete consumer need and a deliberate API/behavior decision under the
relevant ADRs. relevant ADRs.
### Configuration inspection extensions
The [ConfigKit v1.1.0 adoption review](configkit-v1.1.0.md#recommended-scope-decisions)
recommends the following work after dependency and source-report adoption.
Metadata inspection is the recommended next functional sprint; the other
features have no selected sequence or delivery date. These proposals do not
establish command grammar, report schemas, or new provider requirements.
ConfigKit's public APIs own the evidence and its semantics.
- **Optional field metadata, path discovery, and history (OD-3).** Expose native
`Metadata.Lookup`, `IsExplicit`, `HistoricalPaths`, and `History` through an
optional provider capability. Design field and history reports together,
keeping existing providers usable. Distinguish effective paths from removed
historical paths: a failed `Lookup` must not suppress available `History`.
Validate that distinction and faithful projection of returned field/change
records without recreating upstream provenance logic. Historical enumeration
is not an exhaustive inventory of possible schema fields. This gives the
earlier field-origin inventory proposal a concrete, upstream-backed scope;
command names, selectors, and report shapes remain to be designed.
- **Failed-load source inventory (OD-4).** Present acquired source evidence from
`LoadError.Sources()` while retaining the failed outcome and diagnostics.
Design how an adapter returns its source facet on error and how result output
precedes terminal failure presentation. Cover acquisition and report-delivery
failures together; current diagnostic context remains available meanwhile.
- **Detailed comparison (OD-5).** Consider an additional form projecting native
`Difference` paths, both snapshots, presence/redaction fields, and
`HiddenChanged`. The adoption sprint retains the reduced
additions/changes/deletions report. Decide later whether a detailed form
complements it or replaces it through a deliberate compatibility change.
- **Structured diagnostics (OD-6).** Consider machine-readable native codes,
paths, severities, and locations alongside CommandKit's shared reporting
design. Define result/diagnostic channels, warning and terminal-failure
interaction, and delivery outcomes. A ckconfig-specific report remains an
alternative, with its cross-family alignment considered explicitly.
- **Source-ID filtering.** Consider selecting a record already available in the
source inventory. Native `Source(id)` lookup is a convenience; this proposal
need not introduce another command or require a lookup method from every
custom source provider.
Discovery, import defaults, collection identities, and field-level resolution
recording remain available through application loaders. Standard inspection of
resource contexts or secrets-directory bootstrap has no immediate proposal;
those capabilities primarily serve application loading and startup.
### Alias completion and discovery ### Alias completion and discovery
The delivered [shell completion feature](../cli.md#shell-completion) provides The delivered [shell completion feature](../cli.md#shell-completion) provides
@@ -47,8 +91,9 @@ operator or consumer need and an appropriate ownership/behavior decision:
- JSON reports and output-file management or reloadable export. - JSON reports and output-file management or reloadable export.
- Shell completion extensions, including alias discovery described above and - Shell completion extensions, including alias discovery described above and
dynamic discovery of configured or remote values. dynamic discovery of configured or remote values.
- Configuration mutation, generic value assignment, and exhaustive field-origin - Configuration mutation and generic value assignment. Field metadata and
inventories. provenance inspection are scoped under
[configuration inspection extensions](#configuration-inspection-extensions).
- Credential diagnostics beyond PromptKit's native smoke checks and additional - Credential diagnostics beyond PromptKit's native smoke checks and additional
live provider probes. live provider probes.
- Additional component identity registration and domain artifact catalogs. - Additional component identity registration and domain artifact catalogs.