cdp-skill 1.0.7 → 1.0.14

package/src/cdp-skill.js

@@ -60,9 +60,9 @@ function generateDebugFilename(steps, status, tabId) {
   const actions = steps.slice(0, 3).map(step => {
     // Find the action key in the step
     const actionKeys = ['goto', 'click', 'fill', 'type', 'press', 'scroll', 'snapshot',
-      'query', 'hover', 'wait', 'eval', 'openTab', 'closeTab', 'chromeStatus',
+      'query', 'hover', 'wait', 'sleep', 'pageFunction', 'newTab', 'closeTab',
       'selectOption', 'select', 'viewport', 'cookies', 'back', 'forward', 'drag',
-      'fillForm', 'extract', 'formState', 'assert', 'validate', 'submit'];
+      'frame', 'elementsAt', 'extract', 'formState', 'assert', 'validate', 'submit'];
     for (const key of actionKeys) {
       if (step[key] !== undefined) return key;
     }
@@ -95,7 +95,7 @@ function writeDebugLog(request, response) {
   const status = response.status || 'unknown';
 
   // Extract tab ID from request or response
-  const tabId = request.tab || request.config?.tab || response.tab || response.closed || null;
+  const tabId = request.tab || response.tab || response.closed || null;
 
   const filename = generateDebugFilename(steps, status, tabId);
   const filepath = path.join(debugLogDir, filename);
@@ -114,9 +114,56 @@ function writeDebugLog(request, response) {
   }
 }
 
-// Tab registry - maps short aliases (t1, t2, ...) to targetIds
+// Tab registry - maps short aliases (t1, t2, ...) to {targetId, host, port} entries
 const TAB_REGISTRY_PATH = path.join(os.tmpdir(), 'cdp-skill-tabs.json');
 
+// Frame state registry - persists frame context across CLI invocations, keyed by targetId
+const FRAME_STATE_PATH = path.join(os.tmpdir(), 'cdp-skill-frames.json');
+
+function loadFrameStates() {
+  try {
+    if (fs.existsSync(FRAME_STATE_PATH)) {
+      return JSON.parse(fs.readFileSync(FRAME_STATE_PATH, 'utf8'));
+    }
+  } catch (e) {
+    // Ignore errors, start fresh
+  }
+  return {};
+}
+
+function saveFrameStates(states) {
+  try {
+    fs.writeFileSync(FRAME_STATE_PATH, JSON.stringify(states));
+  } catch (e) {
+    // Ignore errors
+  }
+}
+
+function saveFrameState(targetId, frameState) {
+  const states = loadFrameStates();
+  states[targetId] = { ...frameState, timestamp: Date.now() };
+  saveFrameStates(states);
+}
+
+function loadFrameState(targetId) {
+  const states = loadFrameStates();
+  const state = states[targetId];
+  if (!state) return null;
+  // Expire after 1 hour (frames may have reloaded)
+  if (Date.now() - state.timestamp > 3600000) {
+    delete states[targetId];
+    saveFrameStates(states);
+    return null;
+  }
+  return state;
+}
+
+function clearFrameState(targetId) {
+  const states = loadFrameStates();
+  delete states[targetId];
+  saveFrameStates(states);
+}
+
 function loadTabRegistry() {
   try {
     if (fs.existsSync(TAB_REGISTRY_PATH)) {
@@ -136,22 +183,43 @@ function saveTabRegistry(registry) {
   }
 }
 
-function registerTab(targetId) {
+function registerTab(targetId, host = 'localhost', port = 9222) {
   const registry = loadTabRegistry();
 
   // Check if already registered
-  for (const [alias, tid] of Object.entries(registry.tabs)) {
-    if (tid === targetId) return alias;
+  for (const [alias, entry] of Object.entries(registry.tabs)) {
+    const existingTargetId = typeof entry === 'string' ? entry : entry.targetId;
+    if (existingTargetId === targetId) return alias;
   }
 
   // Assign new alias
   const alias = `t${registry.nextId}`;
-  registry.tabs[alias] = targetId;
+  registry.tabs[alias] = { targetId, host, port };
   registry.nextId++;
   saveTabRegistry(registry);
   return alias;
 }
 
+function resolveTabEntry(aliasOrTargetId) {
+  if (!aliasOrTargetId) return null;
+
+  // If it looks like a full targetId (32 hex chars), return with defaults
+  if (/^[A-F0-9]{32}$/i.test(aliasOrTargetId)) {
+    return { targetId: aliasOrTargetId, host: 'localhost', port: 9222 };
+  }
+
+  const registry = loadTabRegistry();
+  const entry = registry.tabs[aliasOrTargetId];
+  if (!entry) return null;
+
+  // Defensive: handle stale registry files with string entries
+  if (typeof entry === 'string') {
+    return { targetId: entry, host: 'localhost', port: 9222 };
+  }
+
+  return { targetId: entry.targetId, host: entry.host || 'localhost', port: entry.port || 9222 };
+}
+
 function resolveTabAlias(aliasOrTargetId) {
   if (!aliasOrTargetId) return null;
 
@@ -162,15 +230,21 @@ function resolveTabAlias(aliasOrTargetId) {
 
   // Try to resolve alias
   const registry = loadTabRegistry();
-  return registry.tabs[aliasOrTargetId] || aliasOrTargetId;
+  const entry = registry.tabs[aliasOrTargetId];
+  if (!entry) return aliasOrTargetId;
+
+  // Defensive: handle stale registry files with string entries
+  return typeof entry === 'string' ? entry : entry.targetId;
 }
 
 function unregisterTab(targetId) {
   const registry = loadTabRegistry();
-  for (const [alias, tid] of Object.entries(registry.tabs)) {
-    if (tid === targetId) {
+  for (const [alias, entry] of Object.entries(registry.tabs)) {
+    const existingTargetId = typeof entry === 'string' ? entry : entry.targetId;
+    if (existingTargetId === targetId) {
       delete registry.tabs[alias];
       saveTabRegistry(registry);
+      clearFrameState(targetId);
       return alias;
     }
   }
@@ -179,8 +253,9 @@ function unregisterTab(targetId) {
 
 function getTabAlias(targetId) {
   const registry = loadTabRegistry();
-  for (const [alias, tid] of Object.entries(registry.tabs)) {
-    if (tid === targetId) return alias;
+  for (const [alias, entry] of Object.entries(registry.tabs)) {
+    const existingTargetId = typeof entry === 'string' ? entry : entry.targetId;
+    if (existingTargetId === targetId) return alias;
   }
   return null;
 }
@@ -283,6 +358,13 @@ function parseInput(input) {
     throw { type: ErrorType.VALIDATION, message: 'Input must be a JSON object' };
   }
 
+  if (json.config) {
+    throw {
+      type: ErrorType.VALIDATION,
+      message: '"config" is no longer supported. Use top-level "tab"/"timeout". Connection params go in newTab: {"steps":[{"newTab":{"url":"...","port":9333}}]}'
+    };
+  }
+
   if (!json.steps) {
     throw { type: ErrorType.VALIDATION, message: 'Missing required "steps" array' };
   }
@@ -325,11 +407,12 @@ function isCloseTabOnly(steps) {
 /**
  * Handle chromeStatus step - lightweight, no session needed
  */
-async function handleChromeStatus(config, step) {
-  const host = config.host || 'localhost';
-  const port = config.port || 9222;
-  const autoLaunch = step.chromeStatus === true || step.chromeStatus?.autoLaunch !== false;
-  const headless = step.chromeStatus?.headless || false;
+async function handleChromeStatus(step) {
+  const params = typeof step.chromeStatus === 'object' ? step.chromeStatus : {};
+  const host = params.host || 'localhost';
+  const port = params.port || 9222;
+  const autoLaunch = step.chromeStatus === true || params.autoLaunch !== false;
+  const headless = params.headless || false;
 
   const status = await getChromeStatus({ host, port, autoLaunch, headless });
 
@@ -351,9 +434,7 @@ async function handleChromeStatus(config, step) {
 /**
  * Handle closeTab step - no session needed, just close the target via CDP
  */
-async function handleCloseTab(config, step) {
-  const host = config.host || 'localhost';
-  const port = config.port || 9222;
+async function handleCloseTab(step) {
   const tabRef = step.closeTab;
 
   if (!tabRef || typeof tabRef !== 'string') {
@@ -363,8 +444,11 @@ async function handleCloseTab(config, step) {
     };
   }
 
-  // Resolve alias to targetId
-  const targetId = resolveTabAlias(tabRef);
+  // Resolve alias to full entry (targetId + host + port)
+  const entry = resolveTabEntry(tabRef);
+  const targetId = entry ? entry.targetId : tabRef;
+  const host = entry ? entry.host : 'localhost';
+  const port = entry ? entry.port : 9222;
   const alias = getTabAlias(targetId);
 
   try {
@@ -374,6 +458,7 @@ async function handleCloseTab(config, step) {
 
     await new Promise((resolve, reject) => {
       const req = http.get(closeUrl, (res) => {
+        res.resume(); // Drain response body to prevent memory leak
         if (res.statusCode === 200) {
           resolve();
         } else {
@@ -409,6 +494,7 @@ async function handleCloseTab(config, step) {
  * Main CLI execution
  */
 async function main() {
+  const startTime = Date.now();
   let browser = null;
   let pageController = null;
   let parsedRequest = null;  // Track for debug logging in error handler
@@ -419,17 +505,16 @@ async function main() {
     const json = parseInput(input);
     parsedRequest = json;  // Store for error handler
 
-    // Extract config with defaults - tab can be at top level or in config
-    const config = json.config || {};
-    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
+    // Extract top-level fields
+    const tab = json.tab || null;
+    const timeout = json.timeout || 30000;
+    let host = 'localhost';
+    let port = 9222;
+    let headless = false;
 
     // Handle chromeStatus specially - no session needed
     if (isChromeStatusOnly(json.steps)) {
-      const result = await handleChromeStatus(config, json.steps[0]);
+      const result = await handleChromeStatus(json.steps[0]);
       writeDebugLog(json, result);
       console.log(JSON.stringify(result));
       process.exit(result.status === 'ok' ? 0 : 1);
@@ -437,12 +522,55 @@ async function main() {
 
     // Handle closeTab specially - no session needed, just close the target
     if (isCloseTabOnly(json.steps)) {
-      const result = await handleCloseTab(config, json.steps[0]);
+      const result = await handleCloseTab(json.steps[0]);
       writeDebugLog(json, result);
       console.log(JSON.stringify(result));
       process.exit(result.status === 'ok' ? 0 : 1);
     }
 
+    // Check if first step is newTab or switchTab
+    const firstStep = json.steps[0];
+    const hasNewTab = firstStep && firstStep.newTab !== undefined;
+    const hasSwitchTab = firstStep && firstStep.switchTab !== undefined;
+
+    // Extract URL and options from newTab if provided
+    let newTabUrl = null;
+    let newTabTimeout = null;
+    if (hasNewTab) {
+      const newTabParam = firstStep.newTab;
+      if (typeof newTabParam === 'string') {
+        newTabUrl = newTabParam;
+      } else if (typeof newTabParam === 'object' && newTabParam !== null) {
+        newTabUrl = newTabParam.url || null;
+        newTabTimeout = newTabParam.timeout || null;
+        // Extract connection overrides from newTab object form
+        if (newTabParam.host) host = newTabParam.host;
+        if (newTabParam.port) port = newTabParam.port;
+        if (newTabParam.headless) headless = newTabParam.headless;
+      }
+    }
+
+    // Extract connection overrides from switchTab object form
+    if (hasSwitchTab) {
+      const switchParam = firstStep.switchTab;
+      if (typeof switchParam === 'object' && switchParam !== null) {
+        if (switchParam.host) host = switchParam.host;
+        if (switchParam.port) port = switchParam.port;
+      }
+    }
+
+    // If tab specified, resolve host/port from registry
+    if (tab) {
+      const tabEntry = resolveTabEntry(tab);
+      if (tabEntry) {
+        host = tabEntry.host;
+        port = tabEntry.port;
+      }
+    }
+
+    // Resolve tab alias to targetId
+    const resolvedTargetId = tab ? resolveTabAlias(tab) : null;
+
     // Connect to browser, auto-launch if needed
     browser = createBrowser({ host, port, connectTimeout: timeout });
 
@@ -468,27 +596,9 @@ async function main() {
       }
     }
 
-    // Get page session - requires explicit targetId or openTab step
+    // Get page session - requires explicit targetId or newTab step
     let session;
 
-    // Check if first step is openTab
-    const firstStep = json.steps[0];
-    const hasOpenTab = firstStep && firstStep.openTab !== undefined;
-
-    // Extract URL from openTab if provided
-    let openTabUrl = null;
-    if (hasOpenTab) {
-      const openTabParam = firstStep.openTab;
-      if (typeof openTabParam === 'string') {
-        openTabUrl = openTabParam;
-      } else if (typeof openTabParam === 'object' && openTabParam !== null && openTabParam.url) {
-        openTabUrl = openTabParam.url;
-      }
-    }
-
-    // Resolve tab alias to targetId
-    const resolvedTargetId = tab ? resolveTabAlias(tab) : null;
-
     if (resolvedTargetId) {
       try {
         session = await browser.attachToPage(resolvedTargetId);
@@ -498,16 +608,56 @@ async function main() {
           message: `Could not attach to tab ${tab}${tab !== resolvedTargetId ? ` (${resolvedTargetId})` : ''}: ${err.message}`
         };
       }
-    } else if (hasOpenTab) {
-      // Create new tab via openTab step
+    } else if (hasSwitchTab) {
+      // Connect to an existing tab by alias, targetId, or URL regex
       try {
-        session = await browser.newPage();
+        const switchParam = firstStep.switchTab;
+        let switchTargetId = null;
+
+        if (typeof switchParam === 'string') {
+          // Try alias first, then targetId
+          switchTargetId = resolveTabAlias(switchParam);
+        } else if (switchParam && typeof switchParam === 'object') {
+          if (switchParam.targetId) {
+            switchTargetId = switchParam.targetId;
+          } else if (switchParam.url) {
+            // Find tab by URL regex
+            const pages = await browser.getPages();
+            const urlRegex = new RegExp(switchParam.url);
+            const match = pages.find(p => urlRegex.test(p.url));
+            if (!match) {
+              throw new Error(`No tab matches URL pattern: ${switchParam.url}`);
+            }
+            switchTargetId = match.targetId;
+          }
+        }
+
+        if (!switchTargetId) {
+          throw new Error('Could not resolve switchTab target');
+        }
+
+        session = await browser.attachToPage(switchTargetId);
+        const tabAlias = getTabAlias(switchTargetId) || registerTab(switchTargetId, host, port);
+        json.steps[0]._switchTabHandled = true;
+        json.steps[0]._switchTabAlias = tabAlias;
+      } catch (err) {
+        throw {
+          type: ErrorType.CONNECTION,
+          message: `switchTab failed: ${err.message}`
+        };
+      }
+    } else if (hasNewTab) {
+      // Create new tab via newTab step
+      try {
+        // Create blank tab - URL navigation happens in step executor
+        session = await browser.newPage('about:blank');
         // Register the new tab and get its alias
-        const tabAlias = registerTab(session.targetId);
-        // Mark openTab as handled and store URL/alias if provided
-        json.steps[0]._openTabHandled = true;
-        json.steps[0]._openTabUrl = openTabUrl;
-        json.steps[0]._openTabAlias = tabAlias;
+        const tabAlias = registerTab(session.targetId, host, port);
+        // Mark newTab as handled and store URL/alias/timeout if provided
+        json.steps[0]._newTabHandled = true;
+        json.steps[0]._newTabUrl = newTabUrl;
+        json.steps[0]._newTabTimeout = newTabTimeout;
+        json.steps[0]._newTabAlias = tabAlias;
       } catch (err) {
         if (err.message.includes('no browser is open')) {
           throw {
@@ -521,23 +671,28 @@ async function main() {
         };
       }
     } else {
-      // No targetId and no openTab step - fail with helpful message
+      // No targetId and no newTab/switchTab step - fail with helpful message
       throw {
         type: ErrorType.VALIDATION,
         message: `No tab specified. Either:\n` +
-          `  1. Use {"steps":[{"openTab":"url"},...]} to create a new tab\n` +
-          `  2. Pass tab id: {"tab":"t1", "steps":[...]}`
+          `  1. Use {"steps":[{"newTab":"url"},...]} to create a new tab\n` +
+          `  2. Use {"steps":[{"switchTab":"t1"},...]} to connect to an existing tab\n` +
+          `  3. Pass tab id: {"tab":"t1", "steps":[...]}`
       };
     }
 
     // Create dependencies
-    pageController = createPageController(session);
-    const elementLocator = createElementLocator(session);
+    pageController = createPageController(session, {
+      onFrameChanged: (frameState) => saveFrameState(session.targetId, frameState),
+      getSavedFrameState: () => loadFrameState(session.targetId)
+    });
+    const frameContextProvider = () => pageController.getFrameContext();
+    const elementLocator = createElementLocator(session, { getFrameContext: frameContextProvider });
     const inputEmulator = createInputEmulator(session);
     const screenshotCapture = createScreenshotCapture(session);
     const consoleCapture = createConsoleCapture(session);
     const pdfCapture = createPdfCapture(session);
-    const ariaSnapshot = createAriaSnapshot(session);
+    const ariaSnapshot = createAriaSnapshot(session, { getFrameContext: frameContextProvider });
     const cookieManager = createCookieManager(session);
 
     // Initialize page controller (enables required CDP domains)
@@ -558,11 +713,12 @@ async function main() {
       consoleCapture,
       pdfCapture,
       ariaSnapshot,
-      cookieManager
+      cookieManager,
+      registerNewTab: (targetId) => registerTab(targetId, host, port)
     };
 
     // Run steps (pass tab alias for auto-screenshots)
-    const tabAlias = getTabAlias(session.targetId) || registerTab(session.targetId);
+    const tabAlias = getTabAlias(session.targetId) || registerTab(session.targetId, host, port);
     const result = await runSteps(deps, json.steps, {
       stopOnError: true,
       stepTimeout: timeout,
@@ -586,10 +742,32 @@ async function main() {
       screenshotPath = null;
     }
 
+    // Bubble up site profile info from goto/newTab steps to top level
+    let siteProfile = undefined;
+    let actionRequired = undefined;
+    for (const step of result.steps) {
+      if (step.siteProfile) {
+        siteProfile = step.siteProfile;
+        delete step.siteProfile;
+      } else if (step.profileAvailable === false) {
+        actionRequired = {
+          action: 'createSiteProfile',
+          domain: step.profileDomain,
+          message: `STOP: No site profile for "${step.profileDomain}". You MUST create one before doing anything else. Run these steps now: (1) snapshot — see page structure, (2) pageFunction — detect framework/routing, (3) writeSiteProfile — save what you learned. Then continue your task. Skipping this causes unreliable automation.`
+        };
+        delete step.profileAvailable;
+        delete step.profileDomain;
+        delete step.hint;
+      }
+    }
+
     // Build streamlined output
     const output = {
       status: result.status,
-      tab: getTabAlias(session.targetId) || registerTab(session.targetId),
+      tab: getTabAlias(session.targetId) || registerTab(session.targetId, host, port),
+      // Site profile — prominent, right after status/tab
+      siteProfile,
+      actionRequired,
       // Command-level auto-snapshot results
       navigated: result.navigated,
       fullSnapshot: result.fullSnapshot,
@@ -606,6 +784,8 @@ async function main() {
     };
 
     // Remove null/undefined fields for compactness
+    if (!output.siteProfile) delete output.siteProfile;
+    if (!output.actionRequired) delete output.actionRequired;
     if (output.navigated === undefined) delete output.navigated;
     if (!output.fullSnapshot) delete output.fullSnapshot;
     if (!output.context) delete output.context;
@@ -631,6 +811,26 @@ async function main() {
     // Debug logging
     writeDebugLog(json, finalOutput);
 
+    // Write metrics if CDP_METRICS_FILE is set
+    const metricsFile = process.env.CDP_METRICS_FILE;
+    if (metricsFile) {
+      const inputBytes = Buffer.byteLength(input, 'utf8');
+      const outputJson = JSON.stringify(finalOutput);
+      const outputBytes = Buffer.byteLength(outputJson, 'utf8');
+      const metricsLine = JSON.stringify({
+        ts: new Date().toISOString(),
+        input_bytes: inputBytes,
+        output_bytes: outputBytes,
+        steps: json.steps.length,
+        time_ms: Date.now() - startTime
+      }) + '\n';
+      try {
+        const metricsDir = path.dirname(metricsFile);
+        if (!fs.existsSync(metricsDir)) fs.mkdirSync(metricsDir, { recursive: true });
+        fs.appendFileSync(metricsFile, metricsLine);
+      } catch (e) { /* metrics write failure is non-fatal */ }
+    }
+
     // Output result
     console.log(JSON.stringify(finalOutput));