@canonical/pragma-cli 0.31.0 → 0.32.0

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}`,
+    "",
+    "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/parity.test.ts

@@ -0,0 +1,72 @@
+import { existsSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  fixtureEffectsModule,
+  touchPath,
+} from "../../../testing/fixtures/fixtureCapability.js";
+import { projectMcp } from "../../../testing/helpers/projectMcp.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+import type { VerbSpec } from "../../spec/types.js";
+import { executeVerb } from "../cli/dispatch.js";
+
+const echoVerb = fixtureEffectsModule.verbs.find(
+  (v) => v.path[1] === "echo",
+) as VerbSpec;
+
+const JSON_FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "json",
+  verbose: false,
+};
+
+describe("envelope parity CLI-json vs MCP (PROTECTED)", () => {
+  it("the echo read verb produces a byte-identical envelope on both surfaces", async () => {
+    const cli = await executeVerb(
+      echoVerb,
+      { message: "hi" },
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(JSON_FLAGS),
+    );
+    const cliEnvelope = JSON.parse(cli.stdout as string);
+
+    const mcp = await projectMcp([fixtureEffectsModule]);
+    const mcpEnvelope = await mcp.callTool("probe_echo", { message: "hi" });
+    await mcp.cleanup();
+
+    expect(cliEnvelope).toEqual(mcpEnvelope);
+    expect(cliEnvelope).toEqual({
+      ok: true,
+      data: { echoed: "hi" },
+      meta: {},
+    });
+  });
+});
+
+describe("MCP mutation plan-first / confirm (PROTECTED)", () => {
+  it("returns a plan and performs no effect without confirm", async () => {
+    const mcp = await projectMcp([fixtureEffectsModule]);
+    const name = `no-confirm-${Date.now()}`;
+
+    const planned = await mcp.callTool("probe_touch", { name });
+    await mcp.cleanup();
+
+    expect(planned.ok).toBe(true);
+    expect(planned.meta).toEqual({ planOnly: true, confirmRequired: true });
+    const { plan } = planned.data as { plan: string[] };
+    expect(plan.length).toBeGreaterThan(0);
+    expect(existsSync(touchPath(name))).toBe(false);
+  });
+
+  it("executes and writes with confirm:true", async () => {
+    const mcp = await projectMcp([fixtureEffectsModule]);
+    const name = `confirmed-${Date.now()}`;
+
+    const done = await mcp.callTool("probe_touch", { name, confirm: true });
+    await mcp.cleanup();
+
+    expect(done).toEqual({ ok: true, data: { touched: name }, meta: {} });
+    expect(existsSync(touchPath(name))).toBe(true);
+  });
+});

package/src/kernel/project/mcp/prompts/prompts.test.ts

@@ -0,0 +1,96 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { capabilities } from "../../../../capabilities/index.js";
+import type { McpHarness } from "../../../../testing/helpers/projectMcp.js";
+import { projectMcp } from "../../../../testing/helpers/projectMcp.js";
+import type { CapabilityModule } from "../../../spec/types.js";
+import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "../instructions.js";
+import { fillTemplate, promptProvider } from "./provider.js";
+
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-prompts-"));
+
+/** A synthetic module that installs the native prompt surface (commit 3 wires
+ * the real prompt module; commit 2 proves the hook mechanism in isolation). */
+const promptHostModule: CapabilityModule = {
+  name: "test-prompt-host",
+  verbs: [],
+  mcpPrompts: promptProvider,
+};
+
+let harness: McpHarness | undefined;
+afterEach(async () => {
+  await harness?.cleanup();
+  harness = undefined;
+});
+
+describe("instructions — handshake orientation (PROTECTED)", () => {
+  it("is present, non-empty, mentions capabilities + the discovery flow", () => {
+    const text = buildInstructions(capabilities);
+    expect(text.length).toBeGreaterThan(0);
+    expect(text).toContain("capabilities");
+    expect(text.toLowerCase()).toContain("discovery sequence");
+  });
+
+  it("stays under the length ceiling (cannot bloat)", () => {
+    expect(buildInstructions(capabilities).length).toBeLessThanOrEqual(
+      INSTRUCTIONS_MAX_CHARS,
+    );
+  });
+
+  it("derives its conventions from the shared catalog source", () => {
+    // The system convention string is authored once (capabilities/catalog.ts);
+    // instructions must carry it verbatim so the two can never diverge.
+    expect(buildInstructions(capabilities)).toContain(
+      "design-system knowledge graph",
+    );
+  });
+
+  it("orients a cold agent to check/build the store before any store read", () => {
+    // Store-blind guard: the handshake must point a cold agent at the store
+    // pre-check (sources_status → sources_update) BEFORE the sample/query steps,
+    // or it walks straight into STORE_UNAVAILABLE.
+    const text = buildInstructions(capabilities);
+    const storeCheck = text.indexOf("sources_status");
+    const sample = text.indexOf("_sample");
+    expect(storeCheck).toBeGreaterThanOrEqual(0);
+    expect(text).toContain("sources_update");
+    expect(storeCheck).toBeLessThan(sample);
+  });
+});
+
+describe("MCP handshake — capabilities advertised (PROTECTED)", () => {
+  it("advertises tools, resources, AND prompts", async () => {
+    harness = await projectMcp([...capabilities, promptHostModule], freshCwd());
+    const caps = harness.serverCapabilities();
+    expect(caps?.tools).toBeDefined();
+    expect(caps?.resources).toBeDefined();
+    expect(caps?.prompts).toBeDefined();
+  });
+
+  it("sends the instructions string at initialize", async () => {
+    harness = await projectMcp([...capabilities, promptHostModule], freshCwd());
+    const instructions = harness.instructions();
+    expect(instructions).toBeDefined();
+    expect(instructions).toContain("capabilities");
+  });
+
+  it("lists zero prompts without a store when no prompt entities exist", async () => {
+    harness = await projectMcp([...capabilities, promptHostModule], freshCwd());
+    const prompts = await harness.listPrompts();
+    expect(prompts).toEqual([]);
+  });
+});
+
+describe("fillTemplate — argument substitution", () => {
+  it("replaces {{arg}} placeholders and leaves unknowns intact", () => {
+    expect(
+      fillTemplate("Build {{name}} in {{framework}}", { name: "Button" }),
+    ).toBe("Build Button in {{framework}}");
+  });
+
+  it("returns the body unchanged when no arguments are given", () => {
+    expect(fillTemplate("static body", undefined)).toBe("static body");
+  });
+});

package/src/kernel/project/mcp/prompts/provider.ts

@@ -0,0 +1,74 @@
+/**
+ * The native MCP `prompts/*` provider — the `mcpPrompts` module hook, mirroring
+ * the resource provider exactly.
+ *
+ * `register` wires the low-level `prompts/list` + `prompts/get` request handlers
+ * and advertises the `prompts` capability (so the server declares it even with
+ * zero prompts — an empty list is a valid, honest surface). Listing is STORELESS
+ * (index-backed via {@link listPromptSummaries}); a get is STORE-BACKED (SPARQL
+ * via {@link readPrompt}), then the template body is filled with the call's
+ * arguments. The SDK request schemas are dynamic-imported inside `register`, so
+ * this module — reachable on the capabilities import graph through the prompt
+ * module — never pulls the SDK types onto the `--help`/`__complete` fast path.
+ */
+
+import type { McpPromptProvider } from "../../../spec/types.js";
+import { listPromptSummaries, readPrompt } from "./source.js";
+
+/** Substitute `{{arg}}` placeholders in a template body with provided values. */
+export function fillTemplate(
+  body: string,
+  args: Record<string, unknown> | undefined,
+): string {
+  if (!args) return body;
+  return body.replace(/\{\{\s*(\w+)\s*\}\}/g, (whole, key: string) => {
+    const value = args[key];
+    return value === undefined || value === null ? whole : String(value);
+  });
+}
+
+/** The native prompt provider (registered by buildServer via `mcpPrompts`). */
+export const promptProvider: McpPromptProvider = {
+  async register(server, runtime) {
+    const {
+      ListPromptsRequestSchema,
+      GetPromptRequestSchema,
+      McpError,
+      ErrorCode,
+    } = await import("@modelcontextprotocol/sdk/types.js");
+
+    // Advertise the capability even when empty — the surface exists regardless
+    // of whether the active graph ships prompt entities.
+    server.server.registerCapabilities({ prompts: { listChanged: false } });
+
+    server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+      prompts: listPromptSummaries(runtime).map((prompt) => ({
+        name: prompt.name,
+        ...(prompt.description ? { description: prompt.description } : {}),
+      })),
+    }));
+
+    server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const entry = await readPrompt(runtime, name);
+      if (!entry) {
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          `Prompt "${name}" not found`,
+        );
+      }
+      return {
+        ...(entry.description ? { description: entry.description } : {}),
+        messages: [
+          {
+            role: "user" as const,
+            content: {
+              type: "text" as const,
+              text: fillTemplate(entry.body, args),
+            },
+          },
+        ],
+      };
+    });
+  },
+};