Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/activity/terminal.ts

Raw
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<TerminalHandle> {
	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<boolean> | undefined;
	let disposePromise: Promise<void> | undefined;
	let resolveCompletion!: () => void;
	const completion = new Promise<void>((resolve) => {
		resolveCompletion = resolve;
	});
	let resolveExit!: () => void;
	const exitSeen = new Promise<void>((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<boolean> {
		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<boolean> {
		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<void>((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;
		},
	};
}