repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/activity/terminal.ts
Rawimport 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;
},
};
}