thunderjar 0.1.2 → 0.1.3-preview-eee7160

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

@@ -0,0 +1,123 @@
+// `thunderjar init`, through the CLI, in a copy of a checked-in fixtureTests/ scenario, because it
+// writes into the project. Each test asserts on what it printed and the files it created or
+// skipped. Any of these can be run by hand, in a scratch copy of the scenario:
+//
+//   cp -r fixtureTests/scenario_6_uninitialised_project/fixtures /tmp/s6 && cd /tmp/s6 && thunderjar init
+
+import { describe, expect, test } from "bun:test";
+import { listEntries } from "../../../platform/fs.ts";
+import { join } from "../../../platform/path.ts";
+import { copyOfFixtures, scenario, thunderjar } from "../../../testing/cli.ts";
+
+/** Every file under `.thunderjar/` in `dir`, sorted. */
+const filesIn = (dir: string) =>
+  listEntries(join(dir, ".thunderjar"), { recursive: true })
+    .filter((entry) => !entry.isDirectory)
+    .map((entry) => entry.path)
+    .toSorted();
+
+const read = (dir: string, rel: string) => Bun.file(join(dir, ".thunderjar", rel)).text();
+
+/** What `init` scaffolds in any project, in the order it prints them. */
+const SCAFFOLD = [
+  "thunderjar.config.ts",
+  "tsconfig.json",
+  "test-cases/example.ts",
+  "test-case-parameters/baseImages/node20/index.ts",
+  "test-case-parameters/codeStates/baseline/index.ts",
+  "test-case-parameters/promptSets/snerk/index.ts",
+  "test-case-parameters/harnessModels/claude-code/index.ts",
+  "test-case-parameters/harnessModels/claude-code/models.ts",
+  "test-case-parameters/harnessModels/claude-code/versions.ts",
+  "test-case-parameters/harnessModels/claude-code/collectTokenCosts.ts",
+  "test-case-parameters/tasks/is-prime/initial-prompts/plain.ts",
+  "test-case-parameters/tasks/is-prime/measurements/isPrimeTsExists.ts",
+];
+
+describe("scenario_6_uninitialised_project", () => {
+  const fixtures = scenario("scenario_6_uninitialised_project");
+
+  test("init: scaffolds .thunderjar/, with a nested package.json and node_modules ignored", async () => {
+    const dir = await copyOfFixtures(fixtures);
+
+    const { stdout, stderr, exitCode } = await thunderjar(dir, ["init"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    const created = [...SCAFFOLD, "package.json", ".gitignore"];
+    expect(stdout).toBe(created.map((f) => `created  .thunderjar/${f}\n`).join(""));
+    expect(filesIn(dir)).toEqual(created.toSorted());
+    expect(await read(dir, ".gitignore")).toBe("_generated/\n.data/\nnode_modules/\n");
+    expect(JSON.parse(await read(dir, "package.json"))).toEqual({
+      name: "thunderjar-config",
+      private: true,
+      type: "module",
+      dependencies: { thunderjar: "latest" },
+    });
+    expect(await read(dir, "thunderjar.config.ts")).toBe(`import { declareConfig, sqliteStore } from "thunderjar";
+
+export default declareConfig({
+  imageStore: { repository: "ghcr.io/your-org/thunderjar-images" },
+  runDataStore: sqliteStore({ path: "./.thunderjar/.data/runs.sqlite" }),
+});
+`);
+  });
+
+  test("init: every TypeScript file it scaffolds resolves its thunderjar imports", async () => {
+    const dir = await copyOfFixtures(fixtures);
+
+    await thunderjar(dir, ["init"]);
+
+    for (const file of filesIn(dir).filter((f) => f.endsWith(".ts"))) {
+      await import(join(dir, ".thunderjar", file));
+    }
+  });
+});
+
+describe("scenario_7_uninitialised_js_project", () => {
+  const fixtures = scenario("scenario_7_uninitialised_js_project");
+
+  test("init: a project with a root package.json gets no nested one", async () => {
+    const dir = await copyOfFixtures(fixtures);
+
+    const { stdout, stderr, exitCode } = await thunderjar(dir, ["init"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    const created = [...SCAFFOLD, ".gitignore"];
+    expect(stdout).toBe(created.map((f) => `created  .thunderjar/${f}\n`).join(""));
+    expect(filesIn(dir)).toEqual(created.toSorted());
+    expect(await read(dir, ".gitignore")).toBe("_generated/\n.data/\n");
+  });
+});
+
+describe("scenario_1_minimal_initial_setup", () => {
+  const fixtures = scenario("scenario_1_minimal_initial_setup");
+
+  test("init: in an existing project, creates only what's missing and leaves the rest as it was", async () => {
+    const dir = await copyOfFixtures(fixtures);
+    const before = new Map(await Promise.all(filesIn(dir).map(async (f) => [f, await read(dir, f)] as const)));
+
+    const { stdout, stderr, exitCode } = await thunderjar(dir, ["init"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`created  .thunderjar/tsconfig.json
+created  .thunderjar/test-case-parameters/harnessModels/claude-code/index.ts
+created  .thunderjar/test-case-parameters/harnessModels/claude-code/models.ts
+created  .thunderjar/test-case-parameters/harnessModels/claude-code/versions.ts
+created  .thunderjar/test-case-parameters/harnessModels/claude-code/collectTokenCosts.ts
+created  .thunderjar/package.json
+exists   .thunderjar/thunderjar.config.ts
+exists   .thunderjar/test-cases/example.ts
+exists   .thunderjar/test-case-parameters/baseImages/node20/index.ts
+exists   .thunderjar/test-case-parameters/codeStates/baseline/index.ts
+exists   .thunderjar/test-case-parameters/promptSets/snerk/index.ts
+exists   .thunderjar/test-case-parameters/tasks/is-prime/initial-prompts/plain.ts
+exists   .thunderjar/test-case-parameters/tasks/is-prime/measurements/isPrimeTsExists.ts
+exists   .thunderjar/.gitignore
+`);
+    for (const [file, content] of before) expect(await read(dir, file)).toBe(content);
+    expect(await read(dir, "test-cases/example.ts")).toContain("fake-harness-alpha@1.0.0/fake-model-small");
+  });
+});

package/src/cli/commands/init/init.ts

@@ -0,0 +1,189 @@
+import { Command } from "commander";
+import { existsSync } from "../../../platform/fs.ts";
+import { join } from "../../../platform/path.ts";
+
+const config = `import { declareConfig, sqliteStore } from "thunderjar";
+
+export default declareConfig({
+  imageStore: { repository: "ghcr.io/your-org/thunderjar-images" },
+  runDataStore: sqliteStore({ path: "./.thunderjar/.data/runs.sqlite" }),
+});
+`;
+
+const stub = (fn: string, body: string) => `import { ${fn} } from "thunderjar";\n\nexport default ${fn}(${body});\n`;
+
+const baseImage = stub(
+  "declareBaseImage",
+  `{
+  applyParameter: () => \`FROM node:20-bookworm\`,
+}`,
+);
+
+// Applying a parameter is up to its applyParameter. These read commits from the repository
+// Thunderjar is run in: checkoutCommit clones the code state's commit, with no later history,
+// into /workspace, and ctx.git.show reads one file at a commit into the build context.
+const codeState = `import { checkoutCommit, declareCodeState } from "thunderjar";
+
+export default declareCodeState({
+  config: { commit: "a1b2c3" },
+  applyParameter: (config, ctx) => \`\${checkoutCommit(ctx, config.commit)}\\nRUN npm ci\`,
+});
+`;
+
+const promptSet = stub(
+  "declarePromptSet",
+  `{
+  config: { commit: "e4f5a6" },
+  applyParameter: (config, ctx) => \`COPY \${ctx.git.show(config.commit, "prompts/snerk.md")} /workspace/CLAUDE.md\`,
+}`,
+);
+
+const harnessIndex = stub(
+  "declareHarness",
+  `{
+  applyParameter: (_config, ctx) => \`RUN npm install -g @anthropic-ai/claude-code@\${ctx.version}\`,
+  cli: (ctx) => \`claude -p "\${ctx.initialPrompt}" --model \${ctx.modelId} > \${ctx.resultPath}\`,
+  requiredEnv: ["ANTHROPIC_API_KEY"],
+}`,
+);
+
+const harnessModels = stub(
+  "declareHarnessModels",
+  `{
+  "haiku-4-5": "claude-haiku-4-5-20251001",
+}`,
+);
+
+const harnessVersions = stub(
+  "declareHarnessVersions",
+  `{
+  "2.1.283": { version: "2.1.283" },
+}`,
+);
+
+const collectTokenCosts = stub(
+  "declareTokenCostCollector",
+  `(_raw, _ctx) => {
+  return { outcome: "unavailable", reason: "notReported" };
+}`,
+);
+
+const initialPrompt = stub(
+  "declareInitialPrompt",
+  `{
+  prompt: "Create a file isPrime.ts exporting a function that tests for primality.",
+  timeoutSeconds: 600,
+  applyParameter: () => \`\`,
+}`,
+);
+
+const measurement = stub(
+  "declareMeasurement",
+  `{
+  instrument: "fileCreated",
+  config: { glob: "**/isPrime.ts" },
+  aggregate: ["rate"],
+}`,
+);
+
+const testCase = stub(
+  "declareTestCase",
+  `{
+  baseImage: ["node20"],
+  codeState: ["baseline"],
+  promptSet: ["snerk"],
+  harnessModel: ["claude-code@2.1.283/haiku-4-5"],
+  task: "is-prime",
+  initialPrompt: ["plain"],
+  iterations: 1,
+}`,
+);
+
+// Brings _generated/parameter-names.d.ts into the editor's program alongside the files
+// that use its names — without it they don't resolve, and nothing is checked
+// (spec/055-declaring-test-cases.md#typed-names). `allowImportingTsExtensions` because
+// thunderjar ships its TypeScript source.
+const tsconfig =
+  JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        allowImportingTsExtensions: true,
+      },
+      include: ["**/*.ts"],
+      // A templateTest template isn't TypeScript until it is rendered.
+      exclude: ["node_modules", ".data", "**/*.template.ts"],
+    },
+    null,
+    2,
+  ) + "\n";
+
+const P = "test-case-parameters";
+
+/** Files `init` creates under `.thunderjar/`, keyed by relative path. */
+function scaffold(): Record<string, string> {
+  return {
+    "thunderjar.config.ts": config,
+    "tsconfig.json": tsconfig,
+    "test-cases/example.ts": testCase,
+    [`${P}/baseImages/node20/index.ts`]: baseImage,
+    [`${P}/codeStates/baseline/index.ts`]: codeState,
+    [`${P}/promptSets/snerk/index.ts`]: promptSet,
+    [`${P}/harnessModels/claude-code/index.ts`]: harnessIndex,
+    [`${P}/harnessModels/claude-code/models.ts`]: harnessModels,
+    [`${P}/harnessModels/claude-code/versions.ts`]: harnessVersions,
+    [`${P}/harnessModels/claude-code/collectTokenCosts.ts`]: collectTokenCosts,
+    [`${P}/tasks/is-prime/initial-prompts/plain.ts`]: initialPrompt,
+    [`${P}/tasks/is-prime/measurements/isPrimeTsExists.ts`]: measurement,
+  };
+}
+
+export interface InitResult {
+  created: string[];
+  skipped: string[];
+}
+
+/**
+ * Scaffolds `<projectRoot>/.thunderjar/`. Existing files are never overwritten.
+ * A nested package.json is created only when the project has no root one.
+ */
+export async function init(projectRoot: string): Promise<InitResult> {
+  const root = join(projectRoot, ".thunderjar");
+  const nested = !existsSync(join(projectRoot, "package.json"));
+
+  const files = scaffold();
+  if (nested) {
+    files["package.json"] =
+      JSON.stringify(
+        { name: "thunderjar-config", private: true, type: "module", dependencies: { thunderjar: "latest" } },
+        null,
+        2,
+      ) + "\n";
+  }
+  files[".gitignore"] = ["_generated/", ".data/", ...(nested ? ["node_modules/"] : [])].join("\n") + "\n";
+
+  const result: InitResult = { created: [], skipped: [] };
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(root, rel);
+    if (existsSync(path)) {
+      result.skipped.push(rel);
+      continue;
+    }
+    await Bun.write(path, content);
+    result.created.push(rel);
+  }
+  return result;
+}
+
+export function createInitCommand(): Command {
+  return new Command("init").description("Create .thunderjar/ in this project.").action(async () => {
+    const { created, skipped } = await init(process.cwd());
+    for (const f of created) console.log(`created  .thunderjar/${f}`);
+    for (const f of skipped) console.log(`exists   .thunderjar/${f}`);
+  });
+}

package/src/cli/commands/options.ts

@@ -0,0 +1,17 @@
+// Options several commands share.
+
+import { InvalidArgumentError, Option } from "commander";
+
+/** An option that takes a value, may be given only once, and whose value isn't another flag. */
+function valueOption(flags: string, description: string): Option {
+  return new Option(flags, description).argParser((value: string, previous: string | undefined) => {
+    if (previous !== undefined) throw new InvalidArgumentError("It may only be given once.");
+    if (value.startsWith("-")) throw new InvalidArgumentError("It needs a value, not another flag.");
+    return value;
+  });
+}
+
+export const imagePrefixOption = (description: string) => valueOption("--image-prefix <name>", description);
+
+export const dataDirOption = () =>
+  valueOption("--data-dir <dir>", "keep the run data store in this folder, in place of .thunderjar/.data/");

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

@@ -0,0 +1,168 @@
+// `thunderjar plan`, through the CLI, in the checked-in fixtureTests/ scenarios, in place. Each
+// asserts on stdout, against the recording fake Docker, which says which prerun images exist. Any
+// of these can be run by hand:
+//
+//   bun run fixture scenario_2 plan is-prime-baseline
+
+import { describe, expect, test } from "bun:test";
+import { fakeDocker, scenario, thunderjar } from "../../../testing/cli.ts";
+
+const prerunTags = (stdout: string) => stdout.match(/prerun-h[0-9a-f]{8}/g);
+
+describe("scenario_1_minimal_initial_setup", () => {
+  const fixtures = scenario("scenario_1_minimal_initial_setup");
+
+  test("plan example: a 1/1/1/1/1 test case has one permutation", async () => {
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "example"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`baseImage:     node20 (26d9745f)
+codeState:     baseline (bb1584cd)
+promptSet:     snerk (827aa0ce)
+harnessModel:  fake-harness-alpha@1.0.0/fake-model-small (da287975)
+task:          is-prime
+initialPrompt: plain (9e30b385)
+
+Matrix shape: 1/1/1/1/1 (1 permutation × 1 iteration = 1 container run)
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    prerun-h8ffdda6e (will build)
+`);
+  });
+});
+
+describe("scenario_2_typical_project", () => {
+  const fixtures = scenario("scenario_2_typical_project");
+
+  // spec/100-cli-reference.md#plan, with the scenario's real hashes. The scenario is deterministic,
+  // so these are exact: a changed hash is a change to execution identity, a tripwire to investigate
+  // rather than loosen (spec/120-test-boundaries.md). Regenerate them deliberately, in the change
+  // that alters the scenario or the hashing.
+  const IS_PRIME_BASELINE = `baseImage:     node20 (26d9745f)
+codeState:     baseline (bb1584cd)
+promptSet:     snerk (827aa0ce), glurk (a4ecb061)
+harnessModel:  fake-harness-alpha@1.0.0/fake-model-small (da287975), fake-harness-beta@1.0.0/fake-model-large (832747bd)
+task:          is-prime
+initialPrompt: plain (9e30b385), terse (7bb8874f)
+
+Matrix shape: 1/1/2/2/2 (8 permutations × 5 iterations = 40 container runs)
+
+ 1  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    prerun-h8ffdda6e (will build)
+
+ 2  node20 | baseline | snerk | fake-harness-alpha@1.0.0/fake-model-small | terse
+    prerun-hefe85dda (will build)
+
+ 3  node20 | baseline | snerk | fake-harness-beta@1.0.0/fake-model-large  | plain
+    prerun-h8baa2cff (will build)
+
+ 4  node20 | baseline | snerk | fake-harness-beta@1.0.0/fake-model-large  | terse
+    prerun-h56ea4852 (will build)
+
+ 5  node20 | baseline | glurk | fake-harness-alpha@1.0.0/fake-model-small | plain
+    prerun-hfaa55eaf (will build)
+
+ 6  node20 | baseline | glurk | fake-harness-alpha@1.0.0/fake-model-small | terse
+    prerun-h3e2038b8 (will build)
+
+ 7  node20 | baseline | glurk | fake-harness-beta@1.0.0/fake-model-large  | plain
+    prerun-h09fa95b9 (will build)
+
+ 8  node20 | baseline | glurk | fake-harness-beta@1.0.0/fake-model-large  | terse
+    prerun-he7379c79 (will build)`;
+
+  test("plan is-prime-baseline prints the parameters with their hashes, and each permutation's prerun image", async () => {
+    const docker = await fakeDocker();
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "is-prime-baseline"], docker.env);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`${IS_PRIME_BASELINE}\n`);
+  });
+
+  test("plan glurk-on-node-lts: a renamed parameter keeps its hash; one whose file differs doesn't", async () => {
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "glurk-on-node-lts"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    // node-lts is node20 under another name, so it has node20's hash, and glurk on it has the same
+    // prerun image as on node20 (entry 8 of is-prime-baseline). glurk-reworded is glurk with its
+    // FAKE_INSTRUCTIONS.md beside the declaration edited, so its hash and prerun image differ.
+    expect(stdout).toContain("baseImage:     node-lts (26d9745f)\n");
+    expect(stdout).toContain("promptSet:     glurk (a4ecb061), glurk-reworded (88256825)\n");
+    expect(prerunTags(stdout)).toEqual(["prerun-he7379c79", "prerun-h2960067a"]);
+    expect(prerunTags(IS_PRIME_BASELINE)).not.toContain("prerun-h2960067a");
+  });
+
+  test("plan with an unknown test case says so", async () => {
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "no-such-test-case"]);
+
+    expect(stdout).toBe("");
+    expect(stderr).toBe(
+      `error: no test case named "no-such-test-case" (expected ${fixtures}/.thunderjar/test-cases/no-such-test-case.ts)\n`,
+    );
+    expect(exitCode).toBe(1);
+  });
+
+  test("a prerun image that already exists is shown as reused; the rest as built", async () => {
+    const docker = await fakeDocker(["thunderjar:prerun-h8ffdda6e", "thunderjar:prerun-he7379c79"]);
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "is-prime-baseline"], docker.env);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout.split("\n").filter((line) => line.includes("prerun-h"))).toEqual([
+      "    prerun-h8ffdda6e (exists, reused)",
+      "    prerun-hefe85dda (will build)",
+      "    prerun-h8baa2cff (will build)",
+      "    prerun-h56ea4852 (will build)",
+      "    prerun-hfaa55eaf (will build)",
+      "    prerun-h3e2038b8 (will build)",
+      "    prerun-h09fa95b9 (will build)",
+      "    prerun-he7379c79 (exists, reused)",
+    ]);
+  });
+
+  test("without Docker, plan still prints, and says whether images exist is unknown", async () => {
+    const docker = await fakeDocker([], ["unreachable"]);
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "is-prime-baseline"], docker.env);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(
+      `${IS_PRIME_BASELINE.replaceAll(" (will build)", "")}\n\n` +
+        "Docker can't be reached (Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?), so whether each prerun image exists is unknown.\n",
+    );
+  });
+
+  test("plan --image-prefix looks up each prerun image under the prefix", async () => {
+    const docker = await fakeDocker(["throwaway:prerun-hefe85dda", "thunderjar:prerun-h56ea4852"]);
+
+    const { stdout, stderr, exitCode } = await thunderjar(fixtures, ["plan", "two-pairs", "--image-prefix", "throwaway"], docker.env);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    // Only the image under the prefix counts; the one under the default prefix doesn't.
+    expect(stdout).toContain("    prerun-hefe85dda (exists, reused)\n");
+    expect(stdout).toContain("    prerun-h56ea4852 (will build)\n");
+    expect(docker.commands()).toEqual([
+      "docker version --format {{.Server.Version}}",
+      "docker image inspect --format {{.Id}} throwaway:prerun-hefe85dda",
+      "docker image inspect --format {{.Id}} throwaway:prerun-h56ea4852",
+    ]);
+  });
+
+  test("plan with no test case, --image-prefix without a name, or an extra argument, says what's wrong, then its usage", async () => {
+    for (const [args, error] of [
+      [["plan"], "error: missing required argument 'test case'"],
+      [["plan", "two-pairs", "--image-prefix"], "error: option '--image-prefix <name>' argument missing"],
+      [["plan", "two-pairs", "extra"], "error: too many arguments for 'plan'"],
+    ] as const) {
+      const { stdout, stderr, exitCode } = await thunderjar(fixtures, [...args]);
+      expect(stdout).toBe("");
+      expect(stderr).toStartWith(error);
+      expect(stderr).toContain("Usage: thunderjar plan [options] <test case>");
+      expect(exitCode).toBe(1);
+    }
+  });
+});

