Browser Trace

MIT License

Copyright (c) 2026 Browserbase, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

{
  "name": "browser-trace",
  "version": "0.1.0",
  "private": true,
  "type": "module"
}

#!/usr/bin/env node
// Start an observability capture against a Browserbase session.
//
// Usage:
//   node scripts/bb-capture.mjs --new [run-id] [interval-seconds]
//   node scripts/bb-capture.mjs <session-id> [run-id] [interval-seconds]
//
// Env:
//   BROWSERBASE_API_KEY   required
//   BB_SESSION_TIMEOUT    timeout for --new sessions, seconds (default: 600)
//   O11Y_ROOT, O11Y_DOMAINS — same as start-capture.mjs

import path from 'node:path';
import { spawnSync } from 'node:child_process';
import { fileURLToPath } from 'node:url';

import { runDir, readJson, writeJson, runCmd } from './lib.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

if (!process.env.BROWSERBASE_API_KEY) {
  console.error('BROWSERBASE_API_KEY must be set');
  process.exit(1);
}

const [target, runIdArg, intervalArg] = process.argv.slice(2);
if (!target) {
  console.error('usage: bb-capture.mjs --new|<session-id> [run-id] [interval-seconds]');
  process.exit(2);
}

let sessionJson;
if (target === '--new') {
  const timeout = String(process.env.BB_SESSION_TIMEOUT || '600');
  const r = runCmd('browse', ['cloud', 'sessions', 'create', '--keep-alive', '--timeout', timeout]);
  if (!r.ok) { console.error(r.stderr || 'browse cloud sessions create failed'); process.exit(1); }
  sessionJson = JSON.parse(r.stdout);
  console.log(`Created Browserbase session: ${sessionJson.id}`);
} else {
  const r = runCmd('browse', ['cloud', 'sessions', 'get', target]);
  if (!r.ok) { console.error(r.stderr || 'browse cloud sessions get failed'); process.exit(1); }
  sessionJson = JSON.parse(r.stdout);
  if (sessionJson.status !== 'RUNNING') {
    console.error(`Session ${target} is not RUNNING (status=${sessionJson.status}). Recreate with --keep-alive.`);
    process.exit(1);
  }
}

const sessionId = sessionJson.id;
const connectUrl = sessionJson.connectUrl;

let debugJson = null;
const dbg = runCmd('browse', ['cloud', 'sessions', 'debug', sessionId]);
if (dbg.ok) {
  try { debugJson = JSON.parse(dbg.stdout); } catch {}
}

// Hand off to start-capture.mjs as a child process so it owns its own
// detached background processes (cdp + snapshot loop).
const startScript = path.join(__dirname, 'start-capture.mjs');
const startArgs = [startScript, connectUrl];
if (runIdArg)   startArgs.push(runIdArg);
if (intervalArg) startArgs.push(intervalArg);

const start = spawnSync(process.execPath, startArgs, { stdio: ['ignore', 'pipe', 'inherit'] });
if (start.status !== 0) process.exit(start.status ?? 1);

// start-capture writes a status block to stdout; surface it minus the noisy
// signed connectUrl, then add the BB-specific lines.
const lines = start.stdout.toString().split('\n').filter(l => l && !l.startsWith('target='));
for (const l of lines) console.log(l);

// Patch the manifest with Browserbase metadata so traversal queries can later
// join CDP events back to platform info (region, debugger URL, project, etc.).
const runId = (lines.find(l => l.startsWith('run_id=')) || '').slice('run_id='.length);
if (!runId) { console.error('could not parse run_id from start-capture output'); process.exit(1); }

const manifestPath = path.join(runDir(runId), 'manifest.json');
const manifest = readJson(manifestPath, {});
const debuggerUrl = debugJson?.debuggerFullscreenUrl ?? debugJson?.debuggerUrl ?? null;

manifest.browserbase = {
  session_id:   sessionJson.id,
  project_id:   sessionJson.projectId,
  region:       sessionJson.region,
  started_at:   sessionJson.startedAt,
  expires_at:   sessionJson.expiresAt,
  keep_alive:   sessionJson.keepAlive,
  debugger_url: debuggerUrl,
};
writeJson(manifestPath, manifest);

if (debuggerUrl) console.log(`Live debugger: ${debuggerUrl}`);
console.log(`session_id=${sessionId}`);
console.log(`connect_url=${(connectUrl || '').slice(0, 60)}…`);

#!/usr/bin/env node
// After stop-capture.mjs, pull final Browserbase-side artifacts (session
// metadata, server logs, downloads) into the run dir. Logs are best-effort —
// they're often sparse.
//
// Usage:
//   node scripts/bb-finalize.mjs <run-id> [--release]
//
//   --release  send `browse cloud sessions update --status REQUEST_RELEASE` after
//              finalizing (use only when this run owns the session).

import fs from 'node:fs';
import path from 'node:path';

