@effected/cli-kit 0.0.0-stage → 0.27.0

package/ui/internal/inkConsole.js

@@ -0,0 +1,150 @@
+import { UiStreams } from "../UiStreams.js";
+import { inkModules } from "./ink.js";
+import { Effect, Inspectable } from "effect";
+
+// src/ui/internal/inkConsole.ts
+/** One argument as a console shows it: a string as is, an `Error` with its stack, anything else as data (JSON). */
+const shown = (arg) => arg instanceof Error ? arg.stack ?? String(arg) : Inspectable.toStringUnknown(arg, 0);
+/** A console call's arguments as one line of text, joined by spaces. */
+const textOf = (args) => args.map(shown).join(" ");
+/** `console.table`'s rows, as a plain pipe table: an `(index)` column, then each key, then `Values` for scalars. */
+const tableOf = (data, properties) => {
+	if (data === null || typeof data !== "object") return textOf([data]);
+	const rows = Object.entries(data);
+	const isRecord = (value) => value !== null && typeof value === "object";
+	const keys = properties ?? [...new Set(rows.flatMap(([, value]) => isRecord(value) ? Object.keys(value) : []))];
+	const scalars = rows.some(([, value]) => !isRecord(value));
+	const header = [
+		"(index)",
+		...keys,
+		...scalars ? ["Values"] : []
+	];
+	const cell = (value) => value === void 0 ? "" : typeof value === "string" ? value : shown(value);
+	const body = rows.map(([index, value]) => [
+		index,
+		...keys.map((key) => isRecord(value) ? cell(value[key]) : ""),
+		...scalars ? [isRecord(value) ? "" : cell(value)] : []
+	]);
+	const widths = header.map((title, column) => Math.max(title.length, ...body.map((row) => (row[column] ?? "").length)));
+	const line = (cells) => `| ${cells.map((text, column) => text.padEnd(widths[column] ?? 0)).join(" | ")} |`;
+	return [line(header), ...body.map(line)].join("\n");
+};
+/** Milliseconds now, for `time`; the platform clock when there is one. */
+const now = () => globalThis.performance?.now() ?? Date.now();
+/**
+* Build an `InkConsole` over `UiStreams`.
+*
+* @remarks
+* Ink's writers (`useStdout().write`, `useStderr().write`) clear the frame, write the line and repaint the frame, so a
+* line written through them lands above the frame without tearing it; a raw write to the stream lands inside the frame
+* instead. They are reachable only from inside the tree, which is what the `Bridge` is for. Ink drops whatever they
+* are handed once it has unmounted, so the owner detaches before it unmounts, and a line written after goes straight
+* to the stream.
+*
+* Every `Console` method is the bridge's own, none the ambient console's: one that fell through would write to the
+* process's terminal past Ink, tearing the frame and escaping `UiStreams`.
+*
+* @internal
+*/
+const makeInkConsole = Effect.gen(function* () {
+	const streams = yield* UiStreams;
+	let attached;
+	let indent = "";
+	const counts = /* @__PURE__ */ new Map();
+	const timers = /* @__PURE__ */ new Map();
+	const emit = (stream, text) => {
+		const data = `${text.split("\n").map((line) => indent + line).join("\n")}\n`;
+		if (attached !== void 0) (stream === "out" ? attached.out : attached.err)(data);
+		else if (stream === "out") streams.stdout.write(data);
+		else streams.stderr.write(data);
+	};
+	const toOut = (...args) => emit("out", textOf(args));
+	const toErr = (...args) => emit("err", textOf(args));
+	const elapsed = (label, method, extra) => {
+		const started = timers.get(label);
+		if (started === void 0) {
+			emit("err", `Warning: No such label '${label}' for console.${method}()`);
+			return;
+		}
+		const tail = extra.length === 0 ? "" : ` ${textOf(extra)}`;
+		emit("out", `${label}: ${(now() - started).toFixed(3)}ms${tail}`);
+	};
+	const group = (...label) => {
+		if (label.length > 0) toOut(...label);
+		indent += "  ";
+	};
+	const writer = {
+		log: toOut,
+		info: toOut,
+		debug: toOut,
+		dirxml: toOut,
+		error: toErr,
+		warn: toErr,
+		trace: (...args) => {
+			const stack = ((/* @__PURE__ */ new Error()).stack ?? "").split("\n").slice(2).join("\n");
+			emit("err", `Trace${args.length === 0 ? "" : `: ${textOf(args)}`}${stack === "" ? "" : `\n${stack}`}`);
+		},
+		dir: (item) => toOut(item),
+		table: (data, properties) => emit("out", tableOf(data, properties)),
+		assert: (condition, ...args) => {
+			if (!condition) emit("err", `Assertion failed${args.length === 0 ? "" : `: ${textOf(args)}`}`);
+		},
+		count: (label = "default") => {
+			const next = (counts.get(label) ?? 0) + 1;
+			counts.set(label, next);
+			emit("out", `${label}: ${next}`);
+		},
+		countReset: (label = "default") => {
+			counts.delete(label);
+		},
+		group,
+		groupCollapsed: group,
+		groupEnd: () => {
+			indent = indent.slice(2);
+		},
+		time: (label = "default") => {
+			timers.set(label, now());
+		},
+		timeLog: (label = "default", ...extra) => elapsed(label, "timeLog", extra),
+		timeEnd: (label = "default") => {
+			elapsed(label, "timeEnd", []);
+			timers.delete(label);
+		},
+		clear: () => void 0
+	};
+	const Bridge = (props) => {
+		const { ink, react } = inkModules();
+		const out = ink.useStdout().write;
+		const err = ink.useStderr().write;
+		react.useLayoutEffect(() => {
+			const writers = {
+				out,
+				err
+			};
+			attached = writers;
+			return () => {
+				if (attached === writers) attached = void 0;
+			};
+		}, [out, err]);
+		return props.children ?? null;
+	};
+	return {
+		writer,
+		print: (text) => {
+			const data = `${text}\n`;
+			if (attached !== void 0) attached.out(data);
+			else streams.stdout.write(data);
+		},
+		printAbove: (stream, text) => {
+			if (attached === void 0) return false;
+			(stream === "stdout" ? attached.out : attached.err)(`${text}\n`);
+			return true;
+		},
+		Bridge,
+		detach: () => {
+			attached = void 0;
+		}
+	};
+});
+
+export { makeInkConsole };

