@pithy-sh/cli 0.1.0

package/src/seed/safety.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { SeedSet } from "@pithy-sh/core/src/seed/seed";
+
+/**
+ * The layered env-safety model for `pithy seed`. Two gates stand between a fixture and a write:
+ *
+ *  1. **Allowlist** — a set is seeded into an environment only if its `environments` lists it. Core's
+ *     `composeSeeds` already filters on this; {@link assertSetAllowedForEnv} re-asserts it per set at
+ *     write time, so a set can never reach a disallowed environment even if the plan is bypassed.
+ *  2. **Escalating confirmation** — `dev` runs freely; `staging` and `production` require `--yes`; and
+ *     `production` additionally requires a hard, exact type-to-confirm phrase. {@link assertSeedConfirmed}
+ *     is the gate.
+ *
+ * `production` is never seeded by accident: the allowlist keeps a set out unless it opts in, and the
+ * confirm phrase keeps a run from starting unless a human (or an explicit CI flag) types the exact words.
+ */
+
+/** The exact phrase that unlocks a production seed. Compared case-insensitively after trimming. */
+export const PRODUCTION_CONFIRM_PHRASE = "yes, i really want to seed production";
+
+/**
+ * The built-in env names that trigger the strongest gate — the hard type-to-confirm phrase — not just
+ * the literal `"production"`. Recognized case-insensitively after trimming, so `prod` and `Production`
+ * cannot slip past the phrase with only `--yes`. A project extends this with `seed.productionEnvironments`
+ * in `pithy.config.ts` (see {@link isProductionEnv}), so a prod env named `live`/`prod-eu`/`main` is gated
+ * identically. Any env classified as production by neither is still guarded by `--yes`.
+ */
+const PRODUCTION_ENV_NAMES = new Set(["production", "prod"]);
+
+/**
+ * Whether `env` names a production environment (case-insensitive), and so needs the hard confirm phrase.
+ * `productionEnvironments` are the extra names the project declared in `pithy.config.ts`
+ * (`seed.productionEnvironments`), unioned with the built-in `production`/`prod` — the fix for a prod
+ * environment whose name is neither canonical value silently dropping to the weaker `--yes`-only gate.
+ */
+export function isProductionEnv(env: string, productionEnvironments: readonly string[] = []): boolean {
+  const normalized = env.trim().toLowerCase();
+  if (PRODUCTION_ENV_NAMES.has(normalized)) return true;
+  return productionEnvironments.some((name) => name.trim().toLowerCase() === normalized);
+}
+
+/**
+ * Re-assert the env allowlist for one set (safety layer 1). Throws if `env` is not among the set's
+ * declared `environments` — the write-time guard behind "seed refuses to write a set into a disallowed
+ * env". Compose already filters disallowed sets out; this makes the invariant impossible to bypass.
+ */
+export function assertSetAllowedForEnv(set: SeedSet, env: string): void {
+  if (!set.environments.includes(env)) {
+    throw new ValidationError({
+      message: `Seed set "${set.name}" is not allowed in ${env}.`,
+      action: `Add "${env}" to the set's environments, or seed one of: ${set.environments.join(", ")}.`,
+    });
+  }
+}
+
+/** Inputs to the escalating-confirmation gate (safety layer 2). */
+export interface ConfirmSeedOptions {
+  /** The environment being seeded. `dev` is free; `staging`/`production` escalate. */
+  env: string;
+  /** The `--yes` flag. Required for any non-`dev` environment. */
+  yes: boolean;
+  /**
+   * Non-interactive mode (set by `--json`, or any headless/CI invocation). No prompt is ever shown;
+   * production must be unlocked by {@link ConfirmSeedOptions.confirmProduction} instead.
+   */
+  json: boolean;
+  /**
+   * The `--confirm-production` flag value. For production it must equal {@link PRODUCTION_CONFIRM_PHRASE}
+   * (case-insensitive, trimmed). When present it is authoritative — used even in interactive mode, so a
+   * script never has to answer a prompt.
+   */
+  confirmProduction?: string;
+  /**
+   * Interactive confirm seam: prompt the operator for the production phrase and resolve their answer.
+   * Injected by the command (an `@clack/prompts` text prompt); omitted in tests and never called when
+   * {@link ConfirmSeedOptions.json} is set or {@link ConfirmSeedOptions.confirmProduction} is supplied.
+   */
+  prompt?: () => Promise<string>;
+  /**
+   * Extra environment names the project classifies as production (`pithy.config.ts`
+   * `seed.productionEnvironments`), unioned with the built-in `production`/`prod`. An env named here also
+   * requires the hard confirm phrase, so a project whose production environment is named `live`/`prod-eu`
+   * is protected like the canonical names rather than passing on `--yes` alone.
+   */
+  productionEnvironments?: readonly string[];
+}
+
+/** Whether `input`, trimmed and lower-cased, is exactly the production confirm phrase. */
+function phraseMatches(input: string | undefined): boolean {
+  return input !== undefined && input.trim().toLowerCase() === PRODUCTION_CONFIRM_PHRASE;
+}
+
+/**
+ * The exact phrase that unlocks a `--redo` schema reset for an environment. **Environment-specific on
+ * purpose** — a phrase naming `staging` cannot be pasted into a command targeting another environment,
+ * which a single fixed phrase would allow.
+ */
+export function resetConfirmPhrase(env: string): string {
+  return `yes, i really want to reset ${env.trim().toLowerCase()}`;
+}
+
+/** Inputs to the reset gate — the stronger confirmation `--redo` requires. */
+export interface ConfirmResetOptions {
+  /** The environment being reset. `dev` is free; everything else needs the phrase. */
+  env: string;
+  /** Non-interactive mode: no prompt is shown, so the phrase must arrive by flag. */
+  json: boolean;
+  /** The `--confirm-reset` flag value; authoritative wherever present. */
+  confirmReset?: string;
+  /** Interactive confirm seam: prompt the operator for the reset phrase. */
+  prompt?: () => Promise<string>;
+}
+
+/**
+ * Enforce the **reset** gate, which is deliberately stricter than the seed gate.
+ *
+ * `--yes` means "yes, this is not dev" — it was designed to authorize *writing seed rows*, which is
+ * additive and non-destructive. `--redo` drops every table first. Letting one flag authorize both would
+ * mean a script (or a hand) that knew only to pass `--yes` could destroy an environment's entire dataset.
+ * So a reset requires the exact, environment-named phrase for **any** non-`dev` environment — not only
+ * production. `dev` stays free, because a local Miniflare store is the thing reset is for.
+ *
+ * Automation is preserved: CI passes `--confirm-reset` explicitly, so a headless reset still works — it
+ * simply cannot happen by accident.
+ */
+export async function assertResetConfirmed(options: ConfirmResetOptions): Promise<void> {
+  if (options.env === "dev") return;
+
+  const expected = resetConfirmPhrase(options.env);
+  const matches = (input: string | undefined): boolean =>
+    input !== undefined && input.trim().toLowerCase() === expected;
+
+  // The flag is authoritative wherever present (CI or interactive).
+  if (options.confirmReset !== undefined) {
+    if (matches(options.confirmReset)) return;
+    throw new ValidationError({
+      message: `That is not the confirmation phrase for resetting ${options.env}.`,
+      action: `Pass --confirm-reset "${expected}" to drop and recreate the ${options.env} schema.`,
+    });
+  }
+
+  if (!options.json && options.prompt) {
+    if (matches(await options.prompt())) return;
+    throw new ValidationError({
+      message: `Reset of ${options.env} not confirmed.`,
+      action: `Type the exact phrase, or pass --confirm-reset "${expected}".`,
+    });
+  }
+
+  throw new ValidationError({
+    message: `Resetting ${options.env} destroys all of its data.`,
+    action: `Pass --confirm-reset "${expected}" to drop and recreate the ${options.env} schema.`,
+  });
+}
+
+/**
+ * Enforce the escalating-confirmation gate before any write. Resolves when the run is authorized and
+ * throws a `ValidationError` otherwise:
+ *
+ *  - `dev` → always authorized.
+ *  - `staging` (and any other non-`dev`, non-production environment) → requires `--yes`.
+ *  - production ({@link isProductionEnv}: the built-in `production`/`prod` plus any name the project
+ *    declares in `seed.productionEnvironments`, case-insensitive) → requires `--yes` **and** the exact
+ *    confirm phrase. A prod environment named `live`/`prod-eu` is gated only if it is declared. The
+ *    phrase comes from `--confirm-production` when supplied (the CI/non-interactive path); otherwise,
+ *    if interactive, the injected `prompt` is asked for it. `--json` forbids the prompt, so production
+ *    without the flag is refused. A supplied-but-wrong phrase is always refused.
+ */
+export async function assertSeedConfirmed(options: ConfirmSeedOptions): Promise<void> {
+  if (options.env === "dev") return;
+
+  if (!options.yes) {
+    throw new ValidationError({
+      message: `Seeding ${options.env} needs confirmation.`,
+      action: `Re-run with --yes to seed ${options.env}.`,
+    });
+  }
+
+  if (!isProductionEnv(options.env, options.productionEnvironments)) return;
+
+  // Production: the flag is authoritative wherever it is present (CI or interactive).
+  if (options.confirmProduction !== undefined) {
+    if (phraseMatches(options.confirmProduction)) return;
+    throw new ValidationError({
+      message: "The production confirmation phrase did not match.",
+      action: `Pass --confirm-production "${PRODUCTION_CONFIRM_PHRASE}" to seed production.`,
+    });
+  }
+
+  // No flag: only an interactive prompt can unlock production. `--json` (or a missing prompt) forbids it.
+  if (options.json || !options.prompt) {
+    throw new ValidationError({
+      message: "Seeding production needs an explicit confirmation phrase.",
+      action: `Pass --confirm-production "${PRODUCTION_CONFIRM_PHRASE}" to seed production.`,
+    });
+  }
+
+  if (phraseMatches(await options.prompt())) return;
+  throw new ValidationError({
+    message: "The production confirmation phrase did not match.",
+    action: `Type "${PRODUCTION_CONFIRM_PHRASE}" exactly to seed production.`,
+  });
+}

