@crouton-kit/capture 1.3.3 → 1.3.4

package/src/cdp/connection.ts

@@ -0,0 +1,108 @@
+import * as fs from 'fs';
+import { CDPClient } from './client.js';
+import { type CDPTarget, type ParsedArgs } from './types.js';
+import { findTabById } from './targets.js';
+import { detectCdpPortsAsync } from './detect.js';
+import { ConsoleRecorder, printConsoleSummary } from './console-recorder.js';
+import { HARRecorder } from './har-recorder.js';
+import {
+  harFilePath,
+  appendToHarRecording as appendToHar,
+} from '../har-manager.js';
+import { getActiveSession, updateActiveSession } from '../session-context.js';
+
+export async function connectForCommand(
+  parsed: ParsedArgs,
+): Promise<{ client: CDPClient; tab: CDPTarget }> {
+  if (!parsed.target) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  // If --port is explicit, search only that port. Otherwise search all endpoints.
+  let tab: CDPTarget | null = null;
+  if (parsed.port) {
+    tab = await findTabById(parsed.port, parsed.target);
+  } else {
+    const endpoints = await detectCdpPortsAsync();
+    for (const ep of endpoints) {
+      try {
+        tab = await findTabById(ep.port, parsed.target);
+        if (tab) break;
+      } catch {
+        // Skip endpoints that fail
+      }
+    }
+  }
+
+  if (!tab) {
+    const query = parsed.target;
+    throw new Error(
+      `No tab found for target "${query}". Run "capture list" to see available tabs.`,
+    );
+  }
+
+  if (!tab.webSocketDebuggerUrl) {
+    throw new Error('Tab has no WebSocket debugger URL');
+  }
+
+  // Lazy-populate targetId in active session if not yet set
+  const activeSession = getActiveSession();
+  if (activeSession && !activeSession.targetId) {
+    updateActiveSession({ targetId: tab.id });
+  }
+
+  const client = new CDPClient(tab.webSocketDebuggerUrl);
+  await client.waitReady();
+
+  return { client, tab };
+}
+
+export async function withConnection<T>(
+  parsed: ParsedArgs,
+  fn: (client: CDPClient, tab: CDPTarget) => Promise<T>,
+  opts: { settle?: number } = {},
+): Promise<T> {
+  const { client, tab } = await connectForCommand(parsed);
+
+  const consoleRecorder = new ConsoleRecorder(client);
+  await consoleRecorder.start();
+
+  let harRecorder: HARRecorder | undefined;
+  if (parsed.har) {
+    // Validate HAR ID exists before starting recording
+    const harPath = harFilePath(parsed.har);
+    if (!fs.existsSync(harPath)) {
+      console.error(
+        `ERROR: No HAR recording found for --har "${parsed.har}". Run 'har create' first.`,
+      );
+      process.exit(1);
+    }
+    harRecorder = new HARRecorder(client);
+    await harRecorder.start();
+  }
+
+  try {
+    const result = await fn(client, tab);
+
+    // Wait for network activity triggered by the action, then append to HAR
+    if (harRecorder && parsed.har) {
+      const settle = opts.settle !== undefined ? opts.settle : 3000;
+      if (settle > 0) {
+        await new Promise((r) => setTimeout(r, settle));
+      }
+      const har = await harRecorder.finish();
+      if (har.log.entries.length > 0) {
+        appendToHar(parsed.har, har.log.entries);
+        console.error(
+          `  [har:${parsed.har}] +${har.log.entries.length} entries`,
+        );
+      }
+    }
+
+    printConsoleSummary(consoleRecorder.finish());
+
+    return result;
+  } finally {
+    client.close();
+  }
+}

package/src/cdp/console-recorder.ts

