@effected/cli-kit 0.0.0-stage → 0.26.0

package/ui/CliUiLive.js

@@ -0,0 +1,436 @@
+import { CliInteractive } from "../CliInteractive.js";
+import { CliLinks } from "../CliLinks.js";
+import { CliTheme } from "../CliTheme.js";
+import { autoFormat } from "../internal/autoFormat.js";
+import { Render } from "../Render.js";
+import { errorBoundary } from "./internal/ErrorBoundary.js";
+import { holder, holderSlot } from "./internal/Holder.js";
+import { fromReact, inkModules, loadInk, withInkColour } from "./internal/ink.js";
+import { makeInkConsole } from "./internal/inkConsole.js";
+import { LazyViewShapeError, loadView } from "./internal/lazyView.js";
+import { mountPermit } from "./internal/mountPermit.js";
+import { UiRenderOptions } from "./internal/renderOptions.js";
+import { treeBase, uiProviders } from "./internal/UiProviders.js";
+import { UiStreams } from "./UiStreams.js";
+import { useTerminalSize } from "./UiTheme.js";
+import { Cause, Clock, Duration, Effect, Exit, Fiber, Option, PubSub, Pull, Queue, Schedule, Scheduler, Scope, Stream } from "effect";
+import { Audience, TerminalEnv } from "@effected/env";
+import { CommandNeutralizer } from "@effected/github-commands";
+
+// src/ui/CliUiLive.ts
+/**
+* The live tree's height clamp: at most the terminal's rows less one, re-read on every render and when the terminal
+* resizes, so a tall frame never takes Ink's clear-terminal path, which wipes the scrollback. No width: Ink sizes the root itself.
+*/
+const heightClamp = fromReact(() => {
+	const HeightClamp = (props) => {
+		const { ink, react } = inkModules();
+		const { rows } = useTerminalSize();
+		return react.createElement(ink.Box, {
+			flexDirection: "column",
+			maxHeight: rows,
+			overflow: "hidden"
+		}, react.createElement(ink.Box, {
+			flexDirection: "column",
+			flexShrink: 0
+		}, props.children));
+	};
+	HeightClamp.displayName = "CliUiLiveHeightClamp";
+	return HeightClamp;
+});
+const TICK_INVALID = (tickMillis) => `@effected/cli-kit/ui: CliUi.live's tickMillis must be a positive, finite number of milliseconds, not ${tickMillis}`;
+const DEGRADED = (error) => `@effected/cli-kit/ui: the live view stopped drawing this run: ${error instanceof Error ? error.message : String(error)}`;
+/**
+* `CliUi.live`, kept in its own module: see `CliUi.live` for the contract.
+*
+* @internal
+*/
+const live = (options) => Effect.gen(function* () {
+	const tickMillis = options.tickMillis ?? 80;
+	const begins = options.begins ?? ((event) => options.isStart(event));
+	if (!(Number.isFinite(tickMillis) && tickMillis > 0)) return yield* Effect.die(new Error(TICK_INVALID(tickMillis)));
+	const audience = yield* Effect.serviceOption(Audience);
+	const cliTheme = yield* CliTheme;
+	const theme = CliTheme.forAudience(cliTheme.forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
+	const colour = theme.color;
+	const provided = yield* treeBase(theme);
+	const neutralize = provided.neutralizeWorkflowCommands === true;
+	const interactive = yield* CliInteractive;
+	const streams = yield* UiStreams;
+	const overrides = yield* UiRenderOptions;
+	const bridge = yield* makeInkConsole;
+	const inbox = yield* Queue.unbounded();
+	const source = options.events;
+	const stream = Stream.isStream(source) ? source : void 0;
+	const subscription = stream === void 0 ? source : void 0;
+	let state = options.initial;
+	let run;
+	let finalTaken = false;
+	const Frame = (props) => options.render(props.state, props.frame);
+	const frameOf = Effect.map(Clock.currentTimeMillis, (now) => Math.floor(now / tickMillis));
+	const elementOf = (shown, frame) => inkModules().react.createElement(Frame, {
+		state: shown,
+		frame
+	});
+	/**
+	* Unmount what a run has mounted: Ink's own unmount commits the last frame. Nothing is written after it. The clear
+	* and the close are one uninterruptible step: an interrupt landing between them would leave a scope nobody closes,
+	* its permit held, its instance mounted and its tick running.
+	*/
+	const unmount = (current) => Effect.uninterruptible(Effect.suspend(() => {
+		const mounted = current.mounted;
+		current.mounted = void 0;
+		return mounted === void 0 ? Effect.void : Scope.close(mounted.scope, Exit.void);
+	}));
+	/** Take the run off and unmount it, in one step an interrupt cannot split; the run taken, if any. */
+	const takeRun = Effect.uninterruptible(Effect.suspend(() => {
+		const current = run;
+		run = void 0;
+		return current === void 0 ? Effect.succeed(void 0) : Effect.as(unmount(current), current);
+	}));
+	/**
+	* A lazy view's shape errors already warned about. A shape error is deterministic, and the lazy view keeps one
+	* error object for it, so a long watch session warns once for it, not once per run; any other failure is a fresh
+	* object, and warns each time.
+	*/
+	const shapesWarned = /* @__PURE__ */ new Set();
+	/** The degraded-run warning, unless it is a shape error this view has already warned about. */
+	const warning = (error) => {
+		if (error instanceof LazyViewShapeError) {
+			if (shapesWarned.has(error)) return Effect.void;
+			shapesWarned.add(error);
+		}
+		return Effect.logWarning(DEGRADED(error));
+	};
+	/** Stop drawing a run: unmount first, so the one warning never lands inside a frame, then warn. */
+	const degrade = (current, error) => Effect.suspend(() => {
+		if (current.degraded) return unmount(current);
+		current.degraded = true;
+		return Effect.andThen(unmount(current), warning(error));
+	});
+	/** Act on a failure the boundary reported for the run mounted now, if any. */
+	const checkFailure = Effect.suspend(() => {
+		const current = run;
+		const failed = current?.failed;
+		return current === void 0 || failed === void 0 ? Effect.void : degrade(current, failed.error);
+	});
+	/** Say once that a run stopped drawing: already said for a degraded run, and said here for one that never mounted. */
+	const warnOnce = (current, error) => Effect.suspend(() => {
+		if (current.degraded) return Effect.void;
+		current.degraded = true;
+		return warning(error);
+	});
+	/** The final frame as a string, at the stdout width (80 when it reports none) and with no height to fit. */
+	const printFrame = (current) => Effect.gen(function* () {
+		const viewLoaded = yield* Effect.exit(loadView(options.render));
+		if (Exit.isFailure(viewLoaded)) return yield* warnOnce(current, Cause.squash(viewLoaded.cause));
+		const { ink, react } = yield* loadInk;
+		const frame = yield* frameOf;
+		const reported = streams.stdout.columns;
+		const columns = reported !== void 0 && reported > 0 ? reported : 80;
+		let failure;
+		const tree = react.createElement(errorBoundary(), {
+			onError: (error) => {
+				failure ??= { error };
+			},
+			children: uiProviders({
+				...provided,
+				size: {
+					columns,
+					rows: Number.POSITIVE_INFINITY
+				}
+			}, elementOf(state, frame))
+		});
+		const text = yield* Effect.scoped(Effect.andThen(withInkColour(colour), Effect.sync(() => ink.renderToString(tree, { columns }))));
+		if (failure !== void 0) return yield* warnOnce(current, failure.error);
+		bridge.print(neutralize ? CommandNeutralizer.text(text) : text);
+	});
+	/** The context `final`'s document is rendered with: `Doc.print`'s when the environment is there. */
+	const finalContext = Effect.gen(function* () {
+		const terminal = yield* Effect.serviceOption(TerminalEnv);
+		const links = yield* Effect.serviceOption(CliLinks);
+		if (Option.isSome(terminal) && Option.isSome(links) && Option.isSome(audience)) return yield* Render.context("stdout").pipe(Effect.provideService(CliTheme, cliTheme), Effect.provideService(TerminalEnv, terminal.value), Effect.provideService(CliLinks, links.value), Effect.provideService(Audience, audience.value));
+		return Render.contextOf({
+			audience: Option.isSome(audience) ? audience.value.kind : "human",
+			color: theme.color,
+			glyphs: theme.glyphs,
+			...neutralize ? { neutralizeWorkflowCommands: true } : {},
+			displayPath: provided.displayPath
+		});
+	});
+	/** A run's `final` document, printed as `Doc.print` would, to the view's stdout; never Ink. */
+	const printFinal = (current, final) => Effect.gen(function* () {
+		const built = yield* Effect.exit(Effect.try({
+			try: () => final(state),
+			catch: (error) => error
+		}));
+		if (Exit.isFailure(built)) return yield* warnOnce(current, Cause.squash(built.cause));
+		const ctx = yield* finalContext;
+		const text = Render[yield* autoFormat(ctx.audience)](built.value, ctx);
+		if (text !== "") bridge.print(text);
+	});
+	/** Mount a run's view with the current state, its tick beside it; a failure degrades the run. */
+	const mount = (current) => Effect.gen(function* () {
+		const scope = yield* Scope.make("sequential");
+		const slot = holderSlot();
+		current.mounted = {
+			scope,
+			slot
+		};
+		const report = (error) => {
+			current.failed ??= { error };
+			Queue.offerUnsafe(inbox, {
+				_tag: "Failed",
+				run: current
+			});
+		};
+		yield* Effect.gen(function* () {
+			yield* Effect.acquireRelease(mountPermit.take(1), () => mountPermit.release(1), { interruptible: true });
+			yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.("live")), () => Effect.sync(() => overrides.onUnmount?.(void 0)));
+			const { ink, react } = yield* loadInk;
+			yield* Effect.orDie(loadView(options.render));
+			yield* withInkColour(colour);
+			const frame = yield* frameOf;
+			const initial = elementOf(state, frame);
+			const shown = state;
+			const lastGood = () => {
+				const good = current.good;
+				return good === void 0 ? null : react.createElement(errorBoundary(), {
+					onError: () => {
+						current.painted = false;
+					},
+					children: elementOf(good.state, good.frame)
+				});
+			};
+			const tree = react.createElement(errorBoundary(), {
+				onError: report,
+				children: uiProviders(provided, react.createElement(bridge.Bridge, null, react.createElement(heightClamp(), null, react.createElement(errorBoundary(), {
+					onError: report,
+					fallback: lastGood,
+					children: react.createElement(holder(), {
+						initial,
+						bind: slot.bind
+					})
+				}))))
+			});
+			yield* Effect.acquireRelease(Effect.sync(() => {
+				return ink.render(tree, {
+					stdin: streams.stdin,
+					stdout: streams.stdout,
+					stderr: streams.stderr,
+					interactive: true,
+					exitOnCtrlC: false,
+					patchConsole: false,
+					...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender },
+					...overrides.maxFps === void 0 ? {} : { maxFps: overrides.maxFps }
+				});
+			}), (instance) => Effect.promise(async () => {
+				bridge.detach();
+				const exited = instance.waitUntilExit();
+				instance.unmount();
+				await exited.catch(() => void 0);
+			}));
+			yield* Effect.forkIn(Effect.repeat(Effect.flatMap(frameOf, (at) => Queue.offer(inbox, {
+				_tag: "Tick",
+				frame: at
+			})), Schedule.spaced(Duration.millis(tickMillis))), scope);
+			current.frame = frame;
+			if (current.failed === void 0) {
+				current.painted = true;
+				current.good = {
+					state: shown,
+					frame
+				};
+			}
+		}).pipe(Scope.provide(scope), Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : Effect.andThen(Effect.sync(() => {
+			if (current.mounted?.scope === scope) current.mounted = void 0;
+		}), Scope.close(scope, exit))));
+		yield* checkFailure;
+	}).pipe(Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : degrade(current, Cause.squash(cause))));
+	/**
+	* Push the current state to the mounted run, at `at` or the clock's frame, and wait for React to commit it; a
+	* frame that throws degrades the run.
+	*/
+	const drawAt = (at) => Effect.suspend(() => {
+		const current = run;
+		const mounted = current?.mounted;
+		if (current === void 0 || mounted === void 0) return Effect.void;
+		const shown = state;
+		return Effect.gen(function* () {
+			const frame = at ?? (yield* frameOf);
+			yield* Effect.callback((resume) => {
+				mounted.slot.swap(elementOf(shown, frame), () => queueMicrotask(() => resume(Effect.void)));
+			});
+			current.frame = frame;
+			if (current.failed === void 0) {
+				current.painted = true;
+				current.good = {
+					state: shown,
+					frame
+				};
+			}
+			yield* checkFailure;
+		});
+	});
+	const draw = drawAt(void 0);
+	/** End the run: unmount, which commits its frame; a degraded run that never painted prints its frame instead. */
+	const endRun = Effect.flatMap(takeRun, (current) => {
+		if (current === void 0) return Effect.void;
+		if (!interactive) {
+			if (options.mode === "hosted") return Effect.void;
+			return options.final === void 0 ? printFrame(current) : printFinal(current, options.final);
+		}
+		return Effect.suspend(() => {
+			const failed = current.failed;
+			const warned = failed === void 0 || current.degraded ? Effect.void : Effect.suspend(() => {
+				current.degraded = true;
+				return Effect.logWarning(DEGRADED(failed.error));
+			});
+			return Effect.andThen(warned, Effect.suspend(() => current.painted ? Effect.void : printFrame(current)));
+		});
+	});
+	const beginRun = Effect.suspend(() => {
+		const current = {
+			mounted: void 0,
+			degraded: false,
+			painted: false,
+			failed: void 0,
+			frame: 0,
+			good: void 0
+		};
+		run = current;
+		return interactive ? mount(current) : Effect.void;
+	});
+	/** Fold a chunk, starting and ending runs at its events, and draw once for what is left of it. */
+	const onChunk = (chunk) => Effect.gen(function* () {
+		let dirty = false;
+		for (const event of chunk) {
+			const folded = yield* Effect.try({
+				try: () => options.reduce(state, event),
+				catch: (error) => error
+			}).pipe(Effect.catch((error) => Effect.andThen(Effect.suspend(() => run === void 0 ? Effect.void : unmount(run)), Effect.die(error))));
+			const before = state;
+			if (run?.degraded === true && options.isStart(event)) {
+				yield* endRun;
+				state = folded;
+				yield* beginRun;
+				dirty = false;
+				continue;
+			}
+			state = folded;
+			if (options.isTerminal(event)) {
+				if (dirty || run !== void 0) yield* draw;
+				dirty = false;
+				yield* endRun;
+			} else if (run === void 0) {
+				if (begins(event, before, folded)) yield* beginRun;
+				dirty = false;
+			} else dirty = true;
+		}
+		if (dirty) yield* draw;
+	});
+	const onTick = (frame) => Effect.suspend(() => {
+		const current = run;
+		return current?.mounted === void 0 || frame <= current.frame ? Effect.void : drawAt(frame);
+	});
+	/**
+	* What a subscription holds now, taken without waiting: its buffered messages, then, once its PubSub has been
+	* ended with `PubSub.end`, the final message, the first time only. A shut-down subscription holds nothing (and a
+	* take from it would interrupt): it is not asked.
+	*/
+	const takeQueued = (sub) => Effect.suspend(() => {
+		const queued = PubSub.remainingUnsafe(sub);
+		if (Option.isNone(queued)) return Effect.succeed([]);
+		const ended = sub.ended.current;
+		const final = Option.isSome(ended) && !finalTaken ? [ended.value] : [];
+		if (final.length > 0) finalTaken = true;
+		return queued.value > 0 ? Effect.map(PubSub.takeUpTo(sub, queued.value), (taken) => [...taken, ...final]) : Effect.succeed(final);
+	});
+	/**
+	* What a subscription still queues, taken without waiting; nothing for a stream. Read once the pump has stopped
+	* (an `Ended` comes after it), so nothing else is taking. A subscription whose PubSub was shut down has nothing
+	* left, and a take from it would interrupt: it is not asked.
+	*/
+	const queuedTail = subscription === void 0 ? Effect.succeed([]) : takeQueued(subscription);
+	const control = Effect.gen(function* () {
+		while (true) {
+			const messages = yield* Queue.takeAll(inbox);
+			let pending = [];
+			const flush = Effect.suspend(() => {
+				const chunk = pending;
+				pending = [];
+				return chunk.length === 0 ? Effect.void : onChunk(chunk);
+			});
+			for (const message of messages) {
+				if (message._tag === "Events") {
+					pending.push(...message.chunk);
+					continue;
+				}
+				yield* flush;
+				switch (message._tag) {
+					case "Tick":
+						yield* onTick(message.frame);
+						break;
+					case "Failed":
+						if (message.run === run) yield* checkFailure;
+						break;
+					case "Ended": {
+						const tail = yield* queuedTail;
+						if (tail.length > 0) yield* onChunk(tail);
+						return yield* endRun;
+					}
+					case "Died":
+						yield* takeRun;
+						return yield* Effect.failCause(message.cause);
+				}
+			}
+			yield* flush;
+		}
+	});
+	const streamPull = stream === void 0 ? void 0 : yield* Stream.toPull(stream);
+	const offerEvents = (chunk) => chunk.length === 0 ? Effect.void : Queue.offer(inbox, {
+		_tag: "Events",
+		chunk
+	});
+	/**
+	* One take from a subscription, taken directly (no stream machinery), true once its events have ended: its
+	* PubSub was shut down, or ended with `PubSub.end` and its final message taken. Only the wait for a message can
+	* be interrupted, and nothing from the wait's end to the hand-off to the inbox yields to the scheduler, so an
+	* interrupt (`close`) never lands while a taken message is held: it is in the subscription or in the inbox. Each
+	* step waits or ends, so holding off the scheduler never spins.
+	*/
+	const subscriptionStep = (sub) => Effect.uninterruptibleMask((restore) => Effect.suspend(() => {
+		if (Option.isNone(PubSub.remainingUnsafe(sub))) return Effect.succeed(true);
+		if (Option.isSome(sub.ended.current)) return Effect.as(Effect.flatMap(takeQueued(sub), offerEvents), true);
+		return restore(PubSub.takeAll(sub)).pipe(Effect.catchCause((cause) => Option.isNone(PubSub.remainingUnsafe(sub)) ? Effect.succeed(void 0) : Effect.failCause(cause)), Effect.flatMap((chunk) => {
+			if (chunk === void 0) return Effect.succeed(true);
+			const ended = sub.ended.current;
+			const final = Option.isSome(ended) && chunk.length === 1 && chunk[0] === ended.value && Option.getOrElse(PubSub.remainingUnsafe(sub), () => 0) === 0;
+			if (final) finalTaken = true;
+			return Effect.as(offerEvents(chunk), final);
+		}));
+	})).pipe(Effect.provideService(Scheduler.PreventSchedulerYield, true));
+	const pump = streamPull !== void 0 ? Effect.forever(Effect.uninterruptibleMask((restore) => Effect.flatMap(restore(streamPull), offerEvents))).pipe(Pull.catchDone(() => Queue.offer(inbox, { _tag: "Ended" })), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Queue.offer(inbox, {
+		_tag: "Died",
+		cause
+	}))) : Effect.gen(function* () {
+		let ended = false;
+		while (!ended) ended = yield* subscriptionStep(source);
+		yield* Queue.offer(inbox, { _tag: "Ended" });
+	});
+	const pumping = yield* Effect.forkScoped(pump, { startImmediately: true });
+	const controlling = yield* Effect.forkScoped(Effect.onExit(control, () => Fiber.interrupt(pumping)));
+	yield* Effect.addFinalizer(() => Effect.andThen(Fiber.interruptAll([controlling, pumping]), takeRun));
+	const done = Fiber.join(controlling);
+	const settled = Effect.flatMap(Fiber.await(controlling), (exit) => Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause) ? Effect.void : Effect.failCause(exit.cause));
+	const ending = yield* Effect.cached(Effect.uninterruptible(Effect.andThen(Fiber.interrupt(pumping), Queue.offer(inbox, { _tag: "Ended" }))));
+	return {
+		state: Effect.sync(() => state),
+		logConsole: bridge.writer,
+		printAbove: bridge.printAbove,
+		done,
+		close: Effect.andThen(ending, settled)
+	};
+});
+
+export { live };

