ompchamber 0.8.0 → 1.1.0

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();
+  });
+});

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

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which shell the PTY runtime launches, with which argv, and with which
+ * environment.
+ *
+ * Resolution is a pure function of the environment plus an existence probe, so
+ * the preference order stays testable without spawning anything: the user's
+ * `$SHELL` first, then the platform's usual suspects.
+ */
+
+const POSIX_FALLBACKS = ['/bin/zsh', '/bin/bash', '/bin/sh'];
+
+/** Candidate executables, most preferred first. */
+export function shellCandidates(
+  env: Record<string, string | undefined> = Bun.env,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  if (platform === 'win32') {
+    const comspec = env.COMSPEC?.trim();
+    return comspec ? [comspec] : ['cmd.exe'];
+  }
+  const candidates: string[] = [];
+  const preferred = env.SHELL?.trim();
+  // Only an absolute $SHELL is trusted: a bare name would be resolved against
+  // PATH at spawn time, which is not the login shell the user configured.
+  if (preferred && preferred.startsWith('/')) candidates.push(preferred);
+  for (const fallback of POSIX_FALLBACKS) {
+    if (!candidates.includes(fallback)) candidates.push(fallback);
+  }
+  return candidates;
+}
+
+/**
+ * `-i -l` for POSIX shells: interactive (prompt, line editing, job control —
+ * job control is what makes Ctrl+Z/`fg` work at all) and login (the user's
+ * profile, so PATH and aliases match a normal terminal). cmd.exe takes neither.
+ */
+export function shellArgs(platform: NodeJS.Platform = process.platform): string[] {
+  return platform === 'win32' ? [] : ['-i', '-l'];
+}
+
+/**
+ * Full argv for the PTY child.
+ *
+ * POSIX shells are launched through a one-line `/bin/sh` shim that re-acquires
+ * the PTY as its controlling terminal before `exec`-ing the real shell:
+ *
+ *     T=$(tty); exec <shell> -i -l <"$T" >"$T" 2>&1
+ *
+ * This is required, not cosmetic. The runtime must spawn with
+ * `detached: true` — without it the child lands in the *server's* process
+ * group, where a group signal would take the chamber down and `SIGWINCH`
+ * cannot be addressed to the shell alone. But `setsid()` also drops the
+ * controlling terminal, and a shell with no controlling tty silently disables
+ * job control (`setopt monitor` fails): Ctrl+Z, `fg` and `jobs` stop working,
+ * and typing while a foreground command runs goes to that command instead of
+ * the shell. Opening the slave device as stdin/stdout restores it. Verified on
+ * macOS: with the shim `tpgid` is the shell's own pid and Ctrl+Z suspends;
+ * without it `tpgid` is 0 and Ctrl+Z is swallowed.
+ *
+ * `exec` keeps the pid, so the shell stays the session leader and group kill
+ * still reaches everything it starts. If `tty` fails the shell runs
+ * unredirected — stdio is already the PTY, only job control is lost.
+ */
+export function shellLaunch(executable: string, platform: NodeJS.Platform = process.platform): string[] {
+  if (platform === 'win32') return [executable];
+  const inner = [executable, ...shellArgs(platform)].join(' ');
+  return ['/bin/sh', '-c', `T=$(tty 2>/dev/null); [ -n "$T" ] && exec ${inner} <"$T" >"$T" 2>&1; exec ${inner}`];
+}
+
+/**
+ * Environment for the PTY child. `TERM`/`COLORTERM` describe the renderer on
+ * the other end of the socket; `COLORFGBG` carries the active chamber theme so
+ * prompts that read it (zsh themes, vim) pick readable colors.
+ */
+export function terminalEnv(
+  base: Record<string, string | undefined>,
+  theme: 'light' | 'dark' = 'dark',
+): Record<string, string | undefined> {
+  const env: Record<string, string | undefined> = { ...base };
+  // The chamber's own IPC descriptor is host-private and meaningless inside the
+  // PTY; an inherited value makes Node CLIs fail to parse their IPC channel.
+  delete env.NODE_CHANNEL_FD;
+  env.TERM = 'xterm-256color';
+  env.COLORTERM = 'truecolor';
+  env.COLORFGBG = theme === 'light' ? '0;15' : '15;0';
+  return env;
+}
+
+/** First candidate that exists on disk, or null when none does. */
+export async function resolveShellExecutable(
+  candidates: string[],
+  exists: (target: string) => Promise<boolean> = async (target) => Bun.file(target).exists(),
+): Promise<string | null> {
+  for (const candidate of candidates) {
+    if (await exists(candidate)) return candidate;
+  }
+  return null;
+}

package/src/server/routes/fs/git.ts

