@canonical/pragma-cli 0.18.0

package/src/mcp/types.ts

@@ -0,0 +1,62 @@
+/**
+ * MCP tool envelope types.
+ *
+ * Defines shapes for MCP response envelopes returned by `wrapTool`.
+ * Error-related types live in `./error/types.js`.
+ */
+
+export type {
+  McpErrorPayload,
+  McpRecovery,
+  ToolErrorResponse,
+} from "./error/types.js";
+
+// ---------------------------------------------------------------------------
+// Tool handler payload (returned by tool implementation functions)
+// ---------------------------------------------------------------------------
+
+/**
+ * Union type returned by tool handler functions to `wrapTool`.
+ * Either structured data with optional metadata, or condensed text output.
+ */
+export type ToolPayload =
+  | {
+      readonly data: unknown;
+      readonly meta?: {
+        readonly count?: number;
+        readonly filters?: Record<string, string>;
+      };
+    }
+  | {
+      readonly condensed: true;
+      readonly text: string;
+      readonly tokens: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Response envelopes (serialized into MCP content)
+// ---------------------------------------------------------------------------
+
+/**
+ * Success envelope — full structured data response.
+ * Agents branch on `ok: true` to access `data` and `meta`.
+ */
+export interface ToolResponse<T = unknown> {
+  readonly ok: true;
+  readonly data: T;
+  readonly meta: {
+    readonly count?: number;
+    readonly filters?: Record<string, string>;
+  };
+}
+
+/**
+ * Success envelope — condensed text response for token-budgeted agents.
+ * Agents branch on `condensed: true` to access markdown text.
+ */
+export interface ToolResponseCondensed {
+  readonly ok: true;
+  readonly condensed: true;
+  readonly text: string;
+  readonly tokens: string;
+}

package/src/mcp/utils/estimateTokens.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+import estimateTokens from "./estimateTokens.js";
+
+describe("estimateTokens", () => {
+  it("estimates ~1 token per 4 chars", () => {
+    expect(estimateTokens("abcd")).toBe("~1");
+    expect(estimateTokens("abcdefgh")).toBe("~2");
+    expect(estimateTokens("a")).toBe("~1");
+  });
+
+  it("rounds up", () => {
+    expect(estimateTokens("abcde")).toBe("~2");
+  });
+});

package/src/mcp/utils/estimateTokens.ts

@@ -0,0 +1,9 @@
+/**
+ * Estimate token count from text length using the ~4 chars/token heuristic.
+ *
+ * @param text - The text to estimate tokens for.
+ * @returns A human-readable string like `"~250"`.
+ */
+export default function estimateTokens(text: string): string {
+  return `~${Math.ceil(text.length / 4)}`;
+}

package/src/mcp/utils/index.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP utility functions.
+ *
+ * Re-exports the tool wrapper and token estimation utilities shared
+ * across all MCP tool registration modules.
+ *
+ * @module
+ */
+
+export { default as estimateTokens } from "./estimateTokens.js";
+export { default as wrapTool } from "./wrapTool.js";

package/src/mcp/utils/wrapTool.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import wrapTool from "./wrapTool.js";
+
+const stubRuntime = {
+  store: {} as PragmaRuntime["store"],
+  config: { tier: undefined, channel: "normal" },
+  cwd: "/test",
+  dispose: () => {},
+} as PragmaRuntime;
+
+function parseEnvelope(result: { content: unknown[] }): unknown {
+  const first = result.content[0] as { type: string; text: string };
+  return JSON.parse(first.text);
+}
+
+describe("wrapTool", () => {
+  it("wraps data payload in success envelope", async () => {
+    const handler = wrapTool(stubRuntime, async () => ({
+      data: [{ name: "Button" }],
+      meta: { count: 1, filters: { tier: "global" } },
+    }));
+
+    const result = await handler({});
+    const envelope = parseEnvelope(result) as Record<string, unknown>;
+
+    expect(envelope.ok).toBe(true);
+    expect(envelope.data).toEqual([{ name: "Button" }]);
+    expect(envelope.meta).toEqual({ count: 1, filters: { tier: "global" } });
+  });
+
+  it("defaults meta to empty object when omitted", async () => {
+    const handler = wrapTool(stubRuntime, async () => ({
+      data: { name: "Button" },
+    }));
+
+    const result = await handler({});
+    const envelope = parseEnvelope(result) as Record<string, unknown>;
+
+    expect(envelope.ok).toBe(true);
+    expect(envelope.meta).toEqual({});
+  });
+
+  it("wraps condensed payload in condensed envelope", async () => {
+    const handler = wrapTool(stubRuntime, async () => ({
+      condensed: true as const,
+      text: "## Components\n- Button",
+      tokens: "~50",
+    }));
+
+    const result = await handler({});
+    const envelope = parseEnvelope(result) as Record<string, unknown>;
+
+    expect(envelope.ok).toBe(true);
+    expect(envelope.condensed).toBe(true);
+    expect(envelope.text).toBe("## Components\n- Button");
+    expect(envelope.tokens).toBe("~50");
+    expect(envelope).not.toHaveProperty("data");
+  });
+
+  it("serializes PragmaError into error envelope", async () => {
+    const handler = wrapTool(stubRuntime, async () => {
+      throw PragmaError.notFound("component", "Buton", {
+        suggestions: ["Button"],
+        recovery: {
+          message: "List available components.",
+          cli: "pragma block list",
+          mcp: { tool: "block_list" },
+        },
+      });
+    });
+
+    const result = await handler({});
+    expect(result.isError).toBe(true);
+
+    const envelope = parseEnvelope(result) as {
+      ok: boolean;
+      error: Record<string, unknown>;
+    };
+    expect(envelope.ok).toBe(false);
+    expect(envelope.error.code).toBe("ENTITY_NOT_FOUND");
+    expect(envelope.error.message).toContain("Buton");
+    expect(envelope.error.suggestions).toEqual(["Button"]);
+  });
+
+  it("rethrows unknown errors", async () => {
+    const handler = wrapTool(stubRuntime, async () => {
+      throw new TypeError("unexpected");
+    });
+
+    await expect(handler({})).rejects.toThrow("unexpected");
+  });
+
+  it("passes runtime and params to handler", async () => {
+    const handler = wrapTool(stubRuntime, async (rt, params) => ({
+      data: { cwd: rt.cwd, name: params.name },
+    }));
+
+    const result = await handler({ name: "Button" });
+    const envelope = parseEnvelope(result) as {
+      data: Record<string, unknown>;
+    };
+
+    expect(envelope.data.cwd).toBe("/test");
+    expect(envelope.data.name).toBe("Button");
+  });
+});

package/src/mcp/utils/wrapTool.ts

@@ -0,0 +1,81 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { PragmaError } from "#error";
+import type { PragmaRuntime } from "../../domains/shared/runtime.js";
+import serializeErrorPayload from "../error/serializeErrorPayload.js";
+import type { ToolPayload } from "../types.js";
+
+/**
+ * Wrap a tool handler function with envelope construction and error handling.
+ *
+ * Every MCP tool is wrapped by this function — no tool constructs its own
+ * envelope. This ensures consistent `{ ok, data, meta }` success responses,
+ * `{ ok, condensed, text, tokens }` condensed responses, and
+ * `{ ok: false, error }` error responses across all tools.
+ *
+ * The returned handler catches `PragmaError` instances and serializes them
+ * as `{ ok: false, error }` responses. Unknown errors propagate to the MCP
+ * SDK's transport-level error handling (JSON-RPC -32603).
+ *
+ * @param runtime - The pragma runtime providing store, config, and cwd.
+ * @param fn - The tool implementation. Receives runtime and parsed params,
+ *   returns a `ToolPayload` (either `{ data, meta }` or `{ condensed, text, tokens }`).
+ * @returns An MCP tool handler function.
+ */
+export default function wrapTool(
+  runtime: PragmaRuntime,
+  fn: (
+    rt: PragmaRuntime,
+    params: Record<string, unknown>,
+  ) => Promise<ToolPayload>,
+): (params: Record<string, unknown>) => Promise<CallToolResult> {
+  return async (params) => {
+    try {
+      const result = await fn(runtime, params);
+
+      if ("condensed" in result) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                ok: true,
+                condensed: true,
+                text: result.text,
+                tokens: result.tokens,
+              }),
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              data: result.data,
+              meta: result.meta ?? {},
+            }),
+          },
+        ],
+      };
+    } catch (error) {
+      if (error instanceof PragmaError) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                ok: false,
+                error: serializeErrorPayload(error),
+              }),
+            },
+          ],
+          isError: true,
+        };
+      }
+      throw error;
+    }
+  };
+}

