@effected/cli-kit 0.0.0-stage → 0.27.0

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# @effected/cli-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@effected%2Fcli?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/cli-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+The presentation boundary of a command-line program built on `effect/cli`: who the output is for, and how it reaches them. Plain log lines on the right stream. Colour, glyphs and links only where the terminal and the reader can use them. Documents rendered for a person, an agent or a CI log. Failures reported through your own logger with the right exit code. Prompts that know when there is nobody to ask. Interactive screens and live progress views drawn with Ink. `effect/cli` still owns argument parsing, flags, the command tree and help; this package adds no parser and no command model.
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/cli-kit
+
+Everything here shares one property: **you only discover you needed it by shipping bad output to a person or a machine.** None of it fails a type-check, a test, or a review of the code in isolation.
+
+Effect's default logger emits `[00:33:56.619] INFO (#2): message`, which is right for a service and noise for a tool someone is watching. A platform `runMain` reports an unhandled failure through that same default logger, outside the layers your program was given, so it prints on **stdout**, the one stream errors must not use. Colour codes end up in an agent's context window. A prompt fires inside a pipe and hangs. A file name containing `::error::` becomes a workflow command in GitHub Actions. And a decode failure arrives as a structured tree when a user needs a sentence naming the key they got wrong.
+
+This package makes those decisions once, at the edge of the program, from the environment it actually runs in.
+
+## Install
+
+```bash
+npm install @effected/cli-kit @effected/env @effected/glob @effected/walker effect
+```
+
+```bash
+pnpm add @effected/cli-kit @effected/env @effected/glob @effected/walker effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4, `@effected/env` (the audience and terminal services), and `@effected/walker` with its `@effected/glob` peer (the project root for editor links) are peer dependencies. The one runtime dependency is `@effected/github-commands`. The package never imports a platform package, so it runs unchanged on Node, Bun and Deno.
+
+Optional peers:
+
+- **`ink` and `react`**, plus **`@types/react`** for TypeScript, for the interactive screens and live views in `@effected/cli-kit/ui`. The root never reaches them, and `./ui` loads neither until a screen first mounts. Without `@types/react`, a program compiled with `skipLibCheck` silently types every screen as `any`.
+
+  ```bash
+  npm install ink react @types/react
+  ```
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
+
+## Quick start
+
+One wiring serves every program: share the audience flags on the root command, run it through `CliAudience.run`, and hand that to `CliRuntime.main` with an `env`.
+
+```ts
+import { CliAudience, CliExit, CliMessage, CliRuntime, Doc } from "@effected/cli-kit";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Effect } from "effect";
+import { Command } from "effect/cli";
+
+const sync = Command.make("sync", {}, () =>
+  Effect.gen(function* () {
+    yield* CliMessage.info("syncing 2 repositories");
+    yield* Doc.print([
+      Doc.table(
+        [{ header: "Repository" }, { header: "Files", align: "right" }],
+        [
+          ["acme/widgets", "12"],
+          ["acme/gadgets", "3"],
+        ],
+      ),
+    ]);
+    yield* CliMessage.warning("acme/gadgets has no default branch");
+    // A finding, not a crash: the handler succeeds and the run still exits 1.
+    yield* CliExit.set(1);
+  }),
+);
+
+const root = Command.make("tool").pipe(Command.withSharedFlags(CliAudience.flags()), Command.withSubcommands([sync]));
+
+NodeRuntime.runMain(
+  CliRuntime.main(CliAudience.run(root, { version: "1.0.0" }), {
+    platform: NodeServices.layer,
+    env: {
+      audienceEnvVar: "TOOL_AUDIENCE",
+      stderrIsTerminal: Effect.sync(() => process.stderr.isTTY === true),
+    },
+  }),
+);
+```
+
+```text
+$ tool sync
+ℹ syncing 2 repositories
+Repository    Files
+------------  -----
+acme/widgets     12
+acme/gadgets      3
+⚠ acme/gadgets has no default branch
+$ echo $?
+1
+```
+
+At a colour terminal the glyphs are painted and the header is bold. For an agent (`--agent`, `TOOL_AUDIENCE=agent`, or an agent detected from the environment), in a pipe, or under `NO_COLOR`, the same program writes no escape sequence of any kind. Under GitHub Actions, anything the runner could read as a workflow command is neutralized. A failure anywhere renders as a short report on stderr and exits non-zero.
+
+## Audiences
+
+The audience is decided once per run: an audience flag (`--audience <human|agent|ci>`, `--human`, `--agent`, `--ci`), then the override variable you name, then an agent detected from the environment, then CI, else a human. It decides:
+
+| | Human | Agent | CI |
+| --- | --- | --- | --- |
+| Colour | When the stream has it | Never, even with `FORCE_COLOR` | When the stream has it (messages) |
+| `Doc.print` | `ansi`: painted, OSC 8 links | `plain` | `githubLog` under GitHub Actions, else `plain` |
+| Width | The terminal's | Unbounded | Unbounded |
+| Diagnostics (`CliLog`) | Pretty lines | NDJSON | NDJSON |
+| Prompts and screens | When interactive | Never | Never |
+
+Colour follows Node's precedence, per stream: `FORCE_COLOR` decides first and beats `NO_COLOR` (`1`–`3` on, even in a pipe; `0` off). Otherwise there is no colour without a terminal. On a terminal, a non-empty `NO_COLOR`, `NODE_DISABLE_COLORS` or `TERM=dumb` turns it off. `TERM=dumb` also switches to ASCII glyphs and makes the run non-interactive.
+
+## Output
+
+- **`CliMessage`**: `success`, `info`, `warning`, `failure` and `status(vocab, name, text)`. One themed line each, through `Console` rather than the logger, so no log level silences them. Warnings and failures go to stderr.
+- **`Doc` and `Render`**: a document IR (headings, paragraphs, lists, tables, trees, counts, count tables, collapsibles, callouts, code blocks, diffs, GitHub annotations) and pure `plain`, `ansi`, `markdown` and `githubLog` renderers. `Doc.print` picks the renderer for the audience, and lays out at the terminal's width only when the stream is a terminal: piped output (`tool | grep`) never wraps. `Doc.line(content, { wrap: false })` keeps one line whole at any width, glyph and colour included. `Render.contextOf` renders outside Effect, for example markdown for a step summary.
+- **`CliTheme`, `Token`, `Status`, `Glyphs`**: semantic tokens (`success`, `failure`, `warning`, `info`, `error`, `muted`, `accent`, `emphasis`), an extendable status vocabulary with glyphs and ranks, and Unicode or ASCII glyph sets. Override tokens with `env.theme`.
+- **`CliLinks`**: file links that open in VS Code (`vscode://file/…`) or as `file://` URLs, as OSC 8 hyperlinks where the terminal renders them, never for an agent.
+- **`Fmt`**: `sanitize`, `width`, `truncate`, `duration`, `percent` and `plural`.
+
+Every string that enters a document or a message is sanitised: escape sequences and control characters are removed, so data cannot paint the terminal or plant a link.
+
+## Failures and exit codes
+
+`CliRuntime.main` reports a failure as a document on stderr, through the audience's renderer: a status line for a typed failure, a tree of rejected values for a schema failure, and a defect's message with a collapsible stack of your own frames (Effect's, Node's and `node_modules` frames hidden). Give an error class a `[CliDoc]()` method to draw itself, or pass a `render` option. Its `details.lines({ status: false })` keeps the run's colour and paths behind your own prefix. The `in: outer › inner` span trail after a failure names only your own spans by default; `env.spans` (`"app"`, `"all"` or `"off"`) chooses, as `env.stackFrames` does for a defect's frames. `"app"` leaves out spans defined in files under `node_modules/@effected/` or `node_modules/effect/`, and fails open: a kit package linked into a workspace, or a bundled program, shows more, never less. A program that is itself installed under `node_modules/@effected/` passes its bin's `import.meta.url` as `env.appModule` to keep its own spans. `env.spansEnvVar` names a variable (say `TOOL_SPANS`) that sets it at run time, as `log.envVar` sets the level. An `Effect.fn` call and its definition are one entry in the trail.
+
+- `CliExit.set(code)` records a findings exit code from a handler that still succeeds. Do not provide `CliExit.layer` yourself under `main`, or the code goes to a second, unread cell.
+- `Cancelled` (a prompt quit) exits `130`, and `NotInteractive` (a prompt with nobody to ask) exits `64`, each as one fixed line.
+- A usage error exits `64`. `helpOnUsageError: "stderr"` keeps stdout clean for a caller piping it into `jq`.
+- Without `main`: `CliRuntime.reportFailures()` is the combinator to apply inside your program, and `CliRuntime.reported(error, code)` marks an error you printed yourself.
+
+`SchemaIssueRenderer.render(issue)` and `ConfigIssueRenderer.render(error)` turn an issue tree into lines like `unknown key at groups.g.rulesetz`.
+
+## Logging
+
+`CliLogger` writes plain lines, with no timestamp, level or fiber id, and routes every level to stderr by default (`stderrFrom` narrows it), so stdout carries only the program's output. Pass `env.log` to `main` for **`CliLog`**: a diagnostics level of its own (`level`, or `envVar` such as `TOOL_LOG_LEVEL`, with core's `--log-level` beating both), pretty lines for a person and NDJSON for an agent or CI, an optional NDJSON log file, and `CliLog.component(name)` tags. `CliLog.status(vocab, name, text)` logs a diagnostic with a painted status glyph (its text still sanitised), and `CliTheme.forAudience` applies the kit's "an agent never gets an escape" rule to a theme you paint with yourself.
+
+## Prompts and screens
+
+A prompt fires only when `CliInteractive` is true: a human audience, a terminal on stdin and stdout, and `TERM` not `dumb`. Otherwise it answers a default you supply, or fails cleanly.
+
+```ts
+import { CliPrompt } from "@effected/cli-kit";
+import { Flag, Prompt } from "effect/cli";
+
+// Core's prompt as a flag fallback: asks at a terminal, uses "library" in a pipe.
+const profile = Flag.String("profile").pipe(
+  Flag.withFallbackPrompt(
+    CliPrompt.fallback(
+      Prompt.Select({ message: "Profile", choices: [{ title: "library", value: "library" }, { title: "application", value: "application" }] }),
+      { flag: "profile", otherwise: "library" },
+    ),
+  ),
+);
+```
+
+`@effected/cli-kit/ui` adds Ink screens: `CliUi.run`, `prompt` (with an `otherwise`) and `fallback` (for a flag), over the widgets `Select`, `TextInput` (with a `mask` for secrets, always, or from the moment a predicate spots one anywhere in the value, latched until the value is cleared: its `validate` message is drawn unmasked, so never echo the value in it), `MultiSelect`, `Confirm` (with toggles), `Toggle`, `Tabs` and `Viewport`. Your own screens use the key layer (`KeyTable`, `useKeys`, `KeyHelp`) and the theme bridge (`Styled`, `useTheme`, `useGlyphs`, `useTerminalSize`).
+
+```tsx
+import { CliUi, Select } from "@effected/cli-kit/ui";
+
+const pickProfile = Select.screen({
+  message: "Profile",
+  choices: [
+    { label: "library", value: "library" },
+    { label: "application", value: "application" },
+  ],
+});
+
+const profile = CliUi.prompt(pickProfile, { otherwise: "library" });
+```
+
+`CliUi.map(screen, f)` maps a screen's answer and leaves a cancel alone, so a `Confirm` can back a boolean flag ("confirm, or `--yes`"):
+
+```ts
+import { CliUi, Confirm } from "@effected/cli-kit/ui";
+import { Flag } from "effect/cli";
+
+const yes = Flag.Boolean("yes").pipe(
+  Flag.withFallbackPrompt(
+    CliUi.fallback(
+      CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
+      { flag: "yes", otherwise: false },
+    ),
+  ),
+);
+```
+
+## Live views
+
+`CliUi.live` folds a stream or a `PubSub` subscription of events into state, and draws **runs** with Ink while they are going: a run starts at `isStart`, redraws on a tick, and commits its final frame at `isTerminal`. Log lines go above the frame through `handle.logConsole`. End with `handle.close`, which folds everything still queued. When nobody is watching (a pipe, an agent, CI), each run's final frame prints once instead: give the view a `final: (state) => Document` and that run prints the document with no Ink or React loaded at all; `render` is then never called on such a run, not even to build an unused string. `render: CliUi.lazyView(() => import("./view.js"))` keeps the view's module, and React, off every run until one draws. `DocView` draws a `Doc` document inside a view byte for byte as `Doc.print` would, and `UiProvider` with `CliUi.context` gives an Ink tree you mount yourself the same theme.
+
+## Testing
+
+- **`@effected/cli-kit/testing`**: `CliTest.sandbox` and `CliTest.run` spawn a built bin hermetically and return `{ exitCode, stdout, stderr }` as data. `TestTerminal` drives core's prompts.
+- **`@effected/cli-kit/ui/testing`**: `CliUiTest.render` mounts a screen on in-memory streams (`press`, `type`, `chunk`, `frame`, `result`). `view` mounts a display-only element, `session` drives a whole command's screens (its `transcript` shows what reached the terminal, a live view's `logConsole` lines included, `stdoutWritten`/`stderrWritten` each stream alone as raw bytes, `stdoutTranscript`/`stderrTranscript` each stream alone as plain text, and `renderPath: "production"` makes `clear` observable), and `live` mounts a live view on the production render path with a `TestClock` tick. `CliUiTest.serializer` prints frames as token markup in snapshots: register it in the Vitest config with `snapshotSerializers: ["@effected/cli-kit/ui/testing/serializer"]`, or with `expect.addSnapshotSerializer`. Snapshots are the one place a test needs `expect`, since `assert` has no snapshot form.
+
+In-process, provide `layerTest`s from `@effected/env` and `CliTheme.layerTest`, swap in a capturing `Console`, and assert on both streams. Neither testing entrypoint is reachable from a CLI's runtime imports.
+
+## Documentation
+
+Guides for every part, and the full API reference, are at [effected.spencerbeg.gs/cli](https://effected.spencerbeg.gs/cli): [getting started](https://effected.spencerbeg.gs/cli/getting-started), [audiences and output](https://effected.spencerbeg.gs/cli/output), [prompts and screens](https://effected.spencerbeg.gs/cli/prompts), [live views](https://effected.spencerbeg.gs/cli/live-views), [testing](https://effected.spencerbeg.gs/cli/testing) and [advanced](https://effected.spencerbeg.gs/cli/advanced).
+
+## License
+
+[MIT](LICENSE)

package/Render.js

@@ -0,0 +1,280 @@
+import { CliLinks } from "./CliLinks.js";
+import { CliTheme } from "./CliTheme.js";
+import { Glyphs } from "./Glyphs.js";
+import { paintStyle } from "./internal/ansi.js";
+import { underGithubActions } from "./internal/autoFormat.js";
+import { CurrentDisplayPath, identity } from "./internal/displayPath.js";
+import { renderAnsi } from "./internal/renderAnsi.js";
+import { renderGithubLog } from "./internal/renderGithubLog.js";
+import { renderMarkdown } from "./internal/renderMarkdown.js";
+import { renderPlain } from "./internal/renderPlain.js";
+import { Token } from "./Token.js";
+import { Context, Effect } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CommandNeutralizer, WorkflowCommand } from "@effected/github-commands";
+
+// src/Render.ts
+/**
+* The fiber-local count of open Actions log groups, by the kit-wide key, so a group `@effected/github-actions`'
+* `ActionLogger.group` opened is visible here without an edge between the two packages.
+*/
+const GroupDepth = Context.Reference(WorkflowCommand.groupDepthKey, { defaultValue: () => 0 });
+/** A renderer's text, with workflow commands neutralized when the context says the runner is reading it. */
+const guarded = (text, ctx) => ctx.neutralizeWorkflowCommands === true ? CommandNeutralizer.text(text) : text;
+/**
+* Pure renderers of a document: `(doc, context) => string`.
+*
+* @remarks
+* A renderer has no environment and no effects, so the same document and context always give the same string.
+* {@link Render.plain} is for agents; the rest of the set follows.
+*
+* @example
+* ```ts
+* import { Doc, Render } from "@effected/cli-kit"
+*
+* const doc = [Doc.heading(2, "Results"), Doc.paragraph("3 checks passed")]
+* const ctx = Render.contextOf({ audience: "agent" })
+*
+* Render.plain(doc, ctx)
+* // => "Results\n3 checks passed"
+* ```
+*
+* @public
+*/
+var Render = class {
+	constructor() {}
+	/**
+	* The {@link RenderContext} for a stream, from the services a CLI already has.
+	*
+	* @remarks
+	* Everything is read once, here, so the renderers stay pure:
+	*
+	* - `audience` is the `Audience` in force, so an audience flag is honoured;
+	* - `color`, `paint` and `glyphs` are the `CliTheme`'s for THAT stream, so redirecting stdout does not quiet
+	*   stderr; except that an agent's `color` is `none` and its `paint` the identity, so no renderer, `ansi` included,
+	*   writes an escape for an agent whatever the terminal could do;
+	* - `link` is `CliLinks.linker` over that stream's hyperlink support and the audience, so an agent never
+	*   gets an escape and a terminal without OSC 8 gets the label;
+	* - `neutralizeWorkflowCommands` is set when `CurrentRuntimeEnv` says GitHub Actions (read if present, not
+	*   required), for every audience, since the runner reads whatever is written there;
+	* - `width` is the option, else `TerminalEnv.width()` for a human whose stream is a terminal, and **unbounded**
+	*   (`Infinity`) for a human whose stream is not one (`tool | grep`, `tool > out.txt`), an agent or a CI, so nothing
+	*   a reader needs is truncated or wrapped for a terminal that is not there: a pipe has no width to honour;
+	* - `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
+	*/
+	static context = (stream, options) => Effect.gen(function* () {
+		const terminal = yield* TerminalEnv;
+		const { kind } = yield* Audience;
+		const theme = (yield* CliTheme).forStream(stream);
+		const seen = CliTheme.forAudience(theme, kind);
+		const links = yield* CliLinks;
+		const underActions = yield* underGithubActions;
+		const groupDepth = yield* GroupDepth;
+		return {
+			...underActions ? { neutralizeWorkflowCommands: true } : {},
+			...groupDepth > 0 ? { groupDepth } : {},
+			width: options?.width ?? (kind === "human" && terminal[stream].isTerminal ? terminal.width() : Number.POSITIVE_INFINITY),
+			audience: kind,
+			color: seen.color,
+			paint: seen.paint,
+			glyphs: theme.glyphs,
+			link: CliLinks.linker({
+				links,
+				hyperlinks: terminal[stream].hyperlinks,
+				audience: kind
+			}),
+			displayPath: options?.displayPath ?? (yield* CurrentDisplayPath)
+		};
+	});
+	/**
+	* A {@link RenderContext} from plain options, for a caller outside Effect, such as a test reporter or an Ink tree.
+	*
+	* @remarks
+	* Pure: nothing is read from the environment. The defaults are colour `none`, the identity paint, no links,
+	* Unicode glyphs, unbounded width and the identity `displayPath`, so a context built from an audience alone renders
+	* with no escape of any kind. A colour level paints with the default token styles. An `agent` is colourless and
+	* unlinked whatever `color` and `links` say, as in {@link Render.context}.
+	*
+	* @param options - the audience, and the colour, glyphs, width, path display, links, neutralizing, link base and
+	*   open group depth
+	*/
+	static contextOf = (options) => {
+		const agent = options.audience === "agent";
+		const color = agent ? "none" : options.color ?? "none";
+		const links = agent ? "off" : options.links ?? "off";
+		return {
+			width: options.width ?? Number.POSITIVE_INFINITY,
+			audience: options.audience,
+			color,
+			paint: color === "none" ? (_token, text) => text : (token, text) => paintStyle(Token.resolve(token), color, text),
+			glyphs: options.glyphs ?? Glyphs.unicode,
+			link: links === "off" ? (_target, label) => label : CliLinks.linker({
+				links,
+				hyperlinks: true,
+				audience: options.audience
+			}),
+			displayPath: options.displayPath ?? identity,
+			...options.neutralizeWorkflowCommands ?? options.audience === "ci" ? { neutralizeWorkflowCommands: true } : options.neutralizeWorkflowCommands === false ? { neutralizeWorkflowCommands: false } : {},
+			...options.linkBase === void 0 ? {} : { linkBase: options.linkBase },
+			...options.groupDepth === void 0 ? {} : { groupDepth: options.groupDepth }
+		};
+	};
+	/**
+	* Render a document as plain text for an agent.
+	*
+	* @remarks
+	* There are no escape sequences of any kind, whatever the context's colour or hyperlinks allow: `paint` and
+	* `link` are never called, and a control character in a document's text is removed. The audience is treated as
+	* `agent`, so a path joins with ` > `.
+	*
+	* - A heading is its text alone, code is in backticks, and a link is its label followed by the target in
+	*   parentheses, as `path:line:col` through `displayPath` for a file, unless the label already is the target.
+	* - A paragraph wraps to the width and is never truncated; a word longer than the width, such as a URL, stays
+	*   whole on its own line.
+	* - A list uses `- ` items, and past its cap the overflow row. A table is aligned text columns with a rule under
+	*   the header; a short row is padded with empty cells, a cell holding line breaks shows its first line and an
+	*   ellipsis, and cells are truncated only when the table is wider than the context, widest column first. A tree uses the glyph set's tree segments.
+	* - A collapsible is its title and the indented body, a callout its upper-case kind and the body, a code block
+	*   four-space indented, and a diff `- expected` lines then `+ received` lines, the cap limiting each side.
+	* - Counts take their total and their visible counters from {@link Doc.total} and {@link Doc.visibleCounters}.
+	*   Inline gives `3/5 passed, 1 failed (1.2s)`: the first counter is the headline and shows its share of the
+	*   total, unless `share` is `false`. Columns gives aligned label and number pairs, and row one line of cells.
+	* - A link with `suffix: false` never has its target after the label, and one with `suffix: true` always does.
+	* - Verbatim text is its lines exactly, each indented by `indent` spaces, never wrapped; an annotation is nothing.
+	* - Strong and emphasised content is its text; a file is its display path, unlinked. `Lines` are one line per entry,
+	*   a `Line` with `truncate` is cut to the width with the ellipsis, and diff text is its lines as given, the cap
+	*   followed by `… N more lines`. A counts table is a table with a column per counter key and the total row last,
+	*   and a counts `suffix` follows the duration.
+	* - A compact list has no blank lines inside an item. A `style: "pipe"` table is istanbul's shape: a rule of dashes
+	*   meeting at `|` above and below the header and at the end, and cells joined with ` | `.
+	* - Top-level blocks are consecutive lines; a section separates its title and children with blank lines.
+	*
+	* @param doc - the document
+	* @param ctx - where the output is going
+	*/
+	static plain = (doc, ctx) => guarded(renderPlain(doc, ctx), ctx);
+	/**
+	* Render a document for a person: the same layout as {@link Render.plain}, painted and linked.
+	*
+	* @remarks
+	* The context's `paint` and `link` do the styling, so a context at colour `none` with links off gives exactly
+	* what `plain` gives, apart from two things: code has no backticks (it is painted `accent` instead), and a path
+	* joins with the audience's separator (`›` for a person) rather than ` > `. Tokens:
+	*
+	* - headings, section and collapsible titles, and table headers are `emphasis`; the rule under a header, tree
+	*   lines and overflow rows are `muted`;
+	* - a status glyph takes its definition's token, and a diff's `-` lines are `failure` and `+` lines `success`;
+	* - a callout's label takes its kind's token (`note` info, `tip` success, `important` accent, `warning` warning,
+	*   `caution` error), and a counter the token of its status, with the qualifier, the duration and the suffix `muted`.
+	*   A `Counts` with `paint: "none"` paints none of it, and with `paint: "glyph"` only a status glyph.
+	* - strong content is bold and emphasised content italic, over any token it has; in diff text a `+` line is
+	*   `success` and a `-` line `failure`; a counts table's counts take their status's token.
+	*
+	* A link goes through `ctx.link`, which makes an OSC 8 hyperlink only when the policy allows it. When it does
+	* not (it returns the label unchanged), the target follows the label in parentheses, muted, as in plain text.
+	*
+	* Text is cut and wrapped before it is painted, so a colour or a hyperlink is never cut in half, and a table
+	* cut to the width keeps the colour of what remains. Tables are plain aligned columns, never box drawing:
+	* box drawing costs two columns of every row for nothing a rule and the padding do not already say, and it
+	* cannot be matched to plain text.
+	*
+	* @param doc - the document
+	* @param ctx - where the output is going
+	*/
+	static ansi = (doc, ctx) => guarded(renderAnsi(doc, ctx), ctx);
+	/**
+	* Render a document as GitHub-flavoured markdown, for a step summary or a file.
+	*
+	* @remarks
+	* There is no ANSI and no OSC 8 (`paint` and `link` are never called), and the width does not apply: a reader
+	* wraps. Everything a document carries as text is escaped so that it cannot become markdown: the characters
+	* that mean something, `|` everywhere so text can never form a table, the marker at the start of a line (a
+	* heading, bullet, setext underline or ordered item) and the start of an autolink (a URL scheme or `www.`). An
+	* email address is not escaped: a reader may make a `mailto:` link of it, which is harmless. A leading indent is
+	* dropped, since markdown would read it as code.
+	*
+	* Under GitHub Actions (`neutralizeWorkflowCommands`) the same neutralizing applies, since markdown can be printed
+	* to the log. Markdown escapes `[` in text, so `##[` cannot appear outside code and the headings are untouched
+	* (a bare `##` is not a command); code spans and blocks, which are not escaped, get the blank marker, which can
+	* also land inside code or table text where it would otherwise have formed a command.
+	*
+	* GitHub also turns `@user`, `@org/team`, `#123` and commit SHAs in rendered markdown into mentions and references.
+	* Nothing here escapes them: in a step summary they do not notify, but markdown posted as a comment could ping
+	* whoever the text names.
+	*
+	* - A heading is `#` repeated by its level. A section's title is a heading of level 2 for a section at the top,
+	*   one deeper for each section nested inside it, to level 6.
+	* - A table is a GFM pipe table: `|` is `\|` in a cell and a line break in a cell is `<br>`. A short row is
+	*   padded and a long one widens the table. With no header, the header row is empty.
+	* - A collapsible is `<details><summary>title</summary>`, a blank line, the body as markdown, a blank line and
+	*   `</details>`. The title is HTML, so it is HTML-escaped and plain.
+	* - A callout is a quoted `[!KIND]` followed by its body. A code block is a fence longer than any backtick run it
+	*   holds, and a diff a `diff` fence of `-` and `+` lines.
+	* - A link is `[label](url)` when it has a URL a reader can follow: an `http`, `https`, `mailto`, `file` or
+	*   `vscode` URL, or a relative one. A file link has one when its path is absolute (`file://`). Otherwise, such as
+	*   for a `javascript:` URL or a relative file path, it is the label followed by the target in inline code, as
+	*   `path:line:col` for a file.
+	* - A list is bullets, a tree a nested bullet list under its root label, and overflow rows paragraphs after what
+	*   they cap. Counts inline is a paragraph, columns a list of `label: n` and row a one-row table of the counter
+	*   labels over their numbers, every header named (the duration as `duration`), with the label above the table and
+	*   the qualifier and suffix below it.
+	* - Verbatim text is a fenced code block, so its indentation survives; an annotation is nothing.
+	* - Strong content is `**…**` and emphasised `*…*`, which GFM reads inside a word too, with the spaces at a run's
+	*   edges kept outside the markers. `Lines` are one paragraph with a hard break between entries, an empty entry
+	*   between two others an empty line (one at either end is dropped); a `Line` is one
+	*   paragraph; diff text a `diff` fence; a counts table a pipe table; a file is its display path as text.
+	* - With `linkBase`, a file link goes to the base and the display path, plus `#L<line>`, in place of `file://`. A
+	*   display path that is absolute or climbs out with `..` is not under the base, so its link has no URL form.
+	* - A compact list item joins its parts with no blank line, putting a hard break where two paragraphs would merge.
+	*   A row of counts names its duration column `duration`.
+	*
+	* @param doc - the document
+	* @param ctx - where the output is going; its glyph set, audience and `displayPath` are used
+	*/
+	static markdown = (doc, ctx) => guarded(renderMarkdown(doc, ctx), ctx);
+	/**
+	* Render a document for a GitHub Actions log.
+	*
+	* @remarks
+	* Everything is what {@link Render.plain} renders, except an annotation, which is one workflow command
+	* (`::error file=…,line=…::message`), and a collapsible that starts a line, which is a group: `::group::title`, its
+	* body, `::endgroup::`. An annotation is a command at the top level, as a top-level section's child, and as a direct
+	* child of a group's body; anywhere deeper (inside a list, a callout, or a section within a group) it is nothing,
+	* as in plain. Its message and properties are escaped, so no text can end
+	* the command or start another, and the kit's own command is never neutralized, though a `##[` in its message,
+	* title or file is. That is a top-level collapsible, or one that is a direct child of a
+	* top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
+	* (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
+	*
+	* A group already open around the output counts the same way. When the context's `groupDepth` is above `0`
+	* ({@link RenderContext.groupDepth}, which `Render.context` reads from the fiber-local `ActionLogger.group` in
+	* `@effected/github-actions` provides, by the key `WorkflowCommand.groupDepthKey`), a top-level collapsible keeps
+	* plain's rendering too, so a document printed inside an `ActionLogger.group` does not open a second group, which
+	* would end the first at the runner. The depth is the context's, read when the context was built. What no depth
+	* can fix is two fibers writing groups at once: the runner has one log stream, so concurrent sibling groups, this
+	* renderer's or `ActionLogger`'s, interleave in it. Render and print a document from the fiber that owns the
+	* stream, not from a fiber racing another group.
+	*
+	* The runner has two command parsers, and a line is a command if either accepts it: after its leading whitespace it
+	* starts with `::`, or `##[` occurs ANYWHERE in it (a bare `##` is not one). A document's text must not be able to
+	* do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a braille pattern blank (U+2800) in
+	* front, which the runner neither trims nor skips, and every `##[` gets one before the `[`. The text is
+	* otherwise unchanged. A
+	* group's title is a command's data, so its `%`, CR and LF are escaped and a `##[` in it is neutralized. Lines are split at CR, LF and CRLF before
+	* that check, as the runner splits them. There is no ANSI and `paint` and `link` are never called, and the audience
+	* is treated as `agent`, as `plain` does.
+	*
+	* @param doc - the document
+	* @param ctx - where the output is going; the width, glyph set and `displayPath` are used as plain uses them
+	*/
+	static githubLog = (doc, ctx) => renderGithubLog(doc, ctx);
+};
+
+export { Render };

