@crouton-kit/capture 1.3.8 → 1.3.9

package/src/cdp/execute.ts

@@ -1,113 +0,0 @@
-import { CDPClient } from './client.js';
-import { findTabByIdAcrossEndpoints } from './targets.js';
-import { buildExecExpression } from './exec-expression.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> {
-  if (!options.targetId) {
-    throw new Error('Use --target <tabId> to target a tab. Run "capture list" to see available tabs.');
-  }
-
-  const resolved = await findTabByIdAcrossEndpoints(options.targetId, options.port);
-  const tab = resolved?.tab ?? null;
-  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: buildExecExpression(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

@@ -1,47 +0,0 @@
-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/usage.ts

@@ -1,79 +0,0 @@
-export const CDP_USAGE = `CDP — browser automation via exec, a11y interactions, and screenshots.
-
-Commands:
-  exec <code>         Execute JavaScript in a browser tab (expressions, return, await)
-  exec --file <path>  Execute JS from file
-  detect              Detect CDP port (prioritizes default browser)
-  list                List all browser tabs
-  open <url>          Open URL in browser (returns tab ID)
-  reset-tab <url>     Abandon stuck tab, open fresh one (updates session)
-  screenshot          Capture screenshot
-  click "name"        Click element by accessible name
-  type "text"         Type text into focused element
-  a11y                Get accessibility tree
-  record              Passive HAR recording
-  navigate <url>      Navigate to URL and record HAR
-  network <offline|online>  Toggle network (simulate disconnect)
-  har create          Create a HAR recording (returns id)
-  har read [id]       Read accumulated HAR entries (id optional in active session)
-  har delete <id>     Delete a HAR recording
-  lib list            List available vault libs (dev checkout only)
-  lib search "<q>"     Fuzzy-search lib functions [--limit N]
-  lib show <name>     Lib + function summaries
-  lib read <name> [fn…]  Full input/output schemas (+ .ts source path)
-  cdp <Domain.method>  Send a raw CDP command capture doesn't wrap [--browser] [--params json] [--wait-event name]
-  measure <leaf>       Enriched snapshot substrate + read-only queries — see \`capture measure --help\`
-  motion <leaf>        Recorder lifecycle + read-only queries over a recording — see \`capture motion --help\`
-
-Options:
-  --port <port>       Override CDP port
-  --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
-  CDP_PORT / CDP_TARGET  Default port + tab when set by orchestrators
-  --new               Force new tab (open)
-  --record            Enable HAR recording (exec)
-  --har <id>          Append traffic to a HAR recording
-  --har-out <path>    HAR output path
-  --file <path>       Read JS from file (exec)
-  --duration <secs>   Recording duration (record, default: 10)
-  --settle <ms>       Settle time override (navigate, click, type)
-  --filter-url <pat>  Filter HAR entries by URL substring/regex (har read)
-  --filter-status <s> Filter HAR by status: code, prefix (4), or range (400-499)
-  --filter-method <m> Filter HAR by HTTP method (har read)
-  --limit <N>         Return only first N matching HAR entries (har read)
-  --browser           Target the browser-level connection (cdp)
-  --params '<json>'   JSON params for the method (cdp)
-  --wait-event <name> Wait for a CDP event and return it (cdp)
-  --timeout <ms>      Wait timeout, default 10000 (cdp)
-  --out <path>        Output path (screenshot)
-  --viewport <preset> Viewport preset: desktop-wide|desktop|tablet|mobile (default: desktop)
-  --height <px>       Override viewport height (screenshot)
-  --full-page         Capture entire scrollable page (screenshot)
-  --json              JSON output (a11y)
-  --interactive       Interactive elements only (a11y)
-  --role <role>       ARIA role filter (click)
-  --into "field"      Target field by name (type)
-  --no-screenshot     Skip auto-screenshot (click, type)
-
-Console output (errors, warnings) is always captured and printed to stderr.
-
-Examples:
-  capture detect
-  capture list
-  capture open "https://app.example.com" --new
-  capture exec "document.title" --target <id>
-  capture exec "return document.title" --target <id>
-  capture exec "const r = await fetch('/api/data'); return await r.json()" --target <id> --record
-  capture exec --file /tmp/scrape.js --target <id>
-  capture screenshot --target <id> --out /tmp/shot.png
-  capture a11y --target <id> --interactive
-  capture record --target <id> --duration 15
-  capture navigate "https://app.example.com/dashboard"
-  capture har create
-  capture exec "document.querySelector('form').submit()" --target <id> --har <id>
-  capture har read <id>
-  capture lib search "search emails"
-  capture lib read gmail searchEmails
-  capture exec "import {searchEmails} from 'libs/gmail'; const ctx = await getContext(); return await searchEmails({ ...ctx, query: 'invoice' })"
-  capture cdp Browser.grantPermissions --browser --params '{"origin":"http://localhost:3000","permissions":["notifications"]}'
-  capture cdp --help   Raw CDP escape hatch (Browser.*, ServiceWorker.*, ...) + how session --hold keeps grants alive
-`;

package/src/tab-session.ts

@@ -1,91 +0,0 @@
-/**
- * TabSession — universal tab lifecycle abstraction for parallel-safe CDP usage.
- *
- * Manages: tab creation, HAR recording, environment injection, and cleanup.
- * Callers create a TabSession, pass its env() to downstream scripts, and close() when done.
- *
- * Usage:
- *   const session = await TabSession.create({ url: 'https://app.hubspot.com' });
- *   console.log(session.env());  // { CDP_TARGET: '...', CDP_HAR_ID: '...' }
- *   await session.validate();     // throws if tab is gone
- *   await session.close();        // closes tab + deletes HAR
- */
-
-import {
-  navigateAndWait,
-  findTabById,
-  detectCdpPort,
-  CDPClient,
-} from './cdp.js';
-import { createHarRecording, deleteHarRecording } from './har-manager.js';
-
-export interface TabSessionOptions {
-  url: string;
-  forceNew?: boolean; // Default true (parallel-safe)
-  createHar?: boolean; // Default true
-  cdpPort?: number; // Auto-detect if not provided
-}
-
-export interface TabSessionEnv {
-  CDP_TARGET: string;
-  CDP_HAR_ID?: string;
-}
-
-export class TabSession {
-  readonly tabTarget: string;
-  readonly harId: string | null;
-  readonly cdpPort: number;
-  private closed = false;
-
-  private constructor(
-    tabTarget: string,
-    harId: string | null,
-    cdpPort: number,
-  ) {
-    this.tabTarget = tabTarget;
-    this.harId = harId;
-    this.cdpPort = cdpPort;
-  }
-
-  static async create(options: TabSessionOptions): Promise<TabSession> {
-    const port = options.cdpPort ?? (await detectCdpPort());
-    const tab = await navigateAndWait(port, options.url, {
-      forceNew: options.forceNew ?? true,
-    });
-    let harId: string | null = null;
-    if (options.createHar !== false) {
-      harId = createHarRecording().id;
-    }
-    return new TabSession(tab.id, harId, port);
-  }
-
-  async validate(): Promise<void> {
-    const tab = await findTabById(this.cdpPort, this.tabTarget);
-    if (!tab) throw new Error(`Tab ${this.tabTarget} no longer exists`);
-  }
-
-  env(): TabSessionEnv {
-    const result: TabSessionEnv = { CDP_TARGET: this.tabTarget };
-    if (this.harId) result.CDP_HAR_ID = this.harId;
-    return result;
-  }
-
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    try {
-      const tab = await findTabById(this.cdpPort, this.tabTarget);
-      if (tab?.webSocketDebuggerUrl) {
-        const client = new CDPClient(tab.webSocketDebuggerUrl);
-        await client.waitReady();
-        await client.send('Runtime.evaluate', {
-          expression: 'window.close()',
-        });
-        client.close();
-      }
-    } catch {
-      /* best-effort */
-    }
-    if (this.harId) deleteHarRecording(this.harId);
-  }
-}