@@ -0,0 +1,80 @@
+import { type CDPClient } from './client.js';
+
+export interface ConsoleEntry {
+  level: 'log' | 'warning' | 'error' | 'info' | 'debug';
+  text: string;
+  timestamp: number;
+  source?: string;
+}
+
+export class ConsoleRecorder {
+  private entries: ConsoleEntry[] = [];
+
+  constructor(private client: CDPClient) {}
+
+  async start(): Promise<void> {
+    await this.client.send('Runtime.enable');
+
+    this.client.on('Runtime.consoleAPICalled', (params: unknown) => {
+      const p = params as {
+        type: string;
+        args: Array<{ type: string; value?: unknown; description?: string }>;
+        timestamp: number;
+      };
+      const text = p.args
+        .map((a) =>
+          a.value !== undefined ? String(a.value) : (a.description ?? ''),
+        )
+        .join(' ');
+      this.entries.push({
+        level: p.type as ConsoleEntry['level'],
+        text,
+        timestamp: p.timestamp,
+      });
+    });
+
+    this.client.on('Runtime.exceptionThrown', (params: unknown) => {
+      const p = params as {
+        timestamp: number;
+        exceptionDetails: {
+          exception?: { description?: string };
+          text?: string;
+          url?: string;
+          lineNumber?: number;
+        };
+      };
+      this.entries.push({
+        level: 'error',
+        text:
+          p.exceptionDetails.exception?.description ??
+          p.exceptionDetails.text ??
+          'Unknown exception',
+        timestamp: p.timestamp,
+        source: p.exceptionDetails.url
+          ? `${p.exceptionDetails.url}:${p.exceptionDetails.lineNumber}`
+          : undefined,
+      });
+    });
+  }
+
+  finish(): ConsoleEntry[] {
+    return [...this.entries];
+  }
+}
+
+export function printConsoleSummary(entries: ConsoleEntry[]): void {
+  const errors = entries.filter((e) => e.level === 'error');
+  const warnings = entries.filter((e) => e.level === 'warning');
+  if (errors.length > 0 || warnings.length > 0) {
+    console.error(
+      `\nConsole: ${errors.length} errors, ${warnings.length} warnings`,
+    );
+    for (const entry of [...errors, ...warnings]) {
+      const prefix = entry.level === 'error' ? 'ERR' : 'WARN';
+      const src = entry.source ? ` (${entry.source})` : '';
+      const text =
+        entry.text.length > 200 ? entry.text.slice(0, 197) + '...' : entry.text;
+      console.error(`  [${prefix}] ${text}${src}`);
+    }
+  }
+}

package/src/cdp/detect.ts

@@ -0,0 +1,150 @@
+import { execSync } from 'child_process';
+
+export const BROWSER_PATTERNS: Record<string, string[]> = {
+  'company.thebrowser.browser': ['arc'],
+  'com.google.chrome': ['chrome', 'google chrome'],
+  'com.brave.browser': ['brave'],
+  'com.microsoft.edgemac': ['edge', 'microsoft edge'],
+  'org.chromium.chromium': ['chromium'],
+};
+
+export function getDefaultBrowserId(): string | null {
+  try {
+    const output = execSync(
+      'defaults read com.apple.LaunchServices/com.apple.launchservices.secure LSHandlers 2>/dev/null',
+      { encoding: 'utf-8' },
+    );
+    const match = output.match(
+      /LSHandlerRoleAll = "([^"]+)";\s*LSHandlerURLScheme = https;/,
+    );
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+interface CdpProbeResult {
+  browser: string;
+  app: string;
+  isElectron: boolean;
+}
+
+async function probeCdpPort(port: number): Promise<CdpProbeResult | null> {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 500);
+    const resp = await fetch(`http://localhost:${port}/json/version`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (resp.ok) {
+      const version = (await resp.json()) as {
+        Browser?: string;
+        'User-Agent'?: string;
+      };
+      const browser = version.Browser;
+      const userAgent = version['User-Agent'] ?? '';
+      if (!browser) return null;
+
+      const isElectron = userAgent.includes('Electron');
+
+      // Extract app name from User-Agent for Electron apps
+      // Pattern: "AppName/1.2.3 Chrome/..." in the UA string
+      let app = browser;
+      if (isElectron) {
+        const appMatch = userAgent.match(
+          /(\S+?)\/[\d.]+ Chrome\/[\d.]+ Electron/,
+        );
+        if (appMatch) app = appMatch[1];
+      }
+
+      return { browser, app, isElectron };
+    }
+  } catch {
+    // Not a CDP port or not responding
+  }
+  return null;
+}
+
+function getLocalhostListeningPorts(): number[] {
+  try {
+    // netstat is much faster than lsof on macOS
+    const output = execSync(
+      'netstat -an 2>/dev/null | grep "127.0.0.1.*LISTEN"',
+      { encoding: 'utf-8' },
+    );
+    const ports: number[] = [];
+    for (const line of output.split('\n')) {
+      // Format: tcp4       0      0  127.0.0.1.56192        *.*                    LISTEN
+      const match = line.match(/127\.0\.0\.1\.(\d+)/);
+      if (match) {
+        ports.push(parseInt(match[1], 10));
+      }
+    }
+    return ports;
+  } catch {
+    return [];
+  }
+}
+
+export interface CdpEndpoint {
+  port: number;
+  app: string;
+  bundleId: string;
+  isElectron: boolean;
+}
+
+export async function detectCdpPortsAsync(): Promise<CdpEndpoint[]> {
+  const ports = getLocalhostListeningPorts();
+  const results: CdpEndpoint[] = [];
+
+  // Probe ports in parallel for speed
+  const probes = ports.map(async (port) => {
+    const probe = await probeCdpPort(port);
+    if (probe) {
+      // Map browser string to bundle ID for default browser matching
+      const lower = probe.browser.toLowerCase();
+      let bundleId = 'unknown';
+      for (const [bid, patterns] of Object.entries(BROWSER_PATTERNS)) {
+        if (patterns.some((p) => lower.includes(p))) {
+          bundleId = bid;
+          break;
+        }
+      }
+      results.push({
+        port,
+        app: probe.app,
+        bundleId,
+        isElectron: probe.isElectron,
+      });
+    }
+  });
+
+  await Promise.all(probes);
+  return results;
+}
+
+export async function detectCdpPort(): Promise<number> {
+  const endpoints = await detectCdpPortsAsync();
+  if (endpoints.length === 0) {
+    throw new Error(
+      'No browser with CDP found. Start your browser with remote debugging enabled:\n' +
+        '  Arc: Already enabled by default\n' +
+        '  Chrome: --remote-debugging-port=9222\n' +
+        '  Electron apps expose CDP automatically',
+    );
+  }
+
+  // Use default browser if available (prefer non-Electron)
+  const defaultBrowser = getDefaultBrowserId();
+  if (defaultBrowser) {
+    const match = endpoints.find(
+      (p) => p.bundleId === defaultBrowser && !p.isElectron,
+    );
+    if (match) return match.port;
+  }
+
+  // Fall back to first non-Electron, then first found
+  const nonElectron = endpoints.find((p) => !p.isElectron);
+  return (nonElectron ?? endpoints[0]).port;
+}

