tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/terminal/NodePtyAdapter.ts

@@ -0,0 +1,271 @@
+/**
+ * NodePtyAdapter — concrete `PtyAdapter` backed by the `node-pty` native
+ * module (T087). The only place in the daemon that imports `node-pty`.
+ *
+ * One-time setup:
+ *   - macOS / Linux: node-pty ships a `spawn-helper` binary. The
+ *     `chmod +x` is occasionally lost during install (npm tarball
+ *     metadata edge cases). Borrowing t3's
+ *     `ensureNodePtySpawnHelperExecutable`, we walk the published candidate
+ *     paths and chmod 0755 once per process. Failure is best-effort —
+ *     spawning will surface a real error if it actually matters.
+ */
+
+import { chmodSync, existsSync, statSync, type Stats } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import * as pty from "node-pty";
+import {
+  PtySpawnError,
+  type PtyAdapter,
+  type PtyExitEvent,
+  type PtyProcess,
+  type PtySpawnInput,
+} from "./PtyAdapter.ts";
+
+const ADAPTER_ID = "node-pty";
+let helperEnsured = false;
+
+function candidateSpawnHelperPaths(): string[] {
+  const requireForNodePty = createRequire(import.meta.url);
+  let pkgJsonPath: string;
+  try {
+    pkgJsonPath = requireForNodePty.resolve("node-pty/package.json");
+  } catch {
+    // node-pty package missing — `pty.spawn` will throw a richer error.
+    return [];
+  }
+  const pkgDir = dirname(pkgJsonPath);
+  return [
+    join(pkgDir, "build", "Release", "spawn-helper"),
+    join(pkgDir, "build", "Debug", "spawn-helper"),
+    join(pkgDir, "prebuilds", `${process.platform}-${process.arch}`, "spawn-helper"),
+  ];
+}
+
+/**
+ * Chmod node-pty's `spawn-helper` to 0755 the first time we touch it.
+ * No-op on Windows (no helper binary). Idempotent across calls.
+ * Exported for the unit test that asserts the chmod side effect.
+ */
+export function ensureNodePtySpawnHelperExecutable(
+  options: { explicitPath?: string; force?: boolean } = {},
+): void {
+  if (process.platform === "win32") return;
+  if (!options.force && !options.explicitPath && helperEnsured) return;
+
+  const candidates = options.explicitPath ? [options.explicitPath] : candidateSpawnHelperPaths();
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    try {
+      chmodSync(candidate, 0o755);
+    } catch {
+      // Best-effort: a hardened filesystem may forbid chmod even when the
+      // bit is already set. Continue to the next candidate so we never
+      // fail spawning just because the helper was already executable.
+    }
+  }
+
+  if (!options.explicitPath) helperEnsured = true;
+}
+
+function assertValidCwd(cwd: string, statFn: (cwd: string) => Stats): void {
+  let stats: Stats;
+  try {
+    stats = statFn(cwd);
+  } catch (err) {
+    throw new PtySpawnError({
+      adapter: ADAPTER_ID,
+      code: "cwd_invalid",
+      message: `cwd does not exist or cannot be stat'd: ${cwd}`,
+      cause: err,
+    });
+  }
+  if (!stats.isDirectory()) {
+    throw new PtySpawnError({
+      adapter: ADAPTER_ID,
+      code: "cwd_invalid",
+      message: `cwd is not a directory: ${cwd}`,
+    });
+  }
+}
+
+/**
+ * Wrap a live `node-pty` IPty with the `PtyProcess` interface. Disposes are
+ * idempotent; `kill` emits a synthetic exit if node-pty doesn't fire one
+ * (e.g. when the child has already gone away under us).
+ */
+class NodePtyProcess implements PtyProcess {
+  private exited = false;
+  private readonly child: pty.IPty;
+  private readonly dataListeners = new Set<(data: Buffer) => void>();
+  private readonly exitListeners = new Set<(event: PtyExitEvent) => void>();
+
+  constructor(child: pty.IPty) {
+    this.child = child;
+    // node-pty hands us strings by default; we want raw buffers for
+    // byte-accurate WS bridging. The encoding:null on spawn opts gives us
+    // buffers in the typings of node-pty@1.2.0-beta.12.
+    this.child.onData((data) => {
+      const buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data), "utf8");
+      for (const listener of this.dataListeners) listener(buf);
+    });
+    this.child.onExit((evt) => {
+      this.exited = true;
+      const event: PtyExitEvent = {
+        exitCode: evt.exitCode ?? 0,
+        signal: typeof evt.signal === "number" ? evt.signal : null,
+      };
+      for (const listener of this.exitListeners) listener(event);
+    });
+  }
+
+  get pid(): number {
+    return this.child.pid;
+  }
+
+  write(data: string | Uint8Array): void {
+    if (this.exited) return;
+    if (typeof data === "string") this.child.write(data);
+    else this.child.write(Buffer.from(data).toString("binary"));
+  }
+
+  resize(cols: number, rows: number): void {
+    if (this.exited) return;
+    if (!Number.isInteger(cols) || cols <= 0)
+      throw new RangeError("cols must be a positive integer");
+    if (!Number.isInteger(rows) || rows <= 0)
+      throw new RangeError("rows must be a positive integer");
+    try {
+      this.child.resize(cols, rows);
+    } catch {
+      // node-pty throws if the underlying fd is gone — treat as no-op so
+      // bridge resize handlers don't have to special-case.
+    }
+  }
+
+  kill(signal?: NodeJS.Signals | number): void {
+    if (this.exited) return;
+    try {
+      this.child.kill(typeof signal === "number" ? String(signal) : signal);
+    } catch {
+      // Already gone. Synthesize an exit so listeners detach cleanly.
+      this.exited = true;
+      for (const listener of this.exitListeners) listener({ exitCode: 0, signal: null });
+    }
+  }
+
+  onData(callback: (data: Buffer) => void): () => void {
+    this.dataListeners.add(callback);
+    return () => {
+      this.dataListeners.delete(callback);
+    };
+  }
+
+  onExit(callback: (event: PtyExitEvent) => void): () => void {
+    if (this.exited) {
+      // Adapters MUST guarantee at most one terminal onExit — late
+      // subscribers get an inert disposer.
+      return () => undefined;
+    }
+    this.exitListeners.add(callback);
+    return () => {
+      this.exitListeners.delete(callback);
+    };
+  }
+}
+
+export interface NodePtyAdapterOptions {
+  /** Override node-pty's `spawn` for tests. */
+  spawnPty?: typeof pty.spawn;
+  /** Override `fs.statSync` for cwd validation in tests. */
+  statCwd?: (cwd: string) => Stats;
+  /** Skip the spawn-helper chmod (test isolation). */
+  skipHelperEnsure?: boolean;
+}
+
+export class NodePtyAdapter implements PtyAdapter {
+  readonly id = ADAPTER_ID;
+  private readonly spawnPty: typeof pty.spawn;
+  private readonly statCwd: (cwd: string) => Stats;
+  private readonly skipHelperEnsure: boolean;
+
+  constructor(options: NodePtyAdapterOptions = {}) {
+    this.spawnPty = options.spawnPty ?? pty.spawn;
+    this.statCwd = options.statCwd ?? statSync;
+    this.skipHelperEnsure = options.skipHelperEnsure ?? false;
+  }
+
+  async spawn(input: PtySpawnInput): Promise<PtyProcess> {
+    if (!this.skipHelperEnsure) ensureNodePtySpawnHelperExecutable();
+    return this.spawnSyncInternal(input);
+  }
+
+  spawnSync(input: PtySpawnInput): PtyProcess {
+    if (!this.skipHelperEnsure) ensureNodePtySpawnHelperExecutable();
+    return this.spawnSyncInternal(input);
+  }
+
+  private spawnSyncInternal(input: PtySpawnInput): PtyProcess {
+    assertValidCwd(input.cwd, this.statCwd);
+    if (!Number.isInteger(input.cols) || input.cols <= 0) {
+      throw new PtySpawnError({
+        adapter: ADAPTER_ID,
+        code: "unknown",
+        message: `cols must be a positive integer (got ${input.cols})`,
+      });
+    }
+    if (!Number.isInteger(input.rows) || input.rows <= 0) {
+      throw new PtySpawnError({
+        adapter: ADAPTER_ID,
+        code: "unknown",
+        message: `rows must be a positive integer (got ${input.rows})`,
+      });
+    }
+    // node-pty wants `Record<string, string>` for env — strip undefined values.
+    const env: Record<string, string> = {};
+    for (const [key, value] of Object.entries(input.env)) {
+      if (typeof value === "string") env[key] = value;
+    }
+    let child: pty.IPty;
+    try {
+      child = this.spawnPty(input.shell, [...(input.args ?? [])], {
+        name: input.name ?? "xterm-256color",
+        cols: input.cols,
+        rows: input.rows,
+        cwd: input.cwd,
+        env,
+        encoding: input.encoding === "utf8" ? "utf8" : (null as unknown as undefined),
+      });
+    } catch (err) {
+      const errno = (err as NodeJS.ErrnoException | undefined)?.code;
+      if (errno === "ENOENT") {
+        throw new PtySpawnError({
+          adapter: ADAPTER_ID,
+          code: "shell_not_found",
+          message: `shell not found in PATH: ${input.shell}`,
+          cause: err,
+        });
+      }
+      if (errno === "EACCES" || errno === "EPERM") {
+        throw new PtySpawnError({
+          adapter: ADAPTER_ID,
+          code: "permission_denied",
+          message: `permission denied spawning ${input.shell}`,
+          cause: err,
+        });
+      }
+      throw new PtySpawnError({
+        adapter: ADAPTER_ID,
+        code: "unknown",
+        message: `node-pty spawn failed: ${err instanceof Error ? err.message : String(err)}`,
+        cause: err,
+      });
+    }
+    return new NodePtyProcess(child);
+  }
+}
+
+/** Convenience singleton — most call sites just want `defaultNodePtyAdapter`. */
+export const defaultNodePtyAdapter: PtyAdapter = new NodePtyAdapter();

