12 KiB
Integration dependency alignment and vanity-path migration
Status: the vanity migration and matched source releases are complete. The implementation plan records candidate commits, validation, and publication outcomes; this roadmap retains the target and review history.
Purpose and authority
Align the independently released integrations with the core APIs their current 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 owns publication commands and release order. The release policy, agent policy, testing policy, documentation policy, and OSS policy govern the work. This roadmap selects the target 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 also requires ckconfig v0.1.0; the ckconfig declaration has no dependency on ckprompt.
- Current integration source uses newer core APIs including
CompletionHint,Explanation, andReporter. Both independent Go 1.26.8 suites fail to compile withGOWORK=offand their existing read-only module graphs. - Updating core alone is insufficient for ckprompt: published ckconfig v0.1.0
still uses removed core APIs, including
Invocation.Streams,Outcome.Diagnostics, andSeverityError, plus the oldFailure(error)call shape. - The authoritative
origintag listing contains core v0.1.0 and v0.2.0, and the two integration v0.1.0 tags. The proposed next versions below were unused at review. Remotemainwas230187296fae5253cb1773f16c2f1d1a39499ed0; the reviewed local changes still need normal publication to the authoritative branch as part of candidate preparation. - A checked-in core v0.3.0 draft already describes the reporting and alias migration. It is an unpublished draft, not proof that the module version can be downloaded.
The investigation used disposable alternate module files, Go 1.26.8,
GOWORK=off, and read-only offline tests. Only temporary dependency selections
changed; the real module declarations, sums, and source remained unchanged.
| Current source under test | Temporary dependency selection | Result |
|---|---|---|
| ckconfig | Current core source | Module suite and maintained example passed. |
| ckprompt | Current core source, published ckconfig v0.1.0 | Compilation failed in the old ckconfig implementation. |
| ckprompt | Current core and current ckconfig source | Module suite and maintained example passed. |
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.
Targeted end state
Compatible independently released modules
Use the following proposed next versions, subject to the existing fresh-version publication guards:
| 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. 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. Core component-version discovery uses
go.maximumdirect.net/commandkit as its build-info identity, retaining the
existing version --scope commandkit behavior with the new module path.
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
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 CommandKit updates. Inspect and explain the resulting graph rather than bundling unrelated upgrades. In particular, transitive tools with different module paths may coexist; attribution must reflect the actual selection.
Preserve the existing launchers, three release profiles, generic validators, credential handling, and separate source-publication and hosted-delivery outcomes. Development workspaces remain useful and ignored. Diagnostic local replacements and the earlier temporary Go shim remain development evidence; release validation uses normal downloaded dependencies without that redirection.
Release-preparation deliverables
The core v0.3.0 draft describes the complete candidate, including completion,
reporting, aliases, tool maintenance, and the vanity-path migration. New
integration notes at integrations/ckconfig/docs/releases/v0.2.0.md and
integrations/ckprompt/docs/releases/v0.2.0.md explain the matched dependency set
and consumer migration. Their source and licensing links follow the current
release procedure; published notes and tags remain immutable.
Current installation examples, README module selections, consumer/developer guidance, affected GoDoc, and maintained examples use the implemented new identities. Import-path-aware tests retain their existing boundary assertions. Source-hosting and license URLs remain repository links, distinct from Go import paths. Module-local attribution describes each actual resolved graph.
The final record identifies module paths, versions, candidate revisions, validation evidence, and independent source-publication outcomes. Current readiness guidance reflects the aligned state; historical failures remain in completed investigation records. The implementation plan owns the ordered migration, dependency preparation, release, and evidence-recording steps.
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
owns the final candidate suite and selected file checks; validation-only checks
remain optional diagnostics. Reuse successful evidence for unchanged candidates
instead of adding a required check-then-publish repetition.
Retrieving a newly published dependency is preparation for the next module's release. It does not turn proxy availability or consumer installation into a completion gate for the preceding source release. Continue to resolve failed 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 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.