package/SchemaIssueRenderer.js

@@ -0,0 +1,47 @@
+import { formatIssue } from "./internal/format.js";
+
+// src/SchemaIssueRenderer.ts
+/**
+* Turns a `SchemaIssue` tree into lines a user can act on.
+*
+* @remarks
+* A decode failure arrives as a structured tree; a person needs
+* `unknown key at groups.g.cleanup.rulesetz`. The formatters core ships for
+* this live on `SchemaIssue` rather than on `SchemaError` or `Schema`, and
+* `SchemaError.message` does not use them, so printing the error alone does not
+* give these lines.
+*
+* The lines and `CliFailure`'s tree are two views of the same rejected values (`internal/format`), so a schema
+* failure in the default report and these lines never disagree.
+*
+* @example
+* ```ts
+* import { SchemaIssueRenderer } from "@effected/cli-kit"
+* import { Effect, Schema } from "effect"
+*
+* const result = Schema.decodeUnknownEffect(MySchema)(input, {
+*   onExcessProperty: "error",
+*   errors: "all",
+* })
+*
+* const reported = result.pipe(
+*   Effect.catchTag("SchemaError", (error) =>
+*     Effect.forEach(SchemaIssueRenderer.render(error.issue), (line) => Effect.logError(`  ${line}`)),
+*   ),
+* )
+* ```
+*
+* @public
+*/
+var SchemaIssueRenderer = class {
+	constructor() {}
+	/**
+	* One line per rejected value, deepest path last.
+	*
+	* @param issue - a `SchemaIssue` tree, or any value
+	* @returns the lines, or empty when `issue` is not an issue tree
+	*/
+	static render = (issue) => formatIssue(issue);
+};
+
+export { SchemaIssueRenderer };