import { runDir, readJson, ensureDir, runCmd } from './lib.mjs';

if (!process.env.BROWSERBASE_API_KEY) {
  console.error('BROWSERBASE_API_KEY must be set');
  process.exit(1);
}

const [runId, ...rest] = process.argv.slice(2);
if (!runId) {
  console.error('usage: bb-finalize.mjs <run-id> [--release]');
  process.exit(2);
}
const release = rest.includes('--release');

const RD = runDir(runId);
const manifestPath = path.join(RD, 'manifest.json');
const manifest = readJson(manifestPath);
if (!manifest) {
  console.error(`manifest not found at ${RD}`);
  process.exit(1);
}

const sessionId = manifest?.browserbase?.session_id;
if (!sessionId) {
  console.error('manifest has no .browserbase.session_id — was this run captured via bb-capture.mjs?');
  process.exit(1);
}

const bbDir = path.join(RD, 'browserbase');
ensureDir(bbDir);

// Final session metadata — proxyBytes, status, ended_at all settle here.
{
  const r = runCmd('browse', ['cloud', 'sessions', 'get', sessionId]);
  if (r.ok) {
    fs.writeFileSync(path.join(bbDir, 'session.json'), r.stdout);
    console.log('wrote session.json');
  } else {
    console.error('warn: browse cloud sessions get failed');
  }
}

// Server-side logs. Often empty — the firehose in cdp/raw.ndjson is the source of truth.
{
  const r = runCmd('browse', ['cloud', 'sessions', 'logs', sessionId]);
  if (r.ok) {
    fs.writeFileSync(path.join(bbDir, 'logs.json'), r.stdout);
    let n = '?';
    try { n = String(JSON.parse(r.stdout).length ?? '?'); } catch {}
    console.log(`wrote logs.json (${n} entries)`);
  }
}

// Downloads. An empty session yields a 22-byte EOCD-only zip; any real
// content is always larger.
{
  const out = path.join(bbDir, 'downloads.zip');
  const r = runCmd('browse', ['cloud', 'sessions', 'downloads', 'get', sessionId, '--output', out]);
  if (r.ok && fs.existsSync(out)) {
    const size = fs.statSync(out).size;
    if (size <= 22) {
      fs.unlinkSync(out);
      console.log('no downloads');
    } else {
      console.log(`wrote downloads.zip (${size} bytes)`);
    }
  } else if (fs.existsSync(out)) {
    fs.unlinkSync(out);
  }
}

if (release) {
  const r = runCmd('browse', ['cloud', 'sessions', 'update', sessionId, '--status', 'REQUEST_RELEASE']);
  if (r.ok) console.log(`released session ${sessionId}`);

  // Re-snapshot session.json so it reflects the final COMPLETED state with
  // settled proxyBytes and endedAt instead of the pre-release values.
  const r2 = runCmd('browse', ['cloud', 'sessions', 'get', sessionId]);
  if (r2.ok) {
    fs.writeFileSync(path.join(bbDir, 'session.json'), r2.stdout);
    console.log('refreshed session.json (post-release)');
  }
}

console.log(`finalized: ${bbDir}`);
for (const f of fs.readdirSync(bbDir)) console.log(f);

#!/usr/bin/env node
// Slice cdp/raw.ndjson into per-bucket and per-page JSONL files, then write a
// structured cdp/summary.json with a top-level overview and a pages[] array.
//
// Usage:
//   node scripts/bisect-cdp.mjs <run-id>
//
// Layout produced:
//   cdp/summary.json                  {sessionId, duration, totalEvents, pages[]}
//   cdp/<domain>/...                  session-wide buckets (legacy layout, always written)
//   cdp/pages/<pid>/                  per-page slices, only non-empty buckets written
//     url.txt, summary.json, raw.jsonl
//     network/, console/, page/, runtime/, log/, target/, dom/

import fs from 'node:fs';
import path from 'node:path';

import {
  runDir, ensureDir, readJson, readJsonl, writeJson, writeJsonl,
  BUCKETS, isTopNav,
} from './lib.mjs';

const [runId] = process.argv.slice(2);
if (!runId) {
  console.error('usage: bisect-cdp.mjs <run-id>');
  process.exit(2);
}

const RD = runDir(runId);
const cdpDir = path.join(RD, 'cdp');
const rawPath = path.join(cdpDir, 'raw.ndjson');
if (!fs.existsSync(rawPath)) {
  console.error(`raw.ndjson not found at ${rawPath}`);
  process.exit(1);
}

const events = readJsonl(rawPath);
const manifest = readJson(path.join(RD, 'manifest.json'), {});

