@crouton-kit/capture 1.3.3 → 1.3.4

package/src/cdp/record.ts

@@ -0,0 +1,221 @@
+import { CDPClient } from './client.js';
+import { type CDPTarget } from './types.js';
+import { detectCdpPort } from './detect.js';
+import { findTab, findTabById, openTab, listTargets } from './targets.js';
+import { HARRecorder } from './har-recorder.js';
+import { writeHarAndPrintSummary } from './har-output.js';
+import { type HAREntry } from '../har-manager.js';
+
+export interface RecordOptions {
+  port?: number;
+  targetId?: string;
+  duration?: number;
+  harOutPath?: string;
+}
+
+export interface RecordResult {
+  harPath: string | undefined;
+  entryCount: number;
+  har: { log: { entries: HAREntry[] } };
+}
+
+export async function recordTraffic(
+  options: RecordOptions,
+): Promise<RecordResult> {
+  const port = options.port ?? (await detectCdpPort());
+  const duration = options.duration ?? 10;
+
+  if (!options.targetId) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  const tab = await findTabById(port, options.targetId);
+  if (!tab) {
+    throw new Error(
+      `No tab found for target "${options.targetId}". Run "capture list" to see available tabs.`,
+    );
+  }
+
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+
+  const recorder = new HARRecorder(client);
+  await recorder.start();
+
+  console.error(
+    `Recording traffic on "${tab.url}" for ${duration}s... (click around in the browser)`,
+  );
+
+  await new Promise((r) => setTimeout(r, duration * 1000));
+
+  const har = await recorder.finish();
+  const harPath = writeHarAndPrintSummary(har, options.harOutPath);
+
+  client.close();
+
+  return { harPath, entryCount: har.log.entries.length, har };
+}
+
+export interface NavigateAndRecordOptions {
+  port?: number;
+  url: string;
+  targetId?: string;
+  harOutPath?: string;
+  settle?: number;
+}
+
+export interface NavigateAndRecordResult {
+  harPath: string | undefined;
+  entryCount: number;
+  har: { log: { entries: HAREntry[] } };
+  tab: CDPTarget;
+  timedOut: boolean;
+}
+
+export async function navigateAndRecord(
+  options: NavigateAndRecordOptions,
+): Promise<NavigateAndRecordResult> {
+  const port = options.port ?? (await detectCdpPort());
+  const settle = options.settle ?? 2000;
+
+  // Find tab — prefer targetId (exact) over domain match (fuzzy)
+  let tab: CDPTarget | null = null;
+  let isNewTab = false;
+  if (options.targetId) {
+    tab = await findTabById(port, options.targetId);
+    if (!tab) {
+      throw new Error(
+        `No tab found with target ID "${options.targetId}". Tab may have been closed.`,
+      );
+    }
+  } else {
+    let domain: string;
+    try {
+      domain = new URL(options.url).hostname;
+    } catch {
+      throw new Error(`Invalid URL: ${options.url}`);
+    }
+    tab = await findTab(port, domain);
+    if (!tab) {
+      tab = await openTab(port, options.url);
+      isNewTab = true;
+    }
+  }
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+  await client.send('Page.enable');
+
+  // Start recording BEFORE navigation
+  const recorder = new HARRecorder(client);
+  await recorder.start();
+
+  if (!isNewTab) {
+    // Navigate existing tab
+    console.error(`Navigating to: ${options.url}`);
+    await client.send('Page.navigate', { url: options.url });
+  }
+
+  const deadline = 60_000;
+  const t0 = Date.now();
+  let timedOut = false;
+  let har!: { log: { entries: HAREntry[] } };
+
+  try {
+    await Promise.race([
+      (async () => {
+        // Wait for load event
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(() => {
+            console.error('Page load timeout (10s), continuing with settle...');
+            resolve();
+          }, 10000);
+          client.on('Page.loadEventFired', () => {
+            clearTimeout(timer);
+            resolve();
+          });
+        });
+
+        // Settle time for SPAs that load after DOMContentLoaded
+        console.error(`Settling for ${settle}ms...`);
+        await new Promise((r) => setTimeout(r, settle));
+
+        har = await recorder.finish();
+      })(),
+      new Promise<never>((_, reject) => {
+        const t = setTimeout(() => reject(new Error('__navigate_timeout__')), deadline - (Date.now() - t0));
+        // Don't keep process alive just for the deadline timer
+        if (typeof t === 'object' && 'unref' in t) t.unref();
+      }),
+    ]);
+  } catch (err) {
+    if (err instanceof Error && err.message === '__navigate_timeout__') {
+      timedOut = true;
+      console.error('Navigate timeout (60s) — returning partial HAR');
+      har = recorder.finishPartial();
+    } else {
+      throw err;
+    }
+  }
+
+  const harPath = writeHarAndPrintSummary(har, options.harOutPath);
+
+  client.close();
+
+  // Refresh target info
+  const updatedTab = (await findTab(port, options.url)) ?? tab;
+
+  return { harPath, entryCount: har.log.entries.length, har, tab: updatedTab, timedOut };
+}
+
+export async function navigateAndWait(
+  port: number,
+  url: string,
+  options: { timeout?: number; forceNew?: boolean } = {},
+): Promise<CDPTarget> {
+  const timeout = options.timeout ?? 10000;
+
+  // Check if tab already exists (unless forceNew requested)
+  if (!options.forceNew) {
+    const existing = await findTab(port, url);
+    if (existing) {
+      return existing;
+    }
+  }
+
+  // Open new tab
+  const tab = await openTab(port, url);
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('New tab has no WebSocket debugger URL');
+  }
+
+  // Wait for page load
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+  await client.send('Page.enable');
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error(`Page load timeout: ${url}`)),
+      timeout,
+    );
+    client.on('Page.loadEventFired', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+  });
+
+  client.close();
+
+  // Refresh target info — find by ID to avoid returning a different tab with same URL
+  const targets = await listTargets(port);
+  const refreshed = targets.find((t) => t.id === tab.id);
+  return refreshed ?? tab;
+}