package/src/terminal/logger.ts

@@ -0,0 +1,42 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createLocalLogger, type LocalPalette } from "@pithy-sh/core/src/logger/local";
+import type { Logger } from "@pithy-sh/core/src/logger/logger";
+import { cyan, dim, red, yellow } from "./style";
+
+/**
+ * The CLI's Mode 1 diagnostic logger — the process-scoped side of the one unified local layer. It is
+ * the runtime-agnostic core `createLocalLogger` configured for a terminal: the `style.ts` color seam,
+ * output on `stderr` (a command's machine-readable stdout stays clean), and level gated by `--debug`.
+ *
+ * This is *diagnostic logging only*. Interactive CLI UX — @clack prompts and spinners, `Done.`,
+ * `PithyError` `renderTerminal` — stays on `output.ts`/`style.ts` and never routes through here.
+ */
+
+/** The level-keyed palette, drawn from the one color seam so all CLI color still flows through `style.ts`. */
+const palette: LocalPalette = { debug: dim, info: cyan, warn: yellow, error: red, dim };
+
+/** Options for {@link createCliLogger}, wired from a command's `--debug` / `--json` args. */
+export interface CliLoggerOptions {
+  /** `--debug`: drop the threshold to `debug` (verbose diagnostics). Off → `warn`, so it stays quiet. */
+  debug?: boolean;
+  /** `--json`: emit a structured line stream (for agents/CI) instead of the colorized human format. */
+  json?: boolean;
+  /** Override the sink (tests capture it). Defaults to `stderr`. */
+  write?: (line: string) => void;
+}
+
+/**
+ * Build the CLI process logger. Quiet by default (`warn`), verbose under `--debug`. In `--json` mode it
+ * emits the same structured records the Worker adapter does — one line each — so an agent driving the
+ * CLI parses diagnostics the same way it parses a deployed Worker's logs.
+ */
+export function createCliLogger(options: CliLoggerOptions = {}): Logger {
+  return createLocalLogger({
+    level: options.debug ? "debug" : "warn",
+    json: options.json,
+    palette: options.json ? undefined : palette,
+    write: options.write,
+  });
+}

