Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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-16
diff --git a/packages/eve/src/cli/dev/tui/markdown.ts b/packages/eve/src/cli/dev/tui/markdown.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 94%
rename from packages/eve/src/cli/dev/tui/live-region.test.ts
rename to packages/eve/src/cli/ui/live-region.test.ts
index 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.ts
similarity index 100%
rename from packages/eve/src/cli/dev/tui/live-region.ts
rename to packages/eve/src/cli/ui/live-region.ts
diff --git a/packages/eve/src/cli/ui/live-row.test.ts b/packages/eve/src/cli/ui/live-row.test.ts
index 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.ts
index 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.ts
similarity index 98%
rename from packages/eve/src/cli/dev/tui/terminal-text.test.ts
rename to packages/eve/src/cli/ui/terminal-text.test.ts
index 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.ts
similarity index 100%
rename from packages/eve/src/cli/dev/tui/terminal-text.ts
rename to packages/eve/src/cli/ui/terminal-text.ts
diff --git a/packages/eve/src/setup/cli/rail-log.test.ts b/packages/eve/src/setup/cli/rail-log.test.ts
index 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.ts
index 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);
},
};
}