@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/capabilities/doctor/checks/harnessInventory.test.ts

@@ -20,10 +20,15 @@ import {
   type WriteState,
 } from "./harnessInventory.js";
 
+// Roo Code is the `unscoped` example: it is `scope: "project"`, so it can
+// never hold a global entry. VS Code used to stand here and stopped being an
+// example of anything when its per-user `mcp.json` was added — it is
+// `scope: "both"` now, and a fixture claiming otherwise would pin a fact the
+// registry no longer holds.
 const REGISTRY: InventoryHarness[] = [
   { id: "claude-code", name: "Claude Code", inScope: true },
   { id: "cursor", name: "Cursor", inScope: true },
-  { id: "vscode", name: "VS Code", inScope: false },
+  { id: "roo-code", name: "Roo Code", inScope: false },
 ];
 
 /** One harness's share of a file — its OWN write's state, never the file's. */
@@ -50,7 +55,7 @@ describe("harnessInventory — the roll-up", () => {
       "cursor:detected",
       // Not detected AND has no location in this scope at all — the two are
       // different facts and the row says which one applies.
-      "vscode:unscoped",
+      "roo-code:unscoped",
     ]);
     expect(rows[0]?.locations).toEqual(["~/.claude.json"]);
     expect(rows[2]?.locations).toEqual([]);
