@crouton-kit/capture 1.3.2 → 1.3.4

package/src/cdp/args.ts

@@ -0,0 +1,101 @@
+import { type ParsedArgs } from './types.js';
+import { getActiveSession } from '../session-context.js';
+
+export function parseCliArgs(argv: string[]): ParsedArgs {
+  const command = argv[0] ?? '';
+  const positional: string[] = [];
+  const parsed: Partial<ParsedArgs> = { command, positional };
+
+  for (let i = 1; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === '--port' && next) {
+      parsed.port = parseInt(next, 10);
+      i++;
+    } else if (arg === '--out' && next) {
+      parsed.out = next;
+      i++;
+    } else if (arg === '--json') {
+      parsed.json = true;
+    } else if (arg === '--interactive') {
+      parsed.interactive = true;
+    } else if (arg === '--har-out' && next) {
+      parsed.harOut = next;
+      i++;
+    } else if (arg === '--record') {
+      parsed.record = true;
+    } else if (arg === '--duration' && next) {
+      parsed.duration = parseInt(next, 10);
+      i++;
+    } else if (arg === '--settle' && next) {
+      parsed.settle = parseInt(next, 10);
+      i++;
+    } else if (arg === '--file' && next) {
+      parsed.file = next;
+      i++;
+    } else if (arg === '--nested') {
+      parsed.nested = true;
+    } else if (arg === '--har' && next) {
+      parsed.har = next;
+      i++;
+    } else if (arg === '--new') {
+      parsed.new = true;
+    } else if (arg === '--target' && next) {
+      parsed.target = next;
+      i++;
+    } else if (arg === '--role' && next) {
+      parsed.role = next;
+      i++;
+    } else if (arg === '--into' && next) {
+      parsed.into = next;
+      i++;
+    } else if (arg === '--no-screenshot') {
+      parsed.noScreenshot = true;
+    } else if (arg === '--viewport' && next) {
+      parsed.viewport = next;
+      i++;
+    } else if (arg === '--full-page') {
+      parsed.fullPage = true;
+    } else if (arg === '--height' && next) {
+      parsed.height = parseInt(next, 10);
+      i++;
+    } else if (arg === '--filter-url' && next) {
+      parsed.filterUrl = next;
+      i++;
+    } else if (arg === '--filter-status' && next) {
+      parsed.filterStatus = next;
+      i++;
+    } else if (arg === '--filter-method' && next) {
+      parsed.filterMethod = next.toUpperCase();
+      i++;
+    } else if (arg === '--limit' && next) {
+      parsed.limit = parseInt(next, 10);
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+    } else if (arg.startsWith('--')) {
+      console.error(`Unknown flag: ${arg}`);
+      process.exit(1);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  // Fill gaps from environment variables (set by pipeline orchestrators)
+  if (!parsed.target && process.env.CDP_TARGET) {
+    parsed.target = process.env.CDP_TARGET;
+  }
+  if (!parsed.har && process.env.CDP_HAR_ID) {
+    parsed.har = process.env.CDP_HAR_ID;
+  }
+
+  // Fill remaining gaps from active session context (explicit flags always win)
+  const session = getActiveSession();
+  if (session) {
+    if (!parsed.har && session.harId) parsed.har = session.harId;
+    if (!parsed.target && session.targetId) parsed.target = session.targetId;
+  }
+
+  return parsed as ParsedArgs;
+}

package/src/cdp/client.ts

@@ -0,0 +1,97 @@
+import WebSocket from 'ws';
+
+export class CDPClient {
+  private ws: WebSocket;
+  private messageId = 0;
+  private pendingRequests = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void }
+  >();
+  private pendingTimeouts = new Map<number, NodeJS.Timeout>();
+  private eventHandlers = new Map<string, Array<(params: unknown) => void>>();
+  private ready: Promise<void>;
+
+  constructor(wsUrl: string, connectTimeout = 5000) {
+    this.ws = new WebSocket(wsUrl);
+    this.ready = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`WebSocket connection timeout (${connectTimeout}ms)`));
+      }, connectTimeout);
+
+      this.ws.on('open', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      this.ws.on('error', (err) => {
+        clearTimeout(timeout);
+        reject(err);
+      });
+    });
+
+    this.ws.on('message', (data: Buffer) => {
+      const msg = JSON.parse(data.toString());
+      if (msg.id !== undefined) {
+        const pending = this.pendingRequests.get(msg.id);
+        if (pending) {
+          this.pendingRequests.delete(msg.id);
+          const timer = this.pendingTimeouts.get(msg.id);
+          if (timer) {
+            clearTimeout(timer);
+            this.pendingTimeouts.delete(msg.id);
+          }
+          if (msg.error) {
+            pending.reject(new Error(msg.error.message));
+          } else {
+            pending.resolve(msg.result);
+          }
+        }
+      } else if (msg.method) {
+        const handlers = this.eventHandlers.get(msg.method);
+        handlers?.forEach((h) => h(msg.params));
+      }
+    });
+  }
+
+  async waitReady(): Promise<void> {
+    await this.ready;
+  }
+
+  async send(
+    method: string,
+    params: Record<string, unknown> = {},
+    timeout = 60000,
+  ): Promise<unknown> {
+    await this.ready;
+    const id = ++this.messageId;
+
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ id, method, params }));
+
+      const timer = setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          this.pendingTimeouts.delete(id);
+          reject(new Error(`CDP request timeout (${timeout}ms): ${method}`));
+        }
+      }, timeout);
+      this.pendingTimeouts.set(id, timer);
+    });
+  }
+
+  on(event: string, handler: (params: unknown) => void): void {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event)!.push(handler);
+  }
+
+  close(): void {
+    // Clear all pending timeouts to allow process to exit
+    for (const timer of this.pendingTimeouts.values()) {
+      clearTimeout(timer);
+    }
+    this.pendingTimeouts.clear();
+    this.ws.close();
+  }
+}

