@effected/cli 0.22.2 → 0.24.0

package/CliTest.js

@@ -1,7 +1,57 @@
-import { Effect, FileSystem, Path, Stream } from "effect";
+import { Fmt } from "./Fmt.js";
+import { Duration, Effect, Fiber, FileSystem, Option, Path, Stream, SubscriptionRef } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 
 // src/CliTest.ts
+/** The complete lines of `captured` from `offset`, and the rest too once it has ended; with the offset after them. */
+const linesFrom = (offset, captured) => {
+	const lines = [];
+	let start = offset;
+	let end = captured.text.indexOf("\n", start);
+	while (end !== -1) {
+		lines.push(captured.text.slice(start, captured.text[end - 1] === "\r" ? end - 1 : end));
+		start = end + 1;
+		end = captured.text.indexOf("\n", start);
+	}
+	if (captured.done && start < captured.text.length) {
+		lines.push(captured.text.slice(start));
+		start = captured.text.length;
+	}
+	return [start, lines];
+};
+/** The bound on a child that ignores its termination signal, when the caller gives none. */
+const FORCE_KILL_AFTER = "2 seconds";
+/** `options.forceKillAfter` or the default; a duration that is not finite is a wiring mistake and throws. */
+const forceKillAfterOf = (options) => {
+	const input = options.forceKillAfter ?? FORCE_KILL_AFTER;
+	const duration = Duration.fromInput(input);
+	if (typeof input === "number" && Number.isNaN(input) || Option.isNone(duration) || !Duration.isFinite(duration.value) || Duration.toMillis(duration.value) < 0) throw new RangeError(`CliTest: forceKillAfter must be a finite, non-negative duration, received ${String(input)}`);
+	return duration.value;
+};
+/**
+* Core's handle fails `exitCode` for a child a signal ended, naming the signal only in the error's text; this reads it
+* back out, so a signal is an outcome as an exit code is. Any other failure (a failed stdin stream) stays a failure.
+*/
+const SIGNALLED = /receipt of signal: '(SIG[A-Z0-9]+)'/;
+const endingOf = (exitCode) => exitCode.pipe(Effect.map((code) => ({
+	exitCode: Number(code),
+	signal: null
+})), Effect.catchTag("PlatformError", (error) => {
+	const match = SIGNALLED.exec(`${error.message} ${Fmt.causeMessage(error) ?? ""}`);
+	return match === null ? Effect.fail(error) : Effect.succeed({
+		exitCode: null,
+		signal: match[1]
+	});
+}));
+const commandOf = (bin, args, options, forceKillAfter) => ChildProcess.make(options.execPath, [bin, ...args], {
+	forceKillAfter,
+	cwd: options.cwd ?? options.sandbox.root,
+	env: {
+		...options.sandbox.env,
+		...options.env
+	},
+	stdin: options.stdin === void 0 || options.stdin === "" ? Stream.empty : Stream.make(new TextEncoder().encode(options.stdin))
+});
 const text = (stream) => Stream.mkString(Stream.decodeText(stream));
 /**
 * Spawn a built CLI bin hermetically and read its exit code and streams as data.
@@ -67,28 +117,90 @@ var CliTest = class {
 	* default `"pipe"` stdio, which stays open until something writes to and
 	* ends it.
 	*/