// CDP exposes two clocks under .params.timestamp depending on the domain:
//   Network/Page              → MonotonicTime, seconds since browser start (small)
//   Console.messageAdded etc. → TimeSinceEpoch in ms (large, > 1e9)
// Anchor only on monotonic so wall-clock conversion stays consistent.
const isMonotonic = ts => ts != null && ts < 1e9;
const anchorCdp = events
  .map(e => e?.params?.timestamp)
  .find(isMonotonic) ?? null;

const startedMs = manifest.started_at ? new Date(manifest.started_at).getTime() : null;
const stoppedMs = manifest.stopped_at ? new Date(manifest.stopped_at).getTime() : null;

function toMs(ts) {
  if (ts == null || anchorCdp == null || startedMs == null) return null;
  return Math.floor((ts - anchorCdp) * 1000 + startedMs);
}

// Walk events in order. Each top-level Page.frameNavigated bumps the page
// counter. Events emitted before the first navigation are clamped to pid 0
// so they fold into the first concrete page (their requests really are part
// of loading that first page).
let pid = -1;
for (const ev of events) {
  if (isTopNav(ev)) pid += 1;
  ev._pid = pid < 0 ? 0 : pid;
}

// ---- session-wide buckets (always written, including empty files) ----
ensureDir(cdpDir);
for (const [bucket, predicate] of BUCKETS) {
  const matched = events
    .filter(e => predicate(e.method ?? ''))
    .map(stripPid);
  writeJsonl(path.join(cdpDir, `${bucket}.jsonl`), matched);
}

// ---- per-page slices ----
const pagesRoot = path.join(cdpDir, 'pages');
if (fs.existsSync(pagesRoot)) fs.rmSync(pagesRoot, { recursive: true, force: true });
ensureDir(pagesRoot);

// Group events by pid. If the run had zero events we still create page 0
// so the run dir has a predictable shape.
const pageMap = new Map();
for (const ev of events) {
  if (!pageMap.has(ev._pid)) pageMap.set(ev._pid, []);
  pageMap.get(ev._pid).push(ev);
}
if (pageMap.size === 0) pageMap.set(0, []);

const pageSummaries = [];
for (const [thisPid, pageEvents] of [...pageMap.entries()].sort((a, b) => a[0] - b[0])) {
  const padded = String(thisPid).padStart(3, '0');
  const pdir = path.join(pagesRoot, padded);
  ensureDir(pdir);

  // URL: first top-level frameNavigated in this page; "(initial)" if none.
  const navEv = pageEvents.find(isTopNav);
  const url = navEv?.params?.frame?.url ?? '(initial)';
  fs.writeFileSync(path.join(pdir, 'url.txt'), url + '\n');

  // raw.jsonl for this page, _pid stripped.
  writeJsonl(path.join(pdir, 'raw.jsonl'), pageEvents.map(stripPid));

  // Per-bucket slices, only writing files that have content.
  for (const [bucket, predicate] of BUCKETS) {
    const matched = pageEvents
      .filter(e => predicate(e.method ?? ''))
      .map(stripPid);
    writeJsonl(path.join(pdir, `${bucket}.jsonl`), matched, { skipEmpty: true });
  }

  const summary = computePageSummary(thisPid, url, pageEvents);
  writeJson(path.join(pdir, 'summary.json'), summary);
  pageSummaries.push(summary);
}

// ---- top-level summary.json ----
const sessionId = manifest?.browserbase?.session_id || manifest.run_id || runId;
const summary = {
  sessionId,
  duration: {
    startMs: startedMs,
    endMs: stoppedMs,
    totalMs: (startedMs != null && stoppedMs != null) ? stoppedMs - startedMs : null,
  },
  totalEvents: events.length,
  pages: pageSummaries,
};
writeJson(path.join(cdpDir, 'summary.json'), summary);

// Compact stdout view (full file is on disk).
console.log(JSON.stringify({
  sessionId,
  duration: summary.duration,
  totalEvents: summary.totalEvents,
  pages: pageSummaries.map(p => ({
    pageId: p.pageId,
    url: p.url,
    durationMs: p.durationMs,
    eventCount: p.eventCount,
  })),
}, null, 2));

// ---------------------------------------------------------------------------

function stripPid(ev) {
  const { _pid, ...rest } = ev;
  return rest;
}

