@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/error/PragmaError.ts

@@ -1,177 +0,0 @@
-import type {
-  CrossDomainRecovery,
-  ErrorCode,
-  PragmaErrorData,
-  Recovery,
-} from "./types.js";
-
-/**
- * Structured error for all pragma domain operations.
- *
- * Carries a machine-readable {@link ErrorCode}, optional recovery hints,
- * and contextual metadata (suggestions, valid options, active filters)
- * so that CLI and MCP adapters can render actionable diagnostics.
- */
-class PragmaError extends Error {
-  /** Machine-readable error classification. */
-  readonly code: ErrorCode;
-  /** Entity that triggered the error (type + name), if applicable. */
-  readonly entity: PragmaErrorData["entity"];
-  /** Fuzzy-matched alternative names the user may have intended. */
-  readonly suggestions: string[];
-  /** Structured recovery hint with optional CLI command or MCP tool call. */
-  readonly recovery: Recovery | undefined;
-  /** Cross-domain redirect when name exists in another domain. */
-  readonly crossDomain: CrossDomainRecovery | undefined;
-  /** Active filters at the time of the error, for diagnostic context. */
-  readonly filters: Record<string, string> | undefined;
-  /** Enumerated valid options when input was rejected. */
-  readonly validOptions: string[] | undefined;
-
-  /**
-   * @param data - Structured error payload.
-   */
-  constructor(data: PragmaErrorData) {
-    super(data.message);
-    this.name = "PragmaError";
-    this.code = data.code;
-    this.entity = data.entity;
-    this.suggestions = data.suggestions ?? [];
-    this.recovery = data.recovery;
-    this.crossDomain = data.crossDomain;
-    this.filters = data.filters;
-    this.validOptions = data.validOptions;
-  }
-
-  /**
-   * Factory: entity not found by name.
-   *
-   * @param entityType - Kind of entity (e.g., `"block"`, `"token"`).
-   * @param entityName - Name the user supplied.
-   * @param opts - Optional suggestions and recovery hint.
-   * @returns PragmaError with code `ENTITY_NOT_FOUND`.
-   */
-  static notFound(
-    entityType: string,
-    entityName: string,
-    opts: {
-      suggestions?: string[];
-      recovery?: Recovery;
-      crossDomain?: CrossDomainRecovery;
-    } = {},
-  ): PragmaError {
-    return new PragmaError({
-      code: "ENTITY_NOT_FOUND",
-      message: `${entityType} "${entityName}" not found.`,
-      entity: { type: entityType, name: entityName },
-      suggestions: opts.suggestions,
-      recovery: opts.recovery,
-      crossDomain: opts.crossDomain,
-    });
-  }
-
-  /**
-   * Factory: query returned zero results.
-   *
-   * @param entityType - Kind of entity being listed.
-   * @param opts - Optional active filters and recovery hint.
-   * @returns PragmaError with code `EMPTY_RESULTS`.
-   */
-  static emptyResults(
-    entityType: string,
-    opts: {
-      message?: string;
-      filters?: Record<string, string>;
-      recovery?: Recovery;
-      validOptions?: string[];
-    } = {},
-  ): PragmaError {
-    return new PragmaError({
-      code: "EMPTY_RESULTS",
-      message: opts.message ?? `No ${entityType}s found.`,
-      filters: opts.filters,
-      recovery: opts.recovery,
-      validOptions: opts.validOptions,
-    });
-  }
-
-  /**
-   * Factory: user-supplied input is invalid.
-   *
-   * @param field - Name of the invalid field or argument.
-   * @param value - The rejected value.
-   * @param opts - Optional valid alternatives and recovery hint.
-   * @returns PragmaError with code `INVALID_INPUT`.
-   */
-  static invalidInput(
-    field: string,
-    value: string,
-    opts: {
-      validOptions?: string[];
-      recovery?: Recovery;
-    } = {},
-  ): PragmaError {
-    return new PragmaError({
-      code: "INVALID_INPUT",
-      message: `Invalid ${field} "${value}".`,
-      validOptions: opts.validOptions,
-      recovery: opts.recovery,
-    });
-  }
-
-  /**
-   * Factory: ke store failed to initialize or query.
-   *
-   * @param reason - Human-readable failure description.
-   * @param opts - Optional recovery hint.
-   * @returns PragmaError with code `STORE_ERROR`.
-   */
-  static storeError(
-    reason: string,
-    opts: { recovery?: Recovery } = {},
-  ): PragmaError {
-    return new PragmaError({
-      code: "STORE_ERROR",
-      message: `Failed to initialize store. ${reason}`,
-      recovery: opts.recovery,
-    });
-  }
-
-  /**
-   * Factory: configuration file is invalid or contains bad values.
-   *
-   * @param reason - Human-readable description of the config problem.
-   * @param opts - Optional valid alternatives and recovery hint.
-   * @returns PragmaError with code `CONFIG_ERROR`.
-   */
-  static configError(
-    reason: string,
-    opts: {
-      validOptions?: string[];
-      recovery?: Recovery;
-    } = {},
-  ): PragmaError {
-    return new PragmaError({
-      code: "CONFIG_ERROR",
-      message: reason,
-      validOptions: opts.validOptions,
-      recovery: opts.recovery,
-    });
-  }
-
-  /**
-   * Factory: unexpected internal failure (bug).
-   *
-   * @param reason - Description of the internal error.
-   * @returns PragmaError with code `INTERNAL_ERROR` and a "please report" recovery.
-   */
-  static internalError(reason: string): PragmaError {
-    return new PragmaError({
-      code: "INTERNAL_ERROR",
-      message: `Internal error: ${reason}`,
-      recovery: { message: "Please report this issue." },
-    });
-  }
-}
-
-export { PragmaError };

