@canonical/pragma-cli 0.34.0 → 0.35.0

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";
 
 /**
@@ -190,7 +192,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 +205,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.

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

@@ -6,9 +6,16 @@ import {
   renderErrorLlm,
   renderErrorPlain,
 } from "../error/renderError.js";
-import type { ColumnDef, LookupField, SectionDef } from "./contracts.js";
+import type {
+  ColumnDef,
+  LookupField,
+  RenderContext,
+  SectionDef,
+} from "./contracts.js";
 import { resolveDetail } from "./disclosure.js";
 import {
+  MAX_PLAIN_CELL_WIDTH,
+  renderListEmptyNotice,
   renderListLlm,
   renderListPlain,
   renderLookupLlm,
@@ -16,6 +23,11 @@ import {
 } from "./renderers.js";
 import { type RenderStyle, styleFor } from "./style.js";
 
+/** An interactive stdout with headers on — the default terminal shape. */
+const TTY_CONTEXT: RenderContext = { headers: true, stdoutIsTty: true };
+/** A piped stdout with headers on — the field-splitting consumer shape. */
+const PIPE_CONTEXT: RenderContext = { headers: true, stdoutIsTty: false };
+
 interface Widget {
   readonly uri: string;
   readonly name: string;
@@ -111,18 +123,21 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
     expect(matrix).toMatchSnapshot();
   });
 
-  it("renders an empty-state message (+ hint) when items are empty", () => {
+  it("separates the empty notice (stderr's text) from the stdout rendering", () => {
     const options = {
       heading: "Widgets",
       columns: columnsFor("summary"),
       emptyMessage: "No widget entries found.",
       emptyHint: "Run `pragma sources update`.",
     };
-    // Plain: message then hint on the next line — a non-blank exit-0 body.
-    expect(renderListPlain([], options)).toBe(
+    // The notice is its own render — the dispatcher routes it to stderr so a
+    // pipe never receives a human sentence as data.
+    expect(renderListEmptyNotice(options)).toBe(
       "No widget entries found.\nRun `pragma sources update`.",
     );
-    // Llm: the `(0)` heading, then the same message + hint.
+    // Plain stdout for an empty list on a TTY: nothing (the notice suffices).
+    expect(renderListPlain([], options, TTY_CONTEXT)).toBe("");
+    // Llm keeps its byte-frozen shape: the `(0)` heading, then message + hint.
     expect(renderListLlm([], options)).toBe(
       "## Widgets (0)\n\nNo widget entries found.\nRun `pragma sources update`.",
     );
@@ -130,7 +145,8 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
 
   it("keeps the bare-empty behavior when no emptyMessage is declared", () => {
     const options = { heading: "Widgets", columns: columnsFor("summary") };
-    expect(renderListPlain([], options)).toBe("");
+    expect(renderListEmptyNotice(options)).toBe("");
+    expect(renderListPlain([], options, TTY_CONTEXT)).toBe("");
     expect(renderListLlm([], options)).toBe("## Widgets (0)\n");
   });
 
@@ -145,6 +161,101 @@ describe("render matrix (list/lookup/empty × plain/llm/json × detail)", () =>
   });
 });
 
+describe("plain list table contract (headers, rectangular grid, cell discipline)", () => {
+  const columns: ColumnDef<Widget>[] = [
+    { key: "name", label: "Name" },
+    { key: "kind", label: "Kind" },
+    { key: "note", label: "Note" },
+  ];
+  const options = { heading: "Widgets", columns };
+
+  it("emits a bold-eligible UPPERCASE header row built from the column labels", () => {
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND\s+NOTE$/);
+    expect(lines).toHaveLength(1 + widgets.length);
+  });
+
+  it("suppresses the header row when the context disables headers", () => {
+    const lines = renderListPlain(widgets, options, {
+      headers: false,
+      stdoutIsTty: true,
+    }).split("\n");
+    expect(lines[0]).not.toMatch(/^NAME/);
+    expect(lines).toHaveLength(widgets.length);
+  });
+
+  it("keeps the grid rectangular — an empty cell renders as -", () => {
+    // Card's note is "": the NOTE column is populated on another row, so the
+    // grid keeps the column and marks the hole instead of shifting fields.
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT).split("\n");
+    const cardRow = lines.find((line) => line.startsWith("Card"));
+    expect(cardRow?.trim().split(/\s{2,}/)).toEqual(["Card", "pattern", "-"]);
+  });
+
+  it("drops a column no row populates (unless it opts into showWhenEmpty)", () => {
+    const noteless = widgets.map((w) => ({ ...w, note: "" }));
+    const lines = renderListPlain(noteless, options, TTY_CONTEXT).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND$/);
+  });
+
+  it("collapses newlines and truncates a long cell with an ellipsis", () => {
+    const prose = [
+      {
+        ...widgets[0],
+        note: `first line\nsecond line ${"x".repeat(2 * MAX_PLAIN_CELL_WIDTH)}`,
+      },
+    ] as Widget[];
+    const lines = renderListPlain(prose, options, TTY_CONTEXT).split("\n");
+    const row = lines[1] as string;
+    expect(row).not.toContain("\n");
+    expect(row).toContain("first line second line");
+    const noteCell = row
+      .trim()
+      .split(/\s{2,}/)
+      .at(-1) as string;
+    expect(noteCell.length).toBeLessThanOrEqual(MAX_PLAIN_CELL_WIDTH);
+    expect(noteCell.endsWith("…")).toBe(true);
+  });
+
+  it("renders only the header row for an empty list on a piped stdout", () => {
+    // An explicit `--format plain` down a pipe gets a well-formed zero-record
+    // table: every declared column, no rows — so `awk` sees a schema.
+    expect(renderListPlain([], options, PIPE_CONTEXT)).toMatch(
+      /^NAME\s+KIND\s+NOTE$/,
+    );
+    // With headers off there is nothing to print at all.
+    expect(
+      renderListPlain([], options, { headers: false, stdoutIsTty: false }),
+    ).toBe("");
+  });
+
+  it("bolds the header row on a color-capable TTY, leaving cells unstyled", () => {
+    const tagged: RenderStyle = {
+      enabled: true,
+      bold: (t) => `B(${t})`,
+      dim: (t) => t,
+      cyan: (t) => t,
+      green: (t) => t,
+      yellow: (t) => t,
+    };
+    const lines = renderListPlain(widgets, options, TTY_CONTEXT, tagged).split(
+      "\n",
+    );
+    expect(lines[0]).toMatch(/^B\(NAME\s+KIND\s+NOTE\)$/);
+    expect(lines[1]).not.toContain("B(");
+  });
+
+  it("is byte-identical plain text when the styler is disabled", () => {
+    const lines = renderListPlain(
+      widgets,
+      options,
+      TTY_CONTEXT,
+      styleFor(false),
+    ).split("\n");
+    expect(lines[0]).toMatch(/^NAME\s+KIND\s+NOTE$/);
+  });
+});
+
 describe("lookup beautify (TTY style seam)", () => {
   const lookupOpts = {
     title: (w: Widget) => w.name,
@@ -203,3 +314,129 @@ describe("error render matrix (× plain/llm/json)", () => {
     }).toMatchSnapshot();
   });
 });
