@canonical/pragma-cli 0.27.1-experimental.0 → 0.30.0

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/checkKeStore.ts

@@ -14,10 +14,10 @@ export default async function checkKeStore(
   ctx: CheckContext,
 ): Promise<CheckResult> {
   const start = performance.now();
-  let store: Awaited<ReturnType<typeof bootStore>> | undefined;
+  let result: Awaited<ReturnType<typeof bootStore>> | undefined;
   try {
-    store = await bootStore({ cwd: ctx.cwd });
-    const summary = await collectStoreSummary(store);
+    result = await bootStore({ cwd: ctx.cwd });
+    const summary = await collectStoreSummary(result.store);
     const elapsed = Math.round(performance.now() - start);
     return {
       name: "ke store",
@@ -30,9 +30,9 @@ export default async function checkKeStore(
       status: "fail",
       detail: "failed to boot",
       remedy:
-        "Ensure design system packages are installed: bun add -D @canonical/ds-global @canonical/code-standards",
+        "Ensure design system packages are installed: bun add -D @canonical/design-system @canonical/anatomy-dsl @canonical/code-standards",
     };
   } finally {
-    store?.dispose();
+    result?.store.dispose();
   }
 }

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

@@ -1,68 +1,50 @@
 /**
  * Doctor check: report how each semantic package is resolved.
  *
- * Shows whether packages resolve from npm, file://, or git cache,
- * and warns if a configured ref is missing its cache.
+ * Uses the loader chain (local > git > bundled) to show where each
+ * package resolves from, its version, and graph/skill counts.
  */
 
-import { existsSync } from "node:fs";
 import { readConfig } from "#config";
 import {
-  parsePackageEntry,
-  type RawPackageEntry,
-} from "../../../refs/operations/parseRef.js";
-import { gitCacheDir } from "../../../refs/operations/paths.js";
-import readGlobalRefs from "../../../refs/operations/readGlobalRefs.js";
-import { DEFAULT_PACKAGES } from "../../../shared/packages.js";
+  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 globalEntries = readGlobalRefs();
-
-  const hasProjectRefs = config.packages && config.packages.length > 0;
-  const hasGlobalRefs = globalEntries.length > 0;
-
-  if (!hasProjectRefs && !hasGlobalRefs) {
-    return {
-      name: "package refs",
-      status: "pass",
-      detail: `${DEFAULT_PACKAGES.length} packages (all npm, defaults)`,
-    };
-  }
-
-  const entries: ReadonlyArray<RawPackageEntry> =
-    config.packages ?? globalEntries;
+  const refs = mergeAndParseRefs(config.packages);
+  const loaders = [
+    createLocalLoader(),
+    createGitLoader(),
+    createBundledLoader(),
+  ];
+  const packages = await resolveSemanticPackages(refs, loaders);
 
   const details: string[] = [];
   let hasIssue = false;
 
-  for (const entry of entries) {
-    const ref = parsePackageEntry(entry);
-
-    switch (ref.kind) {
-      case "npm":
-        details.push(`${ref.pkg}: npm`);
-        break;
-      case "file":
-        if (existsSync(ref.path)) {
-          details.push(`${ref.pkg}: file (${ref.path})`);
-        } else {
-          details.push(`${ref.pkg}: file MISSING (${ref.path})`);
-          hasIssue = true;
-        }
-        break;
-      case "git": {
-        const cached = existsSync(gitCacheDir(ref.pkg, ref.ref));
-        if (cached) {
-          details.push(`${ref.pkg}: git #${ref.ref} (cached)`);
-        } else {
-          details.push(`${ref.pkg}: git #${ref.ref} NOT CACHED`);
-          hasIssue = true;
-        }
-        break;
+  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;
       }
     }
   }

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();
@@ -75,7 +121,10 @@ describe("checkKeStore", () => {
       query: vi.fn(),
       dispose: vi.fn(),
     };
-    vi.mocked(bootStore).mockResolvedValue(mockStore as never);
+    vi.mocked(bootStore).mockResolvedValue({
+      store: mockStore,
+      packages: [],
+    } as never);
     vi.mocked(collectStoreSummary).mockResolvedValue({
       tripleCount: 12847,
       graphNames: [],
@@ -142,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);