@canonical/pragma-cli 0.31.0 → 0.33.0

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,104 @@
+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("states the plan-first/confirm convention in the orientation (D2)", () => {
+    // The confirm gate must be surfaced at handshake, not discovered by an agent
+    // tripping it. Same single source as the `capabilities` tool's conventions.
+    const text = buildInstructions(capabilities);
+    expect(text.toLowerCase()).toContain("plan-first");
+    expect(text).toContain("confirm: true");
+  });
+
+  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,104 @@
+/**
+ * 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.
+ *
+ * Both handlers open with a STORELESS cold-store pre-check ({@link
+ * checkStoreAvailable}) so the native surface converges with the store-backed
+ * `prompt_list` tool: a cold store surfaces the SAME `STORE_UNAVAILABLE` +
+ * `sources_update` recovery here as the tool's `needsStore` guard raises, rather
+ * than a silent `[]` (list) or a bogus "not found" (get) that masks the cold
+ * store. When the store is available (including the embedded fallback) both
+ * handlers behave exactly as before.
+ */
+
+import { checkStoreAvailable } from "../../../runtime/storeReadiness.js";
+import type { McpPromptProvider } from "../../../spec/types.js";
+import { mcpErrorFrom } from "../mcpError.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 } });
+
+    // A STORELESS cold-store pre-check, shared with the store-backed `prompt_list`
+    // tool (whose `needsStore` guard throws) and the resource browser: a cold
+    // store must present the SAME STORE_UNAVAILABLE + `sources_update` recovery on
+    // native `prompts/*` as on the tool surface, not silently list from a stale
+    // index (or `[]`) here while the tool errors. Available (incl. the embedded
+    // fallback) → the native list stays storeless and the get stays store-backed.
+    const guardStore = async (): Promise<void> => {
+      const unavailable = checkStoreAvailable(
+        await runtime.loadConfig(),
+        runtime.cwd,
+      );
+      if (unavailable) throw mcpErrorFrom(unavailable, { McpError, ErrorCode });
+    };
+
+    server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      await guardStore();
+      return {
+        prompts: listPromptSummaries(runtime).map((prompt) => ({
+          name: prompt.name,
+          ...(prompt.description ? { description: prompt.description } : {}),
+        })),
+      };
+    });
+
+    server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      await guardStore();
+      const { name, arguments: args } = request.params;
+      const entry = await readPrompt(runtime, name);
+      if (!entry) {
+        // Reached only when the store IS available — a genuine miss, not a cold
+        // store (which `guardStore` already surfaced as STORE_UNAVAILABLE).
+        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),
+            },
+          },
+        ],
+      };
+    });
+  },
+};

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

