@effected/cli 0.9.0 → 0.11.0

package/Cancelled.js

@@ -0,0 +1,44 @@
+import { Runtime, Schema } from "effect";
+
+//#region src/Cancelled.ts
+/**
+* A person backed out of an interactive prompt: they pressed escape, or the
+* prompt was interrupted.
+*
+* @remarks
+* Exits `130`, the conventional status for a run ended by the user, through
+* core's own `Runtime.errorExitCode` marker, so `CliRuntime.reportFailures`
+* keeps it. Its default rendering is one line, `cancelled; nothing written`,
+* because nothing has been written by the time a prompt is cancelled and a
+* stack trace would only alarm. A consumer `render` still overrides the line, and can hand off to it: the line is
+* the error's `message`, so `error.message` and `String(error)` carry it.
+*
+* @public
+*/
+var Cancelled = class extends Schema.TaggedError()("Cancelled", { reason: Schema.Literals(["escape", "interrupt"]) }) {
+	/**
+	* The one line, `cancelled; nothing written`.
+	*
+	* @remarks
+	* A prototype getter, not a field, so it is not part of the encoded form, equality or a JSON dump. Assigning to
+	* it is ignored: a library that rewrites `error.message` (to prefix a context, say) must not make this error throw,
+	* which a getter-only property does in strict mode. The line is fixed.
+	*/
+	get message() {
+		return "cancelled; nothing written";
+	}
+	set message(_value) {}
+	/**
+	* The process exit code: `130`.
+	*
+	* @remarks
+	* A prototype getter rather than an own field, so a JSON or logger dump of the error does not carry the
+	* runtime marker.
+	*/
+	get [Runtime.errorExitCode]() {
+		return 130;
+	}
+};
+
+//#endregion
+export { Cancelled };

package/CliAudience.js

