@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -0,0 +1,100 @@
+/**
+ * `commandOf` reads BOTH registered entry shapes.
+ *
+ * A harness whose schema requires `command` to be an argv array (OpenCode)
+ * carries the executable in the first element; a string-valued `command` IS the
+ * executable. Reading only the string form made doctor skip an entry `setup`
+ * had just written correctly — and report no command-based servers on a fully
+ * configured machine. The two shapes must resolve to the same executable, which
+ * is what these cases pin.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PlatformEnv } from "@canonical/harnesses";
+import { afterAll, describe, expect, it } from "vitest";
+import { commandOf, commandResolves } from "./mcpCommand.js";
+
+describe("commandOf — one executable, either entry shape", () => {
+  it("reads a string command", () => {
+    expect(commandOf({ command: "pragma", args: ["mcp", "serve"] })).toBe(
+      "pragma",
+    );
+  });
+
+  it("reads the executable out of an argv array", () => {
+    expect(commandOf({ command: ["pragma", "mcp", "serve"] })).toBe("pragma");
+  });
+
+  it("skips the leading empty element rather than returning it", () => {
+    expect(commandOf({ command: ["", "pragma"] })).toBe("pragma");
+  });
+
+  it("has no command for an HTTP entry", () => {
+    expect(commandOf({ type: "http", url: "https://example.test" })).toBe(
+      undefined,
+    );
+  });
+
+  it("has no command for an empty string, an empty array, or a non-entry", () => {
+    expect(commandOf({ command: "" })).toBe(undefined);
+    expect(commandOf({ command: [] })).toBe(undefined);
+    expect(commandOf(null)).toBe(undefined);
+    expect(commandOf("pragma")).toBe(undefined);
+  });
+});
+
+describe("commandResolves — the host's own resolution rules", () => {
+  const dirs: string[] = [];
+  const tmp = (): string => {
+    const dir = mkdtempSync(join(tmpdir(), "pragma-mcp-path-"));
+    dirs.push(dir);
+    return dir;
+  };
+  afterAll(() => {
+    for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+  });
+
+  const hostOf = (
+    platform: PlatformEnv["platform"],
+    dir: string,
+  ): PlatformEnv => ({
+    platform,
+    env: { PATH: dir },
+    home: dir,
+    isWsl: false,
+  });
+
+  it("resolves a Windows shim, which a bare-name PATH join cannot see", async () => {
+    // npm installs the CLI as `pragma.cmd` on Windows. Joining the bare name
+    // onto each PATH directory found nothing, so a registration `setup` had
+    // just written correctly was reported as a dead command. (The file is
+    // spelled to match a default `PATHEXT` entry exactly, because this test
+    // runs on a case-sensitive filesystem.)
+    const dir = tmp();
+    writeFileSync(join(dir, "pragma.CMD"), "");
+    expect(await commandResolves("pragma", dir, hostOf("win32", dir))).toBe(
+      true,
+    );
+  });
+
+  it("resolves a bare name off PATH elsewhere, and says no when it is absent", async () => {
+    const dir = tmp();
+    writeFileSync(join(dir, "pragma"), "");
+    expect(await commandResolves("pragma", dir, hostOf("linux", dir))).toBe(
+      true,
+    );
+    expect(await commandResolves("absent", dir, hostOf("linux", dir))).toBe(
+      false,
+    );
+  });
+
+  it("checks a path-bearing command as a file, relative to the project root", async () => {
+    const dir = tmp();
+    writeFileSync(join(dir, "local-bin"), "");
+    expect(
+      await commandResolves("./local-bin", dir, hostOf("linux", dir)),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,69 @@
+/**
+ * Command resolution for MCP server entries.
+ *
+ * A dead `command` makes every agent session try and fail to boot the server,
+ * so the `mcp` doctor row reports whether the entry it owns resolves. The row
+ * judges ONLY the entry this CLI writes: an aggregate check over every server
+ * in the file failed the row whenever some FOREIGN server had a dead command,
+ * which is a fact about someone else's tool reported as this one's fault.
+ */
+
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { PlatformEnv } from "@canonical/harnesses";
+
+/**
+ * Extract the stdio command from an MCP server config entry, if any. HTTP/SSE
+ * entries (`{ type: "http", url }`) have no command and are not checked.
+ *
+ * Both entry shapes resolve to the same executable. A harness whose schema
+ * requires `command` to be an argv array (OpenCode) carries the executable in
+ * its first element; a string-valued `command` IS the executable. Reading only
+ * the string form made this check skip an entry `setup` had just written
+ * correctly, and report no command-based servers on a configured machine.
+ */
+export function commandOf(entry: unknown): string | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  const command = (entry as { command?: unknown }).command;
+  if (typeof command === "string") {
+    return command.length > 0 ? command : undefined;
+  }
+  if (Array.isArray(command)) {
+    return command.find(
+      (part): part is string => typeof part === "string" && part.length > 0,
+    );
+  }
+  return undefined;
+}
+
+/**
+ * Resolve a command the way the host would: a path-bearing entry is checked as
+ * a file (relative to the project root), a bare name is searched across `PATH`
+ * through `@canonical/harnesses`' `executableCandidates`, which owns the PATH
+ * split and the win32 `PATHEXT` rules in one place.
+ *
+ * The bare-name arm used to join the name onto each PATH directory, which
+ * cannot see the `.cmd` shim npm installs on Windows: a registration this CLI
+ * had just written correctly was reported as a dead command.
+ *
+ * @param command - The executable the entry names.
+ * @param cwd - The project root a relative command is resolved against.
+ * @param platform - The captured host to use instead of this one (tests).
+ * @returns Whether the command resolves on this machine.
+ * @note Impure — tests candidate paths on the filesystem.
+ */
+export async function commandResolves(
+  command: string,
+  cwd: string,
+  platform?: PlatformEnv,
+): Promise<boolean> {
+  if (command.includes("/") || command.includes("\\")) {
+    return existsSync(isAbsolute(command) ? command : join(cwd, command));
+  }
+  const { executableCandidates, readPlatformEnv } = await import(
+    "@canonical/harnesses"
+  );
+  return executableCandidates(command, platform ?? readPlatformEnv()).some(
+    (candidate) => existsSync(candidate),
+  );
+}

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

