@canonical/pragma-cli 0.33.0 → 0.35.0

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

@@ -60,9 +60,39 @@ const selfVerb: VerbSpec = {
   run: async () => null,
 };
 
+/** A mutating verb with a default-true boolean, for the injected-flag rows. */
+const mutating: VerbSpec = {
+  path: ["thing", "make"],
+  summary: "Make a thing.",
+  params: [
+    {
+      kind: "boolean",
+      name: "withStyles",
+      doc: "Include styles.",
+      default: true,
+    },
+  ],
+  output: { formatters: passthrough },
+  capability: { needsStore: false, mutates: true, mcp: { expose: true } },
+  run: async () => null,
+};
+
 describe("formatVerbHelp", () => {
   const help = formatVerbHelp("pragma", get);
 
+  it("renders every flag the command parses: negations and mutation flags", () => {
+    // Help derives from the same spec facts registration reads, so a page
+    // can never deny a flag that works.
+    const mutatingHelp = formatVerbHelp("pragma", mutating);
+    expect(mutatingHelp).toContain("--with-styles");
+    expect(mutatingHelp).toContain("--no-with-styles");
+    expect(mutatingHelp).toContain("--dry-run");
+    expect(mutatingHelp).toContain("--undo");
+    expect(mutatingHelp).toContain("--yes");
+    // A read verb keeps its Flags block free of mutation rows.
+    expect(help).not.toContain("--dry-run");
+  });
+
   it("renders the usage line with the positional", () => {
     expect(help).toContain("Usage: pragma block get <name> [flags]");
   });

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

@@ -8,8 +8,9 @@
  * `formatVerbHelp`, retargeted at the grammar.
  */
 
-import { kebabCase } from "../../spec/emitSurface.js";
-import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/index.js";
+import { kebabCase } from "../../spec/index.js";
+import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
 import {
   helpColumns,
   helpDim,
@@ -73,13 +74,28 @@ export function formatVerbHelp(programName: string, verb: VerbSpec): string {
     if (cliDoc) lines.push("", cliDoc);
   }
 
-  if (flags.length > 0) {
-    lines.push(
-      "",
-      helpHeading("Flags"),
-      ...helpColumns(flags.map((flag) => [flagDisplay(flag), flag.doc])),
+  // Every flag the command PARSES is rendered, from the same spec facts
+  // registration reads: the declared params, each default-true boolean's
+  // `--no-` negation, and — on a mutating verb — the auto-injected mutation
+  // flags. Help denying a working flag is the drift this derivation removes.
+  const flagRows: (readonly [string, string])[] = flags.flatMap((flag) => {
+    const rows: (readonly [string, string])[] = [
+      [flagDisplay(flag), flag.doc] as const,
+    ];
+    if (flag.kind === "boolean" && flag.default === true) {
+      const kebab = kebabCase(flag.name);
+      rows.push([`--no-${kebab}`, negationFlagDoc(kebab)] as const);
+    }
+    return rows;
+  });
+  if (verb.capability.mutates) {
+    flagRows.push(
+      ...MUTATION_FLAG_DOCS.map(({ flag, doc }) => [flag, doc] as const),
     );
   }
+  if (flagRows.length > 0) {
+    lines.push("", helpHeading("Flags"), ...helpColumns(flagRows));
+  }
 
   if (verb.examples && verb.examples.length > 0) {
     lines.push("", helpHeading("Examples"));

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

@@ -1,19 +1,24 @@
 /**
  * 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.
+ * Constructs an {@link McpServer} whose wire identity PROJECTS from the
+ * distribution: `serverInfo.name` is the declared distribution name (the same
+ * projection that names the CLI bin, so existing agent wiring resolves it) and
+ * `serverInfo.version` the package version — a fork's server introduces itself
+ * under the fork's own name with no code change. The covenant records the rule
+ * (`surface.v2.json` `mcpSurface.serverInfo`) and `identity.test.ts` pins it on
+ * the wire from a fork's config. 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 type { GlobalFlags } from "../../runtime/index.js";
+import { bootRuntime } from "../../runtime/index.js";
+import type { CapabilityModule } from "../../spec/index.js";
 import { buildInstructions } from "./instructions.js";
 import { registerVerb } from "./registerVerb.js";
 
@@ -61,7 +66,10 @@ export async function buildServer(
       }
     }
     // A module's optional resource surface (NOT a tool) — the `{+uri}` template.
-    await module.mcpResources?.register(server, runtime);
+    // The WHOLE module set goes with it: the listing the provider installs is
+    // the union of every module's declared `mcpListable` slices, which the
+    // declaring module cannot see from where it sits.
+    await module.mcpResources?.register(server, runtime, modules);
     // A module's optional native prompt surface (NOT a tool) — `prompts/*`.
     await module.mcpPrompts?.register(server, runtime);
   }

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

@@ -9,8 +9,8 @@
  */
 
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { PragmaError } from "../../error/PragmaError.js";
-import { errorEnvelope, successEnvelope } from "../../render/envelope.js";
+import type { PragmaError } from "../../error/index.js";
+import { errorEnvelope, successEnvelope } from "../../render/index.js";
 
 /**
  * Wrap success data as an MCP tool result.

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

@@ -4,7 +4,8 @@
  *
  * 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
+ * `capabilities` tool, the WHOLE orientation — the opening line included —
+ * derives 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`/
@@ -15,9 +16,9 @@
 import {
   buildDiscoverySequence,
   CONVENTIONS,
-  liveTools,
 } from "../../../capabilities/capabilities/catalog.js";
-import type { CapabilityModule } from "../../spec/types.js";
+import type { CapabilityModule } from "../../spec/index.js";
+import { emitSurface } from "../../spec/index.js";
 
 /** Hard ceiling on the instructions length (asserted by the protected test). */
 export const INSTRUCTIONS_MAX_CHARS = 1500;
@@ -31,18 +32,22 @@ export const INSTRUCTIONS_MAX_CHARS = 1500;
 export function buildInstructions(
   modules: readonly CapabilityModule[],
 ): string {
-  const discovery = buildDiscoverySequence(liveTools(modules));
-  const steps = discovery
+  // Tools AND resource templates come from the one emitted surface: the
+  // `<scheme>:{+uri}` template is declared by the module that serves it and
+  // frozen in the covenant, so quoting it here rather than deriving it would be
+  // a second copy of a string the kernel does not own.
+  const { tools, resources } = emitSurface(modules).mcpSurface;
+  const steps = buildDiscoverySequence(tools)
     .map((stage) => `${stage.stage}. ${stage.tool} — ${stage.purpose}`)
     .join("\n");
+  const templates = resources.map((template) => `\`${template}\``).join(", ");
 
   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.",
+    `Call the \`capabilities\` tool for the full annotated tool catalog; read ${templates} resources (or \`graph_inspect\`) for entity detail.`,
   ].join("\n");
 }

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

@@ -17,7 +17,7 @@
  */
 
 import type { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
-import type { PragmaError } from "../../error/PragmaError.js";
+import type { PragmaError } from "../../error/index.js";
 
 /** The SDK error primitives a provider dynamic-imports and hands to {@link mcpErrorFrom}. */
 export interface McpErrorPrimitives {

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

@@ -1,7 +1,10 @@
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   fixtureEffectsModule,
+  fixturePreviewModule,
   touchPath,
 } from "../../../testing/fixtures/fixtureCapability.js";
 import { projectMcp } from "../../../testing/helpers/projectMcp.js";
@@ -70,3 +73,41 @@ describe("MCP mutation plan-first / confirm (PROTECTED)", () => {
     expect(existsSync(touchPath(name))).toBe(true);
   });
 });
+
+describe("MCP plan-first is honest (PRA-104)", () => {
+  it("returns the ERROR a confirmed run would hit, not a confident plan", async () => {
+    // The CLI twin of this guard lives in cli/dispatch.test.ts: the same
+    // mutation, the same missing source, exiting nonzero instead of printing a
+    // plan. Both surfaces run one interpreter, so they cannot drift.
+    const dir = mkdtempSync(join(tmpdir(), "pragma-graft-mcp-"));
+    const missing = join(dir, "gone");
+
+    const mcp = await projectMcp([fixturePreviewModule], dir);
+    const planned = await mcp.callTool("probe_graft", { source: missing });
+    await mcp.cleanup();
+
+    expect(planned.ok).toBe(false);
+    expect(JSON.stringify(planned.error)).toContain(missing);
+    expect(existsSync(`${missing}.grafted`)).toBe(false);
+  });
+
+  it("returns a plan, and writes nothing, when the read would succeed", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pragma-graft-mcp-"));
+    const source = join(dir, "present.txt");
+    writeFileSync(source, "content\n");
+
+    const mcp = await projectMcp([fixturePreviewModule], dir);
+    const planned = await mcp.callTool("probe_graft", { source });
+    await mcp.cleanup();
+
+    expect(planned.ok).toBe(true);
+    expect(planned.meta).toEqual({ planOnly: true, confirmRequired: true });
+    // The SHARED filter applies to every mutating tool and not just `create`:
+    // the write is named, and the `ReadFile` this verb performs first is
+    // internal and filtered out, so the plan is one row.
+    expect((planned.data as { plan: string[] }).plan).toEqual([
+      `Write file: ${source}.grafted (8 bytes)`,
+    ]);
+    expect(readdirSync(dir)).toEqual(["present.txt"]);
+  });
+});

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

@@ -0,0 +1,37 @@
+/**
+ * Prompt entities, read two ways from one graph type.
+ *
+ * A prompt lives in the graph as an entity the distribution's vocabulary
+ * declares, and two surfaces offer it: the native MCP `prompts/list` +
+ * `prompts/get` handlers, and the `prompt list` / `prompt lookup` verbs behind
+ * the covenant tools. The pair is the cohesion principle — the reader here is
+ * the ONE place either surface learns what a prompt is, so the two can never
+ * report a different set of prompts or a different template body for one.
+ *
+ * The barrel carries both halves, and they READ DIFFERENTLY — the distinction
+ * matters to anyone rerouting imports through here, so it is stated rather
+ * than implied.
+ *
+ * `promptProvider` is the MCP module hook. Its `prompts/list` is STORELESS:
+ * it projects the pack index through `listPromptSummaries`, returning `[]`
+ * when no index is reachable and never booting the store. Its `prompts/get`
+ * is store-backed. The provider is imported STATICALLY by the prompt
+ * capability (`capabilities/prompt/index.ts`) — what it defers is the MCP SDK
+ * itself, whose request schemas it reaches through a dynamic import so the SDK
+ * stays off the `--help`/`__complete` fast path.
+ *
+ * `readPrompts` and `readPrompt` are the reads the CLI verbs take, and BOTH
+ * are store-backed: they query through `runSelect` directly, not through the
+ * index projection. A caller that expects a listing here to be as cheap as the
+ * MCP one is mistaken, and a reroute that makes either reachable statically
+ * from the capability graph puts a store boot on the fast path.
+ *
+ * `listPromptSummaries` stays internal. It is the MCP list path's projection,
+ * not a shared foundation under the two exported reads, and a caller choosing
+ * it directly is choosing a partial prompt without the store-backed body that
+ * makes it usable.
+ */
+
+export { promptProvider } from "./provider.js";
+export type { PromptArgument, PromptEntry } from "./source.js";
+export { readPrompt, readPrompts } from "./source.js";

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

@@ -1,13 +1,18 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { afterEach, describe, expect, it } from "vitest";
+import { CONVENTIONS } from "../../../../capabilities/capabilities/catalog.js";
 import { capabilities } from "../../../../capabilities/index.js";
 import type { McpHarness } from "../../../../testing/helpers/projectMcp.js";
 import { projectMcp } from "../../../../testing/helpers/projectMcp.js";
+import type { PragmaRuntime } from "../../../runtime/types.js";
+import { emitSurface } from "../../../spec/emitSurface.js";
 import type { CapabilityModule } from "../../../spec/types.js";
 import { buildInstructions, INSTRUCTIONS_MAX_CHARS } from "../instructions.js";
 import { fillTemplate, promptProvider } from "./provider.js";
+import { readPrompts } from "./source.js";
 
 const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-prompts-"));
 
@@ -39,14 +44,25 @@ describe("instructions — handshake orientation (PROTECTED)", () => {
     );
   });
 
-  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("opens with the shared catalog's conventions, verbatim and once", () => {
+    // The conventions are authored once (capabilities/catalog.ts); instructions
+    // must OPEN with them, so a second hand-written preamble cannot creep back
+    // in and drift from the `capabilities` tool the same handshake carries.
+    expect(buildInstructions(capabilities).startsWith(CONVENTIONS.system)).toBe(
+      true,
     );
   });
 
+  it("quotes the resource templates the MCP surface actually advertises", () => {
+    // The `pragma:` scheme is covenant-frozen protocol identity
+    // (surface.v2.json). The orientation DERIVES it from the emitted surface
+    // instead of hand-copying it, so the two cannot disagree.
+    const { resources } = emitSurface(capabilities).mcpSurface;
+    expect(resources.length).toBeGreaterThan(0);
+    const text = buildInstructions(capabilities);
+    for (const template of resources) expect(text).toContain(template);
+  });
+
   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.
@@ -91,6 +107,105 @@ describe("MCP handshake — capabilities advertised (PROTECTED)", () => {
   });
 });
 
