@effected/cli-kit 0.0.0-stage → 0.26.0

package/CliRuntime.js

@@ -0,0 +1,254 @@
+import { Cancelled } from "./Cancelled.js";
+import { CliColor } from "./CliColor.js";
+import { CliEnv } from "./CliEnv.js";
+import { CliExit } from "./CliExit.js";
+import { CliLog, envBuildLogLayer, platformLogLayer } from "./CliLog.js";
+import { CliLogger, makeCliLogger } from "./CliLogger.js";
+import { sanitize } from "./Fmt.js";
+import { ExitRequested } from "./internal/ExitRequested.js";
+import { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, readSpans, refreshFailureTarget } from "./internal/failureTarget.js";
+import { routeHelpOnUsageError } from "./internal/HelpRouting.js";
+import { failureText, tagOf } from "./internal/inspect.js";
+import { isExitCode } from "./internal/isExitCode.js";
+import { TrustedLine } from "./internal/logSafety.js";
+import { NotInteractive } from "./NotInteractive.js";
+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/kit";
+
+// 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;
+/**
+* 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.
+*
+* @remarks
+* `Runtime.getErrorExitCode` cannot serve alone here: it answers `1` both for
+* an error marked `1` and for an unmarked one, so an `exitCode` option would
+* silently override a deliberate `1`. Testing for the marker keeps "the error
+* chose its code" distinct from "nothing chose".
+*/
+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.
+*
+* @remarks
+* ## 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 —
+* `makeRunMain` composes its reporting `tapCause` around the already-provided
+* effect — so a program that carefully installs {@link CliLogger} still prints
+* its failures in the structured format that logger exists to replace, and
+* prints them on **stdout**, the one stream errors must not use.
+*
+* Nothing about the call site suggests this. The program looks correct, the
+* logger is installed, every success path is right, and only a failure reveals
+* it.
+*
+* ## Why a combinator, and not a `runMain`
+*
+* 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. 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.
+*
+* ## What it does with the failure
+*
+* Renders it through the ambient logger, then **re-fails with a marked error**
+* so the runtime still sees a failure — the exit code is the runtime's to set,
+* and swallowing the failure would make a broken run exit `0`.
+*
+* The marks are core's own, and they are what make this work without a platform
+* import:
+*
+* - `Runtime.errorExitCode` — `defaultTeardown` takes the squashed error's
+*   value as the process exit code. An error that already carries one **keeps
+*   it**: that was a deliberate choice by whatever raised it, and flattening
+*   every failure to a single code would discard it.
+* - `Runtime.errorReported` — set to `false`, which suppresses the runtime's own
+*   duplicate report. **The polarity is inverted relative to the name**: the
+*   marker means "should this be reported", so the intuitive
+*   `errorReported: true` — "I have reported it, stay quiet" — produces exactly
+*   the double report it was meant to prevent.
+*
+* An **interrupt is left alone**: it is not a failure to report, and the
+* default teardown already maps an interrupt-only cause to `130`.
+*
+* A `CliError.ShowHelp` is never rendered: `Command.runWith` already printed
+* the help text (and any parse errors) before re-failing with it, so
+* rendering it again would print nothing but a stray "Help requested" line.
+* A `ShowHelp` carrying errors is remapped to `usageExitCode` (default `64`,
+* BSD `EX_USAGE`); a bare `--help` or root invocation — `errors` empty —
+* keeps exit `0`. A `CliError.UserError` whose `Runtime.errorReported` mark
+* is `false` is likewise skipped: that is how `Command.runWith` leaves one it
+* 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. 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`
+* raises is likewise never rendered; it only carries the exit code a
+* successful program recorded through `CliExit`.
+*
+* @example
+* ```ts
+* import { CliRuntime } from "@effected/cli-kit"
+* 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() {}
+	/**
+	* 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 = {}) => {
+		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 linesOf(cause, target, status, spans ?? target.spans);
+					} catch {
+						try {
+							return plainFailureLines(cause, status, spans ?? target.spans);
+						} catch {
+							return lastResort(error);
+						}
+					}
+				};
+				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;
+		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(Effect.gen(function* () {
+			const { spans, invalid } = yield* readSpans(options.env?.spans, options.env?.spansEnvVar);
+			if (invalid !== void 0) yield* Effect.logWarning(invalid).pipe(Effect.provideService(Logger.CurrentLoggers, /* @__PURE__ */ new Set([makeCliLogger(envLog?.logger)])));
+			yield* refreshFailureTarget(void 0, {
+				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(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}`));
+			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));
+		for (const [key, value] of [[Runtime.errorReported, false], [Runtime.errorExitCode, exitCode]]) Object.defineProperty(marked, key, {
+			value,
+			writable: true,
+			configurable: true,
+			enumerable: false
+		});
+		return marked;
+	}
+};
+
+export { CliRuntime };

package/CliTest.js

@@ -0,0 +1,206 @@
+import { Fmt } from "./Fmt.js";
+import { Duration, Effect, Fiber, FileSystem, Option, Path, Stream, SubscriptionRef } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+
+// src/CliTest.ts
+/** The complete lines of `captured` from `offset`, and the rest too once it has ended; with the offset after them. */
+const linesFrom = (offset, captured) => {
+	const lines = [];
+	let start = offset;
+	let end = captured.text.indexOf("\n", start);
+	while (end !== -1) {
+		lines.push(captured.text.slice(start, captured.text[end - 1] === "\r" ? end - 1 : end));
+		start = end + 1;
+		end = captured.text.indexOf("\n", start);
+	}
+	if (captured.done && start < captured.text.length) {
+		lines.push(captured.text.slice(start));
+		start = captured.text.length;
+	}
+	return [start, lines];
+};
+/** The bound on a child that ignores its termination signal, when the caller gives none. */
+const FORCE_KILL_AFTER = "2 seconds";
+/** `options.forceKillAfter` or the default; a duration that is not finite is a wiring mistake and throws. */
+const forceKillAfterOf = (options) => {
+	const input = options.forceKillAfter ?? FORCE_KILL_AFTER;
+	const duration = Duration.fromInput(input);
+	if (typeof input === "number" && Number.isNaN(input) || Option.isNone(duration) || !Duration.isFinite(duration.value) || Duration.toMillis(duration.value) < 0) throw new RangeError(`CliTest: forceKillAfter must be a finite, non-negative duration, received ${String(input)}`);
+	return duration.value;
+};
+/**
+* Core's handle fails `exitCode` for a child a signal ended, naming the signal only in the error's text; this reads it
+* back out, so a signal is an outcome as an exit code is. Any other failure (a failed stdin stream) stays a failure.
+*/
+const SIGNALLED = /receipt of signal: '(SIG[A-Z0-9]+)'/;
+const endingOf = (exitCode) => exitCode.pipe(Effect.map((code) => ({
+	exitCode: Number(code),
+	signal: null
+})), Effect.catchTag("PlatformError", (error) => {
+	const match = SIGNALLED.exec(`${error.message} ${Fmt.causeMessage(error) ?? ""}`);
+	return match === null ? Effect.fail(error) : Effect.succeed({
+		exitCode: null,
+		signal: match[1]
+	});
+}));
+const commandOf = (bin, args, options, forceKillAfter) => ChildProcess.make(options.execPath, [bin, ...args], {
+	forceKillAfter,
+	cwd: options.cwd ?? options.sandbox.root,
+	env: {
+		...options.sandbox.env,
+		...options.env
+	},
+	stdin: options.stdin === void 0 || options.stdin === "" ? Stream.empty : Stream.make(new TextEncoder().encode(options.stdin))
+});
+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-kit/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 {
+	constructor() {}
+	/**
+	* A scoped temp directory with a fresh `HOME` and XDG tree, `NO_COLOR=1`,
+	* and the `PATH` you pass — the host environment is never inherited.
+	*
+	* @remarks
+	* Each call mints a fresh temp directory; bind the result to a `const`
+	* within one test rather than calling this more than once per assertion.
+	*/
+	static sandbox = (options) => Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const root = yield* fs.makeTempDirectoryScoped({ prefix: "effected-cli-test-" });
+		const home = path.join(root, "home");
+		const xdg = {
+			XDG_CONFIG_HOME: path.join(home, ".config"),
+			XDG_DATA_HOME: path.join(home, ".local", "share"),
+			XDG_STATE_HOME: path.join(home, ".local", "state"),
+			XDG_CACHE_HOME: path.join(home, ".cache")
+		};
+		for (const dir of Object.values(xdg)) yield* fs.makeDirectory(dir, { recursive: true });
+		return {
+			root,
+			home,
+			env: {
+				HOME: home,
+				...xdg,
+				PATH: options.path,
+				NO_COLOR: "1"
+			}
+		};
+	});
+	/**
+	* Run `execPath bin ...args`; a non-zero exit is returned, never failed.
+	*
+	* @remarks
+	* `stdin` is never left as an inherited open pipe: when omitted or `""`
+	* the child gets an already-ended empty input (`Stream.empty`), so a
+	* stdin-reading bin exits instead of hanging on `effect/process`'s
+	* default `"pipe"` stdio, which stays open until something writes to and
+	* ends it.
+	*/
+	static run = (bin, args, options) => {
+		const forceKillAfter = forceKillAfterOf(options);
+		return Effect.scoped(Effect.gen(function* () {
+			const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(commandOf(bin, args, options, forceKillAfter));
+			const [stdout, stderr, ending] = yield* Effect.all([
+				text(handle.stdout),
+				text(handle.stderr),
+				endingOf(handle.exitCode)
+			], { concurrency: "unbounded" });
+			return {
+				...ending,
+				stdout,
+				stderr
+			};
+		}));
+	};
+	/**
+	* Start `execPath bin ...args` and return at once with a handle on it: its output as lines while it runs, a signal,
+	* and its exit, for a long-running command (a `--follow`, a watch mode, a server) that {@link CliTest.run} would wait
+	* on forever.
+	*
+	* @remarks
+	* The child lives in the caller's scope: when the scope closes first, the child is sent `SIGTERM`, then `SIGKILL`
+	* after `forceKillAfter` (`2 seconds` by default), so a test that ends early leaves nothing running and never waits
+	* on a child that ignores the signal. A child a signal ended reports `exitCode: null` and the signal in `result`. Both streams are drained from the start whether or not the test reads them, so a
+	* chatty child never blocks on a full pipe, and each stream replays from its first line to every reader. The
+	* options are {@link CliTest.run}'s, `stdin` included: the child gets that text, then an ended input.
+	*
+	* ```ts
+	* const child = yield* CliTest.spawn("dist/bin.js", ["logs", "--follow"], { sandbox, execPath: process.execPath })
+	* yield* Stream.runHead(child.stdout) // the first line: it is following
+	* yield* child.kill("SIGINT")
+	* assert.strictEqual(yield* child.exitCode, 0)
+	* ```
+	*
+	* @param bin - the built bin to run
+	* @param args - its arguments
+	* @param options - the sandbox, the node binary, and the working directory, environment and stdin
+	*/
+	static spawn = (bin, args, options) => {
+		const forceKillAfter = forceKillAfterOf(options);
+		return Effect.gen(function* () {
+			const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(commandOf(bin, args, options, forceKillAfter));
+			const capture = (stream) => Effect.gen(function* () {
+				const ref = yield* SubscriptionRef.make({
+					text: "",
+					done: false
+				});
+				return {
+					ref,
+					pump: yield* Stream.decodeText(stream).pipe(Stream.runForEach((chunk) => SubscriptionRef.update(ref, (s) => ({
+						text: s.text + chunk,
+						done: false
+					}))), Effect.ensuring(SubscriptionRef.update(ref, (s) => ({
+						text: s.text,
+						done: true
+					}))), Effect.forkScoped),
+					lines: SubscriptionRef.changes(ref).pipe(Stream.takeUntil((s) => s.done), Stream.mapAccum(() => 0, linesFrom))
+				};
+			});
+			const out = yield* capture(handle.stdout);
+			const err = yield* capture(handle.stderr);
+			const ending = endingOf(handle.exitCode);
+			return {
+				stdout: out.lines,
+				stderr: err.lines,
+				kill: (signal) => handle.kill({
+					killSignal: signal ?? "SIGTERM",
+					forceKillAfter
+				}).pipe(Effect.catchTag("PlatformError", (error) => Effect.flatMap(handle.isRunning, (running) => running ? Effect.fail(error) : Effect.void))),
+				exitCode: Effect.map(ending, (end) => end.exitCode),
+				result: Effect.gen(function* () {
+					const end = yield* ending;
+					yield* Fiber.join(out.pump);
+					yield* Fiber.join(err.pump);
+					return {
+						...end,
+						stdout: (yield* SubscriptionRef.get(out.ref)).text,
+						stderr: (yield* SubscriptionRef.get(err.ref)).text
+					};
+				})
+			};
+		});
+	};
+};
+
+export { CliTest };

package/CliTheme.js

@@ -0,0 +1,142 @@
+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";
+
+// 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 glyph = paint(vocab.def(name).token, vocab.glyph(name, glyphs));
+			return text === void 0 || text === "" ? glyph : `${glyph} ${text}`;
+		}
+	};
+};
+/** The audience rule, shared by `CliTheme.forAudience` and the class's own docs. */
+const forAudience = (theme, audience) => audience === "agent" && theme.color !== "none" ? streamThemeAt(theme.style, theme.glyphs, "none") : theme;
+const make = (colors, glyphs, overrides) => {
+	const resolve = (token) => Token.resolve(token, overrides);
+	const stdout = streamThemeAt(resolve, glyphs, colors.stdout);
+	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-kit/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);
+	}));
+	/**
+	* The theme an audience sees of `theme`: for an agent, the same theme at colour `none` (`paint` the identity, `sgr`
+	* empty, `status` unpainted), whatever the terminal could do, because an agent never gets an escape of any kind; for
+	* anyone else, or when the audience is not known, `theme` itself.
+	*
+	* @remarks
+	* The one rule the kit applies wherever it paints for an audience: `Render.context` takes its colour and `paint`
+	* from it, `CliMessage` and `CliLog.status` paint their glyphs through it, and `./ui` gives it to the trees it
+	* mounts, so `useTheme`, `Styled` and the widgets' colour-`none` text markers all agree. A program that paints its
+	* own lines applies the same rule with it rather than re-implementing it:
+	*
+	* ```ts
+	* const line = Effect.gen(function* () {
+	*   const theme = CliTheme.forAudience((yield* CliTheme).forStream("stdout"), (yield* Audience).kind)
+	*   return theme.status(Status.core, "success", Fmt.sanitize(name))
+	* })
+	* ```
+	*
+	* Pure: it reads nothing, so the audience is the caller's to pass, `undefined` when it is not known.
+	*
+	* @param theme - a stream's theme, such as `CliTheme.forStream("stdout")`
+	* @param audience - who the output is for, or `undefined` when that is not known
+	*/
+	static forAudience = forAudience;
+	/**
+	* A fixed theme that needs nothing; `none` colour and Unicode glyphs unless told otherwise.
+	*
+	* @param options - the colour level and glyph set
+	*/
+	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`, and `colors` is the theme's
+	* own decision (`false` at `none`), so core's prompts and its command wizard write no colour or style escape, not
+	* even a reset, and core never re-reads the host for `NO_COLOR` or a TTY. Cursor and redraw controls are still
+	* written, whatever the theme says. Under ASCII glyphs the prompt symbols fall back to ASCII too.
+	*/
+	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,
+			colors: theme.color !== "none",
+			primaryColor: open("accent"),
+			mutedColor: open("muted"),
+			successColor: open("success"),
+			errorColor: open("error"),
+			submittedColor: open("emphasis")
+		});
+	}));
+};
+
+export { CliTheme, streamThemeAt };

