@effected/cli 0.10.0 → 0.11.0

package/index.js

@@ -1,8 +1,26 @@
+import { Cancelled } from "./Cancelled.js";
+import { CliInteractive } from "./CliInteractive.js";
+import { Fmt } from "./Fmt.js";
+import { CliLinks } from "./CliLinks.js";
+import { Glyphs } from "./Glyphs.js";
+import { Token } from "./Token.js";
+import { CliTheme } from "./CliTheme.js";
+import { Render } from "./Render.js";
+import { Doc } from "./Doc.js";
+import { NotInteractive } from "./NotInteractive.js";
+import { Status } from "./Status.js";
+import { CliDoc, CliFailure } from "./CliFailure.js";
+import { CliAudience } from "./CliAudience.js";
 import { CliColor } from "./CliColor.js";
+import { CliPrompt } from "./CliPrompt.js";
+import { CliEnv } from "./CliEnv.js";
 import { CliExit } from "./CliExit.js";
 import { CliLogger } from "./CliLogger.js";
+import { CliLog } from "./CliLog.js";
+import { CliMessage } from "./CliMessage.js";
 import { CliRuntime } from "./CliRuntime.js";
 import { ConfigIssueRenderer } from "./ConfigIssueRenderer.js";
+import { GithubAnnotation } from "./GithubAnnotation.js";
 import { SchemaIssueRenderer } from "./SchemaIssueRenderer.js";
 
-export { CliColor, CliExit, CliLogger, CliRuntime, ConfigIssueRenderer, SchemaIssueRenderer };
+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 };

package/internal/ansi.js