package/src/cdp/dispatch.ts

@@ -0,0 +1,30 @@
+import { parseCliArgs } from './args.js';
+import { CDP_USAGE } from './usage.js';
+import { cmdDetect, cmdList, cmdOpen, cmdResetTab } from './commands/tabs.js';
+import { cmdExec } from './commands/exec.js';
+import { cmdScreenshot, cmdClick, cmdType, cmdA11y } from './commands/ui.js';
+import { cmdRecord, cmdNavigate, cmdNetwork } from './commands/traffic.js';
+import { cmdHar } from './commands/har.js';
+
+export async function cdpMain(): Promise<void> {
+  const args = process.argv.slice(2);
+  const parsed = parseCliArgs(args);
+
+  switch (parsed.command) {
+    case 'detect': return cmdDetect(parsed, args);
+    case 'list': return cmdList(parsed, args);
+    case 'open': return cmdOpen(parsed, args);
+    case 'reset-tab': return cmdResetTab(parsed, args);
+    case 'exec': return cmdExec(parsed, args);
+    case 'screenshot': return cmdScreenshot(parsed, args);
+    case 'click': return cmdClick(parsed, args);
+    case 'type': return cmdType(parsed, args);
+    case 'a11y': return cmdA11y(parsed, args);
+    case 'record': return cmdRecord(parsed, args);
+    case 'navigate': return cmdNavigate(parsed, args);
+    case 'network': return cmdNetwork(parsed, args);
+    case 'har': return cmdHar(parsed, args);
+    default:
+      console.log(CDP_USAGE);
+  }
+}

package/src/cdp/execute.ts

