releasekit/docs/roadmap/implementation.md

Implementation plan: host-native ReleaseKit launchers

Follow the stages in order as one sprint. The feature roadmap defines the intended behavior and scope. The focused checks below describe regression coverage; intermediate stages need no separate review, release, or passing build. Run the assembled checks in Stage 6.

Stage 1: Normalize the local multi-module launcher

1. In the multi-module launcher, after entering the selected module and exporting its existing GOWORK=off and GOTOOLCHAIN=local settings, insert the following before the first Go bootstrap command. Reuse this shell recipe in the subsequent stages:

   releasekit_host_os=$(go env GOHOSTOS) || exit $?
   releasekit_host_arch=$(go env GOHOSTARCH) || exit $?
   export GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch"
   

   Keep the checked assignments separate from export so a failed Go query stops the launcher. Keep host selection inside the existing launcher scope; preserve selected module metadata, dependency preparation, publication arguments, traps, and the child status. Application targets still come from release profiles.

2. Extend the existing launcher tests. In TestMultiModuleLauncherUsesSelectedModuleAndProfile, let the Go shim answer the two host queries and assert the exported target at go list -deps in the selected module. In TestMultiModuleLauncherRunsToolFromSelectedDependency, supply a foreign target to the launcher and retain real Go tool preparation and execution. Keep the checks for the nested module's version, forwarded profile and arguments, statuses 0 through 3, unchanged source, and bootstrap cleanup. For these fixtures, choose windows unless the host OS is windows (then linux), and arm64 unless the host architecture is arm64 (then amd64). This makes both variables differ from the host pair. Keep synthetic versions in a test-owned GOMODCACHE.

Stage 2: Normalize consumer Woodpecker templates

1. Apply the Stage 1 recipe in the single-module and multi-module tag delivery commands, under the existing Go settings and in the selected module. Insert it after tag verification and checkout, before the first Go bootstrap command. Write the new shell variable references as $${releasekit_host_os} and $${releasekit_host_arch} so Woodpecker passes them through. Keep the verified commit, selected tool, profile mapping, credentials, alternate module and sum files, cleanup, and ci-deliver --prepared invocation.

2. Update the existing single-module and multi-module workflow harnesses. Teach the controlled Go shim to answer host queries before enforcing its alternate module file checks. In both Go shims, log the target at go list -deps. Feed a foreign target to TestWoodpeckerTagDeliveryTemplate, TestWoodpeckerTagDeliveryUsesTaggedModuleVersion, and TestMultiModuleWoodpeckerDelivery and check that dependency inspection uses the host pair. Retain real execution where the fixture already uses it, and keep the existing checks that a rejected tag or commit reaches no Go command.

Stage 3: Normalize source-built launchers

1. Apply the same recipe in the maintainer launcher before building and executing ReleaseKit. Prefix the two queries with GOTOOLCHAIN=local to match its existing build. Preserve usage checking, output location, build settings, and the final exec.
2. Apply the recipe in the source delivery template after tag verification and checkout, under its existing Go settings and before the source build. Use the Woodpecker escaping from Stage 2. Keep its temporary build output, dependency preparation through the existing build, and prepared delivery arguments. Exercise TestWoodpeckerSourceDeliveryTemplateSelfBootstraps with a foreign target; log and assert the host pair at the real go build, retain actual execution, and keep the checkout, cleanup, and dependency preparation assertions.
3. Update the manual delivery retry in the maintainer runbook. After fetching and checking out the tagged version, run host selection, dependency download, build, and delivery inside a subshell so the caller's target environment stays intact. Query with GOTOOLCHAIN=local as above; make the sequence stop on failure inside the subshell. Preserve the dependency download before the offline build, the build-only proxy and sum settings, the output path, and the older-tag credential example.

Stage 4: Normalize module-based recovery preparation

