@effected/cli-kit 0.0.0-stage → 0.26.0

package/Fmt.js

@@ -0,0 +1,335 @@
+import { displayWidth, graphemes, isEscapeOnly, stripAnsi } from "./internal/displayWidth.js";
+import { Duration, Option } from "effect";
+import { ErrorText } from "@effected/kit";
+
+// src/Fmt.ts
+/**
+* The Levenshtein distance between `a` and `b` when it is at most `limit`, and `limit + 1` otherwise.
+*
+* Only the diagonal band of the matrix within `limit` of it is computed (a cell outside it is past `limit` already),
+* over two rows reused in turn, and a row whose every cell is past `limit` ends the walk, since no later row can come
+* back under it: the cost is the length of `a` times `2 * limit + 1`.
+*/
+const boundedDistance = (a, b, limit) => {
+	const over = limit + 1;
+	if (Math.abs(a.length - b.length) > limit) return over;
+	const n = b.length;
+	const at = (row, j) => row[j] ?? over;
+	let previous = Array.from({ length: n + 1 }, (_, j) => j <= limit ? j : over);
+	let current = new Array(n + 1).fill(over);
+	for (let i = 1; i <= a.length; i++) {
+		const lo = Math.max(1, i - limit);
+		const hi = Math.min(n, i + limit);
+		const edge = lo === 1 && i <= limit ? i : over;
+		current[lo - 1] = edge;
+		let rowMin = edge;
+		for (let j = lo; j <= hi; j++) {
+			const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+			const cell = Math.min(at(previous, j) + 1, at(current, j - 1) + 1, at(previous, j - 1) + cost, over);
+			current[j] = cell;
+			if (cell < rowMin) rowMin = cell;
+		}
+		if (hi < n) current[hi + 1] = over;
+		if (rowMin > limit) return over;
+		[previous, current] = [current, previous];
+	}
+	return Math.min(at(previous, n), over);
+};
+const CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+/**
+* Text made safe to lay out and print: complete ANSI and OSC sequences removed, every remaining control character
+* removed (a stray ESC, BEL, BS, DEL, the C1 range) except line feed and carriage return, and a tab turned into a
+* space.
+*
+* @remarks
+* Stripping complete sequences is not enough on its own: a lone ESC survives it, and so does whatever would
+* complete a sequence once two adjacent pieces of text are joined (`ESC` in one node, `[31m` in the next). With
+* every ESC and C0 or C1 control gone after the strip, nothing can reassemble, so the width of the text equals what
+* a terminal shows. A tab counts as no columns but draws up to eight, hence the space.
+*
+* @internal
+*/
+const sanitize = (input) => stripAnsi(input).replace(/\t/g, " ").replace(CONTROL, "");
+/**
+* Small, pure formatting primitives for terminal output.
+*
+* @public
+*/
+var Fmt = class {
+	constructor() {}
+	/**
+	* Text made safe to lay out and print, exactly as the renderers make it: complete ANSI and OSC sequences removed,
+	* every other control character removed (a stray ESC, BEL, BS, DEL, the C1 range) except line feed and carriage
+	* return, and a tab turned into a space.
+	*
+	* @remarks
+	* For a `render` or any other text a program builds by hand from data it does not control: an error message, a
+	* file name, a value from the environment. Line breaks are kept, so split on them if the text must be one line.
+	*
+	* @param text - the text
+	*/
+	static sanitize = sanitize;
+	/**
+	* The display width of `text` in terminal columns: wide East Asian characters and emoji count two,
+	* combining marks and ANSI escapes count none.
+	*
+	* @param text - the text to measure
+	*/
+	static width = (text) => displayWidth(text);
+	/**
+	* Cut `text` to at most `width` columns, ending in `ellipsis` when it was cut.
+	*
+	* @remarks
+	* Grapheme-safe: a grapheme, such as a wide character or an emoji ZWJ family, is kept whole or dropped
+	* whole, so the result is never wider than `width`. Text that already fits is returned unchanged, colour
+	* escapes included. Text that must be cut is cut as plain text: its ANSI escapes are dropped rather than cut
+	* in half. When the ellipsis cannot fit, it is omitted and the text is cut to `width`; a `width` of 0 or
+	* less gives `""`.
+	*
+	* @param text - the text to truncate
+	* @param width - the most columns the result may take
+	* @param options - the ellipsis
+	*/
+	static truncate = (text, width, options) => {
+		const limit = Number.isFinite(width) ? Math.floor(width) : width === Number.POSITIVE_INFINITY ? Infinity : 0;
+		if (limit <= 0) return "";
+		if (displayWidth(text) <= limit) return text;
+		const plain = stripAnsi(text);
+		const ellipsis = options?.ellipsis ?? "…";
+		const ellipsisWidth = displayWidth(ellipsis);
+		const useEllipsis = ellipsisWidth <= limit && ellipsis !== "";
+		const budget = useEllipsis ? limit - ellipsisWidth : limit;
+		let out = "";
+		let used = 0;
+		for (const grapheme of graphemes(plain)) {
+			const w = displayWidth(grapheme);
+			if (used + w > budget) break;
+			out += grapheme;
+			used += w;
+		}
+		return useEllipsis ? `${out}${ellipsis}` : out;
+	};
+	/**
+	* A duration as short human text: `250ms`, `1.2s`, `2s`, `1m 3s`, `2m`, `1h 2m`, `2h`.
+	*
+	* @remarks
+	* Under a second it is whole milliseconds; under a minute, seconds to one decimal with a trailing `.0`
+	* dropped; under an hour, minutes and whole seconds, with the seconds dropped when zero; from an hour, hours and
+	* whole minutes, the seconds dropped. A value that rounds up to the next unit (`999.6` to a second, `59999` to a
+	* minute, `3599999` to an hour) is written in that unit, so `1000ms`, `60s` and `60m` never appear. There is no
+	* days unit. The format is bespoke: core's `Duration.format` renders differently.
+	*
+	* The input is anything `Duration.Input` admits. A plain number is milliseconds and is used as given, never
+	* converted through a `Duration`, which rounds a fractional millisecond to whole nanoseconds and would move a value
+	* such as `999.4999999` across the rounding boundary. A `bigint` is nanoseconds, as in core. A negative, infinite
+	* or invalid input (a string `Duration.Input` cannot parse) is `0ms`: a formatter in a render path never throws.
+	*
+	* @param input - the duration; a number is milliseconds
+	*/
+	static duration = (input) => {
+		const ms = typeof input === "number" ? input : Option.match(Duration.fromInput(input), {
+			onNone: () => 0,
+			onSome: Duration.toMillis
+		});
+		const value = Number.isFinite(ms) ? Math.max(0, ms) : 0;
+		const whole = Math.round(value);
+		if (whole < 1e3) return `${whole}ms`;
+		const tenths = Math.round(value / 100);
+		if (tenths < 600) return `${Number((tenths / 10).toFixed(1))}s`;
+		const seconds = Math.round(value / 1e3);
+		if (seconds >= 3600) {
+			const hours = Math.floor(seconds / 3600);
+			const remaining = Math.floor(seconds % 3600 / 60);
+			return remaining === 0 ? `${hours}h` : `${hours}h ${remaining}m`;
+		}
+		const minutes = Math.floor(seconds / 60);
+		const rest = seconds % 60;
+		return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+	};
+	/**
+	* A ratio from 0 to 1 as a percentage, or a number already from 0 to 100 with `scale: 100`: `83.3%`, `50%`,
+	* `100%`.
+	*
+	* @remarks
+	* Rounded to `digits` decimal places (one by default) with trailing zeros dropped, so whole values print
+	* without a decimal. A value that rounds to zero prints `0%`, never `-0%`. The input is not validated.
+	*
+	* @param n - the ratio, 0 to 1 (0 to 100 with `scale: 100`)
+	* @param options - the decimal places and the scale
+	*/
+	static percent = (n, options) => {
+		const digits = Math.min(10, Math.max(0, Math.floor(options?.digits ?? 1)));
+		const percent = options?.scale === 100 ? n : n * 100;
+		return `${Number(percent.toFixed(digits))}%`;
+	};
+	/**
+	* A count with its noun: `1 test`, `2 tests`, `0 tests`.
+	*
+	* @param n - the count
+	* @param singular - the noun for exactly one
+	* @param plural - the noun otherwise; `singular` with an `s` appended by default
+	*/
+	static plural = (n, singular, plural) => `${n} ${n === 1 ? singular : plural ?? `${singular}s`}`;
+	/**
+	* 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 pad = (text, width, options) => {
+		const missing = Number.isFinite(width) ? Math.floor(width) - displayWidth(text) : 0;
+		if (missing <= 0) return text;
+		const fill = options?.fill !== void 0 && displayWidth(options.fill) === 1 && stripAnsi(options.fill) === options.fill ? options.fill : " ";
+		switch (options?.align) {
+			case "right": return `${fill.repeat(missing)}${text}`;
+			case "center": {
+				const before = Math.floor(missing / 2);
+				return `${fill.repeat(before)}${text}${fill.repeat(missing - before)}`;
+			}
+			default: return `${text}${fill.repeat(missing)}`;
+		}
+	};
+	/**
+	* `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 stripAnsi = (text) => stripAnsi(text);
+	/**
+	* 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 isEscapeOnly = (text) => isEscapeOnly(text);
+	/**
+	* 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 ranges = (numbers) => {
+		const sorted = [...new Set(Array.from(numbers).filter((n) => Number.isInteger(n)))].sort((a, b) => a - b);
+		const parts = [];
+		let index = 0;
+		while (index < sorted.length) {
+			const start = sorted[index];
+			let end = start;
+			while (index + 1 < sorted.length && sorted[index + 1] === end + 1) end = sorted[++index];
+			parts.push(start === end ? `${start}` : `${start}-${end}`);
+			index++;
+		}
+		return parts.join(",");
+	};
+	/**
+	* Any value as text, without ever throwing.
+	*
+	* @remarks
+	* A string is itself; a number, boolean, bigint or symbol is `String(value)`; `undefined` and `null` are
+	* `"undefined"` and `"null"`. A value with a string `message` (an `Error`, one from another realm, a plain
+	* `{ message }`) is that message. Anything else is its JSON, or `String(value)` when it has none (a cycle, a
+	* function), or `"[unprintable value]"` when that throws too. A getter that throws is a value with no message.
+	*
+	* The text is not sanitised: pass it through {@link Fmt.sanitize} before printing data you do not control. For
+	* the messages along an error's `cause` chain, use {@link Fmt.causeMessage}; for the two combined, use
+	* {@link Fmt.errorText}.
+	*
+	* It is `@effected/kit`'s `ErrorText.describe`, the same function, so a front end that cannot depend on this
+	* package (an MCP server) describes a value with the same words.
+	*
+	* @param value - the value
+	*/
+	static describe = ErrorText.describe;
+	/**
+	* Every distinct non-empty message along a value's `cause` chain, nearest first and joined with `: `, or
+	* `undefined` when nothing along it has one.
+	*
+	* @remarks
+	* The kit's one guarded cause-message read, the one its own errors render a preserved cause with. A node's message
+	* is a thrown string or a non-empty string `message` property, read without `instanceof Error`, so an error from
+	* another realm or a plain `{ message }` object counts. A deeper message the joined text already contains is not
+	* repeated, and one that contains the joined text replaces it, so a `SqlError` wrapping SQLite's own text reads
+	* `Failed to execute statement: SQLITE_BUSY: database is locked`. It is the whole chain, not the innermost
+	* message alone. The walk stops after eight nodes, so a cyclic chain terminates.
+	*
+	* Never throws: a `message` getter that throws leaves that node without text, and a `cause` getter that throws ends
+	* the walk with the text found so far, `undefined` when there is none, so a caller's own fallback
+	* (`?? Fmt.describe(value)`, which {@link Fmt.errorText} spells once) applies.
+	*
+	* It is `@effected/kit`'s `ErrorText.causeMessage`, the same function.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static causeMessage = ErrorText.causeMessage;
+	/**
+	* The text of an unknown failure: {@link Fmt.causeMessage} when the chain carries a message, otherwise
+	* {@link Fmt.describe}.
+	*
+	* @remarks
+	* Exactly `Fmt.causeMessage(value) ?? Fmt.describe(value)`, the fallback an I/O site turning a caught value into
+	* text would otherwise spell out by hand at every call. An error whose message is empty and whose chain carries none
+	* is `""`, as `describe` reads it. Never throws, and not sanitised: pass it through {@link Fmt.sanitize} before
+	* printing data you do not control. It is `@effected/kit`'s `ErrorText.of`, the same function.
+	*
+	* @param value - the error, or whatever was thrown
+	*/
+	static errorText = ErrorText.of;
+	/**
+	* The candidates nearest to `input`, for a "did you mean" hint: those at the smallest edit distance found, up to
+	* `maxDistance` edits (two by default), in the order given, each once. No candidate that close is `[]`.
+	*
+	* @remarks
+	* The distance is Levenshtein's (one insertion, deletion or substitution per edit), over UTF-16 code units and
+	* case-sensitive, with the same two-edit threshold and the same ties-all-kept rule `effect/cli` uses for an unknown
+	* subcommand or flag, so a program's own suggestions agree with the parser's. A candidate equal to `input` is at
+	* distance zero and is the only one returned.
+	*
+	* The cost is linear in the candidates' total length: a candidate whose length differs from `input`'s by more than
+	* `maxDistance` is skipped unmeasured, and only the band of the edit matrix within `maxDistance` of its diagonal is
+	* measured, so a long typed value cannot make it quadratic. A `maxDistance` that is not a non-negative integer is a programming mistake and
+	* throws a `RangeError`.
+	*
+	* ```ts
+	* Fmt.suggest("stauts", ["status", "stack", "build"]) // => ["status"]
+	* ```
+	*
+	* @param input - what was typed: an unknown key, a profile name, a phase name
+	* @param candidates - the names it could have meant
+	* @param options - the most edits a suggestion may be away
+	*/
+	static suggest = (input, candidates, options) => {
+		const max = options?.maxDistance ?? 2;
+		if (!Number.isInteger(max) || max < 0) throw new RangeError(`Fmt.suggest: maxDistance must be a non-negative integer, received ${max}`);
+		let best = max + 1;
+		let found = [];
+		for (const candidate of new Set(candidates)) {
+			const distance = boundedDistance(input, candidate, Math.min(max, best));
+			if (distance < best) {
+				best = distance;
+				found = [candidate];
+			} else if (distance === best) found.push(candidate);
+		}
+		return best <= max ? found : [];
+	};
+};
+
+export { Fmt, sanitize };