package/ui/internal/lazyView.js

@@ -0,0 +1,73 @@
+import { Effect } from "effect";
+
+// src/ui/internal/lazyView.ts
+/** Where a lazy view keeps its loader: a `Symbol.for` key, so two copies of the package agree on it. */
+const LOAD = Symbol.for("@effected/cli-kit/ui/lazyView");
+const NOT_LOADED = "@effected/cli-kit/ui: a CliUi.lazyView render was called before its module loaded; only CliUi.live loads it first";
+const kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object" : typeof value;
+const EXPECTED = "a view, (state, frame) => ReactElement, or a module whose default export is one: { default: view }";
+/** What a `load` resolved to that is no view: said with what was received and what is expected. */
+const NO_VIEW = (resolved) => {
+	if (typeof resolved !== "object" || resolved === null) return `@effected/cli-kit/ui: CliUi.lazyView's load resolved to ${kindOf(resolved)}. Expected ${EXPECTED}`;
+	const named = Object.keys(resolved).filter((key) => key !== "default");
+	const exports = named.length === 0 ? "" : ` (it exports ${named.join(", ")})`;
+	return `@effected/cli-kit/ui: CliUi.lazyView's load resolved to ${Object.hasOwn(resolved, "default") ? `a module whose default export is ${kindOf(resolved.default)}, not a function${exports}; a CommonJS module imported as ESM nests it one level deeper, as default.default` : `a module with no default export${exports}; resolve to the export itself, as .then((module) => module.name)`}. Expected ${EXPECTED}`;
+};
+/**
+* A load that resolved to no view: deterministic, so a lazy view keeps it (one error object for the handle's life) and
+* the live view warns about it once, where a failed import is tried again by the next run.
+*
+* @internal
+*/
+var LazyViewShapeError = class extends Error {};
+/** The view `load` resolved to: the value itself when it is a function (a `default` property on it is ignored), else
+* its `default` when that is a function; anything else throws, saying what it got. */
+const pick = (resolved) => {
+	if (typeof resolved === "function") return resolved;
+	if (typeof resolved === "object" && resolved !== null) {
+		const fallback = resolved.default;
+		if (typeof fallback === "function") return fallback;
+	}
+	throw new LazyViewShapeError(NO_VIEW(resolved));
+};
+/**
+* `CliUi.lazyView`: a `render` that draws with what `load` resolves to, loaded on first use: the render itself, or a
+* module whose default export it is. One load is shared: an import that rejected is cleared, so the next run loads
+* again; a load that resolved to no view is kept, a `LazyViewShapeError` every later run gets as is. Calling the render
+* before it has loaded is a defect, since only `CliUi.live` knows to load it first.
+*
+* @internal
+*/
+const lazyView = (load) => {
+	let loaded;
+	let pending;
+	const ensure = () => {
+		pending ??= load().then((resolved) => {
+			loaded = pick(resolved);
+		}, (error) => {
+			pending = void 0;
+			throw error;
+		});
+		return pending;
+	};
+	const render = (state, frame) => {
+		if (loaded === void 0) throw new Error(NOT_LOADED);
+		return loaded(state, frame);
+	};
+	return Object.assign(render, { [LOAD]: ensure });
+};
+/**
+* Load a lazy view's module before its render is first called; nothing for a render that is not lazy. Fails with what
+* the import failed with.
+*
+* @internal
+*/
+const loadView = (render) => {
+	const ensure = render[LOAD];
+	return ensure === void 0 ? Effect.void : Effect.asVoid(Effect.tryPromise({
+		try: ensure,
+		catch: (error) => error
+	}));
+};
+
+export { LazyViewShapeError, lazyView, loadView };