@@ -0,0 +1,117 @@
+import { CDPClient } from './client.js';
+import { type CDPTarget } from './types.js';
+import { detectCdpPort } from './detect.js';
+import { findTabById } from './targets.js';
+import { ConsoleRecorder, type ConsoleEntry } from './console-recorder.js';
+import { HARRecorder } from './har-recorder.js';
+import { printConsoleSummary } from './console-recorder.js';
+import { writeHarAndPrintSummary } from './har-output.js';
+import { type HAREntry } from '../har-manager.js';
+
+export interface ExecuteOptions {
+  port?: number;
+  targetId?: string;
+  record?: boolean;
+  harOutPath?: string;
+  timeoutMs?: number;
+}
+
+export interface ExecuteResult {
+  success: boolean;
+  value?: unknown;
+  error?: string;
+  har?: { log: { entries: HAREntry[] } };
+  console: ConsoleEntry[];
+}
+
+export async function executeInBrowser(
+  code: string,
+  options: ExecuteOptions = {},
+): Promise<ExecuteResult> {
+  const port = options.port ?? (await detectCdpPort());
+
+  if (!options.targetId) {
+    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
+  }
+
+  // Find tab by exact/prefix ID
+  let tab: CDPTarget | null = null;
+  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();
+
+  // Emulate focus so network requests aren't deferred by the browser,
+  // without actually bringing the tab to the foreground
+  await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+
+  const consoleRecorder = new ConsoleRecorder(client);
+  await consoleRecorder.start();
+
+  let harRecorder: HARRecorder | undefined;
+  if (options.record) {
+    harRecorder = new HARRecorder(client);
+    await harRecorder.start();
+  }
+
+  try {
+    // Execute code
+    const result = (await client.send(
+      'Runtime.evaluate',
+      {
+        expression: code,
+        awaitPromise: true,
+        returnByValue: true,
+      },
+      options.timeoutMs,
+    )) as {
+      result?: { value?: unknown };
+      exceptionDetails?: { exception?: { description?: string } };
+    };
+
+    // Build HAR if recording
+    let har: { log: { entries: HAREntry[] } } | undefined;
+    if (harRecorder) {
+      har = await harRecorder.finish();
+      writeHarAndPrintSummary(har, options.harOutPath);
+    }
+
+    const consoleEntries = consoleRecorder.finish();
+    printConsoleSummary(consoleEntries);
+    client.close();
+
+    if (result.exceptionDetails) {
+      return {
+        success: false,
+        error:
+          result.exceptionDetails.exception?.description ?? 'Unknown error',
+        har,
+        console: consoleEntries,
+      };
+    }
+
+    return {
+      success: true,
+      value: result.result?.value,
+      har,
+      console: consoleEntries,
+    };
+  } catch (err) {
+    const consoleEntries = consoleRecorder.finish();
+    client.close();
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+      console: consoleEntries,
+    };
+  }
+}

package/src/cdp/har-output.ts

@@ -0,0 +1,47 @@
+import * as fs from 'fs';
+import { type HAREntry } from '../har-manager.js';
+
+export function writeHarAndPrintSummary(
+  har: { log: { entries: HAREntry[] } },
+  harOutPath?: string,
+): string | undefined {
+  if (har.log.entries.length === 0 && !harOutPath) return undefined;
+
+  const harPath = harOutPath ?? `/tmp/capture-har-${Date.now()}.json`;
+  try {
+    fs.writeFileSync(harPath, JSON.stringify(har, null, 2));
+  } catch (err) {
+    // Fallback: strip response bodies and retry
+    const stripped = {
+      log: {
+        ...har.log,
+        entries: har.log.entries.map((e) => ({
+          ...e,
+          response: { ...e.response, content: { text: '[body stripped — too large to serialize]' } },
+        })),
+      },
+    };
+    fs.writeFileSync(harPath, JSON.stringify(stripped, null, 2));
+    console.error('  WARNING: Response bodies stripped from HAR (too large to serialize)');
+  }
+
+  // Print summary to stderr
+  const errors = har.log.entries.filter((e) => e.response.status >= 400);
+  console.error(
+    `\nHAR: ${har.log.entries.length} requests captured → ${harPath}`,
+  );
+  if (errors.length > 0) {
+    console.error(`  ${errors.length} failed:`);
+    for (const entry of errors) {
+      const method = entry.request.method.padEnd(6);
+      const status = entry.response.status;
+      const url =
+        entry.request.url.length > 100
+          ? entry.request.url.slice(0, 97) + '...'
+          : entry.request.url;
+      console.error(`  ${method} ${status} ${url}`);
+    }
+  }
+
+  return harPath;
+}

package/src/cdp/har-recorder.ts

