@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/project/cli/suggestNames.ts

@@ -0,0 +1,122 @@
+/**
+ * Rank candidate names by similarity to a failed token.
+ *
+ * Ported near-verbatim from the v1 suggester: prefix matches first, then
+ * Damerau-Levenshtein edit-distance matches under a normalized threshold. Used
+ * by the unknown-command suggester to turn a typo into "Did you mean: …?".
+ */
+
+/**
+ * Return up to {@link maxResults} candidates most similar to `query`.
+ *
+ * Exact matches are excluded — a match means the caller should have resolved it
+ * and never reached here.
+ *
+ * @param query - The token that failed to resolve.
+ * @param candidates - All known names to rank against.
+ * @param opts.maxResults - Max suggestions to return (default 5).
+ * @param opts.threshold - Max normalized edit distance (default 0.4).
+ * @returns Ranked suggestions, original casing preserved.
+ */
+export function suggestNames(
+  query: string,
+  candidates: readonly string[],
+  opts?: { maxResults?: number; threshold?: number },
+): string[] {
+  if (query === "") return [];
+
+  const maxResults = opts?.maxResults ?? 5;
+  const threshold = opts?.threshold ?? 0.4;
+  const queryLower = query.toLowerCase();
+
+  type Scored = { name: string; score: number };
+  const scored: Scored[] = [];
+
+  for (const candidate of candidates) {
+    const candidateLower = candidate.toLowerCase();
+
+    if (candidateLower === queryLower) continue;
+
+    if (candidateLower.startsWith(queryLower)) {
+      scored.push({ name: candidate, score: 0 });
+      continue;
+    }
+
+    const distance = damerauLevenshtein(queryLower, candidateLower);
+    const maxLen = Math.max(queryLower.length, candidateLower.length);
+    const normalized = maxLen === 0 ? 0 : distance / maxLen;
+
+    if (normalized <= threshold) {
+      scored.push({ name: candidate, score: normalized });
+    }
+  }
+
+  scored.sort((a, b) => a.score - b.score);
+  return scored.slice(0, maxResults).map((s) => s.name);
+}
+
+/**
+ * Damerau-Levenshtein distance: insertions, deletions, substitutions, and
+ * adjacent transpositions.
+ */
+function damerauLevenshtein(a: string, b: string): number {
+  const lenA = a.length;
+  const lenB = b.length;
+
+  if (lenA === 0) return lenB;
+  if (lenB === 0) return lenA;
+
+  const matrix: number[][] = Array.from({ length: lenA + 1 }, () =>
+    Array.from<number>({ length: lenB + 1 }).fill(0),
+  );
+
+  for (let i = 0; i <= lenA; i++) {
+    getRow(matrix, i)[0] = i;
+  }
+  const firstRow = getRow(matrix, 0);
+  for (let j = 0; j <= lenB; j++) {
+    firstRow[j] = j;
+  }
+
+  for (let i = 1; i <= lenA; i++) {
+    const prevRow = getRow(matrix, i - 1);
+    const row = getRow(matrix, i);
+    for (let j = 1; j <= lenB; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+
+      row[j] = Math.min(
+        getCell(prevRow, j) + 1, // deletion
+        getCell(row, j - 1) + 1, // insertion
+        getCell(prevRow, j - 1) + cost, // substitution
+      );
+
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        const prevPrevRow = getRow(matrix, i - 2);
+        row[j] = Math.min(
+          getCell(row, j),
+          getCell(prevPrevRow, j - 2) + cost, // transposition
+        );
+      }
+    }
+  }
+
+  return getCell(getRow(matrix, lenA), lenB);
+}
+
+/** Read a matrix row that is structurally guaranteed to exist. */
+function getRow(matrix: number[][], index: number): number[] {
+  const row = matrix.at(index);
+  if (row === undefined) {
+    throw new Error(`matrix row ${index} is out of bounds`);
+  }
+  return row;
+}
+
+/** Read a matrix cell that is structurally guaranteed to exist. */
+function getCell(row: number[], index: number): number {
+  const cell = row.at(index);
+  if (cell === undefined) {
+    throw new Error(`matrix cell ${index} is out of bounds`);
+  }
+  return cell;
+}