@@ -0,0 +1,178 @@
+import { canPrompt } from "./internal/canPrompt.js";
+import { CliInteractive } from "./CliInteractive.js";
+import { refreshFailureTarget } from "./internal/failureTarget.js";
+import { scanAudience, tallyAudience } from "./internal/scanAudience.js";
+import { WizardDropped } from "./internal/wizardGate.js";
+import { Effect, Option, Stdio } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CliConfig, CliError, Command, Flag, GlobalFlag } from "effect/cli";
+
+//#region src/CliAudience.ts
+const KINDS = [
+	"human",
+	"agent",
+	"ci"
+];
+/**
+* Whether the run may prompt once a flag has named the audience.
+*
+* Only a `human` audience prompts, and only with a terminal on both standard input and standard output and a `TERM`
+* that is not `dumb` (`canPrompt`, the decision `CliInteractive.layer` makes). With the
+* terminal facts in the environment (`TerminalEnv`) that is decided from them, not from the ambient value, so a
+* flag can WIDEN: `--human` under a detected agent on real terminals prompts, and in a pipe it still cannot. With no
+* `TerminalEnv` there is nothing to decide from and the flag only narrows.
+*/
+const interactiveWhenFlagged = (kind, current) => Effect.flatMap(Effect.serviceOption(TerminalEnv), (terminal) => {
+	if (kind !== "human") return Effect.succeed(false);
+	return Option.isSome(terminal) ? canPrompt(terminal.value) : Effect.succeed(current);
+});
+const CONFLICT = "Give at most one of --audience, --human, --agent, --ci (once).";
+/** Resolve the four flags into the audience to provide, failing when more than one occurrence was given. */
+const resolve = (input) => {
+	const { given: named, conflict } = tallyAudience(input);
+	if (conflict) return Effect.fail(new CliError.UserError({
+		cause: /* @__PURE__ */ new Error(CONFLICT),
+		userMessage: CONFLICT
+	}));
+	const [kind] = named;
+	return kind === void 0 ? Audience : Effect.succeed({
+		kind,
+		source: "flag"
+	});
+};
+/**
+* The audience flags of a CLI: `--audience <human|agent|ci>` and the shorthands `--human`, `--agent`, `--ci`,
+* resolved into `@effected/env`'s `Audience`.
+*
+* @remarks
+* The one wiring: share the flags on the root command and hand the root to {@link CliAudience.run} (or
+* {@link CliAudience.runWith}), which resolves the flags from argv before core parses and applies
+* {@link CliAudience.provide} itself:
+*
+* ```ts
+* const root = Command.make("tool").pipe(
+*   Command.withSharedFlags(CliAudience.flags()),
+*   Command.withSubcommands([verify]),
+* )
+* NodeRuntime.runMain(
+*   CliRuntime.main(CliAudience.run(root, { version }), { platform: NodeServices.layer, env: {} }),
+* )
+* ```
+*
+* Core lists a shared flag in the help of every subcommand, not only at the root: that is upstream (Effect-TS/effect
+* issue 8642), and `flags({ hidden: true })` is the way to keep them out of help altogether.
+*
+* A root that forgot `Command.withSharedFlags(CliAudience.flags())` does not compile. Giving more than one
+* occurrence across the four flags is a usage error even when they agree; a boolean set to false (`--no-agent`,
+* `--agent=false`) counts as not given. A bad `--audience` value is core's own parse error. Both exit `64` under
+* `CliRuntime.main`. A conflicting audience together with `--help` exits `0` and prints help, because core handles
+* its action flags before the resolver runs.
+*
+* A flag decides `CliInteractive` from the audience it names and the terminal facts: `--human` is interactive when
+* `TerminalEnv` says there is a terminal on stdin and on stdout, even where the environment detected an agent, so a
+* person running the tool inside an agent can ask for the human experience; in a pipe it still cannot prompt. A
+* non-human flag (`--agent`, `--ci`, `--audience agent|ci`) turns it off and drops `--wizard`, and switches
+* diagnostics to NDJSON, for the whole run including the parse step where a fallback prompt fires. Without
+* `TerminalEnv` in the environment a flag only narrows. `--wizard` follows the decision: a run a flag makes
+* interactive gets it back where the environment's gate had dropped it, and only there: a consumer's own `builtIns`
+* without it stay without it.
+* {@link CliAudience.provide} on its own, the path for a bare `Command.run`, acts only on the subcommand handler,
+* because core parses the root flags into a local context before any of it is visible.
+*
+* @public
+*/
+var CliAudience = class CliAudience {
+	constructor() {}
+	/**
+	* The four flags, for `Command.withSharedFlags` on the root command.
+	*
+	* @remarks
+	* Each is repeatable, so every occurrence is counted; a boolean given as `false` (`--agent=false`,
+	* `--no-agent`) is not an occurrence. Core lists shared flags in every command's help; pass
+	* `hidden` to remove them from all of them.
+	*/
+	static flags = (options) => {
+		const hide = options?.hidden === true;
+		const maybeHide = (flag) => hide ? Flag.withHidden(flag) : flag;
+		return {
+			audience: maybeHide(Flag.Literals("audience", KINDS).pipe(Flag.atLeast(0), Flag.withDescription("Who the output is for"))),
+			human: maybeHide(Flag.Boolean("human").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience human"))),
+			agent: maybeHide(Flag.Boolean("agent").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience agent"))),
+			ci: maybeHide(Flag.Boolean("ci").pipe(Flag.atLeast(0), Flag.withDescription("Shorthand for --audience ci")))
+		};
+	};
+	/**
+	* Resolve the flags before every subcommand handler and re-provide `Audience`.
+	*
+	* @remarks
+	* `CliAudience.run` and `runWith` apply this themselves, so a program run through them never needs it. Use it
+	* directly only with a bare `Command.run`, which leaves a fallback prompt blind to the flags (see the class
+	* remarks).
+	*
+	* A failure report is written outside the run, where the flag is not in force, so only `runWith` and `run` carry
+	* the flag's audience to it; with this on its own the report follows the environment's audience.
+	*
+	* Pipe it onto the composite root, after `withSubcommands`, since a parent's handler does not run when a
+	* subcommand is selected. With exactly one flag the audience is `{ kind, source: "flag" }`; with none the
+	* ambient `Audience` is read and provided back unchanged, so `Audience` stays in the requirement a handler
+	* reading it already has, and is added to a program whose handlers do not read it.
+	*/
+	static provide = (command) => Command.provideEffect(command, Audience, (input) => resolve(input)).pipe(Command.provideEffect(CliInteractive, (input) => Effect.gen(function* () {
+		const current = yield* CliInteractive;
+		const [flagged] = tallyAudience(input).given;
+		return flagged === void 0 ? current : yield* interactiveWhenFlagged(flagged, current);
+	})));
+	/**
+	* Run a command the way `Command.runWith` does, with the audience flag resolved BEFORE core parses.
+	*
+	* @remarks
+	* It scans `argv` for the four audience flags first, then runs core around a provided `Audience` (when exactly
+	* one is given: `{ kind, source: "flag" }`) and a `CliInteractive` decided from it: `--human` is interactive when
+	* `TerminalEnv` reports a terminal on stdin and stdout and `TERM` is not `dumb` (it can turn prompting on under a detected agent), a
+	* non-human flag or a conflict makes it false. A fallback prompt fires while core parses, earlier than
+	* anything `CliAudience.provide` can reach, so `--agent init` on a terminal would otherwise still prompt. No
+	* flag leaves the ambient values untouched. A conflict still gets core's own usage error, exit `64`, from
+	* `CliAudience.provide`'s resolver.
+	*
+	* @param command - the composite root, with the flags shared and `CliAudience.provide` piped on
+	* @param config - the same `version` and `renderErrors` as core's
+	*/
+	static runWith = (command, config) => {
+		const core = Command.runWith(CliAudience.provide(command), config);
+		return (argv) => {
+			const run = core(argv);
+			const { given, conflict } = scanAudience(argv);
+			const [kind] = given;
+			if (kind === void 0) return run;
+			const withAudience = conflict ? run : Effect.provideService(run, Audience, {
+				kind,
+				source: "flag"
+			});
+			return Effect.gen(function* () {
+				const current = yield* CliInteractive;
+				const ambient = yield* CliConfig.CliConfig;
+				if (!conflict) yield* refreshFailureTarget({
+					kind,
+					source: "flag"
+				});
+				const interactive = !conflict && (yield* interactiveWhenFlagged(kind, current));
+				const decided = Effect.provideService(withAudience, CliInteractive, interactive);
+				const hasWizard = ambient.builtIns.includes(GlobalFlag.Wizard);
+				if (!(interactive && !hasWizard && (yield* WizardDropped) === ambient) && !(!interactive && hasWizard)) return yield* decided;
+				const builtIns = interactive ? [...ambient.builtIns, GlobalFlag.Wizard] : ambient.builtIns.filter((flag) => flag !== GlobalFlag.Wizard);
+				return yield* Effect.provideService(decided, CliConfig.CliConfig, CliConfig.make({ builtIns }));
+			});
+		};
+	};
+	/**
+	* `Command.run` with the audience flag resolved before parsing: reads `Stdio.args` and calls
+	* {@link CliAudience.runWith}.
+	*
+	* @param command - the composite root
+	* @param config - the same `version` and `renderErrors` as core's
+	*/
+	static run = (command, config) => Stdio.Stdio.use(({ args }) => Effect.flatMap(args, (argv) => CliAudience.runWith(command, config)(argv)));
+};
+
+//#endregion
+export { CliAudience };

package/CliColor.js

@@ -1,22 +1,23 @@
-import { Config, Effect, Layer, Option, Stdio } from "effect";
-import { CliOutput } from "effect/unstable/cli";
+import { Effect, Layer } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { CliOutput } from "effect/cli";
 
 //#region src/CliColor.ts
-const noColor = Config.option(Config.String("NO_COLOR"));
 /**
 * Whether a CLI's output should carry ANSI colour, decided once and shared by
 * everything that renders — help text, error output, and any rendered result.
 *
 * @remarks
-* Follows the no-color.org rule: colour is off when stdout is not a
-* terminal, or when `NO_COLOR` is set to any **non-empty** value — an empty
-* `NO_COLOR=""` does not disable colour. `FORCE_COLOR` is ignored, matching
-* core's own formatter. The environment is read through the ambient
-* `ConfigProvider`, never `process`, so a test swaps it with
-* `Effect.provideService(ConfigProvider.ConfigProvider, ...)`. The kit's
-* default providers (`fromEnv`, `fromUnknown`) already treat an empty
-* `NO_COLOR` as unset, so the explicit `set === ""` check exists for a
-* provider constructed with `{ preserveEmptyStrings: true }`.
+* The decision is `@effected/env`'s `TerminalEnv.colorLevel("stdout")`, which
+* follows Node's `getColorDepth` precedence: `FORCE_COLOR` first (`0` or an
+* unrecognised value forces colour off; an empty value, `1` or `true` force basic colour, `2` 256 colours and
+* `3` truecolor, even without a terminal), then a non-empty `NO_COLOR` or `NODE_DISABLE_COLORS` and
+* `TERM=dumb`, then the TTY gate. `FORCE_COLOR` therefore beats `NO_COLOR`.
+* The environment
+* is read through the ambient `ConfigProvider`, never `process`, so a test
+* swaps it with `Effect.provideService(ConfigProvider.ConfigProvider, ...)`;
+* an ambient `TerminalEnv`, such as `TerminalEnv.layerTest`, answers instead
+* when one is provided.
 *
 * @public
 */
@@ -27,14 +28,7 @@ var CliColor = class CliColor {
 	*
 	* @public
 	*/
-	static enabled = Effect.gen(function* () {
-		if (!(yield* (yield* Stdio.Stdio).stdoutIsTerminal)) return false;
-		const value = yield* noColor.pipe(Effect.orElseSucceed(() => Option.none()));
-		return Option.match(value, {
-			onNone: () => true,
-			onSome: (set) => set === ""
-		});
-	});
+	static enabled = TerminalEnv.colorLevel("stdout").pipe(Effect.map((level) => level !== "none"));
 	/**
 	* Core's default `CliOutput.Formatter`, coloured by the same decision as
 	* {@link CliColor.enabled}, so help text, parse errors and rendered

package/CliEnv.js

@@ -0,0 +1,89 @@
+import { CliInteractive } from "./CliInteractive.js";
+import { ambientLinksLayer } from "./CliLinks.js";
+import { CliTheme } from "./CliTheme.js";
+import { CliPrompt } from "./CliPrompt.js";
+import { ConfigProvider, Layer, Option } from "effect";
+import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
+
+//#region src/CliEnv.ts
+/**
+* The environment services a CLI reads, built once and in the right order.
+*
+* @remarks
+* Builds `CurrentRuntimeEnv`, `TerminalEnv`, `Audience`, `CliTheme` and `CliLinks`, and sets `CliInteractive` from them, then
+* installs the two gates for the program: `CliPrompt.gateTerminal`, which replaces `Terminal` with a quiet one when
+* the run is not interactive so no prompt runner ever attaches to stdin, and `CliPrompt.gateWizard`, which drops
+* `--wizard` then. `TerminalEnv` is built from the real terminal first. The layer therefore also outputs
+* `Terminal`, the gated one, and consumers never compose the gates themselves. A
+* `Context.Reference`'s key type is `never`, so the layer's output type does not list `CliInteractive`: it sets
+* the reference rather than providing a service. Every read of the environment goes through `Config` and
+* degrades to "unset" when it fails, so building the layer does not fail on a bad provider; it fails only when
+* `Stdio` or `Terminal` do.
+*
+* `CliLinks` reads `FileSystem` and `Path` from the surrounding context if it has them, and does not require them: a
+* `.vscode/` directory is looked for, and a relative path resolved, only when the platform is provided OUTSIDE this
+* layer, as `CliRuntime.main` does. Without them `auto` is `vscode` on the terminal signal alone.
+*
+* Not interactive, the gated `Terminal`'s `readLine` fails as a quit, its input is already ended and its `display`
+* writes nothing. A program that reads piped data must read `Stdio.stdin`, and one that writes output must use
+* `Console` or `Stdio`, never `Terminal`. It also installs `CliTheme.promptTheme`, so core's prompts follow the
+* theme.
+*
+* @public
+*/
+var CliEnv = class {
+	constructor() {}
+	/**
+	* The environment services for the terminal `Stdio` and `Terminal` describe.
+	*
+	* @remarks
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - the audience env var, the stderr check and the theme options
+	*/
+	static layer = (options = {}) => {
+		const base = Layer.mergeAll(CurrentRuntimeEnv.layer, TerminalEnv.layer(options.stderrIsTerminal === void 0 ? void 0 : { stderrIsTerminal: options.stderrIsTerminal }));
+		const withAudience = Audience.layer(options.audienceEnvVar === void 0 ? void 0 : { envVar: options.audienceEnvVar }).pipe(Layer.provideMerge(base));
+		const withTheme = CliTheme.layer(options.theme).pipe(Layer.provideMerge(withAudience));
+		const withLinks = ambientLinksLayer({
+			...options.editorLinks === void 0 ? {} : { editorLinks: options.editorLinks },
+			...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));
+	};
+	/**
+	* The environment services a test fixes, needing nothing and reading nothing of the host's: `TerminalEnv` and
+	* `Audience` from the answers given, `CliTheme` built from them as {@link CliEnv.layer} builds it, and
+	* `CliInteractive` set from them by the same rule (a human, every stream a terminal, and a `TERM` that is not
+	* `dumb`).
+	*
+	* @remarks
+	* `term` is handed to the theme and interactivity builds alone, through a `ConfigProvider` of their own: the
+	* program under the layer keeps its own provider, and a host's `TERM` (a test runner in a dumb terminal) never
+	* decides. A screen or a live view also needs `UiStreams` from `@effected/cli/ui`, which `CliUiTest` provides; this
+	* layer provides no `Terminal` and installs neither of `CliEnv.layer`'s prompt gates.
+	*
+	* A layer-returning function mints a fresh layer per call: call it once and bind the result to a constant.
+	*
+	* @param options - whether the streams are terminals, the `TERM`, the audience, the width, the colour and the theme
+	*/
+	static layerTest = (options = {}) => {
+		const tty = options.tty ?? false;
+		const stream = {
+			isTerminal: tty,
+			color: options.color ?? "none",
+			columns: options.columns === void 0 ? Option.none() : Option.some(options.columns)
+		};
+		const facts = Layer.mergeAll(TerminalEnv.layerTest({
+			stdinIsTerminal: tty,
+			stdout: stream,
+			stderr: stream
+		}), Audience.layerTest(options.audience ?? "human"));
+		const term = ConfigProvider.layer(ConfigProvider.fromUnknown(options.term === void 0 ? {} : { TERM: options.term }));
+		return Layer.mergeAll(CliTheme.layer(options.theme), CliInteractive.layer).pipe(Layer.provide(term), Layer.provideMerge(facts));
+	};
+};
+
+//#endregion
+export { CliEnv };

package/CliExit.js

@@ -11,7 +11,7 @@ import { Context, Effect, Layer, MutableRef } from "effect";
 * handler must return normally — yet the process must exit non-zero. Writing
 * `process.exitCode` works only because Node's `runMain` skips
 * `process.exit(0)` on success; `process.exit(n)` in a handler skips every
-* finalizer. {@link CliRuntime.main} reads this cell after the program
+* finalizer. `CliRuntime.main` reads this cell after the program
 * succeeds and turns a non-zero code into a marked failure the runtime's
 * teardown honours, on any runtime, with finalizers intact.
 *

package/CliFailure.js

@@ -0,0 +1,253 @@
+import { Cancelled } from "./Cancelled.js";
+import { Fmt } from "./Fmt.js";
+import { Doc } from "./Doc.js";
+import { issueEntries, issueTreeChildren } from "./internal/format.js";
+import { splitFrame } from "./internal/splitFrame.js";
+import { NotInteractive } from "./NotInteractive.js";
+import { Status } from "./Status.js";
+import { Cause, Context, SchemaIssue } from "effect";
+
+//#region src/CliFailure.ts
+/**
+* The protocol an error class implements to say how a failure is shown: a method under this key that returns the
+* document.
+*
+* @remarks
+* `CliFailure.toDoc` calls it for a typed failure that has one, so an application error draws itself (a heading, a
+* table of what went wrong) and the default report uses it with no registration. A `Symbol.for` key, so two copies
+* of this package agree on it.
+*
+* @public
+*/
+const CliDoc = Symbol.for("@effected/cli/CliDoc");
+/** The deepest an `Error.cause` chain, or a stack, is followed. */
+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/);
+	return [Doc.paragraph(Doc.status(Status.core, "failure"), " ", first), ...rest.map((line) => Doc.paragraph(line))];
+};
+/** 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 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 root = {
+		label: [
+			Doc.status(Status.core, "failure"),
+			" ",
+			header === "" ? `invalid value (${Fmt.plural(entries.length, "problem")})` : header
+		],
+		children: issueTreeChildren(entries)
+	};
+	return [Doc.tree(root)];
+};
+/** The location of a frame as a path: a `file:` URL decoded, or an absolute POSIX or drive path; else `undefined`. */
+const asPath = (location) => {
+	if (location.startsWith("file:")) try {
+		const path = decodeURIComponent(new URL(location).pathname);
+		return /^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path;
+	} catch {
+		return;
+	}
+	return location.startsWith("/") || /^[A-Za-z]:[\\/]/.test(location) ? location : void 0;
+};
+/** A location without its `:line:col`, and the position when there is one. */
+const splitPosition = (location) => {
+	const position = /^(.*):(\d+):(\d+)$/.exec(location);
+	return position === null ? { where: location } : {
+		where: position[1] ?? "",
+		line: Number(position[2]),
+		col: Number(position[3])
+	};
+};
+const parseFrame = (raw) => {
+	const { text, fn, location } = splitFrame(raw);
+	const { where, line, col } = splitPosition(location);
+	const file = asPath(where);
+	return {
+		raw: text,
+		...fn === void 0 ? {} : { fn },
+		...file === void 0 ? {} : { file },
+		...file === void 0 || line === void 0 || col === void 0 ? {} : {
+			line,
+			col
+		}
+	};
+};
+/** The file a frame ran in, as a path, or `undefined` for a frame with none: `node:`, `<anonymous>`, `native`, `eval`. */
+const frameFile = (raw) => asPath(splitPosition(splitFrame(raw).location).where);
+/** A frame under `node_modules`: a dependency's, or an installed program's own. Decided by its file alone. */
+const isDependency = (raw) => /[\\/]node_modules[\\/]/.test(frameFile(raw) ?? "");
+/**
+* A frame that is the runtime's or Effect's, never the program's, wherever the program is installed: one with no file
+* (every `node:` frame, `<anonymous>`, native), or one in Effect's own files. Decided by the file alone, never by the
+* function name: V8 names a program's own thunk by Effect's method alias (`boom [as ~effect/Effect/args]`).
+*/
+const isRuntime = (raw) => {
+	const file = frameFile(raw);
+	return file === void 0 || /[\\/]node_modules[\\/]effect[\\/]/.test(file) || /[\\/]packages[\\/]effect[\\/]src[\\/]/.test(file);
+};
+/** The frames of a stack that belong to the program, and how many were left out. */
+const cleanStack = (stack, mode) => {
+	if (typeof stack !== "string") return {
+		frames: [],
+		hidden: 0
+	};
+	const lines = stack.split(/\r\n|\r|\n/).filter((line) => /^\s*at\s/.test(line));
+	const app = lines.filter((line) => !isRuntime(line) && !isDependency(line));
+	const kept = mode === "all" ? lines : app.length > 0 ? app : lines.filter((line) => !isRuntime(line));
+	return {
+		frames: kept.map(parseFrame),
+		hidden: lines.length - kept.length
+	};
+};
+const frameBlock = (frame, displayPath) => {
+	if (frame.file === void 0) return Doc.paragraph(Doc.text("at ", "muted"), frame.raw);
+	const where = `${displayPath(frame.file)}${frame.line === void 0 ? "" : `:${frame.line}:${frame.col}`}`;
+	const target = {
+		file: frame.file,
+		...frame.line === void 0 ? {} : { line: frame.line },
+		...frame.col === void 0 ? {} : { col: frame.col }
+	};
+	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);
+	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"))];
+		return Doc.collapsible("stack", [...shown, ...note], { open: true });
+	}
+	const note = hidden === 0 ? "no stack" : `no user frames (${hidden} internal frames hidden)`;
+	return Doc.collapsible("stack", [Doc.paragraph(Doc.text(note, "muted"))], { open: true });
+};
+/** The `Error.cause` chain below a defect as a tree of one-line messages, or none. */
+const causeTree = (defect) => {
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set([defect]);
+	for (let current = 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;
+	}
+	if (chain.length === 0) return void 0;
+	const nest = (index) => index === chain.length - 1 ? { label: chain[index] } : {
+		label: chain[index],
+		children: [nest(index + 1)]
+	};
+	return Doc.tree({
+		label: firstLine(describe(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));
+	if (!(defect instanceof Error)) return [...header, ...spans];
+	const chain = causeTree(defect);
+	return [
+		...header,
+		...spans,
+		stackBlock(defect, displayPath, mode),
+		...chain === void 0 ? [] : [chain]
+	];
+};
+const failBlocks = (error, spans, options) => {
+	if (hasCliDoc(error)) try {
+		return [...error[CliDoc](), ...spans];
+	} catch {}
+	const tag = tagOf(error);
+	const custom = tag === void 0 || options?.render === void 0 || !Object.hasOwn(options.render, tag) ? void 0 : options.render[tag];
+	if (custom !== void 0) try {
+		return [...custom(error), ...spans];
+	} catch {}
+	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];
+};
+/** `in: outer › inner`, from the span stack the runtime annotates a reason with, or none. */
+const spanBlocks = (reason) => {
+	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;
+	}
+	if (names.length === 0) return [];
+	return [Doc.paragraph(Doc.text("in: ", "muted"), Doc.path(...names.reverse()))];
+};
+/**
+* A failure as a document: what the default report prints, and a building block for a custom one.
+*
+* @remarks
+* One run of blocks per `Cause` reason. A typed failure is, in order of preference: the document of an error that
+* implements {@link CliDoc}; the document `options.render` holds for its `_tag`; for `Cancelled` and
+* `NotInteractive`, their one fixed line; a `Tree` of the rejected values, for a schema error or issue; else a failure
+* status line with its message. A defect is its message followed by a collapsible `stack` of the program's own frames,
+* each a file link (so a terminal can open it in an editor) shown through `displayPath`, with the runtime's frames (every
+* `node:` frame and every frame with no file) and every `node_modules` frame (Effect's and any other dependency's)
+* left out unless `stackFrames` is `all`. A frame is classified by its file alone, never by its function name, so a
+* program's own thunk that V8 names by Effect's method alias is still shown. When that would
+* leave no frame at all, as for a program run from its own install under `node_modules`, only the runtime's and
+* Effect's are left out. Then an
+* `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
+* 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.
+*
+* @public
+*/
+var CliFailure = class {
+	constructor() {}
+	/**
+	* Build the document of a cause.
+	*
+	* @param cause - the failure
+	* @param options - per-tag documents and a path display function
+	*/
+	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);
+		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");
+			return [];
+		});
+	};
+};
+
+//#endregion
+export { CliDoc, CliFailure };