commandkit/docs/roadmap/configkit-v1.1.0.md

ConfigKit v1.1.0 adoption

Status: recommended adoption scope recorded; implementation has not begun. This roadmap covers the embedded ckconfig dependency and source-report migration. Recommended scope decisions record the first sprint and the extensions deferred to later work.

Purpose and authority

Adopt go.maximumdirect.net/configkit v1.1.0 and expose its capabilities through CommandKit's existing configuration commands in a neutral, consistent way. ConfigKit owns configuration loading, composition, resolution, inspection, and their semantics. CommandKit owns command selection, coordination, presentation, and invocation outcomes. Adapt upstream capabilities faithfully, using current upstream terminology, without adding independent guarantees or commentary qualifying upstream limitations.

This follows the clarified integration goal and the existing architecture policy. The agent, testing, documentation, release, and OSS policies govern implementation. This roadmap proposes work; current contracts remain in GoDoc, the CLI reference, and the consumer guide until implementation lands.

Current baseline and review evidence

Initial review revision: 60841227b7e2928d3fefd3326f0e3f4694f41e6d. API coverage follow-up revision: 7a9e3a1f7cdd0475f06a63ce0aababefe08651bc; library code and module selections are unchanged between these revisions. The completed dependency alignment roadmap records the preceding vanity migration and releases.

Component	Current selection
Core	go.maximumdirect.net/commandkit v0.3.0; Go 1.26.0 minimum
ckconfig	go.maximumdirect.net/ckconfig v0.2.0; Go 1.26.0 minimum
ckconfig dependencies	Core v0.3.0, gitea.maximumdirect.net/eric/ConfigKit v0.8.0, YAML v4.0.0-rc.6
ckprompt	v0.2.0; ckconfig v0.2.0, old-path ConfigKit v0.8.0 and PromptKit v0.16.0; Go 1.26.0 minimum
Maintainer release toolchain	Go 1.26.8, with GOTOOLCHAIN=local

The ConfigKit vanity endpoint and direct Go module discovery resolve v1.1.0 to published commit 191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9. Its module declares Go 1.27.0 and retains the YAML dependency and LGPL-3.0-or-later library grant. The upstream v1.0 migration notes and v1.1 release notes describe the adopted API and behavior changes. Upgrading from v0.8.0 also crosses the import, collection, CLI-assignment, and discovery changes documented in the v0.9 notes and v0.10 notes.

A disposable ckconfig copy passed its complete module suite and maintained simple example tests on Go 1.27.0 after changing the dependency/import path, minimum, two source-reader fields, and affected test APIs. This establishes that the existing adapter structure remains suitable. It did not exercise the proposed report-field renames, additional source evidence, or a migrated ckprompt; final implementation still needs validation of those selected changes.

API coverage findings

The follow-up compared the public API of the pinned v1.1.0 module with ckconfig's provider facets, adapters, and report projections. These are gaps in current integration coverage, not necessarily APIs newly introduced in v1.1.0.

Capability	Current ckconfig exposure	Recommendation
SourceInfo.EmptyImportSelections	Omitted from the source report.	Include in adoption; OD-2.
Result.Metadata(), Metadata.Lookup, and IsExplicit	No metadata facet in View; explanation reports do not expose explicit input presence.	Prioritize optional field-metadata inspection as the next functional expansion; OD-3.
Metadata.HistoricalPaths and History	Operators must already know a path to request an explanation; metadata history records are not exposed.	Pair path discovery and provenance history with metadata inspection; OD-3.
LoadError.Sources() and Source(id)	Acquired sources support diagnostic context, but config sources returns before reporting an inventory on acquisition failure.	Consider failed-load source inspection separately; OD-4.
Full Difference records	The Go comparison provider returns native records; the CLI reduces them to additions, right-side changes, and deletion paths.	Consider an additional detailed comparison report; OD-5.
Structured Diagnostic records	Native writers present diagnostic content; there is no structured native diagnostic report.	Lower-priority candidate, coordinated with shared reporting; OD-6.

The upstream metadata API, source and diagnostic records, load-error API, and comparison API own the returned evidence and its semantics.

The current explanation projection covers every field of v1.1.0's Explanation: effective and historical snapshots, origin and inheritance, reasons, dependencies, and secret-reference names. Improved list-history behavior can flow through that existing adapter. Metadata queries add distinct information: explicitness and null state from FieldInfo, observed paths including removed ones, and Change records with previous origins and operation paths. They need not replace the value-oriented explanation report.

Result.Source(id) is a convenient lookup of records already available through the source inventory. A source-ID filter is a possible usability refinement; it does not inherently require another command or a required lookup method on every custom source provider. Discovery, import defaults, collection identities, and field-level resolution recording fit the application-supplied loader. Source resource contexts and explicit secrets-directory bootstrap primarily serve application loading and startup; there is no immediate recommendation to add standard inspection operations for them. A consumer need could motivate later presentation of their upstream results.

Targeted end state

Dependency and toolchain

The ckconfig module requires go.maximumdirect.net/configkit v1.1.0, and its production code, tests, and maintained example use that import identity. Raise its consumer minimum to Go 1.27.0. Retain its core v0.3.0 requirement unless implementation identifies a concrete need for a newer core API. Core remains independent of ConfigKit and retains its own Go minimum.

Use a Go 1.27 toolchain for ckconfig dependency preparation and validation. Update the maintainer procedure to select an available Go 1.27 release and distinguish the per-module consumer minimums. The existing host-native, workspace-off launcher can use that toolchain without a new toolchain-selection mechanism.

