cdp-skill 1.0.2 → 1.0.4

package/src/cdp/target-and-session.js

@@ -0,0 +1,439 @@
+/**
+ * Target and Session Management Module
+ * CDP target management and session registry for browser tabs
+ *
+ * PUBLIC EXPORTS:
+ * - createTargetManager(connection) - Factory for target manager
+ * - createSessionRegistry(connection) - Factory for session registry
+ * - createPageSession(connection, sessionId, targetId) - Factory for page session
+ *
+ * @module cdp-skill/cdp/target-and-session
+ */
+
+/**
+ * Create a target manager for browser targets
+ * @param {import('../types.js').CDPConnection} connection - CDP connection
+ * @returns {Object} Target manager interface
+ */
+export function createTargetManager(connection) {
+  const targets = new Map();
+  let discoveryEnabled = false;
+  let boundHandlers = null;
+
+  function onTargetCreated(params) {
+    targets.set(params.targetInfo.targetId, params.targetInfo);
+  }
+
+  function onTargetDestroyed(params) {
+    targets.delete(params.targetId);
+  }
+
+  function onTargetInfoChanged(params) {
+    targets.set(params.targetInfo.targetId, params.targetInfo);
+  }
+
+  /**
+   * Enable automatic target discovery
+   * @returns {Promise<void>}
+   */
+  async function enableDiscovery() {
+    if (discoveryEnabled) return;
+
+    boundHandlers = { onTargetCreated, onTargetDestroyed, onTargetInfoChanged };
+    connection.on('Target.targetCreated', boundHandlers.onTargetCreated);
+    connection.on('Target.targetDestroyed', boundHandlers.onTargetDestroyed);
+    connection.on('Target.targetInfoChanged', boundHandlers.onTargetInfoChanged);
+
+    await connection.send('Target.setDiscoverTargets', { discover: true });
+    discoveryEnabled = true;
+  }
+
+  /**
+   * Disable automatic target discovery
+   * @returns {Promise<void>}
+   */
+  async function disableDiscovery() {
+    if (!discoveryEnabled) return;
+
+    await connection.send('Target.setDiscoverTargets', { discover: false });
+
+    if (boundHandlers) {
+      connection.off('Target.targetCreated', boundHandlers.onTargetCreated);
+      connection.off('Target.targetDestroyed', boundHandlers.onTargetDestroyed);
+      connection.off('Target.targetInfoChanged', boundHandlers.onTargetInfoChanged);
+    }
+
+    discoveryEnabled = false;
+  }
+
+  /**
+   * Get all targets, optionally filtered
+   * @param {Object} [filter] - Optional target filter
+   * @returns {Promise<Array>} Array of target info objects
+   */
+  async function getTargets(filter = null) {
+    const result = await connection.send('Target.getTargets', {
+      filter: filter ? [filter] : undefined
+    });
+
+    for (const info of result.targetInfos) {
+      targets.set(info.targetId, info);
+    }
+
+    return result.targetInfos;
+  }
+
+  /**
+   * Get page targets only
+   * @returns {Promise<Array>} Array of page target info objects
+   */
+  async function getPages() {
+    const allTargets = await getTargets();
+    return allTargets.filter(t => t.type === 'page');
+  }
+
+  /**
+   * Create a new browser target (tab)
+   * @param {string} [url='about:blank'] - Initial URL
+   * @param {Object} [options] - Creation options
+   * @param {number} [options.width] - Viewport width
+   * @param {number} [options.height] - Viewport height
+   * @param {boolean} [options.background=false] - Create in background
+   * @param {boolean} [options.newWindow=false] - Create in new window
+   * @returns {Promise<string>} Target ID
+   */
+  async function createTarget(url = 'about:blank', options = {}) {
+    const result = await connection.send('Target.createTarget', {
+      url,
+      width: options.width,
+      height: options.height,
+      background: options.background ?? false,
+      newWindow: options.newWindow ?? false
+    });
+    return result.targetId;
+  }
+
+  /**
+   * Close a target
+   * @param {string} targetId - Target to close
+   * @returns {Promise<boolean>} Success
+   */
+  async function closeTarget(targetId) {
+    const result = await connection.send('Target.closeTarget', { targetId });
+    targets.delete(targetId);
+    return result.success ?? true;
+  }
+
+  /**
+   * Activate (bring to front) a target
+   * @param {string} targetId - Target to activate
+   * @returns {Promise<void>}
+   */
+  async function activateTarget(targetId) {
+    await connection.send('Target.activateTarget', { targetId });
+  }
+
+  /**
+   * Get detailed info for a target
+   * @param {string} targetId - Target ID
+   * @returns {Promise<Object>} Target info
+   */
+  async function getTargetInfo(targetId) {
+    const result = await connection.send('Target.getTargetInfo', { targetId });
+    targets.set(targetId, result.targetInfo);
+    return result.targetInfo;
+  }
+
+  /**
+   * Get cached target info
+   * @param {string} targetId - Target ID
+   * @returns {Object|undefined} Cached target info
+   */
+  function getCachedTarget(targetId) {
+    return targets.get(targetId);
+  }
+
+  /**
+   * Get all cached targets
+   * @returns {Map} Cached targets map
+   */
+  function getCachedTargets() {
+    return new Map(targets);
+  }
+
+  /**
+   * Clean up target manager
+   * @returns {Promise<void>}
+   */
+  async function cleanup() {
+    await disableDiscovery();
+    targets.clear();
+  }
+
+  return {
+    enableDiscovery,
+    disableDiscovery,
+    getTargets,
+    getPages,
+    createTarget,
+    closeTarget,
+    activateTarget,
+    getTargetInfo,
+    getCachedTarget,
+    getCachedTargets,
+    cleanup
+  };
+}
+
+/**
+ * Create a session registry for managing CDP sessions
+ * @param {import('../types.js').CDPConnection} connection - CDP connection
+ * @returns {Object} Session registry interface
+ */
+export function createSessionRegistry(connection) {
+  const sessions = new Map();
+  const targetToSession = new Map();
+  const pendingAttach = new Map();
+  let boundHandlers = null;
+
+  function onAttached(params) {
+    const { sessionId, targetInfo } = params;
+    sessions.set(sessionId, { targetId: targetInfo.targetId, attached: true });
+    targetToSession.set(targetInfo.targetId, sessionId);
+  }
+
+  function onDetached(params) {
+    const { sessionId } = params;
+    const session = sessions.get(sessionId);
+    if (session) {
+      targetToSession.delete(session.targetId);
+      sessions.delete(sessionId);
+    }
+  }
+
+  function onTargetDestroyed(params) {
+    const { targetId } = params;
+    const sessionId = targetToSession.get(targetId);
+    if (sessionId) {
+      sessions.delete(sessionId);
+      targetToSession.delete(targetId);
+    }
+  }
+
+  // Setup handlers on creation
+  boundHandlers = { onAttached, onDetached, onTargetDestroyed };
+  connection.on('Target.attachedToTarget', boundHandlers.onAttached);
+  connection.on('Target.detachedFromTarget', boundHandlers.onDetached);
+  connection.on('Target.targetDestroyed', boundHandlers.onTargetDestroyed);
+
+  async function doAttach(targetId) {
+    const result = await connection.send('Target.attachToTarget', {
+      targetId,
+      flatten: true
+    });
+
+    const sessionId = result.sessionId;
+    sessions.set(sessionId, { targetId, attached: true });
+    targetToSession.set(targetId, sessionId);
+
+    return sessionId;
+  }
+
+  /**
+   * Attach to a target
+   * @param {string} targetId - Target to attach to
+   * @returns {Promise<string>} Session ID
+   */
+  async function attach(targetId) {
+    const existing = targetToSession.get(targetId);
+    if (existing) return existing;
+
+    const pending = pendingAttach.get(targetId);
+    if (pending) return pending;
+
+    const attachPromise = doAttach(targetId);
+    pendingAttach.set(targetId, attachPromise);
+
+    try {
+      return await attachPromise;
+    } finally {
+      pendingAttach.delete(targetId);
+    }
+  }
+
+  /**
+   * Detach from a session
+   * @param {string} sessionId - Session to detach
+   * @returns {Promise<void>}
+   */
+  async function detach(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session) return;
+
+    await connection.send('Target.detachFromTarget', { sessionId });
+    sessions.delete(sessionId);
+    targetToSession.delete(session.targetId);
+  }
+
+  /**
+   * Detach from a target by target ID
+   * @param {string} targetId - Target to detach from
+   * @returns {Promise<void>}
+   */
+  async function detachByTarget(targetId) {
+    const sessionId = targetToSession.get(targetId);
+    if (sessionId) {
+      await detach(sessionId);
+    }
+  }
+
+  /**
+   * Get session ID for a target
+   * @param {string} targetId - Target ID
+   * @returns {string|undefined} Session ID
+   */
+  function getSessionForTarget(targetId) {
+    return targetToSession.get(targetId);
+  }
+
+  /**
+   * Get target ID for a session
+   * @param {string} sessionId - Session ID
+   * @returns {string|undefined} Target ID
+   */
+  function getTargetForSession(sessionId) {
+    return sessions.get(sessionId)?.targetId;
+  }
+
+  /**
+   * Check if attached to a target
+   * @param {string} targetId - Target ID
+   * @returns {boolean}
+   */
+  function isAttached(targetId) {
+    return targetToSession.has(targetId);
+  }
+
+  /**
+   * Get all sessions
+   * @returns {Array<{sessionId: string, targetId: string}>}
+   */
+  function getAllSessions() {
+    return Array.from(sessions.entries()).map(([sessionId, data]) => ({
+      sessionId,
+      targetId: data.targetId
+    }));
+  }
+
+  /**
+   * Detach from all sessions
+   * @returns {Promise<void>}
+   */
+  async function detachAll() {
+    const sessionIds = Array.from(sessions.keys());
+    await Promise.all(sessionIds.map(s => detach(s)));
+  }
+
+  /**
+   * Clean up session registry
+   * @returns {Promise<void>}
+   */
+  async function cleanup() {
+    await detachAll();
+    if (boundHandlers) {
+      connection.off('Target.attachedToTarget', boundHandlers.onAttached);
+      connection.off('Target.detachedFromTarget', boundHandlers.onDetached);
+      connection.off('Target.targetDestroyed', boundHandlers.onTargetDestroyed);
+    }
+    sessions.clear();
+    targetToSession.clear();
+    pendingAttach.clear();
+  }
+
+  return {
+    attach,
+    detach,
+    detachByTarget,
+    getSessionForTarget,
+    getTargetForSession,
+    isAttached,
+    getAllSessions,
+    detachAll,
+    cleanup
+  };
+}
+
+/**
+ * Create a page session for CDP communication with a specific page
+ * @param {import('../types.js').CDPConnection} connection - CDP connection
+ * @param {string} sessionId - Session ID
+ * @param {string} targetId - Target ID
+ * @returns {import('../types.js').CDPSession} Page session interface
+ */
+export function createPageSession(connection, sessionId, targetId) {
+  let valid = true;
+  let detachHandler = null;
+
+  function onDetached(params) {
+    if (params.sessionId === sessionId) {
+      valid = false;
+      if (detachHandler) {
+        connection.off('Target.detachedFromTarget', detachHandler);
+      }
+    }
+  }
+
+  detachHandler = onDetached;
+  connection.on('Target.detachedFromTarget', detachHandler);
+
+  /**
+   * Send CDP command via this session
+   * @param {string} method - CDP method name
+   * @param {Object} [params={}] - Command parameters
+   * @returns {Promise<Object>} Command result
+   */
+  async function send(method, params = {}) {
+    if (!valid) {
+      throw new Error(`Session ${sessionId} is no longer valid (target was closed or detached)`);
+    }
+    return connection.sendToSession(sessionId, method, params);
+  }
+
+  /**
+   * Subscribe to session-scoped event
+   * @param {string} event - Event name
+   * @param {function} callback - Event handler
+   */
+  function on(event, callback) {
+    connection.on(`${sessionId}:${event}`, callback);
+  }
+
+  /**
+   * Unsubscribe from session-scoped event
+   * @param {string} event - Event name
+   * @param {function} callback - Event handler
+   */
+  function off(event, callback) {
+    connection.off(`${sessionId}:${event}`, callback);
+  }
+
+  /**
+   * Dispose the session
+   */
+  function dispose() {
+    valid = false;
+    if (detachHandler) {
+      connection.off('Target.detachedFromTarget', detachHandler);
+    }
+  }
+
+  return {
+    send,
+    on,
+    off,
+    dispose,
+    isValid: () => valid,
+    get sessionId() { return sessionId; },
+    get targetId() { return targetId; }
+  };
+}

