@effected/cli-kit 0.0.0-stage → 0.27.0

package/ui/testing/fakeStreams.js

@@ -0,0 +1,104 @@
+import { PassThrough, Writable } from "node:stream";
+
+// src/ui/testing/fakeStreams.ts
+/** The hide-cursor escape `cli-cursor` writes to a TTY stream as it arms the restore. */
+const HIDE_CURSOR = `${String.fromCharCode(27)}[?25l`;
+/** A cursor-show escape in a listener's source, as `restore-cursor` writes it (`'\u001B[?25h'`) or as the raw byte. */
+const CURSOR_SHOW = /\[\?25h/;
+/**
+* Disarm the real terminal's cursor restore that a fake TTY arms, so no byte of a run on the fakes reaches the
+* process's own streams (#983). The fake streams call it as the hide escape is written to them.
+*
+* @remarks
+* Ink's frame writer hides the cursor through `cli-cursor` on its first render, and `cli-cursor` does it only for a
+* stream that says it is a TTY, which the fakes do. Hiding it also arms `restore-cursor`, once per loaded copy of it
+* (once per test file where the runner isolates modules): a `signal-exit` hook (`alwaysLast`, so on the `afterexit`
+* event) that writes the cursor-show escape to the REAL `process.stderr` when the process exits or is signalled,
+* whatever stream Ink was given and whether or not stderr is a terminal. Nothing on the fakes hid the real cursor, so
+* that restore is only ever a stray byte in the test runner's output: this removes every `afterexit` listener that
+* writes a cursor-show escape, right after the copy that armed it wrote its hide escape. The emitter is `signal-exit` 3's process-wide one, the version `restore-cursor` 4
+* (the one Ink 8's `cli-cursor` takes) loads; without one there is nothing to disarm.
+*
+* The one read of `process` in the testing fakes, under the process-streams licence: it touches no stream.
+*/
+const disarmCursorRestore = () => {
+	const emitter = process.__signal_exit_emitter__;
+	if (emitter === void 0) return;
+	for (const listener of emitter.listeners("afterexit")) if (CURSOR_SHOW.test(String(listener))) emitter.removeListener("afterexit", listener);
+};
+const capture = (columns, rows, both, onWrite) => {
+	const chunks = [];
+	const stream = new Writable({ write(chunk, _encoding, callback) {
+		const text = chunk.toString();
+		if (text.includes(HIDE_CURSOR)) disarmCursorRestore();
+		chunks.push(text);
+		both.push(text);
+		onWrite?.(text);
+		callback();
+	} });
+	Object.assign(stream, {
+		isTTY: true,
+		columns,
+		rows
+	});
+	return {
+		stream,
+		text: () => chunks.join("")
+	};
+};
+/**
+* Make in-memory stdin, stdout and stderr that satisfy Ink's stream contract: TTYs with a size, a recorded
+* `setRawMode`, `ref` and `unref`, and captured writes.
+*
+* @remarks
+* The third file licensed to touch Node, testing only: Ink's stream
+* contract is Node's, so the fakes are `node:stream` streams rather than a hand-rolled emitter that would have to
+* reproduce `readable`, `read()`, `setEncoding` and the write-callback barrier Ink waits on at unmount.
+*
+* @internal
+*/
+const makeFakeStreams = (options = {}) => {
+	const columns = options.columns ?? 80;
+	const rows = options.rows ?? 24;
+	const rawModes = [];
+	const stdin = new PassThrough();
+	Object.assign(stdin, {
+		isTTY: true,
+		setRawMode: (mode) => {
+			rawModes.push(mode);
+			return stdin;
+		},
+		ref: () => stdin,
+		unref: () => stdin
+	});
+	const both = [];
+	const stdout = capture(columns, rows, both, options.onStdoutWrite);
+	const stderr = capture(columns, rows, both);
+	return {
+		streams: {
+			stdin,
+			stdout: stdout.stream,
+			stderr: stderr.stream
+		},
+		rawModes,
+		stdout: stdout.text,
+		stderr: stderr.text,
+		written: () => both.join(""),
+		input: (data) => {
+			stdin.write(data);
+		},
+		resize: (nextColumns, nextRows) => {
+			Object.assign(stdout.stream, {
+				columns: nextColumns,
+				rows: nextRows
+			});
+			Object.assign(stderr.stream, {
+				columns: nextColumns,
+				rows: nextRows
+			});
+			stdout.stream.emit("resize");
+		}
+	};
+};
+
+export { makeFakeStreams };

package/ui/testing/terminalModel.js

@@ -0,0 +1,67 @@
+// src/ui/testing/terminalModel.ts
+const ESC = String.fromCharCode(27);
+/**
+* A small terminal model for the production render path: what a terminal shows after `written`, as its non-empty
+* lines.
+*
+* @remarks
+* It applies printable text, line feeds, the erase and cursor moves Ink's log-update writes (erase line, cursor up,
+* down and forward, cursor to a column, cursor to the next line), and the clears of Ink's full-clear frame: `ESC[J`
+* erases from the cursor to the end of the screen, `ESC[2J` blanks the visible screen, `ESC[3J` drops the scrollback
+* above it, `ESC[H` homes the cursor to the screen's top left. The visible screen is the last
+* `rows` lines; with `rows` unknown, the whole buffer counts as the screen, so a clear takes everything. Every other
+* escape is ignored. It does not wrap a line wider than the terminal. Shared by `CliUiTest.live`'s transcript and the
+* kit's own production-path tests.
+*
+* @param written - every byte written to the terminal
+* @param rows - the terminal's height, which decides how much of the buffer a clear takes as the screen
+*
+* @internal
+*/
+const screenAfter = (written, rows) => {
+	const lines = [""];
+	let row = 0;
+	let column = 0;
+	const screenTop = () => rows === void 0 ? 0 : Math.max(0, lines.length - rows);
+	const sequence = new RegExp(`${ESC}\\[([0-9;?]*)([A-Za-z])|${ESC}\\][^\\u0007]*\\u0007|([\\s\\S])`, "g");
+	for (const match of written.matchAll(sequence)) {
+		const [, params, command, character] = match;
+		if (character !== void 0) {
+			if (character === "\n") {
+				row++;
+				column = 0;
+				while (lines.length <= row) lines.push("");
+			} else if (character === "\r") column = 0;
+			else if (character >= " ") {
+				const line = lines[row] ?? "";
+				lines[row] = `${line.slice(0, column).padEnd(column)}${character}${line.slice(column + 1)}`;
+				column++;
+			}
+		} else if (command === "K") lines[row] = "";
+		else if (command === "A") row = Math.max(0, row - Number(params === "" ? 1 : params));
+		else if (command === "B" || command === "E") {
+			row += Number(params === "" ? 1 : params);
+			if (command === "E") column = 0;
+			while (lines.length <= row) lines.push("");
+		} else if (command === "C") column += Number(params === "" ? 1 : params);
+		else if (command === "G") column = Math.max(0, Number(params === "" ? 1 : params) - 1);
+		else if (command === "J" && (params === "" || params === "0")) {
+			lines[row] = (lines[row] ?? "").slice(0, column);
+			for (let index = row + 1; index < lines.length; index++) lines[index] = "";
+		} else if (command === "J" && params === "2") for (let index = screenTop(); index < lines.length; index++) lines[index] = "";
+		else if (command === "J" && params === "3") {
+			const top = screenTop();
+			lines.splice(0, top);
+			row = Math.max(0, row - top);
+			if (lines.length === 0) lines.push("");
+		} else if (command === "H") {
+			const [line, col] = params === "" ? [1, 1] : params.split(";").map((part) => Number(part === "" ? 1 : part));
+			row = screenTop() + (line ?? 1) - 1;
+			column = (col ?? 1) - 1;
+			while (lines.length <= row) lines.push("");
+		}
+	}
+	return lines.map((line) => line.trimEnd()).filter((line) => line !== "");
+};
+
+export { screenAfter };

package/ui-testing-serializer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `CliUiTest.serializer`: it claims a string carrying escapes or token markup and prints it as token markup with each
+ * line's trailing spaces trimmed. See `CliUiTest.serializer` for what it claims.
+ *
+ * @public
+ */
+declare const serializer: {
+  readonly test: (value: unknown) => boolean;
+  readonly serialize: (value: unknown) => string;
+};
+export { serializer as default };
+//# sourceMappingURL=ui-testing-serializer.d.ts.map

package/ui-testing-serializer.js

@@ -0,0 +1,32 @@
+import { CliUiTest } from "./ui/testing/CliUiTest.js";
+
+// src/ui-testing-serializer.ts
+/**
+* `CliUiTest.serializer` as a module's default export, for Vitest's `snapshotSerializers` config.
+*
+* @remarks
+* Vitest's `test.snapshotSerializers` takes module paths whose default export is a serializer, so registering this
+* one needs no `expect.addSnapshotSerializer` call and no shim file of your own:
+*
+* ```ts
+* // vitest.config.ts
+* import { defineConfig } from "vitest/config"
+*
+* export default defineConfig({
+*   test: { snapshotSerializers: ["@effected/cli-kit/ui/testing/serializer"] },
+* })
+* ```
+*
+* A separate entrypoint so a program's runtime import graph never loads test code.
+*
+* @packageDocumentation
+*/
+/**
+* `CliUiTest.serializer`: it claims a string carrying escapes or token markup and prints it as token markup with each
+* line's trailing spaces trimmed. See `CliUiTest.serializer` for what it claims.
+*
+* @public
+*/
+const serializer = CliUiTest.serializer;
+
+export { serializer as default };