@effected/cli-kit 0.0.0-stage → 0.26.0

package/Status.js

@@ -0,0 +1,165 @@
+import { sanitize } from "./Fmt.js";
+import { Array, Option } from "effect";
+
+// src/Status.ts
+/**
+* An open vocabulary of statuses.
+*
+* @remarks
+* Start from `Status.core` and add your own with `extend`. The names are a type parameter,
+* so `def` and `worst` reject a name the vocabulary does not have at compile time.
+*
+* @example
+* ```ts
+* import { Status } from "@effected/cli-kit"
+*
+* const vocab = Status.extend({
+* 	timeout: { glyph: "⏱", ascii: "[time]", token: "warning", rank: 85 },
+* })
+* const worst = vocab.worst(["success", "timeout"])
+* // => "timeout"
+* ```
+*
+* @public
+*/
+var Status = class Status {
+	defs;
+	constructor(defs) {
+		this.defs = defs;
+	}
+	/** The core vocabulary: success, skip, pending, info, warning and failure, by rank 10, 20, 30, 40, 60, 90. */
+	static core = new Status({
+		success: {
+			glyph: "✓",
+			ascii: "[ok]",
+			token: "success",
+			rank: 10
+		},
+		skip: {
+			glyph: "↷",
+			ascii: "[skip]",
+			token: "muted",
+			rank: 20
+		},
+		pending: {
+			glyph: "◯",
+			ascii: "[ ]",
+			token: "muted",
+			rank: 30
+		},
+		info: {
+			glyph: "ℹ",
+			ascii: "[info]",
+			token: "info",
+			rank: 40
+		},
+		warning: {
+			glyph: "⚠",
+			ascii: "[warn]",
+			token: "warning",
+			rank: 60
+		},
+		failure: {
+			glyph: "✗",
+			ascii: "[FAIL]",
+			token: "failure",
+			rank: 90
+		}
+	});
+	/**
+	* The core vocabulary plus `extra`; an entry that reuses a core name replaces it.
+	*
+	* @param extra - the statuses to add, by name
+	*/
+	static extend = (extra) => Status.core.extend(extra);
+	/**
+	* This vocabulary plus `extra`; an entry that reuses a name replaces it.
+	*
+	* @remarks
+	* An entry may replace a core name. Replacing `warning` with a lower rank moves the threshold at which
+	* `CliMessage.status` defaults to stderr for this vocabulary, since that threshold is `warning`'s rank in the
+	* vocabulary it is given.
+	*
+	* @param extra - the statuses to add, by name
+	*/
+	extend(extra) {
+		return new Status({
+			...this.defs,
+			...extra
+		});
+	}
+	/**
+	* The definition of a status.
+	*
+	* @remarks
+	* A name the vocabulary does not have is a defect: it throws an `Error` naming it and the names that exist. The
+	* types already reject one, so it is reachable only through a cast.
+	*
+	* @param name - a name in this vocabulary
+	*/
+	def(name) {
+		if (!Object.hasOwn(this.defs, name)) throw new Error(`Unknown status "${name}"; this vocabulary has: ${Object.keys(this.defs).join(", ")}`);
+		return this.defs[name];
+	}
+	/**
+	* The full definition of a status as an immutable snapshot, for a caller that stores it.
+	*
+	* @remarks
+	* `def` answers the vocabulary's own entry. `resolve` answers a frozen copy, so a document node that holds
+	* the definition stays plain data and editing it cannot change the vocabulary. The copy is shallow: a
+	* `token` given as a `Style` keeps its own identity. Throws on an unknown name, as {@link Status.def} does;
+	* storing an empty definition in a document instead would fail far from the cause.
+	*
+	* @param name - a name in this vocabulary
+	*/
+	resolve(name) {
+		return Object.freeze({ ...this.def(name) });
+	}
+	/**
+	* A status's glyph from a glyph set: `def.ascii` for an ASCII set, `def.glyph` otherwise. Unpainted, for a caller
+	* that draws it itself (an Ink tree, a reporter).
+	*
+	* @remarks
+	* Throws on an unknown name, as {@link Status.def} does. The glyph is sanitised, as text in a document is: escape
+	* sequences and control characters in a vocabulary's glyph are removed, so a glyph built from data cannot paint the
+	* terminal, plant a hyperlink or move the cursor. Every kit path that draws a status glyph takes it from here.
+	*
+	* @param name - a name in this vocabulary
+	* @param glyphs - the glyph set, such as `Glyphs.unicode`, `Glyphs.ascii` or a theme's
+	*/
+	glyph(name, glyphs) {
+		const def = this.def(name);
+		return sanitize(glyphs.kind === "ascii" ? def.ascii : def.glyph);
+	}
+	/**
+	* The status with the highest rank; a tie goes to the one that comes first in `names`.
+	*
+	* @remarks
+	* `rank` is SEVERITY, not an aggregation policy: the higher rank wins, so in `Status.core` a `skip` outranks a
+	* `success`. A consumer whose aggregate differs (a test run where passes dominate skips, say) folds its own
+	* rule over the names instead of reading this.
+	*
+	* Takes at least one name, so the answer is always a name. For an array that may be empty, use
+	* {@link Status.worstOption}. They are two methods because a literal and an array variable are the same
+	* array at runtime, so one method could not return a name for one and an `Option` for the other.
+	*
+	* @param names - the statuses to compare
+	*/
+	worst(names) {
+		let worst = names[0];
+		for (const name of names) if (this.def(name).rank > this.def(worst).rank) worst = name;
+		return worst;
+	}
+	/**
+	* The status with the highest rank of an array that may be empty: `None` when it is, otherwise `Some` of
+	* the worst, a tie going to the one that comes first in `names`. Rank is severity, not an aggregation policy; see
+	* {@link Status.worst}.
+	*
+	* @param names - the statuses to compare
+	*/
+	worstOption(names) {
+		return Array.isReadonlyArrayNonEmpty(names) ? Option.some(this.worst(names)) : Option.none();
+	}
+};
+
+export { Status };