package/src/error/constants.ts

@@ -1,12 +0,0 @@
-/** All recognized pragma error codes as a const tuple. */
-const ERROR_CODES = [
-  "ENTITY_NOT_FOUND",
-  "EMPTY_RESULTS",
-  "INVALID_INPUT",
-  "AMBIGUOUS_INPUT",
-  "STORE_ERROR",
-  "CONFIG_ERROR",
-  "INTERNAL_ERROR",
-] as const;
-
-export { ERROR_CODES };

package/src/error/index.ts

@@ -1,4 +0,0 @@
-/** @module Structured error types, codes, and the PragmaError class. */
-export { ERROR_CODES } from "./constants.js";
-export { PragmaError } from "./PragmaError.js";
-export type { ErrorCode, PragmaErrorData, Recovery } from "./types.js";

package/src/error/types.ts

@@ -1,55 +0,0 @@
-/**
- * Error type definitions for the pragma error system.
- *
- * Separates the data shapes from the PragmaError class to allow
- * lightweight imports by consumers that only need type information.
- */
-
-import type { ERROR_CODES } from "./constants.js";
-
-/** Union of all recognized error code literals. */
-type ErrorCode = (typeof ERROR_CODES)[number];
-
-/** Structured recovery hint attached to a PragmaError. */
-interface Recovery {
-  /** Human-readable recovery guidance. */
-  message: string;
-  /** CLI command the user can run to recover. */
-  cli?: string;
-  /** MCP tool invocation an LLM agent can call to recover. */
-  mcp?: { tool: string; params?: Record<string, unknown> };
-}
-
-/** Hint pointing the user/agent to a different domain when a name exists there. */
-interface CrossDomainRecovery {
-  /** Domain where the name was found (e.g., "modifier"). */
-  domain: string;
-  /** Entity type label for messages. */
-  entityType: string;
-  /** CLI command to run. */
-  cli: string;
-  /** MCP tool invocation. */
-  mcp: { tool: string; params: Record<string, unknown> };
-}
-
-/** Raw data payload used to construct a PragmaError. */
-interface PragmaErrorData {
-  /** Machine-readable error classification. */
-  code: ErrorCode;
-  /** Human-readable error message. */
-  message: string;
-  /** Entity that triggered the error, if applicable. */
-  entity?: { type: string; name: string };
-  /** Fuzzy-matched alternative names. */
-  suggestions?: string[];
-  /** Recovery hint for CLI and MCP adapters. */
-  recovery?: Recovery;
-  /** Cross-domain redirect when name exists in another domain. */
-  crossDomain?: CrossDomainRecovery;
-  /** Active filters at the time of the error. */
-  filters?: Record<string, string>;
-  /** Enumerated valid options when input was rejected. */
-  validOptions?: string[];
-}
-
-export type { CrossDomainRecovery, ErrorCode, PragmaErrorData, Recovery };

package/src/mcp/createMcpServer.test.ts