package/packages/daemon/src/terminal/PtyAdapter.ts

@@ -0,0 +1,140 @@
+/**
+ * PtyAdapter — terminal PTY adapter service contract (T087).
+ *
+ * Defines the process primitives required by terminal session management
+ * without binding to a specific PTY implementation. Mirrors t3's
+ * `apps/server/src/terminal/Services/PTY.ts` shape minus the Effect runtime
+ * (Effect adoption is G14-T07 territory; we stay on plain TS Promises here).
+ *
+ * Why:
+ *   - `node-pty` is a native module whose `onData` callback never fires
+ *     under Bun (T085 burned half a day on the diagnosis). Routing every
+ *     daemon-side PTY spawn through this interface lets us swap runtimes
+ *     without touching consumers and lets tests stub the entire layer with
+ *     a `MockPtyAdapter` that returns scripted output.
+ *   - The Electron preload + future remote-PTY transports will eventually
+ *     ship their own adapters. Keeping the seam thin makes that drop-in.
+ *
+ * Synchronous vs async:
+ *   - `spawn(input): Promise<PtyProcess>` is the canonical entry point.
+ *     Async because some adapters do real setup (e.g. NodePtyAdapter chmods
+ *     node-pty's `spawn-helper` binary the first time, t3 does the same).
+ *   - `spawnSync(input): PtyProcess` is a sibling for legacy synchronous
+ *     callers (today: `PtyBridge.spawn` in `server/pty-bridge.ts`). It MUST
+ *     have the same observable semantics as `spawn` once any one-shot setup
+ *     has been done. Adapters that genuinely need async work should throw
+ *     `PtySpawnError` ("sync_unsupported") from `spawnSync` so the caller
+ *     can fall back to the async path.
+ */
+
+export interface PtySpawnInput {
+  /** Executable to run. Defaults are adapter-defined when omitted. */
+  shell: string;
+  /** Argv for the executable (without argv[0]). Optional; adapters may apply defaults. */
+  args?: ReadonlyArray<string>;
+  /** Working directory for the spawned process. Must exist + be a directory. */
+  cwd: string;
+  /** Initial cols. Must be a positive integer. */
+  cols: number;
+  /** Initial rows. Must be a positive integer. */
+  rows: number;
+  /** Environment vars handed to the child. */
+  env: NodeJS.ProcessEnv;
+  /**
+   * Terminal name (`$TERM`) handed to the child. Defaults to
+   * `xterm-256color` when omitted. Some adapters honour it, some pin it.
+   */
+  name?: string;
+  /**
+   * Output encoding. `null` (default) yields raw `Buffer` data — required
+   * for byte-accurate WebSocket bridging.
+   */
+  encoding?: "utf8" | null;
+}
+
+export interface PtyExitEvent {
+  /** Process exit code. `0` is clean shutdown. */
+  exitCode: number;
+  /** Terminating signal (numeric), or `null` when the process exited cleanly. */
+  signal: number | null;
+}
+
+/**
+ * Handle to a live PTY child returned by `PtyAdapter.spawn`. Modelled on
+ * t3's `PtyProcess` and `node-pty`'s `IPty` so wrapping is trivial.
+ *
+ * Listeners returned by `onData`/`onExit` are disposers — call them to
+ * detach. After `kill()` the adapter is expected to emit a single
+ * synthetic `onExit` event so the bridge layer can converge on shutdown.
+ */
+export interface PtyProcess {
+  /** Underlying OS PID (or a synthetic positive integer for mocks). */
+  readonly pid: number;
+  /** Write raw bytes (string is interpreted as UTF-8) into the child stdin. */
+  write(data: string | Uint8Array): void;
+  /** Resize the controlling terminal. */
+  resize(cols: number, rows: number): void;
+  /**
+   * Send a signal to the child. Defaults to `SIGTERM` so adapters that
+   * can't deliver arbitrary signals (mocks, sandboxed remotes) still
+   * honour the common case.
+   */
+  kill(signal?: NodeJS.Signals | number): void;
+  /**
+   * Subscribe to data emissions. Returns a disposer; calling it detaches
+   * the listener without affecting any sibling subscribers.
+   */
+  onData(callback: (data: Buffer) => void): () => void;
+  /**
+   * Subscribe to exit. Returns a disposer. Adapters MUST guarantee at
+   * most one terminal `onExit` per process; resubscribing after exit is
+   * a no-op that returns an inert disposer.
+   */
+  onExit(callback: (event: PtyExitEvent) => void): () => void;
+}
+
+/** Discriminator codes for `PtySpawnError`. */
+export type PtySpawnErrorCode =
+  | "cwd_invalid"
+  | "shell_not_found"
+  | "permission_denied"
+  | "sync_unsupported"
+  | "unknown";
+
+/**
+ * Typed failure for `PtyAdapter.spawn` / `spawnSync`. Adapters MUST throw
+ * (or reject with) this class so the WS bridge can translate to a
+ * structured error frame without sniffing native error message strings.
+ */
+export class PtySpawnError extends Error {
+  readonly adapter: string;
+  readonly code: PtySpawnErrorCode;
+  constructor(args: {
+    adapter: string;
+    code: PtySpawnErrorCode;
+    message: string;
+    cause?: unknown;
+  }) {
+    super(args.message, args.cause !== undefined ? { cause: args.cause } : undefined);
+    this.name = "PtySpawnError";
+    this.adapter = args.adapter;
+    this.code = args.code;
+  }
+}
+
+/**
+ * The adapter contract every PTY backend must satisfy. Async is the
+ * canonical surface; `spawnSync` is provided for the synchronous callers
+ * that exist today (PtyBridge / ws-route). New code should prefer `spawn`.
+ */
+export interface PtyAdapter {
+  /** Human-readable adapter id, surfaced in `PtySpawnError.adapter`. */
+  readonly id: string;
+  /** Canonical async spawn. Resolves once the child PID is known. */
+  spawn(input: PtySpawnInput): Promise<PtyProcess>;
+  /**
+   * Synchronous spawn. Adapters that can't satisfy this (because they
+   * need async setup) MUST throw `PtySpawnError({ code: "sync_unsupported" })`.
+   */
+  spawnSync(input: PtySpawnInput): PtyProcess;
+}