@@ -0,0 +1,230 @@
+//#region src/internal/ansi.ts
+/** Foreground SGR parameter for each named colour: 30 to 37, then 90 to 97. */
+const NAMED = {
+	black: 30,
+	red: 31,
+	green: 32,
+	yellow: 33,
+	blue: 34,
+	magenta: 35,
+	cyan: 36,
+	white: 37,
+	blackBright: 90,
+	redBright: 91,
+	greenBright: 92,
+	yellowBright: 93,
+	blueBright: 94,
+	magentaBright: 95,
+	cyanBright: 96,
+	whiteBright: 97,
+	gray: 90
+};
+/** The 16 ANSI colours as xterm draws them, in SGR order (0 to 7, then bright 8 to 15), for the basic fallback. */
+const PALETTE16 = [
+	[
+		0,
+		0,
+		0
+	],
+	[
+		205,
+		0,
+		0
+	],
+	[
+		0,
+		205,
+		0
+	],
+	[
+		205,
+		205,
+		0
+	],
+	[
+		0,
+		0,
+		238
+	],
+	[
+		205,
+		0,
+		205
+	],
+	[
+		0,
+		205,
+		205
+	],
+	[
+		229,
+		229,
+		229
+	],
+	[
+		127,
+		127,
+		127
+	],
+	[
+		255,
+		0,
+		0
+	],
+	[
+		0,
+		255,
+		0
+	],
+	[
+		255,
+		255,
+		0
+	],
+	[
+		92,
+		92,
+		255
+	],
+	[
+		255,
+		0,
+		255
+	],
+	[
+		0,
+		255,
+		255
+	],
+	[
+		255,
+		255,
+		255
+	]
+];
+/** The six levels of each axis of the xterm 6x6x6 colour cube. */
+const CUBE = [
+	0,
+	95,
+	135,
+	175,
+	215,
+	255
+];
+const ESC = "\x1B[";
+/** `#rgb` or `#rrggbb` to channels, or `undefined` when it is neither. */
+const parseHex = (hex) => {
+	const short = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i.exec(hex);
+	if (short !== null) return [
+		short[1],
+		short[2],
+		short[3]
+	].map((c) => Number.parseInt((c ?? "0").repeat(2), 16));
+	const long = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
+	if (long === null) return void 0;
+	return [
+		Number.parseInt(long[1] ?? "0", 16),
+		Number.parseInt(long[2] ?? "0", 16),
+		Number.parseInt(long[3] ?? "0", 16)
+	];
+};
+const distance = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+/** The index of the cube level nearest a channel value; the lower level wins a tie. */
+const nearestLevel = (value) => {
+	let best = 0;
+	for (let i = 1; i < CUBE.length; i++) if (Math.abs((CUBE[i] ?? 0) - value) < Math.abs((CUBE[best] ?? 0) - value)) best = i;
+	return best;
+};
+/**
+* The nearest xterm 256-colour index for a colour: the closest of the 6x6x6 cube and the 24-step grayscale
+* ramp (232 to 255) by squared RGB distance, the cube winning a tie.
+*/
+const nearest256 = (rgb) => {
+	const [r, g, b] = [
+		nearestLevel(rgb[0]),
+		nearestLevel(rgb[1]),
+		nearestLevel(rgb[2])
+	];
+	const cubeIndex = 16 + 36 * r + 6 * g + b;
+	const cubeDistance = distance(rgb, [
+		CUBE[r] ?? 0,
+		CUBE[g] ?? 0,
+		CUBE[b] ?? 0
+	]);
+	const average = (rgb[0] + rgb[1] + rgb[2]) / 3;
+	const step = Math.min(23, Math.max(0, Math.round((average - 8) / 10)));
+	const gray = 8 + 10 * step;
+	return distance(rgb, [
+		gray,
+		gray,
+		gray
+	]) < cubeDistance ? 232 + step : cubeIndex;
+};
+/** The SGR parameter of the nearest of the 16 ANSI colours: 30 to 37 or 90 to 97. */
+const nearest16 = (rgb) => {
+	let best = 0;
+	for (let i = 1; i < PALETTE16.length; i++) if (distance(rgb, PALETTE16[i] ?? [
+		0,
+		0,
+		0
+	]) < distance(rgb, PALETTE16[best] ?? [
+		0,
+		0,
+		0
+	])) best = i;
+	return best < 8 ? 30 + best : 90 + (best - 8);
+};
+/** The foreground SGR parameters for a colour at a level, or `undefined` for none. */
+const foreground = (fg, level) => {
+	if (level === "none") return void 0;
+	if (!fg.startsWith("#")) return Object.hasOwn(NAMED, fg) ? String(NAMED[fg]) : void 0;
+	const rgb = parseHex(fg);
+	if (rgb === void 0) return void 0;
+	if (level === "truecolor") return `38;2;${rgb[0]};${rgb[1]};${rgb[2]}`;
+	if (level === "256") return `38;5;${nearest256(rgb)}`;
+	return String(nearest16(rgb));
+};
+/** The wraps for a style, innermost first: foreground, then dim, bold, italic and underline outward. */
+const wraps = (style, level) => {
+	const result = [];
+	const fg = style.fg === void 0 ? void 0 : foreground(style.fg, level);
+	if (fg !== void 0) result.push({
+		open: `${ESC}${fg}m`,
+		close: `${ESC}39m`
+	});
+	if (style.dim === true) result.push({
+		open: `${ESC}2m`,
+		close: `${ESC}22m`
+	});
+	if (style.bold === true) result.push({
+		open: `${ESC}1m`,
+		close: `${ESC}22m`
+	});
+	if (style.italic === true) result.push({
+		open: `${ESC}3m`,
+		close: `${ESC}23m`
+	});
+	if (style.underline === true) result.push({
+		open: `${ESC}4m`,
+		close: `${ESC}24m`
+	});
+	return result;
+};
+/**
+* Render `text` in a style at a colour level; identity at `none`.
+*
+* Each attribute closes with its own code (39, 22, 23, 24), never a blanket reset, and a closer that occurs
+* inside `text` is followed by the opener again, so a painted span nested in a painted span leaves the outer
+* style in force for the text after it.
+*/
+const paintStyle = (style, level, text) => {
+	if (level === "none" || text === "") return text;
+	let out = text;
+	for (const { open, close } of wraps(style, level)) out = `${open}${out.replaceAll(close, `${close}${open}`)}${close}`;
+	return out;
+};
+/** The raw opening SGR sequence of a style at a level, `""` at `none` or for a style that paints nothing. */
+const openSequence = (style, level) => level === "none" ? "" : wraps(style, level).toReversed().map((wrap) => wrap.open).join("");
+
+//#endregion
+export { nearest256, openSequence, paintStyle, parseHex };

