thunderjar 0.1.2 → 0.1.3-preview-eee7160

package/src/cli/commands/declarations.typecheck.test.ts

@@ -0,0 +1,173 @@
+// spec/055-declaring-test-cases.md#typed-names: a declaration naming a parameter absent from the
+// generated types, or whose config or aggregate doesn't fit its instrument, is a compile error,
+// and one that fits compiles cleanly.
+//
+// In the checked-in fixtureTests/scenario_11_type_errors, in place: `thunderjar generate` writes
+// its gitignored types, then real `tsc` checks the project with its own tsconfig, once. Each test
+// asserts on what `tsc` reported for one declaration. By hand:
+//
+//   bun run fixture 11 generate
+//   cd fixtureTests/scenario_11_type_errors/fixtures && bunx tsc -p .thunderjar
+
+import { beforeAll, describe, expect, test } from "bun:test";
+import { join, resolve } from "../../platform/path.ts";
+import { scenario, thunderjar } from "../../testing/cli.ts";
+
+const tsc = resolve(import.meta.dir, "..", "..", "..", "node_modules", ".bin", "tsc");
+const fixtures = scenario("scenario_11_type_errors");
+
+let exitCode: number;
+/** Each diagnostic `tsc` printed, with its indented elaboration, keyed by its file. */
+const reported = new Map<string, string[]>();
+
+beforeAll(async () => {
+  const generated = await thunderjar(fixtures, ["generate"]);
+  expect(generated.exitCode).toBe(0);
+
+  const proc = Bun.spawn([tsc, "--noEmit", "-p", join(fixtures, ".thunderjar")], {
+    cwd: fixtures,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([proc.stdout.text(), proc.stderr.text()]);
+  exitCode = await proc.exited;
+  for (const diagnostic of (stdout + stderr).trimEnd().split(/\n(?=\S)/)) {
+    const file = diagnostic.slice(0, diagnostic.indexOf("("));
+    reported.set(file, [...(reported.get(file) ?? []), diagnostic.slice(file.length)]);
+  }
+}, 30000);
+
+/** What `tsc` reported in `.thunderjar/<file>`, each diagnostic without its file name. */
+const errorsIn = (file: string) => reported.get(`.thunderjar/${file}`);
+
+test("only the declarations that don't fit fail to compile", () => {
+  expect(exitCode).not.toBe(0);
+  expect([...reported.keys()].sort()).toEqual(
+    [
+      "test-cases/prompt-of-another-task.ts",
+      "test-cases/unknown-model.ts",
+      "test-cases/unknown-prompt-set.ts",
+      "test-case-parameters/codeStates/reads-missing-config/index.ts",
+      "test-case-parameters/codeStates/top-level-commit/index.ts",
+      ...[
+        "fileCreatedByMean",
+        "grepByRate",
+        "grepWithoutPattern",
+        "misfitConfig",
+        "templateTestByMax",
+        "templateTestWithoutTemplate",
+        "unknownInstrument",
+        "withoutAggregate",
+      ].map((name) => `test-case-parameters/tasks/badly-measured/measurements/${name}.ts`),
+    ]
+      .map((file) => `.thunderjar/${file}`)
+      .sort(),
+  );
+});
+
+describe("a test case", () => {
+  test("naming only generated names compiles cleanly", () => {
+    expect(errorsIn("test-cases/sound.ts")).toBeUndefined();
+  });
+
+  test("naming an unknown prompt set fails to compile", () => {
+    expect(errorsIn("test-cases/unknown-prompt-set.ts")).toEqual([
+      `(6,15): error TS2322: Type '"snirk"' is not assignable to type '"snerk"'.`,
+    ]);
+  });
+
+  test("naming a model absent from its family fails to compile", () => {
+    expect(errorsIn("test-cases/unknown-model.ts")).toEqual([
+      `(7,18): error TS2322: Type '"fake-harness-alpha@1.0.0/fake-model-huge"' is not assignable to type '"fake-harness-alpha@1.0.0/fake-model-small"'.`,
+    ]);
+  });
+
+  test("naming an initial prompt that belongs to a different task fails to compile", () => {
+    expect(errorsIn("test-cases/prompt-of-another-task.ts")).toEqual([
+      `(9,19): error TS2322: Type '"fizzy"' is not assignable to type '"plain"'.`,
+    ]);
+  });
+});
+
+describe("a measurement", () => {
+  const measurement = (task: string, name: string) => errorsIn(`test-case-parameters/tasks/${task}/measurements/${name}.ts`);
+  const bad = (name: string) => measurement("badly-measured", name);
+
+  test("whose config and aggregate fit fileCreated, grep or templateTest compiles cleanly", () => {
+    expect(measurement("is-prime", "isPrimeTsExists")).toBeUndefined();
+    expect(measurement("is-prime", "tsIgnoreCount")).toBeUndefined();
+    expect(measurement("is-prime", "isPrimeTemplateTest")).toBeUndefined();
+  });
+
+  test("whose config doesn't fit its instrument fails to compile", () => {
+    expect(bad("misfitConfig")).toEqual([
+      `(3,74): error TS2353: Object literal may only specify known properties, and 'path' does not exist in type '{ glob: string; } | { glob: string; pattern: string; } | { subject: string; template: string; }'.`,
+    ]);
+  });
+
+  test("naming an unknown instrument fails to compile", () => {
+    expect(bad("unknownInstrument")).toEqual([
+      `(3,37): error TS2820: Type '"fileCraeted"' is not assignable to type '"fileCreated" | "grep" | "templateTest"'. Did you mean '"fileCreated"'?`,
+    ]);
+  });
+
+  test("without an aggregate fails to compile", () => {
+    expect(bad("withoutAggregate")).toEqual([
+      `(3,35): error TS2345: Argument of type '{ instrument: "fileCreated"; config: { glob: string; }; }' is not assignable to parameter of type 'MeasurementDeclaration'.
+  Property 'aggregate' is missing in type '{ instrument: "fileCreated"; config: { glob: string; }; }' but required in type '{ instrument: "fileCreated"; config: { glob: string; }; aggregate: ("count" | "rate")[]; }'.`,
+    ]);
+  });
+
+  test("with an aggregate that doesn't fit its instrument's value type fails to compile", () => {
+    expect(bad("fileCreatedByMean")).toEqual([
+      `(3,35): error TS2345: Argument of type '{ instrument: "fileCreated"; config: { glob: string; }; aggregate: "mean"[]; }' is not assignable to parameter of type 'MeasurementDeclaration'.
+  Types of property 'aggregate' are incompatible.
+    Type '"mean"[]' is not assignable to type '("count" | "rate")[]'.
+      Type '"mean"' is not assignable to type '"count" | "rate"'.`,
+    ]);
+    expect(bad("grepByRate")).toEqual([
+      `(3,35): error TS2345: Argument of type '{ instrument: "grep"; config: { glob: string; pattern: string; }; aggregate: "rate"[]; }' is not assignable to parameter of type 'MeasurementDeclaration'.
+  Types of property 'aggregate' are incompatible.
+    Type '"rate"[]' is not assignable to type '("max" | "mean" | "median" | "min" | "sum")[]'.
+      Type '"rate"' is not assignable to type '"max" | "mean" | "median" | "min" | "sum"'.`,
+    ]);
+    expect(bad("templateTestByMax")).toEqual([
+      `(3,35): error TS2345: Argument of type '{ instrument: "templateTest"; config: { subject: string; template: string; }; aggregate: "max"[]; }' is not assignable to parameter of type 'MeasurementDeclaration'.
+  Types of property 'aggregate' are incompatible.
+    Type '"max"[]' is not assignable to type '("mean" | "sum")[]'.
+      Type '"max"' is not assignable to type '"mean" | "sum"'.`,
+    ]);
+  });
+
+  test("whose config is missing a field fails to compile", () => {
+    expect(bad("grepWithoutPattern")).toEqual([
+      `(3,35): error TS2345: Argument of type '{ instrument: "grep"; config: { glob: string; }; aggregate: "max"[]; }' is not assignable to parameter of type 'MeasurementDeclaration'.
+  Types of property 'config' are incompatible.
+    Property 'pattern' is missing in type '{ glob: string; }' but required in type '{ glob: string; pattern: string; }'.`,
+    ]);
+    expect(bad("templateTestWithoutTemplate")).toEqual([
+      `(3,65): error TS2322: Type '{ subject: string; }' is not assignable to type '{ glob: string; } | { glob: string; pattern: string; } | { subject: string; template: string; }'.
+  Property 'template' is missing in type '{ subject: string; }' but required in type '{ subject: string; template: string; }'.`,
+    ]);
+  });
+});
+
+describe("a code state", () => {
+  const codeState = (name: string) => errorsIn(`test-case-parameters/codeStates/${name}/index.ts`);
+
+  test("whose config reaches its applyParameter typed, and whose checkoutCommit takes its ctx, compiles cleanly", () => {
+    expect(codeState("pinned")).toBeUndefined();
+  });
+
+  test("reading a property its config doesn't have fails to compile", () => {
+    expect(codeState("reads-missing-config")).toEqual([
+      `(5,58): error TS2339: Property 'sha' does not exist on type '{ commit: string; }'.`,
+    ]);
+  });
+
+  test("with the old top-level commit fails to compile: it belongs in config", () => {
+    expect(codeState("top-level-commit")).toEqual([
+      `(4,3): error TS2353: Object literal may only specify known properties, and 'commit' does not exist in type 'CodeStateDeclaration<undefined>'.`,
+    ]);
+  });
+});

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

@@ -0,0 +1,84 @@
+// `thunderjar executions`, through the CLI, in the checked-in fixtureTests/ scenarios, in place.
+// Scenario 8 starts with a run data store of four executions of two test cases; scenario 5 has
+// none. Each asserts on stdout. Any of these can be run by hand:
+//
+//   bun run fixture 8 executions fails
+
+import { describe, expect, test } from "bun:test";
+import { join } from "../../../platform/path.ts";
+import { scenario, thunderjar } from "../../../testing/cli.ts";
+
+describe("scenario_5_empty_parameter_folders", () => {
+  const fixtures = scenario("scenario_5_empty_parameter_folders");
+
+  test("lists nothing before anything has run", async () => {
+    expect(await thunderjar(fixtures, ["executions"])).toEqual({
+      stdout: "No executions recorded.\n",
+      stderr: "",
+      exitCode: 0,
+    });
+    expect(await thunderjar(fixtures, ["executions", "fails"])).toEqual({
+      stdout: "No executions recorded for fails.\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("--data-dir lists the executions in a store kept elsewhere", async () => {
+    const dataDir = join(scenario("scenario_8_recorded_executions"), ".thunderjar", ".data");
+    expect(await thunderjar(fixtures, ["executions", "times-out", "--data-dir", dataDir])).toEqual({
+      stdout: "01k4xb7q0c2tnvabcdefghjkmn  times-out  2026-09-29 15:02\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+});
+
+describe("scenario_8_recorded_executions", () => {
+  const fixtures = scenario("scenario_8_recorded_executions");
+
+  test("executions: every test case's executions, newest first", async () => {
+    expect(await thunderjar(fixtures, ["executions"])).toEqual({
+      stdout: `01k4xc0000000000000000000a  fails      2026-09-30 08:00
+01k4xb7q0c2tnvabcdefghjkmn  times-out  2026-09-29 15:02
+01k4x9j2e8mqz3abcdefghjkmn  fails      2026-09-29 14:30
+01k4tq3h8r0000000000000000  fails      2026-09-28 09:15
+`,
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("executions <test case>: only that test case's, newest first", async () => {
+    expect(await thunderjar(fixtures, ["executions", "fails"])).toEqual({
+      stdout: `01k4xc0000000000000000000a  fails  2026-09-30 08:00
+01k4x9j2e8mqz3abcdefghjkmn  fails  2026-09-29 14:30
+01k4tq3h8r0000000000000000  fails  2026-09-28 09:15
+`,
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("executions <test case> with nothing recorded says so", async () => {
+    expect(await thunderjar(fixtures, ["executions", "nope"])).toEqual({
+      stdout: "No executions recorded for nope.\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("says what's wrong, then its usage, for extra arguments or a flag", async () => {
+    for (const [args, error] of [
+      [["executions", "a", "b"], "error: too many arguments for 'executions'"],
+      [["executions", "--json"], "error: unknown option '--json'"],
+      [["executions", "--data-dir"], "error: option '--data-dir <dir>' argument missing"],
+    ] as const) {
+      const { stdout, stderr, exitCode } = await thunderjar(fixtures, [...args]);
+      expect(stdout).toBe("");
+      expect(stderr).toStartWith(error);
+      expect(stderr).toContain("Usage: thunderjar executions [options] [test case]");
+      expect(exitCode).toBe(1);
+    }
+  });
+});

package/src/cli/commands/executions/executions.ts

@@ -0,0 +1,31 @@
+// `thunderjar executions [<test case>]` — spec/100-cli-reference.md#executions. Lists the test
+// case executions in the run data store, newest first: execution ID, test case, and when it
+// started, in UTC to the minute. `--data-dir` reads a store kept outside the project.
+
+import { Command } from "commander";
+import { jsonFileStore, runDataStorePath } from "../../../store/run-data-store.ts";
+import { minute } from "../format.ts";
+import { dataDirOption } from "../options.ts";
+
+export async function executions(
+  testCase?: string,
+  { cwd = process.cwd(), dataDir }: { cwd?: string; dataDir?: string } = {},
+): Promise<string> {
+  const store = jsonFileStore(runDataStorePath(cwd, dataDir));
+  const listed = await store.listExecutions(testCase);
+  if (listed.length === 0) {
+    return testCase === undefined ? "No executions recorded." : `No executions recorded for ${testCase}.`;
+  }
+  const width = Math.max(...listed.map((e) => e.testCase.length));
+  return listed.map((e) => `${e.executionId}  ${e.testCase.padEnd(width)}  ${minute(e.ranAt)}`).join("\n");
+}
+
+export function createExecutionsCommand(): Command {
+  return new Command("executions")
+    .description("List recorded executions.")
+    .argument("[test case]", "list only this test case's executions")
+    .addOption(dataDirOption())
+    .action(async (testCase: string | undefined, options: { dataDir?: string }) => {
+      console.log(await executions(testCase, { dataDir: options.dataDir }));
+    });
+}

package/src/cli/commands/format.ts

@@ -0,0 +1,33 @@
+// How commands print things they share: counts, durations, measured values, times. A command
+// never imports another command; what two of them print alike lives here.
+
+import type { RecordedOutcome } from "../../store/run-data-store.ts";
+
+/** `1 permutation`, `2 permutations`. */
+export const count = (n: number, noun: string) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
+/** A measured value as `run` prints it: JSON, but with an object's keys unquoted, `{passed: 4, failed: 1}`. */
+export const showValue = (value: unknown): string =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? `{${Object.entries(value)
+        .map(([key, v]) => `${key}: ${showValue(v)}`)
+        .join(", ")}}`
+    : (JSON.stringify(value) ?? String(value));
+
+/** A measure as `run` and `remeasure` print it: its value, or what kept it from having one. */
+export const showOutcome = (outcome: RecordedOutcome) =>
+  outcome.outcome === "measured"
+    ? showValue(outcome.data)
+    : outcome.outcome === "skipped"
+      ? "skipped"
+      : `erroredWhileMeasuring: ${outcome.error.message}`;
+
+/** Milliseconds as a duration: `0.04s`. */
+export const seconds = (ms: number) => `${(ms / 1000).toFixed(2)}s`;
+
+/** How long a container run took: `0.04s`. */
+export const duration = ({ startedAt, finishedAt }: { startedAt: number; finishedAt: number }) =>
+  seconds(finishedAt - startedAt);
+
+/** `2026-09-29 14:30`, from an ISO timestamp. */
+export const minute = (iso: string) => iso.slice(0, 16).replace("T", " ");

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

@@ -0,0 +1,101 @@
+// `thunderjar generate`, through the CLI, in the checked-in fixtureTests/ scenarios, in place. It
+// writes only the gitignored `.thunderjar/_generated/parameter-names.d.ts`, so each test deletes
+// that file first, then asserts on what was written. Any of these can be run by hand:
+//
+//   bun run fixture scenario_2 generate
+
+import { describe, expect, test } from "bun:test";
+import { remove } from "../../../platform/fs.ts";
+import { join } from "../../../platform/path.ts";
+import { scenario, thunderjar } from "../../../testing/cli.ts";
+
+/** Runs `generate` in `fixtures` with no earlier output left, returning its output and the file. */
+async function generateIn(fixtures: string) {
+  const path = join(fixtures, ".thunderjar", "_generated", "parameter-names.d.ts");
+  await remove(path);
+  const result = await thunderjar(fixtures, ["generate"]);
+  return { ...result, path, content: await Bun.file(path).text() };
+}
+
+describe("scenario_1_minimal_initial_setup", () => {
+  const fixtures = scenario("scenario_1_minimal_initial_setup");
+
+  test("generate: one of everything", async () => {
+    const { stdout, stderr, exitCode, path, content } = await generateIn(fixtures);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`generated ${path}\n`);
+    expect(content).toBe(`// _generated/parameter-names.d.ts — generated by \`thunderjar generate\`, not edited
+
+type BaseImageName = "node20";
+type CodeStateName = "baseline";
+type PromptSetName = "snerk";
+type TaskName = "is-prime";
+type InitialPromptNames = {
+  "is-prime": "plain";
+};
+type HarnessModelName = \`fake-harness-alpha@\${"1.0.0"}/\${"fake-model-small"}\`;
+`);
+  });
+});
+
+describe("scenario_2_typical_project", () => {
+  const fixtures = scenario("scenario_2_typical_project");
+
+  test("generate: sorted unions of every name, and a harness model pair per family", async () => {
+    const { stdout, stderr, exitCode, path, content } = await generateIn(fixtures);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`generated ${path}\n`);
+    expect(content).toBe(`// _generated/parameter-names.d.ts — generated by \`thunderjar generate\`, not edited
+
+type BaseImageName = "node-lts" | "node20";
+type CodeStateName = "baseline";
+type PromptSetName = "glurk" | "glurk-reworded" | "snerk";
+type TaskName = "is-prime" | "no-measures";
+type InitialPromptNames = {
+  "is-prime": "plain" | "terse";
+  "no-measures": "plain";
+};
+type HarnessModelName =
+  | \`fake-harness-alpha@\${"1.0.0" | "1.1.0"}/\${"fake-model-large" | "fake-model-small"}\`
+  | \`fake-harness-beta@\${"1.0.0"}/\${"fake-model-large" | "fake-model-small"}\`;
+`);
+  });
+
+  test("generate: from a folder below the project, writes into the project's .thunderjar/", async () => {
+    const below = join(fixtures, ".thunderjar", "test-cases");
+    const path = join(fixtures, ".thunderjar", "_generated", "parameter-names.d.ts");
+    await remove(path);
+
+    const { stdout, stderr, exitCode } = await thunderjar(below, ["generate"]);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`generated ${path}\n`);
+    expect(await Bun.file(path).text()).toContain('type CodeStateName = "baseline";');
+  });
+});
+
+describe("scenario_5_empty_parameter_folders", () => {
+  const fixtures = scenario("scenario_5_empty_parameter_folders");
+
+  test("generate: empty parameter folders render as never", async () => {
+    const { stdout, stderr, exitCode, path, content } = await generateIn(fixtures);
+
+    expect(stderr).toBe("");
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe(`generated ${path}\n`);
+    expect(content).toBe(`// _generated/parameter-names.d.ts — generated by \`thunderjar generate\`, not edited
+
+type BaseImageName = never;
+type CodeStateName = never;
+type PromptSetName = never;
+type TaskName = never;
+type InitialPromptNames = Record<string, never>;
+type HarnessModelName = never;
+`);
+  });
+});

package/src/cli/commands/generate/generate.ts

@@ -0,0 +1,18 @@
+// `thunderjar generate` — spec/100-cli-reference.md#generate.
+
+import { Command } from "commander";
+import { findThunderjarRoot } from "../../../project/config.ts";
+import { writeGeneratedTypes } from "./parameter-names.ts";
+
+export async function generate(cwd: string = process.cwd()): Promise<{ path: string }> {
+  const root = findThunderjarRoot(cwd);
+  const { path } = await writeGeneratedTypes(root);
+  return { path };
+}
+
+export function createGenerateCommand(): Command {
+  return new Command("generate").description("Write the parameter-name types for this project.").action(async () => {
+    const { path } = await generate();
+    console.log(`generated ${path}`);
+  });
+}

package/src/cli/commands/generate/parameter-names.ts

@@ -0,0 +1,131 @@
+// Reads parameter names and harness family version/model maps under
+// `test-case-parameters/` and renders `_generated/parameter-names.d.ts` —
+// spec/055-declaring-test-cases.md#typed-names.
+
+import { listEntries } from "../../../platform/fs.ts";
+import { join } from "../../../platform/path.ts";
+import { InvalidConfigError, loadDeclaration, type Problem } from "../../../project/config.ts";
+
+interface HarnessFamilyNames {
+  versions: string[];
+  models: string[];
+}
+
+export interface ParameterNames {
+  baseImages: string[];
+  codeStates: string[];
+  promptSets: string[];
+  tasks: Record<string, string[]>; // task name -> initial prompt names
+  harnessFamilies: Record<string, HarnessFamilyNames>;
+}
+
+async function listDirNames(dir: string): Promise<string[]> {
+  try {
+    return listEntries(dir)
+      .filter((entry) => entry.isDirectory)
+      .map((entry) => entry.path)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+async function listFileStems(dir: string): Promise<string[]> {
+  try {
+    return listEntries(dir)
+      .filter((entry) => !entry.isDirectory && entry.path.endsWith(".ts"))
+      .map((entry) => entry.path.slice(0, -".ts".length))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+async function loadFamilyNames(root: string, family: string, problems: Problem[]): Promise<HarnessFamilyNames> {
+  const familyDir = `test-case-parameters/harnessModels/${family}`;
+  const models = await loadDeclaration(root, `${familyDir}/models.ts`, "declareHarnessModels", problems);
+  const versions = await loadDeclaration(root, `${familyDir}/versions.ts`, "declareHarnessVersions", problems);
+  return {
+    models: Object.keys(models ?? {}).sort(),
+    versions: Object.keys(versions ?? {}).sort(),
+  };
+}
+
+/** Scans a `.thunderjar/` root's `test-case-parameters/` folder for declared names. */
+export async function collectParameterNames(root: string): Promise<ParameterNames> {
+  const parameters = join(root, "test-case-parameters");
+
+  const [baseImages, codeStates, promptSets, taskNames, familyNames] = await Promise.all([
+    listDirNames(join(parameters, "baseImages")),
+    listDirNames(join(parameters, "codeStates")),
+    listDirNames(join(parameters, "promptSets")),
+    listDirNames(join(parameters, "tasks")),
+    listDirNames(join(parameters, "harnessModels")),
+  ]);
+
+  const tasks: Record<string, string[]> = {};
+  for (const task of taskNames) {
+    tasks[task] = await listFileStems(join(parameters, "tasks", task, "initial-prompts"));
+  }
+
+  const harnessFamilies: Record<string, HarnessFamilyNames> = {};
+  const problems: Problem[] = [];
+  for (const family of familyNames) {
+    harnessFamilies[family] = await loadFamilyNames(root, family, problems);
+  }
+  if (problems.length > 0) throw new InvalidConfigError(problems);
+
+  return { baseImages, codeStates, promptSets, tasks, harnessFamilies };
+}
+
+function literalUnion(names: string[]): string {
+  return names.length === 0 ? "never" : names.map((name) => JSON.stringify(name)).join(" | ");
+}
+
+/** Renders `_generated/parameter-names.d.ts`'s contents from scanned names. */
+export function renderParameterNames(names: ParameterNames): string {
+  const lines = [
+    "// _generated/parameter-names.d.ts — generated by `thunderjar generate`, not edited",
+    "",
+    `type BaseImageName = ${literalUnion(names.baseImages)};`,
+    `type CodeStateName = ${literalUnion(names.codeStates)};`,
+    `type PromptSetName = ${literalUnion(names.promptSets)};`,
+    `type TaskName = ${literalUnion(Object.keys(names.tasks))};`,
+  ];
+
+  const tasks = Object.entries(names.tasks);
+  if (tasks.length === 0) {
+    lines.push("type InitialPromptNames = Record<string, never>;");
+  } else {
+    lines.push("type InitialPromptNames = {");
+    for (const [task, prompts] of tasks) {
+      lines.push(`  ${JSON.stringify(task)}: ${literalUnion(prompts)};`);
+    }
+    lines.push("};");
+  }
+
+  const pairs = Object.entries(names.harnessFamilies)
+    .filter(([, { versions, models }]) => versions.length > 0 && models.length > 0)
+    .map(([family, { versions, models }]) => "`" + family + "@${" + literalUnion(versions) + "}/${" + literalUnion(models) + "}`");
+  if (pairs.length === 0) {
+    lines.push("type HarnessModelName = never;");
+  } else if (pairs.length === 1) {
+    lines.push(`type HarnessModelName = ${pairs[0]};`);
+  } else {
+    lines.push("type HarnessModelName =");
+    lines.push(...pairs.map((pair) => `  | ${pair}`));
+    lines[lines.length - 1] += ";";
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+/** Scans `root` and writes `_generated/parameter-names.d.ts`, returning its path. */
+export async function writeGeneratedTypes(root: string): Promise<{ path: string; content: string }> {
+  const names = await collectParameterNames(root);
+  const content = renderParameterNames(names);
+  const path = join(root, "_generated", "parameter-names.d.ts");
+  await Bun.write(path, content);
+  return { path, content };
+}