@effected/cli 0.23.0 → 0.24.0

package/index.d.ts

@@ -2156,6 +2156,15 @@ type CliEnvTestServices = TerminalEnv | Audience | CliTheme;
  * `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
  */
 export declare class CliEnv {
@@ -2173,7 +2182,7 @@ export declare class CliEnv {
    * 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
@@ -2365,15 +2374,34 @@ type CliFormatName = "auto" | "plain" | "ansi" | "markdown" | "githubLog" | "jso
 /**
  * Options for {@link CliFormat.flag}.
  *
+ * @typeParam F - the built-in formats offered under their own names
+ * @typeParam A - the caller's alias names, each standing for a built-in format
+ * @typeParam C - the caller's own formats, which the caller renders itself
+ *
  * @public
  */
-interface CliFormatFlagOptions<F extends CliFormatName> {
-  /** The format when the flag is not given: `auto` when it is offered, otherwise the first one. */
-  readonly default?: F | undefined;
+interface CliFormatFlagOptions<F extends CliFormatName, A extends Readonly<Record<string, CliFormatName>> = Record<never, CliFormatName>, C extends string = never> {
+  /**
+   * The format when the flag is not given, spelled as on the command line (an alias by its own name): `auto` when it
+   * is offered, otherwise the first one.
+   */
+  readonly default?: F | Extract<keyof A, string> | C | undefined;
   /** The flag's name; `format` by default. */
   readonly name?: string | undefined;
   /** The flag's description in help; one naming the offered formats by default. */
   readonly description?: string | undefined;
+  /**
+   * Names of the caller's own that stand for a built-in format: `{ human: "auto" }` offers `--format human`, whose
+   * value is `auto`. The target need not be offered under its own name, so `["json"]` with `{ human: "auto" }` offers
+   * exactly `json` and `human`. An alias may not reuse a built-in format's name or any other offered name.
+   */
+  readonly aliases?: A | undefined;
+  /**
+   * Formats the caller renders itself, such as `mermaid` or `dot`: offered under their own names and yielded as
+   * themselves. {@link CliFormat.print} takes none of them; branch on a custom value before printing. A custom name
+   * may not reuse a built-in format's name or any other offered name.
+   */
+  readonly custom?: ReadonlyArray<C> | undefined;
 }
 /**
  * What {@link CliFormat.print} prints: the command's document and, for `json`, its data.
@@ -2402,8 +2430,8 @@ interface CliFormatPrintOptions {
  * 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"])
@@ -2417,30 +2445,61 @@ interface CliFormatPrintOptions {
 export declare class CliFormat {
   private 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}.
+   *
+   * 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 formats the command offers, at least one
-   * @param options - the default, the flag's name and its description
+   * @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 readonly flag: <const F extends CliFormatName>(formats: readonly [F, ...ReadonlyArray<F>], options?: CliFormatFlagOptions<F>) => Flag.Flag<F>;
+  static readonly flag: <const F extends CliFormatName, const A extends Readonly<Record<string, CliFormatName>> = Record<never, CliFormatName>, const C extends string = never>(formats: readonly [F, ...ReadonlyArray<F>], options?: CliFormatFlagOptions<F, A, C>) => Flag.Flag<F | A[keyof A] | C>;
   /**
    * 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
    * @param options - the stream and the JSON indent
    */
   static readonly print: (format: CliFormatName, output: CliFormatOutput, options?: CliFormatPrintOptions) => Effect.Effect<void, never, CliTheme | TerminalEnv | Audience | CliLinks>;
+  /**
+   * 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 readonly printJson: (value: unknown, options?: CliFormatPrintOptions) => Effect.Effect<void>;
 }
 declare const CliInteractive_base: Context.Reference<boolean>;
 /**
@@ -2461,6 +2520,19 @@ declare const CliInteractive_base: Context.Reference<boolean>;
  * {@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
  */
 export declare class CliInteractive extends CliInteractive_base {
@@ -2474,11 +2546,13 @@ export declare class CliInteractive extends CliInteractive_base {
    * 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 readonly layer: Layer.Layer<never, never, Audience | TerminalEnv>;
   /**
-   * 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
    */
@@ -2616,6 +2690,13 @@ export declare class CliPrompt {
    * 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
    */
@@ -2853,15 +2934,18 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    * bare invocation of a command group still print help on stdout: neither
    * is an error.
    *
+   * `main` routes through core's `CliOutput.Presenter`, so the help and
+   * errors are rendered by whichever `CliOutput` Formatter is in effect
+   * where `Command.runWith` runs, one provided inside `program` included,
+   * and written to whichever `Console` is in effect there. To change the
+   * Formatter `main` installs, pass `env.formatter` (for example
+   * `formatVersion`); a Formatter the platform provides is shadowed by
+   * `main`'s, so pass it through `env.formatter` as well.
+   *
    * Two cases keep help on stdout even under `"stderr"`. A `CliOutput`
-   * Formatter or a `Console` provided inside `program` is not seen by
-   * `main`, so its help is not rerouted. To change the Formatter, pass
-   * `env.formatter` (for example `formatVersion`): `main` installs its own
-   * Formatter inside the platform, so that is the way in, and a Formatter
-   * provided inside the program is invisible to the routing. A Formatter
-   * the platform provides is shadowed by `main`'s, so pass it through
-   * `env.formatter` as well. And with `Command.runWith`'s `renderErrors: false`
-   * no errors are printed, so nothing marks the help as a usage error's.
+   * Presenter provided inside `program` replaces the routing. And with
+   * `Command.runWith`'s `renderErrors: false` core presents the help as
+   * plain help, with no errors, so it is not a usage error's.
    */
   readonly helpOnUsageError?: "stdout" | "stderr" | undefined;
   /**
@@ -2942,7 +3026,10 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
  * 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`
