@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/bridge/server.ts

@@ -14,68 +14,151 @@
 import * as fs from 'fs';
 import * as net from 'net';
 import * as path from 'path';
-import { getBrowserClient } from '../targets.js';
+import { getBrowserClient, findTabById } from '../targets.js';
 import { type CDPClient } from '../client.js';
 import { type BridgeRequest, type BridgeResponse } from './protocol.js';
 
 interface EventWaiter {
-  resolve: (v: unknown) => void;
+  resolve: (value: unknown) => void;
 }
 
-class EventBroker {
-  private queues = new Map<string, unknown[]>();
-  private waiters = new Map<string, EventWaiter[]>();
+export interface EventWait {
+  /** Returns the event or throws its timeout. The broker observes timeouts internally until this is called, so a slow triggering method cannot create an unhandled rejection. */
+  result(): Promise<unknown>;
+  /** Removes and settles this waiter without affecting any other waiter. */
+  cancel(): void;
+}
+
+type EventWaitOutcome =
+  | { kind: 'event'; value: unknown }
+  | { kind: 'timeout'; error: Error }
+  | { kind: 'cancelled' };
+
+/**
+ * Observes future CDP events on one long-lived client. Waiters are scoped by
+ * the event envelope's actual flattened session id (including `undefined`
+ * for an unscoped event). An event is dropped when no exact-key waiter is
+ * armed, and otherwise broadcasts to every waiter already armed for that
+ * key. The broker never retains event history.
+ */
+export class EventBroker {
+  private waiters = new Map<string, Map<string | undefined, Set<EventWaiter>>>();
   private listening = new Set<string>();
 
-  constructor(private client: CDPClient) {}
+  constructor(private client: Pick<CDPClient, 'on'>) {}
 
   private ensureListening(eventName: string): void {
     if (this.listening.has(eventName)) return;
     this.listening.add(eventName);
-    this.client.on(eventName, (params) => {
-      const waiters = this.waiters.get(eventName);
-      if (waiters && waiters.length > 0) {
-        waiters.shift()!.resolve(params);
-        return;
-      }
-      const q = this.queues.get(eventName) ?? [];
-      q.push(params);
-      // Cap the buffer so an event nobody ever asks for can't leak memory.
-      if (q.length > 50) q.shift();
-      this.queues.set(eventName, q);
+    this.client.on(eventName, (params, actualSessionId) => {
+      const bySession = this.waiters.get(eventName);
+      const matching = bySession?.get(actualSessionId);
+      if (!matching || matching.size === 0) return;
+
+      // Remove the exact bucket before resolving its snapshot. A waiter armed
+      // by a resolution continuation is therefore future-only and cannot
+      // observe the event currently being broadcast.
+      bySession!.delete(actualSessionId);
+      if (bySession!.size === 0) this.waiters.delete(eventName);
+      for (const waiter of matching) waiter.resolve(params);
     });
   }
 
-  wait(eventName: string, timeoutMs: number): Promise<unknown> {
+  wait(eventName: string, sessionId: string | undefined, timeoutMs: number): EventWait {
     this.ensureListening(eventName);
-    const q = this.queues.get(eventName);
-    if (q && q.length > 0) {
-      return Promise.resolve(q.shift());
+    let bySession = this.waiters.get(eventName);
+    if (!bySession) {
+      bySession = new Map();
+      this.waiters.set(eventName, bySession);
+    }
+    let matching = bySession.get(sessionId);
+    if (!matching) {
+      matching = new Set();
+      bySession.set(sessionId, matching);
     }
-    return new Promise((resolve, reject) => {
-      const list = this.waiters.get(eventName) ?? [];
-      const entry: EventWaiter = {
-        resolve: (v) => {
-          clearTimeout(timer);
-          resolve(v);
-        },
-      };
-      const timer = setTimeout(() => {
-        const current = this.waiters.get(eventName);
-        if (current) {
-          const idx = current.indexOf(entry);
-          if (idx >= 0) current.splice(idx, 1);
-        }
-        reject(new Error(`Timed out after ${timeoutMs}ms waiting for event "${eventName}"`));
-      }, timeoutMs);
-      list.push(entry);
-      this.waiters.set(eventName, list);
+
+    let settleOutcome!: (outcome: EventWaitOutcome) => void;
+    const outcome = new Promise<EventWaitOutcome>((resolve) => {
+      settleOutcome = resolve;
     });
+    let settled = false;
+    const removeOnlyThisWaiter = (): void => {
+      const currentBySession = this.waiters.get(eventName);
+      const current = currentBySession?.get(sessionId);
+      if (!current) return;
+      current.delete(waiter);
+      if (current.size === 0) currentBySession!.delete(sessionId);
+      if (currentBySession!.size === 0) this.waiters.delete(eventName);
+    };
+    const waiter: EventWaiter = {
+      resolve: (value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        settleOutcome({ kind: 'event', value });
+      },
+    };
+    matching.add(waiter);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      removeOnlyThisWaiter();
+      settleOutcome({
+        kind: 'timeout',
+        error: new Error(
+          `Timed out after ${timeoutMs}ms waiting for event "${eventName}"` +
+            (sessionId === undefined ? ' without a session' : ` in session "${sessionId}"`),
+        ),
+      });
+    }, timeoutMs);
+
+    return {
+      result: async () => {
+        const settledOutcome = await outcome;
+        if (settledOutcome.kind === 'timeout') throw settledOutcome.error;
+        return settledOutcome.kind === 'event' ? settledOutcome.value : undefined;
+      },
+      cancel: () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        removeOnlyThisWaiter();
+        settleOutcome({ kind: 'cancelled' });
+      },
+    };
+  }
+}
+
+export async function handleBridgeRequest(
+  req: BridgeRequest,
+  client: Pick<CDPClient, 'send'>,
+  events: EventBroker,
+  attach: (targetId: string) => Promise<string>,
+): Promise<BridgeResponse> {
+  let eventWait: EventWait | undefined;
+  try {
+    const sessionId = req.targetId ? await attach(req.targetId) : undefined;
+    eventWait = req.waitEvent
+      ? events.wait(req.waitEvent, sessionId, req.timeoutMs ?? 10000)
+      : undefined;
+    const result = req.method
+      ? await client.send(req.method, req.params ?? {}, 60000, sessionId)
+      : undefined;
+    const event = eventWait ? await eventWait.result() : undefined;
+    return { reqId: req.reqId, ok: true, result, event };
+  } catch (err) {
+    eventWait?.cancel();
+    return {
+      reqId: req.reqId,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
   }
 }
 
 export async function runBridgeServer(socketPath: string, port?: number): Promise<void> {
-  const { client } = await getBrowserClient(await resolvePort(port));
+  const resolvedPort = await resolvePort(port);
+  const { client } = await getBrowserClient(resolvedPort);
   const events = new EventBroker(client);
 
   // Cache flattened Target.attachToTarget sessions so repeated requests
@@ -85,19 +168,78 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
   async function attach(targetId: string): Promise<string> {
     const cached = targetSessions.get(targetId);
     if (cached) return cached;
-    const result = (await client.send('Target.attachToTarget', { targetId, flatten: true })) as {
+    // Accept the same 8-char-prefix targeting every other capture command
+    // promises (see the top-level --help TARGETING section) instead of
+    // requiring the full 32-char target id here.
+    const tab = await findTabById(resolvedPort, targetId);
+    if (!tab) {
+      throw new Error(`No target found for "${targetId}" on port ${resolvedPort}. Run "capture tab list" to see available tabs.`);
+    }
+    const result = (await client.send('Target.attachToTarget', { targetId: tab.id, flatten: true })) as {
       sessionId: string;
     };
     targetSessions.set(targetId, result.sessionId);
     return result.sessionId;
   }
 
+  async function handleLine(line: string, socket: net.Socket): Promise<void> {
+    let req: BridgeRequest;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const resp = await handleBridgeRequest(req, client, events, attach);
+    socket.write(JSON.stringify(resp) + '\n');
+  }
+
+  const server = await listenNdjsonSocket(socketPath, handleLine);
+
+  const cleanup = (): void => {
+    closeNdjsonSocket(server, socketPath);
+    try {
+      client.close();
+    } catch {
+      // Already closed.
+    }
+  };
+  installProcessCleanup(cleanup, client);
+  // Intentionally does not resolve further work here: the open server and
+  // the live websocket keep the event loop (and this detached process) alive
+  // until `stopBridge()` sends SIGTERM.
+}
+
+/**
+ * Ensures `socketPath`'s parent directory exists and removes any stale
+ * socket file left at that path (a previous bridge process that died
+ * without cleaning up). Shared preparation step before binding a new
+ * `net.Server` there.
+ */
+export function prepareSocketPath(socketPath: string): void {
   fs.mkdirSync(path.dirname(socketPath), { recursive: true });
   try {
     fs.unlinkSync(socketPath);
   } catch {
     // No stale socket to remove.
   }
+}
+
+/**
+ * Binds a Unix-domain `net.Server` at `socketPath` that frames each
+ * connection's input as newline-delimited JSON, invoking `handleLine` once
+ * per complete line. This is the wire framing every bridge mode (plain
+ * browser-level bridge, recorder bridge) shares — "one request per
+ * connection, one response, then the socket closes" is a convention the
+ * caller's `handleLine` implements by writing exactly one response per
+ * line and letting the client end the connection; the server itself is
+ * agnostic to that convention and would happily frame a connection that
+ * sends multiple lines.
+ */
+export async function listenNdjsonSocket(
+  socketPath: string,
+  handleLine: (line: string, socket: net.Socket) => void | Promise<void>,
+): Promise<net.Server> {
+  prepareSocketPath(socketPath);
 
   const server = net.createServer((socket) => {
     let buffer = '';
@@ -112,43 +254,36 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     });
   });
 
-  async function handleLine(line: string, socket: net.Socket): Promise<void> {
-    let req: BridgeRequest;
-    try {
-      req = JSON.parse(line);
-    } catch {
-      return;
-    }
-    let resp: BridgeResponse;
-    try {
-      const sessionId = req.targetId ? await attach(req.targetId) : undefined;
-      const eventPromise = req.waitEvent ? events.wait(req.waitEvent, req.timeoutMs ?? 10000) : undefined;
-      const result = req.method ? await client.send(req.method, req.params ?? {}, 60000, sessionId) : undefined;
-      const event = eventPromise ? await eventPromise : undefined;
-      resp = { reqId: req.reqId, ok: true, result, event };
-    } catch (err) {
-      resp = { reqId: req.reqId, ok: false, error: err instanceof Error ? err.message : String(err) };
-    }
-    socket.write(JSON.stringify(resp) + '\n');
+  await new Promise<void>((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(socketPath, () => resolve());
+  });
+  return server;
+}
+
+/** Closes the socket server and best-effort unlinks the socket file. */
+export function closeNdjsonSocket(server: net.Server, socketPath: string): void {
+  try {
+    server.close();
+  } catch {
+    // Already closed.
   }
+  try {
+    fs.unlinkSync(socketPath);
+  } catch {
+    // Already gone.
+  }
+}
 
-  const cleanup = (): void => {
-    try {
-      server.close();
-    } catch {
-      // Already closed.
-    }
-    try {
-      client.close();
-    } catch {
-      // Already closed.
-    }
-    try {
-      fs.unlinkSync(socketPath);
-    } catch {
-      // Already gone.
-    }
-  };
+/**
+ * Wires SIGTERM/SIGINT and the held client's disconnect into one `cleanup`
+ * call followed by `process.exit(0)` — the shutdown sequence every
+ * detached bridge process (plain or recorder) uses.
+ */
+export function installProcessCleanup(
+  cleanup: () => void,
+  client: Pick<CDPClient, 'onDisconnect'>,
+): void {
   process.on('SIGTERM', () => {
     cleanup();
     process.exit(0);
@@ -162,14 +297,6 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     cleanup();
     process.exit(0);
   });
-
-  await new Promise<void>((resolve, reject) => {
-    server.on('error', reject);
-    server.listen(socketPath, () => resolve());
-  });
-  // Intentionally does not resolve further work here: the open server and
-  // the live websocket keep the event loop (and this detached process) alive
-  // until `stopBridge()` sends SIGTERM.
 }
 
 async function resolvePort(port?: number): Promise<number> {

package/src/cdp/bridge/spawn.ts

@@ -5,13 +5,47 @@
  */
 
 import { spawn } from 'child_process';
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
+import { CAPTURE_ROOT, ensurePrivateDir } from '../../session/artifacts.js';
 
 export function bridgeSocketPath(sessionDir: string): string {
   return path.join(sessionDir, 'bridge.sock');
 }
 
+/**
+ * Fixed, short, private (`0700`) directory every recorder socket lives in — flat, and
+ * deliberately NOT nested under a recording's (long) artifact dir. macOS caps `AF_UNIX`
+ * pathnames at ~104 bytes; a real recording dir (`{CAPTURE_ROOT}/{session}/motion/recs/{recId}`)
+ * combined with `os.tmpdir()`'s own (often long, per-user) prefix can already exceed that before
+ * adding a filename, so the socket can never live inside `recDir` — see `recorderSocketPath()`.
+ */
+function recorderSocketDir(): string {
+  return ensurePrivateDir(path.join(CAPTURE_ROOT, 'sock'));
+}
+
+/**
+ * A short, fixed-length filename deterministically derived from `recDir` (not from `recDir`'s
+ * own length/depth), so the resulting socket path stays bounded regardless of how deep the
+ * recording's session/motion/recs nesting is.
+ */
+function shortSocketName(recDir: string): string {
+  return crypto.createHash('sha1').update(path.resolve(recDir)).digest('hex').slice(0, 16);
+}
+
+/**
+ * The recorder bridge's own socket path. Lives in the short, flat `recorderSocketDir()` — NOT
+ * inside `recDir` (the long, deep artifact directory `frames`/`events.jsonl`/etc. write into) —
+ * so binding it never risks exceeding the platform's `AF_UNIX` pathname limit. `recDir` is still
+ * required by every recorder-mode caller (spawn args, artifact writers); this function only
+ * derives the socket's own location from it, deterministically, without embedding `recDir` in
+ * the path itself.
+ */
+export function recorderSocketPath(recDir: string): string {
+  return path.join(recorderSocketDir(), `${shortSocketName(recDir)}.sock`);
+}
+
 export async function startBridge(
   sessionDir: string,
   port: number,
@@ -36,9 +70,13 @@ export async function startBridge(
   const start = Date.now();
   while (!fs.existsSync(socketPath)) {
     if (Date.now() - start > timeoutMs) {
+      // Own the child we spawned: a bridge that never signalled readiness is
+      // ours to reap before we reject, so no orphaned process outlives the
+      // failed start. Mirrors startRecorderBridge()'s ownership discipline.
+      stopBridge(pid, socketPath);
       throw new Error(
         `CDP bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
-          `Check that a browser is reachable on port ${port} (capture detect).`,
+          `Check that a browser is reachable on port ${port} (capture tab list --port ${port}).`,
       );
     }
     await new Promise((r) => setTimeout(r, 50));
@@ -63,3 +101,74 @@ export function stopBridge(pid: number | null | undefined, socketPath: string |
     }
   }
 }
+
+/**
+ * Spawns the same detached `__bridge-serve` entrypoint in recorder mode:
+ * it connects to one tab (`targetId`) instead of the browser level, and
+ * drives `capture motion rec`'s screencast/tracing/observers instead of
+ * proxying arbitrary `--browser` CDP calls. Mirrors `startBridge()`'s
+ * spawn + "wait for the socket file to appear" pattern; the caller
+ * (U14's lifecycle routing) tears it down with the same `stopBridge()`
+ * used for the plain held bridge.
+ *
+ * Recorder mode is selected via a positional (`recorder <recDir> <harId>`)
+ * rather than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is
+ * not owned by this unit, but `positional` is already generic passthrough.
+ *
+ * `harId` is the owning session's live HAR recording id (`.session.json`'s
+ * `harId`) — the recorder bridge installs a streaming `HARRecorder` on its
+ * held tab connection and appends network evidence to that store, so the id
+ * must travel to the spawned process. Required: a session-backed recorder
+ * always has one (the caller throws before spawning if it doesn't).
+ *
+ * The socket-file readiness poll below doubles as the nonce-boot-file
+ * guarantee: the recorder writes `{recDir}/recorder-nonce.json` BEFORE it
+ * binds the socket (see `../recorder-bridge.ts`), so once this resolves the
+ * caller can read the nonce without racing the child.
+ */
+export async function startRecorderBridge(
+  socketPath: string,
+  port: number,
+  targetId: string,
+  recDir: string,
+  harId: string,
+  timeoutMs = 5000,
+): Promise<{ socketPath: string; pid: number }> {
+  const scriptPath = process.argv[1];
+  const child = spawn(
+    process.execPath,
+    [
+      scriptPath,
+      '__bridge-serve',
+      '--socket',
+      socketPath,
+      '--port',
+      String(port),
+      '--target',
+      targetId,
+      'recorder',
+      recDir,
+      harId,
+    ],
+    { detached: true, stdio: 'ignore' },
+  );
+  child.unref();
+  const pid = child.pid;
+  if (!pid) {
+    throw new Error('Failed to spawn recorder bridge process.');
+  }
+
+  const start = Date.now();
+  while (!fs.existsSync(socketPath)) {
+    if (Date.now() - start > timeoutMs) {
+      stopBridge(pid, socketPath);
+      throw new Error(
+        `Recorder bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
+          `Check that target "${targetId}" is reachable on port ${port}.`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  return { socketPath, pid };
+}

package/src/cdp/client.ts

@@ -8,7 +8,7 @@ export class CDPClient {
     { resolve: (v: unknown) => void; reject: (e: Error) => void }
   >();
   private pendingTimeouts = new Map<number, NodeJS.Timeout>();
-  private eventHandlers = new Map<string, Array<(params: unknown) => void>>();
+  private eventHandlers = new Map<string, Array<(params: unknown, sessionId?: string) => void>>();
   private ready: Promise<void>;
 
   constructor(wsUrl: string, connectTimeout = 5000) {
@@ -47,7 +47,7 @@ export class CDPClient {
         }
       } else if (msg.method) {
         const handlers = this.eventHandlers.get(msg.method);
-        handlers?.forEach((h) => h(msg.params));
+        handlers?.forEach((handler) => handler(msg.params, msg.sessionId));
       }
     });
   }
@@ -80,13 +80,23 @@ export class CDPClient {
     });
   }
 
-  on(event: string, handler: (params: unknown) => void): void {
+  /** Registers an event callback. The second argument is the actual optional `sessionId` from a flattened CDP event envelope; it is never inferred from the method or params. */
+  on(event: string, handler: (params: unknown, sessionId?: string) => void): void {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, []);
     }
     this.eventHandlers.get(event)!.push(handler);
   }
 
+  /** Unregisters a handler previously added with {@link on}. Required so one-shot event consumers (e.g. the `LayerTree.layerTreeDidChange` collector) can remove their listener on settle/timeout instead of leaking a retained closure for the connection's lifetime. */
+  off(event: string, handler: (params: unknown, sessionId?: string) => void): void {
+    const handlers = this.eventHandlers.get(event);
+    if (!handlers) return;
+    const index = handlers.indexOf(handler);
+    if (index !== -1) handlers.splice(index, 1);
+    if (handlers.length === 0) this.eventHandlers.delete(event);
+  }
+
   /** Fires when the underlying websocket goes away (browser closed, crashed, CDP endpoint dropped). */
   onDisconnect(handler: () => void): void {
     this.ws.on('close', handler);

package/src/cdp/commands/bridge-serve.ts

@@ -1,16 +1,47 @@
 import { runBridgeServer } from '../bridge/server.js';
+import { runRecorderBridge } from '../recorder-bridge.js';
+import { invalidInput } from '../../errors.js';
 import { type ParsedArgs } from '../types.js';
 
 /**
  * Hidden entrypoint spawned detached by `capture session start --hold`
- * (see `bridge/spawn.ts`). Not documented in `capture --help` \u2014 nothing
- * calls this directly.
+ * (see `bridge/spawn.ts`'s `startBridge()`) or by `capture motion rec
+ * --start` in recorder mode (`startRecorderBridge()`). Not documented in
+ * `capture --help` — nothing calls this directly.
+ *
+ * Recorder mode is selected by a `recorder <recDir> <harId>` positional
+ * rather than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't
+ * owned by this unit but `parsed.positional` is already generic passthrough:
+ *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>
+ *
+ * Usage errors throw the repo's structured `CaptureError` — the root
+ * boundary in `src/capture.ts` renders it via `failureResult()` and exits
+ * nonzero, same as every other command leaf.
  */
 export async function cmdBridgeServe(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (!parsed.socket) {
-    console.error('Usage: capture __bridge-serve --socket <path> [--port <cdpPort>]');
-    process.exit(1);
+    throw invalidInput(
+      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir> <harId>]',
+      'bridge_serve_usage',
+    );
   }
+
+  if (parsed.positional[0] === 'recorder') {
+    const recDir = parsed.positional[1];
+    const harId = parsed.positional[2];
+    if (!parsed.target || !recDir || !harId) {
+      throw invalidInput(
+        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir> <harId>',
+        'bridge_serve_usage',
+      );
+    }
+    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir, harId });
+    // Deliberately does not exit: the open Unix socket server and the live
+    // tab websocket keep this detached process alive until an authenticated
+    // `rec-stop` completes (self-exit) or the caller escalates with SIGTERM.
+    return;
+  }
+
   await runBridgeServer(parsed.socket, parsed.port);
   // Deliberately does not exit: the open Unix socket server and the live
   // browser websocket keep this detached process alive until `session stop`