function computePageSummary(pid, url, pageEvents) {
  const ts = pageEvents
    .map(e => e?.params?.timestamp)
    .filter(isMonotonic);
  const start = ts[0] ?? null;
  const end = ts[ts.length - 1] ?? null;
  const startMs = toMs(start);
  const endMs = toMs(end);

  // Per-CDP-domain rollup with optional errors/warnings keys.
  const counts = new Map();        // domain -> count
  const errors = new Map();        // domain -> errors
  const warnings = new Map();      // domain -> warnings
  const netTypes = new Map();      // resourceType -> count
  let netRequests = 0;
  let netFailed = 0;

  const inc = (m, k, by = 1) => m.set(k, (m.get(k) ?? 0) + by);

  // Classify each event into a logical "domain" bucket. Most CDP events go in
  // the bucket named for their CDP domain (Network, Page, Runtime, …), but
  // `Runtime.consoleAPICalled` is conceptually console activity, not runtime
  // internals — without this remap, the Console bucket's `errors`/`warnings`
  // counts would never line up with any entry in the counts map and would
  // silently disappear from the per-page summary.
  const domainFor = (method) =>
    method === 'Runtime.consoleAPICalled' ? 'Console' : method.split('.')[0];

  for (const ev of pageEvents) {
    const method = ev.method;
    if (!method) continue;
    inc(counts, domainFor(method));

    if (method === 'Network.loadingFailed') {
      inc(errors, 'Network');
      netFailed += 1;
    } else if (method === 'Network.requestWillBeSent') {
      netRequests += 1;
      inc(netTypes, ev?.params?.type ?? 'Other');
    } else if (method === 'Runtime.exceptionThrown') {
      inc(errors, 'Runtime');
    } else if (method === 'Runtime.consoleAPICalled') {
      const t = ev?.params?.type;
      if (t === 'error') inc(errors, 'Console');
      else if (t === 'warning' || t === 'warn') inc(warnings, 'Console');
    } else if (method === 'Log.entryAdded') {
      const level = ev?.params?.entry?.level;
      if (level === 'error') inc(errors, 'Log');
      else if (level === 'warning') inc(warnings, 'Log');
    }
  }

  const domains = {};
  for (const [d, c] of [...counts.entries()].sort()) {
    const block = { count: c };
    if (errors.get(d))   block.errors   = errors.get(d);
    if (warnings.get(d)) block.warnings = warnings.get(d);
    domains[d] = block;
  }

  const out = {
    pageId: pid,
    url,
    startMs,
    endMs,
    durationMs: (startMs != null && endMs != null) ? endMs - startMs : null,
    eventCount: pageEvents.length,
    domains,
  };

  if (netRequests > 0 || netFailed > 0) {
    const byType = {};
    for (const [t, c] of [...netTypes.entries()].sort()) byType[t] = c;
    out.network = { requests: netRequests, failed: netFailed, byType };
  }

  return out;
}

// Shared helpers for the browser-trace scripts.
//
// All scripts read O11Y_ROOT (default ".o11y") so runs land under
// $O11Y_ROOT/<run-id>/. No third-party deps; node stdlib only.

import fs from 'node:fs';
import path from 'node:path';
import { execFileSync } from 'node:child_process';

export function runRoot() {
  return process.env.O11Y_ROOT || '.o11y';
}

export function runDir(runId) {
  return path.join(runRoot(), runId);
}

export function ensureDir(p) {
  fs.mkdirSync(p, { recursive: true });
}

// Wall-clock ISO seconds, no fractional part — same shape as `date -u +%Y-%m-%dT%H:%M:%SZ`.
export function isoUtcSeconds(d = new Date()) {
  return d.toISOString().replace(/\.\d+/, '');
}

// Compact UTC stamp suitable for filenames: 20260427T175533Z (no separators).
export function isoStampForFilename(d = new Date()) {
  return d.toISOString().replace(/[-:]/g, '').replace(/\.\d+/, '');
}

export function readJson(p, fallback = null) {
  if (!fs.existsSync(p)) return fallback;
  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
  catch { return fallback; }
}

export function writeJson(p, obj) {
  ensureDir(path.dirname(p));
  fs.writeFileSync(p, JSON.stringify(obj, null, 2) + '\n');
}

// Stream a JSONL file line-by-line. Returns parsed objects, skipping bad lines.
export function readJsonl(p) {
  if (!fs.existsSync(p)) return [];
  const out = [];
  for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
    if (!line) continue;
    try { out.push(JSON.parse(line)); } catch { /* skip */ }
  }
  return out;
}

// Atomic-ish JSONL write: caller has already mutated the array as desired.
// `skipEmpty: true` removes the file if there's nothing to write — used by per-page bucketing.
export function writeJsonl(p, items, { skipEmpty = false } = {}) {
  if (skipEmpty && items.length === 0) {
    if (fs.existsSync(p)) fs.unlinkSync(p);
    return;
  }
  ensureDir(path.dirname(p));
  const body = items.length ? items.map(o => JSON.stringify(o)).join('\n') + '\n' : '';
  fs.writeFileSync(p, body);
}

export function isAlive(pid) {
  if (!Number.isInteger(pid)) return false;
  try { process.kill(pid, 0); return true; } catch { return false; }
}

// Wrap execFileSync so transient "exit non-zero" doesn't kill the caller.
// Returns { ok, stdout, stderr, status }.
export function runCmd(cmd, args, opts = {}) {
  try {
    const stdout = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
    return { ok: true, stdout, stderr: '', status: 0 };
  } catch (err) {
    return {
      ok: false,
      stdout: err.stdout?.toString?.() ?? '',
      stderr: err.stderr?.toString?.() ?? String(err.message || err),
      status: err.status ?? 1,
    };
  }
}

