@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -11,7 +11,7 @@
  * exit code.
  */
 
-import { describeEffect, type Task } from "@canonical/task";
+import { describeEffect, type Effect, type Task } from "@canonical/task";
 import { runPreview, runTask, runUndo } from "@canonical/task/node";
 import {
   asPragmaError,
@@ -19,22 +19,21 @@ import {
   isCancellation,
   isInterruption,
 } from "../../error/fromTaskError.js";
-import { PragmaError } from "../../error/PragmaError.js";
 import {
+  PragmaError,
   renderErrorJson,
   renderErrorLlm,
   renderErrorPlain,
-} from "../../error/renderError.js";
-import { successEnvelope } from "../../render/envelope.js";
-import { selectFormatter } from "../../render/formatters.js";
-import { writeStdout } from "../../render/writeStdout.js";
-import { bootRuntime } from "../../runtime/boot.js";
+} from "../../error/index.js";
+import type { RenderContext } from "../../render/contracts.js";
+import { successEnvelope, writeStdout } from "../../render/index.js";
+import { bootRuntime } from "../../runtime/index.js";
 import type {
   GlobalFlags,
   InteractionRuntime,
   PragmaRuntime,
 } from "../../runtime/types.js";
-import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/index.js";
 import { EXIT, mapExitCode } from "./exitCodes.js";
 
 /** The CLI-only mutation flags auto-injected onto every mutating verb. */
@@ -44,6 +43,18 @@ export interface MutationFlags {
   readonly yes: boolean;
 }
 