package/src/cdp-skill.js

@@ -11,13 +11,13 @@
  *   node src/cdp-skill.js --debug '{"steps":[...]}'  # Enable debug logging
  */
 
-import { createBrowser, getChromeStatus } from './cdp.js';
-import { createPageController } from './page.js';
-import { createElementLocator, createInputEmulator } from './dom.js';
-import { createScreenshotCapture, createConsoleCapture, createPdfCapture } from './capture.js';
+import { createBrowser, getChromeStatus } from './cdp/index.js';
+import { createPageController } from './page/index.js';
+import { createElementLocator, createInputEmulator } from './dom/index.js';
+import { createScreenshotCapture, createConsoleCapture, createPdfCapture } from './capture/index.js';
 import { createAriaSnapshot } from './aria.js';
-import { createCookieManager } from './page.js';
-import { runSteps } from './runner.js';
+import { createCookieManager } from './page/index.js';
+import { runSteps } from './runner/index.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -424,6 +424,7 @@ async function main() {
     const host = config.host || 'localhost';
     const port = config.port || 9222;
     const timeout = config.timeout || 30000;
+    const headless = config.headless || false;  // Run Chrome in headless mode (no focus stealing)
     const tab = json.tab || config.tab;  // Top-level tab takes precedence
 
     // Handle chromeStatus specially - no session needed
