@effected/cli 0.22.2 → 0.23.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
@@ -2310,7 +2340,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 +2355,93 @@ 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}.
+ *
+ * @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;
+  /** 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;
+}
+/**
+ * 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.Literals` 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`.
+   *
+   * @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.
+   *
+   * @param formats - the formats the command offers, at least one
+   * @param options - the default, the flag's name and its description
+   */
+  static readonly flag: <const F extends CliFormatName>(formats: readonly [F, ...ReadonlyArray<F>], options?: CliFormatFlagOptions<F>) => Flag.Flag<F>;
+  /**
+   * 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.
+   *
+   * @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>;
+}
 declare const CliInteractive_base: Context.Reference<boolean>;
 /**
  * Whether this run may prompt a person: a human audience, with a terminal on
@@ -2598,6 +2716,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 +2771,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.
@@ -2713,6 +2864,26 @@ interface MainOptions<RP, EP> extends ReportFailuresOptions {
    * no errors are printed, so nothing marks the help as 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.
@@ -2988,6 +3159,20 @@ 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;
+}
 /**
  * Small, pure formatting primitives for terminal output.
  *
@@ -3067,6 +3252,86 @@ 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}.
+   *
+   * @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)`) applies.
+   *
+   * @param value - the error, or whatever was thrown
+   */
+  static readonly causeMessage: (value: unknown) => string | undefined;
 }
 /**
  * The severity of a GitHub annotation.
@@ -3317,6 +3582,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 +3794,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, 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 };

package/internal/causeMessage.js

@@ -0,0 +1,57 @@
+import { Predicate } from "effect";
+
+// src/internal/causeMessage.ts
+/** How many nodes of a cause chain the walk reads before stopping, so a cyclic chain cannot spin. */
+const CAUSE_DEPTH = 8;
+/**
+* The message a single node carries: a thrown string, or a non-empty string `message` property. A getter or
+* proxy trap that throws is a node with no message.
+*/
+const messageAt = (node) => {
+	try {
+		const text = Predicate.isString(node) ? node : Predicate.hasProperty(node, "message") && Predicate.isString(node.message) ? node.message : void 0;
+		return text === void 0 || text.trim() === "" ? void 0 : text;
+	} catch {
+		return;
+	}
+};
+/** The next link of the chain: a node's `cause`, or `undefined` when it has none or reading it throws. */
+const causeAt = (node) => {
+	try {
+		return Predicate.hasProperty(node, "cause") ? node.cause : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* Every distinct non-empty message a preserved cause chain carries, nearest
+* first and joined with `: `, or `undefined` when nothing along it has one.
+*
+* A `Schema.Defect()` field holds whatever was thrown, so the read is guarded
+* rather than assumed: `Predicate.hasProperty` + `Predicate.isString` accepts
+* an `Error`, a cross-realm `Error` that fails `instanceof`, a plain
+* `{ message }` object and a thrown string alike. An empty or whitespace-only
+* message counts as none. The walk follows `cause` links because a wrapper's
+* text is often the generic summary and the driver's text underneath is the
+* actionable detail, yet a wrapper that composes its own context must not
+* lose it either; so nothing is dropped, and a deeper text the nearer one
+* already contains is not repeated. The walk is bounded, so a cycle terminates.
+*
+* It never throws: every property read is guarded, so a `message` getter that throws leaves that link
+* without text, and a `cause` getter that throws ends the walk with what was found so far.
+*/
+const causeMessage = (cause) => {
+	let message;
+	let node = cause;
+	for (let depth = 0; depth < CAUSE_DEPTH && node !== void 0 && node !== null; depth++) {
+		const text = messageAt(node);
+		if (text !== void 0) {
+			if (message === void 0 || text.includes(message)) message = text;
+			else if (!message.includes(text)) message = `${message}: ${text}`;
+		}
+		node = causeAt(node);
+	}
+	return message;
+};
+
+export { causeMessage };

package/internal/displayPath.js

@@ -0,0 +1,46 @@
+import { Context, Effect, Layer, Option, Path } from "effect";
+
+// src/internal/displayPath.ts
+/**
+* The display that shows every path as it is.
+*
+* @internal
+*/
+const identity = (absolute) => absolute;
+/**
+* The path display in effect: the identity unless `CliEnv.layer` was given a `displayPath`.
+*
+* @internal
+*/
+const CurrentDisplayPath = Context.Reference("@effected/cli/CurrentDisplayPath", { defaultValue: () => identity });
+/**
+* A path relative to `root` when it lies under it, and the path unchanged when it is `root` itself or lies outside it
+* (a `../..` chain says less than the absolute path). With a `Path` service its `relative` decides; without one, a
+* plain prefix test on `/` and `\` does.
+*
+* @internal
+*/
+const relativeTo = (root, path) => Option.match(path, {
+	onSome: (p) => (absolute) => {
+		const rel = p.relative(root, absolute);
+		return rel === "" || rel === ".." || rel.startsWith(`..${p.sep}`) || rel.startsWith("../") || p.isAbsolute(rel) ? absolute : rel;
+	},
+	onNone: () => {
+		let end = root.length;
+		while (end > 0 && (root[end - 1] === "/" || root[end - 1] === "\\")) end -= 1;
+		const base = root.slice(0, end);
+		return (absolute) => {
+			const next = absolute.charAt(base.length);
+			return absolute.startsWith(base) && (next === "/" || next === "\\") && absolute.length > base.length + 1 ? absolute.slice(base.length + 1) : absolute;
+		};
+	}
+});
+/**
+* Sets {@link CurrentDisplayPath} from the option, reading `Path` from the context when it is there. No option sets
+* nothing.
+*
+* @internal
+*/
+const displayPathLayer = (option) => option === void 0 ? Layer.empty : Layer.effect(CurrentDisplayPath)(typeof option === "function" ? Effect.succeed(option) : Effect.map(Effect.serviceOption(Path.Path), (path) => relativeTo(option.relativeTo, path)));
+
+export { CurrentDisplayPath, displayPathLayer, identity, relativeTo };

package/internal/displayWidth.js

@@ -1,16 +1,24 @@
 // src/internal/displayWidth.ts
 const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
-const ANSI = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)|\u001B\[[0-?]*[ -/]*[@-~]/g;
+const ANSI = /\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001B]*(?:\u0007|\u001B\\)|[PX^_][^\u001B]*\u001B\\|[()*+\-./][0-~]|\$[()*+\-./]?[@-~]|#[3-68]| [FGLMN]|[0-?@-Z\\^_c])/g;
 const EMOJI = /^\p{RGI_Emoji}$/v;
 const WIDE2 = /[\p{Emoji_Presentation}\u1100-\u115E\u2329\u232A\u2630-\u2637\u268A-\u268F\u2E80-\u2E99\u2E9B-\u2EF3\u2F00-\u2FD5\u2FF0-\u303E\u3041-\u3096\u3099-\u30FF\u3105-\u312F\u3131-\u3163\u3165-\u318E\u3190-\u31E5\u31EF-\u321E\u3220-\u3247\u3250-\u4DBF\u4DC0-\uA48C\uA490-\uA4C6\uA960-\uA97C\uAC00-\uD7A3\uF900-\uFAFF\uFE10-\uFE19\uFE30-\uFE52\uFE54-\uFE66\uFE68-\uFE6B\uFF01-\uFF60\uFFE0-\uFFE6\u{16FE0}-\u{16FF6}\u{17000}-\u{191FF}\u{1AFF0}-\u{1AFFF}\u{1B000}-\u{1B2FF}\u{1D300}-\u{1D376}\u{1F200}-\u{1F265}\u{20000}-\u{3FFFD}]/u;
 const ZERO2 = /^[\p{Mn}\p{Me}\p{Cf}\p{Cc}\u115F\u1160\u3164\uFFA0]+$/u;
 /**
-* The text without its ANSI escape sequences: CSI (including SGR colour) and OSC (including OSC-8 hyperlinks).
+* The text without its escape sequences: CSI (including SGR colour), OSC (including OSC-8 hyperlinks), the DCS, SOS,
+* PM and APC strings, and every other escape (`ESC c`, `ESC 7`, `ESC ( B`).
 *
 * @internal
 */
 const stripAnsi = (input) => input.replace(ANSI, "");
 /**
+* Whether `input` is nothing but escape sequences, as {@link stripAnsi} reads them; empty text is not. Every sequence
+* starts with ESC, so text that does not is answered without running the strip.
+*
+* @internal
+*/
+const isEscapeOnly = (input) => input.charCodeAt(0) === 27 && stripAnsi(input) === "";
+/**
 * The display width of `input` in terminal columns: graphemes, wide East Asian characters and emoji count two,
 * combining marks, control characters and ANSI escapes count none.
 *
@@ -31,4 +39,4 @@ const displayWidth = (input) => {
 */
 const graphemes = (input) => Array.from(segmenter.segment(input), (s) => s.segment);
 
-export { displayWidth, graphemes, stripAnsi };
+export { displayWidth, graphemes, isEscapeOnly, stripAnsi };

package/internal/failureTarget.js

@@ -3,6 +3,7 @@ import { sanitize } from "../Fmt.js";
 import { CliLinks } from "../CliLinks.js";
 import { Glyphs } from "../Glyphs.js";
 import { CliTheme } from "../CliTheme.js";
+import { identity } from "./displayPath.js";
 import { Render } from "../Render.js";
 import { CliFailure } from "../CliFailure.js";
 import { Config, Context, Effect, MutableRef, Option } from "effect";
@@ -31,7 +32,7 @@ const fallbackTarget = {
 		paint: (_token, text) => text,
 		glyphs: Glyphs.ascii,
 		link: (_target, label) => label,
-		displayPath: (absolute) => absolute,
+		displayPath: identity,
 		neutralizeWorkflowCommands: true
 	},
 	format: "plain",

package/internal/inspect.js

@@ -0,0 +1,40 @@
+// src/internal/inspect.ts
+/** The value's `_tag` when it is a string; `undefined` otherwise, and when reading it throws. */
+const tagOf = (value) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	try {
+		const tag = value._tag;
+		return typeof tag === "string" ? tag : void 0;
+	} catch {
+		return;
+	}
+};
+/**
+* A failure value as report text: `String(value)`, except that a plain object whose `String` says only
+* `[object Object]` is its string `message` when it has one. `String(value)` throws for an object with no prototype or
+* a hostile `toString`: that value is `unprintable`.
+*/
+const failureText = (value, unprintable = "[unprintable value]") => {
+	try {
+		const text = String(value);
+		if (text !== "[object Object]") return text;
+		const message = value?.message;
+		return typeof message === "string" ? message : text;
+	} catch {
+		return unprintable;
+	}
+};
+/**
+* A property of a failure value, or `undefined` when it has none or reading it throws: a report must never fail on a
+* hostile getter. An `Error`'s `stack` counts, since V8 formats it on first read and the formatting reads `message`.
+*/
+const readProperty = (value, key) => {
+	if (typeof value !== "object" || value === null) return void 0;
+	try {
+		return value[key];
+	} catch {
+		return;
+	}
+};
+
+export { failureText, readProperty, tagOf };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.22.2",
+	"version": "0.23.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,13 +57,15 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
+		"@effected/commands": "^0.17.0",
+		"@effected/engine": "^0.9.0",
 		"@effected/github-commands": "^0.6.2"
 	},
 	"peerDependencies": {
-		"@effected/config-file": "^0.20.1",
-		"@effected/env": "^0.5.0",
-		"@effected/glob": "^0.14.0",
-		"@effected/walker": "^0.20.1",
+		"@effected/config-file": "^0.21.0",
+		"@effected/env": "^0.6.0",
+		"@effected/glob": "^0.15.0",
+		"@effected/walker": "^0.21.0",
 		"@types/react": "^19.3.0",
 		"effect": "^4.0.0",
 		"ink": "^8.0.0",