export function sleepMs(ms) {
  return new Promise(r => setTimeout(r, ms));
}

// Bucket map shared by bisect (session-wide + per-page) and query helpers.
// Format: [bucketRelativePath, predicate(method)].
export const BUCKETS = [
  ['network/requests',    m => m === 'Network.requestWillBeSent'],
  ['network/responses',   m => m === 'Network.responseReceived'],
  ['network/finished',    m => m === 'Network.loadingFinished'],
  ['network/failed',      m => m === 'Network.loadingFailed'],
  ['network/websocket',   m => m.startsWith('Network.webSocket')],
  ['console/logs',        m => m === 'Runtime.consoleAPICalled'],
  ['console/exceptions',  m => m === 'Runtime.exceptionThrown'],
  ['runtime/all',         m => m.startsWith('Runtime.')],
  ['log/entries',         m => m === 'Log.entryAdded'],
  ['page/navigations',    m => m === 'Page.frameNavigated'],
  ['page/lifecycle',      m => m === 'Page.lifecycleEvent'],
  ['page/dialogs',        m => m.startsWith('Page.javascriptDialog')],
  ['page/frames',         m => m.startsWith('Page.frame')],
  ['page/all',            m => m.startsWith('Page.')],
  ['dom/all',             m => m.startsWith('DOM.')],
  ['target/attached',     m => m === 'Target.attachedToTarget'],
  ['target/detached',     m => m === 'Target.detachedFromTarget'],
];

// Top-level frameNavigated detector (parentId null/empty == top frame).
export function isTopNav(ev) {
  if (ev?.method !== 'Page.frameNavigated') return false;
  const parent = ev?.params?.frame?.parentId ?? null;
  return parent === null || parent === '';
}

#!/usr/bin/env node
// Drill-down helper for a captured run.
//
// Usage:
//   node scripts/query.mjs <run-id> list                       List pages with id, url, duration, events.
//   node scripts/query.mjs <run-id> summary                    Print cdp/summary.json (full).
//   node scripts/query.mjs <run-id> page <pid>                 Print this page's summary.json.
//   node scripts/query.mjs <run-id> page <pid> <bucket>        Cat a per-page bucket file. e.g.
//                                                              network/requests, network/failed,
//                                                              console/logs, page/lifecycle, raw
//   node scripts/query.mjs <run-id> errors [pid|all]           All error rows (network failed,
//                                                              runtime exceptions, console errors,
//                                                              log errors). Each line tagged with
//                                                              pid + kind.
//   node scripts/query.mjs <run-id> hosts [pid|all]            Top hosts by request count.
//   node scripts/query.mjs <run-id> host <hostname> [pid|all]  Requests + responses for one host.
//   node scripts/query.mjs <run-id> timeline                   Compact navigation+lifecycle timeline.

import fs from 'node:fs';
import path from 'node:path';

import { runDir, readJson, readJsonl, isTopNav } from './lib.mjs';

const [runId, cmd, ...args] = process.argv.slice(2);
if (!runId || !cmd) usage();

const RD = runDir(runId);
const cdpDir = path.join(RD, 'cdp');
if (!fs.existsSync(cdpDir)) {
  console.error(`no run dir at ${RD}`);
  process.exit(1);
}

switch (cmd) {
  case 'list':     cmdList(); break;
  case 'summary':  cmdSummary(); break;
  case 'page':     cmdPage(args[0], args[1]); break;
  case 'errors':   cmdErrors(args[0]); break;
  case 'hosts':    cmdHosts(args[0]); break;
  case 'host':     cmdHost(args[0], args[1]); break;
  case 'timeline': cmdTimeline(); break;
  default:
    console.error(`unknown command: ${cmd}`);
    usage();
}

// ---------------------------------------------------------------------------

function usage() {
  console.error([
    'usage: query.mjs <run-id> <command> [args...]',
    '',
    '  list                          page table',
    '  summary                       full cdp/summary.json',
    '  page <pid>                    per-page summary',
    '  page <pid> <bucket>           cat pages/<pid>/<bucket>.jsonl  (e.g. network/failed, raw)',
    '  errors [pid|all]              unified errors with pid + kind',
    '  hosts [pid|all]               top hosts by request count',
    '  host <hostname> [pid|all]     all requests/responses for a hostname',
    '  timeline                      nav + lifecycle markers',
  ].join('\n'));
  process.exit(2);
}

function pageDir(pid) {
  return path.join(cdpDir, 'pages', String(pid).padStart(3, '0'));
}

function listPids(filter) {
  if (filter && filter !== 'all') return [Number(filter)];
  const root = path.join(cdpDir, 'pages');
  if (!fs.existsSync(root)) return [];
  return fs.readdirSync(root)
    .filter(d => /^\d+$/.test(d))
    .map(Number)
    .sort((a, b) => a - b);
}

