@crouton-kit/capture 1.3.1

package/src/har-manager.ts

@@ -0,0 +1,69 @@
+/**
+ * HAR recording management — create, read, append, delete.
+ *
+ * Extracted from cdp/index.ts for reuse by TabSession and other modules.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface HAREntry {
+  request: {
+    method: string;
+    url: string;
+    headers: Array<{ name: string; value: string }>;
+    postData?: { text: string };
+  };
+  response: {
+    status: number;
+    headers: Array<{ name: string; value: string }>;
+    content: { text?: string };
+  };
+  startedDateTime: string;
+}
+
+export type HarFile = { log: { entries: HAREntry[] } };
+
+export const HAR_DIR = '/tmp/capture-har';
+
+export function harFilePath(id: string): string {
+  return path.join(HAR_DIR, `${id}.json`);
+}
+
+export function createHarRecording(): { id: string; path: string } {
+  const id = Math.random().toString(36).slice(2, 8);
+  const harPath = harFilePath(id);
+  fs.mkdirSync(HAR_DIR, { recursive: true });
+  fs.writeFileSync(harPath, JSON.stringify({ log: { entries: [] } }, null, 2));
+  return { id, path: harPath };
+}
+
+export function readHarRecording(id: string): HarFile | null {
+  try {
+    return JSON.parse(fs.readFileSync(harFilePath(id), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function appendToHarRecording(id: string, entries: HAREntry[]): void {
+  const harPath = harFilePath(id);
+  let har: HarFile;
+
+  try {
+    har = JSON.parse(fs.readFileSync(harPath, 'utf-8'));
+  } catch {
+    har = { log: { entries: [] } };
+  }
+
+  har.log.entries.push(...entries);
+  fs.writeFileSync(harPath, JSON.stringify(har, null, 2));
+}
+
+export function deleteHarRecording(id: string): void {
+  try {
+    fs.unlinkSync(harFilePath(id));
+  } catch {
+    // best-effort — file may already be gone
+  }
+}

package/src/interact.ts

@@ -0,0 +1,144 @@
+/**
+ * A11y-driven interactions — click and type using the accessibility tree
+ * instead of brittle CSS selectors.
+ *
+ * Pipeline: getFullAXTree → find by name/role → DOM.getBoxModel → Input.dispatchMouseEvent
+ *
+ * Uses getFullAXTree instead of queryAXTree because queryAXTree hangs on
+ * complex pages (7000+ AX nodes) when given the DOM root nodeId.
+ */
+
+import type { CDPClient } from './cdp.js';
+
+interface ClickResult {
+  x: number;
+  y: number;
+  role: string;
+  name: string;
+}
+
+interface FullAXNode {
+  nodeId: string;
+  backendDOMNodeId?: number;
+  role?: { value: string };
+  name?: { value: string };
+  childIds?: string[];
+}
+
+/**
+ * Click an element by its accessible name. Optionally filter by ARIA role.
+ *
+ * Uses Accessibility.getFullAXTree to find elements by name/role,
+ * then dispatches mouse events at the element's center coordinates.
+ */
+export async function clickByName(
+  client: CDPClient,
+  name: string,
+  role?: string,
+): Promise<ClickResult> {
+  await client.send('Accessibility.enable');
+  await client.send('DOM.enable');
+
+  const { nodes } = (await client.send('Accessibility.getFullAXTree')) as {
+    nodes: FullAXNode[];
+  };
+  await client.send('Accessibility.disable');
+
+  // Find nodes matching the accessible name (exact match)
+  const nameLower = name.toLowerCase();
+  const matches = nodes.filter((n) => {
+    if (!n.backendDOMNodeId) return false;
+    if (!n.name?.value) return false;
+    if (n.name.value.toLowerCase() !== nameLower) return false;
+    if (role && n.role?.value !== role) return false;
+    return true;
+  });
+
+  if (matches.length === 0) {
+    throw new Error(
+      `No element found with accessible name "${name}"${role ? ` and role "${role}"` : ''}. ` +
+        'Run `capture a11y --interactive` to see available elements.',
+    );
+  }
+
+  if (matches.length > 1 && !role) {
+    // Auto-prefer input-like roles for better type --into ergonomics
+    const INPUT_ROLES = new Set(['textbox', 'searchbox', 'combobox', 'textarea', 'spinbutton']);
+    const inputMatches = matches.filter((n) => n.role?.value && INPUT_ROLES.has(n.role.value));
+    if (inputMatches.length === 1) {
+      // Unambiguous input element — use it
+      matches.length = 0;
+      matches.push(inputMatches[0]);
+    } else {
+      const summary = matches
+        .slice(0, 5)
+        .map((n) => `  ${n.role?.value} "${n.name?.value}"`)
+        .join('\n');
+      throw new Error(
+        `Multiple elements match "${name}" — disambiguate with --role:\n${summary}`,
+      );
+    }
+  }
+
+  const match = matches[0];
+  const backendNodeId = match.backendDOMNodeId!;
+
+  // Scroll into view
+  await client.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+
+  // Get box model for click coordinates
+  const { model } = (await client.send('DOM.getBoxModel', { backendNodeId })) as {
+    model: { content: number[] };
+  };
+
+  // Content quad is [x1,y1, x2,y2, x3,y3, x4,y4] — calculate center
+  const quad = model.content;
+  const x = (quad[0] + quad[2] + quad[4] + quad[6]) / 4;
+  const y = (quad[1] + quad[3] + quad[5] + quad[7]) / 4;
+
+  // Click: mousePressed + mouseReleased
+  await client.send('Input.dispatchMouseEvent', {
+    type: 'mousePressed',
+    x,
+    y,
+    button: 'left',
+    clickCount: 1,
+  });
+  await client.send('Input.dispatchMouseEvent', {
+    type: 'mouseReleased',
+    x,
+    y,
+    button: 'left',
+    clickCount: 1,
+  });
+
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    role: match.role?.value ?? 'unknown',
+    name: match.name?.value ?? name,
+  };
+}
+
+/**
+ * Type text into the currently focused element via CDP Input.insertText.
+ */
+export async function typeText(client: CDPClient, text: string): Promise<void> {
+  await client.send('Input.insertText', { text });
+}
+
+/**
+ * Click a field by accessible name, then type text into it.
+ */
+export async function focusAndType(
+  client: CDPClient,
+  fieldName: string,
+  text: string,
+  role?: string,
+): Promise<ClickResult> {
+  const result = await clickByName(client, fieldName, role);
+  // Small delay for focus to settle
+  await new Promise((r) => setTimeout(r, 100));
+  await typeText(client, text);
+  return result;
+}

