@effected/cli-kit 0.0.0-stage → 0.27.0

package/ui/Viewport.js

@@ -0,0 +1,203 @@
+import { inkModules } from "./internal/ink.js";
+import { KeyTable } from "./KeyTable.js";
+import { useTerminalSize } from "./UiTheme.js";
+
+// src/ui/Viewport.ts
+/**
+* Throws on a repeated item key. Checked before React sees the rows: React reports a duplicate key on
+* `console.error`, which under a screen's unpatched console lands on the real stderr, over the frame.
+*/
+const assertUniqueItemKeys = (rows) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const row of rows) {
+		if (row._tag !== "Item") continue;
+		if (seen.has(row.key)) throw new Error(`@effected/cli-kit/ui: Viewport item keys must be unique; "${row.key}" repeats`);
+		seen.add(row.key);
+	}
+};
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/** The offset that keeps `cursor` in view, moving as little as possible, never past the last full window. */
+const follow = (cursor, offset, height, count) => {
+	if (count === 0) return 0;
+	let next = offset;
+	if (cursor < next) next = cursor;
+	if (cursor >= next + height) next = cursor - height + 1;
+	return clamp(next, 0, Math.max(0, count - height));
+};
+const init = (count, height, cursor = 0) => {
+	const items = Math.max(0, Math.floor(count));
+	const window = Math.max(1, Math.floor(height));
+	const selected = items === 0 ? 0 : clamp(Math.floor(cursor), 0, items - 1);
+	return {
+		cursor: selected,
+		offset: follow(selected, 0, window, items),
+		height: window,
+		count: items
+	};
+};
+const step = (state, move) => {
+	if (state.count === 0) return state;
+	const last = state.count - 1;
+	const target = move === "up" ? state.cursor - 1 : move === "down" ? state.cursor + 1 : move === "home" ? 0 : move === "end" ? last : move === "pageup" ? state.cursor - state.height : state.cursor + state.height;
+	const cursor = clamp(target, 0, last);
+	return {
+		...state,
+		cursor,
+		offset: follow(cursor, state.offset, state.height, state.count)
+	};
+};
+const resize = (state, height) => {
+	const window = Math.max(1, Math.floor(height));
+	return {
+		...state,
+		height: window,
+		offset: follow(state.cursor, state.offset, window, state.count)
+	};
+};
+/**
+* The rows to draw, as indexes into `rows`, for a window of `budget` lines starting at item `start`: the section
+* header of the first item first (re-emitted when it has scrolled off), then rows in order until the budget is spent.
+*/
+const linesFrom = (rows, items, start, budget) => {
+	const first = items[start] ?? 0;
+	const lines = [];
+	if (budget > 1) {
+		for (let index = first - 1; index >= 0; index--) if (rows[index]?._tag === "Header") {
+			lines.push(index);
+			break;
+		}
+	}
+	for (let index = first; index < rows.length && lines.length < budget; index++) lines.push(index);
+	return lines;
+};
+/**
+* The visible slice, starting where the window last started (`previous`, or the state's offset on first draw) and
+* moving only as far as the selected item needs: back to it when it is above the window, forward until it is drawn
+* when it is below. So moving inside the window moves only the highlight, even when headers take lines the
+* item-counting reducer does not. The cursor is clamped into the items here, for both the slice and the highlight.
+*/
+const slice = (rows, state, budget, previous) => {
+	const items = rows.flatMap((row, index) => row._tag === "Item" ? [index] : []);
+	if (items.length === 0) return {
+		lines: rows.slice(0, budget).map((_, index) => index),
+		start: 0,
+		selected: -1
+	};
+	const cursor = clamp(state.cursor, 0, items.length - 1);
+	const selected = items[cursor] ?? 0;
+	let start = clamp(previous ?? state.offset, 0, cursor);
+	let lines = linesFrom(rows, items, start, budget);
+	while (!lines.includes(selected) && start < cursor) {
+		start++;
+		lines = linesFrom(rows, items, start, budget);
+	}
+	while (lines.length < budget && start > 0) {
+		const earlier = linesFrom(rows, items, start - 1, budget);
+		if (!earlier.includes(selected)) break;
+		start--;
+		lines = earlier;
+	}
+	return {
+		lines,
+		start,
+		selected
+	};
+};
+/**
+* A scrolling list: a pure reducer over a window of items, its key table, and a view that draws the window.
+*
+* @remarks
+* The view never draws more lines than fit: its height is `min(state.height, terminal rows - 1 - reserved)`, and
+* every row is clipped to one line of `columns - 1` cells, so a frame never fills the terminal and Ink never clears
+* the screen and scrollback to redraw it. A section header stays visible: when the header of the first visible item
+* has scrolled off, it is drawn again atop the slice.
+*
+* @public
+*/
+var Viewport = class {
+	constructor() {}
+	/**
+	* A viewport over `count` items, `height` of them in view, with `cursor` selected (clamped; 0 by default).
+	*
+	* @param count - how many items
+	* @param height - how many fit (at least 1)
+	* @param cursor - the item to select
+	*/
+	static init = init;
+	/**
+	* Move the cursor, clamped at both ends with no wrap, keeping it in view. A page is the window height.
+	*
+	* @param state - where the viewport is
+	* @param move - the move
+	*/
+	static step = step;
+	/**
+	* Change the window height, keeping the cursor where it is and in view.
+	*
+	* @param state - where the viewport is
+	* @param height - the new height (at least 1)
+	*/
+	static resize = resize;
+	/** The keys: ↑/↓ move, pgup/pgdn page, home top, end bottom. */
+	static keys = KeyTable.make([
+		{
+			keys: ["up"],
+			action: "up",
+			help: "move"
+		},
+		{
+			keys: ["down"],
+			action: "down",
+			help: "move"
+		},
+		{
+			keys: ["pageup"],
+			action: "pageup",
+			help: "page"
+		},
+		{
+			keys: ["pagedown"],
+			action: "pagedown",
+			help: "page"
+		},
+		{
+			keys: ["home"],
+			action: "home",
+			help: "top"
+		},
+		{
+			keys: ["end"],
+			action: "end",
+			help: "bottom"
+		}
+	]);
+	/**
+	* Draw the window: the visible rows, each clipped to one line. A repeated item key is a defect: the view throws, so
+	* the screen dies with the reason.
+	*
+	* @param props - the rows, the state, how to draw a row, and the lines reserved for the rest of the screen
+	*/
+	static View = (props) => {
+		assertUniqueItemKeys(props.rows);
+		const { ink, react } = inkModules();
+		const size = useTerminalSize();
+		const budget = Math.max(1, Math.min(props.state.height, size.rows - (props.reserved ?? 0)));
+		const started = react.useRef(void 0);
+		const { lines, start, selected } = slice(props.rows, props.state, budget, started.current);
+		started.current = start;
+		return react.createElement(ink.Box, {
+			flexDirection: "column",
+			width: size.columns
+		}, ...lines.map((index) => {
+			const row = props.rows[index];
+			return react.createElement(ink.Box, {
+				key: row._tag === "Item" ? `item:${row.key}` : `header:${index}`,
+				height: 1,
+				width: size.columns,
+				overflow: "hidden"
+			}, props.renderRow(row, index === selected));
+		}));
+	};
+};
+
+export { Viewport };