package/src/kernel/project/cli/verbHelp.test.ts

@@ -0,0 +1,138 @@
+import chalk from "chalk";
+import { afterAll, describe, expect, it } from "vitest";
+import type { VerbSpec } from "../../spec/types.js";
+import { formatNounHelp, formatVerbHelp } from "./verbHelp.js";
+
+// Help styling (helpFormat.ts) routes through chalk, whose `supports-color`
+// enables color when GITHUB_ACTIONS is set — even off a TTY — so CI would paint
+// ANSI into these plain goldens (locally chalk stays at level 0, which is why it
+// only failed in CI). Pin the level to 0 for a deterministic, color-free render
+// (the same guard colophon.render.test.ts uses). Set at module scope so the
+// collection-time formatVerbHelp() call below renders plain too.
+const prevChalkLevel = chalk.level;
+chalk.level = 0;
+afterAll(() => {
+  chalk.level = prevChalkLevel;
+});
+
+const passthrough = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+const get: VerbSpec = {
+  path: ["block", "get"],
+  summary: "Get a block by name.",
+  doc: "Resolves the block and prints its anatomy.",
+  params: [
+    {
+      kind: "string",
+      name: "name",
+      doc: "Block name.",
+      positional: true,
+      required: true,
+    },
+    { kind: "boolean", name: "withAnatomy", doc: "Include the anatomy tree." },
+  ],
+  output: { formatters: passthrough },
+  examples: [{ cmd: "pragma block get Button", note: "the primary button" }],
+  capability: { needsStore: true, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+const list: VerbSpec = {
+  path: ["block", "list"],
+  summary: "List blocks.",
+  params: [],
+  output: { formatters: passthrough },
+  capability: { needsStore: true, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+/** A self-verb (`path.length === 1`) to exercise the root-pointing footer. */
+const selfVerb: VerbSpec = {
+  path: ["doctor"],
+  summary: "Check environment health.",
+  params: [],
+  output: { formatters: passthrough },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async () => null,
+};
+
+describe("formatVerbHelp", () => {
+  const help = formatVerbHelp("pragma", get);
+
+  it("renders the usage line with the positional", () => {
+    expect(help).toContain("Usage: pragma block get <name> [flags]");
+  });
+
+  it("renders summary, extended doc, the kebab flag, and examples", () => {
+    expect(help).toContain("Get a block by name.");
+    expect(help).toContain("Resolves the block and prints its anatomy.");
+    expect(help).toContain("--with-anatomy");
+    expect(help).toContain("pragma block get Button");
+    expect(help).toContain("the primary button");
+  });
+
+  it("closes a sub-verb page with a footer pointing at the noun page", () => {
+    expect(help).toContain(
+      "Run `pragma block --help` to see all block commands.",
+    );
+  });
+
+  it("closes a self-verb page with a footer pointing at the root", () => {
+    expect(formatVerbHelp("pragma", selfVerb)).toContain(
+      "Run `pragma --help` to see all commands.",
+    );
+  });
+
+  it("renders the unified verb page (restyle golden)", () => {
+    expect(help).toMatchInlineSnapshot(`
+      "Usage: pragma block get <name> [flags]
+
+      Get a block by name.
+
+      Resolves the block and prints its anatomy.
+
+      Flags
+        --with-anatomy  Include the anatomy tree.
+
+      Examples
+        pragma block get Button
+          the primary button
+
+      Run \`pragma block --help\` to see all block commands."
+    `);
+  });
+});
+
+describe("formatNounHelp", () => {
+  it("lists the noun's verbs with summaries", () => {
+    const help = formatNounHelp("pragma", "block", [get, list]);
+    expect(help).toContain("Usage: pragma block <verb> [flags]");
+    expect(help).toContain("get");
+    expect(help).toContain("list");
+    expect(help).toContain("Get a block by name.");
+  });
+
+  it("renders the unified noun page (restyle golden)", () => {
+    expect(
+      formatNounHelp("pragma", "block", [get, list]),
+    ).toMatchInlineSnapshot(`
+      "Usage: pragma block <verb> [flags]
+
+      Verbs
+        get   Get a block by name.
+        list  List blocks.
+
+      Run \`pragma block <verb> --help\` for details on a verb."
+    `);
+  });
+
+  it("handles a noun with no verbs", () => {
+    expect(formatNounHelp("pragma", "ghost", [])).toBe(
+      'No commands found for "ghost".',
+    );
+  });
+});

package/src/kernel/project/cli/verbHelp.ts

@@ -0,0 +1,144 @@
+/**
+ * Verb-level help, rendered from a {@link VerbSpec}.
+ *
+ * Help is designed, not auto-generated: a usage line with positional tokens,
+ * the summary and optional extended doc, a flags block, and the verb's own
+ * authored examples. Reads only the spec's declarative fields — never the run
+ * body — so it stays on the fast `--help` path. Ported from the v1 cli-core
+ * `formatVerbHelp`, retargeted at the grammar.
+ */
+
+import { kebabCase } from "../../spec/emitSurface.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import {
+  helpColumns,
+  helpDim,
+  helpHeading,
+  helpTerm,
+  helpUsage,
+} from "./helpFormat.js";
+
+/**
+ * A verb's `doc` doubles as its MCP tool description, so a pack's authored
+ * `toolDescription` may end with an MCP tool-call example — `Example:
+ * token_lookup { names: ["…"] }`. That `noun_verb {…}` syntax is MCP-transport
+ * shape, meaningless on the CLI, so the CLI projector drops the trailing example
+ * sentence; the MCP projector keeps the authored text whole. Hand-written docs
+ * carry no such example and pass through untouched.
+ */
+function stripToolCallExample(doc: string): string {
+  return doc.replace(/\s*Example:\s+[a-z][a-z0-9_]*\s*\{[^{}]*\}\.?\s*$/, "");
+}
+
+/** The positional usage token for a param (`<name>` / `[name]`, `...` variadic). */
+function positionalToken(param: ParamSpec): string {
+  const variadic = param.kind === "string[]" ? "..." : "";
+  return param.required
+    ? `<${param.name}${variadic}>`
+    : `[${param.name}${variadic}]`;
+}
+
+/** The flag display for a non-positional param (`--kebab` or `--kebab <value>`). */
+function flagDisplay(param: ParamSpec): string {
+  const flag = `--${kebabCase(param.name)}`;
+  if (param.kind === "boolean") return flag;
+  if (param.kind === "string[]") return `${flag} <values...>`;
+  return `${flag} <value>`;
+}
+
+/**
+ * Render the full verb help block.
+ *
+ * @param programName - The CLI binary name shown in the usage line.
+ * @param verb - The verb whose interface is documented.
+ * @returns The formatted help text.
+ */
+export function formatVerbHelp(programName: string, verb: VerbSpec): string {
+  const commandPath = verb.path
+    .filter((s): s is string => Boolean(s))
+    .join(" ");
+  const positionals = verb.params.filter((p) => p.positional);
+  const flags = verb.params.filter((p) => !p.positional);
+
+  const positionalStr = positionals.map(positionalToken).join(" ");
+  const usageSuffix = positionalStr ? ` ${positionalStr}` : "";
+  const lines: string[] = [
+    helpUsage(`${programName} ${commandPath}${usageSuffix} [flags]`),
+    "",
+    verb.summary,
+  ];
+
+  if (verb.doc) {
+    const cliDoc = stripToolCallExample(verb.doc);
+    if (cliDoc) lines.push("", cliDoc);
+  }
+
+  if (flags.length > 0) {
+    lines.push(
+      "",
+      helpHeading("Flags"),
+      ...helpColumns(flags.map((flag) => [flagDisplay(flag), flag.doc])),
+    );
+  }
+
+  if (verb.examples && verb.examples.length > 0) {
+    lines.push("", helpHeading("Examples"));
+    for (const example of verb.examples) {
+      lines.push(`  ${helpTerm(example.cmd)}`);
+      if (example.note) lines.push(`    ${helpDim(example.note)}`);
+    }
+  }
+
+  lines.push("", verbHelpFooter(programName, verb));
+
+  return lines.join("\n");
+}
+
+/**
+ * The footer pointing at the next help level: a sub-verb points UP to its noun
+ * page (`pragma block --help`), a self-verb points to the root (`pragma
+ * --help`). Uniform across every verb page — the leaf pages used to have none.
+ */
+function verbHelpFooter(programName: string, verb: VerbSpec): string {
+  if (verb.path.length > 1) {
+    const noun = verb.path[0];
+    return helpDim(
+      `Run \`${programName} ${noun} --help\` to see all ${noun} commands.`,
+    );
+  }
+  return helpDim(`Run \`${programName} --help\` to see all commands.`);
+}
+
+/**
+ * Render noun-level help — the list of verbs under a noun parent
+ * (`pragma config --help`).
+ *
+ * @param programName - The CLI binary name shown in the usage line.
+ * @param noun - The noun whose verbs are listed.
+ * @param verbs - All registered verbs (filtered to this noun's sub-verbs).
+ * @returns The formatted help text.
+ */
+export function formatNounHelp(
+  programName: string,
+  noun: string,
+  verbs: readonly VerbSpec[],
+): string {
+  const nounVerbs = verbs.filter(
+    (v) => v.path[0] === noun && v.path[1] && !v.hidden,
+  );
+  if (nounVerbs.length === 0) return `No commands found for "${noun}".`;
+
+  const lines: string[] = [
+    helpUsage(`${programName} ${noun} <verb> [flags]`),
+    "",
+    helpHeading("Verbs"),
+    ...helpColumns(
+      nounVerbs.map((verb) => [verb.path[1] as string, verb.summary]),
+    ),
+    "",
+    helpDim(
+      `Run \`${programName} ${noun} <verb> --help\` for details on a verb.`,
+    ),
+  ];
+  return lines.join("\n");
+}

package/src/kernel/project/mcp/buildServer.ts

@@ -0,0 +1,70 @@
+/**
+ * Build the MCP server from the grammar.
+ *
+ * Constructs an {@link McpServer} under the stable `pragma` identity (matching
+ * the CLI bin, so existing agent wiring resolves it), then registers every
+ * exposed verb as a tool and each module's optional `mcpResources` surface (the
+ * graph resource browser, wired below via `module.mcpResources?.register`). One
+ * runtime is booted for the server's lifetime and shared by every tool; the
+ * store stays lazy, booting only when a resource read needs it.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MCP_SERVER_NAME, VERSION } from "../../../constants.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+import type { CapabilityModule } from "../../spec/types.js";
+import { buildInstructions } from "./instructions.js";
+import { registerVerb } from "./registerVerb.js";
+
+/**
+ * Neutral flags for the MCP runtime. Output shaping is the projector's job
+ * (every tool returns the machine envelope), so these only seed `run` bodies
+ * that read `globalFlags` — none do in PR1.
+ */
+const MCP_FLAGS: GlobalFlags = {
+  llm: true,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+/**
+ * Assemble the MCP server, registering all exposed verbs as tools and any
+ * module resource surfaces.
+ *
+ * Async because a module's `mcpResources.register` dynamic-imports the SDK's
+ * `ResourceTemplate` (so the resource browser never lands on the storeless
+ * `--help`/`__complete` fast path).
+ *
+ * @param modules - The capability modules to project.
+ * @param cwd - The working directory for the server's runtime.
+ * @returns The configured MCP server, ready to `connect` to a transport.
+ * @note Impure by default — reads `process.cwd()` unless `cwd` is provided.
+ */
+export async function buildServer(
+  modules: readonly CapabilityModule[],
+  cwd: string = process.cwd(),
+): Promise<McpServer> {
+  const server = new McpServer(
+    { name: MCP_SERVER_NAME, version: VERSION },
+    // Handshake orientation (sent once at initialize), derived from the SAME
+    // conventions/discovery as the `capabilities` tool so the two never diverge.
+    { instructions: buildInstructions(modules) },
+  );
+  const runtime = bootRuntime(MCP_FLAGS, cwd);
+
+  for (const module of modules) {
+    for (const verb of module.verbs) {
+      if (verb.capability.mcp.expose) {
+        registerVerb(server, verb, runtime);
+      }
+    }
+    // A module's optional resource surface (NOT a tool) — the `{+uri}` template.
+    await module.mcpResources?.register(server, runtime);
+    // A module's optional native prompt surface (NOT a tool) — `prompts/*`.
+    await module.mcpPrompts?.register(server, runtime);
+  }
+
+  return server;
+}

package/src/kernel/project/mcp/envelope.ts

@@ -0,0 +1,44 @@
+/**
+ * MCP transport wrapping of the shared machine envelope.
+ *
+ * The MCP projector returns the *same* `{ ok, data, meta }` / `{ ok, error }`
+ * envelope the CLI emits under `--format json` — built by the shared
+ * `successEnvelope` / `errorEnvelope` — serialized into a single text content
+ * block (D4). Reusing the shared builders is what guarantees CLI-JSON and MCP
+ * output are byte-identical.
+ */
+
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { PragmaError } from "../../error/PragmaError.js";
+import { errorEnvelope, successEnvelope } from "../../render/envelope.js";
+
+/**
+ * Wrap success data as an MCP tool result.
+ *
+ * @param data - The JSON-safe data projection.
+ * @param meta - Envelope metadata (e.g. plan-first flags); defaults to `{}`.
+ * @returns The tool result carrying the success envelope.
+ */
+export function toolSuccess(
+  data: unknown,
+  meta: Record<string, unknown> = {},
+): CallToolResult {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(successEnvelope(data, meta)) },
+    ],
+  };
+}
+
+/**
+ * Wrap a {@link PragmaError} as an MCP tool result flagged `isError`.
+ *
+ * @param error - The structured error to serialize.
+ * @returns The tool result carrying the failure envelope.
+ */
+export function toolError(error: PragmaError): CallToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(errorEnvelope(error)) }],
+    isError: true,
+  };
+}

