@effected/cli 0.14.0 → 0.16.0

package/Doc.js

@@ -379,12 +379,19 @@ var Doc = class {
 	/**
 	* Lines, one per entry, in every renderer: markdown joins them with hard breaks so they never collapse into one.
 	*
+	* @remarks
+	* `truncate` and `wrap: false` hold for every entry as they do for {@link Doc.line}: each entry is cut to the width,
+	* or kept whole on one line, rather than wrapped. Markdown keeps every entry whole either way.
+	*
 	* @param lines - the entries; each takes a string, an inline or an array of either
+	* @param options - `truncate`, to cut each entry to the width; `wrap: false`, to keep each whole
 	*/
-	static lines(lines) {
+	static lines(lines, options) {
 		return freeze({
 			_tag: "Lines",
-			lines: frozenArray(lines.map(inlines))
+			lines: frozenArray(lines.map(inlines)),
+			...options?.truncate === void 0 ? {} : { truncate: options.truncate },
+			...options?.wrap === void 0 ? {} : { wrap: options.wrap }
 		});
 	}
 	/**

package/index.d.ts

@@ -879,6 +879,8 @@ type Block = {
 } | {
   readonly _tag: "Lines";
   readonly lines: ReadonlyArray<ReadonlyArray<Inline>>;
+  readonly truncate?: boolean;
+  readonly wrap?: boolean;
 } | {
   readonly _tag: "Line";
   readonly content: ReadonlyArray<Inline>;
@@ -1312,9 +1314,17 @@ export declare class Doc {
   /**
    * Lines, one per entry, in every renderer: markdown joins them with hard breaks so they never collapse into one.
    *
+   * @remarks
+   * `truncate` and `wrap: false` hold for every entry as they do for {@link Doc.line}: each entry is cut to the width,
+   * or kept whole on one line, rather than wrapped. Markdown keeps every entry whole either way.
+   *
    * @param lines - the entries; each takes a string, an inline or an array of either
+   * @param options - `truncate`, to cut each entry to the width; `wrap: false`, to keep each whole
    */
-  static lines(lines: ReadonlyArray<InlineInput>): BlockOf<"Lines">;
+  static lines(lines: ReadonlyArray<InlineInput>, options?: {
+    readonly truncate?: boolean;
+    readonly wrap?: boolean;
+  }): BlockOf<"Lines">;
   /**
    * One line of content; with `truncate`, it is cut to the width with the glyph set's ellipsis instead of wrapping,
    * and with `wrap: false` it is kept whole on one line whatever the width.

package/internal/renderDoc.js

@@ -227,6 +227,13 @@ const countsLayout = (walk, block) => {
 		suffix
 	], " "))];
 };
+/** One `Line`, or one entry of a `Lines`: cut with `truncate`, kept whole with `wrap: false`, wrapped otherwise. */
+const lineOf = (walk, content, options, width) => {
+	const spans = oneLine(inline(walk, content));
+	if (options.truncate === true) return [trimLine(truncateSpans(spans, width, walk.ctx.glyphs.ellipsis))];
+	if (options.wrap === false) return [trimLine(spans)];
+	return spans.length === 0 ? [[]] : wrapSpans(spans, width, { hardBreak: false }).map(trimLine);
+};
 /**
 * A block as lines. `compact` is set on a compact list's item: a section there joins its title and children with no
 * blank lines between them.
@@ -275,15 +282,11 @@ const blockLines = (walk, block, width, compact = false) => {
 		case "Annotation": return [];
 		case "CountsTable": return tableLines(walk, countsTableOf(block), width);
 		case "Lines": return block.lines.flatMap((entry) => {
+			if (block.truncate === true || block.wrap === false) return lineOf(walk, entry, block, width);
 			const spans = inline(walk, entry);
 			return spans.length === 0 ? [[]] : wrapSpans(spans, width, { hardBreak: false }).map(trimLine);
 		});
-		case "Line": {
-			const spans = oneLine(inline(walk, block.content));
-			if (block.truncate === true) return [trimLine(truncateSpans(spans, width, walk.ctx.glyphs.ellipsis))];
-			if (block.wrap === false) return [trimLine(spans)];
-			return spans.length === 0 ? [[]] : wrapSpans(spans, width, { hardBreak: false }).map(trimLine);
-		}
+		case "Line": return lineOf(walk, block.content, block, width);
 		case "DiffText": {
 			const cap = capOf(block.cap);
 			const lines = textLines(block.text);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.14.0",
+	"version": "0.16.0",
 	"private": false,
 	"description": "The presentation boundary of an effect/cli program: audience-aware output, a document IR and renderers, editor links, failure reports and logging, plus opt-in Ink screens, widgets and a live view",
 	"keywords": [

package/ui/CliUi.js

@@ -262,7 +262,8 @@ var CliUi = class CliUi {
 	* mount to its end, so a `CliUi.run` during a run waits for the run to end, and one between runs mounts at once.
 	*
 	* While a run is drawn, write logs through `logConsole`, provided around the work the view reports on: its lines
-	* land above the frame. A line written to the terminal any other way tears the frame.
+	* land above the frame. A line written to the terminal any other way tears the frame. A host forwarding output it
+	* did not write itself prints it with `printAbove`, which says whether a frame was mounted to print it above.
 	*
 	* The view draws on stdout (`UiStreams`), at stdout's colour level and glyphs, and mounts only when the run is
 	* interactive (`CliInteractive`).

package/ui/CliUiLive.js

@@ -10,7 +10,6 @@ import { UiStreams } from "./UiStreams.js";
 import { makeInkConsole } from "./internal/inkConsole.js";
 import { LazyViewShapeError, loadView } from "./internal/lazyView.js";
 import { mountPermit } from "./internal/mountPermit.js";
-import { drainPerformance, resolveDrain } from "./internal/perfDrain.js";
 import { UiRenderOptions } from "./internal/renderOptions.js";
 import { uiProviders } from "./internal/UiProviders.js";
 import { useTerminalSize } from "./UiTheme.js";
@@ -63,7 +62,6 @@ const live = (options) => Effect.gen(function* () {
 	const interactive = yield* CliInteractive;
 	const streams = yield* UiStreams;
 	const overrides = yield* UiRenderOptions;
-	const drain = yield* resolveDrain(options.drainPerformance ?? "auto");
 	const bridge = yield* makeInkConsole;
 	const inbox = yield* Queue.unbounded();
 	const source = options.events;
@@ -148,7 +146,6 @@ const live = (options) => Effect.gen(function* () {
 			}, elementOf(state, frame))
 		});
 		const text = yield* Effect.scoped(Effect.andThen(withInkColour(colour), Effect.sync(() => ink.renderToString(tree, { columns }))));
-		drainPerformance(drain);
 		if (failure !== void 0) return yield* warnOnce(current, failure.error);
 		bridge.print(neutralize ? CommandNeutralizer.text(text) : text);
 	});
@@ -220,7 +217,7 @@ const live = (options) => Effect.gen(function* () {
 				}))))
 			});
 			yield* Effect.acquireRelease(Effect.sync(() => {
-				const instance = ink.render(tree, {
+				return ink.render(tree, {
 					stdin: streams.stdin,
 					stdout: streams.stdout,
 					stderr: streams.stderr,
@@ -230,13 +227,10 @@ const live = (options) => Effect.gen(function* () {
 					...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender },
 					...overrides.maxFps === void 0 ? {} : { maxFps: overrides.maxFps }
 				});
-				drainPerformance(drain);
-				return instance;
 			}), (instance) => Effect.promise(async () => {
 				bridge.detach();
 				const exited = instance.waitUntilExit();
 				instance.unmount();
-				drainPerformance(drain);
 				await exited.catch(() => void 0);
 			}));
 			yield* Effect.forkIn(Effect.repeat(Effect.flatMap(frameOf, (at) => Queue.offer(inbox, {
@@ -270,7 +264,6 @@ const live = (options) => Effect.gen(function* () {
 			yield* Effect.callback((resume) => {
 				mounted.slot.swap(elementOf(shown, frame), () => queueMicrotask(() => resume(Effect.void)));
 			});
-			drainPerformance(drain);
 			current.frame = frame;
 			if (current.failed === void 0) {
 				current.painted = true;
@@ -437,6 +430,7 @@ const live = (options) => Effect.gen(function* () {
 	return {
 		state: Effect.sync(() => state),
 		logConsole: bridge.writer,
+		printAbove: bridge.printAbove,
 		done,
 		close: Effect.andThen(ending, settled)
 	};

package/ui/UiTheme.js

@@ -69,6 +69,37 @@ const Styled = (props) => {
 };
 /** A reported size, or `fallback` when it is unknown: absent, or not positive (a pty `script` opens reports 0x0). */
 const known = (reported, fallback) => reported !== void 0 && reported > 0 ? reported : fallback;
+/** The redraws following each stream's size, and the one `resize` listener that calls them all. */
+const resizeFollowers = /* @__PURE__ */ new WeakMap();
+/**
+* Follow `stdout`'s size with `redraw`, returning the unfollow. However many components follow one stream, it holds
+* one `resize` listener, added with the first and removed with the last: one per component passed Node's default
+* limit of 10 on any list of `DocView` rows and printed a `MaxListenersExceededWarning` into the frame.
+*/
+const followResize = (stdout, redraw) => {
+	let entry = resizeFollowers.get(stdout);
+	if (entry === void 0) {
+		const redraws = /* @__PURE__ */ new Set();
+		const onResize = () => {
+			for (const each of redraws) each();
+		};
+		entry = {
+			redraws,
+			onResize
+		};
+		resizeFollowers.set(stdout, entry);
+		stdout.on("resize", onResize);
+	}
+	const { redraws, onResize } = entry;
+	redraws.add(redraw);
+	return () => {
+		redraws.delete(redraw);
+		if (redraws.size === 0 && resizeFollowers.get(stdout) === entry) {
+			resizeFollowers.delete(stdout);
+			stdout.off("resize", onResize);
+		}
+	};
+};
 /**
 * The usable terminal size: the stdout Ink draws on, less one column and one row, re-read on every render and when
 * the terminal resizes; or, under a `UiProvider` given a `size`, that size less one column and one row.
@@ -89,6 +120,9 @@ const known = (reported, fallback) => reported !== void 0 && reported > 0 ? repo
 * same paint, so give a long row Ink's `wrap: "truncate-end"` too: on a shrink Ink then clips it rather than letting
 * the terminal wrap it.
 *
+* Every component following one stdout shares a single `resize` listener on it, so a screen of many rows (a
+* `Viewport` of `DocView`s) holds one listener, not one per row.
+*
 * A React hook: call it from a component rendered inside an Ink tree; it needs no screen, but reads a `UiProvider`'s
 * size when there is one.
 *
@@ -100,13 +134,7 @@ const useTerminalSize = () => {
 	const override = react.useContext(screenContext())?.size;
 	const [, redraw] = react.useReducer((count) => count + 1, 0);
 	const followsStdout = override === void 0;
-	react.useEffect(() => {
-		if (!followsStdout) return void 0;
-		stdout.on("resize", redraw);
-		return () => {
-			stdout.off("resize", redraw);
-		};
-	}, [stdout, followsStdout]);
+	react.useEffect(() => followsStdout ? followResize(stdout, redraw) : void 0, [stdout, followsStdout]);
 	const reported = stdout;
 	const columns = override?.columns ?? reported.columns;
 	const rows = override?.rows ?? reported.rows;

package/ui/internal/inkConsole.js

@@ -135,6 +135,11 @@ const makeInkConsole = Effect.gen(function* () {
 			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;

package/ui/testing/CliUiTest.js

@@ -714,12 +714,17 @@ var CliUiTest = class {
 			end: Effect.andThen(Queue.end(queue), handle.done),
 			advance: (duration) => settled(TestClock.adjust(duration)),
 			resize: (nextColumns, nextRows) => settled(Effect.sync(() => terminal.fake.resize(nextColumns, nextRows))),
+			write: (stream, bytes) => Effect.sync(() => {
+				terminal.fake.streams[stream].write(bytes);
+			}),
 			frame: Effect.sync(() => trimLines(styled(last()))),
 			rawFrame: Effect.sync(last),
 			plainFrame: Effect.sync(() => trimLines(last().replace(ESCAPES, ""))),
 			frames: Effect.sync(() => raws().map((raw) => trimLines(styled(raw)))),
 			transcript: Effect.sync(() => screenAfter(terminal.fake.written(), terminal.fake.streams.stdout.rows).join("\n")),
 			written: Effect.sync(() => terminal.fake.written()),
+			stdoutWritten: Effect.sync(() => terminal.fake.stdout()),
+			stderrWritten: Effect.sync(() => terminal.fake.stderr()),
 			handle
 		};
 	});

package/ui-testing.d.ts

@@ -179,11 +179,14 @@ interface CliUiTestSession {
    * before the call is not missed. It waits at most 2 s, then dies naming the screen's number, the text it waited
    * for and how many screens had mounted. The returned screen's frames start at its own mount. A screen that crashed
    * makes `next` die with the crash instead.
+   *
+   * A `CliUi.live` run counts as a mount too, each run of the view one of its own: a program that draws a live
+   * progress view before its first screen takes one `next` per run before the screen's.
    */
   readonly next: (options?: CliUiTestNextOptions) => Effect.Effect<CliUiTestScreen>;
   /**
    * How many screens have mounted so far: every run that started mounting, one whose thunk threw before Ink drew
-   * included.
+   * included, and every run of a `CliUi.live` view.
    */
   readonly mounts: Effect.Effect<number>;
   /** What the program wrote to stdout through `Console` (`log`, `info`, `debug`), one line per call. */
@@ -250,6 +253,25 @@ interface CliUiTestLive<E, S> {
   readonly advance: (duration: Duration.Input) => Effect.Effect<void>;
   /** Resize the terminal, then wait as `publish` does. */
   readonly resize: (columns: number, rows: number) => Effect.Effect<void>;
+  /**
+   * Write `bytes` straight to the terminal's `stream`, past Ink and past the view: what a child process or another
+   * library writing to the process's own stdout or stderr does while a frame is drawn.
+   *
+   * @remarks
+   * The bytes go to the same in-memory stream the view draws on, so `written` and `transcript` hold them in the order
+   * they were written. Nothing is redrawn and nothing is waited for: a raw line under a mounted frame does its harm at
+   * the frame's next redraw (`advance`, `publish`), which erases as many lines as the frame had, counted from the
+   * cursor the raw line moved, and so leaves the frame's top row stranded in the scrollback above it. That is the
+   * failure to reproduce before proving a fix routes the line through `handle.printAbove` or `handle.logConsole`.
+   *
+   * Write whole lines (end `bytes` with `\n`) to model a line landing under the frame. A write made while a frame is
+   * still due from Ink's throttle can be read as that frame by `frame` and `frames`, which are best-effort;
+   * `transcript` and `written` are the authority.
+   *
+   * @param stream - the terminal stream to write to
+   * @param bytes - the bytes to write, as given: escapes are not removed
+   */
+  readonly write: (stream: "stdout" | "stderr", bytes: string) => Effect.Effect<void>;
   /**
    * The last frame drawn, as token markup (see {@link CliUiTest.styled}); empty before the first.
    *
@@ -281,7 +303,18 @@ interface CliUiTestLive<E, S> {
    * (a scrollback wipe) anywhere in a run.
    */
   readonly written: Effect.Effect<string>;
-  /** The view's own handle: its `state`, its `logConsole`, `done` and `close`. */
+  /**
+   * Every byte written to the terminal's stdout alone, escapes included: {@link CliUiTestLive.written} without stderr.
+   *
+   * @remarks
+   * With {@link CliUiTestLive.stderrWritten}, what to assert a line's stream on. Ink draws the frame, and erases and
+   * repaints it around a line logged above it, on stdout whichever stream the line is for, so a line routed to stderr
+   * shows in `stderrWritten` and never here.
+   */
+  readonly stdoutWritten: Effect.Effect<string>;
+  /** Every byte written to the terminal's stderr alone, escapes included: {@link CliUiTestLive.written} without stdout. */
+  readonly stderrWritten: Effect.Effect<string>;
+  /** The view's own handle: its `state`, its `logConsole`, `printAbove`, `done` and `close`. */
   readonly handle: LiveHandle<S>;
 }
 /**

package/ui.d.ts

@@ -92,13 +92,6 @@ interface LiveOptions<E, S> {
    * turns without events. Anything but a positive, finite number is a defect.
    */
   readonly tickMillis?: number;
-  /**
-   * Clear React's user-timing entries after every render: `true`, `false`, or `"auto"` (the default), which clears
-   * unless `NODE_ENV` is exactly `"production"`. React's development build records them on every render and never
-   * clears them. The clear is process-wide: it removes every `measure` entry, a program's own included; marks are left
-   * alone.
-   */
-  readonly drainPerformance?: boolean | "auto";
 }
 /**
  * The handle of a live view.
@@ -123,6 +116,36 @@ interface LiveHandle<S> {
    * Effect's `Console` (another library's own `process.stderr` writes) still tears the frame.
    */
   readonly logConsole: Console.Console;
+  /**
+   * Print one line above the frame if a run's frame is mounted now, and say whether it did: `true` when `line` and a
+   * line break went through Ink's writer for `stream`, above the frame, and `false`, having written nothing, when no
+   * frame is mounted.
+   *
+   * @remarks
+   * For a host that forwards output it did not write itself (a child process's stderr, a test runner's captured
+   * streams) and must know where it went. `logConsole` answers the same question silently, writing to `UiStreams`
+   * when no frame is mounted; `printAbove` leaves that case to the caller, who may have somewhere better to send the
+   * line, or may already be writing to the stream it would land on.
+   *
+   * A frame is mounted only during an interactive run: from the run's mount until just before its unmount. Between
+   * runs, before the first, after `close`, in a degraded run, and always when the view is not interactive (an agent,
+   * CI, a pipe, `TERM=dumb`, which never mounts), it returns `false`. The check and the write are one synchronous step,
+   * so the answer is never stale: a separate "is a frame mounted" query could be answered by one run and acted on in
+   * the gap before the next. Synchronous, like `logConsole`, so a Node stream's `write` callback can call it.
+   *
+   * `true` means Ink's writer accepted the line, not that it reached the terminal: while a render has handed the
+   * terminal to a child process (`useApp().suspendTerminal`), Ink drops what its writers are handed, and so does
+   * `logConsole`.
+   *
+   * The line is written as given: no formatting, no group indent, and no sanitising. A line break inside `line` is
+   * kept, and each of its lines lands above the frame. A cursor movement inside it (a `\r`, a cursor-up, an erase
+   * line, as a child's own progress bar writes) moves the cursor Ink repaints the frame from, and tears the frame.
+   *
+   * @param stream - the stream the line belongs on: Ink's stdout writer or its stderr writer
+   * @param line - the text to print, without a trailing line break
+   * @returns `true` if Ink's writer above a mounted frame took the line; `false`, with nothing written, otherwise
+   */
+  readonly printAbove: (stream: "stdout" | "stderr", line: string) => boolean;
   /**
    * Completes once the events have ended (the stream ended, the subscription's `PubSub` was ended with `PubSub.end` or
    * shut down, or `close` ended them) and the last run's frame is committed. Dies with what the view died of: a `reduce` that threw, or a
@@ -425,7 +448,8 @@ export declare class CliUi {
    * mount to its end, so a `CliUi.run` during a run waits for the run to end, and one between runs mounts at once.
    *
    * While a run is drawn, write logs through `logConsole`, provided around the work the view reports on: its lines
-   * land above the frame. A line written to the terminal any other way tears the frame.
+   * land above the frame. A line written to the terminal any other way tears the frame. A host forwarding output it
+   * did not write itself prints it with `printAbove`, which says whether a frame was mounted to print it above.
    *
    * The view draws on stdout (`UiStreams`), at stdout's colour level and glyphs, and mounts only when the run is
    * interactive (`CliInteractive`).
@@ -1779,6 +1803,9 @@ export declare const Styled: (props: StyledProps) => ReactElement;
  * same paint, so give a long row Ink's `wrap: "truncate-end"` too: on a shrink Ink then clips it rather than letting
  * the terminal wrap it.
  *
+ * Every component following one stdout shares a single `resize` listener on it, so a screen of many rows (a
+ * `Viewport` of `DocView`s) holds one listener, not one per row.
+ *
  * A React hook: call it from a component rendered inside an Ink tree; it needs no screen, but reads a `UiProvider`'s
  * size when there is one.
  *

package/ui/internal/perfDrain.js

@@ -1,33 +0,0 @@
-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 };