browser-debugger-cli 0.3.0 → 0.6.0

package/dist/__testutils__/testHome.js

@@ -0,0 +1,57 @@
+/**
+ * Ensure smoke/integration tests use a writable BDG session directory and HOME.
+ *
+ * Some CI/macOS environments block writing to ~/.bdg and ~/Library directly.
+ * We point bdg to a repo-local session directory via BDG_SESSION_DIR and also
+ * override HOME so Chrome's Crashpad can write to ~/Library/Application Support/...
+ * without hitting sandbox restrictions.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+let cachedSessionDir = null;
+let cachedHomeDir = null;
+/**
+ * Set BDG_SESSION_DIR to a deterministic path under the repo and make sure it
+ * exists on disk. Subsequent calls are cheap and return the same path.
+ *
+ * @returns Absolute path used as BDG session directory for tests
+ */
+export function ensureTestSessionDir() {
+    if (cachedSessionDir) {
+        return cachedSessionDir;
+    }
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(currentDir, '..', '..');
+    const fallbackDir = path.join(repoRoot, '.tmp', 'bdg-smoke-session');
+    const desiredDir = process.env['BDG_TEST_SESSION_DIR'] ?? fallbackDir;
+    fs.mkdirSync(desiredDir, { recursive: true });
+    process.env['BDG_SESSION_DIR'] = desiredDir;
+    cachedSessionDir = desiredDir;
+    return cachedSessionDir;
+}
+/**
+ * Get a writable HOME directory for tests that shields Chrome from sandbox restrictions.
+ *
+ * macOS workspace sandboxes block writes to ~/Library, causing Chrome's Crashpad to fail
+ * with EPERM errors. By overriding HOME to a repo-local directory, Chrome can safely
+ * write its crash handler settings without hitting the sandbox wall.
+ *
+ * @returns Absolute path to use as HOME for test processes
+ */
+export function getTestHomeDir() {
+    if (cachedHomeDir) {
+        return cachedHomeDir;
+    }
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const repoRoot = path.resolve(currentDir, '..', '..');
+    const fallbackDir = path.join(repoRoot, '.tmp', 'bdg-smoke-home');
+    const desiredDir = process.env['BDG_TEST_HOME_DIR'] ?? fallbackDir;
+    fs.mkdirSync(desiredDir, { recursive: true });
+    // Create Library/Application Support structure for Chrome's Crashpad
+    const libraryDir = path.join(desiredDir, 'Library', 'Application Support', 'Google', 'Chrome');
+    fs.mkdirSync(libraryDir, { recursive: true });
+    cachedHomeDir = desiredDir;
+    return cachedHomeDir;
+}
+//# sourceMappingURL=testHome.js.map

