@canonical/pragma-cli 0.18.0

package/src/domains/doctor/commands/doctor.ts

@@ -0,0 +1,43 @@
+import type { CommandContext } from "@canonical/cli-core";
+import {
+  type CommandDefinition,
+  type CommandResult,
+  createOutputResult,
+} from "@canonical/cli-core";
+import { selectFormatter } from "../../shared/formatters.js";
+import { doctorFormatters } from "../formatters/index.js";
+import { runChecks } from "../operations/index.js";
+
+/**
+ * `pragma doctor` command definition.
+ *
+ * Runs all environment health checks (Node version, pragma installation,
+ * config file, ke store, shell completions, MCP, skills)
+ * and sets exit code 1 when any check fails.
+ *
+ * @note Impure
+ */
+const doctorCommand: CommandDefinition = {
+  path: ["doctor"],
+  description: "Check environment health",
+  parameters: [],
+  meta: {
+    examples: ["pragma doctor"],
+  },
+  execute: async (
+    _params: Record<string, unknown>,
+    ctx: CommandContext,
+  ): Promise<CommandResult> => {
+    const data = await runChecks({ cwd: ctx.cwd });
+
+    if (data.failed > 0) {
+      process.exitCode = 1;
+    }
+
+    return createOutputResult(data, {
+      plain: selectFormatter(ctx, doctorFormatters),
+    });
+  },
+};
+
+export default doctorCommand;

package/src/domains/doctor/commands/index.ts

@@ -0,0 +1,2 @@
+/** @module Doctor command definitions. */
+export { default as doctorCommand } from "./doctor.js";

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

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import type { DoctorData } from "../operations/types.js";
+import formatters from "./doctor.js";
+
+const allPass: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v24.1.0" },
+    {
+      name: "pragma version",
+      status: "pass",
+      detail: "v0.18.0 (installed via bun, global)",
+    },
+    { name: "pragma.config.json", status: "pass", detail: "found" },
+    {
+      name: "ke store",
+      status: "pass",
+      detail: "12,847 triples in 180ms",
+    },
+  ],
+  passed: 4,
+  failed: 0,
+  skipped: 0,
+};
+
+const mixed: DoctorData = {
+  checks: [
+    { name: "Node version", status: "pass", detail: "v24.1.0" },
+    {
+      name: "pragma.config.json",
+      status: "fail",
+      detail: "not found",
+      remedy: "pragma config tier <tier>",
+    },
+    {
+      name: "skills",
+      status: "skip",
+      detail: "no harnesses detected",
+    },
+    {
+      name: "Shell completions",
+      status: "fail",
+      detail: "not installed",
+      remedy: "pragma setup completions",
+    },
+  ],
+  passed: 1,
+  failed: 2,
+  skipped: 1,
+};
+
+describe("doctor formatters", () => {
+  describe("plain", () => {
+    it("renders passing checks with ✓", () => {
+      const output = formatters.plain(allPass);
+      expect(output).toContain("✓");
+      expect(output).toContain("Node version");
+      expect(output).toContain("v24.1.0");
+    });
+
+    it("renders failing checks with ✗ and remedies at the bottom", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("✗");
+      expect(output).toContain("pragma config tier <tier>");
+      expect(output).toContain("pragma setup completions");
+    });
+
+    it("renders skipped checks with ○", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("○");
+      expect(output).toContain("skills");
+    });
+
+    it("does not render remedies section when all pass", () => {
+      const output = formatters.plain(allPass);
+      expect(output).not.toContain("Run ");
+    });
+  });
+
+  describe("llm", () => {
+    it("renders Markdown with ## Doctor heading", () => {
+      const output = formatters.llm(allPass);
+      expect(output).toContain("## Doctor");
+    });
+
+    it("renders checks as bullet list", () => {
+      const output = formatters.llm(allPass);
+      expect(output).toContain("- ✓ **Node version**: v24.1.0");
+    });
+
+    it("includes remedial section for failures", () => {
+      const output = formatters.llm(mixed);
+      expect(output).toContain("### Remedial");
+      expect(output).toContain("`pragma config tier <tier>`");
+      expect(output).toContain("`pragma setup completions`");
+    });
+  });
+
+  describe("json", () => {
+    it("returns valid JSON matching the data shape", () => {
+      const output = formatters.json(allPass);
+      const parsed = JSON.parse(output);
+      expect(parsed.passed).toBe(4);
+      expect(parsed.failed).toBe(0);
+      expect(parsed.checks).toHaveLength(4);
+    });
+
+    it("includes remedy fields for failed checks", () => {
+      const output = formatters.json(mixed);
+      const parsed = JSON.parse(output);
+      const failedChecks = parsed.checks.filter(
+        (c: { status: string }) => c.status === "fail",
+      );
+      expect(failedChecks).toHaveLength(2);
+      expect(failedChecks[0].remedy).toBeDefined();
+    });
+  });
+});

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