// Exact host match — uses `URL.host` (which includes the port when present)
// so `cmdHosts` output is directly consumable as input to `cmdHost`. The
// equality check still rejects impostors like `example.com.evil.tld` whose
// `host` is the full malicious string, not the prefix.
function hostMatches(url, host) {
  try { return new URL(url).host === host; }
  catch { return false; }
}

// ---------------------------------------------------------------------------

function cmdList() {
  const summary = readJson(path.join(cdpDir, 'summary.json'));
  if (!summary) { console.error('no summary.json — run bisect-cdp.mjs first'); process.exit(1); }

  // Pad columns: pid, eventCount, durationSeconds, url.
  const rows = summary.pages.map(p => ([
    String(p.pageId),
    `${p.eventCount}evt`,
    `${((p.durationMs ?? 0) / 1000).toFixed(2)}s`,
    p.url,
  ]));
  const widths = rows[0]?.map((_, i) => Math.max(...rows.map(r => r[i].length))) ?? [];
  for (const r of rows) {
    console.log(r.map((c, i) => c.padEnd(widths[i])).join('  '));
  }
}

function cmdSummary() {
  const s = readJson(path.join(cdpDir, 'summary.json'));
  if (!s) { console.error('no summary.json — run bisect-cdp.mjs first'); process.exit(1); }
  console.log(JSON.stringify(s, null, 2));
}

function cmdPage(pidArg, bucketArg) {
  if (pidArg === undefined) { console.error('page id required'); process.exit(2); }
  const pdir = pageDir(pidArg);
  if (!fs.existsSync(pdir)) { console.error(`no such page: ${pidArg}`); process.exit(1); }

  if (!bucketArg) {
    const s = readJson(path.join(pdir, 'summary.json'));
    if (!s) { console.error(`no summary.json for page ${pidArg}`); process.exit(1); }
    console.log(JSON.stringify(s, null, 2));
    return;
  }

  if (bucketArg === 'raw') {
    const raw = path.join(pdir, 'raw.jsonl');
    if (!fs.existsSync(raw)) { console.error('(empty)'); return; }
    process.stdout.write(fs.readFileSync(raw));
    return;
  }

  const file = path.join(pdir, `${bucketArg}.jsonl`);
  if (!fs.existsSync(file)) { console.error(`(empty: ${bucketArg} for page ${pidArg})`); return; }
  process.stdout.write(fs.readFileSync(file));
}

function cmdErrors(filter) {
  for (const pid of listPids(filter)) {
    const pdir = pageDir(pid);

    for (const ev of readJsonl(path.join(pdir, 'network/failed.jsonl'))) {
      console.log(JSON.stringify({
        pid, kind: 'network.failed',
        rid: ev?.params?.requestId,
        errorText: ev?.params?.errorText,
        type: ev?.params?.type,
      }));
    }
    for (const ev of readJsonl(path.join(pdir, 'console/exceptions.jsonl'))) {
      console.log(JSON.stringify({
        pid, kind: 'runtime.exception',
        text: ev?.params?.exceptionDetails?.text,
        message: ev?.params?.exceptionDetails?.exception?.description,
      }));
    }
    for (const ev of readJsonl(path.join(pdir, 'console/logs.jsonl'))) {
      if (ev?.params?.type !== 'error') continue;
      const arg0 = ev?.params?.args?.[0];
      console.log(JSON.stringify({
        pid, kind: 'console.error',
        msg: arg0?.value ?? arg0?.description ?? '',
      }));
    }
    for (const ev of readJsonl(path.join(pdir, 'log/entries.jsonl'))) {
      if (ev?.params?.entry?.level !== 'error') continue;
      console.log(JSON.stringify({
        pid, kind: 'log.error',
        source: ev?.params?.entry?.source,
        text: ev?.params?.entry?.text,
      }));
    }
  }
}

function cmdHosts(filter) {
  const counts = new Map();
  for (const pid of listPids(filter)) {
    for (const ev of readJsonl(path.join(pageDir(pid), 'network/requests.jsonl'))) {
      const url = ev?.params?.request?.url;
      if (!url) continue;
      let host;
      try { host = new URL(url).host; } catch { host = ''; }
      counts.set(host, (counts.get(host) ?? 0) + 1);
    }
  }
  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
  for (const [host, n] of sorted) {
    console.log(`${String(n).padStart(4)} ${host}`);
  }
}

