@canonical/pragma-cli 0.33.0 → 0.34.0

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

@@ -1,11 +1,18 @@
+import { existsSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { fail, succeed } from "@canonical/task";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { fixturePreviewModule } from "../../../testing/fixtures/fixtureCapability.js";
 import { PragmaError } from "../../error/PragmaError.js";
 import { bootRuntime } from "../../runtime/boot.js";
 import type { GlobalFlags } from "../../runtime/types.js";
 import type { ParamSpec, VerbSpec } from "../../spec/types.js";
 import { dispatch, executeVerb, extractParams } from "./dispatch.js";
 
+/** The read-then-write mutation the honest-preview guards drive. */
+const graft = fixturePreviewModule.verbs[0] as VerbSpec;
+
 const PLAIN: GlobalFlags = {
   llm: false,
   autoLlm: false,
@@ -233,6 +240,66 @@ describe("dispatch — errors", () => {
   });
 });
 
+describe("--dry-run is honest (PRA-104)", () => {
+  const savedExit = process.exitCode;
+  afterEach(() => {
+    process.exitCode = savedExit;
+  });
+
+  /** Capture stderr for one dispatch. */
+  const dispatchCapturing = async (
+    positionals: readonly string[],
+    opts: Record<string, unknown>,
+  ): Promise<string> => {
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    try {
+      await dispatch(graft, positionals, opts, PLAIN);
+    } finally {
+      spy.mockRestore();
+    }
+    return errs.join("");
+  };
+
+  it("exits NONZERO when the mutation's first read would fail for real", async () => {
+    // The structural false positive: this same call used to print a full plan
+    // and exit 0, while the run without --dry-run died on the missing file.
+    const missing = join(mkdtempSync(join(tmpdir(), "pragma-graft-")), "gone");
+    const out = await dispatchCapturing([missing], { dryRun: true });
+    expect(process.exitCode).toBe(1);
+    expect(out).toContain(missing);
+    expect(existsSync(`${missing}.grafted`)).toBe(false);
+  });
+
+  it("still plans, exits 0, and writes nothing when the read would succeed", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pragma-graft-"));
+    const source = join(dir, "present.txt");
+    writeFileSync(source, "content\n");
+    const outs: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        outs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    try {
+      await dispatch(graft, [source], { dryRun: true }, PLAIN);
+    } finally {
+      spy.mockRestore();
+    }
+    expect(process.exitCode).toBe(0);
+    expect(outs.join("")).toContain(`Write file: ${source}.grafted`);
+    expect(readdirSync(dir)).toEqual(["present.txt"]);
+  });
+});
+
 describe("executeVerb — interactivity gate (H3)", () => {
   const setTTY = (
     stream: NodeJS.ReadStream | NodeJS.WriteStream,

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

@@ -11,8 +11,8 @@
  * exit code.
  */
 
-import { describeEffect, dryRun, type Task } from "@canonical/task";
-import { runTask, runUndo } from "@canonical/task/node";
+import { describeEffect, type Task } from "@canonical/task";
+import { runPreview, runTask, runUndo } from "@canonical/task/node";
 import {
   asPragmaError,
   CANCELLED_MESSAGE,
@@ -221,8 +221,11 @@ export async function executeVerb(
     // Also hand it the interaction context so an interactive verb can pick its
     // prompt strategy. The verb's `run` sets `mutationRuntime.exec` (the runner
     // options) as its last act; the projector reads it back on the real-run
-    // branch only — the dry-run/undo branches stay handler-free (they mock
-    // prompts), so `--dry-run`/`--undo` are unchanged by this seam.
+    // branch AND on the dry-run branch, which takes `cwd` (so the preview reads
+    // the tree the run would write into) and `onEffectStart` (so the stamping
+    // transform runs, and planned byte counts match written ones). It never
+    // takes the prompt handler: a preview auto-answers prompts and so can never
+    // block on input. `--undo` stays handler-free and untouched by this seam.
     const controller = new AbortController();
     const interaction: InteractionRuntime = {
       // Gate on STDERR (H3): the Ink wizard renders to stderr and reads stdin,
@@ -252,14 +255,33 @@ export async function executeVerb(
         | Promise<Task<unknown>>,
     );
     if (mutation.dryRun) {
-      // A plan is the effects a mutation WOULD apply — a `Prompt` is not one, so
-      // the interactive confirm gate / answer prompts never clutter the preview.
-      return renderPlan(
-        flags,
-        dryRun(task)
-          .effects.filter((effect) => effect._tag !== "Prompt")
-          .map(describeEffect),
-      );
+      // The HONEST preview (PR7): reads hit the real filesystem, writes are
+      // recorded and never executed. A mutation whose real run would die on its
+      // first template read now fails HERE too, so `--dry-run` exits nonzero
+      // exactly when the run would — the plan is a prediction, not a wish.
+      // `exec.cwd` is the same write root the real run resolves paths against,
+      // and `exec.onEffectStart` carries summon's stamping transform, so the
+      // planned byte counts are the bytes the run would actually write.
+      const previewExec = mutationRuntime.exec ?? {};
+      try {
+        const { effects } = await runPreview(task, {
+          cwd: previewExec.cwd,
+          onEffectStart: previewExec.onEffectStart,
+          onLog: logToStderr,
+        });
+        // A plan is the effects a mutation WOULD apply — a `Prompt` is not one,
+        // so the interactive confirm gate / answer prompts never clutter it.
+        return renderPlan(
+          flags,
+          effects
+            .filter((effect) => effect._tag !== "Prompt")
+            .map(describeEffect),
+        );
+      } finally {
+        // A verb that mounted an interactive session before returning its Task
+        // must be torn down on this branch too, exactly as on the real run.
+        await previewExec.dispose?.();
+      }
     }
     if (mutation.undo) {
       const { undoCount } = await runUndo(task, { onLog: logToStderr });

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

@@ -17,7 +17,7 @@ const INDENT = "  ";
 /** Two-space gap between a term column and its description. */
 const GAP = "  ";
 
-/** A bold section header (`Flags`, `Verbs`, `Explore the design system`). */
+/** A bold section header (`Flags`, `Verbs`, `Set up & maintain`). */
 export function helpHeading(text: string): string {
   return chalk.bold(text);
 }

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

@@ -1,12 +1,13 @@
 /**
- * Curated root `--help` for `pragma`.
+ * The curated root `--help` page.
  *
- * The front door is hand-curated, not auto-generated: nouns are grouped into
- * task-oriented sections with real one-line summaries, and each section is
- * reconciled against the *live* nouns (from the registered verbs) so a noun
- * that is not built yet is dropped and an uncatalogued one still surfaces under
- * "Other" rather than vanishing. Ported from the v1 root help, retargeted at
- * the grammar and the v2 noun set (no `llm`/`graphql`/`trace`/`tokens`).
+ * The kernel curates the nouns it ships — and only those. It names no domain:
+ * the nouns it does NOT curate lead the page untitled (the header one line up
+ * already carries the distribution's blurb) and describe themselves through
+ * their own verbs, so the front door follows the content instead of naming it.
+ * Every section is reconciled against the *live* nouns (from the registered
+ * verbs), so a noun that is not built yet is dropped and one the kernel has
+ * never heard of still surfaces.
  */
 
 import type { VerbSpec } from "../../spec/types.js";
@@ -24,88 +25,86 @@ interface NounSummary {
 }
 
 interface HelpGroup {
-  readonly title: string;
+  /**
+   * Absent for the leading uncurated group: its rows sit directly under the
+   * usage line, since repeating the header's blurb as a heading three lines
+   * below it says the same thing twice.
+   */
+  readonly title?: string;
   readonly nouns: readonly NounSummary[];
 }
 
 /**
- * Task-oriented grouping with curated summaries. Order is intentional: what
- * people reach for most (exploring, generating) comes first; agent tooling
- * comes last.
+ * The kernel's own nouns, grouped by task with curated summaries. Order is
+ * intentional: what people reach for most comes first; agent tooling comes last.
+ *
+ * @param programName - The CLI binary name (the distribution's `name`).
+ * @returns The task-oriented groups, in display order.
  */
-const HELP_GROUPS: readonly HelpGroup[] = [
-  {
-    title: "Explore the design system",
-    nouns: [
-      {
-        noun: "block",
-        summary: "Inspect components & patterns and their anatomy",
-      },
-      { noun: "token", summary: "Look up design tokens and their values" },
-      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
-      { noun: "standard", summary: "Browse code standards and categories" },
-      {
-        noun: "ontology",
-        summary: "Explore the loaded ontologies (classes, properties)",
-      },
-      { noun: "tier", summary: "List the design-system tiers" },
-    ],
-  },
-  {
-    title: "Generate code",
-    nouns: [
-      { noun: "create", summary: "Scaffold components, packages, and apps" },
-    ],
-  },
-  {
-    title: "Query & serve the graph",
-    nouns: [
-      {
-        noun: "graph",
-        summary: "Run SPARQL queries or inspect a URI directly",
-      },
-    ],
-  },
-  {
-    title: "Set up & maintain",
-    nouns: [
-      { noun: "doctor", summary: "Check environment health" },
-      {
-        noun: "setup",
-        summary: "Configure MCP, skills, completions, and the LSP",
-      },
-      {
-        noun: "sources",
-        summary: "Build and refresh the local store from packages",
-      },
-      { noun: "config", summary: "Read and write pragma configuration" },
-      { noun: "info", summary: "Show version, config, and update status" },
-      {
-        noun: "upgrade",
-        summary: "Upgrade the pragma CLI to the latest version",
-      },
-    ],
-  },
-  {
-    title: "For AI agents",
-    nouns: [
-      {
-        noun: "capabilities",
-        summary: "Discover conventions, tools, and the discovery sequence",
-      },
-      {
-        noun: "colophon",
-        summary: "Read how pragma and the active domain are made",
-      },
-      {
-        noun: "skill",
-        summary: "Browse agent skills from design-system packages",
-      },
-      { noun: "prompt", summary: "Browse reusable prompt templates" },
-      { noun: "mcp", summary: "Start the MCP server over stdio" },
-    ],
-  },
-];
+function buildKernelGroups(programName: string): readonly HelpGroup[] {
+  return [
+    {
+      title: "Generate code",
+      nouns: [
+        { noun: "create", summary: "Scaffold components, packages, and apps" },
+      ],
+    },
+    {
+      title: "Query & serve the graph",
+      nouns: [
+        {
+          noun: "graph",
+          summary: "Run SPARQL queries or inspect a URI directly",
+        },
+        {
+          noun: "ontology",
+          summary: "Explore the loaded ontologies (classes, properties)",
+        },
+      ],
+    },
+    {
+      title: "Set up & maintain",
+      nouns: [
+        { noun: "doctor", summary: "Check environment health" },
+        {
+          noun: "setup",
+          summary: "Configure MCP, skills, completions, and the LSP",
+        },
+        {
+          noun: "sources",
+          summary: "Build and refresh the local store from packs",
+        },
+        {
+          noun: "config",
+          summary: `Read and write ${programName} configuration`,
+        },
+        { noun: "info", summary: "Show version, config, and update status" },
+        {
+          noun: "upgrade",
+          summary: `Upgrade the ${programName} CLI to the latest version`,
+        },
+      ],
+    },
+    {
+      title: "For AI agents",
+      nouns: [
+        {
+          noun: "capabilities",
+          summary: "Discover conventions, tools, and the discovery sequence",
+        },
+        {
+          noun: "colophon",
+          summary: `Read how ${programName} and the active domain are made`,
+        },
+        { noun: "skill", summary: "Browse agent skills from the active packs" },
+        { noun: "prompt", summary: "Browse reusable prompt templates" },
+        // The one noun with no verb to speak for it (the bin special-cases it),
+        // so its summary is hand-written rather than derived.
+        { noun: "mcp", summary: "Start the MCP server over stdio" },
+      ],
+    },
+  ];
+}
 
 /** All distinct, non-hidden top-level nouns present in the registered verbs. */
 function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
@@ -117,16 +116,21 @@ function nounsFrom(verbs: readonly VerbSpec[]): Set<string> {
   return nouns;
 }
 
-/** The summary to show for an uncatalogued but live noun. */
-function fallbackSummary(noun: string, verbs: readonly VerbSpec[]): string {
+/**
+ * Summarise an uncurated noun from its first live verb — which is the pack's own
+ * `description` whenever the pack ships a `list` (`compilePack` compiles that
+ * verb first). The terminal period a pack sentence carries is dropped so the
+ * column reads as one voice with the kernel's own fragments.
+ */
+function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
   const first = verbs.find((v) => v.path[0] === noun && !v.hidden);
-  return first?.summary ?? `${noun} commands`;
+  return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
 }
 
 /**
  * Build the curated root help string.
  *
- * @param programName - The CLI binary name (`pragma`).
+ * @param programName - The CLI binary name (the distribution's `name`).
  * @param description - The program description shown in the header.
  * @param verbs - All registered verbs, used to derive the live noun set.
  * @returns The formatted, colorized help text.
@@ -140,27 +144,23 @@ export function formatRootHelp(
   // `mcp` is served by the bin's special-case, not a projected verb, but is
   // always available — surface it so the front door is complete.
   present.add("mcp");
-  const catalogued = new Set(
-    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
-  );
+  const kernel = buildKernelGroups(programName);
+  const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
 
-  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
   const groups: HelpGroup[] = [
-    ...HELP_GROUPS.map((g) => ({
+    // Everything the kernel's curated table does not claim — in the shipped
+    // binary the bundled domain packs, in a fork whatever it ships. Untitled
+    // and first, so the domain leads the page without the kernel naming it.
+    {
+      nouns: [...present]
+        .filter((n) => !curated.has(n))
+        .sort()
+        .map((noun) => ({ noun, summary: summarizeNoun(noun, verbs) })),
+    },
+    ...kernel.map((g) => ({
       ...g,
       nouns: g.nouns.filter((n) => present.has(n.noun)),
     })),
-    ...(uncatalogued.length > 0
-      ? [
-          {
-            title: "Other",
-            nouns: uncatalogued.map((noun) => ({
-              noun,
-              summary: fallbackSummary(noun, verbs),
-            })),
-          },
-        ]
-      : []),
   ].filter((g) => g.nouns.length > 0);
 
   // One column width across ALL groups so the noun column aligns section to
@@ -180,7 +180,7 @@ export function formatRootHelp(
   ];
 
   for (const group of groups) {
-    lines.push(helpHeading(group.title));
+    if (group.title) lines.push(helpHeading(group.title));
     lines.push(
       ...helpColumns(
         group.nouns.map((n) => [n.noun, n.summary] as const),

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

@@ -1,12 +1,17 @@
 /**
  * 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";

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,8 +16,8 @@
 import {
   buildDiscoverySequence,
   CONVENTIONS,
-  liveTools,
 } from "../../../capabilities/capabilities/catalog.js";
+import { emitSurface } from "../../spec/emitSurface.js";
 import type { CapabilityModule } from "../../spec/types.js";
 
 /** Hard ceiling on the instructions length (asserted by the protected test). */
@@ -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/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,38 @@ 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 });
+    expect((planned.data as { plan: string[] }).plan).toContain(
+      `Write file: ${source}.grafted (8 bytes)`,
+    );
+    expect(readdirSync(dir)).toEqual(["present.txt"]);
+  });
+});