thunderjar 0.1.2 → 0.1.3-preview-eee7160

package/src/cli/commands/build/build.docker.test.ts

@@ -0,0 +1,173 @@
+// Docker image tests for `build` — spec/120-test-boundaries.md#31-generating-the-pre-run-image.
+// Docker and the images are real; the agent is the fake one. Skipped by `bun test`; run with
+// `bun run test:prepare && bun run test:docker`. Each run passes a throwaway `--image-prefix`
+// and removes every image under it afterwards.
+//
+// Each runs the CLI in place in a checked-in scenario, as by hand:
+//
+//     bun run fixture scenario_4 build two-commits
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { makeTempDir, readTextSync } from "../../../platform/fs.ts";
+import { dirname, join } from "../../../platform/path.ts";
+import { dockerCli } from "../../../adapters/docker/docker.ts";
+import { scenario, thunderjar } from "../../../testing/cli.ts";
+
+const BASE_IMAGE = `node:20-bookworm`;
+const docker = dockerCli("docker");
+const prefix = `thunderjar-test-${process.pid}-${Date.now()}`;
+
+/**
+ * Runs `thunderjar <command> <testCase> --image-prefix <prefix>` in `project` against real Docker,
+ * with build contexts under a fresh $TMPDIR, and durations replaced by a placeholder.
+ */
+async function cli(project: string, command: string, testCase: string, env: Record<string, string> = {}) {
+  const tmpDir = await makeTempDir("thunderjar-build-docker-");
+  const result = await thunderjar(project, [command, testCase, "--image-prefix", prefix], {
+    THUNDERJAR_DOCKER: "docker",
+    TMPDIR: tmpDir,
+    ...env,
+  });
+  const normalise = (text: string) =>
+    text.replaceAll(tmpDir, "$TMPDIR").replaceAll(prefix, "<prefix>").replace(/ built \(\d+\.\d\ds\)$/gm, " built (<t>s)");
+  return { ...result, stdout: normalise(result.stdout), stderr: normalise(result.stderr) };
+}
+
+/** Runs `script` with sh in a throwaway container from `ref`. */
+function inImage(ref: string, script: string) {
+  const result = Bun.spawnSync(["docker", "run", "--rm", ref, "sh", "-c", script], { stdout: "pipe", stderr: "pipe" });
+  expect(result.stderr.toString()).toBe("");
+  return result.stdout.toString().trim();
+}
+
+const prefixed = (tag: string) => `${prefix}:${tag}`;
+
+describe.skipIf(!process.env.THUNDERJAR_TEST_DOCKER)("build, against real Docker", () => {
+  beforeAll(async () => {
+    const unreachable = await docker.unreachable();
+    if (unreachable) throw new Error(`Docker can't be reached (${unreachable}).`);
+    if (!(await docker.imageExists(BASE_IMAGE))) {
+      throw new Error(`The fixture image ${BASE_IMAGE} is missing. Run \`bun run test:prepare\` first.`);
+    }
+  });
+
+  afterAll(() => {
+    const images = Bun.spawnSync(["docker", "image", "ls", "--format", "{{.Repository}}:{{.Tag}}", prefix], { stdout: "pipe" })
+      .stdout.toString()
+      .split("\n")
+      .filter(Boolean);
+    if (images.length > 0) Bun.spawnSync(["docker", "image", "rm", "--force", ...images]);
+  });
+
+  describe("scenario_1_minimal_initial_setup", () => {
+    const fixtures = scenario("scenario_1_minimal_initial_setup");
+    const REF = prefixed("prerun-h8ffdda6e");
+
+    test("build example: /workspace holds the code state's and prompt set's files, and node; a second build reuses it", async () => {
+      // Outside any git repository, too: its parameters read no commits.
+      const built = await cli(fixtures, "build", "example", { GIT_CEILING_DIRECTORIES: dirname(fixtures) });
+
+      expect(built.exitCode).toBe(0);
+      expect(built.stdout).toBe(`Building 1 prerun image for example (1 permutation)
+Build contexts in $TMPDIR/thunderjar/builds
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    <prefix>:prerun-h8ffdda6e  built (<t>s)
+
+1 prerun image: 1 built, 0 reused
+`);
+      expect(inImage(REF, "pwd && ls -A")).toBe("/workspace\nFAKE_INSTRUCTIONS.md\npackage-lock.json\npackage.json");
+      expect(inImage(REF, "head -1 FAKE_INSTRUCTIONS.md")).toBe("# Snerk");
+      expect(inImage(REF, "node --version")).toStartWith("v20.");
+
+      const again = await cli(fixtures, "build", "example");
+      expect(again.stdout).toBe(`Every prerun image for example exists (1 permutation)
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    <prefix>:prerun-h8ffdda6e  reused
+
+1 prerun image: 0 built, 1 reused
+`);
+    }, 300_000);
+  });
+
+  describe("scenario_2_typical_project", () => {
+    const fixtures = scenario("scenario_2_typical_project");
+    const ALPHA = prefixed("prerun-hefe85dda");
+
+    test("build two-pairs: builds each missing prerun image; with one removed, builds only that one, and plan shows both reused", async () => {
+      const built = await cli(fixtures, "build", "two-pairs");
+
+      expect(built.exitCode).toBe(0);
+      // The tags are those `thunderjar plan two-pairs` shows.
+      expect(built.stdout).toBe(`Building 2 prerun images for two-pairs (2 permutations)
+Build contexts in $TMPDIR/thunderjar/builds
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | terse
+    <prefix>:prerun-hefe85dda  built (<t>s)
+
+ 2  node20 | baseline | snerk | fake-harness-beta@1.0.0/fake-model-large  | terse
+    <prefix>:prerun-h56ea4852  built (<t>s)
+
+2 prerun images: 2 built, 0 reused
+`);
+
+      Bun.spawnSync(["docker", "image", "rm", "--force", ALPHA]);
+      const again = await cli(fixtures, "build", "two-pairs");
+      expect(again.stdout).toContain("    <prefix>:prerun-hefe85dda  built (<t>s)\n");
+      expect(again.stdout).toContain("    <prefix>:prerun-h56ea4852  reused\n");
+      expect(again.stdout).toEndWith("2 prerun images: 1 built, 1 reused\n");
+
+      const plan = await cli(fixtures, "plan", "two-pairs");
+      expect(plan.stdout).toContain("    prerun-hefe85dda (exists, reused)\n");
+      expect(plan.stdout).toContain("    prerun-h56ea4852 (exists, reused)\n");
+    }, 300_000);
+  });
+
+  // Scenario 4's parameters read real commits of this repository, so its images show what only
+  // the copied files can: a prompt file read at its commit, and a bundle with nothing after its commit.
+  describe("scenario_4_git_project", () => {
+    const fixtures = scenario("scenario_4_git_project");
+    const FIRST = "523984c7fd72f047265ab89ce5901605af6acb2b";
+    const SECOND = "952687db16b373d58f79f46690f9c5b0aa1aa141";
+    const PROJECT = "fixtureTests/scenario_4_git_project/fixtures/project";
+    const refs = new Map<string, string>();
+
+    beforeAll(async () => {
+      const { stdout, exitCode } = await cli(fixtures, "build", "two-commits");
+      expect(exitCode).toBe(0);
+      expect(stdout).toEndWith("4 prerun images: 4 built, 0 reused\n");
+      // Each permutation's row, by code state and prompt set, and the image it built.
+      for (const [, codeState, promptSet, tag] of stdout.matchAll(/\| (\w+) +\| ([\w-]+) +\|.*\n {4}<prefix>:(\S+) {2}built/g)) {
+        refs.set(`${codeState}/${promptSet}`, prefixed(tag!));
+      }
+      expect(refs.size).toBe(4);
+    }, 300_000);
+
+    test("the first code state: this repository at the first commit, detached, with nothing after it", () => {
+      const ref = refs.get("first/house-style-second")!;
+      expect(inImage(ref, "pwd && git rev-parse HEAD && git rev-parse --abbrev-ref HEAD")).toBe(`/workspace\n${FIRST}\nHEAD`);
+      expect(inImage(ref, "git remote && git for-each-ref refs/heads")).toBe("");
+      expect(inImage(ref, `git log --all --format=%H | grep -c ${SECOND} || true`)).toBe("0");
+      expect(inImage(ref, `ls ${PROJECT}`)).toBe("greet.js\npackage-lock.json\npackage.json\nprompts");
+      // A git identity for the agent.
+      expect(inImage(ref, "git config user.email")).toBe("agent@thunderjar.invalid");
+    });
+
+    test("the second code state: the second commit, with the file it added", () => {
+      const ref = refs.get("second/house-style-first")!;
+      expect(inImage(ref, "git rev-parse HEAD")).toBe(SECOND);
+      expect(inImage(ref, `ls ${PROJECT}/farewell.js && cat ${PROJECT}/greet.js | tail -1`)).toBe(
+        `${PROJECT}/farewell.js\nexport const greet = (name) => \`Hello, \${name}!\`;`,
+      );
+    });
+
+    test("a prompt file is read at its prompt set's commit, never from the worktree", () => {
+      // The prompt set's commit, whichever the code state's is.
+      expect(inImage(refs.get("first/house-style-second")!, "head -1 HOUSE_STYLE.md")).toBe("# House style (second commit)");
+      expect(inImage(refs.get("second/house-style-first")!, "head -1 HOUSE_STYLE.md")).toBe("# House style (first commit)");
+      // The worktree's copy has moved on from both.
+      expect(readTextSync(join(fixtures, "project", "prompts", "house-style.md"))).toStartWith("# House style (worktree");
+    });
+  });
+});