@@ -1,41 +0,0 @@
-import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestMcpClient } from "#testing";
-
-let client: Client;
-let cleanup: () => Promise<void>;
-
-beforeAll(async () => {
-  const result = await createTestMcpClient();
-  client = result.client;
-  cleanup = result.cleanup;
-});
-
-afterAll(async () => {
-  await cleanup();
-});
-
-describe("createMcpServer", () => {
-  it("creates a server with registered tools", async () => {
-    const { tools } = await client.listTools();
-    expect(tools.length).toBeGreaterThan(0);
-  });
-
-  it("all tools have input schemas", async () => {
-    const { tools } = await client.listTools();
-    for (const tool of tools) {
-      expect(tool.inputSchema).toBeDefined();
-      expect(tool.inputSchema.type).toBe("object");
-    }
-  });
-
-  it("creates a server with registered resources", async () => {
-    const { resources } = await client.listResources();
-    expect(resources.length).toBeGreaterThan(0);
-  });
-
-  it("creates a server with registered resource templates", async () => {
-    const { resourceTemplates } = await client.listResourceTemplates();
-    expect(resourceTemplates.length).toBeGreaterThan(0);
-  });
-});

package/src/mcp/createMcpServer.ts

@@ -1,53 +0,0 @@
-/**
- * MCP server factory.
- *
- * Groups two construction paths for the MCP server: full boot (reads
- * config and ke store) and runtime-injection (for tests that own the
- * runtime lifecycle). Both paths register the same set of tools and
- * resources.
- */
-
-import type { SourceSpec } from "@canonical/ke";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { VERSION } from "../constants.js";
-import type { PragmaRuntime } from "../domains/shared/runtime.js";
-import { bootPragma } from "../domains/shared/runtime.js";
-import registerResources from "./registerResources.js";
-import registerAllTools from "./tools/index.js";
-
-/**
- * Create a fully configured MCP server with its own runtime.
- *
- * The caller owns the returned `dispose` function and must call it when
- * the transport disconnects or the process exits.
- *
- * @param options - Optional overrides for working directory and TTL sources.
- * @returns The MCP server and a dispose callback to release the runtime.
- *
- * @note Impure
- */
-export async function createMcpServer(options?: {
-  cwd?: string;
-  sources?: SourceSpec[];
-}): Promise<{ server: McpServer; dispose: () => void }> {
-  const runtime = await bootPragma(options);
-  const { server } = createMcpServerFromRuntime(runtime);
-  return { server, dispose: () => runtime.dispose() };
-}
-
-/**
- * Create an MCP server from an existing runtime (no boot).
- *
- * Used in testing where the test controls the runtime lifecycle.
- *
- * @param runtime - An already-booted pragma runtime.
- * @returns The MCP server instance.
- */
-export function createMcpServerFromRuntime(runtime: PragmaRuntime): {
-  server: McpServer;
-} {
-  const server = new McpServer({ name: "pragma", version: VERSION });
-  registerAllTools(server, runtime);
-  registerResources(server, runtime);
-  return { server };
-}

package/src/mcp/error/buildRecovery.test.ts

@@ -1,37 +0,0 @@
-import { describe, expect, it } from "vitest";
-import buildRecovery from "./buildRecovery.js";
-
-describe("buildRecovery", () => {
-  it("returns undefined for undefined input", () => {
-    expect(buildRecovery(undefined)).toBeUndefined();
-  });
-
-  it("returns undefined when recovery has no mcp field", () => {
-    expect(
-      buildRecovery({
-        message: "Please report this issue.",
-      }),
-    ).toBeUndefined();
-  });
-
-  it("extracts mcp recovery object", () => {
-    const result = buildRecovery({
-      message: "List available tokens.",
-      cli: "pragma token list",
-      mcp: { tool: "token_list" },
-    });
-    expect(result).toEqual({ tool: "token_list" });
-  });
-
-  it("extracts mcp recovery with params", () => {
-    const result = buildRecovery({
-      message: "Widen the search.",
-      cli: "pragma block list --all-tiers",
-      mcp: { tool: "block_list", params: { allTiers: true } },
-    });
-    expect(result).toEqual({
-      tool: "block_list",
-      params: { allTiers: true },
-    });
-  });
-});

package/src/mcp/error/buildRecovery.ts

