tmux-ide 2.1.4 → 2.6.0

package/packages/daemon/dist/server/pty-bridge.js

@@ -0,0 +1,422 @@
+import { EventEmitter } from "node:events";
+import * as fs from "node:fs";
+import { defaultNodePtyAdapter, NodePtyAdapter } from "../terminal/NodePtyAdapter.js";
+const DEFAULT_RING_BUFFER_BYTES = 256 * 1024;
+/**
+ * Typed error thrown when a requested terminal cwd cannot be used to
+ * spawn a PTY. Carries the offending cwd and a discriminator so the
+ * WebSocket layer can surface a structured error frame to the client.
+ */
+export class TerminalCwdError extends Error {
+    cwd;
+    reason;
+    constructor(args) {
+        const message = TerminalCwdError.formatMessage(args.cwd, args.reason);
+        super(message, args.cause !== undefined ? { cause: args.cause } : undefined);
+        this.name = "TerminalCwdError";
+        this.cwd = args.cwd;
+        this.reason = args.reason;
+    }
+    static formatMessage(cwd, reason) {
+        switch (reason) {
+            case "notFound":
+                return `cwd does not exist: ${cwd}`;
+            case "notDirectory":
+                return `cwd is not a directory: ${cwd}`;
+            case "statFailed":
+                return `cwd stat failed: ${cwd}`;
+        }
+    }
+}
+/**
+ * Typed error thrown when caller-supplied PTY input is structurally
+ * invalid (e.g. empty cwd for the project default terminal). Distinct
+ * from {@link TerminalCwdError} which describes filesystem state.
+ */
+export class TerminalSpawnInputError extends Error {
+    field;
+    constructor(args) {
+        super(args.message);
+        this.name = "TerminalSpawnInputError";
+        this.field = args.field;
+    }
+}
+/**
+ * Validate that the supplied cwd exists and is a directory. Throws a
+ * {@link TerminalCwdError} with a typed reason on any failure so the
+ * caller can surface a structured error frame instead of leaking
+ * stringly-typed errno checks.
+ */
+export function assertValidCwd(cwd, statCwd = fs.statSync) {
+    let stats;
+    try {
+        stats = statCwd(cwd);
+    }
+    catch (err) {
+        const errno = err?.code;
+        if (errno === "ENOENT") {
+            throw new TerminalCwdError({ cwd, reason: "notFound", cause: err });
+        }
+        throw new TerminalCwdError({ cwd, reason: "statFailed", cause: err });
+    }
+    if (!stats.isDirectory()) {
+        throw new TerminalCwdError({ cwd, reason: "notDirectory" });
+    }
+}
+export function cleanEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return env;
+}
+function outputToBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    if (ArrayBuffer.isView(data)) {
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    }
+    return Buffer.from(String(data), "utf8");
+}
+function assertPositiveDimension(name, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+}
+function readPositiveIntEnv(name, fallback) {
+    const parsed = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+export class PtyBridge extends EventEmitter {
+    ptyProcess = null;
+    dataDispose = null;
+    exitDispose = null;
+    exitPoll = null;
+    outputTimer = null;
+    outputChunks = [];
+    pausedOutputChunks = [];
+    outputPaused = false;
+    replayChunks = [];
+    replayBytes = 0;
+    lastCwd = null;
+    options;
+    adapter;
+    ringBufferBytes;
+    statCwd;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        // Resolution order (per T087):
+        //   1. explicit `ptyAdapter` (preferred — pass a MockPtyAdapter in tests)
+        //   2. legacy `options.pty?.spawn` (wraps the hand-rolled stub in a
+        //      NodePtyAdapter so pre-T087 tests still work)
+        //   3. defaultNodePtyAdapter — the production singleton.
+        if (options.ptyAdapter) {
+            this.adapter = options.ptyAdapter;
+        }
+        else if (options.pty?.spawn) {
+            this.adapter = new NodePtyAdapter({
+                spawnPty: options.pty.spawn,
+                statCwd: options.statCwd,
+                skipHelperEnsure: true,
+            });
+        }
+        else {
+            this.adapter = defaultNodePtyAdapter;
+        }
+        this.ringBufferBytes =
+            options.ringBufferBytes ??
+                readPositiveIntEnv("TMUX_IDE_PTY_RING_BUFFER_BYTES", DEFAULT_RING_BUFFER_BYTES);
+        this.statCwd = options.statCwd ?? fs.statSync;
+    }
+    /**
+     * Returns the cwd used by the most recent spawn (or restart). `null`
+     * if the bridge has never been spawned. Used by ws-route to detect
+     * stale-cwd reuse and trigger a respawn.
+     */
+    getCwd() {
+        return this.lastCwd;
+    }
+    get pid() {
+        return this.ptyProcess?.pid ?? null;
+    }
+    // `cols`/`rows` aren't on the canonical PtyProcess shape — we mirror the
+    // most recent value the bridge handed to the adapter so external readers
+    // (status views) can still see the size without rummaging in the child.
+    lastCols = null;
+    lastRows = null;
+    get cols() {
+        return this.lastCols;
+    }
+    get rows() {
+        return this.lastRows;
+    }
+    get running() {
+        return this.ptyProcess !== null;
+    }
+    getReplayBuffer() {
+        return Buffer.concat(this.replayChunks, this.replayBytes);
+    }
+    flushReplayBuffer() {
+        this.replayChunks = [];
+        this.replayBytes = 0;
+    }
+    spawn(cols, rows, spawnOptions = {}) {
+        if (this.running) {
+            throw new Error("PTY already spawned");
+        }
+        assertPositiveDimension("cols", cols);
+        assertPositiveDimension("rows", rows);
+        // When the client doesn't specify cmd, fall back to the user's actual
+        // login shell from $SHELL so .zshrc / .zprofile / etc. load. Defaulting
+        // to "bash" silently downgrades zsh users to a non-zsh experience.
+        const defaultShell = this.options.shell ?? process.env.SHELL ?? "bash";
+        let executable = spawnOptions.cmd?.[0] ?? defaultShell;
+        let args = spawnOptions.cmd ? spawnOptions.cmd.slice(1) : (this.options.args ?? ["-l"]);
+        // `__login_shell__` sentinel: wrap the rest of cmd in `$SHELL -l -c
+        // "exec <cmd...>"`. The user's login shell sources profile/rc files
+        // (PATH, nvm, brew, …) before exec'ing the requested command, so the
+        // spawned program inherits the fully-loaded env. Used by the dashboard
+        // to give tmux-ide the user's real shell environment.
+        if (executable === "__login_shell__" && args.length > 0) {
+            const innerCmd = args.map((part) => `'${part.replace(/'/g, "'\\''")}'`).join(" ");
+            executable = defaultShell;
+            args = ["-l", "-c", `exec ${innerCmd}`];
+        }
+        const cwd = spawnOptions.cwd ?? this.options.cwd ?? process.env.HOME ?? "/";
+        assertValidCwd(cwd, this.statCwd);
+        const env = this.options.env ?? cleanEnv();
+        const spawnInput = {
+            shell: executable,
+            args,
+            cwd,
+            cols,
+            rows,
+            env: env,
+            name: this.options.name ?? "xterm-256color",
+            encoding: null,
+        };
+        let child;
+        try {
+            child = this.adapter.spawnSync(spawnInput);
+        }
+        catch (err) {
+            if (err.code === "ENOENT" && executable === "tmux-ide") {
+                throw new Error("tmux-ide not found in PATH", { cause: err });
+            }
+            throw err;
+        }
+        this.ptyProcess = child;
+        this.lastCwd = cwd;
+        this.lastCols = cols;
+        this.lastRows = rows;
+        this.exitDispose = child.onExit(({ exitCode, signal }) => {
+            this.emitExit({ code: exitCode, signal: signal ?? null });
+        });
+        this.dataDispose = child.onData((data) => {
+            this.enqueueOutput(outputToBuffer(data));
+        });
+        this.startExitPoll(child);
+    }
+    /**
+     * Stop the currently-running PTY process synchronously. Drops listeners
+     * and clears replay so a follow-up spawn starts from a clean slate.
+     * Idempotent — no-op when no process is running.
+     *
+     * Used by {@link restartWith} to swap out a sticky bridge whose cwd no
+     * longer matches the client request.
+     */
+    stopProcess(signal = "SIGTERM") {
+        if (!this.ptyProcess)
+            return;
+        const child = this.ptyProcess;
+        // Drop listeners first so the impending kill does not re-emit `exit`
+        // to the WS client (which would close the socket mid-restart).
+        this.disposeListeners();
+        this.ptyProcess = null;
+        this.lastCwd = null;
+        this.flushReplayBuffer();
+        try {
+            child.kill(signal);
+        }
+        catch {
+            // Process may have already exited between the running check and
+            // the kill syscall.
+        }
+    }
+    /**
+     * Stop the running process (if any) and spawn a new one with the
+     * supplied options. Preserves bridge identity (id, registry slot) but
+     * resets the replay buffer — the prior process is gone, there is no
+     * meaningful output to replay. Used when a reconnect requests a new
+     * cwd; modeled on t3code's `stopProcess + spawn` pattern.
+     */
+    restartWith(cols, rows, spawnOptions = {}) {
+        this.stopProcess("SIGTERM");
+        this.spawn(cols, rows, spawnOptions);
+    }
+    pause() {
+        this.outputPaused = true;
+    }
+    resume() {
+        if (!this.outputPaused)
+            return;
+        this.flushCoalescedOutput();
+        this.outputPaused = false;
+        this.flushPausedOutput();
+    }
+    write(bytes) {
+        if (!this.ptyProcess) {
+            throw new Error("PTY is not running");
+        }
+        this.ptyProcess.write(typeof bytes === "string" ? bytes : Buffer.from(bytes));
+    }
+    resize(cols, rows) {
+        assertPositiveDimension("cols", cols);
+        assertPositiveDimension("rows", rows);
+        if (!this.ptyProcess) {
+            throw new Error("PTY is not running");
+        }
+        this.ptyProcess.resize(cols, rows);
+        this.lastCols = cols;
+        this.lastRows = rows;
+    }
+    kill(signal = "SIGTERM") {
+        if (!this.ptyProcess)
+            return;
+        try {
+            this.ptyProcess.kill(signal);
+        }
+        catch {
+            // The process may already have exited between the running check and kill.
+        }
+    }
+    dispose() {
+        this.disposeListeners();
+        this.kill("SIGTERM");
+        this.flushReplayBuffer();
+    }
+    disposeListeners() {
+        this.flushAllOutput();
+        this.dataDispose?.();
+        this.exitDispose?.();
+        if (this.exitPoll) {
+            clearInterval(this.exitPoll);
+            this.exitPoll = null;
+        }
+        this.dataDispose = null;
+        this.exitDispose = null;
+    }
+    enqueueOutput(bytes) {
+        if (bytes.byteLength === 0)
+            return;
+        const coalesceMs = this.options.coalesceMs ?? 8;
+        if (coalesceMs <= 0) {
+            this.deliverOutput(bytes);
+            return;
+        }
+        this.outputChunks.push(bytes);
+        if (this.outputTimer)
+            return;
+        this.outputTimer = setTimeout(() => {
+            this.outputTimer = null;
+            this.flushCoalescedOutput();
+        }, coalesceMs);
+        this.outputTimer.unref?.();
+    }
+    flushCoalescedOutput() {
+        if (this.outputTimer) {
+            clearTimeout(this.outputTimer);
+            this.outputTimer = null;
+        }
+        if (this.outputChunks.length === 0)
+            return;
+        const chunks = this.outputChunks;
+        this.outputChunks = [];
+        this.deliverOutput(Buffer.concat(chunks));
+    }
+    deliverOutput(bytes) {
+        this.appendReplay(bytes);
+        if (this.outputPaused) {
+            this.pausedOutputChunks.push(bytes);
+            return;
+        }
+        this.emit("output", bytes);
+    }
+    flushPausedOutput() {
+        if (this.pausedOutputChunks.length === 0)
+            return;
+        const chunks = this.pausedOutputChunks;
+        this.pausedOutputChunks = [];
+        this.emit("output", Buffer.concat(chunks));
+    }
+    flushAllOutput() {
+        if (this.outputTimer) {
+            clearTimeout(this.outputTimer);
+            this.outputTimer = null;
+        }
+        if (this.outputChunks.length > 0)
+            this.appendReplay(Buffer.concat(this.outputChunks));
+        const chunks = [...this.pausedOutputChunks, ...this.outputChunks];
+        this.pausedOutputChunks = [];
+        this.outputChunks = [];
+        if (chunks.length > 0) {
+            const bytes = Buffer.concat(chunks);
+            this.emit("output", bytes);
+        }
+    }
+    appendReplay(bytes) {
+        if (this.ringBufferBytes <= 0 || bytes.byteLength === 0)
+            return;
+        if (bytes.byteLength >= this.ringBufferBytes) {
+            const tail = bytes.subarray(bytes.byteLength - this.ringBufferBytes);
+            this.replayChunks = [Buffer.from(tail)];
+            this.replayBytes = tail.byteLength;
+            return;
+        }
+        this.replayChunks.push(Buffer.from(bytes));
+        this.replayBytes += bytes.byteLength;
+        while (this.replayBytes > this.ringBufferBytes && this.replayChunks.length > 0) {
+            const first = this.replayChunks[0];
+            const overflow = this.replayBytes - this.ringBufferBytes;
+            if (first.byteLength <= overflow) {
+                this.replayChunks.shift();
+                this.replayBytes -= first.byteLength;
+            }
+            else {
+                this.replayChunks[0] = first.subarray(overflow);
+                this.replayBytes -= overflow;
+            }
+        }
+    }
+    startExitPoll(child) {
+        this.exitPoll = setInterval(() => {
+            if (this.ptyProcess !== child) {
+                this.disposeListeners();
+                return;
+            }
+            try {
+                process.kill(child.pid, 0);
+            }
+            catch (err) {
+                if (err.code === "ESRCH") {
+                    this.emitExit({ code: 0, signal: null });
+                }
+            }
+        }, 100);
+        this.exitPoll.unref?.();
+    }
+    emitExit(exit) {
+        if (!this.ptyProcess)
+            return;
+        this.flushAllOutput();
+        this.disposeListeners();
+        this.ptyProcess = null;
+        this.lastCwd = null;
+        this.flushReplayBuffer();
+        this.emit("exit", exit);
+    }
+}

