From c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 4 Nov 2026 03:37:44 +0000 Subject: [PATCH] Plan CommandKit vanity path migration --- .../integration-dependency-alignment.md | 178 +++++++++++++----- 1 file changed, 134 insertions(+), 44 deletions(-) diff --git a/docs/roadmap/integration-dependency-alignment.md b/docs/roadmap/integration-dependency-alignment.md index 0ff8ade..e8c2375 100644 --- a/docs/roadmap/integration-dependency-alignment.md +++ b/docs/roadmap/integration-dependency-alignment.md @@ -1,4 +1,4 @@ -# Integration dependency alignment +# Integration dependency alignment and vanity-path migration Status: proposed release-preparation roadmap. This pass adds documentation only; dependency changes and publication remain future work. @@ -6,9 +6,10 @@ dependency changes and publication remain future work. ## Purpose and authority Align the independently released integrations with the core APIs their current -source already uses. Publish compatible module versions in dependency order so -each integration builds and validates against its declared, downloaded -dependencies with workspace discovery off. +source already uses, and migrate all three CommandKit modules to the supplied +vanity paths. Publish compatible module versions in dependency order so each +integration builds and validates against its declared, downloaded dependencies +with workspace discovery off. The [release procedure](../release.md) owns publication commands and release order. The [release policy](../policy/release.md), @@ -20,6 +21,8 @@ and release-preparation scope; it does not change those policies. ## Baseline and investigation evidence Reviewed baseline: `289a171e97699ad9aa57ee2cc40bdad1c0b680a9`. +Vanity-path review baseline: `d7cbaed3ed18bc2909c8144f308e2dfd58ade7ec`. +Module declarations and library source were unchanged between these revisions. - Both integration module declarations require core v0.2.0. The [ckprompt declaration](../../integrations/ckprompt/go.mod) also requires @@ -55,6 +58,28 @@ The successful cases retained ConfigKit v0.8.0 and PromptKit v0.16.0. These results isolate the CommandKit dependency alignment needed here; they do not prove that future published versions or their downloaded sums already exist. +### Verified vanity discovery + +The core endpoint at `https://go.maximumdirect.net/commandkit?go-get=1` serves +the mapping to `https://forge.maximumdirect.net/base-layer/commandkit`. Go direct +discovery finds the existing core v0.1.0 and v0.2.0 tags. Fetching v0.2.0 through +the vanity path reaches its source but reports a module-path mismatch because +that release declares `gitea.maximumdirect.net/eric/CommandKit`. + +Both integration endpoints now return HTTP 200 with these `go-import` contents: + +| Vanity path | VCS | Repository URL | Subdirectory field | +| --- | --- | --- | --- | +| `go.maximumdirect.net/ckconfig` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckconfig` | +| `go.maximumdirect.net/ckprompt` | `git` | `https://forge.maximumdirect.net/base-layer/commandkit` | `integrations/ckprompt` | + +Go 1.26.8 direct discovery finds each integration's v0.1.0 tag. Disposable +consumer fetches reach the correct nested `go.mod` and report its old declared +module path, confirming subdirectory routing. Discovery is working; the +existing tags have not migrated. The optional fourth metadata field is +supported from Go 1.25, within the existing Go 1.26.0 consumer minimum; see the +[Go discovery reference](https://go.dev/ref/mod#vcs-find). + ## Targeted end state ### Compatible independently released modules @@ -62,28 +87,56 @@ prove that future published versions or their downloaded sums already exist. Use the following proposed next versions, subject to the existing fresh-version publication guards: -| Module | Next release | Required CommandKit dependencies | Full tag | -| --- | --- | --- | --- | -| Core | v0.3.0 | None | `v0.3.0` | -| ckconfig | v0.2.0 | Core v0.3.0 | `integrations/ckconfig/v0.2.0` | -| ckprompt | v0.2.0 | Core v0.3.0 and ckconfig v0.2.0 | `integrations/ckprompt/v0.2.0` | +| Module path | Physical module directory | Next release | Required CommandKit dependencies | Full tag | +| --- | --- | --- | --- | --- | +| `go.maximumdirect.net/commandkit` | `.` | v0.3.0 | None | `v0.3.0` | +| `go.maximumdirect.net/ckconfig` | `integrations/ckconfig` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` | `integrations/ckconfig/v0.2.0` | +| `go.maximumdirect.net/ckprompt` | `integrations/ckprompt` | v0.2.0 | `go.maximumdirect.net/commandkit v0.3.0` and `go.maximumdirect.net/ckconfig v0.2.0` | `integrations/ckprompt/v0.2.0` | Minor integration releases fit the existing pre-1.0 compatibility policy: the reporting migration changes consumer-facing behavior and adopts a core version -with incompatible API changes. Migration notes explain the impact on provider -results, invocation reporting, and consuming applications. +with incompatible API changes. The vanity migration also deliberately changes +Go module and import identities. Migration notes explain the new imports and +dependency set, provider results, invocation reporting, and application changes. The three modules retain independent versions and source tags. Their candidates may identify successive commits: core publication need not wait for integration metadata that depends on that newly published core. Each selected module's final release suite runs against its actual declared dependencies. +### Module and import identity + +Change each module declaration and all CommandKit-owned imports to the matching +new path. Core self-imports, including its `internal` packages, use +`go.maximumdirect.net/commandkit/...`; integration self-imports use +`go.maximumdirect.net/ckconfig/...` or `go.maximumdirect.net/ckprompt/...`. +Cross-module imports and requirements use the complete new paths in the table, +including ckprompt's ckconfig dependency. + +Update production files, tests, maintained examples, and any import-path-based +test expectations together. A declared vanity module that still imports the +old core path would select a different Go package identity and can violate +`internal` import rules. The matched new releases compose through one core +identity rather than mixing old-path and new-path CommandKit types. + +Keep physical directories, repository URLs, and Git tag prefixes as shown. The +Go subdirectory metadata makes the short integration vanity paths resolve to +the existing layout. The existing release profiles select physical directories; +the migration does not rename those directories or flatten integration tags. + +Published old-path versions remain immutable. This scope selects the new paths +for new releases and updates consumer guidance; it makes no new promise of +type interoperability between the two identities and adds no old-path forwarding +module or compatibility layer. + ### Retained architecture and scope -Keep the current library APIs and integration adapters, Go 1.26.0 consumer -minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit v0.9.0. -The successful diagnostic suites indicate dependency selection is sufficient; -this work selects no API rollback or compatibility shim for old reporting APIs. +Preserve exported declaration shapes and runtime behavior while deliberately +changing module/import identities. Retain the integration adapters, Go 1.26.0 +consumer minimum, Go 1.26.8 maintainer toolchain, and root-selected ReleaseKit +v0.9.0. The earlier successful diagnostic suites establish the dependency fix +before renaming; the migrated source still needs its own validation. This work +selects no API rollback or shim for old reporting APIs. Retain ConfigKit v0.8.0, PromptKit v0.16.0, and other dependency selections unless ordinary tidy changes the resolved graph as a consequence of the @@ -99,54 +152,89 @@ release validation uses normal downloaded dependencies without that redirection. ## Work needed +### Prepare the module-path migration + +Migrate the three module declarations and their owned source/test/example +imports using the mapping above. Update CommandKit dependency keys to the +vanity paths as each published predecessor becomes available. Preserve package +names and aliases unless an actual import-resolution change requires an edit. + +Update current installation examples, module-selection guidance, package links, +and dependency descriptions in the README, consumer/developer guidance, and +affected GoDoc. Adjust import-path-aware tests to the new identities while +preserving their existing boundary assertions. Retain repository/source and +license URLs as source-hosting links; they are distinct from Go import paths. +Keep historical release records and review evidence accurate instead of doing a +repository-wide textual replacement of the old names. + +Ignored development workspaces or disposable module files can support validation +before predecessor releases are downloadable. Keep that evidence separate from +the independent release graph. The migration may be prepared across all three +modules locally, while source publication and final dependency preparation +still follow core, ckconfig, then ckprompt order. + ### Prepare and release core Review the v0.3.0 draft against changes since the published v0.2.0 tag, including completion, invocation reporting, aliases, and release-tool maintenance. Bring -its summary, migration guidance, and immutable source/licensing links into line -with the final candidate and current release procedure. Keep published notes -and tags unchanged. +its summary, vanity import migration, compatibility guidance, and immutable +source/licensing links into line with the final candidate and current release +procedure. Keep published notes and tags unchanged. -Prepare and commit the intended core candidate on `main`, then use the existing -source-publication workflow to publish v0.3.0. Preserve the procedure's required -candidate-commit publication before tag publication. The root suite covers the -root module; the still-pending integration alignment is separate work. +Prepare and commit the core candidate declaring `go.maximumdirect.net/commandkit` +on `main`, then use the existing source-publication workflow to publish v0.3.0. +Preserve the procedure's required candidate-commit publication before tag +publication. The root suite covers the root module; still-pending integration +alignment is separate work. ### Align and release ckconfig -After core v0.3.0 is published, update ckconfig's core requirement to that version -and prepare dependencies with workspace discovery off. Tidy its module metadata -and retain authentic sums from actual downloads. No future checksum or local -replacement substitutes for the published dependency. +After core v0.3.0 is published under its new path, prepare ckconfig declaring +`go.maximumdirect.net/ckconfig` and requiring +`go.maximumdirect.net/commandkit v0.3.0`. Remove the superseded old core +requirement, prepare dependencies with workspace discovery off, and tidy the +module metadata. Retain authentic sums from actual downloads. No future +checksum or local replacement substitutes for the published dependency. Prepare `integrations/ckconfig/docs/releases/v0.2.0.md`, documenting the new core -requirement and reporting/completion behavior relevant to consumers. Update +requirement, vanity import migration, and reporting/completion behavior. Update affected current guidance and module-local attribution from the actual resolved graph, including immutable notice links. Validate and publish the selected ckconfig candidate through the ordinary module release workflow. ### Align and release ckprompt -After ckconfig v0.2.0 is published, update ckprompt's direct requirements to core -v0.3.0 and ckconfig v0.2.0 together. Prepare downloaded dependencies and tidy -with workspace discovery off. Retain real sums and inspect indirect changes. +After ckconfig v0.2.0 is published under its new path, prepare ckprompt declaring +`go.maximumdirect.net/ckprompt` and requiring +`go.maximumdirect.net/commandkit v0.3.0` and +`go.maximumdirect.net/ckconfig v0.2.0` together. Remove the superseded old +CommandKit dependency keys. Prepare downloaded dependencies and tidy with +workspace discovery off. Retain real sums and inspect indirect changes. Prepare `integrations/ckprompt/docs/releases/v0.2.0.md`, covering the compatible -dependency set and consumer migration. Align current guidance and module-local -attribution with that selection. Validate and publish its candidate through the -ordinary module release workflow. +dependency set, vanity imports, and consumer migration. Align current guidance +and module-local attribution with that selection. Validate and publish its +candidate through the ordinary module release workflow. ### Record the aligned result -Record the selected versions, candidate revisions, validation outcomes, and -source-publication outcomes separately for all three modules. Update current -dependency-readiness statements that still describe this mismatch as unresolved; -preserve historical baseline failures in completed review and implementation -records. Link future implementation tracking here without restarting the -completed ReleaseKit adoption or remediation work. +Record the selected module paths and versions, candidate revisions, validation +outcomes, and source-publication outcomes separately for all three modules. +Update current dependency-readiness statements that still describe this mismatch +as unresolved; preserve historical baseline failures in completed review and +implementation records. Link future implementation tracking here without +restarting the completed ReleaseKit adoption or remediation work. ## Validation and completion boundaries +Review current CommandKit-owned source and dependency selections for stale +self-imports or old direct dependency keys. Historical notes, source URLs, and +unrelated upstream module identities are outside that mechanical rename. +Confirm release identity still pairs each new module path with its existing +physical directory and tag prefix. The verified redirects are preparation +evidence; publishing the renamed modules is needed for real consumers to use +them through those paths. + Use the selected module's ordinary deterministic offline suite with `GOWORK=off` and read-only metadata after dependency preparation. Its maintained consumer compiles and runs with that suite. ReleaseKit's publication command @@ -161,8 +249,10 @@ or ambiguous publication using the existing policy and upstream recovery flow. Hosted Gitea delivery keeps its separate outcome; this roadmap adds no CI polling, live provider calls, or additional publication gate. -Alignment is complete when the matched source versions are published, each -integration declares the compatible versions with authentic downloaded sums, -each final selected-module suite passes without workspace or replacement -redirection, and its current documentation and attribution agree with that -graph. Temporary local-source success alone does not establish that end state. +Alignment is complete when the matched source versions are published under all +three vanity module paths, owned imports and examples use the new identities, +each integration declares the compatible vanity-path versions with authentic +downloaded sums, each final selected-module suite passes without workspace or +replacement redirection, and current documentation and attribution agree with +that graph. Temporary local-source success alone does not establish that end +state.