The Open Framework for Building Agents
fix(eve): improve live rendering of output (#912)
OwenKephartb53d713affcf
diff --git a/.changeset/fix-spinner-command-output-trample.md b/.changeset/fix-spinner-command-output-trample.mdnew file mode 100644index 000000000..79b6705cd--- /dev/null+++ b/.changeset/fix-spinner-command-output-trample.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Fixed transient TUI and CLI output rendering by standardizing spinners and progress rows on the shared `LiveRegion`. Streamed command output now stays aligned beneath active spinners, while failed operations preserve their command transcript for diagnostics.diff --git a/packages/eve/src/cli/dev/tui/agent-header.test.ts b/packages/eve/src/cli/dev/tui/agent-header.test.tsindex 33d8b34e2..73f760056 100644--- a/packages/eve/src/cli/dev/tui/agent-header.test.ts+++ b/packages/eve/src/cli/dev/tui/agent-header.test.ts@@ -3,7 +3,7 @@ import { describe, expect, it } from "vitest";import type { AgentInfoResult, AgentInfoToolEntry } from "#client/index.js";import { AGENT_HEADER_TIPS, buildAgentHeader, pickAgentHeaderTip } from "./agent-header.js";-import { stripAnsi } from "./terminal-text.js";+import { stripAnsi } from "#cli/ui/terminal-text.js";import { createTheme } from "./theme.js";const FRAMEWORK_TOOL: AgentInfoToolEntry = {diff --git a/packages/eve/src/cli/dev/tui/blocks.test.ts b/packages/eve/src/cli/dev/tui/blocks.test.tsindex d36e9b915..bd91ef0fb 100644--- a/packages/eve/src/cli/dev/tui/blocks.test.ts+++ b/packages/eve/src/cli/dev/tui/blocks.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from "vitest";import { type Block, renderBlockLines } from "./blocks.js";-import { stripAnsi, visibleLength } from "./terminal-text.js";+import { stripAnsi, visibleLength } from "#cli/ui/terminal-text.js";import { createTheme } from "./theme.js";const theme = createTheme({ color: false, unicode: true });diff --git a/packages/eve/src/cli/dev/tui/blocks.ts b/packages/eve/src/cli/dev/tui/blocks.tsindex 424ff3d45..7cc76bbf7 100644--- a/packages/eve/src/cli/dev/tui/blocks.ts+++ b/packages/eve/src/cli/dev/tui/blocks.ts@@ -14,7 +14,7 @@ import { renderMarkdown } from "./markdown.js";import type { Theme } from "./theme.js";import { isPromptControlCommand } from "./prompt-commands.js";import { formatValuePretty, truncate } from "./tool-format.js";-import { sliceVisible, visibleLength, wrapVisibleLine } from "./terminal-text.js";+import { sliceVisible, visibleLength, wrapVisibleLine } from "#cli/ui/terminal-text.js";export type ToolStatus = "running" | "done" | "error" | "denied" | "approval";diff --git a/packages/eve/src/cli/dev/tui/command-typeahead.test.ts b/packages/eve/src/cli/dev/tui/command-typeahead.test.tsindex 5817813fc..e039fec26 100644--- a/packages/eve/src/cli/dev/tui/command-typeahead.test.ts+++ b/packages/eve/src/cli/dev/tui/command-typeahead.test.ts@@ -11,7 +11,7 @@ import {typeaheadFor,} from "./command-typeahead.js";import { PROMPT_COMMANDS, type PromptCommandSpec } from "./prompt-commands.js";-import { stripAnsi } from "./terminal-text.js";+import { stripAnsi } from "#cli/ui/terminal-text.js";import { createTheme } from "./theme.js";const theme = createTheme({ color: false, unicode: true });diff --git a/packages/eve/src/cli/dev/tui/command-typeahead.ts b/packages/eve/src/cli/dev/tui/command-typeahead.tsindex 2c31dd968..7eba38746 100644--- a/packages/eve/src/cli/dev/tui/command-typeahead.ts+++ b/packages/eve/src/cli/dev/tui/command-typeahead.ts@@ -7,7 +7,7 @@*/import type { PromptCommandSpec } from "./prompt-commands.js";-import { sliceVisible, visibleLength } from "./terminal-text.js";+import { sliceVisible, visibleLength } from "#cli/ui/terminal-text.js";import type { Theme } from "./theme.js";import { renderCursorRow } from "#setup/cli/option-row.js";diff --git a/packages/eve/src/cli/dev/tui/line-editor.ts b/packages/eve/src/cli/dev/tui/line-editor.tsindex 2f64fcbfd..377287346 100644--- a/packages/eve/src/cli/dev/tui/line-editor.ts+++ b/packages/eve/src/cli/dev/tui/line-editor.ts@@ -17,7 +17,7 @@ import {nextGraphemeBoundary,previousGraphemeBoundary,} from "#shared/text-boundaries.js";-import { inputTextWidth, offsetAtVisibleColumn } from "./terminal-text.js";+import { inputTextWidth, offsetAtVisibleColumn } from "#cli/ui/terminal-text.js";/*** Editor text and a caret at a grapheme boundary, represented as a UTF-16diff --git a/packages/eve/src/cli/dev/tui/markdown.ts b/packages/eve/src/cli/dev/tui/markdown.tsindex c4d79fef2..19bf6849a 100644--- a/packages/eve/src/cli/dev/tui/markdown.ts+++ b/packages/eve/src/cli/dev/tui/markdown.ts@@ -1,4 +1,4 @@-import { visibleLength } from "./terminal-text.js";+import { visibleLength } from "#cli/ui/terminal-text.js";type TableAlignment = "left" | "center" | "right";diff --git a/packages/eve/src/cli/dev/tui/setup-panel.test.ts b/packages/eve/src/cli/dev/tui/setup-panel.test.tsindex b4747ca65..26c022297 100644--- a/packages/eve/src/cli/dev/tui/setup-panel.test.ts+++ b/packages/eve/src/cli/dev/tui/setup-panel.test.ts@@ -9,7 +9,7 @@ import {renderTextQuestion,type SetupPanelOption,} from "./setup-panel.js";-import { stripAnsi } from "./terminal-text.js";+import { stripAnsi } from "#cli/ui/terminal-text.js";import { createTheme } from "./theme.js";const theme = createTheme({ color: false, unicode: true });diff --git a/packages/eve/src/cli/dev/tui/setup-panel.ts b/packages/eve/src/cli/dev/tui/setup-panel.tsindex f32ea0cd0..1babe8a43 100644--- a/packages/eve/src/cli/dev/tui/setup-panel.ts+++ b/packages/eve/src/cli/dev/tui/setup-panel.ts@@ -38,7 +38,7 @@ import {renderInputWithBlockCursor,visibleLength,wrapVisibleLine,-} from "./terminal-text.js";+} from "#cli/ui/terminal-text.js";function clip(line: string, width: number): string {return clipVisible(line, width);diff --git a/packages/eve/src/cli/dev/tui/status-line.test.ts b/packages/eve/src/cli/dev/tui/status-line.test.tsindex 80c44f235..03fe30f5a 100644--- a/packages/eve/src/cli/dev/tui/status-line.test.ts+++ b/packages/eve/src/cli/dev/tui/status-line.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from "vitest";import { buildStatusLine } from "./status-line.js";-import { stripAnsi, visibleLength } from "./terminal-text.js";+import { stripAnsi, visibleLength } from "#cli/ui/terminal-text.js";import { createTheme } from "./theme.js";import type { RemoteConnectionSnapshot } from "./remote-connection.js";diff --git a/packages/eve/src/cli/dev/tui/status-line.ts b/packages/eve/src/cli/dev/tui/status-line.tsindex 8ed47e157..86b3c1a18 100644--- a/packages/eve/src/cli/dev/tui/status-line.ts+++ b/packages/eve/src/cli/dev/tui/status-line.ts@@ -1,4 +1,4 @@-import { clipVisible, stripAnsi, visibleLength } from "./terminal-text.js";+import { clipVisible, stripAnsi, visibleLength } from "#cli/ui/terminal-text.js";import type { Theme } from "./theme.js";import type { LogDisplayMode } from "./log-display-mode.js";import type { RemoteConnectionSnapshot } from "./remote-connection.js";diff --git a/packages/eve/src/cli/dev/tui/terminal-renderer.ts b/packages/eve/src/cli/dev/tui/terminal-renderer.tsindex 9126f354f..cd2739e84 100644--- a/packages/eve/src/cli/dev/tui/terminal-renderer.ts+++ b/packages/eve/src/cli/dev/tui/terminal-renderer.ts@@ -98,7 +98,7 @@ import {visibleLine,type LineState,} from "./line-editor.js";-import { LiveRegion } from "./live-region.js";+import { LiveRegion } from "#cli/ui/live-region.js";import { buildStatusLine } from "./status-line.js";import { nextLogDisplayMode } from "./log-display-mode.js";import { createTheme, detectUnicode, type Theme } from "./theme.js";@@ -108,7 +108,7 @@ import {renderInputWithBlockCursor,stripAnsi,stripTerminalControls,-} from "./terminal-text.js";+} from "#cli/ui/terminal-text.js";import type { VercelStatusSnapshot } from "./vercel-status.js";import type { RemoteConnectionSnapshot } from "./remote-connection.js";import { summarizeToolArgs, summarizeToolResult } from "./tool-format.js";diff --git a/packages/eve/src/cli/dev/tui/tool-format.ts b/packages/eve/src/cli/dev/tui/tool-format.tsindex a5549fc32..b9c1863aa 100644--- a/packages/eve/src/cli/dev/tui/tool-format.ts+++ b/packages/eve/src/cli/dev/tui/tool-format.ts@@ -7,7 +7,7 @@* plain strings — color is applied by the block renderer.*/-import { stripTerminalControls } from "./terminal-text.js";+import { stripTerminalControls } from "#cli/ui/terminal-text.js";const ELLIPSIS = "…";diff --git a/packages/eve/src/cli/run.test.ts b/packages/eve/src/cli/run.test.tsindex 1659c46e3..df11f2a3f 100644--- a/packages/eve/src/cli/run.test.ts+++ b/packages/eve/src/cli/run.test.ts@@ -3,6 +3,7 @@ import { resolve } from "node:path";import { describe, expect, it, vi } from "vitest";import { resolveDevUiMode, resolveTuiDisplayOptions, runCli } from "#cli/run.js";+import { MockScreen } from "#cli/dev/tui/test/mock-terminal.js";import type { RunDevelopmentTuiInput } from "#cli/dev/tui/tui.js";import type { DevelopmentServerOptions } from "#internal/nitro/host/types.js";@@ -353,7 +354,11 @@ describe("eve dev boot progress", () => {expect(hostReporter).toBeTypeOf("function");expect(tuiReporter).toBe(hostReporter);- expect(writes.at(-1)).toBe("\r\u001B[K");+ // Replaying every write through a terminal emulator: the boot progress row+ // is erased, leaving a clean screen for the error to print onto.+ const screen = new MockScreen({ columns: 80, rows: 10 });+ screen.write(writes.join(""));+ expect(screen.snapshot()).toBe("");expect(close).toHaveBeenCalledOnce();});});diff --git a/packages/eve/src/cli/dev/tui/live-region.test.ts b/packages/eve/src/cli/ui/live-region.test.tssimilarity index 94%rename from packages/eve/src/cli/dev/tui/live-region.test.tsrename to packages/eve/src/cli/ui/live-region.test.tsindex e5244179f..247551adf 100644--- a/packages/eve/src/cli/dev/tui/live-region.test.ts+++ b/packages/eve/src/cli/ui/live-region.test.ts@@ -1,7 +1,7 @@import { describe, expect, it } from "vitest";import { LiveRegion } from "./live-region.js";-import { MockScreen } from "./test/mock-terminal.js";+import { MockScreen } from "#cli/dev/tui/test/mock-terminal.js";function setup() {const screen = new MockScreen({ columns: 40, rows: 10 });diff --git a/packages/eve/src/cli/dev/tui/live-region.ts b/packages/eve/src/cli/ui/live-region.tssimilarity index 100%rename from packages/eve/src/cli/dev/tui/live-region.tsrename to packages/eve/src/cli/ui/live-region.tsdiff --git a/packages/eve/src/cli/ui/live-row.test.ts b/packages/eve/src/cli/ui/live-row.test.tsindex a270be72e..389a4e95b 100644--- a/packages/eve/src/cli/ui/live-row.test.ts+++ b/packages/eve/src/cli/ui/live-row.test.ts@@ -1,6 +1,7 @@import { afterEach, describe, expect, it, vi } from "vitest";-import { stripAnsi, visibleLength } from "#cli/dev/tui/terminal-text.js";+import { MockScreen } from "#cli/dev/tui/test/mock-terminal.js";+import { visibleLength } from "#cli/ui/terminal-text.js";import { startCliLiveRow } from "./live-row.js";@@ -8,40 +9,42 @@ afterEach(() => {vi.useRealTimers();});+function makeScreen(columns = 80) {+ return new MockScreen({ columns, rows: 10 });+}++/** The glyph column carries a lit marker on visible pulse steps, a space otherwise. */+function lit(screen: MockScreen): boolean {+ return screen.snapshot().trimStart().startsWith("▪");+}+describe("startCliLiveRow", () => {it("starts each indicator at the first sequence step", () => {vi.useFakeTimers();const sequence = "10100000";const makeIndicator = () => {- const writes: string[] = [];+ const screen = makeScreen();const progress = startCliLiveRow({ log: vi.fn() },- {- output: { columns: 80, isTTY: true, write: (chunk) => writes.push(chunk) },- pulseSequence: sequence,- },+ { output: screen, pulseSequence: sequence },);- return { progress, writes };+ return { progress, screen };};- const lit = (writes: string[]): boolean =>- stripAnsi(writes.at(-1) ?? "")- .trimStart()- .startsWith("▪");const first = makeIndicator();first.progress.update("First");- expect(lit(first.writes)).toBe(true);+ expect(lit(first.screen)).toBe(true);vi.advanceTimersByTime(125);- expect(lit(first.writes)).toBe(false);+ expect(lit(first.screen)).toBe(false);const second = makeIndicator();second.progress.update("Second");- expect(lit(second.writes)).toBe(true);+ expect(lit(second.screen)).toBe(true);vi.advanceTimersByTime(125);- expect(lit(first.writes)).toBe(true);- expect(lit(second.writes)).toBe(false);+ expect(lit(first.screen)).toBe(true);+ expect(lit(second.screen)).toBe(false);first.progress.stop();second.progress.stop();@@ -50,53 +53,39 @@ describe("startCliLiveRow", () => {it("renders installer detail inline without a second animation", () => {vi.useFakeTimers();- const writes: string[] = [];+ const screen = makeScreen();const progress = startCliLiveRow({ log: vi.fn() },- {- output: {- columns: 80,- isTTY: true,- write: (chunk) => writes.push(chunk),- },- pulseSequence: "00000000",- },+ { output: screen, pulseSequence: "00000000" },);- const rendered = (): string => stripAnsi(writes.at(-1) ?? "");progress.update("Preparing project");- expect(rendered()).toContain("Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");progress.update("Installing dependencies", "npm install");- expect(rendered()).toContain("Installing dependencies npm install");- expect(rendered()).not.toContain(" · ");- expect(rendered()).not.toContain("dependencies...");- const writesAfterUpdate = writes.length;+ // The detail replaces the row in place — one screen line, no stranded row.+ expect(screen.snapshot()).toBe(" Installing dependencies npm install");+ const rawAfterUpdate = screen.rawOutput();vi.advanceTimersByTime(600);- expect(writes).toHaveLength(writesAfterUpdate);+ // A silent pulse sequence never repaints, so nothing more is written.+ expect(screen.rawOutput()).toBe(rawAfterUpdate);progress.stop();+ expect(screen.snapshot()).toBe("");expect(vi.getTimerCount()).toBe(0);});it("collapses whitespace before fitting a progress row", () => {vi.useFakeTimers();- const writes: string[] = [];+ const screen = makeScreen(20);const progress = startCliLiveRow({ log: vi.fn() },- {- output: {- columns: 20,- isTTY: true,- write: (chunk) => writes.push(chunk),- },- pulseSequence: "00000000",- },+ { output: screen, pulseSequence: "00000000" },);progress.update("X\nY", "\u001B]0;title\u0007aa\t\u001B[31mbbbbbbb\u001B[0m");- const row = stripAnsi(writes.at(-1) ?? "");+ const row = screen.snapshot();expect(row).toContain("X Y aa bbbbbbb");expect(row).not.toContain("title");expect(row).not.toContain("\n");@@ -109,28 +98,20 @@ describe("startCliLiveRow", () => {it("plays a 16-step sequence over the same one-second loop", () => {vi.useFakeTimers();- const writes: string[] = [];+ const screen = makeScreen();const progress = startCliLiveRow({ log: vi.fn() },- {- output: {- columns: 80,- isTTY: true,- write: (chunk) => writes.push(chunk),- },- pulseSequence: "1000000010000000",- },+ { output: screen, pulseSequence: "1000000010000000" },);- const rendered = (): string => stripAnsi(writes.at(-1) ?? "");progress.update("Preparing project");- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");vi.advanceTimersByTime(63);- expect(rendered()).toContain(" Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");vi.advanceTimersByTime(437);- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");progress.stop();expect(vi.getTimerCount()).toBe(0);@@ -145,24 +126,18 @@ describe("startCliLiveRow", () => {it("keeps the 00000000 sequence silent", () => {vi.useFakeTimers();- const writes: string[] = [];+ const screen = makeScreen();const progress = startCliLiveRow({ log: vi.fn() },- {- output: {- columns: 80,- isTTY: true,- write: (chunk) => writes.push(chunk),- },- pulseSequence: "00000000",- },+ { output: screen, pulseSequence: "00000000" },);progress.update("Preparing project");- expect(stripAnsi(writes.at(-1) ?? "")).toContain(" Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");+ const rawAfterUpdate = screen.rawOutput();vi.advanceTimersByTime(1000);- expect(writes).toHaveLength(1);+ expect(screen.rawOutput()).toBe(rawAfterUpdate);progress.stop();expect(vi.getTimerCount()).toBe(0);@@ -170,40 +145,32 @@ describe("startCliLiveRow", () => {it("follows an eight-step pulse sequence", () => {vi.useFakeTimers();- const writes: string[] = [];+ const screen = makeScreen();const progress = startCliLiveRow({ log: vi.fn() },- {- output: {- columns: 80,- isTTY: true,- write: (chunk) => writes.push(chunk),- },- pulseSequence: "10100100",- },+ { output: screen, pulseSequence: "10100100" },);- const rendered = (): string => stripAnsi(writes.at(-1) ?? "");progress.update("Preparing project");- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");vi.advanceTimersByTime(125);- expect(rendered()).toContain(" Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");vi.advanceTimersByTime(125);- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");vi.advanceTimersByTime(125);- expect(rendered()).toContain(" Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");vi.advanceTimersByTime(250);- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");vi.advanceTimersByTime(125);- expect(rendered()).toContain(" Preparing project...");+ expect(screen.snapshot()).toBe(" Preparing project...");vi.advanceTimersByTime(250);- expect(rendered()).toContain("▪ Preparing project...");+ expect(screen.snapshot()).toBe("▪ Preparing project...");progress.stop();expect(vi.getTimerCount()).toBe(0);@@ -214,21 +181,18 @@ describe("startCliLiveRow", () => {const previous = process.env.EVE_LOG_LEVEL;process.env.EVE_LOG_LEVEL = "debug";try {- const writes: string[] = [];+ const screen = makeScreen();const logs: string[] = [];const progress = startCliLiveRow({ log: (message) => logs.push(message) },- {- output: { columns: 80, isTTY: true, write: (chunk) => writes.push(chunk) },- pulseSequence: "10101010",- },+ { output: screen, pulseSequence: "10101010" },);progress.update("Preparing project");progress.update("Creating agent");vi.advanceTimersByTime(1000);- expect(writes).toEqual([]);+ expect(screen.rawOutput()).toBe("");expect(logs).toEqual(["Preparing project..."]);expect(vi.getTimerCount()).toBe(0);diff --git a/packages/eve/src/cli/ui/live-row.ts b/packages/eve/src/cli/ui/live-row.tsindex aba00643d..41a407472 100644--- a/packages/eve/src/cli/ui/live-row.ts+++ b/packages/eve/src/cli/ui/live-row.ts@@ -1,6 +1,7 @@import pc from "picocolors";-import { sliceVisible, visibleLength } from "#cli/dev/tui/terminal-text.js";+import { sliceVisible, visibleLength } from "#cli/ui/terminal-text.js";+import { LiveRegion } from "#cli/ui/live-region.js";import { sanitizeForTerminal } from "#cli/ui/output.js";import {PROGRESS_PULSE_DURATION_MS,@@ -29,8 +30,6 @@ interface CliLiveRowOptions {readonly pulseSequence?: string;}-const REDRAW_PROGRESS_ROW = "\r\u001B[K";-function validatePulseSequence(sequence: string): void {if (sequence.length !== 8 && sequence.length !== 16) {throw new RangeError("Pulse sequence must contain 8 or 16 steps.");@@ -87,6 +86,16 @@ export function startCliLiveRow(validatePulseSequence(pulseSequence);const animate = output.isTTY === true && !isLogLevelEnabled("debug");+ // Single-row live region; only the animating path repaints, non-TTY logs once.+ const live = animate+ ? new LiveRegion({+ write: (chunk) => {+ output.write(chunk);+ return true;+ },+ })+ : undefined;+let pulseStepIndex = 0;let pulseVisible = pulseSequence[0] === "1";let current: { detail: string; message: string } | undefined;@@ -96,14 +105,14 @@ export function startCliLiveRow(let pulseTimer: ReturnType<typeof setTimeout> | undefined;const paint = (): void => {- if (current === undefined) return;+ if (current === undefined || live === undefined) return;const row = renderProgressRow(pulseVisible ? PROGRESS_PULSE_GLYPH : " ",current.message,current.detail,output.columns,);- output.write(`${painted ? REDRAW_PROGRESS_ROW : ""}${row}`);+ live.update([row]);painted = true;};@@ -146,7 +155,7 @@ export function startCliLiveRow(if (stopped) return;stopped = true;if (pulseTimer !== undefined) clearTimeout(pulseTimer);- if (animate && painted) output.write(REDRAW_PROGRESS_ROW);+ if (live !== undefined && painted) live.clear();},};}diff --git a/packages/eve/src/cli/dev/tui/terminal-text.test.ts b/packages/eve/src/cli/ui/terminal-text.test.tssimilarity index 98%rename from packages/eve/src/cli/dev/tui/terminal-text.test.tsrename to packages/eve/src/cli/ui/terminal-text.test.tsindex e88ac1d71..cbcd4668c 100644--- a/packages/eve/src/cli/dev/tui/terminal-text.test.ts+++ b/packages/eve/src/cli/ui/terminal-text.test.ts@@ -10,7 +10,7 @@ import {stripTerminalControls,visibleLength,wrapVisibleLine,-} from "./terminal-text.js";+} from "#cli/ui/terminal-text.js";describe("stripTerminalControls", () => {it("removes C0 and C1 controls while preserving tabs and newlines", () => {diff --git a/packages/eve/src/cli/dev/tui/terminal-text.ts b/packages/eve/src/cli/ui/terminal-text.tssimilarity index 100%rename from packages/eve/src/cli/dev/tui/terminal-text.tsrename to packages/eve/src/cli/ui/terminal-text.tsdiff --git a/packages/eve/src/setup/cli/rail-log.test.ts b/packages/eve/src/setup/cli/rail-log.test.tsindex e4b3f26f6..e28bbcb19 100644--- a/packages/eve/src/setup/cli/rail-log.test.ts+++ b/packages/eve/src/setup/cli/rail-log.test.ts@@ -2,9 +2,13 @@ import { Writable } from "node:stream";import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";+import { MockScreen } from "#cli/dev/tui/test/mock-terminal.js";+import { visibleLength } from "#cli/ui/terminal-text.js";+import { createRailLog, SPINNER_FRAMES } from "./rail-log.js";import type { PromptColors } from "./prompt-ui.js";+const ESC = String.fromCharCode(27);const identity = (text: string) => text;const colors: PromptColors = {@@ -47,14 +51,17 @@ class FakeOutput extends Writable {}}+/** Replays the recorded byte stream through a terminal emulator to the on-screen text. */+function screenOf(output: FakeOutput, columns = 80): string {+ const screen = new MockScreen({ columns, rows: 20 });+ screen.write(output.text());+ return screen.snapshot();+}+// The animation breathes a single braille cell; non-TTY shows the densest frame.const FIRST_FRAME = "⠨";const SECOND_FRAME = "⠸";const STATIC_FRAME = "⢿";-// Carriage return + clear-to-end-of-line: redraws the animated row in place.-const REDRAW = "\r\u001B[K";-// Clear the animated row, step up, and clear the leading rail spacer.-const ERASE_SPINNER = "\r\u001B[K\u001B[1A\r\u001B[K";describe("createRailLog spinner", () => {beforeEach(() => {@@ -70,22 +77,65 @@ describe("createRailLog spinner", () => {const log = createRailLog({ colors, output });const spinner = log.spinner("Loading Vercel teams...");- // Leading rail spacer, then the animated glyph row with no trailing newline.- expect(output.text()).toBe(`│\n${FIRST_FRAME} Loading Vercel teams...`);+ expect(screenOf(output)).toBe(`│\n${FIRST_FRAME} Loading Vercel teams...`);- output.chunks.length = 0;vi.advanceTimersByTime(120);- expect(output.text()).toBe(`${REDRAW}${SECOND_FRAME} Loading Vercel teams...`);+ // Redrawn in place, no stranded rows.+ expect(screenOf(output)).toBe(`│\n${SECOND_FRAME} Loading Vercel teams...`);- output.chunks.length = 0;spinner.stop();- expect(output.text()).toBe(ERASE_SPINNER);+ expect(screenOf(output)).toBe("");// Stop is idempotent and the animation no longer fires.- output.chunks.length = 0;+ const settledText = output.text();spinner.stop();vi.advanceTimersByTime(800);- expect(output.text()).toBe("");+ expect(output.text()).toBe(settledText);+ expect(vi.getTimerCount()).toBe(0);+ });++ test("folds streamed command output into a single preview row beneath the spinner", () => {+ const output = new FakeOutput(true);+ const log = createRailLog({ colors, output });++ const spinner = log.spinner("Deploying...");++ log.commandOutput("Progress: resolved 479");+ expect(screenOf(output)).toBe(`│\n${FIRST_FRAME} Deploying...\n│ Progress: resolved 479`);++ // The next line replaces the preview in place.+ log.commandOutput("Progress: resolved 479, added 101");+ expect(screenOf(output)).toBe(+ `│\n${FIRST_FRAME} Deploying...\n│ Progress: resolved 479, added 101`,+ );++ // Animation ticks keep the latest preview line visible.+ vi.advanceTimersByTime(120);+ expect(screenOf(output)).toBe(+ `│\n${SECOND_FRAME} Deploying...\n│ Progress: resolved 479, added 101`,+ );++ spinner.stop();+ expect(screenOf(output)).toBe("");+ });++ test("keeps failed command evidence and discards successful command noise", () => {+ const output = new FakeOutput(true);+ const log = createRailLog({ colors, output });++ let spinner = log.spinner("Deploying...");+ log.commandOutput("Uploading files");+ spinner.stop();+ log.success("Deployed the agent.");+ expect(screenOf(output)).toBe("│ Deployed the agent.");++ spinner = log.spinner("Redeploying...");+ log.commandOutput("Deployment failed: forbidden");+ spinner.stop();+ log.warning("Could not deploy the agent.");+ expect(screenOf(output)).toBe(+ "│ Deployed the agent.\n│ Deployment failed: forbidden\n│ Could not deploy the agent.",+ );});test("keeps the animated row to one terminal width so wrapping never strands a line", () => {@@ -93,25 +143,60 @@ describe("createRailLog spinner", () => {const log = createRailLog({ colors, output });log.spinner("Loading projects in vercel-internal-playground...");- // Truncated to columns - 4 with an ellipsis (1-cell glyph + two spaces + a- // margin cell), so the row stays within the 24-column width and never wraps.- expect(output.text()).toBe(`│\n${FIRST_FRAME} Loading projects in…`);- const drawn = output.text().split("\n")[1] ?? "";+ // Truncated with an ellipsis so the row stays within the 24-column width.+ expect(screenOf(output, 24)).toBe(`│\n${FIRST_FRAME} Loading projects in…`);+ const drawn = screenOf(output, 24).split("\n")[1] ?? "";expect([...drawn].length).toBeLessThanOrEqual(24);});+ test("clips ANSI-styled Unicode previews by visible terminal cells", () => {+ const output = new FakeOutput(true, 24);+ const log = createRailLog({ colors, output });+ const family = "👨👩👧👦";++ const first = log.spinner("First operation...");+ const spinner = log.spinner("Deploying...");+ first.stop();+ log.commandOutput(`\u001B[31m${family.repeat(20)}\u001B[0m`);++ const previewLine = screenOf(output, 24).split("\n")[2] ?? "";+ expect(visibleLength(previewLine)).toBeLessThanOrEqual(24);+ expect(previewLine).toContain(family);+ expect(previewLine).toContain("…");+ expect(previewLine).not.toContain("�");+ expect(vi.getTimerCount()).toBe(1);++ spinner.stop();+ });+test("prints one static line and never animates without a TTY", () => {- const output = new FakeOutput(false);+ const output = new FakeOutput(false, 12);const log = createRailLog({ colors, output });+ const message = "Loading a deliberately long operation name without truncation";- const spinner = log.spinner("Loading Vercel teams...");- expect(output.text()).toBe(`│\n${STATIC_FRAME} Loading Vercel teams...\n`);- expect(output.text()).not.toContain("\u001B[");+ const spinner = log.spinner(message);+ expect(output.text()).toBe(`│\n${STATIC_FRAME} ${message}\n`);+ expect(output.text()).not.toContain(ESC);- output.chunks.length = 0;+ const settledText = output.text();vi.advanceTimersByTime(800);spinner.stop();- expect(output.text()).toBe("");+ expect(output.text()).toBe(settledText);+ expect(vi.getTimerCount()).toBe(0);+ });++ test("appends command output line-by-line without a TTY", () => {+ const output = new FakeOutput(false);+ const log = createRailLog({ colors, output });++ const spinner = log.spinner("Deploying...");+ output.chunks.length = 0;++ // Non-TTY output is append-only: no cursor redraws that would corrupt logs.+ log.commandOutput("Progress: resolved 479");+ expect(output.text()).toBe("│ Progress: resolved 479\n");+ expect(output.text()).not.toContain(ESC);+ spinner.stop();});test("settles a live status row before drawing the spinner", () => {@@ -120,12 +205,14 @@ describe("createRailLog spinner", () => {log.message("Linking project...");log.commandOutput("vercel: working");- output.chunks.length = 0;log.spinner("Loading Vercel teams...");- // The transient command preview is cleared first, then the spinner draws.- expect(output.text()).toContain(`${FIRST_FRAME} Loading Vercel teams...`);- expect(output.text()).not.toContain("vercel: working");+ // The committed message stays; the transient command preview is gone, and the+ // spinner draws beneath it.+ const screen = screenOf(output);+ expect(screen).toContain(`${FIRST_FRAME} Loading Vercel teams...`);+ expect(screen).toContain("│ Linking project...");+ expect(screen).not.toContain("vercel: working");});test("paints the glyph the same green as the rail so it blends into the border", () => {diff --git a/packages/eve/src/setup/cli/rail-log.ts b/packages/eve/src/setup/cli/rail-log.tsindex dfc164de1..993704922 100644--- a/packages/eve/src/setup/cli/rail-log.ts+++ b/packages/eve/src/setup/cli/rail-log.ts@@ -1,5 +1,8 @@import type { Writable } from "node:stream";+import { LiveRegion } from "#cli/ui/live-region.js";+import { clipVisible, visibleLength } from "#cli/ui/terminal-text.js";+import type { ChannelSetupLog } from "./channel-setup-prompter.js";import { formatPromptHeader, formatRailLine, RAIL, type PromptColors } from "./prompt-ui.js";@@ -8,14 +11,6 @@ interface PromptOutput extends Writable {readonly columns?: number;}-type ActiveStatus =- | { kind: "idle" }- | {- kind: "active";- commandLines: string[];- previewRows: number;- };-/*** A running spinner anchored to the rail. Call {@link RailSpinner.stop}* once the awaited work settles to remove it; the call is idempotent.@@ -95,129 +90,166 @@ export interface RailLogOptions {output: PromptOutput;}-function countRows(rendered: string): number {- return rendered.split("\n").length - 1;+interface ActiveOperation {+ readonly commandLines: string[];+ view?: ActiveOperationView;}+type ActiveStatusView = { kind: "status"; preview?: string };+type ActiveSpinnerView = {+ kind: "spinner";+ frame: number;+ readonly label: string;+ preview?: string;+ timer?: ReturnType<typeof setInterval>;+};++type ActiveOperationView = ActiveStatusView | ActiveSpinnerView;+/**- * Renders setup status rows and keeps child command noise inside one live detail row.- *- * A TTY sees the latest dim command line below the current status while the command- * runs. Successful progression removes that transient detail. Warnings and errors- * commit the captured command transcript before the diagnostic. Non-TTY output is- * append-only because cursor redraw sequences would corrupt captured logs.+ * Renders setup status rows above a single {@link LiveRegion}. Committed lines+ * scroll away; the spinner and the latest command-output line are the region's+ * live rows. Warnings and errors commit the captured command transcript first.+ * Non-TTY output is append-only because cursor redraws would corrupt captured logs.*/export function createRailLog(options: RailLogOptions): RailLog {- let status: ActiveStatus = { kind: "idle" };- const canRedraw = options.output.isTTY === true;+ const { colors, output } = options;+ const canRedraw = output.isTTY === true;+ const columns = canRedraw && output.columns ? output.columns : 80;+ // Width budget that keeps every live row on one terminal line so it never wraps.+ const maxContent = Math.max(4, columns - (SPINNER_CELLS + 3));- function writeLine(text: string): void {- options.output.write(formatRailLine(text, options.colors, options.output));+ // TTY only; non-TTY output is append-only.+ const live = canRedraw+ ? new LiveRegion({+ write: (chunk) => {+ output.write(chunk);+ return true;+ },+ })+ : undefined;++ let activeOperation: ActiveOperation | undefined;++ const clip = (text: string): string =>+ visibleLength(text) > maxContent ? `${clipVisible(text, maxContent - 1)}…` : text;++ // The glyph shares the rail's green so it blends into the border.+ const spinnerRow = (spinner: ActiveSpinnerView): string => {+ const glyph = SPINNER_FRAMES[spinner.frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];+ return `${colors.green(glyph)} ${spinner.label}`;+ };+ const previewRow = (text: string): string => `${colors.green(RAIL)} ${colors.dim(clip(text))}`;++ function liveRows(): string[] {+ const view = activeOperation?.view;+ if (view === undefined) return [];++ const rows = view.kind === "spinner" ? [colors.green(RAIL), spinnerRow(view)] : [];+ if (view.preview !== undefined) rows.push(previewRow(view.preview));+ return rows;}- function clearPreview(): void {- if (!canRedraw || status.kind === "idle" || status.previewRows === 0) {+ // `formatRailLine` output may span several rows and ends in a newline; the+ // live region wants one entry per screen row.+ function commit(rendered: string): void {+ if (live === undefined) {+ output.write(rendered);return;}- options.output.write(`\u001B[${status.previewRows}A\u001B[J`);- status.previewRows = 0;+ live.flush(rendered.replace(/\n+$/u, "").split("\n"), liveRows());}- function settleStatus(preserveCommandOutput: boolean): void {- if (status.kind === "idle") {- return;+ function writeLine(text: string): void {+ commit(formatRailLine(text, colors, output));+ }++ function settle(preserveCommandOutput: boolean): void {+ const operation = activeOperation;+ if (operation === undefined) return;++ if (operation.view?.kind === "spinner" && operation.view.timer !== undefined) {+ clearInterval(operation.view.timer);}- if (canRedraw) {- clearPreview();- if (preserveCommandOutput) {- for (const text of status.commandLines) {- writeLine(options.colors.dim(text));- }- }+ activeOperation = undefined;++ if (live === undefined) return;+ if (preserveCommandOutput && operation.commandLines.length > 0) {+ const evidence = operation.commandLines.flatMap((line) =>+ formatRailLine(colors.dim(line), colors, output).replace(/\n+$/u, "").split("\n"),+ );+ live.flush(evidence, []);+ } else {+ live.update([]);}- status = { kind: "idle" };}return {message(text) {- settleStatus(false);+ settle(false);writeLine(text);- status = { kind: "active", commandLines: [], previewRows: 0 };+ activeOperation = { commandLines: [], view: { kind: "status" } };},info(text) {- settleStatus(false);- writeLine(options.colors.dim(text));+ settle(false);+ writeLine(colors.dim(text));},success(text) {- settleStatus(false);- writeLine(options.colors.dim(text));+ settle(false);+ writeLine(colors.dim(text));},warning(text) {- settleStatus(true);- writeLine(options.colors.yellow(text));+ settle(true);+ writeLine(colors.yellow(text));},error(text) {- settleStatus(true);- writeLine(options.colors.red(text));+ settle(true);+ writeLine(colors.red(text));},commandOutput(text) {- if (status.kind === "idle") {- writeLine(options.colors.dim(text));+ if (live === undefined || activeOperation === undefined) {+ output.write(formatRailLine(colors.dim(text), colors, output));return;}- status.commandLines.push(text);- if (!canRedraw) {- writeLine(options.colors.dim(text));- return;+ activeOperation.commandLines.push(text);+ if (activeOperation.view !== undefined) {+ activeOperation.view.preview = text;+ live.update(liveRows());}- clearPreview();- const preview = formatRailLine(options.colors.dim(text), options.colors, options.output);- options.output.write(preview);- status.previewRows = countRows(preview);},section(title, lines) {- settleStatus(false);- const body = lines- .map((line) => formatRailLine(line, options.colors, options.output))- .join("");- options.output.write(- `${formatPromptHeader("submit", title, { colors: options.colors, leadingRail: "green" })}${body}`,- );+ settle(false);+ const body = lines.map((line) => formatRailLine(line, colors, output)).join("");+ const header = formatPromptHeader("submit", title, { colors, leadingRail: "green" });+ commit(`${header}${body}`);},spinner(message) {- settleStatus(false);-- // The breathing cell stands in for the section bullet: a green leading- // rail, then an animated `<frame> <message>` row beneath it.- const spacer = `${options.colors.green(RAIL)}\n`;-- // Animation redraws the message row in place (carriage return + clear- // line), so it must stay on a single terminal row. Wrapping is what- // strands rows, so the label is truncated to the visible width: the- // spinner glyph (SPINNER_CELLS) + two spaces, minus a trailing cell to- // dodge the auto-wrap margin. Non-TTY output keeps the full message since- // it never redraws.- const columns = canRedraw && options.output.columns ? options.output.columns : 80;- const maxLabel = Math.max(4, columns - (SPINNER_CELLS + 3));- const label = message.length > maxLabel ? `${message.slice(0, maxLabel - 1)}…` : message;- // Paint the glyph the same green as the rail so it blends into the border.- const row = (glyph: string): string => `${options.colors.green(glyph)} ${label}`;-- if (!canRedraw) {- // No animation here, so show the densest frame as a static marker.- options.output.write(`${spacer}${row(SPINNER_STATIC)}\n`);+ settle(false);++ if (live === undefined) {+ // Append-only output is not constrained by terminal repaint geometry.+ output.write(`${colors.green(RAIL)}\n${colors.green(SPINNER_STATIC)} ${message}\n`);return { stop() {} };}- let frame = 0;- options.output.write(`${spacer}${row(SPINNER_FRAMES[0])}`);+ const spinnerView: ActiveSpinnerView = {+ kind: "spinner",+ frame: 0,+ label: clip(message),+ };+ const operation: ActiveOperation = {+ commandLines: [],+ view: spinnerView,+ };+ activeOperation = operation;+ live.update(liveRows());const timer = setInterval(() => {- frame += 1;- const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];- options.output.write(`\r\u001B[K${row(glyph)}`);+ if (activeOperation !== operation || operation.view !== spinnerView) return;+ spinnerView.frame += 1;+ live.update(liveRows());}, SPINNER_FRAME_MS);- // Never let the animation keep the process alive on its own.+ spinnerView.timer = timer;timer.unref?.();let stopped = false;@@ -226,14 +258,14 @@ export function createRailLog(options: RailLogOptions): RailLog {if (stopped) return;stopped = true;clearInterval(timer);- // Erase the animated row, step up, and erase the leading rail spacer- // so the spinner leaves no trace before the next prompt draws.- options.output.write("\r\u001B[K\u001B[1A\r\u001B[K");+ if (activeOperation !== operation) return;+ operation.view = undefined;+ live.update([]);},};},settle() {- settleStatus(false);+ settle(false);},};}