browser-debugger-cli 0.15.0 → 0.16.0

package/.claude/skills/bdg/SKILL.md

@@ -56,9 +56,10 @@ bdg page info                                # URL and title
 Page: navigated to https://app.test/secure (200)    # navigation (or "URL changed ... (same document)")
 New text: "Your password is invalid!" (div#flash)   # alert/status/aria-live messages that appeared
 ⚠ Element Clicked (no visible effect observed ...)  # nothing changed - wrong element or a broken handler
+Download: report.txt → ~/.bdg/downloads/report.txt (completed, 15 B)  # files go to <session dir>/downloads
 ```
 
-- In `--json`: `navigation`, `messages`, `effect: "none"` and pending work (timers, spinners) are fields on `data`.
+- In `--json`: `navigation`, `messages`, `downloads`, `effect: "none"` and pending work (timers, spinners) are fields on `data`.
 - Results the page shows later are not waited for: follow up with `bdg dom wait`.
 
 ```bash

package/dist/cdp/methodTarget.d.ts

@@ -0,0 +1,92 @@
+/**
+ * What `bdg cdp <name>` calls: the bundled protocol follows Chromium's
+ * tip of tree, so the user's Chrome can have methods it lacks (and lack
+ * methods it has). A well-formed name is sent even when the schema does not
+ * know it, unless it is a close typo of a method or domain the schema knows.
+ */
+/** What a `Domain.method` name resolves to */
+export type MethodTarget = 
+/** A method in the bundled protocol, with its casing */
+{
+    kind: 'known';
+    method: string;
+}
+/** A well-formed method the bundled protocol lacks, sent as typed (known domain recased) */
+ | {
+    kind: 'unlisted';
+    method: string;
+}
+/**
+ * A close typo of bundled methods (suggestions may be empty when only the
+ * domain is close), with the method to send if the user insists
+ */
+ | {
+    kind: 'typo';
+    method: string;
+    suggestions: string[];
+}
+/** A protocol type, not a method */
+ | {
+    kind: 'type';
+    name: string;
+}
+/** Not `Domain.method` */
+ | {
+    kind: 'malformed';
+};
+/**
+ * Decide what `bdg cdp <name>` calls.
+ *
+ * @param input - Method name as typed (case-insensitive for bundled methods)
+ * @returns Known, unlisted, typo, type or malformed
+ *
+ * @example
+ * ```typescript
+ * resolveMethodTarget('network.getcookies');            // known Network.getCookies
+ * resolveMethodTarget('Storage.getRelatedWebsiteSets'); // unlisted: sent as is
+ * resolveMethodTarget('Network.getCookes');             // typo of Network.getCookies
+ * ```
+ */
+export declare function resolveMethodTarget(input: string): MethodTarget;
+/**
+ * Why Chrome may have answered that it has no method bdg sent (-32601), as
+ * far as the bundled protocol tells.
+ */
+export type MissingMethodCause = 
+/** A bundled method: this Chrome is older than the bundled protocol (or the method is not for pages) */
+{
+    kind: 'older';
+}
+/** A bundled method redirected to a method the protocol lacks, with methods close to that one */
+ | {
+    kind: 'deadRedirect';
+    target: string;
+    similar: string[];
+}
+/** A domain the bundled protocol lacks too, with bundled domains close to it */
+ | {
+    kind: 'unknownDomain';
+    domain: string;
+    similar: string[];
+}
+/** A method of a bundled domain the bundled protocol lacks; `oneCase` when typed in one case */
+ | {
+    kind: 'unlisted';
+    oneCase: boolean;
+};
+/**
+ * Why Chrome has no method bdg sent (it answered -32601): a bundled method
+ * this Chrome is older than, one redirected to a method the protocol lacks,
+ * a domain neither knows, or a method the bundled protocol lacks.
+ *
+ * @param method - Method as sent (`Domain.method`, a bundled domain recased)
+ * @returns The cause
+ *
+ * @example
+ * ```typescript
+ * missingMethodCause('Page.deleteCookie'); // deadRedirect to Network.deleteCookie
+ * missingMethodCause('Foo.bar');           // unknownDomain Foo
+ * ```
+ */
+export declare function missingMethodCause(method: string): MissingMethodCause;
+//# sourceMappingURL=methodTarget.d.ts.map

package/dist/cdp/methodTarget.js

@@ -0,0 +1,159 @@
+/**
+ * What `bdg cdp <name>` calls: the bundled protocol follows Chromium's
+ * tip of tree, so the user's Chrome can have methods it lacks (and lack
+ * methods it has). A well-formed name is sent even when the schema does not
+ * know it, unless it is a close typo of a method or domain the schema knows.
+ */
+import { findCommand, findDomain, findType, loadProtocol, normalizeMethod, } from './protocol.js';
+import { levenshteinDistance } from '../utils/levenshtein.js';
+import { findSimilar } from '../utils/suggestions.js';
+/** `Domain.method`: letters and digits, starting with a letter */
+const METHOD_NAME = /^[A-Za-z][A-Za-z0-9]*\.[A-Za-z][A-Za-z0-9]*$/;
+/**
+ * Most edits a name can be off a known one and still count as its typo: 1
+ * for names of up to 5 letters (so `Foo` is not taken for `Log`), else 2.
+ *
+ * @param name - Name as typed
+ * @returns Edit distance limit
+ */
+function typoLimit(name) {
+    return name.length <= 5 ? 1 : 2;
+}
+/**
+ * Names close enough to count as typos of the input, closest first.
+ *
+ * @param input - Name as typed
+ * @param candidates - Known names
+ * @returns Close candidates
+ */
+function closeNames(input, candidates) {
+    const lower = input.toLowerCase();
+    return candidates
+        .map((name) => ({ name, distance: levenshteinDistance(lower, name.toLowerCase()) }))
+        .filter(({ distance }) => distance > 0 && distance <= typoLimit(input))
+        .sort((a, b) => a.distance - b.distance)
+        .map(({ name }) => name);
+}
+/**
+ * Methods of a domain close to the typed method name.
+ *
+ * @param domainName - Domain with its schema casing
+ * @param methodName - Method part as typed
+ * @returns Full names of close methods
+ */
+function closeMethods(domainName, methodName) {
+    const commands = findDomain(domainName)?.commands ?? [];
+    const exact = commands.find((c) => c.name.toLowerCase() === methodName.toLowerCase());
+    const names = exact
+        ? [exact.name]
+        : closeNames(methodName, commands.map((c) => c.name));
+    return names.map((name) => `${domainName}.${name}`);
+}
+/**
+ * Resolve a domain the schema does not know: a typo of a known domain, or a
+ * domain to send as is.
+ *
+ * @param domainName - Domain part as typed
+ * @param methodName - Method part as typed
+ * @returns Typo with suggested methods, or an unlisted method
+ */
+function resolveUnknownDomain(domainName, methodName) {
+    const domains = closeNames(domainName, loadProtocol().domains.map((d) => d.domain));
+    const method = `${domainName}.${methodName}`;
+    if (domains.length === 0)
+        return { kind: 'unlisted', method };
+    return { kind: 'typo', method, suggestions: domains.flatMap((d) => closeMethods(d, methodName)) };
+}
+/**
+ * Decide what `bdg cdp <name>` calls.
+ *
+ * @param input - Method name as typed (case-insensitive for bundled methods)
+ * @returns Known, unlisted, typo, type or malformed
+ *
+ * @example
+ * ```typescript
+ * resolveMethodTarget('network.getcookies');            // known Network.getCookies
+ * resolveMethodTarget('Storage.getRelatedWebsiteSets'); // unlisted: sent as is
+ * resolveMethodTarget('Network.getCookes');             // typo of Network.getCookies
+ * ```
+ */
+export function resolveMethodTarget(input) {
+    if (!METHOD_NAME.test(input))
+        return { kind: 'malformed' };
+    const known = normalizeMethod(input);
+    if (known)
+        return { kind: 'known', method: known };
+    const [domainName = '', methodName = ''] = input.split('.');
+    const domain = findDomain(domainName);
+    if (!domain)
+        return resolveUnknownDomain(domainName, methodName);
+    const type = findType(domain.domain, methodName);
+    if (type)
+        return { kind: 'type', name: `${domain.domain}.${type.id}` };
+    const method = `${domain.domain}.${methodName}`;
+    const suggestions = closeMethods(domain.domain, methodName);
+    return suggestions.length > 0
+        ? { kind: 'typo', method, suggestions }
+        : { kind: 'unlisted', method };
+}
+/**
+ * Names close to a name, for a "Did you mean" after Chrome refused it: up
+ * to half its length off (at most 3), so `Foo` is not taken for `Log`.
+ *
+ * @param name - Name as sent
+ * @param candidates - Known names
+ * @returns Close names, closest first
+ */
+function similarNames(name, candidates) {
+    return findSimilar(name, candidates, {
+        maxDistance: Math.min(3, Math.max(1, Math.floor(name.length / 2))),
+    });
+}
+/**
+ * Whether a method name is all lower or all upper case, which a CDP method
+ * of more than one word never is (they are lowerCamelCase).
+ *
+ * @param methodName - Method part as sent
+ * @returns True for e.g. `getrelatedwebsitesets`
+ */
+function isOneCase(methodName) {
+    return methodName === methodName.toLowerCase() || methodName === methodName.toUpperCase();
+}
+/**
+ * Why Chrome has no method bdg sent (it answered -32601): a bundled method
+ * this Chrome is older than, one redirected to a method the protocol lacks,
+ * a domain neither knows, or a method the bundled protocol lacks.
+ *
+ * @param method - Method as sent (`Domain.method`, a bundled domain recased)
+ * @returns The cause
+ *
+ * @example
+ * ```typescript
+ * missingMethodCause('Page.deleteCookie'); // deadRedirect to Network.deleteCookie
+ * missingMethodCause('Foo.bar');           // unknownDomain Foo
+ * ```
+ */
+export function missingMethodCause(method) {
+    const [domainName = '', methodName = ''] = method.split('.');
+    const domain = findDomain(domainName);
+    if (!domain) {
+        const domains = loadProtocol().domains.map((d) => d.domain);
+        return {
+            kind: 'unknownDomain',
+            domain: domainName,
+            similar: similarNames(domainName, domains),
+        };
+    }
+    const command = findCommand(domain.domain, methodName);
+    if (!command)
+        return { kind: 'unlisted', oneCase: isOneCase(methodName) };
+    if (!command.redirect || findCommand(command.redirect, command.name))
+        return { kind: 'older' };
+    const targetMethods = findDomain(command.redirect)?.commands?.map((c) => c.name) ?? [];
+    return {
+        kind: 'deadRedirect',
+        target: `${command.redirect}.${command.name}`,
+        similar: similarNames(command.name, targetMethods).map((name) => `${command.redirect}.${name}`),
+    };
+}
+//# sourceMappingURL=methodTarget.js.map

package/dist/cdp/protocol.d.ts

@@ -5,7 +5,14 @@
  * devtools-protocol package. Provides utilities for domain/method lookup
  * and introspection.
  */
-import type { ProtocolSchema, Domain, Command } from './types.js';
+import type { ProtocolSchema, Domain, Command, Type } from './types.js';
+/**
+ * Version of the bundled devtools-protocol package, which names the Chromium
+ * revision its schema comes from.
+ *
+ * @returns e.g. '0.0.1710668'
+ */
+export declare function getBundledProtocolVersion(): string;
 /**
  * Load the CDP protocol schema.
  *
@@ -53,6 +60,14 @@ export declare function findDomain(domainName: string): Domain | undefined;
  * ```
  */
 export declare function findCommand(domainName: string, commandName: string): Command | undefined;
+/**
+ * Find a type within a domain (case-insensitive).
+ *
+ * @param domainName - Domain name (e.g., 'Network')
+ * @param typeName - Type id (e.g., 'CookieSameSite', 'cookiesamesite')
+ * @returns Type definition or undefined if not found
+ */
+export declare function findType(domainName: string, typeName: string): Type | undefined;
 /**
  * Normalize a CDP method name to proper casing.
  *

package/dist/cdp/protocol.js

@@ -10,6 +10,16 @@ import { createRequire } from 'module';
 import { dirname, join } from 'path';
 const require = createRequire(import.meta.url);
 let cachedProtocol = null;
+/**
+ * Version of the bundled devtools-protocol package, which names the Chromium
+ * revision its schema comes from.
+ *
+ * @returns e.g. '0.0.1710668'
+ */
+export function getBundledProtocolVersion() {
+    const packageJson = JSON.parse(readFileSync(require.resolve('devtools-protocol/package.json'), 'utf-8'));
+    return packageJson.version;
+}
 /**
  * Load the CDP protocol schema.
  *
@@ -83,6 +93,17 @@ export function findCommand(domainName, commandName) {
     const normalized = commandName.toLowerCase();
     return domain.commands.find((c) => c.name.toLowerCase() === normalized);
 }
+/**
+ * Find a type within a domain (case-insensitive).
+ *
+ * @param domainName - Domain name (e.g., 'Network')
+ * @param typeName - Type id (e.g., 'CookieSameSite', 'cookiesamesite')
+ * @returns Type definition or undefined if not found
+ */
+export function findType(domainName, typeName) {
+    const normalized = typeName.toLowerCase();
+    return findDomain(domainName)?.types?.find((t) => t.id.toLowerCase() === normalized);
+}
 /**
  * Normalize a CDP method name to proper casing.
  *

package/dist/cdp/schema.d.ts

@@ -27,6 +27,16 @@ export interface MethodSchema {
     parameters: ParameterSchema[];
     /** Return value schema */
     returns: ReturnSchema[];
+    /**
+     * The method implementing this one (the schema's `redirect`) and its
+     * parameters; `resolved` is false when the protocol lacks that method
+     * (e.g. Page.deleteCookie names Network.deleteCookie)
+     */
+    redirect?: {
+        method: string;
+        resolved: boolean;
+        parameters: ParameterSchema[];
+    };
     /** Usage example (JSON) */
     example?: {
         command: string;
@@ -45,12 +55,43 @@ export interface ParameterSchema {
     required: boolean;
     /** Human-readable description */
     description?: string;
-    /** Enum values (if type is enum) */
+    /** Enum values (inline, or of the referenced type) */
     enum?: string[];
+    /** Referenced protocol type with its domain (e.g. 'Network.CookieSameSite'), for `--describe` */
+    ref?: string;
+    /** Base type of the referenced type (e.g. 'number' for Network.TimeSinceEpoch, 'object') */
+    refType?: string;
     /** Array item type (if type is array) */
     items?: string;
     /** Deprecated flag */
     deprecated?: boolean;
+    /** Experimental flag */
+    experimental?: boolean;
+}
+/**
+ * Protocol type (`Network.CookieSameSite`, `Network.Cookie`) for agent consumption.
+ */
+export interface TypeSchema {
+    /** Full type name (Domain.Type) */
+    name: string;
+    /** Domain name */
+    domain: string;
+    /** Type id */
+    id: string;
+    /** Base type (string, object, array, ...) */
+    baseType: string;
+    /** Human-readable description */
+    description?: string;
+    /** Whether type is experimental */
+    experimental?: boolean;
+    /** Whether type is deprecated */
+    deprecated?: boolean;
+    /** Enum values (string enums) */
+    enum?: string[];
+    /** Array item type */
+    items?: string;
+    /** Properties (object types) */
+    properties?: ParameterSchema[];
 }
 /**
  * Return value schema for agent consumption.
@@ -100,6 +141,19 @@ export interface DomainSummary {
  * ```
  */
 export declare function getMethodSchema(domainName: string, methodName: string): MethodSchema | undefined;
+/**
+ * Get structured schema for a protocol type.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @param typeName - Type id (case-insensitive)
+ * @returns Type schema or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * getTypeSchema('Network', 'CookieSameSite')?.enum; // ['Strict', 'Lax', 'None']
+ * ```
+ */
+export declare function getTypeSchema(domainName: string, typeName: string): TypeSchema | undefined;
 /**
  * Get all methods in a domain.
  *

package/dist/cdp/schema.js

@@ -7,7 +7,7 @@
  * - Self-describing tools
  * - Structured context without verbosity
  */
-import { loadProtocol, findDomain, findCommand } from './protocol.js';
+import { loadProtocol, findDomain, findCommand, findType } from './protocol.js';
 /**
  * Get structured schema for a specific method.
  *
@@ -40,31 +40,20 @@ export function getMethodSchema(domainName, methodName) {
  * @returns Structured method schema
  */
 function buildMethodSchema(domainName, command) {
-    const parameters = command.parameters?.map(paramToSchema) ?? [];
+    const parameters = command.parameters?.map((p) => paramToSchema(domainName, p)) ?? [];
     const returns = command.returns?.map(returnToSchema) ?? [];
-    const example = {
-        command: `bdg cdp ${domainName}.${command.name}`,
-    };
-    if (parameters.length > 0) {
-        const exampleParams = {};
-        parameters.forEach((p) => {
-            if (!p.required)
-                return; // Skip optional params in example
-            exampleParams[p.name] = getExampleValue(p);
-        });
-        if (Object.keys(exampleParams).length > 0) {
-            example.params = exampleParams;
-            example.command += ` --params '${JSON.stringify(exampleParams)}'`;
-        }
-    }
+    const redirect = buildRedirect(command);
+    const exampleSource = parameters.length > 0 ? parameters : (redirect?.parameters ?? []);
     const schema = {
         name: `${domainName}.${command.name}`,
         domain: domainName,
         method: command.name,
         parameters,
         returns,
-        example,
+        example: buildExample(`${domainName}.${command.name}`, exampleSource),
     };
+    if (redirect)
+        schema.redirect = redirect;
     if (command.description)
         schema.description = command.description;
     if (command.experimental)
@@ -74,24 +63,122 @@ function buildMethodSchema(domainName, command) {
     return schema;
 }
 /**
- * Convert protocol parameter to schema.
+ * The method a redirected command runs (e.g. DOM.highlightNode runs
+ * Overlay.highlightNode), with the parameters Chrome checks, and whether the
+ * protocol has that method.
+ *
+ * @param command - Command from protocol
+ * @returns Redirect target, or undefined when the command has none
+ */
+function buildRedirect(command) {
+    if (!command.redirect)
+        return undefined;
+    const target = findCommand(command.redirect, command.name);
+    return {
+        method: `${command.redirect}.${command.name}`,
+        resolved: target !== undefined,
+        parameters: target?.parameters?.map((p) => paramToSchema(command.redirect ?? '', p)) ?? [],
+    };
+}
+/**
+ * Example command with the required parameters.
+ *
+ * @param methodName - Full method name
+ * @param parameters - Parameters to take the required ones from
+ * @returns Example command and its parameters
+ */
+function buildExample(methodName, parameters) {
+    const example = { command: `bdg cdp ${methodName}` };
+    const required = parameters.filter((p) => p.required);
+    if (required.length === 0)
+        return example;
+    const exampleParams = Object.fromEntries(required.map((p) => [p.name, getExampleValue(p)]));
+    example.params = exampleParams;
+    example.command += ` --params '${JSON.stringify(exampleParams)}'`;
+    return example;
+}
+/**
+ * A protocol type a `$ref` names, resolved against the domain it is used in.
+ *
+ * @param domainName - Domain of the parameter (for refs without a domain)
+ * @param ref - `$ref` value, e.g. 'CookieSameSite' or 'Runtime.RemoteObject'
+ * @returns Full type name and definition, or undefined when the schema lacks it
+ */
+function lookupRef(domainName, ref) {
+    const [refDomain, id] = ref.includes('.') ? ref.split('.') : [domainName, ref];
+    const type = refDomain && id ? findType(refDomain, id) : undefined;
+    return type && { name: `${refDomain}.${type.id}`, type };
+}
+/**
+ * Convert protocol parameter (or object property) to schema; a `$ref` gets its
+ * full type name and, for an enum type, its values.
+ *
+ * @param domainName - Domain the parameter belongs to
+ * @param param - Protocol parameter
+ * @returns Parameter schema
  */
-function paramToSchema(param) {
+function paramToSchema(domainName, param) {
     const schema = {
         name: param.name,
         type: resolveType(param),
         required: !param.optional,
     };
+    const referenced = param.$ref ? lookupRef(domainName, param.$ref) : undefined;
+    const values = param.enum ?? referenced?.type.enum;
     if (param.description)
         schema.description = param.description;
     if (param.deprecated)
         schema.deprecated = param.deprecated;
-    if (param.enum)
-        schema.enum = param.enum;
+    if (param.experimental)
+        schema.experimental = param.experimental;
+    if (values)
+        schema.enum = values;
+    if (referenced) {
+        schema.ref = referenced.name;
+        schema.refType = referenced.type.type;
+    }
     if (param.items)
         schema.items = resolveType(param.items);
     return schema;
 }
+/**
+ * Get structured schema for a protocol type.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @param typeName - Type id (case-insensitive)
+ * @returns Type schema or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * getTypeSchema('Network', 'CookieSameSite')?.enum; // ['Strict', 'Lax', 'None']
+ * ```
+ */
+export function getTypeSchema(domainName, typeName) {
+    const domain = findDomain(domainName);
+    const type = domain && findType(domain.domain, typeName);
+    if (!domain || !type)
+        return undefined;
+    const schema = {
+        name: `${domain.domain}.${type.id}`,
+        domain: domain.domain,
+        id: type.id,
+        baseType: type.type,
+    };
+    if (type.description)
+        schema.description = type.description;
+    if (type.experimental)
+        schema.experimental = type.experimental;
+    if (type.deprecated)
+        schema.deprecated = type.deprecated;
+    if (type.enum)
+        schema.enum = type.enum;
+    if (type.items)
+        schema.items = resolveType(type.items);
+    if (type.properties) {
+        schema.properties = type.properties.map((p) => paramToSchema(domain.domain, p));
+    }
+    return schema;
+}
 /**
  * Convert protocol return value to schema.
  */
@@ -120,7 +207,24 @@ function resolveType(typeRef) {
     return typeRef.type ?? 'any';
 }
 /**
- * Get example value for a parameter type.
+ * Example values for parameters whose name says what a realistic value is,
+ * where the type's placeholder would do something else (`width: 0` disables
+ * `Emulation.setDeviceMetricsOverride`, `url: "example"` is no URL).
+ */
+const EXAMPLE_VALUES = {
+    width: 1280,
+    height: 800,
+    x: 100,
+    y: 100,
+    deviceScaleFactor: 1,
+    scale: 1,
+    timeout: 5000,
+    responseCode: 200,
+    url: 'https://example.com',
+};
+/**
+ * Get example value for a parameter: a realistic value for its name, else
+ * one for its type (1 for numbers, so it never means "off").
  *
  * @param param - Parameter schema
  * @returns Example value
@@ -129,12 +233,17 @@ function getExampleValue(param) {
     if (param.enum && param.enum.length > 0) {
         return param.enum[0];
     }
-    switch (param.type) {
+    const type = param.refType ?? param.type;
+    const named = Object.hasOwn(EXAMPLE_VALUES, param.name) ? EXAMPLE_VALUES[param.name] : undefined;
+    const namedType = typeof named === 'number' ? ['integer', 'number'] : ['string'];
+    if (named !== undefined && namedType.includes(type))
+        return named;
+    switch (type) {
         case 'string':
             return 'example';
         case 'integer':
         case 'number':
-            return 0;
+            return 1;
         case 'boolean':
             return true;
         case 'array':

package/dist/cdp/types.d.ts

@@ -69,7 +69,7 @@ export interface Command {
     experimental?: boolean;
     /** Whether command is deprecated */
     deprecated?: boolean;
-    /** URL to specification */
+    /** Domain whose command of the same name implements this one (e.g. 'Overlay' for DOM.highlightNode) */
     redirect?: string;
 }
 /**
@@ -105,6 +105,8 @@ export interface Type {
     items?: TypeRef;
     /** Whether type is experimental */
     experimental?: boolean;
+    /** Whether type is deprecated */
+    deprecated?: boolean;
 }
 /**
  * CDP Domain (e.g., Network, Runtime, DOM).