Include native inspection adapter in the adoption scope
This commit is contained in:
@@ -28,7 +28,7 @@ Reviewed repository revision: `b1c7962f51eb9e81104a291bc1966a90b4e772a3`.
|
||||
| Component | Baseline | Adoption target |
|
||||
| --- | --- | --- |
|
||||
| CommandKit core | v0.7.0 | No core change required by this scope |
|
||||
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0 and native scoped path enumeration support |
|
||||
| ckconfig | v0.9.0; ConfigKit v1.2.1 | ConfigKit v1.4.0, native scoped path enumeration, and a public native-inspection adapter |
|
||||
| ckprompt | v0.10.0; PromptKit v0.23.2, ConfigKit v1.2.1, ckconfig v0.9.0 | PromptKit v0.24.0, ConfigKit v1.4.0, and the resulting released ckconfig |
|
||||
| Go | Consumer minimum 1.27.0; release toolchain 1.27.4 | No change required by these upstream releases |
|
||||
|
||||
@@ -121,6 +121,28 @@ their native whole-document meaning. An absent effective subtree and explicit
|
||||
null retain their upstream distinction and errors through the existing report
|
||||
delivery mechanism. Do not invent an empty configuration to hide absence.
|
||||
|
||||
### Public native-inspection adapter
|
||||
|
||||
Include a reusable ckconfig adapter in this adoption and the next ckconfig
|
||||
release. It registers a named configuration scope backed by ConfigKit's native
|
||||
subtree inspection, reducing application wiring for effective settings, path
|
||||
discovery, explanations, source evidence, and comparison. Applications retain
|
||||
configuration acquisition and selection; the adapter supplies standard CLI
|
||||
integration and delegates domain operations to ConfigKit.
|
||||
|
||||
Design this adapter together with the shared native path-enumeration capability.
|
||||
Demonstrate one application section, such as storage settings, in the maintained
|
||||
composed example. The section name is illustrative, not a new reserved scope.
|
||||
Preserve load diagnostics and error evidence through existing reporting and
|
||||
outcome conventions. A focused inspection does not independently validate a
|
||||
subtree or make whole-load evidence local to it.
|
||||
|
||||
PromptKit uses the shared inspection capability directly. It need not pass
|
||||
through this new helper if that would require converting its public inspection
|
||||
type merely to fit the helper. Exact API shape and evidence handoff remain under
|
||||
discussion in OD-2; acceptance of the feature does not select a new result type,
|
||||
loader framework, or diagnostics policy.
|
||||
|
||||
### Existing commands expose the new upstream evidence
|
||||
|
||||
| Operator task | Existing command | Adoption behavior |
|
||||
@@ -174,8 +196,14 @@ resources and reports, not just successful engine construction.
|
||||
|
||||
### Adapter and example work
|
||||
|
||||
- Implement scoped enumeration through the shared configuration provider boundary
|
||||
and wire the native PromptKit method directly.
|
||||
- Design the adapter's public API and evidence handoff, then implement scoped
|
||||
enumeration through the shared configuration provider boundary and the public
|
||||
ckconfig adapter together. Reuse existing acquisition, diagnostics, comparison,
|
||||
and outcome conventions where they serve the native capability.
|
||||
- Wire PromptKit's native enumeration directly through the shared capability;
|
||||
avoid an extra conversion layer solely to reuse the new adapter.
|
||||
- Demonstrate registration and inspection of one application subtree, including
|
||||
comparison and preservation of available diagnostics on failure.
|
||||
- Restructure the composed example around the shared load, with local fixtures
|
||||
and the existing injected client for smoke demonstrations. Update its consumer
|
||||
walkthrough and meaningful tests together.
|
||||
@@ -225,6 +253,9 @@ layout or hash literals. Tests remain offline and credential-independent.
|
||||
- [ ] Scoped path enumeration uses upstream's listing; existing CLI filters and
|
||||
metadata descriptions still work. A representative whole-load sibling verifies
|
||||
that the adapter does not substitute full metadata enumeration.
|
||||
- [ ] The public ckconfig adapter exposes a native subtree through the standard
|
||||
scope commands, with a maintained example and focused coverage of acquisition,
|
||||
comparison, and diagnostics/error propagation. Its public handoff is documented.
|
||||
- [ ] Explicit paths, source evidence, focused rendering, and comparison preserve
|
||||
native meaning and error handling, including available ancestor evidence.
|
||||
- [ ] Reports preserve returned schema fields, repair-budget zero, and the new
|
||||
@@ -250,33 +281,47 @@ This roadmap selects no new commands, engine-construction convenience API,
|
||||
automatic configuration migration, core cache, or application execution workflow.
|
||||
These are scope decisions for this adoption, not additional permanent prohibitions.
|
||||
|
||||
## Resolved decisions
|
||||
|
||||
### OD-1: Include the native-inspection adapter in this adoption — closed
|
||||
|
||||
Include the helper in the next ckconfig release, as part of this roadmap.
|
||||
Its implementation overlaps the required native enumeration work; designing both
|
||||
together provides a concrete second use of the shared boundary and avoids
|
||||
revisiting that boundary immediately after release. Keep the adapter focused on
|
||||
standard CLI scopes and direct upstream inspection. Preserve native comparison
|
||||
semantics for the views accepted by the selected API.
|
||||
|
||||
The previous deferral recommendation is superseded. The remaining API discussion
|
||||
does not reopen whether to include the feature.
|
||||
|
||||
## Open Decisions
|
||||
|
||||
### OD-1: Add a general native-inspection adapter to ckconfig now?
|
||||
### OD-2: Public API and diagnostics/error handoff
|
||||
|
||||
ConfigKit's non-generic `Inspection` could support a reusable public adapter for
|
||||
applications exposing additional subtree scopes, including native comparison
|
||||
across different root Go types. This is separate from the required narrow path
|
||||
enumeration support used by `ckprompt.ConfigScope`.
|
||||
**Recommendation for discussion: accept the existing typed ConfigKit result
|
||||
loader plus an explicit subtree path.** A sibling of `FromConfigKit` can obtain
|
||||
diagnostics and source evidence from the result, select `InspectSubtree(path)`,
|
||||
and delegate comparison to the native inspection views. On failed loading,
|
||||
reuse the existing handling of ConfigKit load-error evidence and supported error
|
||||
identity. This keeps the ordinary application loader reusable and avoids asking
|
||||
applications to package inspection and diagnostics into a new envelope. The
|
||||
tradeoff is that a callback returning only an already selected native inspection,
|
||||
or different root result types across comparison sides, does not fit this typed
|
||||
loader signature directly. The proposed name and signature are not yet selected.
|
||||
|
||||
**Recommendation: defer the additional public adapter from this sprint.** The
|
||||
existing typed `FromConfigKit` adapter serves the application's result, and
|
||||
`ckprompt.ConfigScope` serves the engine's inspection. Shared loading itself
|
||||
does not require a third adapter. Keep the required native enumeration capability
|
||||
small, and use the revised example to identify any actual remaining boilerplate
|
||||
before selecting another public contract. The tradeoff is that applications
|
||||
wanting additional native subtree scopes must currently assemble the existing
|
||||
scope/provider contract themselves.
|
||||
**Viable alternative: accept an already selected `configkit.Inspection` with
|
||||
its associated acquisition evidence.** This directly serves callers holding
|
||||
native views and allows native comparison across different root Go types.
|
||||
However, the view itself has no diagnostics method, and a failed load may provide
|
||||
sources and diagnostics without any usable view. The API would need a way to
|
||||
carry that evidence, adding application wiring or a public handoff type. Evaluate
|
||||
that complete handoff against the result-and-path approach before selecting it;
|
||||
do not require callers to reconstruct provenance or stringify structured errors.
|
||||
|
||||
**Viable alternative: include a focused native-inspection adapter now.** This
|
||||
could standardize useful CLI subtree scopes and avoid repeated acquisition and
|
||||
comparison wiring across applications. It belongs in ckconfig because it serves
|
||||
operator commands, not application-internal configuration access. However, native
|
||||
`Inspection` does not itself carry the result's diagnostics or acquisition
|
||||
errors; the helper's inputs must account for that evidence without becoming a
|
||||
second result type or loader framework. Before selecting this alternative,
|
||||
demonstrate a concrete scope in the maintained example and compare the complete
|
||||
wiring burden and conceptual cost against using the existing provider API.
|
||||
|
||||
This choice does not reopen the agreed requirement to delegate PromptKit path
|
||||
enumeration and explicit queries to the native upstream methods.
|
||||
For either approach, retain the existing distinction between report evidence
|
||||
and a returned error. Discuss how native diagnostics reach detailed validation,
|
||||
ordinary messages, and terminal explanations without duplicate presentation.
|
||||
Existing error classification remains authoritative; the scope's reporting focus
|
||||
does not imply that unrelated load failures can be ignored or that validation is
|
||||
limited to the selected subtree.
|
||||
|
||||
Reference in New Issue
Block a user