@canonical/pragma-cli 0.34.0 → 0.36.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

@@ -16,9 +16,9 @@
 
 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";
 
@@ -66,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

@@ -17,8 +17,8 @@ import {
   buildDiscoverySequence,
   CONVENTIONS,
 } from "../../../capabilities/capabilities/catalog.js";
-import { emitSurface } from "../../spec/emitSurface.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;

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

@@ -102,9 +102,12 @@ describe("MCP plan-first is honest (PRA-104)", () => {
 
     expect(planned.ok).toBe(true);
     expect(planned.meta).toEqual({ planOnly: true, confirmRequired: true });
-    expect((planned.data as { plan: string[] }).plan).toContain(
+    // 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/source.ts

@@ -30,11 +30,11 @@
  */
 
 import { readPackIndex } from "../../../completion/entitySource.js";
-import { runSelect } from "../../../packs/sparql/runSelect.js";
+import { runSelect } from "../../../packs/sparql/index.js";
 import type { PackRow } from "../../../packs/types.js";
 import { distributionSource } from "../../../packs/types.js";
+import type { PragmaRuntime } from "../../../runtime/index.js";
 import type { SourcesDecision } from "../../../runtime/resolveSources.js";
-import type { PragmaRuntime } from "../../../runtime/types.js";
 import { VOCABULARY } from "../../../vocabulary.js";
 
 /** The declared prompt terms this module reads the graph with. */

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

@@ -7,7 +7,9 @@
  * capability, and a mutating verb gains the plan-first `confirm` flow: without
  * `confirm`, the verb's `Task` is dry-run and a plan is returned
  * (`{ planOnly: true, confirmRequired: true }`); with `confirm: true`, it runs
- * for real.
+ * for real. That plan is rendered through the SAME shared effect formatter the
+ * CLI preview uses, so the agent-facing and human-facing surfaces describe one
+ * plan rather than two views of it.
  */
 
 import { statSync } from "node:fs";
@@ -18,10 +20,10 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { asPragmaError } from "../../error/fromTaskError.js";
-import { PragmaError } from "../../error/PragmaError.js";
+import { PragmaError } from "../../error/index.js";
 import type { InteractionRuntime, PragmaRuntime } from "../../runtime/types.js";
-import { toolName } from "../../spec/emitSurface.js";
-import type { McpAnnotations, ParamSpec, VerbSpec } from "../../spec/types.js";
+import type { McpAnnotations, ParamSpec, VerbSpec } from "../../spec/index.js";
+import { toolName } from "../../spec/index.js";
 import { toolError, toolSuccess } from "./envelope.js";
 
 /**
@@ -141,6 +143,22 @@ function withDetail(
   };
 }
 
+/**
+ * The notice seam, projected into the envelope's `meta`.
+ *
+ * It existed with exactly ONE consumer: the CLI dispatcher, which writes it to
+ * stderr. An agent therefore could not tell an unbuilt store, a mistyped filter
+ * and a genuinely empty result apart — all three were
+ * `{"ok":true,"data":[],"meta":{}}` — and, later, could not tell an unambiguous
+ * lookup hit from one of three blocks sharing a name. Riding in `meta` keeps
+ * `data` its uniform shape while making both of those ≠ silence, and the CLI's
+ * `--format json` carries the same key so the two surfaces stay byte-equal.
+ */
+function noticeMeta(verb: VerbSpec, data: unknown): Record<string, unknown> {
+  const notice = verb.output.formatters.notice?.(data as never);
+  return notice ? { notice } : {};
+}
+
 /** The tool handler for a read verb: run, project, envelope. */
 function readHandler(verb: VerbSpec, runtime: PragmaRuntime) {
   return async (args: Record<string, unknown>): Promise<CallToolResult> => {
@@ -150,7 +168,10 @@ function readHandler(verb: VerbSpec, runtime: PragmaRuntime) {
       const result = await Promise.resolve(
         verb.run(params, withDetail(verb, runtime, args)) as Promise<unknown>,
       );
-      return toolSuccess(JSON.parse(verb.output.formatters.json(result)));
+      return toolSuccess(
+        JSON.parse(verb.output.formatters.json(result)),
+        noticeMeta(verb, result),
+      );
     } catch (error) {
       return toolError(asPragmaError(error));
     }
@@ -190,7 +211,7 @@ function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
       const mutationRuntime: PragmaRuntime = {
         ...runtime,
         cwd: effectiveCwd,
-        mutation: { preview },
+        mutation: { preview, undo: false },
         interaction,
       };
       const task = await Promise.resolve(
@@ -203,16 +224,40 @@ function mutateHandler(verb: VerbSpec, runtime: PragmaRuntime) {
         // reads are real, writes are recorded and never executed. A tool call
         // whose confirmed run would fail now returns that error instead of a
         // confident plan, so plan-first predicts rather than reassures.
+        //
+        // NO `onLog`: a preview that PERFORMS an effect is not a preview of
+        // that effect, and the recorded `Log`s are already about to be listed.
+        // The interpreter prints nothing of its own when it is absent.
         const previewExec = mutationRuntime.exec ?? {};
         try {
           const { effects } = await runPreview(task, {
             cwd: previewExec.cwd,
             onEffectStart: previewExec.onEffectStart,
-            onLog: logToStderr,
           });
-          const plan = effects
-            .filter((effect) => effect._tag !== "Prompt")
-            .map(describeEffect);
+          // This payload is read by an LLM on a token budget, so it carries
+          // the plan a person is shown rather than the interpreter's
+          // transcript: the same `visiblePlanEffects` filter the CLI preview
+          // applies, from the same module. Without it every internal
+          // `Check exists:` and every repeat of the output directory spent
+          // tokens burying the real artifacts.
+          //
+          // The FILTER is what the surfaces share; the ROW FORMAT is not.
+          // These strings are structured data, so they stay `describeEffect` —
+          // the description `@canonical/task` gives its own effects, which
+          // carries byte counts, has no terminal chrome, and cannot embed an
+          // ANSI escape however the editor that spawned this server configured
+          // colour. That also lets the CLI's `--format json` plan and this one
+          // be compared string for string, which is the A6 invariant.
+          //
+          // Loaded lazily, and from the LIGHT `/format` subpath: the kernel
+          // keeps summon-core proper (and React) off its static import graph.
+          const { visiblePlanEffects } = await import(
+            "@canonical/summon-core/format"
+          );
+          const plan = visiblePlanEffects(
+            effects,
+            runtime.globalFlags.verbose === true,
+          ).map(describeEffect);
           return toolSuccess(
             { plan },
             { planOnly: true, confirmRequired: true },

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

@@ -8,8 +8,8 @@
  */
 
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { loadEffectiveModules } from "../../packs/collect.js";
-import type { CapabilityModule } from "../../spec/types.js";
+import { loadEffectiveModules } from "../../packs/index.js";
+import type { CapabilityModule } from "../../spec/index.js";
 import { buildServer } from "./buildServer.js";
 
 /**

package/src/kernel/render/__snapshots__/renderers.test.ts.snap

@@ -47,8 +47,9 @@ exports[`render matrix (list/lookup/empty × plain/llm/json × detail) > renders
 
 - \`ds:Button\` — **Button** component | Primary action
 - \`ds:Card\` — **Card** pattern",
-      "plain": "ds:Button  Button  component  Primary action
-ds:Card    Card    pattern",
+      "plain": "URI        NAME    KIND       NOTE
+ds:Button  Button  component  Primary action
+ds:Card    Card    pattern    -",
     },
     "lookup": {
       "json": "{"uri":"https://ds.canonical.com/Button","name":"Button","kind":"component","note":"Primary action"}",
@@ -82,7 +83,8 @@ Note:
 
 - **Button** component
 - **Card** pattern",
-      "plain": "Button  component
+      "plain": "NAME    KIND
+Button  component
 Card    pattern",
     },
     "lookup": {
@@ -109,7 +111,8 @@ Card    pattern",
 
 - **Button**
 - **Card**",
-      "plain": "Button
+      "plain": "NAME
+Button
 Card",
     },
     "lookup": {

package/src/kernel/render/contracts.ts

@@ -7,6 +7,27 @@
  * option bags and hand them to {@link renderers}.
  */
 
+/**
+ * Presentation context the dispatcher threads into a verb's PLAIN formatter.
+ *
+ * Only list-shaped formatters read it: the header row is a plain-table
+ * concern (`llm` is the byte-frozen agent contract, `json` the envelope), so
+ * rather than a second formatter family the plain formatter takes this
+ * optional second argument. Absent context reads as an interactive terminal
+ * with headers on — the shape every pre-existing caller assumed.
+ */
+export interface RenderContext {
+  /** False when `--no-headers` suppressed the list header row. */
+  readonly headers: boolean;
+  /**
+   * Whether stdout is an interactive terminal. A piped plain EMPTY list
+   * prints its header row as a zero-record table so field-splitting
+   * consumers stay well-formed; a terminal prints nothing (the empty notice
+   * goes to stderr).
+   */
+  readonly stdoutIsTty: boolean;
+}
+
 /** A single column in a list rendering. */
 export interface ColumnDef<T> {
   readonly key: keyof T & string;

package/src/kernel/render/envelope.ts

@@ -8,9 +8,8 @@
  * pair — is what makes CLI-JSON and MCP output provably identical.
  */
 
-import type { PragmaError } from "../error/PragmaError.js";
-import { serializeError } from "../error/serialize.js";
-import type { ErrorPayload } from "../error/types.js";
+import type { ErrorPayload, PragmaError } from "../error/index.js";
+import { serializeError } from "../error/index.js";
 
 /** The success envelope: an agent branches on `ok` before reading `data`. */
 export interface SuccessEnvelope {

package/src/kernel/render/formatters.ts

@@ -10,7 +10,7 @@
  */
 
 import type { GlobalFlags } from "../runtime/types.js";
-import type { Formatters } from "../spec/types.js";
+import type { Formatters } from "../spec/index.js";
 
 /**
  * Pick the formatter for the active output mode.