From 7a9e3a1f7cdd0475f06a63ce0aababefe08651bc Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 13:14:31 +0000 Subject: [PATCH] Plan ConfigKit 1.1 adoption --- docs/roadmap/configkit-v1.1.0.md | 205 +++++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) create mode 100644 docs/roadmap/configkit-v1.1.0.md diff --git a/docs/roadmap/configkit-v1.1.0.md b/docs/roadmap/configkit-v1.1.0.md new file mode 100644 index 0000000..0e03d98 --- /dev/null +++ b/docs/roadmap/configkit-v1.1.0.md @@ -0,0 +1,205 @@ +# ConfigKit v1.1.0 adoption + +Status: proposed; dependency and report changes are not implemented. This +roadmap covers the embedded `ckconfig` integration. Release coordination and +additional source evidence have recommendations under [Open Decisions](#open-decisions). + +## 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](../policy/architecture.md#backend-and-library-integration). +The [agent](../policy/agents.md), [testing](../policy/testing.md), +[documentation](../policy/documentation.md), [release](../policy/release.md), and +[OSS](../policy/oss.md) policies govern implementation. This roadmap proposes +work; current contracts remain in GoDoc, the [CLI reference](../cli.md), and the +[consumer guide](../consumers/guide.md) until implementation lands. + +## Current baseline and review evidence + +Reviewed CommandKit revision: `60841227b7e2928d3fefd3326f0e3f4694f41e6d`. +The completed [dependency alignment roadmap](integration-dependency-alignment.md) +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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md) +and [v1.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md) +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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md) +and [v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md). + +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. + +## Targeted end state + +### Dependency and toolchain + +The [ckconfig module](../../integrations/ckconfig/go.mod) 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](../release.md#release-toolchain) 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. + +ConfigKit's source inventory also supplies `EmptyImportSelections`, with +declaration path, location, and selector. OD-2 addresses including this evidence +in the existing source report; it is not yet a selected report-schema addition. + +### 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. OD-1 determines scheduling; this roadmap does +not select an unreviewed PromptKit release or claim a new matched integration set. + +## Work from the baseline + +1. **Confirm scope choices and prepare module metadata.** Resolve OD-1 and + OD-2, 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. Apply the selected + empty-import-evidence choice. Retain the existing coordination and outcome + behavior, adapting upstream results rather than adding domain validation. +3. **Update canonical documentation and notices.** Revise the ckconfig README + and GoDoc, [CLI source-report reference](../cli.md#list-configuration-sources), + consumer guide, and release toolchain instructions 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. If coordinated + 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. +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 the resolved scope choices and final validation evidence. A future source +release is reported separately from implementation completion; preparing this +roadmap does not publish a version or migrate external applications. + +## Open Decisions + +### OD-1: Release ckconfig first or coordinate both integrations? + +**Recommendation:** implement and release ckconfig independently first, and +review ckprompt's upstream migration as the next integration task. This keeps +the current scope concrete and uses the established independent module releases. +Existing ckprompt v0.2.0 consumers retain their published dependency set; document +that moving them to the new ckconfig needs the corresponding ckprompt migration. +The tradeoff is an interval with no newly aligned release pair. + +**Viable alternative:** complete the ConfigKit/PromptKit review and both +integration migrations before releasing the next pair, publishing ckconfig first +in dependency order. This gives composed consumers a coordinated adoption path +and validates the shared type boundaries together. It expands this work into +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? + +**Recommendation:** add `empty_import_selections` to the existing text/YAML +source report, projecting ConfigKit's declaration path, location, selector, and +record order. This exposes structured source evidence already available +upstream without a new command or a second explanation engine. It adds report +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.