package/internal/autoFormat.js

@@ -0,0 +1,34 @@
+import { Effect, Option } from "effect";
+import { CurrentRuntimeEnv } from "@effected/env";
+
+//#region src/internal/autoFormat.ts
+/**
+* Whether the environment says the program runs under GitHub Actions, whose runner reads workflow commands out of
+* the log.
+*
+* @remarks
+* `CurrentRuntimeEnv` is read if the environment has it and is not required: without it, the answer is no.
+*
+* @internal
+*/
+const underGithubActions = Effect.gen(function* () {
+	const runtime = yield* Effect.serviceOption(CurrentRuntimeEnv);
+	return Option.contains(Option.flatMap(runtime, (env) => env.ci), "github-actions");
+});
+/**
+* The renderer an audience gets when nothing says otherwise: a person is painted, a machine reads plain text.
+*
+* @remarks
+* A CI gets GitHub's log format only where `CurrentRuntimeEnv` says it is GitHub Actions; that service is read if the
+* environment has it and is not required. Shared by `Doc.print` and the failure report.
+*
+* @internal
+*/
+const autoFormat = (audience) => Effect.gen(function* () {
+	if (audience === "human") return "ansi";
+	if (audience === "agent") return "plain";
+	return (yield* underGithubActions) ? "githubLog" : "plain";
+});
+
+//#endregion
+export { autoFormat, underGithubActions };

package/internal/canPrompt.js

@@ -0,0 +1,15 @@
+import { Config, Effect, Option } from "effect";
+
+//#region src/internal/canPrompt.ts
+/**
+* Whether the terminal facts let a run prompt: a terminal on standard input and on standard output, and a `TERM` that
+* is not `dumb`. A dumb terminal is a terminal, but it cannot move the cursor or take synchronized output, which every
+* redrawing prompt and screen needs. `TERM` is read through `Config` (never `process`), and only when both streams are
+* terminals; a read that fails counts as unset, as the env package treats every read.
+*
+* @internal
+*/
+const canPrompt = (terminal) => terminal.stdinIsTerminal && terminal.stdout.isTerminal ? Effect.map(Config.option(Config.String("TERM")).pipe(Effect.orElseSucceed(() => Option.none())), (term) => !(Option.isSome(term) && term.value === "dumb")) : Effect.succeed(false);
+
+//#endregion
+export { canPrompt };

package/internal/counts.js

