@effected/cli 0.9.0 → 0.11.0

package/ui/internal/ink.js

@@ -0,0 +1,122 @@
+import { inkChalk } from "./inkChalk.js";
+import { Effect, Option } from "effect";
+
+//#region src/ui/internal/ink.ts
+const MISSING_PEERS = "@effected/cli/ui could not load its optional peers ink and react: install both beside @effected/cli to mount a screen";
+const READ_BEFORE_LOAD = "@effected/cli/ui read Ink before loading it: run CliUi.context (or mount a screen with CliUi.run) before rendering UiProvider or a kit component in a tree of your own";
+const UNRESOLVED_CHALK = "@effected/cli/ui could not resolve the chalk Ink uses (is ink bundled?), so Ink decides its own colour level";
+let modules;
+let loading;
+const importPeers = async () => {
+	const [ink, react] = await Promise.all([import("ink"), import("react")]);
+	return {
+		ink,
+		react: react.default
+	};
+};
+/**
+* Load `ink` and `react`, once. The only runtime access the kit has to either package: nothing imports a value
+* from them, so importing `./ui` loads neither, and only mounting a screen does.
+*
+* @remarks
+* Concurrent loads share one import, and a failed one is retried by the next call. A missing peer is a defect, not
+* a typed failure, because it is an installation error no handler can recover from; its message names both peers.
+*
+* @internal
+*/
+const loadInk = Effect.suspend(() => {
+	if (modules !== void 0) return Effect.succeed(modules);
+	return Effect.tryPromise({
+		try: () => {
+			loading ??= importPeers();
+			return loading;
+		},
+		catch: (cause) => new Error(MISSING_PEERS, { cause })
+	}).pipe(Effect.tap((loaded) => Effect.sync(() => {
+		modules = loaded;
+	})), Effect.tapError(() => Effect.sync(() => {
+		loading = void 0;
+	})), Effect.orDie);
+});
+/**
+* The modules {@link loadInk} loaded, read at render time by kit components.
+*
+* @remarks
+* Throws when nothing has loaded them: a kit component rendered outside a screen. Inside a render that throw is
+* caught by the screen's error boundary and becomes a defect.
+*
+* @internal
+*/
+const inkModules = () => {
+	if (modules === void 0) throw new Error(READ_BEFORE_LOAD);
+	return modules;
+};
+/**
+* A value built once from the loaded React, such as a class component or a context, which cannot be declared at
+* module scope because the kit holds no runtime React until {@link loadInk} runs.
+*
+* @remarks
+* The returned accessor builds on first call and returns the same value thereafter; like {@link inkModules}, it
+* throws if called before the load.
+*
+* @internal
+*/
+const fromReact = (build) => {
+	let built;
+	return () => {
+		const { react } = inkModules();
+		if (built === void 0 || built.react !== react) built = {
+			react,
+			value: build(react)
+		};
+		return built.value;
+	};
+};
+const LEVELS = {
+	none: 0,
+	basic: 1,
+	"256": 2,
+	truecolor: 3
+};
+/**
+* A stream's colour level as a chalk level: `none` 0, `basic` 1, `256` 2, `truecolor` 3.
+*
+* @internal
+*/
+const levelOf = (colour) => LEVELS[colour];
+let chalk;
+const resolveChalk = Effect.promise(() => {
+	chalk ??= inkChalk();
+	return chalk;
+});
+let warned = false;
+/**
+* Hold `chalk` at `colour`'s level for the enclosing scope, restoring the saved level when the scope closes, by
+* release or by interruption. With no chalk to hold, warn once and leave Ink's own detection in place.
+*
+* @internal
+*/
+const holdChalkLevel = (found, colour) => Option.match(found, {
+	onNone: () => Effect.suspend(() => {
+		if (warned) return Effect.void;
+		warned = true;
+		return Effect.logWarning(UNRESOLVED_CHALK);
+	}),
+	onSome: (instance) => Effect.asVoid(Effect.acquireRelease(Effect.sync(() => {
+		const saved = instance.level;
+		instance.level = levelOf(colour);
+		return saved;
+	}), (saved) => Effect.sync(() => {
+		instance.level = saved;
+	})))
+});
+/**
+* Set Ink's colour level from the stream's `ColorLevel` for the enclosing scope, on Ink's own chalk. The level is process-global while held: the last screen
+* mounted wins.
+*
+* @internal
+*/
+const withInkColour = (colour) => Effect.flatMap(resolveChalk, (found) => holdChalkLevel(found, colour));
+
+//#endregion
+export { fromReact, holdChalkLevel, inkModules, levelOf, loadInk, withInkColour };

package/ui/internal/inkChalk.js

@@ -0,0 +1,58 @@
+import { createRequire } from "node:module";
+import { Option } from "effect";
+import { realpathSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+//#region src/ui/internal/inkChalk.ts
+const isInkChalk = (value) => (typeof value === "function" || typeof value === "object" && value !== null) && typeof value.level === "number";
+/** The runtime's `import.meta.resolve`, when it has one. */
+const esmResolve = typeof import.meta.resolve === "function" ? (specifier) => import.meta.resolve(specifier) : void 0;
+/**
+* The path of Ink's entry: through `resolve` (the runtime's `import.meta.resolve` by default), or, where that is
+* missing or throws, through Node's CommonJS resolution from this module.
+*
+* @remarks
+* Vite's module runner, which evaluates a Vitest reporter loaded by path, has an `import.meta.resolve` that throws
+* ("not supported"); the CommonJS resolution finds the same file, since Ink's `exports` has a `default` condition.
+*
+* @param resolve - an ESM resolver, to stand in for the runtime's in a test
+*
+* @internal
+*/
+const resolveInkEntry = (resolve = esmResolve) => {
+	if (resolve !== void 0) try {
+		return fileURLToPath(resolve("ink"));
+	} catch {}
+	return createRequire(import.meta.url).resolve("ink");
+};
+/**
+* The chalk instance Ink itself imports, resolved from Ink's own location; `None` when it cannot be resolved.
+*
+* @remarks
+* One of the three files licensed to touch Node. Ink's `exports` has
+* only `"."` and chalk is its own dependency, so the kit cannot import Ink's chalk by name: a `chalk` of the kit's
+* own could be a different copy, and setting its level would silently change nothing. Resolving `chalk` from Ink's
+* entry ({@link resolveInkEntry}) and importing its realpath yields the very module Ink imports, because Node keys ES
+* modules by realpath. A consumer that bundles Ink leaves nothing
+* to resolve, and the answer is `None`; it never rejects.
+*
+* @param inkEntryOf - how Ink's entry is found; {@link resolveInkEntry} by default
+*
+* @internal
+*/
+const inkChalk = async (inkEntryOf = () => resolveInkEntry()) => {
+	try {
+		const inkEntry = inkEntryOf();
+		const chalkPath = realpathSync(createRequire(inkEntry).resolve("chalk"));
+		const chalk = await import(
+			/* @vite-ignore */
+			pathToFileURL(chalkPath).href
+);
+		return isInkChalk(chalk.default) ? Option.some(chalk.default) : Option.none();
+	} catch {
+		return Option.none();
+	}
+};
+
+//#endregion
+export { inkChalk, resolveInkEntry };

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/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 };