@effected/cli 0.10.0 → 0.11.0

package/CliMessage.js

@@ -0,0 +1,83 @@
+import { underGithubActions } from "./internal/autoFormat.js";
+import { sanitize } from "./Fmt.js";
+import { CliTheme } from "./CliTheme.js";
+import { Status } from "./Status.js";
+import { Console, Effect } from "effect";
+import { Audience } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+//#region src/CliMessage.ts
+/**
+* One-line status messages: a glyph and some text, themed for a person and plain for an agent.
+*
+* @remarks
+* Each line goes through `Console`, `log` for stdout and `error` for stderr, never through the logger, so no
+* log level can silence it. Only the glyph is painted; the text stays plain. An `agent` audience gets the glyph
+* and the text and never colour, even when the theme has colour. `success` and `info` go to stdout, `warning`
+* and `failure` to stderr.
+*
+* The text is whatever the caller supplies, so it is sanitised: escape sequences and control characters are removed
+* (a line break is kept as one, a tab becomes a space), as in a document. Under GitHub Actions, where
+* `CurrentRuntimeEnv` says so, a line the runner would read as a workflow command is neutralized as well. The glyphs
+* come from the vocabulary, which is configuration, and are not.
+*
+* @public
+*/
+var CliMessage = class CliMessage {
+	constructor() {}
+	/**
+	* Print a status line from a vocabulary.
+	*
+	* @remarks
+	* The stream defaults to stderr when the status ranks at or above `warning` in `vocab`, and stdout
+	* otherwise, so a custom status follows its own rank: a `timeout` ranked 85 goes to stderr.
+	*
+	* @param vocab - the vocabulary the status belongs to
+	* @param name - the status
+	* @param text - the text after the glyph
+	* @param options - the stream override
+	*/
+	static status = (vocab, name, text, options) => Effect.gen(function* () {
+		const theme = yield* CliTheme;
+		const audience = yield* Audience;
+		const def = vocab.def(name);
+		const message = sanitize(text);
+		const warning = vocab.def("warning").rank;
+		const stream = options?.stream ?? (def.rank >= warning ? "stderr" : "stdout");
+		const streamTheme = theme.forStream(stream);
+		let line;
+		if (audience.kind === "agent") {
+			const glyph = streamTheme.glyphs.kind === "ascii" ? def.ascii : def.glyph;
+			line = message === "" ? glyph : `${glyph} ${message}`;
+		} else line = streamTheme.status(vocab, name, message);
+		if (yield* underGithubActions) line = CommandNeutralizer.text(line);
+		yield* stream === "stderr" ? Console.error(line) : Console.log(line);
+	});
+	/**
+	* A success line, on stdout.
+	*
+	* @param text - the text after the glyph
+	*/
+	static success = (text) => CliMessage.status(Status.core, "success", text);
+	/**
+	* An informational line, on stdout.
+	*
+	* @param text - the text after the glyph
+	*/
+	static info = (text) => CliMessage.status(Status.core, "info", text);
+	/**
+	* A warning line, on stderr.
+	*
+	* @param text - the text after the glyph
+	*/
+	static warning = (text) => CliMessage.status(Status.core, "warning", text);
+	/**
+	* A failure line, on stderr.
+	*
+	* @param text - the text after the glyph
+	*/
+	static failure = (text) => CliMessage.status(Status.core, "failure", text);
+};
+
+//#endregion
+export { CliMessage };

package/CliPrompt.js

