@effected/cli 0.23.0 → 0.24.0

package/CliEnv.js

@@ -3,6 +3,7 @@ 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";
 
@@ -30,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 {
@@ -50,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));
+		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
@@ -82,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/CliFormat.js

@@ -5,13 +5,21 @@ 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.Literals` with the kit's names, default and description; the print hands every document
-* format to `Doc.print` and writes `json` itself.
+* 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"])
@@ -22,30 +30,54 @@ import { Flag } from "effect/cli";
 *
 * @public
 */
-var CliFormat = class {
+var CliFormat = class CliFormat {
 	constructor() {}
 	/**
-	* A `--format` flag offering `formats`.
+	* 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.
+	* 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}.
 	*
-	* @param formats - the formats the command offers, at least one
-	* @param options - the default, the flag's name and its description
+	* 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 fallback = options?.default ?? (formats.includes("auto") ? "auto" : formats[0]);
-		return Flag.Literals(options?.name ?? "format", formats).pipe(Flag.withDefault(fallback), Flag.withDescription(options?.description ?? `Output format: ${formats.join(", ")} (default ${fallback})`));
+		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()` as JSON, one `Console.log` (or `Console.error` for stderr), indented by `indent`.
-	* Under GitHub Actions a `##[` inside it is written as the JSON escape `#\u0023[`, which decodes to the same text,
-	* so the runner cannot read it as a command. A value JSON cannot hold (a cycle, a bigint) is a defect. Every other
-	* format prints `output.doc()` with `Doc.print`, which renders it as `auto` or the named renderer would.
+	* `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
@@ -59,10 +91,33 @@ var CliFormat = class {
 		});
 		const data = output.json;
 		if (data === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.print: format json needs output.json"));
-		const text = yield* Effect.sync(() => JSON.stringify(data(), null, options?.indent ?? 2));
-		if (text === void 0) return yield* Effect.die(/* @__PURE__ */ new Error("CliFormat.print: output.json() is not JSON"));
+		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* stream === "stdout" ? Console.log(safe) : Console.error(safe);
+		yield* (options?.stream ?? "stdout") === "stdout" ? Console.log(safe) : Console.error(safe);
 	});
 };
 

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/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

@@ -22,6 +22,11 @@ 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.
@@ -113,7 +118,10 @@ const checkExitCodes = (exitCodes) => {
 * 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`
@@ -175,6 +183,7 @@ 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)));
+			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)));

package/CliTest.js

@@ -1,7 +1,57 @@
-import { Effect, FileSystem, Path, Stream } from "effect";
+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.
@@ -67,28 +117,90 @@ var CliTest = class {
 	* default `"pipe"` stdio, which stays open until something writes to and
 	* ends it.
 	*/
-	static run = (bin, args, options) => Effect.scoped(Effect.gen(function* () {
-		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-		const command = ChildProcess.make(options.execPath, [bin, ...args], {
-			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))
+	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
+					};
+				})
+			};
 		});
-		const handle = yield* spawner.spawn(command);
-		const [stdout, stderr, exitCode] = yield* Effect.all([
-			text(handle.stdout),
-			text(handle.stderr),
-			handle.exitCode
-		], { concurrency: "unbounded" });
-		return {
-			exitCode: Number(exitCode),
-			stdout,
-			stderr
-		};
-	}));
+	};
 };
 
 export { CliTest };

package/ConfigIssueRenderer.js

@@ -1,4 +1,4 @@
-import { formatIssue } from "./internal/format.js";
+import { formatIssueWithHints } from "./internal/format.js";
 
 // src/ConfigIssueRenderer.ts
 /**
@@ -47,11 +47,17 @@ var ConfigIssueRenderer = class {
 	* `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) => formatIssue(error?.issue);
+	static render = (error) => formatIssueWithHints(error?.issue);
 };
 
 export { ConfigIssueRenderer };

package/Fmt.js

@@ -1,8 +1,40 @@
-import { causeMessage } from "./internal/causeMessage.js";
 import { displayWidth, graphemes, isEscapeOnly, stripAnsi } from "./internal/displayWidth.js";
-import { Duration, Option, Predicate } from "effect";
+import { Duration, Option } from "effect";
+import { ErrorText } from "@effected/engine";
 
 // src/Fmt.ts
+/**
+* The Levenshtein distance between `a` and `b` when it is at most `limit`, and `limit + 1` otherwise.
+*
+* Only the diagonal band of the matrix within `limit` of it is computed (a cell outside it is past `limit` already),
+* over two rows reused in turn, and a row whose every cell is past `limit` ends the walk, since no later row can come
+* back under it: the cost is the length of `a` times `2 * limit + 1`.
+*/
+const boundedDistance = (a, b, limit) => {
+	const over = limit + 1;
+	if (Math.abs(a.length - b.length) > limit) return over;
+	const n = b.length;
+	const at = (row, j) => row[j] ?? over;
+	let previous = Array.from({ length: n + 1 }, (_, j) => j <= limit ? j : over);
+	let current = new Array(n + 1).fill(over);
+	for (let i = 1; i <= a.length; i++) {
+		const lo = Math.max(1, i - limit);
+		const hi = Math.min(n, i + limit);
+		const edge = lo === 1 && i <= limit ? i : over;
+		current[lo - 1] = edge;
+		let rowMin = edge;
+		for (let j = lo; j <= hi; j++) {
+			const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+			const cell = Math.min(at(previous, j) + 1, at(current, j - 1) + 1, at(previous, j - 1) + cost, over);
+			current[j] = cell;
+			if (cell < rowMin) rowMin = cell;
+		}
+		if (hi < n) current[hi + 1] = over;
+		if (rowMin > limit) return over;
+		[previous, current] = [current, previous];
+	}
+	return Math.min(at(previous, n), over);
+};
 const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 /**
 * Text made safe to lay out and print: complete ANSI and OSC sequences removed, every remaining control character
@@ -218,27 +250,15 @@ var Fmt = class {
 	* function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no message.
 	*
 	* The text is not sanitised: pass it through {@link Fmt.sanitize} before printing data you do not control. For
-	* the messages along an error's `cause` chain, use {@link Fmt.causeMessage}.
+	* the messages along an error's `cause` chain, use {@link Fmt.causeMessage}; for the two combined, use
+	* {@link Fmt.errorText}.
+	*
+	* It is `@effected/engine`'s `ErrorText.describe`, the same function, so a front end that cannot depend on this
+	* package (an MCP server) describes a value with the same words.
 	*
 	* @param value - the value
 	*/
