@effected/cli-kit 0.0.0-stage → 0.26.0

package/index.js

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

@@ -0,0 +1,21 @@
+import { Runtime } from "effect";
+
+// src/internal/ExitRequested.ts
+/**
+* The failure `CliRuntime.main` raises when a successful program recorded a
+* non-zero exit code through `CliExit`. Private: nothing outside this package
+* constructs or matches it, and `reportFailures` never renders it.
+*
+* @internal
+*/
+var ExitRequested = class extends Error {
+	[Runtime.errorReported] = false;
+	[Runtime.errorExitCode];
+	constructor(code) {
+		super(`exit ${code}`);
+		this.name = "ExitRequested";
+		this[Runtime.errorExitCode] = code;
+	}
+};
+
+export { ExitRequested };

package/internal/HelpRouting.js

@@ -0,0 +1,35 @@
+import { Console, Effect } from "effect";
+import { CliOutput } from "effect/cli";
+
+// src/internal/HelpRouting.ts
+/**
+* Core's presenter, with an invalid invocation's help written to stderr beside
+* its errors instead of stdout.
+*
+* @remarks
+* Core's `defaultPresenter` writes an invalid invocation's help with
+* `Console.log` and its errors with `Console.error`. Here it runs under a
+* `Console` whose `log` is the ambient one's `error`, so the help and errors
+* keep core's rendering, Formatter resolution included, and only the stream
+* moves. An explicit `--help`, a bare group invocation and `--version` are
+* other events, presented by core unchanged on stdout.
+*/
+const usageErrorsToStderr = { present: (event) => event._tag !== "InvalidInvocation" ? CliOutput.defaultPresenter.present(event) : Effect.gen(function* () {
+	const sink = yield* Console.Console;
+	const toStderr = Object.assign(Object.create(sink), { log: (...args) => sink.error(...args) });
+	yield* CliOutput.defaultPresenter.present(event).pipe(Effect.provideService(Console.Console, toStderr));
+}) };
+/**
+* Run `program` so a help document printed together with parse errors goes to
+* stderr, beside the errors, instead of stdout.
+*
+* @remarks
+* Provides core's `CliOutput.Presenter`, which `Command.runWith` hands each
+* help, invalid-invocation and version event to. A Presenter provided inside
+* `program` replaces this one.
+*
+* @internal
+*/
+const routeHelpOnUsageError = (program) => Effect.provideService(program, CliOutput.Presenter, usageErrorsToStderr);
+
+export { routeHelpOnUsageError };

package/internal/ansi.js

@@ -0,0 +1,229 @@
+// 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("");
+
+export { nearest256, openSequence, paintStyle, parseHex };

package/internal/autoFormat.js

@@ -0,0 +1,33 @@
+import { Effect, Option } from "effect";
+import { CurrentRuntimeEnv } from "@effected/env";
+
+// 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";
+});
+
+export { autoFormat, underGithubActions };

package/internal/canPrompt.js

@@ -0,0 +1,14 @@
+import { Config, Effect, Option } from "effect";
+
+// 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);
+
+export { canPrompt };

package/internal/counts.js

@@ -0,0 +1,83 @@
+import { Fmt } from "../Fmt.js";
+
+// src/internal/counts.ts
+/**
+* The label a counter shows for a count: its one label, or `one` when the count is exactly 1 and `other` otherwise.
+* The count is the counter's own `n`, except in a share headline (`1/3 repos`), which reads by the denominator, the
+* total, and passes it.
+*
+* @internal
+*/
+const counterLabel = (counter, count = counter.n) => typeof counter.label === "string" ? counter.label : count === 1 ? counter.label.one : counter.label.other;
+/**
+* The label a counter's column is headed with in a `CountsTable`: its one label, or its plural form, since a column
+* holds every row's count.
+*
+* @internal
+*/
+const columnLabel = (counter) => typeof counter.label === "string" ? counter.label : counter.label.other;
+/**
+* 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(columnLabel(key))] })),
+			...timed ? [{ header: block.durationHeader ?? [text("duration")] }] : []
+		],
+		rows: [...rows, ...total]
+	};
+};
+
+export { columnLabel, counterLabel, countsTableOf, totalOf, visibleCountersOf };

package/internal/diagnostics.js

@@ -0,0 +1,31 @@
+import { Context, LogLevel, Logger, References } from "effect";
+
+// 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-kit/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);
+
+export { Level, formatNdjson, passes };

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-kit/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

@@ -0,0 +1,42 @@
+// src/internal/displayWidth.ts
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+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 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.
+*
+* @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);
+
+export { displayWidth, graphemes, isEscapeOnly, stripAnsi };