octocode-cli 1.3.1 → 1.5.1

package/skills/octocode-chrome-devtools/references/INTENTS_STORAGE_CONSENT.md

@@ -0,0 +1,214 @@
+# CDP Storage And Consent Intent Details
+
+## storage
+
+**Trigger phrases:** "storage", "localStorage", "sessionStorage", "IndexedDB", "cookies", "cache storage", "service worker cache", "check what's stored", "what data does this site store", "storage quota", "offline data", "browser storage"
+
+**Purpose:** Full metadata inventory of client-side storage — cookie names/flags, localStorage and sessionStorage keys/sizes, IndexedDB database names, Cache Storage caches, Service Worker registrations, and storage quota. Use for privacy audits, debugging persistence bugs, and session forensics without emitting stored secret values.
+
+**Domains:** `Network.enable`, `Runtime.enable`, `Page.enable`
+
+**Key events/methods:**
+- `Network.getAllCookies` → all cookies across all domains in the browser jar (richer than `getCookies`)
+- `Runtime.evaluate` → localStorage, sessionStorage, indexedDB.databases(), caches.keys(), navigator.serviceWorker.getRegistrations(), navigator.storage.estimate()
+- `Network.getCookies({ urls })` → scoped to a specific origin when full jar is too noisy
+
+**Script skeleton:**
+
+```js
+export async function run(cdp) {
+  await cdp.send('Network.enable', {});
+  await cdp.send('Runtime.enable', {});
+  await cdp.send('Page.enable', {});
+  cdp.on('Page.javascriptDialogOpening', () =>
+    cdp.send('Page.handleJavaScriptDialog', { accept: false }).catch(() => {}));
+
+  await cdp.send('Page.navigate', { url: 'https://TARGET_URL/' });
+  await new Promise(r => setTimeout(r, 5000)); // settle
+
+  // ── Cookies (all domains) ─────────────────────────────────────────────────
+  const { cookies } = await cdp.send('Network.getAllCookies', {});
+  console.log(`[SECURITY] Cookies total: ${cookies.length}`);
+  for (const c of cookies) {
+    const flags = [c.httpOnly ? 'httpOnly' : 'NO_httpOnly', c.secure ? 'secure' : 'NO_secure', `sameSite=${c.sameSite || 'None'}`].join(' ');
+    console.log(`[SECURITY] Cookie: ${c.name.padEnd(28)} domain=${c.domain} [${flags}]`);
+    if (!c.httpOnly) console.log(`[FINDING] COOKIE_NO_HTTPONLY: ${c.name}`);
+    if (!c.secure)   console.log(`[FINDING] COOKIE_NO_SECURE: ${c.name}`);
+  }
+
+  // ── localStorage ─────────────────────────────────────────────────────────
+  const { result: lsR } = await cdp.send('Runtime.evaluate', {
+    expression: `JSON.stringify(Object.entries(localStorage).map(([k,v])=>({k,size:new Blob([k+v]).size,sensitive:/token|auth|jwt|secret|password|credential/i.test(k)})))`,
+    returnByValue: true,
+  });
+  const ls = JSON.parse(lsR.value || '[]');
+  console.log(`[STORAGE] localStorage: ${ls.length} keys, ~${ls.reduce((s,i)=>s+i.size,0)}B`);
+  for (const { k, size, sensitive } of ls) {
+    console.log(`[STORAGE] LS[${k}] size=${size}B`);
+    if (sensitive) console.log(`[FINDING] SENSITIVE_IN_STORAGE: localStorage["${k}"]`);
+  }
+
+  // ── sessionStorage ────────────────────────────────────────────────────────
+  const { result: ssR } = await cdp.send('Runtime.evaluate', {
+    expression: `JSON.stringify(Object.entries(sessionStorage).map(([k,v])=>({k,size:new Blob([k+v]).size,sensitive:/token|auth|jwt|secret|password|credential/i.test(k)})))`,
+    returnByValue: true,
+  });
+  const ss = JSON.parse(ssR.value || '[]');
+  console.log(`[STORAGE] sessionStorage: ${ss.length} keys`);
+  for (const { k, size, sensitive } of ss) {
+    console.log(`[STORAGE] SS[${k}] size=${size}B`);
+    if (sensitive) console.log(`[FINDING] SENSITIVE_IN_STORAGE: sessionStorage["${k}"]`);
+  }
+
+  // ── IndexedDB ─────────────────────────────────────────────────────────────
+  const { result: idbR } = await cdp.send('Runtime.evaluate', {
+    expression: `indexedDB.databases().then(dbs=>JSON.stringify(dbs))`,
+    returnByValue: true, awaitPromise: true,
+  });
+  const dbs = JSON.parse(idbR.value || '[]');
+  console.log(`[STORAGE] IndexedDB: ${dbs.length} databases`);
+  for (const db of dbs) console.log(`[STORAGE] IDB: ${db.name} v${db.version}`);
+
+  // ── Service Workers ───────────────────────────────────────────────────────
+  const { result: swR } = await cdp.send('Runtime.evaluate', {
+    expression: `navigator.serviceWorker.getRegistrations().then(r=>JSON.stringify(r.map(s=>({scope:s.scope,state:s.active?.state??'none',script:s.active?.scriptURL}))))`,
+    returnByValue: true, awaitPromise: true,
+  });
+  const sws = JSON.parse(swR.value || '[]');
+  console.log(`[STORAGE] Service Workers: ${sws.length}`);
+  for (const sw of sws) console.log(`[STORAGE] SW: ${sw.scope} state=${sw.state} script=${sw.script}`);
+
+  // ── Cache Storage ─────────────────────────────────────────────────────────
+  const { result: cacheR } = await cdp.send('Runtime.evaluate', {
+    expression: `caches.keys().then(names=>Promise.all(names.map(n=>caches.open(n).then(c=>c.keys().then(k=>({name:n,count:k.length})))))).then(JSON.stringify)`,
+    returnByValue: true, awaitPromise: true,
+  });
+  const cachesData = JSON.parse(cacheR.value || '[]');
+  console.log(`[STORAGE] Cache Storage: ${cachesData.length} caches`);
+  for (const c of cachesData) console.log(`[STORAGE] Cache "${c.name}": ${c.count} entries`);
+
+  // ── Quota ─────────────────────────────────────────────────────────────────
+  const { result: quotaR } = await cdp.send('Runtime.evaluate', {
+    expression: `navigator.storage.estimate().then(e=>JSON.stringify({usedKB:Math.round(e.usage/1024),quotaMB:Math.round(e.quota/1024/1024),pct:((e.usage/e.quota)*100).toFixed(2)+'%'}))`,
+    returnByValue: true, awaitPromise: true,
+  });
+  console.log(`[STORAGE] Quota: ${quotaR.value}`);
+
+  // ── Cookie resurrection detection ─────────────────────────────────────────
+  // Checks whether tracking IDs exist in both cookies AND localStorage (persistence pattern)
+  const cookieNames = cookies.map(c => c.name);
+  for (const { k } of ls) {
+    if (cookieNames.includes(k))
+      console.log(`[FINDING] COOKIE_RESURRECTION: "${k}" duplicated in both cookies and localStorage — tracking persistence pattern`);
+  }
+}
+```
+
+**Output prefixes:** `[STORAGE]` `[SECURITY]` `[FINDING]`
+
+**Key findings to watch:**
+- `COOKIE_NO_HTTPONLY` / `COOKIE_NO_SECURE` — tracking cookies readable by JS or transmittable over HTTP
+- `SENSITIVE_IN_STORAGE` — token/auth/JWT keys in localStorage
+- `COOKIE_RESURRECTION` — IDs stored in both cookies and localStorage (e.g. cross-domain tracker IDs)
+- Large IndexedDB stores or Cache Storage entries indicate PWA / offline capability
+
+**Combine with:** `security` (CSP, headers, POST body scan), `consent` (GDPR pre-grant check), `supply-chain` (third-party domain inventory).
+
+## consent
+
+**Trigger phrases:** "GDPR", "consent", "tracking", "privacy", "CMP", "Usercentrics", "OneTrust", "Cookiebot", "cookie banner", "ad consent", "is consent required", "what is tracked", "analytics opt-out", "adStorage", "pre-granted"
+
+**Purpose:** Audit whether a Consent Management Platform (CMP) is present, whether consent is properly gated before trackers fire, and whether stored consent state matches what was granted. Works across Usercentrics, OneTrust, CookieYes, Cookiebot, TrustArc, and custom CMPs.
+
+**Domains:** `Network.enable`, `Runtime.enable`, `Page.enable`
+
+**Key signals:**
+- Analytics and ad trackers firing before consent dialog appears → violation
+- `ucData` / `_uetsid` / `_gcl_au` in localStorage with consent already granted → pre-grant
+- `window.dataLayer` populated before consent → GTM firing too early
+- `window.UC_UI` / `window.__tcfapi` / `window.Optanon` → CMP present
+- Consent string in localStorage (`ucString` = Usercentrics, `eupubconsent-v2` = IAB TCF v2)
+
+**Script skeleton:**
+
+```js
+export async function run(cdp) {
+  await cdp.send('Network.enable', {});
+  await cdp.send('Runtime.enable', {});
+  await cdp.send('Page.enable', {});
+  cdp.on('Page.javascriptDialogOpening', () =>
+    cdp.send('Page.handleJavaScriptDialog', { accept: false }).catch(() => {}));
+
+  // Track tracker requests BEFORE consent can fire
+  const trackerHits = [];
+  cdp.on('Network.requestWillBeSent', ({ request, timestamp }) => {
+    const url = request.url;
+    if (/googletagmanager|google-analytics|clarity\.ms|bat\.bing|fbq|meta\.net|doubleclick|twitter|ads-twitter/i.test(url))
+      trackerHits.push({ url: url.substring(0, 100), ts: timestamp });
+  });
+
+  await cdp.send('Page.navigate', { url: 'https://TARGET_URL/' });
+  await new Promise(r => setTimeout(r, 6000));
+
+  // ── CMP detection ─────────────────────────────────────────────────────────
+  const { result: cmpR } = await cdp.send('Runtime.evaluate', {
+    expression: `JSON.stringify({
+      usercentrics: !!window.UC_UI || !!window.usercentrics,
+      onetrust:     !!window.OneTrust || !!window.Optanon,
+      cookiebot:    !!window.CookieConsent || !!window.Cookiebot,
+      trustArc:     !!window.truste,
+      iabTCF:       typeof window.__tcfapi === 'function',
+      gtmLoaded:    Array.isArray(window.dataLayer),
+      dlEvents:     (window.dataLayer || []).length,
+    })`,
+    returnByValue: true,
+  });
+  const cmp = JSON.parse(cmpR.value || '{}');
+  console.log(`[SECURITY] CMP detected: ${JSON.stringify(cmp)}`);
+  if (!Object.values(cmp).slice(0,5).some(Boolean)) console.log('[FINDING] NO_CMP: no consent management platform detected');
+
+  // ── Consent state in storage ───────────────────────────────────────────────
+  const { result: csR } = await cdp.send('Runtime.evaluate', {
+    expression: `JSON.stringify({
+      ucGcm:       (() => { try { return JSON.parse(localStorage.getItem('ucData') || '{}').gcm || null; } catch { return null; } })(),
+      ucString:    !!localStorage.getItem('ucString'),
+      iabConsent:  !!localStorage.getItem('eupubconsent-v2'),
+      otConsent:   !!localStorage.getItem('OptanonConsent'),
+    })`,
+    returnByValue: true,
+  });
+  const cs = JSON.parse(csR.value || '{}');
+  if (cs.ucGcm) {
+    const gcm = cs.ucGcm;
+    console.log(`[SECURITY] Usercentrics GCM flags: ${JSON.stringify(gcm)}`);
+    if (gcm.adStorage === 'granted')        console.log('[FINDING] CONSENT_PRE_GRANTED: adStorage=granted without user interaction');
+    if (gcm.adPersonalization === 'granted') console.log('[FINDING] CONSENT_PRE_GRANTED: adPersonalization=granted');
+    if (gcm.analyticsStorage === 'granted') console.log('[FINDING] CONSENT_PRE_GRANTED: analyticsStorage=granted');
+  }
+  if (cs.iabConsent) console.log('[SECURITY] IAB TCF v2 string present (value redacted)');
+  if (cs.otConsent) console.log('[SECURITY] OneTrust consent string present (value redacted)');
+
+  // ── Trackers that fired before any consent interaction ─────────────────────
+  console.log(`[SECURITY] Tracker requests on cold load: ${trackerHits.length}`);
+  for (const h of trackerHits) console.log(`[SECURITY] Tracker fired: ${h.url}`);
+  if (trackerHits.length > 0) console.log(`[FINDING] TRACKERS_BEFORE_CONSENT: ${trackerHits.length} tracker requests fired before consent could be shown`);
+
+  // ── dataLayer events (GTM) ────────────────────────────────────────────────
+  const { result: dlR } = await cdp.send('Runtime.evaluate', {
+    expression: `JSON.stringify((window.dataLayer||[]).slice(0,10).map(e=>e.event||JSON.stringify(e).slice(0,60)))`,
+    returnByValue: true,
+  });
+  const dlEvents = JSON.parse(dlR.value || '[]');
+  console.log(`[SECURITY] dataLayer events: ${dlEvents.join(', ')}`);
+}
+```
+
+**Output prefixes:** `[SECURITY]` `[FINDING]`
+
+**Key findings to watch:**
+- `NO_CMP` — no consent platform detected; all tracking is ungated
+- `CONSENT_PRE_GRANTED` — adStorage/adPersonalization/analyticsStorage pre-granted (GDPR risk in EU)
+- `TRACKERS_BEFORE_CONSENT` — trackers fire on first load before banner can appear
+- Large `dataLayer` event count suggests aggressive GTM firing
+
+**Combine with:** `storage` (full cookie + localStorage inventory), `supply-chain` (enumerate all third-party domains loaded), `network` (capture timing of tracker requests relative to page load).

