test(cli): hold every edit mutate makes in the command files

A whole-repository mutate run left 66 edits in open, stop, check, exec,
up, build and gpu that no test refused. The new tests check what a
caller depends on, without Docker: the positional [path] of open, stop,
down and build, open's editor launch and config, check's exit code,
saved state and JSON, the up/build host hint on a real pseudo-terminal,
the lifecycle marker scripts run by the host's sh, exec's Compose
container lookup against the fake engine, and the GPU runtime probe.

Two edits nobody can observe carry a mutate-exempt instead: the
tabwriter's minwidth, tabwidth and flags in the check table (moved to a
const so the padding stays mutated and tested), and the signal branch
of execExitCode, where ExitCode -1 always comes with a signaled
WaitStatus.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: aledbf

internal/cli/build_repo_held_test.go

@@ -0,0 +1,96 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/devcontainers/cli/internal/config"
+)
+
+// buildConfigNotFound runs build with args and returns the path its "config
+// not found" error names.
+func buildConfigNotFound(t *testing.T, args ...string) string {
+	t.Helper()
+	cmd := newBuildCmd()
+	cmd.SilenceUsage, cmd.SilenceErrors = true, true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&bytes.Buffer{})
+	cmd.SetArgs(args)
+	_ = cmd.ExecuteContext(t.Context())
+	var got struct{ Outcome, Message string }
+	if err := json.Unmarshal(out.Bytes(), &got); err != nil {
+		t.Fatalf("stdout is not one JSON result: %v\n%s", err, out.String())
+	}
+	if got.Outcome != "error" {
+		t.Fatalf("outcome = %q, want error", got.Outcome)
+	}
+	return got.Message
+}
+
+// build [path] builds the workspace the argument names, not the current
+// directory; --workspace-folder wins over the argument.
+func TestBuildPositionalPathIsTheWorkspace(t *testing.T) {
+	ws := t.TempDir()
+	t.Chdir(t.TempDir())
+	want := "Dev container config (" + filepath.Join(ws, ".devcontainer", "devcontainer.json") + ") not found."
+	if got := buildConfigNotFound(t, ws); got != want {
+		t.Errorf("message = %q, want %q", got, want)
+	}
+	if got := buildConfigNotFound(t, t.TempDir(), "--workspace-folder", ws); got != want {
+		t.Errorf("message with --workspace-folder = %q, want %q", got, want)
+	}
+}
+
+// A build target names the stage to build, and the Dockerfile is used as it
+// is, with no stage name added.
+func TestPrepareDockerfileBuildUsesTheConfiguredTarget(t *testing.T) {
+	dir := t.TempDir()
+	dockerfile := filepath.Join(dir, "Dockerfile")
+	if err := os.WriteFile(dockerfile, []byte("FROM alpine AS base\nFROM base\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cfg := &config.DevContainer{
+		ConfigFilePath: filepath.Join(dir, "devcontainer.json"),
+		Build:          &config.Build{Dockerfile: "Dockerfile", Target: "base"},
+	}
+	prep, err := prepareDockerfileBuild(cfg)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer prep.Cleanup()
+	if prep.StageName != "base" || prep.Path != dockerfile {
+		t.Errorf("stage %q at %q, want base at %q", prep.StageName, prep.Path, dockerfile)
+	}
+}
+
+// Without a target, the final stage gets a name to build, in a Dockerfile
+// written next to the user's, whether the Dockerfile is named under build or
+// at the top level.
+func TestPrepareDockerfileBuildNamesTheFinalStageWithoutATarget(t *testing.T) {
+	for name, cfg := range map[string]config.DevContainer{
+		"build":     {Build: &config.Build{Dockerfile: "Dockerfile"}},
+		"top level": {DockerFile: "Dockerfile"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			dockerfile := filepath.Join(dir, "Dockerfile")
+			if err := os.WriteFile(dockerfile, []byte("FROM alpine\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			cfg.ConfigFilePath = filepath.Join(dir, "devcontainer.json")
+			prep, err := prepareDockerfileBuild(&cfg)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer prep.Cleanup()
+			const stage = "dev_container_auto_added_stage_label"
+			if prep.StageName != stage || prep.Path != dockerfile+".devcontainer.build" {
+				t.Errorf("stage %q at %q, want %s at the written Dockerfile", prep.StageName, prep.Path, stage)
+			}
+		})
+	}
+}

internal/cli/check.go

@@ -147,7 +147,9 @@ func writeSetupResult(out Output, opts *setupOpts, actions []doctor.Action, fina
 
 // writeReportTable renders the ✔/⚠/✖ table plus per-line remediation hints.
 func writeReportTable(w io.Writer, report doctor.Report) {
-	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+	// mutate-exempt: a minwidth of 1 is below every cell's width plus the padding of 2, tabwidth counts only with '\t' padding, and flag 1 (FilterHTML) re-measures only HTML, which no status symbol or check name holds
+	const minwidth, tabwidth, flags = 0, 0, 0
+	tw := tabwriter.NewWriter(w, minwidth, tabwidth, 2, ' ', flags)
 	for _, r := range report.Results {
 		fmt.Fprintf(tw, "%s\t%s\t%s\n", r.Status.Symbol(), r.Name, r.Summary)
 	}

internal/cli/check_held_test.go

@@ -4,6 +4,8 @@ import (
 	"encoding/json"
 	"errors"
 	"io"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -98,3 +100,82 @@ func TestWriteSetupResultText(t *testing.T) {
 		t.Errorf("stderr = %q, want no note when the state was saved", saved.err.String())
 	}
 }
+
+// The table pads its columns two spaces past their widest cell.
+func TestWriteReportTableAlignsTheColumns(t *testing.T) {
+	var buf strings.Builder
+	writeReportTable(&buf, sampleReport())
+	want := "✔  docker-daemon       Docker daemon reachable (server 27.0)\n" +
+		"⚠  build-cache-export  cannot export cache\n" +
+		"  → build-cache-export: run `devcontainer setup`\n" +
+		"\noverall: ⚠ warn\n"
+	if buf.String() != want {
+		t.Errorf("table =\n%s\nwant\n%s", buf.String(), want)
+	}
+}
+
+// runCheckWithoutDocker runs check against a docker CLI that does not exist,
+// so the daemon check fails, with the check state under stateHome.
+func runCheckWithoutDocker(t *testing.T, out Output, json bool, stateHome string) error {
+	t.Helper()
+	t.Setenv("XDG_STATE_HOME", stateHome)
+	return runCheck(t.Context(), out, &checkOpts{json: json, dockerPath: filepath.Join(t.TempDir(), "docker")})
+}
+
+// A failing host prints the table, saves the state and exits 1.
+func TestRunCheckFailingHostExitsOne(t *testing.T) {
+	state := t.TempDir()
+	out := &captureOutput{}
+	err := runCheckWithoutDocker(t, out, false, state)
+	if exitCode(err) != 1 {
+		t.Fatalf("err = %v, want exit code 1 for a failing host", err)
+	}
+	if s := out.out.String(); !strings.HasSuffix(s, "\noverall: ✖ fail\n") {
+		t.Errorf("stdout = %q, want the table of a failing host", s)
+	}
+	if out.err.Len() != 0 {
+		t.Errorf("stderr = %q, want nothing when the state was saved", out.err.String())
+	}
+	saved, ok, err := doctor.LoadFrom(filepath.Join(state, "devcontainer", "check.json"))
+	if err != nil || !ok || saved.Overall != doctor.StatusFail {
+		t.Errorf("saved state = %+v, %v, %v; want the failing report", saved, ok, err)
+	}
+}
+
+// A state that cannot be saved is a note on stderr, not a failure of its own.
+func TestRunCheckNotesAStateItCouldNotSave(t *testing.T) {
+	blocker := filepath.Join(t.TempDir(), "file")
+	if err := os.WriteFile(blocker, nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out := &captureOutput{}
+	err := runCheckWithoutDocker(t, out, false, blocker)
+	if exitCode(err) != 1 {
+		t.Fatalf("err = %v, want exit code 1 for a failing host", err)
+	}
+	if s := out.err.String(); !strings.HasPrefix(s, "note: could not save check state: ") {
+		t.Errorf("stderr = %q, want the note", s)
+	}
+}
+
+// --json prints the report as JSON and still exits 1 for a failing host; a
+// stdout that cannot be written fails with that error.
+func TestRunCheckJSON(t *testing.T) {
+	out := &captureOutput{}
+	err := runCheckWithoutDocker(t, out, true, t.TempDir())
+	if exitCode(err) != 1 {
+		t.Fatalf("err = %v, want exit code 1 for a failing host", err)
+	}
+	var got doctor.Report
+	if err := json.Unmarshal(out.out.Bytes(), &got); err != nil {
+		t.Fatalf("stdout is not JSON: %v\n%s", err, out.out.String())
+	}
+	if got.Overall != doctor.StatusFail || len(got.Results) == 0 {
+		t.Errorf("report = %+v, want a failing report", got)
+	}
+
+	err = runCheckWithoutDocker(t, &brokenStdout{}, true, t.TempDir())
+	if err == nil || !strings.Contains(err.Error(), "stdout closed") {
+		t.Fatalf("err = %v, want the write error", err)
+	}
+}

internal/cli/check_repo_held_test.go

@@ -0,0 +1,106 @@
+//go:build linux
+
+package cli
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+	"unsafe"
+
+	"github.com/devcontainers/cli/internal/doctor"
+)
+
+// openPTY opens a pseudo-terminal: what is written to the returned terminal
+// can be read back from the returned master.
+func openPTY(t *testing.T) (master, terminal *os.File) {
+	t.Helper()
+	master, err := os.OpenFile("/dev/ptmx", os.O_RDWR, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { master.Close() })
+	var unlock int32
+	if _, _, errno := syscall.Syscall(syscall.SYS_IOCTL, master.Fd(), syscall.TIOCSPTLCK, uintptr(unsafe.Pointer(&unlock))); errno != 0 {
+		t.Fatalf("unlock pty: %v", errno)
+	}
+	var n uint32
+	if _, _, errno := syscall.Syscall(syscall.SYS_IOCTL, master.Fd(), syscall.TIOCGPTN, uintptr(unsafe.Pointer(&n))); errno != 0 {
+		t.Fatalf("pty number: %v", errno)
+	}
+	terminal, err = os.OpenFile(fmt.Sprintf("/dev/pts/%d", n), os.O_RDWR|syscall.O_NOCTTY, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { terminal.Close() })
+	return master, terminal
+}
+
+type terminalStderr struct{ terminal *os.File }
+
+func (terminalStderr) Stdout() io.Writer   { return io.Discard }
+func (o terminalStderr) Stderr() io.Writer { return o.terminal }
+
+// warnOnTerminal runs warnUncheckedHost with a terminal for stderr and the
+// check state under stateHome, and returns what it wrote there.
+func warnOnTerminal(t *testing.T, stateHome string) string {
+	t.Helper()
+	t.Setenv("XDG_STATE_HOME", stateHome)
+	master, terminal := openPTY(t)
+	warnUncheckedHost(terminalStderr{terminal})
+	const end = "END-OF-OUTPUT"
+	fmt.Fprintln(terminal, end)
+	var got strings.Builder
+	r := bufio.NewReader(master)
+	for {
+		line, err := r.ReadString('\n')
+		if err != nil {
+			t.Fatalf("read terminal: %v (read %q)", err, got.String())
+		}
+		line = strings.TrimRight(line, "\r\n")
+		if line == end {
+			return got.String()
+		}
+		got.WriteString(line + "\n")
+	}
+}
+
+func saveCheckState(t *testing.T, overall doctor.Status) string {
+	t.Helper()
+	home := t.TempDir()
+	if err := doctor.SaveTo(filepath.Join(home, "devcontainer", "check.json"), doctor.Report{Overall: overall}); err != nil {
+		t.Fatal(err)
+	}
+	return home
+}
+
+// On a terminal, up and build hint at `check` when the host was never checked,
+// warn when the last check failed, and say nothing after a passing check or
+// when the state cannot be read.
+func TestWarnUncheckedHostOnATerminal(t *testing.T) {
+	unreadable := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(unreadable, "devcontainer", "check.json"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		name  string
+		state string
+		want  string
+	}{
+		{"never checked", t.TempDir(), "hint: host not yet checked — run `devcontainer check` to verify your Docker setup.\n"},
+		{"failing host", saveCheckState(t, doctor.StatusFail), "warning: `devcontainer check` reported a failing host configuration — run `devcontainer check` for details.\n"},
+		{"passing host", saveCheckState(t, doctor.StatusOK), ""},
+		{"unreadable state", unreadable, ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := warnOnTerminal(t, tc.state); got != tc.want {
+				t.Errorf("stderr = %q, want %q", got, tc.want)
+			}
+		})
+	}
+}

internal/cli/exec.go

@@ -366,6 +366,7 @@ func execExitCode(exitErr *exec.ExitError) int {
 	if code != -1 {
 		return code
 	}
+	// mutate-exempt: ExitCode is -1 only for a child a signal ended, whose WaitStatus is always there and Signaled, so || takes the same branch
 	if ws, ok := exitErr.Sys().(syscall.WaitStatus); ok && ws.Signaled() {
 		return 128 + int(ws.Signal())
 	}