+/**
+ * THE CLI interactivity gate (H3): stdin AND stderr are TTYs. The Ink wizard
+ * renders to stderr and reads stdin, so `<verb> 2>/dev/null` must be
+ * non-interactive — gating on stdout would mount an invisible render that
+ * blocks on stdin. One exported fact: the kernel's interaction context and a
+ * mounted subtree's own decision both read it here, so the two callers can
+ * never disagree about what "a TTY" means.
+ */
+export function cliIsTTY(): boolean {
+  return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
+
 /**
  * Route a Task's log effects to stderr. The interpreter otherwise falls back to
  * `console.log` (stdout), which would corrupt the `--format json` / MCP stdio
@@ -53,6 +64,18 @@ const logToStderr = (_level: string, message: string): void => {
   process.stderr.write(`${message}\n`);
 };
 
+/** A silenced log sink — `--quiet` drops progress; errors render elsewhere. */
+const logNowhere = (_level: string, _message: string): void => {};
+
+/**
+ * The interpreter log sink for this invocation: stderr, or — under `--quiet`
+ * — nothing. Progress/stage lines are success-path output; error rendering
+ * never routes through this sink, so muting it cannot hide a failure.
+ */
+function logSink(flags: GlobalFlags): (level: string, message: string) => void {
+  return flags.quiet === true ? logNowhere : logToStderr;
+}
+
 /** The result of running a verb: what to write where, and the exit code. */
 export interface DispatchOutcome {
   readonly stdout?: string;
@@ -62,6 +85,15 @@ export interface DispatchOutcome {
 
 /** Coerce one raw arg into the type its {@link ParamSpec} declares. */
 function coerceParam(param: ParamSpec, raw: unknown): unknown {
+  // A repeatable flag's collector hands over an array of occurrences; coerce
+  // each element so an enum still validates every value.
+  if (
+    Array.isArray(raw) &&
+    (param.kind === "string" || param.kind === "enum") &&
+    param.repeatable === true
+  ) {
+    return raw.map((value) => coerceParam(param, value));
+  }
   switch (param.kind) {
     case "number": {
       const value = typeof raw === "number" ? raw : Number(raw);
@@ -128,7 +160,19 @@ export function extractParams(
   return result;
 }
 
-/** Render a read/execute result through the verb's formatters. */
+/**
+ * Render a read/execute result through the verb's formatters.
+ *
+ * The plain branch owns two ROUTING decisions (the rendering itself stays in
+ * the formatters): it threads the presentation context (`--no-headers`,
+ * stdout's TTY-ness) into the plain formatter, and it routes a declared
+ * empty-state notice to STDERR with exit 0 — a zero-record result is a calm
+ * success, and stdout (the data stream) must not carry a human sentence a
+ * pipe would read as a record. `llm` and `json` keep their own empty shapes
+ * on stdout: both are machine contracts whose consumers read one stream.
+ *
+ * @note Impure — reads `process.stdout.isTTY` for the render context.
+ */
 function renderData(
   verb: VerbSpec,
   flags: GlobalFlags,
@@ -142,21 +186,81 @@ function renderData(
       exitCode: 0,
     };
   }
-  const text = selectFormatter(flags, verb.output.formatters)(data);
-  return { stdout: text ? `${text}\n` : "", exitCode: 0 };
+  if (flags.llm) {
+    const text = verb.output.formatters.llm(data);
+    return { stdout: text ? `${text}\n` : "", exitCode: 0 };
+  }
+  const context: RenderContext = {
+    headers: flags.noHeaders !== true,
+    stdoutIsTty: process.stdout.isTTY === true,
+  };
+  const text = verb.output.formatters.plain(data, context);
+  // The calm zero-record notice is success-path guidance — `--quiet` mutes it.
+  const notice =
+    flags.quiet === true
+      ? undefined
+      : verb.output.formatters.emptyNotice?.(data);
+  return {
+    stdout: text ? `${text}\n` : "",
+    ...(notice ? { stderr: `${notice}\n` } : {}),
+    exitCode: 0,
+  };
 }
 
-/** Render a dry-run plan (the effects a mutation would perform). */
-function renderPlan(
+/**
+ * Render a dry-run plan.
+ *
+ * The default render is the effect dump — one described effect per line — which
+ * is what every verb without a plan of its own gets, byte for byte as before.
+ * A verb that declares `output.formatPlan` renders that instead: the dump is
+ * debug material (interpreter log effects, a repeated absolute path prefix on
+ * every line), and a preview is something a user is meant to read.
+ *
+ * The JSON envelope is decided by the STASHED DATA, not by the seam: `plan` is
+ * the same string array it always was, and `targets` appears only for a verb
+ * that stashed a structured plan beside it. So a verb whose renderer works off
+ * the effects alone leaves the machine-readable shape exactly as it found it.
+ *
+ * @param flags - The global flags (format selection, verbosity).
+ * @param plan - The described effects the mutation would perform.
+ * @param effects - Those same effects, unformatted, for the verb's renderer.
+ * @param seam - The verb's plan renderer + whatever it stashed, when it has one.
+ * @returns The dispatch outcome.
+ */
+async function renderPlan(
   flags: GlobalFlags,
   plan: readonly string[],
-): DispatchOutcome {
+  effects: readonly Effect[],
+  seam?: {
+    format: (
+      planData: unknown,
+      effects: readonly Effect[],
+      verbose: boolean,
+    ) => string | Promise<string>;
+    planData: unknown;
+  },
+): Promise<DispatchOutcome> {
   if (flags.format === "json") {
+    const body =
+      seam?.planData === undefined
+        ? { plan }
+        : { plan, targets: seam.planData };
     return {
-      stdout: `${JSON.stringify(successEnvelope({ plan }, { dryRun: true }))}\n`,
+      stdout: `${JSON.stringify(successEnvelope(body, { dryRun: true }))}\n`,
       exitCode: 0,
     };
   }
+  if (seam !== undefined) {
+    // Awaited: the seam MAY be async, so a renderer can load formatting rules
+    // that live in another package behind a dynamic `import()` instead of
+    // charging every `--help` spawn for them (see `VerbSpec.output.formatPlan`).
+    const rendered = await seam.format(
+      seam.planData,
+      effects,
+      flags.verbose === true,
+    );
+    return { stdout: `${rendered}\n`, exitCode: 0 };
+  }
   const body =
     plan.length > 0
       ? `Dry run — planned effects:\n${plan.map((p) => `  - ${p}`).join("\n")}`
@@ -228,10 +332,8 @@ export async function executeVerb(
     // 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,
-      // so `<verb> 2>/dev/null` must be non-interactive — gating on stdout would
-      // mount an invisible render that blocks on stdin.
-      isTTY: process.stdin.isTTY === true && process.stderr.isTTY === true,
+      // The shared H3 gate (see cliIsTTY): stderr, never stdout.
+      isTTY: cliIsTTY(),
       transport: "cli",
       yes: mutation.yes,
       signal: controller.signal,
@@ -242,12 +344,15 @@ export async function executeVerb(
     };
     const mutationRuntime: PragmaRuntime = {
       ...runtime,
-      mutation: { preview: mutation.dryRun },
+      mutation: { preview: mutation.dryRun, undo: mutation.undo },
       interaction,
       // Progress seam (U7): a long mutation's eager resolve/build runs before its
       // Task is returned, so `onLog` can't reach it — stream stage lines straight
       // to stderr instead, keeping stdout (the JSON/data stream) clean.
-      report: (message: string) => process.stderr.write(`${message}\n`),
+      report:
+        flags.quiet === true
+          ? () => {}
+          : (message: string) => process.stderr.write(`${message}\n`),
     };
     const task = await Promise.resolve(
       verb.run(params, mutationRuntime) as
@@ -262,20 +367,46 @@ export async function executeVerb(
       // `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.
+      //
+      // NO `onLog`, deliberately. A preview that PERFORMS an effect is not a
+      // preview of that effect: routing the recorded `Log`s to stderr printed
+      // the generator's whole commentary on the way through, and the plan then
+      // listed the very same lines as rows. The interpreter prints nothing of
+      // its own when `onLog` is absent, so a log is now planned once and
+      // performed never.
       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(
+        const planned = effects.filter((effect) => effect._tag !== "Prompt");
+        // The DESCRIBED plan — what `--format json` carries and what a verb
+        // with no renderer of its own is dumped as — passes the same
+        // visibility filter the MCP payload and the human preview use. It is
+        // the filter, not the row format, that this seam shares: `plan` is
+        // structured description, so it stays `describeEffect` strings rather
+        // than terminal rows, and the two surfaces can be compared string for
+        // string (`testing/behavioral/parity.test.ts`, A6).
+        //
+        // Loaded lazily from the LIGHT `/format` subpath. A dry run is already
+        // several filesystem reads deep here; a `--help` spawn never reaches
+        // this branch, and the kernel keeps summon-core off its static graph.
+        const { visiblePlanEffects } = await import(
+          "@canonical/summon-core/format"
+        );
+        const format = verb.output.formatPlan;
+        return await renderPlan(
           flags,
-          effects
-            .filter((effect) => effect._tag !== "Prompt")
-            .map(describeEffect),
+          visiblePlanEffects(planned, flags.verbose === true).map(
+            describeEffect,
+          ),
+          planned,
+          format === undefined
+            ? undefined
+            : { format, planData: mutationRuntime.planData },
         );
       } finally {
         // A verb that mounted an interactive session before returning its Task
@@ -284,7 +415,7 @@ export async function executeVerb(
       }
     }
     if (mutation.undo) {
-      const { undoCount } = await runUndo(task, { onLog: logToStderr });
+      const { undoCount } = await runUndo(task, { onLog: logSink(flags) });
       return renderUndo(flags, undoCount);
     }
     // Real execution: spread the verb's runner options into the node
@@ -294,7 +425,7 @@ export async function executeVerb(
     const onSigint = (): void => controller.abort();
     process.once("SIGINT", onSigint);
     try {
-      const value = await runTask(task, { onLog: logToStderr, ...exec });
+      const value = await runTask(task, { onLog: logSink(flags), ...exec });
       return renderData(verb, flags, value, {});
     } finally {
       process.removeListener("SIGINT", onSigint);
@@ -309,30 +440,29 @@ export async function executeVerb(
 }
 
 /**
- * Dispatch a matched verb: coerce, run, and perform the output I/O.
+ * Run a verb whose params are already prepared, then perform the output I/O —
+ * the shared tail of {@link dispatch} and of a mounted subtree's own
+ * dispatcher, which extracts its params by its own rules but reuses every
+ * piece of the kernel machinery from here down: dry-run/undo/real-run
+ * interpretation, error rendering, exit codes, SIGINT.
  *
- * @param verb - The matched verb spec.
- * @param positionals - Positional args from Commander.
- * @param opts - Commander's parsed option values (incl. mutation flags).
+ * @param verb - The verb spec to run.
+ * @param getParams - Produces the coerced param bag (may throw a usage error;
+ *   it is rendered exactly like a run error).
+ * @param mutation - The mutation flags.
  * @param globalFlags - The parsed global flags.
  * @note Impure — writes stdout/stderr and sets `process.exitCode`.
  */
-export async function dispatch(
+async function runPrepared(
   verb: VerbSpec,
-  positionals: readonly string[],
-  opts: Record<string, unknown>,
+  getParams: () => Record<string, unknown>,
+  mutation: MutationFlags,
   globalFlags: GlobalFlags,
 ): Promise<void> {
   const runtime = bootRuntime(globalFlags);
   let outcome: DispatchOutcome;
   try {
-    const params = extractParams(verb.params, positionals, opts);
-    const mutation: MutationFlags = {
-      dryRun: opts.dryRun === true,
-      undo: opts.undo === true,
-      yes: opts.yes === true,
-    };
-    outcome = await executeVerb(verb, params, mutation, runtime);
+    outcome = await executeVerb(verb, getParams(), mutation, runtime);
   } catch (error) {
     // Two clean, non-bug outcomes print the same "Cancelled." line but exit
     // differently — both set DIRECTLY here, out-of-band from `mapExitCode`'s
@@ -354,3 +484,53 @@ export async function dispatch(
   if (outcome.stderr) process.stderr.write(outcome.stderr);
   if (outcome.exitCode !== 0) process.exitCode = outcome.exitCode;
 }
+
+/**
+ * Dispatch a matched verb: coerce, run, and perform the output I/O.
+ *
+ * @param verb - The matched verb spec.
+ * @param positionals - Positional args from Commander.
+ * @param opts - Commander's parsed option values (incl. mutation flags).
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatch(
+  verb: VerbSpec,
+  positionals: readonly string[],
+  opts: Record<string, unknown>,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  const mutation: MutationFlags = {
+    dryRun: opts.dryRun === true,
+    undo: opts.undo === true,
+    yes: opts.yes === true,
+  };
+  await runPrepared(
+    verb,
+    () => extractParams(verb.params, positionals, opts),
+    mutation,
+    globalFlags,
+  );
+}
+
+/**
+ * Dispatch a verb whose params were ALREADY extracted by the caller — the
+ * seam a mounted subtree drives: its leaf specs carry no Commander defaults
+ * (explicit stays distinguishable from default), so the mount extracts the
+ * explicit answers itself and hands them here, reusing the whole kernel tail
+ * (interpreters, rendering, exit codes, SIGINT) byte-for-byte.
+ *
+ * @param verb - The (possibly synthesized) verb spec to run.
+ * @param params - The prepared param bag.
+ * @param mutation - The mutation flags.
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatchPrepared(
+  verb: VerbSpec,
+  params: Record<string, unknown>,
+  mutation: MutationFlags,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  await runPrepared(verb, () => params, mutation, globalFlags);
+}

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

@@ -18,7 +18,7 @@
  *     is NOT produced by `mapExitCode`.
  */
 
-import type { ErrorCode } from "../../error/types.js";
+import type { ErrorCode } from "../../error/index.js";
 
 /**
  * The process exit codes. The first four are the covenant's frozen

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

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 import {
+  findValuedVerbose,
   parseGlobalFlags,
+  readRawDetail,
   readRawFormat,
   stripGlobalFlags,
 } from "./globalFlags.js";
@@ -30,7 +32,7 @@ describe("parseGlobalFlags", () => {
     expect(parseGlobalFlags(["--format=json"], TTY).format).toBe("json");
   });
 
-  it("renames --format text to plain", () => {
+  it("maps an unrecognized --format value to plain (the bin rejects it first)", () => {
     expect(parseGlobalFlags(["--format", "text"], PIPE).format).toBe("plain");
   });
 
@@ -68,6 +70,55 @@ describe("parseGlobalFlags", () => {
   it("reads --verbose", () => {
     expect(parseGlobalFlags(["--verbose"], TTY).verbose).toBe(true);
   });
+
+  it("reports the raw --detail value for validation, including valueless", () => {
+    expect(readRawDetail(["--detail", "detailed"])).toBe("detailed");
+    expect(readRawDetail(["--detail=bogus"])).toBe("bogus");
+    // "" so a valueless flag is rejected, never silently defaulted.
+    expect(readRawDetail(["--detail", "--category"])).toBe("");
+    expect(readRawDetail(["block", "list"])).toBeUndefined();
+    // Past the terminator it is data, not a flag of this program.
+    expect(readRawDetail(["lookup", "--", "--detail=x"])).toBeUndefined();
+  });
+
+  it("finds a valued --verbose token so the bin can reject it", () => {
+    expect(findValuedVerbose(["--verbose=true"])).toBe("--verbose=true");
+    expect(findValuedVerbose(["--verbose"])).toBeUndefined();
+    expect(findValuedVerbose(["lookup", "--", "--verbose=x"])).toBeUndefined();
+  });
+
+  it("reads --no-headers anywhere and strips it before Commander", () => {
+    expect(parseGlobalFlags(["--no-headers"], TTY).noHeaders).toBe(true);
+    expect(
+      parseGlobalFlags(["block", "list", "--no-headers"], TTY).noHeaders,
+    ).toBe(true);
+    expect(parseGlobalFlags(["block", "list"], TTY).noHeaders).toBeUndefined();
+    expect(stripGlobalFlags(["block", "list", "--no-headers"])).toEqual([
+      "block",
+      "list",
+    ]);
+    // Past the terminator it is the user's data, not this program's flag.
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--no-headers"], TTY)
+        .noHeaders,
+    ).toBeUndefined();
+  });
+
+  it("reads --quiet anywhere and strips it before Commander", () => {
+    expect(parseGlobalFlags(["--quiet"], TTY).quiet).toBe(true);
+    expect(parseGlobalFlags(["sources", "update", "--quiet"], TTY).quiet).toBe(
+      true,
+    );
+    expect(parseGlobalFlags(["sources", "update"], TTY).quiet).toBeUndefined();
+    expect(stripGlobalFlags(["sources", "update", "--quiet"])).toEqual([
+      "sources",
+      "update",
+    ]);
+    // Past the terminator it is the user's data, not this program's flag.
+    expect(
+      parseGlobalFlags(["graph", "query", "--", "--quiet"], TTY).quiet,
+    ).toBeUndefined();
+  });
 });
 
 describe("stripGlobalFlags", () => {
@@ -105,3 +156,68 @@ describe("readRawFormat", () => {
     expect(readRawFormat(["block", "list"])).toBeUndefined();
   });
 });
+
+describe("the option terminator bounds every scan (PROTECTED)", () => {
+  // `--` means the rest is the user's data. A scanner that ignored it would
+  // both misread a flag and STRIP it, so a lookup for a block literally named
+  // `--format` would lose its own argument and change how the error rendered.
+  it("does not read a flag that appears after `--`", () => {
+    expect(readRawFormat(["block", "lookup", "--", "--format", "json"])).toBe(
+      undefined,
+    );
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--verbose"], TTY).verbose,
+    ).toBe(false);
+    expect(
+      parseGlobalFlags(["block", "lookup", "--", "--detail", "detailed"], TTY)
+        .detail,
+    ).toBe(undefined);
+  });
+
+  it("hands everything from `--` onward through untouched", () => {
+    expect(
+      stripGlobalFlags(["block", "lookup", "--", "--format", "json"]),
+    ).toEqual(["block", "lookup", "--", "--format", "json"]);
+  });
+
+  it("still reads a flag that appears before `--`", () => {
+    expect(
+      readRawFormat(["--format", "json", "block", "lookup", "--", "x"]),
+    ).toBe("json");
+    expect(
+      stripGlobalFlags(["--format", "json", "block", "lookup", "--", "x"]),
+    ).toEqual(["block", "lookup", "--", "x"]);
+  });
+});
+
+describe("a flag's value is never another flag (PROTECTED)", () => {
+  // The defect this pins: a valueless `--detail` consumed the NEXT flag as its
+  // value and stripped it, so `--detail --category css` silently answered over
+  // the whole set instead of the filtered one — a wrong answer, no diagnostic.
+  it("leaves a following flag standing when the value is absent", () => {
+    expect(
+      stripGlobalFlags(["standard", "list", "--detail", "--category", "css"]),
+    ).toEqual(["standard", "list", "--category", "css"]);
+  });
+
+  it("reports no detail for a valueless --detail", () => {
+    expect(
+      parseGlobalFlags(["standard", "list", "--detail", "--category"], TTY)
+        .detail,
+    ).toBe(undefined);
+  });
+
+  it("still consumes a real value", () => {
+    expect(
+      stripGlobalFlags(["standard", "list", "--detail", "summary"]),
+    ).toEqual(["standard", "list"]);
+    expect(
+      parseGlobalFlags(["standard", "list", "--detail", "summary"], TTY).detail,
+    ).toBe("summary");
+  });
+
+  it("reports a valueless --format as empty so the caller rejects it", () => {
+    // `""`, not `undefined` — `undefined` would fall through to the default.
+    expect(readRawFormat(["--format", "--verbose"])).toBe("");
+  });
+});