@@ -0,0 +1,69 @@
+import { Fmt } from "../Fmt.js";
+
+//#region src/internal/counts.ts
+/**
+* The total of a `Counts` block: the caller's rule when it has one, otherwise the sum of `n` over every counter.
+*
+* @remarks
+* Lives here, not on `Doc`, so a renderer needs nothing from `Doc` at runtime: `Doc.print` imports the renderers, and
+* a renderer importing `Doc` back would make a cycle. `Doc.total` is this function.
+*
+* @internal
+*/
+const totalOf = (block) => block.total === void 0 ? block.counters.reduce((sum, counter) => sum + counter.n, 0) : block.total(block.counters);
+/**
+* The counters a renderer shows: every one except a zero counter that does not ask for `showZero`. `Doc.visibleCounters`
+* is this function.
+*
+* @internal
+*/
+const visibleCountersOf = (block) => block.counters.filter((counter) => counter.n !== 0 || counter.showZero === true);
+/**
+* A `CountsTable` as the `Table` it renders as: a label column, then a column per counter key in the order the keys
+* first appear, headed by that counter's label; a cell is the count painted with its status token, empty where a row
+* has no counter for the key; a duration column, when some row has a `durationMs`, formatted with `Fmt.duration`; and,
+* with `totalRow`, a last row summing each column (a missing count or duration is zero).
+*
+* @remarks
+* Plain literals, not `Doc` constructors: a renderer needs nothing from `Doc` at runtime (see {@link totalOf}).
+*
+* @internal
+*/
+const countsTableOf = (block) => {
+	const keys = [];
+	for (const row of block.rows) for (const counter of row.counters) if (!keys.some((known) => known.key === counter.key)) keys.push(counter);
+	const text = (value, token) => token === void 0 ? {
+		_tag: "Text",
+		value
+	} : {
+		_tag: "Text",
+		value,
+		token
+	};
+	const countCell = (counter) => counter === void 0 ? [] : [text(String(counter.n), counter.status.def.token)];
+	const timed = block.rows.some((row) => row.durationMs !== void 0);
+	const durationCell = (ms) => timed ? [ms === void 0 ? [] : [text(Fmt.duration(ms))]] : [];
+	const rows = block.rows.map((row) => [
+		row.label,
+		...keys.map((key) => countCell(row.counters.find((counter) => counter.key === key.key))),
+		...durationCell(row.durationMs)
+	]);
+	const totalLabel = block.totalRow === void 0 || block.totalRow === false ? void 0 : block.totalRow === true ? [text("Total")] : block.totalRow;
+	const total = totalLabel === void 0 ? [] : [[
+		totalLabel,
+		...keys.map((key) => [text(String(block.rows.reduce((sum, row) => sum + (row.counters.find((counter) => counter.key === key.key)?.n ?? 0), 0)))]),
+		...durationCell(block.rows.reduce((sum, row) => sum + (row.durationMs ?? 0), 0))
+	]];
+	return {
+		_tag: "Table",
+		columns: [
+			{ header: block.labelHeader ?? [] },
+			...keys.map((key) => ({ header: [text(key.label)] })),
+			...timed ? [{ header: block.durationHeader ?? [text("duration")] }] : []
+		],
+		rows: [...rows, ...total]
+	};
+};
+
+//#endregion
+export { countsTableOf, totalOf, visibleCountersOf };

package/internal/diagnostics.js

@@ -0,0 +1,32 @@
+import { Context, LogLevel, Logger, References } from "effect";
+
+//#region src/internal/diagnostics.ts
+/**
+* The diagnostics threshold reference behind `CliLog.Level`. Lives here so the stderr sink and the file sink share
+* one definition without `CliLog` importing itself.
+*
+* @internal
+*/
+const Level = Context.Reference("@effected/cli/CliLog/Level", { defaultValue: () => "None" });
+/**
+* Whether a diagnostics sink writes `record`. `installed` is the `MinimumLogLevel` the diagnostics layer put in
+* place: while the fiber still sees that value the sink filters on its own {@link Level}; a different value is taken
+* to be core's `--log-level` flag and the sink follows it. A flag whose value EQUALS `installed` cannot be told from
+* no flag, so the sink keeps filtering on its own level; the plain `CliLogger` prints those records anyway.
+*
+* @internal
+*/
+const passes = (record, installed) => {
+	const current = record.fiber.getRef(References.MinimumLogLevel);
+	const threshold = current === installed ? record.fiber.getRef(Level) : current;
+	return LogLevel.isGreaterThanOrEqualTo(record.logLevel, threshold);
+};
+/**
+* The NDJSON line for a record, the one shape every diagnostics sink writes.
+*
+* @internal
+*/
+const formatNdjson = (record) => Logger.formatJson.log(record);
+
+//#endregion
+export { Level, formatNdjson, passes };

package/internal/displayWidth.js

