tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/server/ws-route.ts

@@ -0,0 +1,483 @@
+import type { RawData, WebSocket } from "ws";
+import {
+  PtyBridge,
+  TerminalCwdError,
+  type PtyExit,
+  type PtySpawnOptions,
+  type TerminalCwdErrorReason,
+} from "./pty-bridge.ts";
+
+const WS_OPEN = 1;
+const DEFAULT_BACKPRESSURE_BYTES = 1 << 20;
+const DRAIN_POLL_MS = 16;
+const DEFAULT_BRIDGE_IDLE_MS = 300000;
+
+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";
+
+const CWD_ERROR_WIRE_REASON: Record<TerminalCwdErrorReason, CwdErrorWireReason> = {
+  notFound: "cwd-not-found",
+  notDirectory: "cwd-not-directory",
+  statFailed: "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;
+}
+
+interface InitFrame {
+  type: "init";
+  cols: number;
+  rows: number;
+  cwd?: string;
+  cmd?: string[];
+}
+
+interface ResizeFrame {
+  type: "resize";
+  cols: number;
+  rows: number;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return Number.isInteger(value) && Number(value) > 0;
+}
+
+function rawDataToBuffer(data: RawData | string): Buffer {
+  if (typeof data === "string") return Buffer.from(data, "utf8");
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  if (Array.isArray(data)) return Buffer.concat(data);
+  return Buffer.from(data);
+}
+
+function rawDataToText(data: RawData | string): string {
+  return typeof data === "string" ? data : rawDataToBuffer(data).toString("utf8");
+}
+
+function isJsonControlFrame(data: RawData | string, isBinary: boolean): boolean {
+  return !isBinary && rawDataToText(data).startsWith("{");
+}
+
+function parseJsonObject(data: RawData | string): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(rawDataToText(data));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("control frame must be a JSON object");
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function parseInitFrame(data: RawData | string): InitFrame {
+  const frame = parseJsonObject(data);
+  if (frame.type !== "init") {
+    throw new Error("first frame must be init");
+  }
+  if (!isPositiveInteger(frame.cols) || !isPositiveInteger(frame.rows)) {
+    throw new Error("init requires positive integer cols and rows");
+  }
+  if (frame.cwd !== undefined && typeof frame.cwd !== "string") {
+    throw new Error("init cwd must be a string");
+  }
+  if (
+    frame.cmd !== undefined &&
+    (!Array.isArray(frame.cmd) ||
+      frame.cmd.length === 0 ||
+      !frame.cmd.every((part) => typeof part === "string"))
+  ) {
+    throw new Error("init cmd must be a non-empty string array");
+  }
+  return {
+    type: "init",
+    cols: frame.cols,
+    rows: frame.rows,
+    ...(frame.cwd !== undefined ? { cwd: frame.cwd } : {}),
+    ...(frame.cmd !== undefined ? { cmd: frame.cmd } : {}),
+  };
+}
+
+function parseResizeFrame(data: RawData | string): ResizeFrame {
+  const frame = parseJsonObject(data);
+  if (frame.type !== "resize") {
+    throw new Error(`unsupported control frame: ${String(frame.type)}`);
+  }
+  if (!isPositiveInteger(frame.cols) || !isPositiveInteger(frame.rows)) {
+    throw new Error("resize requires positive integer cols and rows");
+  }
+  return { type: "resize", cols: frame.cols, rows: frame.rows };
+}
+
+interface ErrorFrameExtras {
+  reason?: CwdErrorWireReason;
+  cwd?: string;
+}
+
+function sendError(ws: WsLike, message: string, extras?: ErrorFrameExtras): void {
+  if (ws.readyState !== WS_OPEN) return;
+  const frame: Record<string, unknown> = { type: "error", message };
+  if (extras?.reason !== undefined) frame.reason = extras.reason;
+  if (extras?.cwd !== undefined) frame.cwd = extras.cwd;
+  ws.send(JSON.stringify(frame));
+}
+
+function sendCwdError(ws: WsLike, err: TerminalCwdError): void {
+  sendError(ws, err.message, {
+    reason: CWD_ERROR_WIRE_REASON[err.reason],
+    cwd: err.cwd,
+  });
+}
+
+function closeWs(ws: WsLike): void {
+  if (ws.readyState === WS_OPEN) {
+    ws.close();
+  }
+}
+
+function backpressureBytes(): number {
+  const parsed = Number.parseInt(process.env.TMUX_IDE_PTY_BACKPRESSURE_BYTES ?? "", 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_BACKPRESSURE_BYTES;
+}
+
+function bridgeIdleMs(options?: { idleMs?: number }): number {
+  if (options?.idleMs !== undefined) return options.idleMs;
+  const parsed = Number.parseInt(process.env.TMUX_IDE_BRIDGE_IDLE_MS ?? "", 10);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_BRIDGE_IDLE_MS;
+}
+
+interface BridgeEntry {
+  bridge: PtyBridgeLike;
+  clients: number;
+  idleTimer: ReturnType<typeof setTimeout> | null;
+}
+
+export class PtyBridgeRegistry {
+  private entries = new Map<string, BridgeEntry>();
+
+  acquire(
+    id: string,
+    createBridge: (id: string) => PtyBridgeLike,
+    options: { idleMs?: number } = {},
+  ): { bridge: PtyBridgeLike; reused: boolean; release: () => void } {
+    let entry = this.entries.get(id);
+    const reused = !!entry && entry.bridge.running !== false;
+    if (!entry || entry.bridge.running === false) {
+      entry = { bridge: createBridge(id), clients: 0, idleTimer: null };
+      this.entries.set(id, entry);
+      entry.bridge.on("exit", () => {
+        this.entries.delete(id);
+      });
+    }
+
+    if (entry.idleTimer) {
+      clearTimeout(entry.idleTimer);
+      entry.idleTimer = null;
+    }
+    entry.clients++;
+
+    let released = false;
+    const release = () => {
+      if (released) return;
+      released = true;
+      const current = this.entries.get(id);
+      if (!current) return;
+      current.clients = Math.max(0, current.clients - 1);
+      if (current.clients > 0 || current.bridge.running === false) return;
+      const idleMs = bridgeIdleMs(options);
+      current.idleTimer = setTimeout(() => {
+        const latest = this.entries.get(id);
+        if (!latest || latest.clients > 0) return;
+        latest.bridge.kill("SIGTERM");
+        this.entries.delete(id);
+      }, idleMs);
+      current.idleTimer.unref?.();
+    };
+
+    return { bridge: entry.bridge, reused, release };
+  }
+
+  /**
+   * 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 {
+    const entry = this.entries.get(id);
+    if (!entry) return null;
+    if (entry.bridge.running === false) return null;
+    return entry.bridge;
+  }
+
+  /**
+   * 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 {
+    const entry = this.entries.get(id);
+    if (!entry) return false;
+    if (entry.idleTimer) {
+      clearTimeout(entry.idleTimer);
+      entry.idleTimer = null;
+    }
+    try {
+      entry.bridge.kill("SIGTERM");
+    } catch {
+      // Best-effort — the process may already have exited.
+    }
+    this.entries.delete(id);
+    return true;
+  }
+
+  shutdown(): void {
+    for (const entry of this.entries.values()) {
+      if (entry.idleTimer) clearTimeout(entry.idleTimer);
+      entry.bridge.kill("SIGTERM");
+    }
+    this.entries.clear();
+  }
+
+  size(): number {
+    return this.entries.size;
+  }
+}
+
+export const defaultPtyBridgeRegistry = new PtyBridgeRegistry();
+
+export function shutdownPtyBridges(): void {
+  defaultPtyBridgeRegistry.shutdown();
+}
+
+export function handlePtyWebSocket(
+  ws: WebSocket | WsLike,
+  id: string,
+  options: PtyWebSocketOptions = {},
+): PtyWebSocketConnection {
+  const socket = ws as WsLike;
+  let bridge: PtyBridgeLike | null = null;
+  let initialized = false;
+  let ptyExited = false;
+  let killTimer: ReturnType<typeof setTimeout> | null = null;
+  let drainTimer: ReturnType<typeof setTimeout> | null = null;
+  let releaseBridge: (() => void) | null = null;
+  let outputListener: ((bytes: Buffer) => void) | null = null;
+  let exitListener: ((exit: PtyExit) => void) | null = null;
+  const backpressureThreshold = backpressureBytes();
+  const resumeThreshold = Math.floor(backpressureThreshold / 2);
+
+  const clearKillTimer = () => {
+    if (!killTimer) return;
+    clearTimeout(killTimer);
+    killTimer = null;
+  };
+
+  const clearDrainTimer = () => {
+    if (!drainTimer) return;
+    clearTimeout(drainTimer);
+    drainTimer = null;
+  };
+
+  const scheduleDrainCheck = () => {
+    if (drainTimer || !bridge) return;
+    drainTimer = setTimeout(() => {
+      drainTimer = null;
+      if (!bridge || socket.readyState !== WS_OPEN) return;
+      if ((socket.bufferedAmount ?? 0) <= resumeThreshold) {
+        bridge.resume();
+        return;
+      }
+      scheduleDrainCheck();
+    }, DRAIN_POLL_MS);
+    drainTimer.unref?.();
+  };
+
+  const maybePauseForBackpressure = () => {
+    if (!bridge || (socket.bufferedAmount ?? 0) <= backpressureThreshold) return;
+    bridge.pause();
+    scheduleDrainCheck();
+  };
+
+  const closeWithError = (message: string) => {
+    sendError(socket, message);
+    closeWs(socket);
+  };
+
+  const closeWithCwdError = (err: TerminalCwdError) => {
+    sendCwdError(socket, err);
+    closeWs(socket);
+  };
+
+  const attachBridgeEvents = (ptyBridge: PtyBridgeLike) => {
+    outputListener = (bytes) => {
+      if (socket.readyState === WS_OPEN) {
+        maybePauseForBackpressure();
+        socket.send(bytes, { binary: true });
+        maybePauseForBackpressure();
+      }
+    };
+
+    exitListener = (exit) => {
+      ptyExited = true;
+      clearKillTimer();
+      clearDrainTimer();
+      if (socket.readyState === WS_OPEN) {
+        socket.send(JSON.stringify({ type: "exit", code: exit.code, signal: exit.signal }));
+        socket.close();
+      }
+    };
+
+    ptyBridge.on("output", outputListener);
+    ptyBridge.on("exit", exitListener);
+  };
+
+  const detachBridgeEvents = () => {
+    if (bridge && outputListener) bridge.off("output", outputListener);
+    if (bridge && exitListener) bridge.off("exit", exitListener);
+    outputListener = null;
+    exitListener = null;
+  };
+
+  socket.on("message", (data, isBinary) => {
+    if (!initialized) {
+      if (!isJsonControlFrame(data, isBinary)) {
+        closeWithError("init frame required before input");
+        return;
+      }
+
+      let init: InitFrame;
+      try {
+        init = parseInitFrame(data);
+      } catch (err) {
+        closeWithError(err instanceof Error ? err.message : String(err));
+        return;
+      }
+
+      const registry = options.registry ?? defaultPtyBridgeRegistry;
+      const acquired = registry.acquire(
+        id,
+        options.createBridge ?? ((bridgeId) => new PtyBridge({ id: bridgeId })),
+        {
+          idleMs: options.idleMs,
+        },
+      );
+      bridge = acquired.bridge;
+      releaseBridge = acquired.release;
+      attachBridgeEvents(bridge);
+
+      try {
+        const spawnOptions: PtySpawnOptions = {};
+        if (init.cwd !== undefined) spawnOptions.cwd = init.cwd;
+        if (init.cmd !== undefined) spawnOptions.cmd = init.cmd;
+
+        const currentCwd = bridge.getCwd?.() ?? null;
+        const cwdChanged = init.cwd !== undefined && currentCwd !== null && currentCwd !== init.cwd;
+
+        if (!acquired.reused) {
+          bridge.spawn(init.cols, init.rows, spawnOptions);
+        } else if (cwdChanged && bridge.restartWith) {
+          // Sticky-bridge cwd mismatch: stop the running shell and
+          // respawn in the new cwd. Replay is meaningless since the
+          // prior process is gone — emit an empty replay-end so the
+          // client's reconnect bookkeeping stays consistent.
+          bridge.restartWith(init.cols, init.rows, spawnOptions);
+          if (socket.readyState === WS_OPEN) {
+            socket.send(JSON.stringify({ type: "replay-end", bytes: 0 }));
+          }
+        } else {
+          try {
+            bridge.resize(init.cols, init.rows);
+          } catch {
+            // Reconnect replay is still useful if the PTY is exiting between
+            // the registry running check and the resize request.
+          }
+          const replay = bridge.getReplayBuffer?.() ?? Buffer.alloc(0);
+          if (replay.byteLength > 0 && socket.readyState === WS_OPEN) {
+            socket.send(replay, { binary: true });
+          }
+          if (socket.readyState === WS_OPEN) {
+            socket.send(JSON.stringify({ type: "replay-end", bytes: replay.byteLength }));
+          }
+        }
+        initialized = true;
+      } catch (err) {
+        detachBridgeEvents();
+        releaseBridge?.();
+        if (err instanceof TerminalCwdError) {
+          closeWithCwdError(err);
+        } else {
+          closeWithError(`spawn failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+      return;
+    }
+
+    if (isJsonControlFrame(data, isBinary)) {
+      try {
+        const resize = parseResizeFrame(data);
+        bridge?.resize(resize.cols, resize.rows);
+      } catch (err) {
+        closeWithError(err instanceof Error ? err.message : String(err));
+      }
+      return;
+    }
+
+    try {
+      bridge?.write(rawDataToBuffer(data));
+    } catch (err) {
+      closeWithError(err instanceof Error ? err.message : String(err));
+    }
+  });
+
+  socket.on("close", () => {
+    clearDrainTimer();
+    detachBridgeEvents();
+    if (!bridge || ptyExited) return;
+    releaseBridge?.();
+  });
+
+  socket.on("error", () => {
+    closeWs(socket);
+  });
+
+  return {
+    getBridge: () => bridge,
+  };
+}

package/packages/daemon/src/status.ts

@@ -0,0 +1,59 @@
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { getSessionName } from "./lib/yaml-io.ts";
+import { getSessionState, isProcessAlive, listPanes } from "@tmux-ide/tmux-bridge";
+import { isCanonicalDaemonAlive, readCanonicalDaemonInfo } from "./lib/canonical-daemon.ts";
+
+export async function status(
+  targetDir: string | undefined,
+  { json }: { json?: boolean } = {},
+): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+  const { name: session } = getSessionName(dir);
+  const configExists = existsSync(resolve(dir, "ide.yml"));
+
+  const state = getSessionState(session);
+  const running = state.running;
+  let panes: ReturnType<typeof listPanes> = [];
+
+  if (running) panes = listPanes(session);
+
+  const daemonInfo = readCanonicalDaemonInfo();
+  const healthy = daemonInfo ? await isCanonicalDaemonAlive(daemonInfo) : false;
+
+  const data = {
+    session,
+    running,
+    configExists,
+    panes,
+    daemon: {
+      pid: daemonInfo?.pid ?? null,
+      alive: daemonInfo ? isProcessAlive(daemonInfo.pid) : false,
+      port: daemonInfo?.port ?? null,
+      healthy,
+    },
+  };
+
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  console.log(`Session: ${session}`);
+  console.log(`Running: ${running ? "yes" : "no"}`);
+  console.log(`Config:  ${configExists ? "ide.yml found" : "no ide.yml"}`);
+
+  if (running) {
+    console.log(
+      `Daemon:  ${data.daemon.alive ? "running" : "not running"}${data.daemon.port ? ` (port ${data.daemon.port})` : ""}`,
+    );
+  }
+
+  if (panes.length > 0) {
+    console.log(`\nPanes:`);
+    for (const p of panes) {
+      const active = p.active ? " (active)" : "";
+      console.log(`  ${p.index}: ${p.title} [${p.width}x${p.height}]${active}`);
+    }
+  }
+}

package/packages/daemon/src/stop.ts

@@ -0,0 +1,28 @@
+import { resolve } from "node:path";
+import { getSessionName } from "./lib/yaml-io.ts";
+import { outputError } from "./lib/output.ts";
+import { killSession, stopSessionMonitor } from "@tmux-ide/tmux-bridge";
+
+export async function stop(
+  targetDir: string | undefined,
+  { json }: { json?: boolean } = {},
+): Promise<void> {
+  const dir = resolve(targetDir ?? ".");
+  const { name: session } = getSessionName(dir);
+
+  // Stop the session monitor before killing the session
+  stopSessionMonitor(session);
+
+  const result = killSession(session);
+
+  if (result.stopped) {
+    if (json) {
+      console.log(JSON.stringify({ stopped: session }));
+    } else {
+      console.log(`Stopped session "${session}"`);
+    }
+    return;
+  }
+
+  outputError(`No active session "${session}" found`, "NOT_RUNNING");
+}