diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..a52a48d --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,80 @@ +# Host-native launcher review findings + +Reviewed the implementation from `bf07bed` through `0269648` against the +[feature roadmap](host-native-launchers.md) and +[implementation plan](implementation.md). + +The maintained launchers select the Go host before preparing and running the +tool. API-only recovery prepares its private module on the host; printed Go +handoffs discover the host again when run. The CLI retains the native fallback +and saved-record selection. Application build targets still come from the +profile, and the public Go facades and dependency boundaries are unchanged. + +## Make the adoption smoke command runnable + +**Evidence:** The [adoption guide](../consumers/adoption.md#cli-tool-dependency) +tells readers to save the launcher as `releasekit` and run +`./releasekit version`. A newly saved shell file ordinarily lacks its execute +bit. In a disposable directory, the documented command failed with status 126 +and “Permission denied.” Invoking the same snippet through `sh` ran a +module-registered fixture tool on Linux/amd64 with inherited +`GOOS=windows GOARCH=arm64`. + +**Fix:** Use `sh ./releasekit version` in the smoke instructions, or give an +explicit `chmod +x ./releasekit` step before direct execution. Verify the +published instructions from a newly created file under a foreign target. + +## Limit the recovery guarantee to GOOS and GOARCH + +**Evidence:** The [CLI contract](../cli.md) says Go handoffs select the host +“independently of inherited cross-compilation settings.” The +[command formatter](../../cmd/releasekit/main.go) overrides `GOOS` and +`GOARCH` and retains other build settings. For example, building the actual CLI +with the native target, `CGO_ENABLED=1`, and an unavailable C compiler named +by `CC` still fails in `runtime/cgo`. This is consistent with the roadmap's +scope, but the CLI wording implies broader independence. + +**Fix:** Say that generated Go handoffs set `GOOS` and `GOARCH` from the +selected Go toolchain at invocation time. Preserve the other inherited settings +and the existing workspace and toolchain overrides. The documented handoff +uses POSIX shell syntax; identify that syntax when telling operators where to +paste the command. + +## Exercise a profile target that differs from the launcher host + +**Evidence:** The binary-delivery case in +[`TestMultiModuleWoodpeckerDelivery`](../../cmd/releasekit/multi_module_woodpecker_test.go) +supplies a foreign target to the workflow and checks the uploaded +`core-v2.1.0-linux-amd64` asset. The profile itself selects `linux/amd64`. +On the Linux/amd64 review host, the test cannot distinguish using the +profile target from accidentally using the normalized launcher target. The +current build code still applies the selected profile target explicitly. + +**Fix:** In that fixture, select a supported profile target distinct from the +host and assert the uploaded asset matches it. Where practical, inspect the +uploaded executable header as well as the name, so the test catches a +host-built payload with a profile-derived filename. Keep the existing local +forge fixture and native version check; the cross-built asset need not run on +the host. + +## Reconcile the feature roadmap with the completed implementation + +**Evidence:** The [feature roadmap](host-native-launchers.md) still declares +“implementation pending” and describes the pre-change launchers as the current +baseline. All six stages in the [implementation plan](implementation.md) are +marked complete, and the maintained launchers and recovery code implement the +host selection described there. + +**Fix:** Mark the roadmap implemented and label the old baseline as historical, +or retire the completed planning documents after review. Preserve the planned +release-note entry for the next selected release version. + +## Verification + +`go test ./...`, `go run ./internal/apicheck`, and syntax checks for the +maintained shell scripts passed. The Go suite exercised real tool preparation, +Woodpecker command blocks with local fixtures, and later execution of printed +recovery commands. Disposable smoke probes also verified the maintainer +launcher forwards the child status and the manual retry preserves the calling +shell's target variables. The review made no changes to production code or +tests.