@@ -0,0 +1,84 @@
+import chalk from "chalk";
+import type { Formatters } from "../../shared/formatters.js";
+import type { CheckResult, DoctorData } from "../operations/types.js";
+
+/** Status icons for pass/fail/skip check results. */
+const STATUS_ICONS = {
+  pass: chalk.green("✓"),
+  fail: chalk.red("✗"),
+  skip: chalk.yellow("○"),
+} as const;
+
+/**
+ * Format a single check result as a styled terminal line.
+ *
+ * @param check - The check result to format.
+ * @returns A single-line string with status icon, name, and detail.
+ */
+function formatCheckPlain(check: CheckResult): string {
+  return `${STATUS_ICONS[check.status]} ${check.name} ${chalk.dim(check.detail)}`;
+}
+
+/**
+ * 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.
+ */
+const formatters: Formatters<DoctorData> = {
+  plain(data) {
+    const lines: string[] = [];
+
+    for (const check of data.checks) {
+      lines.push(formatCheckPlain(check));
+    }
+
+    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)}.`,
+        );
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const lines: string[] = [];
+
+    lines.push("## Doctor");
+    lines.push("");
+
+    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);
+
+    if (remedies.length > 0) {
+      lines.push("");
+      lines.push("### Remedial");
+      for (const r of remedies) {
+        lines.push(`- \`${r.remedy}\``);
+      }
+    }
+
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data, null, 2);
+  },
+};
+
+export default formatters;

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

@@ -0,0 +1,2 @@
+/** @module Formatter sets for doctor domain output. */
+export { default as doctorFormatters } from "./doctor.js";

package/src/domains/doctor/index.ts

@@ -0,0 +1,9 @@
+/** @module Doctor domain -- environment health checks via `pragma doctor`. */
+export { doctorCommand } from "./commands/index.js";
+export { specs as mcpSpecs } from "./mcp/index.js";
+export type {
+  CheckContext,
+  CheckResult,
+  DoctorData,
+} from "./operations/index.js";
+export { runChecks } from "./operations/index.js";

package/src/domains/doctor/mcp/index.ts

@@ -0,0 +1,2 @@
+/** @module Doctor domain MCP barrel — doctor, info. */
+export { default as specs } from "./specs.js";

package/src/domains/doctor/mcp/specs.ts

@@ -0,0 +1,88 @@
+/**
+ * MCP tool specs for doctor domain — doctor, info.
+ *
+ * The info tool is cross-domain: it uses operations and formatters from
+ * the info domain, plus VERSION from #constants.
+ */
+
+import { VERSION } from "#constants";
+import { detectInstallSource } from "#package-manager";
+import { renderInfoLlm } from "../../info/formatters/index.js";
+import { collectStoreSummary } from "../../info/operations/index.js";
+import type { InfoData } from "../../info/types.js";
+import type { ToolSpec } from "../../shared/ToolSpec.js";
+import { doctorFormatters } from "../formatters/index.js";
+import { runChecks } from "../operations/index.js";
+
+const specs: readonly ToolSpec[] = [
+  {
+    name: "doctor",
+    description:
+      "Run health checks on the pragma environment. Validates config, store, completions, skills, and more.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      const result = await runChecks({ cwd: rt.cwd });
+
+      if (params.condensed) {
+        const text = doctorFormatters.llm(result);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data: result };
+    },
+  },
+  {
+    name: "info",
+    description: "Show pragma version, configuration, and store summary.",
+    params: {
+      condensed: {
+        type: "boolean",
+        description: "Token-optimized output",
+        optional: true,
+      },
+    },
+    readOnly: true,
+    async execute(rt, params) {
+      const storeSummary = await collectStoreSummary(rt.store);
+      const install = detectInstallSource();
+
+      const data: InfoData = {
+        version: VERSION,
+        pm: install.packageManager,
+        installSource: install.label,
+        configPath: "pragma.config.json",
+        tier: rt.config.tier,
+        tierChain: [],
+        channel: rt.config.channel,
+        channelReleases: [],
+        update: undefined,
+        updateSkipped: true,
+        store: storeSummary,
+      };
+
+      if (params.condensed) {
+        const text = renderInfoLlm(data);
+        return {
+          condensed: true,
+          text,
+          tokens: `~${Math.ceil(text.length / 4)}`,
+        };
+      }
+
+      return { data };
+    },
+  },
+];
+
+export default specs;

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

