@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/mcp/types.ts

@@ -1,66 +0,0 @@
-/**
- * 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>;
-        /** Queries that failed unexpectedly (surfaced only when > 0). */
-        readonly internalErrorCount?: number;
-      };
-    }
-  | {
-      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>;
-    /** Queries that failed unexpectedly (surfaced only when > 0). */
-    readonly internalErrorCount?: number;
-  };
-}
-
-/**
- * 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

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

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

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

@@ -1,109 +0,0 @@
-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",
-  packages: [],
-  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

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

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

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

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

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

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

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

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

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

@@ -1,10 +0,0 @@
-/** 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 { InstallSource, PackageManager };