package/TestTerminal.js

@@ -0,0 +1,101 @@
+import { Effect, Layer, Option, Queue, Terminal } from "effect";
+
+// src/TestTerminal.ts
+/**
+* A scripted `Terminal` for testing prompts and anything that reads the terminal.
+*
+* @remarks
+* Queue keys with `input` or `type`, run the program under `layer`, then read `output`. `size` behaves as a real
+* terminal's does: each subscription starts with the current size, receives every `resize`, keeps only the latest,
+* and ends when its scope closes. To assert that a code path
+* did NOT touch the terminal, queue some keys first and check `reads` is all zero (no subscription, no key, no
+* line) and `pending` is unchanged afterwards. Only
+* available from `@effected/cli-kit/testing`.
+*
+* @public
+*/
+var TestTerminal = class {
+	constructor() {}
+	/**
+	* Build a test terminal.
+	*
+	* @param options - the reported size; 80 by 24 by default
+	*/
+	static make = (options) => Effect.gen(function* () {
+		const queue = yield* Queue.unbounded();
+		const written = [];
+		let offered = 0;
+		let lines = 0;
+		let subscriptions = 0;
+		let current = {
+			columns: options?.columns ?? 80,
+			rows: options?.rows ?? 24
+		};
+		const sizeSubscribers = /* @__PURE__ */ new Set();
+		const offer = (inputs) => Effect.suspend(() => {
+			offered += inputs.length;
+			return Queue.offerAll(queue, inputs);
+		}).pipe(Effect.asVoid);
+		const terminal = Terminal.make({
+			columns: Effect.sync(() => current.columns),
+			rows: Effect.sync(() => current.rows),
+			size: Effect.acquireRelease(Effect.flatMap(Queue.sliding(1), (subscriber) => Effect.sync(() => {
+				Queue.offerUnsafe(subscriber, current);
+				sizeSubscribers.add(subscriber);
+				return subscriber;
+			})), (subscriber) => Effect.sync(() => {
+				sizeSubscribers.delete(subscriber);
+				Queue.endUnsafe(subscriber);
+			})),
+			readInput: Effect.sync(() => {
+				subscriptions++;
+				return queue;
+			}),
+			readLine: Effect.suspend(() => {
+				lines++;
+				return Effect.fail(new Terminal.QuitError({}));
+			}),
+			display: (text) => Effect.sync(() => {
+				written.push(text);
+			})
+		});
+		return {
+			layer: Layer.succeed(Terminal.Terminal, terminal),
+			input: (keys) => offer(keys.map((key) => ({
+				input: Option.none(),
+				key: {
+					name: key.name,
+					ctrl: key.ctrl ?? false,
+					meta: key.meta ?? false,
+					shift: key.shift ?? false
+				}
+			}))),
+			type: (text) => offer(Array.from(text, (char) => ({
+				input: Option.some(char),
+				key: {
+					name: char,
+					ctrl: false,
+					meta: false,
+					shift: false
+				}
+			}))),
+			end: Queue.end(queue).pipe(Effect.asVoid),
+			resize: (size) => Effect.sync(() => {
+				current = {
+					columns: size.columns,
+					rows: size.rows
+				};
+				for (const subscriber of sizeSubscribers) Queue.offerUnsafe(subscriber, current);
+			}),
+			output: Effect.sync(() => written.join("")),
+			pending: Queue.size(queue),
+			reads: Effect.map(Queue.size(queue), (size) => ({
+				keys: offered - size,
+				lines,
+				subscriptions
+			}))
+		};
+	});
+};
+
+export { TestTerminal };