package/skills/octocode-chrome-devtools/references/RECOVERY.md

@@ -0,0 +1,39 @@
+# Recovery Reference
+
+
+| Situation | Fix |
+|-----------|-----|
+| `Chrome not found` | Install Chrome or check path in `open-browser.mjs` |
+| `Chrome not running on port` | Run `open-browser.mjs --headless` first |
+| Chrome already open, no CDP | Handled automatically — `open-browser.mjs` launches isolated CDP session |
+| `WebSocket unavailable` | Upgrade to Node.js 22+ (native WebSocket required, no install needed) |
+| `Script not found` | Use `$TMPDIR/cdp-<task>.mjs`, never hardcode `/tmp/` |
+| `CDP timeout for <method>` | Domain not enabled — add the required `enable` call before using it |
+| `No page targets found` | Use `--new-tab about:blank` to open a fresh tab |
+| Need to inspect an iframe or service worker | Use `--list-targets` to discover, then `--target-url <pattern>` or `--target-type service_worker` |
+| `[CDP_RETRY_NEEDED]` in output (exit 2) | Read the `[CDP_RETRY_NEEDED]` lines — fix the domain enable or method name, retry once |
+| Bot-wall detected (bot-wall / CDN challenge instead of real page) | Pass `--userAgent` explicitly with a current Chrome desktop UA string only when needed. For sites that fingerprint JS (canvas, WebGL, timing): use the `user-auth` flow — visible browser, user solves the challenge in the CDP-controlled session. |
+| `ERR_ACCESS_DENIED` in sandbox | Script tried to write outside `cdp.outputDir`, read a blocked path, or spawn a child process / Worker. Fix: all file writes via `join(cdp.outputDir, filename)`; all browser interaction via `cdp.send()`; no `child_process`, `net`, or `new Worker()`. |
+| `[AUTH_TIMEOUT]` — user-auth script timed out | User did not authenticate within `TIMEOUT_MS`. Increase the timeout, verify `POST_AUTH_PATTERN` matches the actual post-login URL fragment, or set `AUTH_COOKIE_NAME` to the exact cookie the app sets on successful login. |
+| Events not firing | Page loaded before listeners attached — attach listeners first, then call `Page.navigate` inside `run()` |
+| `--new-tab <url>` misses network/script events | Tab loads before script connects — use `--new-tab about:blank` + `Page.navigate` inside `run()` |
+| JavaScript dialog blocking all commands | Add dialog guard before navigate: `cdp.on('Page.javascriptDialogOpening', () => cdp.send('Page.handleJavaScriptDialog', { accept: true }))` — see Dialog guard in `CDP_AGENT_REFERENCE.md` section 0 |
+| URL with `?` or `&` fails in zsh | Always quote the URL: `--url "http://..."` |
+| `Runtime.evaluate` hangs after `Debugger.enable` | Add `await cdp.send('Debugger.setSkipAllPauses', { skip: true })` immediately after `Debugger.enable` |
+| `Page.navigate` times out on ALL URLs | Chrome session is stale — run `open-browser.mjs --cleanup` then relaunch with `--headless` |
+| Unsure whether cleanup will kill the tracked browser | Run `open-browser.mjs --cleanup --dry-run`; it reports whether the tracked PID matches both the CDP port and temp profile without killing anything |
+| `Security.getSecurityState` not found | Removed from current CDP — use `Security.visibleSecurityStateChanged` event instead |
+| `Storage.enable` not found (exit 2) | Not available in Chrome CDP (Chrome 120+). Remove the call — cookies, localStorage, sessionStorage, and IndexedDB are accessible without it via `Network.getAllCookies`, `Runtime.evaluate`, and `IndexedDB.*` domain calls |
+| `IndexedDB.requestDatabaseNames` not found | Use `Runtime.evaluate` with `indexedDB.databases()` instead — it is a Promise-based browser API available in Chrome 71+ |
+| `Target.createBrowserContext` not allowed | Requires browser-level WebSocket — not available in tab-level CDP connection |
+| Geolocation `getCurrentPosition` hangs | Add `Browser.grantPermissions({ permissions: ["geolocation"] })` before `Emulation.setGeolocationOverride` |
+| `CSS.enable` throws "DOM agent needs to be enabled first" | Enable `DOM` before `CSS` — order matters |
+| Coverage shows 0 functions/rules | Target page has no JS/CSS frameworks — test on a real app page, not static HTML |
+| **Consent / GDPR wall — page redirects to privacy dialog before content** | Detect: title in foreign language, request count < 20, no API calls seen. Fix: `const btn = [...document.querySelectorAll('button,a')].find(b => /accept\|agree\|לקבל/i.test(b.innerText\|b.textContent\|'')); if (btn) btn.click();` → wait 1500ms → re-navigate to original URL. Add this check after first `Page.navigate` settles. |
+| Performance metrics show DNS/TCP/TLS = 0ms and all resource durations = 0ms | You are measuring a warm/cached navigation. For cold-load metrics: call `await cdp.send('Network.clearBrowserCache', {})` and `await cdp.send('Network.clearBrowserCookies', {})` before `Page.navigate`, or use `--headless` with a fresh profile (default). |
+| FCP / First Paint is `null` after navigation | Paint entries only exist for the navigated frame. If you navigated twice (e.g. after accepting a consent wall), call `performance.getEntriesByType('paint')` immediately after the *second* navigate settles, not after waiting. **Recommended:** read `performance.getEntriesByType('paint').find(e => e.name === 'first-contentful-paint')?.startTime` — already in ms from `navigationStart`, no reference-frame conversion needed. **Alternative (CDP lifecycle):** call `Page.setLifecycleEventsEnabled({ enabled: true })` after `Page.enable`; use `'commit'` for `navStartTs` and `'firstContentfulPaint'` for FCP delta — do NOT mix with `performance.now()` (different reference frame). |
+| JS dead-code findings are all single-letter names (`c`, `i`, `Tt`, `Ut`) | Bundle is minified — function names are mangled. Filter out names with `name.length <= 2` before emitting `[FINDING] DEAD_CODE`. To get readable names you need source maps: serve the site with `//# sourceMappingURL=` intact and use `Debugger.getScriptSource` + source map parsing. |
+| Fetch mocking not intercepting | Call `Fetch.enable` with `patterns` BEFORE navigation — it must be active before requests start |
+| Screenshot is blank / all black | Page not fully loaded — add a `setTimeout` wait after navigate before calling `captureScreenshot` |
+| Heap snapshot times out | Large page — increase `--timeout` to 120000+ ms |
+| `Network.getResponseBody` returns nothing | Body was already evicted from cache — capture the `requestId` in `Network.responseReceived` immediately |

