@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/token/runAddConfig.ts

@@ -0,0 +1,95 @@
+/**
+ * The `token add-config` write body (lazily imported, off the fast path).
+ *
+ * A store-backed mutation: it counts the design tokens in the active graph (so
+ * the plan reports how many tokens the config will cover) and derives the
+ * terrazzo token-source globs from the configured design-system packages, then
+ * returns a Task that writes `tokens.config.mjs`. The store read happens in the
+ * async setup; the file write is the Task's single `WriteFile` effect, so a
+ * plan-only preview (`mutation.preview`) describes the write without performing
+ * it. Ported from the old shell's `token add-config` (terrazzo `defineConfig`).
+ */
+
+import { resolve } from "node:path";
+import { $, exists, gen, type Task, writeFile } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+
+/** The default token source when no design-system packages are configured. */
+const DEFAULT_TOKEN_SOURCE =
+  "node_modules/@canonical/ds-global/tokens/**/*.json";
+
+/** The result of generating a terrazzo tokens config. */
+export interface AddConfigResult {
+  /** The absolute path written. */
+  readonly path: string;
+  /** How many `ds:Token` entities the active graph holds. */
+  readonly tokenCount: number;
+  /** The token-source globs written into the config. */
+  readonly sources: readonly string[];
+  /** Whether a `tokens.config.mjs` already existed (it is overwritten). */
+  readonly alreadyExisted: boolean;
+}
+
+/** Count the `ds:Token` entities in the booted store (best-effort). */
+async function countTokens(rt: PragmaRuntime): Promise<number> {
+  try {
+    const result = (await rt.query.sparql(
+      "SELECT (COUNT(DISTINCT ?token) AS ?count) WHERE { ?token a ds:Token }",
+    )) as { type?: string; bindings?: { count?: string }[] };
+    const raw = result.bindings?.[0]?.count;
+    return raw ? Number(raw) : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/** Derive the terrazzo token-source globs from the configured packages. */
+async function resolveSources(rt: PragmaRuntime): Promise<string[]> {
+  const { config } = await rt.loadConfig();
+  const packages = config.packages ?? [];
+  if (packages.length === 0) return [DEFAULT_TOKEN_SOURCE];
+  return packages.map((pkg) => {
+    const name = typeof pkg === "string" ? pkg : pkg.name;
+    return `node_modules/${name}/tokens/**/*.json`;
+  });
+}
+
+/** Render the terrazzo `tokens.config.mjs` content. */
+function generateConfig(sources: readonly string[]): string {
+  const sourceList = sources
+    .map((source) => `    ${JSON.stringify(source)}`)
+    .join(",\n");
+  return `// tokens.config.mjs — generated by \`pragma token add-config\`
+import { defineConfig } from "@canonical/terrazzo";
+
+export default defineConfig({
+  tokens: [
+${sourceList},
+  ],
+  outDir: "./tokens/",
+  plugins: [],
+});
+`;
+}
+
+/**
+ * Build the Task that writes `tokens.config.mjs` for the terrazzo pipeline.
+ *
+ * @param rt - The runtime (its store is booted by the projector for needsStore).
+ * @returns A Task yielding the write outcome.
+ * @note Impure — reads the store + config; the write is the Task's effect.
+ */
+export async function runAddConfig(
+  rt: PragmaRuntime,
+): Promise<Task<AddConfigResult>> {
+  const tokenCount = await countTokens(rt);
+  const sources = await resolveSources(rt);
+  const path = resolve(rt.cwd, "tokens.config.mjs");
+  const content = generateConfig(sources);
+
+  return gen(function* () {
+    const alreadyExisted = yield* $(exists(path));
+    yield* $(writeFile(path, content));
+    return { path, tokenCount, sources, alreadyExisted };
+  });
+}

package/src/capabilities/upgrade/index.ts

@@ -0,0 +1,6 @@
+/**
+ * The `upgrade` capability barrel.
+ */
+
+export type { UpgradeData } from "./types.js";
+export { upgradeModule } from "./upgrade.verb.js";

package/src/capabilities/upgrade/runUpgrade.ts

@@ -0,0 +1,119 @@
+/**
+ * Build the `upgrade` Task (lazily imported, off the fast path).
+ *
+ * Async-setup then compose: read the channel, detect the install source, and
+ * check the registry (a preview-safe READ — no side effect), then return a Task
+ * shaped by the outcome. The `exec` effect is the SOLE mutation, so the effect
+ * seam does the rest for free:
+ *
+ * - `--dry-run` (dispatcher `dryRun`) MOCKS the exec and describes the plan —
+ *   both the `Log` version-delta line AND the `Execute: <command>` line show,
+ *   and nothing runs.
+ * - `--yes` / MCP `confirm` runs the exec for real; a nonzero exit is surfaced
+ *   by `assertExecOk` as an actionable UNSUPPORTED (exit 1) — the interpreter
+ *   RESOLVES on a nonzero exit, so the check is the consumer's job.
+ * - offline / already-latest carry NO exec — a real run just returns the status.
+ *
+ * The whole registry read is preview-safe, so no `mutation.preview` gating is
+ * needed here (unlike `sources update`, whose heavy resolve must be gated).
+ * `run` returns `Promise<Task<R>>`, presented through the `Task<R>` arm by the
+ * honest cast at the verb (the `update.verb.ts` precedent).
+ */
+
+import { $, exec, gen, info, type Task, warn } from "@canonical/task";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import { assertExecOk, guardMissingBinary } from "../shared/assertExecOk.js";
+import {
+  detectInstallSource,
+  pmUpdateCommand,
+} from "../shared/packageManager.js";
+import { checkRegistryVersion, PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { UpgradeData } from "./types.js";
+
+/**
+ * Resolve the upgrade state and compose the corresponding Task.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A Task yielding the upgrade outcome (its exec runs only on a real,
+ *   update-needed execution).
+ * @note Impure — reads the config + the registry (the exec is the only mutation,
+ *   and it runs only under a real, update-needed execution).
+ */
+export async function runUpgrade(
+  rt: PragmaRuntime,
+): Promise<Task<UpgradeData>> {
+  const { channel } = (await rt.loadConfig()).config;
+  const install = detectInstallSource();
+  const command = pmUpdateCommand(install.pm, PRAGMA_PACKAGE);
+  const pm = install.label;
+  const current = rt.version;
+
+  const registry = await checkRegistryVersion(PRAGMA_PACKAGE, channel);
+
+  if (registry === undefined) {
+    const data: UpgradeData = {
+      pm,
+      current,
+      latest: undefined,
+      command,
+      offline: true,
+      alreadyLatest: false,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(
+        warn("Could not reach the registry — skipped the update check."),
+      );
+      return data;
+    });
+  }
+
+  if (registry.latest === current) {
+    const data: UpgradeData = {
+      pm,
+      current,
+      latest: registry.latest,
+      command,
+      offline: false,
+      alreadyLatest: true,
+      executed: false,
+    };
+    return gen(function* () {
+      yield* $(info(`Already at the latest version (${current}).`));
+      return data;
+    });
+  }
+
+  const data: UpgradeData = {
+    pm,
+    current,
+    latest: registry.latest,
+    command,
+    offline: false,
+    alreadyLatest: false,
+    executed: true,
+  };
+  const parts = command.split(" ");
+  const bin = parts[0] ?? "npm";
+  const args = parts.slice(1);
+  // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
+  // exec with ENOENT, which would collapse to INTERNAL_ERROR ("please report
+  // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
+  return guardMissingBinary(
+    bin,
+    {
+      message: `Install ${pm} (or your package manager) and ensure it is on your PATH, then try again.`,
+    },
+    gen(function* () {
+      // The version-delta rides a Log effect, so `--dry-run` describes it too.
+      yield* $(info(`${current} → ${registry.latest}`));
+      // The one mutation — mocked under dry-run, run for real under --yes/confirm.
+      // The interpreter RESOLVES on a nonzero exit (only a spawn error rejects),
+      // so inspect the result: a failed install (e.g. EACCES on a global
+      // `npm i -g`) must fail loudly, not report a silent success.
+      const result = yield* $(exec(bin, args, rt.cwd));
+      assertExecOk(command, result);
+      return data;
+    }),
+  );
+}

package/src/capabilities/upgrade/types.ts

@@ -0,0 +1,21 @@
+/**
+ * Data shape for `pragma upgrade`.
+ */
+
+/** The outcome of an upgrade run (or its plan). */
+export interface UpgradeData {
+  /** The install-source label (e.g. `bun (global)`). */
+  readonly pm: string;
+  /** The currently-installed version. */
+  readonly current: string;
+  /** The latest published version, or `undefined` when offline. */
+  readonly latest: string | undefined;
+  /** The package-manager command that applies the update. */
+  readonly command: string;
+  /** True when the registry could not be reached. */
+  readonly offline: boolean;
+  /** True when the installed version is already the latest. */
+  readonly alreadyLatest: boolean;
+  /** True when the update command was actually executed (a real run). */
+  readonly executed: boolean;
+}

package/src/capabilities/upgrade/upgrade.render.ts

@@ -0,0 +1,55 @@
+/**
+ * Formatters for `pragma upgrade` — plain (chalk), llm, json.
+ *
+ * Renders the REAL-run outcome (the `--dry-run` plan is rendered by the
+ * dispatcher's plan renderer, not here), so there is no "would run" branch: a
+ * needed run always carries `executed: true`.
+ */
+
+import chalk from "chalk";
+import type { Formatters } from "../../kernel/spec/types.js";
+import { PRAGMA_PACKAGE } from "../shared/registry.js";
+import type { UpgradeData } from "./types.js";
+
+export const upgradeFormatters: Formatters<UpgradeData> = {
+  plain(data) {
+    const lines = [`Installed via: ${data.pm}`];
+    if (data.offline) {
+      lines.push("Could not reach the registry — try again later.");
+      return lines.join("\n");
+    }
+    if (data.alreadyLatest) {
+      lines.push(`Already at the latest version (${data.current}).`);
+      return lines.join("\n");
+    }
+    lines.push(
+      "",
+      `${PRAGMA_PACKAGE}  ${data.current} → ${chalk.green(String(data.latest))}`,
+      "",
+    );
+    if (data.executed) {
+      lines.push(
+        `Ran: ${chalk.cyan(data.command)}`,
+        "",
+        `Updated to ${data.latest}.`,
+      );
+    } else {
+      lines.push(`Run: ${chalk.cyan(data.command)}`);
+    }
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    if (data.offline)
+      return "Upgrade check failed: could not reach the registry.";
+    if (data.alreadyLatest) {
+      return `Already at the latest version (${data.current}).`;
+    }
+    if (data.executed) return `Upgraded: ${data.current} → ${data.latest}`;
+    return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/upgrade/upgrade.test.ts

@@ -0,0 +1,372 @@
+/**
+ * `pragma upgrade` — the async-setup mutation whose sole effect is the exec.
+ *
+ * The real update command is NEVER spawned: offline / already-latest carry no
+ * exec (safe real runs); the update-needed path is asserted via `dryRun(task)`
+ * (which mocks the exec and exposes both the plan and the returned value); the
+ * exec-failure mapping is proven with a synthetic verb that RUNS a command
+ * exiting nonzero (plus an ENOENT case), exercising the `assertExecOk` guard the
+ * real consumers apply. Also covers the `checkRegistryVersion` unit contract and
+ * MCP plan-first/confirm.
+ */
+
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { $, dryRun, exec, gen, type Task } from "@canonical/task";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { VERSION } from "../../constants.js";
+import { asPragmaError } from "../../kernel/error/fromTaskError.js";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { mapExitCode } from "../../kernel/project/cli/exitCodes.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags, PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import {
+  assertExecOk,
+  guardMissingBinary,
+  isMissingBinaryError,
+} from "../shared/assertExecOk.js";
+import {
+  checkRegistryVersion,
+  REGISTRY_TIMEOUT_MS,
+} from "../shared/registry.js";
+import { runUpgrade } from "./runUpgrade.js";
+import type { UpgradeData } from "./types.js";
+import { upgradeModule } from "./upgrade.verb.js";
+
+const upgradeVerb = upgradeModule.verbs[0] as VerbSpec;
+const FLAGS_JSON: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+const REAL = { dryRun: false, undo: false, yes: true };
+const DRY = { dryRun: true, undo: false, yes: false };
+
+const roots: string[] = [];
+const tmpCwd = (): string => {
+  const dir = mkdtempSync(join(tmpdir(), "pragma-upgrade-"));
+  roots.push(dir);
+  return dir;
+};
+
+function stubRegistry(latest: string | "offline" | "notok"): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () => {
+      if (latest === "offline") throw new Error("network down");
+      if (latest === "notok") return { ok: false } as unknown as Response;
+      return {
+        ok: true,
+        json: async () => ({ "dist-tags": { latest } }),
+      } as unknown as Response;
+    }),
+  );
+}
+
+let prevXdg: string | undefined;
+beforeEach(() => {
+  prevXdg = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = tmpCwd();
+});
+afterEach(() => {
+  process.env.XDG_CONFIG_HOME = prevXdg;
+  vi.unstubAllGlobals();
+  for (const dir of roots) rmSync(dir, { recursive: true, force: true });
+  roots.length = 0;
+});
+
+async function realData(rt: PragmaRuntime): Promise<UpgradeData> {
+  const outcome = await executeVerb(upgradeVerb, {}, REAL, rt);
+  return JSON.parse(outcome.stdout as string).data as UpgradeData;
+}
+
+describe("checkRegistryVersion — unit contract", () => {
+  it("maps channels to dist-tags and encodes the scoped package in the URL", async () => {
+    const calls: { url: string; opts: RequestInit }[] = [];
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (url: string, opts: RequestInit) => {
+        calls.push({ url, opts });
+        return {
+          ok: true,
+          json: async () => ({
+            "dist-tags": {
+              latest: "1.0.0",
+              experimental: "1.1.0-exp",
+              next: "1.2.0-next",
+            },
+          }),
+        } as unknown as Response;
+      }),
+    );
+
+    // Each channel selects its dist-tag; the RETURNED version proves the
+    // mapping (normal→latest→1.0.0, etc.) — the dist-tag is internal now.
+    expect(
+      await checkRegistryVersion("@canonical/pragma-cli", "normal"),
+    ).toEqual({ latest: "1.0.0" });
+    expect(calls[0]?.url).toBe(
+      "https://registry.npmjs.org/%40canonical%2Fpragma-cli",
+    );
+    // The timeout is wired via AbortSignal.timeout(3000).
+    expect(calls[0]?.opts.signal).toBeInstanceOf(AbortSignal);
+    expect(REGISTRY_TIMEOUT_MS).toBe(3000);
+
+    expect((await checkRegistryVersion("x", "experimental"))?.latest).toBe(
+      "1.1.0-exp",
+    );
+    expect((await checkRegistryVersion("x", "prerelease"))?.latest).toBe(
+      "1.2.0-next",
+    );
+  });
+
+  it("returns undefined on a non-2xx response or an offline error", async () => {
+    stubRegistry("notok");
+    expect(await checkRegistryVersion("x", "normal")).toBeUndefined();
+    stubRegistry("offline");
+    expect(await checkRegistryVersion("x", "normal")).toBeUndefined();
+  });
+});
+
+describe("upgrade — offline & already-latest (no exec)", () => {
+  it("offline: no exec, offline data", async () => {
+    stubRegistry("offline");
+    const data = await realData(bootRuntime(FLAGS_JSON, tmpCwd()));
+    expect(data.offline).toBe(true);
+    expect(data.executed).toBe(false);
+    expect(data.latest).toBeUndefined();
+  });
+
+  it("already-latest: no exec, alreadyLatest data", async () => {
+    stubRegistry(VERSION);
+    const data = await realData(bootRuntime(FLAGS_JSON, tmpCwd()));
+    expect(data.alreadyLatest).toBe(true);
+    expect(data.executed).toBe(false);
+    expect(data.latest).toBe(VERSION);
+  });
+});
+
+describe("upgrade — update needed", () => {
+  it("--dry-run lists the version delta and the Execute command, running nothing", async () => {
+    stubRegistry("99.0.0");
+    const outcome = await executeVerb(
+      upgradeVerb,
+      {},
+      DRY,
+      bootRuntime(FLAGS_JSON, tmpCwd()),
+    );
+    const plan = JSON.parse(outcome.stdout as string).data.plan as string[];
+    expect(plan.some((line) => line.includes(`${VERSION} → 99.0.0`))).toBe(
+      true,
+    );
+    expect(
+      plan.some(
+        (line) =>
+          line.startsWith("Execute:") && line.includes("@canonical/pragma-cli"),
+      ),
+    ).toBe(true);
+  });
+
+  it("the composed task returns executed:true (exec mocked under dry-run)", async () => {
+    stubRegistry("99.0.0");
+    const task = await runUpgrade(bootRuntime(FLAGS_JSON, tmpCwd()));
+    const { value } = dryRun(task);
+    expect(value.executed).toBe(true);
+    expect(value.latest).toBe("99.0.0");
+    expect(value.alreadyLatest).toBe(false);
+  });
+});
+
+describe("assertExecOk — the exec-exitCode guard", () => {
+  it("returns on a zero exit and throws an actionable UNSUPPORTED (with stderr) on nonzero", () => {
+    expect(() =>
+      assertExecOk("cmd", { stdout: "", stderr: "", exitCode: 0 }),
+    ).not.toThrow();
+
+    let thrown: unknown;
+    try {
+      assertExecOk("npm i -g @canonical/pragma-cli", {
+        stdout: "",
+        stderr: "  npm ERR! code EACCES  ",
+        exitCode: 13,
+      });
+    } catch (error) {
+      thrown = error;
+    }
+    const err = asPragmaError(thrown);
+    // A denied `npm i -g` is user-fixable, NOT a bug — so it must not tell the
+    // user to "please report this issue" (that is INTERNAL_ERROR's recovery).
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(err.recovery?.message).not.toContain("report this issue");
+    expect(err.recovery?.message).toMatch(/permissions or network/i);
+    // Surfaces the command + exit code + the captured stderr (trimmed).
+    expect(err.message).toContain("npm i -g @canonical/pragma-cli");
+    expect(err.message).toContain("code 13");
+    expect(err.message).toContain("npm ERR! code EACCES");
+  });
+});
+
+describe("upgrade — a failed exec maps to an actionable runtime error (exit 1)", () => {
+  // A minimal verb whose sole effect is the given exec seam — the same shape
+  // runUpgrade/setupLsp use (exec then assertExecOk), driven through dispatch.
+  const failVerbWith = (
+    run: (p: Record<string, unknown>, rt: PragmaRuntime) => Task<unknown>,
+  ): VerbSpec => {
+    const verb: VerbSpec<Record<string, unknown>, unknown> = {
+      path: ["failx"],
+      summary: "test",
+      params: [],
+      output: {
+        formatters: { plain: () => "", llm: () => "", json: () => "{}" },
+      },
+      capability: {
+        needsStore: false,
+        mutates: true,
+        mcp: { expose: false, reason: "test" },
+      },
+      run,
+    };
+    return verb as VerbSpec;
+  };
+
+  const runToError = async (verb: VerbSpec): Promise<unknown> => {
+    try {
+      await executeVerb(verb, {}, REAL, bootRuntime(FLAGS_JSON, tmpCwd()));
+    } catch (error) {
+      return error;
+    }
+    return undefined;
+  };
+
+  it("a command that RUNS and exits nonzero is surfaced, not silently succeeded", async () => {
+    // The interpreter RESOLVES exec on a nonzero exit (only ENOENT rejects), so
+    // the guard the consumers apply (assertExecOk) is what turns a failed
+    // install into a failure. Without that guard this verb would return {} —
+    // the masked "silent false success" the old ENOENT-only test never caught.
+    const thrown = await runToError(
+      failVerbWith(
+        (_p, rt) =>
+          gen(function* () {
+            const result = yield* $(
+              exec(
+                "sh",
+                ["-c", "echo boom-from-installer >&2; exit 7"],
+                rt.cwd,
+              ),
+            );
+            assertExecOk("sh -c 'exit 7'", result);
+            return {};
+          }) as Task<unknown>,
+      ),
+    );
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    // A command that RAN and failed is user-fixable (permissions/network), so
+    // it is UNSUPPORTED (exit 1) with an actionable recovery — not a bug report.
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(mapExitCode(err.code)).toBe(1);
+    // The subprocess's own stderr is surfaced, not discarded.
+    expect(err.message).toContain("boom-from-installer");
+    expect(err.message).toContain("code 7");
+  });
+
+  it("a missing-binary spawn (ENOENT) at a guarded site is a named UNSUPPORTED, not INTERNAL_ERROR", async () => {
+    // The same wrapper `runUpgrade`/`setupLsp` apply: a spawn ENOENT REJECTS the
+    // exec, which used to collapse to INTERNAL_ERROR ("please report this issue").
+    // `guardMissingBinary` names it instead.
+    const thrown = await runToError(
+      failVerbWith((_p, rt) =>
+        guardMissingBinary(
+          "pragma-nonexistent-binary-xyz",
+          { message: "Install it and ensure it is on your PATH." },
+          gen(function* () {
+            yield* $(exec("pragma-nonexistent-binary-xyz", [], rt.cwd));
+            return {};
+          }) as Task<unknown>,
+        ),
+      ),
+    );
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    // NOT INTERNAL_ERROR — a named environment condition with actionable recovery.
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(mapExitCode(err.code)).toBe(1);
+    expect(err.message).toContain("pragma-nonexistent-binary-xyz");
+    expect(err.message).toMatch(/not found on your PATH/i);
+    expect(err.recovery?.message).not.toContain("report this issue");
+    expect(err.recovery?.message).toMatch(/PATH/);
+  });
+
+  it("guardMissingBinary is transparent to a nonzero exit (still assertExecOk's UNSUPPORTED)", async () => {
+    // A command that RUNS and exits nonzero RESOLVES the effect; assertExecOk's
+    // synchronous throw bypasses the guard's effect-failure handler, so the
+    // subprocess stderr is preserved (not masked as a missing binary).
+    const thrown = await runToError(
+      failVerbWith((_p, rt) =>
+        guardMissingBinary(
+          "sh",
+          { message: "unused" },
+          gen(function* () {
+            const result = yield* $(
+              exec("sh", ["-c", "echo boom >&2; exit 7"], rt.cwd),
+            );
+            assertExecOk("sh -c 'exit 7'", result);
+            return {};
+          }) as Task<unknown>,
+        ),
+      ),
+    );
+    const err = asPragmaError(thrown);
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(err.message).toContain("boom");
+    expect(err.message).toContain("code 7");
+    expect(err.message).not.toMatch(/not found on your PATH/i);
+  });
+});
+
+describe("isMissingBinaryError — ENOENT recognition (raw + normalised)", () => {
+  it("recognises a raw spawn ENOENT and the interpreter's normalised TaskError", () => {
+    // Raw spawn reject (Node/Bun) carries `.code === "ENOENT"`.
+    expect(isMissingBinaryError({ code: "ENOENT" })).toBe(true);
+    // The task interpreter normalises it to FILE_NOT_FOUND, tucking the raw spawn
+    // error under `.cause` — unwrap one level.
+    expect(
+      isMissingBinaryError({
+        code: "FILE_NOT_FOUND",
+        cause: { code: "ENOENT", syscall: "spawn npm" },
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects unrelated errors", () => {
+    expect(isMissingBinaryError({ code: "EACCES" })).toBe(false);
+    expect(isMissingBinaryError(new Error("boom"))).toBe(false);
+    expect(isMissingBinaryError(undefined)).toBe(false);
+    expect(isMissingBinaryError("nope")).toBe(false);
+  });
+});
+
+describe("upgrade — MCP plan-first / confirm", () => {
+  it("returns a plan without confirm (needed), and runs safely with confirm when up-to-date", async () => {
+    stubRegistry("99.0.0");
+    const mcp = await projectMcp([upgradeModule], tmpCwd());
+    const plan = await mcp.callTool("upgrade");
+    expect(plan.ok).toBe(true);
+    expect(plan.meta).toMatchObject({ planOnly: true, confirmRequired: true });
+    const planLines = (plan.data as { plan: string[] }).plan;
+    expect(planLines.some((line) => line.startsWith("Execute:"))).toBe(true);
+    await mcp.cleanup();
+
+    // confirm:true with an up-to-date registry runs for real WITHOUT an exec.
+    stubRegistry(VERSION);
+    const mcp2 = await projectMcp([upgradeModule], tmpCwd());
+    const done = await mcp2.callTool("upgrade", { confirm: true });
+    await mcp2.cleanup();
+    expect(done.ok).toBe(true);
+    expect(done.data).toMatchObject({ alreadyLatest: true, executed: false });
+  });
+});