package/Token.js

@@ -0,0 +1,68 @@
+// src/Token.ts
+/** The default style of every token. Deeply frozen: the record is shared. */
+const DEFAULTS = Object.freeze({
+	success: Object.freeze({ fg: "green" }),
+	failure: Object.freeze({ fg: "red" }),
+	error: Object.freeze({
+		fg: "red",
+		bold: true
+	}),
+	warning: Object.freeze({ fg: "yellow" }),
+	info: Object.freeze({ fg: "cyan" }),
+	muted: Object.freeze({ dim: true }),
+	accent: Object.freeze({ fg: "cyan" }),
+	emphasis: Object.freeze({ bold: true })
+});
+/**
+* Constructors for {@link Style} values, and the pure resolution of a token to one.
+*
+* @public
+*/
+var Token = class {
+	constructor() {}
+	/**
+	* The default {@link Style} of every token, frozen.
+	*
+	* @remarks
+	* Data, not a service: it is what `CliTheme` starts from, and a renderer with no Effect context (an Ink
+	* component) reads it directly.
+	*/
+	static defaults = DEFAULTS;
+	/**
+	* The style a token or style resolves to, as a pure function: no service, no terminal.
+	*
+	* @remarks
+	* An explicit style resolves to itself. A token name resolves to its override when `overrides` has one, else
+	* its default; a name that is not a token (including an `Object.prototype` member) resolves to the empty
+	* style. This is the same resolution `CliTheme.paint` applies, which is what `StreamTheme.style` reports.
+	*
+	* @param token - a token name or an explicit style
+	* @param overrides - styles that replace the default of a token, as `CliThemeOptions.tokens` does
+	*/
+	static resolve = (token, overrides) => {
+		if (typeof token !== "string") return token;
+		const own = overrides !== void 0 && Object.hasOwn(overrides, token) ? overrides[token] : void 0;
+		if (own !== void 0) return own;
+		return Object.hasOwn(DEFAULTS, token) ? DEFAULTS[token] : {};
+	};
+	/**
+	* A foreground from a hex colour.
+	*
+	* @param hex - `#rrggbb` (or `#rgb`)
+	*/
+	static hex = (hex) => ({ fg: hex });
+	/**
+	* A foreground from a named colour.
+	*
+	* @param color - the colour
+	*/
+	static named = (color) => ({ fg: color });
+	/**
+	* A style, as written. Exists so a style reads as a token at a call site.
+	*
+	* @param style - the style
+	*/
+	static style = (style) => style;
+};
+
+export { Token };