@crouton-kit/capture 1.3.2 → 1.3.4

package/src/cdp/commands/traffic.ts

@@ -0,0 +1,121 @@
+import { recordTraffic, navigateAndRecord } from '../record.js';
+import { withConnection } from '../connection.js';
+import { appendToHarRecording as appendToHar } from '../../har-manager.js';
+import { type ParsedArgs } from '../types.js';
+
+export async function cmdRecord(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture record --target <id> [--duration <secs>] [--har-out <path>]\n\n' +
+        'Passive HAR recording for the specified duration (default: 10s).',
+    );
+    process.exit(0);
+  }
+  if (!parsed.target) {
+    console.error(
+      'Usage: capture record --target <id> [--duration <secs>] [--har-out <path>]',
+    );
+    process.exit(1);
+  }
+
+  const result = await recordTraffic({
+    port: parsed.port,
+    targetId: parsed.target,
+    duration: parsed.duration,
+    harOutPath: parsed.harOut,
+  });
+  console.log(
+    JSON.stringify(
+      { entryCount: result.entryCount, harPath: result.harPath },
+      null,
+      2,
+    ),
+  );
+  return;
+}
+
+export async function cmdNavigate(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture navigate <url> [--har-out <path>] [--settle <ms>] [--har <id>]\n\n' +
+        'Navigate to URL and record HAR. Appends to session HAR if --har is set.\n\n' +
+        'Example: capture navigate "https://app.example.com/dashboard" --settle 3000',
+    );
+    process.exit(0);
+  }
+  const url = parsed.positional[0];
+  if (!url) {
+    console.error(
+      'Usage: capture navigate <url> [--har-out <path>] [--settle <ms>]',
+    );
+    process.exit(1);
+  }
+
+  const result = await navigateAndRecord({
+    port: parsed.port,
+    url,
+    targetId: parsed.target,
+    harOutPath: parsed.har ? undefined : parsed.harOut,
+    settle: parsed.settle,
+  });
+
+  // Append to session HAR if active
+  if (parsed.har && result.har.log.entries.length > 0) {
+    appendToHar(parsed.har, result.har.log.entries);
+    console.error(`  [har:${parsed.har}] +${result.har.log.entries.length} entries`);
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        entryCount: result.entryCount,
+        harPath: result.harPath,
+        tabUrl: result.tab.url,
+        timedOut: result.timedOut,
+      },
+      null,
+      2,
+    ),
+  );
+  return;
+}
+
+export async function cmdNetwork(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture network <offline|online> [--target <id>]\n\n' +
+        'Toggle network connectivity for a tab. Use "offline" to simulate\n' +
+        'network failure (kills WebSocket connections, blocks HTTP requests).\n' +
+        'Use "online" to restore connectivity.',
+    );
+    process.exit(0);
+  }
+  const mode = parsed.positional[0];
+  if (!mode || !['offline', 'online'].includes(mode)) {
+    console.error('Usage: capture network <offline|online> [--target <id>]');
+    process.exit(1);
+  }
+  const offline = mode === 'offline';
+  const result = await withConnection(
+    parsed,
+    async (client) => {
+      await client.send('Network.enable');
+      await client.send('Network.emulateNetworkConditions', {
+        offline,
+        latency: offline ? -1 : 0,
+        downloadThroughput: offline ? 0 : -1,
+        uploadThroughput: offline ? 0 : -1,
+      });
+      return { network: mode, offline };
+    },
+    { settle: 0 },
+  );
+  console.log(JSON.stringify(result, null, 2));
+  if (offline) {
+    console.error('\nNetwork disabled. WebSocket connections will drop.');
+    console.error('Restore with: capture network online');
+  } else {
+    console.error('\nNetwork restored.');
+  }
+  return;
+}

package/src/cdp/commands/ui.ts

