@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -1,84 +0,0 @@
-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

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

package/src/domains/doctor/index.ts

@@ -1,9 +0,0 @@
-/** @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

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

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

@@ -1,41 +0,0 @@
-/**
- * MCP tool specs for the doctor domain.
- *
- * The info tool has moved to its own domain: `info/mcp/specs.ts`.
- */
-
-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 };
-    },
-  },
-];
-
-export default specs;

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

@@ -1,42 +0,0 @@
-import { readConfigLayers } from "#config";
-import type { CheckContext, CheckResult } from "../types.js";
-
-/**
- * Check which config layer is active for the working directory.
- *
- * Passes when a project `pragma.config.json` is found up the tree, or —
- * pragma is global-first — when only the global XDG config exists. Fails
- * only when neither layer is configured.
- *
- * @param ctx - Check context with the working directory.
- * @returns A CheckResult indicating pass or fail with the active layer.
- * @note Impure
- */
-export default async function checkConfigFile(
-  ctx: CheckContext,
-): Promise<CheckResult> {
-  const layers = readConfigLayers(ctx.cwd);
-
-  if (layers.project.exists) {
-    return {
-      name: "pragma.config.json",
-      status: "pass",
-      detail: `found (${layers.project.path})`,
-    };
-  }
-
-  if (layers.global.exists) {
-    return {
-      name: "pragma.config.json",
-      status: "pass",
-      detail: `no project config — global config active (${layers.global.path})`,
-    };
-  }
-
-  return {
-    name: "pragma.config.json",
-    status: "fail",
-    detail: "not found",
-    remedy: "pragma config tier <tier>",
-  };
-}

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

@@ -1,38 +0,0 @@
-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 result: Awaited<ReturnType<typeof bootStore>> | undefined;
-  try {
-    result = await bootStore({ cwd: ctx.cwd });
-    const summary = await collectStoreSummary(result.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/design-system @canonical/anatomy-dsl @canonical/code-standards",
-    };
-  } finally {
-    result?.store.dispose();
-  }
-}

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