@@ -1,17 +0,0 @@
-import type { Recovery } from "#error";
-import type { McpRecovery } from "./types.js";
-
-/**
- * Build an {@link McpRecovery} object from the structured Recovery type.
- *
- * Extracts `recovery.mcp` directly — no regex parsing needed.
- *
- * @param recovery - The structured recovery attached to a PragmaError, if any.
- * @returns The MCP recovery hint, or `undefined` when no MCP path exists.
- */
-export default function buildRecovery(
-  recovery: Recovery | undefined,
-): McpRecovery | undefined {
-  if (!recovery?.mcp) return undefined;
-  return recovery.mcp;
-}

package/src/mcp/error/index.ts

@@ -1,12 +0,0 @@
-/**
- * MCP error serialization pipeline.
- *
- * Re-exports functions that transform PragmaError instances into
- * MCP-compatible error payloads and tool responses.
- *
- * @module
- */
-
-export { default as buildRecovery } from "./buildRecovery.js";
-export { default as serializeError } from "./serializeError.js";
-export { default as serializeErrorPayload } from "./serializeErrorPayload.js";

package/src/mcp/error/serializeError.test.ts

@@ -1,121 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import serializeError from "./serializeError.js";
-import type { McpErrorPayload } from "./types.js";
-
-function parsePayload(result: { content: unknown[] }): McpErrorPayload {
-  const first = result.content[0] as { text: string };
-  return JSON.parse(first.text);
-}
-
-describe("serializeError", () => {
-  it("serializes ENTITY_NOT_FOUND with structured recovery", () => {
-    const error = PragmaError.notFound("component", "Buton", {
-      suggestions: ["Button", "ButtonGroup"],
-      recovery: {
-        message: "List available components.",
-        cli: "pragma block list",
-        mcp: { tool: "block_list" },
-      },
-    });
-
-    const result = serializeError(error);
-    expect(result.isError).toBe(true);
-    expect(result.content).toHaveLength(1);
-    expect(result.content[0]?.type).toBe("text");
-
-    const payload = parsePayload(result);
-    expect(payload.code).toBe("ENTITY_NOT_FOUND");
-    expect(payload.message).toContain("Buton");
-    expect(payload.suggestions).toEqual(["Button", "ButtonGroup"]);
-    expect(payload.recovery).toEqual({ tool: "block_list" });
-  });
-
-  it("extracts mcp recovery with params", () => {
-    const error = PragmaError.emptyResults("component", {
-      recovery: {
-        message: "Widen the search to show all tiers.",
-        cli: "pragma block list --all-tiers",
-        mcp: { tool: "block_list", params: { allTiers: true } },
-      },
-    });
-
-    const payload = parsePayload(serializeError(error));
-    expect(payload.recovery?.tool).toBe("block_list");
-    expect(payload.recovery?.params).toEqual({ allTiers: true });
-  });
-
-  it("serializes EMPTY_RESULTS with filters", () => {
-    const error = PragmaError.emptyResults("component", {
-      filters: { tier: "apps/lxd", channel: "normal" },
-      recovery: {
-        message: "Widen the search to show all tiers.",
-        cli: "pragma block list --all-tiers",
-        mcp: { tool: "block_list", params: { allTiers: true } },
-      },
-    });
-
-    const payload = parsePayload(serializeError(error));
-    expect(payload.code).toBe("EMPTY_RESULTS");
-    expect(payload.filters).toEqual({ tier: "apps/lxd", channel: "normal" });
-    expect(payload.recovery?.tool).toBe("block_list");
-  });
-
-  it("omits recovery when no mcp field", () => {
-    const error = PragmaError.internalError("unexpected failure");
-
-    const payload = parsePayload(serializeError(error));
-    expect(payload.code).toBe("INTERNAL_ERROR");
-    expect(payload.recovery).toBeUndefined();
-  });
-
-  it("extracts mcp recovery from modifier error", () => {
-    const error = PragmaError.notFound("modifier", "x", {
-      recovery: {
-        message: "List available modifiers.",
-        cli: "pragma modifier list",
-        mcp: { tool: "modifier_list" },
-      },
-    });
-
-    const payload = parsePayload(serializeError(error));
-    expect(payload.recovery).toEqual({ tool: "modifier_list" });
-  });
-
-  it("omits recovery when undefined", () => {
-    const error = PragmaError.storeError("boot failed");
-    const payload = parsePayload(serializeError(error));
-    expect(payload.recovery).toBeUndefined();
-  });
-
-  it("serializes INVALID_INPUT with validOptions", () => {
-    const error = PragmaError.invalidInput("channel", "aggressive", {
-      validOptions: ["normal", "experimental", "prerelease"],
-    });
-
-    const payload = parsePayload(serializeError(error));
-    expect(payload.code).toBe("INVALID_INPUT");
-    expect(payload.validOptions).toEqual([
-      "normal",
-      "experimental",
-      "prerelease",
-    ]);
-  });
-
-  it("always sets isError to true", () => {
-    const error = PragmaError.storeError("boot failed");
-    expect(serializeError(error).isError).toBe(true);
-  });
-
-  it("always returns text content type", () => {
-    const error = PragmaError.configError("bad config");
-    const result = serializeError(error);
-    expect(result.content[0]?.type).toBe("text");
-  });
-
-  it("omits suggestions when empty", () => {
-    const error = PragmaError.storeError("boot failed");
-    const payload = parsePayload(serializeError(error));
-    expect(payload.suggestions).toBeUndefined();
-  });
-});