package/src/cdp/commands/exec.ts

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import { withConnection } from '../connection.js';
+import { HARRecorder } from '../har-recorder.js';
+import { writeHarAndPrintSummary } from '../har-output.js';
+import { type ParsedArgs } from '../types.js';
+
+export async function cmdExec(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture exec <code> [--target <id>] [--record] [--file <path>] [--har <id>]\n\n' +
+        'Execute JavaScript in a browser tab. Supports await (wrapped in async IIFE).\n\n' +
+        'Examples:\n' +
+        '  capture exec "document.title" --target <id>\n' +
+        '  capture exec "await fetch(\'/api/data\').then(r=>r.json())" --target <id>\n' +
+        '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
+        '  capture exec --file /tmp/scrape.js --target <id> --record',
+    );
+    process.exit(0);
+  }
+  let code: string;
+  if (parsed.file) {
+    code = fs.readFileSync(parsed.file, 'utf-8');
+  } else {
+    code = parsed.positional[0];
+    if (!code) {
+      console.error(
+        'ERROR: Missing code to execute.\n\n' +
+          'Usage: capture exec <code> [--target <id>] [--record] [--file <path>]\n\n' +
+          'Examples:\n' +
+          '  capture exec "document.title" --target <id>\n' +
+          '  capture exec "document.querySelector(\'.btn\').click()" --target <id>\n' +
+          '  capture exec --file /tmp/scrape.js --target <id> --record',
+      );
+      process.exit(1);
+    }
+  }
+
+  await withConnection(
+    parsed,
+    async (client) => {
+      await client.send('Emulation.setFocusEmulationEnabled', { enabled: true });
+
+      // Standalone HAR recording (--record flag writes its own file)
+      let standaloneRecorder: HARRecorder | undefined;
+      if (parsed.record) {
+        standaloneRecorder = new HARRecorder(client);
+        await standaloneRecorder.start();
+      }
+
+      // Smart wrapping: only use async IIFE when code contains `await`.
+      // Without wrapping, Runtime.evaluate returns the completion value
+      // of the last expression, handling multi-statement code naturally.
+      const needsAsyncWrap = /\bawait\b/.test(code);
+      const expression = needsAsyncWrap
+        ? `(async () => { ${code} })()`
+        : code;
+
+      const evalResult = (await client.send('Runtime.evaluate', {
+        expression,
+        awaitPromise: true,
+        returnByValue: true,
+      })) as {
+        result?: { value?: unknown };
+        exceptionDetails?: { exception?: { description?: string } };
+      };
+
+      if (standaloneRecorder) {
+        const har = await standaloneRecorder.finish();
+        writeHarAndPrintSummary(har, parsed.harOut);
+      }
+
+      if (evalResult.exceptionDetails) {
+        console.error(
+          `ERROR: ${evalResult.exceptionDetails.exception?.description ?? 'Unknown error'}`,
+        );
+        process.exit(1);
+      }
+
+      console.log(JSON.stringify(evalResult.result?.value));
+    },
+    { settle: 3000 },
+  );
+  return;
+}