@@ -0,0 +1,104 @@
+import { Cancelled } from "./Cancelled.js";
+import { CliInteractive } from "./CliInteractive.js";
+import { WizardDropped } from "./internal/wizardGate.js";
+import { answerWithoutPerson } from "./internal/fallbackAnswer.js";
+import { Context, Effect, Layer, Queue, Terminal } from "effect";
+import { CliConfig, GlobalFlag, Prompt } from "effect/cli";
+
+//#region src/CliPrompt.ts
+/**
+* Prompts that know whether there is a person to ask.
+*
+* @public
+*/
+var CliPrompt = class {
+	constructor() {}
+	/**
+	* A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that only prompts when the run is
+	* interactive.
+	*
+	* @remarks
+	* Interactive (`CliInteractive`): the prompt runs and its answer is used. Not interactive: `otherwise` is used
+	* when given, and the terminal is never read; without it the parameter fails as missing, exactly as it would
+	* with no fallback, so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with
+	* `flag` (the name without dashes, as given to `Flag.String`) or `argument` so that error can be built.
+	*
+	* Why the prompt runs inside this function rather than being handed back to core: core's
+	* `withFallbackPrompt` turns a quit, such as Ctrl-C, into the original missing-parameter error, which would
+	* exit `64` as if the flag had been forgotten. Here a quit is `Cancelled` with reason `interrupt`, exit `130`.
+	* It is raised as a defect because core's parse step turns every typed failure into a usage error. Core then
+	* runs the already-answered `Prompt.succeed` it is handed. Because it travels as a defect, a handler's
+	* `Effect.catchTag("Cancelled", ...)` cannot see it, and only `CliRuntime.main` (or
+	* `CliRuntime.reportFailures`) renders it as one line with exit `130`; under a bare `runMain` it prints a
+	* stack.
+	*
+	* Pair it with `CliPrompt.gateTerminal`, which `CliEnv.layer` installs: core still runs `Prompt.run` on the
+	* answered prompt it is handed, and `Prompt.run` subscribes the terminal's input, which on a real terminal
+	* attaches a reader to stdin and drops piped input. The gate makes that subscription harmless when the run is
+	* not interactive.
+	*
+	* @param prompt - the prompt to show
+	* @param options - the parameter it stands in for, and the non-interactive default
+	*/
+	static fallback = (prompt, options) => Effect.gen(function* () {
+		if (yield* CliInteractive) {
+			const answer = yield* Prompt.run(prompt).pipe(Effect.catchTag("QuitError", () => Effect.die(new Cancelled({ reason: "interrupt" }))));
+			return Prompt.succeed(answer);
+		}
+		return yield* answerWithoutPerson(options);
+	});
+	/**
+	* Gates core's `Terminal` on `CliInteractive`, so a run that is not interactive never touches the real one.
+	*
+	* @remarks
+	* Core's prompt runner subscribes the terminal's input even for a prompt that is already answered, and the
+	* real Node terminal then attaches a readline to stdin, which drops piped input and puts a TTY stdin into raw
+	* mode. Not interactive, this terminal's input is an already-ended queue, its `readLine` fails as quit and its
+	* `display` writes nothing, so any prompt, the wizard included, is quit at once and the real terminal is never
+	* read. Its `columns` and `rows` always come from the real one, so layout keeps working. Interactive, every
+	* call passes through to the real terminal.
+	*
+	* The decision is made on every call, not when the layer is built, so a scope that narrows `CliInteractive`
+	* later, such as an audience flag under `CliAudience.runWith`, gates it too.
+	*
+	* It requires the real `Terminal`. `CliEnv.layer` installs it, after `TerminalEnv` is built from the real
+	* terminal, so consumers do not compose it.
+	*/
+	static gateTerminal = Layer.effect(Terminal.Terminal, Effect.gen(function* () {
+		const real = yield* Terminal.Terminal;
+		const endedInput = Effect.map(Queue.unbounded(), (queue) => {
+			Queue.endUnsafe(queue);
+			return queue;
+		});
+		return Terminal.make({
+			columns: real.columns,
+			rows: real.rows,
+			readInput: Effect.flatMap(CliInteractive, (interactive) => interactive ? real.readInput : endedInput),
+			readLine: Effect.flatMap(CliInteractive, (interactive) => interactive ? real.readLine : Effect.fail(new Terminal.QuitError({}))),
+			display: (text) => Effect.flatMap(CliInteractive, (interactive) => interactive ? real.display(text) : Effect.void)
+		});
+	}));
+	/**
+	* Drops core's `--wizard` built-in flag when the run is not interactive.
+	*
+	* @remarks
+	* The wizard prompts, so offering it without a terminal only leads to a dead end. With the flag gone, core
+	* treats `--wizard` as an unknown flag, a usage error that exits `64`, and lists it nowhere in `--help`.
+	* The layer reads `CliInteractive` and the ambient `CliConfig` when it is built, so provide those first, for
+	* example `CliPrompt.gateWizard.pipe(Layer.provide(CliInteractive.layer))`. It filters the ambient `CliConfig`,
+	* so a consumer's own `builtIns` survive, and returns it untouched when interactive. An audience flag read
+	* later is covered by `CliAudience.runWith`, which drops the wizard too. When this layer removes the flag it records
+	* that it did, so `runWith` puts it back only when a flag turns interactivity on where this took it away: a
+	* consumer who never had `Wizard` in their `builtIns` keeps it out.
+	*/
+	static gateWizard = Layer.effectContext(Effect.gen(function* () {
+		const ambient = yield* CliConfig.CliConfig;
+		const unchanged = Context.make(CliConfig.CliConfig, ambient);
+		if ((yield* CliInteractive) || !ambient.builtIns.includes(GlobalFlag.Wizard)) return unchanged;
+		const dropped = CliConfig.make({ builtIns: ambient.builtIns.filter((flag) => flag !== GlobalFlag.Wizard) });
+		return Context.make(CliConfig.CliConfig, dropped).pipe(Context.add(WizardDropped, dropped));
+	}));
+};
+
+//#endregion
+export { CliPrompt };