package/ui/internal/lineRouter.js

@@ -0,0 +1,70 @@
+import { isEscapeOnly } from "../../internal/displayWidth.js";
+
+// src/ui/internal/lineRouter.ts
+/** The text a printer is handed for one line: a CRLF's `\r` dropped, and under `last` only what the line ends on. */
+const printable = (line, carriageReturn) => {
+	const text = line.endsWith("\r") ? line.slice(0, -1) : line;
+	if (carriageReturn === "keep") return text;
+	const cut = text.lastIndexOf("\r");
+	return cut === -1 ? text : text.slice(cut + 1);
+};
+/** @internal */
+const makeLineRouter = (options) => {
+	const decoder = new TextDecoder("utf-8");
+	let held = "";
+	let routing = true;
+	const offer = (line) => {
+		if (!options.printer(options.stream, printable(line, options.carriageReturn))) options.write(`${line}\n`);
+	};
+	const route = (text) => {
+		if (text === "") return;
+		if (!routing) {
+			options.write(text);
+			return;
+		}
+		if (held === "" && isEscapeOnly(text)) {
+			options.write(text);
+			return;
+		}
+		if (!text.includes("\n")) {
+			held += text;
+			if (held.length > options.maxHeld) {
+				const line = held;
+				held = "";
+				offer(line);
+			}
+			return;
+		}
+		const lines = (held + text).split("\n");
+		const rest = lines.pop() ?? "";
+		if (rest.length > options.maxHeld) {
+			lines.push(rest);
+			held = "";
+		} else held = rest;
+		for (const line of lines) offer(line);
+	};
+	return {
+		take: (chunk) => {
+			const text = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+			if (text !== "") options.onText?.(text);
+			route(text);
+		},
+		route: (on) => {
+			if (!on && held !== "") {
+				options.write(held);
+				held = "";
+			}
+			routing = on;
+		},
+		flush: () => {
+			const pending = decoder.decode();
+			if (pending !== "") options.onText?.(pending);
+			const text = held + pending;
+			held = "";
+			if (text === "") return;
+			if (!routing || !options.printer(options.stream, printable(text, options.carriageReturn))) options.write(text);
+		}
+	};
+};
+
+export { makeLineRouter };

package/ui/internal/lineText.js

@@ -0,0 +1,18 @@
+import { sanitize } from "../../Fmt.js";
+
+// src/ui/internal/lineText.ts
+/**
+* Consumer text made safe for one row of a widget: sanitised as `Fmt.sanitize` does (no escape sequence, no other
+* control character), with each line break (CR, LF or CR LF) folded to a space.
+*
+* @remarks
+* Every string a kit widget draws from data goes through it before it is measured or cut. Ink keeps SGR and OSC
+* sequences it is handed, so unsanitised text would paint colour at colour `none` and could plant a hyperlink whose
+* target differs from its label; and a widget's row budget counts one row per line, so a second line would push the
+* frame past the terminal, where Ink wipes the screen and its scrollback.
+*
+* @internal
+*/
+const lineText = (text) => sanitize(text).replace(/\r\n|\r|\n/g, " ");
+
+export { lineText };

package/ui/internal/mountPermit.js

@@ -0,0 +1,15 @@
+import { Semaphore } from "effect";
+
+// src/ui/internal/mountPermit.ts
+/**
+* One Ink mount at a time, process-wide: a `CliUi.run` screen, or one run of a live view.
+*
+* @remarks
+* Ink keys its instances by stdout and owns raw mode on the one terminal, so concurrent mounts are meaningless, and
+* serializing them keeps each mount's save-and-restore of Ink's colour level well nested.
+*
+* @internal
+*/
+const mountPermit = Semaphore.makeUnsafe(1);
+
+export { mountPermit };

package/ui/internal/processStreams.js

@@ -0,0 +1,18 @@
+// src/ui/internal/processStreams.ts
+/**
+* The process's own standard streams, the default `UiStreams`.
+*
+* @remarks
+* One of the three files licensed to touch Node: it reads
+* `process.stdin`, `process.stdout` and `process.stderr` and nothing else, and only when called, never at import.
+* The boundary test holds that licence exact.
+*
+* @internal
+*/
+const processStreams = () => ({
+	stdin: process.stdin,
+	stdout: process.stdout,
+	stderr: process.stderr
+});
+
+export { processStreams };

package/ui/internal/renderOptions.js

@@ -0,0 +1,12 @@
+import { Context } from "effect";
+
+// src/ui/internal/renderOptions.ts
+/**
+* The render-option overrides in force: none by default. Internal, so `CliUi.run`'s public signature stays as
+* specified; `CliUiTest` sets it.
+*
+* @internal
+*/
+var UiRenderOptions = class extends Context.Reference("@effected/cli-kit/ui/UiRenderOptions", { defaultValue: () => ({}) }) {};
+
+export { UiRenderOptions };