package/src/cdp/commands/har.ts

@@ -0,0 +1,128 @@
+import {
+  createHarRecording,
+  readHarRecording as readHarFile,
+  deleteHarRecording,
+  harFilePath,
+} from '../../har-manager.js';
+import { getActiveSession } from '../../session-context.js';
+import { type ParsedArgs } from '../types.js';
+
+export async function cmdHar(parsed: ParsedArgs, args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture har <create|read|delete>\n\n' +
+        '  create                      Create a new HAR recording (returns id)\n' +
+        '  read [id]                   Read accumulated HAR entries (id optional in active session)\n' +
+        '  delete <id>                 Delete a HAR recording\n\n' +
+        'Filters (read):\n' +
+        '  --filter-url <pattern>      Substring or regex match on URL\n' +
+        '  --filter-status <code>      Status code, prefix (e.g. 4), or range (e.g. 400-499)\n' +
+        '  --filter-method <method>    HTTP method (GET, POST, ...)\n' +
+        '  --limit <N>                 Return only the first N matching entries\n\n' +
+        'Pass --har <id> to exec/navigate commands to append traffic to a recording.',
+    );
+    process.exit(0);
+  }
+  const subcommand = args[1];
+
+  if (subcommand === 'create') {
+    // Generate a short random ID
+    const { id, path: harPath } = createHarRecording();
+    console.log(JSON.stringify({ id, path: harPath }, null, 2));
+    console.error(
+      `\nPass --har ${id} to subsequent commands to record traffic.`,
+    );
+    return;
+  }
+
+  if (subcommand === 'read') {
+    // ID is optional — fall back to active session's harId
+    let id = args[2];
+    if (id && id.startsWith('--')) id = undefined as unknown as string;
+    if (!id) {
+      const session = getActiveSession();
+      if (session?.harId) {
+        id = session.harId;
+      } else {
+        console.error('Usage: capture har read [id]\n' +
+          '  ID is optional when a capture session is active.');
+        process.exit(1);
+      }
+    }
+
+    const har = readHarFile(id);
+    if (!har) {
+      console.error(`No HAR recording found for id: ${id}`);
+      process.exit(1);
+    }
+
+    let entries = har.log.entries;
+    const total = entries.length;
+    const filters: string[] = [];
+
+    if (parsed.filterUrl) {
+      const pattern = parsed.filterUrl;
+      let re: RegExp | null = null;
+      try { re = new RegExp(pattern, 'i'); } catch { re = null; }
+      entries = entries.filter((e) =>
+        re ? re.test(e.request.url) : e.request.url.toLowerCase().includes(pattern.toLowerCase()),
+      );
+      filters.push(`url~${pattern}`);
+    }
+    if (parsed.filterStatus) {
+      const s = parsed.filterStatus;
+      let matcher: (code: number) => boolean;
+      if (/^\d+-\d+$/.test(s)) {
+        const [lo, hi] = s.split('-').map((n) => parseInt(n, 10));
+        matcher = (c) => c >= lo && c <= hi;
+      } else if (/^\d+$/.test(s)) {
+        if (s.length < 3) {
+          matcher = (c) => String(c).startsWith(s);
+        } else {
+          const n = parseInt(s, 10);
+          matcher = (c) => c === n;
+        }
+      } else {
+        matcher = () => true;
+      }
+      entries = entries.filter((e) => matcher(e.response.status));
+      filters.push(`status=${s}`);
+    }
+    if (parsed.filterMethod) {
+      const m = parsed.filterMethod;
+      entries = entries.filter((e) => e.request.method.toUpperCase() === m);
+      filters.push(`method=${m}`);
+    }
+    if (typeof parsed.limit === 'number' && parsed.limit > 0) {
+      entries = entries.slice(0, parsed.limit);
+      filters.push(`limit=${parsed.limit}`);
+    }
+
+    const filtersLabel = filters.length > 0 ? `  [${filters.join(', ')}]` : '';
+    console.error(
+      `HAR: ${harFilePath(id)} (${entries.length}/${total} entries)${filtersLabel}`,
+    );
+    console.log(JSON.stringify({ log: { entries } }, null, 2));
+    return;
+  }
+
+  if (subcommand === 'delete') {
+    const id = args[2];
+    if (!id) {
+      console.error('Usage: capture har delete <id>');
+      process.exit(1);
+    }
+
+    deleteHarRecording(id);
+    console.log(JSON.stringify({ deleted: true, id }, null, 2));
+    return;
+  }
+
+  console.error(
+    'Usage: capture har <create|read|delete>\n' +
+      '  create              Create a new HAR recording (returns id)\n' +
+      '  read <id>           Read accumulated HAR entries\n' +
+      '  delete <id>         Delete a HAR recording',
+  );
+  process.exit(1);
+}