package/src/mcp/error/serializeError.ts

@@ -1,31 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { PragmaError } from "#error";
-import buildRecovery from "./buildRecovery.js";
-import type { McpErrorPayload } from "./types.js";
-
-/**
- * Serialize a PragmaError into an MCP tool error response.
- *
- * Returns `{ content, isError: true }` — the shape expected by
- * MCP tool handlers when reporting tool-level errors.
- *
- * @param error - The PragmaError to serialize.
- * @returns An MCP `CallToolResult` with JSON error content and `isError: true`.
- */
-export default function serializeError(error: PragmaError): CallToolResult {
-  const recovery = buildRecovery(error.recovery);
-
-  const payload: McpErrorPayload = {
-    code: error.code,
-    message: error.message,
-    ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
-    ...(recovery && { recovery }),
-    ...(error.filters && { filters: error.filters }),
-    ...(error.validOptions && { validOptions: error.validOptions }),
-  };
-
-  return {
-    content: [{ type: "text", text: JSON.stringify(payload) }],
-    isError: true,
-  };
-}

package/src/mcp/error/serializeErrorPayload.test.ts

@@ -1,38 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { PragmaError } from "#error";
-import serializeErrorPayload from "./serializeErrorPayload.js";
-
-describe("serializeErrorPayload", () => {
-  it("includes code and message", () => {
-    const error = PragmaError.emptyResults("component");
-    const payload = serializeErrorPayload(error);
-
-    expect(payload.code).toBe("EMPTY_RESULTS");
-    expect(payload.message).toContain("component");
-  });
-
-  it("includes filters when present", () => {
-    const error = PragmaError.emptyResults("component", {
-      filters: { tier: "global" },
-    });
-    const payload = serializeErrorPayload(error);
-
-    expect(payload.filters).toEqual({ tier: "global" });
-  });
-
-  it("includes validOptions when present", () => {
-    const error = PragmaError.invalidInput("channel", "beta", {
-      validOptions: ["normal", "experimental"],
-    });
-    const payload = serializeErrorPayload(error);
-
-    expect(payload.validOptions).toEqual(["normal", "experimental"]);
-  });
-
-  it("omits empty suggestions", () => {
-    const error = PragmaError.storeError("fail");
-    const payload = serializeErrorPayload(error);
-
-    expect(payload).not.toHaveProperty("suggestions");
-  });
-});

package/src/mcp/error/serializeErrorPayload.ts

@@ -1,34 +0,0 @@
-import type { PragmaError } from "#error";
-import buildRecovery from "./buildRecovery.js";
-import type { McpErrorPayload } from "./types.js";
-
-/**
- * Serialize a PragmaError into the `ok: false` error envelope fields.
- *
- * Extracts code, message, suggestions, recovery, filters, and validOptions
- * into an {@link McpErrorPayload} for embedding in the tool response envelope.
- *
- * @param error - The PragmaError to serialize.
- * @returns A structured error payload for the MCP response envelope.
- */
-export default function serializeErrorPayload(
-  error: PragmaError,
-): McpErrorPayload {
-  const recovery = buildRecovery(error.recovery);
-
-  return {
-    code: error.code,
-    message: error.message,
-    ...(error.suggestions.length > 0 && { suggestions: error.suggestions }),
-    ...(recovery && { recovery }),
-    ...(error.crossDomain && {
-      crossDomain: {
-        domain: error.crossDomain.domain,
-        tool: error.crossDomain.mcp.tool,
-        params: error.crossDomain.mcp.params,
-      },
-    }),
-    ...(error.filters && { filters: error.filters }),
-    ...(error.validOptions && { validOptions: error.validOptions }),
-  };
-}