Self-host bootstrap: add unified preflight (docker + php) with actionable guidance #2810

Milestone

M2 (bootstrap usability) — unblocks running #1492 gates on fresh/minimal hosts.

Problem

On minimal environments, the first self-host gate fails before any compiler signal is collected because required host tools are missing. Today, failures are split across multiple entrypoints (docker-exec.sh, bootstrap-selfhost-link.sh, Make targets), and the first failure can be low-signal or misleading.

Observed in a local workspace (2026-05-27):

• docker not present (docker: command not found)
• php not present (php: command not found)
• make bootstrap-selfhost-link and make bootstrap-selfhost-helloworld abort with “missing 'php' on host; run via Docker instead”, but Docker is also missing.

This blocks running the mandatory probes in #1492.

Repro (today)

On a host missing either dependency:

./script/docker-exec.sh -- true
make bootstrap-selfhost-link
make bootstrap-selfhost-helloworld
php script/bootstrap-inventory.php --check

Scope

• New: script/selfhost-preflight.sh (or similar)
  • Checks for: docker CLI (and docker info), host php, and prints one clear “what to install / what command to run next” message.
• Wire into:
  • script/docker-exec.sh (when used for bootstrap workflows)
  • script/bootstrap-selfhost-link.sh
  • script/bootstrap-selfhost-helloworld-probe.sh
  • optionally the relevant make bootstrap-* targets

Done when

• Running the repro commands on a minimal host produces a single, high-signal error that:
  • clearly categorizes the failure as environment prerequisites (not a compiler regression)
  • tells the user exactly which prerequisite is missing (docker and/or php)
  • gives one copy/paste path to proceed (e.g. install Docker, then ./script/docker-exec.sh -- bash -lc 'make bootstrap-selfhost-link')
• No change to the actual compiler gates; only preflight + messaging.

Labels

Suggest: self-host, bootstrap, IMPORTANT, area:tooling

Links

• Epic: Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492
• Related: docker-exec.sh: preflight missing docker binary with clear self-host guidance #2674 (docker-exec missing docker guidance)