@effected/cli-kit 0.26.0 → 0.27.0

package/CliColor.js

@@ -41,6 +41,10 @@ var CliColor = class CliColor {
 	* result to a `const` or the decision is re-read every time it is
 	* provided.
 	*
+	* `helpFlags` sets how subcommand help renders the flags a parent declared (`inheritedFlags`) and the
+	* program-wide built-ins (`globalFlags`): `"full"` (core's default), `"summary"` or `"none"`. It is passed to
+	* core's `defaultFormatter` beside the colour decision, so choosing a mode costs no colour.
+	*
 	* The `never` in its output does not mean it installs nothing.
 	* `CliOutput.Formatter` is a `Context.Reference`, whose key type is
 	* `never`, so this layer sets the formatter reference rather than
@@ -50,8 +54,11 @@ var CliColor = class CliColor {
 	*
 	* @public
 	*/
-	static formatterLayer = (overrides = {}) => Layer.unwrap(Effect.map(CliColor.enabled, (colors) => CliOutput.layer({
-		...CliOutput.defaultFormatter({ colors }),
+	static formatterLayer = (overrides = {}, helpFlags) => Layer.unwrap(Effect.map(CliColor.enabled, (colors) => CliOutput.layer({
+		...CliOutput.defaultFormatter({
+			colors,
+			...helpFlags
+		}),
 		...overrides
 	})));
 };

package/CliExit.js

@@ -1,5 +1,6 @@
+import { Fmt } from "./Fmt.js";
 import { isExitCode } from "./internal/isExitCode.js";
-import { Context, Effect, Layer, MutableRef } from "effect";
+import { Cause, Console, Context, Effect, Layer, MutableRef, Predicate } from "effect";
 
 // src/CliExit.ts
 /**
@@ -59,6 +60,58 @@ var CliExit = class CliExit extends Context.Service()("@effected/cli-kit/CliExit
 		const exit = yield* CliExit;
 		if (code > MutableRef.get(exit.code)) MutableRef.set(exit.code, code);
 	});
+	/**
+	* Write one line to stderr, record an exit code, and succeed: the shape of a
+	* hook-style command that must say why it exits non-zero without failing.
+	*
+	* @remarks
+	* This does **not** stop the program. It succeeds, so the caller must still
+	* return (or otherwise end its own flow) after calling it; finalizers and log
+	* sinks run as they would on any successful run, and `CliRuntime.main` turns
+	* the recorded code into the exit.
+	*
+	* The code is validated first, exactly as {@link CliExit.set} validates it, and
+	* an invalid code dies as the same defect before anything is written. The
+	* line goes through `Console.error`, never stdout, and is written as given:
+	* sanitize anything you do not control with `Fmt.sanitize` first. The
+	* highest code recorded during the run wins.
+	*/
+	static report = (code, line) => Effect.gen(function* () {
+		yield* CliExit.set(code);
+		yield* Console.error(line);
+	});
+	/**
+	* Report a failure cause as one stderr line, record the exit code the caller
+	* chooses for it, and succeed.
+	*
+	* @remarks
+	* The cause is squashed and the line is `<code> <tag>: <message>`, or
+	* `<code> <message>` when the error has no string `_tag`. The message comes
+	* from `Fmt.errorText` and is sanitized with `Fmt.sanitize` and its line breaks
+	* become a space, so a hostile error can neither throw, write an escape nor
+	* forge a second line. Reading `_tag` is guarded
+	* too: a getter that throws means no tag.
+	*
+	* An interrupt-only cause is not a failure to report: nothing is written or
+	* recorded and the effect re-interrupts. `codeOf` receives the squashed error
+	* and must return an integer in `0..255`; anything else dies as
+	* {@link CliExit.set} does, which is wiring.
+	*
+	* Like {@link CliExit.report} it does not stop the program: the caller still
+	* has to return.
+	*/
+	static reportCause = (cause, codeOf) => Cause.hasInterruptsOnly(cause) ? Effect.interrupt : Effect.suspend(() => {
+		const error = Cause.squash(cause);
+		const code = codeOf(error);
+		let tag;
+		try {
+			const read = Predicate.hasProperty(error, "_tag") ? error._tag : void 0;
+			tag = Predicate.isString(read) ? read : void 0;
+		} catch {}
+		const oneLine = (text) => Fmt.sanitize(text).replace(/\r?\n|\r/gu, " ");
+		const message = oneLine(Fmt.errorText(error));
+		return CliExit.report(code, tag === void 0 ? `${code} ${message}` : `${code} ${oneLine(tag)}: ${message}`);
+	});
 };
 
 export { CliExit };

package/CliRuntime.js

@@ -220,7 +220,7 @@ var CliRuntime = class CliRuntime {
 		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 inside = env === void 0 ? Layer.empty : Layer.mergeAll(CliColor.formatterLayer(options.env?.formatter, options.env?.helpFlags), 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, {
@@ -231,7 +231,7 @@ var CliRuntime = class CliRuntime {
 		}))).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;
+			yield* options.helpOnUsageError === "stderr" ? routeHelpOnUsageError(carried, options.env?.formatter, options.env?.helpFlags) : 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}`));

package/CliTest.js

@@ -1,8 +1,35 @@
 import { Fmt } from "./Fmt.js";
-import { Duration, Effect, Fiber, FileSystem, Option, Path, Stream, SubscriptionRef } from "effect";
+import { Duration, Effect, Fiber, FileSystem, Option, Path, Schema, Stream, SubscriptionRef } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 
 // src/CliTest.ts
+/**
+* A run ended otherwise than {@link RunOptions.expectExit} required.
+*
+* @remarks
+* Audience: the person reading a failed test. The message holds what the child did and its stderr, so a suite that
+* only cares about the happy path needs no hand-rolled helper to see why it did not get it.
+*
+* @public
+*/
+var CliTestFailure = class extends Schema.TaggedError()("CliTestFailure", {
+	expected: Schema.Number,
+	exitCode: Schema.NullOr(Schema.Number),
+	signal: Schema.NullOr(Schema.String),
+	stderr: Schema.String
+}) {
+	/**
+	* What was expected, what happened, and the child's stderr.
+	*
+	* @remarks
+	* Assigning to it is ignored: a runner or logger that rewrites `error.message` must not make this error throw,
+	* which a getter-only property does in strict mode.
+	*/
+	get message() {
+		return `expected exit ${this.expected}, but the bin ${this.signal === null ? `exited with code ${this.exitCode}` : `was ended by ${this.signal}`}\nstderr:\n${this.stderr}`;
+	}
+	set message(_value) {}
+};
 /** 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 = [];
@@ -108,7 +135,7 @@ var CliTest = class {
 		};
 	});
 	/**
-	* Run `execPath bin ...args`; a non-zero exit is returned, never failed.
+	* Run `execPath bin ...args`; a non-zero exit is returned, never failed, unless `expectExit` is set.
 	*
 	* @remarks
 	* `stdin` is never left as an inherited open pipe: when omitted or `""`
@@ -126,11 +153,18 @@ var CliTest = class {
 				text(handle.stderr),
 				endingOf(handle.exitCode)
 			], { concurrency: "unbounded" });
-			return {
+			const result = {
 				...ending,
 				stdout,
 				stderr
 			};
+			if (options.expectExit !== void 0 && result.exitCode !== options.expectExit) return yield* new CliTestFailure({
+				expected: options.expectExit,
+				exitCode: result.exitCode,
+				signal: result.signal,
+				stderr
+			});
+			return result;
 		}));
 	};
 	/**
@@ -203,4 +237,4 @@ var CliTest = class {
 	};
 };
 
-export { CliTest };
+export { CliTest, CliTestFailure };

package/ConfigIssueRenderer.js

@@ -13,10 +13,9 @@ import { formatIssueWithHints } from "./internal/format.js";
 * 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.
+* The parameter is {@link ConfigIssueSource}, a structural type, so this module
+* names nothing from `@effected/config-file` and the package is not a peer. A
+* real `ConfigValidationError` is assignable to it.
 *
 * @example
 * ```ts
@@ -45,7 +44,7 @@ var ConfigIssueRenderer = class {
 	* 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.
+	* shape.
 	*
 	* 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

package/Fmt.js

@@ -1,40 +1,9 @@
 import { displayWidth, graphemes, isEscapeOnly, stripAnsi } from "./internal/displayWidth.js";
 import { Duration, Option } from "effect";
 import { ErrorText } from "@effected/kit";
+import { EditDistance } from "@effected/source";
 
 // 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
@@ -319,16 +288,7 @@ var Fmt = class {
 	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 : [];
+		return EditDistance.suggest(input, candidates, { maxDistance: max });
 	};
 };
 

package/README.md

@@ -47,8 +47,6 @@ Optional peers:
   npm install ink react @types/react
   ```
 
-- **`@effected/config-file`**, only for `ConfigIssueRenderer`. It is imported as a type, so nothing at runtime reaches for it.
-
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
 
 ## Quick start

package/TestTerminal.js

@@ -1,6 +1,7 @@
 import { Effect, Layer, Option, Queue, Terminal } from "effect";
 
 // src/TestTerminal.ts
+const FORBIDDEN = "TestTerminal: this path must not read the terminal (forbidInput is set)";
 /**
 * A scripted `Terminal` for testing prompts and anything that reads the terminal.
 *
@@ -19,7 +20,12 @@ var TestTerminal = class {
 	/**
 	* Build a test terminal.
 	*
-	* @param options - the reported size; 80 by 24 by default
+	* @remarks
+	* With `forbidInput`, `readInput` and `readLine` die with a message saying this path must not read the terminal,
+	* where the default double hands back an empty queue (a stray read hangs) and quits `readLine`. `size`, `columns`,
+	* `rows`, `display` and `resize` behave as ever, so a "this path never prompts" platform keeps a real terminal size.
+	*
+	* @param options - the reported size, 80 by 24 by default; `forbidInput` to die on any input read
 	*/
 	static make = (options) => Effect.gen(function* () {
 		const queue = yield* Queue.unbounded();
@@ -47,11 +53,11 @@ var TestTerminal = class {
 				sizeSubscribers.delete(subscriber);
 				Queue.endUnsafe(subscriber);
 			})),
-			readInput: Effect.sync(() => {
+			readInput: options?.forbidInput === true ? Effect.die(/* @__PURE__ */ new Error(FORBIDDEN)) : Effect.sync(() => {
 				subscriptions++;
 				return queue;
 			}),
-			readLine: Effect.suspend(() => {
+			readLine: options?.forbidInput === true ? Effect.die(/* @__PURE__ */ new Error(FORBIDDEN)) : Effect.suspend(() => {
 				lines++;
 				return Effect.fail(new Terminal.QuitError({}));
 			}),

package/Token.js

@@ -34,7 +34,9 @@ var Token = class {
 	* @remarks
 	* An explicit style resolves to itself. A token name resolves to its override when `overrides` has one, else
 	* its default; a name that is not a token (including an `Object.prototype` member) resolves to the empty
-	* style. This is the same resolution `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
+	* style. It is theme-blind: it knows only the default palette and the `overrides` you pass, never a mounted
+	* theme, so a component under `CliUi` that wants the screen's theme uses `useStyle`. This is the same resolution
+	* `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
 	*
 	* @param token - a token name or an explicit style
 	* @param overrides - styles that replace the default of a token, as `CliThemeOptions.tokens` does

package/index.d.ts

@@ -2,7 +2,6 @@ import { Array as Array$1, Cause, Context, Duration, Effect, FileSystem, Layer,
 import { Audience, AudienceKind, ColorLevel, CurrentRuntimeEnv, RuntimeEnv, TerminalEnv } from "@effected/env";
 import { CliError, CliOutput, Command, Flag, Param, Prompt } from "effect/cli";
 import { Distribution } from "@effected/kit";
-import { ConfigValidationError } from "@effected/config-file";
 declare const Cancelled_base: Schema.Class<Cancelled, Schema.TaggedStruct<"Cancelled", {
   readonly reason: Schema.Literals<readonly ["escape", "interrupt"]>;
 }>, import("effect/Cause").YieldableError>;
@@ -183,6 +182,20 @@ export declare class CliAudience {
     readonly renderErrors?: boolean | undefined;
   }) => Effect.Effect<void, Exclude<E | CliError.UserError, Terminal.QuitError> | CliError.CliError, Exclude<R, Audience> | Audience | Command.Environment>;
 }
+/**
+ * How subcommand help renders flags the command does not own, as core's `CliOutput.defaultFormatter` takes them.
+ *
+ * @remarks
+ * `inheritedFlags` covers flags a parent command shares with its subcommands (for example `CliAudience.flags()`);
+ * `globalFlags` covers the built-ins such as `--help` and `--version`. Each is `"full"` (core's default, every flag
+ * listed), `"summary"` (a one-line pointer) or `"none"`.
+ *
+ * @public
+ */
+interface CliHelpFlags {
+  readonly inheritedFlags?: "full" | "summary" | "none" | undefined;
+  readonly globalFlags?: "full" | "summary" | "none" | undefined;
+}
 /**
  * Whether a CLI's output should carry ANSI colour, decided once and shared by
  * everything that renders — help text, error output, and any rendered result.
@@ -221,6 +234,10 @@ export declare class CliColor {
    * result to a `const` or the decision is re-read every time it is
    * provided.
    *
+   * `helpFlags` sets how subcommand help renders the flags a parent declared (`inheritedFlags`) and the
+   * program-wide built-ins (`globalFlags`): `"full"` (core's default), `"summary"` or `"none"`. It is passed to
+   * core's `defaultFormatter` beside the colour decision, so choosing a mode costs no colour.
+   *
    * The `never` in its output does not mean it installs nothing.
    * `CliOutput.Formatter` is a `Context.Reference`, whose key type is
    * `never`, so this layer sets the formatter reference rather than
@@ -230,7 +247,7 @@ export declare class CliColor {
    *
    * @public
    */
-  static readonly formatterLayer: (overrides?: Partial<CliOutput.Formatter>) => Layer.Layer<never, never, Stdio.Stdio>;
+  static readonly formatterLayer: (overrides?: Partial<CliOutput.Formatter>, helpFlags?: CliHelpFlags) => Layer.Layer<never, never, Stdio.Stdio>;
 }
 /**
  * The symbols a theme draws with.
@@ -368,7 +385,9 @@ export declare class Token {
    * @remarks
    * An explicit style resolves to itself. A token name resolves to its override when `overrides` has one, else
    * its default; a name that is not a token (including an `Object.prototype` member) resolves to the empty
-   * style. This is the same resolution `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
+   * style. It is theme-blind: it knows only the default palette and the `overrides` you pass, never a mounted
+   * theme, so a component under `CliUi` that wants the screen's theme uses `useStyle`. This is the same resolution
+   * `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
    *
    * @param token - a token name or an explicit style
    * @param overrides - styles that replace the default of a token, as `CliThemeOptions.tokens` does
@@ -2048,6 +2067,17 @@ interface CliEnvOptions {
    * sets; this is the way to keep a method of your own. Methods you omit keep the coloured defaults.
    */
   readonly formatter?: Partial<CliOutput.Formatter> | undefined;
+  /**
+   * How subcommand help renders flags it does not own, passed to core's `CliOutput.defaultFormatter` beside the
+   * colour decision. Only `CliRuntime.main` reads this.
+   *
+   * @remarks
+   * `inheritedFlags` covers flags a parent command shares with its subcommands (for example `CliAudience.flags()`);
+   * `globalFlags` covers the built-ins such as `--help` and `--version`. Each is `"full"` (core's default, every flag
+   * listed), `"summary"` (a one-line pointer) or `"none"`. Setting a mode here keeps the kit's colour decision, which
+   * supplying your own `formatHelpDoc` through {@link CliEnvOptions.formatter} would lose.
+   */
+  readonly helpFlags?: CliHelpFlags | undefined;
   /**
    * How an absolute path is shown: a function, or `{ relativeTo: root }` to show a path under `root` relative to it.
    * The identity by default.
@@ -2259,6 +2289,44 @@ export declare class CliExit extends CliExit_base {
    * cell, and the failure's own exit code (or the `exitCode` fallback) wins.
    */
   static readonly set: (code: number) => Effect.Effect<void, never, CliExit>;
+  /**
+   * Write one line to stderr, record an exit code, and succeed: the shape of a
+   * hook-style command that must say why it exits non-zero without failing.
+   *
+   * @remarks
+   * This does **not** stop the program. It succeeds, so the caller must still
+   * return (or otherwise end its own flow) after calling it; finalizers and log
+   * sinks run as they would on any successful run, and `CliRuntime.main` turns
+   * the recorded code into the exit.
+   *
+   * The code is validated first, exactly as {@link CliExit.set} validates it, and
+   * an invalid code dies as the same defect before anything is written. The
+   * line goes through `Console.error`, never stdout, and is written as given:
+   * sanitize anything you do not control with `Fmt.sanitize` first. The
+   * highest code recorded during the run wins.
+   */
+  static readonly report: (code: number, line: string) => Effect.Effect<void, never, CliExit>;
+  /**
+   * Report a failure cause as one stderr line, record the exit code the caller
+   * chooses for it, and succeed.
+   *
+   * @remarks
+   * The cause is squashed and the line is `<code> <tag>: <message>`, or
+   * `<code> <message>` when the error has no string `_tag`. The message comes
+   * from `Fmt.errorText` and is sanitized with `Fmt.sanitize` and its line breaks
+   * become a space, so a hostile error can neither throw, write an escape nor
+   * forge a second line. Reading `_tag` is guarded
+   * too: a getter that throws means no tag.
+   *
+   * An interrupt-only cause is not a failure to report: nothing is written or
+   * recorded and the effect re-interrupts. `codeOf` receives the squashed error
+   * and must return an integer in `0..255`; anything else dies as
+   * {@link CliExit.set} does, which is wiring.
+   *
+   * Like {@link CliExit.report} it does not stop the program: the caller still
+   * has to return.
+   */
+  static readonly reportCause: <E>(cause: Cause.Cause<E>, codeOf: (error: unknown) => number) => Effect.Effect<void, never, CliExit>;
 }
 /**
  * The protocol an error class implements to say how a failure is shown: a method under this key that returns the
@@ -2942,6 +3010,11 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    * `formatVersion`); a Formatter the platform provides is shadowed by
    * `main`'s, so pass it through `env.formatter` as well.
    *
+   * The installed Formatter paints by stdout's terminal check. When `env` is set and stderr's colour decision
+   * differs from stdout's, a usage error's help is rendered with `formatHelpDoc`, `formatError` and `formatErrors` rebuilt from
+   * core's default formatter under stderr's decision (and `env.helpFlags`), so those methods follow stderr
+   * unless given through `env.formatter`, which always wins. Every other method is left as installed.
+   *
    * Two cases keep help on stdout even under `"stderr"`. A `CliOutput`
    * Presenter provided inside `program` replaces the routing. And with
    * `Command.runWith`'s `renderErrors: false` core presents the help as
@@ -3179,6 +3252,18 @@ export declare class CliRuntime {
   static reported<E extends Error>(error: E, exitCode?: number): E;
   static reported(error: unknown, exitCode?: number): Error;
 }
+/**
+ * What {@link ConfigIssueRenderer.render} reads: anything that may carry an `issue` tree.
+ *
+ * @remarks
+ * A `@effected/config-file` `ConfigValidationError` is assignable to it, as is any
+ * other value with an optional `issue` property.
+ *
+ * @public
+ */
+interface ConfigIssueSource {
+  readonly issue?: unknown;
+}
 /**
  * Turns a `@effected/config-file` `ConfigValidationError` into one line per rejected value.
  *
@@ -3191,10 +3276,9 @@ export declare class CliRuntime {
  * 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.
+ * The parameter is {@link ConfigIssueSource}, a structural type, so this module
+ * names nothing from `@effected/config-file` and the package is not a peer. A
+ * real `ConfigValidationError` is assignable to it.
  *
  * @example
  * ```ts
@@ -3223,7 +3307,7 @@ export declare class ConfigIssueRenderer {
    * 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.
+   * shape.
    *
    * 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
@@ -3235,7 +3319,7 @@ export declare class ConfigIssueRenderer {
    * a guard before it is read, so a renderer on an error path never becomes the
    * reason a program dies.
    */
-  static readonly render: (error: ConfigValidationError) => ReadonlyArray<string>;
+  static readonly render: (error: ConfigIssueSource) => ReadonlyArray<string>;
 }
 /**
  * Options for {@link Fmt.truncate}.
@@ -3947,5 +4031,5 @@ export declare class SchemaIssueRenderer {
    */
   static readonly render: (issue: unknown) => ReadonlyArray<string>;
 }
-export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliFormatFlagOptions, CliFormatName, CliFormatOutput, CliFormatPrintOptions, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLogStatusOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PadOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, SuggestOptions, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
+export type { AnnotationLevel, AnnotationOptions, AudienceFlagInput, Block, BlockOf, CliAudienceFlagsOptions, CliDocSource, CliEnvOptions, CliEnvServices, CliEnvTestOptions, CliEnvTestServices, CliExitShape, CliFailureOptions, CliFormatFlagOptions, CliFormatName, CliFormatOutput, CliFormatPrintOptions, CliHelpFlags, CliLinksLinkerOptions, CliLinksOptions, CliLinksShape, CliLogFile, CliLogFileOptions, CliLogOptions, CliLogStatusOptions, CliLoggerOptions, CliMessageOptions, CliPromptFallbackOptions, CliPromptTarget, CliThemeOptions, CliThemeShape, CliThemeTestOptions, Column, ConfigIssueSource, CoreStatusName, Counter, CountsOptions, CountsRow, CountsTableOptions, DocPrintOptions, Document, EditorLinks, FailureDetails, GithubAnnotationProperties, GlyphSelectOptions, GlyphSet, Inline, InlineInput, InlineOf, LinkOptions, LinkTarget, ListOptions, MainOptions, NamedColor, OverflowOptions, PadOptions, PercentOptions, RenderContext, RenderContextOfOptions, RenderContextOptions, ReportFailuresOptions, RequiresAudienceFlags, StatusDef, StatusRef, StreamTheme, Style, SuggestOptions, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
 //# sourceMappingURL=index.d.ts.map

package/internal/HelpRouting.js

@@ -1,8 +1,29 @@
-import { Console, Effect } from "effect";
+import { Console, Effect, Option } from "effect";
+import { TerminalEnv } from "@effected/env";
 import { CliOutput } from "effect/cli";
 
 // src/internal/HelpRouting.ts
 /**
+* The installed formatter with its colour-bearing methods (`formatHelpDoc`, `formatError`, `formatErrors`) rebuilt
+* from core's default under `colors`, then `overrides` applied so they still win. Every other method of `current`,
+* `formatVersion` included, is kept.
+*
+* @internal
+*/
+const stderrFormatter = (current, colors, overrides, helpFlags) => {
+	const { formatHelpDoc, formatError, formatErrors } = CliOutput.defaultFormatter({
+		colors,
+		...helpFlags
+	});
+	return {
+		...current,
+		formatHelpDoc,
+		formatError,
+		formatErrors,
+		...overrides
+	};
+};
+/**
 * Core's presenter, with an invalid invocation's help written to stderr beside
 * its errors instead of stdout.
 *
@@ -14,11 +35,18 @@ import { CliOutput } from "effect/cli";
 * moves. An explicit `--help`, a bare group invocation and `--version` are
 * other events, presented by core unchanged on stdout.
 */
-const usageErrorsToStderr = { present: (event) => event._tag !== "InvalidInvocation" ? CliOutput.defaultPresenter.present(event) : Effect.gen(function* () {
+const usageErrorsToStderr = (overrides, helpFlags) => ({ present: (event) => event._tag !== "InvalidInvocation" ? CliOutput.defaultPresenter.present(event) : Effect.gen(function* () {
 	const sink = yield* Console.Console;
 	const toStderr = Object.assign(Object.create(sink), { log: (...args) => sink.error(...args) });
-	yield* CliOutput.defaultPresenter.present(event).pipe(Effect.provideService(Console.Console, toStderr));
-}) };
+	const terminal = yield* Effect.serviceOption(TerminalEnv);
+	const current = yield* CliOutput.Formatter;
+	const colors = Option.map(terminal, (t) => ({
+		stdout: t.stdout.color !== "none",
+		stderr: t.stderr.color !== "none"
+	}));
+	const formatter = Option.isNone(colors) || colors.value.stderr === colors.value.stdout ? current : stderrFormatter(current, colors.value.stderr, overrides, helpFlags);
+	yield* CliOutput.defaultPresenter.present(event).pipe(Effect.provideService(Console.Console, toStderr), Effect.provideService(CliOutput.Formatter, formatter));
+}) });
 /**
 * Run `program` so a help document printed together with parse errors goes to
 * stderr, beside the errors, instead of stdout.
@@ -30,6 +58,6 @@ const usageErrorsToStderr = { present: (event) => event._tag !== "InvalidInvocat
 *
 * @internal
 */
-const routeHelpOnUsageError = (program) => Effect.provideService(program, CliOutput.Presenter, usageErrorsToStderr);
+const routeHelpOnUsageError = (program, overrides, helpFlags) => Effect.provideService(program, CliOutput.Presenter, usageErrorsToStderr(overrides, helpFlags));
 
-export { routeHelpOnUsageError };
+export { routeHelpOnUsageError, stderrFormatter };

package/internal/format.js

@@ -25,9 +25,7 @@ const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue)
 *
 * @remarks
 * Shared by `SchemaIssueRenderer` and `ConfigIssueRenderer` and imported by
-* nothing else. It lives here rather than in either module so that
-* `ConfigIssueRenderer` — the only export that references the optional
-* `@effected/config-file` peer — can stay a module no other module imports.
+* nothing else.
 *
 * **No walker of our own.** `makeFormatterStandardSchemaV1` already flattens the
 * tree to `{ message, path }` entries, and `defaultLeafHook` covers every leaf
@@ -47,7 +45,7 @@ const formatIssue = (issue) => issueEntries(issue).map((entry) => entry.path.len
 * @remarks
 * Used by `ConfigIssueRenderer` only. The declared keys come from the issue tree itself: core's `UnexpectedKey` leaf
 * carries the AST of the struct being decoded, whose property signatures are the keys the schema accepts at that
-* path, so no schema is passed in and no `@effected/config-file` value is needed. The hint is `Fmt.suggest`'s list,
+* path, so no schema is passed in. The hint is `Fmt.suggest`'s list,
 * each key sanitised, and a line with no near match is exactly the line {@link formatIssue} draws.
 *
 * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli-kit",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"private": false,
 	"description": "The presentation boundary of an effect/cli program: audience-aware output, a document IR and renderers, editor links, failure reports and logging, plus opt-in Ink screens, widgets and a live view",
 	"keywords": [
@@ -59,22 +59,19 @@
 	"dependencies": {
 		"@effected/commands": "^0.20.0",
 		"@effected/github-commands": "^0.9.0",
-		"@effected/kit": "^0.12.0"
+		"@effected/kit": "^0.13.0",
+		"@effected/source": "^0.4.0"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.24.0",
-		"@effected/env": "^0.10.0",
-		"@effected/glob": "^0.18.0",
-		"@effected/walker": "^0.25.0",
+		"@effected/env": "^0.11.0",
+		"@effected/glob": "^0.19.0",
+		"@effected/walker": "^0.25.1",
 		"@types/react": "^19.3.0",
 		"effect": "~4.1.0",
 		"ink": "^8.0.0",
 		"react": "^19.3.0"
 	},
 	"peerDependenciesMeta": {
-		"@effected/config-file": {
-			"optional": true
-		},
 		"@types/react": {
 			"optional": true
 		},

package/testing.d.ts

@@ -1,4 +1,4 @@
-import { Duration, Effect, FileSystem, Layer, Path, PlatformError, Scope, Stream, Terminal } from "effect";
+import { Duration, Effect, FileSystem, Layer, Path, PlatformError, Schema, Scope, Stream, Terminal } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 /**
  * A hermetic temp directory minted by {@link CliTest.sandbox}, removed when its
@@ -45,6 +45,37 @@ interface RunOptions {
    * child that ignores the signal would otherwise keep the scope from closing forever, and leave the process behind.
    */
   readonly forceKillAfter?: Duration.Input | undefined;
+  /**
+   * The exit code the run must end with. Any other ending, a signal included, fails with a {@link CliTestFailure}
+   * carrying the code, the signal and the child's stderr in its message. Omitted, a non-zero exit is data.
+   */
+  readonly expectExit?: number | undefined;
+}
+declare const CliTestFailure_base: Schema.Class<CliTestFailure, Schema.TaggedStruct<"CliTestFailure", {
+  readonly expected: Schema.Number;
+  readonly exitCode: Schema.NullOr<Schema.Number>;
+  readonly signal: Schema.NullOr<Schema.String>;
+  readonly stderr: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A run ended otherwise than {@link RunOptions.expectExit} required.
+ *
+ * @remarks
+ * Audience: the person reading a failed test. The message holds what the child did and its stderr, so a suite that
+ * only cares about the happy path needs no hand-rolled helper to see why it did not get it.
+ *
+ * @public
+ */
+export declare class CliTestFailure extends CliTestFailure_base {
+  /**
+   * What was expected, what happened, and the child's stderr.
+   *
+   * @remarks
+   * Assigning to it is ignored: a runner or logger that rewrites `error.message` must not make this error throw,
+   * which a getter-only property does in strict mode.
+   */
+  get message(): string;
+  set message(_value: string);
 }
 /**
  * What a spawned bin did, as data: a non-zero exit is a result, not a failure.
@@ -132,7 +163,7 @@ export declare class CliTest {
     readonly path: string;
   }) => Effect.Effect<Sandbox, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Scope.Scope>;
   /**
-   * Run `execPath bin ...args`; a non-zero exit is returned, never failed.
+   * Run `execPath bin ...args`; a non-zero exit is returned, never failed, unless `expectExit` is set.
    *
    * @remarks
    * `stdin` is never left as an inherited open pipe: when omitted or `""`
@@ -141,7 +172,7 @@ export declare class CliTest {
    * default `"pipe"` stdio, which stays open until something writes to and
    * ends it.
    */
-  static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+  static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError | CliTestFailure, ChildProcessSpawner.ChildProcessSpawner>;
   /**
    * 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
@@ -235,11 +266,17 @@ export declare class TestTerminal {
   /**
    * Build a test terminal.
    *
-   * @param options - the reported size; 80 by 24 by default
+   * @remarks
+   * With `forbidInput`, `readInput` and `readLine` die with a message saying this path must not read the terminal,
+   * where the default double hands back an empty queue (a stray read hangs) and quits `readLine`. `size`, `columns`,
+   * `rows`, `display` and `resize` behave as ever, so a "this path never prompts" platform keeps a real terminal size.
+   *
+   * @param options - the reported size, 80 by 24 by default; `forbidInput` to die on any input read
    */
   static readonly make: (options?: {
     readonly columns?: number | undefined;
     readonly rows?: number | undefined;
+    readonly forbidInput?: boolean | undefined;
   }) => Effect.Effect<TestTerminalHandle>;
 }
 export type { KeyInput, RunOptions, RunResult, Sandbox, SpawnedBin, TestTerminalHandle };

package/testing.js

@@ -1,4 +1,4 @@
-import { CliTest } from "./CliTest.js";
+import { CliTest, CliTestFailure } from "./CliTest.js";
 import { TestTerminal } from "./TestTerminal.js";
 
-export { CliTest, TestTerminal };
+export { CliTest, CliTestFailure, TestTerminal };

package/ui/CliUi.js

@@ -354,9 +354,11 @@ var CliUi = class CliUi {
 	* naming the peers, never a silent `otherwise`. Screens in sequence make a wizard: discover the defaults first,
 	* pass each as an `otherwise`, and a non-interactive run returns exactly them.
 	*
-	* Without `otherwise`, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since
-	* the type cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
-	* `CliRuntime.main`).
+	* It has two forms. With a real `otherwise` (any value but `undefined`) the error type is `Cancelled` alone, since a
+	* non-interactive run answers and cannot fail. Without one, or with `{ otherwise: undefined }`, which counts as not
+	* given, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since the type
+	* cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
+	* `CliRuntime.main`). `A` is read from the screen, never from `otherwise`.
 	*
 	* As with `CliUi.run`, do not log while the screen is mounted: a line written to the terminal from elsewhere tears
 	* the frame.

package/ui/UiTheme.js

@@ -49,6 +49,25 @@ const useTheme = () => useScreen().theme;
 */
 const useGlyphs = () => useScreen().glyphs;
 /**
+* The Ink `Text` props for `token`, resolved through the mounted screen's theme.
+*
+* @remarks
+* The route a component takes to honour the theme: it sees a consumer's token overrides and `CliUiTest.styled`'s
+* marker palette, and gives no styling props at colour `none`. `inkProps(Token.resolve(token))` resolves against the
+* default palette and ignores the mounted theme, so under `CliUiTest.styled` it renders a raw colour where this
+* renders the token.
+*
+* A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+*
+* @param token - a theme token, or an explicit style
+*
+* @public
+*/
+const useStyle = (token) => {
+	const theme = useTheme();
+	return inkProps(theme.style(token), theme.color);
+};
+/**
 * Text painted with a theme token or style, through the mounted screen's theme.
 *
 * @remarks
@@ -144,4 +163,4 @@ const useTerminalSize = () => {
 	};
 };
 
-export { Styled, inkProps, useGlyphs, useTerminalSize, useTheme };
+export { Styled, inkProps, useGlyphs, useStyle, useTerminalSize, useTheme };

package/ui.d.ts

@@ -660,9 +660,11 @@ export declare class CliUi {
    * naming the peers, never a silent `otherwise`. Screens in sequence make a wizard: discover the defaults first,
    * pass each as an `otherwise`, and a non-interactive run returns exactly them.
    *
-   * Without `otherwise`, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since
-   * the type cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
-   * `CliRuntime.main`).
+   * It has two forms. With a real `otherwise` (any value but `undefined`) the error type is `Cancelled` alone, since a
+   * non-interactive run answers and cannot fail. Without one, or with `{ otherwise: undefined }`, which counts as not
+   * given, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since the type
+   * cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
+   * `CliRuntime.main`). `A` is read from the screen, never from `otherwise`.
    *
    * As with `CliUi.run`, do not log while the screen is mounted: a line written to the terminal from elsewhere tears
    * the frame.
@@ -670,7 +672,12 @@ export declare class CliUi {
    * @param screen - the screen to show
    * @param options - the non-interactive default, and whether to erase the last frame
    */
-  static readonly prompt: <A>(screen: Screen<A>, options?: CliUiPromptOptions<A>) => Effect.Effect<A, Cli.Cancelled | Cli.NotInteractive, Cli.CliTheme>;
+  static readonly prompt: {
+    <A>(screen: Screen<A>, options: CliUiPromptOptions<A> & {
+      readonly otherwise: Exclude<A, undefined>;
+    }): Effect.Effect<A, Cli.Cancelled, Cli.CliTheme>;
+    <A>(screen: Screen<A>, options?: CliUiPromptOptions<A>): Effect.Effect<A, Cli.Cancelled | Cli.NotInteractive, Cli.CliTheme>;
+  };
   /**
    * A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that shows a screen when the run is
    * interactive: `CliPrompt.fallback` for screens.
@@ -1942,6 +1949,22 @@ export declare const useTheme: () => Cli.StreamTheme;
  * @public
  */
 export declare const useGlyphs: () => Cli.GlyphSet;
+/**
+ * The Ink `Text` props for `token`, resolved through the mounted screen's theme.
+ *
+ * @remarks
+ * The route a component takes to honour the theme: it sees a consumer's token overrides and `CliUiTest.styled`'s
+ * marker palette, and gives no styling props at colour `none`. `inkProps(Token.resolve(token))` resolves against the
+ * default palette and ignores the mounted theme, so under `CliUiTest.styled` it renders a raw colour where this
+ * renders the token.
+ *
+ * A React hook: call it from a component rendered inside a `CliUi.run` screen or a `UiProvider`.
+ *
+ * @param token - a theme token, or an explicit style
+ *
+ * @public
+ */
+export declare const useStyle: (token: Cli.TokenName | Cli.Style) => InkTextProps;
 /**
  * Text painted with a theme token or style, through the mounted screen's theme.
  *

package/ui.js

@@ -11,7 +11,7 @@ import { Toggle } from "./ui/Toggle.js";
 import { UiKey } from "./ui/UiKey.js";
 import { UiProvider } from "./ui/UiProvider.js";
 import { UiStreams } from "./ui/UiStreams.js";
-import { Styled, inkProps, useGlyphs, useTerminalSize, useTheme } from "./ui/UiTheme.js";
+import { Styled, inkProps, useGlyphs, useStyle, useTerminalSize, useTheme } from "./ui/UiTheme.js";
 import { Viewport } from "./ui/Viewport.js";
 
-export { CliUi, Confirm, DocView, KeyHelp, KeyTable, MultiSelect, Select, Styled, Tabs, TextInput, Toggle, UiKey, UiProvider, UiStreams, Viewport, inkProps, useGlyphs, useKeys, useTerminalSize, useTheme };
+export { CliUi, Confirm, DocView, KeyHelp, KeyTable, MultiSelect, Select, Styled, Tabs, TextInput, Toggle, UiKey, UiProvider, UiStreams, Viewport, inkProps, useGlyphs, useKeys, useStyle, useTerminalSize, useTheme };