@@ -0,0 +1,35 @@
+//#region src/internal/displayWidth.ts
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+const ANSI = /\u001B\][^\u0007\u001B]*(?:\u0007|\u001B\\)|\u001B\[[0-?]*[ -/]*[@-~]/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).
+*
+* @internal
+*/
+const stripAnsi = (input) => input.replace(ANSI, "");
+/**
+* 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.
+*
+* @internal
+*/
+const displayWidth = (input) => {
+	let width = 0;
+	for (const { segment } of segmenter.segment(stripAnsi(input))) {
+		if (ZERO2.test(segment)) continue;
+		width += EMOJI.test(segment) || /^\p{RI}{2}/u.test(segment) || WIDE2.test(Array.from(segment)[0] ?? "") ? 2 : 1;
+	}
+	return width;
+};
+/**
+* The grapheme clusters of `input`, in order; a cluster is never split.
+*
+* @internal
+*/
+const graphemes = (input) => Array.from(segmenter.segment(input), (s) => s.segment);
+
+//#endregion
+export { displayWidth, graphemes, stripAnsi };

package/internal/failureTarget.js

@@ -0,0 +1,156 @@
+import { autoFormat } from "./autoFormat.js";
+import { sanitize } from "../Fmt.js";
+import { CliLinks } from "../CliLinks.js";
+import { Glyphs } from "../Glyphs.js";
+import { CliTheme } from "../CliTheme.js";
+import { Render } from "../Render.js";
+import { CliFailure } from "../CliFailure.js";
+import { Context, Effect, MutableRef, Option } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+//#region src/internal/failureTarget.ts
+/**
+* A cell `CliRuntime.main` provides outside failure reporting and fills from inside it.
+*
+* @remarks
+* `reportFailures` catches OUTSIDE the layers `main` provides, so the theme, terminal, audience and links a report is
+* rendered with are not in its context when a failure arrives. The environment layer writes the target here as it is
+* built, and an audience flag rewrites it once the flag is read. A `Reference` defaulting to `undefined`, so a
+* program run without `main` finds no cell and falls back, and no state is shared between runs.
+*
+* @internal
+*/
+const FailureTargetCell = Context.Reference("@effected/cli/FailureTargetCell", { defaultValue: () => void 0 });
+/** What a report is rendered with when nothing is known about the terminal: plain text, no limit, no escapes. */
+const fallbackTarget = {
+	ctx: {
+		width: Number.POSITIVE_INFINITY,
+		audience: "agent",
+		color: "none",
+		paint: (_token, text) => text,
+		glyphs: Glyphs.ascii,
+		link: (_target, label) => label,
+		displayPath: (absolute) => absolute,
+		neutralizeWorkflowCommands: true
+	},
+	format: "plain",
+	assumed: true
+};
+/**
+* The target for the services in the current context, or `undefined` when it lacks any of the four.
+*
+* @remarks
+* Each is read with `serviceOption`, so this never adds a requirement. `audience` overrides the one in context: an
+* audience flag is provided deeper than the environment layer, where the report cannot see it.
+*/
+const build = (audience, settings = {}) => Effect.gen(function* () {
+	const theme = yield* Effect.serviceOption(CliTheme);
+	const terminal = yield* Effect.serviceOption(TerminalEnv);
+	const current = yield* Effect.serviceOption(Audience);
+	const links = yield* Effect.serviceOption(CliLinks);
+	if (Option.isNone(theme) || Option.isNone(terminal) || Option.isNone(links)) return void 0;
+	const shape = audience ?? (Option.isSome(current) ? current.value : void 0);
+	if (shape === void 0) return void 0;
+	const { displayPath, stackFrames } = settings;
+	const ctx = yield* Render.context("stderr", displayPath === void 0 ? void 0 : { displayPath }).pipe(Effect.provideService(CliTheme, theme.value), Effect.provideService(TerminalEnv, terminal.value), Effect.provideService(CliLinks, links.value), Effect.provideService(Audience, shape));
+	const format = yield* autoFormat(ctx.audience);
+	return stackFrames === void 0 ? {
+		ctx,
+		format
+	} : {
+		ctx,
+		format,
+		stackFrames
+	};
+});
+/**
+* Record the target for the services in context in the cell, if there is one. A no-op without a cell or services.
+*
+* @internal
+*/
+const refreshFailureTarget = (audience, settings) => Effect.gen(function* () {
+	const cell = yield* FailureTargetCell;
+	if (cell === void 0) return;
+	const recorded = MutableRef.get(cell);
+	const target = yield* build(audience, settings ?? {
+		displayPath: recorded?.ctx.displayPath,
+		stackFrames: recorded?.stackFrames
+	});
+	if (target !== void 0) MutableRef.set(cell, target);
+});
+/**
+* The target a report is rendered with: the cell, else the services in context, else the plain fallback.
+*
+* @internal
+*/
+const currentTarget = Effect.gen(function* () {
+	const cell = yield* FailureTargetCell;
+	const recorded = cell === void 0 ? void 0 : MutableRef.get(cell);
+	if (recorded !== void 0) return recorded;
+	return (yield* build()) ?? fallbackTarget;
+});
+/** Content with its leading status mark (and the space after it) removed. */
+const dropStatus = (content) => {
+	if (content[0]?._tag !== "StatusMark") return content;
+	const next = content[1];
+	return next?._tag === "Text" && next.value === " " ? content.slice(2) : content.slice(1);
+};
+/**
+* A failure document without its status marks. A failure's status leads its first paragraph, or a schema failure's
+* tree label; nothing else in the document carries one.
+*/
+const withoutStatus = (doc) => doc.map((block) => {
+	if (block._tag === "Paragraph") return {
+		...block,
+		content: dropStatus(block.content)
+	};
+	if (block._tag === "Tree") return {
+		...block,
+		root: {
+			...block.root,
+			label: dropStatus(block.root.label)
+		}
+	};
+	return block;
+});
+/**
+* The lines of a failure report for a target, with or without the leading status.
+*
+* @internal
+*/
+const linesOf = (cause, target, status = true) => {
+	const full = CliFailure.toDoc(cause, {
+		displayPath: target.ctx.displayPath,
+		...target.stackFrames === void 0 ? {} : { stackFrames: target.stackFrames }
+	});
+	const doc = status ? full : withoutStatus(full);
+	const text = Render[target.format](doc, target.ctx);
+	return text === "" ? [] : text.split("\n");
+};
+/**
+* A consumer `render`'s lines, made safe: neutralized under GitHub Actions, and stripped of escapes for an agent.
+*
+* @remarks
+* What a consumer's `render` returns is text the kit did not build and cannot vouch for: it interpolates error
+* messages, file names, whatever the failure carried. So it gets the output policy the kit's own report has. Under
+* GitHub Actions (the target says so, and with no environment services at all it is assumed) every line is neutralized,
+* a returned line break splitting it first. For an agent or a CI audience the escapes are removed too (GitHub Actions
+* detects as `ci`, and the kit's own output for it has none). For a person they are kept: the kit cannot tell the consumer's own colour from an injected sequence, so the consumer's `render` is
+* responsible for sanitising what it interpolates. An audience that was only assumed is not an agent.
+*
+* @internal
+*/
+const guardConsumerLines = (lines) => Effect.map(currentTarget, (target) => {
+	const stripped = target.assumed !== true && (target.ctx.audience === "agent" || target.ctx.audience === "ci") ? lines.map(sanitize) : lines;
+	return target.ctx.neutralizeWorkflowCommands === true ? stripped.flatMap((line) => CommandNeutralizer.lines(line)) : stripped;
+});
+/**
+* The plain lines of a failure, for a caller with no services: what `CliRuntime.defaultRender` returns.
+*
+* @internal
+*/
+const plainFailureLines = (cause, status = true) => linesOf(cause, fallbackTarget, status);
+
+//#endregion
+export { FailureTargetCell, currentTarget, fallbackTarget, guardConsumerLines, linesOf, plainFailureLines, refreshFailureTarget };