package/CliRuntime.js

@@ -1,15 +1,32 @@
+import { sanitize } from "./Fmt.js";
+import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, refreshFailureTarget } from "./internal/failureTarget.js";
+import { CliColor } from "./CliColor.js";
+import { CliEnv } from "./CliEnv.js";
 import { isExitCode } from "./internal/isExitCode.js";
 import { CliExit } from "./CliExit.js";
+import { TrustedLine } from "./internal/logSafety.js";
 import { CliLogger } from "./CliLogger.js";
+import { CliLog, envBuildLogLayer, platformLogLayer } from "./CliLog.js";
 import { ExitRequested } from "./internal/ExitRequested.js";
 import { routeHelpOnUsageError } from "./internal/HelpRouting.js";
-import { Cause, Effect, MutableRef, Runtime } from "effect";
+import { Cause, Effect, Layer, MutableRef, Runtime } from "effect";
 import { CliError } from "effect/cli";
+import { CommandNeutralizer } from "@effected/github-commands";
 
 //#region 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));
+};
 const toLines = (rendered) => typeof rendered === "string" ? [rendered] : rendered;
 /**
 * The error's own exit code when it carries one, otherwise the fallback.
@@ -25,7 +42,7 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * Report a CLI program's failures through the program's own logger.
 *
 * @remarks
-* ## The bug this exists to prevent
+* ## What it prevents
 *
 * A platform `runMain` reports an unhandled failure using Effect's **default**
 * logger. That logger sits **outside** the layers the program was provided —
@@ -42,18 +59,7 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 *
 * The fix has to happen **inside** the effect, before any `runMain` sees it. So
 * this is a combinator you apply to your program, and you still call your own
-* platform's runner:
-*
-* @example
-* ```ts
-* import { CliRuntime } from "@effected/cli"
-* import { NodeRuntime } from "@effect/platform-node"
-* import { Effect } from "effect"
-*
-* NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
-* ```
-*
-* Wrapping `runMain` itself would drag a platform choice into a library that
+* platform's runner. Wrapping `runMain` itself would drag a platform choice into a library that
 * has no business making one, and would make this package unusable from Bun or
 * Deno for no gain.
 *
@@ -96,13 +102,49 @@ const chooseExitCode = (error, fallback) => typeof error === "object" && error !
 * raises is likewise never rendered; it only carries the exit code a
 * successful program recorded through `CliExit`.
 *
+* @example
+* ```ts
+* import { CliRuntime } from "@effected/cli"
+* import { NodeRuntime } from "@effect/platform-node"
+* import { Effect } from "effect"
+*
+* NodeRuntime.runMain(program.pipe(CliRuntime.reportFailures(), Effect.provide(MainLive)))
+* ```
+*
 * @public
 */
 var CliRuntime = class CliRuntime {
 	constructor() {}
 	/**
-	* Catch, render through the ambient logger, and re-fail with the exit code
-	* and the no-double-report mark.
+	* What `reportFailures` and `main` render a failure as when no `render` option is given, for a consumer's own
+	* `render` to hand a failure back to.
+	*
+	* @remarks
+	* The plain lines of `CliFailure.toDoc(details.cause)`: a failure status line, a `Tree` for a schema failure, a
+	* defect's message with its cleaned `stack`, and the one fixed line each for `Cancelled` and `NotInteractive`.
+	* It has no terminal to ask, so it is the plain rendering for an agent, with absolute paths; the report `main` writes
+	* with no `render` option is the same document in the renderer the audience gets (painted for a person), and that
+	* report is `details.defaultLines`: return those to hand a failure back with the run's colour, links and path
+	* display. With `status: false` the leading status (the glyph, or `[FAIL]` in plain text) is left off, so a prefix
+	* such as the program's name reads cleanly; for that AND the run's settings, use `details.lines({ status: false })`.
+	* A custom `render` that only cares about its own errors delegates the rest:
+	*
+	* ```ts
+	* const render = (error: unknown, details: FailureDetails) =>
+	*   error instanceof MyError ? myLines(error) : CliRuntime.defaultRender(error, details)
+	* ```
+	*
+	* @param error - the squashed failure
+	* @param details - what `render` is told about the failure; accepted so a delegating `render` passes both
+	*   arguments through unchanged (only `cause` and `isDefect` are read)
+	* @param options - `status: false` leaves off the leading status glyph or `[FAIL]` tag
+	*/
+	static defaultRender = (error, details, options) => plainFailureLines(details.cause.reasons.length > 0 ? details.cause : Cause.fail(error), options?.status !== false);
+	/**
+	* Catch a program's failure, render it through the ambient logger, and re-fail with the exit code and the
+	* no-double-report mark.
+	*
+	* @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);
@@ -113,50 +155,58 @@ var CliRuntime = class CliRuntime {
 			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 ?? ((value) => String(value));
-		const details = {
-			cause,
-			isDefect: !Cause.hasFails(cause)
-		};
+		const render = options.render;
 		return Effect.gen(function* () {
-			for (const line of toLines(render(error, details))) yield* Effect.logError(line);
+			const target = yield* currentTarget.pipe(Effect.catchCause(() => Effect.succeed(fallbackTarget)));
+			const reportLines = (status) => {
+				try {
+					return linesOf(cause, target, status);
+				} catch {
+					try {
+						return plainFailureLines(cause, status);
+					} catch {
+						return lastResort(error);
+					}
+				}
+			};
+			const defaultLines = reportLines(true);
+			const details = {
+				cause,
+				isDefect: !Cause.hasFails(cause),
+				defaultLines,
+				lines: (options) => options?.status === false ? reportLines(false) : 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)));
 		});
 	}));
-	/**
-	* Assemble a CLI program in the one order that reports every failure well.
-	*
-	* @remarks
-	* - `CliExit` is provided fresh, and a non-zero code after success becomes a
-	*   marked failure the teardown honours.
-	* - The platform layer is provided **inside** failure reporting, so a
-	*   layer-build failure (`HOME` unset, say) renders as one line with the
-	*   fallback code rather than escaping to the runtime's stack trace.
-	* - The logger is provided **outermost**, so it is present whichever branch
-	*   fails.
-	*
-	* You still call your platform's runner:
-	*
-	* @example
-	* ```ts
-	* NodeRuntime.runMain(
-	*   CliRuntime.main(Command.run(root, { version }), { platform: NodeServices.layer, exitCode: 3 }),
-	* )
-	* ```
-	*/
-	static main = (program, options) => Effect.gen(function* () {
-		yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(program) : program;
-		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}`));
-		if (code !== 0) return yield* Effect.fail(new ExitRequested(code));
-	}).pipe(Effect.provide(CliExit.layer), Effect.provide(options.platform), CliRuntime.reportFailures(options), Effect.provide(options.logger ?? CliLogger.layer()));
+	static main(program, options) {
+		const env = options.env === void 0 ? void 0 : CliEnv.layer(options.env);
+		const envLog = options.env?.log;
+		const logger = options.logger ?? (env === void 0 || envLog === void 0 ? CliLogger.layer() : CliLog.layer(envLog).pipe(Layer.provide(env), Layer.provide(Layer.provideMerge(options.platform.pipe(Layer.provide(platformLogLayer(envLog, options.env?.audienceEnvVar))), envBuildLogLayer(envLog, options.env?.audienceEnvVar))), Layer.catchCause(() => CliLogger.layer(envLog.logger))));
+		const inside = env === void 0 ? Layer.empty : Layer.mergeAll(CliColor.formatterLayer(options.env?.formatter), Layer.effectDiscard(refreshFailureTarget(void 0, {
+			displayPath: options.env?.displayPath,
+			stackFrames: options.env?.stackFrames
+		}))).pipe(Layer.provideMerge(env));
+		const run = Effect.gen(function* () {
+			yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(program) : program;
+			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}`));
+			if (code !== 0) return yield* Effect.fail(new ExitRequested(code));
+		}).pipe(Effect.provide(CliExit.layer), Effect.provide(inside), Effect.provide(options.platform), CliRuntime.reportFailures(options), Effect.provide(logger));
+		return Effect.suspend(() => Effect.provideService(run, FailureTargetCell, MutableRef.make(void 0)));
+	}
 	static reported(error, exitCode = 1) {
 		const marked = error instanceof Error ? error : new Error(String(error));
-		return Object.assign(marked, {
-			[Runtime.errorReported]: false,
-			[Runtime.errorExitCode]: exitCode
+		for (const [key, value] of [[Runtime.errorReported, false], [Runtime.errorExitCode, exitCode]]) Object.defineProperty(marked, key, {
+			value,
+			writable: true,
+			configurable: true,
+			enumerable: false
 		});
+		return marked;
 	}
 };
 

package/CliTest.js

@@ -6,6 +6,22 @@ const text = (stream) => Stream.mkString(Stream.decodeText(stream));
 /**
 * Spawn a built CLI bin hermetically and read its exit code and streams as data.
 *
+* @example
+* ```ts
+* import * as NodeServices from "@effect/platform-node/NodeServices"
+* import { assert, it } from "@effect/vitest"
+* import { CliTest } from "@effected/cli/testing"
+* import { Effect } from "effect"
+*
+* it.effect("prints its version", () =>
+*   Effect.gen(function* () {
+*     const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" })
+*     const result = yield* CliTest.run("dist/bin.js", ["--version"], { sandbox, execPath: process.execPath })
+*     assert.strictEqual(result.exitCode, 0)
+*   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+* )
+* ```
+*
 * @public
 */
 var CliTest = class {

package/CliTheme.js

@@ -0,0 +1,128 @@
+import { Glyphs } from "./Glyphs.js";
+import { openSequence, paintStyle } from "./internal/ansi.js";
+import { Token } from "./Token.js";
+import { Config, Context, Effect, Layer, Option } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { Prompt } from "effect/cli";
+
+//#region src/CliTheme.ts
+/**
+* A stream theme at `color`, over a style resolution and a glyph set: the one way a {@link StreamTheme} is built.
+*
+* @internal
+*/
+const streamThemeAt = (resolve, glyphs, color) => {
+	const paint = (token, text) => paintStyle(resolve(token), color, text);
+	return {
+		paint,
+		style: resolve,
+		sgr: (token) => openSequence(resolve(token), color),
+		glyphs,
+		color,
+		status: (vocab, name, text) => {
+			const def = vocab.def(name);
+			const glyph = paint(def.token, glyphs.kind === "ascii" ? def.ascii : def.glyph);
+			return text === void 0 || text === "" ? glyph : `${glyph} ${text}`;
+		}
+	};
+};
+/**
+* The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+* empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+* anyone else, or when the audience is not known, `theme` itself.
+*
+* @remarks
+* The one place that rule is applied to a theme: `Render.context` takes its colour and `paint` from it, and `./ui`
+* gives it to the trees it mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree.
+*
+* @internal
+*/
+const themeForAudience = (theme, audience) => audience === "agent" && theme.color !== "none" ? streamThemeAt(theme.style, theme.glyphs, "none") : theme;
+const make = (colors, glyphs, overrides) => {
+	const resolve = (token) => Token.resolve(token, overrides);
+	const stdout = streamThemeAt(resolve, glyphs, colors.stdout);
+	const stderr = streamThemeAt(resolve, glyphs, colors.stderr);
+	return {
+		...stdout,
+		forStream: (stream) => stream === "stdout" ? stdout : stderr
+	};
+};
+/** The prompt glyphs that differ under ASCII; `Prompt.makeTheme` already holds the Unicode ones. */
+const ASCII_PROMPT_GLYPHS = {
+	prefix: "?",
+	arrowUp: "^",
+	arrowDown: "v",
+	checkboxOn: "[x]",
+	checkboxOff: "[ ]",
+	tick: "+",
+	pointerSmall: ">",
+	pointer: ">"
+};
+/**
+* The presentation of a CLI: colour tokens, glyphs and statuses, decided once from the terminal.
+*
+* @remarks
+* A `Context.Service`, not a `Reference`. A colour level is a fact about the terminal, not a preference with a
+* safe default, so there is nothing sensible for an unprovided theme to read; requiring it puts `CliTheme` in
+* `R` and a program that forgot to wire it fails to compile rather than printing plain text to a colour
+* terminal. {@link CliTheme.layer} reads `TerminalEnv`.
+*
+* @public
+*/
+var CliTheme = class CliTheme extends Context.Service()("@effected/cli/CliTheme") {
+	/**
+	* The theme for the terminal `TerminalEnv` describes.
+	*
+	* @remarks
+	* Bind the layer to a constant and provide it once. With `glyphs: "auto"` the glyph set is ASCII only when
+	* `TERM=dumb`, read through `Config`.
+	*
+	* @param options - token overrides and the glyph set
+	*/
+	static layer = (options) => Layer.effect(CliTheme, Effect.gen(function* () {
+		const terminal = yield* TerminalEnv;
+		const choice = options?.glyphs ?? "auto";
+		const term = choice === "auto" ? Option.getOrUndefined(yield* Config.option(Config.String("TERM")).pipe(Effect.orElseSucceed(() => Option.none()))) : void 0;
+		const glyphs = Glyphs.select({
+			ascii: choice === "ascii" ? true : choice === "unicode" ? false : "auto",
+			...term === void 0 ? {} : { term }
+		});
+		return make({
+			stdout: terminal.stdout.color,
+			stderr: terminal.stderr.color
+		}, glyphs, options?.tokens);
+	}));
+	/**
+	* A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
+	*
+	* @param options - the colour level and glyph set
+	*/
+	static layerTest = (options) => Layer.succeed(CliTheme, make({
+		stdout: options?.color ?? "none",
+		stderr: options?.stderrColor ?? options?.color ?? "none"
+	}, options?.glyphs === "ascii" ? Glyphs.ascii : Glyphs.unicode, void 0));
+	/**
+	* Sets core's `Prompt.Theme` from the tokens, so built-in prompts match the rest of the output.
+	*
+	* @remarks
+	* The colour fields are raw SGR openers and are empty strings when colour is `none`. Under ASCII glyphs the
+	* prompt symbols fall back to ASCII too. A colourless theme is not byte-clean: core's `Ansi.annotate`
+	* appends a `\x1b[0m` reset, and prompts write cursor and underline codes, whatever the theme says.
+	*/
+	static promptTheme = Layer.effect(Prompt.Theme, Effect.gen(function* () {
+		const theme = yield* CliTheme;
+		const open = (token) => theme.sgr(token);
+		return Prompt.makeTheme({
+			...theme.glyphs.kind === "ascii" ? ASCII_PROMPT_GLYPHS : {},
+			ellipsis: theme.glyphs.ellipsis,
+			primaryColor: open("accent"),
+			mutedColor: open("muted"),
+			successColor: open("success"),
+			errorColor: open("error"),
+			submittedColor: open("emphasis")
+		});
+	}));
+};
+
+//#endregion
+export { CliTheme, streamThemeAt, themeForAudience };

package/ConfigIssueRenderer.js

@@ -2,35 +2,21 @@ import { formatIssue } from "./internal/format.js";
 
 //#region src/ConfigIssueRenderer.ts
 /**
-* Render a `@effected/config-file` validation failure.
+* Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
 *
 * @remarks
 * `ConfigValidationError` carries the structured `issue` tree rather than a
-* string, which is the right design and leaves the consumer holding a tree it
-* has to turn into sentences. This is that step, and it is the same treatment
-* {@link SchemaIssueRenderer} gives a bare issue.
+* string, so a caller holds a tree it has to turn into sentences. This is that
+* step, the same treatment {@link SchemaIssueRenderer} gives a bare issue.
 *
-* **This module is the only thing in the package that references
-* `@effected/config-file`, deliberately.** The peer is declared optional, and
-* an optional peer whose import is reachable from a shared module is not
-* optional — it is a crash for every consumer who took the manifest at its word
-* and did not install it. So nothing else in this package imports this module;
-* only the entrypoint re-exports it, and the shared rendering lives in
-* `internal/format`.
+* `ConfigValidationError.message` names the file but not the value, and the
+* value is the diagnostic: printing only the message tells a user their config
+* is invalid without saying which value is wrong or how it is shaped.
 *
-* The import is additionally `import type`, so it is erased at build time and
-* the runtime reach is **zero** — a consumer without `@effected/config-file`
-* installed can import this module and call `render` on any value without the
-* resolver ever being asked for the package.
-*
-* ## Why this and not just the error's message
-*
-* `ConfigValidationError.message` names the file. It does not name the value,
-* and the difference is the whole diagnostic: a consumer that printed only the
-* message told users "your config is invalid, run the doctor command", and the
-* doctor command — which guessed from a hand-written list of known keys — could
-* only ever find a *misspelling*. A wrongly **shaped** value left the two
-* commands pointing at each other and neither saying what was wrong.
+* `@effected/config-file` is an optional peer, and this module only
+* `import type`s it, so the import is erased at build time. A consumer without
+* the package installed can import this module without the resolver being asked
+* for it.
 *
 * @example
 * ```ts
@@ -56,17 +42,12 @@ var ConfigIssueRenderer = class {
 	*
 	* @remarks
 	* Takes the **error**, not its `issue`, because that is what a `catchTag`
-	* hands you and because `issue` is typed `Schema.Defect` — reaching into it
-	* at every call site is exactly the ceremony this removes.
-	*
-	* The parameter is the **typed** error rather than `unknown`. An earlier
-	* draft wrote `ConfigValidationError | unknown` to be accommodating, which
-	* collapses to plain `unknown` in TypeScript — so it accepted anything, said
-	* nothing, and left the type import in the `.d.ts` earning nothing. Inside
+	* hands you and because `issue` is typed `Schema.Defect`, which every call
+	* site would otherwise have to reach into. Inside
 	* `Effect.catchTag("ConfigValidationError", …)` the error is already this
-	* type, which is where this is called.
+	* type.
 	*
-	* It still cannot throw on a malformed value: the issue tree is validated by
+	* It cannot throw on a malformed value: the issue tree is validated by
 	* a guard before it is read, so a renderer on an error path never becomes the
 	* reason a program dies.
 	*/