@effected/cli 0.22.2 → 0.23.0

package/CliEnv.js

@@ -1,6 +1,7 @@
 import { CliInteractive } from "./CliInteractive.js";
 import { ambientLinksLayer } from "./CliLinks.js";
 import { CliTheme } from "./CliTheme.js";
+import { displayPathLayer } from "./internal/displayPath.js";
 import { CliPrompt } from "./CliPrompt.js";
 import { ConfigProvider, Layer, Option } from "effect";
 import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
@@ -50,7 +51,7 @@ var CliEnv = class {
 			...options.editorLinksEnvVar === void 0 ? {} : { envVar: options.editorLinksEnvVar }
 		}).pipe(Layer.provideMerge(withTheme));
 		const withInteractive = CliInteractive.layer.pipe(Layer.provideMerge(withLinks));
-		return Layer.mergeAll(CliPrompt.gateTerminal, CliPrompt.gateWizard, CliTheme.promptTheme).pipe(Layer.provideMerge(withInteractive));
+		return Layer.mergeAll(CliPrompt.gateTerminal, CliPrompt.gateWizard, CliTheme.promptTheme, displayPathLayer(options.displayPath)).pipe(Layer.provideMerge(withInteractive));
 	};
 	/**
 	* The environment services a test fixes, needing nothing and reading nothing of the host's: `TerminalEnv` and

package/CliFailure.js

@@ -1,7 +1,9 @@
 import { Cancelled } from "./Cancelled.js";
 import { Fmt } from "./Fmt.js";
+import { identity } from "./internal/displayPath.js";
 import { Doc } from "./Doc.js";
 import { issueEntries, issueTreeChildren } from "./internal/format.js";
+import { failureText, readProperty, tagOf } from "./internal/inspect.js";
 import { splitFrame } from "./internal/splitFrame.js";
 import { NotInteractive } from "./NotInteractive.js";
 import { Status } from "./Status.js";
@@ -24,22 +26,7 @@ const CliDoc = Symbol.for("@effected/cli/CliDoc");
 const MAX_DEPTH = 8;
 const MAX_SPANS = 32;
 const hasCliDoc = (value) => typeof value === "object" && value !== null && typeof value[CliDoc] === "function";
-const describe = (value) => {
-	try {
-		const text = String(value);
-		if (text !== "[object Object]") return text;
-		const message = value?.message;
-		return typeof message === "string" ? message : text;
-	} catch {
-		return "[unprintable value]";
-	}
-};
 const firstLine = (text) => text.split(/\r\n|\r|\n/, 1)[0] ?? "";
-const tagOf = (value) => {
-	if (typeof value !== "object" || value === null) return void 0;
-	const tag = value._tag;
-	return typeof tag === "string" ? tag : void 0;
-};
 /** The failure status and the text of a message: one block per line, the status on the first. */
 const failureBlocks = (message) => {
 	const [first = "", ...rest] = message.split(/\r\n|\r|\n/);
@@ -48,15 +35,13 @@ const failureBlocks = (message) => {
 /** The issue of a schema failure: the value itself, or the `issue` an error carries. */
 const issueOf = (error) => {
 	if (SchemaIssue.isIssue(error)) return error;
-	if (typeof error === "object" && error !== null) {
-		const issue = error.issue;
-		if (SchemaIssue.isIssue(issue)) return issue;
-	}
+	const issue = readProperty(error, "issue");
+	return SchemaIssue.isIssue(issue) ? issue : void 0;
 };
 const schemaBlocks = (error) => {
 	const entries = issueEntries(issueOf(error));
 	if (entries.length === 0) return void 0;
-	const header = typeof error === "object" && error !== null && !SchemaIssue.isIssue(error) ? firstLine(describe(error.message ?? "")) : "";
+	const header = typeof error === "object" && error !== null && !SchemaIssue.isIssue(error) ? firstLine(failureText(readProperty(error, "message") ?? "")) : "";
 	const root = {
 		label: [
 			Doc.status(Status.core, "failure"),
@@ -138,7 +123,7 @@ const frameBlock = (frame, displayPath) => {
 	return Doc.paragraph(Doc.text("at ", "muted"), ...frame.fn === void 0 ? [] : [`${frame.fn} `], Doc.link(target, where));
 };
 const stackBlock = (defect, displayPath, mode) => {
-	const { frames, hidden } = cleanStack(defect.stack, mode);
+	const { frames, hidden } = cleanStack(readProperty(defect, "stack"), mode);
 	if (frames.length > 0) {
 		const shown = frames.map((frame) => frameBlock(frame, displayPath));
 		const note = hidden === 0 ? [] : [Doc.paragraph(Doc.text(`(+${hidden} internal frames hidden)`, "muted"))];
@@ -151,11 +136,11 @@ const stackBlock = (defect, displayPath, mode) => {
 const causeTree = (defect) => {
 	const chain = [];
 	const seen = /* @__PURE__ */ new Set([defect]);
-	for (let current = defect.cause; current !== void 0 && chain.length < MAX_DEPTH;) {
+	for (let current = readProperty(defect, "cause"); current !== void 0 && chain.length < MAX_DEPTH;) {
 		if (seen.has(current)) break;
 		seen.add(current);
-		chain.push(firstLine(describe(current)));
-		current = current instanceof Error ? current.cause : void 0;
+		chain.push(firstLine(failureText(current)));
+		current = current instanceof Error ? readProperty(current, "cause") : void 0;
 	}
 	if (chain.length === 0) return void 0;
 	const nest = (index) => index === chain.length - 1 ? { label: chain[index] } : {
@@ -163,13 +148,13 @@ const causeTree = (defect) => {
 		children: [nest(index + 1)]
 	};
 	return Doc.tree({
-		label: firstLine(describe(defect)),
+		label: firstLine(failureText(defect)),
 		children: [nest(0)]
 	});
 };
 const dieBlocks = (defect, spans, displayPath, mode) => {
 	if (defect instanceof Cancelled || defect instanceof NotInteractive) return [Doc.paragraph(defect.message)];
-	const header = failureBlocks(describe(defect));
+	const header = failureBlocks(failureText(defect));
 	if (!(defect instanceof Error)) return [...header, ...spans];
 	const chain = causeTree(defect);
 	return [
@@ -191,7 +176,7 @@ const failBlocks = (error, spans, options) => {
 	if (error instanceof Cancelled || error instanceof NotInteractive) return [Doc.paragraph(error.message)];
 	const schema = schemaBlocks(error);
 	if (schema !== void 0) return [...schema, ...spans];
-	return [...failureBlocks(describe(error)), ...spans];
+	return [...failureBlocks(failureText(error)), ...spans];
 };
 /** 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);
@@ -272,7 +257,8 @@ const spanBlocks = (reason, mode, appDir) => {
 * one line `interrupted`.
 *
 * All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
-* Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
+* Building it never throws: an error whose `_tag`, `message`, `stack`, `cause` or `issue` getter throws is drawn without
+* that part (an unreadable `stack` as `no stack`, an unreadable `cause` ending the chain there). Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
 *
 * @public
 */
@@ -287,7 +273,7 @@ var CliFailure = class {
 	static toDoc = (cause, options) => {
 		const reasons = cause.reasons;
 		if (reasons.length > 0 && reasons.every(Cause.isInterruptReason)) return [Doc.paragraph("interrupted")];
-		const displayPath = options?.displayPath ?? ((absolute) => absolute);
+		const displayPath = options?.displayPath ?? identity;
 		return reasons.flatMap((reason) => {
 			const spans = options?.spans ?? "app";
 			const appDir = packageDirOf(options?.appModule);

package/CliFormat.js

@@ -0,0 +1,69 @@
+import { underGithubActions } from "./internal/autoFormat.js";
+import { Doc } from "./Doc.js";
+import { neutralizeJson } from "./internal/logSafety.js";
+import { Console, Effect } from "effect";
+import { Flag } from "effect/cli";
+
+// src/CliFormat.ts
+/**
+* A `--format` flag and the one print that honours it, so a command builds its report once as a `Doc` and its data
+* once as a value, and never writes per-format output by hand.
+*
+* @remarks
+* The flag is core's `Flag.Literals` with the kit's names, default and description; the print hands every document
+* format to `Doc.print` and writes `json` itself.
+*
+* ```ts
+* const format = CliFormat.flag(["auto", "markdown", "json"])
+* const doctor = Command.make("doctor", { format }, ({ format }) =>
+*   CliFormat.print(format, { doc: () => report(results), json: () => results }),
+* )
+* ```
+*
+* @public
+*/
+var CliFormat = class {
+	constructor() {}
+	/**
+	* A `--format` flag offering `formats`.
+	*
+	* @remarks
+	* Its default is `options.default`, else `auto` when it is offered, else the first format. Any other value is a
+	* usage error from core's parser, naming the accepted ones.
+	*
+	* @param formats - the formats the command offers, at least one
+	* @param options - the default, the flag's name and its description
+	*/
+	static flag = (formats, options) => {
+		const fallback = options?.default ?? (formats.includes("auto") ? "auto" : formats[0]);
+		return Flag.Literals(options?.name ?? "format", formats).pipe(Flag.withDefault(fallback), Flag.withDescription(options?.description ?? `Output format: ${formats.join(", ")} (default ${fallback})`));
+	};
+	/**
+	* Print a command's output in `format`.
+	*
+	* @remarks
+	* `json` writes `output.json()` as JSON, one `Console.log` (or `Console.error` for stderr), indented by `indent`.
+	* Under GitHub Actions a `##[` inside it is written as the JSON escape `#\u0023[`, which decodes to the same text,
+	* so the runner cannot read it as a command. A value JSON cannot hold (a cycle, a bigint) is a defect. Every other
+	* format prints `output.doc()` with `Doc.print`, which renders it as `auto` or the named renderer would.
+	*
+	* @param format - the chosen format, usually the value of {@link CliFormat.flag}
+	* @param output - the document and the data
+	* @param options - the stream and the JSON indent
+	*/
+	static print = (format, output, options) => Effect.gen(function* () {
+		const stream = options?.stream ?? "stdout";
+		if (format !== "json") return yield* Doc.print(output.doc(), {
+			stream,
+			format
+		});
+		const data = output.json;
+		if (data === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.print: format json needs output.json"));
+		const text = yield* Effect.sync(() => JSON.stringify(data(), null, options?.indent ?? 2));
+		if (text === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.print: output.json() is not JSON"));
+		const safe = (yield* underGithubActions) ? neutralizeJson(text) : text;
+		yield* stream === "stdout" ? Console.log(safe) : Console.error(safe);
+	});
+};
+
+export { CliFormat };

package/CliLog.js

@@ -19,18 +19,20 @@ const indentOf = (indent) => {
 	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",
-	trace: "Trace",
-	debug: "Debug",
-	info: "Info",
-	warn: "Warn",
-	warning: "Warn",
-	error: "Error",
-	fatal: "Fatal",
-	none: "None"
-};
+/** The accepted spellings of a level, lower-cased, to the level they mean. A `Map`, so no inherited key matches. */
+const LEVELS = /* @__PURE__ */ new Map([
+	["all", "All"],
+	["trace", "Trace"],
+	["debug", "Debug"],
+	["info", "Info"],
+	["warn", "Warn"],
+	["warning", "Warn"],
+	["error", "Error"],
+	["fatal", "Fatal"],
+	["none", "None"]
+]);
+/** A level's spelling, in any case, to the level it means. */
+const parseLevel = (text) => Option.fromUndefinedOr(LEVELS.get(text.toLowerCase()));
 const LEVEL_STYLES = {
 	FATAL: {
 		fg: "red",
@@ -57,14 +59,14 @@ const readLevel = (explicit, envVar) => Effect.gen(function* () {
 		level: "None",
 		invalid: void 0
 	};
-	const level = LEVELS[raw.value.toLowerCase()];
-	if (level !== void 0) return {
-		level,
+	const level = parseLevel(raw.value);
+	if (Option.isSome(level)) return {
+		level: level.value,
 		invalid: void 0
 	};
 	return {
 		level: "None",
-		invalid: `${envVar}=${raw.value} is not a log level (${Object.keys(LEVELS).join("|")}); ignoring it`
+		invalid: `${envVar}=${raw.value} is not a log level (${[...LEVELS.keys()].join("|")}); ignoring it`
 	};
 });
 /**
@@ -149,6 +151,26 @@ var CliLog = class CliLog {
 	* cannot lower it below the level the layer installed, because Effect has already dropped those records.
 	*/
 	static Level = Level;
+	/**
+	* Read a log level the way `CliLog.layer` reads its environment variable: `Option.some` of the level, or
+	* `Option.none()` when the text is not one.
+	*
+	* @remarks
+	* Case-insensitive, and not trimmed. The spellings are `all`, `trace`, `debug`, `info`, `warn` (or `warning`),
+	* `error`, `fatal` and `none`. For a host that reads a level from its own flag or config and wants the same answer
+	* the layer would give.
+	*
+	* @example
+	* ```ts
+	* CliLog.parseLevel("WARNING") // Option.some("Warn")
+	* CliLog.parseLevel("loud") // Option.none()
+	* ```
+	*
+	* @param text - the level's spelling
+	*/
+	static parseLevel(text) {
+		return parseLevel(text);
+	}
 	static layer(options = {}) {
 		const file = "file" in options ? options.file : void 0;
 		const format = options.format ?? "auto";

package/CliRuntime.js

@@ -1,5 +1,6 @@
 import { Cancelled } from "./Cancelled.js";
 import { sanitize } from "./Fmt.js";
+import { failureText, tagOf } from "./internal/inspect.js";
 import { NotInteractive } from "./NotInteractive.js";
 import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget } from "./internal/failureTarget.js";
 import { CliColor } from "./CliColor.js";
@@ -11,24 +12,29 @@ 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, Logger, MutableRef, Runtime } from "effect";
-import { CliError } from "effect/cli";
+import { Cause, Effect, Layer, Logger, MutableRef, Option, Runtime } from "effect";
+import { CliError, CliOutput } from "effect/cli";
 import { CommandNeutralizer } from "@effected/github-commands";
+import { withDistribution, withDistributionVersion } from "@effected/engine";
 
 // src/CliRuntime.ts
 const isShowHelp = (u) => CliError.isCliError(u) && u._tag === "ShowHelp";
 /** A `UserError` `Command.runWith` already printed: it sets the mark to `false` after rendering. */
 const isRenderedUserError = (u) => CliError.isCliError(u) && u._tag === "UserError" && Runtime.getErrorReported(u) === false;
-/** The last line of defence of a failure report: the error's text, sanitised and neutralized, whatever else broke. */
-const lastResort = (error) => {
-	let text;
-	try {
-		text = String(error);
-	} catch {
-		text = "[unprintable failure]";
-	}
-	return CommandNeutralizer.lines(sanitize(text));
+/**
+* The program with `CurrentDistribution` set (engine's own `withDistribution`), and `--version` decorated with the
+* carrier's suffix (`withDistributionVersion`), wrapping whatever `formatVersion` is in effect rather than replacing a
+* coloured or custom one.
+*/
+const withCarrier = (program, distribution) => {
+	const provided = program.pipe(withDistribution(distribution));
+	return distribution === null ? provided : Effect.updateService(provided, CliOutput.Formatter, (formatter) => ({
+		...formatter,
+		formatVersion: withDistributionVersion(Option.some(distribution))(formatter.formatVersion)
+	}));
 };
+/** The last line of defence of a failure report: the error's text, sanitised and neutralized, whatever else broke. */
+const lastResort = (error) => CommandNeutralizer.lines(sanitize(failureText(error, "[unprintable failure]")));
 const toLines = (rendered) => typeof rendered === "string" ? [rendered] : rendered;
 /**
 * The error's own exit code when it carries one, otherwise the fallback.
@@ -39,7 +45,17 @@ const toLines = (rendered) => typeof rendered === "string" ? [rendered] : render
 * silently override a deliberate `1`. Testing for the marker keeps "the error
 * chose its code" distinct from "nothing chose".
 */
-const chooseExitCode = (error, fallback) => typeof error === "object" && error !== null && Runtime.errorExitCode in error ? Runtime.getErrorExitCode(error) : fallback ?? 1;
+const chooseExitCode = (error, fallback, byTag) => {
+	if (typeof error === "object" && error !== null && Runtime.errorExitCode in error) return Runtime.getErrorExitCode(error);
+	if (byTag === void 0) return fallback ?? 1;
+	const tag = tagOf(error);
+	return tag !== void 0 && Object.hasOwn(byTag, tag) ? byTag[tag] : fallback ?? 1;
+};
+/** Every `exitCodes` entry an integer in `1..255`, or a `RangeError` naming the first that is not. */
+const checkExitCodes = (exitCodes) => {
+	if (exitCodes === void 0) return;
+	for (const [tag, code] of Object.entries(exitCodes)) if (!isExitCode(code) || code === 0) throw new RangeError(`CliRuntime: exitCodes.${tag} must be an integer 1..255, received ${String(code)}`);
+};
 /**
 * Report a CLI program's failures through the program's own logger.
 *
@@ -148,43 +164,49 @@ var CliRuntime = class CliRuntime {
 	*
 	* @param options - how to render the failure and which exit codes to use
 	*/
-	static reportFailures = (options = {}) => (effect) => effect.pipe(Effect.catchCause((cause) => {
-		if (Cause.hasInterruptsOnly(cause)) return Effect.failCause(cause);
-		const error = Cause.squash(cause);
-		if (error instanceof ExitRequested) return Effect.fail(error);
-		if (isShowHelp(error)) {
-			const code = error.errors.length > 0 ? options.usageExitCode ?? 64 : 0;
-			return Effect.fail(CliRuntime.reported(error, code));
-		}
-		if (isRenderedUserError(error)) return Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.usageExitCode ?? 64)));
-		const render = options.render;
-		return Effect.gen(function* () {
-			const target = yield* currentTarget.pipe(Effect.catchCause(() => Effect.succeed(fallbackTarget)));
-			const reportLines = (status, spans) => {
-				try {
-					return linesOf(cause, target, status, spans ?? target.spans);
-				} catch {
+	static reportFailures = (options = {}) => {
+		checkExitCodes(options.exitCodes);
+		return (effect) => effect.pipe(Effect.catchCause((cause) => {
+			if (Cause.hasInterruptsOnly(cause)) return Effect.failCause(cause);
+			const error = Cause.squash(cause);
+			if (error instanceof ExitRequested) return Effect.fail(error);
+			if (isShowHelp(error)) {
+				const code = error.errors.length > 0 ? options.usageExitCode ?? 64 : 0;
+				return Effect.fail(CliRuntime.reported(error, code));
+			}
+			if (isRenderedUserError(error)) return Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.usageExitCode ?? 64)));
+			const render = options.render;
+			return Effect.gen(function* () {
+				const target = yield* currentTarget.pipe(Effect.catchCause(() => Effect.succeed(fallbackTarget)));
+				const reportLines = (status, spans) => {
 					try {
-						return plainFailureLines(cause, status, spans ?? target.spans);
+						return linesOf(cause, target, status, spans ?? target.spans);
 					} catch {
-						return lastResort(error);
+						try {
+							return plainFailureLines(cause, status, spans ?? target.spans);
+						} catch {
+							return lastResort(error);
+						}
 					}
-				}
-			};
-			const defaultLines = reportLines(true);
-			const details = {
-				cause,
-				isDefect: !Cause.hasFails(cause),
-				isCancelled: error instanceof Cancelled,
-				isNotInteractive: error instanceof NotInteractive,
-				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));
-			return yield* Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.exitCode)));
-		});
-	}));
+				};
+				const defaultLines = reportLines(true);
+				const isDefect = !Cause.hasFails(cause);
+				const exitCode = chooseExitCode(error, options.exitCode, isDefect ? void 0 : options.exitCodes);
+				const details = {
+					cause,
+					isDefect,
+					exitCode,
+					isCancelled: error instanceof Cancelled,
+					isNotInteractive: error instanceof NotInteractive,
+					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));
+				return yield* Effect.fail(CliRuntime.reported(error, exitCode));
+			});
+		}));
+	};
 	static main(program, options) {
 		const env = options.env === void 0 ? void 0 : CliEnv.layer(options.env);
 		const envLog = options.env?.log;
@@ -193,14 +215,14 @@ var CliRuntime = class CliRuntime {
 			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 carried = options.distribution === void 0 ? program : withCarrier(program, options.distribution);
 		const run = Effect.gen(function* () {
-			yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(program) : program;
+			yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(carried) : carried;
 			const exit = yield* CliExit;
 			const code = MutableRef.get(exit.code);
 			if (!isExitCode(code)) return yield* Effect.die(/* @__PURE__ */ new Error(`CliRuntime.main: CliExit code must be an integer 0..255, received ${code}`));

package/Fmt.js

@@ -1,5 +1,6 @@
-import { displayWidth, graphemes, stripAnsi } from "./internal/displayWidth.js";
-import { Duration, Option } from "effect";
+import { causeMessage } from "./internal/causeMessage.js";
+import { displayWidth, graphemes, isEscapeOnly, stripAnsi } from "./internal/displayWidth.js";
+import { Duration, Option, Predicate } from "effect";
 
 // src/Fmt.ts
 const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
@@ -137,6 +138,126 @@ var Fmt = class {
 	* @param plural - the noun otherwise; `singular` with an `s` appended by default
 	*/
 	static plural = (n, singular, plural) => `${n} ${n === 1 ? singular : plural ?? `${singular}s`}`;
+	/**
+	* Pad `text` to `width` terminal columns, measured as {@link Fmt.width} measures: a wide character counts two and
+	* an escape sequence none, so coloured text pads to the same column as plain text.
+	*
+	* @remarks
+	* Text already `width` columns or wider is returned unchanged: compose with {@link Fmt.truncate} to cut it. A
+	* `width` that is not a finite number pads nothing. Never throws.
+	*
+	* @param text - the text to pad
+	* @param width - the columns the result should take
+	* @param options - the alignment and the fill
+	*/
+	static pad = (text, width, options) => {
+		const missing = Number.isFinite(width) ? Math.floor(width) - displayWidth(text) : 0;
+		if (missing <= 0) return text;
+		const fill = options?.fill !== void 0 && displayWidth(options.fill) === 1 && stripAnsi(options.fill) === options.fill ? options.fill : " ";
+		switch (options?.align) {
+			case "right": return `${fill.repeat(missing)}${text}`;
+			case "center": {
+				const before = Math.floor(missing / 2);
+				return `${fill.repeat(before)}${text}${fill.repeat(missing - before)}`;
+			}
+			default: return `${text}${fill.repeat(missing)}`;
+		}
+	};
+	/**
+	* `text` without its escape sequences: CSI (colour, cursor moves, erases), OSC (titles, OSC 8 hyperlinks) ending in
+	* BEL or ST, the DCS, SOS, PM and APC strings, and every other escape, the nF sequences (`ESC ( B`) and the
+	* two-byte ones (`ESC 7`, `ESC 8`, `ESC =`, `ESC c`).
+	*
+	* @remarks
+	* The same strip {@link Fmt.width} and {@link Fmt.sanitize} start from. Only complete sequences go: a lone ESC, or
+	* any other control character, is kept, and so is an ESC in front of a lowercase letter other than `c`, which a
+	* stray ESC before a word would otherwise cost the word its first letter. An unterminated CSI or OSC keeps its `[`
+	* or `]`. Use {@link Fmt.sanitize} for text that will be laid out and printed.
+	*
+	* @param text - the text
+	*/
+	static stripAnsi = (text) => stripAnsi(text);
+	/**
+	* Whether `text` is nothing but escape sequences, as {@link Fmt.stripAnsi} reads them: a cursor hide or show, a
+	* clear-screen, an erase-scrollback. Empty text is not escape-only, and neither is a bare control character
+	* (`\r`, BEL), which is not an escape sequence.
+	*
+	* @param text - the text
+	*/
+	static isEscapeOnly = (text) => isEscapeOnly(text);
+	/**
+	* Integers as compact ranges: `[1, 2, 3, 5, 10, 11]` is `"1-3,5,10-11"`, a run of consecutive numbers written
+	* `start-end` and the rest one by one, joined with commas.
+	*
+	* @remarks
+	* The input is sorted and its duplicates dropped first, so order does not matter. Anything that is not a finite
+	* integer is left out, and no input is `""`. Never throws.
+	*
+	* @param numbers - the integers, such as line numbers
+	*/
+	static ranges = (numbers) => {
+		const sorted = [...new Set(Array.from(numbers).filter((n) => Number.isInteger(n)))].sort((a, b) => a - b);
+		const parts = [];
+		let index = 0;
+		while (index < sorted.length) {
+			const start = sorted[index];
+			let end = start;
+			while (index + 1 < sorted.length && sorted[index + 1] === end + 1) end = sorted[++index];
+			parts.push(start === end ? `${start}` : `${start}-${end}`);
+			index++;
+		}
+		return parts.join(",");
+	};
+	/**
+	* Any value as text, without ever throwing.
+	*
+	* @remarks
+	* A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
+	* `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
+	* `{ message }`) is that message. Anything else is its JSON, or `String(value)` when it has none (a cycle, a
+	* function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no message.
+	*
+	* The text is not sanitised: pass it through {@link Fmt.sanitize} before printing data you do not control. For
+	* the messages along an error's `cause` chain, use {@link Fmt.causeMessage}.
+	*
+	* @param value - the value
+	*/
+	static describe = (value) => {
+		if (Predicate.isString(value)) return value;
+		if (value === void 0 || value === null) return String(value);
+		if (typeof value !== "object" && typeof value !== "function") return String(value);
+		try {
+			if (Predicate.hasProperty(value, "message") && Predicate.isString(value.message)) return value.message;
+		} catch {}
+		try {
+			const json = JSON.stringify(value);
+			if (json !== void 0) return json;
+		} catch {}
+		try {
+			return String(value);
+		} catch {
+			return "[unprintable value]";
+		}
+	};
+	/**
+	* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
+	* `undefined` when nothing along it has one.
+	*
+	* @remarks
+	* The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
+	* is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
+	* another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
+	* repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
+	* `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost
+	* message alone. The walk stops after eight nodes, so a cyclic chain terminates.
+	*
+	* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
+	* the walk with the text found so far, `undefined` when there is none, so a caller's own fallback
+	* (`?? Fmt.describe(value)`) applies.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static causeMessage = (value) => causeMessage(value);
 };
 
 export { Fmt, sanitize };

package/Render.js

@@ -4,6 +4,7 @@ import { Glyphs } from "./Glyphs.js";
 import { paintStyle } from "./internal/ansi.js";
 import { Token } from "./Token.js";
 import { CliTheme } from "./CliTheme.js";
+import { CurrentDisplayPath, identity } from "./internal/displayPath.js";
 import { renderAnsi } from "./internal/renderAnsi.js";
 import { renderPlain } from "./internal/renderPlain.js";
 import { renderGithubLog } from "./internal/renderGithubLog.js";
@@ -62,6 +63,8 @@ var Render = class {
 	* - `groupDepth` is the fiber's count of open Actions log groups (the fiber-local keyed by
 	*   `WorkflowCommand.groupDepthKey`, which `ActionLogger.group` provides), set when it is above `0`, so a
 	*   document printed inside a group opens no second one; see {@link RenderContext.groupDepth}.
+	* - `displayPath` is the option, else the run's own path display (`CliEnvOptions.displayPath`, which
+	*   `CliEnv.layer` sets), else the identity.
 	*
 	* @param stream - the stream the output is for
 	* @param options - an explicit width and a path display function
@@ -87,7 +90,7 @@ var Render = class {
 				hyperlinks: terminal[stream].hyperlinks,
 				audience: kind
 			}),
-			displayPath: options?.displayPath ?? ((absolute) => absolute)
+			displayPath: options?.displayPath ?? (yield* CurrentDisplayPath)
 		};
 	});
 	/**
@@ -117,7 +120,7 @@ var Render = class {
 				hyperlinks: true,
 				audience: options.audience
 			}),
-			displayPath: options.displayPath ?? ((absolute) => absolute),
+			displayPath: options.displayPath ?? identity,
 			...options.neutralizeWorkflowCommands ?? options.audience === "ci" ? { neutralizeWorkflowCommands: true } : options.neutralizeWorkflowCommands === false ? { neutralizeWorkflowCommands: false } : {},
 			...options.linkBase === void 0 ? {} : { linkBase: options.linkBase },
 			...options.groupDepth === void 0 ? {} : { groupDepth: options.groupDepth }