@effected/cli 0.22.2 → 0.24.0

package/CliEnv.js

@@ -1,7 +1,9 @@
 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 { capabilitiesLayer } from "./internal/terminalCapabilities.js";
 import { ConfigProvider, Layer, Option } from "effect";
 import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
 
@@ -29,6 +31,15 @@ import { Audience, CurrentRuntimeEnv, TerminalEnv } from "@effected/env";
 * `Console` or `Stdio`, never `Terminal`. It also installs `CliTheme.promptTheme`, so core's prompts follow the
 * theme.
 *
+* It sets core's `TerminalCapabilities` from `TerminalEnv` (through `TerminalEnv.capabilities` in `@effected/env`), so
+* the colour of core's own help, version and error output follows the kit's colour rule, and `canAnimate` is stdout
+* being a terminal that is not `dumb`. `canPrompt` alone is held at `true` whatever the terminal is: core skips a
+* fallback prompt entirely when it is `false`, which would lose `CliPrompt.fallback`'s and `CliUi.fallback`'s
+* `otherwise` in every piped run, and `CliInteractive` with `CliPrompt.gateTerminal` already owns that decision (the
+* gate quits any other prompt at once when the run is not interactive). A `TerminalCapabilities` with
+* `canPrompt: false` provided inside the program bypasses the kit's fallbacks: the parameter then fails as missing even
+* when an `otherwise` is given.
+*
 * @public
 */
 var CliEnv = class {
@@ -49,14 +60,15 @@ var CliEnv = class {
 			...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));
+		const withCapabilities = capabilitiesLayer.pipe(Layer.provideMerge(withLinks));
+		const withInteractive = CliInteractive.layer.pipe(Layer.provideMerge(withCapabilities));
+		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
 	* `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`).
+	* `dumb`), and core's `TerminalCapabilities` from them as `CliEnv.layer` sets it, `canPrompt` held at `true`.
 	*
 	* @remarks
 	* `term` is handed to the theme and interactivity builds alone, through a `ConfigProvider` of their own: the
@@ -81,7 +93,8 @@ var CliEnv = class {
 			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));