function cmdHost(hostname, filter) {
  if (!hostname) { console.error('hostname required'); process.exit(2); }
  for (const pid of listPids(filter)) {
    const pdir = pageDir(pid);
    for (const ev of readJsonl(path.join(pdir, 'network/requests.jsonl'))) {
      const url = ev?.params?.request?.url ?? '';
      if (!hostMatches(url, hostname)) continue;
      console.log(JSON.stringify({
        pid, kind: 'request',
        method: ev?.params?.request?.method,
        url,
        type: ev?.params?.type,
      }));
    }
    for (const ev of readJsonl(path.join(pdir, 'network/responses.jsonl'))) {
      const url = ev?.params?.response?.url ?? '';
      if (!hostMatches(url, hostname)) continue;
      console.log(JSON.stringify({
        pid, kind: 'response',
        status: ev?.params?.response?.status,
        url,
      }));
    }
  }
}

function cmdTimeline() {
  // Read raw.ndjson directly so nav + lifecycle events come out in the order
  // they actually fired. The bisected per-method buckets group by type and
  // would otherwise print all NAVs before any lifecycle markers, even when
  // navigations occurred between lifecycle phases.
  const rawPath = path.join(cdpDir, 'raw.ndjson');
  if (!fs.existsSync(rawPath)) {
    console.error('no raw.ndjson — capture may not have started');
    process.exit(1);
  }
  for (const ev of readJsonl(rawPath)) {
    if (isTopNav(ev)) {
      console.log(`[NAV ${ev?.params?.frame?.url ?? '?'}]`);
    } else if (ev?.method === 'Page.lifecycleEvent') {
      console.log(`[${ev?.params?.name ?? '?'}]`);
    }
  }
}

#!/usr/bin/env node
// Periodic screenshot + DOM HTML + URL sampler. Invoked by start-capture.mjs;
// not meant to be run directly.
//
// Each tick samples the traced CDP target through browse. Passing --cdp here
// ensures this helper attaches to the traced target even when it runs outside
// the user's main automation flow.

import fs from 'node:fs';
import path from 'node:path';
import { spawnSync } from 'node:child_process';

import { isoStampForFilename, sleepMs } from './lib.mjs';

const [target, RD, intervalArg] = process.argv.slice(2);
if (!target || !RD) {
  console.error('usage: snapshot-loop.mjs <target> <run-dir> [interval-seconds]');
  process.exit(2);
}

const intervalMs = (Number(intervalArg) || 2) * 1000;
const indexPath = path.join(RD, 'index.jsonl');

let stopping = false;
process.on('SIGTERM', () => { stopping = true; });
process.on('SIGINT',  () => { stopping = true; });

function getJsonField(stdout, field) {
  if (!stdout) return '';
  try {
    const parsed = JSON.parse(stdout);
    return typeof parsed?.[field] === 'string' ? parsed[field] : '';
  } catch {
    return '';
  }
}

while (!stopping) {
  const ts   = isoStampForFilename();
  const png  = path.join(RD, 'screenshots', `${ts}.png`);
  const html = path.join(RD, 'dom',         `${ts}.html`);
  const tmp  = `${html}.partial`;

  // Best-effort screenshot. If browse fails we just don't get one this tick.
  spawnSync('browse', ['screenshot', '--cdp', target, '--path', png], { stdio: 'ignore' });
  if (fs.existsSync(png) && fs.statSync(png).size === 0) {
    fs.unlinkSync(png);
  }

  // DOM dump via temp file → rename, so we never leave a 0-byte HTML behind.
  try {
    const r = spawnSync('browse', ['get', 'html', 'body', '--cdp', target], { encoding: 'utf8' });
    const htmlBody = getJsonField(r.stdout, 'html');
    if (htmlBody) {
      fs.writeFileSync(tmp, htmlBody);
      fs.renameSync(tmp, html);
    }
  } catch { /* best-effort */ }
  // Cleanup any leftover .partial from a previous interrupted iteration.
  if (fs.existsSync(tmp)) {
    try { fs.unlinkSync(tmp); } catch {}
  }

  // URL from the traced target. Returns {"url": "..."}.
  let urlValue = '';
  const u = spawnSync('browse', ['get', 'url', '--cdp', target], { encoding: 'utf8' });
  urlValue = getJsonField(u.stdout, 'url');

  const screenshotRel = fs.existsSync(png)  ? `screenshots/${ts}.png` : '';
  const domRel        = fs.existsSync(html) ? `dom/${ts}.html`        : '';
  fs.appendFileSync(indexPath,
    JSON.stringify({ ts, screenshot: screenshotRel, dom: domRel, url: urlValue }) + '\n');

  await sleepMs(intervalMs);
}

#!/usr/bin/env node
// Start an observability capture against a CDP target.
//
// Usage:
//   node scripts/start-capture.mjs <port|ws-url> [run-id] [interval-seconds]
//
// Env:
//   O11Y_ROOT     base directory for runs (default: .o11y)
//   O11Y_DOMAINS  space-separated CDP domains (default: "Network Console Runtime Log Page")

import fs from 'node:fs';
import path from 'node:path';
import { spawn } from 'node:child_process';
import { fileURLToPath } from 'node:url';

