@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -61,6 +61,50 @@ describe("buildProgram — flags", () => {
   });
 });
 
+describe("buildProgram — default-true boolean negation (B9)", () => {
+  const negatableVerb: VerbSpec = {
+    path: ["thing", "do"],
+    summary: "thing do summary",
+    params: [
+      { kind: "boolean", name: "ssr", doc: "Include SSR.", default: true },
+      {
+        kind: "boolean",
+        name: "runInstall",
+        doc: "Install now.",
+        default: false,
+      },
+      { kind: "boolean", name: "withHistory", doc: "Seed history." },
+    ],
+    output: {
+      formatters: {
+        plain: (d) => String(d),
+        llm: (d) => String(d),
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async () => null,
+  };
+  const program = projectCli([{ name: "thing", verbs: [negatableVerb] }]);
+  const doCmd = program.commands
+    .find((c) => c.name() === "thing")
+    ?.commands.find((c) => c.name() === "do");
+
+  it("pairs a `--no-` negation onto a default-true boolean so it is disableable", () => {
+    const longs = doCmd?.options.map((o) => o.long) ?? [];
+    expect(longs).toContain("--ssr");
+    expect(longs).toContain("--no-ssr");
+  });
+
+  it("leaves default-false / defaultless booleans un-negated (no Commander default-flip)", () => {
+    const longs = doCmd?.options.map((o) => o.long) ?? [];
+    expect(longs).toContain("--run-install");
+    expect(longs).not.toContain("--no-run-install");
+    expect(longs).toContain("--with-history");
+    expect(longs).not.toContain("--no-with-history");
+  });
+});
+
 describe("buildProgram — early exits", () => {
   it("throws commander.version for --version, writing the version", async () => {
     const program = projectCli([fixtureModule]);
@@ -334,9 +378,15 @@ describe("formatRootHelp — grouping", () => {
     makeVerb(["block", "list"]),
   ]);
 
-  it("shows the task-oriented section titles for live nouns", () => {
-    expect(help).toContain("Explore the design system");
+  it("leads with the uncurated nouns, untitled, under the usage line", () => {
+    // `block` is not in the kernel's curated table, so it leads the page with
+    // no heading of its own — the header already carries the blurb, and the
+    // kernel has no name for the domain. The kernel's own nouns keep their
+    // task-oriented sections.
+    expect(help).toMatch(/^Usage: pragma .*\n\n {2}block\b/m);
     expect(help).toContain("Set up & maintain");
+    // The blurb appears exactly once: in the header.
+    expect(help.match(/pragma test/g)).toHaveLength(1);
   });
 
   it("lists the live nouns and always-available mcp", () => {
@@ -353,7 +403,8 @@ describe("formatRootHelp — grouping", () => {
 
   it("shows the global flags block", () => {
     expect(help).toContain("Global flags");
-    expect(help).toContain("--llm");
+    expect(help).not.toContain("--llm");
+    expect(help).toContain("--format <plain|llm|json>");
     expect(help).toContain("--detail <level>");
   });
 
@@ -363,8 +414,7 @@ describe("formatRootHelp — grouping", () => {
 
       Usage: pragma <command> [subcommand] [flags]
 
-      Explore the design system
-        block   Inspect components & patterns and their anatomy
+        block   block list summary
 
       Set up & maintain
         config  Read and write pragma configuration
@@ -374,12 +424,11 @@ describe("formatRootHelp — grouping", () => {
         mcp     Start the MCP server over stdio
 
       Global flags
-        --llm                  Condensed Markdown output for agents
-        --format <json|plain>  Select output format
-        --detail <level>       Progressive-disclosure level (summary, standard, detailed)
-        --verbose              Diagnostic output on stderr
-        --help                 Show help (works on any command)
-        --version              Show the CLI version
+        --format <plain|llm|json>  Select output format (llm = condensed Markdown for agents)
+        --detail <level>           Progressive-disclosure level (summary, standard, detailed)
+        --verbose                  Diagnostic output on stderr
+        --help                     Show help (works on any command)
+        --version                  Show the CLI version
 
       Run \`pragma <command> --help\` for details, or \`pragma capabilities\` to get oriented."
     `);

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

@@ -70,6 +70,17 @@ function registerParams(command: Command, verb: VerbSpec): void {
     } else {
       command.option(spec, param.doc);
     }
+    // B9: a default-`true` boolean is otherwise undisableable — the grammar has
+    // no negation form, so `create`'s sibling booleans (--ssr/--with-styles/…)
+    // could never be turned off. Register a paired `--no-<flag>` so they can:
+    // Commander keeps the `true` default and lets `--no-<flag>` set it false
+    // (verified: an unset default-false boolean is left alone). This is a CLI
+    // PARSE convenience, never a ParamSpec — `emitSurface`/MCP/the covenant are
+    // untouched — so the frozen flag list stands and negation stays additive.
+    if (param.kind === "boolean" && param.default === true) {
+      const flag = kebabCase(param.name);
+      command.option(`--no-${flag}`, `Disable --${flag} (on by default).`);
+    }
   }
 
   if (verb.capability.mutates) {

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/globalFlags.test.ts

@@ -9,10 +9,18 @@ const TTY = { isTty: true, noAutoLlm: false };
 const PIPE = { isTty: false, noAutoLlm: false };
 
 describe("parseGlobalFlags", () => {
-  it("honours an explicit --llm", () => {
-    expect(parseGlobalFlags(["--llm"], TTY)).toMatchObject({
+  it("honours an explicit --format llm (condensed even on a TTY)", () => {
+    expect(parseGlobalFlags(["--format", "llm"], TTY)).toMatchObject({
       llm: true,
       autoLlm: false,
+      format: "llm",
+    });
+  });
+
+  it("forces human output with --format plain down a pipe", () => {
+    expect(parseGlobalFlags(["--format", "plain"], PIPE)).toMatchObject({
+      llm: false,
+      autoLlm: false,
       format: "plain",
     });
   });
@@ -69,7 +77,7 @@ describe("stripGlobalFlags", () => {
       "list",
     ]);
     expect(
-      stripGlobalFlags(["block", "--llm", "list", "--detail", "detailed"]),
+      stripGlobalFlags(["block", "--verbose", "list", "--detail", "detailed"]),
     ).toEqual(["block", "list"]);
     expect(stripGlobalFlags(["--format=json", "config", "show"])).toEqual([
       "config",
@@ -90,7 +98,7 @@ describe("readRawFormat", () => {
 
   it("reports a valueless --format as empty string", () => {
     expect(readRawFormat(["--format"])).toBe("");
-    expect(readRawFormat(["--format", "--llm"])).toBe("");
+    expect(readRawFormat(["--format", "--verbose"])).toBe("");
   });
 
   it("returns undefined when --format is absent", () => {

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

@@ -1,13 +1,14 @@
 /**
  * Global-flag pre-parsing, ahead of Commander.
  *
- * `--llm`, `--format`, `--verbose`, and `--detail` may appear anywhere on the
- * line, so they are scanned and stripped before Commander sees argv — otherwise
+ * `--format`, `--verbose`, and `--detail` may appear anywhere on the line, so
+ * they are scanned and stripped before Commander sees argv — otherwise
  * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
  * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
  * flag and the `--format text` value renamed to `plain` (the kernel's
- * {@link OutputFormat}). Both the space (`--format json`) and equals
- * (`--format=json`) forms are recognized.
+ * {@link OutputFormat}). The dedicated `--llm` flag was folded into
+ * `--format llm`, leaving auto-detection as the sole implicit trigger. Both the
+ * space (`--format json`) and equals (`--format=json`) forms are recognized.
  */
 
 import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
@@ -86,10 +87,11 @@ function readDetail(argv: readonly string[]): DetailLevel | undefined {
 /**
  * Extract the global flags from raw argv (the user's arguments, argv[2:]).
  *
- * Auto-LLM: with no `--llm`/`--format` and a non-interactive stdout (piped or
+ * Auto-LLM: with no explicit `--format` and a non-interactive stdout (piped or
  * redirected — the shape an agent captures), `llm` defaults to true so agents
- * get condensed Markdown without a flag. `--llm`, `--format`, and
- * `PRAGMA_NO_AUTO_LLM` all override it.
+ * get condensed Markdown without a flag. Any explicit `--format` overrides it —
+ * `--format plain` forces human output down a pipe, `--format llm` forces the
+ * condensed form even on a TTY — as does `PRAGMA_NO_AUTO_LLM`.
  *
  * @param argv - The user's arguments (no `node`/script prefix).
  * @param env - Output environment probe (defaults to the real process).
@@ -100,15 +102,14 @@ export function parseGlobalFlags(
   argv: readonly string[],
   env: OutputEnvironment = readOutputEnvironment(),
 ): GlobalFlags {
-  const explicitLlm = argv.includes("--llm");
   const rawFormat = readFlagValue(argv, "--format");
-  const format = rawFormat === "json" ? "json" : "plain";
+  const format =
+    rawFormat === "json" ? "json" : rawFormat === "llm" ? "llm" : "plain";
   const formatRequested = rawFormat !== undefined;
-  const autoLlm =
-    !explicitLlm && !formatRequested && !env.isTty && !env.noAutoLlm;
+  const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
   const detail = readDetail(argv);
   return {
-    llm: explicitLlm || autoLlm,
+    llm: format === "llm" || autoLlm,
     autoLlm,
     format,
     verbose: argv.includes("--verbose"),
@@ -130,10 +131,9 @@ export function stripGlobalFlags(argv: readonly string[]): string[] {
   const result: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === "--llm" || arg === "--verbose") continue;
+    if (arg === "--verbose") continue;
     if (
       arg?.startsWith("--format=") ||
-      arg?.startsWith("--llm=") ||
       arg?.startsWith("--verbose=") ||
       arg?.startsWith("--detail=")
     ) {

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);
 }