@crouton-kit/capture 1.3.3 → 1.3.5

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

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