import type { IPty as Pty } from "@lydell/node-pty"; import { Unicode11Addon } from "@xterm/addon-unicode11"; import type { Terminal as Xterm } from "@xterm/headless"; import type { ProcessStart, TerminalCallbacks, TerminalHandle, TerminalScreen, } from "./types.js"; import { terminalView } from "./view.js"; import { resolveWindowsExecutable } from "./windows-executable.js"; const DEFAULT_COLS = 100; const DEFAULT_ROWS = 28; const MIN_COLS = 20; const MAX_COLS = 200; const MIN_ROWS = 5; const MAX_ROWS = 60; const SCROLLBACK = 1000; const MAX_SCREEN_BYTES = 16 * 1024; const PAUSE_AT_BYTES = 128 * 1024; const RESUME_AT_BYTES = 32 * 1024; const MAX_QUEUE_BYTES = 256 * 1024; const STOP_GRACE_MS = 500; const STOP_FORCE_MS = 1_000; const quietLogger = { debug() {}, info() {}, warn() {}, error() {}, log() {}, }; function dimensions(spec: ProcessStart): { cols: number; rows: number } { const cols = spec.cols ?? DEFAULT_COLS; const rows = spec.rows ?? DEFAULT_ROWS; if (!Number.isInteger(cols) || cols < MIN_COLS || cols > MAX_COLS) { throw new RangeError( `Terminal cols must be an integer from ${MIN_COLS} to ${MAX_COLS}.`, ); } if (!Number.isInteger(rows) || rows < MIN_ROWS || rows > MAX_ROWS) { throw new RangeError( `Terminal rows must be an integer from ${MIN_ROWS} to ${MAX_ROWS}.`, ); } return { cols, rows }; } function usefulNativeError(error: unknown): Error { const detail = error instanceof Error && error.message ? ` ${error.message}` : ""; return new Error( `Native terminal support is unavailable. Install @lydell/node-pty for this platform.${detail}`, { cause: error }, ); } function isNativeBindingError(error: unknown): boolean { return ( error instanceof Error && /failed to load native module|(?:conpty|winpty)\.node/i.test(error.message) ); } function byteLength(text: string): number { return Buffer.byteLength(text); } function boundedScreen( terminal: Xterm, cols: number, rows: number, ): TerminalScreen { const buffer = terminal.buffer.active; const lines: string[] = []; for (let row = 0; row < rows; row += 1) { lines.push( buffer.getLine(buffer.baseY + row)?.translateToString(true) ?? "", ); } const text = lines.join("\n"); const bytes = Buffer.from(text); if (bytes.byteLength <= MAX_SCREEN_BYTES) { return { text, cols, rows, cursorX: buffer.cursorX, cursorY: buffer.cursorY, truncated: false, }; } let start = bytes.byteLength - MAX_SCREEN_BYTES; while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++; return { text: bytes.subarray(start).toString("utf8"), cols, rows, cursorX: buffer.cursorX, cursorY: buffer.cursorY, truncated: true, }; } export async function openTerminal( spec: ProcessStart, cwd: string, callbacks: TerminalCallbacks, ): Promise { const { cols: initialCols, rows: initialRows } = dimensions(spec); let ptyModule: typeof import("@lydell/node-pty"); try { ptyModule = await import("@lydell/node-pty"); } catch (error) { throw usefulNativeError(error); } const { Terminal } = await import("@xterm/headless"); const executable = process.platform === "win32" ? await resolveWindowsExecutable(spec.command, cwd) : spec.command; const terminal = new Terminal({ allowProposedApi: true, cols: initialCols, rows: initialRows, scrollback: SCROLLBACK, logger: quietLogger, }); // Xterm's default Unicode 6 provider treats modern emoji as one cell. terminal.loadAddon(new Unicode11Addon()); terminal.unicode.activeVersion = "11"; let cursorVisible = true; const cursorSubscriptions = [ terminal.parser.registerCsiHandler( { prefix: "?", final: "h" }, (params) => { if (params.includes(25)) cursorVisible = true; return false; }, ), terminal.parser.registerCsiHandler( { prefix: "?", final: "l" }, (params) => { if (params.includes(25)) cursorVisible = false; return false; }, ), terminal.parser.registerCsiHandler( { intermediates: "!", final: "p" }, () => { cursorVisible = true; return false; }, ), ]; let pty: Pty; try { pty = ptyModule.spawn(executable, spec.args ?? [], { cols: initialCols, rows: initialRows, cwd, env: { ...process.env, TERM: "xterm-256color" }, name: "xterm-256color", }); } catch (error) { terminal.dispose(); if (isNativeBindingError(error)) throw usefulNativeError(error); throw error; } let cols = initialCols; let rows = initialRows; let parserBytes = 0; let parsing = false; let paused = false; let exited = false; let disposed = false; let backendError: string | undefined; let exitCode: number | null = null; let exitCallbackSent = false; let stopPromise: Promise | undefined; let disposePromise: Promise | undefined; let resolveCompletion!: () => void; const completion = new Promise((resolve) => { resolveCompletion = resolve; }); let resolveExit!: () => void; const exitSeen = new Promise((resolve) => { resolveExit = resolve; }); const queue: string[] = []; const responseSubscription = terminal.onData((data) => { if (!disposed && !exited) pty.write(data); }); function finishIfReady(): void { if (parsing || queue.length > 0 || !exited || disposed || exitCallbackSent) return; exitCallbackSent = true; resolveCompletion(); callbacks.changed(); callbacks.exit(exitCode, backendError); } function waitForExit(timeoutMs: number): Promise { return new Promise((resolve) => { const timer = setTimeout(() => resolve(false), timeoutMs); exitSeen.then(() => { clearTimeout(timer); resolve(true); }); }); } function parseNext(): void { if (parsing || disposed) return; const chunk = queue.shift(); if (chunk === undefined) { finishIfReady(); return; } parsing = true; terminal.write(chunk, () => { parserBytes -= byteLength(chunk); parsing = false; if (disposed) return; callbacks.changed(); if (paused && parserBytes <= RESUME_AT_BYTES && !exited) { paused = false; pty.resume(); } parseNext(); }); } function enqueue(data: string): void { if (backendError) return; const bytes = byteLength(data); if (parserBytes + bytes > MAX_QUEUE_BYTES) { backendError = "Terminal parser backlog exceeded 256 KiB; terminal stopped instead of silently dropping screen updates."; void stop(); return; } queue.push(data); parserBytes += bytes; if (!paused && parserBytes >= PAUSE_AT_BYTES) { paused = true; pty.pause(); } parseNext(); } const dataSubscription = pty.onData((data) => { if (disposed) return; callbacks.data(data); enqueue(data); }); const exitSubscription = pty.onExit((event) => { if (exited) return; exited = true; exitCode = event.signal ? null : event.exitCode; if (event.signal && !stopPromise) backendError ??= `Terminal exited from signal ${event.signal}.`; resolveExit(); finishIfReady(); }); function stop(): Promise { if (exited) return Promise.resolve(true); if (stopPromise) return stopPromise; const attempt = (async () => { if (process.platform === "win32") { try { pty.kill(); } catch {} } else { if (!exited && pty.pid > 0) { try { process.kill(-pty.pid, "SIGTERM"); } catch {} } try { pty.kill("SIGTERM"); } catch {} } if (await waitForExit(STOP_GRACE_MS)) return true; if (process.platform === "win32") { try { pty.kill(); } catch {} } else if (!exited) { if (pty.pid > 0) { try { process.kill(-pty.pid, "SIGKILL"); } catch {} } try { pty.kill("SIGKILL"); } catch {} } return waitForExit(STOP_FORCE_MS); })(); stopPromise = attempt; void attempt.then((stopped) => { if (!stopped && stopPromise === attempt) stopPromise = undefined; }); return attempt; } return { get pid() { return pty.pid > 0 ? pty.pid : undefined; }, write(text, keyboard = false) { if (disposed || exited) return; const input = keyboard && terminal.modes.applicationCursorKeysMode ? text.replace(/^\x1b\[([ABCDHF])$/, "\x1bO$1") : text; pty.write(input); }, paste(text) { if (disposed || exited) return; const safe = text.replace(/\x1b/g, ""); pty.write( terminal.modes.bracketedPasteMode ? `\x1b[200~${safe}\x1b[201~` : safe, ); }, resize(nextCols, nextRows) { const next = dimensions({ ...spec, cols: nextCols, rows: nextRows }); if (disposed) return; cols = next.cols; rows = next.rows; pty.resize(cols, rows); terminal.resize(cols, rows); }, screen() { return boundedScreen(terminal, cols, rows); }, view() { return terminalView(terminal, cursorVisible); }, stop, dispose() { if (disposePromise) return disposePromise; disposePromise = (async () => { await stop(); await new Promise((resolve) => { const timer = setTimeout(resolve, 1000); completion.then(() => { clearTimeout(timer); resolve(); }); }); disposed = true; dataSubscription.dispose(); exitSubscription.dispose(); responseSubscription.dispose(); for (const subscription of cursorSubscriptions) subscription.dispose(); terminal.dispose(); })(); return disposePromise; }, }; }