@effected/cli 0.15.0 → 0.16.1

package/Doc.js

@@ -463,8 +463,9 @@ var Doc = class {
 	* and every other renderer writes nothing.
 	*
 	* @remarks
-	* It is the kit's own command, so `githubLog` does not neutralize it; its message and properties are escaped, so
-	* no text in them can end the command or start another. It is a command where a line starts: at the top level, as a
+	* It is the kit's own command, so `githubLog` does not neutralize the command itself; its message and properties are
+	* escaped, so no text in them can end the command or start another, and a `##[` in its message, title or file gets
+	* a braille pattern blank (U+2800) before the `[`, as in plain text. It is a command where a line starts: at the top level, as a
 	* top-level section's child, or as a direct child of a group's body. Nested deeper, it is dropped.
 	*
 	* @param options - the level, and the optional file, position and title

package/Render.js

@@ -232,7 +232,8 @@ var Render = class {
 	* body, `::endgroup::`. An annotation is a command at the top level, as a top-level section's child, and as a direct
 	* child of a group's body; anywhere deeper (inside a list, a callout, or a section within a group) it is nothing,
 	* as in plain. Its message and properties are escaped, so no text can end
-	* the command or start another, and the kit's own command is never neutralized. That is a top-level collapsible, or one that is a direct child of a
+	* the command or start another, and the kit's own command is never neutralized, though a `##[` in its message,
+	* title or file is. That is a top-level collapsible, or one that is a direct child of a
 	* top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
 	* (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
 	*
@@ -241,7 +242,7 @@ var Render = class {
 	* do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a braille pattern blank (U+2800) in
 	* front, which the runner neither trims nor skips, and every `##[` gets one before the `[`. The text is
 	* otherwise unchanged. A
-	* group's title is a command's data, so its `%`, CR and LF are escaped. Lines are split at CR, LF and CRLF before
+	* group's title is a command's data, so its `%`, CR and LF are escaped and a `##[` in it is neutralized. Lines are split at CR, LF and CRLF before
 	* that check, as the runner splits them. There is no ANSI and `paint` and `link` are never called, and the audience
 	* is treated as `agent`, as `plain` does.
 	*

package/index.d.ts

@@ -1382,8 +1382,9 @@ export declare class Doc {
    * and every other renderer writes nothing.
    *
    * @remarks
-   * It is the kit's own command, so `githubLog` does not neutralize it; its message and properties are escaped, so
-   * no text in them can end the command or start another. It is a command where a line starts: at the top level, as a
+   * It is the kit's own command, so `githubLog` does not neutralize the command itself; its message and properties are
+   * escaped, so no text in them can end the command or start another, and a `##[` in its message, title or file gets
+   * a braille pattern blank (U+2800) before the `[`, as in plain text. It is a command where a line starts: at the top level, as a
    * top-level section's child, or as a direct child of a group's body. Nested deeper, it is dropped.
    *
    * @param options - the level, and the optional file, position and title
@@ -3474,7 +3475,8 @@ export declare class Render {
    * body, `::endgroup::`. An annotation is a command at the top level, as a top-level section's child, and as a direct
    * child of a group's body; anywhere deeper (inside a list, a callout, or a section within a group) it is nothing,
    * as in plain. Its message and properties are escaped, so no text can end
-   * the command or start another, and the kit's own command is never neutralized. That is a top-level collapsible, or one that is a direct child of a
+   * the command or start another, and the kit's own command is never neutralized, though a `##[` in its message,
+   * title or file is. That is a top-level collapsible, or one that is a direct child of a
    * top-level section. GitHub does not nest groups, so a collapsible inside a group, or inside a list or callout
    * (where it would not start a line), keeps plain's rendering: its title on a line and its body indented.
    *
@@ -3483,7 +3485,7 @@ export declare class Render {
    * do that (`::add-mask::`, `::error::`, `##[error]`), so such a `::` line gets a braille pattern blank (U+2800) in
    * front, which the runner neither trims nor skips, and every `##[` gets one before the `[`. The text is
    * otherwise unchanged. A
-   * group's title is a command's data, so its `%`, CR and LF are escaped. Lines are split at CR, LF and CRLF before
+   * group's title is a command's data, so its `%`, CR and LF are escaped and a `##[` in it is neutralized. Lines are split at CR, LF and CRLF before
    * that check, as the runner splits them. There is no ANSI and `paint` and `link` are never called, and the audience
    * is treated as `agent`, as `plain` does.
    *

package/internal/renderGithubLog.js

@@ -5,10 +5,22 @@ import { CommandNeutralizer, WorkflowCommand } from "@effected/github-commands";
 //#region src/internal/renderGithubLog.ts
 /** Plain lines, neutralized; a block that draws nothing, such as an empty table, gives no line at all. */
 const plainLines = (blocks, ctx) => renderPlainLines(blocks, ctx).flatMap((line) => CommandNeutralizer.lines(line));
-/** An annotation as the kit's own command, on the trusted path: escaped by `WorkflowCommand`, never neutralized. */
-const annotationLine = (block) => WorkflowCommand[block.level](sanitize(block.message), {
-	...block.title === void 0 ? {} : { title: sanitize(block.title) },
-	...block.file === void 0 ? {} : { file: sanitize(block.file) },
+/**
+* A command's data, with every `##[` neutralized and its line breaks kept as they were. `WorkflowCommand` escapes the
+* breaks, so the command stays one line, but the runner's legacy parser reads `##[` ANYWHERE in a line, including in
+* a command's message and property values (it is tried when the V2 parser rejects the line), so each `##[` gets the
+* neutralizer's marker before its `[`. The V2 rule does not apply: no part of the data starts a line of the log, so
+* each part is neutralized behind a one-character lead that cannot start a command and is cut off again, which keeps
+* a part that begins `::` as it was. The command itself is not neutralized: only the data that goes into it.
+*/
+const commandData = (text) => text.split(/(\r\n|\r|\n)/).map((part, index) => index % 2 === 0 ? CommandNeutralizer.text(`.${part}`).slice(1) : part).join("");
+/**
+* An annotation as the kit's own command, on the trusted path: escaped by `WorkflowCommand`, and its message, title
+* and file neutralized as data (the line and the columns are numbers, which carry nothing).
+*/
+const annotationLine = (block) => WorkflowCommand[block.level](commandData(sanitize(block.message)), {
+	...block.title === void 0 ? {} : { title: commandData(sanitize(block.title)) },
+	...block.file === void 0 ? {} : { file: commandData(sanitize(block.file)) },
 	...block.line === void 0 ? {} : { startLine: block.line },
 	...block.endLine === void 0 ? {} : { endLine: block.endLine },
 	...block.col === void 0 ? {} : { startColumn: block.col },
@@ -20,7 +32,7 @@ const blockLines = (block, ctx) => {
 	switch (block._tag) {
 		case "Annotation": return [annotationLine(block)];
 		case "Collapsible": {
-			const title = plainInline(block.title, ctx).map((span) => span.text).join("");
+			const title = commandData(plainInline(block.title, ctx).map((span) => span.text).join(""));
 			return [
 				WorkflowCommand.group(title),
 				...bodyLines(block.body, ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/cli",
-	"version": "0.15.0",
+	"version": "0.16.1",
 	"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": [
@@ -57,11 +57,11 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/github-commands": "^0.2.0"
+		"@effected/github-commands": "^0.2.1"
 	},
 	"peerDependencies": {
 		"@effected/config-file": "^0.14.2",
-		"@effected/env": "^0.1.0",
+		"@effected/env": "^0.1.1",
 		"@effected/glob": "^0.10.0",
 		"@effected/walker": "^0.15.0",
 		"@types/react": "^19.3.0",

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/fakeStreams.js

@@ -1,10 +1,36 @@
 import { PassThrough, Writable } from "node:stream";
 
 //#region src/ui/testing/fakeStreams.ts
+/** The hide-cursor escape `cli-cursor` writes to a TTY stream as it arms the restore. */
+const HIDE_CURSOR = `${String.fromCharCode(27)}[?25l`;
+/** A cursor-show escape in a listener's source, as `restore-cursor` writes it (`'\u001B[?25h'`) or as the raw byte. */
+const CURSOR_SHOW = /\[\?25h/;
+/**
+* Disarm the real terminal's cursor restore that a fake TTY arms, so no byte of a run on the fakes reaches the
+* process's own streams (#983). The fake streams call it as the hide escape is written to them.
+*
+* @remarks
+* Ink's frame writer hides the cursor through `cli-cursor` on its first render, and `cli-cursor` does it only for a
+* stream that says it is a TTY, which the fakes do. Hiding it also arms `restore-cursor`, once per loaded copy of it
+* (once per test file where the runner isolates modules): a `signal-exit` hook (`alwaysLast`, so on the `afterexit`
+* event) that writes the cursor-show escape to the REAL `process.stderr` when the process exits or is signalled,
+* whatever stream Ink was given and whether or not stderr is a terminal. Nothing on the fakes hid the real cursor, so
+* that restore is only ever a stray byte in the test runner's output: this removes every `afterexit` listener that
+* writes a cursor-show escape, right after the copy that armed it wrote its hide escape. The emitter is `signal-exit` 3's process-wide one, the version `restore-cursor` 4
+* (the one Ink 8's `cli-cursor` takes) loads; without one there is nothing to disarm.
+*
+* The one read of `process` in the testing fakes, under the process-streams licence: it touches no stream.
+*/
+const disarmCursorRestore = () => {
+	const emitter = process.__signal_exit_emitter__;
+	if (emitter === void 0) return;
+	for (const listener of emitter.listeners("afterexit")) if (CURSOR_SHOW.test(String(listener))) emitter.removeListener("afterexit", listener);
+};
 const capture = (columns, rows, both, onWrite) => {
 	const chunks = [];
 	const stream = new Writable({ write(chunk, _encoding, callback) {
 		const text = chunk.toString();
+		if (text.includes(HIDE_CURSOR)) disarmCursorRestore();
 		chunks.push(text);
 		both.push(text);
 		onWrite?.(text);

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`).