@@ -0,0 +1,28 @@
+import { configExists } from "#config";
+import type { CheckContext, CheckResult } from "../types.js";
+
+/**
+ * Check that `pragma.config.json` exists in the working directory.
+ *
+ * @param ctx - Check context with the working directory.
+ * @returns A CheckResult indicating pass or fail.
+ * @note Impure
+ */
+export default async function checkConfigFile(
+  ctx: CheckContext,
+): Promise<CheckResult> {
+  if (configExists(ctx.cwd)) {
+    return {
+      name: "pragma.config.json",
+      status: "pass",
+      detail: "found",
+    };
+  }
+
+  return {
+    name: "pragma.config.json",
+    status: "fail",
+    detail: "not found",
+    remedy: "pragma config tier <tier>",
+  };
+}

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

@@ -0,0 +1,38 @@
+import { collectStoreSummary } from "../../../info/operations/index.js";
+import { bootStore } from "../../../shared/bootStore.js";
+import type { CheckContext, CheckResult } from "../types.js";
+
+/**
+ * Check that the ke store boots successfully, reporting triple count
+ * and boot time.
+ *
+ * @param ctx - Check context with the working directory.
+ * @returns A CheckResult indicating pass (with triple count) or fail.
+ * @note Impure
+ */
+export default async function checkKeStore(
+  ctx: CheckContext,
+): Promise<CheckResult> {
+  const start = performance.now();
+  let store: Awaited<ReturnType<typeof bootStore>> | undefined;
+  try {
+    store = await bootStore({ cwd: ctx.cwd });
+    const summary = await collectStoreSummary(store);
+    const elapsed = Math.round(performance.now() - start);
+    return {
+      name: "ke store",
+      status: "pass",
+      detail: `${summary.tripleCount.toLocaleString()} triples in ${elapsed}ms`,
+    };
+  } catch {
+    return {
+      name: "ke store",
+      status: "fail",
+      detail: "failed to boot",
+      remedy:
+        "Ensure design system packages are installed: bun add -D @canonical/ds-global @canonical/code-standards",
+    };
+  } finally {
+    store?.dispose();
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
+import { runTask } from "@canonical/task";
+import type { CheckContext, CheckResult } from "../types.js";
+
+/**
+ * Check that at least one AI harness has pragma configured as an MCP server.
+ *
+ * @param ctx - Check context with the working directory.
+ * @returns A CheckResult listing configured harnesses, or fail with remedy.
+ * @note Impure
+ */
+export default async function checkMcpConfigured(
+  ctx: CheckContext,
+): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(ctx.cwd));
+  } catch {
+    return {
+      name: "MCP configured",
+      status: "fail",
+      detail: "harness detection failed",
+      remedy: "pragma setup mcp",
+    };
+  }
+
+  if (detected.length === 0) {
+    return {
+      name: "MCP configured",
+      status: "fail",
+      detail: "no AI harnesses detected",
+      remedy: "pragma setup mcp",
+    };
+  }
+
+  const configured: string[] = [];
+  for (const d of detected) {
+    if (!d.configExists) continue;
+    try {
+      const servers = await runTask(readMcpConfig(d.harness, ctx.cwd));
+      if ("pragma" in servers) {
+        configured.push(d.harness.name);
+      }
+    } catch {
+      // Config unreadable — skip
+    }
+  }
+
+  if (configured.length > 0) {
+    return {
+      name: "MCP configured",
+      status: "pass",
+      detail: configured.join(", "),
+    };
+  }
+
+  const names = detected.map((d) => d.harness.name).join(", ");
+  return {
+    name: "MCP configured",
+    status: "fail",
+    detail: `detected ${names} but pragma not configured`,
+    remedy: "pragma setup mcp",
+  };
+}

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

