@co0ontty/wand 4.38.0 → 4.39.0

package/dist/terminal-daemon-client.js

@@ -0,0 +1,406 @@
+import { existsSync, readFileSync } from "node:fs";
+import net from "node:net";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { TERMINAL_DAEMON_PROTOCOL_VERSION, terminalDaemonPaths, } from "./terminal-daemon-protocol.js";
+import { appendTerminalChunkWindow, InProcessTerminalHost, } from "./terminal-host.js";
+import { appendWindow, PTY_OUTPUT_MAX_SIZE } from "./pty-text-utils.js";
+class RemoteTerminalProcess {
+    sessionId;
+    incarnationId;
+    pid;
+    client;
+    dataListeners = new Set();
+    exitListeners = new Set();
+    paused = false;
+    pausedEvents = [];
+    undeliveredEvents = [];
+    pendingExit = null;
+    constructor(sessionId, incarnationId, pid, client) {
+        this.sessionId = sessionId;
+        this.incarnationId = incarnationId;
+        this.pid = pid;
+        this.client = client;
+    }
+    write(data) {
+        void this.client.request("write", { sessionId: this.sessionId, data }).catch((error) => {
+            this.client.reportOperationError(this.sessionId, error);
+        });
+    }
+    resize(cols, rows) {
+        void this.client.request("resize", { sessionId: this.sessionId, cols, rows }).catch((error) => {
+            this.client.reportOperationError(this.sessionId, error);
+        });
+    }
+    kill(signal) {
+        void this.client.request("kill", { sessionId: this.sessionId, signal }).catch((error) => {
+            this.client.reportOperationError(this.sessionId, error);
+        });
+    }
+    pause() {
+        this.paused = true;
+    }
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        const pending = this.pausedEvents;
+        this.pausedEvents = [];
+        for (const event of pending)
+            this.emitData(event);
+    }
+    onData(listener) {
+        this.dataListeners.add(listener);
+        if (this.undeliveredEvents.length > 0) {
+            const pending = this.undeliveredEvents;
+            this.undeliveredEvents = [];
+            queueMicrotask(() => {
+                if (!this.dataListeners.has(listener))
+                    return;
+                for (const event of pending)
+                    listener(event);
+            });
+        }
+        return { dispose: () => this.dataListeners.delete(listener) };
+    }
+    onExit(listener) {
+        this.exitListeners.add(listener);
+        const pending = this.pendingExit;
+        if (pending) {
+            queueMicrotask(() => {
+                if (this.exitListeners.has(listener))
+                    listener(pending);
+            });
+        }
+        return { dispose: () => this.exitListeners.delete(listener) };
+    }
+    acceptData(event) {
+        if (this.paused) {
+            this.pausedEvents = appendTerminalChunkWindow(this.pausedEvents, event);
+            return;
+        }
+        if (this.dataListeners.size === 0) {
+            this.undeliveredEvents = appendTerminalChunkWindow(this.undeliveredEvents, event);
+            return;
+        }
+        this.emitData(event);
+    }
+    acceptExit(event) {
+        this.pendingExit = event;
+        for (const listener of Array.from(this.exitListeners))
+            listener(event);
+    }
+    emitData(event) {
+        for (const listener of Array.from(this.dataListeners))
+            listener(event);
+    }
+}
+export class TerminalDaemonClient {
+    socketPath;
+    token;
+    persistent = true;
+    socket = null;
+    buffer = "";
+    nextRequestId = 1;
+    pending = new Map();
+    inventory = new Map();
+    handles = new Map();
+    pendingEvents = new Map();
+    constructor(socketPath, token) {
+        this.socketPath = socketPath;
+        this.token = token;
+    }
+    async connect() {
+        if (this.socket && !this.socket.destroyed)
+            return;
+        const socket = net.createConnection(this.socketPath);
+        socket.setNoDelay(true);
+        this.socket = socket;
+        await new Promise((resolve, reject) => {
+            const onConnect = () => { cleanup(); resolve(); };
+            const onError = (error) => { cleanup(); reject(error); };
+            const cleanup = () => {
+                socket.off("connect", onConnect);
+                socket.off("error", onError);
+            };
+            socket.once("connect", onConnect);
+            socket.once("error", onError);
+        });
+        socket.on("data", (data) => this.consume(data.toString("utf8")));
+        socket.on("close", () => this.rejectPending(new Error("Terminal daemon disconnected")));
+        socket.on("error", (error) => this.rejectPending(error));
+        await this.request("hello");
+        const sessions = await this.request("list");
+        this.inventory.clear();
+        for (const session of sessions)
+            this.inventory.set(session.sessionId, session);
+    }
+    attach(sessionId, afterSeq = 0) {
+        const state = this.inventory.get(sessionId);
+        if (!state)
+            return null;
+        return this.resultFromState(state, false, afterSeq);
+    }
+    async createOrAttach(request, afterSeq = 0) {
+        const existing = this.inventory.get(request.sessionId);
+        if (existing)
+            return this.resultFromState(existing, false, afterSeq);
+        const payload = await this.request("createOrAttach", { ...request, afterSeq });
+        this.inventory.set(payload.state.sessionId, payload.state);
+        return this.resultFromState(payload.state, payload.isNew, afterSeq);
+    }
+    forget(sessionId) {
+        this.inventory.delete(sessionId);
+        this.handles.delete(sessionId);
+        this.pendingEvents.delete(sessionId);
+        void this.request("forget", { sessionId }).catch((error) => this.reportOperationError(sessionId, error));
+    }
+    disconnect() {
+        const socket = this.socket;
+        this.socket = null;
+        if (socket && !socket.destroyed)
+            socket.destroy();
+        this.rejectPending(new Error("Terminal daemon client disposed"));
+        this.handles.clear();
+        this.pendingEvents.clear();
+    }
+    async request(method, params) {
+        const socket = this.socket;
+        if (!socket || socket.destroyed || !socket.writable)
+            throw new Error("Terminal daemon is unavailable");
+        const id = this.nextRequestId++;
+        const request = {
+            kind: "request",
+            id,
+            token: this.token,
+            protocolVersion: TERMINAL_DAEMON_PROTOCOL_VERSION,
+            method,
+            params,
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Terminal daemon ${method} timed out`));
+            }, 10_000);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            socket.write(`${JSON.stringify(request)}\n`);
+        });
+    }
+    reportOperationError(sessionId, error) {
+        if (!this.socket || this.socket.destroyed)
+            return;
+        process.stderr.write(`[wand] terminal daemon operation failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    resultFromState(state, isNew, afterSeq) {
+        let process = this.handles.get(state.sessionId) ?? null;
+        if (state.status === "running" && (!process || process.incarnationId !== state.incarnationId)) {
+            process = new RemoteTerminalProcess(state.sessionId, state.incarnationId, state.pid, this);
+            this.handles.set(state.sessionId, process);
+            const pending = this.pendingEvents.get(state.sessionId) ?? [];
+            this.pendingEvents.delete(state.sessionId);
+            for (const event of pending) {
+                const alreadyInSnapshot = event.event === "data"
+                    ? typeof event.seq === "number" && event.seq <= state.seq
+                    : false;
+                if (!alreadyInSnapshot)
+                    this.routeEvent(event);
+            }
+        }
+        if (state.status !== "running")
+            process = null;
+        return {
+            process,
+            state,
+            replay: state.chunks.filter((chunk) => chunk.seq > afterSeq),
+            isNew,
+        };
+    }
+    consume(chunk) {
+        this.buffer += chunk;
+        while (true) {
+            const newline = this.buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = this.buffer.slice(0, newline);
+            this.buffer = this.buffer.slice(newline + 1);
+            if (!line)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (message.kind === "response") {
+                const pending = this.pending.get(message.id);
+                if (!pending)
+                    continue;
+                this.pending.delete(message.id);
+                clearTimeout(pending.timer);
+                if (message.ok)
+                    pending.resolve(message.result);
+                else
+                    pending.reject(new Error(message.error));
+            }
+            else {
+                this.routeEvent(message);
+            }
+        }
+    }
+    routeEvent(event) {
+        const state = this.inventory.get(event.sessionId);
+        if (state && state.incarnationId === event.incarnationId) {
+            if (event.event === "data" && typeof event.data === "string" && typeof event.seq === "number") {
+                state.seq = Math.max(state.seq, event.seq);
+                state.output = appendWindow(state.output, event.data, PTY_OUTPUT_MAX_SIZE);
+                state.chunks = appendTerminalChunkWindow(state.chunks, { data: event.data, seq: event.seq });
+            }
+            else if (event.event === "exit") {
+                state.status = "exited";
+                state.exitCode = event.exitCode ?? -1;
+            }
+        }
+        const handle = this.handles.get(event.sessionId);
+        if (!handle || handle.incarnationId !== event.incarnationId) {
+            const pending = this.pendingEvents.get(event.sessionId) ?? [];
+            pending.push(event);
+            this.pendingEvents.set(event.sessionId, pending.slice(-512));
+            return;
+        }
+        if (event.event === "data" && typeof event.data === "string" && typeof event.seq === "number") {
+            handle.acceptData({ data: event.data, seq: event.seq });
+        }
+        else if (event.event === "exit") {
+            handle.acceptExit({ exitCode: event.exitCode ?? -1, signal: event.signal });
+            this.handles.delete(event.sessionId);
+        }
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}
+export async function createTerminalHost(configPath) {
+    if (process.env.WAND_TEST_MODE === "1" || process.env.NODE_TEST_CONTEXT)
+        return new InProcessTerminalHost();
+    const paths = terminalDaemonPaths(configPath);
+    const endpointExists = process.platform === "win32" || existsSync(paths.socketPath);
+    if (endpointExists) {
+        const adopted = await tryConnect(paths.socketPath, paths.tokenPath);
+        if (adopted)
+            return adopted;
+        if (await probeSocket(paths.socketPath)) {
+            const starting = await waitForTerminalDaemon(paths.socketPath, paths.tokenPath, 5_000);
+            if (starting)
+                return starting;
+            process.stderr.write("[wand] Existing terminal daemon rejected adoption; using non-persistent PTYs without replacing it.\n");
+            return new InProcessTerminalHost();
+        }
+    }
+    // Service managers can start terminald and the web process at nearly the
+    // same time. The daemon writes its pid before opening the socket, so give
+    // that owner time to become ready instead of spawning a competing daemon.
+    if (hasLiveDaemonPid(paths.pidPath)) {
+        const adopted = await waitForTerminalDaemon(paths.socketPath, paths.tokenPath, 5_000);
+        if (adopted)
+            return adopted;
+        process.stderr.write("[wand] Terminal daemon process is alive but its socket is unavailable; using non-persistent PTYs without replacing it.\n");
+        return new InProcessTerminalHost();
+    }
+    try {
+        startDetachedDaemon(configPath);
+        const client = await waitForTerminalDaemon(paths.socketPath, paths.tokenPath, 5_000);
+        if (client)
+            return client;
+    }
+    catch (error) {
+        process.stderr.write(`[wand] Failed to start terminal daemon: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.stderr.write("[wand] Terminal daemon unavailable; falling back to in-process PTYs.\n");
+    return new InProcessTerminalHost();
+}
+async function waitForTerminalDaemon(socketPath, tokenPath, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const client = await tryConnect(socketPath, tokenPath);
+        if (client)
+            return client;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return null;
+}
+function hasLiveDaemonPid(pidPath) {
+    let pid;
+    try {
+        pid = Number(readFileSync(pidPath, "utf8").trim());
+    }
+    catch {
+        return false;
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function tryConnect(socketPath, tokenPath) {
+    let token;
+    try {
+        token = readFileSync(tokenPath, "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+    if (!token)
+        return null;
+    const client = new TerminalDaemonClient(socketPath, token);
+    try {
+        await client.connect();
+        return client;
+    }
+    catch {
+        client.disconnect();
+        return null;
+    }
+}
+/** Connect to an already-running terminal daemon without starting a replacement. */
+export async function connectExistingTerminalHost(configPath) {
+    const paths = terminalDaemonPaths(configPath);
+    return tryConnect(paths.socketPath, paths.tokenPath);
+}
+function probeSocket(socketPath) {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const finish = (alive) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(alive);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        const timer = setTimeout(() => finish(false), 300);
+        timer.unref?.();
+    });
+}
+function startDetachedDaemon(configPath) {
+    const entry = process.argv[1];
+    if (!entry || !existsSync(entry))
+        throw new Error("Cannot resolve Wand CLI entrypoint");
+    const runtimeArgs = entry.endsWith(".ts") ? process.execArgv : [];
+    const child = spawn(process.execPath, [...runtimeArgs, entry, "terminald", "-c", configPath], {
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        env: process.env,
+    });
+    child.unref();
+}

package/dist/terminal-daemon-protocol.d.ts

@@ -0,0 +1,45 @@
+import type { TerminalSessionState, TerminalSpawnRequest } from "./terminal-host.js";
+export declare const TERMINAL_DAEMON_PROTOCOL_VERSION = 1;
+export interface TerminalDaemonPaths {
+    socketPath: string;
+    tokenPath: string;
+    pidPath: string;
+}
+export type TerminalDaemonRequest = {
+    kind: "request";
+    id: number;
+    token: string;
+    protocolVersion: number;
+    method: "hello" | "list" | "createOrAttach" | "write" | "resize" | "kill" | "forget";
+    params?: Record<string, unknown>;
+};
+export type TerminalDaemonResponse = {
+    kind: "response";
+    id: number;
+    ok: true;
+    result?: unknown;
+} | {
+    kind: "response";
+    id: number;
+    ok: false;
+    error: string;
+};
+export type TerminalDaemonEvent = {
+    kind: "event";
+    event: "data" | "exit";
+    sessionId: string;
+    incarnationId: string;
+    data?: string;
+    seq?: number;
+    exitCode?: number;
+    signal?: number;
+};
+export interface TerminalDaemonCreateParams extends TerminalSpawnRequest {
+    afterSeq?: number;
+}
+export interface TerminalDaemonAttachPayload {
+    state: TerminalSessionState;
+    isNew: boolean;
+}
+export declare function terminalDaemonPaths(configPath: string): TerminalDaemonPaths;
+export declare function terminalDaemonRuntimeLabel(configPath: string): string;

package/dist/terminal-daemon-protocol.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+export const TERMINAL_DAEMON_PROTOCOL_VERSION = 1;
+export function terminalDaemonPaths(configPath) {
+    const resolved = path.resolve(configPath);
+    const suffix = createHash("sha256").update(resolved).digest("hex").slice(0, 12);
+    const dir = path.dirname(resolved);
+    const uid = (() => {
+        try {
+            return os.userInfo().uid;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    return {
+        socketPath: process.platform === "win32"
+            ? `\\\\.\\pipe\\wand-terminald-${suffix}`
+            // Unix-domain socket paths are limited to roughly 100 bytes on macOS.
+            // Keep the endpoint short even when the config lives in a deep directory;
+            // the per-config secret remains alongside the config with mode 0600.
+            : path.join("/tmp", `wand-terminald-${uid}-${suffix}.sock`),
+        tokenPath: path.join(dir, `.terminald-${suffix}.token`),
+        pidPath: path.join(dir, `.terminald-${suffix}.pid`),
+    };
+}
+export function terminalDaemonRuntimeLabel(configPath) {
+    const suffix = createHash("sha256").update(path.resolve(configPath)).digest("hex").slice(0, 8);
+    return `wand-terminald-${os.userInfo().uid}-${suffix}`;
+}

package/dist/terminal-daemon-server.d.ts

@@ -0,0 +1,2 @@
+export declare function runTerminalDaemon(configPath: string): Promise<void>;
+export declare function readTerminalDaemonPid(configPath: string): number | null;