@@ -0,0 +1,274 @@
+/**
+ * The banded doctor rows, derived from the setup target table.
+ *
+ * `doctor` and `setup` are the SAME LIST. Every banded row here carries a
+ * target id verbatim — `completions`, not "Shell completions"; `mcp`, not "MCP
+ * configured" — because the row name IS the fix command's argument, and a user
+ * who reads `✗ mcp` beside `fix: pragma setup mcp` can see that they are the
+ * same thing. Two checks reporting on one target under two different names, one
+ * of which no command accepts, is how a report ends up describing a machine
+ * nobody can repair.
+ *
+ * Every row's detection comes from the target table's own `detect`, so the two
+ * surfaces cannot disagree about what they looked at, and every `fix:` is
+ * derived from the row's id and band rather than authored per check.
+ *
+ * Doctor's UNBANDED environment checks (Node version, the CLI's own version,
+ * pack refs, the store) diagnose things setup cannot install and stay outside
+ * this list.
+ */
+
+import { MCP_SERVER_NAME } from "../../../constants.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
+import {
+  type DetectedRow,
+  detectionFailure,
+  detectTargets,
+  resolveRoots,
+} from "../../setup/buildPlan.js";
+import type {
+  CompletionsDetection,
+  ConfigDetection,
+} from "../../setup/operations/index.js";
+import {
+  type LspDetection,
+  lspEditorNames,
+  lspSkipReason,
+  type McpDetection,
+  mcpGroupState,
+  type SkillsDetection,
+  skillsSkipReason,
+} from "../../setup/operations/index.js";
+import { shortenPath, TARGET_IDS } from "../../setup/plan.js";
+import type { CheckItem, CheckResult, ScopeBand } from "../types.js";
+import { checkShellCompletions } from "./checkShellCompletions.js";
+import { commandResolves } from "./mcpCommand.js";
+
+/** What a row reports before its name, band and `fix:` line are attached. */
+interface Health {
+  readonly status: CheckResult["status"];
+  readonly detail: string;
+  readonly items?: readonly CheckItem[];
+  /**
+   * A remedy that is NOT the derived setup command — the zsh activation line,
+   * for instance, which setup cannot perform for the user. Absent means "the
+   * fix is to run the target's own setup command", which is the default and the
+   * reason the bijection holds without anyone authoring it.
+   */
+  readonly remedy?: string;
+}
+
+/** The `config` row: the global config file exists and parses. */
+const configHealth = (
+  d: ConfigDetection,
+  roots: { global: string; project: string },
+): Health => {
+  const path = shortenPath(d.path, roots);
+  if (!d.exists) return { status: "available", detail: `${path} not created` };
+  if (!d.parses) {
+    return { status: "fail", detail: `${path} cannot be parsed as JSON` };
+  }
+  return { status: "pass", detail: `${path} — valid` };
+};
+
+/** The `lsp` row — the first this report has ever had. */
+const lspHealth = (d: LspDetection): Health => {
+  if (d.state === "unknown") {
+    return { status: "skip", detail: lspSkipReason(d) };
+  }
+  const editors = lspEditorNames(d).join(", ");
+  return d.state === "installed"
+    ? { status: "pass", detail: `installed (${editors})` }
+    : { status: "available", detail: `not installed (${editors})` };
+};
+
+/**
+ * The `mcp` row: one sub-item per file, each saying whether the entry is
+ * present, current, and bootable. Two separate checks used to report this —
+ * one for presence, one for command resolution — and the second judged every
+ * server in the file, so a foreign server's dead command failed this CLI's row.
+ */
+async function mcpHealth(
+  d: McpDetection,
+  band: ScopeBand,
+  cwd: string,
+  roots: { global: string; project: string },
+): Promise<Health> {
+  if (d.groups.length === 0) {
+    return {
+      status: "skip",
+      detail: "no harness config location in this band",
+    };
+  }
+  const resolves = await commandResolves(MCP_SERVER_NAME, cwd);
+  const items: CheckItem[] = d.groups.map((group) => {
+    const state = mcpGroupState(d, group.path);
+    const label = shortenPath(group.path, roots);
+    if (state === "absent") {
+      return { label, status: "available", detail: "not configured" };
+    }
+    if (state === "drifted") {
+      return { label, status: "fail", detail: "entry differs from current" };
+    }
+    return {
+      label,
+      status: resolves ? "pass" : "fail",
+      detail: resolves
+        ? `entry current, \`${MCP_SERVER_NAME}\` resolves`
+        : `entry current, \`${MCP_SERVER_NAME}\` is not on PATH`,
+    };
+  });
+  const configured = items.filter((item) => item.status === "pass").length;
+  const failing = items.filter((item) => item.status === "fail").length;
+  if (failing > 0) {
+    return {
+      status: "fail",
+      detail: `${failing} of ${items.length} need attention`,
+      items,
+    };
+  }
+  if (configured === 0) {
+    // Project-band absence is not a failure: the band is opt-in, so a
+    // repository with no checked-in MCP config is a healthy repository.
+    return band === "project"
+      ? { status: "skip", detail: "not configured for this project (opt-in)" }
+      : {
+          status: "available",
+          detail: `${items.length} not configured`,
+          items,
+        };
+  }
+  return {
+    status: configured === items.length ? "pass" : "available",
+    detail: `${configured} of ${items.length} current`,
+    items,
+  };
+}
+
+/** The `skills` row: every expected link present, lstat-verified, none stale. */
+function skillsHealth(
+  d: SkillsDetection,
+  band: ScopeBand,
+  roots: { global: string; project: string },
+): Health {
+  if (!d.available) {
+    return {
+      status: "skip",
+      detail: skillsSkipReason(shortenPath(d.sourceRoot, roots), band),
+    };
+  }
+  const stale = d.actions.filter((a) => a.action === "replaced").length;
+  const missing = d.actions.filter((a) => a.action === "created").length;
+  if (stale > 0) {
+    return {
+      status: "fail",
+      detail: `${stale} of ${d.actions.length} links point elsewhere`,
+    };
+  }
+  // A hand-placed real directory is `skipped` like an already-correct link is,
+  // and reporting the two the same way made this row say "links current" where
+  // no link exists at all. Setup will never clear such a path — it is not this
+  // command's to delete — so the row carries the only remedy that settles it.
+  const blocked = d.actions.filter((a) => a.blocked).length;
+  if (blocked > 0) {
+    return {
+      status: "available",
+      detail: `${blocked} of ${d.actions.length} link paths hold a real directory`,
+      remedy:
+        "Move or delete the directory at that path, then link the skills again.",
+    };
+  }
+  if (missing > 0) {
+    return {
+      status: "available",
+      detail: `${missing} of ${d.actions.length} links not created`,
+    };
+  }
+  return { status: "pass", detail: `${d.actions.length} links current` };
+}
+
+/**
+ * Map one detected row onto its health. The `completions` row delegates to the
+ * check that owns the three gates the script depends on — the resolver answers,
+ * the installed bytes are current, and zsh has the directory on its `fpath`.
+ */
+async function healthOf(
+  row: DetectedRow,
+  rt: PragmaRuntime,
+  roots: { global: string; project: string },
+): Promise<Health> {
+  // A detection that threw is reported as ITS OWN failing row. Letting the
+  // rejection escape took the whole banded section of the report with it, so a
+  // single unreadable config file left the user with no rows at all — the one
+  // moment the report is most worth having.
+  const failure = detectionFailure(row);
+  if (failure !== undefined) return { status: "fail", detail: failure };
+  switch (row.target.id) {
+    case "config":
+      return configHealth(row.detection as ConfigDetection, roots);
+    case "completions": {
+      const result = await checkShellCompletions(
+        rt.cwd,
+        row.detection as CompletionsDetection,
+      );
+      return {
+        status: result.status,
+        detail: result.detail,
+        ...(result.remedy === undefined ? {} : { remedy: result.remedy }),
+      };
+    }
+    case "lsp":
+      return lspHealth(row.detection as LspDetection);
+    case "mcp":
+      return mcpHealth(row.detection as McpDetection, row.band, rt.cwd, roots);
+    default:
+      return skillsHealth(row.detection as SkillsDetection, row.band, roots);
+  }
+}
+
+/**
+ * The command that repairs a row — derived from its id and band, never
+ * authored. This is the bijection made mechanical: a row exists because a
+ * target exists, and its fix is that target's own invocation.
+ */
+export const fixCommandFor = (
+  id: string,
+  band: ScopeBand,
+  bin: string,
+): string => `${bin} setup ${id}${band === "project" ? " --local" : ""}`;
+
+/**
+ * Run every banded check: the target table, both bands, in table order.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param bin - The binary name the `fix:` lines are derived from.
+ * @returns One {@link CheckResult} per (target, band) the machine can hold.
+ * @note Impure — every target's detection reads the real filesystem.
+ */
+export async function bandedChecks(
+  rt: PragmaRuntime,
+  bin: string,
+): Promise<CheckResult[]> {
+  const roots = await resolveRoots(rt);
+  const detected = await detectTargets(rt, [...TARGET_IDS], "both");
+  return Promise.all(
+    detected.map(async (row): Promise<CheckResult> => {
+      const health = await healthOf(row, rt, roots);
+      const needsFix =
+        health.status === "fail" || health.status === "available";
+      return {
+        name: row.target.id,
+        status: health.status,
+        detail: health.detail,
+        band: row.band,
+        ...(health.items === undefined ? {} : { items: health.items }),
+        ...(needsFix
+          ? {
+              remedy:
+                health.remedy ?? fixCommandFor(row.target.id, row.band, bin),
+            }
+          : {}),
+      };
+    }),
+  );
+}

