cdp-skill 1.0.2 → 1.0.4

package/src/cdp/connection.js

@@ -0,0 +1,369 @@
+/**
+ * CDP Connection Module
+ * WebSocket-based Chrome DevTools Protocol connection handling
+ *
+ * PUBLIC EXPORTS:
+ * - createConnection(wsUrl, options?) - Factory for CDP WebSocket connection
+ *
+ * @module cdp-skill/cdp/connection
+ */
+
+/**
+ * Create a CDP WebSocket connection
+ * @param {string} wsUrl - WebSocket URL for CDP endpoint
+ * @param {Object} [options] - Connection options
+ * @param {number} [options.maxRetries=5] - Max reconnection attempts
+ * @param {number} [options.retryDelay=1000] - Base delay between retries
+ * @param {number} [options.maxRetryDelay=30000] - Maximum retry delay cap
+ * @param {boolean} [options.autoReconnect=false] - Enable auto reconnection
+ * @returns {import('../types.js').CDPConnection} Connection interface
+ */
+export function createConnection(wsUrl, options = {}) {
+  const maxRetries = options.maxRetries ?? 5;
+  const retryDelay = options.retryDelay ?? 1000;
+  const maxRetryDelay = options.maxRetryDelay ?? 30000;
+  const autoReconnect = options.autoReconnect ?? false;
+
+  let ws = null;
+  let messageId = 0;
+  const pendingCommands = new Map();
+  const eventListeners = new Map();
+  let connected = false;
+  let connecting = false;
+  let onCloseCallback = null;
+  let reconnecting = false;
+  let retryAttempt = 0;
+  let intentionalClose = false;
+
+  function emit(event, data = {}) {
+    const listeners = eventListeners.get(event);
+    if (listeners) {
+      for (const callback of listeners) {
+        try {
+          callback(data);
+        } catch (err) {
+          console.error(`Event handler error for ${event}:`, err);
+        }
+      }
+    }
+  }
+
+  function calculateBackoff(attempt) {
+    const delay = retryDelay * Math.pow(2, attempt);
+    return Math.min(delay, maxRetryDelay);
+  }
+
+  function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  function rejectPendingCommands(reason) {
+    for (const [id, pending] of pendingCommands) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(reason));
+    }
+    pendingCommands.clear();
+  }
+
+  function handleMessage(data) {
+    let message;
+    try {
+      message = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+
+    if (message.id !== undefined) {
+      const pending = pendingCommands.get(message.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        pendingCommands.delete(message.id);
+        if (message.error) {
+          pending.reject(new Error(`CDP error: ${message.error.message}`));
+        } else {
+          pending.resolve(message.result);
+        }
+      }
+      return;
+    }
+
+    if (message.method) {
+      if (message.sessionId) {
+        const sessionEventKey = `${message.sessionId}:${message.method}`;
+        const sessionListeners = eventListeners.get(sessionEventKey);
+        if (sessionListeners) {
+          for (const callback of sessionListeners) {
+            try {
+              callback(message.params, message.sessionId);
+            } catch (err) {
+              console.error(`Event handler error for ${sessionEventKey}:`, err);
+            }
+          }
+        }
+      }
+
+      const globalListeners = eventListeners.get(message.method);
+      if (globalListeners) {
+        for (const callback of globalListeners) {
+          try {
+            callback(message.params, message.sessionId);
+          } catch (err) {
+            console.error(`Event handler error for ${message.method}:`, err);
+          }
+        }
+      }
+    }
+  }
+
+  function setupWebSocketListeners() {
+    ws.addEventListener('close', () => {
+      const wasConnected = connected;
+      connected = false;
+      connecting = false;
+      rejectPendingCommands('Connection closed');
+
+      if (wasConnected && !intentionalClose && autoReconnect) {
+        attemptReconnect();
+      } else if (wasConnected && onCloseCallback && !intentionalClose) {
+        onCloseCallback('Connection closed unexpectedly');
+      }
+    });
+
+    ws.addEventListener('message', (event) => handleMessage(event.data));
+  }
+
+  async function attemptReconnect() {
+    if (reconnecting || intentionalClose) return;
+
+    reconnecting = true;
+    retryAttempt = 0;
+
+    while (retryAttempt < maxRetries && !intentionalClose) {
+      const delay = calculateBackoff(retryAttempt);
+      emit('reconnecting', { attempt: retryAttempt + 1, delay });
+
+      await sleep(delay);
+      if (intentionalClose) break;
+
+      try {
+        await doReconnect();
+        reconnecting = false;
+        retryAttempt = 0;
+        emit('reconnected', {});
+        return;
+      } catch {
+        retryAttempt++;
+      }
+    }
+
+    reconnecting = false;
+    if (!intentionalClose && onCloseCallback) {
+      onCloseCallback('Connection closed unexpectedly after max retries');
+    }
+  }
+
+  function doReconnect() {
+    return new Promise((resolve, reject) => {
+      ws = new WebSocket(wsUrl);
+      ws.addEventListener('open', () => {
+        connected = true;
+        setupWebSocketListeners();
+        resolve();
+      });
+      ws.addEventListener('error', (event) => {
+        reject(new Error(`CDP reconnection error: ${event.message || 'Connection failed'}`));
+      });
+    });
+  }
+
+  /**
+   * Establish WebSocket connection
+   * @returns {Promise<void>}
+   */
+  async function connect() {
+    if (connected) return;
+    if (connecting) throw new Error('Connection already in progress');
+
+    connecting = true;
+    intentionalClose = false;
+
+    return new Promise((resolve, reject) => {
+      ws = new WebSocket(wsUrl);
+
+      ws.addEventListener('open', () => {
+        connected = true;
+        connecting = false;
+        resolve();
+      });
+
+      ws.addEventListener('error', (event) => {
+        connecting = false;
+        reject(new Error(`CDP connection error: ${event.message || 'Connection failed'}`));
+      });
+
+      ws.addEventListener('close', () => {
+        const wasConnected = connected;
+        connected = false;
+        connecting = false;
+        rejectPendingCommands('Connection closed');
+
+        if (wasConnected && !intentionalClose && autoReconnect) {
+          attemptReconnect();
+        } else if (wasConnected && onCloseCallback && !intentionalClose) {
+          onCloseCallback('Connection closed unexpectedly');
+        }
+      });
+
+      ws.addEventListener('message', (event) => handleMessage(event.data));
+    });
+  }
+
+  /**
+   * Send CDP command
+   * @param {string} method - CDP method name
+   * @param {Object} [params={}] - Command parameters
+   * @param {number} [timeout=30000] - Command timeout in ms
+   * @returns {Promise<Object>} Command result
+   */
+  async function send(method, params = {}, timeout = 30000) {
+    if (!connected) throw new Error('Not connected to CDP');
+
+    const id = ++messageId;
+    const message = JSON.stringify({ id, method, params });
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingCommands.delete(id);
+        reject(new Error(`CDP command timeout: ${method}`));
+      }, timeout);
+
+      pendingCommands.set(id, { resolve, reject, timer });
+      ws.send(message);
+    });
+  }
+
+  /**
+   * Send CDP command to specific session
+   * @param {string} sessionId - Target session ID
+   * @param {string} method - CDP method name
+   * @param {Object} [params={}] - Command parameters
+   * @param {number} [timeout=30000] - Command timeout in ms
+   * @returns {Promise<Object>} Command result
+   */
+  async function sendToSession(sessionId, method, params = {}, timeout = 30000) {
+    if (!connected) throw new Error('Not connected to CDP');
+
+    const id = ++messageId;
+    const message = JSON.stringify({ id, sessionId, method, params });
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingCommands.delete(id);
+        reject(new Error(`CDP command timeout: ${method} (session: ${sessionId})`));
+      }, timeout);
+
+      pendingCommands.set(id, { resolve, reject, timer });
+      ws.send(message);
+    });
+  }
+
+  /**
+   * Subscribe to CDP event
+   * @param {string} event - Event name
+   * @param {function} callback - Event handler
+   */
+  function on(event, callback) {
+    if (!eventListeners.has(event)) {
+      eventListeners.set(event, new Set());
+    }
+    eventListeners.get(event).add(callback);
+  }
+
+  /**
+   * Unsubscribe from CDP event
+   * @param {string} event - Event name
+   * @param {function} callback - Event handler
+   */
+  function off(event, callback) {
+    const listeners = eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(callback);
+    }
+  }
+
+  /**
+   * Wait for specific event
+   * @param {string} event - Event name
+   * @param {function} [predicate=()=>true] - Filter predicate
+   * @param {number} [timeout=30000] - Timeout in ms
+   * @returns {Promise<Object>} Event parameters
+   */
+  function waitForEvent(event, predicate = () => true, timeout = 30000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off(event, handler);
+        reject(new Error(`Timeout waiting for event: ${event}`));
+      }, timeout);
+
+      const handler = (params) => {
+        if (predicate(params)) {
+          clearTimeout(timer);
+          off(event, handler);
+          resolve(params);
+        }
+      };
+
+      on(event, handler);
+    });
+  }
+
+  /**
+   * Close the connection
+   * @returns {Promise<void>}
+   */
+  async function close() {
+    intentionalClose = true;
+    reconnecting = false;
+    if (ws) {
+      rejectPendingCommands('Connection closed');
+      ws.close();
+      ws = null;
+      connected = false;
+      eventListeners.clear();
+    }
+  }
+
+  /**
+   * Remove all event listeners
+   * @param {string} [event] - Specific event, or all if omitted
+   */
+  function removeAllListeners(event) {
+    if (event) {
+      eventListeners.delete(event);
+    } else {
+      eventListeners.clear();
+    }
+  }
+
+  /**
+   * Set close callback
+   * @param {function} callback - Callback for unexpected close
+   */
+  function onClose(callback) {
+    onCloseCallback = callback;
+  }
+
+  return {
+    connect,
+    send,
+    sendToSession,
+    on,
+    off,
+    waitForEvent,
+    close,
+    removeAllListeners,
+    onClose,
+    isConnected: () => connected,
+    getWsUrl: () => wsUrl
+  };
+}