package/ui/internal/ErrorBoundary.js

@@ -0,0 +1,29 @@
+import { fromReact } from "./ink.js";
+
+// src/ui/internal/ErrorBoundary.ts
+/**
+* The screen's error boundary: catches a render error anywhere in the screen, renders nothing, and reports it.
+*
+* @remarks
+* It sits inside Ink's own boundary, so Ink's `ErrorOverview` (which Ink writes to stdout) never renders: a probe on
+* fake streams found zero bytes of it with this boundary in place, against an `ERROR` header, a stack and a
+* screen-and-scrollback clear without it. A class over the loaded React, built on first use, because the kit holds
+* no runtime React at module scope.
+*
+* @internal
+*/
+const errorBoundary = fromReact((react) => class ScreenErrorBoundary extends react.Component {
+	static displayName = "CliUiErrorBoundary";
+	static getDerivedStateFromError() {
+		return { failed: true };
+	}
+	state = { failed: false };
+	componentDidCatch(error) {
+		this.props.onError(error);
+	}
+	render() {
+		return this.state.failed ? this.props.fallback?.() ?? null : this.props.children ?? null;
+	}
+});
+
+export { errorBoundary };

package/ui/internal/Holder.js

@@ -0,0 +1,73 @@
+import { fromReact } from "./ink.js";
+
+// src/ui/internal/Holder.ts
+/**
+* A component that shows one element and lets its owner swap it in place.
+*
+* @remarks
+* Everything above the holder stays mounted across a swap: the screen's error boundary, its context, the root keys
+* and the colour hold. Only the held subtree changes, so the screen's `ScreenControl` keeps meaning the same screen.
+* The swap function is handed over in a layout effect, before the first frame is written, and taken back in that
+* effect's cleanup. A swap is a state update, which React commits in a microtask rather than at once, so a swap can
+* ask to be told when its element is committed: the live view waits for that before it draws on or unmounts. Built on
+* the loaded React, like every kit component; the screen harness's `rerender` and the live view's pushes use it.
+*
+* @internal
+*/
+const holder = fromReact((react) => {
+	const Holder = (props) => {
+		const [shown, setShown] = react.useState(() => ({
+			element: props.initial,
+			committed: void 0
+		}));
+		react.useLayoutEffect(() => {
+			props.bind((element, committed) => setShown({
+				element,
+				committed
+			}));
+			return () => props.bind(void 0);
+		}, [props.bind]);
+		react.useLayoutEffect(() => shown.committed?.(), [shown]);
+		return shown.element;
+	};
+	Holder.displayName = "CliUiHolder";
+	return Holder;
+});
+/**
+* A fresh {@link HolderSlot}.
+*
+* @internal
+*/
+const holderSlot = () => {
+	let bound;
+	const pending = [];
+	const release = (through) => {
+		for (const committed of pending.splice(0, through + 1)) committed();
+	};
+	return {
+		bind: (swap) => {
+			bound = swap;
+			if (swap === void 0) release(pending.length - 1);
+		},
+		isBound: () => bound !== void 0,
+		swap: (next, committed) => {
+			if (bound === void 0) {
+				committed?.();
+				return false;
+			}
+			if (committed === void 0) {
+				bound(next);
+				return true;
+			}
+			const own = () => committed();
+			pending.push(own);
+			bound(next, () => {
+				const at = pending.indexOf(own);
+				if (at !== -1) release(at);
+			});
+			return true;
+		}
+	};
+};
+
+export { holder, holderSlot };