@@ -0,0 +1,172 @@
+import * as fs from 'fs';
+import { withConnection } from '../connection.js';
+import { captureScreenshot, autoScreenshot } from '../screenshot.js';
+import { getAccessibilityTree, flattenA11yTree } from '../a11y.js';
+import { clickByName, typeText, focusAndType } from '../../interact.js';
+import { nextStepPath } from '../../session-context.js';
+import { type ParsedArgs } from '../types.js';
+
+export async function cmdScreenshot(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture screenshot [--target <id>] [--out <path>] [--viewport <preset>] [--height <px>] [--full-page]\n\n' +
+        'Capture a screenshot of the targeted tab. Saves to --out or auto-generates a path.\n\n' +
+        'Options:\n' +
+        '  --viewport <preset>  Viewport preset (default: desktop)\n' +
+        '                       desktop-wide  1920x1080\n' +
+        '                       desktop       1280x800\n' +
+        '                       tablet        768x1024\n' +
+        '                       mobile        390x844\n' +
+        '  --height <px>        Override viewport height (e.g. 1600)\n' +
+        '  --full-page          Capture the entire scrollable page',
+    );
+    process.exit(0);
+  }
+  const VIEWPORTS: Record<string, { width: number; height: number }> = {
+    'desktop-wide': { width: 1920, height: 1080 },
+    'desktop': { width: 1280, height: 800 },
+    'tablet': { width: 768, height: 1024 },
+    'mobile': { width: 390, height: 844 },
+  };
+  const viewportName = parsed.viewport ?? 'desktop';
+  const viewport = VIEWPORTS[viewportName];
+  if (!viewport) {
+    console.error(`Unknown viewport "${viewportName}". Options: ${Object.keys(VIEWPORTS).join(', ')}`);
+    process.exit(1);
+  }
+  // Allow --height to override the viewport preset height
+  if (parsed.height) {
+    viewport.height = parsed.height;
+  }
+  const result = await withConnection(
+    parsed,
+    async (client) => {
+      const png = await captureScreenshot(client, viewport, { fullPage: parsed.fullPage });
+      const outPath = parsed.out
+        ? parsed.out
+        : (nextStepPath('screenshot', 'manual') ?? `/tmp/capture-screenshot-${Date.now()}.png`);
+      fs.writeFileSync(outPath, png);
+      return { path: outPath, bytes: png.length };
+    },
+    { settle: 0 },
+  );
+  console.log(JSON.stringify(result, null, 2));
+  return;
+}
+
+export async function cmdClick(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture click "name" [--role button|link|...] [--no-screenshot]\n\n' +
+        'Click an element by its accessible name. Auto-captures a screenshot after clicking.',
+    );
+    process.exit(0);
+  }
+  const name = parsed.positional[0];
+  if (!name) {
+    console.error('Usage: capture click "name" [--role button|link|...] [--no-screenshot]');
+    process.exit(1);
+  }
+  const clickSettle = parsed.settle !== undefined ? parsed.settle : (parsed.har ? 2500 : 1000);
+  const result = await withConnection(
+    parsed,
+    async (client) => {
+      const clickResult = await clickByName(client, name, parsed.role);
+      const screenshot = await autoScreenshot(client, 'click', name, parsed.noScreenshot);
+      return { ...clickResult, screenshot };
+    },
+    { settle: clickSettle },
+  );
+  console.log(JSON.stringify(result, null, 2));
+  return;
+}
+
+export async function cmdType(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture type "text" [--into "field name"] [--no-screenshot]\n\n' +
+        'Type text into the focused element, or into a named field with --into.',
+    );
+    process.exit(0);
+  }
+  const text = parsed.positional[0];
+  if (!text) {
+    console.error('Usage: capture type "text" [--into "field name"] [--no-screenshot]');
+    process.exit(1);
+  }
+  const result = await withConnection(
+    parsed,
+    async (client) => {
+      let field: string | null = null;
+      if (parsed.into) {
+        await focusAndType(client, parsed.into, text, parsed.role);
+        field = parsed.into;
+      } else {
+        await typeText(client, text);
+      }
+      const label = field ?? text;
+      const screenshot = await autoScreenshot(client, 'type', label, parsed.noScreenshot);
+      return { typed: text, field, screenshot };
+    },
+    { settle: parsed.settle !== undefined ? parsed.settle : (parsed.har ? 1500 : 500) },
+  );
+  console.log(JSON.stringify(result, null, 2));
+  return;
+}
+
+export async function cmdA11y(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(
+      'Usage: capture a11y [--target <id>] [--json] [--interactive]\n\n' +
+        'Get the accessibility tree. Use --interactive for interactive elements only.\n' +
+        'Use --json for structured JSON output.',
+    );
+    process.exit(0);
+  }
+  const result = await withConnection(
+    parsed,
+    async (client) => {
+      const tree = await getAccessibilityTree(client);
+
+      if (parsed.json) {
+        return tree;
+      }
+
+      // Flat text output
+      const lines = flattenA11yTree(tree, {
+        interactive: parsed.interactive,
+      });
+      return lines.join('\n');
+    },
+    { settle: 0 },
+  );
+
+  if (parsed.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result);
+  }
+
+  // Hint when a11y tree is sparse
+  if (!parsed.json) {
+    const lineCount = typeof result === 'string' ? result.split('\n').filter(Boolean).length : 0;
+    if (lineCount === 0) {
+      console.error(
+        '\nNo elements found.' +
+        (parsed.interactive ? ' Try without --interactive to see all nodes.' : '') +
+        '\n\nIf this page is part of your project, consider adding ARIA attributes:\n' +
+        '  - role="button|link|textbox" on interactive elements\n' +
+        '  - aria-label="..." on elements without visible text\n' +
+        '  - Semantic HTML (<button>, <input>, <nav>) provides roles automatically',
+      );
+    } else if (parsed.interactive && lineCount < 5) {
+      console.error(
+        `\nOnly ${lineCount} interactive element${lineCount === 1 ? '' : 's'} found. ` +
+        'If this seems low, the page may lack ARIA markup.\n' +
+        'Consider adding role and aria-label attributes to interactive elements in your frontend code.',
+      );
+    }
+  }
+
+  return;
+}

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