@effected/cli 0.11.0 → 0.13.0

package/CliFailure.js

@@ -193,13 +193,60 @@ const failBlocks = (error, spans, options) => {
 	if (schema !== void 0) return [...schema, ...spans];
 	return [...failureBlocks(describe(error)), ...spans];
 };
-/** `in: outer › inner`, from the span stack the runtime annotates a reason with, or none. */
-const spanBlocks = (reason) => {
+/** A file of the kit's own packages or of Effect, as installed: a span defined there is not the program's. */
+const isKitFile = (file) => /[\\/]node_modules[\\/](?:@effected[\\/]|effect[\\/])/.test(file);
+/**
+* The installed package directory that holds `module`: the path through the last `node_modules/<name>` or
+* `node_modules/@scope/name` in it, or `undefined` when the module is not under `node_modules` (or not a path at all).
+* Read from the path alone, with no file system.
+*/
+const packageDirOf = (module) => {
+	if (module === void 0) return void 0;
+	const path = asPath(module);
+	if (path === void 0) return void 0;
+	return /^(.*\/node_modules\/(?:@[^/]+\/)?[^/]+)\//.exec(comparable(path))?.[1];
+};
+/**
+* A path in the one spelling both sides of a comparison use: `/` separators, and a Windows drive letter lower-cased. A
+* CommonJS frame on Windows reads `C:\…` where an `import.meta.url` reads `file:///C:/…`, and the drive's case is not
+* fixed (`c:` and `C:` are one drive). Lexical only: no file system, no realpath.
+*/
+const comparable = (path) => path.replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, drive) => `${drive.toLowerCase()}:`);
+/** Whether `file` is in the program's own package `appDir`, and not in a dependency nested in its `node_modules`. */
+const isAppFile = (file, appDir) => {
+	if (appDir === void 0) return false;
+	const path = comparable(file);
+	if (!path.startsWith(appDir)) return false;
+	const rest = path.slice(appDir.length);
+	return rest.startsWith("/") && !rest.includes("/node_modules/");
+};
+/** The file a span frame's captured stack points at, or `undefined` when it captured none. */
+const spanFile = (frame) => {
+	try {
+		const stack = frame.stack();
+		if (stack === void 0) return void 0;
+		const line = stack.split(/\r\n|\r|\n/).find((candidate) => /^\s*at\s/.test(candidate)) ?? stack;
+		return frameFile(line.trim().startsWith("at ") ? line : `at ${line.trim()}`);
+	} catch {
+		return;
+	}
+};
+/**
+* `in: outer › inner`, from the span stack the runtime annotates a reason with, or none. With `app`, a span the kit or
+* Effect defined is left out. An `Effect.fn` call carries its definition as its parent (`name (definition)`): the two
+* are one entry, `name`, judged by the definition's site, so a kit function the program calls goes with its
+* definition.
+*/
+const spanBlocks = (reason, mode, appDir) => {
+	if (mode === "off") return [];
 	const names = [];
 	let frame = Context.getOrUndefined(Cause.reasonAnnotations(reason), Cause.StackTrace);
-	while (frame !== void 0 && names.length < MAX_SPANS) {
-		names.push(frame.name);
-		frame = frame.parent;
+	for (let seen = 0; frame !== void 0 && seen < MAX_SPANS; seen++) {
+		const parent = frame.parent;
+		const definition = parent !== void 0 && parent.name === `${frame.name} (definition)` ? parent : void 0;
+		const file = (definition === void 0 ? void 0 : spanFile(definition)) ?? spanFile(frame);
+		if (mode === "all" || file === void 0 || isAppFile(file, appDir) || !isKitFile(file)) names.push(frame.name);
+		frame = definition === void 0 ? parent : definition.parent;
 	}
 	if (names.length === 0) return [];
 	return [Doc.paragraph(Doc.text("in: ", "muted"), Doc.path(...names.reverse()))];
@@ -221,7 +268,7 @@ const spanBlocks = (reason) => {
 * `Error.cause` chain as a tree. When cleaning leaves no frame the stack says
 * `no user frames (N internal frames hidden)`, never an empty block; when frames survive and some were left out, the
 * count follows them as `(+N internal frames hidden)`. A reason that ran under spans is followed by
-* `in: outer › inner`. Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
+* `in: outer › inner`: by default only the program's own spans, the kit's and Effect's left out (`spans`). Interrupts are not rendered beside a real failure, and a cause with only interrupts is the
 * one line `interrupted`.
 *
 * All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
@@ -242,8 +289,10 @@ var CliFailure = class {
 		if (reasons.length > 0 && reasons.every(Cause.isInterruptReason)) return [Doc.paragraph("interrupted")];
 		const displayPath = options?.displayPath ?? ((absolute) => absolute);
 		return reasons.flatMap((reason) => {
-			if (Cause.isFailReason(reason)) return failBlocks(reason.error, spanBlocks(reason), options);
-			if (Cause.isDieReason(reason)) return dieBlocks(reason.defect, spanBlocks(reason), displayPath, options?.stackFrames ?? "app");
+			const spans = options?.spans ?? "app";
+			const appDir = packageDirOf(options?.appModule);
+			if (Cause.isFailReason(reason)) return failBlocks(reason.error, spanBlocks(reason, spans, appDir), options);
+			if (Cause.isDieReason(reason)) return dieBlocks(reason.defect, spanBlocks(reason, spans, appDir), displayPath, options?.stackFrames ?? "app");
 			return [];
 		});
 	};

package/CliLog.js

@@ -1,7 +1,8 @@
 import { sanitize } from "./Fmt.js";
 import { paintStyle } from "./internal/ansi.js";
+import { CliTheme } from "./CliTheme.js";
 import { scanAudience } from "./internal/scanAudience.js";
-import { neutralizeJson } from "./internal/logSafety.js";
+import { TrustedLine, neutralizeJson } from "./internal/logSafety.js";
 import { makeCliLogger } from "./CliLogger.js";
 import { Level, passes } from "./internal/diagnostics.js";
 import { makeFileSink } from "./internal/fileSink.js";
@@ -10,6 +11,14 @@ import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
 import { CommandNeutralizer } from "@effected/github-commands";
 
 //#region src/CliLog.ts
+/** The most spaces a numeric `indent` writes. */
+const MAX_INDENT = 64;
+/** An indent as written before the glyph: spaces for a number, a string with nothing in it that is not text. */
+const indentOf = (indent) => {
+	if (indent === void 0) return "";
+	if (typeof indent === "number") return Number.isFinite(indent) && indent > 0 ? " ".repeat(Math.min(MAX_INDENT, Math.floor(indent))) : "";
+	return sanitize(indent).replace(/\r\n|\r|\n/g, "");
+};
 /** The accepted spellings of a level, lower-cased, to the level they mean. */
 const LEVELS = {
 	all: "All",
@@ -204,6 +213,49 @@ var CliLog = class CliLog {
 		}));
 	}
 	/**
+	* Log a status line: its glyph painted through the theme, then `text`, at a level that follows the status.
+	*
+	* @remarks
+	* The line goes through the logger, so it is a diagnostic like any `Effect.log*` call: filtered by the level in
+	* force (`--log-level`, `CliLog.Level`), routed by `CliLogger`'s `stderrFrom` (stderr by default) and neutralized
+	* under GitHub Actions. What differs is the glyph: the logger sanitises every line a program logs, which strips a
+	* colour a program painted itself, so a glyph on the log channel was always drawn bare. Here the kit paints it and
+	* marks the line as its own, so the plain `CliLogger` line keeps the colour, while `text` is still sanitised:
+	* escape sequences and control characters in it are removed, as in every line the kit writes.
+	*
+	* The glyph is painted with stderr's theme (where diagnostics go) through {@link CliTheme.forAudience}, so an agent
+	* gets it unpainted, and an `Audience` is read only when provided, so it stays out of the requirements. ASCII glyphs
+	* give the status's ASCII form. A diagnostics record carries the line as its message as any record does: the `CliLog`
+	* sink's pretty line sanitises it (the glyph is drawn bare there), and NDJSON keeps it, JSON-escaped.
+	*
+	* The level defaults to the status's rank in `vocab`: `Error` at or above `failure`'s, `Warn` at or above
+	* `warning`'s, `Info` below, so a custom status follows its own rank. Pass `level` to choose it, and `indent` (a
+	* number of spaces, or a string, sanitised) to start the line inside an indented block: `    ✗ error   x: red`.
+	*
+	* @example
+	* ```ts
+	* import { CliLog, Status } from "@effected/cli"
+	*
+	* // ✗ in the failure colour, then the message: on stderr, filtered by the log level.
+	* const reportError = (resource: string, message: string) =>
+	*   CliLog.status(Status.core, "failure", `${resource}: ${message}`)
+	* ```
+	*
+	* @param vocab - the vocabulary the status belongs to
+	* @param name - the status
+	* @param text - the text after the glyph, sanitised
+	* @param options - the level to log at, and the indent before the glyph
+	*/
+	static status = (vocab, name, text, options) => Effect.gen(function* () {
+		const audience = yield* Effect.serviceOption(Audience);
+		const theme = CliTheme.forAudience((yield* CliTheme).forStream("stderr"), Option.isSome(audience) ? audience.value.kind : void 0);
+		const line = `${indentOf(options?.indent)}${theme.status(vocab, name, sanitize(text))}`;
+		const core = vocab;
+		const rank = vocab.def(name).rank;
+		const level = options?.level ?? (rank >= core.def("failure").rank ? "Error" : rank >= core.def("warning").rank ? "Warn" : "Info");
+		yield* Effect.logWithLevel(level)(line).pipe(Effect.provideService(TrustedLine, true));
+	});
+	/**
 	* Mark the log records an effect emits as coming from `name`.
 	*
 	* @remarks

package/CliMessage.js

@@ -18,8 +18,8 @@ import { CommandNeutralizer } from "@effected/github-commands";
 *
 * The text is whatever the caller supplies, so it is sanitised: escape sequences and control characters are removed
 * (a line break is kept as one, a tab becomes a space), as in a document. Under GitHub Actions, where
-* `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyphs
-* come from the vocabulary, which is configuration, and are not.
+* `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyph
+* comes from the vocabulary, sanitised too (`Status.glyph`), so a glyph built from data cannot inject an escape either.
 *
 * @public
 */
@@ -46,10 +46,7 @@ var CliMessage = class CliMessage {
 		const stream = options?.stream ?? (def.rank >= warning ? "stderr" : "stdout");
 		const streamTheme = theme.forStream(stream);
 		let line;
-		if (audience.kind === "agent") {
-			const glyph = streamTheme.glyphs.kind === "ascii" ? def.ascii : def.glyph;
-			line = message === "" ? glyph : `${glyph} ${message}`;
-		} else line = streamTheme.status(vocab, name, message);
+		line = CliTheme.forAudience(streamTheme, audience.kind).status(vocab, name, message);
 		if (yield* underGithubActions) line = CommandNeutralizer.text(line);
 		yield* stream === "stderr" ? Console.error(line) : Console.log(line);
 	});