package/src/cli/commands/plan/plan.ts

@@ -0,0 +1,72 @@
+// `thunderjar plan <test case>` — spec/100-cli-reference.md#plan,
+// spec/055-declaring-test-cases.md#declaration. Lists the parameters a test case names with
+// their parameter hashes, then its matrix shape, container run count, and each permutation
+// with its prerun image and whether that image exists (and would be reused) or would be built.
+// Without Docker, plan still works, and says the images' status is unknown.
+
+import { Command } from "commander";
+import { dockerCli, type Docker } from "../../../adapters/docker/docker.ts";
+import { findThunderjarRoot, loadTestCase } from "../../../project/config.ts";
+import { abbreviateHash } from "../../../matrix/hashing.ts";
+import { matrixShape, permutationRows } from "../../../matrix/permutations.ts";
+import { LOCAL_REPOSITORY, prerunStatuses, showPrerunStatus, unreachableNote } from "../../../images/prerun.ts";
+import { resolveTestCase } from "../../../matrix/resolve.ts";
+import { prerunTag } from "../../../matrix/tags.ts";
+import { count } from "../format.ts";
+import { imagePrefixOption } from "../options.ts";
+
+export interface PlanOptions {
+  docker?: Docker;
+  /** The image repository prerun images are looked up in, `--image-prefix`. */
+  repository?: string;
+}
+
+/** The parameter lines, in declaration field order. `task` has no hash of its own. */
+const LABELS = ["baseImage", "codeState", "promptSet", "harnessModel", "task", "initialPrompt"] as const;
+
+const LABEL_WIDTH = Math.max(...LABELS.map((label) => label.length)) + 2; // + ":" + one space
+
+export async function plan(name: string, cwd: string = process.cwd(), options: PlanOptions = {}): Promise<string> {
+  const { docker = dockerCli(), repository = LOCAL_REPOSITORY } = options;
+  const root = findThunderjarRoot(cwd);
+  const testCase = await loadTestCase(root, name);
+  const { hashes, permutations } = await resolveTestCase(root, testCase);
+  const found = await prerunStatuses(docker, repository, permutations);
+  const status = (hash: string) => ("statuses" in found ? showPrerunStatus(found.statuses.get(hash)) : "");
+
+  const parameterLines = LABELS.map((label) => {
+    const value =
+      label === "task"
+        ? testCase.task
+        : testCase[label].map((n) => `${n} (${abbreviateHash(hashes[label].get(n)!)})`).join(", ");
+    return `${(label + ":").padEnd(LABEL_WIDTH)}${value}`;
+  });
+
+  const runs = permutations.length * testCase.iterations;
+  const summary =
+    `Matrix shape: ${matrixShape(testCase).join("/")} ` +
+    `(${count(permutations.length, "permutation")} × ${count(testCase.iterations, "iteration")} = ${count(runs, "container run")})`;
+
+  // Each permutation: a right-aligned number, then the five names as columns; below, its
+  // prerun image, which carries the permutation hash.
+  const rows = permutationRows(permutations);
+  const numberWidth = Math.max(2, String(permutations.length).length);
+  const entries = permutations.map(
+    (permutation, n) =>
+      `${String(n + 1).padStart(numberWidth)}  ${rows[n]}\n` +
+      `${" ".repeat(numberWidth + 2)}${prerunTag(permutation.hash)}${status(permutation.hash)}`,
+  );
+
+  const note = "unreachable" in found ? ["", unreachableNote(found.unreachable)] : [];
+  return [...parameterLines, "", summary, "", entries.join("\n\n"), ...note].join("\n");
+}
+
+export function createPlanCommand(): Command {
+  return new Command("plan")
+    .description("Print what a run of a test case would do.")
+    .argument("<test case>", "the test case to plan")
+    .addOption(imagePrefixOption("the image repository prerun images are looked up in"))
+    .action(async (name: string, options: { imagePrefix?: string }) => {
+      console.log(await plan(name, process.cwd(), { repository: options.imagePrefix }));
+    });
+}