@@ -0,0 +1,147 @@
+import { type HAREntry } from '../har-manager.js';
+import { type CDPClient } from './client.js';
+
+interface NetworkRequest {
+  requestId: string;
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  postData?: string;
+  timestamp: number;
+}
+
+interface NetworkResponse {
+  requestId: string;
+  url: string;
+  status: number;
+  headers: Record<string, string>;
+  body?: string;
+  timestamp: number;
+}
+
+// HAREntry imported from ../har-manager.ts
+
+const SKIP_EXTENSIONS =
+  /\.(png|jpg|jpeg|gif|webp|svg|ico|woff2?|ttf|eot|css|mp4|webm|mp3)(\?|$)/i;
+const SKIP_DOMAINS =
+  /(google-analytics|googletagmanager|doubleclick|facebook\.com\/tr|px\.ads|analytics|tracking|beacon|telemetry)/i;
+const MAX_BODY_SIZE = 256 * 1024; // 256KB per response body in HAR
+
+function shouldRecordRequest(url: string): boolean {
+  if (SKIP_EXTENSIONS.test(url)) return false;
+  if (SKIP_DOMAINS.test(url)) return false;
+  return true;
+}
+
+export class HARRecorder {
+  private requests = new Map<string, NetworkRequest>();
+  private responses = new Map<string, NetworkResponse>();
+
+  constructor(private client: CDPClient) {}
+
+  get responseCount(): number {
+    return this.responses.size;
+  }
+
+  async start(): Promise<void> {
+    await this.client.send('Network.enable');
+
+    this.client.on('Network.requestWillBeSent', (params: unknown) => {
+      const p = params as {
+        requestId: string;
+        request: {
+          url: string;
+          method: string;
+          headers: Record<string, string>;
+          postData?: string;
+        };
+        timestamp: number;
+      };
+      if (!shouldRecordRequest(p.request.url)) return;
+      this.requests.set(p.requestId, {
+        requestId: p.requestId,
+        url: p.request.url,
+        method: p.request.method,
+        headers: p.request.headers,
+        postData: p.request.postData,
+        timestamp: p.timestamp,
+      });
+    });
+
+    this.client.on('Network.responseReceived', (params: unknown) => {
+      const p = params as {
+        requestId: string;
+        response: {
+          url: string;
+          status: number;
+          headers: Record<string, string>;
+        };
+        timestamp: number;
+      };
+      if (!this.requests.has(p.requestId)) return;
+      this.responses.set(p.requestId, {
+        requestId: p.requestId,
+        url: p.response.url,
+        status: p.response.status,
+        headers: p.response.headers,
+        timestamp: p.timestamp,
+      });
+    });
+  }
+
+  private buildHar(): { log: { entries: HAREntry[] } } {
+    return {
+      log: {
+        entries: Array.from(this.responses.values()).map((resp) => {
+          const req = this.requests.get(resp.requestId);
+          return {
+            startedDateTime: new Date(resp.timestamp * 1000).toISOString(),
+            request: {
+              method: req?.method ?? 'GET',
+              url: resp.url,
+              headers: Object.entries(req?.headers ?? {}).map(
+                ([name, value]) => ({ name, value }),
+              ),
+              postData: req?.postData ? { text: req.postData } : undefined,
+            },
+            response: {
+              status: resp.status,
+              headers: Object.entries(resp.headers).map(([name, value]) => ({
+                name,
+                value,
+              })),
+              content: { text: resp.body },
+            },
+          };
+        }),
+      },
+    };
+  }
+
+  async finish(): Promise<{ log: { entries: HAREntry[] } }> {
+    // Fetch response bodies in parallel — sequential fetches with 5s timeouts
+    // were causing ~50s hangs when many responses had evicted bodies
+    await Promise.allSettled(
+      Array.from(this.responses.entries()).map(async ([reqId, resp]) => {
+        const bodyResult = (await this.client.send('Network.getResponseBody', {
+          requestId: reqId,
+        }, 5000)) as {
+          body: string;
+          base64Encoded: boolean;
+        };
+        const decoded = bodyResult.base64Encoded
+          ? Buffer.from(bodyResult.body, 'base64').toString()
+          : bodyResult.body;
+        resp.body = decoded.length > MAX_BODY_SIZE
+          ? decoded.slice(0, MAX_BODY_SIZE) + `\n[truncated: ${decoded.length} bytes]`
+          : decoded;
+      }),
+    );
+
+    return this.buildHar();
+  }
+
+  finishPartial(): { log: { entries: HAREntry[] } } {
+    return this.buildHar();
+  }
+}