cdp-toolkit 1.0.0 → 1.2.0

package/src/shared-tools.ts

@@ -0,0 +1,466 @@
+/**
+ * ONE implementation per tool, built only on the browser-neutral Driver contract in driver.ts
+ * (ADR-001), used by BOTH Chrome (via cdp/driver.ts's createCdpDriver()) and Firefox (via
+ * bidi/driver.ts's createFirefoxDriver()). This file replaces the split that used to exist
+ * between src/tools/*.ts (raw CDP, Chrome only) and src/neutral.ts (Driver-based, Firefox only)
+ * for the 20 tools below.
+ *
+ * THE HARD REQUIREMENT this file exists to satisfy: Chrome's return shape, timing, and quirks
+ * stay byte-identical to what src/tools/*.ts produced before this migration: that already
+ * shipped to npm. Where the clean Driver abstraction and that requirement conflicted, the
+ * requirement won; every such place is called out in a comment at the call site. The most
+ * significant ones:
+ *   - take_snapshot's uid is rendered as a bare digit for the "cdp" scheme (matching the legacy
+ *     backendDOMNodeId-as-uid contract) rather than the driver's own tagged "cdp:N" form, and its
+ *     extras (checked/expanded/disabled/url/focused) keep the legacy per-key quoting AND the
+ *     "expanded" quirk (included even when literally "false") rather than a clean uniform rule.
+ *   - navigate_page's field names (frameId, not contextId) and waitedFor vocabulary (load /
+ *     domcontentloaded / frameStoppedLoading / navigate-only) are the legacy CDP tool's, not the
+ *     Driver's own (committed / timeout).
+ *   - Every nested `target` object in a result is the legacy 3-field {id,url,title}: PageInfo's
+ *     additive `type` field is deliberately dropped there (list_pages is the one place `type` is
+ *     part of the contract).
+ *
+ * NOT here: list_console_messages / get_console_message / list_network_requests /
+ * get_network_request / mock_request / list_mocks / clear_mocks. Chrome's versions of those 7
+ * tools are built on src/tools/recorder.ts, a disk-persisted, cross-process capture keyed by
+ * target id (rec-<targetId>.jsonl) with a materially richer shape (ConsoleEntry/NetworkRequest
+ * correlation, per-rule hit counts, dedup-by-pattern+method). Firefox's existing implementation
+ * (now in src/bidi-tools.ts) is a same-process, in-memory event buffer with a different shape.
+ * Unifying them safely would mean either dropping Chrome's cross-process persistence (a real
+ * behavior change to something that ships today) or teaching Firefox to write the same JSONL
+ * format (new feature work, not a safety-preserving migration). Per the explicit instruction that
+ * behavior outranks the abstraction, these 7 stay two implementations; see the migration report.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type {
+  BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+} from "./driver.ts";
+import type { TargetSelector } from "./types.ts";
+import { assertLeaseOk, claimLease, leaseTtlMs, releaseLeaseFor, type LeaseBackend, type LeaseToken } from "./leases.ts";
+
+const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+const STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
+
+class SharedToolError extends Error {}
+
+/** Trim a PageInfo down to the legacy 3-field {id,url,title} target shape used everywhere except list_pages. */
+function target3(p: PageInfo): { id: string; url: string; title: string } {
+  return { id: p.id, url: p.url, title: p.title };
+}
+
+/** Same discriminator leases-tools.ts uses: the driver's own uid scheme tag
+ *  ("cdp" for Chrome, "bidi" for Firefox). */
+function backendOf(driver: BrowserDriver): LeaseBackend {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+
+/* -------------------------------- page acquisition -------------------------------- */
+
+/** Acquire, run, always release: the Driver counterpart of client.ts's withPage. */
+async function withPage<T>(driver: BrowserDriver, target: TargetSelector | undefined, fn: (page: PageDriver) => Promise<T>): Promise<T> {
+  const page = await driver.page(target);
+  try {
+    return await fn(page);
+  } finally {
+    await page.release();
+  }
+}
+
+async function resolvePage(driver: BrowserDriver, selector?: TargetSelector): Promise<PageInfo> {
+  const pages = await driver.listPages();
+  const hit = await pickPage(driver, pages, selector);
+  // THE third choke point. close_page and select_page resolve here and nowhere
+  // else, so the lease check has to be here too, not only in resolveTarget /
+  // resolveContext. Closing someone else's leased tab is the worst version of
+  // the collision this feature exists to stop.
+  //
+  // Deliberately NOT passing liveIds, matching resolveTarget and resolveContext.
+  // For every branch but one it would be inert (hit is an element of `pages`),
+  // and for the bare-id branch it would be actively wrong: that branch can
+  // return a non-page target off the `all:true` listing, whose id is absent
+  // from `pages`, so passing pages' ids would report a perfectly healthy lease
+  // as target-gone and wave the caller straight through it.
+  await assertLeaseOk(backendOf(driver), hit.id, { url: hit.url, title: hit.title });
+  return hit;
+}
+
+/**
+ * Same TargetSelector grammar as client.ts's resolveTarget. Matches its one asymmetry exactly:
+ * every branch resolves against page-type targets only EXCEPT a bare-id lookup, which (like
+ * legacy resolveTarget's `targets.find`) searches the FULL unfiltered listing, so passing an
+ * exact non-page targetId (a worker, an iframe) still resolves.
+ */
+async function pickPage(driver: BrowserDriver, pages: PageInfo[], selector?: TargetSelector): Promise<PageInfo> {
+  if (selector === undefined || selector === "active") {
+    if (!pages.length) throw new SharedToolError("no page targets open");
+    return pages[0]!;
+  }
+  if (selector.startsWith("index:")) {
+    const p = pages[Number(selector.slice(6))];
+    if (!p) throw new SharedToolError(`no page target at index ${selector.slice(6)} (have ${pages.length})`);
+    return p;
+  }
+  if (selector.startsWith("url:")) {
+    const needle = selector.slice(4);
+    const p = pages.find((x) => x.url.includes(needle));
+    if (!p) throw new SharedToolError(`no page url containing '${needle}'`);
+    return p;
+  }
+  if (selector.startsWith("title:")) {
+    const needle = selector.slice(6);
+    const p = pages.find((x) => x.title.includes(needle));
+    if (!p) throw new SharedToolError(`no page title containing '${needle}'`);
+    return p;
+  }
+  const exactPage = pages.find((x) => x.id === selector);
+  if (exactPage) return exactPage;
+  const all = await driver.listPages({ all: true });
+  const exact = all.find((x) => x.id === selector);
+  if (exact) return exact;
+  throw new SharedToolError(`no target with id '${selector}'`);
+}
+
+/* -------------------------------- element locators -------------------------------- */
+
+function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator {
+  const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== ("" as unknown);
+  const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
+  if (hasUid === hasSelector) throw new SharedToolError("provide exactly one of { uid } or { selector }");
+  return hasUid ? { uid: args.uid as DriverUid } : { css: args.selector as string };
+}
+
+/* -------------------------------- pages (4) -------------------------------- */
+
+export async function listPages(driver: BrowserDriver, args: { all?: boolean } = {}): Promise<{ pages: PageInfo[]; count: number }> {
+  const pages = await driver.listPages({ all: args.all });
+  return { pages, count: pages.length };
+}
+
+export async function newPage(
+  driver: BrowserDriver,
+  args: { url?: string; claim?: boolean; label?: string; ttlMs?: number } = {},
+): Promise<{ targetId: string; url: string; lease?: LeaseToken; label?: string; expiresAt?: number }> {
+  const p = await driver.newPage(args.url);
+  if (args.claim !== true) return { targetId: p.id, url: p.url };
+  // Atomic in the sense that matters: the tab is claimed before this call
+  // returns, so no other agent can see it unclaimed and take it first.
+  const { record, token } = await claimLease(backendOf(driver), p.id, {
+    label: typeof args.label === "string" && args.label.length ? args.label : `pid-${process.pid}`,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+  });
+  return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
+}
+
+export async function closePage(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector },
+): Promise<{ closed: string; success: boolean; leaseReleased?: boolean }> {
+  if (args.target === undefined || args.target === "") throw new SharedToolError("close_page requires an explicit target; refusing to guess which page to close");
+  const p = await resolvePage(driver, args.target);
+  const res = await driver.closePage(p.id);
+  // A failed close (target refused to close, or was already gone) must leave
+  // the lease intact: the caller still owns a tab that never actually closed,
+  // and releasing it here would let another agent claim a tab this one still
+  // thinks it holds.
+  if (!res.success) return { closed: p.id, success: false, leaseReleased: false };
+  // Closing a leased tab must not leave its lease file behind waiting on the
+  // TTL. resolvePage above already refused this call unless the caller holds
+  // the lease, so no token is needed here.
+  const released = await releaseLeaseFor(backendOf(driver), p.id);
+  return { closed: p.id, success: true, ...(released.released ? { leaseReleased: true } : {}) };
+}
+
+async function writeSelectedFile(id: string): Promise<void> {
+  await mkdir(STATE_DIR, { recursive: true });
+  await writeFile(join(STATE_DIR, "selected"), id, "utf8");
+}
+
+export async function selectPage(driver: BrowserDriver, args: { target?: TargetSelector }): Promise<{ selected: string }> {
+  if (args.target === undefined || args.target === "") throw new SharedToolError("select_page requires an explicit target");
+  const p = await resolvePage(driver, args.target);
+  const activated = await driver.activatePage(p.id);
+  await writeSelectedFile(activated.id);
+  return { selected: activated.id };
+}
+
+/* ------------------------------ navigation (2) ------------------------------ */
+
+/** Legacy tools/navigation.ts vocabulary, not the Driver's own (see file header). */
+function toLegacyWaitedFor(w: NavigateResult["waitedFor"]): "load" | "domcontentloaded" | "frameStoppedLoading" | "navigate-only" {
+  if (w === "committed") return "frameStoppedLoading";
+  if (w === "timeout") return "navigate-only";
+  return w;
+}
+
+export interface LegacyNavigateResult {
+  url: string;
+  frameId: string;
+  reloaded?: boolean;
+  waitedFor: "load" | "domcontentloaded" | "frameStoppedLoading" | "navigate-only";
+}
+
+export async function navigatePage(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; url?: string; reload?: boolean; ignoreCache?: boolean; waitUntil?: "load" | "domcontentloaded"; timeoutMs?: number },
+): Promise<LegacyNavigateResult> {
+  const reload = args.reload === true;
+  if (!reload && (!args.url || typeof args.url !== "string")) {
+    throw new SharedToolError("navigate_page: 'url' is required (or pass reload:true to reload the current page)");
+  }
+  return withPage(driver, args.target, async (page) => {
+    const r = await page.navigate(args);
+    return {
+      url: r.url,
+      frameId: r.contextId,
+      ...(r.reloaded ? { reloaded: r.reloaded } : {}),
+      waitedFor: toLegacyWaitedFor(r.waitedFor),
+    };
+  });
+}
+
+export async function waitForText(driver: BrowserDriver, args: { target?: TargetSelector; text: string; timeoutMs?: number; pollMs?: number }): Promise<{ found: true; waitedMs: number }> {
+  if (typeof args.text !== "string" || args.text.length === 0) throw new SharedToolError("wait_for: 'text' is required");
+  return withPage(driver, args.target, async (page) => {
+    const r = await page.waitForText(args.text, args.timeoutMs ?? 15_000, args.pollMs ?? 250);
+    return { found: true, waitedMs: r.elapsedMs };
+  });
+}
+/** Contract-mandated alias, matching tools/navigation.ts's exported `waitFor`. */
+export const waitFor = waitForText;
+
+/* ------------------------------- evaluate (1) ------------------------------- */
+
+export async function evaluateScript(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[] },
+): Promise<unknown> {
+  if (typeof args.expression !== "string" || args.expression.length === 0) {
+    throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
+  }
+  return withPage(driver, args.target, (page) => page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true }));
+}
+
+/* -------------------------------- snapshot (1) -------------------------------- */
+
+/**
+ * Legacy-faithful render, keyed by field name (see the file header's uid/extras note). The
+ * "cdp" scheme strips its "cdp:" tag to reproduce the historical bare-backendDOMNodeId uid;
+ * every other scheme keeps its tag (a tool must never guess at a foreign driver's uid grammar,
+ * per driver.ts's THE UID CODEC block: this is a display choice made by the tool that already
+ * knows its own driver's scheme, not a parse of a uid it didn't mint).
+ */
+const BARE_TOKEN_EXTRAS = new Set(["disabled", "focused"]);
+const UNQUOTED_EXTRAS = new Set(["checked", "expanded", "url"]);
+
+function renderSnapshotLine(n: SnapshotNode, scheme: string): string {
+  const indent = "  ".repeat(n.depth);
+  const uidText = scheme === "cdp" && n.uid.startsWith("cdp:") ? n.uid.slice(4) : n.uid;
+  const name = n.name !== undefined ? ` ${JSON.stringify(n.name)}` : "";
+  const extrasToks: string[] = [];
+  if (n.extras) {
+    for (const [k, v] of Object.entries(n.extras)) {
+      if (BARE_TOKEN_EXTRAS.has(k)) extrasToks.push(k);
+      else if (UNQUOTED_EXTRAS.has(k)) extrasToks.push(`${k}=${v}`);
+      else extrasToks.push(`${k}=${JSON.stringify(v)}`);
+    }
+  }
+  const extra = extrasToks.length ? ` [${extrasToks.join(" ")}]` : "";
+  return `${indent}[${uidText}] ${n.role}${name}${extra}`;
+}
+
+export async function takeSnapshot(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; interactiveOnly?: boolean } = {},
+): Promise<{ snapshot: string; target: { id: string; url: string; title: string }; nodeCount: number }> {
+  return withPage(driver, args.target, async (page) => {
+    const nodes = await page.snapshot({ interactiveOnly: args.interactiveOnly ?? false });
+    const scheme = page.browser.scheme;
+    return { snapshot: nodes.map((n) => renderSnapshotLine(n, scheme)).join("\n"), target: target3(page.info), nodeCount: nodes.length };
+  });
+}
+
+/* ------------------------------ interaction (8) ------------------------------ */
+
+export async function click(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number },
+): Promise<{ clicked: true; x: number; y: number }> {
+  return withPage(driver, args.target, async (page) => {
+    const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1 });
+    return { clicked: true, x, y };
+  });
+}
+
+export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; x: number; y: number }> {
+  return withPage(driver, args.target, async (page) => {
+    const { x, y } = await page.hover(locatorOf(args));
+    return { hovered: true, x, y };
+  });
+}
+
+export async function drag(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; from: { uid?: DriverUid; selector?: string }; to: { uid?: DriverUid; selector?: string } },
+): Promise<{ dragged: true; from: { x: number; y: number }; to: { x: number; y: number } }> {
+  if (!args.from || !args.to) throw new SharedToolError("drag requires { from } and { to }");
+  return withPage(driver, args.target, async (page) => {
+    const { from, to } = await page.drag(locatorOf(args.from), locatorOf(args.to));
+    return { dragged: true, from, to };
+  });
+}
+
+export async function fill(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; value: string }): Promise<{ filled: true; value: string }> {
+  if (typeof args.value !== "string") throw new SharedToolError("fill requires a string { value }");
+  return withPage(driver, args.target, async (page) => {
+    await page.setValue(locatorOf(args), args.value);
+    return { filled: true, value: args.value };
+  });
+}
+
+export async function fillForm(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; fields: Array<{ uid?: DriverUid; selector?: string; value: string }> },
+): Promise<{ filled: number; fields: number }> {
+  if (!Array.isArray(args.fields) || args.fields.length === 0) throw new SharedToolError("fill_form requires a non-empty { fields } array");
+  return withPage(driver, args.target, async (page) => {
+    let filled = 0;
+    for (const f of args.fields) {
+      if (typeof f.value !== "string") throw new SharedToolError("each fill_form field requires a string value");
+      await page.setValue(locatorOf(f), f.value);
+      filled++;
+    }
+    return { filled, fields: args.fields.length };
+  });
+}
+
+export async function typeText(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; text: string }): Promise<{ typed: true; text: string }> {
+  if (typeof args.text !== "string") throw new SharedToolError("type_text requires a string { text }");
+  return withPage(driver, args.target, async (page) => {
+    await page.typeText(locatorOf(args), args.text);
+    return { typed: true, text: args.text };
+  });
+}
+
+export async function pressKey(driver: BrowserDriver, args: { target?: TargetSelector; key: string; modifiers?: string[] }): Promise<{ pressed: string; modifiers: string[] }> {
+  if (typeof args.key !== "string" || !args.key.length) throw new SharedToolError("press_key requires a non-empty { key }");
+  const modifiers = args.modifiers ?? [];
+  return withPage(driver, args.target, async (page) => {
+    await page.pressKey({ key: args.key, modifiers });
+    return { pressed: args.key, modifiers };
+  });
+}
+
+export async function uploadFile(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string; files: string | string[] }): Promise<{ uploaded: string[] }> {
+  const files = Array.isArray(args.files) ? args.files : [args.files];
+  if (!files.length || files.some((f) => typeof f !== "string" || !f.length)) {
+    throw new SharedToolError("upload_file requires { files } as a non-empty path or array of paths");
+  }
+  return withPage(driver, args.target, async (page) => {
+    await page.setFiles(locatorOf(args), files);
+    return { uploaded: files };
+  });
+}
+
+/* -------------------------- screenshot + emulation (3) -------------------------- */
+
+function stamp(): string {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+
+export async function takeScreenshot(
+  driver: BrowserDriver,
+  args: {
+    target?: TargetSelector; format?: "png" | "jpeg"; quality?: number; fullPage?: boolean;
+    uid?: DriverUid; selector?: string; savePath?: string; returnBase64?: boolean;
+  } = {},
+): Promise<{ path: string; bytes: number; format: "png" | "jpeg"; target: { id: string; url: string; title: string }; base64?: string }> {
+  if ((args.uid !== undefined && args.uid !== "") && args.selector) throw new SharedToolError("provide exactly one of uid or selector, not both");
+  const format = args.format ?? "png";
+  return withPage(driver, args.target, async (page) => {
+    const clip = args.uid !== undefined || args.selector ? locatorOf(args) : undefined;
+    const { data, format: outFormat } = await page.screenshot({ format, quality: args.quality, fullPage: args.fullPage, ...(clip ? { clip } : {}) });
+    if (data.byteLength === 0) throw new SharedToolError("captureScreenshot returned empty data");
+    await mkdir(ARTIFACT_DIR, { recursive: true });
+    const ext = outFormat === "jpeg" ? "jpg" : "png";
+    const path = args.savePath ?? join(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
+    await writeFile(path, Buffer.from(data));
+    const result: { path: string; bytes: number; format: "png" | "jpeg"; target: { id: string; url: string; title: string }; base64?: string } = {
+      path, bytes: data.byteLength, format: outFormat, target: target3(page.info),
+    };
+    if (args.returnBase64) result.base64 = Buffer.from(data).toString("base64");
+    return result;
+  });
+}
+
+export async function emulate(
+  driver: BrowserDriver,
+  args: {
+    target?: TargetSelector; width?: number; height?: number; deviceScaleFactor?: number; mobile?: boolean;
+    userAgent?: string; cpuThrottlingRate?: number; media?: string; mediaFeatures?: Array<{ name: string; value: string }>;
+    networkConditions?: { offline?: boolean; latency?: number; downloadThroughput?: number; uploadThroughput?: number; connectionType?: string };
+    clearOverrides?: boolean;
+  } = {},
+): Promise<{ target: { id: string; url: string; title: string }; applied: string[]; cleared?: boolean }> {
+  return withPage(driver, args.target, async (page) => {
+    if (args.clearOverrides) {
+      await page.emulate({ clearOverrides: true });
+      return { target: target3(page.info), applied: [], cleared: true };
+    }
+    const { applied } = await page.emulate(args);
+    if (applied.length === 0) throw new SharedToolError("emulate: no overrides specified (pass clearOverrides:true to reset)");
+    return { target: target3(page.info), applied };
+  });
+}
+
+export async function resizePage(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; width: number; height: number; deviceScaleFactor?: number; mobile?: boolean },
+): Promise<{ target: { id: string; url: string; title: string }; width: number; height: number; innerWidth: number; innerHeight: number }> {
+  if (!Number.isFinite(args.width) || !Number.isFinite(args.height) || args.width <= 0 || args.height <= 0) {
+    throw new SharedToolError("resize_page requires positive numeric width and height");
+  }
+  return withPage(driver, args.target, async (page) => {
+    await page.emulate({ width: args.width, height: args.height, deviceScaleFactor: args.deviceScaleFactor, mobile: args.mobile });
+    const v = (await page.evaluate("({ w: window.innerWidth, h: window.innerHeight })")) as { w?: number; h?: number } | undefined;
+    return { target: target3(page.info), width: args.width, height: args.height, innerWidth: v?.w ?? args.width, innerHeight: v?.h ?? args.height };
+  });
+}
+
+/* ---------------------------------- dialogs (1) ---------------------------------- */
+
+export async function handleDialog(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; accept: boolean; promptText?: string; timeoutMs?: number; autoMs?: number },
+): Promise<unknown> {
+  if (args.accept === undefined) throw new SharedToolError("handle_dialog requires { accept }");
+  return withPage(driver, args.target, (page) => page.handleDialog(args.accept, args.promptText, { timeoutMs: args.timeoutMs, autoMs: args.autoMs }));
+}
+
+/* ------------------------------------- registry ------------------------------------- */
+
+/** The 20 tools this file unifies, importable by both src/index.ts (Chrome) and
+ *  src/firefox-tools.ts (Firefox). Each function is (driver, args) => Promise<result>. */
+export const SHARED_TOOLS = {
+  list_pages: listPages,
+  new_page: newPage,
+  close_page: closePage,
+  select_page: selectPage,
+  navigate_page: navigatePage,
+  wait_for: waitForText,
+  evaluate_script: evaluateScript,
+  take_snapshot: takeSnapshot,
+  click,
+  hover,
+  drag,
+  fill,
+  fill_form: fillForm,
+  type_text: typeText,
+  press_key: pressKey,
+  upload_file: uploadFile,
+  take_screenshot: takeScreenshot,
+  emulate,
+  resize_page: resizePage,
+  handle_dialog: handleDialog,
+} satisfies Record<string, (driver: BrowserDriver, args: never) => Promise<unknown>>;

