@termfleet/terminal 0.1.0

package/dist/tmux-stream.js

@@ -0,0 +1,187 @@
+import pty from "@homebridge/node-pty-prebuilt-multiarch";
+import fs from "node:fs";
+import { assertSession, getWindowSize } from "./tmux.js";
+export class TmuxTerminalAttachError extends Error {
+    phase;
+    constructor(phase, cause) {
+        super(errorMessage(cause), { cause });
+        this.name = "TmuxTerminalAttachError";
+        this.phase = phase;
+    }
+}
+// Attach one ephemeral PTY client to a durable tmux session. The returned
+// attachment owns every listener and descriptor it creates; dispose is
+// idempotent and never terminates the tmux session itself.
+export function attachTmuxTerminalSocket(options) {
+    const window = options.window ?? 0;
+    if (!Number.isInteger(window) || window < 0) {
+        throw new Error("window must be a non-negative integer");
+    }
+    let tmuxSize;
+    try {
+        assertSession(options.terminalId, options.tmuxSocket);
+        tmuxSize = getWindowSize({ name: options.terminalId, socket: options.tmuxSocket, window });
+    }
+    catch (error) {
+        throw new TmuxTerminalAttachError("resolve", error);
+    }
+    const cols = options.cols ?? tmuxSize.width;
+    const rows = options.rows ?? tmuxSize.height;
+    let reconciledPty;
+    try {
+        reconciledPty = spawnReconciledPty("tmux", [
+            ...(options.tmuxSocket ? ["-L", options.tmuxSocket] : []),
+            "-T",
+            "RGB",
+            "attach-session",
+            "-t",
+            options.terminalId
+        ], {
+            cols,
+            cwd: options.cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                TERM: "screen-256color"
+            },
+            rows
+        });
+    }
+    catch (error) {
+        throw new TmuxTerminalAttachError("spawn", error);
+    }
+    const { child, orphanPtmxFds } = reconciledPty;
+    let disposed = false;
+    let outputSubscription;
+    let exitSubscription;
+    const onClose = () => dispose();
+    const onMessage = (raw) => {
+        try {
+            const message = JSON.parse(raw.toString());
+            if (message.type !== "input") {
+                throw new Error(`Unsupported websocket message type: ${message.type}`);
+            }
+            if (typeof message.data !== "string") {
+                throw new Error("Input message did not include string data.");
+            }
+            void Promise.resolve(options.authorizeInput?.())
+                .then(async (authorization) => {
+                if (disposed)
+                    return;
+                await options.onInput?.(message.data, authorization);
+                if (!disposed)
+                    child.write(message.data);
+            })
+                .catch((error) => {
+                sendTerminalSocketError(options.socket, error, options.errorLabel);
+                options.socket.close(1008, "terminal access ended");
+            });
+        }
+        catch (error) {
+            sendTerminalSocketError(options.socket, error, options.errorLabel);
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        options.socket.off("close", onClose);
+        options.socket.off("message", onMessage);
+        outputSubscription?.dispose();
+        exitSubscription?.dispose();
+        releasePtyMaster(child, orphanPtmxFds);
+    };
+    options.socket.send(JSON.stringify({ cols, rows, type: "hello" }));
+    outputSubscription = child.onData((data) => {
+        if (!disposed && options.socket.readyState === options.socket.OPEN) {
+            options.socket.send(JSON.stringify({ data: wellFormedTerminalText(data), type: "output" }));
+        }
+    });
+    exitSubscription = child.onExit(({ exitCode, signal }) => {
+        if (!disposed && options.socket.readyState === options.socket.OPEN) {
+            options.socket.send(JSON.stringify({ exitCode, signal, type: "exit" }));
+            options.socket.close(1000, "tmux client exited");
+        }
+        dispose();
+    });
+    options.socket.on("close", onClose);
+    options.socket.on("message", onMessage);
+    return { dispose };
+}
+export function spawnReconciledPty(file, args, options) {
+    if (process.platform !== "darwin") {
+        return { child: pty.spawn(file, args, options), orphanPtmxFds: [] };
+    }
+    const before = listCharacterDeviceFds();
+    const child = pty.spawn(file, args, options);
+    const masterFd = child._fd;
+    const masterMajor = characterDeviceMajor(masterFd);
+    const orphanPtmxFds = [];
+    if (typeof masterFd === "number" && masterMajor !== null) {
+        for (const fd of listCharacterDeviceFds()) {
+            if (!before.has(fd) && fd !== masterFd && characterDeviceMajor(fd) === masterMajor) {
+                orphanPtmxFds.push(fd);
+            }
+        }
+    }
+    return { child, orphanPtmxFds };
+}
+export function releasePtyMaster(child, orphanPtmxFds = []) {
+    try {
+        child.destroy();
+    }
+    catch {
+        // Child already gone; destroy is best-effort.
+    }
+    for (const fd of orphanPtmxFds) {
+        if (characterDeviceMajor(fd) === null)
+            continue;
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // Already closed.
+        }
+    }
+}
+function characterDeviceMajor(fd) {
+    if (typeof fd !== "number")
+        return null;
+    try {
+        const stat = fs.fstatSync(fd);
+        return stat.isCharacterDevice() ? (stat.rdev >> 24) & 0xff : null;
+    }
+    catch {
+        return null;
+    }
+}
+function listCharacterDeviceFds() {
+    const fds = new Set();
+    try {
+        for (const entry of fs.readdirSync("/dev/fd")) {
+            const fd = Number(entry);
+            if (Number.isInteger(fd) && characterDeviceMajor(fd) !== null)
+                fds.add(fd);
+        }
+    }
+    catch {
+        // No /dev/fd (for example Windows conpty).
+    }
+    return fds;
+}
+function sendTerminalSocketError(socket, error, label = "terminal") {
+    if (socket.readyState !== socket.OPEN)
+        return;
+    socket.send(JSON.stringify({
+        message: `\r\n[${label}] ${errorMessage(error)}\r\n`,
+        type: "error"
+    }));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function wellFormedTerminalText(value) {
+    const maybeWellFormed = value;
+    if (typeof maybeWellFormed.toWellFormed === "function")
+        return maybeWellFormed.toWellFormed();
+    return value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+}

package/dist/tmux.d.ts

@@ -0,0 +1,128 @@
+export type TmuxPane = {
+    pane: number;
+    id: string;
+    rootPid?: number;
+    dead: boolean;
+    currentCommand: string;
+};
+export type TmuxWindowSize = {
+    width: number;
+    height: number;
+};
+export type CreateSessionOptions = {
+    cwd?: string;
+    env?: Record<string, string>;
+    name: string;
+    owner?: string;
+    ownerOption?: string;
+    panes: number;
+    socket?: string;
+};
+export declare function assertTmux(): void;
+export declare function targetForSession(sessionName: string): string;
+export declare function assertSession(name: string, socket?: string): void;
+export declare function createSession({ cwd, env, name, owner, ownerOption: ownershipOption, panes, socket }: CreateSessionOptions): Promise<{
+    name: string;
+    panes: number;
+}>;
+export declare function sessionOwner(session: string, socket?: string, ownershipOption?: string): string | undefined;
+export declare function sessionsOwnedBy(owner: string, socket?: string, ownershipOption?: string): string[];
+export declare function killSessionProcessTree({ session, socket }: {
+    session: string;
+    socket?: string;
+}): void;
+export declare function listTmuxSessionNames(socket?: string): string[];
+export declare function selectOrphanSessions({ allSessions, ownedSessions, prefix }: {
+    allSessions: string[];
+    ownedSessions: Iterable<string>;
+    prefix: string;
+}): string[];
+export declare function classifyPrefixSessions({ allSessions, ownedSessions, prefix }: {
+    allSessions: string[];
+    ownedSessions: Iterable<string>;
+    prefix: string;
+}): {
+    discovered: string[];
+    kept: string[];
+    orphans: string[];
+    tracked: string[];
+};
+export declare function waitForPanesReady({ expectedPanes, socket, target, timeoutMs }: {
+    target: string;
+    expectedPanes: number;
+    timeoutMs?: number;
+    socket?: string;
+}): Promise<TmuxPane[]>;
+export declare function inspectPanes(target: string, socket?: string): TmuxPane[];
+export declare function inspectPanesAsync(target: string, socket?: string): Promise<TmuxPane[]>;
+declare function parseListPanesOutput(output: string): {
+    active: boolean;
+    cwd: string;
+    id: string;
+    pane: number;
+    rootPid: number;
+    session: string;
+    title: string;
+    window: number;
+}[];
+export declare function listPanes(socket?: string): {
+    active: boolean;
+    cwd: string;
+    id: string;
+    pane: number;
+    rootPid: number;
+    session: string;
+    title: string;
+    window: number;
+}[];
+export declare function listPanesAsync(socket?: string): Promise<ReturnType<typeof parseListPanesOutput>>;
+export declare function clientForTty(tty: string, socket?: string): {
+    height: number;
+    target: string;
+    width: number;
+} | undefined;
+export declare function clientForTtyAsync(tty: string, socket?: string): Promise<{
+    height: number;
+    target: string;
+    width: number;
+} | undefined>;
+export declare function clientTtysForSession(session: string, socket?: string): string[];
+export declare function getWindowSize({ name, socket, window }: {
+    name: string;
+    window?: number;
+    socket?: string;
+}): TmuxWindowSize;
+export declare function listWindowSizesAsync(socket?: string): Promise<Map<string, TmuxWindowSize>>;
+export declare function setPaneStyle(target: string, style: string, socket?: string): Promise<void>;
+export declare function clearPaneStyle(target: string, socket?: string): Promise<void>;
+export declare function capturePane({ lines, preserveEscapes, socket, target }: {
+    target: string;
+    lines?: number;
+    preserveEscapes?: boolean;
+    socket?: string;
+}): string;
+export declare function capturePaneAsync({ lines, preserveEscapes, socket, target }: {
+    target: string;
+    lines?: number;
+    preserveEscapes?: boolean;
+    socket?: string;
+}): Promise<string>;
+export type TerminalInputDelivery = "keystream" | "submitted-line" | "submitted-paste";
+export declare function sendInterruptAsync({ socket, target }: {
+    target: string;
+    socket?: string;
+}): Promise<void>;
+export declare function sendInputAsync({ data, deadlineMs, socket, submitMode, target }: {
+    target: string;
+    data: string;
+    deadlineMs?: number;
+    submitMode?: "retry" | "single";
+    socket?: string;
+}): Promise<TerminalInputDelivery>;
+export declare function attachSession({ name, socket, window }: {
+    name: string;
+    socket?: string;
+    window?: number;
+}): void;
+export declare function submittedTextFromInput(data: string): string | undefined;
+export {};