package/src/capabilities/doctor/doctor.render.test.ts

@@ -29,8 +29,8 @@ const BANDED_DATA: DoctorData = {
     },
     {
       name: "MCP configured",
-      status: "fail",
-      detail: "detected Windsurf but pragma not configured",
+      status: "available",
+      detail: "not set up for Windsurf",
       remedy: "pragma setup mcp",
       band: "global",
     },
@@ -42,11 +42,12 @@ const BANDED_DATA: DoctorData = {
     },
   ],
   passed: 2,
-  failed: 1,
+  failed: 0,
+  available: 1,
   skipped: 1,
 };
 
-/** A fixture spanning pass/fail/skip, sub-items, and a remedy — every color path. */
+/** A fixture spanning every status tier, sub-items, and remedies — every color path. */
 const COLOR_DATA: DoctorData = {
   checks: [
     { name: "Node version", status: "pass", detail: "v24" },
@@ -60,10 +61,17 @@ const COLOR_DATA: DoctorData = {
       ],
       remedy: "pragma sources update",
     },
+    {
+      name: "Shell completions",
+      status: "available",
+      detail: "resolver OK; zsh script not installed",
+      remedy: "pragma setup completions",
+    },
     { name: "Skills symlinked", status: "skip", detail: "no harness" },
   ],
   passed: 1,
   failed: 1,