package/src/tools/console.ts

@@ -1,5 +1,5 @@
 /**
- * console.ts — read console output captured by the recorder.
+ * console.ts: read console output captured by the recorder.
  *
  *   list_console_messages -> listConsoleMessages
  *   get_console_message   -> getConsoleMessage
@@ -135,7 +135,7 @@ async function readConsoleEntries(file: string): Promise<ConsoleEntry[]> {
 }
 
 /**
- * list_console_messages — return console output for the target. With
+ * list_console_messages: return console output for the target. With
  * `reload:true`, records a fresh capture window by reloading the page.
  */
 export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): Promise<{
@@ -166,7 +166,7 @@ export async function listConsoleMessages(args: ListConsoleMessagesArgs = {}): P
 }
 
 /**
- * get_console_message — return a single console entry by index from the
+ * get_console_message: return a single console entry by index from the
  * existing buffer for the target. Throws if the index is out of range.
  */
 export async function getConsoleMessage(args: GetConsoleMessageArgs = {}): Promise<ConsoleEntry> {

package/src/tools/evaluate.ts

@@ -1,5 +1,5 @@
 /**
- * evaluate_script — run arbitrary JavaScript in a page's main context over raw
+ * evaluate_script: run arbitrary JavaScript in a page's main context over raw
  * CDP and return the evaluated value.
  *
  * Two modes, selected by whether `args` is supplied:
@@ -148,7 +148,7 @@ export async function evaluateScript(args: EvaluateScriptArgs): Promise<unknown>
  *
  * Parity gaps vs chrome-devtools-mcp evaluate_script:
  *   - MCP injects a typed `page`/element handle into the evaluated function; here `args` are plain
- *     JSON-serializable values passed positionally — no live element/page handle is bound.
+ *     JSON-serializable values passed positionally; no live element/page handle is bound.
  *   - Non-serializable return values (DOM nodes, functions, circular objects) come back as their CDP
  *     `description` string rather than a structured handle, since returnByValue is used.
  *   - No isolated-world/contextId selection: evaluation runs in the page's default main-world context.

package/src/tools/heap.ts

@@ -1,5 +1,5 @@
 /**
- * heap.ts — `take_heapsnapshot` over raw CDP.
+ * heap.ts: `take_heapsnapshot` over raw CDP.
  *
  * Captures a V8 heap snapshot of a page target and writes it as a
  * `.heapsnapshot` file (the JSON format DevTools' Memory panel loads).
@@ -7,7 +7,7 @@
  * CDP semantics this module relies on:
  *   - `HeapProfiler.takeHeapSnapshot` streams the snapshot back as a sequence
  *     of `HeapProfiler.addHeapSnapshotChunk` events. The command's own result
- *     does NOT carry the data — it resolves only after the final chunk has been
+ *     does NOT carry the data; it resolves only after the final chunk has been
  *     emitted. So we subscribe to the chunk event first, accumulate every
  *     chunk's string, then `await` the command; once it resolves we have the
  *     complete snapshot and join the chunks into one JSON document.
@@ -103,7 +103,7 @@ export async function takeHeapsnapshot(
  *
  * Parity gaps vs chrome-devtools-mcp `take_heapsnapshot`:
  *   - reportProgress is forced false; no incremental progress callbacks surfaced.
- *   - Returns {path,bytes,chunks,target} only — does not parse/summarize the
+ *   - Returns {path,bytes,chunks,target} only; does not parse/summarize the
  *     snapshot (node counts, retained sizes); the .heapsnapshot file is for the
  *     DevTools Memory panel to load, matching the MCP tool's artifact behavior.
  * --------------------------------------------------------------------------*/

package/src/tools/lighthouse.ts

@@ -1,5 +1,5 @@
 /**
- * lighthouse_audit — THE ONLY non-CDP tool in this toolkit.
+ * lighthouse_audit: THE ONLY non-CDP tool in this toolkit.
  *
  * Unlike every other module, this one does NOT speak the Chrome DevTools
  * Protocol over a WebSocket. Instead it shells out to the external Lighthouse
@@ -105,7 +105,7 @@ interface LighthouseReport {
 }
 
 export interface LighthouseAuditArgs {
-  /** The URL to audit. Required — never points at a user tab implicitly. */
+  /** The URL to audit. Required, and never points at a user tab implicitly. */
   url: string;
   /**
    * Lighthouse categories to run. Defaults to the full set.
@@ -206,7 +206,7 @@ export async function lighthouseAudit(
     const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(
       res.stderr,
     )
-      ? " The Lighthouse CLI could not be fetched/installed via npx — ensure network access and that 'lighthouse' is installable."
+      ? " The Lighthouse CLI could not be fetched/installed via npx; ensure network access and that 'lighthouse' is installable."
       : "";
     throw new CdpError(
       `lighthouse_audit produced no report (exit code ${res.code}).${hint} stderr: ${truncate(res.stderr)}`,
@@ -264,7 +264,7 @@ function truncate(s: string, max = 600): string {
  * ---------------------------------------------------------------------------
  * NON-CDP MODULE. This is the toolkit's sole tool that does not speak raw CDP.
  *
- * External dependency (subprocess, fetched on demand by npx — not an npm dep):
+ * External dependency (subprocess, fetched on demand by npx, not an npm dep):
  *   - `npx --yes lighthouse <url> --port=<cdpPort> --output=json
  *      --output-path=<artifact> --quiet --preset=desktop
  *      [--only-categories=...] --chrome-flags=--headless=new`

package/src/tools/navigation.ts

@@ -48,7 +48,7 @@ export interface NavigatePageResult {
  * finish loading.
  *
  * `Page.navigate`/`Page.reload` resolve once the action is *committed*. We
- * separately race the load milestone event — subscribed BEFORE issuing the
+ * separately race the load milestone event, subscribed BEFORE issuing the
  * command so a fast load can't fire before we're listening. Pass
  * `reload:true, ignoreCache:true` for a hard reload that refetches every
  * subresource (the only way to pick up a freshly-deployed bundle the HTTP

package/src/tools/network.ts

@@ -1,5 +1,5 @@
 /**
- * network.ts — read network activity captured by the recorder.
+ * network.ts: read network activity captured by the recorder.
  *
  *   list_network_requests -> listNetworkRequests
  *   get_network_request   -> getNetworkRequest
@@ -8,14 +8,14 @@
  *   - default ({ reload: false }): read the target's shared "latest" buffer
  *     (rec-<targetId>.jsonl), correlate the four Network.* events by requestId,
  *     and return one row per request.
- *   - { reload: true }: run a captureWindow (both domains) — Page.reload, capture
+ *   - { reload: true }: run a captureWindow (both domains): Page.reload, capture
  *     for `durationMs` (default 2500ms), stop, then read+return the requests.
  *
  * Response bodies: CDP only serves a body from the LIVE renderer session, so
  * get_network_request with { includeBody: true } drives a fresh reload capture
  * and calls Network.getResponseBody before closing. Because a reload re-mints
  * requestIds, body fetch is matched by `url` (stable), not by a carried-over
- * requestId — see getNetworkRequest for the exact contract.
+ * requestId; see getNetworkRequest for the exact contract.
  */
 import { readFile } from "node:fs/promises";
 import { CdpError, resolveTarget } from "../client.ts";
@@ -59,7 +59,7 @@ export interface ListNetworkRequestsArgs {
 
 export interface GetNetworkRequestArgs {
   target?: TargetSelector;
-  /** Match by exact requestId (metadata only — see includeBody). */
+  /** Match by exact requestId (metadata only, see includeBody). */
   requestId?: string;
   /** Match by URL substring (first match). Required for body fetch (includeBody). */
   url?: string;
@@ -153,7 +153,7 @@ async function readNetworkRequests(file: string): Promise<NetworkRequest[]> {
 }
 
 /**
- * list_network_requests — correlated request rows for the target. With
+ * list_network_requests: correlated request rows for the target. With
  * `reload:true`, records a fresh capture window (both domains) by reloading.
  */
 export async function listNetworkRequests(args: ListNetworkRequestsArgs = {}): Promise<{
@@ -187,13 +187,13 @@ export async function listNetworkRequests(args: ListNetworkRequestsArgs = {}): P
 }
 
 /**
- * get_network_request — return one request (matched by requestId, else by URL
+ * get_network_request: return one request (matched by requestId, else by URL
  * substring) including response status/headers.
  *
  * Body retrieval: CDP only serves a response body from the LIVE renderer
  * session, so `includeBody:true` must drive a fresh reload capture and fetch the
  * body before the connection closes. A reload re-mints requestIds, so a body
- * fetch can only be matched by `url` (stable across reload) — NOT by a
+ * fetch can only be matched by `url` (stable across reload), NOT by a
  * `requestId` carried over from a prior `list_network_requests`. When a
  * requestId is supplied with includeBody we therefore return metadata from the
  * existing buffer and explain why the body is unavailable, rather than reloading