package/GithubAnnotation.js

@@ -0,0 +1,39 @@
+import { WorkflowCommand } from "@effected/github-commands";
+
+// src/GithubAnnotation.ts
+/**
+* GitHub Actions annotations, as workflow commands.
+*
+* @public
+*/
+var GithubAnnotation = class {
+	constructor() {}
+	/**
+	* Format an annotation as a workflow command: `::error title=T,file=F,line=1,endLine=2,col=3,endColumn=4::message`.
+	*
+	* @remarks
+	* The message escapes `%`, CR and LF; a property value escapes those and `:` and `,`, per GitHub's
+	* [workflow-command documentation](https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions).
+	* The percent sign is escaped first, so an escape that was just written is never escaped again. An unescaped line
+	* break in a message would let the text after it be read as a new command, which is why the escaping is not optional.
+	*
+	* A property that is not given is left out, and the properties are written in the order `title`, `file`, `line`,
+	* `endLine`, `col`, `endColumn`, the same as `@effected/github-commands`' `WorkflowCommand`, which this renders
+	* through.
+	*
+	* @param annotation - the level and the optional file, position and title
+	* @param message - the annotation's text
+	*/
+	static format = (annotation, message) => {
+		return WorkflowCommand.render(annotation.level, {
+			title: annotation.title,
+			file: annotation.file,
+			line: annotation.line,
+			endLine: annotation.endLine,
+			col: annotation.col,
+			endColumn: annotation.endColumn
+		}, message);
+	};
+};
+
+export { GithubAnnotation };

