browser-debugger-cli 0.7.2 → 0.9.0

package/dist/runtime/dom/evalHelpers.js

@@ -0,0 +1,516 @@
+import { CDPProtocolError } from '../../connection/errors.js';
+import { CommandError } from '../../errors/index.js';
+import { navigationPendingError, pageBusyError, pageClosedDuringEvalError, pageNavigatedDuringEvalError, promiseTimeoutError, scriptExecutionError, scriptTimeoutError, } from '../../errors/messages.js';
+import { pendingNavigationUrl } from '../page/navigation.js';
+import { senderFor } from '../../telemetry/objectExpander.js';
+import { formatRemoteObject } from '../../telemetry/remoteObject.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+const log = createLogger('dom');
+/**
+ * Type guard to validate CDP Runtime.evaluate response structure
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid Protocol.Runtime.EvaluateResponse
+ */
+function isRuntimeEvaluateResult(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const obj = value;
+    if (!('result' in obj) && !('exceptionDetails' in obj)) {
+        return false;
+    }
+    if ('exceptionDetails' in obj) {
+        const exceptionDetails = obj['exceptionDetails'];
+        if (typeof exceptionDetails !== 'object' || exceptionDetails === null) {
+            return false;
+        }
+        const details = exceptionDetails;
+        if ('exception' in details) {
+            const exception = details['exception'];
+            if (typeof exception !== 'object' || exception === null) {
+                return false;
+            }
+            const exObj = exception;
+            if ('description' in exObj && typeof exObj['description'] !== 'string') {
+                return false;
+            }
+        }
+    }
+    if ('result' in obj) {
+        const result = obj['result'];
+        if (typeof result !== 'object' || result === null) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Execute JavaScript in browser context via CDP
+ *
+ * @param cdp - CDP connection instance
+ * @param script - JavaScript expression to execute
+ * @param options - Runtime.evaluate options (default: return the value as JSON)
+ * @returns Execution result
+ * @throws Error When script execution throws exception or returns invalid response
+ */
+export async function executeScript(cdp, script, options = { returnByValue: true }) {
+    const startedAt = Date.now();
+    let response;
+    try {
+        response = await cdp.send('Runtime.evaluate', {
+            expression: script,
+            awaitPromise: true,
+            ...options,
+        });
+    }
+    catch (error) {
+        const elapsed = Date.now() - startedAt;
+        const timeout = options.timeout;
+        if (timeout !== undefined && elapsed >= timeout && elapsed < timeout + TERMINATION_GRACE_MS) {
+            const err = scriptTimeoutError(timeout);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+        }
+        throw error;
+    }
+    if (!isRuntimeEvaluateResult(response)) {
+        throw new CommandError('Invalid CDP Runtime.evaluate response structure', {
+            suggestion: 'CDP response did not match expected format. This may indicate a CDP protocol version mismatch',
+        }, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    if (response.exceptionDetails && isTerminated(response.exceptionDetails)) {
+        const err = scriptTimeoutError(options.timeout ?? 0);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+    }
+    if (response.exceptionDetails) {
+        const errorMsg = describeException(response.exceptionDetails);
+        const err = scriptExecutionError(errorMsg, script);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    return response;
+}
+/**
+ * Wait for a returned promise and use its value, as `dom eval` always has
+ * (REPL mode awaits top-level `await` but returns a promise value as is).
+ *
+ * @param cdp - CDP connection
+ * @param result - Evaluation result
+ * @param script - The script (for error messages)
+ * @returns The promise's value, or `result` if it is not a promise
+ * @throws CommandError (91) when the promise rejects
+ */
+async function settlePromise(cdp, result, script) {
+    if (result.subtype !== 'promise' || !result.objectId)
+        return result;
+    const settled = (await cdp.send('Runtime.awaitPromise', {
+        promiseObjectId: result.objectId,
+        returnByValue: false,
+        generatePreview: true,
+    }));
+    if (settled.exceptionDetails) {
+        const err = scriptExecutionError(describeException(settled.exceptionDetails), script);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.SCRIPT_ERROR);
+    }
+    return settled.result;
+}
+/**
+ * Message of an exception, including thrown non-Error values (`throw "x"`).
+ *
+ * @param details - Exception details
+ * @returns Readable message
+ */
+function describeException(details) {
+    const exception = details.exception;
+    if (exception?.type === 'object' && exception.subtype !== 'error' && exception.preview) {
+        return `Uncaught ${formatRemoteObject(exception)}`;
+    }
+    if (exception?.description)
+        return exception.description;
+    if (exception?.value !== undefined) {
+        return `Uncaught ${typeof exception.value === 'string' ? exception.value : JSON.stringify(exception.value)}`;
+    }
+    return details.text || 'Unknown error executing script';
+}
+/** Time after the limit within which a failed evaluate counts as V8 terminating it. */
+const TERMINATION_GRACE_MS = 5_000;
+/** How long a `bdg dom eval` script may run before V8 terminates it. */
+const EVAL_TIMEOUT_MS = 20_000;
+/** Object group for remote objects created by `bdg dom eval`. */
+const EVAL_OBJECT_GROUP = 'bdg-eval';
+/** Object subtypes shown as a description rather than as JSON. */
+const DESCRIBED_SUBTYPES = new Set([
+    'node',
+    'date',
+    'regexp',
+    'error',
+    'map',
+    'set',
+    'weakmap',
+    'weakset',
+    'promise',
+    'proxy',
+    'iterator',
+    'generator',
+]);
+/** Object subtypes shown by their short description (`button#submit`, `ArrayBuffer(8)`). */
+const BRIEF_SUBTYPES = new Set(['node', 'arraybuffer', 'dataview']);
+/**
+ * Page-side copy of an object as JSON, keeping what JSON would lose inside
+ * it: `undefined`, NaN, ±Infinity and -0 become strings, DOM nodes their
+ * short description (`button#submit`), node lists and typed arrays arrays,
+ * dates ISO strings, maps and sets entries, errors their message, BigInts
+ * `12n`, functions `function name()`, and cycles `[Circular]` (an object
+ * shared by two properties is copied twice). Works for objects of iframes
+ * (other realms); lists and objects are cut after 1000 entries, and a
+ * throwing getter becomes `[Error: …]`.
+ */
+export const JSON_SAFE_COPY_FUNCTION = `function () {
+  const MAX_ITEMS = 1000;
+  const ancestors = new Set();
+  const kind = (value) => Object.prototype.toString.call(value).slice(8, -1);
+  const isNode = (value) => typeof value.nodeType === 'number' && typeof value.nodeName === 'string';
+  const describeNode = (node) => {
+    if (node.nodeType !== 1) return node.nodeName.toLowerCase();
+    return node.tagName.toLowerCase() + (node.id ? '#' + node.id : '') +
+      (node.classList && node.classList.length ? '.' + Array.from(node.classList).join('.') : '');
+  };
+  const items = (list, next) => {
+    const result = [];
+    let count = 0;
+    for (const item of list) {
+      if (count++ === MAX_ITEMS) { result.push('…'); break; }
+      result.push(next(item));
+    }
+    return result;
+  };
+  const leaf = (value) => {
+    if (value === undefined) return null;
+    if (typeof value === 'number') {
+      if (Number.isNaN(value) || !Number.isFinite(value)) return String(value);
+      return Object.is(value, -0) ? '-0' : value;
+    }
+    if (typeof value === 'bigint') return value + 'n';
+    if (typeof value === 'symbol') return value.toString();
+    if (typeof value === 'function') return 'function ' + (value.name || '(anonymous)') + '()';
+    return value;
+  };
+  const copy = (value, depth) => {
+    if (value === null || typeof value !== 'object') return leaf(value);
+    if (ancestors.has(value)) return '[Circular]';
+    if (depth > 20) return '[…]';
+    const next = (item) => copy(item, depth + 1);
+    const type = kind(value);
+    if (isNode(value)) return describeNode(value);
+    if (value.window === value) return 'Window';
+    if (type === 'Date') return isNaN(value) ? 'Invalid Date' : value.toISOString();
+    if (type === 'RegExp') return String(value);
+    if (type === 'Error' || value instanceof Error) return value.name + ': ' + value.message;
+    ancestors.add(value);
+    try {
+      if (type === 'Map') return items(value, ([k, v]) => [next(k), next(v)]);
+      if (type === 'Set' || type === 'NodeList' || type === 'HTMLCollection') return items(value, next);
+      if (ArrayBuffer.isView(value) && type !== 'DataView') return items(value, next);
+      if (Array.isArray(value)) return items(value, next);
+      const result = {};
+      const keys = Object.keys(value);
+      for (const key of keys.slice(0, MAX_ITEMS)) {
+        try { result[key] = next(value[key]); } catch (e) { result[key] = '[Error: ' + (e && e.message) + ']'; }
+      }
+      if (keys.length > MAX_ITEMS) result['…'] = (keys.length - MAX_ITEMS) + ' more keys';
+      return result;
+    } finally {
+      ancestors.delete(value);
+    }
+  };
+  return copy(this, 0);
+}`;
+/**
+ * Whether an exception is V8 terminating a script that ran too long.
+ *
+ * @param details - Exception details
+ * @returns True for a terminated execution
+ */
+function isTerminated(details) {
+    return /Execution was terminated/i.test(details.exception?.description ?? details.text);
+}
+/**
+ * Convert an evaluation result to a JSON-safe value.
+ *
+ * Plain objects and arrays are copied by value; values JSON cannot represent
+ * (NaN, -0, BigInt, functions, symbols, DOM nodes, dates, maps, errors, the
+ * window, cyclic objects) are given as their readable description.
+ *
+ * @param cdp - CDP connection
+ * @param remote - Remote object returned by Runtime.evaluate
+ * @returns Value and type
+ */
+async function toEvalResult(cdp, remote) {
+    const kind = { type: remote.type, ...(remote.subtype && { subtype: remote.subtype }) };
+    if (remote.unserializableValue !== undefined)
+        return { value: remote.unserializableValue, ...kind };
+    if (remote.type === 'undefined')
+        return { value: undefined, ...kind };
+    if (!remote.objectId || remote.subtype === 'null')
+        return { value: remote.value ?? null, ...kind };
+    if (BRIEF_SUBTYPES.has(remote.subtype ?? '')) {
+        return { value: remote.description ?? remote.subtype, ...kind };
+    }
+    if (remote.type !== 'object' || DESCRIBED_SUBTYPES.has(remote.subtype ?? '')) {
+        return { value: formatRemoteObject(remote), ...kind };
+    }
+    try {
+        const copy = (await cdp.send('Runtime.callFunctionOn', {
+            objectId: remote.objectId,
+            functionDeclaration: JSON_SAFE_COPY_FUNCTION,
+            returnByValue: true,
+        }));
+        if (!copy.exceptionDetails)
+            return { value: copy.result?.value, ...kind };
+    }
+    catch (error) {
+        log.debug(`Could not copy eval result by value: ${getErrorMessage(error)}`);
+    }
+    return { value: formatRemoteObject(remote), ...kind };
+}
+/**
+ * Wait for `work`, or fail when it takes longer than `ms`.
+ *
+ * @param work - Pending work (its later failure is ignored once timed out)
+ * @param ms - Time limit
+ * @param onTimeout - Builds the error (and may clean up) when the limit passes
+ * @returns The work's result
+ * @throws What `onTimeout` returns, when the limit passes first
+ */
+async function withDeadline(work, ms, onTimeout) {
+    let timer;
+    const expired = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => void Promise.resolve(onTimeout()).then(reject, reject), ms);
+    });
+    work.catch(() => undefined);
+    try {
+        return await Promise.race([work, expired]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Stop whatever JavaScript keeps the page busy (e.g. a loop started from a
+ * timer, which `Runtime.evaluate`'s own timeout cannot reach: the script
+ * waits behind it), so the page is usable again. A page that is not
+ * answering because a navigation still waits for the server is left alone.
+ *
+ * @param cdp - CDP connection
+ * @param scope - Whether the target is the page or an iframe
+ * @returns The timeout error to report
+ */
+async function terminatePageScripts(cdp, scope) {
+    const pendingUrl = await pendingNavigationUrl(cdp).catch((error) => {
+        log.debug(`Could not check for a pending navigation: ${getErrorMessage(error)}`);
+        return undefined;
+    });
+    if (pendingUrl !== undefined) {
+        const err = navigationPendingError(pendingUrl);
+        return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+    }
+    const err = pageBusyError(EVAL_TIMEOUT_MS, scope, await terminateExecution(cdp));
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+}
+/**
+ * Ask V8 to terminate the target's running script.
+ *
+ * @param cdp - CDP connection of the target
+ * @returns Whether the target acknowledged it in time
+ */
+async function terminateExecution(cdp) {
+    try {
+        const stopped = await settledWithin(cdp.send('Runtime.terminateExecution'), LIVENESS_CHECK_MS);
+        return stopped.settled;
+    }
+    catch (error) {
+        log.debug(`terminateExecution failed: ${getErrorMessage(error)}`);
+        return false;
+    }
+}
+/** How long a page gets to answer a liveness check before it counts as busy */
+const LIVENESS_CHECK_MS = 2_000;
+/**
+ * Whether the target answers a trivial evaluation in time.
+ *
+ * @param cdp - CDP connection
+ * @param ms - Time limit
+ * @returns False when its scripts keep it busy
+ */
+async function isAnswering(cdp, ms) {
+    const probe = await settledWithin(cdp.send('Runtime.evaluate', { expression: '1', returnByValue: true }), ms);
+    return probe.settled;
+}
+/** Chrome's messages for a command whose execution context or target went away */
+const CONTEXT_LOST_PATTERN = /Execution context was destroyed|Inspected target navigated or closed|Cannot find context with specified id|uniqueContextId not found|Session with given id not found/i;
+/**
+ * Whether Chrome failed a command because the document it ran in went away
+ * (navigation, a removed iframe).
+ *
+ * @param error - Error thrown by a CDP command
+ * @returns True for a lost context
+ */
+export function isContextLostError(error) {
+    return error instanceof CDPProtocolError && CONTEXT_LOST_PATTERN.test(error.message);
+}
+/**
+ * Run a CDP command on the page, recovering a page kept busy by its own
+ * scripts. If the command has not answered when a script would have been
+ * terminated, the page is checked with a trivial evaluation: a page that
+ * answers is only slow (a huge screenshot or tree), so the command keeps
+ * waiting; a page that does not answer has its scripts terminated, and the
+ * command fails with 102 instead of hanging until the connection times out.
+ *
+ * @param cdp - CDP connection
+ * @param command - The pending command
+ * @param options - When to check the page, how long it gets to answer, what to call it
+ * @returns The command's result
+ * @throws CommandError (102) when the page was busy
+ */
+export async function withBusyPageRecovery(cdp, command, options = {}) {
+    const { busyAfterMs = EVAL_TIMEOUT_MS + TERMINATION_GRACE_MS, livenessMs = LIVENESS_CHECK_MS, scope = 'page', } = options;
+    command.catch(() => undefined);
+    const early = await settledWithin(command, busyAfterMs);
+    if (early.settled)
+        return early.value;
+    if (await isAnswering(cdp, livenessMs))
+        return command;
+    throw await terminatePageScripts(cdp, scope);
+}
+/**
+ * The work's value if it settles within `ms` (its rejection is passed on).
+ *
+ * @param work - Pending work
+ * @param ms - Time limit
+ * @returns `{ settled: true, value }`, or `{ settled: false }` when time ran out
+ */
+export async function settledWithin(work, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ settled: false }), ms);
+    });
+    try {
+        return await Promise.race([work.then((value) => ({ settled: true, value })), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The error for an evaluation that did not answer in time: a target that
+ * still answers was only waiting for a promise that never settled
+ * (`await new Promise(() => {})`); one that does not answer is busy, and its
+ * scripts are terminated.
+ *
+ * @param cdp - CDP connection of the target
+ * @param scope - Whether the script ran in the page or an iframe
+ * @returns The error to report (102)
+ */
+async function evaluationTimeoutError(cdp, scope) {
+    if (await isAnswering(cdp, LIVENESS_CHECK_MS))
+        return promiseTimeout();
+    return terminatePageScripts(cdp, scope);
+}
+/**
+ * A promise the script awaited or returned did not settle in time.
+ *
+ * @returns Command error (102)
+ */
+function promiseTimeout() {
+    const err = promiseTimeoutError(EVAL_TIMEOUT_MS);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+}
+/** Chrome's message for a command sent to a session (target) that is gone */
+const SESSION_GONE_PATTERN = /Session with given id not found/i;
+/**
+ * Whether the page still answers. A page that does not answer in time is
+ * taken as open: commands wait while a navigation is pending.
+ *
+ * @param cdp - CDP connection of the page
+ * @returns False when the page (tab) was closed
+ */
+export async function pageStillOpen(cdp) {
+    try {
+        await settledWithin(cdp.send('Runtime.evaluate', { expression: '1', returnByValue: true }), LIVENESS_CHECK_MS);
+        return true;
+    }
+    catch (error) {
+        log.debug(`Page did not answer: ${getErrorMessage(error)}`);
+        return false;
+    }
+}
+/**
+ * The error for a page script whose context went away: the page navigated,
+ * or the tab was closed.
+ *
+ * @param error - Chrome's context-lost error
+ * @param cdp - CDP connection of the page
+ * @returns Command error (83)
+ */
+async function pageContextLostError(error, cdp) {
+    const sessionGone = SESSION_GONE_PATTERN.test(getErrorMessage(error));
+    const err = sessionGone || !(await pageStillOpen(cdp))
+        ? pageClosedDuringEvalError()
+        : pageNavigatedDuringEvalError();
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
+/**
+ * `Runtime.evaluate` options of a `bdg dom eval` script.
+ *
+ * @param target - Execution context to run in
+ * @returns Options (REPL mode, previews, 20 s limit)
+ */
+function evaluateOptions(target) {
+    return {
+        returnByValue: false,
+        generatePreview: true,
+        replMode: true,
+        objectGroup: EVAL_OBJECT_GROUP,
+        timeout: EVAL_TIMEOUT_MS,
+        ...(target.uniqueContextId && { uniqueContextId: target.uniqueContextId }),
+    };
+}
+/**
+ * Evaluate a `bdg dom eval` script.
+ *
+ * Runs like the DevTools console (REPL mode: top-level `const`/`let` may be
+ * declared again in a later call, top-level `await` works), awaits promises,
+ * terminates scripts running longer than 20 s (so the page is not left
+ * frozen by e.g. an endless loop), and returns a JSON-safe value. The eval's
+ * objects are released without waiting: a script that started a busy loop
+ * from a timer has already returned, and the next command recovers the page.
+ *
+ * @param cdp - CDP connection
+ * @param script - JavaScript expression
+ * @param target - Session and execution context to run in (default: the page)
+ * @returns Value and type
+ * @throws CommandError (102) when the script was terminated or a promise did
+ *   not settle, (91) when it threw, (83) when the page navigated while it ran
+ *   (in a frame, Chrome's context-lost error is passed on for the caller to explain)
+ */
+export async function evaluateScript(cdp, script, target = {}) {
+    const session = senderFor(cdp, target.sessionId);
+    const scope = target.uniqueContextId ? 'frame' : 'page';
+    try {
+        const response = await withDeadline(executeScript(session, script, evaluateOptions(target)), EVAL_TIMEOUT_MS + TERMINATION_GRACE_MS, () => evaluationTimeoutError(target.recovery ?? session, scope));
+        const settled = await withDeadline(settlePromise(session, response.result, script), EVAL_TIMEOUT_MS, promiseTimeout);
+        return await toEvalResult(session, settled);
+    }
+    catch (error) {
+        throw scope === 'page' && isContextLostError(error)
+            ? await pageContextLostError(error, session)
+            : error;
+    }
+    finally {
+        void session
+            .send('Runtime.releaseObjectGroup', { objectGroup: EVAL_OBJECT_GROUP })
+            .catch((error) => log.debug(`Could not release eval objects: ${getErrorMessage(error)}`));
+    }
+}
+//# sourceMappingURL=evalHelpers.js.map

package/dist/runtime/dom/eventListeners.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Event listeners that run for an element (`bdg dom listeners`).
+ *
+ * Collects the listeners of the element, every ancestor (through open shadow
+ * roots), its document and its window with `DOMDebugger.getEventListeners`,
+ * so handlers that frameworks attach by delegation (React on its root
+ * container, jQuery on `document`) are found too, along with the handlers
+ * behind them (jQuery's handlers, React's `on…` props). The Debugger domain is not
+ * enabled: that would make `debugger;` statements pause the page.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { DomListenersCommand } from '../../ipc/protocol/commands.js';
+import type { ListenersResult } from '../../ipc/protocol/domTypes.js';
+/**
+ * List the event listeners that run for an element.
+ *
+ * @param cdp - CDP connection
+ * @param params - Selector (and index) or backend node id, optional event types
+ * @returns Listener report
+ * @throws CommandError (83) no match, (81) index out of range or invalid
+ *   selector, (87) the cached element left the page, (110) no DOMDebugger
+ */
+export declare function inspectEventListeners(cdp: CDPConnection, params: DomListenersCommand): Promise<ListenersResult>;
+//# sourceMappingURL=eventListeners.d.ts.map