package/packages/daemon/dist/server/standalone.d.ts

@@ -0,0 +1 @@
+export {};

package/packages/daemon/dist/server/standalone.js

@@ -0,0 +1,14 @@
+import { parseArgs } from "node:util";
+import { start } from "./index.js";
+const { values } = parseArgs({
+    options: {
+        port: { type: "string" },
+    },
+});
+const running = await start(values.port ? Number.parseInt(values.port, 10) : undefined);
+const shutdown = async () => {
+    await running.close();
+    process.exit(0);
+};
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());

package/packages/daemon/dist/server/ws-route.d.ts

@@ -0,0 +1,74 @@
+import type { RawData, WebSocket } from "ws";
+import { type PtyExit, type PtySpawnOptions } from "./pty-bridge.ts";
+export interface PtyBridgeLike {
+    spawn(cols: number, rows: number, options?: PtySpawnOptions): void;
+    restartWith?(cols: number, rows: number, options?: PtySpawnOptions): void;
+    getCwd?(): string | null;
+    readonly running?: boolean;
+    getReplayBuffer?(): Buffer;
+    flushReplayBuffer?(): void;
+    write(bytes: Buffer): void;
+    resize(cols: number, rows: number): void;
+    pause(): void;
+    resume(): void;
+    kill(signal?: NodeJS.Signals): void;
+    on(event: "output", listener: (bytes: Buffer) => void): this;
+    on(event: "exit", listener: (exit: PtyExit) => void): this;
+    off(event: "output", listener: (bytes: Buffer) => void): this;
+    off(event: "exit", listener: (exit: PtyExit) => void): this;
+}
+/**
+ * Wire reason codes for terminal-cwd errors. Mirrors the bridge's
+ * {@link TerminalCwdErrorReason} discriminator into the kebab-case the
+ * WS protocol speaks. Adding a new reason is a single-line change in
+ * both directions.
+ */
+export type CwdErrorWireReason = "cwd-not-found" | "cwd-not-directory" | "cwd-stat-failed";
+interface WsLike {
+    readyState: number;
+    bufferedAmount?: number;
+    send(data: string | Buffer, options?: {
+        binary?: boolean;
+    }): void;
+    close(code?: number, reason?: string): void;
+    on(event: "message", listener: (data: RawData | string, isBinary: boolean) => void): this;
+    on(event: "close", listener: () => void): this;
+    on(event: "error", listener: () => void): this;
+}
+export interface PtyWebSocketOptions {
+    createBridge?: (id: string) => PtyBridgeLike;
+    registry?: PtyBridgeRegistry;
+    idleMs?: number;
+}
+export interface PtyWebSocketConnection {
+    getBridge(): PtyBridgeLike | null;
+}
+export declare class PtyBridgeRegistry {
+    private entries;
+    acquire(id: string, createBridge: (id: string) => PtyBridgeLike, options?: {
+        idleMs?: number;
+    }): {
+        bridge: PtyBridgeLike;
+        reused: boolean;
+        release: () => void;
+    };
+    /**
+     * Look up a bridge by id without acquiring it. Returns `null` when no
+     * bridge is registered for the id. Used by server-side action handlers
+     * (terminal.respawn, terminal.stop) that need to operate on an existing
+     * bridge — they should not bump the client refcount.
+     */
+    peek(id: string): PtyBridgeLike | null;
+    /**
+     * Drop the bridge for `id`, killing it synchronously. Used by the
+     * terminal.stop action handler to release a sticky bridge whose owner
+     * has explicitly asked to terminate it.
+     */
+    delete(id: string): boolean;
+    shutdown(): void;
+    size(): number;
+}
+export declare const defaultPtyBridgeRegistry: PtyBridgeRegistry;
+export declare function shutdownPtyBridges(): void;
+export declare function handlePtyWebSocket(ws: WebSocket | WsLike, id: string, options?: PtyWebSocketOptions): PtyWebSocketConnection;
+export {};