@@ -1,130 +0,0 @@
-import { existsSync } from "node:fs";
-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";
-
-const NAME = "MCP commands";
-
-/**
- * Extract the stdio command from an MCP server config entry, if any.
- * HTTP/SSE entries (e.g. `{ "type": "http", "url": ... }`) have no command
- * and are not checked.
- *
- * @param entry - Raw server entry from a harness MCP config.
- * @returns The command string, or `undefined` when the entry is not
- *   command-based.
- */
-function commandOf(entry: unknown): string | undefined {
-  if (typeof entry !== "object" || entry === null) return undefined;
-  const command = (entry as { command?: unknown }).command;
-  return typeof command === "string" && command.length > 0
-    ? command
-    : undefined;
-}
-
-/**
- * Resolve a command the way a shell would: entries containing a path
- * separator are checked as file paths (relative to the project root),
- * bare names are searched across `PATH`.
- *
- * @param command - Command string from an MCP server entry.
- * @param cwd - Project root for resolving relative paths.
- * @returns Whether the command resolves to an existing file.
- * @note Impure — reads `process.env.PATH` and the filesystem.
- */
-function commandResolves(command: string, cwd: string): boolean {
-  if (command.includes("/") || command.includes("\\")) {
-    return existsSync(isAbsolute(command) ? command : join(cwd, command));
-  }
-
-  return (process.env.PATH ?? "")
-    .split(delimiter)
-    .filter((dir) => dir.length > 0)
-    .some((dir) => existsSync(join(dir, command)));
-}
-
-/**
- * Check that every command-based MCP server entry in detected harness
- * configs resolves to an executable. A dead entry (e.g. a leftover server
- * whose binary was never installed) makes every agent session try and fail
- * to boot it, so it is flagged with the offending config path.
- *
- * @param ctx - Check context with the working directory.
- * @returns A CheckResult: pass when all commands resolve, fail listing the
- *   broken entries, or skip when there is nothing to check.
- * @note Impure
- */
-export default async function checkMcpCommands(
-  ctx: CheckContext,
-): Promise<CheckResult> {
-  let detected: DetectedHarness[];
-  try {
-    detected = await runTask(detectHarnesses(ctx.cwd));
-  } catch {
-    return {
-      name: NAME,
-      status: "skip",
-      detail: "harness detection failed",
-    };
-  }
-
-  const withConfig = detected.filter((d) => d.configExists);
-  if (withConfig.length === 0) {
-    return {
-      name: NAME,
-      status: "skip",
-      detail: "no MCP configs found",
-    };
-  }
-
-  const broken: string[] = [];
-  let checked = 0;
-
-  for (const d of withConfig) {
-    let servers: Record<string, unknown>;
-    try {
-      servers = await runTask(readMcpConfig(d.harness, ctx.cwd));
-    } catch {
-      // Config unreadable — the "MCP configured" check reports on this.
-      continue;
-    }
-
-    for (const [serverName, entry] of Object.entries(servers)) {
-      const command = commandOf(entry);
-      if (!command) continue;
-
-      checked += 1;
-      if (!commandResolves(command, ctx.cwd)) {
-        broken.push(
-          `"${serverName}" ("${command}" not found, ${d.configPath})`,
-        );
-      }
-    }
-  }
-
-  if (checked === 0) {
-    return {
-      name: NAME,
-      status: "skip",
-      detail: "no command-based MCP servers configured",
-    };
-  }
-
-  if (broken.length === 0) {
-    return {
-      name: NAME,
-      status: "pass",
-      detail: `${checked} command${checked === 1 ? "" : "s"} resolve on PATH`,
-    };
-  }
-
-  return {
-    name: NAME,
-    status: "fail",
-    detail: `unresolvable: ${broken.join("; ")}`,
-    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/checkMcpConfigured.ts

@@ -1,65 +0,0 @@
-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";
-
-/**
- * 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

@@ -1,25 +0,0 @@
-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/checkPackageRefs.ts

@@ -1,58 +0,0 @@
-/**
- * Doctor check: report how each semantic package is resolved.
- *
- * Uses the loader chain (local > git > bundled) to show where each
- * package resolves from, its version, and graph/skill counts.
- */
-
-import { readConfig } from "#config";
-import {
-  createBundledLoader,
-  createGitLoader,
-  createLocalLoader,
-} from "../../../shared/loaders/index.js";
-import { mergeAndParseRefs } from "../../../shared/mergeAndParseRefs.js";
-import { resolveSemanticPackages } from "../../../shared/semanticPackage.js";
-import type { CheckContext, CheckResult } from "../types.js";
-
-export default async function checkPackageRefs(
-  ctx: CheckContext,
-): Promise<CheckResult> {
-  const config = readConfig(ctx.cwd);
-  const refs = mergeAndParseRefs(config.packages);
-  const loaders = [
-    createLocalLoader(),
-    createGitLoader(),
-    createBundledLoader(),
-  ];
-  const packages = await resolveSemanticPackages(refs, loaders);
-
-  const details: string[] = [];
-  let hasIssue = false;
-
-  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)`,
-      );
-    } 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}`);
-      } else {
-        details.push(`${ref.pkg}: NOT RESOLVED`);
-        hasIssue = true;
-      }
-    }
-  }
-
-  return {
-    name: "package refs",
-    status: hasIssue ? "fail" : "pass",
-    detail: details.join("; "),
-    ...(hasIssue ? { remedy: "pragma update-refs" } : {}),
-  };
-}

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

@@ -1,20 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,64 +0,0 @@
-import { existsSync } from "node:fs";
-import type { DetectedHarness } from "@canonical/harnesses";
-import { detectHarnesses } from "@canonical/harnesses";
-import { runTask } from "@canonical/task/node";
-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

@@ -1,10 +0,0 @@
-/** @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 checkMcpCommands } from "./checkMcpCommands.js";
-export { default as checkMcpConfigured } from "./checkMcpConfigured.js";
-export { default as checkNodeVersion } from "./checkNodeVersion.js";
-export { default as checkPackageRefs } from "./checkPackageRefs.js";
-export { default as checkPragmaVersion } from "./checkPragmaVersion.js";
-export { default as checkShellCompletions } from "./checkShellCompletions.js";
-export { default as checkSkillsSymlinked } from "./checkSkillsSymlinked.js";