package/packages/daemon/src/terminal/README.md

@@ -0,0 +1,92 @@
+# `terminal/` — PTY adapter layer (T087)
+
+The daemon's PTY surface is layered to keep `node-pty` (a native module
+with sharp runtime edges) confined to one file. Everything above this
+folder talks to the abstract `PtyAdapter` interface and never knows
+whether the bytes came from a real OS PTY, a mock, or — eventually —
+a remote transport.
+
+```
++------------------+      +------------------------+      +-------------+
+| server/pty-bridge | ---> |   PtyAdapter (iface)    | ---> | node-pty    |
+|  (ring buffer,    |      |                         |      | (NodePty-   |
+|   replay, WS      |      |  spawn  spawnSync       |      |  Adapter)   |
+|   bridge)         |      |  PtyProcess primitives  |      +-------------+
++------------------+      +-------------+-----------+
+                                        |
+                                        v
+                                +----------------+
+                                | MockPtyAdapter  |
+                                | (tests)         |
+                                +----------------+
+```
+
+## Files
+
+- `PtyAdapter.ts` — the contract: `PtySpawnInput`, `PtyExitEvent`,
+  `PtyProcess`, `PtyAdapter`, and the `PtySpawnError` taxonomy.
+- `NodePtyAdapter.ts` — concrete implementation backed by `node-pty`.
+  Ports t3's `ensureNodePtySpawnHelperExecutable` chmod-on-helper trick
+  so a fresh install always boots.
+- `__tests__/MockPtyAdapter.ts` — scripted PTY for the test suite. Lives
+  under `__tests__/` so production bundling never picks it up.
+- `__tests__/*.test.ts` — contract tests parameterised over every
+  adapter, plus adapter-specific units.
+
+## Why this exists
+
+`node-pty` is a native module compiled against an underlying runtime ABI.
+T085 burned half a day finding out that under Bun, `node-pty`'s `onData`
+callback never fires — the PTY spawns, the child exits, and zero bytes
+flow back. The fix had to live in two places:
+
+1. **Runtime pinning** (T087 PART 1): every daemon spawn site uses
+   `node`/`tsx`, never `bun`. See `daemon-watchdog.ts`,
+   `tmux-bridge/src/monitor.ts`, `src/lib/tmux.ts`. The
+   `packages/daemon/package.json` `dev`/`start` scripts mirror t3's
+   `apps/server/package.json` (`tsx --watch` in dev, `node dist/...` in
+   prod).
+2. **Adapter abstraction** (T087 PART 2): a thin interface so the future
+   doesn't paint us into the same corner. New runtimes get their own
+   adapter; tests use `MockPtyAdapter` so we never accidentally spawn a
+   real PTY in CI.
+
+## When to add a new adapter
+
+Anything that produces PTY-shaped bytes is fair game. Concrete examples
+we've considered:
+
+- A **remote PTY** adapter that proxies over WebSocket to a daemon
+  running on another host. Drops in here without touching `pty-bridge`.
+- A **mock SSH** adapter for integration tests that need a deterministic
+  remote shell. Built on `MockPtyAdapter` semantics.
+- An **xterm replay** adapter that pipes a captured `.cast` file back
+  through `onData` for demos. Useful for marketing GIFs.
+
+Each new adapter MUST satisfy `PtyAdapter.contract.test.ts` — the
+parameterised suite runs every contract assertion against every adapter
+we register there.
+
+## Constraints we honour
+
+- `spawn` is async; `spawnSync` exists for legacy callers (today:
+  `server/pty-bridge.ts`). Adapters that can't satisfy `spawnSync` throw
+  `PtySpawnError({ code: "sync_unsupported" })`.
+- Errors are typed (`PtySpawnError` with a discriminator) so the WS
+  bridge can surface a structured error frame instead of grepping native
+  messages.
+- `kill()` is idempotent. After it the adapter MUST guarantee at most
+  one terminal `onExit` event — subsequent `onExit(...)` subscribers
+  receive an inert disposer.
+- No production code outside `NodePtyAdapter.ts` imports `node-pty`.
+  This is enforced by `pty-bridge.ts` now consuming `PtyAdapter` and is
+  the gate G14-T10 will tighten further.
+
+## Roadmap notes
+
+- **G14-T07** introduces Effect runtime. When that lands, this contract
+  grows an `Effect.Effect<PtyProcess, PtySpawnError>` shape; the plain-
+  TS interface here stays so adapters can implement either side.
+- **G14-T10** moves chat reactor → Effect Stream. PTY bytes will flow
+  through the same Stream pipeline; today's `EventEmitter`-based
+  `pty-bridge` becomes the bottom of that Stream.