@@ -0,0 +1,194 @@
+/**
+ * The ONE source of truth for prompt entities — read TWO ways from ONE KG type
+ * (`ds:Prompt`), so the native MCP `prompts/*` surface and the covenant
+ * `prompt_list`/`prompt_lookup` content tools never diverge.
+ *
+ * A `ds:Prompt` is authored as:
+ *   ds:prompt.x a ds:Prompt ;
+ *     rdfs:label "x" ;                 # the prompt NAME (indexed → storeless list)
+ *     rdfs:comment "…" ;               # the description (indexed)
+ *     ds:promptBody "…" ;              # the template body (store-backed)
+ *     ds:promptArgument [ ds:argName "a" ; rdfs:comment "…" ; ds:argRequired true ] .
+ *
+ * Listing is STORELESS (over the pack index — `label`/`description` are indexed),
+ * so `prompts/list` and native discovery cost nothing until a `get`. A `get`
+ * (body + arguments) is STORE-BACKED through the SPARQL facade — identical
+ * laziness to the resource browser (list storeless, read store-backed). An empty
+ * or missing index yields zero prompts (never a store boot on the list path).
+ */
+
+import { readPackIndex } from "../../../completion/entitySource.js";
+import type { PragmaRuntime } from "../../../runtime/types.js";
+
+/** The KG type (prefixed) every prompt entity carries. */
+export const PROMPT_TYPE = "ds:Prompt";
+
+/** One declared argument of a prompt template. */
+export interface PromptArgument {
+  readonly name: string;
+  readonly description?: string;
+  readonly required?: boolean;
+}
+
+/** A prompt as it appears in a listing (name + description only — storeless). */
+export interface PromptSummary {
+  readonly name: string;
+  readonly description?: string;
+}
+
+/** A fully materialized prompt (body + arguments — store-backed). */
+export interface PromptEntry extends PromptSummary {
+  readonly body: string;
+  readonly arguments: readonly PromptArgument[];
+}
+
+/** Whether an index entity is a `ds:Prompt` (primary type or any type). */
+function isPromptEntity(entity: {
+  type: string;
+  types?: readonly string[];
+}): boolean {
+  return (
+    entity.type === PROMPT_TYPE ||
+    (Array.isArray(entity.types) && entity.types.includes(PROMPT_TYPE))
+  );
+}
+
+/**
+ * List prompt summaries STORELESSLY from the active pack index. Returns `[]`
+ * when no index is reachable or the index carries no prompts — never boots the
+ * store.
+ *
+ * @param rt - The per-invocation runtime (for `cwd`).
+ * @returns Prompt summaries (name from the entity label, sorted by name).
+ */
+export function listPromptSummaries(rt: PragmaRuntime): PromptSummary[] {
+  const index = readPackIndex(rt.cwd);
+  if (!index || !Array.isArray(index.entities)) return [];
+  const summaries: PromptSummary[] = [];
+  for (const entity of index.entities) {
+    if (!isPromptEntity(entity)) continue;
+    const name = entity.label || entity.name;
+    summaries.push({
+      name,
+      ...(entity.description ? { description: entity.description } : {}),
+    });
+  }
+  return summaries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Rows the prompt SELECT returns (one per argument; body repeats). The facade's
+ * SELECT bindings are keyed by variable name with PLAIN string values (an
+ * unbound OPTIONAL variable is simply absent) — the same shape `runSelect`
+ * consumes.
+ */
+interface PromptRow {
+  readonly name?: string;
+  readonly description?: string;
+  readonly body?: string;
+  readonly argName?: string;
+  readonly argDescription?: string;
+  readonly argRequired?: string;
+}
+
+/** The SPARQL that materializes prompts (all, or one when `label` is bound). */
+function promptQuery(labelFilter?: string): string {
+  const filter = labelFilter
+    ? `  FILTER(LCASE(STR(?name)) = LCASE(${JSON.stringify(labelFilter)}))`
+    : "";
+  return [
+    "SELECT ?name ?description ?body ?argName ?argDescription ?argRequired WHERE {",
+    "  ?prompt a ds:Prompt ;",
+    "          rdfs:label ?name .",
+    filter,
+    "  OPTIONAL { ?prompt rdfs:comment ?description }",
+    "  OPTIONAL { ?prompt ds:promptBody ?body }",
+    "  OPTIONAL {",
+    "    ?prompt ds:promptArgument ?arg .",
+    "    ?arg ds:argName ?argName .",
+    "    OPTIONAL { ?arg rdfs:comment ?argDescription }",
+    "    OPTIONAL { ?arg ds:argRequired ?argRequired }",
+    "  }",
+    "}",
+    "ORDER BY ?name ?argName",
+  ].join("\n");
+}
+
+/** Fold SELECT rows (one per argument) into distinct {@link PromptEntry}s. */
+function foldPromptRows(rows: readonly PromptRow[]): PromptEntry[] {
+  const byName = new Map<
+    string,
+    { description?: string; body: string; args: Map<string, PromptArgument> }
+  >();
+  for (const row of rows) {
+    const name = row.name;
+    if (!name) continue;
+    let entry = byName.get(name);
+    if (!entry) {
+      entry = { body: "", args: new Map() };
+      if (row.description) entry.description = row.description;
+      byName.set(name, entry);
+    }
+    if (row.body) entry.body = row.body;
+    const argName = row.argName;
+    if (argName && !entry.args.has(argName)) {
+      entry.args.set(argName, {
+        name: argName,
+        ...(row.argDescription ? { description: row.argDescription } : {}),
+        ...(row.argRequired !== undefined
+          ? { required: row.argRequired === "true" }
+          : {}),
+      });
+    }
+  }
+  return [...byName.entries()]
+    .map(([name, entry]) => ({
+      name,
+      ...(entry.description ? { description: entry.description } : {}),
+      body: entry.body,
+      arguments: [...entry.args.values()],
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Extract the SELECT binding rows from a facade query result. */
+function selectRows(result: unknown): PromptRow[] {
+  const typed = result as { type?: string; bindings?: unknown };
+  if (typed.type !== "select" || !Array.isArray(typed.bindings)) return [];
+  return typed.bindings as PromptRow[];
+}
+
+/**
+ * Read every prompt entity STORE-BACKED (body + arguments). Boots the store via
+ * the SPARQL facade; returns `[]` on any query failure (graceful degradation).
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns The materialized prompt entries, sorted by name.
+ */
+export async function readPrompts(rt: PragmaRuntime): Promise<PromptEntry[]> {
+  try {
+    const result = await rt.query.sparql(promptQuery());
+    return foldPromptRows(selectRows(result));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read ONE prompt entity by name (case-insensitive), STORE-BACKED.
+ *
+ * @param rt - The per-invocation runtime.
+ * @param name - The prompt name (its `rdfs:label`).
+ * @returns The materialized prompt, or `undefined` when not found.
+ */
+export async function readPrompt(
+  rt: PragmaRuntime,
+  name: string,
+): Promise<PromptEntry | undefined> {
+  try {
+    const result = await rt.query.sparql(promptQuery(name));
+    return foldPromptRows(selectRows(result))[0];
+  } catch {
+    return undefined;
+  }
+}