+  available: 1,
   skipped: 1,
 };
 
@@ -112,7 +120,7 @@ describe("doctor render — banded plain report", () => {
     expect(at("Global")).toBeLessThan(at("Shell completions"));
     expect(at("MCP configured")).toBeLessThan(at("Project"));
     expect(at("Project")).toBeLessThan(at("Skills symlinked"));
-    // A failing banded check keeps its inline remedy under its band.
+    // An available banded check keeps its inline setup command under its band.
     expect(out).toContain("fix: pragma setup mcp");
     // The tally closes the report.
     expect(out).toContain("2 passed");
@@ -131,7 +139,7 @@ describe("doctor render — banded llm report", () => {
     expect(at("### Global")).toBeLessThan(at("Shell completions"));
     expect(at("Shell completions")).toBeLessThan(at("### Project"));
     expect(at("### Project")).toBeLessThan(at("Skills symlinked"));
-    expect(out).toContain("_2 passed, 1 failed, 1 skipped_");
+    expect(out).toContain("_2 passed, 0 failed, 1 available, 1 skipped_");
   });
 });
 
@@ -152,9 +160,12 @@ describe("doctor render — piped output is ANSI-free (F1)", () => {
       expect(out).toContain("pragma doctor");
       expect(out).toContain("✓  Node version");
       expect(out).toContain("✗  pack refs");
+      expect(out).toContain("◇  Shell completions");
       expect(out).toContain("○  Skills symlinked");
       expect(out).toContain("↳ fix: pragma sources update");
-      expect(out).toContain("  1 passed · 1 failed · 1 skipped");
+      // The available tier keeps its setup command inline, like a fail's fix.
+      expect(out).toContain("↳ fix: pragma setup completions");
+      expect(out).toContain("  1 passed · 1 failed · 1 available · 1 skipped");
     });
   });
 });

