@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/kernel/project/cli/dispatch.test.ts

@@ -0,0 +1,288 @@
+import { fail, succeed } from "@canonical/task";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PragmaError } from "../../error/PragmaError.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { dispatch, executeVerb, extractParams } from "./dispatch.js";
+
+const PLAIN: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const JSON_FLAGS: GlobalFlags = { ...PLAIN, format: "json" };
+
+const passthroughFormatters = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+const echo: VerbSpec = {
+  path: ["probe", "echo"],
+  summary: "Echo the message.",
+  params: [
+    {
+      kind: "string",
+      name: "message",
+      doc: "The message.",
+      positional: true,
+      required: true,
+    },
+  ],
+  output: { formatters: passthroughFormatters },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async (p) => ({ echoed: (p as { message: string }).message }),
+};
+
+const make: VerbSpec = {
+  path: ["probe", "make"],
+  summary: "Make a thing.",
+  params: [],
+  output: { formatters: passthroughFormatters },
+  capability: { needsStore: false, mutates: true, mcp: { expose: true } },
+  run: () => succeed({ made: true }),
+};
+
+describe("extractParams", () => {
+  it("maps positionals and flags into the param bag", () => {
+    const params: ParamSpec[] = [
+      {
+        kind: "string",
+        name: "name",
+        doc: "",
+        positional: true,
+        required: true,
+      },
+      { kind: "boolean", name: "withHistory", doc: "" },
+    ];
+    expect(extractParams(params, ["Gadget"], { withHistory: true })).toEqual({
+      name: "Gadget",
+      withHistory: true,
+    });
+  });
+
+  it("coerces a number and rejects a non-number", () => {
+    const params: ParamSpec[] = [
+      { kind: "number", name: "count", doc: "", positional: true },
+    ];
+    expect(extractParams(params, ["42"], {})).toEqual({ count: 42 });
+    expect(() => extractParams(params, ["nan"], {})).toThrow(PragmaError);
+  });
+
+  it("rejects an out-of-set enum value", () => {
+    const params: ParamSpec[] = [
+      { kind: "enum", name: "mode", doc: "", values: ["a", "b"] },
+    ];
+    expect(() => extractParams(params, [], { mode: "c" })).toThrow(
+      /Invalid mode/,
+    );
+  });
+
+  it("absorbs the remainder into a trailing string[] positional", () => {
+    const params: ParamSpec[] = [
+      { kind: "string[]", name: "names", doc: "", positional: true },
+    ];
+    expect(extractParams(params, ["a", "b", "c"], {})).toEqual({
+      names: ["a", "b", "c"],
+    });
+  });
+});
+
+describe("executeVerb — reads", () => {
+  it("renders plain text", async () => {
+    const outcome = await executeVerb(
+      echo,
+      { message: "hi" },
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toBe("[object Object]\n");
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("wraps json output in the {ok,data,meta} envelope", async () => {
+    const outcome = await executeVerb(
+      echo,
+      { message: "hi" },
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(JSON_FLAGS),
+    );
+    expect(JSON.parse(outcome.stdout as string)).toEqual({
+      ok: true,
+      data: { echoed: "hi" },
+      meta: {},
+    });
+  });
+});
+
+describe("executeVerb — mutations", () => {
+  it("executes a Task and envelopes the result", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(JSON_FLAGS),
+    );
+    expect(JSON.parse(outcome.stdout as string)).toEqual({
+      ok: true,
+      data: { made: true },
+      meta: {},
+    });
+  });
+
+  it("previews under --dry-run without executing", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: true, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toContain("Dry run");
+  });
+
+  it("reports undo count under --undo", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: false, undo: true, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toBe("Undid 0 step(s).\n");
+  });
+});
+
+describe("dispatch — errors", () => {
+  const savedExit = process.exitCode;
+  afterEach(() => {
+    process.exitCode = savedExit;
+  });
+
+  it("renders a PragmaError to stderr with a mapped exit code", async () => {
+    const failing: VerbSpec = {
+      ...echo,
+      run: async () => {
+        throw PragmaError.notFound("thing", "Nope");
+      },
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    await dispatch(failing, ["x"], {}, PLAIN);
+    spy.mockRestore();
+    expect(errs.join("")).toContain('thing "Nope" not found.');
+    expect(process.exitCode).toBe(1);
+  });
+
+  it("renders a declined confirm gate as a clean cancellation, not a bug report", async () => {
+    // A TTY user declining execute()'s "Proceed?" gate fails the task with
+    // GENERATOR_CANCELLED; the boundary must treat it as a clean cancel, never
+    // the scary INTERNAL_ERROR "please report this issue" / exit 1.
+    const cancelling: VerbSpec = {
+      ...make,
+      run: () => fail({ code: "GENERATOR_CANCELLED", message: "Cancelled." }),
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    await dispatch(cancelling, [], { yes: true }, PLAIN);
+    spy.mockRestore();
+    const out = errs.join("");
+    expect(out).toContain("Cancelled.");
+    expect(out).not.toContain("INTERNAL_ERROR");
+    expect(out).not.toMatch(/report this issue/i);
+    // A deliberate cancel is a success exit under the frozen exit-code covenant.
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("renders an interrupt (SIGINT / mid-run Ctrl-C) as a clean cancel, exit 130 (M1)", async () => {
+    // A --yes/CI run aborted by SIGINT fails the task with TASK_INTERRUPTED.
+    // The boundary must render it as a clean cancel (not a bug), but exit with
+    // the UNIX 128+SIGINT code 130 — out-of-band from the frozen {0,1,2,3}.
+    const interrupting: VerbSpec = {
+      ...make,
+      run: () =>
+        fail({ code: "TASK_INTERRUPTED", message: "Task interrupted" }),
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    await dispatch(interrupting, [], { yes: true }, PLAIN);
+    spy.mockRestore();
+    const out = errs.join("");
+    expect(out).toContain("Cancelled.");
+    expect(out).not.toContain("INTERNAL_ERROR");
+    expect(out).not.toMatch(/report this issue/i);
+    expect(process.exitCode).toBe(130);
+  });
+});
+
+describe("executeVerb — interactivity gate (H3)", () => {
+  const setTTY = (
+    stream: NodeJS.ReadStream | NodeJS.WriteStream,
+    value: boolean | undefined,
+  ): void => {
+    (stream as { isTTY?: boolean }).isTTY = value;
+  };
+  const savedIn = process.stdin.isTTY;
+  const savedOut = process.stdout.isTTY;
+  const savedErr = process.stderr.isTTY;
+  afterEach(() => {
+    setTTY(process.stdin, savedIn);
+    setTTY(process.stdout, savedOut);
+    setTTY(process.stderr, savedErr);
+  });
+
+  /** A mutating verb that records the interaction context it was handed. */
+  const captureTTY = (sink: { isTTY?: boolean }): VerbSpec => ({
+    ...make,
+    run: (_p, rt) => {
+      sink.isTTY = rt.interaction?.isTTY;
+      return succeed({ made: true });
+    },
+  });
+
+  it("is NON-interactive when stderr is redirected, even with a stdout TTY (2>/dev/null)", async () => {
+    setTTY(process.stdin, true);
+    setTTY(process.stdout, true);
+    setTTY(process.stderr, false); // the Ink UI's stream is gone
+    const sink: { isTTY?: boolean } = {};
+    await executeVerb(
+      captureTTY(sink),
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(sink.isTTY).toBe(false);
+  });
+
+  it("is interactive on a stdin+stderr TTY, even when stdout is piped (gate is stderr, not stdout)", async () => {
+    setTTY(process.stdin, true);
+    setTTY(process.stdout, false); // piped stdout must NOT force non-interactive
+    setTTY(process.stderr, true);
+    const sink: { isTTY?: boolean } = {};
+    await executeVerb(
+      captureTTY(sink),
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(sink.isTTY).toBe(true);
+  });
+});

package/src/kernel/project/cli/dispatch.ts

@@ -0,0 +1,334 @@
+/**
+ * The CLI dispatcher: from parsed argv to rendered output.
+ *
+ * Coerces raw string args into typed params by {@link ParamSpec.kind} (no zod
+ * on this path), boots the runtime, runs the verb across the effect seam, and
+ * renders. The seam is the discriminator `capability.mutates`: a read is a
+ * plain `Promise` rendered directly; a mutation is a `Task` interpreted under
+ * the node interpreter (`--yes`), the dry-run interpreter (`--dry-run`), or the
+ * undo interpreter (`--undo`). `--format json` wraps output in the full
+ * `{ ok, data, meta }` envelope (D3); errors render to stderr with a mapped
+ * exit code.
+ */
+
+import { describeEffect, dryRun, type Task } from "@canonical/task";
+import { runTask, runUndo } from "@canonical/task/node";
+import {
+  asPragmaError,
+  CANCELLED_MESSAGE,
+  isCancellation,
+  isInterruption,
+} from "../../error/fromTaskError.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "../../error/renderError.js";
+import { successEnvelope } from "../../render/envelope.js";
+import { selectFormatter } from "../../render/formatters.js";
+import { writeStdout } from "../../render/writeStdout.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type {
+  GlobalFlags,
+  InteractionRuntime,
+  PragmaRuntime,
+} from "../../runtime/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { EXIT, mapExitCode } from "./exitCodes.js";
+
+/** The CLI-only mutation flags auto-injected onto every mutating verb. */
+export interface MutationFlags {
+  readonly dryRun: boolean;
+  readonly undo: boolean;
+  readonly yes: boolean;
+}
+
+/**
+ * Route a Task's log effects to stderr. The interpreter otherwise falls back to
+ * `console.log` (stdout), which would corrupt the `--format json` / MCP stdio
+ * data stream; diagnostics belong on stderr.
+ */
+const logToStderr = (_level: string, message: string): void => {
+  process.stderr.write(`${message}\n`);
+};
+
+/** The result of running a verb: what to write where, and the exit code. */
+export interface DispatchOutcome {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode: number;
+}
+
+/** Coerce one raw arg into the type its {@link ParamSpec} declares. */
+function coerceParam(param: ParamSpec, raw: unknown): unknown {
+  switch (param.kind) {
+    case "number": {
+      const value = typeof raw === "number" ? raw : Number(raw);
+      if (Number.isNaN(value)) {
+        throw PragmaError.invalidInput(param.name, String(raw));
+      }
+      return value;
+    }
+    case "boolean":
+      return typeof raw === "boolean" ? raw : raw === "true";
+    case "enum": {
+      const value = String(raw);
+      if (!param.values.includes(value)) {
+        throw PragmaError.invalidInput(param.name, value, {
+          validOptions: [...param.values],
+        });
+      }
+      return value;
+    }
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Build the typed param bag from Commander's positional args and options.
+ *
+ * Flag options arrive keyed by their camelCase param name (Commander derives
+ * `withHistory` from `--with-history`); positionals map in declared order, with
+ * a trailing `string[]` param absorbing the remainder.
+ *
+ * @param params - The verb's parameter specs.
+ * @param positionals - Positional args in order.
+ * @param opts - Commander's parsed option values.
+ * @returns The coerced param bag passed to `run`.
+ */
+export function extractParams(
+  params: readonly ParamSpec[],
+  positionals: readonly string[],
+  opts: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const param of params) {
+    if (param.positional) continue;
+    const raw = opts[param.name];
+    if (raw !== undefined) {
+      result[param.name] = coerceParam(param, raw);
+    } else if ("default" in param && param.default !== undefined) {
+      result[param.name] = param.default;
+    }
+  }
+
+  const positional = params.filter((p) => p.positional);
+  for (let i = 0; i < positional.length && i < positionals.length; i++) {
+    const param = positional[i] as ParamSpec;
+    if (param.kind === "string[]" && i === positional.length - 1) {
+      result[param.name] = positionals.slice(i);
+      break;
+    }
+    result[param.name] = coerceParam(param, positionals[i]);
+  }
+
+  return result;
+}
+
+/** Render a read/execute result through the verb's formatters. */
+function renderData(
+  verb: VerbSpec,
+  flags: GlobalFlags,
+  data: unknown,
+  meta: Record<string, unknown>,
+): DispatchOutcome {
+  if (flags.format === "json") {
+    const projection = JSON.parse(verb.output.formatters.json(data));
+    return {
+      stdout: `${JSON.stringify(successEnvelope(projection, meta))}\n`,
+      exitCode: 0,
+    };
+  }
+  const text = selectFormatter(flags, verb.output.formatters)(data);
+  return { stdout: text ? `${text}\n` : "", exitCode: 0 };
+}
+
+/** Render a dry-run plan (the effects a mutation would perform). */
+function renderPlan(
+  flags: GlobalFlags,
+  plan: readonly string[],
+): DispatchOutcome {
+  if (flags.format === "json") {
+    return {
+      stdout: `${JSON.stringify(successEnvelope({ plan }, { dryRun: true }))}\n`,
+      exitCode: 0,
+    };
+  }
+  const body =
+    plan.length > 0
+      ? `Dry run — planned effects:\n${plan.map((p) => `  - ${p}`).join("\n")}`
+      : "Dry run — no effects.";
+  return { stdout: `${body}\n`, exitCode: 0 };
+}
+
+/** Render the outcome of an undo. */
+function renderUndo(flags: GlobalFlags, undone: number): DispatchOutcome {
+  if (flags.format === "json") {
+    return {
+      stdout: `${JSON.stringify(successEnvelope({ undone }, { undo: true }))}\n`,
+      exitCode: 0,
+    };
+  }
+  return { stdout: `Undid ${undone} step(s).\n`, exitCode: 0 };
+}
+
+/** Render a caught error to stderr with a mapped exit code. */
+function renderError(error: PragmaError, flags: GlobalFlags): DispatchOutcome {
+  const rendered =
+    flags.format === "json"
+      ? renderErrorJson(error)
+      : flags.llm
+        ? renderErrorLlm(error)
+        : renderErrorPlain(error);
+  return { stderr: `${rendered}\n`, exitCode: mapExitCode(error.code) };
+}
+
+/**
+ * Run a verb across the effect seam and produce its output.
+ *
+ * The testable core of {@link dispatch}: pure of process I/O, it returns what
+ * to write rather than writing it, so tests (and the envelope-parity check)
+ * can assert on the outcome directly.
+ *
+ * @param verb - The verb to run.
+ * @param params - The coerced param bag.
+ * @param mutation - The mutation flags (ignored for reads).
+ * @param runtime - The booted runtime.
+ * @returns The dispatch outcome.
+ * @note Impure — a mutation's node/undo interpreter touches the filesystem.
+ */
+export async function executeVerb(
+  verb: VerbSpec,
+  params: Record<string, unknown>,
+  mutation: MutationFlags,
+  runtime: PragmaRuntime,
+): Promise<DispatchOutcome> {
+  const flags = runtime.globalFlags;
+
+  // The lazy-store seam: boot the store (once, memoized) only for verbs that
+  // declare they need it. A storeless verb never reaches the store factory, so
+  // the storeless guarantee holds by construction (no STORE_SKIP triage).
+  if (verb.capability.needsStore) {
+    await runtime.store.get();
+  }
+
+  if (verb.capability.mutates) {
+    // Tell the verb whether this is a plan-only preview (`--dry-run`) or a real
+    // execution, so a network-touching mutation can stay offline for the plan.
+    // Also hand it the interaction context so an interactive verb can pick its
+    // prompt strategy. The verb's `run` sets `mutationRuntime.exec` (the runner
+    // options) as its last act; the projector reads it back on the real-run
+    // branch only — the dry-run/undo branches stay handler-free (they mock
+    // prompts), so `--dry-run`/`--undo` are unchanged by this seam.
+    const controller = new AbortController();
+    const interaction: InteractionRuntime = {
+      // Gate on STDERR (H3): the Ink wizard renders to stderr and reads stdin,
+      // so `<verb> 2>/dev/null` must be non-interactive — gating on stdout would
+      // mount an invisible render that blocks on stdin.
+      isTTY: process.stdin.isTTY === true && process.stderr.isTTY === true,
+      transport: "cli",
+      yes: mutation.yes,
+      signal: controller.signal,
+      // Let an interactive verb's wizard abort the run on an in-Ink Ctrl-C (H2):
+      // raw mode swallows SIGINT, so the keypress can't reach the SIGINT handler
+      // below — the wizard drives this instead. `abort()` is idempotent.
+      abort: () => controller.abort(),
+    };
+    const mutationRuntime: PragmaRuntime = {
+      ...runtime,
+      mutation: { preview: mutation.dryRun },
+      interaction,
+      // Progress seam (U7): a long mutation's eager resolve/build runs before its
+      // Task is returned, so `onLog` can't reach it — stream stage lines straight
+      // to stderr instead, keeping stdout (the JSON/data stream) clean.
+      report: (message: string) => process.stderr.write(`${message}\n`),
+    };
+    const task = await Promise.resolve(
+      verb.run(params, mutationRuntime) as
+        | Task<unknown>
+        | Promise<Task<unknown>>,
+    );
+    if (mutation.dryRun) {
+      // A plan is the effects a mutation WOULD apply — a `Prompt` is not one, so
+      // the interactive confirm gate / answer prompts never clutter the preview.
+      return renderPlan(
+        flags,
+        dryRun(task)
+          .effects.filter((effect) => effect._tag !== "Prompt")
+          .map(describeEffect),
+      );
+    }
+    if (mutation.undo) {
+      const { undoCount } = await runUndo(task, { onLog: logToStderr });
+      return renderUndo(flags, undoCount);
+    }
+    // Real execution: spread the verb's runner options into the node
+    // interpreter (prompt handler, stamping/progress callbacks, log routing,
+    // signal). Teardown (e.g. unmount an Ink render) runs in `finally`.
+    const exec = mutationRuntime.exec ?? {};
+    const onSigint = (): void => controller.abort();
+    process.once("SIGINT", onSigint);
+    try {
+      const value = await runTask(task, { onLog: logToStderr, ...exec });
+      return renderData(verb, flags, value, {});
+    } finally {
+      process.removeListener("SIGINT", onSigint);
+      await exec.dispose?.();
+    }
+  }
+
+  const data = await Promise.resolve(
+    verb.run(params, runtime) as Promise<unknown>,
+  );
+  return renderData(verb, flags, data, {});
+}
+
+/**
+ * Dispatch a matched verb: coerce, run, and perform the output I/O.
+ *
+ * @param verb - The matched verb spec.
+ * @param positionals - Positional args from Commander.
+ * @param opts - Commander's parsed option values (incl. mutation flags).
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatch(
+  verb: VerbSpec,
+  positionals: readonly string[],
+  opts: Record<string, unknown>,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  const runtime = bootRuntime(globalFlags);
+  let outcome: DispatchOutcome;
+  try {
+    const params = extractParams(verb.params, positionals, opts);
+    const mutation: MutationFlags = {
+      dryRun: opts.dryRun === true,
+      undo: opts.undo === true,
+      yes: opts.yes === true,
+    };
+    outcome = await executeVerb(verb, params, mutation, runtime);
+  } catch (error) {
+    // Two clean, non-bug outcomes print the same "Cancelled." line but exit
+    // differently — both set DIRECTLY here, out-of-band from `mapExitCode`'s
+    // frozen {0,1,2,3} (see exitCodes.ts):
+    //   - a DECLINE (confirm gate / at-prompt Ctrl-C) is a deliberate user
+    //     choice, not a failure → success exit 0; and
+    //   - an INTERRUPT (SIGINT on --yes/CI, or an in-wizard Ctrl-C mid-run) is
+    //     an abort of work already underway → UNIX 128+SIGINT exit 130.
+    // Everything else maps through the shared task-error bridge (which turns a
+    // bad/absent non-interactive answer into a usage error, not an internal bug).
+    outcome = isCancellation(error)
+      ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.OK }
+      : isInterruption(error)
+        ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.INTERRUPTED }
+        : renderError(asPragmaError(error), globalFlags);
+  }
+
+  if (outcome.stdout) writeStdout(outcome.stdout);
+  if (outcome.stderr) process.stderr.write(outcome.stderr);
+  if (outcome.exitCode !== 0) process.exitCode = outcome.exitCode;
+}

package/src/kernel/project/cli/exitCodes.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { ERROR_CODES } from "../../error/constants.js";
+import type { ErrorCode } from "../../error/types.js";
+import { EXIT, mapExitCode } from "./exitCodes.js";
+
+/**
+ * Protected: the exit-code table is a frozen covenant (D2). Every error code
+ * maps (via {@link mapExitCode}) to exactly one of the four blessed
+ * ERROR-CLASSIFICATION codes, and the table below is the enumerated contract —
+ * changing a mapping must change this test.
+ *
+ * `INTERRUPTED` (130, UNIX 128+SIGINT) is an INTENTIONAL out-of-band addition:
+ * it is set DIRECTLY at the dispatch catch (like the existing exit-0 cancel),
+ * NEVER produced by `mapExitCode`, so the frozen four-code classification range
+ * is untouched. The tests below assert exactly that split.
+ */
+describe("exit codes (PROTECTED)", () => {
+  it("blesses exactly four error-classification codes (mapExitCode's frozen range)", () => {
+    // The four codes mapExitCode is allowed to produce. 130 is deliberately NOT
+    // among them — it bypasses the map (asserted by the exhaustive table below).
+    expect({
+      OK: EXIT.OK,
+      RUNTIME: EXIT.RUNTIME,
+      USAGE: EXIT.USAGE,
+      STORE_UNAVAILABLE: EXIT.STORE_UNAVAILABLE,
+    }).toEqual({ OK: 0, RUNTIME: 1, USAGE: 2, STORE_UNAVAILABLE: 3 });
+  });
+
+  it("adds INTERRUPTED=130 as an out-of-band code never produced by mapExitCode", () => {
+    // A deliberate SIGINT/interrupt exit (UNIX 128+SIGINT), set directly at the
+    // dispatch catch. It must never leak into mapExitCode's classification range.
+    expect(EXIT.INTERRUPTED).toBe(130);
+    const produced = new Set(ERROR_CODES.map(mapExitCode));
+    expect(produced.has(130)).toBe(false);
+    expect([...produced].every((c) => c === 1 || c === 2 || c === 3)).toBe(
+      true,
+    );
+  });
+
+  const table: Record<ErrorCode, number> = {
+    ENTITY_NOT_FOUND: 1,
+    EMPTY_RESULTS: 1,
+    CONFIG_ERROR: 1,
+    INTERNAL_ERROR: 1,
+    UNSUPPORTED: 1,
+    INVALID_INPUT: 2,
+    AMBIGUOUS_INPUT: 2,
+    UNKNOWN_VERB: 2,
+    STORE_UNAVAILABLE: 3,
+  };
+
+  it.each(ERROR_CODES)("maps %s to its exit code", (code) => {
+    expect(mapExitCode(code)).toBe(table[code]);
+  });
+
+  it("covers every error code in the table", () => {
+    expect(Object.keys(table).sort()).toEqual([...ERROR_CODES].sort());
+  });
+});