@@ -5,6 +5,7 @@ import { resolveRoot } from '@/server/lib/fs/root';
 import { runShell } from '@/server/lib/fs/shell';
 import { fetchFileDiff, fetchGitCommits } from '@/server/lib/fs/git-log';
 import { fetchWorkingFileDiff } from '@/server/lib/fs/git-diff';
+import { gitSyncCount, invalidateRemoteRefs, markRemoteRefsFresh, refreshRemoteRefs } from '@/server/lib/fs/git-sync';
 
 const MAX_GIT_DEPTH = 8;
 
@@ -117,7 +118,17 @@ export async function loader({ request }: LoaderFunctionArgs) {
     });
   }
 
+  // Ahead/behind are only requested by the git panel (`?sync=1`); the
+  // status-only polls (activity bar, file explorer) must not trigger a network
+  // fetch, and must not pay for a count they never read.
+  const syncRequested = url.searchParams.get('sync') === '1';
+
   try {
+    // Started before the local probes below so the fetch overlaps them instead
+    // of adding up; TTL'd inside the helper, so the panel's 5s poll is not a 5s
+    // fetch loop.
+    const remoteRefresh = syncRequested ? refreshRemoteRefs(targetDir) : Promise.resolve();
+
     // Use --porcelain=v1 -uall so all individual edited/untracked files are listed
     const statusOut = (await runShell('git status --porcelain=v1 -uall', { cwd: targetDir, maxBuffer: 1024 * 1024 })).stdout;
 
@@ -167,18 +178,8 @@ export async function loader({ request }: LoaderFunctionArgs) {
         };
       });
 
-    // `git rev-list --left-right --count HEAD...@{upstream}` prints "<ahead>\t<behind>".
-    let syncCount = { ahead: 0, behind: 0 };
-    try {
-      const syncOut = await runShell(
-        'git rev-list --left-right --count HEAD...@{upstream}',
-        { cwd: targetDir, timeout: 8000 }
-      );
-      const [ahead, behind] = syncOut.stdout.trim().split(/\s+/).map(Number);
-      syncCount = { ahead: ahead || 0, behind: behind || 0 };
-    } catch {
-      // No upstream configured — nothing to sync against.
-    }
+    await remoteRefresh;
+    const syncCount = syncRequested ? await gitSyncCount(targetDir) : undefined;
 
     return json({
       changes,
@@ -262,9 +263,13 @@ export async function action({ request }: ActionFunctionArgs) {
           await expectOk(`git checkout -b "${localName}" --track "${branch}"`, targetDir);
         }
       }
+      // The counts are per-branch: the refs the previous branch refreshed say
+      // nothing about the new one's upstream.
+      invalidateRemoteRefs(targetDir);
     } else if (actionType === 'create_branch') {
       const branch = formData.get('branch') as string;
       await expectOk(`git checkout -b "${branch}"`, targetDir);
+      invalidateRemoteRefs(targetDir);
     } else if (actionType === 'history' || actionType === 'graph') {
       const limit = parseInt((formData.get('limit') as string) || '50', 10);
       const skip = parseInt((formData.get('skip') as string) || '0', 10);
@@ -306,11 +311,16 @@ export async function action({ request }: ActionFunctionArgs) {
       await expectOk(`git rebase "${hash}"`, targetDir);
     } else if (actionType === 'push') {
       await expectOk('git push', targetDir, 120000);
+      markRemoteRefsFresh(targetDir);
     } else if (actionType === 'pull') {
       await expectOk('git pull --ff-only', targetDir, 120000);
+      markRemoteRefsFresh(targetDir);
     } else if (actionType === 'sync') {
       await expectOk('git pull --ff-only', targetDir, 120000);
       await expectOk('git push', targetDir, 120000);
+      // Both commands already moved the tracking ref; the next poll must not
+      // fetch again to see a state it just produced.
+      markRemoteRefsFresh(targetDir);
     }
     return json({ success: true });
   } catch (error: any) {

package/src/server/routes/index.ts

@@ -10,6 +10,7 @@ import { foldersBindings } from '@/server/routes/folders';
 import { filesBindings } from '@/server/routes/files';
 import { telemetryBindings } from '@/server/routes/telemetry';
 import { terminalBindings } from '@/server/routes/terminal';
+import { terminalWsRoutes } from '@/server/routes/terminal/ws';
 import { browserBindings } from '@/server/routes/browser';
 import { modelsBindings } from '@/server/routes/models';
 import { ompBindings } from '@/server/routes/omp';
@@ -35,4 +36,4 @@ const allBindings: HandlerBinding[] = [
   ...wellKnownBindings,
 ];
 
-export const apiRoutes = mountBindings(new Elysia(), allBindings).use(agentWsRoutes);
+export const apiRoutes = mountBindings(new Elysia(), allBindings).use(agentWsRoutes).use(terminalWsRoutes);