+
+describe("section-body headings nest under the heading the renderer gives them", () => {
+  interface Doc {
+    readonly guidelines: string;
+  }
+
+  const render = (guidelines: string): string =>
+    renderLookupLlm<Doc>(
+      { guidelines },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+
+  it("demotes authored headings that collide with the section heading", () => {
+    const out = render(
+      "### Accessibility\n\n- Label the button.\n\n### Content\n\n- Verb first.",
+    );
+    expect(out).toContain("### Guidelines");
+    expect(out).toContain("#### Accessibility");
+    expect(out).toContain("#### Content");
+    expect(out).not.toMatch(/^### Accessibility$/m);
+  });
+
+  it("preserves the content's own hierarchy while shifting it as a block", () => {
+    const out = render("## Overview\n\ntext\n\n### Detail\n\nmore");
+    expect(out).toContain("#### Overview");
+    expect(out).toContain("##### Detail");
+  });
+
+  it("leaves content already nested below the section alone", () => {
+    const out = render("#### Already nested\n\ntext");
+    expect(out).toContain("#### Already nested");
+    expect(out).not.toContain("##### Already nested");
+  });
+
+  it("never emits a heading deeper than markdown's floor", () => {
+    const out = render("###### Deep\n\ntext");
+    expect(out).toContain("###### Deep");
+  });
+
+  it("leaves `#` inside a fenced code block exactly as authored", () => {
+    const out = render("### Setup\n\n```sh\n# not a heading\nbun install\n```");
+    expect(out).toContain("#### Setup");
+    expect(out).toContain("# not a heading");
+    expect(out).not.toContain("## not a heading");
+  });
+
+  it("leaves a body with no headings untouched", () => {
+    const out = render("Plain prose with a # hash mid-line.");
+    expect(out).toContain("Plain prose with a # hash mid-line.");
+  });
+
+  it("does not rewrite the plain body, where `###` is literal text", () => {
+    const out = renderLookupPlain<Doc>(
+      { guidelines: "### Accessibility" },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+    expect(out).toContain("Guidelines:");
+    expect(out).toContain("  ### Accessibility");
+  });
+});
+
+describe("section-body nesting follows CommonMark, not a near-enough reading", () => {
+  interface Doc {
+    readonly guidelines: string;
+  }
+
+  const render = (guidelines: string): string =>
+    renderLookupLlm<Doc>(
+      { guidelines },
+      {
+        title: () => "Button",
+        fields: [],
+        sections: [{ key: "guidelines", heading: "Guidelines", kind: "field" }],
+      },
+    );
+
+  it("nests a heading indented up to three spaces, keeping its indent", () => {
+    // Four spaces would make the line an indented code block; three or fewer
+    // leave it a heading. Missing that left an indented heading at the
+    // section's own level while its unindented twin was demoted — one body
+    // rendered with two conflicting hierarchies.
+    expect(render("  ### Accessibility\n\ntext")).toMatch(
+      /^ {2}#### Accessibility$/m,
+    );
+  });
+
+  it("does not close a four-backtick fence on a three-backtick sample", () => {
+    // A closing fence must be AT LEAST as long as the opener. Toggling on any
+    // same-character run let the inner sample read as the close, after which
+    // every `#` line in that code block was rewritten — the renderer silently
+    // editing the user's sample code.
+    const out = render(
+      [
+        "````md",
+        "```",
+        "### Sample text, not a heading",
+        "```",
+        "````",
+        "",
+        "### A real heading",
+      ].join("\n"),
+    );
+    // Anchored: `#### x` CONTAINS `### x`, so a substring check would pass
+    // against the very rewrite this pins against.
+    expect(out).toMatch(/^### Sample text, not a heading$/m);
+    expect(out).toMatch(/^#### A real heading$/m);
+  });
+
+  it("does not close a fence on a run that carries an info string", () => {
+    // An opener may carry an info string; a CLOSER may not. A ```js line
+    // inside a block opens nothing and closes nothing.
+    const out = render(
+      ["```", "### inside", "```js", "### also inside", "```"].join("\n"),
+    );
+    expect(out).toMatch(/^### inside$/m);
+    expect(out).toMatch(/^### also inside$/m);
+  });
+});