@canonical/pragma-cli 0.35.0 → 0.37.0

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

@@ -0,0 +1,298 @@
+/**
+ * The harness inventory: one row per harness per scope, saying what was detected
+ * and whether pragma is registered in it.
+ *
+ * Every fact this needs was ALREADY COMPUTED and thrown away.
+ * `TargetGroup.harnessNames` carries every harness sharing a config file and
+ * both consumers reduced it to `shortenPath(group.path)`; `McpDetection`
+ * carries the `absent`/`registered`/`drifted` classification of every WRITE in
+ * that file. The only thing detection could NOT answer is the negative —
+ * `detectHarnesses` filters to hits, so a harness the machine does not have was
+ * unrepresentable — which is why the roll-up takes the REGISTRY alongside the
+ * groups: the registry supplies the universe, the groups supply the state.
+ *
+ * The state arrives PER HARNESS, never per file. A shared `.vscode/mcp.json`
+ * holds VS Code's `servers` and Cline's `mcpServers` as two independent
+ * entries, so the file's aggregate — `drifted`, when one key is current and the
+ * other absent — is the standing of NEITHER harness. Pairing each name with
+ * the write it owns is the caller's job (it holds the registry's `mcpKey`s and
+ * the group's writes); by the time a group reaches this module the association
+ * is resolved and every name carries its own state.
+ *
+ * Three deliberate constraints:
+ *
+ * 1. **No `@canonical/harnesses` import, of any kind.** `capabilities/lazy.test`
+ *    forbids one from any file statically reachable from `capabilities/index`,
+ *    and its regex has no `import type` exemption. This module is reached only
+ *    through `runChecks`'s dynamic import today, but it is written so that
+ *    staying legal never depends on that: the inputs are declared here as
+ *    narrow structural records.
+ *
+ * 2. **Narrowed to DATA, so `mutates: false` is enforced rather than asserted.**
+ *    `McpDetection` is write-capable — it carries `writeMcpConfigTargets` and
+ *    `removeMcpConfigFrom` as live function references. Projecting it down to
+ *    {@link InventoryGroup} before it reaches this file means a read-only
+ *    report literally cannot reach a writer.
+ *
+ * 3. **It never invents a failure.** The states an inventory can report map onto
+ *    `pass`/`available`/`skip` and NEVER `fail` (see `../types.ts`): a machine
+ *    that simply does not have Windsurf is not a broken machine, and the `mcp`
+ *    row already owns the actionable finding for the harnesses it does have.
+ *    Reporting it twice is how a failure count becomes noise.
+ *
+ * Placement: this is a doctor helper because doctor is its only consumer today,
+ * and `shared/` is explicitly not a utility drawer (see `shared/index.ts`). It
+ * is written to MOVE there unchanged — pure, no capability imports beyond the
+ * scope type — the moment `setup`'s detection summary becomes the second caller.
+ */
+
+import type { CheckItem, CheckStatus, Scope } from "../types.js";
+
+/**
+ * What the inventory says about one harness in one scope.
+ *
+ * The vocabulary is deliberately NOT "installed". Two different claims used
+ * to share that word — `DetectedHarness.configExists` ("the harness's own
+ * config file exists", a harnesses-package field this module never surfaces)
+ * and the pragma-entry state (`McpTargetState`, which now says `registered`
+ * for exactly this reason). Every state here names the PRAGMA-ENTRY meaning.
+ * One name per claim, held across the reports: "installed" is reserved for
+ * artifacts the CLI itself places (the completion script, the LSP extension),
+ * "registered" for pragma's entry in someone else's config, "linked" for
+ * skill symlinks.
+ *
+ * - `registered` — detected, and pragma's MCP entry in this scope is current.
+ * - `drifted` — detected, and a pragma entry exists but differs from what a
+ *   write would emit. Actionable, but the `mcp` row is where it is actionED;
+ *   here it is reported without inflating the failure count.
+ * - `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.
+ */
+export type InventoryState =
+  | "registered"
+  | "drifted"
+  | "detected"
+  | "undetected"
+  | "unscoped";
+
+/** One harness's standing in one scope. */
+export interface InventoryRow {
+  readonly harnessId: string;
+  readonly harnessName: string;
+  readonly scope: Scope;
+  readonly state: InventoryState;
+  /** The config paths in this scope that carry (or would carry) the entry. */
+  readonly locations: readonly string[];
+}
+
+/** A registry entry, narrowed to what the roll-up reads. */
+export interface InventoryHarness {
+  readonly id: string;
+  readonly name: string;
+  /** Whether this harness has a config location in the scope being rolled up. */
+  readonly inScope: boolean;
+}
+
+/** The prior state of one harness's own write, as detection classified it. */
+export type WriteState = "absent" | "registered" | "drifted";
+
+/** One harness's share of a config file: the state of the write IT owns. */
+export interface InventoryMember {
+  readonly name: string;
+  readonly state: WriteState;
+}
+
+/**
+ * One detected config file, narrowed off {@link McpDetection}: the group's
+ * already-shortened path, and every harness sharing it WITH ITS OWN state.
+ *
+ * Per harness, not per file — see the module docblock. A file-level state here
+ * would report both harnesses sharing `.vscode/mcp.json` as drifted the moment
+ * either one of them is registered alone.
+ */
+export interface InventoryGroup {
+  readonly path: string;
+  readonly harnesses: readonly InventoryMember[];
+}
+
+/** Whether a state means "this harness is on the machine". */
+export const isDetectedState = (state: InventoryState): boolean =>
+  state === "registered" || state === "drifted" || state === "detected";
+
+/**
+ * Roll one scope's detected config groups up against the registry into one row
+ * per harness.
+ *
+ * Groups are keyed by harness NAME because that is the only identity
+ * `TargetGroup` records; the registry is the map back to an id, which is why it
+ * is a parameter rather than a lookup. A harness naming no registry row is
+ * ignored rather than invented — the inventory reports on the registry, not on
+ * whatever a group happened to say.
+ *
+ * @param registry - Every known harness, each flagged for scope membership.
+ * @param groups - This scope's detected config files (narrowed, path-shortened),
+ *   each naming the harnesses that share it with their own per-write state.
+ * @param scope - The scope being rolled up.
+ * @returns One row per registry harness, in registry order.
+ * @note Pure — it reads no filesystem and holds no live effect.
+ */
+export function harnessInventory(
+  registry: readonly InventoryHarness[],
+  groups: readonly InventoryGroup[],
+  scope: Scope,
+): InventoryRow[] {
+  const states = new Map<string, WriteState>();
+  const locations = new Map<string, string[]>();
+  for (const group of groups) {
+    for (const member of group.harnesses) {
+      const paths = locations.get(member.name) ?? [];
+      paths.push(group.path);
+      locations.set(member.name, paths);
+      // A harness sharing two files is registered only where EVERY one of them
+      // carries the current entry — the same "all or nothing" rule
+      // `aggregateMcpStates` applies across the writes within a single file.
+      const prior = states.get(member.name);
+      states.set(
+        member.name,
+        prior === undefined || prior === member.state
+          ? member.state
+          : "drifted",
+      );
+    }
+  }
+
+  return registry.map((harness): InventoryRow => {
+    const detected = states.get(harness.name);
+    const paths = locations.get(harness.name) ?? [];
+    const state: InventoryState =
+      detected === undefined
+        ? harness.inScope
+          ? "undetected"
+          : "unscoped"
+        : detected === "registered"
+          ? "registered"
+          : detected === "drifted"
+            ? "drifted"
+            : "detected";
+    return {
+      harnessId: harness.id,
+      harnessName: harness.name,
+      scope,
+      state,
+      locations: paths,
+    };
+  });
+}
+
+/** The per-item status each state renders as. Never `fail` — see the docblock. */
+const STATE_STATUS: Record<InventoryState, CheckStatus> = {
+  registered: "pass",
+  drifted: "available",
+  detected: "available",
+  undetected: "skip",
+  unscoped: "skip",
+};
+
+/**
+ * The phrase each state reads as, scope-aware for the unscoped case.
+ *
+ * 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
+ * config per project, so there is no global file for pragma to be in — is the
+ * thing that explains the row.
+ */
+const stateDetail = (row: InventoryRow): string => {
+  switch (row.state) {
+    case "registered":
+      return "registered";
+    case "drifted":
+      return "registered, entry differs from current";
+    case "detected":
+      return "detected, not registered";
+    case "undetected":
+      return "not detected";
+    case "unscoped":
+      return row.scope === "global"
+        ? "keeps no global config — it is per-project only"
+        : "keeps no per-project config — it is global only";
+  }
+};
+
+/**
+ * Project inventory rows into doctor sub-items.
+ *
+ * The default listing is DETECTED HARNESSES ONLY — a report that names every
+ * tool the user does not have buries the ones they do. `--verbose` widens it to
+ * the whole registry, which is the only view in which `undetected`/`unscoped`
+ * rows appear at all.
+ *
+ * @param rows - This scope's inventory rows.
+ * @param verbose - Whether to list the whole registry rather than the hits.
+ * @returns The sub-items, harness name in the left column.
+ */
+export function inventoryItems(
+  rows: readonly InventoryRow[],
+  verbose: boolean,
+): CheckItem[] {
+  const shown = verbose
+    ? rows
+    : rows.filter((row) => isDetectedState(row.state));
+  return shown.map((row): CheckItem => {
+    const where = row.locations.join(", ");
+    return {
+      label: row.harnessName,
+      status: STATE_STATUS[row.state],
+      detail: where ? `${stateDetail(row)} — ${where}` : stateDetail(row),
+    };
+  });
+}
+
+/** The inventory check's headline, and whether it has anything to show. */
+export interface InventoryHealth {
+  readonly status: CheckStatus;
+  readonly detail: string;
+  readonly items: readonly CheckItem[];
+}
+
+/**
+ * The whole inventory row for one scope: a listing, not a verdict.
+ *
+ * Its status is only ever `pass` (this scope has harnesses) or `skip` (it has
+ * none). It is the one scoped row that is not a setup target, so it derives no
+ * `fix:` line — the `mcp` and `skills` rows beside it own every action a
+ * harness can need, and a second row proposing the same command would be the
+ * "same finding seen twice" the report is built to avoid.
+ *
+ * @param rows - This scope's inventory rows.
+ * @param verbose - Whether the listing widens to the whole registry.
+ * @returns The status, headline and sub-items for the scope's inventory check.
+ */
+export function inventoryHealth(
+  rows: readonly InventoryRow[],
+  verbose: boolean,
+): InventoryHealth {
+  const detected = rows.filter((row) => isDetectedState(row.state));
+  const registered = rows.filter((row) => row.state === "registered");
+  const items = inventoryItems(rows, verbose);
+  if (detected.length === 0) {
+    return {
+      status: "skip",
+      detail: verbose
+        ? `none of ${rows.length} known harnesses detected`
+        : "no harnesses detected",
+      items,
+    };
+  }
+  return {
+    status: "pass",
+    detail: `${detected.length} detected · ${registered.length} registered${
+      verbose ? ` · ${rows.length} known` : ""
+    }`,
+    items,
+  };
+}

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