-	static describe = (value) => {
-		if (Predicate.isString(value)) return value;
-		if (value === void 0 || value === null) return String(value);
-		if (typeof value !== "object" && typeof value !== "function") return String(value);
-		try {
-			if (Predicate.hasProperty(value, "message") && Predicate.isString(value.message)) return value.message;
-		} catch {}
-		try {
-			const json = JSON.stringify(value);
-			if (json !== void 0) return json;
-		} catch {}
-		try {
-			return String(value);
-		} catch {
-			return "[unprintable value]";
-		}
-	};
+	static describe = ErrorText.describe;
 	/**
 	* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
 	* `undefined` when nothing along it has one.
@@ -253,11 +273,63 @@ var Fmt = class {
 	*
 	* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
 	* the walk with the text found so far, `undefined` when there is none, so a caller's own fallback
-	* (`?? Fmt.describe(value)`) applies.
+	* (`?? Fmt.describe(value)`, which {@link Fmt.errorText} spells once) applies.
+	*
+	* It is `@effected/engine`'s `ErrorText.causeMessage`, the same function.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static causeMessage = ErrorText.causeMessage;
+	/**
+	* The text of an unknown failure: {@link Fmt.causeMessage} when the chain carries a message, otherwise
+	* {@link Fmt.describe}.
+	*
+	* @remarks
+	* Exactly `Fmt.causeMessage(value) ?? Fmt.describe(value)`, the fallback an I/O site turning a caught value into
+	* text would otherwise spell out by hand at every call. An error whose message is empty and whose chain carries none
+	* is `""`, as `describe` reads it. Never throws, and not sanitised: pass it through {@link Fmt.sanitize} before
+	* printing data you do not control. It is `@effected/engine`'s `ErrorText.of`, the same function.
 	*
 	* @param value - the error, or whatever was thrown
 	*/
-	static causeMessage = (value) => causeMessage(value);
+	static errorText = ErrorText.of;
+	/**
+	* The candidates nearest to `input`, for a "did you mean" hint: those at the smallest edit distance found, up to
+	* `maxDistance` edits (two by default), in the order given, each once. No candidate that close is `[]`.
+	*
+	* @remarks
+	* The distance is Levenshtein's (one insertion, deletion or substitution per edit), over UTF-16 code units and
+	* case-sensitive, with the same two-edit threshold and the same ties-all-kept rule `effect/cli` uses for an unknown
+	* subcommand or flag, so a program's own suggestions agree with the parser's. A candidate equal to `input` is at
+	* distance zero and is the only one returned.
+	*
+	* The cost is linear in the candidates' total length: a candidate whose length differs from `input`'s by more than
+	* `maxDistance` is skipped unmeasured, and only the band of the edit matrix within `maxDistance` of its diagonal is
+	* measured, so a long typed value cannot make it quadratic. A `maxDistance` that is not a non-negative integer is a programming mistake and
+	* throws a `RangeError`.
+	*
+	* ```ts
+	* Fmt.suggest("stauts", ["status", "stack", "build"]) // => ["status"]
+	* ```
+	*
+	* @param input - what was typed: an unknown key, a profile name, a phase name
+	* @param candidates - the names it could have meant
+	* @param options - the most edits a suggestion may be away
+	*/
+	static suggest = (input, candidates, options) => {
+		const max = options?.maxDistance ?? 2;
+		if (!Number.isInteger(max) || max < 0) throw new RangeError(`Fmt.suggest: maxDistance must be a non-negative integer, received ${max}`);
+		let best = max + 1;
+		let found = [];
+		for (const candidate of new Set(candidates)) {
+			const distance = boundedDistance(input, candidate, Math.min(max, best));
+			if (distance < best) {
+				best = distance;
+				found = [candidate];
+			} else if (distance === best) found.push(candidate);
+		}
+		return best <= max ? found : [];
+	};
 };
 
 export { Fmt, sanitize };