From 5ccdcb91c931220a197261b685346ac359479c54 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 15:05:42 +0000 Subject: [PATCH] Document ConfigKit adoption --- README.md | 6 +- docs/cli.md | 26 +++++--- docs/consumers/guide.md | 27 ++++++-- docs/development.md | 63 ++++++++----------- docs/release.md | 15 ++--- docs/roadmap/implementation.md | 6 +- integrations/ckconfig/README.md | 12 ++-- integrations/ckconfig/doc.go | 4 +- integrations/ckconfig/docs/releases/v0.3.0.md | 25 ++++++++ .../ckconfig/examples/simple/README.md | 4 +- 10 files changed, 118 insertions(+), 70 deletions(-) create mode 100644 integrations/ckconfig/docs/releases/v0.3.0.md diff --git a/README.md b/README.md index 081fd84..f65186b 100644 --- a/README.md +++ b/README.md @@ -22,8 +22,10 @@ defines the shared visibility policy. | `go.maximumdirect.net/ckconfig` | `ckconfig` | ConfigKit-backed `config` scopes, including configuration source evidence. | | `go.maximumdirect.net/ckprompt` | `ckprompt` | PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, concrete request validation, and native smoke tests. | -Importing an integration does not install commands. The matched ckconfig and -ckprompt v0.2.0 modules use core v0.3.0. See the +Importing an integration does not install commands. The published ckconfig and +ckprompt v0.2.0 modules use core v0.3.0. The local +ckconfig v0.3.0 candidate uses ConfigKit v1.1.0 and does not compose with +ckprompt v0.2.0; the published v0.2.0 pair remains matched. See the [consumer guide](docs/consumers/guide.md#module-selection) for migration details. ## Examples diff --git a/docs/cli.md b/docs/cli.md index 23924e7..45173bf 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -363,14 +363,14 @@ sources: - id: source-1 label: "application config" path: /etc/example/config.yml - layer: base + layer: main kind: file underlay_index: 0 imported_from: null destination: /server placement: mapping - destination_unresolved: false - version_check: + destination_is_fallback: false + version_evidence: path: /version version: present: true @@ -381,22 +381,28 @@ sources: line: 2 column: 1 redacted: false + empty_import_selections: [] ``` Each source includes `id`, `label`, `path`, `layer`, `kind`, `underlay_index`, -and `imported_from`, plus the native destination pointer, placement, unresolved -destination flag, and nullable `version_check`. Placement is `mapping` or -`sequence_item`. The import location is null when absent; otherwise it has +and `imported_from`, plus the native destination pointer, placement, +`destination_is_fallback`, nullable `version_evidence`, and +`empty_import_selections`. Placement is `mapping` or `sequence_item`. The +import location is null when absent; otherwise it has `source_id`, `line`, and `column`. Version evidence preserves `path`, `present`, `null`, `text`, optional source `location`, and `redacted` as returned by ConfigKit. Owning values and source order are preserved, including empty fields, zero coordinates, false and null observations, and synthetic sources without -paths. An absent version check is null. An empty inventory is `sources: []`. +paths. Absent version evidence is null. Each empty-import record has a source-local +`path`, a `location` mapping (`source_id`, `line`, `column`), and a `selector`; +records preserve their returned order. No records are `empty_import_selections: []`. +An empty inventory is `sources: []`. Text output begins with the scope heading and prints the same source fields, quoting labels and paths. These fields project the selected ConfigKit source records; CommandKit does not reload files or rerun version checks. See the -[ConfigKit v0.8.0 inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go) -for native evidence definitions. +[ConfigKit v1.1.0 source records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go) +for native evidence definitions. Ckprompt v0.2.0 uses +[ConfigKit v0.8.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go). ### Explain a configuration path @@ -427,7 +433,7 @@ effective: redacted: false yaml: "localhost:8080\n" origin: - layer: base + layer: main locations: - source_id: source-1 line: 4 diff --git a/docs/consumers/guide.md b/docs/consumers/guide.md index cf18ed5..9743550 100644 --- a/docs/consumers/guide.md +++ b/docs/consumers/guide.md @@ -15,7 +15,9 @@ installed at the application root, not as group children. | `go.maximumdirect.net/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. | | `go.maximumdirect.net/ckprompt` | The application wants PromptKit engine configuration/comparison, five catalogs, named inspection, requirements discovery, request validation, or native smoke testing. | -The matched releases are core v0.3.0, ckconfig v0.2.0, and ckprompt v0.2.0. +The published matched releases are core v0.3.0, ckconfig v0.2.0, and ckprompt v0.2.0. +The local ckconfig v0.3.0 candidate uses ConfigKit v1.1.0 and does not compose +with ckprompt v0.2.0, which retains ckconfig v0.2.0 and ConfigKit v0.8.0. Update application imports and dependency versions together; old and new core paths have distinct Go type identities. Install core with `go get go.maximumdirect.net/commandkit@v0.3.0` and either integration with @@ -30,12 +32,13 @@ core-only, ConfigKit-only, and composed applications. ## Go compatibility -All three modules declare a consumer minimum of Go 1.26.0. The root module also +Core and ckprompt declare a consumer minimum of Go 1.26.0; the ckconfig +v0.3.0 candidate requires Go 1.27.0. The root module also selects ReleaseKit v0.9.0 (`go.maximumdirect.net/releasekit`) as a Go tool, which makes that tool's module graph part of the root consumer module requirements even though production packages do not import ReleaseKit. The [release policy](../policy/release.md#consumer-minimum-and-release-toolchain) -defines the support assumption. Maintainers use Go 1.26.8 for validation and +defines the support assumption. Maintainers use Go 1.27.0 for validation and publication; see the [release procedure](../release.md#release-toolchain). ## Core commands @@ -347,8 +350,24 @@ signal handling, and exit mapping; `Execute` never exits the process. Go declarations and GoDoc own exact exported contracts. ConfigKit owns configuration decoding, validation, and provenance. PromptKit owns prompt formats, profile resolution, and inspection details. See the -[ConfigKit v0.8.0 inspection API](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go), +[ConfigKit v0.8.0 inspection API for ckprompt v0.2.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/137769f3f18a370c68444242fb5d88e620e307e5/inspection.go), [PromptKit engine methods](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/engine.go), [configuration inspection](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/configuration_inspection.go), [smoke diagnostics](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/smoke_diagnostics.go), and [PromptKit v0.16.0 consumer guidance](https://gitea.maximumdirect.net/eric/promptkit/src/commit/9178f3eb91c2b2138caa78e22be93c048b4bc992/docs/consumers/pkg-promptkit.md). + +## ConfigKit v1.1 migration + +The ckconfig v0.3.0 candidate uses `go.maximumdirect.net/configkit v1.1.0` +and Go 1.27.0. Consumers must migrate ConfigKit imports and values passed to +ckconfig: the old and new package paths have distinct type identities. Source +reports rename `destination_unresolved` to `destination_is_fallback` and +`version_check` to `version_evidence`, and add `empty_import_selections`. + +The upstream [v0.9 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md), +[v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md), +[v1.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md), +and [v1.1 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md) +cover source-root `configkit` controls becoming `config`, import requiredness +and defaults, collection registration and operations, removed APIs, and CLI +assignment order. diff --git a/docs/development.md b/docs/development.md index 3590c72..f60a3eb 100644 --- a/docs/development.md +++ b/docs/development.md @@ -99,25 +99,14 @@ Sibling-checkout references in retired planning records are historical review evidence, not build dependencies. Implemented contracts belong in CommandKit under their canonical owners. -The root module does not traverse nested modules. During development, use a -local workspace for all three modules; it is ignored and must not be committed. -If a local `go.work` already exists, preserve it and add these module directories: +The root module does not traverse nested modules. Preserve the ignored `go.work` +and `go.work.sum`; use `GOWORK=off GOTOOLCHAIN=local` for dependency preparation, +module suites, and examples during the ckconfig migration. Local ckprompt uses +the old ConfigKit identity and cannot compose with migrated local ckconfig. Its +independent suite and composed example use published ckconfig v0.2.0; restore +full local workspace guidance after the coordinated ckprompt migration. +Run `go test ./...` separately from each module directory. -```sh -if [ -f go.work ]; then - go work use . ./integrations/ckconfig ./integrations/ckprompt -else - go work init . ./integrations/ckconfig ./integrations/ckprompt -fi -go test ./... -(cd integrations/ckconfig && go test ./...) -(cd integrations/ckprompt && go test ./...) -``` - -The workspace checks package behavior. Workspace-off checks with each module's -own dependency graph are separate evidence. For unpublished CommandKit dependency -versions, the [completed integration validation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/8a82620dfcd34c0ae56bbecb0d014eb49786bc92/docs/roadmap/implementation.md#stage-12-validate-the-complete-end-state-and-finish) -describes the disposable module-file procedure used during implementation. Format changed Go files with `gofmt`. The [maintainer release procedure](release.md) owns candidate preparation and publication commands. @@ -141,25 +130,25 @@ external services. The PromptKit smoke examples use local fixtures and the example's configured client: ```sh -go run ./examples/core workspace greet --count=0 --tag=first --tag second -(cd integrations/ckconfig/examples/simple && go run . config show) -(cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml) -(cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0) -(cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml) -(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring) -(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring) -(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml) -(cd integrations/ckprompt/examples/composed && go run . promptkit list backends --namespace team) -(cd integrations/ckprompt/examples/composed && go run . promptkit list namespaces --kind prompt --kind profile) -(cd integrations/ckprompt/examples/composed && go run . promptkit list collections) -(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml) -(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring) -(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml) -(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt) -(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml) -(cd integrations/ckprompt/examples/composed && go run . promptkit test reachability --campaign spring --prompt briefing --profile spring) -(cd integrations/ckprompt/examples/composed && go run . promptkit test all --campaign spring --prompt briefing --profile spring) -(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring) +GOWORK=off GOTOOLCHAIN=local go run ./examples/core workspace greet --count=0 --tag=first --tag second +(cd integrations/ckconfig/examples/simple && GOWORK=off GOTOOLCHAIN=local go run . config show) +(cd integrations/ckconfig/examples/simple && GOWORK=off GOTOOLCHAIN=local go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config validate --scope all --campaign spring --limit=0) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list prompts --config fixtures/before.yml --campaign spring) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list backends --namespace team) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list namespaces --kind prompt --kind profile) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit list collections) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit show prompt briefing --campaign spring --format yaml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit test reachability --campaign spring --prompt briefing --profile spring) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . promptkit test all --campaign spring --prompt briefing --profile spring) +(cd integrations/ckprompt/examples/composed && GOWORK=off GOTOOLCHAIN=local go run . session restore session-42 --campaign spring) ``` The [consumer guide](consumers/guide.md) explains how their public API usage diff --git a/docs/release.md b/docs/release.md index 980b1f2..17611a2 100644 --- a/docs/release.md +++ b/docs/release.md @@ -35,20 +35,21 @@ module metadata. ## Release toolchain -The selected release toolchain is **Go 1.26.8**. Each module declares a consumer -minimum of **Go 1.26.0**. Maintainers use Go 1.26.8 for dependency preparation, -candidate validation, and ReleaseKit execution. The +The selected release toolchain is **Go 1.27.0**. Core and ckprompt declare a +consumer minimum of **Go 1.26.0**; ckconfig requires **Go 1.27.0**. Maintainers +use Go 1.27.0 for dependency preparation, candidate validation, and ReleaseKit +execution. The [consumer guide](consumers/guide.md#go-compatibility) and [release policy](policy/release.md#consumer-minimum-and-release-toolchain) describe these selections. -Select Go 1.26.8 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed, +Select Go 1.27.0 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed, install it with the standard Go tools: ```sh -GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.26.8@latest -go1.26.8 download -export PATH="$(go1.26.8 env GOROOT)/bin:$PATH" +GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.27.0@latest +go1.27.0 download +export PATH="$(go1.27.0 env GOROOT)/bin:$PATH" hash -r GOWORK=off GOTOOLCHAIN=local go version ``` diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c9bedf1..82ec3db 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # ConfigKit v1.1.0 adoption implementation plan -Status: Stages 1–3 complete; Stages 4–6 are not started. +Status: Stages 1–4 complete; Stages 5–6 are not started. This plan is for a Luna coding agent implementing the selected [ConfigKit adoption target](configkit-v1.1.0.md). Follow Stage 1 through Stage 6 @@ -187,6 +187,10 @@ classifies sensitive data correctly. ## Stage 4: Update current guidance and prepare the release note +**Completed.** Current guidance describes the new source report, consumer and +toolchain migration, and temporary ckprompt mismatch. The v0.3.0 candidate +note is prepared; published notes remain unchanged. + 1. Update ckconfig README, GoDoc, and `examples/simple/README.md` for the new dependency identity and Go minimum, and the planned ckconfig v0.3.0 with core v0.3.0. Keep package/provider usage consistent with actual code. diff --git a/integrations/ckconfig/README.md b/integrations/ckconfig/README.md index 6a3367b..70b1af2 100644 --- a/integrations/ckconfig/README.md +++ b/integrations/ckconfig/README.md @@ -7,9 +7,9 @@ itself. ## Module -The module path is `go.maximumdirect.net/ckconfig`. Version v0.2.0 uses -`go.maximumdirect.net/commandkit v0.3.0` and -ConfigKit; it does not import PromptKit. See the +The module path is `go.maximumdirect.net/ckconfig`. The prepared v0.3.0 +candidate requires Go 1.27.0 and uses `go.maximumdirect.net/commandkit v0.3.0` and +`go.maximumdirect.net/configkit v1.1.0`; it does not import PromptKit. See the [consumer guide](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/consumers/guide.md#configkit-scopes) for exact callback and lifetime contracts. @@ -26,9 +26,9 @@ scopes, selectors, input checks, and state shared by the selected acquisitions or comparison in a config invocation. `ckconfig.FromConfigKit` adapts a typed ConfigKit loader. The `config` command family exposes scope discovery and the validate, show, sources, explain, and diff operations supported by the declared -scopes. Source reports include native destination, placement, unresolved -destination, and source version-check evidence. Comparison returns ConfigKit's -native records to the YAML report path; the +scopes. Source reports include native destination, placement, destination +fallback, version evidence, and empty-import selections. Comparison returns +ConfigKit's native records to the YAML report path; the [CLI reference](https://gitea.maximumdirect.net/eric/CommandKit/src/branch/main/docs/cli.md#compare-configuration-selections) owns its operator details. diff --git a/integrations/ckconfig/doc.go b/integrations/ckconfig/doc.go index 8dd67cd..3e28f2b 100644 --- a/integrations/ckconfig/doc.go +++ b/integrations/ckconfig/doc.go @@ -1,10 +1,10 @@ // Package ckconfig, provided by go.maximumdirect.net/ckconfig, provides -// CommandKit's optional ConfigKit integration. Its +// CommandKit's optional ConfigKit v1.1.0 integration, requiring Go 1.27.0. Its // canonical Command declaration installs the standard config command family // through the core commandkit package. Applications can install CommandKit // RoutingRule declarations alongside it through commandkit.New or // App.Register. Source reports preserve ConfigKit's destination, placement, -// and version-check evidence. Invocation reporting applies CommandKit's shared +// version, and empty-import evidence. Invocation reporting applies CommandKit's shared // visibility and delivery policy; provider warnings remain independent of // failure explanations. Importing ckconfig alone installs no commands. package ckconfig diff --git a/integrations/ckconfig/docs/releases/v0.3.0.md b/integrations/ckconfig/docs/releases/v0.3.0.md new file mode 100644 index 0000000..ab366a2 --- /dev/null +++ b/integrations/ckconfig/docs/releases/v0.3.0.md @@ -0,0 +1,25 @@ +# CommandKit ckconfig v0.3.0 + +## Summary + +This candidate adopts `go.maximumdirect.net/configkit v1.1.0` and requires Go +1.27.0, while retaining `go.maximumdirect.net/commandkit v0.3.0`. It updates +configuration source reports to expose ConfigKit's current evidence. + +## Migration + +Change ConfigKit imports from `gitea.maximumdirect.net/eric/ConfigKit` to +`go.maximumdirect.net/configkit`. Values from the two paths have distinct Go +type identities. Update application loaders and provider values together with +ckconfig. Published ckprompt v0.2.0 continues to use ckconfig v0.2.0 and the old +ConfigKit identity; it does not compose with this candidate. + +Source reports rename `destination_unresolved` to `destination_is_fallback` and +`version_check` to `version_evidence`, use the native `main` layer name, and add +`empty_import_selections` records (or `[]` when empty). Update report consumers. +See the [consumer migration guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/docs/consumers/guide.md#configkit-v11-migration) +for links to upstream configuration and API changes. + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/COPYRIGHT) | +[LICENSE](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/LICENSE) | +[ATTRIBUTION](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations/ckconfig/v0.3.0/integrations/ckconfig/docs/oss/attribution.md) diff --git a/integrations/ckconfig/examples/simple/README.md b/integrations/ckconfig/examples/simple/README.md index c846d4d..7464210 100644 --- a/integrations/ckconfig/examples/simple/README.md +++ b/integrations/ckconfig/examples/simple/README.md @@ -1,7 +1,9 @@ # Simple consumer This example imports `go.maximumdirect.net/ckconfig` and -`go.maximumdirect.net/commandkit`; use ckconfig v0.2.0 with core v0.3.0. +`go.maximumdirect.net/commandkit`; use the ckconfig v0.3.0 candidate with core +v0.3.0, ConfigKit v1.1.0, and Go 1.27.0. Set `GOWORK=off GOTOOLCHAIN=local` +for the commands below. Run the maintained example with: