@canonical/pragma-cli 0.31.0 → 0.33.0

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 });
+  });
+});

package/src/capabilities/upgrade/upgrade.verb.ts

@@ -0,0 +1,56 @@
+/**
+ * The `upgrade` verb spec (noun `upgrade`, self-verb).
+ *
+ * A storeless, network-touching mutation: check the registry, then run the
+ * package-manager update. `destructive: false` is load-bearing (D4) — upgrading
+ * replaces the binary, it destroys no user data — so `annotationsFor` emits
+ * `destructiveHint: false` rather than letting MCP clients default an unset hint
+ * on a non-read-only tool to `true`.
+ *
+ * `run` returns `Promise<Task<UpgradeData>>` (async registry read before the
+ * effects are known) presented through the `Task<R>` arm by the honest cast —
+ * the `update.verb.ts` precedent; a literal `Promise<Task>` union arm would
+ * poison async read-verb inference.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import type { UpgradeData } from "./types.js";
+import { upgradeFormatters } from "./upgrade.render.js";
+
+const upgradeVerb: VerbSpec<Record<string, unknown>, UpgradeData> = {
+  path: ["upgrade"],
+  summary: "Upgrade the pragma CLI to the latest version.",
+  doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
+  params: [],
+  output: { formatters: upgradeFormatters },
+  examples: [
+    { cmd: "pragma upgrade" },
+    { cmd: "pragma upgrade --dry-run", note: "show the delta and the command" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    destructive: false,
+    needsNetwork: true,
+    mcp: {
+      expose: true,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./runUpgrade.js").then((m) =>
+      m.runUpgrade(runtime),
+    ) as unknown as Task<UpgradeData>,
+};
+
+/** The `upgrade` capability module. */
+export const upgradeModule: CapabilityModule = {
+  name: "upgrade",
+  verbs: [asVerb(upgradeVerb)],
+};