package/src/capabilities/doctor/doctor.render.ts

@@ -13,14 +13,21 @@
 import chalk from "chalk";
 import { BIN_NAME } from "../../constants.js";
 import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
-import type { Formatters } from "../../kernel/spec/types.js";
-import { BAND_LABELS } from "../shared/bands.js";
+import type { Formatters } from "../../kernel/spec/index.js";
+import { BAND_LABELS } from "../shared/index.js";
 import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
 
-/** Uncolored status glyphs — tinted at render time (never baked at module load). */
+/**
+ * Uncolored status glyphs — tinted at render time (never baked at module load).
+ * `available` gets its own glyph, distinct from ✗: an opt-in integration that
+ * is not set up is not a fault, and rendering it as one would train users to
+ * ignore the failure count. The glyph pairs with the word in the tally, so the
+ * distinction survives with color stripped.
+ */
 const STATUS_GLYPHS: Record<CheckStatus, string> = {
   pass: "✓",
   fail: "✗",
+  available: "◇",
   skip: "○",
 };
 
@@ -48,11 +55,16 @@ function doctorStyle(): DoctorStyle {
   };
 }
 
-/** Tint a status glyph by meaning — green pass, red fail, yellow skip. */
+/**
+ * Tint a status glyph by meaning — green pass, red fail, cyan available
+ * (actionable-but-optional, the same tint as the `fix:` arrow it points at),
+ * yellow skip.
+ */
 function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
   const glyph = STATUS_GLYPHS[status];
   if (status === "pass") return style.green(glyph);
   if (status === "fail") return style.red(glyph);
