web-terminal/src/session/session.ts

/**
 * src/session/session.ts (T12) — single PTY session: lifecycle + ws plumbing.
 *
 * Owns one node-pty process and its scrollback. Wires:
 *   - pty.onData → ring buffer + (forward to attachedWs as `output`),
 *   - pty.onExit → stamp exitedAt/exitCode → (notify attachedWs with `exit`)
 *                  → call the injected onExit so the manager can drop it (L2).
 *
 * Cross-validated fixes embedded here (ARCHITECTURE §3.4 / §4.4):
 *   - M4: spawn failure THROWS — createSession does not swallow it; server.ts
 *         catches and serializes a single `exit(-1, reason)` for that connection.
 *   - M5: every ws.send is guarded by `ws.readyState === WS_OPEN`.
 *   - L1: detach-then-exit keeps the session; with no attachedWs the `exit` is
 *         not delivered now — it is re-sent on the next attach (manager's job).
 *   - L4: writeInput/resize are silently ignored once the PTY has exited
 *         (calling write/resize on a dead PTY throws).
 *
 * The session never holds a reference to the manager; the exit event bubbles
 * across that layer purely through the injected `onExit` callback.
 *
 * Imports src/types.ts (frozen, read-only) and createRingBuffer (T6).
 * node-pty's `spawn` is imported here and mocked in tests so no real shell runs.
 */

import { randomUUID } from 'node:crypto';
import { spawn } from 'node-pty';

import type {
  Config,
  Dims,
  IPty,
  Session,
  SessionMeta,
  ServerMessage,
  WebSocketLike,
} from '../types.js';
import { WS_OPEN } from '../types.js';
import { serialize } from '../protocol.js';
import { createRingBuffer } from './ring-buffer.js';
import { tmuxName, killSession } from './tmux.js';

/** Send a server message to `ws` only if it is OPEN (M5). Never throws on a
 *  closed socket; forwarding to a dead ws is simply a no-op. */
function sendIfOpen(ws: WebSocketLike | null, msg: ServerMessage): void {
  if (ws !== null && ws.readyState === WS_OPEN) {
    ws.send(serialize(msg));
  }
}

/**
 * Spawn a PTY and wire its data/exit streams. Throws on spawn failure (M4).
 *
 * @param onExit injected by the manager — invoked after exitedAt is set so the
 *               session can be removed from the table (L2).
 */
export function createSession(
  cfg: Config,
  dims: Dims,
  now: number,
  onExit: (session: Session) => void,
  // H1: pass an existing id to RE-ATTACH to a surviving tmux session (e.g. after
  // a server restart). Default = a fresh id for a brand-new session.
  id: string = randomUUID(),
  // M6: spawn directory for a new session ("new tab here"); defaults to homeDir.
  cwd?: string,
): Session {
  // The id is injected into the shell env so Claude Code hooks know which tab an
  // event belongs to ($WEBTERM_SESSION) and where to POST ($WEBTERM_HOOK_URL, H2).
  const tName = cfg.useTmux ? tmuxName(id) : null;

  // H1: under tmux, the node-pty process is a tmux CLIENT; `new-session -A`
  // attaches to web_<id> if it exists (restart survival) or creates it.
  const file = tName !== null ? 'tmux' : cfg.shellPath;
  const args = tName !== null ? ['new-session', '-A', '-s', tName, cfg.shellPath] : [];

  // M4: let a spawn failure (e.g. missing shell / tmux) propagate synchronously.
  const pty: IPty = spawn(file, args, {
    name: 'xterm-256color',
    cols: dims.cols,
    rows: dims.rows,
    cwd: cwd ?? cfg.homeDir,
    env: {
      ...process.env,
      WEBTERM_SESSION: id,
      WEBTERM_HOOK_URL: `http://127.0.0.1:${cfg.port}/hook`,
    },
  });

  const meta: SessionMeta = {
    id,
    createdAt: now,
    shellPath: cfg.shellPath,
  };

  const session: Session = {
    meta,
    buffer: createRingBuffer(cfg.scrollbackBytes),
    attachedWs: null,
    detachedAt: null,
    lastOutputAt: now,
    exitedAt: null,
    exitCode: null,
    claudeStatus: 'unknown',
    tmuxName: tName,
    pty,
  };

  // onData: persist to scrollback, refresh liveness, forward to the live ws.
  pty.onData((chunk) => {
    session.buffer.append(chunk);
    session.lastOutputAt = Date.now();
    sendIfOpen(session.attachedWs, { type: 'output', data: chunk });
  });

  // onExit: record exit, notify the attached ws (if any, L1), then bubble up.
  pty.onExit(({ exitCode }) => {
    session.exitedAt = Date.now();
    session.exitCode = exitCode;
    sendIfOpen(session.attachedWs, { type: 'exit', code: exitCode });
    onExit(session);
  });

  return session;
}

/**
 * Bind `ws` to the session: swap the pointer to the new ws FIRST (so live
 * forwarding never targets a kicked socket), replay the scrollback, then let
 * the real-time stream continue. Returns the kicked old ws (caller closes it).
 */
export function attachWs(session: Session, ws: WebSocketLike): WebSocketLike | null {
  const previous = session.attachedWs;

  // Pointer first: later attach wins; forwarding henceforth only reaches `ws`.
  session.attachedWs = ws;
  session.detachedAt = null;

  // Replay the buffered scrollback so the reconnecting client sees the last screen.
  sendIfOpen(ws, { type: 'output', data: session.buffer.snapshot() });

  return previous;
}

/** Detach the ws and stamp detachedAt. NEVER kills the PTY (vibe-coding core). */
export function detachWs(session: Session, now: number): void {
  session.attachedWs = null;
  session.detachedAt = now;
}

/** Forward input to the PTY. No-op once the PTY has exited (L4). */
export function writeInput(session: Session, data: string): void {
  if (session.exitedAt !== null) return;
  session.pty.write(data);
}

/** Resize the PTY. No-op after exit (L4); idempotent when dims are unchanged. */
export function resize(session: Session, cols: number, rows: number): void {
  if (session.exitedAt !== null) return;
  if (session.pty.cols === cols && session.pty.rows === rows) return;
  session.pty.resize(cols, rows);
}

/**
 * Kill the session (idle reclaim). Under tmux this ends the actual shell via
 * `tmux kill-session` (H1); killing only the client pty would leave the tmux
 * session running. Always also kills the client pty.
 */
export function kill(session: Session): void {
  if (session.tmuxName !== null) killSession(session.tmuxName);
  session.pty.kill();
}