package/ui/internal/ScreenContext.js

@@ -0,0 +1,51 @@
+import { fromReact, inkModules } from "./ink.js";
+
+// src/ui/internal/ScreenContext.ts
+/**
+* The React context carrying {@link ScreenContextValue}, built on the loaded React.
+*
+* @internal
+*/
+const screenContext = fromReact((react) => react.createContext(void 0));
+const ignore = () => void 0;
+/**
+* The mounted screen's cancel, for a widget whose own key (such as Select's `q`) ends the screen.
+*
+* @remarks
+* A React hook; throws outside a screen mounted by `CliUi.run` or a `UiProvider`. Under a tree that is not a screen
+* (a `UiProvider`, a live view) there is nothing to cancel, and it does nothing.
+*
+* @internal
+*/
+const useScreenCancel = () => {
+	const screen = inkModules().react.useContext(screenContext());
+	if (screen === void 0) throw new Error("@effected/cli-kit/ui: a widget was used outside a screen mounted by CliUi.run or a UiProvider");
+	return screen.cancel ?? ignore;
+};
+/**
+* Wrap an input handler so a throw ends the screen as a defect instead of escaping.
+*
+* @remarks
+* Ink calls `useInput` and `usePaste` handlers from its stdin listener, outside React's render, so an error boundary
+* never sees what they throw: unguarded, it is an uncaught exception (the process dies, Effect finalizers skipped)
+* or, where something keeps the process alive, a screen left waiting. Guarded, the screen dies with the error and
+* `CliUi.run` unmounts it like any other defect. Outside a screen mounted by `CliUi.run`, a `UiProvider` tree
+* included, a handler is called as is.
+*
+* A React hook.
+*
+* @internal
+*/
+const useScreenGuard = () => {
+	const die = inkModules().react.useContext(screenContext())?.die;
+	return (handler) => (...args) => {
+		if (die === void 0) return handler(...args);
+		try {
+			handler(...args);
+		} catch (error) {
+			die(error);
+		}
+	};
+};
+
+export { screenContext, useScreenCancel, useScreenGuard };

