@effected/cli 0.22.2 → 0.24.0

package/index.d.ts

@@ -1,6 +1,7 @@
 import { Array as Array$1, Cause, Context, Duration, Effect, FileSystem, Layer, LogLevel, Logger, MutableRef, Option, Path, Runtime, Schema, Stdio, Terminal } from "effect";
 import { Audience, AudienceKind, ColorLevel, CurrentRuntimeEnv, RuntimeEnv, TerminalEnv } from "@effected/env";
 import { CliError, CliOutput, Command, Flag, Param, Prompt } from "effect/cli";
+import { Distribution } from "@effected/engine";
 import { ConfigValidationError } from "@effected/config-file";
 declare const Cancelled_base: Schema.Class<Cancelled, Schema.TaggedStruct<"Cancelled", {
   readonly reason: Schema.Literals<readonly ["escape", "interrupt"]>;
@@ -1847,6 +1848,24 @@ export declare class CliLog {
    * cannot lower it below the level the layer installed, because Effect has already dropped those records.
    */
   static readonly Level: Context.Reference<LogLevel.LogLevel>;
+  /**
+   * Read a log level the way `CliLog.layer` reads its environment variable: `Option.some` of the level, or
+   * `Option.none()` when the text is not one.
+   *
+   * @remarks
+   * Case-insensitive, and not trimmed. The spellings are `all`, `trace`, `debug`, `info`, `warn` (or `warning`),
+   * `error`, `fatal` and `none`. For a host that reads a level from its own flag or config and wants the same answer
+   * the layer would give.
+   *
+   * @example
+   * ```ts
+   * CliLog.parseLevel("WARNING") // Option.some("Warn")
+   * CliLog.parseLevel("loud") // Option.none()
+   * ```
+   *
+   * @param text - the level's spelling
+   */
+  static parseLevel(text: string): Option.Option<LogLevel.LogLevel>;
   /**
    * The whole logger set of a program: a `CliLogger` for ordinary lines plus the diagnostics sink.
    *
@@ -2030,10 +2049,21 @@ interface CliEnvOptions {
    */
   readonly formatter?: Partial<CliOutput.Formatter> | undefined;
   /**
-   * Turns an absolute path into its display form, for example relative to the workspace: the stack frames of the
-   * default failure report are shown through it. Only `CliRuntime.main` reads this. The identity by default.
+   * How an absolute path is shown: a function, or `{ relativeTo: root }` to show a path under `root` relative to it.
+   * The identity by default.
+   *
+   * @remarks
+   * It is every path the kit shows for this run: `Render.context` takes it as its default, so `Doc.print`, a
+   * `Doc.path` or file link, and a live view's `final` document follow it, and so do the stack frames of the default
+   * failure report. An explicit `displayPath` passed to `Doc.print` or `Render.context` still wins.
+   *
+   * `{ relativeTo: root }` takes an absolute `root`. A path under it is shown relative to it; `root` itself, and a path
+   * outside it, are shown absolute, since a `../..` chain says less than the absolute path. It uses the `Path` service
+   * when the platform provides one (as `CliRuntime.main`'s does), and otherwise a plain prefix test on `/` and `\`.
    */
-  readonly displayPath?: ((absolute: string) => string) | undefined;
+  readonly displayPath?: ((absolute: string) => string) | {
+    readonly relativeTo: string;
+  } | undefined;
   /**
    * Which frames of a defect's stack the default failure report shows: `app`, the default, leaves out every
    * `node_modules` frame (Effect's and any other dependency's) and the runtime's own (every `node:` frame and every
@@ -2126,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 {
@@ -2143,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
@@ -2310,7 +2349,8 @@ interface CliFailureOptions {
  * one line `interrupted`.
  *
  * All text goes through the document, so a control character in a message or a stack frame never reaches the terminal.
- * Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
+ * Building it never throws: an error whose `_tag`, `message`, `stack`, `cause` or `issue` getter throws is drawn without
+ * that part (an unreadable `stack` as `no stack`, an unreadable `cause` ending the chain there). Render it with `Render.context` and `Render.plain`, `ansi`, `markdown` or `githubLog`, or `Doc.print` it.
  *
  * @public
  */
@@ -2324,6 +2364,143 @@ export declare class CliFailure {
    */
   static readonly toDoc: (cause: Cause.Cause<unknown>, options?: CliFailureOptions) => Document;
 }
+/**
+ * An output format a `--format` flag can offer: `auto` (the renderer the audience gets, as `Doc.print` picks it),
+ * one of the `Doc` renderers by name, or `json`, the command's data rather than its document.
+ *
+ * @public
+ */
+type CliFormatName = "auto" | "plain" | "ansi" | "markdown" | "githubLog" | "json";
+/**
+ * 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, 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.
+ *
+ * @public
+ */
+interface CliFormatOutput {
+  /** The document, built only when a document format is chosen. */
+  readonly doc: () => Document;
+  /** The data `json` prints, built only when `json` is chosen. A `json` format with no `json` here is a defect. */
+  readonly json?: (() => unknown) | undefined;
+}
+/**
+ * Options for {@link CliFormat.print}.
+ *
+ * @public
+ */
+interface CliFormatPrintOptions {
+  /** The stream to write to; stdout by default. */
+  readonly stream?: "stdout" | "stderr" | undefined;
+  /** The JSON indent, in spaces; `2` by default, `0` for one line. */
+  readonly indent?: number | undefined;
+}
+/**
+ * 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.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"])
+ * const doctor = Command.make("doctor", { format }, ({ format }) =>
+ *   CliFormat.print(format, { doc: () => report(results), json: () => results }),
+ * )
+ * ```
+ *
+ * @public
+ */
+export declare class CliFormat {
+  private constructor();
+  /**
+   * 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. 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 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, 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()` 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>;
 /**
  * Whether this run may prompt a person: a human audience, with a terminal on
@@ -2343,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 {
@@ -2356,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
    */
@@ -2498,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
    */
@@ -2598,6 +2797,22 @@ interface FailureDetails {
     readonly status?: boolean | undefined;
     readonly spans?: "app" | "all" | "off" | undefined;
   }) => ReadonlyArray<string>;
+  /**
+   * The exit code this failure exits with: the error's own `Runtime.errorExitCode` when it carries one, else its
+   * entry in `exitCodes` (a typed failure only), else `exitCode`, else `1`.
+   *
+   * @remarks
+   * The code is decided before `render` is called, so a render can print it. A hook that parses a fixed stderr shape
+   * builds it here, reading the tag off `error` itself:
+   *
+   * ```ts
+   * const render = (error: unknown, details: FailureDetails) => {
+   *   const tag = Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag) ? error._tag : "Defect";
+   *   return `${details.exitCode} ${tag}: ${Fmt.sanitize(Fmt.describe(error))}`;
+   * };
+   * ```
+   */
+  readonly exitCode: number;
 }
 /**
  * How a failure is turned into output and an exit code.
@@ -2637,6 +2852,23 @@ interface ReportFailuresOptions {
    * POSIX exit status can carry — `256` wraps to `0` and passes a failed run.
    */
   readonly exitCode?: number | undefined;
+  /**
+   * Exit codes by tag: a typed failure whose `_tag` is a key here exits with that code.
+   *
+   * @remarks
+   * Checked after the error's own `Runtime.errorExitCode` (an error that chose its code keeps it) and before
+   * `exitCode`, which stays the fallback for every other failure, defects included. Only a typed failure is looked
+   * up: a defect that happens to carry a `_tag` exits with `exitCode`. A usage error (`usageExitCode`), a cancel
+   * (`130`) and a non-interactive prompt (`64`) carry their own codes and are not looked up either.
+   *
+   * Each code must be an integer in `1..255`: `0` would pass a failed run, and `256` wraps to `0`. Anything else
+   * throws a `RangeError` when the options are passed, since it is a wiring mistake, not a runtime condition.
+   *
+   * ```ts
+   * CliRuntime.main(program, { platform, exitCodes: { DataStoreError: 3, SidecarTimeoutError: 2 }, exitCode: 5 })
+   * ```
+   */
+  readonly exitCodes?: Readonly<Record<string, number>> | undefined;
   /**
    * The exit code for a usage error: a `ShowHelp` carrying parse errors, or a
    * `CliError.UserError` `Command.runWith` already printed.
@@ -2702,17 +2934,40 @@ 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;
+  /**
+   * The carrier package the bin was installed through, when a carrier launched it: `null` (or `undefined`) for a
+   * direct install.
+   *
+   * @remarks
+   * Given (even as `null`), `main` provides `@effected/engine`'s `CurrentDistribution` around the program, as
+   * `Option.some` of the carrier or `Option.none()`, so a program and the engine it calls read the same value. With a
+   * carrier, `--version` ends with its `via <name> <version>` suffix (`distributionSuffix`), appended to whatever
+   * `formatVersion` is in effect, the coloured default or `env.formatter`'s: do not also append it in
+   * `env.formatter`.
+   *
+   * Core's default `formatVersion` prints `<name> v<version>`. A program moving off a hand-rolled `--version` that
+   * printed another shape (no `v`, say) keeps it by passing that shape as `env.formatter`'s `formatVersion`; the
+   * suffix is appended to it either way.
+   *
+   * ```ts
+   * CliRuntime.main(CliAudience.run(root, { version }), { platform, env, distribution: options.distribution ?? null })
+   * ```
+   */
+  readonly distribution?: Distribution | null | undefined;
 }
 /**
  * Report a CLI program's failures through the program's own logger.
@@ -2771,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`
@@ -2884,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.
@@ -2897,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
@@ -2959,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.
@@ -2988,6 +3260,29 @@ interface PercentOptions {
    */
   readonly scale?: 1 | 100 | undefined;
 }