package/src/cdp/screenshot.ts

@@ -0,0 +1,100 @@
+import * as fs from 'fs';
+import { CDPClient } from './client.js';
+import { nextStepPath } from '../session-context.js';
+
+export async function captureScreenshot(
+  client: CDPClient,
+  viewport?: { width: number; height: number },
+  options?: { fullPage?: boolean },
+): Promise<Buffer> {
+  const MAX_DIM = 1600; // headroom below Anthropic's 2000px many-image limit
+
+  // Apply viewport emulation if requested
+  if (viewport) {
+    await client.send('Emulation.setDeviceMetricsOverride', {
+      width: viewport.width,
+      height: viewport.height,
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+    // Let the page re-layout at the new size
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  // For full-page capture, resize viewport to the full content height
+  if (options?.fullPage) {
+    const layoutMetrics = (await client.send('Page.getLayoutMetrics')) as {
+      contentSize?: { width: number; height: number };
+      cssVisualViewport?: { clientWidth: number };
+    };
+    const contentWidth = layoutMetrics.cssVisualViewport?.clientWidth ?? viewport?.width ?? 1280;
+    const contentHeight = layoutMetrics.contentSize?.height ?? viewport?.height ?? 800;
+    await client.send('Emulation.setDeviceMetricsOverride', {
+      width: contentWidth,
+      height: Math.ceil(contentHeight),
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+    await new Promise((r) => setTimeout(r, 150));
+  }
+
+  let screenshotOpts: Record<string, unknown> = {
+    format: 'png',
+    captureBeyondViewport: false,
+  };
+
+  try {
+    const metrics = (await client.send('Page.getLayoutMetrics')) as {
+      cssVisualViewport?: { clientWidth: number; clientHeight: number; pageX: number; pageY: number };
+    };
+    const vw = metrics.cssVisualViewport?.clientWidth ?? 0;
+    const vh = metrics.cssVisualViewport?.clientHeight ?? 0;
+    const sx = metrics.cssVisualViewport?.pageX ?? 0;
+    const sy = metrics.cssVisualViewport?.pageY ?? 0;
+
+    const dprResult = (await client.send('Runtime.evaluate', {
+      expression: 'window.devicePixelRatio',
+      returnByValue: true,
+    })) as { result: { value: number } };
+    const dpr = dprResult.result.value ?? 1;
+
+    const actualMaxSide = Math.max(vw, vh) * dpr;
+    const scale = actualMaxSide > MAX_DIM ? MAX_DIM / actualMaxSide : 1 / dpr;
+    screenshotOpts = {
+      ...screenshotOpts,
+      clip: { x: sx, y: sy, width: vw, height: vh, scale },
+    };
+  } catch {
+    // Fallback: capture without downscaling
+  }
+
+  const result = (await client.send(
+    'Page.captureScreenshot',
+    screenshotOpts,
+  )) as { data: string };
+
+  // Reset emulation so the browser window isn't stuck at the overridden size
+  if (viewport || options?.fullPage) {
+    await client.send('Emulation.clearDeviceMetricsOverride');
+  }
+
+  return Buffer.from(result.data, 'base64');
+}
+
+export async function autoScreenshot(
+  client: CDPClient,
+  action: string,
+  label: string,
+  noScreenshot?: boolean,
+): Promise<string | null> {
+  if (noScreenshot) return null;
+  const shotPath = nextStepPath(action, label);
+  if (!shotPath) return null;
+
+  // Brief settle for UI to update
+  await new Promise((r) => setTimeout(r, 300));
+  const png = await captureScreenshot(client);
+  fs.writeFileSync(shotPath, png);
+  console.error(`  [screenshot] ${shotPath}`);
+  return shotPath;
+}

package/src/cdp/tab-lock.ts

@@ -0,0 +1,132 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const LOCK_DIR = os.tmpdir();
+const LOCK_STALE_MS = 120_000;
+const LOCK_TIMEOUT_MS = 60_000;
+const LOCK_POLL_BASE_MS = 200;
+
+function lockPath(tabId: string): string {
+  return path.join(LOCK_DIR, `capture-cdp-tab-${tabId}.lock`);
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLockStale(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const { pid, ts } = JSON.parse(content) as { pid: number; ts: number };
+    if (!isPidAlive(pid)) return true;
+    return Date.now() - ts > LOCK_STALE_MS;
+  } catch {
+    return true;
+  }
+}
+
+// Track locks held by this process for cleanup on exit
+const heldLocks = new Set<string>();
+let cleanupRegistered = false;
+
+function registerCleanup(): void {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+
+  const cleanup = () => {
+    for (const file of heldLocks) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Best-effort
+      }
+    }
+    heldLocks.clear();
+  };
+
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(143);
+  });
+}
+
+export async function acquireTabLock(tabId: string): Promise<void> {
+  registerCleanup();
+  const file = lockPath(tabId);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let delay = LOCK_POLL_BASE_MS;
+
+  while (true) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      heldLocks.add(file);
+      return;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+    }
+
+    if (isLockStale(file)) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Another process may have already removed it
+      }
+      continue;
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for CDP tab lock (${tabId}). ` +
+          `Another process may be using this tab. Lock file: ${file}`,
+      );
+    }
+
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, 2000);
+  }
+}
+
+export function isTabLocked(tabId: string): boolean {
+  const file = lockPath(tabId);
+  try {
+    fs.accessSync(file);
+    return !isLockStale(file);
+  } catch {
+    return false;
+  }
+}
+
+export function releaseTabLock(tabId: string): void {
+  const file = lockPath(tabId);
+  heldLocks.delete(file);
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    // Already removed — fine
+  }
+}
+
+export async function withTabLock<T>(
+  tabId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await acquireTabLock(tabId);
+  try {
+    return await fn();
+  } finally {
+    releaseTabLock(tabId);
+  }
+}

package/src/cdp/targets.ts

@@ -0,0 +1,112 @@
+import { CDPClient } from './client.js';
+import { type CDPTarget } from './types.js';
+
+async function getBrowserClient(
+  port: number,
+): Promise<{ client: CDPClient; browserWsUrl: string }> {
+  const versionResp = await fetch(`http://localhost:${port}/json/version`);
+  if (!versionResp.ok) {
+    throw new Error(
+      `Failed to connect to CDP on port ${port}: ${versionResp.status}`,
+    );
+  }
+  const version = (await versionResp.json()) as {
+    webSocketDebuggerUrl: string;
+  };
+  const client = new CDPClient(version.webSocketDebuggerUrl);
+  await client.waitReady();
+  return { client, browserWsUrl: version.webSocketDebuggerUrl };
+}
+
+export async function listTargets(port: number): Promise<CDPTarget[]> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Enable target discovery to get all targets including pages
+    await client.send('Target.setDiscoverTargets', { discover: true });
+    const result = (await client.send('Target.getTargets')) as {
+      targetInfos: Array<{
+        targetId: string;
+        type: string;
+        title: string;
+        url: string;
+      }>;
+    };
+
+    // Convert to CDPTarget format with webSocketDebuggerUrl
+    return result.targetInfos.map((t) => ({
+      id: t.targetId,
+      title: t.title,
+      url: t.url,
+      type: t.type,
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${t.targetId}`,
+    }));
+  } finally {
+    client.close();
+  }
+}
+
+export async function findTab(
+  port: number,
+  urlPattern?: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  const pages = targets.filter((t) => t.type === 'page');
+
+  if (!urlPattern) {
+    // Return first page
+    return pages[0] ?? null;
+  }
+
+  // Find by URL pattern
+  const pattern = urlPattern.toLowerCase();
+  return pages.find((t) => t.url.toLowerCase().includes(pattern)) ?? null;
+}
+
+export async function findTabById(
+  port: number,
+  targetId: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  // Exact match first
+  const exact = targets.find((t) => t.id === targetId);
+  if (exact) return exact;
+  // Prefix match (min 4 chars to avoid ambiguity)
+  if (targetId.length >= 4) {
+    const prefix = targetId.toUpperCase();
+    const matches = targets.filter((t) => t.id.toUpperCase().startsWith(prefix));
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      throw new Error(
+        `Ambiguous target prefix "${targetId}" matches ${matches.length} tabs:\n` +
+          matches.map((t) => `  ${t.id.slice(0, 8)}  ${t.url}`).join('\n'),
+      );
+    }
+  }
+  return null;
+}
+
+export async function openTab(port: number, url: string): Promise<CDPTarget> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Create new target in background to avoid stealing user's focus
+    const result = (await client.send('Target.createTarget', {
+      url,
+      background: true,
+    })) as {
+      targetId: string;
+    };
+
+    // Return target info
+    return {
+      id: result.targetId,
+      title: '',
+      url,
+      type: 'page',
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${result.targetId}`,
+    };
+  } finally {
+    client.close();
+  }
+}