Faithful adaptation and reports

Retain the existing scope, loader, comparison, diagnostic, and reporting structure. Continue using ConfigKit's public results, native rendering, and diff APIs rather than reproducing its domain logic locally. New collection, discovery, and resolution features can be used by application loaders through the adopted library; they do not inherently require additional CLI flags or CommandKit-owned loading policy.

Align the existing source report with ConfigKit's current vocabulary:

Current API or report spelling	Target
SourceInfo.DestinationUnresolved	SourceInfo.DestinationIsFallback
SourceInfo.VersionCheck / SourceVersionCheck	SourceInfo.VersionEvidence / SourceVersionEvidence
Text/YAML destination_unresolved	destination_is_fallback
Text/YAML version_check	version_evidence
Native main layer value base	Native main layer value main

Update DTOs and both report formats together. Preserve the upstream evidence and its supported presence, null, location, ordering, and redaction information through adaptation. Use the upstream terms directly in help and documentation; 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 without duplicate legacy report fields.

Include EmptyImportSelections as empty_import_selections in both text and YAML source reports under OD-2. Project each declaration path, location, and 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.

Deferred inspection expansion

Metadata inspection and path discovery are recommended as the next functional sprint after adoption (OD-3). Failed-load source inventory, detailed comparison, and structured diagnostics remain separate later proposals (OD-4 through OD-6). The configuration inspection extensions record owns their proposed capabilities and design considerations. None is part of this adoption sprint or a new requirement on existing providers.

Consumer migration and module coordination

Public ckconfig signatures expose ConfigKit types, so switching import identity requires consumers to migrate the ConfigKit values they pass across those boundaries. Use the adopted upstream API names in maintained consumers and fixtures. Known test changes include Definition.Secret to Sensitive and Resolution.Record(..., ChangeNormalization, ...) to RecordNormalization. Review other removed pre-v1 symbols where actually used.

Migration guidance should link to upstream for source-root configkit controls becoming config, optional becoming required with changed defaults, identified-collection registrations and operations, and CLI-assignment ordering. Change affected maintained fixtures when present. Application configuration and validation choices remain application-owned; CommandKit does not introduce a compatibility loader or impose new configuration restrictions.

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 adoption needs a coordinated ConfigKit/PromptKit migration and review of its own adapters and composed example. Under OD-1, prepare ckconfig independently 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:

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

1. Prepare module metadata for the recommended scope. Follow OD-1 and OD-2; OD-3 through OD-6 remain deferred. Select the Go 1.27 maintainer toolchain, update ckconfig's requirement, imports, and minimum, and regenerate authentic sums with workspace discovery off. Inspect the resulting dependency graph; do not commit local replacements or environment files as an adoption mechanism.
2. Adapt APIs and source reports. Update the native source field accesses, DTOs, text/YAML output, affected tests, and example code. Add empty-import evidence, including empty lists and record order. Preserve current coordination and outcomes. Adapt upstream results rather than adding domain validation.
3. Update canonical documentation and notices. Revise the ckconfig README and GoDoc, CLI source-report reference, consumer guide, release toolchain instructions, and development workspace guidance with the implemented changes. Review the selected graph and upstream notices, then update ckconfig attribution with the vanity identity, selected versions, and pinned source links. Update other module notices only when their actual selections change. Preserve published release history.
4. Validate the selected end state. Run the ckconfig suite, including its maintained example, independently with GOWORK=off and read-only module metadata on the selected Go 1.27 toolchain. Update focused adapter/report assertions for the new vocabulary and faithful projection of returned evidence. Preserve coverage of request forwarding, diagnostics, cancellation, output failures, and supported error identity. Assertions establish CommandKit adaptation; ConfigKit owns tests of its domain correctness. Review changed Markdown links, fragments, and examples. Use the interim workspace guidance for unchanged modules; record that their independent checks do not establish compatibility with the migrated ckconfig. Full composed-workspace validation belongs to the later ckprompt migration.
5. Prepare the integration release. Propose ckconfig v0.3.0, subject to the existing fresh-version guards, with tag integrations/ckconfig/v0.3.0. Explain changed ConfigKit type identity, Go minimum, report fields, and consumer migration in its checked-in note with the usual licensing footer. A pre-v1 minor fits these intentional compatibility changes. Use the existing selected-module release procedure when publication is requested; this plan adds no release gate. Source publication and hosted Gitea delivery retain their separate outcomes.

Completion evidence

Implementation is complete when ckconfig's actual module metadata and imports select the new dependency, the selected report changes faithfully expose its returned evidence, the module suite and maintained consumer pass independently, and current documentation, notices, and release preparation describe that state. Record final validation evidence and the temporary workspace composition status. OD-3 through OD-6 remain in deferred work; their implementation is not a completion condition for this sprint. A future source release is reported separately from implementation completion; preparing this roadmap does not publish a version or migrate external applications.

Recommended scope decisions

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.

Decision	Recommended disposition	Reason
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.
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.
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.
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.

The first sprint therefore covers dependency and API migration, source-report terminology and empty-import evidence, documentation and notices, independent module validation, and ckconfig release preparation. Core retains its own Go minimum. Application loaders continue to own discovery and loading policy.

Coordinating both integrations before release remains an alternative if a matched adoption path becomes necessary. It would expand the sprint to include PromptKit review and ckprompt migration; publication would still proceed in dependency order. The deferred feature record retains the capability proposals and unresolved design choices for OD-3 through OD-6, plus the possible source-ID filter.