package/src/cdp/commands/tabs.ts

@@ -0,0 +1,189 @@
+import { detectCdpPortsAsync, detectCdpPort, getDefaultBrowserId } from '../detect.js';
+import { listTargets, openTab } from '../targets.js';
+import { navigateAndWait } from '../record.js';
+import { CDPClient } from '../client.js';
+import { updateActiveSession } from '../../session-context.js';
+import { type ParsedArgs } from '../types.js';
+
+export async function cmdDetect(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture detect\n\n' +
+        'Detect CDP port (prioritizes default browser).\n' +
+        'Returns JSON with port, app name, and all discovered endpoints.',
+    );
+    process.exit(0);
+  }
+  const endpoints = await detectCdpPortsAsync();
+  if (endpoints.length === 0) {
+    console.error(
+      'ERROR: No browser with CDP found.\n\n' +
+        'Fix: Start a browser with remote debugging enabled:\n' +
+        '  Arc: Already enabled by default\n' +
+        '  Chrome: --remote-debugging-port=9222\n' +
+        '  Electron apps expose CDP automatically',
+    );
+    process.exit(1);
+  }
+  const defaultBrowser = getDefaultBrowserId();
+  const preferred =
+    endpoints.find(
+      (p) => p.bundleId === defaultBrowser && !p.isElectron,
+    ) ??
+    endpoints.find((p) => !p.isElectron) ??
+    endpoints[0];
+  console.log(
+    JSON.stringify(
+      {
+        port: preferred.port,
+        app: preferred.app,
+        isElectron: preferred.isElectron,
+        all: endpoints.map((e) => ({
+          port: e.port,
+          app: e.app,
+          isElectron: e.isElectron,
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+  console.error(
+    `\nFound ${endpoints.length} CDP endpoint${endpoints.length > 1 ? 's' : ''}. Default: port ${preferred.port} (${preferred.app}).` +
+      `\n\nNext (most tasks): capture session start --url <your app url>` +
+      `\n      (one-off):    capture list --port ${preferred.port}`,
+  );
+  return;
+}
+
+export async function cmdList(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture list [--port <port>]\n\n' +
+        'List all browser tabs across all CDP endpoints (or a specific port).\n' +
+        'Returns JSON array of {id, title, url, port, app}.',
+    );
+    process.exit(0);
+  }
+  if (parsed.port) {
+    // Single port mode
+    const targets = await listTargets(parsed.port);
+    const pages = targets.filter((t) => t.type === 'page');
+    console.log(JSON.stringify(pages.map((t) => ({
+      id: t.id,
+      title: t.title,
+      url: t.url,
+    })), null, 2));
+    console.error(
+      `\n${pages.length} tab${pages.length !== 1 ? 's' : ''} on port ${parsed.port}.` +
+        `\n\nTarget a tab with: --target <id prefix>  (first 8 chars sufficient)`,
+    );
+  } else {
+    // All endpoints mode
+    const endpoints = await detectCdpPortsAsync();
+    if (endpoints.length === 0) {
+      console.error('No CDP endpoints found.');
+      process.exit(1);
+    }
+    const allPages: { id: string; title: string; url: string; port: number; app: string }[] = [];
+    await Promise.all(endpoints.map(async (ep) => {
+      try {
+        const targets = await listTargets(ep.port);
+        const pages = targets.filter((t) => t.type === 'page');
+        for (const t of pages) {
+          allPages.push({ id: t.id, title: t.title, url: t.url, port: ep.port, app: ep.app });
+        }
+      } catch {
+        // Skip endpoints that fail to respond
+      }
+    }));
+    console.log(JSON.stringify(allPages, null, 2));
+    console.error(
+      `\n${allPages.length} tab${allPages.length !== 1 ? 's' : ''} across ${endpoints.length} CDP endpoint${endpoints.length !== 1 ? 's' : ''}.` +
+        `\n\nTarget a tab with: --target <id prefix>  (first 8 chars sufficient)`,
+    );
+  }
+  return;
+}
+
+export async function cmdOpen(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture open <url> [--new] [--port <port>]\n\n' +
+        'Open URL in browser (returns tab ID).\n\n' +
+        'Example: capture open "https://app.example.com" --new',
+    );
+    process.exit(0);
+  }
+  const url = parsed.positional[0];
+  if (!url) {
+    console.error(
+      'ERROR: Missing URL.\n\n' +
+        'Usage: capture open <url> [--new] [--port <port>]\n\n' +
+        'Example: capture open "https://app.example.com" --new',
+    );
+    process.exit(1);
+  }
+  const p = parsed.port ?? (await detectCdpPort());
+  const tab = await navigateAndWait(p, url, { forceNew: parsed.new });
+  console.log(JSON.stringify({
+    id: tab.id,
+    title: tab.title,
+    url: tab.url,
+    port: p,
+  }, null, 2));
+  console.error(
+    `\nOpened: ${tab.title || url}` +
+      `\n\nFor a multi-step validation, prefer a session (auto-targets this kind of tab):` +
+      `\n  capture session start --url "${url}"` +
+      `\n\nOr interact one-off against this tab:` +
+      `\n  capture a11y       --port ${p} --target ${tab.id.slice(0, 8)} --interactive` +
+      `\n  capture screenshot --port ${p} --target ${tab.id.slice(0, 8)}` +
+      `\n  capture exec "<js>" --port ${p} --target ${tab.id.slice(0, 8)}`,
+  );
+  return;
+}
+
+export async function cmdResetTab(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture reset-tab <url> [--port <port>]\n\n' +
+        'Abandon a stuck/unresponsive tab and open a fresh one.\n' +
+        'Updates session context so subsequent commands auto-target the new tab.\n\n' +
+        'Example: capture reset-tab "https://www.instagram.com/"',
+    );
+    process.exit(0);
+  }
+  const url = parsed.positional[0];
+  if (!url) {
+    console.error(
+      'Usage: capture reset-tab <url> [--port <port>]',
+    );
+    process.exit(1);
+  }
+  const p = parsed.port ?? (await detectCdpPort());
+  const tab = await openTab(p, url);
+
+  // Wait for page load
+  if (tab.webSocketDebuggerUrl) {
+    const client = new CDPClient(tab.webSocketDebuggerUrl);
+    await client.waitReady();
+    await client.send('Page.enable');
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => resolve(), 10000);
+      client.on('Page.loadEventFired', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+    client.close();
+  }
+
+  // Update session context so subsequent commands auto-target the new tab
+  updateActiveSession({ targetId: tab.id });
+
+  console.log(JSON.stringify({ id: tab.id, url: tab.url, port: p }, null, 2));
+  console.error(`\nNew tab opened. Session context updated.`);
+  console.error(`Use --target ${tab.id.slice(0, 8)} if passing target explicitly.`);
+  return;
+}