package/internal/fallbackAnswer.js

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { CliError, Prompt } from "effect/cli";
+
+//#region src/internal/fallbackAnswer.ts
+/**
+* What a fallback hands core when the run is not interactive: `otherwise`, answered, when given (`undefined` counts
+* as not given); otherwise core's own missing-parameter error, so the parse fails exactly as it would with no
+* fallback and `CliRuntime.main` exits `64`. Shared by `CliPrompt.fallback` and `CliUi.fallback`.
+*
+* @internal
+*/
+const answerWithoutPerson = (target) => {
+	if ("otherwise" in target && target.otherwise !== void 0) return Effect.succeed(Prompt.succeed(target.otherwise));
+	return Effect.fail("flag" in target ? new CliError.MissingOption({ option: target.flag }) : new CliError.MissingArgument({ argument: target.argument }));
+};
+
+//#endregion
+export { answerWithoutPerson };

package/internal/fileSink.js

@@ -0,0 +1,62 @@
+import { sanitize } from "../Fmt.js";
+import { formatNdjson, passes } from "./diagnostics.js";
+import { Cause, Console, Effect, Exit, Fiber, FileSystem, Logger, Path, Queue } from "effect";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+//#region src/internal/fileSink.ts
+/** How long closing the scope waits for queued lines to reach the file before giving up on a hung filesystem. */
+const CLOSE_TIMEOUT = "2 seconds";
+/**
+* An asynchronous NDJSON file logger.
+*
+* @remarks
+* `Logger.make` takes a synchronous callback, so the logger only offers the line to a queue; a fiber scoped to the
+* layer drains it and appends each batch with `FileSystem.writeFileString(..., { flag: "a" })`. The first write
+* error prints one stderr line and disables the sink: later lines, including any still queued, are discarded
+* without a message. A defect from the filesystem counts as a write error. Closing the scope ends the queue and
+* waits for the drain for at most two seconds, so lines queued before the close are flushed unless the sink had
+* already disabled itself or the filesystem hangs; past the bound the drain is interrupted and the rest is lost.
+*
+* The stderr line is held to the rules of every other kit write: the path (which a workflow can set through an env
+* var) and the error's message are sanitised, and the line is neutralized when `underActions` says the drain's fiber
+* runs under GitHub Actions, the same decision the diagnostics sink makes.
+*
+* @internal
+*/
+const makeFileSink = (path, installed, underActions) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const location = yield* Path.Path;
+	const queue = yield* Queue.unbounded();
+	let disabled = false;
+	let directoryMade = false;
+	const append = (lines) => Effect.gen(function* () {
+		if (!directoryMade) {
+			yield* fs.makeDirectory(location.dirname(path), { recursive: true });
+			directoryMade = true;
+		}
+		yield* fs.writeFileString(path, lines.map((line) => `${line}\n`).join(""), { flag: "a" });
+	});
+	const drain = Effect.gen(function* () {
+		while (true) {
+			const batch = yield* Queue.takeAll(queue);
+			if (disabled) continue;
+			const exit = yield* Effect.exit(append(batch));
+			if (Exit.isFailure(exit)) {
+				disabled = true;
+				const error = Cause.squash(exit.cause);
+				const message = error instanceof Error ? error.message : String(error);
+				const line = sanitize(`diagnostics log file ${path} failed: ${message}; further file logging disabled`);
+				yield* Effect.withFiber((self) => Console.error(underActions(self) ? CommandNeutralizer.text(line) : line));
+			}
+		}
+	}).pipe(Effect.ignore);
+	const fiber = yield* Effect.forkScoped(drain);
+	yield* Effect.addFinalizer(() => Queue.end(queue).pipe(Effect.andThen(Fiber.join(fiber).pipe(Effect.timeout(CLOSE_TIMEOUT))), Effect.ignore));
+	return Logger.make((record) => {
+		if (!passes(record, installed)) return;
+		Queue.offerUnsafe(queue, formatNdjson(record));
+	});
+});
+
+//#endregion
+export { makeFileSink };