@@ -442,16 +443,29 @@ async function main() {
       process.exit(result.status === 'ok' ? 0 : 1);
     }
 
-    // Connect to browser
+    // Connect to browser, auto-launch if needed
     browser = createBrowser({ host, port, connectTimeout: timeout });
 
     try {
       await browser.connect();
     } catch (err) {
-      throw {
-        type: ErrorType.CONNECTION,
-        message: `Chrome not running on ${host}:${port} - ${err.message}`
-      };
+      // Chrome not running - try to auto-launch
+      const status = await getChromeStatus({ host, port, autoLaunch: true, headless });
+      if (!status.running) {
+        throw {
+          type: ErrorType.CONNECTION,
+          message: `Chrome not running and failed to launch: ${status.error || 'unknown error'}`
+        };
+      }
+      // Retry connection after launch
+      try {
+        await browser.connect();
+      } catch (retryErr) {
+        throw {
+          type: ErrorType.CONNECTION,
+          message: `Chrome launched but connection failed: ${retryErr.message}`
+        };
+      }
     }
 
     // Get page session - requires explicit targetId or openTab step

package/src/constants.js

@@ -0,0 +1,79 @@
+/**
+ * Constants
+ * Centralized configuration values used across the codebase
+ *
+ * EXPORTS:
+ * - TIMEOUTS - Timeout values in milliseconds
+ * - POLL_INTERVALS - Polling interval values
+ * - LIMITS - Various size and count limits
+ * - VALID_FORMATS - Allowed screenshot formats
+ * - KEY_DEFINITIONS - Special key code mappings
+ * - NON_EDITABLE_INPUT_TYPES - Input types that cannot be typed into
+ */
+
+// Timeouts (milliseconds)
+export const TIMEOUTS = {
+  MAX: 300000,           // 5 minutes - absolute maximum
+  DEFAULT: 10000,        // 10 seconds - default for actionability
+  NETWORK_IDLE: 500,     // network idle threshold
+  STABILITY: 50,         // DOM stability check
+};
+
+export const POLL_INTERVALS = {
+  DEFAULT: 100,          // standard polling
+  FAST: 50,              // actionability retries
+};
+
+export const LIMITS = {
+  MAX_CONSOLE_MESSAGES: 10000,
+  MAX_SCREENSHOT_DIMENSION: 16384,
+  MAX_PENDING_REQUESTS: 10000,
+  MAX_DOM_NODES: 500,
+};
+
+export const VALID_FORMATS = ['png', 'jpeg', 'webp'];
+
+/**
+ * Special key definitions for keyboard input
+ */
+export const KEY_DEFINITIONS = {
+  Enter: { key: 'Enter', code: 'Enter', keyCode: 13, text: '\r' },
+  Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
+  Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
+  Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
+  Delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
+  Space: { key: ' ', code: 'Space', keyCode: 32, text: ' ' },
+  ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
+  ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
+  ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
+  ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
+  Shift: { key: 'Shift', code: 'ShiftLeft', keyCode: 16 },
+  Control: { key: 'Control', code: 'ControlLeft', keyCode: 17 },
+  Alt: { key: 'Alt', code: 'AltLeft', keyCode: 18 },
+  Meta: { key: 'Meta', code: 'MetaLeft', keyCode: 91 },
+  F1: { key: 'F1', code: 'F1', keyCode: 112 },
+  F2: { key: 'F2', code: 'F2', keyCode: 113 },
+  F3: { key: 'F3', code: 'F3', keyCode: 114 },
+  F4: { key: 'F4', code: 'F4', keyCode: 115 },
+  F5: { key: 'F5', code: 'F5', keyCode: 116 },
+  F6: { key: 'F6', code: 'F6', keyCode: 117 },
+  F7: { key: 'F7', code: 'F7', keyCode: 118 },
+  F8: { key: 'F8', code: 'F8', keyCode: 119 },
+  F9: { key: 'F9', code: 'F9', keyCode: 120 },
+  F10: { key: 'F10', code: 'F10', keyCode: 121 },
+  F11: { key: 'F11', code: 'F11', keyCode: 122 },
+  F12: { key: 'F12', code: 'F12', keyCode: 123 },
+  Home: { key: 'Home', code: 'Home', keyCode: 36 },
+  End: { key: 'End', code: 'End', keyCode: 35 },
+  PageUp: { key: 'PageUp', code: 'PageUp', keyCode: 33 },
+  PageDown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },
+  Insert: { key: 'Insert', code: 'Insert', keyCode: 45 }
+};
+
+/**
+ * Non-editable input types that cannot receive text input
+ */
+export const NON_EDITABLE_INPUT_TYPES = [
+  'button', 'checkbox', 'color', 'file', 'hidden',
+  'image', 'radio', 'range', 'reset', 'submit'
+];