@@ -6,17 +6,17 @@
  * them apart from the report body is what lets `runChecks` stay a composition
  * — it orders and awaits, and knows nothing about what any check looks at.
  *
- * Two kinds live here, and the barrel exposes them differently. The UNBANDED
+ * Two kinds live here, and the barrel exposes them differently. The UNSCOPED
  * checks diagnose what `setup` cannot install — the Node floor, the CLI's own
  * version and install source, the pack answering this project's reads, and the
- * store — so each is its own named entry point. The BANDED rows are derived
- * per target, per band, from the setup target table rather than authored here,
+ * store — so each is its own named entry point. The SCOPED rows are derived
+ * per target, per scope, from the setup target table rather than authored here,
  * so they surface as the one generator that derives them, never as a list of
  * row names this file would then have to keep in step with `setup`.
  *
  * The per-target probes (the completions script check, the MCP command
- * resolution helpers) stay internal on purpose: `bandedChecks` is the only way
- * they are meant to be reached, and a row reachable past its band is a row
+ * resolution helpers) stay internal on purpose: `scopedChecks` is the only way
+ * they are meant to be reached, and a row reachable past its scope is a row
  * `doctor` can report and `setup` cannot fix.
  */
 
@@ -24,4 +24,4 @@ export { checkKeStore } from "./checkKeStore.js";
 export { checkNodeVersion } from "./checkNodeVersion.js";
 export { checkPackageRefs } from "./checkPackageRefs.js";
 export { checkPragmaVersion } from "./checkPragmaVersion.js";
-export { bandedChecks } from "./targetHealth.js";
+export { scopedChecks } from "./targetHealth.js";

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