-	static run = (bin, args, options) => Effect.scoped(Effect.gen(function* () {
-		const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-		const command = ChildProcess.make(options.execPath, [bin, ...args], {
-			cwd: options.cwd ?? options.sandbox.root,
-			env: {
-				...options.sandbox.env,
-				...options.env
-			},
-			stdin: options.stdin === void 0 || options.stdin === "" ? Stream.empty : Stream.make(new TextEncoder().encode(options.stdin))
+	static run = (bin, args, options) => {
+		const forceKillAfter = forceKillAfterOf(options);
+		return Effect.scoped(Effect.gen(function* () {
+			const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(commandOf(bin, args, options, forceKillAfter));
+			const [stdout, stderr, ending] = yield* Effect.all([
+				text(handle.stdout),
+				text(handle.stderr),
+				endingOf(handle.exitCode)
+			], { concurrency: "unbounded" });
+			return {
+				...ending,
+				stdout,
+				stderr
+			};
+		}));
+	};
+	/**
+	* Start `execPath bin ...args` and return at once with a handle on it: its output as lines while it runs, a signal,
+	* and its exit, for a long-running command (a `--follow`, a watch mode, a server) that {@link CliTest.run} would wait
+	* on forever.
+	*
+	* @remarks
+	* The child lives in the caller's scope: when the scope closes first, the child is sent `SIGTERM`, then `SIGKILL`
+	* after `forceKillAfter` (`2 seconds` by default), so a test that ends early leaves nothing running and never waits
+	* on a child that ignores the signal. A child a signal ended reports `exitCode: null` and the signal in `result`. Both streams are drained from the start whether or not the test reads them, so a
+	* chatty child never blocks on a full pipe, and each stream replays from its first line to every reader. The
+	* options are {@link CliTest.run}'s, `stdin` included: the child gets that text, then an ended input.
+	*
+	* ```ts
+	* const child = yield* CliTest.spawn("dist/bin.js", ["logs", "--follow"], { sandbox, execPath: process.execPath })
+	* yield* Stream.runHead(child.stdout) // the first line: it is following
+	* yield* child.kill("SIGINT")
+	* assert.strictEqual(yield* child.exitCode, 0)
+	* ```
+	*
+	* @param bin - the built bin to run
+	* @param args - its arguments
+	* @param options - the sandbox, the node binary, and the working directory, environment and stdin
+	*/
+	static spawn = (bin, args, options) => {
+		const forceKillAfter = forceKillAfterOf(options);
+		return Effect.gen(function* () {
+			const handle = yield* (yield* ChildProcessSpawner.ChildProcessSpawner).spawn(commandOf(bin, args, options, forceKillAfter));
+			const capture = (stream) => Effect.gen(function* () {
+				const ref = yield* SubscriptionRef.make({
+					text: "",
+					done: false
+				});
+				return {
+					ref,
+					pump: yield* Stream.decodeText(stream).pipe(Stream.runForEach((chunk) => SubscriptionRef.update(ref, (s) => ({
+						text: s.text + chunk,
+						done: false
+					}))), Effect.ensuring(SubscriptionRef.update(ref, (s) => ({
+						text: s.text,
+						done: true
+					}))), Effect.forkScoped),
+					lines: SubscriptionRef.changes(ref).pipe(Stream.takeUntil((s) => s.done), Stream.mapAccum(() => 0, linesFrom))
+				};
+			});
+			const out = yield* capture(handle.stdout);
+			const err = yield* capture(handle.stderr);
+			const ending = endingOf(handle.exitCode);
+			return {
+				stdout: out.lines,
+				stderr: err.lines,
+				kill: (signal) => handle.kill({
+					killSignal: signal ?? "SIGTERM",
+					forceKillAfter
+				}).pipe(Effect.catchTag("PlatformError", (error) => Effect.flatMap(handle.isRunning, (running) => running ? Effect.fail(error) : Effect.void))),
+				exitCode: Effect.map(ending, (end) => end.exitCode),
+				result: Effect.gen(function* () {
+					const end = yield* ending;
+					yield* Fiber.join(out.pump);
+					yield* Fiber.join(err.pump);
+					return {
+						...end,
+						stdout: (yield* SubscriptionRef.get(out.ref)).text,
+						stderr: (yield* SubscriptionRef.get(err.ref)).text
+					};
+				})
+			};
 		});
-		const handle = yield* spawner.spawn(command);
-		const [stdout, stderr, exitCode] = yield* Effect.all([
-			text(handle.stdout),
-			text(handle.stderr),
-			handle.exitCode
-		], { concurrency: "unbounded" });
-		return {
-			exitCode: Number(exitCode),
-			stdout,
-			stderr
-		};
-	}));
+	};
 };
 
 export { CliTest };

package/ConfigIssueRenderer.js

@@ -1,4 +1,4 @@
-import { formatIssue } from "./internal/format.js";
+import { formatIssueWithHints } from "./internal/format.js";
 
 // src/ConfigIssueRenderer.ts
 /**
@@ -47,11 +47,17 @@ var ConfigIssueRenderer = class {
 	* `Effect.catchTag("ConfigValidationError", …)` the error is already this
 	* type.
 	*
+	* An unknown key the schema has a near match for at the same path ends in a
+	* hint, `unknown key at theme.colour (did you mean "color"?)`, drawn from the
+	* keys the struct declares there (every branch's, under a union) with
+	* {@link Fmt.suggest}'s threshold. A key with no near match is drawn exactly
+	* as {@link SchemaIssueRenderer} draws it.
+	*
 	* It cannot throw on a malformed value: the issue tree is validated by
 	* a guard before it is read, so a renderer on an error path never becomes the
 	* reason a program dies.
 	*/
-	static render = (error) => formatIssue(error?.issue);
+	static render = (error) => formatIssueWithHints(error?.issue);
 };
 
 export { ConfigIssueRenderer };

package/Fmt.js

@@ -1,7 +1,40 @@
-import { displayWidth, graphemes, stripAnsi } from "./internal/displayWidth.js";
+import { displayWidth, graphemes, isEscapeOnly, stripAnsi } from "./internal/displayWidth.js";
 import { Duration, Option } from "effect";
+import { ErrorText } from "@effected/engine";
 
 // 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
@@ -137,6 +170,166 @@ var Fmt = class {
 	* @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/engine`'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/engine`'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/engine`'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/Render.js

@@ -4,6 +4,7 @@ import { Glyphs } from "./Glyphs.js";
 import { paintStyle } from "./internal/ansi.js";
 import { Token } from "./Token.js";
 import { CliTheme } from "./CliTheme.js";
+import { CurrentDisplayPath, identity } from "./internal/displayPath.js";
 import { renderAnsi } from "./internal/renderAnsi.js";
 import { renderPlain } from "./internal/renderPlain.js";
 import { renderGithubLog } from "./internal/renderGithubLog.js";
@@ -62,6 +63,8 @@ var Render = class {
 	* - `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
@@ -87,7 +90,7 @@ var Render = class {
 				hyperlinks: terminal[stream].hyperlinks,
 				audience: kind
 			}),
-			displayPath: options?.displayPath ?? ((absolute) => absolute)
+			displayPath: options?.displayPath ?? (yield* CurrentDisplayPath)
 		};
 	});
 	/**
@@ -117,7 +120,7 @@ var Render = class {
 				hyperlinks: true,
 				audience: options.audience
 			}),
-			displayPath: options.displayPath ?? ((absolute) => absolute),
+			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 }