@canonical/pragma-cli 0.18.0

package/src/error/PragmaError.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "./PragmaError.js";
+
+describe("PragmaError", () => {
+  describe("notFound", () => {
+    it("creates an ENTITY_NOT_FOUND error with entity info", () => {
+      const err = PragmaError.notFound("component", "Buton", {
+        suggestions: ["Button", "ButtonGroup"],
+        recovery: {
+          message: "List available components.",
+          cli: "pragma block list",
+          mcp: { tool: "block_list" },
+        },
+      });
+
+      expect(err).toBeInstanceOf(PragmaError);
+      expect(err.code).toBe("ENTITY_NOT_FOUND");
+      expect(err.message).toBe('component "Buton" not found.');
+      expect(err.entity).toEqual({ type: "component", name: "Buton" });
+      expect(err.suggestions).toEqual(["Button", "ButtonGroup"]);
+      expect(err.recovery).toEqual({
+        message: "List available components.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      });
+    });
+
+    it("defaults suggestions to empty array", () => {
+      const err = PragmaError.notFound("standard", "react/fold");
+      expect(err.suggestions).toEqual([]);
+      expect(err.recovery).toBeUndefined();
+    });
+  });
+
+  describe("emptyResults", () => {
+    it("creates an EMPTY_RESULTS error with filters", () => {
+      const err = 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 } },
+        },
+      });
+
+      expect(err.code).toBe("EMPTY_RESULTS");
+      expect(err.message).toBe("No components found.");
+      expect(err.filters).toEqual({ tier: "apps/lxd", channel: "normal" });
+      expect(err.recovery).toEqual({
+        message: "Widen the search to show all tiers.",
+        cli: "pragma block list --all-tiers",
+        mcp: { tool: "block_list", params: { allTiers: true } },
+      });
+    });
+  });
+
+  describe("invalidInput", () => {
+    it("creates an INVALID_INPUT error with valid options", () => {
+      const err = PragmaError.invalidInput("channel", "aggressive", {
+        validOptions: ["normal", "experimental", "prerelease"],
+      });
+
+      expect(err.code).toBe("INVALID_INPUT");
+      expect(err.message).toBe('Invalid channel "aggressive".');
+      expect(err.validOptions).toEqual([
+        "normal",
+        "experimental",
+        "prerelease",
+      ]);
+    });
+  });
+
+  describe("storeError", () => {
+    it("creates a STORE_ERROR with reason and recovery", () => {
+      const err = PragmaError.storeError("WASM module failed to load", {
+        recovery: {
+          message: "Run pragma doctor to diagnose.",
+          cli: "pragma doctor",
+        },
+      });
+
+      expect(err.code).toBe("STORE_ERROR");
+      expect(err.message).toContain("WASM module failed to load");
+      expect(err.recovery).toEqual({
+        message: "Run pragma doctor to diagnose.",
+        cli: "pragma doctor",
+      });
+    });
+  });
+
+  describe("configError", () => {
+    it("creates a CONFIG_ERROR with valid options", () => {
+      const err = PragmaError.configError(
+        'Tier "apps/nonexistent" not found in ontology.',
+        { validOptions: ["global", "apps", "apps/lxd"] },
+      );
+
+      expect(err.code).toBe("CONFIG_ERROR");
+      expect(err.message).toContain("apps/nonexistent");
+      expect(err.validOptions).toEqual(["global", "apps", "apps/lxd"]);
+    });
+  });
+
+  describe("internalError", () => {
+    it("creates an INTERNAL_ERROR with recovery", () => {
+      const err = PragmaError.internalError("Unexpected null in query result");
+
+      expect(err.code).toBe("INTERNAL_ERROR");
+      expect(err.message).toContain("Unexpected null");
+      expect(err.recovery).toEqual({
+        message: "Please report this issue.",
+      });
+    });
+  });
+
+  it("is an instance of Error", () => {
+    const err = PragmaError.notFound("component", "Foo");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("PragmaError");
+  });
+});

package/src/error/PragmaError.ts

@@ -0,0 +1,164 @@
+import type { 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;
+  /** 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.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;
+    } = {},
+  ): PragmaError {
+    return new PragmaError({
+      code: "ENTITY_NOT_FOUND",
+      message: `${entityType} "${entityName}" not found.`,
+      entity: { type: entityType, name: entityName },
+      suggestions: opts.suggestions,
+      recovery: opts.recovery,
+    });
+  }
+
+  /**
+   * 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: {
+      filters?: Record<string, string>;
+      recovery?: Recovery;
+    } = {},
+  ): PragmaError {
+    return new PragmaError({
+      code: "EMPTY_RESULTS",
+      message: `No ${entityType}s found.`,
+      filters: opts.filters,
+      recovery: opts.recovery,
+    });
+  }
+
+  /**
+   * 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

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

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

@@ -0,0 +1,41 @@
+/**
+ * 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> };
+}
+
+/** 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;
+  /** Active filters at the time of the error. */
+  filters?: Record<string, string>;
+  /** Enumerated valid options when input was rejected. */
+  validOptions?: string[];
+}
+
+export type { ErrorCode, PragmaErrorData, Recovery };