@@ -3055,8 +3142,10 @@ export declare class CliRuntime {
    *
    * Under `CliRuntime.main` or {@link CliRuntime.reportFailures}, do NOT
    * print the failure yourself before failing with it: `reportFailures`
-   * renders every error except a `ShowHelp` and a `CliError.UserError` whose
-   * reported mark is `false`, so it would print twice. Fail with the marked
+   * renders every error except a `ShowHelp`, a `CliError.UserError` whose
+   * reported mark is `false`, and any error carrying a string
+   * `[CliError.userMessage]` whose reported mark is `false`, so it would
+   * print twice. Fail with the marked
    * error and put any multi-line rendering in the `render` option instead. The
    * mark matters for a program run WITHOUT `reportFailures`, where it keeps the
    * runtime from reporting a failure the program already printed.
@@ -3068,6 +3157,12 @@ export declare class CliRuntime {
    * mark. It does keep the code you pass: `reported(userError, 3)` exits `3`,
    * not `usageExitCode`.
    *
+   * The same holds for an error carrying a string `[CliError.userMessage]`:
+   * `Command.runWith` prints such a handler failure and leaves the same
+   * `false` mark, so one marked here is treated as already printed and is not
+   * rendered. Mark an error without the annotation, or leave it unmarked, if
+   * the program has not printed it. It keeps the code you pass.
+   *
    * The marks are added in place, so a typed error comes back as its own
    * type: the `E` overload returns the very instance it was given, and a
    * program failing with it keeps `catchTags` narrowing downstream without a
@@ -3130,6 +3225,12 @@ export declare class ConfigIssueRenderer {
    * `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.
@@ -3173,6 +3274,15 @@ interface PadOptions {
   /** The fill, one column wide; a space by default. Anything that is not exactly one column wide is a space. */
   readonly fill?: string | undefined;
 }
+/**
+ * Options for {@link Fmt.suggest}.
+ *
+ * @public
+ */
+interface SuggestOptions {
+  /** The most edits a suggestion may be away from the input; `2` by default, as `effect/cli` uses. */
+  readonly maxDistance?: number | undefined;
+}
 /**
  * Small, pure formatting primitives for terminal output.
  *
@@ -3308,7 +3418,11 @@ export declare class Fmt {
    * 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
    */
@@ -3327,11 +3441,50 @@ export declare class Fmt {
    *
    * 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 readonly causeMessage: (value: unknown) => string | undefined;
+  /**
+   * 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 readonly errorText: (value: unknown) => string;
+  /**
+   * 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 readonly suggest: (input: string, candidates: Iterable<string>, options?: SuggestOptions) => ReadonlyArray<string>;
 }
 /**
  * The severity of a GitHub annotation.
@@ -3794,5 +3947,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, TableOptions, TokenName, TreeInput, TreeNode, TruncateOptions };
+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 };
 //# sourceMappingURL=index.d.ts.map

package/internal/HelpRouting.js

@@ -2,88 +2,34 @@ import { Console, Effect } from "effect";
 import { CliOutput } from "effect/cli";
 
 // src/internal/HelpRouting.ts
-const OTHER_METHODS = Object.keys({
-	assert: true,
-	clear: true,
-	count: true,
-	countReset: true,
-	debug: true,
-	dir: true,
-	dirxml: true,
-	group: true,
-	groupCollapsed: true,
-	groupEnd: true,
-	info: true,
-	table: true,
-	time: true,
-	timeEnd: true,
-	timeLog: true,
-	trace: true,
-	warn: true
-});
+/**
+* Core's presenter, with an invalid invocation's help written to stderr beside
+* its errors instead of stdout.
+*
+* @remarks
+* Core's `defaultPresenter` writes an invalid invocation's help with
+* `Console.log` and its errors with `Console.error`. Here it runs under a
+* `Console` whose `log` is the ambient one's `error`, so the help and errors
+* keep core's rendering, Formatter resolution included, and only the stream
+* 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 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));
+}) };
 /**
 * Run `program` so a help document printed together with parse errors goes to
 * stderr, beside the errors, instead of stdout.
 *
 * @remarks
-* Core's `Command.runWith` prints a usage error as `Console.log(help)` then
-* `Console.error(errors)`, and an explicit `--help` or a bare group
-* invocation as the same `Console.log(help)` with nothing after it. The two
-* only differ in what follows, so the help is held: the Formatter records
-* every string its `formatHelpDoc` and `formatErrors` return, and a `log` of
-* a recorded help string waits for the next console call. An `error` of a
-* recorded errors string moves it to stderr; anything else, or the program
-* ending, releases it to stdout. At most one document is held, and output
-* order is kept.
-*
-* A Formatter or Console provided inside `program` is not wrapped, so help
-* stays on stdout there: core's own behaviour.
+* Provides core's `CliOutput.Presenter`, which `Command.runWith` hands each
+* help, invalid-invocation and version event to. A Presenter provided inside
+* `program` replaces this one.
 *
 * @internal
 */
-const routeHelpOnUsageError = (program) => Effect.gen(function* () {
-	const formatter = yield* CliOutput.Formatter;
-	const sink = yield* Console.Console;
-	const helps = /* @__PURE__ */ new Set();
-	const errors = /* @__PURE__ */ new Set();
-	let held;
-	const release = () => {
-		if (held === void 0) return;
-		const help = held;
-		held = void 0;
-		sink.log(...help);
-	};
-	const recording = Object.assign(Object.create(formatter), {
-		formatHelpDoc: (doc) => {
-			const text = formatter.formatHelpDoc(doc);
-			helps.add(text);
-			return text;
-		},
-		formatErrors: (list) => {
-			const text = formatter.formatErrors(list);
-			errors.add(text);
-			return text;
-		}
-	});
-	const routing = Object.create(sink);
-	for (const method of OTHER_METHODS) routing[method] = (...args) => {
-		release();
-		return sink[method](...args);
-	};
-	routing.log = (...args) => {
-		release();
-		if (args.length === 1 && typeof args[0] === "string" && helps.has(args[0])) held = args;
-		else sink.log(...args);
-	};
-	routing.error = (...args) => {
-		if (held !== void 0 && args.length === 1 && typeof args[0] === "string" && errors.has(args[0])) {
-			const help = held;
-			held = void 0;
-			sink.error(...help);
-		} else release();
-		sink.error(...args);
-	};
-	return yield* program.pipe(Effect.provideService(CliOutput.Formatter, recording), Effect.provideService(Console.Console, routing), Effect.ensuring(Effect.sync(release)));
-});
+const routeHelpOnUsageError = (program) => Effect.provideService(program, CliOutput.Presenter, usageErrorsToStderr);
 
 export { routeHelpOnUsageError };

package/internal/format.js

@@ -1,6 +1,9 @@
-import { SchemaIssue } from "effect";
+import { Fmt } from "../Fmt.js";
+import { SchemaAST, SchemaIssue } from "effect";
 
 // src/internal/format.ts
+/** The message an unknown key renders as: the leaf hook below writes it and the "did you mean" hint reads it. */
+const UNKNOWN_KEY = "unknown key";
 /**
 * Core's structured formatter, with one phrasing override.
 *
@@ -16,7 +19,7 @@ import { SchemaIssue } from "effect";
 *
 * @internal
 */
-const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag === "UnexpectedKey" ? "unknown key" : SchemaIssue.defaultLeafHook(issue) });
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue) => issue._tag === "UnexpectedKey" ? UNKNOWN_KEY : SchemaIssue.defaultLeafHook(issue) });
 /**
 * Flatten an issue tree to one line per rejected value.
 *
@@ -39,6 +42,74 @@ const formatter = SchemaIssue.makeFormatterStandardSchemaV1({ leafHook: (issue)
 */
 const formatIssue = (issue) => issueEntries(issue).map((entry) => entry.path.length === 0 ? entry.message : `${entry.message} at ${entry.path.join(".")}`);
 /**
+* {@link formatIssue}, with a "did you mean" hint on an unknown key the schema has a near match for.
+*
+* @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,
+* each key sanitised, and a line with no near match is exactly the line {@link formatIssue} draws.
+*
+* @internal
+*/
+const formatIssueWithHints = (issue) => {
+	const declared = declaredKeys(issue);
+	return issueEntries(issue).map((entry) => {
+		if (entry.path.length === 0) return entry.message;
+		const line = `${entry.message} at ${entry.path.join(".")}`;
+		if (entry.message !== UNKNOWN_KEY) return line;
+		const candidates = declared.get(pathKey(entry.path));
+		const input = entry.path[entry.path.length - 1];
+		if (candidates === void 0 || input === void 0) return line;
+		const near = Fmt.suggest(input, candidates);
+		if (near.length === 0) return line;
+		return `${line} (did you mean ${orList(near.map((key) => `"${Fmt.sanitize(key)}"`))}?)`;
+	});
+};
+/** A path as a map key: `JSON.stringify` keeps `["a.b"]` and `["a", "b"]` apart, which joining on `.` would not. */
+const pathKey = (path) => JSON.stringify(path);
+/** `"a"`, `"a" or "b"`, `"a", "b" or "c"`. */
+const orList = (items) => items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+/**
+* The keys each unknown key's struct declares, by the unknown key's own path.
+*
+* @remarks
+* Walks the tree the way core's formatter does (a `Pointer` extends the path; a `Filter`, `Encoding`, `Composite` or
+* `AnyOf` passes it through), so a path here is the path the formatter gives the same leaf. A union reports one
+* `UnexpectedKey` per branch at one path, and every branch's keys are candidates. Only string keys are offered: a
+* symbol key is never something a person typed into a config file.
+*/
+const declaredKeys = (issue) => {
+	const found = /* @__PURE__ */ new Map();
+	if (!SchemaIssue.isIssue(issue)) return found;
+	const walk = (node, path) => {
+		switch (node._tag) {
+			case "Filter":
+			case "Encoding":
+				walk(node.issue, path);
+				return;
+			case "Pointer":
+				walk(node.issue, [...path, ...node.path.map(String)]);
+				return;
+			case "Composite":
+			case "AnyOf":
+				for (const child of node.issues) walk(child, path);
+				return;
+			case "UnexpectedKey": {
+				if (!SchemaAST.isObjects(node.ast)) return;
+				const key = pathKey(path);
+				const keys = found.get(key) ?? /* @__PURE__ */ new Set();
+				for (const signature of node.ast.propertySignatures) if (typeof signature.name === "string") keys.add(signature.name);
+				found.set(key, keys);
+				return;
+			}
+			default: return;
+		}
+	};
+	walk(issue, []);
+	return found;
+};
+/**
 * The rejected values of an issue tree, once each: what both the lines and the tree are built from.
 *
 * @remarks
@@ -101,4 +172,4 @@ const issueTreeChildren = (entries) => {
 	return [...leaves(root), ...[...root.children].map(([name, child]) => named(name, child))];
 };
 
-export { formatIssue, issueEntries, issueTreeChildren };
+export { formatIssue, formatIssueWithHints, issueEntries, issueTreeChildren };

package/internal/logSafety.js

@@ -36,7 +36,7 @@ const sanitizeParts = (message) => {
 };
 /**
 * Neutralize the `##[` the runner's legacy parser finds anywhere in a line, inside an NDJSON record, as the JSON escape
-* `##[`: it decodes to the identical text, so the record loses nothing. A `##[` can only sit in a string there.
+* `#\u0023[`: it decodes to the identical text, so the record loses nothing. A `##[` can only sit in a string there.
 *
 * @internal
 */

package/internal/terminalCapabilities.js

@@ -0,0 +1,23 @@
+import { Config, Effect, Layer, Option } from "effect";
+import { TerminalEnv } from "@effected/env";
+import { TerminalCapabilities } from "effect/cli";
+
+// src/internal/terminalCapabilities.ts
+/**
+* Installs core's `TerminalCapabilities` from the ambient `TerminalEnv`, through `TerminalEnv.capabilities`, so core's
+* own colour decision follows the kit's rule. `TERM` is read through `Config`, and a read that fails counts as unset.
+*
+* @remarks
+* It lives here rather than in `@effected/env` because `effect/cli` exports the reference only through its barrel,
+* and a value import there would load that barrel for every env consumer. `CliInteractive.layer`, built over it,
+* then holds `canPrompt` at `true`.
+*
+* @internal
+*/
+const capabilitiesLayer = Layer.effect(TerminalCapabilities.TerminalCapabilities, Effect.gen(function* () {
+	const terminal = yield* TerminalEnv;
+	const term = yield* Config.option(Config.String("TERM")).pipe(Effect.orElseSucceed(() => Option.none()));
+	return TerminalEnv.capabilities(terminal, Option.getOrUndefined(term));
+}));
+
+export { capabilitiesLayer };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.23.0",
+	"version": "0.24.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": [
@@ -57,15 +57,15 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/commands": "^0.17.0",
-		"@effected/engine": "^0.9.0",
-		"@effected/github-commands": "^0.6.2"
+		"@effected/commands": "^0.18.0",
+		"@effected/engine": "^0.10.0",
+		"@effected/github-commands": "^0.7.0"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.21.0",
-		"@effected/env": "^0.6.0",
-		"@effected/glob": "^0.15.0",
-		"@effected/walker": "^0.21.0",
+		"@effected/config-file": "^0.22.0",
+		"@effected/env": "^0.7.0",
+		"@effected/glob": "^0.16.0",
+		"@effected/walker": "^0.22.0",
 		"@types/react": "^19.3.0",
 		"effect": "^4.0.0",
 		"ink": "^8.0.0",