@effected/cli 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.15.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

@@ -430,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/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

@@ -253,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.
    *
@@ -284,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

@@ -116,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
@@ -418,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`).