+  if (status === "available") return style.cyan(glyph);
   return style.yellow(glyph);
 }
 
@@ -89,7 +101,12 @@ function formatCheckPlain(
     }
   }
 
-  if (check.status === "fail" && check.remedy) {
+  // Both actionable tiers keep their inline instruction: a fail's remedy is
+  // the repair, an available's remedy is the setup command that enables it.
+  if (
+    (check.status === "fail" || check.status === "available") &&
+    check.remedy
+  ) {
     lines.push(
       `${INDENT}${style.cyan(FIX_ARROW)} ${style.cyan("fix:")} ${check.remedy}`,
     );
@@ -98,7 +115,11 @@ function formatCheckPlain(
   return lines;
 }
 
-/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
+/**
+ * Render the pass/fail/available/skip tally, coloring the non-zero counts.
+ * `available` is counted apart from `failed` so a healthy install with
+ * integrations left to opt into never reports failures it does not have.
+ */
 function formatSummary(data: DoctorData, style: DoctorStyle): string {
   const parts = [style.green(`${data.passed} passed`)];
   parts.push(
@@ -106,6 +127,11 @@ function formatSummary(data: DoctorData, style: DoctorStyle): string {
       ? style.red(`${data.failed} failed`)
       : style.dim(`${data.failed} failed`),
   );
+  parts.push(
+    data.available > 0
+      ? style.cyan(`${data.available} available`)
+      : style.dim(`${data.available} available`),
+  );
   parts.push(
     data.skipped > 0
       ? style.yellow(`${data.skipped} skipped`)
@@ -155,22 +181,20 @@ export const doctorFormatters: Formatters<DoctorData> = {
 
   llm(data) {
     const renderCheck = (check: CheckResult): string[] => {
-      const icon =
-        check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
-      const out = [`- ${icon} **${check.name}**: ${check.detail}`];
+      const out = [
+        `- ${STATUS_GLYPHS[check.status]} **${check.name}**: ${check.detail}`,
+      ];
       for (const item of check.items ?? []) {
-        const itemIcon =
-          item.status === "pass"
-            ? "✓ "
-            : item.status === "fail"
-              ? "✗ "
-              : item.status === "skip"
-                ? "○ "
-                : "";
+        const itemIcon = item.status ? `${STATUS_GLYPHS[item.status]} ` : "";
         const detail = item.detail ? `: ${item.detail}` : "";
         out.push(`  - ${itemIcon}${item.label}${detail}`);
       }
-      if (check.status === "fail" && check.remedy) {
+      // Same rule as the plain path: fail and available both carry their
+      // inline instruction (the repair, or the setup command).
+      if (
+        (check.status === "fail" || check.status === "available") &&
+        check.remedy
+      ) {
         out.push(`  - _fix:_ \`${check.remedy}\``);
       }
       return out;
@@ -188,7 +212,7 @@ export const doctorFormatters: Formatters<DoctorData> = {
     section(BAND_LABELS.project, project);
     lines.push(
       "",
-      `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,
+      `_${data.passed} passed, ${data.failed} failed, ${data.available} available, ${data.skipped} skipped_`,
     );
     return lines.join("\n");
   },