import {
  runDir, ensureDir, isoUtcSeconds, isAlive, sleepMs, writeJson,
} from './lib.mjs';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

const [target, runIdArg, intervalArg] = process.argv.slice(2);
if (!target) {
  console.error('usage: start-capture.mjs <port|ws-url> [run-id] [interval-seconds]');
  process.exit(2);
}

const runId = runIdArg || isoUtcSeconds().replace(/[-:]/g, '');
const interval = Number(intervalArg) || 2;
const domainsList = (process.env.O11Y_DOMAINS || 'Network Console Runtime Log Page').trim().split(/\s+/);
const domainArgs = domainsList.flatMap(d => ['--domain', d]);

const RD = runDir(runId);
ensureDir(path.join(RD, 'cdp'));
ensureDir(path.join(RD, 'screenshots'));
ensureDir(path.join(RD, 'dom'));

writeJson(path.join(RD, 'manifest.json'), {
  run_id: runId,
  target,
  domains: domainsList.join(' '),
  interval_seconds: interval,
  started_at: isoUtcSeconds(),
});

// Spawn the CDP firehose in the background. Detach + unref so it survives this
// process exiting. browse cdp writes one JSON object per line to stdout.
const rawFd = fs.openSync(path.join(RD, 'cdp', 'raw.ndjson'), 'w');
const errFd = fs.openSync(path.join(RD, 'cdp', 'stderr.log'), 'w');
const cdp = spawn('browse', ['cdp', target, ...domainArgs], {
  detached: true,
  stdio: ['ignore', rawFd, errFd],
});
cdp.unref();
fs.writeFileSync(path.join(RD, '.cdp.pid'), String(cdp.pid));

// Spawn the periodic screenshot/DOM/url sampler (separate process so it can
// be SIGTERM'd independently from the CDP stream).
const loopFd = fs.openSync(path.join(RD, 'snapshot-loop.log'), 'w');
const loopScript = path.join(__dirname, 'snapshot-loop.mjs');
const loop = spawn(process.execPath, [loopScript, target, RD, String(interval)], {
  detached: true,
  stdio: ['ignore', loopFd, loopFd],
});
loop.unref();
fs.writeFileSync(path.join(RD, '.loop.pid'), String(loop.pid));

// Give browse cdp a beat to fail loudly on bad targets so the user sees the
// real error instead of a silent zero-event capture.
await sleepMs(1000);
if (!isAlive(cdp.pid)) {
  console.error(`browse cdp exited immediately — check ${RD}/cdp/stderr.log`);
  try { console.error(fs.readFileSync(path.join(RD, 'cdp', 'stderr.log'), 'utf8')); } catch {}
  try { process.kill(loop.pid); } catch {}
  process.exit(1);
}

console.log(`run_id=${runId}`);
console.log(`run_dir=${RD}`);
console.log(`target=${target}`);
console.log(`cdp_pid=${cdp.pid}`);
console.log(`loop_pid=${loop.pid}`);

#!/usr/bin/env node
// Stop an in-progress capture and stamp the manifest with stopped_at.
//
// Usage:
//   node scripts/stop-capture.mjs <run-id>

import fs from 'node:fs';
import path from 'node:path';

import { runDir, readJson, writeJson, isoUtcSeconds, isAlive, sleepMs } from './lib.mjs';

const [runId] = process.argv.slice(2);
if (!runId) {
  console.error('usage: stop-capture.mjs <run-id>');
  process.exit(2);
}

const RD = runDir(runId);
if (!fs.existsSync(RD)) {
  console.error(`run dir not found: ${RD}`);
  process.exit(1);
}

for (const pidFile of ['.cdp.pid', '.loop.pid']) {
  const p = path.join(RD, pidFile);
  if (!fs.existsSync(p)) continue;
  const pid = parseInt(fs.readFileSync(p, 'utf8').trim(), 10);
  if (!Number.isInteger(pid)) { fs.unlinkSync(p); continue; }

  try { process.kill(pid, 'SIGTERM'); } catch {}
  for (let i = 0; i < 3 && isAlive(pid); i++) {
    await sleepMs(1000);
  }
  if (isAlive(pid)) {
    try { process.kill(pid, 'SIGKILL'); } catch {}
  }
  fs.unlinkSync(p);
}

const manifestPath = path.join(RD, 'manifest.json');
const manifest = readJson(manifestPath);
if (manifest) {
  manifest.stopped_at = isoUtcSeconds();
  writeJson(manifestPath, manifest);
}

// Sweep half-written DOM dumps if the loop got SIGTERM'd mid-write.
const domDir = path.join(RD, 'dom');
if (fs.existsSync(domDir)) {
  for (const f of fs.readdirSync(domDir)) {
    if (f.endsWith('.partial')) {
      try { fs.unlinkSync(path.join(domDir, f)); } catch {}
    }
  }
}

console.log(`stopped: ${RD}`);