@@ -58,12 +63,14 @@ describe("harnessInventory — the roll-up", () => {
 
   it("keeps 'undetected' and 'unscoped' apart", () => {
     // Same absence, two different reasons: Cursor could be here and is not,
-    // VS Code could never be here at all.
+    // Roo Code could never be here at all.
     const rows = roll([]);
     expect(rows.find((r) => r.harnessId === "cursor")?.state).toBe(
       "undetected",
     );
-    expect(rows.find((r) => r.harnessId === "vscode")?.state).toBe("unscoped");
+    expect(rows.find((r) => r.harnessId === "roo-code")?.state).toBe(
+      "unscoped",
+    );
   });
 
   it("reports a drifted group as drifted, not as registered", () => {
@@ -158,11 +165,11 @@ describe("harnessInventory — the listing", () => {
     expect(items.map((i) => i.label)).toEqual([
       "Claude Code",
       "Cursor",
-      "VS Code",
+      "Roo Code",
     ]);
     expect(items[1]?.detail).toBe("not detected");
     // Scope-aware, and it states the FACT rather than naming a partition:
-    // VS Code keeps its MCP config per project, so there is no global file for
+    // Roo Code keeps its MCP config per project, so there is no global file for
     // pragma to be in. `no Global band` named an internal word for that.
     expect(items[2]?.detail).toBe(
       "keeps no global config — it is per-project only",

package/src/capabilities/doctor/checks/harnessInventory.ts

@@ -68,9 +68,13 @@ import type { CheckItem, CheckStatus, Scope } from "../types.js";
  * - `detected` — the harness is on this machine; pragma is not registered.
  * - `undetected` — in the registry, has a location in this scope, not found.
  * - `unscoped` — in the registry, but has NO config location in this scope at
- *   all (VS Code is `scope: "project"`, so it can never hold a global entry).
- *   Stated rather than omitted: a verbose listing that silently dropped a row
- *   reads as a bug in the listing.
+ *   all. Roo Code and Cline are `scope: "project"`, so neither can ever hold a
+ *   global entry: Cline is a VS Code EXTENSION whose config is the workspace
+ *   `.vscode/mcp.json`, and Roo Code's is `.roo/mcp.json` — neither keeps a
+ *   per-user file of its own. (VS Code itself used to be the example here, and
+ *   stopped being one when its per-user `mcp.json` was added: it is
+ *   `scope: "both"` now.) Stated rather than omitted: a verbose listing that
+ *   silently dropped a row reads as a bug in the listing.
  */
 export type InventoryState =
   | "registered"
@@ -202,7 +206,7 @@ const STATE_STATUS: Record<InventoryState, CheckStatus> = {
  *
  * The unscoped line says WHERE the harness keeps its config rather than naming
  * an internal partition. `no Global band` told the reader nothing: "band" was
- * this repository's word, and the fact underneath it — VS Code stores its MCP
+ * this repository's word, and the fact underneath it — Roo Code stores its MCP
  * config per project, so there is no global file for pragma to be in — is the
  * thing that explains the row.
  */

package/src/capabilities/doctor/checks/isSupportedNodeVersion.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Pins the hand-written comparison in `isSupportedNodeVersion` to the range the
+ * package actually declares.
+ *
+ * The implementation encodes `engines.node` as a chain of comparisons rather
+ * than parsing it, so nothing structural stops the two drifting apart. This
+ * suite closes that by building a SECOND, independent predicate directly from
+ * the declared range string and requiring both to agree across a version grid.
+ * A change to `engines.node` therefore moves the oracle and fails here until the
+ * implementation is moved with it — which a table of hand-written expectations
+ * could not do, since its cheapest repair is editing the expectations.
+ */
+
+import { describe, expect, it } from "vitest";
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
+import { isSupportedNodeVersion } from "./isSupportedNodeVersion.js";
+
+/**
+ * Evaluate a version against a range of the form `>=22.18 <23 || >=23.6`.
+ *
+ * Deliberately naive and deliberately separate from the implementation: it is
+ * an oracle, not a utility, and it throws on any comparator shape it was not
+ * written for so a widened range fails loudly instead of silently passing.
+ */
+function satisfiesDeclaredRange(version: string, range: string): boolean {
+  // Semver excludes prereleases from a range unless a comparator opts in, and
+  // none of ours does. Encoded here too, so the oracle and the implementation
+  // are held to the same rule rather than agreeing by omission.
+  if (version.includes("-")) return false;
+
+  const rank = (major: number, minor: number) => major * 1_000_000 + minor;
+  const [major = Number.NaN, minor = Number.NaN] = version
+    .split(".")
+    .map(Number);
+
+  return range.split("||").some((clause) =>
+    clause
+      .trim()
+      .split(/\s+/)
+      .every((comparator) => {
+        // A comparator may be major-only (`<23`) or major.minor (`>=22.18`).
+        const parsed = /^(>=|<)(\d+)(?:\.(\d+))?$/.exec(comparator);
+        if (!parsed)
+          throw new Error(`oracle cannot parse comparator: ${comparator}`);
+        const [, operator, boundMajor, boundMinor] = parsed;
+        const actual = rank(major, minor);
+        const bound = rank(Number(boundMajor), Number(boundMinor ?? 0));
+        return operator === ">=" ? actual >= bound : actual < bound;
+      }),
+  );
+}
+
+const GRID = [
+  "20.19.0",
+  "21.7.3",
+  "22.0.0",
+  "22.12.0",
+  "22.17.9",
+  "22.18.0",
+  "22.18.1",
+  "22.99.0",
+  "23.0.0",
+  "23.5.9",
+  "23.6.0",
+  "23.9.0",
+  "24.0.0",
+  "24.18.1",
+  "25.0.0",
+  "26.0.0",
+  // Prereleases: numerically inside the range, excluded by semver.
+  "22.18.0-pre",
+  "23.6.0-nightly",
+  "24.0.0-rc.1",
+];
+
+describe("isSupportedNodeVersion — agrees with the declared engines range", () => {
+  it.each(GRID)("matches the oracle for %s", (version) => {
+    expect(isSupportedNodeVersion(version)).toBe(
+      satisfiesDeclaredRange(version, SUPPORTED_NODE_RANGE),
+    );
+  });
+
+  // The oracle is only trustworthy if it can disagree; prove it discriminates
+  // rather than returning a constant.
+  it("uses an oracle that actually discriminates", () => {
+    const verdicts = GRID.map((v) =>
+      satisfiesDeclaredRange(v, SUPPORTED_NODE_RANGE),
+    );
+    expect(verdicts).toContain(true);
+    expect(verdicts).toContain(false);
+  });
+
+  it("rejects prerelease builds whose numeric part is in range", () => {
+    // Asserted directly, not only through the oracle: if both sides dropped the
+    // rule together the grid would still agree and prove nothing.
+    for (const pre of ["22.18.0-pre", "23.6.0-nightly", "24.0.0-rc.1"]) {
+      expect(isSupportedNodeVersion(pre)).toBe(false);
+    }
+    // The same versions without the suffix are supported, so it is the suffix
+    // doing the work and not the numbers.
+    for (const stable of ["22.18.0", "23.6.0", "24.0.0"]) {
+      expect(isSupportedNodeVersion(stable)).toBe(true);
+    }
+  });
+
+  it("fails closed on a version it cannot parse", () => {
+    for (const bad of ["not-a-version", "", "v24.1.0", "24"]) {
+      expect(isSupportedNodeVersion(bad)).toBe(false);
+    }
+  });
+});

package/src/capabilities/doctor/checks/isSupportedNodeVersion.ts

@@ -0,0 +1,34 @@
+/**
+ * Whether a Node.js version satisfies the range this package declares in its
+ * own `engines.node`, surfaced as `SUPPORTED_NODE_RANGE` in `constants.ts`.
+ *
+ * The range is expressed here as a comparison rather than parsed: the CLI
+ * carries no semver dependency, and one range does not justify a range parser.
+ * What keeps the two honest is `isSupportedNodeVersion.test.ts`, which builds an
+ * independent predicate straight from the declared range string and requires
+ * the two to agree across a version grid — so a change to `engines.node` that
+ * is not mirrored here fails the suite rather than shipping.
+ *
+ * A major-only comparison cannot express this range: it cannot say "22.18 but
+ * not 22.0", and it cannot exclude the 23.0–23.5 window.
+ *
+ * @param version - A Node version string, e.g. `process.versions.node`.
+ * @returns Whether the version falls inside the declared range.
+ */
+export function isSupportedNodeVersion(version: string): boolean {
+  // A semver range excludes prereleases unless a comparator opts into them, and
+  // `engines.node` opts into none. So `22.18.0-pre` is outside the declared
+  // range even though its numeric part is inside it, and reporting it as
+  // supported would be doctor passing a runtime the install contract rejects.
+  if (version.includes("-")) return false;
+
+  const [rawMajor, rawMinor] = version.split(".");
+  const major = Number(rawMajor);
+  const minor = Number(rawMinor);
+
+  if (!Number.isInteger(major) || !Number.isInteger(minor)) return false;
+  if (major < 22) return false;
+  if (major === 22) return minor >= 18;
+  if (major === 23) return minor >= 6;
+  return true;
+}

package/src/capabilities/doctor/checks/mcpCommand.test.ts

@@ -45,6 +45,12 @@ describe("commandOf — one executable, either entry shape", () => {
   });
 });
 
+// Every test in this suite writes into a temp directory and then resolves
+// against it, so each one is bound by filesystem latency rather than by any
+// work of its own. Vitest's 5s default is comfortable on an idle machine and
+// marginal on a loaded one — this suite has timed out in CI while asserting
+// nothing slow. Ten seconds keeps the assertions meaningful without making a
+// genuine hang cheap to ignore.
 describe("commandResolves — the host's own resolution rules", () => {
   const dirs: string[] = [];
   const tmp = (): string => {
@@ -97,4 +103,4 @@ describe("commandResolves — the host's own resolution rules", () => {
       await commandResolves("./local-bin", dir, hostOf("linux", dir)),
     ).toBe(true);
   });
-});
+}, 10_000);

package/src/capabilities/doctor/checks/targetHealth.ts

@@ -38,17 +38,26 @@ import type {
   ConfigDetection,
 } from "../../setup/operations/index.js";
 import {
+  blockedMcpGroups,
+  describeEditorSource,
+  type FsProbe,
+  firstLspBlock,
+  firstMcpBlock,
+  installableEditors,
+  LSP_SKIP_REMEDY,
   type LspDetection,
+  lspBlockReason,
   lspEditorNames,
   lspSkipReason,
   type McpDetection,
+  mcpBlockReason,
   mcpGroupState,
   mcpWriteState,
   type SkillsDetection,
   skillsSkipReason,
   skillsSkipRemedy,
 } from "../../setup/operations/index.js";
-import { shortenPath, TARGET_IDS } from "../../setup/plan.js";
+import { type Roots, shortenPath, TARGET_IDS } from "../../setup/plan.js";
 import { MCP_NO_LOCATION } from "../../setup/targets.js";
 import type { CheckItem, CheckResult, Scope } from "../types.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
@@ -88,15 +97,78 @@ const configHealth = (
   return { status: "pass", detail: `${path} — valid` };
 };
 
-/** The `lsp` row — the first this report has ever had. */
-const lspHealth = (d: LspDetection): Health => {
+/**
+ * The `lsp` row: one sub-item per editor, saying HOW it was found and where
+ * pragma stands in it.
+ *
+ * Provenance per editor is the point. A colleague whose macOS `setup lsp`
+ * reported nothing had VS Code installed the whole time, and a one-line row
+ * ("not installed in …", or a bare skip) could not tell them whether pragma had
+ * missed the editor or found it and could not act. Per the owner, 2026-09-16,
+ * this report says per editor how it was found and why a step was skipped.
+ *
+ * The row's own status keeps the report's invariant that every `available` row
+ * has a remedy: any editor that CAN be installed into makes the row
+ * `available`, whose derived fix is `pragma setup lsp`. A row where NOTHING is
+ * installed and nothing is installable is a `skip` carrying the first block's
+ * own remedy — a Nix declaration, a `chmod`, or the palette command — never
+ * the derived command, which would only reproduce the skip.
+ *
+ * An INSTALLED editor is a `pass` even when its extensions folder is blocked.
+ * The copy is there and works; the block only says this command cannot CHANGE
+ * it. Reporting a skip instead told the owner of a site-managed folder that
+ * already held the extension to chmod it and install again, and made a machine
+ * that is installed everywhere it can be a permanent `○ lsp`.
+ */
+const lspHealth = (d: LspDetection, roots: Roots): Health => {
   if (d.state === "unknown") {
-    return { status: "skip", detail: lspSkipReason(d) };
+    return {
+      status: "skip",
+      detail: lspSkipReason(d),
+      remedy: LSP_SKIP_REMEDY,
+    };
+  }
+  const items: CheckItem[] = d.editors.map((e): CheckItem => {
+    const reason = e.installed ? undefined : lspBlockReason(e);
+    const state = reason ?? (e.installed ? "installed" : "not installed");
+    return {
+      label: e.editor.name,
+      status: e.installed
+        ? "pass"
+        : reason !== undefined
+          ? "skip"
+          : "available",
+      detail: `${describeEditorSource(e, roots)} · ${state}`,
+    };
+  });
+  const installable = installableEditors(d);
+  if (installable.length > 0) {
+    return {
+      status: "available",
+      detail: `not installed in ${installable.map((e) => e.editor.name).join(", ")}`,
+      items,
+    };
+  }
+  // Nothing installable. The row is the block's only when nothing is installed
+  // either — otherwise the honest headline is what IS in place.
+  const block = d.editors.some((e) => e.installed)
+    ? undefined
+    : firstLspBlock(d);
+  if (block !== undefined) {
+    return {
+      status: "skip",
+      // The headline names the editor; the item's own detail does not, because
+      // its label already has.
+      detail: block.headline,
+      items,
+      remedy: block.remedy,
+    };
   }
-  const editors = lspEditorNames(d).join(", ");
-  return d.state === "installed"
-    ? { status: "pass", detail: `installed in ${editors}` }
-    : { status: "available", detail: `not installed in ${editors}` };
+  return {
+    status: "pass",
+    detail: `installed in ${lspEditorNames(d).join(", ")}`,
+    items,
+  };
 };
 
 /**
@@ -118,6 +190,12 @@ async function mcpHealth(
   const items: CheckItem[] = d.groups.map((group) => {
     const state = mcpGroupState(d, group.path);
     const label = shortenPath(group.path, roots);
+    // A file pragma must not write is reported as a skip, not as an
+    // `available` whose `fix:` would fail the moment it ran.
+    const blocked = mcpBlockReason(d, group, roots);
+    if (blocked !== undefined) {
+      return { label, status: "skip" as const, detail: blocked };
+    }
     if (state === "absent") {
       return { label, status: "available", detail: "not registered" };
     }
@@ -132,6 +210,22 @@ async function mcpHealth(
         : `registered, but \`${MCP_SERVER_NAME}\` is not on PATH`,
     };
   });
+  // Every location blocked means the row's whole answer is the block: it
+  // carries the first one's remedy — the entry to declare by hand — rather than
+  // the derived `pragma setup mcp`, which would only reproduce the skip.
+  const blockedGroups = blockedMcpGroups(d);
+  const block =
+    blockedGroups.length === d.groups.length
+      ? firstMcpBlock(d, roots)
+      : undefined;
+  if (block !== undefined) {
+    return {
+      status: "skip",
+      detail: block.reason,
+      items,
+      remedy: block.remedy,
+    };
+  }
   const configured = items.filter((item) => item.status === "pass").length;
   const failing = items.filter((item) => item.status === "fail").length;
   if (failing > 0) {
@@ -141,6 +235,7 @@ async function mcpHealth(
       items,
     };
   }
+  const writable = items.length - blockedGroups.length;
   if (configured === 0) {
     // Absence in the LOCAL PROJECT is not a failure: registering there is
     // opt-in, so a repository with no checked-in MCP config is healthy. The
@@ -153,13 +248,13 @@ async function mcpHealth(
         }
       : {
           status: "available",
-          detail: `not registered in any of ${items.length} config files`,
+          detail: `not registered in any of ${writable} config files`,
           items,
         };
   }
   return {
-    status: configured === items.length ? "pass" : "available",
-    detail: `registered in ${configured} of ${items.length} config files`,
+    status: configured === writable ? "pass" : "available",
+    detail: `registered in ${configured} of ${writable} config files`,
     items,
   };
 }
@@ -267,7 +362,7 @@ async function healthOf(
       };
     }
     case "lsp":
-      return lspHealth(row.detection as LspDetection);
+      return lspHealth(row.detection as LspDetection, roots);
     case "mcp":
       return mcpHealth(row.detection as McpDetection, row.scope, rt.cwd, roots);
     default:
@@ -406,15 +501,21 @@ export const fixCommandFor = (id: string, scope: Scope, bin: string): string =>
  *
  * @param rt - The per-invocation runtime.
  * @param bin - The binary name the `fix:` lines are derived from.
+ * @param probe - The writability filesystem seam, threaded to every row's
+ *   detection. Defaults to the real one; a test injects a fixture to reach the
+ *   blocked arms — a `/nix/store` path, a directory that refuses `W_OK` —
+ *   through THIS entry point, rather than opening the row bodies up as exports
+ *   nothing in production would call.
  * @returns One {@link CheckResult} per (target, scope), plus one per scope.
  * @note Impure — every target's detection reads the real filesystem.
  */
 export async function scopedChecks(
   rt: PragmaRuntime,
   bin: string,
+  probe?: FsProbe,
 ): Promise<CheckResult[]> {
   const roots = await resolveRoots(rt);
-  const detected = await detectTargets(rt, [...TARGET_IDS], "both");
+  const detected = await detectTargets(rt, [...TARGET_IDS], "both", probe);
   const [targetRows, inventoryRows] = await Promise.all([
     Promise.all(
       detected.map(async (row): Promise<CheckResult> => {