package/src/index.ts

@@ -0,0 +1,141 @@
+/**
+ * Public API surface for `@canonical/pragma-cli`.
+ *
+ * Exports types, boot functions, domain operations, and the MCP adapter.
+ * Internal formatters, command builders, and infrastructure are not exported.
+ *
+ * @module
+ */
+
+// — Config & Error ————————————————————————————————————————————————————————————
+
+export type { PragmaConfig } from "./config/index.js";
+export { readConfig } from "./config/index.js";
+export type { ErrorCode, PragmaErrorData, Recovery } from "./error/index.js";
+export { PragmaError } from "./error/index.js";
+
+// — Runtime ———————————————————————————————————————————————————————————————————
+
+export type { PragmaRuntime } from "./domains/shared/runtime.js";
+export { bootPragma } from "./domains/shared/runtime.js";
+
+// — Shared Types —————————————————————————————————————————————————————————————
+
+export type {
+  ColumnDef,
+  EntityDisplayConfig,
+  ListContract,
+  ListParams,
+  ListResult,
+  LookupContract,
+  LookupParams,
+  LookupResult,
+  MutateContract,
+  SectionDef,
+  SectionKind,
+  ShowContract,
+} from "./domains/shared/contracts.js";
+
+export type {
+  AnatomyNode,
+  AnatomyTree,
+  BatchResult,
+  BlockDetailed,
+  BlockDigest,
+  BlockSummary,
+  CategorySummary,
+  CodeBlock,
+  Disclosure,
+  FilterConfig,
+  InspectResult,
+  ModifierFamily,
+  OntologyClass,
+  OntologyDetailed,
+  OntologyProperty,
+  OntologySummary,
+  PredicateGroup,
+  StandardDetailed,
+  StandardListFilters,
+  StandardRef,
+  StandardSummary,
+  TierEntry,
+  TokenDetailed,
+  TokenRef,
+  TokenSummary,
+} from "./domains/shared/types.js";
+
+// — Domain Operations —————————————————————————————————————————————————————————
+
+export {
+  buildBlockFilters,
+  listBlocks,
+  lookupBlock,
+  resolveBlockList,
+  resolveBlockLookup,
+} from "./domains/block/index.js";
+export { runChecks } from "./domains/doctor/operations/index.js";
+export {
+  executeQuery,
+  inspectUri,
+} from "./domains/graph/operations/index.js";
+export {
+  listModifiers,
+  lookupModifier,
+  modifierEmptyError,
+  resolveModifierList,
+  resolveModifierLookup,
+} from "./domains/modifier/index.js";
+export {
+  listOntologies,
+  showOntology,
+  showOntologyRaw,
+} from "./domains/ontology/operations/index.js";
+export {
+  discoverSkills,
+  listSkills,
+} from "./domains/skill/operations/index.js";
+export {
+  listCategories,
+  listStandards,
+  lookupStandard,
+  resolveStandardList,
+  resolveStandardLookup,
+} from "./domains/standard/index.js";
+export { listTiers } from "./domains/tier/operations/index.js";
+export {
+  listTokens,
+  lookupToken,
+  resolveTokenList,
+  resolveTokenLookup,
+  tokenEmptyError,
+} from "./domains/token/index.js";
+
+// — Domain Types ——————————————————————————————————————————————————————————————
+
+export type { ConfigShowData } from "./domains/config/operations/index.js";
+export type {
+  CheckContext,
+  CheckResult,
+  DoctorData,
+} from "./domains/doctor/operations/index.js";
+export type {
+  InfoData,
+  RegistryCheckResult,
+  StoreSummary,
+  UpgradeData,
+} from "./domains/info/types.js";
+export type { SkillListResult } from "./domains/skill/operations/index.js";
+export type {
+  DiscoveredSkill,
+  SkillFrontmatter,
+  SkillSource,
+} from "./domains/skill/types.js";
+
+// — MCP Adapter ——————————————————————————————————————————————————————————————
+
+export {
+  createMcpServer,
+  createMcpServerFromRuntime,
+} from "./mcp/index.js";
+export { default as registerAllTools } from "./mcp/tools/index.js";
+export type { McpErrorPayload, McpRecovery } from "./mcp/types.js";

package/src/mcp/createMcpServer.test.ts

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

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * 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";