@effected/cli 0.10.0 → 0.12.0

package/ui/internal/inkConsole.js

@@ -0,0 +1,146 @@
+import { inkModules } from "./ink.js";
+import { UiStreams } from "../UiStreams.js";
+import { Effect, Inspectable } from "effect";
+
+//#region 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);
+		},
+		Bridge,
+		detach: () => {
+			attached = void 0;
+		}
+	};
+});
+
+//#endregion
+export { makeInkConsole };

package/ui/internal/lazyView.js

@@ -0,0 +1,74 @@
+import { Effect } from "effect";
+
+//#region 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/ui/lazyView");
+const NOT_LOADED = "@effected/cli/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/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/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
+	}));
+};
+
+//#endregion
+export { LazyViewShapeError, lazyView, loadView };

package/ui/internal/lineText.js

@@ -0,0 +1,19 @@
+import { sanitize } from "../../Fmt.js";
+
+//#region 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, " ");
+
+//#endregion
+export { lineText };

package/ui/internal/mountPermit.js

@@ -0,0 +1,16 @@
+import { Semaphore } from "effect";
+
+//#region 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);
+
+//#endregion
+export { mountPermit };

package/ui/internal/perfDrain.js

@@ -0,0 +1,33 @@
+import { Config, Effect } from "effect";
+
+//#region src/ui/internal/perfDrain.ts
+/**
+* Whether a drain mode drains: `true` and `false` as given, and `"auto"` unless `NODE_ENV` is exactly `"production"`.
+*
+* @remarks
+* React picks its development build whenever `NODE_ENV` is not exactly `"production"`, and that build records
+* user-timing entries on every render and never clears them. An
+* unset `NODE_ENV`, the common case for a CLI, leaks like `"development"`, so `"auto"` drains then too. `NODE_ENV` is
+* read through `Config`, so a test sets it with a `ConfigProvider` and `./ui` reads no `process`.
+*
+* @internal
+*/
+const resolveDrain = (mode) => mode === "auto" ? Config.String("NODE_ENV").pipe(Config.withDefault(""), Effect.map((env) => env !== "production"), Effect.orElseSucceed(() => true)) : Effect.succeed(mode);
+/**
+* Clear every user-timing `measure` entry in the process, when `drain` is true.
+*
+* @remarks
+* The clear is global: it removes a consumer's own measures too, because the platform's `clearMeasures` filters only
+* by name, and React's entries (`Update`, `Mount`, tagged `detail.devtools`) share their names with anything a
+* consumer might call a measure. Marks are left alone: React's development build leaks measures only, never marks,
+* so clearing marks would only take a host's own. A runtime without `performance` is left alone.
+*
+* @internal
+*/
+const drainPerformance = (drain) => {
+	if (!drain) return;
+	globalThis.performance?.clearMeasures?.();
+};
+
+//#endregion
+export { drainPerformance, resolveDrain };

package/ui/internal/processStreams.js

@@ -0,0 +1,19 @@
+//#region 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
+});
+
+//#endregion
+export { processStreams };

package/ui/internal/renderOptions.js

@@ -0,0 +1,13 @@
+import { Context } from "effect";
+
+//#region 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/ui/UiRenderOptions", { defaultValue: () => ({}) }) {};
+
+//#endregion
+export { UiRenderOptions };