package/CliRuntime.js

@@ -1,15 +1,17 @@
+import { Cancelled } from "./Cancelled.js";
 import { sanitize } from "./Fmt.js";
-import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, refreshFailureTarget } from "./internal/failureTarget.js";
+import { NotInteractive } from "./NotInteractive.js";
+import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget } from "./internal/failureTarget.js";
 import { CliColor } from "./CliColor.js";
 import { CliEnv } from "./CliEnv.js";
 import { isExitCode } from "./internal/isExitCode.js";
 import { CliExit } from "./CliExit.js";
 import { TrustedLine } from "./internal/logSafety.js";
-import { CliLogger } from "./CliLogger.js";
+import { CliLogger, makeCliLogger } from "./CliLogger.js";
 import { CliLog, envBuildLogLayer, platformLogLayer } from "./CliLog.js";
 import { ExitRequested } from "./internal/ExitRequested.js";
 import { routeHelpOnUsageError } from "./internal/HelpRouting.js";
-import { Cause, Effect, Layer, MutableRef, Runtime } from "effect";
+import { Cause, Effect, Layer, Logger, MutableRef, Runtime } from "effect";
 import { CliError } from "effect/cli";
 import { CommandNeutralizer } from "@effected/github-commands";
 
@@ -158,12 +160,12 @@ var CliRuntime = class CliRuntime {
 		const render = options.render;
 		return Effect.gen(function* () {
 			const target = yield* currentTarget.pipe(Effect.catchCause(() => Effect.succeed(fallbackTarget)));
-			const reportLines = (status) => {
+			const reportLines = (status, spans) => {
 				try {
-					return linesOf(cause, target, status);
+					return linesOf(cause, target, status, spans ?? target.spans);
 				} catch {
 					try {
-						return plainFailureLines(cause, status);
+						return plainFailureLines(cause, status, spans ?? target.spans);
 					} catch {
 						return lastResort(error);
 					}
@@ -173,8 +175,10 @@ var CliRuntime = class CliRuntime {
 			const details = {
 				cause,
 				isDefect: !Cause.hasFails(cause),
+				isCancelled: error instanceof Cancelled,
+				isNotInteractive: error instanceof NotInteractive,
 				defaultLines,
-				lines: (options) => options?.status === false ? reportLines(false) : defaultLines
+				lines: (options) => options?.status === false || options?.spans !== void 0 ? reportLines(options?.status !== false, options?.spans) : defaultLines
 			};
 			const lines = render === void 0 ? defaultLines : yield* guardConsumerLines(toLines(render(error, details)));
 			for (const line of lines) yield* Effect.logError(line).pipe(Effect.provideService(TrustedLine, true));
@@ -185,9 +189,15 @@ var CliRuntime = class CliRuntime {
 		const env = options.env === void 0 ? void 0 : CliEnv.layer(options.env);
 		const envLog = options.env?.log;
 		const logger = options.logger ?? (env === void 0 || envLog === void 0 ? CliLogger.layer() : CliLog.layer(envLog).pipe(Layer.provide(env), Layer.provide(Layer.provideMerge(options.platform.pipe(Layer.provide(platformLogLayer(envLog, options.env?.audienceEnvVar))), envBuildLogLayer(envLog, options.env?.audienceEnvVar))), Layer.catchCause(() => CliLogger.layer(envLog.logger))));
-		const inside = env === void 0 ? Layer.empty : Layer.mergeAll(CliColor.formatterLayer(options.env?.formatter), Layer.effectDiscard(refreshFailureTarget(void 0, {
-			displayPath: options.env?.displayPath,
-			stackFrames: options.env?.stackFrames
+		const inside = env === void 0 ? Layer.empty : Layer.mergeAll(CliColor.formatterLayer(options.env?.formatter), Layer.effectDiscard(Effect.gen(function* () {
+			const { spans, invalid } = yield* readSpans(options.env?.spans, options.env?.spansEnvVar);
+			if (invalid !== void 0) yield* Effect.logWarning(invalid).pipe(Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([makeCliLogger(envLog?.logger)])));
+			yield* refreshFailureTarget(void 0, {
+				displayPath: options.env?.displayPath,
+				stackFrames: options.env?.stackFrames,
+				spans,
+				appModule: options.env?.appModule
+			});
 		}))).pipe(Layer.provideMerge(env));
 		const run = Effect.gen(function* () {
 			yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(program) : program;

package/CliTheme.js

@@ -20,24 +20,13 @@ const streamThemeAt = (resolve, glyphs, color) => {
 		glyphs,
 		color,
 		status: (vocab, name, text) => {
-			const def = vocab.def(name);
-			const glyph = paint(def.token, glyphs.kind === "ascii" ? def.ascii : def.glyph);
+			const glyph = paint(vocab.def(name).token, vocab.glyph(name, glyphs));
 			return text === void 0 || text === "" ? glyph : `${glyph} ${text}`;
 		}
 	};
 };
-/**
-* The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
-* empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
-* anyone else, or when the audience is not known, `theme` itself.
-*
-* @remarks
-* The one place that rule is applied to a theme: `Render.context` takes its colour and `paint` from it, and `./ui`
-* gives it to the trees it mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree.
-*
-* @internal
-*/
-const themeForAudience = (theme, audience) => audience === "agent" && theme.color !== "none" ? streamThemeAt(theme.style, theme.glyphs, "none") : theme;
+/** The audience rule, shared by `CliTheme.forAudience` and the class's own docs. */
+const forAudience = (theme, audience) => audience === "agent" && theme.color !== "none" ? streamThemeAt(theme.style, theme.glyphs, "none") : theme;
 const make = (colors, glyphs, overrides) => {
 	const resolve = (token) => Token.resolve(token, overrides);
 	const stdout = streamThemeAt(resolve, glyphs, colors.stdout);
@@ -93,6 +82,30 @@ var CliTheme = class CliTheme extends Context.Service()("@effected/cli/CliTheme"
 		}, glyphs, options?.tokens);
 	}));
 	/**
+	* The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+	* empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+	* anyone else, or when the audience is not known, `theme` itself.
+	*
+	* @remarks
+	* The one rule the kit applies wherever it paints for an audience: `Render.context` takes its colour and `paint`
+	* from it, `CliMessage` and `CliLog.status` paint their glyphs through it, and `./ui` gives it to the trees it
+	* mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree. A program that paints its
+	* own lines applies the same rule with it rather than re-implementing it:
+	*
+	* ```ts
+	* const line = Effect.gen(function* () {
+	*   const theme = CliTheme.forAudience((yield* CliTheme).forStream("stdout"), (yield* Audience).kind)
+	*   return theme.status(Status.core, "success", Fmt.sanitize(name))
+	* })
+	* ```
+	*
+	* Pure: it reads nothing, so the audience is the caller's to pass, `undefined` when it is not known.
+	*
+	* @param theme - a stream's theme, such as `CliTheme.forStream("stdout")`
+	* @param audience - who the output is for, or `undefined` when that is not known
+	*/
+	static forAudience = forAudience;
+	/**
 	* A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
 	*
 	* @param options - the colour level and glyph set
@@ -125,4 +138,4 @@ var CliTheme = class CliTheme extends Context.Service()("@effected/cli/CliTheme"
 };
 
 //#endregion
-export { CliTheme, streamThemeAt, themeForAudience };
+export { CliTheme, streamThemeAt };

package/Doc.js

@@ -25,6 +25,10 @@ const treeNode = (input) => freeze({
 });
 const counterOf = (counter) => freeze({
 	...counter,
+	label: typeof counter.label === "string" ? counter.label : freeze({
+		one: counter.label.one,
+		other: counter.label.other
+	}),
 	status: freeze({
 		name: counter.status.name,
 		def: freeze({ ...counter.status.def })
@@ -278,6 +282,11 @@ var Doc = class {
 	/**
 	* Children under an optional title.
 	*
+	* @remarks
+	* The children are separated by blank lines (unless the document is compact); a title sits directly above the first.
+	* `Doc.section(undefined, blocks)` is the way to space a document's top-level blocks, which are otherwise joined with
+	* no blank line.
+	*
 	* @param title - the title, or `undefined` for none
 	* @param children - the blocks
 	*/
@@ -294,9 +303,15 @@ var Doc = class {
 	* @remarks
 	* A name the vocabulary does not have is a compile error.
 	*
+	* The label is one string, or `{ one, other }` to pluralise by count: `one` when the count is exactly 1 and `other`
+	* for every other count, 0 included. A count standing alone reads by its own `n` (`1 change`, `2 changes`); a
+	* headline shown as a share of the total reads by that total, the noun it counts (`1/1 repo`, `1/3 repos`,
+	* `2/3 repos`).
+	*
 	* @param vocab - the vocabulary the status belongs to
 	* @param name - a status name in it
-	* @param options - the counter's `key`, `label` and count `n`, and `showZero` to keep it when `n` is zero
+	* @param options - the counter's `key`, its `label` (one string, or `{ one, other }`), its count `n`, and `showZero`
+	* to keep it when `n` is zero
 	*/
 	static counter(vocab, name, options) {
 		return counterOf({
@@ -373,20 +388,25 @@ var Doc = class {
 		});
 	}
 	/**
-	* One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping.
+	* One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping,
+	* and with `wrap: false` it is kept whole on one line whatever the width.
 	*
 	* @remarks
-	* Without `truncate` a line longer than the width wraps. For a single line that must never wrap nor be cut, such
-	* as a test's full name used as a title, use {@link Doc.verbatim}.
+	* By default a line longer than the width wraps. `wrap: false` keeps it atomic in every audience and renderer, still
+	* carrying its status glyphs, theme tokens and links, which {@link Doc.verbatim} (a plain string) cannot: the tool for
+	* a finding such as `✗ path:line:col  rule  message` that a reader greps or reads line by line, while the prose around
+	* it still wraps. A line break inside it is still a space. With both `truncate` and `wrap: false`, `truncate` wins:
+	* the line is cut to the width.
 	*
 	* @param content - the line
-	* @param options - `truncate`
+	* @param options - `truncate`, to cut it to the width; `wrap: false`, to keep it whole
 	*/
 	static line(content, options) {
 		return freeze({
 			_tag: "Line",
 			content: inlines(content),
-			...options?.truncate === void 0 ? {} : { truncate: options.truncate }
+			...options?.truncate === void 0 ? {} : { truncate: options.truncate },
+			...options?.wrap === void 0 ? {} : { wrap: options.wrap }
 		});
 	}
 	/**
@@ -482,11 +502,15 @@ var Doc = class {
 	* The context is {@link Render.context} for the stream, so the width, the colour, the links and the audience
 	* come from the services the program already has, and the text is written with `Console.log` or
 	* `Console.error`: a test captures it by swapping the `Console`. With `format: "auto"` the renderer follows
-	* the audience, and the width is unbounded for an agent and a CI.
+	* the audience, and the width is unbounded for an agent, a CI, and a human whose stream is not a terminal.
 	*
 	* An agent is never written an escape of any kind, even with an explicit `format: "ansi"`: its context is
 	* colourless and its links are off. A document that renders to nothing prints nothing.
 	*
+	* The whole document is written as one `Console.log` (or `Console.error`) call, with its line breaks embedded, so a
+	* captured `Console` holds one entry per document, not one per line. Top-level blocks are joined with no blank
+	* line between them; wrap them in `Doc.section(undefined, [...])` to space them.
+	*
 	* `CurrentRuntimeEnv` is read if the environment has one and is not required: a `ci` audience prints
 	* GitHub's log format only when it says GitHub Actions, and plain text otherwise, including when it is
 	* absent. An explicit `format` is honoured whatever the audience.

package/README.md

@@ -123,7 +123,7 @@ Colour follows Node's precedence, per stream: `FORCE_COLOR` decides first and be
 ## Output
 
 - **`CliMessage`**: `success`, `info`, `warning`, `failure` and `status(vocab, name, text)`. One themed line each, through `Console` rather than the logger, so no log level silences them. Warnings and failures go to stderr.
-- **`Doc` and `Render`**: a document IR (headings, paragraphs, lists, tables, trees, counts, count tables, collapsibles, callouts, code blocks, diffs, GitHub annotations) and pure `plain`, `ansi`, `markdown` and `githubLog` renderers. `Doc.print` picks the renderer for the audience. `Render.contextOf` renders outside Effect, for example markdown for a step summary.
+- **`Doc` and `Render`**: a document IR (headings, paragraphs, lists, tables, trees, counts, count tables, collapsibles, callouts, code blocks, diffs, GitHub annotations) and pure `plain`, `ansi`, `markdown` and `githubLog` renderers. `Doc.print` picks the renderer for the audience, and lays out at the terminal's width only when the stream is a terminal: piped output (`tool | grep`) never wraps. `Doc.line(content, { wrap: false })` keeps one line whole at any width, glyph and colour included. `Render.contextOf` renders outside Effect, for example markdown for a step summary.
 - **`CliTheme`, `Token`, `Status`, `Glyphs`**: semantic tokens (`success`, `failure`, `warning`, `info`, `error`, `muted`, `accent`, `emphasis`), an extendable status vocabulary with glyphs and ranks, and Unicode or ASCII glyph sets. Override tokens with `env.theme`.
 - **`CliLinks`**: file links that open in VS Code (`vscode://file/…`) or as `file://` URLs, as OSC 8 hyperlinks where the terminal renders them, never for an agent.
 - **`Fmt`**: `sanitize`, `width`, `truncate`, `duration`, `percent` and `plural`.
@@ -132,7 +132,7 @@ Every string that enters a document or a message is sanitised: escape sequences
 
 ## Failures and exit codes
 
-`CliRuntime.main` reports a failure as a document on stderr, through the audience's renderer: a status line for a typed failure, a tree of rejected values for a schema failure, and a defect's message with a collapsible stack of your own frames (Effect's, Node's and `node_modules` frames hidden). Give an error class a `[CliDoc]()` method to draw itself, or pass a `render` option. Its `details.lines({ status: false })` keeps the run's colour and paths behind your own prefix.
+`CliRuntime.main` reports a failure as a document on stderr, through the audience's renderer: a status line for a typed failure, a tree of rejected values for a schema failure, and a defect's message with a collapsible stack of your own frames (Effect's, Node's and `node_modules` frames hidden). Give an error class a `[CliDoc]()` method to draw itself, or pass a `render` option. Its `details.lines({ status: false })` keeps the run's colour and paths behind your own prefix. The `in: outer › inner` span trail after a failure names only your own spans by default; `env.spans` (`"app"`, `"all"` or `"off"`) chooses, as `env.stackFrames` does for a defect's frames. `"app"` leaves out spans defined in files under `node_modules/@effected/` or `node_modules/effect/`, and fails open: a kit package linked into a workspace, or a bundled program, shows more, never less. A program that is itself installed under `node_modules/@effected/` passes its bin's `import.meta.url` as `env.appModule` to keep its own spans. `env.spansEnvVar` names a variable (say `TOOL_SPANS`) that sets it at run time, as `log.envVar` sets the level. An `Effect.fn` call and its definition are one entry in the trail.
 
 - `CliExit.set(code)` records a findings exit code from a handler that still succeeds. Do not provide `CliExit.layer` yourself under `main`, or the code goes to a second, unread cell.
 - `Cancelled` (a prompt quit) exits `130`, and `NotInteractive` (a prompt with nobody to ask) exits `64`, each as one fixed line.
@@ -143,7 +143,7 @@ Every string that enters a document or a message is sanitised: escape sequences
 
 ## Logging
 
-`CliLogger` writes plain lines, with no timestamp, level or fiber id, and routes every level to stderr by default (`stderrFrom` narrows it), so stdout carries only the program's output. Pass `env.log` to `main` for **`CliLog`**: a diagnostics level of its own (`level`, or `envVar` such as `TOOL_LOG_LEVEL`, with core's `--log-level` beating both), pretty lines for a person and NDJSON for an agent or CI, an optional NDJSON log file, and `CliLog.component(name)` tags.
+`CliLogger` writes plain lines, with no timestamp, level or fiber id, and routes every level to stderr by default (`stderrFrom` narrows it), so stdout carries only the program's output. Pass `env.log` to `main` for **`CliLog`**: a diagnostics level of its own (`level`, or `envVar` such as `TOOL_LOG_LEVEL`, with core's `--log-level` beating both), pretty lines for a person and NDJSON for an agent or CI, an optional NDJSON log file, and `CliLog.component(name)` tags. `CliLog.status(vocab, name, text)` logs a diagnostic with a painted status glyph (its text still sanitised), and `CliTheme.forAudience` applies the kit's "an agent never gets an escape" rule to a theme you paint with yourself.
 
 ## Prompts and screens
 
@@ -164,7 +164,7 @@ const profile = Flag.String("profile").pipe(
 );
 ```
 
-`@effected/cli/ui` adds Ink screens: `CliUi.run`, `prompt` (with an `otherwise`) and `fallback` (for a flag), over the widgets `Select`, `TextInput`, `MultiSelect`, `Confirm` (with toggles), `Toggle`, `Tabs` and `Viewport`. Your own screens use the key layer (`KeyTable`, `useKeys`, `KeyHelp`) and the theme bridge (`Styled`, `useTheme`, `useGlyphs`, `useTerminalSize`).
+`@effected/cli/ui` adds Ink screens: `CliUi.run`, `prompt` (with an `otherwise`) and `fallback` (for a flag), over the widgets `Select`, `TextInput` (with a `mask` for secrets, always, or from the moment a predicate spots one anywhere in the value, latched until the value is cleared: its `validate` message is drawn unmasked, so never echo the value in it), `MultiSelect`, `Confirm` (with toggles), `Toggle`, `Tabs` and `Viewport`. Your own screens use the key layer (`KeyTable`, `useKeys`, `KeyHelp`) and the theme bridge (`Styled`, `useTheme`, `useGlyphs`, `useTerminalSize`).
 
 ```tsx
 import { CliUi, Select } from "@effected/cli/ui";
@@ -180,14 +180,30 @@ const pickProfile = Select.screen({
 const profile = CliUi.prompt(pickProfile, { otherwise: "library" });
 ```
 
+`CliUi.map(screen, f)` maps a screen's answer and leaves a cancel alone, so a `Confirm` can back a boolean flag ("confirm, or `--yes`"):
+
+```ts
+import { CliUi, Confirm } from "@effected/cli/ui";
+import { Flag } from "effect/cli";
+
+const yes = Flag.Boolean("yes").pipe(
+  Flag.withFallbackPrompt(
+    CliUi.fallback(
+      CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
+      { flag: "yes", otherwise: false },
+    ),
+  ),
+);
+```
+
 ## Live views
 
-`CliUi.live` folds a stream or a `PubSub` subscription of events into state, and draws **runs** with Ink while they are going: a run starts at `isStart`, redraws on a tick, and commits its final frame at `isTerminal`. Log lines go above the frame through `handle.logConsole`. End with `handle.close`, which folds everything still queued. When nobody is watching (a pipe, an agent, CI), each run's final frame prints once instead. `DocView` draws a `Doc` document inside a view byte for byte as `Doc.print` would, and `UiProvider` with `CliUi.context` gives an Ink tree you mount yourself the same theme.
+`CliUi.live` folds a stream or a `PubSub` subscription of events into state, and draws **runs** with Ink while they are going: a run starts at `isStart`, redraws on a tick, and commits its final frame at `isTerminal`. Log lines go above the frame through `handle.logConsole`. End with `handle.close`, which folds everything still queued. When nobody is watching (a pipe, an agent, CI), each run's final frame prints once instead: give the view a `final: (state) => Document` and that run prints the document with no Ink or React loaded at all; `render` is then never called on such a run, not even to build an unused string. `render: CliUi.lazyView(() => import("./view.js"))` keeps the view's module, and React, off every run until one draws. `DocView` draws a `Doc` document inside a view byte for byte as `Doc.print` would, and `UiProvider` with `CliUi.context` gives an Ink tree you mount yourself the same theme.
 
 ## Testing
 
 - **`@effected/cli/testing`**: `CliTest.sandbox` and `CliTest.run` spawn a built bin hermetically and return `{ exitCode, stdout, stderr }` as data. `TestTerminal` drives core's prompts.
-- **`@effected/cli/ui/testing`**: `CliUiTest.render` mounts a screen on in-memory streams (`press`, `type`, `chunk`, `frame`, `result`). `view` mounts a display-only element, `session` drives a whole command's screens, and `live` mounts a live view on the production render path with a `TestClock` tick.
+- **`@effected/cli/ui/testing`**: `CliUiTest.render` mounts a screen on in-memory streams (`press`, `type`, `chunk`, `frame`, `result`). `view` mounts a display-only element, `session` drives a whole command's screens (its `transcript` shows what reached the terminal, a live view's `logConsole` lines included, `stdoutWritten`/`stderrWritten` each stream alone as raw bytes, `stdoutTranscript`/`stderrTranscript` each stream alone as plain text, and `renderPath: "production"` makes `clear` observable), and `live` mounts a live view on the production render path with a `TestClock` tick. `CliUiTest.serializer` prints frames as token markup in snapshots: register it in the Vitest config with `snapshotSerializers: ["@effected/cli/ui/testing/serializer"]`, or with `expect.addSnapshotSerializer`. Snapshots are the one place a test needs `expect`, since `assert` has no snapshot form.
 
 In-process, provide `layerTest`s from `@effected/env` and `CliTheme.layerTest`, swap in a capturing `Console`, and assert on both streams. Neither testing entrypoint is reachable from a CLI's runtime imports.
 

package/Render.js

@@ -3,7 +3,7 @@ import { CliLinks } from "./CliLinks.js";
 import { Glyphs } from "./Glyphs.js";
 import { paintStyle } from "./internal/ansi.js";
 import { Token } from "./Token.js";
-import { CliTheme, themeForAudience } from "./CliTheme.js";
+import { CliTheme } from "./CliTheme.js";
 import { renderAnsi } from "./internal/renderAnsi.js";
 import { renderPlain } from "./internal/renderPlain.js";
 import { renderGithubLog } from "./internal/renderGithubLog.js";
@@ -51,8 +51,9 @@ var Render = class {
 	*   gets an escape and a terminal without OSC 8 gets the label;
 	* - `neutralizeWorkflowCommands` is set when `CurrentRuntimeEnv` says GitHub Actions (read if present, not
 	*   required), for every audience, since the runner reads whatever is written there;
-	* - `width` is the option, else `TerminalEnv.width()` for a human, and **unbounded** (`Infinity`) for an agent
-	*   or a CI, so nothing a reader needs is truncated or wrapped for a terminal that is not there.
+	* - `width` is the option, else `TerminalEnv.width()` for a human whose stream is a terminal, and **unbounded**
+	*   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
+	*   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour.
 	*
 	* @param stream - the stream the output is for
 	* @param options - an explicit width and a path display function
@@ -61,11 +62,11 @@ var Render = class {
 		const terminal = yield* TerminalEnv;
 		const { kind } = yield* Audience;
 		const theme = (yield* CliTheme).forStream(stream);
-		const seen = themeForAudience(theme, kind);
+		const seen = CliTheme.forAudience(theme, kind);
 		const links = yield* CliLinks;
 		return {
 			...(yield* underGithubActions) ? { neutralizeWorkflowCommands: true } : {},
-			width: options?.width ?? (kind === "human" ? terminal.width() : Number.POSITIVE_INFINITY),
+			width: options?.width ?? (kind === "human" && terminal[stream].isTerminal ? terminal.width() : Number.POSITIVE_INFINITY),
 			audience: kind,
 			color: seen.color,
 			paint: seen.paint,

package/Status.js

@@ -1,3 +1,4 @@
+import { sanitize } from "./Fmt.js";
 import { Array, Option } from "effect";
 
 //#region src/Status.ts
@@ -119,14 +120,16 @@ var Status = class Status {
 	* that draws it itself (an Ink tree, a reporter).
 	*
 	* @remarks
-	* Throws on an unknown name, as {@link Status.def} does.
+	* Throws on an unknown name, as {@link Status.def} does. The glyph is sanitised, as text in a document is: escape
+	* sequences and control characters in a vocabulary's glyph are removed, so a glyph built from data cannot paint the
+	* terminal, plant a hyperlink or move the cursor. Every kit path that draws a status glyph takes it from here.
 	*
 	* @param name - a name in this vocabulary
 	* @param glyphs - the glyph set, such as `Glyphs.unicode`, `Glyphs.ascii` or a theme's
 	*/
 	glyph(name, glyphs) {
 		const def = this.def(name);
-		return glyphs.kind === "ascii" ? def.ascii : def.glyph;
+		return sanitize(glyphs.kind === "ascii" ? def.ascii : def.glyph);
 	}
 	/**
 	* The status with the highest rank; a tie goes to the one that comes first in `names`.