package/dist/__testutils__/testHome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testHome.js","sourceRoot":"","sources":["../../src/__testutils__/testHome.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAC3C,IAAI,aAAa,GAAkB,IAAI,CAAC;AAExC;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAErE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,IAAI,WAAW,CAAC;IACtE,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,GAAG,UAAU,CAAC;IAE5C,gBAAgB,GAAG,UAAU,CAAC;IAC9B,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,aAAa,EAAE,CAAC;QAClB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACtD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAElE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,WAAW,CAAC;IACnE,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,qEAAqE;IACrE,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,qBAAqB,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/F,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,aAAa,GAAG,UAAU,CAAC;IAC3B,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/__testutils__/testProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testProcess.d.ts","sourceRoot":"","sources":["../../src/__testutils__/testProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAwB1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}
+{"version":3,"file":"testProcess.d.ts","sourceRoot":"","sources":["../../src/__testutils__/testProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAkC1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC"}

package/dist/__testutils__/testProcess.js

@@ -37,9 +37,10 @@ export function mockProcessAlive(alivePids) {
     originalKill ??= process.kill.bind(process);
     const alivePidSet = new Set(alivePids);
     process.kill = ((pid, signal) => {
+        const normalizedPid = Math.abs(pid);
         // Signal 0 is used to check if process exists (doesn't actually send signal)
         if (signal === 0 || signal === undefined) {
-            if (alivePidSet.has(pid)) {
+            if (alivePidSet.has(normalizedPid)) {
                 // Process is alive - return true
                 return true;
             }
@@ -52,8 +53,15 @@ export function mockProcessAlive(alivePids) {
                 throw err;
             }
         }
-        // For other signals, delegate to original implementation
-        return originalKill(pid, signal);
+        if (!alivePidSet.has(normalizedPid)) {
+            const err = new Error(`kill ESRCH`);
+            err.code = 'ESRCH';
+            err.errno = -3;
+            err.syscall = 'kill';
+            throw err;
+        }
+        alivePidSet.delete(normalizedPid);
+        return true;
     });
 }
 /**

package/dist/__testutils__/testProcess.js.map

@@ -1 +1 @@
-{"version":3,"file":"testProcess.js","sourceRoot":"","sources":["../../src/__testutils__/testProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,IAAI,YAAY,GAA+B,IAAI,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAmB;IAClD,oFAAoF;IACpF,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAEvC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE;QAChE,6EAA6E;QAC7E,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,iCAAiC;gBACjC,OAAO,IAAI,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,+DAA+D;gBAC/D,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,YAAY,CAA0B,CAAC;gBAC7D,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC;gBACnB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACf,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC;gBACrB,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,yDAAyD;QACzD,OAAQ,YAAoC,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5D,CAAC,CAAwB,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC;QAC5B,YAAY,GAAG,IAAI,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,KAAK,IAAI,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"testProcess.js","sourceRoot":"","sources":["../../src/__testutils__/testProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,IAAI,YAAY,GAA+B,IAAI,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAmB;IAClD,oFAAoF;IACpF,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE5C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAEvC,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAAW,EAAE,MAAgC,EAAE,EAAE;QAChE,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpC,6EAA6E;QAC7E,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;gBACnC,iCAAiC;gBACjC,OAAO,IAAI,CAAC;YACd,CAAC;iBAAM,CAAC;gBACN,+DAA+D;gBAC/D,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,YAAY,CAA0B,CAAC;gBAC7D,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC;gBACnB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACf,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC;gBACrB,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,CAAC;YACpC,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,YAAY,CAA0B,CAAC;YAC7D,GAAG,CAAC,IAAI,GAAG,OAAO,CAAC;YACnB,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACf,GAAG,CAAC,OAAO,GAAG,MAAM,CAAC;YACrB,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,WAAW,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC,CAAwB,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;QAC1B,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC;QAC5B,YAAY,GAAG,IAAI,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,YAAY,KAAK,IAAI,CAAC;AAC/B,CAAC"}

package/dist/cdp/protocol.d.ts

@@ -0,0 +1,121 @@
+/**
+ * CDP Protocol Schema Loader
+ *
+ * Loads and parses the Chrome DevTools Protocol schema from the bundled
+ * devtools-protocol package. Provides utilities for domain/method lookup
+ * and introspection.
+ */
+import type { ProtocolSchema, Domain, Command } from './types.js';
+/**
+ * Load the CDP protocol schema.
+ *
+ * Merges browser_protocol.json and js_protocol.json from devtools-protocol package.
+ * The browser protocol contains domains like Network, Page, DOM, etc.
+ * The JS protocol contains Runtime, Debugger, Console, Profiler, etc.
+ * The merged protocol is cached after first load for performance.
+ *
+ * @returns CDP protocol schema with all domains, commands, and types
+ *
+ * @example
+ * ```typescript
+ * const protocol = loadProtocol();
+ * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
+ * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * ```
+ */
+export declare function loadProtocol(): ProtocolSchema;
+/**
+ * Get all domain names from the protocol.
+ *
+ * @returns Array of domain names (e.g., ['Accessibility', 'Network', 'Runtime'])
+ *
+ * @example
+ * ```typescript
+ * const domains = getDomains();
+ * console.log(domains); // ['Accessibility', 'Animation', 'Network', ...]
+ * ```
+ */
+export declare function getDomains(): string[];
+/**
+ * Find a domain by name (case-insensitive).
+ *
+ * @param domainName - Domain name to find (e.g., 'network', 'Network', 'NETWORK')
+ * @returns Domain object or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const domain = findDomain('network');  // Case-insensitive
+ * console.log(domain?.domain); // 'Network'
+ * console.log(domain?.commands.length); // 39
+ * ```
+ */
+export declare function findDomain(domainName: string): Domain | undefined;
+/**
+ * Find a command within a domain (case-insensitive).
+ *
+ * @param domainName - Domain name (e.g., 'Network')
+ * @param commandName - Command name (e.g., 'getCookies', 'GETCOOKIES')
+ * @returns Command object or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const cmd = findCommand('Network', 'getcookies');  // Case-insensitive
+ * console.log(cmd?.name); // 'getCookies'
+ * console.log(cmd?.parameters); // [...]
+ * ```
+ */
+export declare function findCommand(domainName: string, commandName: string): Command | undefined;
+/**
+ * Normalize a CDP method name to proper casing.
+ *
+ * Converts user input (any case) to CDP's actual method name.
+ *
+ * @param input - Method name in any format (e.g., 'network.getcookies', 'Runtime.Evaluate')
+ * @returns Normalized method name (e.g., 'Network.getCookies') or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * normalizeMethod('network.getcookies') // 'Network.getCookies'
+ * normalizeMethod('runtime.evaluate')   // 'Runtime.evaluate'
+ * normalizeMethod('NETWORK.GETCOOKIES') // 'Network.getCookies'
+ * normalizeMethod('invalid.method')     // undefined
+ * ```
+ */
+export declare function normalizeMethod(input: string): string | undefined;
+/**
+ * Get all commands for a domain.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @returns Array of command names or empty array if domain not found
+ *
+ * @example
+ * ```typescript
+ * const commands = getCommandsForDomain('Network');
+ * console.log(commands); // ['getCookies', 'setCookie', 'enable', ...]
+ * ```
+ */
+export declare function getCommandsForDomain(domainName: string): string[];
+/**
+ * Format command signature for help text.
+ *
+ * @param domainName - Domain name
+ * @param commandName - Command name
+ * @returns Formatted signature string or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const sig = formatCommandSignature('Network', 'getCookies');
+ * console.log(sig);
+ * // Network.getCookies
+ * //
+ * // Returns all browser cookies for the current URL.
+ * //
+ * // Parameters:
+ * //   --urls <array> (optional) - The list of URLs for which to fetch cookies
+ * //
+ * // Returns:
+ * //   cookies: Array of Cookie objects
+ * ```
+ */
+export declare function formatCommandSignature(domainName: string, commandName: string): string | undefined;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/cdp/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/cdp/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAa,MAAM,YAAY,CAAC;AAQ7E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,IAAI,cAAc,CA2B7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAGrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAQxF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiBjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAMjE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CA4CpB"}

package/dist/cdp/protocol.js

@@ -0,0 +1,215 @@
+/**
+ * CDP Protocol Schema Loader
+ *
+ * Loads and parses the Chrome DevTools Protocol schema from the bundled
+ * devtools-protocol package. Provides utilities for domain/method lookup
+ * and introspection.
+ */
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Cache the protocol to avoid re-reading the file
+let cachedProtocol = null;
+/**
+ * Load the CDP protocol schema.
+ *
+ * Merges browser_protocol.json and js_protocol.json from devtools-protocol package.
+ * The browser protocol contains domains like Network, Page, DOM, etc.
+ * The JS protocol contains Runtime, Debugger, Console, Profiler, etc.
+ * The merged protocol is cached after first load for performance.
+ *
+ * @returns CDP protocol schema with all domains, commands, and types
+ *
+ * @example
+ * ```typescript
+ * const protocol = loadProtocol();
+ * console.log(`Protocol version: ${protocol.version.major}.${protocol.version.minor}`);
+ * console.log(`Domains: ${protocol.domains.length}`); // ~53 domains (47 browser + 6 JS)
+ * ```
+ */
+export function loadProtocol() {
+    if (cachedProtocol) {
+        return cachedProtocol;
+    }
+    // Find the protocol files in node_modules
+    // When compiled, __dirname is dist/cdp, so go up to project root
+    const browserProtocolPath = join(__dirname, '../../node_modules/devtools-protocol/json/browser_protocol.json');
+    const jsProtocolPath = join(__dirname, '../../node_modules/devtools-protocol/json/js_protocol.json');
+    const browserProtocol = JSON.parse(readFileSync(browserProtocolPath, 'utf-8'));
+    const jsProtocol = JSON.parse(readFileSync(jsProtocolPath, 'utf-8'));
+    // Merge the two protocols
+    // Use browser protocol as base, add JS protocol domains
+    cachedProtocol = {
+        version: browserProtocol.version,
+        domains: [...browserProtocol.domains, ...jsProtocol.domains],
+    };
+    return cachedProtocol;
+}
+/**
+ * Get all domain names from the protocol.
+ *
+ * @returns Array of domain names (e.g., ['Accessibility', 'Network', 'Runtime'])
+ *
+ * @example
+ * ```typescript
+ * const domains = getDomains();
+ * console.log(domains); // ['Accessibility', 'Animation', 'Network', ...]
+ * ```
+ */
+export function getDomains() {
+    const protocol = loadProtocol();
+    return protocol.domains.map((d) => d.domain);
+}
+/**
+ * Find a domain by name (case-insensitive).
+ *
+ * @param domainName - Domain name to find (e.g., 'network', 'Network', 'NETWORK')
+ * @returns Domain object or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const domain = findDomain('network');  // Case-insensitive
+ * console.log(domain?.domain); // 'Network'
+ * console.log(domain?.commands.length); // 39
+ * ```
+ */
+export function findDomain(domainName) {
+    const protocol = loadProtocol();
+    const normalized = domainName.toLowerCase();
+    return protocol.domains.find((d) => d.domain.toLowerCase() === normalized);
+}
+/**
+ * Find a command within a domain (case-insensitive).
+ *
+ * @param domainName - Domain name (e.g., 'Network')
+ * @param commandName - Command name (e.g., 'getCookies', 'GETCOOKIES')
+ * @returns Command object or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const cmd = findCommand('Network', 'getcookies');  // Case-insensitive
+ * console.log(cmd?.name); // 'getCookies'
+ * console.log(cmd?.parameters); // [...]
+ * ```
+ */
+export function findCommand(domainName, commandName) {
+    const domain = findDomain(domainName);
+    if (!domain?.commands) {
+        return undefined;
+    }
+    const normalized = commandName.toLowerCase();
+    return domain.commands.find((c) => c.name.toLowerCase() === normalized);
+}
+/**
+ * Normalize a CDP method name to proper casing.
+ *
+ * Converts user input (any case) to CDP's actual method name.
+ *
+ * @param input - Method name in any format (e.g., 'network.getcookies', 'Runtime.Evaluate')
+ * @returns Normalized method name (e.g., 'Network.getCookies') or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * normalizeMethod('network.getcookies') // 'Network.getCookies'
+ * normalizeMethod('runtime.evaluate')   // 'Runtime.evaluate'
+ * normalizeMethod('NETWORK.GETCOOKIES') // 'Network.getCookies'
+ * normalizeMethod('invalid.method')     // undefined
+ * ```
+ */
+export function normalizeMethod(input) {
+    const [domainName, commandName] = input.split('.');
+    if (!domainName || !commandName) {
+        return undefined;
+    }
+    const domain = findDomain(domainName);
+    if (!domain) {
+        return undefined;
+    }
+    const command = findCommand(domain.domain, commandName);
+    if (!command) {
+        return undefined;
+    }
+    return `${domain.domain}.${command.name}`;
+}
+/**
+ * Get all commands for a domain.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @returns Array of command names or empty array if domain not found
+ *
+ * @example
+ * ```typescript
+ * const commands = getCommandsForDomain('Network');
+ * console.log(commands); // ['getCookies', 'setCookie', 'enable', ...]
+ * ```
+ */
+export function getCommandsForDomain(domainName) {
+    const domain = findDomain(domainName);
+    if (!domain?.commands) {
+        return [];
+    }
+    return domain.commands.map((c) => c.name);
+}
+/**
+ * Format command signature for help text.
+ *
+ * @param domainName - Domain name
+ * @param commandName - Command name
+ * @returns Formatted signature string or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const sig = formatCommandSignature('Network', 'getCookies');
+ * console.log(sig);
+ * // Network.getCookies
+ * //
+ * // Returns all browser cookies for the current URL.
+ * //
+ * // Parameters:
+ * //   --urls <array> (optional) - The list of URLs for which to fetch cookies
+ * //
+ * // Returns:
+ * //   cookies: Array of Cookie objects
+ * ```
+ */
+export function formatCommandSignature(domainName, commandName) {
+    const domain = findDomain(domainName);
+    if (!domain) {
+        return undefined;
+    }
+    const command = findCommand(domain.domain, commandName);
+    if (!command) {
+        return undefined;
+    }
+    const lines = [];
+    // Method name
+    lines.push(`${domain.domain}.${command.name}`);
+    lines.push('');
+    // Description
+    if (command.description) {
+        lines.push(command.description);
+        lines.push('');
+    }
+    // Parameters
+    if (command.parameters && command.parameters.length > 0) {
+        lines.push('Parameters:');
+        command.parameters.forEach((param) => {
+            const optional = param.optional ? ' (optional)' : '';
+            const desc = param.description ? ` - ${param.description}` : '';
+            lines.push(`  --${param.name} <${param.type}>${optional}${desc}`);
+        });
+        lines.push('');
+    }
+    // Returns
+    if (command.returns && command.returns.length > 0) {
+        lines.push('Returns:');
+        command.returns.forEach((ret) => {
+            const desc = ret.description ? ` - ${ret.description}` : '';
+            lines.push(`  ${ret.name}: ${ret.type ?? ret.$ref}${desc}`);
+        });
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=protocol.js.map

package/dist/cdp/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/cdp/protocol.ts"],"names":[],"mappings":"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"}

package/dist/cdp/schema.d.ts

@@ -0,0 +1,159 @@
+/**
+ * CDP Schema Introspection
+ *
+ * Provides structured, agent-friendly schema information for all CDP domains and methods.
+ * Follows principles from docs/AGENT_FRIENDLY_TOOLS.md:
+ * - Machine-readable output (JSON schema)
+ * - Self-describing tools
+ * - Structured context without verbosity
+ */
+/**
+ * Structured method schema for agent consumption.
+ */
+export interface MethodSchema {
+    /** Full method name (Domain.method) */
+    name: string;
+    /** Domain name */
+    domain: string;
+    /** Method name */
+    method: string;
+    /** Human-readable description */
+    description?: string;
+    /** Whether method is experimental */
+    experimental?: boolean;
+    /** Whether method is deprecated */
+    deprecated?: boolean;
+    /** Parameter schema */
+    parameters: ParameterSchema[];
+    /** Return value schema */
+    returns: ReturnSchema[];
+    /** Usage example (JSON) */
+    example?: {
+        command: string;
+        params?: Record<string, unknown>;
+    };
+}
+/**
+ * Parameter schema for agent consumption.
+ */
+export interface ParameterSchema {
+    /** Parameter name */
+    name: string;
+    /** Type (string, integer, boolean, array, object, or custom type reference) */
+    type: string;
+    /** Whether parameter is required */
+    required: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Enum values (if type is enum) */
+    enum?: string[];
+    /** Array item type (if type is array) */
+    items?: string;
+    /** Deprecated flag */
+    deprecated?: boolean;
+}
+/**
+ * Return value schema for agent consumption.
+ */
+export interface ReturnSchema {
+    /** Return value name */
+    name: string;
+    /** Type (string, integer, boolean, array, object, or custom type reference) */
+    type: string;
+    /** Whether return value is optional */
+    optional: boolean;
+    /** Human-readable description */
+    description?: string;
+    /** Array item type (if type is array) */
+    items?: string;
+}
+/**
+ * Domain summary for agent consumption.
+ */
+export interface DomainSummary {
+    /** Domain name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Number of commands in this domain */
+    commandCount: number;
+    /** Number of events in this domain */
+    eventCount: number;
+    /** Whether domain is experimental */
+    experimental?: boolean;
+    /** Whether domain is deprecated */
+    deprecated?: boolean;
+    /** Domain dependencies */
+    dependencies?: string[];
+}
+/**
+ * Get structured schema for a specific method.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @param methodName - Method name (case-insensitive)
+ * @returns Method schema or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const schema = getMethodSchema('Network', 'getCookies');
+ * console.log(schema.parameters); // [{ name: 'urls', type: 'array', required: false, ... }]
+ * ```
+ */
+export declare function getMethodSchema(domainName: string, methodName: string): MethodSchema | undefined;
+/**
+ * Get all methods in a domain.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @returns Array of method schemas
+ *
+ * @example
+ * ```typescript
+ * const methods = getDomainMethods('Network');
+ * console.log(methods.length); // 39
+ * console.log(methods[0].name); // 'Network.getIPProtectionProxyStatus'
+ * ```
+ */
+export declare function getDomainMethods(domainName: string): MethodSchema[];
+/**
+ * Get summary information for a domain.
+ *
+ * @param domainName - Domain name (case-insensitive)
+ * @returns Domain summary or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const summary = getDomainSummary('Network');
+ * console.log(summary.commandCount); // 39
+ * console.log(summary.eventCount); // 12
+ * ```
+ */
+export declare function getDomainSummary(domainName: string): DomainSummary | undefined;
+/**
+ * Get summaries for all domains.
+ *
+ * @returns Array of domain summaries
+ *
+ * @example
+ * ```typescript
+ * const summaries = getAllDomainSummaries();
+ * console.log(summaries.length); // 53
+ * console.log(summaries.find(d => d.name === 'Network').commandCount); // 39
+ * ```
+ */
+export declare function getAllDomainSummaries(): DomainSummary[];
+/**
+ * Search methods by keyword (case-insensitive).
+ *
+ * Searches in method names and descriptions.
+ *
+ * @param query - Search query
+ * @returns Array of matching method schemas
+ *
+ * @example
+ * ```typescript
+ * const cookies = searchMethods('cookie');
+ * // Returns: Network.getCookies, Network.setCookie, Network.deleteCookies, etc.
+ * ```
+ */
+export declare function searchMethods(query: string): MethodSchema[];
+//# sourceMappingURL=schema.d.ts.map

package/dist/cdp/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/cdp/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uBAAuB;IACvB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,0BAA0B;IAC1B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,2BAA2B;IAC3B,OAAO,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAClC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mCAAmC;IACnC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAYhG;AA0HD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,EAAE,CAOnE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAO9E;AAoBD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,EAAE,CAGvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAmB3D"}