cdp-toolkit 1.8.0 → 1.9.0

package/dist/index.js

@@ -276,6 +276,169 @@ async function listLeases(opts = {}) {
   return out;
 }
 
+// src/origins.ts
+import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function safeId2(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function originFile(backend, targetId) {
+  return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
+}
+var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
+async function recordOrigin(backend, targetId, opts = {}) {
+  const record = {
+    backend,
+    targetId,
+    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
+    pid: process.pid,
+    createdAt: opts.now ?? Date.now()
+  };
+  const file = originFile(backend, targetId);
+  try {
+    await mkdir2(leaseDir(), { recursive: true });
+    try {
+      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    await unlink2(file).catch(() => {
+      return;
+    });
+    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+  } catch {}
+}
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
+async function listOrigins(opts = {}) {
+  let names = [];
+  try {
+    names = await readdir2(leaseDir());
+  } catch {
+    return [];
+  }
+  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
+  const out = [];
+  for (const name of names) {
+    const parts = ORIGIN_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const backend = parts[1];
+    const nameId = parts[2];
+    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
+    if (scoped && !live.has(nameId)) {
+      await unlink2(join2(leaseDir(), name)).catch(() => {
+        return;
+      });
+      continue;
+    }
+    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
+  }
+  return out;
+}
+async function originIndex(backend, liveIds) {
+  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
+  const index = new Map;
+  for (const row of rows) {
+    if (row.backend !== backend)
+      continue;
+    index.set(row.targetId, row);
+  }
+  return index;
+}
+async function newTrackedPage(driver, backend, opts = {}) {
+  const page = await driver.newPage(opts.url);
+  await recordOrigin(backend, page.id, { label: opts.label });
+  return page;
+}
+async function resolveLiveLabel(backend, label, liveIds) {
+  const live = new Set(liveIds);
+  const [origins, leases] = await Promise.all([originIndex(backend), listLeases({ liveBackend: backend })]);
+  const knownLabels = new Set;
+  const matchIds = new Set;
+  for (const rec of origins.values()) {
+    if (rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  for (const rec of leases) {
+    if (rec.backend !== backend || rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  return { matchIds: [...matchIds], knownLabels: [...knownLabels].sort() };
+}
+
+// src/workers.ts
+var WORKER_SELECTOR_PREFIX = "worker:";
+var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
+function isWorkerSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
+}
+function workerNeedle(selector) {
+  return selector.slice(WORKER_SELECTOR_PREFIX.length);
+}
+function isWorkerTargetType(type) {
+  return type !== undefined && WORKER_TARGET_TYPES.has(type);
+}
+function resolveWorkerTargets(targets, needle) {
+  const liveWorkers = targets.filter((t) => isWorkerTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveWorkers.filter((t) => t.url.includes(needle)),
+    liveWorkers
+  };
+}
+var WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js";
+var WORKER_SELECTOR_UNSUPPORTED_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " + "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " + "Use --browser chrome to evaluate in an extension's background worker.";
+var WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). evaluate_script is the one tool that " + "accepts a worker: target.";
+function urlList(workers) {
+  return workers.map((w) => w.url).join(", ");
+}
+function workerAmbiguityMessage(needle, matches) {
+  return `'worker:${needle}' matches more than one running worker: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the worker's target id directly.";
+}
+function workerMissMessage(needle, opts) {
+  const running = opts.liveWorkers?.length ? ` (running workers: ${urlList(opts.liveWorkers)})` : " (no workers are running)";
+  if (!opts.wakeAttempted) {
+    return `no running worker whose url contains '${needle}'${running}. ` + "An MV3 extension service worker is idle-evicted after seconds of inactivity and then appears in NO target " + "listing, so this is usually a sleeping worker rather than a wrong substring. You passed wake:false; " + "wake:true (the default) asks Chrome to start it first.";
+  }
+  const scopes = opts.registeredScopes?.length ? ` Registered service-worker scopes in this browser: ${opts.registeredScopes.join(", ")}.` : " No service-worker registrations were reported by this browser at all.";
+  return `no worker whose url contains '${needle}' could be reached${running}. ` + `A start was requested (wake:true) and no matching worker appeared.${scopes} ` + "If the extension is installed but its worker never starts, check the worker script for a top-level throw.";
+}
+
 // src/client.ts
 var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
 var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
@@ -431,11 +594,13 @@ async function browserWsUrl() {
 }
 async function resolveTarget(selector, opts = {}) {
   const targets = await listTargets();
-  const hit = pickTarget(targets, selector);
+  const hit = await pickTarget(targets, selector);
+  if (isWorkerTargetType(hit.type))
+    return hit;
   await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
   return hit;
 }
-function pickTarget(targets, selector) {
+async function pickTarget(targets, selector) {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length)
@@ -462,6 +627,30 @@ function pickTarget(targets, selector) {
       throw new CdpError(`no page title containing '${needle}'`);
     return hit;
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("chrome", label, pages.map((t) => t.id));
+    if (matchIds.length > 1) {
+      throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = pages.find((t) => t.id === matchIds[0]);
+      if (hit)
+        return hit;
+    }
+    throw new CdpError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+  }
+  if (isWorkerSelector(selector)) {
+    const needle = workerNeedle(selector);
+    if (needle === "")
+      throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveWorkers } = resolveWorkerTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(workerAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -651,6 +840,91 @@ async function resolveUid(conn, uid) {
   return { objectId: object.objectId };
 }
 
+// src/cdp/workers.ts
+var INVENTORY_FIRST_EVENT_MS = 1500;
+var INVENTORY_SETTLE_MS = 250;
+var WAKE_POLL_MS = 300;
+var WAKE_POLL_ATTEMPTS = 30;
+var NO_HOST_PAGE_MESSAGE = "cannot start a service worker: the ServiceWorker CDP domain is only reachable over a page session, " + "and this browser has no page target open. Open any tab (new_page) and retry — the tab does not have " + "to belong to the extension.";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function requestWorkerStart(needle) {
+  const conn = await openBrowser();
+  try {
+    const host = (await listTargets()).find((t) => t.type === "page");
+    if (!host)
+      throw new CdpError(NO_HOST_PAGE_MESSAGE);
+    const { sessionId } = await conn.send("Target.attachToTarget", {
+      targetId: host.id,
+      flatten: true
+    });
+    if (!sessionId)
+      throw new CdpError("could not attach a session to host the ServiceWorker domain");
+    const scopeById = new Map;
+    const versions = [];
+    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
+      for (const r of params.registrations ?? []) {
+        if (r.isDeleted === true)
+          continue;
+        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
+      }
+    });
+    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
+      for (const v of params.versions ?? []) {
+        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
+      }
+    });
+    await conn.send("ServiceWorker.enable", {}, { sessionId });
+    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => {
+      return;
+    });
+    await sleep(INVENTORY_SETTLE_MS);
+    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
+    const matched = new Set;
+    for (const v of versions) {
+      const scope = scopeById.get(v.registrationId);
+      if (scope === undefined)
+        continue;
+      if (v.scriptURL.includes(needle) || scope.includes(needle))
+        matched.add(scope);
+    }
+    if (matched.size === 0)
+      return { startRequested: false, scopes };
+    if (matched.size > 1) {
+      throw new CdpError(`'worker:${needle}' matches more than one registered service-worker scope: ${[...matched].sort().join(", ")}. ` + "Narrow the substring.");
+    }
+    await conn.send("ServiceWorker.startWorker", { scopeURL: [...matched][0] }, { sessionId });
+    return { startRequested: true, scopes };
+  } finally {
+    conn.close();
+  }
+}
+async function resolveWorkerSelector(selector, opts) {
+  const needle = workerNeedle(selector);
+  if (needle === "")
+    throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+  const first = resolveWorkerTargets(await listTargets(), needle);
+  if (first.matches.length > 1)
+    throw new CdpError(workerAmbiguityMessage(needle, first.matches));
+  if (first.matches.length === 1)
+    return first.matches[0];
+  if (!opts.wake) {
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers: first.liveWorkers }));
+  }
+  const { startRequested, scopes } = await requestWorkerStart(needle);
+  if (startRequested) {
+    for (let i = 0;i < WAKE_POLL_ATTEMPTS; i++) {
+      await sleep(WAKE_POLL_MS);
+      const again = resolveWorkerTargets(await listTargets(), needle);
+      if (again.matches.length > 1)
+        throw new CdpError(workerAmbiguityMessage(needle, again.matches));
+      if (again.matches.length === 1)
+        return again.matches[0];
+    }
+  }
+  const final = resolveWorkerTargets(await listTargets(), needle);
+  throw new CdpError(workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }));
+}
+
 // src/tools/network_mock.ts
 function escapeRegExpChar(ch) {
   return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
@@ -1132,7 +1406,8 @@ var CDP_CAPABILITIES = new Set([
   "input.raw",
   "input.html5Drag",
   "browser.downloads",
-  "browser.permissions"
+  "browser.permissions",
+  "worker.targets"
 ]);
 
 class CdpPageDriver {
@@ -1700,6 +1975,10 @@ class CdpBrowserDriver {
     await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
     return { id: target.id, url: target.url, title: target.title };
   }
+  async resolveWorkerTarget(selector, opts) {
+    const target = await resolveWorkerSelector(selector, opts).catch(noSuchTarget);
+    return { id: target.id, url: target.url, title: target.title, type: target.type };
+  }
   async page(selector) {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     return new CdpPageDriver(conn, target, this);
@@ -1786,111 +2065,6 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
-// src/origins.ts
-import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
-function safeId2(id) {
-  return id.replace(/[^A-Za-z0-9._-]/g, "_");
-}
-function originFile(backend, targetId) {
-  return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
-}
-var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
-async function recordOrigin(backend, targetId, opts = {}) {
-  const record = {
-    backend,
-    targetId,
-    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
-    pid: process.pid,
-    createdAt: opts.now ?? Date.now()
-  };
-  const file = originFile(backend, targetId);
-  try {
-    await mkdir2(leaseDir(), { recursive: true });
-    try {
-      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-      return;
-    } catch (err) {
-      if (err.code !== "EEXIST")
-        throw err;
-    }
-    await unlink2(file).catch(() => {
-      return;
-    });
-    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-  } catch {}
-}
-async function readOrigin(backend, targetId) {
-  let raw;
-  try {
-    raw = await readFile2(originFile(backend, targetId), "utf8");
-  } catch {
-    return;
-  }
-  try {
-    const rec = JSON.parse(raw);
-    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
-      return rec;
-  } catch {}
-  return;
-}
-async function listOrigins(opts = {}) {
-  let names = [];
-  try {
-    names = await readdir2(leaseDir());
-  } catch {
-    return [];
-  }
-  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
-  const out = [];
-  for (const name of names) {
-    const parts = ORIGIN_FILE_RE.exec(name);
-    if (!parts)
-      continue;
-    const backend = parts[1];
-    const nameId = parts[2];
-    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
-    if (scoped && !live.has(nameId)) {
-      await unlink2(join2(leaseDir(), name)).catch(() => {
-        return;
-      });
-      continue;
-    }
-    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
-    let rec;
-    try {
-      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT")
-        continue;
-      out.push({ ...fromName, unreadable: code ?? "unparseable" });
-      continue;
-    }
-    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
-      out.push({ ...fromName, unreadable: "unparseable" });
-      continue;
-    }
-    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
-  }
-  return out;
-}
-async function originIndex(backend, liveIds) {
-  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
-  const index = new Map;
-  for (const row of rows) {
-    if (row.backend !== backend)
-      continue;
-    index.set(row.targetId, row);
-  }
-  return index;
-}
-async function newTrackedPage(driver, backend, opts = {}) {
-  const page = await driver.newPage(opts.url);
-  await recordOrigin(backend, page.id, { label: opts.label });
-  return page;
-}
-
 // src/reap.ts
 function staleAgentTabs(input) {
   const live = new Set(input.livePageIds);
@@ -1991,6 +2165,11 @@ async function pickPage(driver, pages, selector) {
       throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:"))
+    return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -2000,6 +2179,18 @@ async function pickPage(driver, pages, selector) {
     return exact;
   throw new SharedToolError(`no target with id '${selector}'`);
 }
+async function pickByLabel(driver, pages, label) {
+  const { matchIds, knownLabels } = await resolveLiveLabel(backendOf(driver), label, pages.map((x) => x.id));
+  if (matchIds.length > 1) {
+    throw new SharedToolError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+  }
+  if (matchIds.length === 1) {
+    const p = pages.find((x) => x.id === matchIds[0]);
+    if (p)
+      return p;
+  }
+  throw new SharedToolError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+}
 function locatorOf(args) {
   const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== "";
   const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
@@ -2141,11 +2332,29 @@ async function writeJsonSink(savePath, value) {
 function sinkRequested(savePath) {
   return savePath !== undefined && savePath !== "";
 }
+var EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"];
+async function resolveWorkerSelectorFor(driver, selector, wake) {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
 async function evaluateScript(driver, args) {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => args[k] !== undefined);
+    if (wrongKey !== undefined) {
+      throw new SharedToolError(`evaluateScript: you passed '${wrongKey}'; the key is 'expression' — function literals go in 'expression', invoked with 'args'.`);
+    }
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage2(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  if (args.wake !== undefined && !isWorkerSelector(args.target)) {
+    throw new SharedToolError("evaluateScript: 'wake' only applies to a target of the form 'worker:<substring>'; a page target is never asleep.");
+  }
+  const target = isWorkerSelector(args.target) ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id : args.target;
+  return withPage2(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     if (!sinkRequested(args.savePath))
       return value;
@@ -2509,7 +2718,7 @@ async function claimPage(driver, args = {}) {
   const hasTarget = typeof args.target === "string" && args.target.length > 0;
   const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
   if (hasTarget && hasTargetId) {
-    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
   }
   const backend = backendOf2(driver);
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();