package/ui/internal/UiProviders.js

@@ -0,0 +1,38 @@
+import { underGithubActions } from "../../internal/autoFormat.js";
+import { CurrentDisplayPath } from "../../internal/displayPath.js";
+import { inkModules } from "./ink.js";
+import { screenContext } from "./ScreenContext.js";
+import { Effect } from "effect";
+
+// src/ui/internal/UiProviders.ts
+/**
+* Wrap `children` in the kit's providers: the theme, the glyph set, the optional size override, and a screen's cancel
+* and defect route when it has them.
+*
+* @remarks
+* The one place a kit tree's context is built, for `CliUi.run`'s screens, a live view and the public `UiProvider`,
+* so every kit hook reads the same value under each.
+*
+* @internal
+*/
+const uiProviders = (value, children) => inkModules().react.createElement(screenContext().Provider, {
+	value,
+	children
+});
+/**
+* The base of a kit tree drawn with `theme`: its glyphs, `neutralizeWorkflowCommands` under the GitHub Actions
+* runner, and the run's path display. Read once per mount, so a screen, a live view and `CliUi.context` agree.
+*
+* @internal
+*/
+const treeBase = (theme) => Effect.gen(function* () {
+	const neutralize = yield* underGithubActions;
+	return {
+		theme,
+		glyphs: theme.glyphs,
+		...neutralize ? { neutralizeWorkflowCommands: true } : {},
+		displayPath: yield* CurrentDisplayPath
+	};
+});
+
+export { treeBase, uiProviders };

package/ui/internal/ink.js

@@ -0,0 +1,121 @@
+import { inkChalk } from "./inkChalk.js";
+import { Effect, Option } from "effect";
+
+// src/ui/internal/ink.ts
+const MISSING_PEERS = "@effected/cli-kit/ui could not load its optional peers ink and react: install both beside @effected/cli-kit to mount a screen";
+const READ_BEFORE_LOAD = "@effected/cli-kit/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-kit/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));
+
+export { fromReact, holdChalkLevel, inkModules, levelOf, loadInk, withInkColour };

package/ui/internal/inkChalk.js

@@ -0,0 +1,47 @@
+import { Option } from "effect";
+
+// 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` for THIS module, when it has one. It resolves relative to the module that owns
+* it, so it has to be the kit's own: `ModuleResolution` cannot supply it.
+*
+* @internal
+*/
+const esmResolve = typeof import.meta.resolve === "function" ? (specifier) => import.meta.resolve(specifier) : void 0;
+/**
+* The chalk instance Ink itself imports, resolved from Ink's own location; `None` when it cannot be resolved.
+*
+* @remarks
+* 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. So Ink's
+* entry is resolved from here (`esm` first, Node's CommonJS resolution where it is missing or throws, as under Vite's
+* module runner, which evaluates a Vitest reporter loaded by path), `chalk` is resolved from that entry to its
+* realpath, and that file is imported: Node keys ES modules by realpath, so it is the very module Ink imports. The
+* resolution is `@effected/commands/node-sync`'s `ModuleResolution`, loaded only when this runs, so importing `./ui`
+* loads none of it. A consumer that bundles Ink leaves nothing to resolve, and the answer is `None`; it never rejects.
+*
+* @param esm - an ESM resolver relative to this module; the runtime's `import.meta.resolve` by default, and a stand-in
+*   in a test
+*
+* @internal
+*/
+const inkChalk = async (esm = esmResolve) => {
+	try {
+		const { ModuleResolution } = await import("@effected/commands/node-sync");
+		const chalkPath = Option.flatMap(ModuleResolution.resolve("ink", {
+			from: import.meta.url,
+			esm
+		}), (entry) => ModuleResolution.resolve("chalk", {
+			from: entry,
+			realPath: true
+		}));
+		if (Option.isNone(chalkPath)) return Option.none();
+		const chalk = await ModuleResolution.load(chalkPath.value);
+		return isInkChalk(chalk.default) ? Option.some(chalk.default) : Option.none();
+	} catch {
+		return Option.none();
+	}
+};
+
+export { esmResolve, inkChalk };