package/src/package-manager/constants.ts

@@ -0,0 +1,29 @@
+import type { PackageManager } from "./types.js";
+
+/** Per-package-manager CLI command templates for global install and update. */
+const PM_COMMANDS: Record<
+  PackageManager,
+  {
+    install: (pkg: string) => string;
+    update: (pkg: string) => string;
+  }
+> = {
+  bun: {
+    install: (pkg) => `bun add -g ${pkg}`,
+    update: (pkg) => `bun update -g ${pkg}`,
+  },
+  npm: {
+    install: (pkg) => `npm install -g ${pkg}`,
+    update: (pkg) => `npm update -g ${pkg}`,
+  },
+  pnpm: {
+    install: (pkg) => `pnpm add -g ${pkg}`,
+    update: (pkg) => `pnpm update -g ${pkg}`,
+  },
+  yarn: {
+    install: (pkg) => `yarn global add ${pkg}`,
+    update: (pkg) => `yarn global upgrade ${pkg}`,
+  },
+};
+
+export { PM_COMMANDS };

package/src/package-manager/detectInstallSource.test.ts

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import detectInstallSource from "./detectInstallSource.js";
+
+describe("detectInstallSource", () => {
+  it("returns local install for a checked-out source entrypoint", () => {
+    const result = detectInstallSource(
+      resolve(import.meta.dirname, "../bin.ts"),
+    );
+
+    expect(result.scope).toBe("local");
+    expect(result.label).toBe("bun (local)");
+  });
+
+  it("returns global install for a global bun path", () => {
+    const result = detectInstallSource(
+      "/home/user/.bun/install/global/node_modules/.bin/pragma",
+    );
+
+    expect(result.scope).toBe("global");
+    expect(result.label).toBe("bun (global)");
+  });
+});

