@canonical/pragma-cli 0.29.0 → 0.30.0

package/src/domains/config/tasks/setTrace.ts

@@ -1,38 +1,20 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import { readConfig } from "../../../config/index.js";
-import resolveConfigPath from "../../../config/resolveConfigPath.js";
+import type { Task } from "@canonical/task";
+import type { ConfigScope } from "../../../config/index.js";
+import writeConfigField from "./writeConfigField.js";
 
 /**
  * Build a config-write task for enabling or disabling query tracing.
  *
- * @param cwd - Working directory containing pragma.config.json.
+ * @param cwd - Working directory the target config layer is resolved from.
  * @param trace - `true` to enable, `false` to disable.
- * @returns Task yielding the persisted field/value payload.
+ * @param scope - Optional explicit target layer (`"global"` | `"local"`).
+ * @returns Task yielding the persisted field/value payload and target path.
+ * @note - Impure — reads and writes the target config file.
  */
 export default function setTrace(
   cwd: string,
   trace: boolean,
-): Task<{ field: "trace"; value: boolean }> {
-  return gen(function* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`)
-    // survive — rebuilding from a fixed field list silently drops everything
-    // not listed, and `packages` is runtime-consumed, so dropping it is data
-    // loss. `readConfig` normalises defaults (tier: undefined, channel:
-    // "normal"); strip those so we keep the file minimal, matching the
-    // existing convention of not persisting unset defaults.
-    const current = readConfig(cwd);
-    const { tier, channel, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { tier } : {}),
-      ...(channel !== "normal" ? { channel } : {}),
-      trace,
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "trace", value: trace };
-  });
+  scope?: ConfigScope,
+): Task<{ field: "trace"; value: boolean | undefined; path: string }> {
+  return writeConfigField(cwd, "trace", trace, scope);
 }

package/src/domains/config/tasks/writeConfigField.ts

@@ -0,0 +1,41 @@
+import { $, gen, type Task, writeFile } from "@canonical/task";
+import {
+  type ConfigScope,
+  type ConfigUpdate,
+  mergeConfigFileUpdate,
+  resolveWriteConfigPath,
+} from "../../../config/index.js";
+
+/**
+ * Build a config-write task for one field.
+ *
+ * Resolves the target layer with the global-first write rule (explicit
+ * scope wins, else the nearest existing project file, else the global XDG
+ * file), merges the update into that file's own contents — never copying
+ * values from another layer — and writes through the tracked `writeFile`
+ * effect so the change participates in dry-run and undo. `undefined`
+ * removes the field from the target file.
+ *
+ * @param cwd - Working directory the project layer is resolved from.
+ * @param field - Config field to set or remove.
+ * @param value - New value, or `undefined` to remove the field.
+ * @param scope - Optional explicit target layer.
+ * @returns Task yielding the persisted field/value payload and the path written.
+ * @note Impure — resolves and reads the target file, writes via effect.
+ */
+export default function writeConfigField<F extends keyof ConfigUpdate>(
+  cwd: string,
+  field: F,
+  value: ConfigUpdate[F],
+  scope?: ConfigScope,
+): Task<{ field: F; value: ConfigUpdate[F]; path: string }> {
+  return gen(function* () {
+    const path = resolveWriteConfigPath(cwd, scope);
+    const update = { [field]: value } as ConfigUpdate;
+    const content = mergeConfigFileUpdate(path, update);
+
+    yield* $(writeFile(path, content));
+
+    return { field, value, path };
+  });
+}

package/src/domains/create/commands/component.ts

@@ -90,7 +90,7 @@ export default function buildComponentCommand(): CommandDefinition {
           validOptions: ["react", "svelte", "lit"],
           recovery: {
             message: "Provide a framework for component generation.",
-            cli: "pragma create component react --component-path src/components/Button",
+            cli: "pragma create component react src/components/Button",
           },
         });
       }
@@ -109,10 +109,10 @@ export default function buildComponentCommand(): CommandDefinition {
     },
     meta: {
       examples: [
-        "pragma create component react --component-path src/components/Button",
-        "pragma create component svelte --component-path src/lib/components/Toggle",
-        "pragma create component lit --component-path src/lib/Accordion",
-        "pragma create component react --component-path src/components/Button --dry-run",
+        "pragma create component react src/components/Button",
+        "pragma create component svelte src/lib/components/Toggle",
+        "pragma create component lit src/lib/Accordion",
+        "pragma create component react src/components/Button --dry-run",
       ],
     },
     parameterGroups: {

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

@@ -1,21 +1,35 @@
-import { configExists } from "#config";
+import { readConfigLayers } from "#config";
 import type { CheckContext, CheckResult } from "../types.js";
 
 /**
- * Check that `pragma.config.json` exists in the working directory.
+ * 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.
+ * @returns A CheckResult indicating pass or fail with the active layer.
  * @note Impure
  */
 export default async function checkConfigFile(
   ctx: CheckContext,
 ): Promise<CheckResult> {
-  if (configExists(ctx.cwd)) {
+  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: "found",
+      detail: `no project config — global config active (${layers.global.path})`,
     };
   }
 

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

@@ -0,0 +1,130 @@
+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,6 +1,6 @@
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import type { CheckContext, CheckResult } from "../types.js";
 
 /**

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

@@ -6,14 +6,12 @@
  */
 
 import { readConfig } from "#config";
-import { parsePackageEntry } from "../../../refs/operations/parseRef.js";
-import readGlobalRefs from "../../../refs/operations/readGlobalRefs.js";
 import {
   createBundledLoader,
   createGitLoader,
   createLocalLoader,
 } from "../../../shared/loaders/index.js";
-import { DEFAULT_PACKAGES } from "../../../shared/packages.js";
+import { mergeAndParseRefs } from "../../../shared/mergeAndParseRefs.js";
 import { resolveSemanticPackages } from "../../../shared/semanticPackage.js";
 import type { CheckContext, CheckResult } from "../types.js";
 
@@ -21,17 +19,7 @@ export default async function checkPackageRefs(
   ctx: CheckContext,
 ): Promise<CheckResult> {
   const config = readConfig(ctx.cwd);
-  const globalEntries = readGlobalRefs();
-
-  const hasProjectRefs = config.packages && config.packages.length > 0;
-
-  const rawEntries = hasProjectRefs
-    ? config.packages!
-    : globalEntries.length > 0
-      ? globalEntries
-      : DEFAULT_PACKAGES;
-
-  const refs = [...rawEntries].map(parsePackageEntry);
+  const refs = mergeAndParseRefs(config.packages);
   const loaders = [
     createLocalLoader(),
     createGitLoader(),

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

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses } from "@canonical/harnesses";
-import { runTask } from "@canonical/task";
+import { runTask } from "@canonical/task/node";
 import type { CheckContext, CheckResult } from "../types.js";
 
 /**

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

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

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

@@ -1,8 +1,12 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 vi.mock("#config", async (importOriginal) => ({
   ...(await importOriginal<typeof import("#config")>()),
   configExists: vi.fn(),
+  readConfigLayers: vi.fn(),
 }));
 vi.mock("../../shared/bootStore.js", () => ({
   bootStore: vi.fn(),
@@ -14,17 +18,18 @@ vi.mock("@canonical/harnesses", () => ({
   detectHarnesses: vi.fn(),
   readMcpConfig: vi.fn(),
 }));
-vi.mock("@canonical/task", () => ({
+vi.mock("@canonical/task/node", () => ({
   runTask: vi.fn((task: unknown) => task),
 }));
 
 import { detectHarnesses, readMcpConfig } from "@canonical/harnesses";
-import { configExists } from "#config";
+import { configExists, readConfigLayers } from "#config";
 import { collectStoreSummary } from "../../info/operations/index.js";
 import { bootStore } from "../../shared/bootStore.js";
 import {
   checkConfigFile,
   checkKeStore,
+  checkMcpCommands,
   checkMcpConfigured,
   checkNodeVersion,
   checkPragmaVersion,
@@ -55,14 +60,55 @@ describe("checkPragmaVersion", () => {
 });
 
 describe("checkConfigFile", () => {
-  it("passes when config exists", async () => {
-    vi.mocked(configExists).mockReturnValue(true);
+  it("passes when a project config exists", async () => {
+    vi.mocked(readConfigLayers).mockReturnValue({
+      config: { tier: undefined, channel: "normal" },
+      origins: {
+        tier: "default",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: false },
+      project: { path: "/repo/pragma.config.json", exists: true },
+    });
+    const result = await checkConfigFile(ctx);
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("/repo/pragma.config.json");
+  });
+
+  it("passes when only the global config exists", async () => {
+    vi.mocked(readConfigLayers).mockReturnValue({
+      config: { tier: undefined, channel: "normal" },
+      origins: {
+        tier: "default",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: true },
+      project: { path: "/repo/pragma.config.json", exists: false },
+    });
     const result = await checkConfigFile(ctx);
     expect(result.status).toBe("pass");
+    expect(result.detail).toContain("global config active");
   });
 
-  it("fails with remedy when config missing", async () => {
-    vi.mocked(configExists).mockReturnValue(false);
+  it("fails with remedy when neither layer exists", async () => {
+    vi.mocked(readConfigLayers).mockReturnValue({
+      config: { tier: undefined, channel: "normal" },
+      origins: {
+        tier: "default",
+        channel: "default",
+        packages: "default",
+        trace: "default",
+        framework: "default",
+      },
+      global: { path: "/home/u/.config/pragma/config.json", exists: false },
+      project: { path: "/repo/pragma.config.json", exists: false },
+    });
     const result = await checkConfigFile(ctx);
     expect(result.status).toBe("fail");
     expect(result.remedy).toBeDefined();
@@ -145,6 +191,111 @@ describe("checkMcpConfigured", () => {
   });
 });
 
+describe("checkMcpCommands", () => {
+  const harness = {
+    id: "claude-code",
+    name: "Claude Code",
+    configPath: () => "/test/.mcp.json",
+    skillsPath: () => "/test/.claude/skills",
+    detect: [],
+    version: "*",
+    configFormat: "json" as const,
+    mcpKey: "mcpServers",
+  };
+  const detected = {
+    harness,
+    confidence: "high" as const,
+    configExists: true,
+    configPath: "/test/.mcp.json",
+  };
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("skips when no harnesses detected", async () => {
+    vi.mocked(detectHarnesses).mockReturnValue(Promise.resolve([]) as never);
+    const result = await checkMcpCommands(ctx);
+    expect(result.status).toBe("skip");
+  });
+
+  it("skips when only URL-based servers are configured", async () => {
+    vi.mocked(detectHarnesses).mockReturnValue(
+      Promise.resolve([detected]) as never,
+    );
+    vi.mocked(readMcpConfig).mockReturnValue(
+      Promise.resolve({
+        figma: { type: "http", url: "https://mcp.figma.com/mcp" },
+      }) as never,
+    );
+
+    const result = await checkMcpCommands(ctx);
+    expect(result.status).toBe("skip");
+    expect(result.detail).toContain("no command-based");
+  });
+
+  it("passes when every configured command resolves on PATH", async () => {
+    const binDir = mkdtempSync(join(tmpdir(), "pragma-doctor-"));
+    writeFileSync(join(binDir, "pragma"), "#!/bin/sh\n", { mode: 0o755 });
+    vi.stubEnv("PATH", binDir);
+
+    vi.mocked(detectHarnesses).mockReturnValue(
+      Promise.resolve([detected]) as never,
+    );
+    vi.mocked(readMcpConfig).mockReturnValue(
+      Promise.resolve({
+        pragma: { command: "pragma", args: ["mcp"] },
+      }) as never,
+    );
+
+    const result = await checkMcpCommands(ctx);
+    expect(result.status).toBe("pass");
+    expect(result.detail).toContain("1 command");
+  });
+
+  it("fails and names the entry whose command does not resolve", async () => {
+    const emptyDir = mkdtempSync(join(tmpdir(), "pragma-doctor-empty-"));
+    vi.stubEnv("PATH", emptyDir);
+
+    vi.mocked(detectHarnesses).mockReturnValue(
+      Promise.resolve([detected]) as never,
+    );
+    vi.mocked(readMcpConfig).mockReturnValue(
+      Promise.resolve({
+        sem: { command: "sem", args: ["mcp"] },
+      }) as never,
+    );
+
+    const result = await checkMcpCommands(ctx);
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain('"sem"');
+    expect(result.detail).toContain("/test/.mcp.json");
+    expect(result.remedy).toBeDefined();
+  });
+
+  it("flags only the broken entry among several", async () => {
+    const binDir = mkdtempSync(join(tmpdir(), "pragma-doctor-mixed-"));
+    writeFileSync(join(binDir, "pragma"), "#!/bin/sh\n", { mode: 0o755 });
+    vi.stubEnv("PATH", binDir);
+
+    vi.mocked(detectHarnesses).mockReturnValue(
+      Promise.resolve([detected]) as never,
+    );
+    vi.mocked(readMcpConfig).mockReturnValue(
+      Promise.resolve({
+        pragma: { command: "pragma", args: ["mcp"] },
+        sem: { command: "sem", args: ["mcp"] },
+        figma: { type: "http", url: "https://mcp.figma.com/mcp" },
+      }) as never,
+    );
+
+    const result = await checkMcpCommands(ctx);
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain('"sem"');
+    expect(result.detail).not.toContain('"pragma"');
+  });
+});
+
 describe("checkSkillsSymlinked", () => {
   it("skips when no harnesses detected", async () => {
     vi.mocked(detectHarnesses).mockReturnValue(Promise.resolve([]) as never);

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

@@ -8,12 +8,14 @@ vi.mock("./checks/index.js", () => ({
   checkKeStore: vi.fn(),
   checkShellCompletions: vi.fn(),
   checkMcpConfigured: vi.fn(),
+  checkMcpCommands: vi.fn(),
   checkSkillsSymlinked: vi.fn(),
 }));
 
 import {
   checkConfigFile,
   checkKeStore,
+  checkMcpCommands,
   checkMcpConfigured,
   checkNodeVersion,
   checkPackageRefs,
@@ -50,13 +52,14 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
 
     const data = await runChecks({ cwd: "/test" });
-    expect(data.passed).toBe(8);
+    expect(data.passed).toBe(9);
     expect(data.failed).toBe(0);
     expect(data.skipped).toBe(0);
-    expect(data.checks).toHaveLength(8);
+    expect(data.checks).toHaveLength(9);
   });
 
   it("counts failures and skips correctly", async () => {
@@ -67,10 +70,11 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockResolvedValue(fail("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(fail("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(skip("skills"));
 
     const data = await runChecks({ cwd: "/test" });
-    expect(data.passed).toBe(4);
+    expect(data.passed).toBe(5);
     expect(data.failed).toBe(3);
     expect(data.skipped).toBe(1);
   });
@@ -83,6 +87,7 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
 
     const data = await runChecks({ cwd: "/test" });
@@ -91,7 +96,7 @@ describe("runChecks", () => {
     expect(data.checks[2].name).toBe("config");
     expect(data.checks[3].name).toBe("refs");
     expect(data.checks[4].name).toBe("store");
-    expect(data.checks[7].name).toBe("skills");
+    expect(data.checks[8].name).toBe("skills");
   });
 
   it("preserves order even when checks resolve out of order", async () => {
@@ -109,6 +114,7 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockReturnValue(delayed(pass("skills"), 0));
 
     const data = await runChecks({ cwd: "/test" });
@@ -120,6 +126,7 @@ describe("runChecks", () => {
       "store",
       "completions",
       "mcp",
+      "mcp commands",
       "skills",
     ]);
   });
@@ -132,13 +139,14 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockResolvedValue(pass("store"));
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
 
     const data = await runChecks({ cwd: "/test" });
 
     // The whole run still completes; the thrown check becomes a fail in place.
-    expect(data.checks).toHaveLength(8);
-    expect(data.passed).toBe(7);
+    expect(data.checks).toHaveLength(9);
+    expect(data.passed).toBe(8);
     expect(data.failed).toBe(1);
     const failed = data.checks[2];
     expect(failed.status).toBe("fail");
@@ -157,6 +165,7 @@ describe("runChecks", () => {
     vi.mocked(checkKeStore).mockRejectedValue("string failure");
     vi.mocked(checkShellCompletions).mockResolvedValue(pass("completions"));
     vi.mocked(checkMcpConfigured).mockResolvedValue(pass("mcp"));
+    vi.mocked(checkMcpCommands).mockResolvedValue(pass("mcp commands"));
     vi.mocked(checkSkillsSymlinked).mockResolvedValue(pass("skills"));
 
     const data = await runChecks({ cwd: "/test" });

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

@@ -1,6 +1,7 @@
 import {
   checkConfigFile,
   checkKeStore,
+  checkMcpCommands,
   checkMcpConfigured,
   checkNodeVersion,
   checkPackageRefs,
@@ -28,6 +29,7 @@ function buildChecks(
     ["ke store", checkKeStore(ctx)],
     ["Shell completions", checkShellCompletions()],
     ["MCP configured", checkMcpConfigured(ctx)],
+    ["MCP commands", checkMcpCommands(ctx)],
     ["Skills symlinked", checkSkillsSymlinked(ctx)],
   ];
 }