@crouton-kit/capture 1.3.8 → 1.3.10

package/src/cdp/commands/har.ts

@@ -1,128 +0,0 @@
-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

@@ -1,183 +0,0 @@
-import { detectCdpPortsAsync, detectCdpPort, getDefaultBrowserId, pickPreferredEndpoint } 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 preferred = pickPreferredEndpoint(endpoints, getDefaultBrowserId());
-  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

@@ -1,121 +0,0 @@
-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

@@ -1,172 +0,0 @@
-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> | --url <pattern>] [--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;
-}