package/ui/CliUiRouteStream.js

@@ -0,0 +1,72 @@
+import { makeLineRouter } from "./internal/lineRouter.js";
+import { Writable } from "node:stream";
+
+// src/ui/CliUiRouteStream.ts
+/** The terminal facts a writer reads off its stream, delegated only where the original carries them. */
+const DELEGATED = [
+	"isTTY",
+	"columns",
+	"rows",
+	"getColorDepth",
+	"hasColors",
+	"getWindowSize"
+];
+const DEFAULT_MAX_HELD = 8192;
+/** Run one `Writable` step and settle its callback: with nothing, or with what the step threw, as an `Error`. */
+const guarded = (step, callback) => {
+	try {
+		step();
+		callback();
+	} catch (error) {
+		callback(error instanceof Error ? error : new Error(String(error)));
+	}
+};
+/** @internal */
+const routeStream = (original, printer, options) => {
+	const maxHeld = options.maxHeld ?? DEFAULT_MAX_HELD;
+	if (!Number.isInteger(maxHeld) || maxHeld < 0) throw new RangeError(`CliUi.routeStream: maxHeld must be a non-negative integer, got ${String(maxHeld)}`);
+	const router = makeLineRouter({
+		stream: options.stream,
+		printer,
+		write: (text) => {
+			original.write(text);
+		},
+		maxHeld,
+		carriageReturn: options.carriageReturn ?? "keep",
+		onText: options.onText
+	});
+	const writable = new Writable({
+		decodeStrings: false,
+		write(chunk, _encoding, callback) {
+			guarded(() => router.take(chunk), callback);
+		},
+		final(callback) {
+			guarded(router.flush, callback);
+		}
+	});
+	for (const key of DELEGATED) {
+		if (!(key in original)) continue;
+		let source;
+		let bound;
+		Object.defineProperty(writable, key, {
+			configurable: true,
+			enumerable: true,
+			get: () => {
+				const value = original[key];
+				if (typeof value !== "function") return value;
+				if (value !== source) {
+					source = value;
+					bound = value.bind(original);
+				}
+				return bound;
+			}
+		});
+	}
+	return {
+		writable,
+		route: router.route,
+		flush: router.flush
+	};
+};
+
+export { routeStream };