package/src/cdp/types.ts

@@ -0,0 +1,36 @@
+export interface CDPTarget {
+  id: string;
+  title: string;
+  url: string;
+  type: string;
+  webSocketDebuggerUrl?: string;
+}
+
+export interface ParsedArgs {
+  command: string;
+  positional: string[];
+  port?: number;
+  out?: string;
+  json?: boolean;
+  interactive?: boolean;
+  harOut?: string;
+  record?: boolean;
+  duration?: number;
+  settle?: number;
+  file?: string;
+  nested?: boolean;
+  har?: string;
+  new?: boolean;
+  target?: string;
+  role?: string;
+  into?: string;
+  noScreenshot?: boolean;
+  viewport?: string;
+  fullPage?: boolean;
+  height?: number;
+  help?: boolean;
+  filterUrl?: string;
+  filterStatus?: string;
+  filterMethod?: string;
+  limit?: number;
+}

package/src/cdp/usage.ts

@@ -0,0 +1,62 @@
+export const CDP_USAGE = `CDP — browser automation via exec, a11y interactions, and screenshots.
+
+Commands:
+  exec <code>         Execute JavaScript in a browser tab
+  exec --file <path>  Execute JS from file
+  detect              Detect CDP port (prioritizes default browser)
+  list                List all browser tabs
+  open <url>          Open URL in browser (returns tab ID)
+  reset-tab <url>     Abandon stuck tab, open fresh one (updates session)
+  screenshot          Capture screenshot
+  click "name"        Click element by accessible name
+  type "text"         Type text into focused element
+  a11y                Get accessibility tree
+  record              Passive HAR recording
+  navigate <url>      Navigate to URL and record HAR
+  network <offline|online>  Toggle network (simulate disconnect)
+  har create          Create a HAR recording (returns id)
+  har read [id]       Read accumulated HAR entries (id optional in active session)
+  har delete <id>     Delete a HAR recording
+
+Options:
+  --port <port>       Override CDP port
+  --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
+  --new               Force new tab (open)
+  --record            Enable HAR recording (exec)
+  --har <id>          Append traffic to a HAR recording
+  --har-out <path>    HAR output path
+  --file <path>       Read JS from file (exec)
+  --duration <secs>   Recording duration (record, default: 10)
+  --settle <ms>       Settle time override (navigate, click, type)
+  --filter-url <pat>  Filter HAR entries by URL substring/regex (har read)
+  --filter-status <s> Filter HAR by status: code, prefix (4), or range (400-499)
+  --filter-method <m> Filter HAR by HTTP method (har read)
+  --limit <N>         Return only first N matching HAR entries (har read)
+  --out <path>        Output path (screenshot)
+  --viewport <preset> Viewport preset: desktop-wide|desktop|tablet|mobile (default: desktop)
+  --height <px>       Override viewport height (screenshot)
+  --full-page         Capture entire scrollable page (screenshot)
+  --json              JSON output (a11y)
+  --interactive       Interactive elements only (a11y)
+  --role <role>       ARIA role filter (click)
+  --into "field"      Target field by name (type)
+  --no-screenshot     Skip auto-screenshot (click, type)
+
+Console output (errors, warnings) is always captured and printed to stderr.
+
+Examples:
+  capture detect
+  capture list
+  capture open "https://app.example.com" --new
+  capture exec "document.title" --target <id>
+  capture exec "document.querySelector('.btn').click()" --target <id>
+  capture exec "fetch('/api/data').then(r=>r.json())" --target <id> --record
+  capture exec --file /tmp/scrape.js --target <id>
+  capture screenshot --target <id> --out /tmp/shot.png
+  capture a11y --target <id> --interactive
+  capture record --target <id> --duration 15
+  capture navigate "https://app.example.com/dashboard"
+  capture har create
+  capture exec "document.querySelector('form').submit()" --target <id> --har <id>
+  capture har read <id>
+`;