package/src/package-manager/detectInstallSource.ts

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import detectPackageManager from "./detectPackageManager.js";
+import type { InstallSource } from "./types.js";
+
+function isGlobalPrefix(path: string): boolean {
+  return (
+    path.includes("/.bun/") ||
+    path.includes("/pnpm/") ||
+    path.includes("/yarn/") ||
+    path.includes("/.yarn/")
+  );
+}
+
+function resolvePath(binPath: string): string {
+  try {
+    return realpathSync(binPath);
+  } catch {
+    return binPath;
+  }
+}
+
+function findPackageName(startPath: string): string | undefined {
+  let current = dirname(startPath);
+
+  while (true) {
+    const packageJsonPath = join(current, "package.json");
+    if (existsSync(packageJsonPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+          name?: string;
+        };
+        return parsed.name;
+      } catch {
+        return undefined;
+      }
+    }
+
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function isLocalCheckout(path: string): boolean {
+  if (path.includes("/node_modules/")) return false;
+  if (!path.endsWith("/src/bin.ts") && !path.endsWith("/dist/pragma")) {
+    return false;
+  }
+
+  return findPackageName(path) === "@canonical/pragma-cli";
+}
+
+function detectRuntimePackageManager(): InstallSource["packageManager"] {
+  const execPath = process.execPath;
+  const npmExecPath = process.env.npm_execpath;
+  const userAgent = process.env.npm_config_user_agent ?? "";
+
+  if (execPath) {
+    const fromExec = detectPackageManager(execPath);
+    if (fromExec !== "npm") return fromExec;
+  }
+
+  if (npmExecPath) {
+    const fromNpmExec = detectPackageManager(npmExecPath);
+    if (fromNpmExec !== "npm") return fromNpmExec;
+  }
+
+  if (userAgent.startsWith("bun/")) return "bun";
+  if (userAgent.startsWith("pnpm/")) return "pnpm";
+  if (userAgent.startsWith("yarn/")) return "yarn";
+
+  return "npm";
+}
+
+/**
+ * Detect whether pragma is running from a global install, local
+ * `node_modules`, or a local source checkout, and which package
+ * manager owns the installation.
+ *
+ * @param binPath - The `process.argv[1]` binary path (defaults to current).
+ * @returns Install source with package manager, scope, and display label.
+ *
+ * @note Impure
+ */
+export default function detectInstallSource(
+  binPath: string = process.argv[1] ?? "",
+): InstallSource {
+  const resolved = resolvePath(binPath);
+  const localCheckout = isLocalCheckout(resolved);
+  const packageManager = localCheckout
+    ? detectRuntimePackageManager()
+    : detectPackageManager(binPath);
+
+  if (
+    (resolved.includes("node_modules/.bin") && !isGlobalPrefix(resolved)) ||
+    localCheckout
+  ) {
+    return {
+      packageManager,
+      scope: "local",
+      label: `${packageManager} (local)`,
+    };
+  }
+
+  return {
+    packageManager,
+    scope: "global",
+    label: `${packageManager} (global)`,
+  };
+}

package/src/package-manager/detectLocalInstall.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import detectLocalInstall from "./detectLocalInstall.js";
+
+describe("detectLocalInstall", () => {
+  it("returns undefined for global installs", () => {
+    expect(
+      detectLocalInstall(
+        "/home/user/.bun/install/global/node_modules/.bin/pragma",
+      ),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when path cannot be resolved", () => {
+    expect(detectLocalInstall("/nonexistent/path/pragma")).toBeUndefined();
+  });
+});

package/src/package-manager/detectLocalInstall.ts

@@ -0,0 +1,43 @@
+import { realpathSync } from "node:fs";
+import { PM_COMMANDS } from "./constants.js";
+import detectPackageManager from "./detectPackageManager.js";
+
+/**
+ * Check whether a resolved binary path falls within a known global prefix directory.
+ *
+ * @param path - Resolved filesystem path.
+ * @returns `true` if the path is under a global package manager directory.
+ */
+function isGlobalPrefix(path: string): boolean {
+  return (
+    path.includes("/.bun/") ||
+    path.includes("/pnpm/") ||
+    path.includes("/yarn/") ||
+    path.includes("/.yarn/")
+  );
+}
+
+/**
+ * Warn if pragma is installed locally (in node_modules/.bin) instead of globally.
+ *
+ * @param binPath - Path to the pragma binary (defaults to `process.argv[1]`).
+ * @returns Warning string if locally installed, or `undefined` if global.
+ *
+ * @note Impure — resolves real filesystem path.
+ */
+export default function detectLocalInstall(
+  binPath: string = process.argv[1] ?? "",
+): string | undefined {
+  let resolved: string;
+  try {
+    resolved = realpathSync(binPath);
+  } catch {
+    resolved = binPath;
+  }
+
+  if (!resolved.includes("node_modules/.bin")) return undefined;
+  if (isGlobalPrefix(resolved)) return undefined;
+
+  const pm = detectPackageManager(binPath);
+  return `Warning: pragma is installed locally in this project.\nGlobal installation is recommended: ${PM_COMMANDS[pm].install("@canonical/pragma-cli")}`;
+}

package/src/package-manager/detectPackageManager.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { PM_COMMANDS } from "./constants.js";
+import detectPackageManager from "./detectPackageManager.js";
+
+describe("detectPackageManager", () => {
+  it("detects bun from bin path", () => {
+    expect(
+      detectPackageManager(
+        "/home/user/.bun/install/global/node_modules/.bin/pragma",
+      ),
+    ).toBe("bun");
+  });
+
+  it("detects pnpm from bin path", () => {
+    expect(
+      detectPackageManager(
+        "/home/user/.local/share/pnpm/global/5/node_modules/.bin/pragma",
+      ),
+    ).toBe("pnpm");
+  });
+
+  it("detects yarn from bin path", () => {
+    expect(detectPackageManager("/home/user/.yarn/bin/pragma")).toBe("yarn");
+  });
+
+  it("detects yarn from global node_modules path", () => {
+    expect(
+      detectPackageManager(
+        "/home/user/.config/yarn/global/node_modules/.bin/pragma",
+      ),
+    ).toBe("yarn");
+  });
+
+  it("defaults to npm for nvm paths", () => {
+    expect(
+      detectPackageManager(
+        "/home/user/.config/nvm/versions/node/v24/bin/pragma",
+      ),
+    ).toBe("npm");
+  });
+
+  it("defaults to npm for unknown paths", () => {
+    expect(detectPackageManager("/usr/local/bin/pragma")).toBe("npm");
+  });
+
+  it("defaults to npm when path cannot be resolved", () => {
+    expect(detectPackageManager("/nonexistent/path/to/pragma")).toBe("npm");
+  });
+});
+
+describe("PM_COMMANDS", () => {
+  it("generates correct bun install command", () => {
+    expect(PM_COMMANDS.bun.install("@canonical/pragma-cli")).toBe(
+      "bun add -g @canonical/pragma-cli",
+    );
+  });
+
+  it("generates correct npm update command", () => {
+    expect(PM_COMMANDS.npm.update("@canonical/pragma-cli")).toBe(
+      "npm update -g @canonical/pragma-cli",
+    );
+  });
+
+  it("generates correct pnpm install command", () => {
+    expect(PM_COMMANDS.pnpm.install("@canonical/pragma-cli")).toBe(
+      "pnpm add -g @canonical/pragma-cli",
+    );
+  });
+
+  it("generates correct yarn install command", () => {
+    expect(PM_COMMANDS.yarn.install("@canonical/pragma-cli")).toBe(
+      "yarn global add @canonical/pragma-cli",
+    );
+  });
+
+  it("generates correct yarn update command", () => {
+    expect(PM_COMMANDS.yarn.update("@canonical/pragma-cli")).toBe(
+      "yarn global upgrade @canonical/pragma-cli",
+    );
+  });
+});

package/src/package-manager/detectPackageManager.ts

@@ -0,0 +1,30 @@
+import { realpathSync } from "node:fs";
+import type { PackageManager } from "./types.js";
+
+/**
+ * Detect which package manager installed pragma from the binary path.
+ *
+ * Inspects the resolved symlink target for known directory patterns
+ * (`.bun/`, `/pnpm/`, `/yarn/`). Falls back to `"npm"`.
+ *
+ * @param binPath - Path to the pragma binary (defaults to `process.argv[1]`).
+ * @returns Detected package manager identifier.
+ *
+ * @note Impure — resolves real filesystem path.
+ */
+export default function detectPackageManager(
+  binPath: string = process.argv[1] ?? "",
+): PackageManager {
+  let resolved: string;
+  try {
+    resolved = realpathSync(binPath);
+  } catch {
+    resolved = binPath;
+  }
+
+  if (resolved.includes("/.bun/")) return "bun";
+  if (resolved.includes("/pnpm/")) return "pnpm";
+  if (resolved.includes("/yarn/") || resolved.includes("/.yarn/"))
+    return "yarn";
+  return "npm";
+}

package/src/package-manager/index.ts

@@ -0,0 +1,6 @@
+/** @module Package manager detection and command templates. */
+export { PM_COMMANDS } from "./constants.js";
+export { default as detectInstallSource } from "./detectInstallSource.js";
+export { default as detectLocalInstall } from "./detectLocalInstall.js";
+export { default as detectPackageManager } from "./detectPackageManager.js";
+export type { InstallSource, PackageManager } from "./types.js";

package/src/package-manager/types.ts

@@ -0,0 +1,12 @@
+/** Supported Node.js package managers. */
+type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+
+interface InstallSource {
+  readonly packageManager: PackageManager;
+  readonly scope: "global" | "local";
+  readonly label: string;
+}
+
+export type { PackageManager };
+
+export type { InstallSource };

package/src/pipeline/collectCommands.test.ts

@@ -0,0 +1,37 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { PragmaContext } from "../domains/shared/context.js";
+import type { PragmaRuntime } from "../domains/shared/runtime.js";
+import createTestRuntime from "../testing/helpers/createTestRuntime.js";
+import collectCommands from "./collectCommands.js";
+
+let runtime: PragmaRuntime;
+
+beforeAll(async () => {
+  runtime = await createTestRuntime();
+});
+
+afterAll(() => {
+  runtime.dispose();
+});
+
+function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
+  return {
+    ...runtime,
+    globalFlags: { llm: false, format: "text" as const, verbose: false },
+    ...overrides,
+  };
+}
+
+describe("collectCommands", () => {
+  it("includes block, ontology, and graph command paths", () => {
+    const commands = collectCommands(makeCtx());
+    const paths = commands.map((command) => command.path.join(" "));
+
+    expect(paths).toContain("block list");
+    expect(paths).toContain("block lookup");
+    expect(paths).toContain("ontology list");
+    expect(paths).toContain("ontology show");
+    expect(paths).toContain("graph query");
+    expect(paths).toContain("graph inspect");
+  });
+});