+/** A runtime whose SPARQL facade always fails with `message`. */
+function createFailingRuntime(message: string): PragmaRuntime {
+  return {
+    query: {
+      sparql: () => Promise.reject(new Error(message)),
+    },
+  } as unknown as PragmaRuntime;
+}
+
+/** Every field at the default layer — the embedded pack answers, so the store IS available. */
+const DEFAULT_ORIGINS = {
+  tier: "default",
+  channel: "default",
+  detail: "default",
+  packs: "default",
+  stories: "default",
+  prefixes: "default",
+} as const;
+
+/**
+ * The same failing facade, wearing the shape `promptProvider.register` needs:
+ * a cwd whose store is AVAILABLE (so `guardStore` passes and the read is what
+ * fails) plus a `loadConfig` the readiness check can resolve.
+ */
+function createFailingProviderRuntime(
+  cwd: string,
+  message: string,
+): PragmaRuntime {
+  return {
+    cwd,
+    loadConfig: async () => ({
+      config: { channel: "normal" as const },
+      origins: DEFAULT_ORIGINS,
+      global: { path: "/nonexistent", exists: false },
+      project: { exists: false },
+    }),
+    query: { sparql: () => Promise.reject(new Error(message)) },
+  } as unknown as PragmaRuntime;
+}
+
+describe("native prompts/get — a failed read reaches the agent as one", () => {
+  it("carries the machine code and recovery, not a bare Error", async () => {
+    // The native surface signals failure by THROWING, so a read that fails must
+    // be projected the way the resource browser projects its own — with `code`
+    // and `recovery` in the JSON-RPC `data`. Otherwise the store diagnosis is
+    // lost between `prompt_lookup` (which envelopes it) and `prompts/get`.
+    const handlers = new Map<unknown, (request: unknown) => Promise<unknown>>();
+    const stubServer = {
+      server: {
+        registerCapabilities: () => {},
+        setRequestHandler: (
+          schema: unknown,
+          handler: (request: unknown) => Promise<unknown>,
+        ) => {
+          handlers.set(schema, handler);
+        },
+      },
+    };
+    await promptProvider.register(
+      stubServer as never,
+      createFailingProviderRuntime(freshCwd(), "Prefix not found: ds"),
+    );
+
+    const get = handlers.get(GetPromptRequestSchema);
+    expect(get).toBeDefined();
+    await expect(
+      get?.({ params: { name: "build-a-block" } }),
+    ).rejects.toMatchObject({
+      data: {
+        code: "STORE_UNAVAILABLE",
+        recovery: { mcp: { tool: "sources_update" } },
+      },
+    });
+  });
+});
+
+describe("readPrompts — a failed read is never an empty graph", () => {
+  it("reports an unbound prefix as a store that cannot answer, not as no prompts", async () => {
+    // A pack whose store does not know the declared prompt namespace cannot
+    // answer, and the actionable form of that is STORE_UNAVAILABLE with the
+    // build command — not a silent zero-prompt listing.
+    await expect(
+      readPrompts(createFailingRuntime("Prefix not found: ds")),
+    ).rejects.toMatchObject({
+      code: "STORE_UNAVAILABLE",
+      recovery: { mcp: { tool: "sources_update" } },
+    });
+  });
+
+  it("propagates a query failure instead of returning no prompts", async () => {
+    // The exact defect a bare `catch {}` here caused: a malformed declaration
+    // becomes a parse error, the parse error becomes `[]`, and the user is told
+    // the distribution ships no prompts. It must surface as a failure.
+    await expect(
+      readPrompts(createFailingRuntime("SPARQL syntax error at line 2")),
+    ).rejects.toThrow(/syntax error/);
+  });
+});
+
 describe("fillTemplate — argument substitution", () => {
   it("replaces {{arg}} placeholders and leaves unknowns intact", () => {
     expect(

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

@@ -12,14 +12,17 @@
  * 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.
+ * checkStoreAvailable}), and the store-backed `get` projects any read failure
+ * through {@link mcpErrorFrom}, so the native surface converges with the
+ * store-backed `prompt_list` tool: a cold store — or a store that cannot answer
+ * the prompt query — surfaces the SAME machine code and recovery here as the
+ * tool envelope carries, rather than a silent `[]` (list) or a bogus "not found"
+ * (get) that masks it. When the store is available (including the embedded
+ * fallback) both handlers behave exactly as before.
  */
 
+import { asPragmaError } from "../../../error/fromTaskError.js";
+import { resolveSources } from "../../../runtime/resolveSources.js";
 import { checkStoreAvailable } from "../../../runtime/storeReadiness.js";
 import type { McpPromptProvider } from "../../../spec/types.js";
 import { mcpErrorFrom } from "../mcpError.js";
@@ -68,7 +71,9 @@ export const promptProvider: McpPromptProvider = {
     server.server.setRequestHandler(ListPromptsRequestSchema, async () => {
       await guardStore();
       return {
-        prompts: listPromptSummaries(runtime).map((prompt) => ({
+        prompts: listPromptSummaries(
+          resolveSources(await runtime.loadConfig(), runtime.cwd),
+        ).map((prompt) => ({
           name: prompt.name,
           ...(prompt.description ? { description: prompt.description } : {}),
         })),
@@ -78,7 +83,16 @@ export const promptProvider: McpPromptProvider = {
     server.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
       await guardStore();
       const { name, arguments: args } = request.params;
-      const entry = await readPrompt(runtime, name);
+      // The read can fail (a store that cannot answer the prompt query), and a
+      // native surface signals that by THROWING — so project it the way the
+      // resource browser does, carrying the machine code and the recovery into
+      // the JSON-RPC `data` instead of letting a bare Error reach the agent.
+      let entry: Awaited<ReturnType<typeof readPrompt>>;
+      try {
+        entry = await readPrompt(runtime, name);
+      } catch (error) {
+        throw mcpErrorFrom(asPragmaError(error), { McpError, ErrorCode });
+      }
       if (!entry) {
         // Reached only when the store IS available — a genuine miss, not a cold
         // store (which `guardStore` already surfaced as STORE_UNAVAILABLE).