package/ConfigIssueRenderer.js

@@ -0,0 +1,63 @@
+import { formatIssueWithHints } from "./internal/format.js";
+
+// src/ConfigIssueRenderer.ts
+/**
+* Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
+*
+* @remarks
+* `ConfigValidationError` carries the structured `issue` tree rather than a
+* 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.
+*
+* `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.
+*
+* `@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
+* import { ConfigIssueRenderer } from "@effected/cli-kit"
+* import { Effect } from "effect"
+*
+* const load = configFile.load.pipe(
+*   Effect.catchTag("ConfigValidationError", (error) =>
+*     Effect.gen(function* () {
+*       yield* Effect.logError(String(error))
+*       for (const line of ConfigIssueRenderer.render(error)) yield* Effect.logError(`  ${line}`)
+*     }),
+*   ),
+* )
+* ```
+*
+* @public
+*/
+var ConfigIssueRenderer = class {
+	constructor() {}
+	/**
+	* One line per rejected value.
+	*
+	* @remarks
+	* Takes the **error**, not its `issue`, because that is what a `catchTag`
+	* 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.
+	*
+	* An unknown key the schema has a near match for at the same path ends in a
+	* hint, `unknown key at theme.colour (did you mean "color"?)`, drawn from the
+	* keys the struct declares there (every branch's, under a union) with
+	* {@link Fmt.suggest}'s threshold. A key with no near match is drawn exactly
+	* as {@link SchemaIssueRenderer} draws it.
+	*
+	* 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.
+	*/
+	static render = (error) => formatIssueWithHints(error?.issue);
+};
+
+export { ConfigIssueRenderer };