ompchamber 0.7.0 → 1.0.0

package/src/server/lib/terminal/runtime.server.ts

@@ -0,0 +1,338 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal registry: which shells are live, who is watching them, and when
+ * they die.
+ *
+ * One real shell per terminal id, created on the first `attach` (there is no
+ * separate create endpoint to race against), kept alive while clients come and
+ * go, and killed through the process group so the commands it started die with
+ * it. Session mechanics live in `session.server.ts`; this module owns the map,
+ * the viewer sets, the idle reaper and process-exit cleanup.
+ */
+
+import path from 'path';
+import { detectBusyShells, type ShellProcess } from '@/server/lib/terminal/foreground';
+import {
+  TERMINATION_GRACE_MS,
+  TerminalRuntimeError,
+  closeTerminalStream,
+  createSession,
+  signalGroup,
+  snapshotOf,
+  type AttachRequest,
+  type TerminalSession,
+  type TerminalViewer,
+} from '@/server/lib/terminal/session.server';
+import { TERMINAL_MAX_INPUT_BYTES, clampTerminalSize, type TerminalSnapshot } from '@/shared/lib/workspace/terminal/protocol';
+
+const MAX_TERMINALS = 8;
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+const IDLE_SWEEP_MS = 60 * 1000;
+/** Quiet period before a resize burst is committed to the PTY. */
+const RESIZE_SETTLE_MS = 120;
+
+export interface TerminalAttachment {
+  snapshot: TerminalSnapshot;
+  /** Retained scrollback, to be sent after the `ready` frame. */
+  replay: Uint8Array;
+}
+
+/**
+ * The registry lives on `globalThis`, not in a module-local binding.
+ *
+ * `bun run --hot` re-evaluates this module on every server-file edit, but the
+ * PTY children are detached sessions that keep running. A module-local `Map`
+ * would be replaced by a fresh empty one on each reload, leaving the previous
+ * shells alive with nothing tracking them — unreachable from the client, never
+ * counted, never reaped, and still holding their slots. Anchoring the map to
+ * the process keeps a reload from orphaning anything.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminals: Map<string, TerminalSession> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalSweep: ReturnType<typeof setInterval> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalResizes: Map<string, ReturnType<typeof setTimeout>> | undefined;
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
+}
+
+const sessions: Map<string, TerminalSession> = (globalThis.__ompChamberTerminals ??= new Map());
+
+function getSweepTimer() {
+  return globalThis.__ompChamberTerminalSweep;
+}
+
+function setSweepTimer(timer: ReturnType<typeof setInterval> | undefined) {
+  globalThis.__ompChamberTerminalSweep = timer;
+  return timer;
+}
+
+function getResizeTimers(): Map<string, ReturnType<typeof setTimeout>> {
+  return (globalThis.__ompChamberTerminalResizes ??= new Map());
+}
+
+/**
+ * Attach `viewer` to `request.id`, creating the shell when the id is unknown.
+ *
+ * Registration and history capture happen in one synchronous block: Bun cannot
+ * interleave a PTY `data` callback inside it, so the viewer can neither miss
+ * output nor receive it twice.
+ *
+ * The cap counts *live* shells only. An exited shell is a corpse holding a
+ * scrollback nobody is reading, and letting corpses consume the budget is how
+ * a session that restarted a shell a few times hits the limit with nothing
+ * running: every restart leaves its predecessor behind.
+ */
+export async function attachTerminal(viewer: TerminalViewer, request: AttachRequest): Promise<TerminalAttachment> {
+  let session = sessions.get(request.id);
+  if (!session) {
+    reclaimExitedTerminals();
+    if ((await countLiveTerminals()) >= MAX_TERMINALS) {
+      throw new TerminalRuntimeError('capacity', `Terminal limit reached (${MAX_TERMINALS} busy shells)`);
+    }
+    const created = await createSession(request);
+    sessions.set(request.id, created);
+    // An exit with nobody watching is the common case for a replaced shell
+    // (restart, repo switch): reap it as soon as it lands instead of leaving
+    // the record for the sweep, which is up to a minute of holding a slot.
+    void created.proc?.exited.then(() => {
+      if (created.viewers.size === 0) forgetTerminal(created.id);
+    });
+    ensureSweeper();
+    session = created;
+  }
+
+  const replay = session.history.replay();
+  const snapshot = snapshotOf(session);
+  session.viewers.add(viewer);
+  session.lastActivity = Date.now();
+  return { snapshot, replay };
+}
+
+/**
+ * Shells that are actually doing work, which is what the cap budgets.
+ *
+ * Two things are deliberately excluded: an exited shell (a corpse with a
+ * scrollback) and a shell sitting at its prompt — the PTY's foreground process
+ * group tells them apart exactly (see `foreground.ts`). Counting idle shells
+ * is how a panel that was restarted or switched a few times pins the budget
+ * with nothing running, and the next attach is refused.
+ */
+export async function countLiveTerminals(): Promise<number> {
+  const running: ShellProcess[] = [];
+  for (const session of sessions.values()) {
+    if (session.status !== 'running' || !session.proc) continue;
+    running.push({ id: session.id, pid: session.proc.pid });
+  }
+  const busy = await detectBusyShells(running);
+  return busy.size;
+}
+
+/**
+ * Drop exited shells that nobody is watching.
+ *
+ * Run before a create, not only on the idle sweep: the sweep is a minute away,
+ * and a burst of restarts inside that window would otherwise be rejected while
+ * every corpse in the way is already dead.
+ */
+export function reclaimExitedTerminals(): number {
+  let reclaimed = 0;
+  for (const [id, session] of sessions) {
+    if (session.status !== 'exited') continue;
+    if (session.viewers.size > 0) continue;
+    forgetTerminal(id);
+    reclaimed += 1;
+  }
+  return reclaimed;
+}
+
+export function detachTerminal(viewer: TerminalViewer, id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  session.viewers.delete(viewer);
+  session.lastActivity = Date.now();
+  // The last viewer leaving a finished shell leaves nothing behind worth
+  // keeping: no process to reattach to, and a scrollback nobody will read.
+  if (session.status === 'exited' && session.viewers.size === 0) forgetTerminal(id);
+}
+
+/**
+ * Live terminal summaries, optionally narrowed to one scope, so a client can
+ * adopt a shell it does not have an id for (a reloaded page, a second tab).
+ *
+ * `busy` marks a shell with a foreground command — the panel shows it as
+ * running, and the cap budgets it. One `ps` for the whole list.
+ */
+export async function listTerminals(root?: string | null, repo?: string | null): Promise<TerminalSnapshot[]> {
+  const scope = root ? (repo && repo !== '.' ? path.join(root, repo) : root) : null;
+  const running: ShellProcess[] = [];
+  const out: TerminalSnapshot[] = [];
+  for (const session of sessions.values()) {
+    if (scope && !isWithin(session.cwd, scope)) continue;
+    if (session.status === 'running' && session.proc) {
+      running.push({ id: session.id, pid: session.proc.pid });
+    }
+    out.push(snapshotOf(session));
+  }
+  const busy = await detectBusyShells(running);
+  return out.map((snapshot) => ({ ...snapshot, busy: busy.has(snapshot.id) }));
+}
+
+function isWithin(target: string, root: string): boolean {
+  return target === root || target.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+}
+
+export function writeTerminalInput(id: string, data: Uint8Array): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  if (data.length === 0 || data.length > TERMINAL_MAX_INPUT_BYTES) return;
+  session.lastActivity = Date.now();
+  try {
+    session.term.write(data);
+  } catch {
+    // The PTY closed between the status check and the write.
+  }
+}
+
+export function resizeTerminal(id: string, cols: number, rows: number): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  const size = clampTerminalSize(cols, rows);
+  if (size.cols === session.cols && size.rows === session.rows) return;
+  session.cols = size.cols;
+  session.rows = size.rows;
+  session.lastActivity = Date.now();
+  try {
+    session.term.resize(size.cols, size.rows);
+  } catch {
+    return;
+  }
+  // resize() updates the winsize but never signals the child, so a TUI would
+  // not repaint. Deliver SIGWINCH ourselves.
+  signalGroup(session, 'SIGWINCH');
+}
+
+/**
+ * Debounce for `resizeTerminal`.
+ *
+ * A panel drag produces a burst of sizes — the pointer moves in steps and
+ * xterm's FitAddon refits on every animation frame — and each accepted size
+ * sends SIGWINCH. The shell answers every one of them by redrawing its prompt,
+ * so a single drag used to print the prompt a dozen times (measured: 10
+ * SIGWINCH in one second for one drag).
+ *
+ * Only the trailing size matters: the PTY ends at the final grid either way,
+ * and a repaint of an intermediate size is invisible work. A single timeout is
+ * reused so the burst coalesces into one signal.
+ */
+const resizeTimers = getResizeTimers();
+
+export function resizeTerminalDebounced(id: string, cols: number, rows: number): void {
+  const pending = resizeTimers.get(id);
+  if (pending) clearTimeout(pending);
+  resizeTimers.set(
+    id,
+    setTimeout(() => {
+      resizeTimers.delete(id);
+      resizeTerminal(id, cols, rows);
+    }, RESIZE_SETTLE_MS),
+  );
+}
+
+/**
+ * Kill the shell for `id`, keeping the record and its viewers: the process exit
+ * is what reports the real exit code, so nothing is synthesized here.
+ *
+ * SIGHUP, not SIGTERM. An interactive shell ignores SIGTERM — verified on
+ * macOS: `kill -TERM` to a zsh process group left it alive indefinitely, while
+ * SIGHUP terminated it in ~150 ms along with its background jobs. SIGHUP is
+ * also the semantically right signal: the terminal is going away.
+ */
+export function closeTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session || session.status !== 'running') return;
+  signalGroup(session, 'SIGHUP');
+  setTimeout(() => {
+    if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  }, TERMINATION_GRACE_MS).unref?.();
+}
+
+/**
+ * Drop a session record and release its PTY stream. Used by the idle reaper and
+ * when a client closes a terminal it does not intend to reopen — there are no
+ * viewers left to inform, so a running shell is killed outright.
+ */
+export function forgetTerminal(id: string): void {
+  const session = sessions.get(id);
+  if (!session) return;
+  sessions.delete(id);
+  clearPendingResize(id);
+  session.viewers.clear();
+  if (session.status === 'running') signalGroup(session, 'SIGKILL');
+  closeTerminalStream(session);
+}
+
+function clearPendingResize(id: string): void {
+  const pending = resizeTimers.get(id);
+  if (pending) {
+    clearTimeout(pending);
+    resizeTimers.delete(id);
+  }
+}
+
+/**
+ * Kill every shell at process exit. Synchronous by contract — `exit` handlers
+ * cannot await — so it escalates straight to SIGKILL: a detached shell is its
+ * own session and would otherwise outlive the server.
+ */
+export function disposeAllTerminals(): void {
+  clearInterval(setSweepTimer(undefined));
+  for (const [id, session] of sessions) {
+    clearPendingResize(id);
+    session.viewers.clear();
+    signalGroup(session, 'SIGKILL');
+    closeTerminalStream(session);
+  }
+  sessions.clear();
+}
+
+function ensureSweeper(): void {
+  if (getSweepTimer() !== undefined) return;
+  setSweepTimer(setInterval(() => {
+    // Exited shells are reaped on exit and on detach; this catches the one
+    // that finished while a viewer was still attached to it.
+    reclaimExitedTerminals();
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      // A live shell is only reaped when nobody watches it: an attached
+      // terminal is idle by definition while the user reads its output.
+      if (session.viewers.size > 0) continue;
+      if (now - session.lastActivity < IDLE_TIMEOUT_MS) continue;
+      forgetTerminal(id);
+    }
+  }, IDLE_SWEEP_MS));
+  getSweepTimer()!.unref();
+}
+
+/**
+ * Register process-wide cleanup exactly once. A `bun --hot` reload re-evaluates
+ * this module while the shells live on, so the guard keeps a reload from
+ * stacking duplicate signal handlers.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTerminalCleanupInstalled: boolean | undefined;
+}
+
+if (!globalThis.__ompChamberTerminalCleanupInstalled) {
+  globalThis.__ompChamberTerminalCleanupInstalled = true;
+  process.once('exit', disposeAllTerminals);
+  process.once('SIGINT', disposeAllTerminals);
+  process.once('SIGTERM', disposeAllTerminals);
+}

package/src/server/lib/terminal/session.server.ts

@@ -0,0 +1,215 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One PTY-backed shell: how it is created, how it is signalled, and what a
+ * snapshot of it looks like.
+ *
+ * Three behaviours here are load-bearing and were verified against Bun 1.4.2.
+ * Each fails *silently* when broken, which is why they are stated rather than
+ * implied by the code:
+ *
+ * 1. **`detached: true` is mandatory.** Without it the child stays in the
+ *    server's own process group: an interactive shell reports "no job control
+ *    in this shell" (Ctrl+Z and `fg` stop working), `process.kill(-pid, …)`
+ *    fails with ESRCH, and a group signal aimed at the *server's* group would
+ *    take the chamber down with it.
+ * 2. **The shell must re-acquire the PTY as its controlling terminal.** `setsid`
+ *    drops it, and a shell without one disables job control regardless of
+ *    `-i`. `shellLaunch` performs the re-open; see that module.
+ * 3. **`Bun.Terminal.resize()` never signals the child** — it updates the
+ *    kernel winsize only, so a TUI would not repaint. The caller sends
+ *    SIGWINCH itself.
+ *
+ * A fourth: a PTY read may split a multi-byte character, so bytes are forwarded
+ * verbatim and xterm's own streaming decoder reassembles them.
+ */
+
+import { resolveRoot } from '@/server/lib/fs/root';
+import { scopeToRepo } from '@/server/lib/fs/repo-scope';
+import { createTerminalHistory, type TerminalHistory } from '@/server/lib/terminal/history';
+import { resolveShellExecutable, shellCandidates, shellLaunch, terminalEnv } from '@/server/lib/terminal/shell';
+import {
+  clampTerminalSize,
+  type TerminalErrorCode,
+  type TerminalSnapshot,
+} from '@/shared/lib/workspace/terminal/protocol';
+
+export const TERMINATION_GRACE_MS = 1000;
+
+/** A socket attached to a terminal. Output is raw PTY bytes; control is JSON. */
+export interface TerminalViewer {
+  send(frame: string | Uint8Array): void;
+}
+
+export interface TerminalSession {
+  id: string;
+  cwd: string;
+  shell: string;
+  term: Bun.Terminal;
+  proc: Bun.Subprocess | null;
+  history: TerminalHistory;
+  viewers: Set<TerminalViewer>;
+  cols: number;
+  rows: number;
+  /** Grid the retained scrollback was drawn for — replay must match it. */
+  replayCols: number;
+  replayRows: number;
+  status: 'running' | 'exited';
+  exitCode: number | null;
+  signal: string | null;
+  lastActivity: number;
+}
+
+/** A rejected attach, carrying the code the client shows to the user. */
+export class TerminalRuntimeError extends Error {
+  constructor(
+    readonly code: TerminalErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'TerminalRuntimeError';
+  }
+}
+
+export interface AttachRequest {
+  id: string;
+  cols: number;
+  rows: number;
+  root?: string;
+  repo?: string;
+  theme?: 'light' | 'dark';
+}
+
+export async function createSession(request: AttachRequest): Promise<TerminalSession> {
+  const cwd = await resolveSessionCwd(request.root, request.repo);
+  const executable = await resolveShellExecutable(shellCandidates());
+  if (!executable) {
+    throw new TerminalRuntimeError('shell', 'No usable shell found (checked $SHELL, /bin/zsh, /bin/bash, /bin/sh)');
+  }
+
+  const size = clampTerminalSize(request.cols, request.rows);
+  const session: TerminalSession = {
+    id: request.id,
+    cwd,
+    shell: executable,
+    // Assigned below: the PTY callback closes over `session`, so the record has
+    // to exist before the terminal does.
+    term: undefined as unknown as Bun.Terminal,
+    proc: null,
+    history: createTerminalHistory(),
+    viewers: new Set(),
+    cols: size.cols,
+    rows: size.rows,
+    replayCols: size.cols,
+    replayRows: size.rows,
+    status: 'running',
+    exitCode: null,
+    signal: null,
+    lastActivity: Date.now(),
+  };
+
+  const term = new Bun.Terminal({
+    cols: size.cols,
+    rows: size.rows,
+    name: 'xterm-256color',
+    data(_term, bytes) {
+      session.history.append(bytes);
+      session.lastActivity = Date.now();
+      for (const viewer of session.viewers) viewer.send(bytes);
+    },
+  });
+  session.term = term;
+
+  let proc: Bun.Subprocess;
+  try {
+    proc = Bun.spawn(shellLaunch(executable), {
+      terminal: term,
+      detached: true,
+      cwd,
+      env: terminalEnv(Bun.env, request.theme ?? 'dark'),
+    });
+  } catch (error) {
+    closeTerminalStream(session);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new TerminalRuntimeError('spawn', `Failed to start ${executable}: ${message}`);
+  }
+  session.proc = proc;
+
+  void proc.exited.then((code) => {
+    if (session.status === 'exited') return;
+    session.status = 'exited';
+    session.exitCode = code ?? null;
+    session.signal = proc.signalCode ?? null;
+    session.lastActivity = Date.now();
+    const frame = JSON.stringify({ t: 'exit', exitCode: session.exitCode, signal: session.signal });
+    for (const viewer of session.viewers) viewer.send(frame);
+  });
+
+  return session;
+}
+
+async function resolveSessionCwd(root: string | undefined, repo: string | undefined): Promise<string> {
+  const baseDir = await resolveRoot(root ?? null, process.cwd());
+  let scoped = baseDir;
+  try {
+    scoped = await scopeToRepo(baseDir, repo ?? null);
+  } catch {
+    throw new TerminalRuntimeError('cwd', 'Invalid repo path');
+  }
+  const stat = await Bun.file(scoped).stat().catch(() => null);
+  if (!stat?.isDirectory()) throw new TerminalRuntimeError('cwd', `Not a directory: ${scoped}`);
+  return scoped;
+}
+
+export function snapshotOf(session: TerminalSession): TerminalSnapshot {
+  return {
+    id: session.id,
+    cwd: session.cwd,
+    shell: session.shell,
+    cols: session.cols,
+    rows: session.rows,
+    status: session.status,
+    exitCode: session.exitCode,
+    signal: session.signal,
+    bunVersion: Bun.version,
+    // `process.version` is the Node version Bun emulates, not a real binary.
+    nodeVersion: process.version,
+    replayCols: session.replayCols,
+    replayRows: session.replayRows,
+  };
+}
+
+/**
+ * Signal the shell's whole process group.
+ *
+ * `detached: true` made the shell a session leader, so the group holds every
+ * command it started — a build, a dev server, a suspended job. Signalling the
+ * pid alone would leave those behind.
+ */
+export function signalGroup(session: TerminalSession, signal: NodeJS.Signals): void {
+  const pid = session.proc?.pid;
+  if (!pid || process.platform === 'win32') {
+    try {
+      session.proc?.kill(signal);
+    } catch {
+      // Already gone.
+    }
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch {
+    // The group is gone: the shell exited on its own.
+  }
+}
+
+export function closeTerminalStream(session: TerminalSession): void {
+  try {
+    session.term.close();
+  } catch {
+    // Already closed.
+  }
+}

package/src/server/lib/terminal/shell.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  resolveShellExecutable,
+  shellArgs,
+  shellCandidates,
+  shellLaunch,
+  terminalEnv,
+} from '@/server/lib/terminal/shell';
+
+describe('shellCandidates', () => {
+  test('prefers an absolute $SHELL over the platform defaults', () => {
+    expect(shellCandidates({ SHELL: '/opt/homebrew/bin/fish' }, 'darwin')[0]).toBe('/opt/homebrew/bin/fish');
+  });
+
+  test('ignores a relative $SHELL so PATH cannot choose the login shell', () => {
+    expect(shellCandidates({ SHELL: 'fish' }, 'darwin')).toEqual(['/bin/zsh', '/bin/bash', '/bin/sh']);
+  });
+
+  test('falls back to the platform defaults without $SHELL', () => {
+    expect(shellCandidates({}, 'linux')).toEqual(['/bin/zsh', '/bin/bash', '/bin/sh']);
+  });
+
+  test('uses COMSPEC on windows', () => {
+    expect(shellCandidates({ COMSPEC: 'C:\\Windows\\System32\\cmd.exe' }, 'win32')).toEqual([
+      'C:\\Windows\\System32\\cmd.exe',
+    ]);
+  });
+});
+
+describe('shellArgs', () => {
+  test('POSIX shells launch interactive and login', () => {
+    // Interactive is what enables job control; without it Ctrl+Z/`fg` are dead.
+    expect(shellArgs('darwin')).toEqual(['-i', '-l']);
+  });
+
+  test('cmd.exe takes neither flag', () => {
+    expect(shellArgs('win32')).toEqual([]);
+  });
+});
+
+describe('shellLaunch', () => {
+  test('re-acquires the controlling terminal before exec on POSIX', () => {
+    // Without this, a detached child has no controlling tty and the shell
+    // silently disables job control.
+    const argv = shellLaunch('/bin/zsh', 'darwin');
+    expect(argv[0]).toBe('/bin/sh');
+    expect(argv[1]).toBe('-c');
+    expect(argv[2]).toContain('tty');
+    expect(argv[2]).toContain('exec /bin/zsh -i -l');
+    // `exec` matters: it keeps the pid, so the shell stays the session leader
+    // and a group signal still reaches everything it starts.
+    expect(argv[2].match(/exec /g)?.length).toBe(2);
+  });
+
+  test('runs the shell directly on windows', () => {
+    expect(shellLaunch('cmd.exe', 'win32')).toEqual(['cmd.exe']);
+  });
+});
+
+describe('terminalEnv', () => {
+  test('describes the renderer and theme to the child', () => {
+    const env = terminalEnv({ PATH: '/usr/bin', COLORFGBG: 'stale' }, 'light');
+    expect(env.TERM).toBe('xterm-256color');
+    expect(env.COLORTERM).toBe('truecolor');
+    expect(env.COLORFGBG).toBe('0;15');
+    expect(env.PATH).toBe('/usr/bin');
+  });
+
+  test('drops the chamber IPC descriptor', () => {
+    // An inherited NODE_CHANNEL_FD makes Node CLIs print IPC parse errors.
+    const env = terminalEnv({ NODE_CHANNEL_FD: '3' }, 'dark');
+    expect('NODE_CHANNEL_FD' in env).toBe(false);
+    expect(env.COLORFGBG).toBe('15;0');
+  });
+});
+
+describe('resolveShellExecutable', () => {
+  test('returns the first candidate that exists', async () => {
+    const checked: string[] = [];
+    const resolved = await resolveShellExecutable(['/nope/zsh', '/bin/bash'], async (target) => {
+      checked.push(target);
+      return target === '/bin/bash';
+    });
+    expect(resolved).toBe('/bin/bash');
+    expect(checked).toEqual(['/nope/zsh', '/bin/bash']);
+  });
+
+  test('reports no shell when nothing exists', async () => {
+    expect(await resolveShellExecutable(['/nope'], async () => false)).toBeNull();
+  });
+});