@canonical/pragma-cli 0.35.0 → 0.36.0

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

@@ -3,6 +3,7 @@ import { afterAll, describe, expect, it, vi } from "vitest";
 import { VERSION } from "../../../constants.js";
 import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
 import { projectCli } from "../../../testing/helpers/projectCli.js";
+import type { GlobalFlags } from "../../runtime/index.js";
 import type { CapabilityModule, VerbSpec } from "../../spec/types.js";
 import { formatRootHelp } from "./rootHelp.js";
 
@@ -486,8 +487,26 @@ describe("buildProgram — sub-verb-only noun invoked bare (U2)", () => {
   });
 });
 
-describe("formatRootHelp — grouping", () => {
-  const help = formatRootHelp(
+/** The global flags of a human at a terminal: plain output, nothing inferred. */
+const HUMAN_FLAGS: GlobalFlags = {
+  llm: false,
+  format: "plain",
+  verbose: false,
+};
+
+/** A run whose stdout is captured: `llm`, inferred or asked for. */
+const CAPTURED_FLAGS: GlobalFlags = {
+  llm: true,
+  autoLlm: true,
+  format: "plain",
+  verbose: false,
+};
+
+/** The first line of the wordmark art — present iff the wordmark printed. */
+const WORDMARK_LINE = "(___,";
+
+const rootHelpFor = (flags: GlobalFlags): string =>
+  formatRootHelp(
     "pragma",
     "pragma test",
     [
@@ -497,8 +516,60 @@ describe("formatRootHelp — grouping", () => {
     ],
     "1.2.3",
     "https://example.test/issues",
+    flags,
   );
 
+describe("formatRootHelp — the wordmark is gated on the AUDIENCE", () => {
+  // Asserted on the ART, never on styling: `golden.ts` strips ANSI and this
+  // suite pins `chalk.level = 0`, so a colour-only change would be invisible
+  // here — and chalk emits no escapes off a TTY anyway, so it would save an
+  // agent nothing. The lines have to go.
+  it("prints the art for a human reading plain output", () => {
+    expect(rootHelpFor(HUMAN_FLAGS)).toContain(WORDMARK_LINE);
+  });
+
+  it("drops the art — every line of it — when stdout is captured", () => {
+    const help = rootHelpFor(CAPTURED_FLAGS);
+    expect(help).not.toContain(WORDMARK_LINE);
+    // No leading blank line either: the header IS the first line.
+    expect(help.startsWith("pragma v1.2.3 — pragma test")).toBe(true);
+    // Only the art goes; the page itself is untouched.
+    expect(help).toContain("Usage: pragma <command> [subcommand] [flags]");
+    expect(help).toContain("Global flags");
+  });
+
+  it("drops the art for `--format json` too", () => {
+    expect(
+      rootHelpFor({ llm: false, format: "json", verbose: false }),
+    ).not.toContain(WORDMARK_LINE);
+  });
+
+  it("keeps the art for an EXPLICIT `--format plain` down a pipe", () => {
+    // Explicit beats inference: asking for the human shape gets the human page,
+    // captured or not. (`parseGlobalFlags` leaves `llm` false whenever
+    // `--format` was requested.)
+    expect(
+      rootHelpFor({
+        llm: false,
+        autoLlm: false,
+        format: "plain",
+        verbose: false,
+      }),
+    ).toContain(WORDMARK_LINE);
+  });
+
+  it("differs ONLY by the wordmark block", () => {
+    const human = rootHelpFor(HUMAN_FLAGS).split("\n");
+    const captured = rootHelpFor(CAPTURED_FLAGS).split("\n");
+    // 10 art lines + the blank that separates them from the header.
+    expect(human.length - captured.length).toBe(11);
+    expect(human.slice(11)).toEqual(captured);
+  });
+});
+
+describe("formatRootHelp — grouping", () => {
+  const help = rootHelpFor(HUMAN_FLAGS);
+
   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

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

@@ -298,7 +298,14 @@ export function buildProgram(
   program.enablePositionalOptions();
   program.exitOverride();
   useDesignedHelp(program, () =>
-    formatRootHelp(programName, description, live, version, issuesUrl),
+    formatRootHelp(
+      programName,
+      description,
+      live,
+      version,
+      issuesUrl,
+      options.globalFlags,
+    ),
   );
 
   const groups = new Map<string, VerbSpec[]>();

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

@@ -5,10 +5,11 @@ import { $, fail, gen, log, mkdir, succeed, writeFile } 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 { canPrompt } from "../../interactivity.js";
 import { bootRuntime } from "../../runtime/boot.js";
 import type { GlobalFlags } from "../../runtime/types.js";
 import type { ParamSpec, VerbSpec } from "../../spec/types.js";
-import { cliIsTTY, dispatch, executeVerb, extractParams } from "./dispatch.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;
@@ -218,7 +219,7 @@ describe("--quiet — success is silent, failure is not", () => {
       formatters: {
         ...passthroughFormatters,
         plain: () => "",
-        emptyNotice: () => "No results.",
+        notice: () => "No results.",
       },
     },
     run: async () => [],
@@ -491,7 +492,7 @@ describe("executeVerb — interactivity gate (H3)", () => {
     expect(sink.isTTY).toBe(true);
   });
 
-  it("cliIsTTY IS the stdin+stderr conjunction — the one gate both callers read", () => {
+  it("canPrompt IS the stdin+stderr conjunction — the one gate both callers read", () => {
     // The mount's create decision reads the same exported function this
     // describe drives through executeVerb, so pinning the truth table here
     // pins BOTH callers (nothing is left to keep two copies in step).
@@ -506,7 +507,7 @@ describe("executeVerb — interactivity gate (H3)", () => {
       setTTY(process.stdin, stdin);
       setTTY(process.stderr, stderr);
       setTTY(process.stdout, stdout);
-      expect(cliIsTTY(), `stdin=${stdin} stderr=${stderr}`).toBe(expected);
+      expect(canPrompt(), `stdin=${stdin} stderr=${stderr}`).toBe(expected);
     }
   });
 });

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

@@ -25,6 +25,7 @@ import {
   renderErrorLlm,
   renderErrorPlain,
 } from "../../error/index.js";
+import { canPrompt, stdoutIsCaptured } from "../../interactivity.js";
 import type { RenderContext } from "../../render/contracts.js";
 import { successEnvelope, writeStdout } from "../../render/index.js";
 import { bootRuntime } from "../../runtime/index.js";
@@ -43,18 +44,6 @@ 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
@@ -171,7 +160,7 @@ export function extractParams(
  * 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.
+ * @note Impure — reads stdout's capture state for the render context.
  */
 function renderData(
   verb: VerbSpec,
@@ -181,8 +170,17 @@ function renderData(
 ): DispatchOutcome {
   if (flags.format === "json") {
     const projection = JSON.parse(verb.output.formatters.json(data));
+    // The calm notice rides `meta` on the machine surfaces, so an empty result
+    // is distinguishable from an unbuilt store or a mistyped filter, and an
+    // ambiguous lookup hit from an unambiguous one. `data` keeps its uniform
+    // shape, and MCP builds the same key from the same seam
+    // (`mcp/registerVerb.ts#noticeMeta`) — the two machine surfaces stay
+    // byte-equal.
+    const notice = verb.output.formatters.notice?.(data);
     return {
-      stdout: `${JSON.stringify(successEnvelope(projection, meta))}\n`,
+      stdout: `${JSON.stringify(
+        successEnvelope(projection, notice ? { ...meta, notice } : meta),
+      )}\n`,
       exitCode: 0,
     };
   }
@@ -192,14 +190,12 @@ function renderData(
   }
   const context: RenderContext = {
     headers: flags.noHeaders !== true,
-    stdoutIsTty: process.stdout.isTTY === true,
+    stdoutIsTty: !stdoutIsCaptured(),
   };
   const text = verb.output.formatters.plain(data, context);
-  // The calm zero-record notice is success-path guidance — `--quiet` mutes it.
+  // The calm notice is success-path guidance — `--quiet` mutes it.
   const notice =
-    flags.quiet === true
-      ? undefined
-      : verb.output.formatters.emptyNotice?.(data);
+    flags.quiet === true ? undefined : verb.output.formatters.notice?.(data);
   return {
     stdout: text ? `${text}\n` : "",
     ...(notice ? { stderr: `${notice}\n` } : {}),
@@ -332,8 +328,8 @@ export async function executeVerb(
     // block on input. `--undo` stays handler-free and untouched by this seam.
     const controller = new AbortController();
     const interaction: InteractionRuntime = {
-      // The shared H3 gate (see cliIsTTY): stderr, never stdout.
-      isTTY: cliIsTTY(),
+      // The shared H3 gate (see `canPrompt`): stdin and stderr, never stdout.
+      isTTY: canPrompt(),
       transport: "cli",
       yes: mutation.yes,
       signal: controller.signal,
@@ -420,17 +416,22 @@ export async function executeVerb(
     }
     // Real execution: spread the verb's runner options into the node
     // interpreter (prompt handler, stamping/progress callbacks, log routing,
-    // signal). Teardown (e.g. unmount an Ink render) runs in `finally`.
+    // signal). Teardown (e.g. unmount an Ink render) runs in `finally` —
+    // BEFORE the outcome is rendered: an interactive session's closing frame
+    // flushes on its dispose, so printing the result first put the verb's
+    // stdout recap ABOVE a frame that then repainted stale beneath it. Tear
+    // the UI down, then report; the error path gets the same order for free.
     const exec = mutationRuntime.exec ?? {};
     const onSigint = (): void => controller.abort();
     process.once("SIGINT", onSigint);
+    let value: unknown;
     try {
-      const value = await runTask(task, { onLog: logSink(flags), ...exec });
-      return renderData(verb, flags, value, {});
+      value = await runTask(task, { onLog: logSink(flags), ...exec });
     } finally {
       process.removeListener("SIGINT", onSigint);
       await exec.dispose?.();
     }
+    return renderData(verb, flags, value, {});
   }
 
   const data = await Promise.resolve(

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

@@ -25,6 +25,7 @@
  */
 
 import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
+import { stdoutIsCaptured } from "../../interactivity.js";
 import type { GlobalFlags } from "../../runtime/index.js";
 
 /** The end-of-options separator: nothing after it is a flag of this program. */
@@ -153,7 +154,9 @@ export interface OutputEnvironment {
 /** Read the real stdout/env output environment. @note Impure — reads process. */
 function readOutputEnvironment(): OutputEnvironment {
   return {
-    isTty: process.stdout.isTTY === true,
+    // The OUTPUT-SHAPE question, on stdout — not the prompting one. A run whose
+    // stdout is captured may still have a terminal to prompt on (`canPrompt`).
+    isTty: !stdoutIsCaptured(),
     noAutoLlm: Boolean(process.env.PRAGMA_NO_AUTO_LLM),
   };
 }

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

@@ -11,9 +11,8 @@
  */
 
 import chalk from "chalk";
+import { INDENT } from "../../render/vocabulary.js";
 
-/** Two-space indent for every list body row. */
-const INDENT = "  ";
 /** Two-space gap between a term column and its description. */
 const GAP = "  ";
 

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

@@ -11,6 +11,7 @@
  */
 
 import { PROGRAM_LOGO } from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/index.js";
 import type { VerbSpec } from "../../spec/index.js";
 import {
   helpColumns,
@@ -132,6 +133,27 @@ function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
   return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
 }
 
+/**
+ * Whether this reader is worth spending the wordmark on.
+ *
+ * An AUDIENCE question, not a data question: the art is 11 lines and ~200
+ * tokens — roughly a third of what `--help` costs an agent — and it says
+ * nothing an agent can act on. Both captured shapes are excluded:
+ * `llm` (requested, or inferred from a non-interactive stdout — the shape an
+ * agent captures) and `json`. `--format plain` therefore keeps the art even
+ * down a pipe, and `--format llm` drops it even on a terminal: explicit beats
+ * inference, the same inferred-vs-explicit split `renderErrorForFormat` uses.
+ *
+ * The DECISION is passed in as data — both call sites already hold the parsed
+ * flags — so this module still reads no `process` state and stays testable.
+ *
+ * @param flags - The invocation's global flags.
+ * @returns `true` when a human is reading and the wordmark should print.
+ */
+function wordmarkSuitsReader(flags: GlobalFlags): boolean {
+  return flags.llm !== true && flags.format !== "json";
+}
+
 /**
  * Build the curated root help string.
  *
@@ -144,6 +166,9 @@ function summarizeNoun(noun: string, verbs: readonly VerbSpec[]): string {
  *   read here so it is the SAME string `--version` prints: `buildProgram`
  *   resolves `options.version ?? VERSION`, and a host that overrides one must
  *   not be able to leave the other saying something else.
+ * @param globalFlags - The invocation's global flags, read only to decide who
+ *   is reading (see {@link wordmarkSuitsReader}). Passed rather than probed: the
+ *   help layer must not learn to read `process`.
  * @returns The formatted, colorized help text.
  */
 export function formatRootHelp(
@@ -152,6 +177,7 @@ export function formatRootHelp(
   verbs: readonly VerbSpec[],
   version: string,
   issuesUrl: string,
+  globalFlags: GlobalFlags,
 ): string {
   const present = nounsFrom(verbs);
   const kernel = buildKernelGroups(programName);
@@ -181,9 +207,16 @@ export function formatRootHelp(
   );
 
   const lines: string[] = [
-    // The wordmark leads when the distribution declares one. A fork ships its
-    // own art or none, so its front door is never branded with someone else's.
-    ...(PROGRAM_LOGO.length > 0 ? [...PROGRAM_LOGO.map(helpLogo), ""] : []),
+    // The wordmark leads when the distribution declares one AND a human is
+    // reading it. A fork ships its own art or none, so its front door is never
+    // branded with someone else's; and a captured run drops the art entirely
+    // rather than charging an agent ~200 tokens for a picture of the name it
+    // just typed (see `wordmarkSuitsReader`). The LINES go, not their colour:
+    // chalk already emits no escapes off a TTY, so dimming would save nobody
+    // anything.
+    ...(PROGRAM_LOGO.length > 0 && wordmarkSuitsReader(globalFlags)
+      ? [...PROGRAM_LOGO.map(helpLogo), ""]
+      : []),
     // `<name> v<version> — <blurb>`, the spelling `info` and `capabilities`
     // already use, so the front door names the build the same way every other
     // surface does. Dimmed: it answers "which build am I on" for someone who

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

@@ -143,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> => {
@@ -152,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));
     }

package/src/kernel/render/renderers.ts

@@ -85,7 +85,7 @@ function emptyBody<T>(options: RenderListOptions<T>): string {
  * The empty-list notice a dispatcher routes to STDERR (exit 0): zero rows is
  * a calm success, and stdout — the data stream — must not carry a human
  * sentence a pipe would read as a record. Exported for the formatter seam's
- * `emptyNotice`; the plain renderer itself no longer prints it.
+ * `notice`; the plain renderer itself no longer prints it.
  */
 export function renderListEmptyNotice<T>(
   options: RenderListOptions<T>,

package/src/kernel/render/style.ts

@@ -12,6 +12,7 @@
  */
 
 import chalk from "chalk";
+import { stdoutIsCaptured } from "../interactivity.js";
 
 /** The palette + gate a renderer consults to beautify the human path. */
 export interface RenderStyle {
@@ -27,6 +28,8 @@ export interface RenderStyle {
   green(text: string): string;
   /** Tint a status that wants attention. */
   yellow(text: string): string;
+  /** Tint a real fault — a failed check or a failed row, nothing milder. */
+  red(text: string): string;
 }
 
 /** The identity styler — every function returns its input unchanged. */
@@ -37,6 +40,7 @@ const PLAIN_STYLE: RenderStyle = {
   cyan: (text) => text,
   green: (text) => text,
   yellow: (text) => text,
+  red: (text) => text,
 };
 
 /**
@@ -55,6 +59,7 @@ export function styleFor(enabled: boolean): RenderStyle {
     cyan: (text) => chalk.cyan(text),
     green: (text) => chalk.green(text),
     yellow: (text) => chalk.yellow(text),
+    red: (text) => chalk.red(text),
   };
 }
 
@@ -75,8 +80,8 @@ export function forbidsColor(env: NodeJS.ProcessEnv): boolean {
 }
 
 // Applied to the SHARED chalk instance at module load, not inside
-// `defaultStyle()`, because four modules reach for `chalk` directly rather than
-// through `RenderStyle` — help formatting, doctor, upgrade and the colophon's
+// `defaultStyle()`, because three modules reach for `chalk` directly rather
+// than through `RenderStyle` — help formatting, upgrade and the colophon's
 // Markdown renderer. Gating only the style seam would leave every one of them
 // still emitting escapes. Zeroing the level once covers them by construction,
 // including any site added later.
@@ -87,18 +92,36 @@ export function forbidsColor(env: NodeJS.ProcessEnv): boolean {
 // worked.
 if (forbidsColor(process.env)) chalk.level = 0;
 
+/**
+ * Whether stdout may carry color: an attended terminal AND a usable chalk
+ * level (zeroed by the module-load check above under `NO_COLOR`).
+ *
+ * The third question of the interactivity vocabulary (`kernel/interactivity.ts`
+ * holds the other two, and its docblock says why this one lives here: it needs
+ * `chalk`, and that module is on the flag-parsing fast path). Both signals are
+ * required — `supports-color` enables color off a TTY in CI, which would paint
+ * escapes into a redirected stream every byte-comparison then has to strip.
+ *
+ * @returns True on a color-capable terminal.
+ * @note Impure — reads stdout's capture state and chalk's color level.
+ */
+export function canColor(): boolean {
+  return !stdoutIsCaptured() && chalk.level > 0;
+}
+
 /**
  * The active style for this process's stdout.
  *
- * Gated on BOTH signals: stdout must be an attended TTY, so piped / redirected /
- * MCP output stays byte-stable even where `supports-color` fires off a TTY (CI
- * sets `GITHUB_ACTIONS`, which chalk honors); AND chalk must report a usable
- * color level, which the module-load check above forces to zero under
- * `NO_COLOR`.
+ * Both signals, asked as one named question ({@link canColor}): stdout must be
+ * an attended TTY, so piped / redirected / MCP output stays byte-stable even
+ * where `supports-color` fires off a TTY (CI sets `GITHUB_ACTIONS`, which chalk
+ * honors); AND chalk must report a usable color level, which the module-load
+ * check above forces to zero under `NO_COLOR`.
  *
  * @returns A colorizing style on a color-capable TTY, else the identity styler.
- * @note Impure — reads `process.stdout.isTTY` and chalk's color level.
+ * @note Impure — {@link canColor} reads stdout's capture state and chalk's
+ *   color level.
  */
 export function defaultStyle(): RenderStyle {
-  return styleFor(process.stdout.isTTY === true && chalk.level > 0);
+  return styleFor(canColor());
 }