@canonical/pragma-cli 0.34.0 → 0.36.0

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

@@ -1,14 +1,16 @@
 /**
- * Render goldens for `pragma doctor` — the band-grouped report AND the plain-path
- * color gate (F1).
+ * Render goldens for `pragma doctor` — the scope-grouped report AND the
+ * plain-path color gate (F1).
  *
- * The banded Global/Project grouping (`partitionByBand` → sections) is pinned for
- * both the plain and llm formatters, locking the unified Global/Project
- * vocabulary (the report no longer says MACHINE/PROJECT). Separately, the plain
+ * The Global / Local project grouping (`partitionByScope` → sections) is pinned
+ * for both the plain and llm formatters, locking the vocabulary the flags
+ * already use — `--global` and `--local`. It is neither MACHINE/PROJECT (the
+ * first spelling) nor "band" (the second): "band" was this repository's word for
+ * the partition and nobody else's. Separately, the plain
  * formatter tints ONLY on a color-capable TTY: `supports-color` reports a
  * non-zero `chalk.level` off a TTY under `GITHUB_ACTIONS` / `FORCE_COLOR`, so the
  * `isTTY` gate (via the shared style seam) keeps ANSI out of
- * `doctor --format plain | tee`. `beforeEach` forces color OFF so the banded
+ * `doctor --format plain | tee`. `beforeEach` forces color OFF so the section
  * goldens stay deterministic; the color tests opt a level back in explicitly.
  */
 
@@ -17,36 +19,37 @@ import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { doctorFormatters } from "./doctor.render.js";
 import type { DoctorData } from "./types.js";
 