package/src/kernel/project/mcp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP projector barrel — the server builder and the verb→tool adapter.
+ */
+
+export { buildServer } from "./buildServer.js";
+export { toolError, toolSuccess } from "./envelope.js";
+export { buildZodSchema, registerVerb } from "./registerVerb.js";
+export { serveMcp } from "./serve.js";

package/src/kernel/project/mcp/instructions.ts

@@ -0,0 +1,48 @@
+/**
+ * The MCP server `instructions` string — orientation sent ONCE in the
+ * initialize handshake (not per tool call), so agents arrive oriented.
+ *
+ * It carries the same content the retired `llm` tool front-loaded: the
+ * conventions + the discovery sequence. To guarantee it never diverges from the
+ * `capabilities` tool, it derives BOTH from the SAME source — `CONVENTIONS` and
+ * `buildDiscoverySequence` in `capabilities/capabilities/catalog.ts`. Live
+ * numbers (tier/channel/entity counts) are deliberately DROPPED (they would need
+ * a store boot at handshake); agents fetch those via `info`/`config show`/
+ * `sources status`. Kept short (a hard length ceiling is asserted in the test),
+ * since it counts against every session's context.
+ */
+
+import {
+  buildDiscoverySequence,
+  CONVENTIONS,
+  liveTools,
+} from "../../../capabilities/capabilities/catalog.js";
+import type { CapabilityModule } from "../../spec/types.js";
+
+/** Hard ceiling on the instructions length (asserted by the protected test). */
+export const INSTRUCTIONS_MAX_CHARS = 1500;
+
+/**
+ * Build the handshake orientation string from the live capability modules.
+ *
+ * @param modules - The capability modules (for the live discovery-sample list).
+ * @returns A short, single-source orientation string (≤ {@link INSTRUCTIONS_MAX_CHARS}).
+ */
+export function buildInstructions(
+  modules: readonly CapabilityModule[],
+): string {
+  const discovery = buildDiscoverySequence(liveTools(modules));
+  const steps = discovery
+    .map((stage) => `${stage.stage}. ${stage.tool} — ${stage.purpose}`)
+    .join("\n");
+
+  return [
+    "pragma is a CLI and MCP server over a design-system knowledge graph.",
+    `${CONVENTIONS.system} ${CONVENTIONS.model} ${CONVENTIONS.querying} ${CONVENTIONS.mutations}`,
+    "",
+    "Discovery sequence:",
+    steps,
+    "",
+    "Call the `capabilities` tool for the full annotated tool catalog; read `pragma:{+uri}` resources (or `graph_inspect`) for entity detail.",
+  ].join("\n");
+}