package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS.md

@@ -0,0 +1,43 @@
+# Script Pattern Router
+
+Use this file to choose the smallest pattern detail file. Do not load every code-heavy pattern by default.
+
+## Loading Rule
+
+1. Pick the pattern that matches the missing helper or script shape.
+2. Load only the listed `SCRIPT_PATTERNS_*.md` file and section.
+3. Treat code as an adaptable example, not a fixed framework.
+4. Verify current CDP params in `CDP_AGENT_REFERENCE.md`; feature-detect browser/Web APIs inside the page.
+
+## Detail Files
+
+| File | Patterns | Load when |
+|---|---|---|
+| `SCRIPT_PATTERNS_OBSERVE.md` | `Network Console (most common)`, `Performance Audit`, `Core Web Vitals (inject before navigate)`, `DOM Accessibility Audit`, `Heap Memory Audit (leak detection)`, `Security Audit` | Load for console/network capture, performance, DOM, memory, and security observation patterns. |
+| `SCRIPT_PATTERNS_BROWSER.md` | `WebSocket Surveillance`, `Search Text Across All Resources`, `File Upload`, `Save Files Screenshots PDFs and Metadata`, `Shadow DOM Querying Inside Shadow Roots`, `Source Map Resolution` | Load for WebSocket frames, page resource search, file upload, artifact saving, shadow DOM, and source-map resolution patterns. |
+| `SCRIPT_PATTERNS_ASYNC_WORKERS.md` | `waitForNetworkIdle`, `waitForSelector with Actionability`, `Service Worker Lifecycle`, `WebSocket inside Workers` | Load for wait helpers, Service Worker lifecycle tracking, and WebSocket traffic inside worker sessions. |
+| `SCRIPT_PATTERNS_SPECIAL.md` | `Storage Audit`, `Consent Audit`, `Full Audit (combine all)` | Load for storage, consent, and full-audit pointers that delegate to intent detail files. |
+
+## Pattern Index
+
+| Need | Details |
+|---|---|
+| Network Console (most common) | [SCRIPT_PATTERNS_OBSERVE.md#network-console-most-common](SCRIPT_PATTERNS_OBSERVE.md#network-console-most-common) |
+| Performance Audit | [SCRIPT_PATTERNS_OBSERVE.md#performance-audit](SCRIPT_PATTERNS_OBSERVE.md#performance-audit) |
+| Core Web Vitals (inject before navigate) | [SCRIPT_PATTERNS_OBSERVE.md#core-web-vitals-inject-before-navigate](SCRIPT_PATTERNS_OBSERVE.md#core-web-vitals-inject-before-navigate) |
+| DOM Accessibility Audit | [SCRIPT_PATTERNS_OBSERVE.md#dom-accessibility-audit](SCRIPT_PATTERNS_OBSERVE.md#dom-accessibility-audit) |
+| Heap Memory Audit (leak detection) | [SCRIPT_PATTERNS_OBSERVE.md#heap-memory-audit-leak-detection](SCRIPT_PATTERNS_OBSERVE.md#heap-memory-audit-leak-detection) |
+| Security Audit | [SCRIPT_PATTERNS_OBSERVE.md#security-audit](SCRIPT_PATTERNS_OBSERVE.md#security-audit) |
+| WebSocket Surveillance | [SCRIPT_PATTERNS_BROWSER.md#websocket-surveillance](SCRIPT_PATTERNS_BROWSER.md#websocket-surveillance) |
+| Search Text Across All Resources | [SCRIPT_PATTERNS_BROWSER.md#search-text-across-all-resources](SCRIPT_PATTERNS_BROWSER.md#search-text-across-all-resources) |
+| File Upload | [SCRIPT_PATTERNS_BROWSER.md#file-upload](SCRIPT_PATTERNS_BROWSER.md#file-upload) |
+| waitForNetworkIdle | [SCRIPT_PATTERNS_ASYNC_WORKERS.md#waitfornetworkidle](SCRIPT_PATTERNS_ASYNC_WORKERS.md#waitfornetworkidle) |
+| waitForSelector with Actionability | [SCRIPT_PATTERNS_ASYNC_WORKERS.md#waitforselector-with-actionability](SCRIPT_PATTERNS_ASYNC_WORKERS.md#waitforselector-with-actionability) |
+| Save Files Screenshots PDFs and Metadata | [SCRIPT_PATTERNS_BROWSER.md#save-files-screenshots-pdfs-and-metadata](SCRIPT_PATTERNS_BROWSER.md#save-files-screenshots-pdfs-and-metadata) |
+| Shadow DOM Querying Inside Shadow Roots | [SCRIPT_PATTERNS_BROWSER.md#shadow-dom-querying-inside-shadow-roots](SCRIPT_PATTERNS_BROWSER.md#shadow-dom-querying-inside-shadow-roots) |
+| Source Map Resolution | [SCRIPT_PATTERNS_BROWSER.md#source-map-resolution](SCRIPT_PATTERNS_BROWSER.md#source-map-resolution) |
+| Service Worker Lifecycle | [SCRIPT_PATTERNS_ASYNC_WORKERS.md#service-worker-lifecycle](SCRIPT_PATTERNS_ASYNC_WORKERS.md#service-worker-lifecycle) |
+| WebSocket inside Workers | [SCRIPT_PATTERNS_ASYNC_WORKERS.md#websocket-inside-workers](SCRIPT_PATTERNS_ASYNC_WORKERS.md#websocket-inside-workers) |
+| Storage Audit | [SCRIPT_PATTERNS_SPECIAL.md#storage-audit](SCRIPT_PATTERNS_SPECIAL.md#storage-audit) |
+| Consent Audit | [SCRIPT_PATTERNS_SPECIAL.md#consent-audit](SCRIPT_PATTERNS_SPECIAL.md#consent-audit) |
+| Full Audit (combine all) | [SCRIPT_PATTERNS_SPECIAL.md#full-audit-combine-all](SCRIPT_PATTERNS_SPECIAL.md#full-audit-combine-all) |

package/skills/octocode-chrome-devtools/references/SCRIPT_PATTERNS_ASYNC_WORKERS.md

@@ -0,0 +1,345 @@
+# CDP Async And Worker Pattern Details
+
+## waitForNetworkIdle
+
+Event-driven wait until all in-flight network requests finish. More reliable than `setTimeout` because it tracks every `requestWillBeSent` / `loadingFinished` pair, including late XHR/fetch calls fired by page JS after DOM load.
+
+```js
+// Requires: Network.enable (already active)
+// Attach listeners BEFORE navigating — events fire immediately on navigation start
+
+async function waitForNetworkIdle(cdp, { idleMs = 500, timeoutMs = 30000 } = {}) {
+  return new Promise((resolve, reject) => {
+    let pending = 0;
+    let idleTimer = null;
+
+    const deadline = setTimeout(() => {
+      clearTimeout(idleTimer);
+      reject(new Error(`waitForNetworkIdle timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const scheduleIdle = () => {
+      clearTimeout(idleTimer);
+      if (pending === 0) {
+        idleTimer = setTimeout(() => { clearTimeout(deadline); resolve(); }, idleMs);
+      }
+    };
+
+    cdp.on('Network.requestWillBeSent',    () => { pending++; clearTimeout(idleTimer); });
+    cdp.on('Network.loadingFinished',      () => { pending = Math.max(0, pending - 1); scheduleIdle(); });
+    cdp.on('Network.loadingFailed',        () => { pending = Math.max(0, pending - 1); scheduleIdle(); });
+    cdp.on('Network.requestServedFromCache', () => { pending = Math.max(0, pending - 1); scheduleIdle(); });
+
+    scheduleIdle(); // resolve immediately if nothing is already in-flight
+  });
+}
+
+export async function run(cdp) {
+  await cdp.send('Network.enable', {});
+  await cdp.send('Page.enable', {});
+
+  // Attach idle listener BEFORE navigating
+  const idlePromise = waitForNetworkIdle(cdp, { idleMs: 500, timeoutMs: 15000 });
+
+  await cdp.send('Page.navigate', { url: 'https://example.com' });
+  await idlePromise;
+
+  console.log('[METRIC] Network idle — all requests finished');
+}
+```
+
+**Alternative: `Page.lifecycleEvent` (simpler, less precise)**
+
+```js
+await cdp.send('Page.setLifecycleEventsEnabled', { enabled: true });
+await new Promise(resolve =>
+  cdp.on('Page.lifecycleEvent', ({ name }) => {
+    if (name === 'networkIdle') resolve();
+  })
+);
+```
+
+**Parameters:**
+- `idleMs` (default 500ms): quiet window — how long zero pending requests must hold before resolving
+- `timeoutMs` (default 30000ms): hard ceiling — rejects if network never goes idle
+
+**`requestServedFromCache` note:** cache hits never fire `loadingFinished`, so they must be counted as completions separately.
+
+## waitForSelector with Actionability
+
+Wait for an element to be present **and** actionable — visible, enabled, and reachable by pointer. Prevents premature clicks on elements that exist in the DOM but are animating, hidden behind overlays, or inside disabled fieldsets.
+
+```js
+// Requires: Runtime.enable, DOM.enable
+// Checks: in DOM + non-zero size + not display:none/visibility:hidden/opacity:0 + not disabled + pointer-events != none
+
+async function waitForSelector(cdp, selector, {
+  timeoutMs    = 10000,
+  checkVisible = true,  // non-zero bounding box + not hidden via CSS
+  checkEnabled = true,  // not disabled (self or ancestor)
+  checkPointer = true,  // CSS pointer-events !== 'none'
+  pollMs       = 150,
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    const { result } = await cdp.send('Runtime.evaluate', {
+      expression: `(function() {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return null;
+        const s   = window.getComputedStyle(el);
+        const r   = el.getBoundingClientRect();
+        return {
+          visible: r.width > 0 && r.height > 0
+                   && s.display     !== 'none'
+                   && s.visibility  !== 'hidden'
+                   && s.opacity     !== '0',
+          enabled: !el.disabled && !el.closest('[disabled]'),
+          pointer: s.pointerEvents !== 'none',
+        };
+      })()`,
+      returnByValue: true,
+    });
+
+    const state = result.value;
+    if (!state) { await new Promise(r => setTimeout(r, pollMs)); continue; }
+
+    const ready = (!checkVisible || state.visible)
+               && (!checkEnabled || state.enabled)
+               && (!checkPointer || state.pointer);
+
+    if (ready) {
+      const { root }   = await cdp.send('DOM.getDocument', { depth: 0 });
+      const { nodeId } = await cdp.send('DOM.querySelector', { nodeId: root.nodeId, selector });
+      console.log(`[AUTOMATE] "${selector}" ready — visible:${state.visible} enabled:${state.enabled} pointer:${state.pointer}`);
+      return nodeId; // use with DOM.getBoxModel + Input.dispatchMouseEvent to click
+    }
+
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+
+  throw new Error(`waitForSelector("${selector}") timed out after ${timeoutMs}ms`);
+}
+
+// Usage: click a button only once it is visible and enabled
+export async function run(cdp) {
+  await cdp.send('DOM.enable', {});
+  await cdp.send('Runtime.enable', {});
+  await cdp.send('Page.enable', {});
+  await cdp.send('Page.navigate', { url: 'https://example.com' });
+
+  const nodeId = await waitForSelector(cdp, '#submit-btn');
+
+  // Real mouse click via CDP Input (required for some frameworks)
+  await cdp.send('DOM.scrollIntoViewIfNeeded', { nodeId });
+  const { model } = await cdp.send('DOM.getBoxModel', { nodeId });
+  const [x1,,x3,,,,,y1,,,,y3] = model.content; // 8-point polygon
+  const cx = (x1 + x3) / 2, cy = (y1 + y3) / 2;
+  await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: cx, y: cy, button: 'left', clickCount: 1 });
+  await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: cx, y: cy, button: 'left', clickCount: 1 });
+  console.log('[AUTOMATE] clicked #submit-btn');
+}
+```
+
+**Actionability checks explained:**
+- **visible**: `getBoundingClientRect().width/height > 0` AND not `display:none` / `visibility:hidden` / `opacity:0`
+- **enabled**: `!el.disabled` AND not inside a `[disabled]` fieldset/ancestor
+- **pointer**: `pointer-events !== 'none'` — catches elements blocked by CSS overlays
+
+**Skip flags:**
+- `checkVisible: false` — for off-screen or hidden inputs you set by value, not click
+- `checkEnabled: false` — for read-only fields
+- `checkPointer: false` — for elements that use JS click handlers bypassing CSS pointer-events
+
+## Service Worker Lifecycle
+
+Tracks every Service Worker state transition via the `ServiceWorker` CDP domain. Captures registration, full lifecycle (new → installing → installed → activating → activated → redundant), and the navigator API snapshot.
+
+```js
+export async function run(cdp) {
+  await cdp.send('Network.enable', {});
+  await cdp.send('Page.enable', {});
+  await cdp.send('Page.setLifecycleEventsEnabled', { enabled: true });
+  await cdp.send('ServiceWorker.enable', {}); // must be before navigation
+
+  const swVersions = new Map(); // scriptURL → latest status/runningStatus key
+  const swRegistrations = new Set(); // scopeURLs seen
+
+  cdp.on('ServiceWorker.workerRegistrationUpdated', ({ registrations }) => {
+    for (const r of registrations) {
+      if (r.scopeURL.startsWith('chrome-extension:')) continue;
+      const label = r.isDeleted ? 'DELETED' : 'REGISTERED';
+      console.log(`[SW] ${label}: scope=${r.scopeURL} id=${r.registrationId}`);
+      if (!r.isDeleted) {
+        swRegistrations.add(r.scopeURL);
+        console.log(`[FINDING] SW_REGISTERED: ${r.scopeURL}`);
+      } else {
+        console.log(`[FINDING] SW_REMOVED: ${r.scopeURL}`);
+      }
+    }
+  });
+
+  cdp.on('ServiceWorker.workerVersionUpdated', ({ versions }) => {
+    for (const v of versions) {
+      if (!v.scriptURL || v.scriptURL.startsWith('chrome-extension:')) continue;
+      const key = `${v.status}/${v.runningStatus}`;
+      const prev = swVersions.get(v.scriptURL);
+      if (prev === key) continue; // deduplicate repeated events
+      swVersions.set(v.scriptURL, key);
+      const fn = v.scriptURL.split('/').slice(-1)[0].split('?')[0];
+      console.log(`[SW] VERSION: ${fn} → ${v.status}/${v.runningStatus} (script=${v.scriptURL})`);
+      if (v.status === 'activated') console.log(`[FINDING] SW_ACTIVATED: ${v.scriptURL}`);
+      if (v.status === 'redundant')  console.log(`[FINDING] SW_REDUNDANT: ${v.scriptURL}`);
+      const swHost = (() => { try { return new URL(v.scriptURL).hostname; } catch { return ''; } })();
+      const pageHost = (() => { try { return new URL(TARGET_URL).hostname; } catch { return ''; } })();
+      if (swHost && pageHost && swHost !== pageHost) console.log(`[FINDING] SW_THIRD_PARTY_SCRIPT: ${v.scriptURL}`);
+    }
+  });
+
+  await cdp.send('Page.navigate', { url: TARGET_URL });
+  await new Promise(r => setTimeout(r, 15000)); // allow SW to install + activate
+
+  // Point-in-time snapshot via navigator API
+  const { result } = await cdp.send('Runtime.evaluate', {
+    expression: `(async () => {
+      if (!navigator.serviceWorker) return '[]';
+      const regs = await navigator.serviceWorker.getRegistrations();
+      return JSON.stringify(regs.map(r => ({
+        scope: r.scope,
+        updateViaCache: r.updateViaCache,
+        state: (r.active || r.installing || r.waiting)?.state ?? 'unknown',
+        scriptURL: (r.active || r.installing || r.waiting)?.scriptURL ?? null,
+      })));
+    })()`,
+    awaitPromise: true, returnByValue: false,
+  });
+  const sws = JSON.parse(result.value ?? '[]');
+
+  console.log(`[METRIC] SW registrations (live CDP): ${swRegistrations.size}`);
+  console.log(`[METRIC] SW registrations (navigator API): ${sws.length}`);
+  for (const s of sws) {
+    console.log(`[SW] SNAPSHOT: scope=${s.scope} state=${s.state} script=${s.scriptURL}`);
+  }
+
+  await cdp.send('ServiceWorker.disable', {});
+}
+```
+
+**Key facts:**
+- `ServiceWorker.enable` must be called before navigation — events are not replayed retroactively
+- `workerVersionUpdated` fires repeatedly for the same version as state advances — deduplicate on `scriptURL + status/runningStatus`
+- `workerRegistrationUpdated` fires for ALL known registrations (including from prior sessions, extensions) on enable — filter `chrome-extension:` scopes
+- `status` lifecycle order: `new` → `installing` → `installed` → `activating` → `activated` → `redundant`
+- `runningStatus` lifecycle: `stopped` → `starting` → `running` → `stopping`
+- Use `ServiceWorker.skipWaiting({scopeURL})` to force a waiting SW to activate immediately (useful in tests)
+
+## WebSocket inside Workers
+
+Web Workers and Shared Workers can open their own WebSocket connections. These do **not** emit `Network.webSocketCreated` on the main session — you must attach to each worker via `Target.setAutoAttach` and enable `Network` on its session.
+
+```js
+export async function run(cdp) {
+  await cdp.send('Network.enable', {});
+  await cdp.send('Page.enable', {});
+  await cdp.send('Page.setLifecycleEventsEnabled', { enabled: true });
+  await cdp.send('ServiceWorker.enable', {});
+  // flatten:true = worker sessions share the same CDP WebSocket; sessionId routes commands
+  await cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+  await cdp.send('Target.setDiscoverTargets', { discover: true });
+
+  const wsMap = new Map(); // `${sessionLabel}::${requestId}` → { url, frames }
+
+  // Helper: attach Network WS listeners to any session (main page OR worker)
+  function listenWS(session, label) {
+    function on(event, handler) {
+      cdp.on(event, (params, meta) => {
+        // main page: no meta.sessionId; worker: meta.sessionId matches
+        const isTarget = label === 'MAIN'
+          ? !meta?.sessionId
+          : meta?.sessionId === session.sessionId;
+        if (isTarget) handler(params);
+      });
+    }
+
+    on('Network.webSocketCreated', ({ requestId, url }) => {
+      wsMap.set(`${label}::${requestId}`, { url, sent: [], recv: [] });
+      console.log(`[WORKER] WS OPENED [${label}]: ${url}`);
+      const wsHost = (() => { try { return new URL(url).hostname; } catch { return '?'; } })();
+      console.log(`[FINDING] WS_IN_WORKER: type=${label} host=${wsHost} url=${url}`);
+    });
+
+    on('Network.webSocketFrameSent', ({ requestId, response }) => {
+      const ws = wsMap.get(`${label}::${requestId}`);
+      if (!ws) return;
+      const p = response?.payloadData ?? '';
+      ws.sent.push({ bytes: p.length, opcode: response?.opcode });
+      console.log(`[WORKER] WS SENT [${label}] ${p.length}B op=${response?.opcode}`);
+      if (/token|password|secret|key|auth|jwt/i.test(p))
+        console.log(`[FINDING] SENSITIVE_IN_WS_SENT [${label}]: value redacted`);
+    });
+
+    on('Network.webSocketFrameReceived', ({ requestId, response }) => {
+      const ws = wsMap.get(`${label}::${requestId}`);
+      if (!ws) return;
+      const p = response?.payloadData ?? '';
+      ws.recv.push({ bytes: p.length, opcode: response?.opcode });
+      console.log(`[WORKER] WS RECV [${label}] ${p.length}B op=${response?.opcode}`);
+    });
+
+    on('Network.webSocketClosed', ({ requestId }) => {
+      const ws = wsMap.get(`${label}::${requestId}`);
+      if (!ws) return;
+      console.log(`[WORKER] WS CLOSED [${label}]: ${ws.url} S:${ws.sent.length} R:${ws.recv.length}`);
+    });
+  }
+
+  // Listen on the main page session
+  listenWS({ sessionId: null }, 'MAIN');
+
+  // When a worker attaches, enable Network on it and listen there too
+  let workerCount = 0;
+  cdp.on('Target.attachedToTarget', async ({ targetInfo, sessionId }) => {
+    const t = targetInfo.type;
+    if (!['worker', 'shared_worker', 'service_worker'].includes(t)) return;
+    workerCount++;
+    const label = `${t.toUpperCase()}(${workerCount})`;
+    console.log(`[WORKER] Attached: type=${t} label=${label} url=${targetInfo.url || '(blob)'}`);
+    console.log(`[FINDING] WORKER_${t.toUpperCase()}: ${targetInfo.url || '(blob)'}`);
+    try {
+      await cdp.send('Network.enable', {}, sessionId); // route to worker session
+      listenWS({ sessionId }, label);
+    } catch (e) {
+      console.log(`[WORKER] Network.enable failed for ${label}: ${e.message}`);
+    }
+  });
+
+  cdp.on('Page.javascriptDialogOpening', () => cdp.send('Page.handleJavaScriptDialog', { accept: true }));
+
+  await cdp.send('Page.navigate', { url: TARGET_URL });
+  await new Promise(r => setTimeout(r, 20000));
+
+  // Summary
+  const allWS = [...wsMap.values()];
+  console.log(`[METRIC] Total WS connections (main + workers): ${allWS.length}`);
+  for (const ws of allWS) {
+    console.log(`[METRIC]  WS: ${ws.url} sent:${ws.sent.length} recv:${ws.recv.length}`);
+  }
+  const { targetInfos } = await cdp.send('Target.getTargets', {});
+  const wTargets = targetInfos.filter(t => ['worker','shared_worker','service_worker'].includes(t.type));
+  console.log(`[METRIC] Worker targets: ${wTargets.length}`);
+  for (const t of wTargets) console.log(`[METRIC]  type=${t.type} url=${t.url || '(blob)'}`);
+
+  // Cleanup
+  await cdp.send('ServiceWorker.disable', {});
+  await cdp.send('Target.setAutoAttach', { autoAttach: false, waitForDebuggerOnStart: false, flatten: true });
+  await cdp.send('Target.setDiscoverTargets', { discover: false });
+}
+```
+
+**Key facts:**
+- `flatten: true` on `setAutoAttach` is required — it makes all sessions share one WS connection and routes via `sessionId`
+- Pass `sessionId` as the **third argument** to `cdp.send(method, params, sessionId)` to send commands to a worker session
+- Worker `Network.*` events arrive on the main `cdp.on()` listener but carry a `meta.sessionId` in the second argument — check it to route correctly
+- Workers spawned as `blob:` URLs cannot be read by source, but their network traffic (HTTP + WS) is fully capturable
+- `Target.setAutoAttach` with `waitForDebuggerOnStart: false` lets workers run normally — set to `true` only if you need to pause a worker at startup for debugging
+- `shared_worker` type means a single worker shared across tabs — it persists even after the page navigates