-/** A fixture spanning all three groups: environment (no band), global, project. */
-const BANDED_DATA: DoctorData = {
+/** A fixture spanning all three groups: environment (no scope), global, project. */
+const SCOPED_DATA: DoctorData = {
   checks: [
     { name: "Node version", status: "pass", detail: "v20 detected" },
     {
       name: "Shell completions",
       status: "pass",
       detail: "zsh up to date and resolving",
-      band: "global",
+      scope: "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",
+      scope: "global",
     },
     {
       name: "Skills symlinked",
       status: "skip",
       detail: "no AI harnesses detected",
-      band: "project",
+      scope: "project",
     },
   ],
   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 +63,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,
 };
 
@@ -90,54 +100,59 @@ afterAll(() => {
   chalk.level = prevLevel;
 });
 
-describe("doctor render — banded plain report", () => {
-  it("groups checks under Global then Project headers (unified labels)", () => {
-    const out = doctorFormatters.plain(BANDED_DATA);
+describe("doctor render — scoped plain report", () => {
+  it("groups checks under Global then Local project headers", () => {
+    const out = doctorFormatters.plain(SCOPED_DATA);
     const lines = out.split("\n");
-    // The two banded section headers use the unified Global/Project vocabulary.
+    // The two section headers use the words the flags use.
     expect(lines).toContain("Global");
-    expect(lines).toContain("Project");
-    // The superseded MACHINE/PROJECT labels are gone.
+    expect(lines).toContain("Local project");
+    // The superseded MACHINE/PROJECT labels are gone — and so is "band", which
+    // no user-facing string in this report may say.
     expect(out).not.toContain("MACHINE");
     expect(out).not.toMatch(/^PROJECT$/m);
+    expect(out).not.toMatch(/\bbands?\b/);
   });
 
-  it("orders environment → Global → Project, banding each check correctly", () => {
-    const out = doctorFormatters.plain(BANDED_DATA);
-    // Environment check leads with no header; the two global-band checks sit
-    // under Global; the project-band check sits under Project.
+  it("orders environment → Global → Local project, placing each check correctly", () => {
+    const out = doctorFormatters.plain(SCOPED_DATA);
+    // Environment check leads with no header; the two global checks sit under
+    // Global; the per-project check sits under Local project.
     const at = (needle: string): number => out.indexOf(needle);
     expect(at("Node version")).toBeGreaterThanOrEqual(0);
     expect(at("Node version")).toBeLessThan(at("Global"));
     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.
+    expect(at("MCP configured")).toBeLessThan(at("Local project"));
+    expect(at("Local project")).toBeLessThan(at("Skills symlinked"));
+    // An available scoped check keeps its inline setup command under its scope.
     expect(out).toContain("fix: pragma setup mcp");
     // The tally closes the report.
     expect(out).toContain("2 passed");
   });
 });
 
-describe("doctor render — banded llm report", () => {
-  it("groups checks under ### Global then ### Project headers", () => {
-    const out = doctorFormatters.llm(BANDED_DATA);
+describe("doctor render — scoped llm report", () => {
+  it("groups checks under ### Global then ### Local project headers", () => {
+    const out = doctorFormatters.llm(SCOPED_DATA);
     expect(out).toContain("### Global");
-    expect(out).toContain("### Project");
+    expect(out).toContain("### Local project");
     expect(out).not.toContain("### Machine");
     const at = (needle: string): number => out.indexOf(needle);
-    // Environment leads (no section header), then the two banded sections.
+    // Environment leads (no section header), then the two scoped sections.
     expect(at("Node version")).toBeLessThan(at("### Global"));
     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(at("Shell completions")).toBeLessThan(at("### Local project"));
+    expect(at("### Local project")).toBeLessThan(at("Skills symlinked"));
+    expect(out).toContain("_2 passed, 0 failed, 1 available, 1 skipped_");
   });
 });
 
 describe("doctor render — json", () => {
   it("is the exact DoctorData round-trip", () => {
-    expect(JSON.parse(doctorFormatters.json(BANDED_DATA))).toEqual(BANDED_DATA);
+    expect(JSON.parse(doctorFormatters.json(SCOPED_DATA))).toEqual(SCOPED_DATA);
+    // The machine surface uses the scope vocabulary too — the retired word
+    // cannot survive as a JSON key.
+    expect(doctorFormatters.json(SCOPED_DATA)).not.toMatch(/\bbands?\b/);
   });
 });
 
@@ -152,9 +167,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");
     });
   });
 });
@@ -168,3 +186,72 @@ describe("doctor render — color ON (attended TTY)", () => {
     });
   });
 });
+
+/**
+ * The harness inventory renders through the EXISTING check-with-items
+ * primitive — a listing needs no new machinery, only a check whose `items` are
+ * harnesses. This pins that it reads as an inventory in both formats: named
+ * harnesses under their scope, mixed per-item glyphs, and NO `fix:` line (the
+ * `mcp`/`skills` rows own every action a harness can need).
+ */
+const INVENTORY_DATA: DoctorData = {
+  checks: [
+    {
+      name: "harnesses",
+      status: "pass",
+      detail: "1 detected · 1 registered · 3 known",
+      scope: "global",
+      items: [
+        {
+          label: "Claude Code",
+          status: "pass",
+          detail: "registered — ~/.claude.json",
+        },
+        { label: "Cursor", status: "skip", detail: "not detected" },
+        {
+          label: "VS Code",
+          status: "skip",
+          detail: "keeps no global config",
+        },
+      ],
+    },
+  ],
+  passed: 1,
+  failed: 0,
+  available: 0,
+  skipped: 0,
+};
+
+describe("doctor render — the harness inventory", () => {
+  it("renders one aligned sub-item per harness, with no fix line", () => {
+    const out = doctorFormatters.plain(INVENTORY_DATA);
+    expect(out).toContain("Global");
+    expect(out).toContain("harnesses");
+    expect(out).toContain("1 detected · 1 registered · 3 known");
+    expect(out).toContain("· ✓ Claude Code  registered — ~/.claude.json");
+    expect(out).toContain("· ○ Cursor       not detected");
+    expect(out).toContain("· ○ VS Code      keeps no global config");
+    // A listing proposes nothing — and never renders a failure glyph.
+    expect(out).not.toContain("fix:");
+    expect(out).not.toContain("✗");
+  });
+
+  it("nests the harnesses under the check in the llm format", () => {
+    const out = doctorFormatters.llm(INVENTORY_DATA);
+    expect(out).toContain("### Global");
+    expect(out).toContain(
+      "- ✓ **harnesses**: 1 detected · 1 registered · 3 known",
+    );
+    expect(out).toContain("  - ✓ Claude Code: registered — ~/.claude.json");
+    expect(out).toContain("  - ○ VS Code: keeps no global config");
+    expect(out).not.toContain("_fix:_");
+  });
+
+  it("round-trips through json with every row intact", () => {
+    const parsed = JSON.parse(
+      doctorFormatters.json(INVENTORY_DATA),
+    ) as DoctorData;
+    expect(parsed).toEqual(INVENTORY_DATA);
+    expect(parsed.checks[0]?.items).toHaveLength(3);
+  });
+});

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

@@ -10,61 +10,41 @@
  * Glyphs are plain constants tinted at render time; nothing is baked at load.
  */
 
-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 {
+  CHECK_GLYPHS,
+  checkRemedyWord,
+  FIX_ARROW,
+  SCOPE_LABELS,
+  SUB_BULLET,
+  SUB_INDENT,
+} from "../../kernel/render/vocabulary.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 import type { CheckResult, CheckStatus, DoctorData } from "./types.js";
 
-/** Uncolored status glyphs — tinted at render time (never baked at module load). */
-const STATUS_GLYPHS: Record<CheckStatus, string> = {
-  pass: "✓",
-  fail: "✗",
-  skip: "○",
-};
-
-const SUB_BULLET = "·";
-const FIX_ARROW = "↳";
-const INDENT = "     "; // aligns sub-lines under the check name
-
-/** The TTY styler plus `red` — the one tint {@link RenderStyle} does not carry. */
-interface DoctorStyle extends RenderStyle {
-  red(text: string): string;
-}
-
 /**
- * Build the doctor styler for this process's stdout: the shared TTY seam, plus a
- * `red` gated on the SAME decision, so a fail tint appears only on a color TTY.
- *
- * @returns A colorizing styler on a color-capable TTY, else the identity styler.
- * @note Impure — {@link defaultStyle} reads `process.stdout.isTTY` + chalk level.
+ * 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 doctorStyle(): DoctorStyle {
-  const style = defaultStyle();
-  return {
-    ...style,
-    red: style.enabled ? (text) => chalk.red(text) : (text) => text,
-  };
-}
-
-/** Tint a status glyph by meaning — green pass, red fail, yellow skip. */
-function paintGlyph(status: CheckStatus, style: DoctorStyle): string {
-  const glyph = STATUS_GLYPHS[status];
+function paintGlyph(status: CheckStatus, style: RenderStyle): string {
+  const glyph = CHECK_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);
 }
 
 /**
  * Render one check as terminal lines: a headline row (icon, aligned name,
- * detail), an optional indented breakdown of sub-items, and — for failures — an
- * inline remedial instruction.
+ * detail), an optional indented breakdown of sub-items, and — whenever the
+ * check carries one — an inline instruction.
  */
 function formatCheckPlain(
   check: CheckResult,
   nameWidth: number,
-  style: DoctorStyle,
+  style: RenderStyle,
 ): string[] {
   const name = check.name.padEnd(nameWidth);
   const label = check.status === "fail" ? style.red(name) : style.bold(name);
@@ -84,28 +64,46 @@ function formatCheckPlain(
       const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
       const detail = item.detail ? `  ${style.dim(item.detail)}` : "";
       lines.push(
-        `${INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
+        `${SUB_INDENT}${style.dim(SUB_BULLET)} ${icon}${itemLabel}${detail}`,
       );
     }
   }
 
-  if (check.status === "fail" && check.remedy) {
+  // Every row that HAS an instruction prints it. A fail's remedy is the
+  // repair, an available's is the setup command that enables it — and a skip's,
+  // when it authored one, is the only thing standing between the reader and a
+  // dead end. Skips were dropped here, so `skills` reported "no skills
+  // installed" with the next step (`sources update`) computed, carried through
+  // the check, published in `--format json`, and then thrown away one line
+  // before it reached the person reading. A skip never DERIVES a remedy
+  // (`scopedChecks` only passes through an authored one), so this prints
+  // nothing that was not deliberately written for this machine.
+  if (check.remedy) {
     lines.push(
-      `${INDENT}${style.cyan(FIX_ARROW)} ${style.cyan("fix:")} ${check.remedy}`,
+      `${SUB_INDENT}${style.cyan(FIX_ARROW)} ${style.cyan(`${checkRemedyWord(check.status)}:`)} ${check.remedy}`,
     );
   }
 
   return lines;
 }
 
-/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
-function formatSummary(data: DoctorData, style: DoctorStyle): string {
+/**
+ * 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: RenderStyle): string {
   const parts = [style.green(`${data.passed} passed`)];
   parts.push(
     data.failed > 0
       ? 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`)
@@ -115,28 +113,28 @@ function formatSummary(data: DoctorData, style: DoctorStyle): string {
 }
 
 /**
- * Partition checks into ordered bands: environment (no band), then the global
- * and project bands. Declaration order is preserved within each band, so the
- * report stays deterministic.
+ * Partition checks into ordered sections: environment (no scope), then the
+ * global and local-project scopes. Declaration order is preserved within each,
+ * so the report stays deterministic.
  */
-function partitionByBand(checks: readonly CheckResult[]): {
+function partitionByScope(checks: readonly CheckResult[]): {
   environment: CheckResult[];
-  machine: CheckResult[];
+  global: CheckResult[];
   project: CheckResult[];
 } {
   return {
-    environment: checks.filter((c) => c.band === undefined),
-    machine: checks.filter((c) => c.band === "global"),
-    project: checks.filter((c) => c.band === "project"),
+    environment: checks.filter((c) => c.scope === undefined),
+    global: checks.filter((c) => c.scope === "global"),
+    project: checks.filter((c) => c.scope === "project"),
   };
 }
 
 export const doctorFormatters: Formatters<DoctorData> = {
   plain(data) {
-    const style = doctorStyle();
+    const style = defaultStyle();
     const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
     const lines: string[] = [style.bold(`${BIN_NAME} doctor`), ""];
-    const { environment, machine, project } = partitionByBand(data.checks);
+    const { environment, global, project } = partitionByScope(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;
       if (heading) lines.push(style.bold(heading));
@@ -144,51 +142,53 @@ export const doctorFormatters: Formatters<DoctorData> = {
         lines.push(...formatCheckPlain(check, nameWidth, style));
       lines.push("");
     };
-    // Environment checks lead (no header); the global then project bands are the
-    // two banded sections before the tally.
+    // Environment checks lead (no header); Global then Local project are the
+    // two scoped sections before the tally.
     section("", environment);
-    section(BAND_LABELS.global, machine);
-    section(BAND_LABELS.project, project);
+    section(SCOPE_LABELS.global, global);
+    section(SCOPE_LABELS.project, project);
     lines.push(formatSummary(data, style));
     return lines.join("\n");
   },
 
   llm(data) {
     const renderCheck = (check: CheckResult): string[] => {
-      const icon =
-        check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
-      const out = [`- ${icon} **${check.name}**: ${check.detail}`];
+      const out = [
+        `- ${CHECK_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 ? `${CHECK_GLYPHS[item.status]} ` : "";
         const detail = item.detail ? `: ${item.detail}` : "";
         out.push(`  - ${itemIcon}${item.label}${detail}`);
       }
-      if (check.status === "fail" && check.remedy) {
-        out.push(`  - _fix:_ \`${check.remedy}\``);
+      // Same rule as the plain path: every row that carries an instruction
+      // prints it, under the label its status earns. Only a `fix:` is code-set
+      // — a derived remedy is a bare command, while a skip's authored `next:`
+      // is a sentence that may quote a command of its own, and wrapping that in
+      // backticks nests one code span inside another.
+      if (check.remedy) {
+        out.push(
+          check.status === "skip"
+            ? `  - _${checkRemedyWord(check.status)}:_ ${check.remedy}`
+            : `  - _${checkRemedyWord(check.status)}:_ \`${check.remedy}\``,
+        );
       }
       return out;
     };
 
     const lines: string[] = ["## Doctor", ""];
-    const { environment, machine, project } = partitionByBand(data.checks);
+    const { environment, global, project } = partitionByScope(data.checks);
     const section = (heading: string, checks: CheckResult[]): void => {
       if (checks.length === 0) return;
       if (heading) lines.push(`### ${heading}`, "");
       for (const check of checks) lines.push(...renderCheck(check));
     };
     section("", environment);
-    section(BAND_LABELS.global, machine);
-    section(BAND_LABELS.project, project);
+    section(SCOPE_LABELS.global, global);
+    section(SCOPE_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");
   },