package/Glyphs.js

@@ -0,0 +1,82 @@
+// src/Glyphs.ts
+/**
+* The two glyph sets: Unicode, and a plain-ASCII fallback for terminals that cannot draw it.
+*
+* @remarks
+* The sets are shared, so they and their nested values are frozen.
+*
+* @public
+*/
+var Glyphs = class Glyphs {
+	constructor() {}
+	/** Unicode symbols. */
+	static unicode = Object.freeze({
+		kind: "unicode",
+		ellipsis: "…",
+		spinner: Object.freeze([
+			"⠋",
+			"⠙",
+			"⠹",
+			"⠸",
+			"⠼",
+			"⠴",
+			"⠦",
+			"⠧",
+			"⠇",
+			"⠏"
+		]),
+		bullet: "•",
+		arrow: "→",
+		pathSeparator: Object.freeze({
+			human: "›",
+			agent: " > "
+		}),
+		spinnerIntervalMs: 80,
+		tree: Object.freeze({
+			branch: "├─ ",
+			last: "└─ ",
+			pipe: "│  ",
+			blank: "   "
+		})
+	});
+	/**
+	* Pick a glyph set without a service: the one `CliTheme` uses, as a pure function.
+	*
+	* @remarks
+	* `CliTheme.layer` reads `TERM` through `Config` and calls this, so the two agree. `StreamEnv` carries no
+	* `TERM`, and nothing else in it decides ASCII, so the caller passes `term` when it wants `auto` to mean
+	* something.
+	*
+	* @param options - whether to force ASCII or Unicode, and the `TERM` value `auto` reads
+	*/
+	static select = (options) => {
+		const ascii = options?.ascii ?? "auto";
+		return ascii === true || ascii === "auto" && options?.term === "dumb" ? Glyphs.ascii : Glyphs.unicode;
+	};
+	/** ASCII-only symbols. */
+	static ascii = Object.freeze({
+		kind: "ascii",
+		ellipsis: "...",
+		spinner: Object.freeze([
+			"-",
+			"\\",
+			"|",
+			"/"
+		]),
+		bullet: "*",
+		arrow: "->",
+		pathSeparator: Object.freeze({
+			human: ">",
+			agent: " > "
+		}),
+		spinnerIntervalMs: 80,
+		tree: Object.freeze({
+			branch: "|-- ",
+			last: "\\-- ",
+			pipe: "|   ",
+			blank: "    "
+		})
+	});
+};
+
+export { Glyphs };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NotInteractive.js