@@ -0,0 +1,25 @@
+import type { CheckResult } from "../types.js";
+
+const MIN_NODE_MAJOR = 20;
+
+/**
+ * Check that the Node.js major version is at least {@link MIN_NODE_MAJOR}.
+ *
+ * @returns A CheckResult with the current version and pass/fail status.
+ * @note Impure
+ */
+export default async function checkNodeVersion(): Promise<CheckResult> {
+  const version = process.versions.node;
+  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
+
+  if (major >= MIN_NODE_MAJOR) {
+    return { name: "Node version", status: "pass", detail: `v${version}` };
+  }
+
+  return {
+    name: "Node version",
+    status: "fail",
+    detail: `v${version} (requires >= ${MIN_NODE_MAJOR})`,
+    remedy: `Install Node.js >= ${MIN_NODE_MAJOR}`,
+  };
+}

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

@@ -0,0 +1,20 @@
+import { VERSION } from "#constants";
+import { detectInstallSource } from "#package-manager";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Report pragma version, install method, and global/local status.
+ * Always passes -- this is purely informational.
+ *
+ * @returns A CheckResult with version and install details.
+ * @note Impure
+ */
+export default async function checkPragmaVersion(): Promise<CheckResult> {
+  const install = detectInstallSource();
+
+  return {
+    name: "pragma version",
+    status: "pass",
+    detail: `v${VERSION} (installed via ${install.label})`,
+  };
+}

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

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { CheckResult } from "../types.js";
+
+/**
+ * Check whether "pragma" appears in any of the user's shell RC files
+ * (`.bashrc`, `.zshrc`, `config.fish`), indicating completions are installed.
+ *
+ * @returns A CheckResult indicating pass (installed) or fail with remedy.
+ * @note Impure
+ */
+export default async function checkShellCompletions(): Promise<CheckResult> {
+  const home = homedir();
+  const rcFiles = [
+    join(home, ".bashrc"),
+    join(home, ".zshrc"),
+    join(home, ".config", "fish", "config.fish"),
+  ];
+
+  for (const rcFile of rcFiles) {
+    try {
+      const content = readFileSync(rcFile, "utf-8");
+      if (content.includes("pragma")) {
+        return {
+          name: "Shell completions",
+          status: "pass",
+          detail: "installed",
+        };
+      }
+    } catch {
+      // File doesn't exist — continue
+    }
+  }
+
+  return {
+    name: "Shell completions",
+    status: "fail",
+    detail: "not installed",
+    remedy: "pragma setup completions",
+  };
+}

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

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import type { DetectedHarness } from "@canonical/harnesses";
+import { detectHarnesses } from "@canonical/harnesses";
+import { runTask } from "@canonical/task";
+import type { CheckContext, CheckResult } from "../types.js";
+
+/**
+ * Check that skill directories exist for each detected AI harness.
+ * Skipped when no harnesses are detected.
+ *
+ * @param ctx - Check context with the working directory.
+ * @returns A CheckResult indicating pass, fail, or skip.
+ * @note Impure
+ */
+export default async function checkSkillsSymlinked(
+  ctx: CheckContext,
+): Promise<CheckResult> {
+  let detected: DetectedHarness[];
+  try {
+    detected = await runTask(detectHarnesses(ctx.cwd));
+  } catch {
+    return {
+      name: "Skills symlinked",
+      status: "fail",
+      detail: "harness detection failed",
+      remedy: "pragma setup skills",
+    };
+  }
+
+  if (detected.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "skip",
+      detail: "no AI harnesses detected",
+    };
+  }
+
+  const linked: string[] = [];
+  const missing: string[] = [];
+
+  for (const d of detected) {
+    const skillsPath = d.harness.skillsPath(ctx.cwd);
+    if (existsSync(skillsPath)) {
+      linked.push(d.harness.name);
+    } else {
+      missing.push(d.harness.name);
+    }
+  }
+
+  if (missing.length === 0) {
+    return {
+      name: "Skills symlinked",
+      status: "pass",
+      detail: linked.join(", "),
+    };
+  }
+
+  return {
+    name: "Skills symlinked",
+    status: "fail",
+    detail: `missing for ${missing.join(", ")}`,
+    remedy: "pragma setup skills",
+  };
+}

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

@@ -0,0 +1,8 @@
+/** @module Individual environment health checks invoked by runChecks. */
+export { default as checkConfigFile } from "./checkConfigFile.js";
+export { default as checkKeStore } from "./checkKeStore.js";
+export { default as checkMcpConfigured } from "./checkMcpConfigured.js";
+export { default as checkNodeVersion } from "./checkNodeVersion.js";
+export { default as checkPragmaVersion } from "./checkPragmaVersion.js";
+export { default as checkShellCompletions } from "./checkShellCompletions.js";
+export { default as checkSkillsSymlinked } from "./checkSkillsSymlinked.js";