+		const interactive = CliInteractive.layer.pipe(Layer.provideMerge(capabilitiesLayer));
+		return Layer.mergeAll(CliTheme.layer(options.theme), interactive).pipe(Layer.provide(term), Layer.provideMerge(facts));
 	};
 };
 

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,124 @@
+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
+const BUILT_IN = /* @__PURE__ */ new Set([
+	"auto",
+	"plain",
+	"ansi",
+	"markdown",
+	"githubLog",
+	"json"
+]);
+/**
+* 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.ChoiceWithValue` 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 CliFormat {
+	constructor() {}
+	/**
+	* A `--format` flag offering `formats`, and the caller's own `aliases` and `custom` 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. The value is the built-in format a name stands for
+	* (`human` under `{ human: "auto" }` is `auto`), or a custom name as itself, so the value of a flag with no custom
+	* formats goes straight to {@link CliFormat.print}.
+	*
+	* Two offered names that clash (an alias or custom name reusing a built-in name, or any name offered twice) and a
+	* default that is not offered are programming mistakes: the call throws. A CLI that still accepts a `--json` of its
+	* own declares and resolves that flag itself; {@link CliFormat.printJson} prints the JSON the same way.
+	*
+	* ```ts
+	* // okfit's contract: --format human|json, and a graph command that also draws mermaid and dot
+	* const format = CliFormat.flag(["json"], { aliases: { human: "auto" }, default: "human" })
+	* const graph = CliFormat.flag(["json"], { custom: ["mermaid", "dot"], default: "mermaid" })
+	* ```
+	*
+	* @param formats - the built-in formats the command offers under their own names, at least one
+	* @param options - the default, the flag's name and description, aliases and custom formats
+	*/
+	static flag = (formats, options) => {
+		const name = options?.name ?? "format";
+		const choices = [
+			...formats.map((format) => [format, format]),
+			...Object.entries(options?.aliases ?? {}).map(([alias, target]) => [alias, target]),
+			...(options?.custom ?? []).map((custom) => [custom, custom])
+		];
+		const offered = choices.map(([spelling]) => spelling);
+		for (const [index, spelling] of offered.entries()) {
+			if (offered.indexOf(spelling) !== index) throw new Error(`CliFormat.flag: the format name "${spelling}" is offered twice`);
+			if (index >= formats.length && BUILT_IN.has(spelling)) throw new Error(`CliFormat.flag: "${spelling}" is a built-in format, not an alias or a custom one`);
+		}
+		const fallback = options?.default ?? (offered.includes("auto") ? "auto" : formats[0]);
+		const fallbackChoice = choices.find(([spelling]) => spelling === fallback);
+		if (fallbackChoice === void 0) throw new Error(`CliFormat.flag: the default "${fallback}" is not one of ${offered.join(", ")}`);
+		const flag = Flag.ChoiceWithValue(name, choices).pipe(Flag.withDescription(options?.description ?? `Output format: ${offered.join(", ")} (default ${fallback})`));
+		return Flag.withDefault(flag, fallbackChoice[1]);
+	};
+	/**
+	* Print a command's output in `format`.
+	*
+	* @remarks
+	* `json` writes `output.json()` exactly as {@link CliFormat.printJson} writes a value, which it delegates to. 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"));
+		return yield* CliFormat.printJson(data(), options);
+	});
+	/**
+	* Print `value` as JSON, the way {@link CliFormat.print} prints the `json` format, for a CLI that keeps a JSON flag
+	* of its own.
+	*
+	* @remarks
+	* One `Console.log` (or `Console.error` for stderr), indented by `indent`: one document, never one line per item.
+	* 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, `undefined`) is a
+	* defect. It needs no theme, terminal or audience: whether this is GitHub Actions is read from `CurrentRuntimeEnv`
+	* when the environment has it, and is "no" otherwise.
+	*
+	* ```ts
+	* const status = Command.make("status", { json: Flag.Boolean("json").pipe(Flag.withDefault(false)) }, ({ json }) =>
+	*   json ? CliFormat.printJson(results) : Doc.print(report(results)),
+	* )
+	* ```
+	*
+	* @param value - the data to print
+	* @param options - the stream and the JSON indent
+	*/
+	static printJson = (value, options) => Effect.gen(function* () {
+		const text = yield* Effect.sync(() => JSON.stringify(value, null, options?.indent ?? 2));
+		if (text === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.printJson: the value is not JSON"));
+		const safe = (yield* underGithubActions) ? neutralizeJson(text) : text;
+		yield* (options?.stream ?? "stdout") === "stdout" ? Console.log(safe) : Console.error(safe);
+	});
+};
+
+export { CliFormat };

package/CliInteractive.js

@@ -1,6 +1,7 @@
 import { canPrompt } from "./internal/canPrompt.js";
 import { Context, Effect, Layer } from "effect";
 import { Audience, TerminalEnv } from "@effected/env";
