@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/doctor/formatters/doctor.test.ts

@@ -48,6 +48,26 @@ const mixed: DoctorData = {
   skipped: 1,
 };
 
+const withItems: DoctorData = {
+  checks: [
+    {
+      name: "package refs",
+      status: "pass",
+      detail: "1 package resolved",
+      items: [
+        {
+          label: "@canonical/design-system",
+          status: "pass",
+          detail: "git v0.1.2 · 362 graphs, 3 skills",
+        },
+      ],
+    },
+  ],
+  passed: 1,
+  failed: 0,
+  skipped: 0,
+};
+
 describe("doctor formatters", () => {
   describe("plain", () => {
     it("renders passing checks with ✓", () => {
@@ -74,6 +94,29 @@ describe("doctor formatters", () => {
       const output = formatters.plain(allPass);
       expect(output).not.toContain("Run ");
     });
+
+    it("renders a summary tally", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("1 passed");
+      expect(output).toContain("2 failed");
+      expect(output).toContain("1 skipped");
+    });
+
+    it("renders sub-items indented under a check", () => {
+      const output = formatters.plain(withItems);
+      expect(output).toContain("@canonical/design-system");
+      expect(output).toContain("git v0.1.2 · 362 graphs, 3 skills");
+      // sub-item lines are indented beneath the check headline
+      const lines = output.split("\n");
+      const sub = lines.find((l) => l.includes("@canonical/design-system"));
+      expect(sub?.startsWith("     ")).toBe(true);
+    });
+
+    it("renders the remedy inline with a fix label", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("fix:");
+      expect(output).toContain("pragma config tier <tier>");
+    });
   });
 
   describe("llm", () => {
@@ -87,12 +130,17 @@ describe("doctor formatters", () => {
       expect(output).toContain("- ✓ **Node version**: v24.1.0");
     });
 
-    it("includes remedial section for failures", () => {
+    it("includes inline fixes for failures", () => {
       const output = formatters.llm(mixed);
-      expect(output).toContain("### Remedial");
+      expect(output).toContain("_fix:_");
       expect(output).toContain("`pragma config tier <tier>`");
       expect(output).toContain("`pragma setup completions`");
     });
+
+    it("renders sub-items as nested bullets", () => {
+      const output = formatters.llm(withItems);
+      expect(output).toContain("  - ✓ @canonical/design-system");
+    });
   });
 
   describe("json", () => {

package/src/domains/doctor/formatters/doctor.ts

@@ -1,78 +1,130 @@
 import chalk from "chalk";
 import type { Formatters } from "../../shared/formatters.js";
-import type { CheckResult, DoctorData } from "../operations/types.js";
+import type {
+  CheckResult,
+  CheckStatus,
+  DoctorData,
+} from "../operations/types.js";
 
-/** Status icons for pass/fail/skip check results. */
-const STATUS_ICONS = {
+/** Status icons for pass/fail/skip results (checks and sub-items). */
+const STATUS_ICONS: Record<CheckStatus, string> = {
   pass: chalk.green("✓"),
   fail: chalk.red("✗"),
   skip: chalk.yellow("○"),
-} as const;
+};
+
+const SUB_BULLET = chalk.dim("·");
+const FIX_ARROW = chalk.cyan("↳");
+const INDENT = "     "; // aligns sub-lines under the check name
 
 /**
- * Format a single check result as a styled terminal line.
+ * 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.
  *
- * @param check - The check result to format.
- * @returns A single-line string with status icon, name, and detail.
+ * @param check - The check result to render.
+ * @param nameWidth - Width to pad check names to so details align in a column.
+ * @returns The lines for this check.
  */
-function formatCheckPlain(check: CheckResult): string {
-  return `${STATUS_ICONS[check.status]} ${check.name} ${chalk.dim(check.detail)}`;
+function formatCheckPlain(check: CheckResult, nameWidth: number): string[] {
+  const name = check.name.padEnd(nameWidth);
+  const label = check.status === "fail" ? chalk.red(name) : chalk.bold(name);
+  const lines = [
+    `  ${STATUS_ICONS[check.status]}  ${label}  ${chalk.dim(check.detail)}`,
+  ];
+
+  if (check.items && check.items.length > 0) {
+    const itemWidth = Math.max(...check.items.map((i) => i.label.length));
+    const anyStatus = check.items.some((i) => i.status !== undefined);
+    for (const item of check.items) {
+      const icon = anyStatus
+        ? item.status
+          ? `${STATUS_ICONS[item.status]} `
+          : "  "
+        : "";
+      const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
+      const detail = item.detail ? `  ${chalk.dim(item.detail)}` : "";
+      lines.push(`${INDENT}${SUB_BULLET} ${icon}${itemLabel}${detail}`);
+    }
+  }
+
+  if (check.status === "fail" && check.remedy) {
+    lines.push(`${INDENT}${FIX_ARROW} ${chalk.cyan("fix:")} ${check.remedy}`);
+  }
+
+  return lines;
+}
+
+/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
+function formatSummary(data: DoctorData): string {
+  const parts = [chalk.green(`${data.passed} passed`)];
+  parts.push(
+    data.failed > 0
+      ? chalk.red(`${data.failed} failed`)
+      : chalk.dim(`${data.failed} failed`),
+  );
+  parts.push(
+    data.skipped > 0
+      ? chalk.yellow(`${data.skipped} skipped`)
+      : chalk.dim(`${data.skipped} skipped`),
+  );
+  return `  ${parts.join(chalk.dim(" · "))}`;
 }
 
 /**
  * Formatters for `pragma doctor` output.
  *
- * - **plain** renders a check list with chalk icons and remedial commands.
- * - **llm** renders a markdown list with remedial section.
- * - **json** serializes the raw DoctorData.
+ * - **plain** renders an aligned check list with indented sub-items and
+ *   inline remedies, followed by a summary tally.
+ * - **llm** renders a Markdown list with nested sub-items and inline fixes.
+ * - **json** serializes the raw DoctorData (including `items`).
  */
 const formatters: Formatters<DoctorData> = {
   plain(data) {
-    const lines: string[] = [];
+    const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
+    const lines: string[] = [chalk.bold("pragma doctor"), ""];
 
     for (const check of data.checks) {
-      lines.push(formatCheckPlain(check));
+      lines.push(...formatCheckPlain(check, nameWidth));
     }
 
-    const remedies = data.checks.filter(
-      (c): c is CheckResult & { remedy: string } =>
-        c.status === "fail" && c.remedy !== undefined,
-    );
-
-    if (remedies.length > 0) {
-      lines.push("");
-      for (const r of remedies) {
-        lines.push(
-          `Run ${chalk.cyan(`\`${r.remedy}\``)} to fix ${chalk.dim(r.name)}.`,
-        );
-      }
-    }
+    lines.push("");
+    lines.push(formatSummary(data));
 
     return lines.join("\n");
   },
 
   llm(data) {
-    const lines: string[] = [];
-
-    lines.push("## Doctor");
-    lines.push("");
+    const lines: string[] = ["## Doctor", ""];
 
     for (const check of data.checks) {
       const icon =
         check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
       lines.push(`- ${icon} **${check.name}**: ${check.detail}`);
-    }
 
-    const remedies = data.checks.filter((c) => c.status === "fail" && c.remedy);
+      for (const item of check.items ?? []) {
+        const itemIcon =
+          item.status === "pass"
+            ? "✓ "
+            : item.status === "fail"
+              ? "✗ "
+              : item.status === "skip"
+                ? "○ "
+                : "";
+        const detail = item.detail ? `: ${item.detail}` : "";
+        lines.push(`  - ${itemIcon}${item.label}${detail}`);
+      }
 
-    if (remedies.length > 0) {
-      lines.push("");
-      lines.push("### Remedial");
-      for (const r of remedies) {
-        lines.push(`- \`${r.remedy}\``);
+      if (check.status === "fail" && check.remedy) {
+        lines.push(`  - _fix:_ \`${check.remedy}\``);
       }
     }
 
+    lines.push("");
+    lines.push(
+      `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,
+    );
+
     return lines.join("\n");
   },
 

package/src/domains/doctor/operations/checks/checkMcpCommands.ts

@@ -3,7 +3,7 @@ import { delimiter, isAbsolute, join } from "node:path";
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
-import type { CheckContext, CheckResult } from "../types.js";
+import type { CheckContext, CheckItem, CheckResult } from "../types.js";
 
 const NAME = "MCP commands";
 
@@ -79,7 +79,7 @@ export default async function checkMcpCommands(
     };
   }
 
-  const broken: string[] = [];
+  const broken: CheckItem[] = [];
   let checked = 0;
 
   for (const d of withConfig) {
@@ -97,9 +97,11 @@ export default async function checkMcpCommands(
 
       checked += 1;
       if (!commandResolves(command, ctx.cwd)) {
-        broken.push(
-          `"${serverName}" ("${command}" not found, ${d.configPath})`,
-        );
+        broken.push({
+          label: `"${serverName}"`,
+          status: "fail",
+          detail: `"${command}" not found · ${d.configPath}`,
+        });
       }
     }
   }
@@ -123,7 +125,8 @@ export default async function checkMcpCommands(
   return {
     name: NAME,
     status: "fail",
-    detail: `unresolvable: ${broken.join("; ")}`,
+    detail: `${broken.length} of ${checked} unresolvable`,
+    items: broken,
     remedy:
       "Install the missing command or remove the entry from the MCP config — every agent session tries and fails to boot it.",
   };

package/src/domains/doctor/operations/checks/checkPackageRefs.ts

@@ -13,7 +13,12 @@ import {
 } from "../../../shared/loaders/index.js";
 import { mergeAndParseRefs } from "../../../shared/mergeAndParseRefs.js";
 import { resolveSemanticPackages } from "../../../shared/semanticPackage.js";
-import type { CheckContext, CheckResult } from "../types.js";
+import type { CheckContext, CheckItem, CheckResult } from "../types.js";
+
+/** Pluralize a count, e.g. `1 graph` / `2 graphs`. */
+function count(n: number, unit: string): string {
+  return `${n} ${unit}${n === 1 ? "" : "s"}`;
+}
 
 export default async function checkPackageRefs(
   ctx: CheckContext,
@@ -27,32 +32,45 @@ export default async function checkPackageRefs(
   ];
   const packages = await resolveSemanticPackages(refs, loaders);
 
-  const details: string[] = [];
-  let hasIssue = false;
+  const items: CheckItem[] = [];
+  let unresolved = 0;
 
   for (const ref of refs) {
     const resolved = packages.find((p) => p.name === ref.pkg);
 
     if (resolved) {
-      details.push(
-        `${ref.pkg}: ${resolved.source} v${resolved.version} (${resolved.graphs.length} graphs, ${resolved.skills.length} skills)`,
-      );
+      items.push({
+        label: ref.pkg,
+        status: "pass",
+        detail: `${resolved.source} v${resolved.version} · ${count(resolved.graphs.length, "graph")}, ${count(resolved.skills.length, "skill")}`,
+      });
     } else {
       // Check if covered by bundled fallback
       const bundled = packages.find((p) => p.name === "(bundled)");
       if (bundled) {
-        details.push(`${ref.pkg}: bundled v${bundled.version}`);
+        items.push({
+          label: ref.pkg,
+          status: "pass",
+          detail: `bundled fallback v${bundled.version}`,
+        });
       } else {
-        details.push(`${ref.pkg}: NOT RESOLVED`);
-        hasIssue = true;
+        items.push({ label: ref.pkg, status: "fail", detail: "not resolved" });
+        unresolved += 1;
       }
     }
   }
 
+  const total = refs.length;
+  const detail =
+    unresolved > 0
+      ? `${unresolved} of ${count(total, "package")} not resolved`
+      : `${count(total, "package")} resolved`;
+
   return {
     name: "package refs",
-    status: hasIssue ? "fail" : "pass",
-    detail: details.join("; "),
-    ...(hasIssue ? { remedy: "pragma update-refs" } : {}),
+    status: unresolved > 0 ? "fail" : "pass",
+    detail,
+    items,
+    ...(unresolved > 0 ? { remedy: "pragma update-refs" } : {}),
   };
 }

package/src/domains/doctor/operations/checks.test.ts

@@ -268,8 +268,9 @@ describe("checkMcpCommands", () => {
 
     const result = await checkMcpCommands(ctx);
     expect(result.status).toBe("fail");
-    expect(result.detail).toContain('"sem"');
-    expect(result.detail).toContain("/test/.mcp.json");
+    const semItem = result.items?.find((i) => i.label === '"sem"');
+    expect(semItem).toBeDefined();
+    expect(semItem?.detail).toContain("/test/.mcp.json");
     expect(result.remedy).toBeDefined();
   });
 
@@ -291,8 +292,9 @@ describe("checkMcpCommands", () => {
 
     const result = await checkMcpCommands(ctx);
     expect(result.status).toBe("fail");
-    expect(result.detail).toContain('"sem"');
-    expect(result.detail).not.toContain('"pragma"');
+    const labels = (result.items ?? []).map((i) => i.label);
+    expect(labels).toContain('"sem"');
+    expect(labels).not.toContain('"pragma"');
   });
 });
 

package/src/domains/doctor/operations/types.ts

@@ -1,8 +1,30 @@
+/** Status of a doctor check or one of its sub-items. */
+export type CheckStatus = "pass" | "fail" | "skip";
+
+/**
+ * A structured sub-item under a check — e.g. one resolved package under
+ * `package refs`, or one unresolvable server under `MCP commands`. Lets the
+ * formatter render an indented, aligned breakdown instead of cramming
+ * everything into a single `detail` string.
+ */
+export interface CheckItem {
+  /** Left-column label (e.g. the package or server name). */
+  readonly label: string;
+  /** Right-column detail (e.g. `git v0.1.2 · 362 graphs`). */
+  readonly detail?: string;
+  /** Optional per-item status, rendered as its own icon. */
+  readonly status?: CheckStatus;
+}
+
 /** Result of a single doctor check. */
 export interface CheckResult {
   readonly name: string;
-  readonly status: "pass" | "fail" | "skip";
+  readonly status: CheckStatus;
+  /** One-line headline shown next to the check name. */
   readonly detail: string;
+  /** Optional structured breakdown, rendered as indented sub-items. */
+  readonly items?: readonly CheckItem[];
+  /** Remedial instruction shown inline under a failing check. */
   readonly remedy?: string;
 }
 

package/src/domains/graph/commands/inspect.test.ts

@@ -2,7 +2,7 @@ import type { CommandDefinition } from "@canonical/cli-core";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import createTestRuntime from "../../../testing/helpers/createTestRuntime.js";
 import type { PragmaContext } from "../../shared/context.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import type { PragmaRuntime } from "../../shared/runtime.js";
 import type { InspectResult } from "../../shared/types/index.js";
 import buildInspectCommand from "./inspect.js";
@@ -37,7 +37,7 @@ async function executeOutput(
 }
 
 describe("graph inspect command", () => {
-  const uri = `${PREFIX_MAP.ds}global.component.button`;
+  const uri = `${DEFAULT_PREFIX_MAP.ds}global.component.button`;
 
   it("returns inspect results", async () => {
     const ctx = makeCtx();

package/src/domains/graph/commands/query.test.ts

@@ -58,15 +58,17 @@ describe("graph query command", () => {
     expect(text).toContain("n");
   });
 
-  it("renders llm output", async () => {
+  it("renders llm output as a Markdown table for SELECT", async () => {
     const ctx = makeCtx({
       globalFlags: { llm: true, format: "text" as const, verbose: false },
     });
     const cmd = buildQueryCommand(ctx);
     const { text } = await executeOutput(cmd, { sparql }, ctx);
 
-    const parsed = JSON.parse(text) as QueryResult;
-    expect(parsed.type).toBe("select");
+    // Condensed Markdown, not a raw JSON dump.
+    expect(text).toContain("| n |");
+    expect(text).toContain("| --- |");
+    expect(() => JSON.parse(text)).toThrow();
   });
 
   it("renders json output", async () => {

package/src/domains/graph/formatters/inspect.ts

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import { formatHeading } from "#pipeline";
 import compactUri from "../../shared/compactUri.js";
 import type { Formatters } from "../../shared/formatters.js";
-import { PREFIX_MAP } from "../../shared/prefixes.js";
+import { DEFAULT_PREFIX_MAP } from "../../shared/prefixes.js";
 import type { InspectResult } from "../../shared/types/index.js";
 
 /**
@@ -15,13 +15,13 @@ import type { InspectResult } from "../../shared/types/index.js";
 const formatters: Formatters<InspectResult> = {
   plain(result) {
     const lines: string[] = [];
-    lines.push(formatHeading(compactUri(result.uri, PREFIX_MAP)));
+    lines.push(formatHeading(compactUri(result.uri, DEFAULT_PREFIX_MAP)));
 
     for (const g of result.groups) {
       lines.push("");
-      lines.push(chalk.bold(compactUri(g.predicate, PREFIX_MAP)));
+      lines.push(chalk.bold(compactUri(g.predicate, DEFAULT_PREFIX_MAP)));
       for (const o of g.objects) {
-        lines.push(`  ${compactUri(o, PREFIX_MAP)}`);
+        lines.push(`  ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
       }
     }
 
@@ -30,13 +30,13 @@ const formatters: Formatters<InspectResult> = {
 
   llm(result) {
     const lines = [
-      `## ${compactUri(result.uri, PREFIX_MAP)} (${result.uri})`,
+      `## ${compactUri(result.uri, DEFAULT_PREFIX_MAP)} (${result.uri})`,
       "",
     ];
     for (const g of result.groups) {
-      lines.push(`**${compactUri(g.predicate, PREFIX_MAP)}:**`);
+      lines.push(`**${compactUri(g.predicate, DEFAULT_PREFIX_MAP)}:**`);
       for (const o of g.objects) {
-        lines.push(`  - ${compactUri(o, PREFIX_MAP)}`);
+        lines.push(`  - ${compactUri(o, DEFAULT_PREFIX_MAP)}`);
       }
     }
     return lines.join("\n");

package/src/domains/graph/formatters/query.test.ts

@@ -0,0 +1,87 @@
+import type { QueryResult } from "@canonical/ke";
+import { describe, expect, it } from "vitest";
+import formatters from "./query.js";
+
+const selectResult = {
+  type: "select",
+  bindings: [
+    { s: "a", n: "1" },
+    { s: "b", n: "2" },
+  ],
+} as unknown as QueryResult;
+
+const emptySelect = {
+  type: "select",
+  bindings: [],
+} as unknown as QueryResult;
+
+const askResult = { type: "ask", result: true } as unknown as QueryResult;
+
+const constructResult = {
+  type: "construct",
+  triples: [
+    { subject: "s1", predicate: "p1", object: "line one\nline two" },
+    { subject: "s2", predicate: "p2", object: "o2" },
+  ],
+} as unknown as QueryResult;
+
+const emptyConstruct = {
+  type: "construct",
+  triples: [],
+} as unknown as QueryResult;
+
+describe("graph query formatters — plain", () => {
+  it("renders SELECT as a tab table", () => {
+    const text = formatters.plain(selectResult);
+    expect(text.split("\n")).toEqual(["s\tn", "a\t1", "b\t2"]);
+  });
+
+  it("reports no results for an empty SELECT", () => {
+    expect(formatters.plain(emptySelect)).toBe("No results.");
+  });
+
+  it("renders ASK as a boolean", () => {
+    expect(formatters.plain(askResult)).toBe("ASK: true");
+  });
+
+  it("renders CONSTRUCT as one-line triples", () => {
+    const text = formatters.plain(constructResult);
+    expect(text).toContain("s1\tp1\tline one line two");
+    expect(text).toContain("s2\tp2\to2");
+  });
+
+  it("reports no triples for an empty CONSTRUCT", () => {
+    expect(formatters.plain(emptyConstruct)).toBe("No triples.");
+  });
+});
+
+describe("graph query formatters — llm", () => {
+  it("renders SELECT as a Markdown table", () => {
+    const text = formatters.llm(selectResult);
+    expect(text).toContain("| s | n |");
+    expect(text).toContain("| --- | --- |");
+    expect(text).toContain("| a | 1 |");
+  });
+
+  it("renders an empty SELECT as italic no-results", () => {
+    expect(formatters.llm(emptySelect)).toBe("_No results._");
+  });
+
+  it("renders ASK as bold", () => {
+    expect(formatters.llm(askResult)).toBe("**ASK** → true");
+  });
+
+  it("renders CONSTRUCT triples as a bullet list", () => {
+    const text = formatters.llm(constructResult);
+    expect(text).toContain("- s1\tp1\tline one line two");
+  });
+});
+
+describe("graph query formatters — json", () => {
+  it("serializes the raw result", () => {
+    expect(JSON.parse(formatters.json(askResult))).toMatchObject({
+      type: "ask",
+      result: true,
+    });
+  });
+});

package/src/domains/graph/formatters/query.ts

@@ -1,12 +1,33 @@
 import type { QueryResult } from "@canonical/ke";
 import type { Formatters } from "../../shared/formatters.js";
 
+/**
+ * Render CONSTRUCT triples as readable `subject  predicate  object` lines,
+ * collapsing any newlines in literal objects so each triple stays on one line.
+ */
+function formatTriples(
+  triples: ReadonlyArray<{
+    subject: string;
+    predicate: string;
+    object: string;
+  }>,
+): string {
+  if (triples.length === 0) return "No triples.";
+  return triples
+    .map((t) => {
+      const object = t.object.replace(/\s*\n\s*/g, " ").trim();
+      return `${t.subject}\t${t.predicate}\t${object}`;
+    })
+    .join("\n");
+}
+
 /**
  * Formatters for `pragma graph query` output.
  *
- * - **plain**: tab-separated table for SELECT results, `ASK: true/false` for ASK
- *   queries, JSON fallback for CONSTRUCT.
- * - **llm**: indented JSON for all query types.
+ * - **plain**: tab-separated table for SELECT, `ASK: true/false` for ASK, and
+ *   readable triple lines for CONSTRUCT.
+ * - **llm**: condensed Markdown (table for SELECT, one line for ASK, a triple
+ *   list for CONSTRUCT) rather than a raw JSON dump.
  * - **json**: serialized {@link QueryResult} as indented JSON.
  */
 const formatters: Formatters<QueryResult> = {
@@ -22,11 +43,27 @@ const formatters: Formatters<QueryResult> = {
     if (result.type === "ask") {
       return `ASK: ${String(result.result)}`;
     }
-    return JSON.stringify(result, null, 2);
+    return formatTriples(result.triples);
   },
 
   llm(result) {
-    return JSON.stringify(result, null, 2);
+    if (result.type === "select") {
+      if (result.bindings.length === 0) return "_No results._";
+      const cols = Object.keys(result.bindings[0] ?? {});
+      const header = `| ${cols.join(" | ")} |`;
+      const divider = `| ${cols.map(() => "---").join(" | ")} |`;
+      const rows = result.bindings.map(
+        (b) => `| ${cols.map((c) => b[c] ?? "").join(" | ")} |`,
+      );
+      return [header, divider, ...rows].join("\n");
+    }
+    if (result.type === "ask") {
+      return `**ASK** → ${String(result.result)}`;
+    }
+    return formatTriples(result.triples)
+      .split("\n")
+      .map((line) => (line.includes("\t") ? `- ${line}` : line))
+      .join("\n");
   },
 
   json(result) {