@canonical/pragma-cli 0.18.0

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

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

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

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

@@ -0,0 +1,27 @@
+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.filters && { filters: error.filters }),
+    ...(error.validOptions && { validOptions: error.validOptions }),
+  };
+}

package/src/mcp/error/types.ts

@@ -0,0 +1,51 @@
+/**
+ * MCP error and recovery types.
+ *
+ * Defines shapes for error payloads and recovery objects used by the MCP
+ * error serialization pipeline.
+ */
+
+import type { ErrorCode } from "#error";
+
+// ---------------------------------------------------------------------------
+// Recovery
+// ---------------------------------------------------------------------------
+
+/**
+ * MCP recovery object — tells the AI agent what tool to try next.
+ * Extracted directly from the structured `Recovery.mcp` field.
+ */
+export interface McpRecovery {
+  readonly tool: string;
+  readonly params?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Error payload
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured MCP error payload embedded in tool response content.
+ * Returned as JSON text content with `isError: true`.
+ */
+export interface McpErrorPayload {
+  readonly code: ErrorCode;
+  readonly message: string;
+  readonly suggestions?: readonly string[];
+  readonly recovery?: McpRecovery;
+  readonly filters?: Record<string, string>;
+  readonly validOptions?: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// Error envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Error envelope — structured error with recovery hints.
+ * Agents branch on `ok: false` to access error details.
+ */
+export interface ToolErrorResponse {
+  readonly ok: false;
+  readonly error: McpErrorPayload;
+}

package/src/mcp/index.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP server adapter for pragma.
+ *
+ * Re-exports server construction, tool registration, and error types
+ * used by the CLI entry point and integration tests.
+ *
+ * @module
+ */
+
+export {
+  createMcpServer,
+  createMcpServerFromRuntime,
+} from "./createMcpServer.js";
+export type { McpErrorPayload, McpRecovery } from "./error/types.js";
+export { default as registerAllTools } from "./tools/index.js";

package/src/mcp/registerResources.test.ts

@@ -0,0 +1,236 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createTestMcpClient } from "#testing";
+import { P } from "../domains/shared/prefixes.js";
+
+let client: Client;
+let cleanup: () => Promise<void>;
+
+beforeAll(async () => {
+  const result = await createTestMcpClient();
+  client = result.client;
+  cleanup = result.cleanup;
+});
+
+afterAll(async () => {
+  await cleanup();
+});
+
+interface ResourceContent {
+  uri: string;
+  mimeType: string;
+  text: string;
+}
+
+function parseContents(result: { contents: unknown[] }): unknown {
+  const first = result.contents[0] as ResourceContent;
+  return JSON.parse(first.text);
+}
+
+// =============================================================================
+// Resource listing
+// =============================================================================
+
+describe("resource listing", () => {
+  it("registers 1 resource template", async () => {
+    const { resourceTemplates } = await client.listResourceTemplates();
+    expect(resourceTemplates).toHaveLength(1);
+    expect(resourceTemplates[0]?.uriTemplate).toBe("pragma:{+uri}");
+  });
+
+  it("lists resources including known entities", async () => {
+    const { resources } = await client.listResources();
+    const uris = resources.map((r) => r.uri);
+    expect(uris).toContain(`pragma:${P.ds}global.component.button`);
+    expect(uris).toContain(`pragma:${P.ds}global.component.card`);
+    expect(uris).toContain(`pragma:${P.ds}global`);
+  });
+
+  it("lists OWL classes as resources", async () => {
+    const { resources } = await client.listResources();
+    const uris = resources.map((r) => r.uri);
+    expect(uris).toContain(`pragma:${P.ds}UIBlock`);
+    expect(uris).toContain(`pragma:${P.ds}Component`);
+  });
+
+  it("lists code standards as resources", async () => {
+    const { resources } = await client.listResources();
+    const uris = resources.map((r) => r.uri);
+    expect(uris).toContain(`pragma:${P.cs}react_folder`);
+    expect(uris).toContain(`pragma:${P.cs}code_purity`);
+  });
+
+  it("uses label as resource name when available", async () => {
+    const { resources } = await client.listResources();
+    const button = resources.find(
+      (r) => r.uri === `pragma:${P.ds}global.component.button`,
+    );
+    expect(button?.name).toBe("Button");
+  });
+});
+
+// =============================================================================
+// Read instances
+// =============================================================================
+
+describe("read component instance", () => {
+  it("returns entity with types and label", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}global.component.button`,
+    });
+    const entity = parseContents(result) as {
+      uri: string;
+      prefixed: string;
+      types: string[];
+      label: string | null;
+      properties: { predicate: string; values: unknown[] }[];
+    };
+    expect(entity.prefixed).toBe(`${P.ds}global.component.button`);
+    expect(entity.types).toContain(`${P.ds}Component`);
+    expect(entity.label).toBe("Button");
+  });
+
+  it("resolves level-1 URI objects to summaries", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}global.component.button`,
+    });
+    const entity = parseContents(result) as {
+      properties: {
+        predicate: string;
+        values: {
+          type: string;
+          uri?: string;
+          prefixed?: string;
+          label?: string | null;
+        }[];
+      }[];
+    };
+
+    const tierProp = entity.properties.find(
+      (p) => p.predicate === `${P.ds}tier`,
+    );
+    expect(tierProp).toBeDefined();
+    const tierValue = tierProp?.values[0];
+    expect(tierValue?.type).toBe("uri");
+    expect(tierValue?.prefixed).toBe(`${P.ds}global`);
+  });
+
+  it("includes literal values", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}global.component.button`,
+    });
+    const entity = parseContents(result) as {
+      properties: {
+        predicate: string;
+        values: { type: string; value?: string }[];
+      }[];
+    };
+
+    const nameProp = entity.properties.find(
+      (p) => p.predicate === `${P.ds}name`,
+    );
+    expect(nameProp).toBeDefined();
+    expect(nameProp?.values[0]?.type).toBe("literal");
+    expect(nameProp?.values[0]?.value).toBe("Button");
+  });
+});
+
+// =============================================================================
+// Read OWL classes
+// =============================================================================
+
+describe("read OWL class", () => {
+  it("returns class with rdfs:label", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}UIBlock`,
+    });
+    const entity = parseContents(result) as {
+      types: string[];
+      label: string | null;
+      properties: {
+        predicate: string;
+        values: { type: string; value?: string }[];
+      }[];
+    };
+    expect(entity.types).toContain(`${P.owl}Class`);
+    const labelProp = entity.properties.find(
+      (p) => p.predicate === `${P.rdfs}label`,
+    );
+    expect(labelProp?.values[0]?.value).toBe("UI Block");
+  });
+});
+
+// =============================================================================
+// Read code standards
+// =============================================================================
+
+describe("read code standard", () => {
+  it("returns standard with properties", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.cs}code_purity`,
+    });
+    const entity = parseContents(result) as {
+      types: string[];
+      label: string | null;
+      properties: {
+        predicate: string;
+        values: { type: string; value?: string }[];
+      }[];
+    };
+    expect(entity.types).toContain(`${P.cs}CodeStandard`);
+
+    const nameProp = entity.properties.find(
+      (p) => p.predicate === `${P.cs}name`,
+    );
+    expect(nameProp?.values[0]?.value).toBe("code/function/purity");
+
+    const doProp = entity.properties.find((p) => p.predicate === `${P.cs}do`);
+    expect(doProp).toBeDefined();
+    expect(doProp?.values.length).toBeGreaterThan(0);
+
+    const dontProp = entity.properties.find(
+      (p) => p.predicate === `${P.cs}dont`,
+    );
+    expect(dontProp).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Read tiers
+// =============================================================================
+
+describe("read tier", () => {
+  it("returns tier with name", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}apps_lxd`,
+    });
+    const entity = parseContents(result) as {
+      types: string[];
+      properties: {
+        predicate: string;
+        values: { type: string; value?: string; prefixed?: string }[];
+      }[];
+    };
+    expect(entity.types).toContain(`${P.ds}Tier`);
+
+    const nameProp = entity.properties.find(
+      (p) => p.predicate === `${P.ds}name`,
+    );
+    expect(nameProp?.values[0]?.value).toBe("apps/lxd");
+  });
+});
+
+// =============================================================================
+// Error handling
+// =============================================================================
+
+describe("error handling", () => {
+  it("returns text/plain error for unknown entity", async () => {
+    const result = await client.readResource({
+      uri: `pragma:${P.ds}nonexistent`,
+    });
+    const first = result.contents[0] as ResourceContent;
+    expect(first.mimeType).toBe("text/plain");
+    expect(first.text).toContain("ENTITY_NOT_FOUND");
+  });
+});