package/src/kernel/project/mcp/mcpError.ts

@@ -0,0 +1,52 @@
+/**
+ * Project a {@link PragmaError} into an SDK `McpError` for the NATIVE MCP
+ * surfaces (the `prompts/*` provider, the `pragma:{+uri}` resource browser),
+ * which signal failure by throwing a JSON-RPC error rather than by returning the
+ * `{ ok, error }` tool envelope.
+ *
+ * A native read must not swallow a failure into plain-text "success" content: it
+ * carries the machine `code` AND the structured `recovery` into the JSON-RPC
+ * `data`, so an agent that hits a cold store over `prompts/list` or a resource
+ * read sees the SAME `STORE_UNAVAILABLE` + `sources_update` recovery the tool
+ * envelope carries — never a bare string with the recovery dropped.
+ *
+ * The SDK's `McpError`/`ErrorCode` are PASSED IN by the caller (which already
+ * dynamic-imported them in its `register`), so this module — reachable on the
+ * capabilities import graph — never statically pulls the SDK onto the
+ * `--help`/`__complete` fast path.
+ */
+
+import type { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import type { PragmaError } from "../../error/PragmaError.js";
+
+/** The SDK error primitives a provider dynamic-imports and hands to {@link mcpErrorFrom}. */
+export interface McpErrorPrimitives {
+  readonly McpError: typeof McpError;
+  readonly ErrorCode: typeof ErrorCode;
+}
+
+/**
+ * Build an `McpError` from a {@link PragmaError}, mapping the machine code to a
+ * JSON-RPC code and preserving `code`/`recovery`/`suggestions`/`validOptions` in
+ * `data`.
+ *
+ * @param error - The structured pragma error to project.
+ * @param primitives - The SDK `McpError`/`ErrorCode` the caller imported.
+ * @returns An `McpError` carrying the diagnostic + recovery in its `data`.
+ */
+export function mcpErrorFrom(
+  error: PragmaError,
+  { McpError: McpErrorCtor, ErrorCode: ErrorCodeEnum }: McpErrorPrimitives,
+): McpError {
+  // A bad/missing entity or rejected input is the caller's fault (InvalidParams);
+  // an unreachable store or internal fault is the server's (InternalError).
+  const jsonRpcCode =
+    error.code === "ENTITY_NOT_FOUND" || error.code === "INVALID_INPUT"
+      ? ErrorCodeEnum.InvalidParams
+      : ErrorCodeEnum.InternalError;
+  const data: Record<string, unknown> = { code: error.code };
+  if (error.recovery) data.recovery = error.recovery;
+  if (error.suggestions.length > 0) data.suggestions = error.suggestions;
+  if (error.validOptions) data.validOptions = error.validOptions;
+  return new McpErrorCtor(jsonRpcCode, error.message, data);
+}