package/src/session-context.ts

@@ -0,0 +1,85 @@
+/**
+ * Session Context — persists active session state so CDP commands
+ * can auto-fill --target, --har, and --out without manual threading.
+ *
+ * State is written to /tmp/capture-sessions/.active (JSON).
+ * Stale sessions (dir deleted, crashed process) are cleaned up on read.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
+const ACTIVE_PATH = path.join(CAPTURE_ROOT, '.active');
+
+export interface ActiveSessionState {
+  sessionId: string;
+  dir: string;
+  harId: string | null;
+  targetId: string | null;
+  stepCount: number;
+}
+
+export function getActiveSession(): ActiveSessionState | null {
+  try {
+    if (!fs.existsSync(ACTIVE_PATH)) return null;
+    const state = JSON.parse(fs.readFileSync(ACTIVE_PATH, 'utf-8')) as ActiveSessionState;
+    // Validate session dir still exists — clean up stale files
+    if (!fs.existsSync(state.dir)) {
+      clearActiveSession();
+      return null;
+    }
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+export function setActiveSession(state: ActiveSessionState): void {
+  fs.mkdirSync(CAPTURE_ROOT, { recursive: true });
+  fs.writeFileSync(ACTIVE_PATH, JSON.stringify(state, null, 2));
+}
+
+export function clearActiveSession(): void {
+  try {
+    fs.unlinkSync(ACTIVE_PATH);
+  } catch {
+    // Already gone
+  }
+}
+
+export function updateActiveSession(patch: Partial<ActiveSessionState>): ActiveSessionState | null {
+  const current = getActiveSession();
+  if (!current) return null;
+  const updated = { ...current, ...patch };
+  setActiveSession(updated);
+  return updated;
+}
+
+function sanitizeLabel(label: string): string {
+  return label
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40);
+}
+
+/**
+ * Returns the next auto-numbered screenshot path for the active session.
+ * Format: {dir}/shots/{NN}-{action}-{sanitized-label}.png
+ * Increments stepCount in the session state.
+ */
+export function nextStepPath(action: string, label: string): string | null {
+  const session = getActiveSession();
+  if (!session) return null;
+
+  const step = session.stepCount + 1;
+  const nn = String(step).padStart(2, '0');
+  const sanitized = sanitizeLabel(label);
+  const filename = `${nn}-${action}-${sanitized}.png`;
+  const shotPath = path.join(session.dir, 'shots', filename);
+
+  updateActiveSession({ stepCount: step });
+  return shotPath;
+}

package/src/tab-session.ts

@@ -0,0 +1,91 @@
+/**
+ * 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);
+  }
+}