cdp-skill 1.0.2 → 1.0.4

package/src/dom/wait-executor.js

@@ -0,0 +1,423 @@
+/**
+ * Wait Executor
+ * Wait operations for selectors, text, visibility, and timing
+ *
+ * EXPORTS:
+ * - createWaitExecutor(session, elementLocator) → WaitExecutor
+ *   Methods: execute, waitForSelector, waitForHidden, waitForCount,
+ *            waitForText, waitForTextRegex, waitForUrlContains, waitForTime
+ *
+ * DEPENDENCIES:
+ * - ../constants.js: TIMEOUTS, POLL_INTERVALS
+ * - ../utils.js: sleep, timeoutError
+ */
+
+import { TIMEOUTS, POLL_INTERVALS } from '../constants.js';
+import { sleep, timeoutError } from '../utils.js';
+
+const DEFAULT_TIMEOUT = TIMEOUTS.DEFAULT;
+const MAX_TIMEOUT = TIMEOUTS.MAX;
+const POLL_INTERVAL = POLL_INTERVALS.DEFAULT;
+
+/**
+ * Create a wait executor for handling wait operations
+ * @param {Object} session - CDP session
+ * @param {Object} elementLocator - Element locator instance
+ * @returns {Object} Wait executor interface
+ */
+export function createWaitExecutor(session, elementLocator) {
+  if (!session) throw new Error('CDP session is required');
+  if (!elementLocator) throw new Error('Element locator is required');
+
+  function validateTimeout(timeout) {
+    if (typeof timeout !== 'number' || !Number.isFinite(timeout)) {
+      return DEFAULT_TIMEOUT;
+    }
+    if (timeout < 0) return 0;
+    if (timeout > MAX_TIMEOUT) return MAX_TIMEOUT;
+    return timeout;
+  }
+
+  /**
+   * Wait for selector using browser-side MutationObserver
+   * Much faster than Node.js polling as it avoids network round-trips
+   */
+  async function waitForSelector(selector, timeout = DEFAULT_TIMEOUT) {
+    const validatedTimeout = validateTimeout(timeout);
+
+    try {
+      // Use browser-side polling with MutationObserver for better performance
+      const result = await session.send('Runtime.evaluate', {
+        expression: `
+          new Promise((resolve, reject) => {
+            const selector = ${JSON.stringify(selector)};
+            const timeout = ${validatedTimeout};
+
+            // Check if element already exists
+            const existing = document.querySelector(selector);
+            if (existing) {
+              resolve({ found: true, immediate: true });
+              return;
+            }
+
+            let resolved = false;
+            const timeoutId = setTimeout(() => {
+              if (!resolved) {
+                resolved = true;
+                observer.disconnect();
+                reject(new Error('Timeout waiting for selector: ' + selector));
+              }
+            }, timeout);
+
+            const observer = new MutationObserver((mutations, obs) => {
+              const el = document.querySelector(selector);
+              if (el && !resolved) {
+                resolved = true;
+                obs.disconnect();
+                clearTimeout(timeoutId);
+                resolve({ found: true, mutations: mutations.length });
+              }
+            });
+
+            observer.observe(document.documentElement || document.body, {
+              childList: true,
+              subtree: true,
+              attributes: true,
+              attributeFilter: ['class', 'id', 'style', 'hidden']
+            });
+
+            // Also check with RAF as a fallback
+            const checkWithRAF = () => {
+              if (resolved) return;
+              const el = document.querySelector(selector);
+              if (el) {
+                resolved = true;
+                observer.disconnect();
+                clearTimeout(timeoutId);
+                resolve({ found: true, raf: true });
+                return;
+              }
+              requestAnimationFrame(checkWithRAF);
+            };
+            requestAnimationFrame(checkWithRAF);
+          })
+        `,
+        awaitPromise: true,
+        returnByValue: true
+      });
+
+      if (result.exceptionDetails) {
+        throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text);
+      }
+
+      return result.result.value;
+    } catch (error) {
+      // Fall back to original Node.js polling if browser-side fails
+      const element = await elementLocator.waitForSelector(selector, {
+        timeout: validatedTimeout
+      });
+      if (element) await element.dispose();
+    }
+  }
+
+  async function checkElementHidden(selector) {
+    try {
+      const result = await session.send('Runtime.evaluate', {
+        expression: `
+          (function() {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) return true;
+            const style = window.getComputedStyle(el);
+            if (style.display === 'none') return true;
+            if (style.visibility === 'hidden') return true;
+            if (style.opacity === '0') return true;
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 && rect.height === 0) return true;
+            return false;
+          })()
+        `,
+        returnByValue: true
+      });
+      return result.result.value === true;
+    } catch {
+      return true;
+    }
+  }
+
+  async function waitForHidden(selector, timeout = DEFAULT_TIMEOUT) {
+    const validatedTimeout = validateTimeout(timeout);
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < validatedTimeout) {
+      const isHidden = await checkElementHidden(selector);
+      if (isHidden) return;
+      await sleep(POLL_INTERVAL);
+    }
+
+    throw timeoutError(
+      `Timeout (${validatedTimeout}ms) waiting for element to disappear: "${selector}"`
+    );
+  }
+
+  async function getElementCount(selector) {
+    try {
+      const result = await session.send('Runtime.evaluate', {
+        expression: `document.querySelectorAll(${JSON.stringify(selector)}).length`,
+        returnByValue: true
+      });
+      return result.result.value || 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  async function waitForCount(selector, minCount, timeout = DEFAULT_TIMEOUT) {
+    if (typeof minCount !== 'number' || minCount < 0) {
+      throw new Error('minCount must be a non-negative number');
+    }
+
+    const validatedTimeout = validateTimeout(timeout);
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < validatedTimeout) {
+      const count = await getElementCount(selector);
+      if (count >= minCount) return;
+      await sleep(POLL_INTERVAL);
+    }
+
+    const finalCount = await getElementCount(selector);
+    throw timeoutError(
+      `Timeout (${validatedTimeout}ms) waiting for ${minCount} elements matching "${selector}" (found ${finalCount})`
+    );
+  }
+
+  /**
+   * Wait for text using browser-side MutationObserver
+   */
+  async function waitForText(text, opts = {}) {
+    const { timeout = DEFAULT_TIMEOUT, caseSensitive = false } = opts;
+    const validatedTimeout = validateTimeout(timeout);
+
+    try {
+      // Use browser-side polling with MutationObserver
+      const result = await session.send('Runtime.evaluate', {
+        expression: `
+          new Promise((resolve, reject) => {
+            const searchText = ${JSON.stringify(text)};
+            const caseSensitive = ${caseSensitive};
+            const timeout = ${validatedTimeout};
+
+            const checkText = () => {
+              const bodyText = document.body ? document.body.innerText : '';
+              if (caseSensitive) {
+                return bodyText.includes(searchText);
+              }
+              return bodyText.toLowerCase().includes(searchText.toLowerCase());
+            };
+
+            // Check if text already exists
+            if (checkText()) {
+              resolve({ found: true, immediate: true });
+              return;
+            }
+
+            let resolved = false;
+            const timeoutId = setTimeout(() => {
+              if (!resolved) {
+                resolved = true;
+                observer.disconnect();
+                reject(new Error('Timeout waiting for text: ' + searchText));
+              }
+            }, timeout);
+
+            const observer = new MutationObserver((mutations, obs) => {
+              if (!resolved && checkText()) {
+                resolved = true;
+                obs.disconnect();
+                clearTimeout(timeoutId);
+                resolve({ found: true, mutations: mutations.length });
+              }
+            });
+
+            observer.observe(document.documentElement || document.body, {
+              childList: true,
+              subtree: true,
+              characterData: true
+            });
+
+            // Also check with RAF as a fallback
+            const checkWithRAF = () => {
+              if (resolved) return;
+              if (checkText()) {
+                resolved = true;
+                observer.disconnect();
+                clearTimeout(timeoutId);
+                resolve({ found: true, raf: true });
+                return;
+              }
+              requestAnimationFrame(checkWithRAF);
+            };
+            requestAnimationFrame(checkWithRAF);
+          })
+        `,
+        awaitPromise: true,
+        returnByValue: true
+      });
+
+      if (result.exceptionDetails) {
+        throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text);
+      }
+
+      return result.result.value;
+    } catch (error) {
+      // Fall back to original Node.js polling
+      const startTime = Date.now();
+      const checkExpr = caseSensitive
+        ? `document.body.innerText.includes(${JSON.stringify(text)})`
+        : `document.body.innerText.toLowerCase().includes(${JSON.stringify(text.toLowerCase())})`;
+
+      while (Date.now() - startTime < validatedTimeout) {
+        try {
+          const result = await session.send('Runtime.evaluate', {
+            expression: checkExpr,
+            returnByValue: true
+          });
+          if (result.result.value === true) return;
+        } catch {
+          // Continue polling
+        }
+        await sleep(POLL_INTERVAL);
+      }
+
+      throw timeoutError(
+        `Timeout (${validatedTimeout}ms) waiting for text: "${text}"${caseSensitive ? ' (case-sensitive)' : ''}`
+      );
+    }
+  }
+
+  async function waitForTextRegex(pattern, timeout = DEFAULT_TIMEOUT) {
+    const validatedTimeout = validateTimeout(timeout);
+    const startTime = Date.now();
+
+    try {
+      new RegExp(pattern);
+    } catch (e) {
+      throw new Error(`Invalid regex pattern: ${pattern} - ${e.message}`);
+    }
+
+    while (Date.now() - startTime < validatedTimeout) {
+      try {
+        const result = await session.send('Runtime.evaluate', {
+          expression: `
+            (function() {
+              try {
+                const regex = new RegExp(${JSON.stringify(pattern)});
+                return regex.test(document.body.innerText);
+              } catch {
+                return false;
+              }
+            })()
+          `,
+          returnByValue: true
+        });
+        if (result.result.value === true) return;
+      } catch {
+        // Continue polling
+      }
+      await sleep(POLL_INTERVAL);
+    }
+
+    throw timeoutError(
+      `Timeout (${validatedTimeout}ms) waiting for text matching pattern: /${pattern}/`
+    );
+  }
+
+  async function waitForUrlContains(substring, timeout = DEFAULT_TIMEOUT) {
+    const validatedTimeout = validateTimeout(timeout);
+    const startTime = Date.now();
+
+    while (Date.now() - startTime < validatedTimeout) {
+      try {
+        const result = await session.send('Runtime.evaluate', {
+          expression: 'window.location.href',
+          returnByValue: true
+        });
+        const currentUrl = result.result.value;
+        if (currentUrl && currentUrl.includes(substring)) return;
+      } catch {
+        // Continue polling
+      }
+      await sleep(POLL_INTERVAL);
+    }
+
+    let finalUrl = 'unknown';
+    try {
+      const result = await session.send('Runtime.evaluate', {
+        expression: 'window.location.href',
+        returnByValue: true
+      });
+      finalUrl = result.result.value || 'unknown';
+    } catch {
+      // Ignore
+    }
+
+    throw timeoutError(
+      `Timeout (${validatedTimeout}ms) waiting for URL to contain "${substring}" (current: ${finalUrl})`
+    );
+  }
+
+  async function waitForTime(ms) {
+    if (typeof ms !== 'number' || ms < 0) {
+      throw new Error('wait time must be a non-negative number');
+    }
+    await sleep(ms);
+  }
+
+  async function execute(params) {
+    if (typeof params === 'string') {
+      return waitForSelector(params);
+    }
+
+    if (params.time !== undefined) {
+      return waitForTime(params.time);
+    }
+
+    if (params.selector !== undefined) {
+      if (params.hidden === true) {
+        return waitForHidden(params.selector, params.timeout);
+      }
+      if (params.minCount !== undefined) {
+        return waitForCount(params.selector, params.minCount, params.timeout);
+      }
+      return waitForSelector(params.selector, params.timeout);
+    }
+
+    if (params.text !== undefined) {
+      return waitForText(params.text, {
+        timeout: params.timeout,
+        caseSensitive: params.caseSensitive
+      });
+    }
+
+    if (params.textRegex !== undefined) {
+      return waitForTextRegex(params.textRegex, params.timeout);
+    }
+
+    if (params.urlContains !== undefined) {
+      return waitForUrlContains(params.urlContains, params.timeout);
+    }
+
+    throw new Error(`Invalid wait params: ${JSON.stringify(params)}`);
+  }
+
+  return {
+    execute,
+    waitForSelector,
+    waitForHidden,
+    waitForCount,
+    waitForText,
+    waitForTextRegex,
+    waitForUrlContains,
+    waitForTime
+  };
+}

