@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -24,13 +24,13 @@ const BANDED_DATA: DoctorData = {
     {
       name: "Shell completions",
       status: "pass",
-      detail: "zsh installed and resolving",
+      detail: "zsh up to date and resolving",
       band: "global",
     },
     {
       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,28 +42,36 @@ 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" },
     {
-      name: "package refs",
+      name: "pack refs",
       status: "fail",
-      detail: "3 configured, 0 locked",
+      detail: "packs are configured but the store has not been built",
       items: [
-        { label: "core", status: "fail", detail: "unlocked" },
-        { label: "ui", status: "fail", detail: "unlocked" },
+        { label: "core", status: "fail", detail: "not built" },
+        { label: "ui", status: "fail", detail: "not built" },
       ],
       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_");
   });
 });
 
@@ -151,10 +159,13 @@ describe("doctor render — piped output is ANSI-free (F1)", () => {
       // The structural, color-free content still renders (glyphs, names, remedy).
       expect(out).toContain("pragma doctor");
       expect(out).toContain("✓  Node version");
-      expect(out).toContain("✗  package refs");
+      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

@@ -11,15 +11,23 @@
  */
 
 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: "○",
 };
 
@@ -47,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);
 }
 
@@ -88,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}`,
     );
@@ -97,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(
@@ -105,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`)
@@ -134,7 +161,7 @@ export const doctorFormatters: Formatters<DoctorData> = {
   plain(data) {
     const style = doctorStyle();
     const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
-    const lines: string[] = [style.bold("pragma doctor"), ""];
+    const lines: string[] = [style.bold(`${BIN_NAME} doctor`), ""];
     const { environment, machine, project } = partitionByBand(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;
@@ -154,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;
@@ -187,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");
   },