@crouton-kit/capture 1.3.2 → 1.3.4

package/src/cdp/tab-lock.ts

@@ -0,0 +1,132 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const LOCK_DIR = os.tmpdir();
+const LOCK_STALE_MS = 120_000;
+const LOCK_TIMEOUT_MS = 60_000;
+const LOCK_POLL_BASE_MS = 200;
+
+function lockPath(tabId: string): string {
+  return path.join(LOCK_DIR, `capture-cdp-tab-${tabId}.lock`);
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isLockStale(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const { pid, ts } = JSON.parse(content) as { pid: number; ts: number };
+    if (!isPidAlive(pid)) return true;
+    return Date.now() - ts > LOCK_STALE_MS;
+  } catch {
+    return true;
+  }
+}
+
+// Track locks held by this process for cleanup on exit
+const heldLocks = new Set<string>();
+let cleanupRegistered = false;
+
+function registerCleanup(): void {
+  if (cleanupRegistered) return;
+  cleanupRegistered = true;
+
+  const cleanup = () => {
+    for (const file of heldLocks) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Best-effort
+      }
+    }
+    heldLocks.clear();
+  };
+
+  process.on('exit', cleanup);
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(130);
+  });
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(143);
+  });
+}
+
+export async function acquireTabLock(tabId: string): Promise<void> {
+  registerCleanup();
+  const file = lockPath(tabId);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  let delay = LOCK_POLL_BASE_MS;
+
+  while (true) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      fs.writeSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      fs.closeSync(fd);
+      heldLocks.add(file);
+      return;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+    }
+
+    if (isLockStale(file)) {
+      try {
+        fs.unlinkSync(file);
+      } catch {
+        // Another process may have already removed it
+      }
+      continue;
+    }
+
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for CDP tab lock (${tabId}). ` +
+          `Another process may be using this tab. Lock file: ${file}`,
+      );
+    }
+
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(delay * 2, 2000);
+  }
+}
+
+export function isTabLocked(tabId: string): boolean {
+  const file = lockPath(tabId);
+  try {
+    fs.accessSync(file);
+    return !isLockStale(file);
+  } catch {
+    return false;
+  }
+}
+
+export function releaseTabLock(tabId: string): void {
+  const file = lockPath(tabId);
+  heldLocks.delete(file);
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    // Already removed — fine
+  }
+}
+
+export async function withTabLock<T>(
+  tabId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  await acquireTabLock(tabId);
+  try {
+    return await fn();
+  } finally {
+    releaseTabLock(tabId);
+  }
+}

package/src/cdp/targets.ts

@@ -0,0 +1,112 @@
+import { CDPClient } from './client.js';
+import { type CDPTarget } from './types.js';
+
+async function getBrowserClient(
+  port: number,
+): Promise<{ client: CDPClient; browserWsUrl: string }> {
+  const versionResp = await fetch(`http://localhost:${port}/json/version`);
+  if (!versionResp.ok) {
+    throw new Error(
+      `Failed to connect to CDP on port ${port}: ${versionResp.status}`,
+    );
+  }
+  const version = (await versionResp.json()) as {
+    webSocketDebuggerUrl: string;
+  };
+  const client = new CDPClient(version.webSocketDebuggerUrl);
+  await client.waitReady();
+  return { client, browserWsUrl: version.webSocketDebuggerUrl };
+}
+
+export async function listTargets(port: number): Promise<CDPTarget[]> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Enable target discovery to get all targets including pages
+    await client.send('Target.setDiscoverTargets', { discover: true });
+    const result = (await client.send('Target.getTargets')) as {
+      targetInfos: Array<{
+        targetId: string;
+        type: string;
+        title: string;
+        url: string;
+      }>;
+    };
+
+    // Convert to CDPTarget format with webSocketDebuggerUrl
+    return result.targetInfos.map((t) => ({
+      id: t.targetId,
+      title: t.title,
+      url: t.url,
+      type: t.type,
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${t.targetId}`,
+    }));
+  } finally {
+    client.close();
+  }
+}
+
+export async function findTab(
+  port: number,
+  urlPattern?: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  const pages = targets.filter((t) => t.type === 'page');
+
+  if (!urlPattern) {
+    // Return first page
+    return pages[0] ?? null;
+  }
+
+  // Find by URL pattern
+  const pattern = urlPattern.toLowerCase();
+  return pages.find((t) => t.url.toLowerCase().includes(pattern)) ?? null;
+}
+
+export async function findTabById(
+  port: number,
+  targetId: string,
+): Promise<CDPTarget | null> {
+  const targets = await listTargets(port);
+  // Exact match first
+  const exact = targets.find((t) => t.id === targetId);
+  if (exact) return exact;
+  // Prefix match (min 4 chars to avoid ambiguity)
+  if (targetId.length >= 4) {
+    const prefix = targetId.toUpperCase();
+    const matches = targets.filter((t) => t.id.toUpperCase().startsWith(prefix));
+    if (matches.length === 1) return matches[0];
+    if (matches.length > 1) {
+      throw new Error(
+        `Ambiguous target prefix "${targetId}" matches ${matches.length} tabs:\n` +
+          matches.map((t) => `  ${t.id.slice(0, 8)}  ${t.url}`).join('\n'),
+      );
+    }
+  }
+  return null;
+}
+
+export async function openTab(port: number, url: string): Promise<CDPTarget> {
+  const { client } = await getBrowserClient(port);
+
+  try {
+    // Create new target in background to avoid stealing user's focus
+    const result = (await client.send('Target.createTarget', {
+      url,
+      background: true,
+    })) as {
+      targetId: string;
+    };
+
+    // Return target info
+    return {
+      id: result.targetId,
+      title: '',
+      url,
+      type: 'page',
+      webSocketDebuggerUrl: `ws://localhost:${port}/devtools/page/${result.targetId}`,
+    };
+  } finally {
+    client.close();
+  }
+}

package/src/cdp/types.ts

@@ -0,0 +1,36 @@
+export interface CDPTarget {
+  id: string;
+  title: string;
+  url: string;
+  type: string;
+  webSocketDebuggerUrl?: string;
+}
+
+export interface ParsedArgs {
+  command: string;
+  positional: string[];
+  port?: number;
+  out?: string;
+  json?: boolean;
+  interactive?: boolean;
+  harOut?: string;
+  record?: boolean;
+  duration?: number;
+  settle?: number;
+  file?: string;
+  nested?: boolean;
+  har?: string;
+  new?: boolean;
+  target?: string;
+  role?: string;
+  into?: string;
+  noScreenshot?: boolean;
+  viewport?: string;
+  fullPage?: boolean;
+  height?: number;
+  help?: boolean;
+  filterUrl?: string;
+  filterStatus?: string;
+  filterMethod?: string;
+  limit?: number;
+}

package/src/cdp/usage.ts

@@ -0,0 +1,62 @@
+export const CDP_USAGE = `CDP — browser automation via exec, a11y interactions, and screenshots.
+
+Commands:
+  exec <code>         Execute JavaScript in a browser tab
+  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
+
+Options:
+  --port <port>       Override CDP port
+  --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
+  --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)
+  --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 "document.querySelector('.btn').click()" --target <id>
+  capture exec "fetch('/api/data').then(r=>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>
+`;