1. In the Go recovery implementation, keep the existing registered-tool, API-only, and no-dependency selections. Have RecoveryTool return (*RecoveryInvocation, error) within the internal package. Give the descriptor Directory string and Args []string fields. A nil result still selects the native executable fallback. Set the directory to the original module for a registered tool or the durable bootstrap root for an API-only consumer. Put tool -modfile= and the existing full command package path in Args; the caller supplies the working directory. Preserve the selected version, local and versioned replacements, private module and sum files, and their existing lifetime.
2. Immediately before the API-only branch runs go list -deps, query go env -json GOHOSTOS GOHOSTARCH in its private root with its existing GOWORK=off and GOTOOLCHAIN=local overrides. Reuse the internal discover runner with the existing context. Decode both fields, treat missing values as a preparation error, and add only GOOS and GOARCH to the environment of the dependency command. Keep the target-independent module-selection query and the registered-tool early return. Use the existing preparation error and cleanup paths; leave candidate Go settings, proxy policy, and fallback selection as they are.
3. Update the direct RecoveryTool callers in the handoff tests to run the descriptor's arguments in its directory. In TestRecoveryToolPreservesVersionedReplacement, set a foreign target for the preparation call, log the target of the real go list -deps through a delegating shim, and verify the host pair there. Run the test's subsequent direct tool invocation with the host pair and retain its version and metadata assertions. Retain the source-module and vendored API-only cases. Update the CLI caller in Stage 5.

Stage 5: Normalize the printed recovery command when it runs

1. In selectedPublicationRecoveryCommand in the CLI, render the descriptor as one copyable POSIX shell command. Use this structure, with <dir>, <package>, and <record> standing for shell-quoted operands:

   (export GOWORK=off GOTOOLCHAIN=local && releasekit_host_os=$(go -C <dir> env GOHOSTOS) && releasekit_host_arch=$(go -C <dir> env GOHOSTARCH) && GOOS="$releasekit_host_os" GOARCH="$releasekit_host_arch" go -C <dir> tool '-modfile=' <package> reconcile --record <record>)
   

   Build the common go -C prefix from the descriptor directory and render its tool arguments using the existing diagnostic redaction and shell quoting. Keep the explicit absolute record operand. Both host queries run in the invocation directory with the same Go settings as the final command. A failed query stops the command, and the subshell returns the final command status when launched. Leave the native executable command, handoff timeout and cancellation behavior, and existing fallback and diagnostic behavior intact.

2. In TestColdGoToolRecoverySurvivesLauncherExit, execute the printed command in a separate shell with a foreign target, after the original launcher and its temporary files are gone. Exercise both registered and API-only handoffs and retain status checks for 0 through 3. For the alternate-record cases, replace the quoted original record operand inside the command instead of appending flags after the closing subshell. Retain the vendored API-only, native fallback, record-selection, and redaction checks. Exercise the printed command itself; running the Go descriptor directly would miss a regression in the shell recipe.

Stage 6: Align consumer guidance and verify the sprint

1. In the adoption guide, make the minimal launcher use the Stage 1 recipe followed by exec go tool releasekit "$@". Run it from the selected module, retaining that consumer's workspace and toolchain settings. Move the registration smoke check to follow the launcher example and invoke version through that launcher. In the multi-module README, apply the same recipe to the direct check smoke commands: enter each selected module in its own subshell, select the host there, then run the existing check with its repository-root profile and version. Preserve the source-selected fixture instructions and avoid turning the smoke check into publication.
2. Align the consumer delivery guide, CLI contract, and internal Go tool guide with the maintained recipes and handoff behavior. Explain that consumers update copied launchers and templates separately from upgrading the module dependency. ReleaseKit tests generic bootstrap behavior; consumers can focus their own wiring tests on selectors and profile mapping. Profile build targets continue to select application binaries.
3. Run the focused launcher, workflow, and recovery fixtures from the preceding stages with the existing local Git and module proxy fixtures. Run go test ./... and go run ./internal/apicheck as documented in the development guide. Check shell syntax, including Woodpecker command blocks after interpolation, local documentation links, and git diff --check. Use the existing offline fixtures; no hosted delivery, live publication, or external runner is needed.
4. Include the following entry in the next release note during release preparation, when its version is selected: “Maintained launchers and generated Go recovery commands now use the host target to prepare and run ReleaseKit. Update copied launchers and CI templates to get the fix; release profiles still select application build targets.”