package/src/cdp/discovery.js

@@ -0,0 +1,138 @@
+/**
+ * CDP Discovery Module
+ * HTTP-based Chrome DevTools Protocol endpoint discovery
+ *
+ * PUBLIC EXPORTS:
+ * - createDiscovery(host?, port?, timeout?) - Factory for CDP discovery
+ * - discoverChrome(host?, port?, timeout?) - Convenience function
+ *
+ * @module cdp-skill/cdp/discovery
+ */
+
+/**
+ * Discover Chrome CDP endpoints via HTTP
+ * @param {string} [host='localhost'] - Chrome debugging host
+ * @param {number} [port=9222] - Chrome debugging port
+ * @param {number} [timeout=5000] - Request timeout in ms
+ * @returns {Object} Discovery interface
+ */
+export function createDiscovery(host = 'localhost', port = 9222, timeout = 5000) {
+  const baseUrl = `http://${host}:${port}`;
+
+  function createTimeoutController() {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    return {
+      signal: controller.signal,
+      clear: () => clearTimeout(timeoutId)
+    };
+  }
+
+  /**
+   * Get Chrome version information
+   * @returns {Promise<{browser: string, protocolVersion: string, webSocketDebuggerUrl: string}>}
+   */
+  async function getVersion() {
+    const timeoutCtrl = createTimeoutController();
+    try {
+      const response = await fetch(`${baseUrl}/json/version`, { signal: timeoutCtrl.signal });
+      if (!response.ok) {
+        throw new Error(`Chrome not reachable at ${baseUrl}: ${response.status}`);
+      }
+      const data = await response.json();
+      return {
+        browser: data.Browser,
+        protocolVersion: data['Protocol-Version'],
+        webSocketDebuggerUrl: data.webSocketDebuggerUrl
+      };
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new Error(`Chrome discovery timeout at ${baseUrl}`);
+      }
+      throw err;
+    } finally {
+      timeoutCtrl.clear();
+    }
+  }
+
+  /**
+   * Get all browser targets
+   * @returns {Promise<Array>} Array of target info objects
+   */
+  async function getTargets() {
+    const timeoutCtrl = createTimeoutController();
+    try {
+      const response = await fetch(`${baseUrl}/json/list`, { signal: timeoutCtrl.signal });
+      if (!response.ok) {
+        throw new Error(`Failed to get targets: ${response.status}`);
+      }
+      return response.json();
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new Error('Chrome discovery timeout getting targets');
+      }
+      throw err;
+    } finally {
+      timeoutCtrl.clear();
+    }
+  }
+
+  /**
+   * Get page targets only
+   * @returns {Promise<Array>} Array of page target info objects
+   */
+  async function getPages() {
+    const targets = await getTargets();
+    return targets.filter(t => t.type === 'page');
+  }
+
+  /**
+   * Find a page by URL pattern
+   * @param {string|RegExp} urlPattern - URL pattern to match
+   * @returns {Promise<Object|null>} Matching target or null
+   */
+  async function findPageByUrl(urlPattern) {
+    const pages = await getPages();
+    const regex = urlPattern instanceof RegExp ? urlPattern : new RegExp(urlPattern);
+    return pages.find(p => regex.test(p.url)) || null;
+  }
+
+  /**
+   * Check if Chrome is available
+   * @returns {Promise<boolean>}
+   */
+  async function isAvailable() {
+    try {
+      await getVersion();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  return {
+    getVersion,
+    getTargets,
+    getPages,
+    findPageByUrl,
+    isAvailable
+  };
+}
+
+/**
+ * Convenience function to discover Chrome
+ * @param {string} [host='localhost'] - Chrome debugging host
+ * @param {number} [port=9222] - Chrome debugging port
+ * @param {number} [timeout=5000] - Request timeout in ms
+ * @returns {Promise<{wsUrl: string, version: Object, targets: Array}>}
+ */
+export async function discoverChrome(host = 'localhost', port = 9222, timeout = 5000) {
+  const discovery = createDiscovery(host, port, timeout);
+  const version = await discovery.getVersion();
+  const targets = await discovery.getTargets();
+  return {
+    wsUrl: version.webSocketDebuggerUrl,
+    version,
+    targets
+  };
+}

package/src/cdp/index.js

@@ -0,0 +1,29 @@
+/**
+ * CDP Protocol Module
+ * Re-exports all CDP-related functionality
+ *
+ * @module cdp-skill/cdp
+ */
+
+// Connection
+export { createConnection } from './connection.js';
+
+// Discovery
+export { createDiscovery, discoverChrome } from './discovery.js';
+
+// Target and Session Management
+export {
+  createTargetManager,
+  createSessionRegistry,
+  createPageSession
+} from './target-and-session.js';
+
+// Browser Client and Launcher
+export {
+  createBrowser,
+  findChromePath,
+  launchChrome,
+  getChromeStatus,
+  isChromeProcessRunning,
+  createNewTab
+} from './browser.js';