package/src/constants.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import {
+  BIN_NAME,
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  MCP_SERVER_NAME,
+  OUTPUT_FORMATS,
+  PROGRAM_DESCRIPTION,
+  RECOVERY_CLI_PREFIX,
+  VERSION,
+} from "./constants.js";
+
+describe("constants", () => {
+  it("names the v2 bin and the MCP server pragma", () => {
+    expect(BIN_NAME).toBe("pragma");
+    expect(MCP_SERVER_NAME).toBe("pragma");
+  });
+
+  it("reads a semver version from package.json", () => {
+    expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("keeps the recovery prefix on the stable command name (D5)", () => {
+    expect(RECOVERY_CLI_PREFIX).toBe("pragma ");
+  });
+
+  it("exposes the stable output formats and detail levels", () => {
+    expect(OUTPUT_FORMATS).toEqual(["plain", "llm", "json"]);
+    expect(DETAIL_LEVELS).toEqual(["summary", "standard", "detailed"]);
+    expect(DETAIL_LEVELS).toContain(DEFAULT_DETAIL_LEVEL);
+    expect(PROGRAM_DESCRIPTION.length).toBeGreaterThan(0);
+  });
+});

package/src/constants.ts

@@ -1,91 +1,59 @@
 /**
- * Package-level constants for the pragma CLI.
+ * Package-level constants for the pragma v2 kernel.
  *
- * Groups program metadata (name, version, description), release channel
- * definitions, and the cross-ontology property resolution map shared
- * by MCP resources and domain operations.
+ * Program metadata (bin name, MCP server name, description, version) plus the
+ * stable cross-cutting enums (output formats, detail levels). The CLI binary
+ * and the MCP server share the single `pragma` identity, so existing agent
+ * wiring keeps resolving the server unchanged.
  */
 
 import pkg from "../package.json" with { type: "json" };
-// DEFAULT_PREFIX_MAP carries the transitional DS prefixes (ds/cs) this map
-// still keys on; remove in P4 when DS prefixes ship from their packages.
-import { DEFAULT_PREFIX_MAP as PREFIX_MAP } from "./domains/shared/prefixes.js";
 
-/** CLI program name used in help text and error messages. */
-const PROGRAM_NAME = "pragma";
+/** CLI binary name for the v2 kernel (installed as `pragma`). */
+const BIN_NAME = "pragma";
 
-/** One-line program description for help text. */
+/**
+ * MCP server identity — `pragma`, matching the CLI bin, so agents already
+ * pointed at the pragma server resolve it unchanged.
+ */
+const MCP_SERVER_NAME = "pragma";
+
+/** One-line program description for help and server metadata. */
 const PROGRAM_DESCRIPTION = "CLI and MCP server for Canonical's design system.";
 
 /** Semver version string read from package.json. */
-const VERSION = pkg.version;
+const VERSION: string = pkg.version;
 
-/** Allowed release channel values for the `channel` config field. */
-const VALID_CHANNELS = ["normal", "experimental", "prerelease"] as const;
+/**
+ * Literal prefix for every `recovery.cli` hint (`pragma `): recovery strings
+ * quote the stable, documented command name — matching the bin (D5). The
+ * recovery invariant test enforces this.
+ */
+const RECOVERY_CLI_PREFIX = "pragma ";
 
-/** A release channel name. */
-type Channel = (typeof VALID_CHANNELS)[number];
+/** The output formats the renderer selects between (`llm` = condensed Markdown). */
+const OUTPUT_FORMATS = ["plain", "llm", "json"] as const;
 
-/** Allowed values for the `framework` config field. */
-const VALID_FRAMEWORKS = ["react", "svelte", "lit"] as const;
+/** A selected output format. `--format text` is normalised to `plain`. */
+type OutputFormat = (typeof OUTPUT_FORMATS)[number];
 
-/**
- * A preferred UI framework. Currently advisory only (a no-op); reserved for
- * future use to default framework-specific behaviour (e.g. which generator
- * `pragma`/`summon` scaffolds, which component tier is surfaced).
- */
-type Framework = (typeof VALID_FRAMEWORKS)[number];
+/** Progressive-disclosure levels, least to most detail. */
+const DETAIL_LEVELS = ["summary", "standard", "detailed"] as const;
 
-/**
- * Per-namespace property URIs for semantically equivalent fields.
- * Each ontology uses different property names for the same concept
- * (name/label, description/summary/comment).
- */
-interface OntologyPropertyMap {
-  readonly label: string;
-  readonly description?: string;
-  readonly definition?: string;
-}
+/** A progressive-disclosure level. */
+type DetailLevel = (typeof DETAIL_LEVELS)[number];
 
-/**
- * Maps namespace prefix → property URIs for human-readable label and
- * description. Used by MCP resource handlers and domain operations to
- * resolve cross-ontology properties uniformly.
- */
-const PROPERTY_MAP: Record<string, OntologyPropertyMap> = {
-  ds: {
-    label: `${PREFIX_MAP.ds}name`,
-    description: `${PREFIX_MAP.ds}summary`,
-    definition: `${PREFIX_MAP.ds}definition`,
-  },
-  cs: {
-    label: `${PREFIX_MAP.cs}name`,
-    description: `${PREFIX_MAP.cs}description`,
-    definition: `${PREFIX_MAP.cs}definition`,
-  },
-  rdfs: {
-    label: `${PREFIX_MAP.rdfs}label`,
-    description: `${PREFIX_MAP.rdfs}comment`,
-  },
-  owl: {
-    label: `${PREFIX_MAP.rdfs}label`,
-    description: `${PREFIX_MAP.rdfs}comment`,
-  },
-  skos: {
-    label: `${PREFIX_MAP.skos}prefLabel`,
-    definition: `${PREFIX_MAP.skos}definition`,
-  },
-  anatomy: {
-    label: `${PREFIX_MAP.ds}name`,
-  },
-};
+/** Default detail level when neither flag, config, nor spec pins one. */
+const DEFAULT_DETAIL_LEVEL: DetailLevel = "standard";
 
-export type { Channel, Framework, OntologyPropertyMap };
+export type { DetailLevel, OutputFormat };
 export {
+  BIN_NAME,
+  DEFAULT_DETAIL_LEVEL,
+  DETAIL_LEVELS,
+  MCP_SERVER_NAME,
+  OUTPUT_FORMATS,
   PROGRAM_DESCRIPTION,
-  PROGRAM_NAME,
-  PROPERTY_MAP,
-  VALID_CHANNELS,
-  VALID_FRAMEWORKS,
+  RECOVERY_CLI_PREFIX,
   VERSION,
 };