@co0ontty/wand 4.38.0 → 4.39.0

package/dist/terminal-daemon-server.js

@@ -0,0 +1,349 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import pty from "node-pty";
+import { ensureNodePtyHelperExecutable } from "./ensure-node-pty-helper.js";
+import { TERMINAL_DAEMON_PROTOCOL_VERSION, terminalDaemonPaths, } from "./terminal-daemon-protocol.js";
+import { appendTerminalChunkWindow, } from "./terminal-host.js";
+import { PtyTerminalState } from "./pty-terminal-state.js";
+import { PtyCliExitMarker } from "./pty-shell-launch.js";
+import { appendWindow, PTY_OUTPUT_MAX_SIZE } from "./pty-text-utils.js";
+const MAX_REQUEST_BUFFER = 4 * 1024 * 1024;
+export async function runTerminalDaemon(configPath) {
+    const paths = terminalDaemonPaths(configPath);
+    mkdirSync(path.dirname(paths.tokenPath), { recursive: true, mode: 0o700 });
+    const previousPid = readTerminalDaemonPid(configPath);
+    if (previousPid && previousPid !== process.pid && isProcessAlive(previousPid)) {
+        // A service install/update must never evict the daemon that owns live PTYs.
+        // Stay as the service-manager-owned successor and take over only after the
+        // previous standalone/versioned daemon naturally exits (for example reboot).
+        await waitForProcessExit(previousPid);
+    }
+    if (process.platform !== "win32" && existsSync(paths.socketPath)) {
+        if (await socketAcceptsConnections(paths.socketPath)) {
+            // Covers the narrow startup window before the winning daemon publishes
+            // its pid. Never unlink a socket that another live daemon already bound.
+            await waitForSocketRelease(paths.socketPath);
+        }
+        try {
+            unlinkSync(paths.socketPath);
+        }
+        catch { /* listen will report the real error */ }
+    }
+    const token = randomBytes(32).toString("hex");
+    const sessions = new Map();
+    const clients = new Set();
+    const send = (socket, message) => {
+        if (!socket.destroyed && socket.writable)
+            socket.write(`${JSON.stringify(message)}\n`);
+    };
+    const broadcast = (event) => {
+        for (const client of clients) {
+            if (client.authenticated)
+                send(client.socket, event);
+        }
+    };
+    const serialize = (session) => ({
+        sessionId: session.sessionId,
+        incarnationId: session.incarnationId,
+        pid: session.pid,
+        status: session.status,
+        exitCode: session.exitCode,
+        cols: session.cols,
+        rows: session.rows,
+        seq: session.seq,
+        output: session.output,
+        chunks: session.chunks.map((chunk) => ({ ...chunk })),
+        terminalSnapshot: session.terminalState.snapshot(),
+        launchMarkerToken: session.launchMarkerToken,
+    });
+    const createOrAttach = (params) => {
+        const existing = sessions.get(params.sessionId);
+        if (existing)
+            return { state: serialize(existing), isNew: false };
+        ensureNodePtyHelperExecutable();
+        const child = pty.spawn(params.file, params.args, {
+            cwd: params.cwd,
+            env: params.env,
+            name: params.name,
+            cols: params.cols,
+            rows: params.rows,
+        });
+        const session = {
+            sessionId: params.sessionId,
+            incarnationId: randomUUID(),
+            process: child,
+            pid: child.pid,
+            status: "running",
+            exitCode: null,
+            cols: params.cols,
+            rows: params.rows,
+            seq: 0,
+            output: "",
+            chunks: [],
+            terminalState: new PtyTerminalState(params.cols, params.rows),
+            launchMarkerToken: params.launchMarkerToken ?? null,
+            displayMarker: params.launchMarkerToken ? new PtyCliExitMarker(params.launchMarkerToken) : null,
+        };
+        sessions.set(params.sessionId, session);
+        child.onData((data) => {
+            if (sessions.get(session.sessionId) !== session || session.process !== child)
+                return;
+            const event = { data, seq: ++session.seq };
+            const visibleData = session.displayMarker?.consume(data).data ?? data;
+            session.output = appendWindow(session.output, visibleData, PTY_OUTPUT_MAX_SIZE);
+            session.chunks = appendTerminalChunkWindow(session.chunks, event);
+            if (visibleData)
+                session.terminalState.write(visibleData);
+            broadcast({
+                kind: "event",
+                event: "data",
+                sessionId: session.sessionId,
+                incarnationId: session.incarnationId,
+                data,
+                seq: event.seq,
+            });
+        });
+        child.onExit(({ exitCode, signal }) => {
+            if (sessions.get(session.sessionId) !== session || session.process !== child)
+                return;
+            session.process = null;
+            session.status = "exited";
+            session.exitCode = exitCode;
+            broadcast({
+                kind: "event",
+                event: "exit",
+                sessionId: session.sessionId,
+                incarnationId: session.incarnationId,
+                exitCode,
+                signal,
+            });
+        });
+        return { state: serialize(session), isNew: true };
+    };
+    const forget = (sessionId) => {
+        const session = sessions.get(sessionId);
+        if (!session)
+            return;
+        sessions.delete(sessionId);
+        const child = session.process;
+        session.process = null;
+        if (child) {
+            try {
+                child.kill();
+            }
+            catch { /* best-effort explicit deletion */ }
+        }
+        session.terminalState.dispose();
+    };
+    const handleRequest = (client, request) => {
+        if (request.token !== token) {
+            send(client.socket, { kind: "response", id: request.id, ok: false, error: "Unauthorized" });
+            client.socket.destroy();
+            return;
+        }
+        if (request.protocolVersion !== TERMINAL_DAEMON_PROTOCOL_VERSION) {
+            send(client.socket, {
+                kind: "response",
+                id: request.id,
+                ok: false,
+                error: `Unsupported terminal daemon protocol ${request.protocolVersion}`,
+            });
+            return;
+        }
+        client.authenticated = true;
+        try {
+            let result;
+            const params = request.params ?? {};
+            switch (request.method) {
+                case "hello":
+                    result = { protocolVersion: TERMINAL_DAEMON_PROTOCOL_VERSION, pid: process.pid };
+                    break;
+                case "list":
+                    result = Array.from(sessions.values(), serialize);
+                    break;
+                case "createOrAttach":
+                    result = createOrAttach(params);
+                    break;
+                case "write": {
+                    const session = sessions.get(String(params.sessionId ?? ""));
+                    if (!session?.process || session.status !== "running")
+                        throw new Error("Terminal is not running");
+                    session.process.write(String(params.data ?? ""));
+                    result = { ok: true };
+                    break;
+                }
+                case "resize": {
+                    const session = sessions.get(String(params.sessionId ?? ""));
+                    if (!session?.process || session.status !== "running")
+                        throw new Error("Terminal is not running");
+                    const cols = Number(params.cols);
+                    const rows = Number(params.rows);
+                    if (!Number.isSafeInteger(cols) || !Number.isSafeInteger(rows))
+                        throw new Error("Invalid terminal size");
+                    session.process.resize(cols, rows);
+                    session.terminalState.resize(cols, rows);
+                    session.cols = cols;
+                    session.rows = rows;
+                    result = { ok: true };
+                    break;
+                }
+                case "kill": {
+                    const session = sessions.get(String(params.sessionId ?? ""));
+                    if (session?.process)
+                        session.process.kill(typeof params.signal === "string" ? params.signal : undefined);
+                    result = { ok: true };
+                    break;
+                }
+                case "forget":
+                    forget(String(params.sessionId ?? ""));
+                    result = { ok: true };
+                    break;
+            }
+            send(client.socket, { kind: "response", id: request.id, ok: true, result });
+        }
+        catch (error) {
+            send(client.socket, {
+                kind: "response",
+                id: request.id,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+    const server = net.createServer((socket) => {
+        const client = { socket, authenticated: false, buffer: "" };
+        clients.add(client);
+        socket.setNoDelay(true);
+        socket.on("data", (data) => {
+            client.buffer += data.toString("utf8");
+            if (client.buffer.length > MAX_REQUEST_BUFFER) {
+                socket.destroy();
+                return;
+            }
+            while (true) {
+                const newline = client.buffer.indexOf("\n");
+                if (newline < 0)
+                    break;
+                const line = client.buffer.slice(0, newline);
+                client.buffer = client.buffer.slice(newline + 1);
+                if (!line)
+                    continue;
+                try {
+                    handleRequest(client, JSON.parse(line));
+                }
+                catch {
+                    socket.destroy();
+                    return;
+                }
+            }
+        });
+        socket.on("close", () => clients.delete(client));
+        socket.on("error", () => clients.delete(client));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(paths.socketPath, () => {
+            server.off("error", reject);
+            if (process.platform !== "win32")
+                chmodSync(paths.socketPath, 0o600);
+            // Publish credentials only after this process has atomically won the
+            // socket bind. Concurrent starters can no longer overwrite the live
+            // daemon's token/pid before discovering EADDRINUSE.
+            writeFileSync(paths.tokenPath, `${token}\n`, { encoding: "utf8", mode: 0o600 });
+            writeFileSync(paths.pidPath, `${process.pid}\n`, { encoding: "utf8", mode: 0o600 });
+            resolve();
+        });
+    });
+    const shutdown = () => {
+        for (const sessionId of Array.from(sessions.keys()))
+            forget(sessionId);
+        for (const client of clients)
+            client.socket.destroy();
+        server.close(() => process.exit(0));
+        cleanupDaemonFiles(paths.socketPath, paths.tokenPath, paths.pidPath);
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}
+function cleanupDaemonFiles(socketPath, tokenPath, pidPath) {
+    for (const file of [socketPath, tokenPath, pidPath]) {
+        if (process.platform === "win32" && file === socketPath)
+            continue;
+        try {
+            unlinkSync(file);
+        }
+        catch { /* already absent */ }
+    }
+}
+export function readTerminalDaemonPid(configPath) {
+    try {
+        const value = Number(readFileSync(terminalDaemonPaths(configPath).pidPath, "utf8").trim());
+        return Number.isSafeInteger(value) && value > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function waitForProcessExit(pid) {
+    return new Promise((resolve) => {
+        const timer = setInterval(() => {
+            if (isProcessAlive(pid))
+                return;
+            clearInterval(timer);
+            process.off("SIGINT", stopWaiting);
+            process.off("SIGTERM", stopWaiting);
+            resolve();
+        }, 500);
+        const stopWaiting = () => {
+            clearInterval(timer);
+            process.exit(0);
+        };
+        process.once("SIGINT", stopWaiting);
+        process.once("SIGTERM", stopWaiting);
+    });
+}
+function socketAcceptsConnections(socketPath) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        let settled = false;
+        const finish = (alive) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(alive);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        const timer = setTimeout(() => finish(false), 300);
+        timer.unref?.();
+    });
+}
+async function waitForSocketRelease(socketPath) {
+    let stopped = false;
+    const stopWaiting = () => {
+        stopped = true;
+    };
+    process.once("SIGINT", stopWaiting);
+    process.once("SIGTERM", stopWaiting);
+    while (!stopped && await socketAcceptsConnections(socketPath)) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    process.off("SIGINT", stopWaiting);
+    process.off("SIGTERM", stopWaiting);
+    if (stopped)
+        process.exit(0);
+}

package/dist/terminal-host.d.ts

@@ -0,0 +1,79 @@
+import type { PtyTerminalSnapshot } from "./pty-terminal-state.js";
+export interface TerminalDataEvent {
+    data: string;
+    /** Monotonic per-incarnation chunk sequence used for gap-free reattach. */
+    seq: number;
+}
+export interface TerminalExitEvent {
+    exitCode: number;
+    signal?: number;
+}
+export interface TerminalProcess {
+    readonly sessionId: string;
+    readonly incarnationId: string;
+    readonly pid: number;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+    pause(): void;
+    resume(): void;
+    onData(listener: (event: TerminalDataEvent) => void): {
+        dispose(): void;
+    };
+    onExit(listener: (event: TerminalExitEvent) => void): {
+        dispose(): void;
+    };
+}
+export interface TerminalSessionState {
+    sessionId: string;
+    incarnationId: string;
+    pid: number;
+    status: "running" | "exited";
+    exitCode: number | null;
+    cols: number;
+    rows: number;
+    seq: number;
+    output: string;
+    chunks: TerminalDataEvent[];
+    terminalSnapshot: PtyTerminalSnapshot | null;
+    launchMarkerToken: string | null;
+}
+export interface TerminalAttachResult {
+    process: TerminalProcess | null;
+    state: TerminalSessionState;
+    replay: TerminalDataEvent[];
+    isNew: boolean;
+}
+export interface TerminalSpawnRequest {
+    sessionId: string;
+    file: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    name: string;
+    cols: number;
+    rows: number;
+    launchMarkerToken?: string;
+}
+/**
+ * Owns terminal processes behind one small seam. Persistent adapters may outlive
+ * their caller; in-process adapters deliberately retain the legacy lifecycle.
+ */
+export interface TerminalHost {
+    readonly persistent: boolean;
+    attach(sessionId: string, afterSeq?: number): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest, afterSeq?: number): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    disconnect(): void;
+}
+/** Legacy/local adapter and deterministic test adapter for the TerminalHost seam. */
+export declare class InProcessTerminalHost implements TerminalHost {
+    readonly persistent = false;
+    private readonly processes;
+    attach(): TerminalAttachResult | null;
+    createOrAttach(request: TerminalSpawnRequest): Promise<TerminalAttachResult>;
+    forget(sessionId: string): void;
+    disconnect(): void;
+}
+/** Keep a bounded replay log while preserving chunk sequence numbers. */
+export declare function appendTerminalChunkWindow(chunks: readonly TerminalDataEvent[], event: TerminalDataEvent): TerminalDataEvent[];

package/dist/terminal-host.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import pty from "node-pty";
+import { ensureNodePtyHelperExecutable } from "./ensure-node-pty-helper.js";
+import { PTY_OUTPUT_MAX_SIZE } from "./pty-text-utils.js";
+class InProcessTerminalProcess {
+    sessionId;
+    child;
+    incarnationId = randomUUID();
+    seq = 0;
+    constructor(sessionId, child) {
+        this.sessionId = sessionId;
+        this.child = child;
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    write(data) {
+        this.child.write(data);
+    }
+    resize(cols, rows) {
+        this.child.resize(cols, rows);
+    }
+    kill(signal) {
+        this.child.kill(signal);
+    }
+    pause() {
+        this.child.pause();
+    }
+    resume() {
+        this.child.resume();
+    }
+    onData(listener) {
+        return this.child.onData((data) => listener({ data, seq: ++this.seq }));
+    }
+    onExit(listener) {
+        return this.child.onExit(({ exitCode, signal }) => listener({ exitCode, signal }));
+    }
+}
+/** Legacy/local adapter and deterministic test adapter for the TerminalHost seam. */
+export class InProcessTerminalHost {
+    persistent = false;
+    processes = new Map();
+    attach() {
+        return null;
+    }
+    async createOrAttach(request) {
+        const existing = this.processes.get(request.sessionId);
+        if (existing) {
+            return {
+                process: existing,
+                state: emptyRunningState(existing, request.cols, request.rows, request.launchMarkerToken),
+                replay: [],
+                isNew: false,
+            };
+        }
+        ensureNodePtyHelperExecutable();
+        const child = pty.spawn(request.file, request.args, {
+            cwd: request.cwd,
+            env: request.env,
+            name: request.name,
+            cols: request.cols,
+            rows: request.rows,
+        });
+        const process = new InProcessTerminalProcess(request.sessionId, child);
+        this.processes.set(request.sessionId, process);
+        process.onExit(() => {
+            if (this.processes.get(request.sessionId) === process) {
+                this.processes.delete(request.sessionId);
+            }
+        });
+        return {
+            process,
+            state: emptyRunningState(process, request.cols, request.rows, request.launchMarkerToken),
+            replay: [],
+            isNew: true,
+        };
+    }
+    forget(sessionId) {
+        this.processes.delete(sessionId);
+    }
+    disconnect() {
+        for (const process of this.processes.values()) {
+            try {
+                process.kill();
+            }
+            catch { /* best-effort legacy shutdown */ }
+        }
+        this.processes.clear();
+    }
+}
+function emptyRunningState(process, cols, rows, launchMarkerToken) {
+    return {
+        sessionId: process.sessionId,
+        incarnationId: process.incarnationId,
+        pid: process.pid,
+        status: "running",
+        exitCode: null,
+        cols,
+        rows,
+        seq: 0,
+        output: "",
+        chunks: [],
+        terminalSnapshot: null,
+        launchMarkerToken: launchMarkerToken ?? null,
+    };
+}
+/** Keep a bounded replay log while preserving chunk sequence numbers. */
+export function appendTerminalChunkWindow(chunks, event) {
+    const boundedEvent = event.data.length > PTY_OUTPUT_MAX_SIZE
+        ? { ...event, data: event.data.slice(-PTY_OUTPUT_MAX_SIZE) }
+        : event;
+    const next = [...chunks, boundedEvent];
+    let size = 0;
+    let first = next.length;
+    while (first > 0) {
+        const candidate = next[first - 1].data.length;
+        if (size > 0 && size + candidate > PTY_OUTPUT_MAX_SIZE)
+            break;
+        size += candidate;
+        first -= 1;
+    }
+    return next.slice(first);
+}