+/**
+ * Options for {@link Fmt.pad}.
+ *
+ * @public
+ */
+interface PadOptions {
+  /**
+   * Where the text sits in the padded field: `left` (the default) fills on the right, `right` fills on the left, and
+   * `center` splits the fill, the odd column going on the right.
+   */
+  readonly align?: "left" | "right" | "center" | undefined;
+  /** 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.
  *
@@ -3067,6 +3362,129 @@ export declare class Fmt {
    * @param plural - the noun otherwise; `singular` with an `s` appended by default
    */
   static readonly plural: (n: number, singular: string, plural?: string) => string;
+  /**
+   * Pad `text` to `width` terminal columns, measured as {@link Fmt.width} measures: a wide character counts two and
+   * an escape sequence none, so coloured text pads to the same column as plain text.
+   *
+   * @remarks
+   * Text already `width` columns or wider is returned unchanged: compose with {@link Fmt.truncate} to cut it. A
+   * `width` that is not a finite number pads nothing. Never throws.
+   *
+   * @param text - the text to pad
+   * @param width - the columns the result should take
+   * @param options - the alignment and the fill
+   */
+  static readonly pad: (text: string, width: number, options?: PadOptions) => string;
+  /**
+   * `text` without its escape sequences: CSI (colour, cursor moves, erases), OSC (titles, OSC 8 hyperlinks) ending in
+   * BEL or ST, the DCS, SOS, PM and APC strings, and every other escape, the nF sequences (`ESC ( B`) and the
+   * two-byte ones (`ESC 7`, `ESC 8`, `ESC =`, `ESC c`).
+   *
+   * @remarks
+   * The same strip {@link Fmt.width} and {@link Fmt.sanitize} start from. Only complete sequences go: a lone ESC, or
+   * any other control character, is kept, and so is an ESC in front of a lowercase letter other than `c`, which a
+   * stray ESC before a word would otherwise cost the word its first letter. An unterminated CSI or OSC keeps its `[`
+   * or `]`. Use {@link Fmt.sanitize} for text that will be laid out and printed.
+   *
+   * @param text - the text
+   */
+  static readonly stripAnsi: (text: string) => string;
+  /**
+   * Whether `text` is nothing but escape sequences, as {@link Fmt.stripAnsi} reads them: a cursor hide or show, a
+   * clear-screen, an erase-scrollback. Empty text is not escape-only, and neither is a bare control character
+   * (`\r`, BEL), which is not an escape sequence.
+   *
+   * @param text - the text
+   */
+  static readonly isEscapeOnly: (text: string) => boolean;
+  /**
+   * Integers as compact ranges: `[1, 2, 3, 5, 10, 11]` is `"1-3,5,10-11"`, a run of consecutive numbers written
+   * `start-end` and the rest one by one, joined with commas.
+   *
+   * @remarks
+   * The input is sorted and its duplicates dropped first, so order does not matter. Anything that is not a finite
+   * integer is left out, and no input is `""`. Never throws.
+   *
+   * @param numbers - the integers, such as line numbers
+   */
+  static readonly ranges: (numbers: Iterable<number>) => string;
+  /**
+   * Any value as text, without ever throwing.
+   *
+   * @remarks
+   * A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
+   * `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
+   * `{ message }`) is that message. Anything else is its JSON, or `String(value)` when it has none (a cycle, a
+   * 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}; 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 readonly describe: (value: unknown) => string;
+  /**
+   * Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
+   * `undefined` when nothing along it has one.
+   *
+   * @remarks
+   * The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
+   * is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
+   * another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
+   * repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
+   * `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost
+   * message alone. The walk stops after eight nodes, so a cyclic chain terminates.
+   *
+   * 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)`, 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.
@@ -3317,6 +3735,8 @@ export declare class Render {
    * - `groupDepth` is the fiber's count of open Actions log groups (the fiber-local keyed by
    *   `WorkflowCommand.groupDepthKey`, which `ActionLogger.group` provides), set when it is above `0`, so a
    *   document printed inside a group opens no second one; see {@link RenderContext.groupDepth}.
+   * - `displayPath` is the option, else the run's own path display (`CliEnvOptions.displayPath`, which
+   *   `CliEnv.layer` sets), else the identity.
    *
    * @param stream - the stream the output is for
    * @param options - an explicit width and a path display function
@@ -3527,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, 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, 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/index.js

@@ -15,6 +15,7 @@ import { CliColor } from "./CliColor.js";
 import { CliPrompt } from "./CliPrompt.js";
 import { CliEnv } from "./CliEnv.js";
 import { CliExit } from "./CliExit.js";
+import { CliFormat } from "./CliFormat.js";
 import { CliLogger } from "./CliLogger.js";
 import { CliLog } from "./CliLog.js";
 import { CliMessage } from "./CliMessage.js";
@@ -23,4 +24,4 @@ import { ConfigIssueRenderer } from "./ConfigIssueRenderer.js";
 import { GithubAnnotation } from "./GithubAnnotation.js";
 import { SchemaIssueRenderer } from "./SchemaIssueRenderer.js";
 
-export { Cancelled, CliAudience, CliColor, CliDoc, CliEnv, CliExit, CliFailure, CliInteractive, CliLinks, CliLog, CliLogger, CliMessage, CliPrompt, CliRuntime, CliTheme, ConfigIssueRenderer, Doc, Fmt, GithubAnnotation, Glyphs, NotInteractive, Render, SchemaIssueRenderer, Status, Token };
+export { Cancelled, CliAudience, CliColor, CliDoc, CliEnv, CliExit, CliFailure, CliFormat, CliInteractive, CliLinks, CliLog, CliLogger, CliMessage, CliPrompt, CliRuntime, CliTheme, ConfigIssueRenderer, Doc, Fmt, GithubAnnotation, Glyphs, NotInteractive, Render, SchemaIssueRenderer, Status, Token };