diff --git a/docs/roadmap/host-native-launchers.md b/docs/roadmap/host-native-launchers.md index 0294b50..6b3c655 100644 --- a/docs/roadmap/host-native-launchers.md +++ b/docs/roadmap/host-native-launchers.md @@ -4,10 +4,11 @@ Status: planned; implementation pending. ## Purpose -Make ReleaseKit's maintained consumer launchers prepare and execute the release -tool for the maintainer's host when inherited `GOOS` and `GOARCH` select a -different application target. Centralize the recipe and regression coverage so -consumers can retain small launchers and product-specific wiring tests. +Make ReleaseKit's maintained launchers and generated recovery commands prepare +and execute the release tool for the maintainer's host when inherited `GOOS` +and `GOARCH` select a different application target. Centralize the recipe and +regression coverage so consumers can retain small launchers and product-specific +wiring tests. This is a launcher correctness improvement. It requires no public bootstrap API, validation option, or test-helper package. This roadmap selects no release version @@ -32,6 +33,13 @@ launcher. The [single-module CI template](../../examples/woodpecker/tag-delivery and [multi-module CI template](../../examples/multi-module/woodpecker.yml) also invoke the selected tool without explicit host-target normalization. +The [maintainer launcher](../../scripts/release), +[source delivery template](../../examples/woodpecker/releasekit-source-delivery.yml), +and [manual delivery retry](../release.md) build and execute the tool with the +same inherited-target assumption. The CLI's [generated recovery command](../../cmd/releasekit/main.go) +inherits the target from the shell where it is run, and [recovery dependency +preparation](../../internal/gotool/recovery.go) also inherits the target. + Existing [launcher tests](../../cmd/releasekit/multi_module_example_test.go) exercise synthetic module selection, publication arguments, child statuses 0 through 3, and preservation of source module metadata. Those fixtures provide @@ -39,11 +47,12 @@ the starting point for foreign-target regression coverage. ## Targeted end state -Maintained consumer launchers obtain `GOHOSTOS` and `GOHOSTARCH` from the selected -Go toolchain and use them as `GOOS` and `GOARCH` while preparing and running +Maintained launchers and module-based recovery use `GOHOSTOS` and `GOHOSTARCH` +from the selected Go toolchain as `GOOS` and `GOARCH` while preparing and running ReleaseKit. The tool executes on that host even when the caller was working with a foreign application target. Normalize before target-dependent dependency -inspection as well as tool execution. +inspection as well as tool execution. Generated recovery commands select the +host when run, using the Go toolchain that will execute the command. Application targets continue to come from existing release profiles. The launcher's host selection preserves module-selected tool versions, profile and @@ -78,18 +87,24 @@ for host-query failures. Avoid hard-coded host values or a new bootstrap layer. **Rationale:** The same inherited-target failure can affect local and CI tool execution. Maintained recipes should give consumers consistent behavior. -**Target:** The minimal adoption launcher and consumer CI templates select the -host target when preparing and invoking ReleaseKit. +**Target:** The adoption example, consumer and maintainer launchers, CI +templates, and generated recovery commands select the host target when +preparing and invoking ReleaseKit. **Work:** Apply the same small normalization recipe to the adoption example and the single-module and multi-module CI templates. Preserve tag verification before bootstrap, tagged module selection, profile routing, credentials, and temporary -metadata handling. Review other maintained executable bootstrap examples for the -same target assumption and align affected paths. Update the multi-module README +metadata handling. Apply host selection to the maintainer launcher, source +delivery template, and manual delivery retry. Update the multi-module README and consumer guidance to explain host selection and profile-owned application targets. Document that consumers adopt the corrected launcher or template; a module dependency upgrade alone does not rewrite their copied scripts. +Apply host selection to module-based recovery dependency preparation and to the +Go invocation printed by `publish`. Preserve registered-tool selection, private +bootstrap metadata for API-only consumers, the native executable fallback, +explicit record selection, and recovery exit statuses. + ### 3. Extend existing behavioral coverage **Rationale:** Successful execution under a foreign target directly protects @@ -106,10 +121,14 @@ that statuses 0, 1, 2, and 3 propagate. Check unchanged source module files and existing temporary bootstrap cleanup. Reuse unaffected tests rather than adding a parallel launcher or publication-engine suite. -Cover affected CI/bootstrap recipes through their existing test harnesses where -practical, including normalization before dependency inspection. Preserve -profile-selected application targets. Use synthetic local tools and test-owned -module caches under the [fixture-isolation guidance](../development.md#testing-synthetic-modules). +Verify host selection at the dependency inspection step itself, using a +host-specific fixture or an environment assertion at `go list -deps`. Cover +affected CI/bootstrap recipes through their existing test harnesses where +practical. Extend the existing handoff tests to exercise recovery preparation +under a foreign target, then run the printed command under a foreign target in +a separate invocation. Preserve profile-selected application targets. Use +synthetic local tools and test-owned module caches under the +[fixture-isolation guidance](../development.md#testing-synthetic-modules). The regression needs no actual publication, hosted service, or external platform runner. Choose a representative supported foreign target instead of introducing a platform matrix. @@ -132,11 +151,12 @@ that protect their own behavior. ## Completion evidence -Completion requires host execution under a foreign target, preserved selected -tool identity and arguments, child-status forwarding, unchanged source metadata, -and existing cleanup behavior. The maintained local and CI recipes and adoption -guidance must use the same host-selection approach. Application build targets -must retain their existing profile-driven behavior. +Completion requires host selection before dependency inspection and successful +host execution under a foreign target, including for generated recovery commands. +Preserve selected tool identity and arguments, child-status forwarding, unchanged +source metadata, and existing cleanup behavior. The maintained local and CI +recipes and adoption guidance must use the same host-selection approach. +Application build targets must retain their existing profile-driven behavior. There are no significant open design decisions for this scope. Exact shell variable names and fixture arrangement can be selected during implementation.