package/src/terminal/output.ts

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ErrorPayload } from "@pithy-sh/core/src/error/payload";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { operatorError, renderTerminal } from "@pithy-sh/core/src/error/terminal";
+import { red, saffron } from "./style";
+
+/** Completion, brand voice: `Done.` with the saffron period (docs/CLI.md §3.2). */
+export function formatDone(): string {
+  return `Done${saffron(".")}`;
+}
+
+/** One machine-readable line — every command's `--json` output shape. */
+export function formatJsonLine(payload: Record<string, unknown>): string {
+  return JSON.stringify(payload);
+}
+
+/**
+ * A two-column name/description list, whitespace-aligned — the multi-row output
+ * shape from docs/CLI.md §3.5 (no borders; the whitespace is the layout). Names
+ * pad to the longest, then two spaces, then the description. Empty in → empty out.
+ */
+export function formatList(rows: { name: string; description: string }[]): string {
+  const width = Math.max(0, ...rows.map((row) => row.name.length));
+  return rows.map((row) => `${row.name.padEnd(width)}  ${row.description}`).join("\n");
+}
+
+/** Problem line (red), then action line (docs/CLI.md §3.3). */
+export function formatError(payload: ErrorPayload): string {
+  const rendered = renderTerminal(payload);
+  const newline = rendered.indexOf("\n");
+  if (newline === -1) return red(rendered);
+  return red(rendered.slice(0, newline)) + rendered.slice(newline);
+}
+
+/**
+ * The `--json` error line: `{ error: <operator payload> }` — the public fields plus
+ * the `action` line, which is what {@link formatError} prints two lines above.
+ *
+ * Not the HTTP encoder, and that is the point. Both surfaces drop `detail`, but they
+ * drop it for different people: a browser is a caller, and whoever ran the command is
+ * the operator the remedy was written for. Reusing `HttpError.encode` here would have
+ * classified `action` by the encoder that happened to be shared rather than by who reads
+ * the line — and taken the fix out of a scripted `pithy` run for no gain anywhere.
+ */
+export function formatErrorJson(payload: ErrorPayload): string {
+  return JSON.stringify({ error: operatorError(payload) });
+}
+
+/**
+ * Run a command body; on `PithyError`, report it to stderr and exit 1 — as the
+ * `{ error: … }` JSON line when `json` is set, otherwise the problem/action
+ * lines. Anything else is a CLI bug and keeps its stack trace.
+ */
+export async function withErrorReporting(json: boolean, work: () => Promise<void>): Promise<void> {
+  try {
+    await work();
+  } catch (error) {
+    if (!(error instanceof PithyError)) throw error;
+    process.stderr.write(`${json ? formatErrorJson(error.payload) : formatError(error.payload)}\n`);
+    process.exit(1);
+  }
+}