package/src/index.js

@@ -21,7 +21,7 @@ export {
   getChromeStatus,
   isChromeProcessRunning,
   createNewTab
-} from './cdp.js';
+} from './cdp/index.js';
 
 // ============================================================================
 // Page Operations and Waiting
@@ -42,7 +42,7 @@ export {
   lcsSimilarity,
   getDOMSignature,
   waitForDOMStability
-} from './page.js';
+} from './page/index.js';
 
 // ============================================================================
 // DOM Operations and Input
@@ -70,7 +70,7 @@ export {
   createActionabilityChecker,
   createElementValidator,
   createReactInputFiller
-} from './dom.js';
+} from './dom/index.js';
 
 // ============================================================================
 // ARIA and Role-based Queries
@@ -97,7 +97,7 @@ export {
   createPdfCapture,
   createDebugCapture,
   createEvalSerializer
-} from './capture.js';
+} from './capture/index.js';
 
 // ============================================================================
 // Test Execution
@@ -107,7 +107,7 @@ export {
   executeStep,
   runSteps,
   createTestRunner
-} from './runner.js';
+} from './runner/index.js';
 
 // ============================================================================
 // Utilities and Errors
@@ -156,5 +156,5 @@ export {
 // ============================================================================
 // Default Export - High-level browser factory
 // ============================================================================
-import { createBrowser } from './cdp.js';
+import { createBrowser } from './cdp/index.js';
 export default createBrowser;

package/src/page/cookie-manager.js

@@ -0,0 +1,202 @@
+/**
+ * Cookie Manager Module
+ * CDP-based cookie management for getting, setting, and clearing cookies
+ *
+ * PUBLIC EXPORTS:
+ * - createCookieManager(session) - Factory for cookie manager
+ *
+ * @module cdp-skill/page/cookie-manager
+ */
+
+/**
+ * Creates a cookie manager for getting, setting, and clearing cookies
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @returns {Object} Cookie manager interface
+ */
+export function createCookieManager(session) {
+  /**
+   * Get all cookies, optionally filtered by URLs
+   * @param {string[]} [urls=[]] - Optional URLs to filter cookies
+   * @returns {Promise<import('../types.js').CookieObject[]>} Array of cookie objects
+   */
+  async function getCookies(urls = []) {
+    const result = await session.send('Storage.getCookies', {});
+    let cookies = result.cookies || [];
+
+    // Filter by URLs if provided
+    if (urls.length > 0) {
+      cookies = cookies.filter(cookie => {
+        return urls.some(url => {
+          try {
+            const parsed = new URL(url);
+            // Domain matching
+            const domainMatch = cookie.domain.startsWith('.')
+              ? parsed.hostname.endsWith(cookie.domain.slice(1))
+              : parsed.hostname === cookie.domain;
+            // Path matching
+            const pathMatch = parsed.pathname.startsWith(cookie.path);
+            // Secure matching
+            const secureMatch = !cookie.secure || parsed.protocol === 'https:';
+            return domainMatch && pathMatch && secureMatch;
+          } catch {
+            return false;
+          }
+        });
+      });
+    }
+
+    return cookies.map(cookie => ({
+      name: cookie.name,
+      value: cookie.value,
+      domain: cookie.domain,
+      path: cookie.path,
+      expires: cookie.expires,
+      httpOnly: cookie.httpOnly,
+      secure: cookie.secure,
+      sameSite: cookie.sameSite || 'Lax'
+    }));
+  }
+
+  /**
+   * Set one or more cookies
+   * @param {import('../types.js').CookieObject[]} cookies - Array of cookie objects to set
+   * @returns {Promise<void>}
+   */
+  async function setCookies(cookies) {
+    const processedCookies = cookies.map(cookie => {
+      const processed = {
+        name: cookie.name,
+        value: cookie.value
+      };
+
+      // If URL provided, derive domain/path/secure from it
+      if (cookie.url) {
+        try {
+          const parsed = new URL(cookie.url);
+          processed.domain = cookie.domain || parsed.hostname;
+          processed.path = cookie.path || '/';
+          processed.secure = cookie.secure !== undefined ? cookie.secure : parsed.protocol === 'https:';
+        } catch {
+          throw new Error(`Invalid cookie URL: ${cookie.url}`);
+        }
+      } else {
+        // Require domain and path if no URL
+        if (!cookie.domain) {
+          throw new Error('Cookie requires either url or domain');
+        }
+        processed.domain = cookie.domain;
+        processed.path = cookie.path || '/';
+        processed.secure = cookie.secure || false;
+      }
+
+      // Optional properties
+      if (cookie.expires !== undefined) {
+        processed.expires = cookie.expires;
+      }
+      if (cookie.httpOnly !== undefined) {
+        processed.httpOnly = cookie.httpOnly;
+      }
+      if (cookie.sameSite) {
+        processed.sameSite = cookie.sameSite;
+      }
+
+      return processed;
+    });
+
+    await session.send('Storage.setCookies', { cookies: processedCookies });
+  }
+
+  /**
+   * Clear all cookies or cookies matching specific domains
+   * @param {string[]} [urls=[]] - Optional URLs to filter cookies by domain
+   * @param {Object} [options] - Optional filters
+   * @param {string} [options.domain] - Clear cookies for specific domain
+   * @returns {Promise<{count: number}>} Number of cookies deleted
+   */
+  async function clearCookies(urls = [], options = {}) {
+    const { domain } = options;
+
+    if (urls.length === 0 && !domain) {
+      // Clear all cookies
+      const allCookies = await getCookies();
+      const count = allCookies.length;
+      await session.send('Storage.clearCookies', {});
+      return { count };
+    }
+
+    // Get cookies to filter
+    let cookiesToDelete;
+    if (domain) {
+      // Filter by domain - get all cookies and match domain
+      const allCookies = await getCookies();
+      cookiesToDelete = allCookies.filter(cookie =>
+        cookie.domain === domain ||
+        cookie.domain === `.${domain}` ||
+        cookie.domain.endsWith(`.${domain}`)
+      );
+    } else {
+      // Filter by URLs (original behavior)
+      cookiesToDelete = await getCookies(urls);
+    }
+
+    let deletedCount = 0;
+
+    for (const cookie of cookiesToDelete) {
+      try {
+        await session.send('Network.deleteCookies', {
+          name: cookie.name,
+          domain: cookie.domain,
+          path: cookie.path
+        });
+        deletedCount++;
+      } catch {
+        // Ignore individual deletion failures
+      }
+    }
+
+    return { count: deletedCount };
+  }
+
+  /**
+   * Delete specific cookies by name
+   * @param {string|string[]} names - Cookie name(s) to delete
+   * @param {Object} [options] - Optional filters
+   * @param {string} [options.domain] - Limit deletion to specific domain
+   * @param {string} [options.path] - Limit deletion to specific path
+   * @returns {Promise<{count: number}>} Number of cookies deleted
+   */
+  async function deleteCookies(names, options = {}) {
+    const nameList = Array.isArray(names) ? names : [names];
+    const { domain, path } = options;
+    let deletedCount = 0;
+
+    // Get all cookies to find matching ones
+    const allCookies = await getCookies();
+
+    for (const cookie of allCookies) {
+      if (!nameList.includes(cookie.name)) continue;
+      if (domain && cookie.domain !== domain && !cookie.domain.endsWith(`.${domain}`)) continue;
+      if (path && cookie.path !== path) continue;
+
+      try {
+        await session.send('Network.deleteCookies', {
+          name: cookie.name,
+          domain: cookie.domain,
+          path: cookie.path
+        });
+        deletedCount++;
+      } catch {
+        // Ignore individual deletion failures
+      }
+    }
+
+    return { count: deletedCount };
+  }
+
+  return {
+    getCookies,
+    setCookies,
+    clearCookies,
+    deleteCookies
+  };
+}