package/src/cli/commands/build/build.test.ts

@@ -0,0 +1,234 @@
+// `thunderjar build`, through the CLI, in the checked-in fixtureTests/ scenarios, in place.
+//
+// - `--dry-run` prints each permutation's Dockerfile, so what each image is built from is
+//   asserted on stdout, with nothing built. Any of these can be run by hand:
+//
+//     bun run fixture scenario_2 build two-pairs --dry-run
+//
+// - The rest stop before an image is made, against the recording fake Docker
+//   (spec/120-test-boundaries.md#2-cli-with-recording-adapters): Docker can't be reached, a commit
+//   is missing, the project isn't in a git repository, or a build fails, which no scenario's does.
+//
+// What a real build makes, and which images it reuses, is in build.docker.test.ts.
+
+import { describe, expect, test } from "bun:test";
+import { existsSync, listDir, makeTempDir } from "../../../platform/fs.ts";
+import { dirname, join } from "../../../platform/path.ts";
+import { fakeDocker, scenario, thunderjar } from "../../../testing/cli.ts";
+
+type FakeDocker = Awaited<ReturnType<typeof fakeDocker>>;
+
+/**
+ * Runs `thunderjar build <testCase> <flags…>` in `project`, keeping build contexts under a fresh
+ * $TMPDIR, with $TMPDIR replaced by a placeholder.
+ */
+async function cliBuild(
+  project: string,
+  testCase: string,
+  { docker, flags = [], env = {} }: { docker?: FakeDocker; flags?: string[]; env?: Record<string, string> } = {},
+) {
+  docker ??= await fakeDocker();
+  const tmpDir = await makeTempDir("thunderjar-fixture-tmp-");
+  const result = await thunderjar(project, ["build", testCase, ...flags], { ...docker.env, TMPDIR: tmpDir, ...env });
+  const normalise = (text: string) => text.replaceAll(tmpDir, "$TMPDIR");
+  return {
+    exitCode: result.exitCode,
+    stdout: normalise(result.stdout),
+    stderr: normalise(result.stderr),
+    commands: docker.commands().map(normalise),
+    builds: join(tmpDir, "thunderjar", "builds"),
+  };
+}
+
+describe("scenario_1_minimal_initial_setup", () => {
+  const fixtures = scenario("scenario_1_minimal_initial_setup");
+
+  test("build example --dry-run: the Dockerfile copies the files beside the declarations", async () => {
+    const { stdout, stderr, exitCode } = await cliBuild(fixtures, "example", { flags: ["--dry-run"] });
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`Dockerfiles for example (1 permutation). Nothing is built.
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    thunderjar:prerun-h8ffdda6e
+
+    FROM node:20-bookworm
+    RUN echo "install fake-harness-alpha@1.0.0"
+    WORKDIR /workspace
+    COPY parameters/codeState/files/ /workspace/
+    RUN npm ci
+    COPY parameters/promptSet/FAKE_INSTRUCTIONS.md /workspace/FAKE_INSTRUCTIONS.md
+`);
+  });
+});
+
+describe("scenario_2_typical_project", () => {
+  // Its parameters copy the files beside their declarations, so it builds in place, with no commits to read.
+  const fixtures = scenario("scenario_2_typical_project");
+  const ALPHA = "thunderjar:prerun-hefe85dda";
+  const BETA = "thunderjar:prerun-h56ea4852";
+
+  test("build two-pairs --dry-run: prints each permutation's Dockerfile, without Docker, and writes nothing", async () => {
+    const { stdout, stderr, exitCode, commands, builds } = await cliBuild(fixtures, "two-pairs", {
+      docker: await fakeDocker([], ["unreachable"]),
+      flags: ["--dry-run"],
+    });
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    // The tags are those `thunderjar plan two-pairs` shows. Each fragment is in order, with
+    // Thunderjar's WORKDIR before the code state: nothing else is Thunderjar's.
+    expect(stdout).toBe(`Dockerfiles for two-pairs (2 permutations). Nothing is built.
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | terse
+    ${ALPHA}
+
+    FROM node:20-bookworm
+    RUN echo "install fake-harness-alpha@1.0.0"
+    WORKDIR /workspace
+    COPY parameters/codeState/files/ /workspace/
+    RUN npm ci
+    COPY parameters/promptSet/FAKE_INSTRUCTIONS.md /workspace/FAKE_INSTRUCTIONS.md
+
+ 2  node20 | baseline | snerk | fake-harness-beta@1.0.0/fake-model-large  | terse
+    ${BETA}
+
+    FROM node:20-bookworm
+    RUN echo "install fake-harness-beta@1.0.0"
+    WORKDIR /workspace
+    COPY parameters/codeState/files/ /workspace/
+    RUN npm ci
+    COPY parameters/promptSet/FAKE_INSTRUCTIONS.md /workspace/FAKE_INSTRUCTIONS.md
+`);
+    expect(commands).toEqual([]);
+    expect(existsSync(builds)).toBe(false);
+  });
+
+  test("--dry-run prints every permutation's Dockerfile, even when its image exists", async () => {
+    const { stdout, commands } = await cliBuild(fixtures, "two-pairs", {
+      docker: await fakeDocker([ALPHA, BETA]),
+      flags: ["--dry-run"],
+    });
+
+    expect(stdout).toContain(`RUN echo "install fake-harness-alpha@1.0.0"\n`);
+    expect(stdout).toContain(`RUN echo "install fake-harness-beta@1.0.0"\n`);
+    expect(commands).toEqual([]);
+  });
+
+  test("--dry-run tags with --image-prefix", async () => {
+    const { stdout } = await cliBuild(fixtures, "two-pairs", { flags: ["--dry-run", "--image-prefix", "throwaway"] });
+
+    expect(stdout).toContain("    throwaway:prerun-hefe85dda\n");
+    expect(stdout).toContain("    throwaway:prerun-h56ea4852\n");
+  });
+
+  test("without Docker, build stops before reading anything", async () => {
+    const { stdout, stderr, exitCode, commands } = await cliBuild(fixtures, "two-pairs", {
+      docker: await fakeDocker([], ["unreachable"]),
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toBe("");
+    expect(stderr).toBe(
+      "error: Docker can't be reached (Cannot connect to the Docker daemon at unix:///var/run/docker.sock. " +
+        "Is the docker daemon running?). Building prerun images needs Docker.\n",
+    );
+    expect(commands).toEqual(["docker version --format {{.Server.Version}}"]);
+  });
+
+  test("a failed build stops, and keeps its build context for inspection", async () => {
+    const { stdout, stderr, exitCode, commands, builds } = await cliBuild(fixtures, "two-pairs", {
+      docker: await fakeDocker([], ["fail-build"]),
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toEndWith(" 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | terse\n");
+    expect(stderr).toBe(`fake docker: the build failed
+error: building ${ALPHA} failed (docker build exited 1).
+Its build context is kept in $TMPDIR/thunderjar/builds/prerun-hefe85dda
+`);
+    expect(commands.filter((c) => c.startsWith("docker build"))).toHaveLength(1);
+    expect(listDir(join(builds, "prerun-hefe85dda"))).toContain("Dockerfile");
+  });
+
+  test("build with no test case, an unknown flag, or --image-prefix without a name, says what's wrong, then its usage", async () => {
+    for (const [args, error] of [
+      [["build"], "error: missing required argument 'test case'"],
+      [["build", "two-pairs", "--dry"], "error: unknown option '--dry'"],
+      [["build", "two-pairs", "--image-prefix"], "error: option '--image-prefix <name>' argument missing"],
+      [["build", "--image-prefix", "two-pairs"], "error: missing required argument 'test case'"],
+    ] as const) {
+      const { stdout, stderr, exitCode } = await thunderjar(fixtures, [...args]);
+      expect(stdout).toBe("");
+      expect(stderr).toStartWith(error);
+      expect(stderr).toContain("Usage: thunderjar build [options] <test case>");
+      expect(exitCode).toBe(1);
+    }
+  });
+});
+
+describe("scenario_4_git_project", () => {
+  // Its code states and prompt sets read two real commits of this repository, the ones that added
+  // and changed fixtures/project/ (tags fixture-scenario-4-first and fixture-scenario-4-second).
+  const fixtures = scenario("scenario_4_git_project");
+  const FIRST = "523984c7fd72f047265ab89ce5901605af6acb2b";
+  const SECOND = "952687db16b373d58f79f46690f9c5b0aa1aa141";
+  const PROJECT = "fixtureTests/scenario_4_git_project/fixtures/project";
+
+  test("build two-commits --dry-run: each code state checks out its own commit, each prompt set copies its file at its own", async () => {
+    const { stdout, stderr, exitCode, commands } = await cliBuild(fixtures, "two-commits", { flags: ["--dry-run"] });
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(commands).toEqual([]);
+    const permutation = (row: string, tag: string, commit: string, promptCommit: string) => `
+${row} | fake-harness-alpha@1.0.0/fake-model-small | plain
+    thunderjar:${tag}
+
+    FROM node:20-bookworm
+    RUN echo "install fake-harness-alpha@1.0.0"
+    WORKDIR /workspace
+    COPY git/${commit}.bundle /tmp/code.bundle
+    RUN git clone --quiet /tmp/code.bundle /workspace \\
+      && git -C /workspace checkout --quiet --detach ${commit} \\
+      && git -C /workspace branch --quiet --delete --force code-state \\
+      && git -C /workspace remote remove origin \\
+      && git -C /workspace config user.name "Thunderjar agent" \\
+      && git -C /workspace config user.email agent@thunderjar.invalid \\
+      && rm /tmp/code.bundle
+    RUN cd ${PROJECT} && npm ci
+    COPY git/${promptCommit}/${PROJECT}/prompts/house-style.md /workspace/HOUSE_STYLE.md
+`;
+    expect(stdout).toBe(
+      "Dockerfiles for two-commits (4 permutations). Nothing is built.\n" +
+        permutation(" 1  node20 | first  | house-style-first ", "prerun-hf803f77d", FIRST, FIRST) +
+        permutation(" 2  node20 | first  | house-style-second", "prerun-h85c50e99", FIRST, SECOND) +
+        permutation(" 3  node20 | second | house-style-first ", "prerun-hc7fcb855", SECOND, FIRST) +
+        permutation(" 4  node20 | second | house-style-second", "prerun-h51cb391f", SECOND, SECOND),
+    );
+  });
+
+  test("a commit that isn't in this repository stops the build before anything is built", async () => {
+    const { stdout, stderr, exitCode, commands } = await cliBuild(fixtures, "unpushed-commit");
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toBe("");
+    expect(stderr).toBe(`error: commit a1b2c3 (code state "unpushed") is not in this repository.
+Fetch it, or check that it has been pushed.
+`);
+    expect(commands.filter((c) => c.startsWith("docker build"))).toEqual([]);
+  });
+
+  test("a project whose parameters read commits must be in a git repository", async () => {
+    // Git doesn't look above the scenario's folder, so finds no repository for fixtures/.
+    const { stdout, stderr, exitCode, commands } = await cliBuild(fixtures, "two-commits", {
+      env: { GIT_CEILING_DIRECTORIES: dirname(fixtures) },
+    });
+
+    expect(exitCode).toBe(1);
+    expect(stdout).toBe("");
+    expect(stderr).toBe(`error: ${fixtures} is not in a git repository, but code state "first" reads commit ${FIRST} from it.\n`);
+    expect(commands.filter((c) => c.startsWith("docker build"))).toEqual([]);
+  });
+});

package/src/cli/commands/build/build.ts

@@ -0,0 +1,115 @@
+// `thunderjar build <test case>` — builds each permutation's prerun image that doesn't exist
+// yet, then stops: nothing is run and nothing is recorded. spec/080-docker-execution.md#process,
+// as far as "Prerun image ready".
+//
+// What it checks before the first build, and where it keeps each build context, are
+// src/images/prerun-builds.ts's, which `run` builds through too.
+//
+// `--dry-run` prints the Dockerfile each permutation's prerun image would be built from, for
+// every permutation, whether or not its image exists. It builds nothing, writes nothing, and
+// doesn't ask Docker anything, nor read any commit, so what it prints doesn't depend on either.
+
+import { Command } from "commander";
+import { join } from "../../../platform/path.ts";
+import { dockerCli, type Docker } from "../../../adapters/docker/docker.ts";
+import { findThunderjarRoot, loadTestCase } from "../../../project/config.ts";
+import { permutationRows } from "../../../matrix/permutations.ts";
+import { LOCAL_REPOSITORY, loadPrerunParameters, prerunImageRef, renderPrerun } from "../../../images/prerun.ts";
+import { preparePrerunBuilds } from "../../../images/prerun-builds.ts";
+import { resolveTestCase } from "../../../matrix/resolve.ts";
+import { defaultRootDir } from "../../../running/runner.ts";
+import { count, seconds } from "../format.ts";
+import { imagePrefixOption } from "../options.ts";
+
+export interface BuildOptions {
+  cwd?: string;
+  /** Receives the output a block at a time, as it is produced. */
+  log?: (text: string) => void;
+  docker?: Docker;
+  /** Print each permutation's Dockerfile instead of building, `--dry-run`. */
+  dryRun?: boolean;
+  /** The image repository prerun images are tagged in, `--image-prefix`. Tests use a throwaway one. */
+  repository?: string;
+  /** Build contexts are kept under `<rootDir>/builds/`. Defaults to `$TMPDIR/thunderjar`. */
+  rootDir?: string;
+  /** The clock for timing builds; stubbed in tests so output is deterministic. */
+  now?: () => number;
+}
+
+export async function build(name: string, options: BuildOptions = {}): Promise<void> {
+  const {
+    cwd = process.cwd(),
+    log = (text) => console.log(text),
+    docker = dockerCli(),
+    dryRun = false,
+    repository = LOCAL_REPOSITORY,
+    rootDir = defaultRootDir(),
+    now = Date.now,
+  } = options;
+
+  const root = findThunderjarRoot(cwd);
+  const testCase = await loadTestCase(root, name);
+  const { permutations } = await resolveTestCase(root, testCase);
+  const rows = permutationRows(permutations);
+  const numberWidth = Math.max(2, String(permutations.length).length);
+  const pad = " ".repeat(numberWidth + 2);
+
+  if (dryRun) {
+    log(`Dockerfiles for ${name} (${count(permutations.length, "permutation")}). Nothing is built.`);
+    for (const [n, permutation] of permutations.entries()) {
+      const { dockerfile } = renderPrerun(await loadPrerunParameters(root, testCase.task, permutation));
+      log("");
+      log(`${String(n + 1).padStart(numberWidth)}  ${rows[n]}`);
+      log(`${pad}${prerunImageRef(repository, permutation.hash)}`);
+      log("");
+      log(dockerfile.trimEnd().replace(/^(?=.)/gm, pad));
+    }
+    return;
+  }
+
+  const builds = await preparePrerunBuilds({
+    root,
+    task: testCase.task,
+    permutations,
+    docker,
+    repository,
+    rootDir,
+    purpose: "Building prerun images",
+  });
+  const toBuild = builds.missing.size;
+  if (toBuild > 0) {
+    log(`Building ${count(toBuild, "prerun image")} for ${name} (${count(permutations.length, "permutation")})`);
+    log(`Build contexts in ${join(rootDir, "builds")}`);
+  } else {
+    log(`Every prerun image for ${name} exists (${count(permutations.length, "permutation")})`);
+  }
+
+  for (const [n, permutation] of permutations.entries()) {
+    const ref = prerunImageRef(repository, permutation.hash);
+    log("");
+    log(`${String(n + 1).padStart(numberWidth)}  ${rows[n]}`);
+    if (!builds.missing.has(permutation.hash)) {
+      log(`${pad}${ref}  reused`);
+      continue;
+    }
+    const started = now();
+    await builds.build(permutation.hash);
+    log(`${pad}${ref}  built (${seconds(now() - started)})`);
+  }
+
+  log("");
+  log(
+    `${count(permutations.length, "prerun image")}: ${toBuild} built, ${permutations.length - toBuild} reused`,
+  );
+}
+
+export function createBuildCommand(): Command {
+  return new Command("build")
+    .description("Build a test case's prerun images.")
+    .argument("<test case>", "the test case whose prerun images to build")
+    .option("--dry-run", "print each permutation's Dockerfile instead of building")
+    .addOption(imagePrefixOption("the image repository prerun images are tagged in"))
+    .action(async (name: string, options: { dryRun?: boolean; imagePrefix?: string }) => {
+      await build(name, { dryRun: options.dryRun ?? false, repository: options.imagePrefix });
+    });
+}