@crouton-kit/capture 1.3.2 → 1.3.4

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

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