cmd/boot: harden engine execution (#358)

Assisted-by: GPT-5.5

Author: astrophena

cmd/boot/internal/README.md

@@ -9,14 +9,16 @@ contracts used by the built-in modules.
 `main.go` builds an `internal.Engine` with:
 
 - a `Runtime`, which stores recipe root, home directory, environment access,
-  stdio, and whether the current run is interactive;
+  runtime environment overrides, stdio, color preference, and whether the current
+  run is interactive;
 - an entrypoint, normally `BOOT.star`;
 - a list of modules, each exposed as a Starlark module.
 
 `Engine.Load` executes the entrypoint with predeclared globals:
 
 - `task(...)` registers a task;
 - `fail(message)` stops recipe evaluation;
+- `host()` returns host/runtime metadata for top-level branching;
 - each Go module appears under its module name, such as `fs` or `pkg`.
 
 Top-level Starlark should only register tasks and choose machine profiles. Host
@@ -25,8 +27,8 @@ mutation belongs in task functions through module actions.
 ## Tasks and Actions
 
 A task is a named Starlark callable. When the engine runs a task, it attaches
-the task to the Starlark thread with `SetTask`. Module functions validate
-`InTask(thread)` and call `AddAction(thread, Action{...})`.
+the task to the Starlark thread with `SetTask`. Module functions call
+`RequireTask(thread, b)` and then `AddAction(thread, Action{...})`.
 
 An `Action` has:
 
@@ -59,16 +61,18 @@ that emits one idempotent action over a general-purpose command wrapper.
 
 Module function checklist:
 
-- Require task context for functions that emit actions.
+- Require task context for functions that emit actions with `boot.RequireTask`.
 - Parse arguments with `starlark.UnpackArgs`.
 - Resolve recipe inputs with `Runtime.ResolveSource`.
 - Resolve host targets with `Runtime.ResolveTarget`.
-- Use `Runtime.ExpandHome` or `Runtime.Hostname` rather than duplicating that
-  logic.
+- Use `Runtime.ExpandHome`, `Runtime.Hostname`, `Runtime.EnvValue`, and
+  `Runtime.SetEnv` rather than duplicating that logic.
 - Do not mutate the host while registering actions.
 - In dry-run, perform enough checks to decide skip/change but do not write.
-- Include command output in returned errors; use `boot.CommandError` when it
-  fits.
+- Include command output in returned errors; prefer `boot.RunCommand`,
+  `boot.RunCmd`, `boot.CommandOutput`, or `boot.CommandError`.
+- Use `boot.Output` and `boot.BulletList` for user-visible check details.
+- Validate Starlark file modes with `boot.FileMode`.
 - Keep successful JSON or textual output minimal; noisy reporting belongs in
   explicit check modules.
 
@@ -93,6 +97,10 @@ Use `--json` when another program needs stable output. JSON runs intentionally
 use a simpler sequential execution path so action results are ordered and easy
 to consume.
 
+Task selection is strict: if `-only`, `-skip`, or `-tag` leaves a selected task
+without one of its declared dependencies, selection fails instead of silently
+ignoring the missing dependency.
+
 When debugging command execution, prefer fake commands in a temporary `PATH`
 inside tests. See the `packages`, `systemd`, and `rescue` tests for examples.
 

cmd/boot/internal/command.go

@@ -18,15 +18,36 @@ func RunCommand(ctx context.Context, dir string, argv ...string) error {
 	if dir != "" {
 		cmd.Dir = dir
 	}
+	return RunCmd(cmd)
+}
+
+// RunCmd runs cmd and includes combined output in returned errors.
+func RunCmd(cmd *exec.Cmd) error {
 	var buf bytes.Buffer
 	cmd.Stdout = &buf
 	cmd.Stderr = &buf
 	if err := cmd.Run(); err != nil {
-		return CommandError(argv, buf.Bytes(), err)
+		return CommandError(cmd.Args, buf.Bytes(), err)
 	}
 	return nil
 }
 
+// CommandOutput runs argv and returns stdout, including combined output in returned errors.
+func CommandOutput(ctx context.Context, dir string, argv ...string) ([]byte, error) {
+	cmd := exec.CommandContext(ctx, argv[0], argv[1:]...)
+	if dir != "" {
+		cmd.Dir = dir
+	}
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		combined := append(append([]byte{}, out...), stderr.Bytes()...)
+		return nil, CommandError(cmd.Args, combined, err)
+	}
+	return out, nil
+}
+
 // CommandError formats a command failure with trimmed command output.
 func CommandError(argv []string, out []byte, err error) error {
 	msg := strings.TrimSpace(string(out))

cmd/boot/internal/consent/consent.go

@@ -37,8 +37,8 @@ type impl struct {
 }
 
 func (m *impl) require(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
-	if !boot.InTask(thread) {
-		return nil, fmt.Errorf("%s: can only be called from a task", b.Name())
+	if err := boot.RequireTask(thread, b); err != nil {
+		return nil, err
 	}
 
 	var (