@@ -0,0 +1,41 @@
+import { Runtime, Schema } from "effect";
+
+// src/NotInteractive.ts
+/**
+* A command needed to prompt, but there is no terminal to prompt on.
+*
+* @remarks
+* Exits `64` (BSD `EX_USAGE`) through core's `Runtime.errorExitCode` marker:
+* the caller invoked the command the wrong way, so the fix is to run it in a
+* terminal or pass the flag that supplies the answer. Its default rendering is
+* one line, `not interactive: run in a terminal or pass the flag`, which is the error's `message`, so a consumer
+* `render` can print `error.message` and keep it.
+*
+* @public
+*/
+var NotInteractive = class extends Schema.TaggedError()("NotInteractive", {}) {
+	/**
+	* The one line, `not interactive: run in a terminal or pass the flag`.
+	*
+	* @remarks
+	* A prototype getter, not a field, so it is not part of the encoded form, equality or a JSON dump. Assigning to
+	* it is ignored: a library that rewrites `error.message` must not make this error throw, which a getter-only
+	* property does in strict mode. The line is fixed.
+	*/
+	get message() {
+		return "not interactive: run in a terminal or pass the flag";
+	}
+	set message(_value) {}
+	/**
+	* The process exit code: `64`.
+	*
+	* @remarks
+	* A prototype getter rather than an own field, so a JSON or logger dump of the error does not carry the
+	* runtime marker. It is the error's own code, so `CliRuntime`'s `usageExitCode` option does not change it.
+	*/
+	get [Runtime.errorExitCode]() {
+		return 64;
+	}
+};
+
+export { NotInteractive };