+import { TerminalCapabilities } from "effect/cli";
 
 // src/CliInteractive.ts
 /**
@@ -21,6 +22,19 @@ import { Audience, TerminalEnv } from "@effected/env";
 * {@link CliInteractive.layerTest} are typed `Layer<never>`: they set the
 * reference rather than provide a service.
 *
+* Both layers also hold core's `TerminalCapabilities.canPrompt` at `true`,
+* keeping its `canColor` and `canAnimate` as they find them. Core skips a
+* `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` fallback entirely
+* when `canPrompt` is `false`, and decides that from the process's own
+* terminal, so a kit fallback (`CliPrompt.fallback`, `CliUi.fallback`) would
+* never be called in a piped run and its `otherwise` would be lost. With the
+* gate held open, this reference makes the prompt decision instead: the kit's
+* fallbacks answer without a person when it is `false`, and
+* `CliPrompt.gateTerminal` quits any other prompt at once. A
+* `TerminalCapabilities` with `canPrompt: false` provided inside the program,
+* under these layers, bypasses the kit's fallbacks again: the parameter fails
+* as missing even when an `otherwise` is given.
+*
 * @public
 */
 var CliInteractive = class CliInteractive extends Context.Reference("@effected/cli/CliInteractive", { defaultValue: () => false }) {
@@ -34,19 +48,21 @@ var CliInteractive = class CliInteractive extends Context.Reference("@effected/c
 	* as `@effected/env` reads the environment, so it adds no requirement; a test fixes it with
 	* `Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromUnknown({ TERM: "dumb" }))`.
 	*
+	* It also holds core's `TerminalCapabilities.canPrompt` at `true`; see {@link CliInteractive}.
+	*
 	* Bind the layer to a constant and provide it once; `Audience` and `TerminalEnv` come from `@effected/env`.
 	*/
-	static layer = Layer.effect(CliInteractive, Effect.gen(function* () {
+	static layer = Layer.effectContext(Effect.gen(function* () {
 		const audience = yield* Audience;
 		const terminal = yield* TerminalEnv;
-		return audience.kind === "human" && (yield* canPrompt(terminal));
+		return yield* decided(audience.kind === "human" && (yield* canPrompt(terminal)));
 	}));
 	/**
-	* A fixed answer that needs nothing.
+	* A fixed answer that needs nothing. It holds core's `canPrompt` open too, as {@link CliInteractive.layer} does.
 	*
 	* @param value - whether the run is interactive
 	*/
-	static layerTest = (value) => Layer.succeed(CliInteractive, value);
+	static layerTest = (value) => Layer.effectContext(decided(value));
 	/**
 	* Run `self` with interactivity switched off when `condition` holds.
 	*
@@ -66,5 +82,13 @@ var CliInteractive = class CliInteractive extends Context.Reference("@effected/c
 		return yield* Effect.provideService(self, CliInteractive, current && !condition);
 	});
 };
+/**
+* The context the two layers set: the decision, and core's capabilities as they are found with `canPrompt` held at
+* `true`, so core always hands a missing parameter to its fallback and the kit's decision governs.
+*/
+const decided = (interactive) => Effect.map(TerminalCapabilities.TerminalCapabilities, (capabilities) => Context.make(CliInteractive, interactive).pipe(Context.add(TerminalCapabilities.TerminalCapabilities, {
+	...capabilities,
+	canPrompt: true
+})));
 
 export { CliInteractive };

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/CliPrompt.js

@@ -36,6 +36,13 @@ var CliPrompt = class {
 	* input (core acquires it only when a prompt needs a key), so piped stdin is left untouched without any gate.
 	* `CliPrompt.gateTerminal`, which `CliEnv.layer` installs, covers the prompts this function does not wrap.
 	*
+	* Core calls a fallback only when its `TerminalCapabilities.canPrompt` is `true`, and its own default decides that
+	* from the process's terminal, so in a piped run it would fail the parameter as missing without calling this
+	* function and `otherwise` would be lost. `CliInteractive.layer` and `CliInteractive.layerTest` (and so
+	* `CliEnv.layer`) hold `canPrompt` at `true` for that reason: the decision is `CliInteractive`'s, made here. A
+	* `TerminalCapabilities` with `canPrompt: false` provided inside the program bypasses this fallback again, and a
+	* program that sets `CliInteractive` with neither layer keeps core's own gate.
+	*
 	* @param prompt - the prompt to show
 	* @param options - the parameter it stands in for, and the non-interactive default
 	*/

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,34 @@ 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));
+/**
+* A handler failure carrying a `CliError.userMessage` that `Command.runWith` already printed: it renders any such
+* failure and sets the mark to `false`, keeping the error's own tag.
+*/
+const isRenderedUserMessage = (u) => typeof u === "object" && u !== null && CliError.getUserMessage(u) !== void 0 && Runtime.getErrorReported(u) === false;
+/**
+* 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 +50,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.
 *
@@ -97,7 +118,10 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * already rendered through its `CliOutput` formatter. It exits with its own
 * `Runtime.errorExitCode` when it carries one, otherwise `usageExitCode`;
 * under runWith's `renderErrors: false` the mark stays set, and it renders
-* here like any other failure. Every other
+* here like any other failure. A handler failure carrying a
+* `CliError.userMessage` is skipped the same way, since `Command.runWith`
+* renders it and sets the mark to `false`; it keeps the exit code a
+* handler failure gets (`exitCodes` by tag, then `exitCode`). Every other
 * error renders even when it already carries the reported mark — a gate
 * failure marked with `CliRuntime.reported` still prints its line. The
 * private `ExitRequested` sentinel `CliRuntime.main`
@@ -148,43 +172,50 @@ 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)));
+			if (isRenderedUserMessage(error)) return Effect.fail(CliRuntime.reported(error, chooseExitCode(error, options.exitCode, options.exitCodes)));
+			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 +224,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}`));