package/src/terminal/style.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import pc from "picocolors";
+
+/**
+ * The color seam. Every colored character the CLI prints flows through here —
+ * no raw ANSI anywhere else (docs/CLI.md §3.4). `picocolors` carries the
+ * terminal-themed tiers (dim, basic-16); `saffron` is the one truecolor brand
+ * accent, constant everywhere it renders.
+ */
+
+const SAFFRON_TRUECOLOR = "\x1b[38;2;212;160;23m"; // #D4A017
+const SAFFRON_256 = "\x1b[38;5;178m";
+const RESET = "\x1b[0m";
+
+function supportsTruecolor(): boolean {
+  const colorterm = process.env.COLORTERM;
+  return colorterm === "truecolor" || colorterm === "24bit";
+}
+
+/**
+ * Color is on only for an interactive terminal — never when the output is piped,
+ * redirected, or captured. `NO_COLOR` forces it off, `FORCE_COLOR` forces it on
+ * (the standard env overrides). We decide here rather than trusting
+ * `pc.isColorSupported`: picocolors treats any `CI` env as color-capable, which
+ * would bleed ANSI into our `--json` and `Done.` output the moment a CI runner
+ * (or a piped consumer) reads it. Our output is parsed; a TTY is the real signal.
+ */
+function detectColor(): boolean {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+// Decided once at import, the way picocolors itself latches its detection.
+const enabled = detectColor();
+
+/**
+ * The latched decision, for the one caller that needs the rule rather than a colored string: `bin.ts`
+ * hands it to citty, which renders its own help and consults none of the above. Exported so the rule
+ * lives in exactly one place — a second copy of it is how the help output came to disagree with every
+ * other surface in the first place.
+ */
+export function colorEnabled(): boolean {
+  return enabled;
+}
+
+/** The brand mark in terminal form. Truecolor → 256-color 178 → no color. */
+export function saffron(text: string): string {
+  if (!enabled) return text;
+  return (supportsTruecolor() ? SAFFRON_TRUECOLOR : SAFFRON_256) + text + RESET;
+}
+
+// The terminal-themed tiers, re-exported so all color still imports from the one
+// seam. Built from our own `enabled` flag (not picocolors' detection) so they
+// honor the same TTY-gated rule as `saffron`. This is the documented exception
+// to the no-re-export rule; further tiers join as commands need them.
+export const { red, yellow, cyan, dim, magenta, bold } = pc.createColors(enabled);
+
+/**
+ * A group heading on the root help screen: bold + basic-16 magenta (docs/CLI.md §3.4).
+ *
+ * One symbol rather than a nesting each call site repeats, because "bold + magenta" is a tier decision
+ * and a tier decision lives here. A second call site that reached for half the pair would be a heading
+ * that looks styled and is not, which is the failure a reader cannot see.
+ *
+ * Magenta rather than saffron deliberately: §3.4 lists the places saffron appears and a heading is not
+ * one of them. A heading carries structure; saffron carries meaning.
+ */
+export function heading(text: string): string {
+  return bold(magenta(text));
+}
+
+// A stable, TTY-gated palette for per-worker labels in `pithy dev`. Built from the one seam so no
+// raw ANSI leaks. Cyan/red/yellow/dim are reserved for meaning elsewhere, so the palette leans on the
+// remaining hues and their bright variants; it cycles when a project has more workers than colors.
+// Magenta is in both this palette and `heading` on purpose: `pithy dev` and the help screen never share
+// an output stream, and dropping an entry would silently reassign every worker's color from index 1 on.
+const palette = pc.createColors(enabled);
+const WORKER_PALETTE: readonly ((text: string) => string)[] = [
+  palette.green,
+  palette.magenta,
+  palette.blue,
+  palette.cyan,
+  palette.greenBright,
+  palette.magentaBright,
+  palette.blueBright,
+  palette.cyanBright,
+];
+
+/**
+ * A stable color for one worker's log label, chosen by its discovery index and cycling the palette.
+ * `pithy dev` colorizes each worker's `[name]` prefix so interleaved output stays readable.
+ */
+export function workerColor(index: number): (text: string) => string {
+  return WORKER_PALETTE[((index % WORKER_PALETTE.length) + WORKER_PALETTE.length) % WORKER_PALETTE.length] as (
+    text: string,
+  ) => string;
+}
+
+/**
+ * Wrap `text` in an OSC-8 terminal hyperlink pointing at `url` — the id-as-link
+ * rendering `pithy env` uses so a resource id opens its Cloudflare dashboard page.
+ * Gated on the same latched `enabled` flag as every other symbol here: off when the
+ * output is piped/redirected or `NO_COLOR` is set (where escape sequences would be
+ * noise), so the caller falls back to printing the plain URL. `FORCE_COLOR` forces
+ * it on. When off, the plain `text` is returned unchanged.
+ */
+export function link(url: string, text: string): string {
+  if (!enabled) return safe(text);
+  return `\x1b]8;;${safe(url)}\x1b\\${safe(text)}\x1b]8;;\x1b\\`;
+}
+
+/**
+ * Strip C0/C1 control characters. Both halves of a hyperlink are values read out of a project's
+ * `wrangler.jsonc` — a resource id and a URL built from it — so an embedded `ESC` could close this
+ * sequence early and open its own, making the rendered link point somewhere other than what it displays.
+ * Stripping them also stops a malformed id from corrupting the surrounding output.
+ */
+function safe(value: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point.
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+}
+
+/**
+ * Whether OSC-8 hyperlinks render — the same TTY-gated `enabled` flag `link` uses.
+ * Callers branch on it to choose the clickable id or the plain-URL fallback.
+ */
+export function supportsHyperlinks(): boolean {
+  return colorEnabled();
+}

package/src/test-utils/doctorHarness.ts

@@ -0,0 +1,190 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, vi } from "vitest";
+import type { ReconcilePlan } from "../capabilities/reconcile";
+import type { DoctorReportOptions } from "../commands/doctor";
+import type { BuildPlan, ProjectHealth, WorkerHealth } from "../doctor/health";
+import type { FetchLike } from "../notifier/check";
+import type { ShellInfo } from "../platform/shell";
+import type { ProjectConfig } from "../project/config";
+import type { ResolvedWorker } from "../project/workerScope";
+
+/**
+ * Shared scaffolding for building a `DoctorReport` — every environment and network seam stubbed, so a
+ * suite states only the scenario it is about.
+ *
+ * Extracted so there is exactly one way to construct a report. `commands/doctor.test.ts` asserts what the
+ * renderer prints; `commands/doctorDocs.test.ts` asserts that `docs/CLI.md` prints the same thing. Two
+ * builders would let the doc pin drift from the suite it is meant to hold the doc against — the pin would
+ * still pass while describing a report the CLI no longer produces.
+ */
+
+/**
+ * The nth **checked** Worker in a health report — #371's `WorkerHealth` union narrowed in one place.
+ *
+ * It throws rather than answering `undefined`, so a Worker that silently stopped being checked fails the
+ * assertion that was about something else, loudly, instead of passing as an optional-chained skip. The
+ * suites that are about the unchecked state read `health.workers` directly.
+ */
+export function checkedWorker(
+  health: ProjectHealth | undefined,
+  index = 0,
+): Extract<WorkerHealth, { state: "checked" }> {
+  const worker = health?.workers[index];
+  if (worker?.state !== "checked") throw new Error(`worker ${index} was not checked: ${worker?.state ?? "absent"}`);
+  return worker;
+}
+
+/** A `fetch` mapping each package's registry URL to a canned latest version. */
+export function registryFetch(versions: Record<string, string>): FetchLike {
+  return vi.fn(async (url: string) => {
+    const match = url.match(/@pithy-sh%2F([^/]+)\/latest/);
+    const name = match?.[1] ?? "";
+    const version = versions[name];
+    if (!version) return { ok: false, status: 404, json: async () => ({}) };
+    return { ok: true, status: 200, json: async () => ({ version }) };
+  });
+}
+
+/**
+ * A clean plan for one Worker.
+ *
+ * `deployedAs` is derived rather than echoed, so every fixture built here has a directory and a deployed
+ * name that differ. A harness that set both to `worker` would let code reading the wrong one pass.
+ */
+export const cleanPlanFor = (worker: string): ReconcilePlan => ({
+  worker,
+  deployedAs: `acme-${worker}`,
+  env: "dev",
+  perCapability: [],
+  ejectedSkipped: [],
+  ledger: { state: "read", pending: 0, undeclared: [] },
+  entitlements: { state: "read", gates: [] },
+  missingPrerequisites: [],
+  declinedBindings: { state: "read", declines: [] },
+  missingVersionMetadata: false,
+});
+
+/** A plan builder that stamps the requested Worker's name onto a fixed plan. */
+export const planStub = (plan: ReconcilePlan): BuildPlan =>
+  vi.fn(async (options) => ({ ...plan, worker: options.worker ?? plan.worker }));
+
+/** A plan builder keyed by Worker — for a project whose Workers differ. */
+export const planStubPer = (plans: Record<string, ReconcilePlan>): BuildPlan =>
+  vi.fn(async (options) => plans[options.worker ?? ""] ?? cleanPlanFor(options.worker ?? ""));
+
+/** The Worker set doctor's resolver seam returns; `ResolvedWorker` is satisfied structurally. */
+export const workerSet = (...names: string[]) =>
+  names.map((name) => ({ name, dir: `/p/apps/${name}`, capabilities: [] }) as unknown as ResolvedWorker);
+
+/** The shell every fixture reports — installed alias included, so the alias line is a constant. */
+export const zsh: ShellInfo = { kind: "zsh", rcPath: "/home/u/.zshrc", aliasSyntax: "alias p.='pithy'" };
+
+/** The loaded root config every fixture reports. */
+export const config: ProjectConfig = { name: "pithy-app" };
+
+/** A throwaway directory per test, plus the two option builders every doctor suite starts from. */
+export interface DoctorHarness {
+  /** The temp project directory. A getter: `beforeEach` makes a new one for every test. */
+  readonly dir: string;
+  /** The notifier state file inside it. */
+  readonly stateFile: string;
+  /** A project present, fresh registry, deterministic env/os/runtime — the verbose starting point. */
+  baseOptions(overrides?: Partial<DoctorReportOptions>): DoctorReportOptions;
+  /** Nothing to report: current CLI, current capabilities, alias installed — the terse starting point. */
+  healthyOptions(overrides?: Partial<DoctorReportOptions>): DoctorReportOptions;
+}
+
+/**
+ * Registers the per-test temp directory and returns the option builders. Call it once at module or
+ * `describe` scope; `dir` is a getter because each test gets a fresh directory, so a plain value captured
+ * at import would go stale after the first test.
+ */
+export function doctorHarness(): DoctorHarness {
+  let dir = "";
+  let stateFile = "";
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "pithy-doctor-"));
+    stateFile = join(dir, "state.json");
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  function baseOptions(overrides: Partial<DoctorReportOptions> = {}): DoctorReportOptions {
+    return {
+      projectDir: dir,
+      installedVersion: "1.2.0",
+      stateFile,
+      argv1: "/home/u/.bun/bin/pithy",
+      env: {},
+      homedir: "/home/u",
+      os: { name: "macOS", version: "14.5" },
+      runtime: { name: "Node", version: "22.10.0", nodeCompat: null },
+      node: "22.10.0",
+      // Injected so the unit suite never reaches Cloudflare; the live probe is exercised by its own module.
+      checkCloudflare: async () => ({
+        state: "ok" as const,
+        missing: [],
+        tokenStatus: "active",
+        credentialSplit: null,
+      }),
+      // Same reason: unstubbed, every test here would list the real account's D1 and R2.
+      checkProjectName: async () => ({ state: "ok" as const, project: "pithy-app", misnamed: [] }),
+      // And the same again for the machine's port registry: unstubbed, `present` and every row of the
+      // listing would depend on which checkouts the machine running the suite happens to hold — a report
+      // that differs by machine, and a transcript nobody could pin. One own block, which is the state a
+      // developer on their default branch is in; the suites about the other rows override this.
+      checkPortsRegistry: async () => ({
+        path: "/home/u/.config/pithy/dev-ports.json",
+        present: true,
+        stray: null,
+        root: "/home/u/code/acme",
+        unreadable: null,
+        entries: [
+          { root: "/home/u/code/acme", branch: "main", block: 0, base: 8787, size: 20, own: true, onDisk: true },
+        ],
+      }),
+      now: () => 1_000,
+      fetch: registryFetch({ cli: "1.3.0" }),
+      detectShell: async () => zsh,
+      readRc: async () => "# >>> pithy alias >>>\nalias p.='pithy'\n# <<< pithy alias <<<\n",
+      loadProject: async () => config,
+      resolveWorkers: async () => workerSet("api"),
+      installedCapabilities: async () => [
+        { name: "@pithy-sh/core", version: "1.2.0" },
+        { name: "@pithy-sh/auth", version: "1.1.8" },
+        { name: "@pithy-sh/leaderboard", version: "1.2.0" },
+      ],
+      buildPlan: planStub(cleanPlanFor("api")),
+      ...overrides,
+    };
+  }
+
+  return {
+    get dir(): string {
+      return dir;
+    },
+    get stateFile(): string {
+      return stateFile;
+    },
+    baseOptions,
+    healthyOptions(overrides: Partial<DoctorReportOptions> = {}): DoctorReportOptions {
+      return baseOptions({
+        installedVersion: "1.3.0",
+        argv1: "/opt/homebrew/bin/pithy",
+        fetch: registryFetch({ cli: "1.3.0", core: "1.2.0", auth: "1.2.0", leaderboard: "1.2.0" }),
+        installedCapabilities: async () => [
+          { name: "@pithy-sh/core", version: "1.2.0" },
+          { name: "@pithy-sh/auth", version: "1.2.0" },
+          { name: "@pithy-sh/leaderboard", version: "1.2.0" },
+        ],
+        ...overrides,
+      });
+    },
+  };
+}