browser-debugger-cli 0.6.5 → 0.6.7

package/dist/commands/dom/reactEventHelpers.js

@@ -18,9 +18,9 @@
  */
 export const REACT_FILL_SCRIPT = `
 (function(selector, value, options) {
-  const el = document.querySelector(selector);
+  const allMatches = document.querySelectorAll(selector);
   
-  if (!el) {
+  if (allMatches.length === 0) {
     return { 
       success: false, 
       error: 'Element not found',
@@ -28,6 +28,26 @@ export const REACT_FILL_SCRIPT = `
     };
   }
   
+  let el;
+  const index = options.index;
+  
+  // If index is provided, use it directly (1-based)
+  if (typeof index === 'number' && index > 0) {
+    if (index > allMatches.length) {
+      return {
+        success: false,
+        error: 'Index out of range',
+        selector: selector,
+        matchCount: allMatches.length,
+        requestedIndex: index,
+        suggestion: 'Use --index between 1 and ' + allMatches.length
+      };
+    }
+    el = allMatches[index - 1];
+  } else {
+    el = allMatches[0];
+  }
+  
   const tagName = el.tagName.toLowerCase();
   const inputType = el.type?.toLowerCase();
   
@@ -109,14 +129,15 @@ export const REACT_FILL_SCRIPT = `
  * JavaScript function to click an element.
  *
  * @remarks
- * Simple click implementation that works with buttons, links, and custom components.
- * When selector matches multiple elements, prioritizes visible ones.
+ * Handles both direct selector matching and indexed selection.
+ * When index is provided, selects the nth matching element (1-based).
+ * When selector matches multiple elements without index, prioritizes visible ones.
  */
 export const CLICK_ELEMENT_SCRIPT = `
-(function(selector) {
-  let el = document.querySelector(selector);
+(function(selector, index) {
+  const allMatches = document.querySelectorAll(selector);
   
-  if (!el) {
+  if (allMatches.length === 0) {
     return {
       success: false,
       error: 'Element not found',
@@ -124,8 +145,27 @@ export const CLICK_ELEMENT_SCRIPT = `
     };
   }
   
-  const allMatches = document.querySelectorAll(selector);
-  if (allMatches.length > 1) {
+  let el;
+  
+  // If index is provided, use it directly (1-based)
+  if (typeof index === 'number' && index > 0) {
+    if (index > allMatches.length) {
+      return {
+        success: false,
+        error: 'Index out of range',
+        selector: selector,
+        matchCount: allMatches.length,
+        requestedIndex: index,
+        suggestion: 'Use --index between 1 and ' + allMatches.length
+      };
+    }
+    el = allMatches[index - 1];
+  } else if (allMatches.length === 1) {
+    // Single match - use it directly
+    el = allMatches[0];
+  } else {
+    // Multiple matches without index - find first visible one
+    el = allMatches[0];
     for (const candidate of allMatches) {
       const style = window.getComputedStyle(candidate);
       const rect = candidate.getBoundingClientRect();
@@ -166,81 +206,34 @@ export const CLICK_ELEMENT_SCRIPT = `
     success: true,
     selector: selector,
     elementType: tagName,
-    clickable: isClickable
+    clickable: isClickable,
+    matchCount: allMatches.length,
+    selectedIndex: typeof index === 'number' ? index : undefined
   };
 })
 `;
 /**
- * JavaScript function to get multiple elements by selector.
+ * Type guard for FillResult.
  *
- * @remarks
- * Used when --index is specified to select from multiple matches.
+ * @param value - Value to check
+ * @returns True if value is a valid FillResult
  */
-export const GET_ELEMENT_BY_INDEX_SCRIPT = `
-(function(selector, index) {
-  const elements = document.querySelectorAll(selector);
-  
-  if (elements.length === 0) {
-    return {
-      success: false,
-      error: 'No elements found',
-      selector: selector,
-      matchCount: 0
-    };
-  }
-  
-  if (index < 1 || index > elements.length) {
-    return {
-      success: false,
-      error: 'Index out of range',
-      selector: selector,
-      matchCount: elements.length,
-      requestedIndex: index,
-      suggestion: \`Use --index between 1 and \${elements.length}\`
-    };
-  }
-  
-  const el = elements[index - 1]; // Convert to 0-based
-  
-  function buildUniquePath(element) {
-    if (element.id) {
-      return \`#\${CSS.escape(element.id)}\`;
-    }
-    
-    const path = [];
-    let current = element;
-    
-    while (current && current !== document.documentElement) {
-      let selector = current.tagName.toLowerCase();
-      
-      if (current.parentElement) {
-        const siblings = Array.from(current.parentElement.children);
-        const sameTagSiblings = siblings.filter(
-          (sibling) => sibling.tagName === current!.tagName
-        );
-        
-        if (sameTagSiblings.length > 1) {
-          const index = sameTagSiblings.indexOf(current) + 1;
-          selector += \`:nth-of-type(\${index})\`;
-        }
-      }
-      
-      path.unshift(selector);
-      current = current.parentElement;
-    }
-    
-    return 'html > ' + path.join(' > ');
-  }
-  
-  const uniqueSelector = buildUniquePath(el);
-  
-  return {
-    success: true,
-    selector: selector,
-    matchCount: elements.length,
-    selectedIndex: index,
-    uniqueSelector: uniqueSelector
-  };
-})
-`;
+export function isFillResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return typeof obj['success'] === 'boolean';
+}
+/**
+ * Type guard for ClickResult.
+ *
+ * @param value - Value to check
+ * @returns True if value is a valid ClickResult
+ */
+export function isClickResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    return typeof obj['success'] === 'boolean';
+}
 //# sourceMappingURL=reactEventHelpers.js.map

package/dist/commands/dom/reactEventHelpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactEventHelpers.js","sourceRoot":"","sources":["../../../src/commands/dom/reactEventHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwFhC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkE1C,CAAC"}
+{"version":3,"file":"reactEventHelpers.js","sourceRoot":"","sources":["../../../src/commands/dom/reactEventHelpers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4GhC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8EnC,CAAC;AAyCF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,OAAO,GAAG,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC;AAC7C,CAAC"}

package/dist/commands/helpJson.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Machine-readable help generation using Commander.js introspection API.
+ */
+import type { Command } from 'commander';
+import { type DecisionTree } from '../utils/decisionTrees.js';
+import { type TaskMapping } from '../utils/taskMappings.js';
+/**
+ * Option metadata for machine-readable help.
+ */
+export interface OptionMetadata {
+    /** Option flags (e.g., "-j, --json") */
+    flags: string;
+    /** Option description */
+    description: string;
+    /** Whether option is required */
+    required: boolean;
+    /** Whether option has an optional value */
+    optional: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Description of default value */
+    defaultValueDescription?: string;
+    /** Allowed choices if restricted */
+    choices?: readonly string[];
+}
+/**
+ * Argument metadata for machine-readable help.
+ */
+export interface ArgumentMetadata {
+    /** Argument name */
+    name: string;
+    /** Argument description */
+    description: string;
+    /** Whether argument is required */
+    required: boolean;
+    /** Whether argument accepts multiple values */
+    variadic: boolean;
+    /** Default value if any */
+    defaultValue?: unknown;
+    /** Allowed choices if restricted */
+    choices?: readonly string[];
+}
+/**
+ * Command metadata for machine-readable help.
+ */
+export interface CommandMetadata {
+    /** Command name */
+    name: string;
+    /** Command aliases */
+    aliases: readonly string[];
+    /** Command description */
+    description: string;
+    /** Command usage string */
+    usage: string;
+    /** Command arguments */
+    arguments: ArgumentMetadata[];
+    /** Command options */
+    options: OptionMetadata[];
+    /** Subcommands */
+    subcommands: CommandMetadata[];
+}
+/**
+ * Runtime state information for dynamic command availability.
+ */
+export interface RuntimeState {
+    /** Whether a session is currently active */
+    sessionActive: boolean;
+    /** Whether the daemon is running */
+    daemonRunning: boolean;
+    /** Commands available in current state */
+    availableCommands: string[];
+}
+/**
+ * Tool capabilities summary for agent discovery.
+ */
+export interface Capabilities {
+    /** CDP protocol capabilities */
+    cdp: {
+        /** Number of CDP domains */
+        domains: number;
+        /** Number of CDP methods (approximate) */
+        methods: string;
+    };
+    /** High-level command capabilities */
+    highLevel: {
+        /** List of high-level commands available */
+        commands: string[];
+        /** Domain coverage areas */
+        coverage: string[];
+    };
+}
+/**
+ * Root machine-readable help structure.
+ */
+export interface MachineReadableHelp {
+    /** CLI name */
+    name: string;
+    /** CLI version */
+    version: string;
+    /** CLI description */
+    description: string;
+    /** Root command metadata */
+    command: CommandMetadata;
+    /** Exit code documentation */
+    exitCodes: {
+        /** Exit code value */
+        code: number;
+        /** Exit code name */
+        name: string;
+        /** Exit code description */
+        description: string;
+    }[];
+    /** Task-to-command mappings with CDP alternatives */
+    taskMappings: Record<string, TaskMapping>;
+    /** Current runtime state */
+    runtimeState: RuntimeState;
+    /** Intent-based decision trees */
+    decisionTrees: Record<string, DecisionTree>;
+    /** Tool capabilities summary */
+    capabilities: Capabilities;
+}
+/**
+ * Generates machine-readable help from a Commander program.
+ *
+ * Includes comprehensive metadata for agent discovery:
+ * - Command structure and options
+ * - Exit codes with semantic meanings
+ * - Task-to-command mappings with CDP alternatives
+ * - Runtime state and command availability
+ * - Intent-based decision trees
+ * - Capabilities summary
+ *
+ * @param program - Commander program instance
+ * @returns Machine-readable help structure
+ *
+ * @example
+ * ```typescript
+ * import { program } from 'commander';
+ * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
+ *
+ * const help = generateMachineReadableHelp(program);
+ * console.log(JSON.stringify(help, null, 2));
+ * ```
+ */
+export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+/**
+ * Generates machine-readable help for a specific subcommand.
+ *
+ * Returns the same structure as generateMachineReadableHelp but with
+ * the command field focused on the requested subcommand. If the subcommand
+ * is not found, falls back to full root help.
+ *
+ * @param program - Root Commander program instance
+ * @param commandPath - Array of command names (e.g., ['dom', 'query'])
+ * @returns Machine-readable help structure for the subcommand
+ *
+ * @example
+ * ```typescript
+ * // Get help for 'bdg dom query'
+ * const help = generateSubcommandHelp(program, ['dom', 'query']);
+ * console.log(help.command.name); // 'query'
+ * ```
+ */
+export declare function generateSubcommandHelp(program: Command, commandPath: string[]): MachineReadableHelp;
+//# sourceMappingURL=helpJson.d.ts.map

package/dist/commands/helpJson.d.ts.map

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

package/dist/commands/helpJson.js

@@ -0,0 +1,252 @@
+/**
+ * Machine-readable help generation using Commander.js introspection API.
+ */
+import { getAllDomainSummaries } from '../cdp/schema.js';
+import { isDaemonRunning } from '../daemon/launcher.js';
+import { readPid } from '../session/pid.js';
+import { getAllDecisionTrees } from '../utils/decisionTrees.js';
+import { filterDefined } from '../utils/objects.js';
+import { isProcessAlive } from '../utils/process.js';
+import { getAllTaskMappings } from '../utils/taskMappings.js';
+/**
+ * Converts a Commander Option to OptionMetadata.
+ *
+ * @param option - Commander option instance
+ * @returns Option metadata
+ */
+function convertOption(option) {
+    return filterDefined({
+        flags: option.flags,
+        description: option.description,
+        required: option.required,
+        optional: option.optional,
+        defaultValue: option.defaultValue,
+        defaultValueDescription: option.defaultValueDescription,
+        choices: option.argChoices,
+    });
+}
+/**
+ * Converts a Commander Argument to ArgumentMetadata.
+ *
+ * @param argument - Commander argument instance
+ * @returns Argument metadata
+ */
+function convertArgument(argument) {
+    return filterDefined({
+        name: argument.name(),
+        description: argument.description,
+        required: argument.required,
+        variadic: argument.variadic,
+        defaultValue: argument.defaultValue,
+        choices: argument.argChoices,
+    });
+}
+/**
+ * Recursively converts a Commander Command to CommandMetadata.
+ *
+ * @param command - Commander command instance
+ * @returns Command metadata
+ */
+function convertCommand(command) {
+    return {
+        name: command.name(),
+        aliases: command.aliases(),
+        description: command.description(),
+        usage: command.usage(),
+        arguments: command.registeredArguments.map(convertArgument),
+        options: command.options.map(convertOption),
+        subcommands: command.commands.map(convertCommand),
+    };
+}
+/**
+ * Checks if a session is currently active.
+ *
+ * @returns True if session is active, false otherwise
+ */
+function isSessionActive() {
+    const sessionPid = readPid();
+    if (sessionPid === null) {
+        return false;
+    }
+    return isProcessAlive(sessionPid);
+}
+/**
+ * Generates runtime state information.
+ *
+ * Checks current daemon and session status to provide state-aware
+ * command availability information.
+ *
+ * @returns Runtime state object
+ */
+function generateRuntimeState() {
+    const daemonRunning = isDaemonRunning();
+    const sessionActive = isSessionActive();
+    const availableCommands = [];
+    if (!daemonRunning && !sessionActive) {
+        availableCommands.push('bdg <url>', 'cleanup', '--help', '--version');
+    }
+    else if (daemonRunning && sessionActive) {
+        availableCommands.push('peek', 'tail', 'details', 'dom', 'network', 'console', 'cdp', 'status', 'stop');
+    }
+    else if (daemonRunning && !sessionActive) {
+        availableCommands.push('bdg <url>', 'cleanup', 'status');
+    }
+    return {
+        sessionActive,
+        daemonRunning,
+        availableCommands,
+    };
+}
+/**
+ * Extracts unique command strings from task mappings.
+ *
+ * Flattens all command arrays from task mappings and deduplicates them.
+ *
+ * @param taskMappings - Task mapping registry
+ * @returns Sorted array of unique command strings
+ */
+function extractCommandList(taskMappings) {
+    const allCommands = Object.values(taskMappings).flatMap((mapping) => mapping.commands);
+    const uniqueCommands = [...new Set(allCommands)];
+    return uniqueCommands.sort();
+}
+/**
+ * Exit code documentation for machine-readable help.
+ */
+const EXIT_CODE_DOCS = [
+    { code: 0, name: 'SUCCESS', description: 'Operation completed successfully' },
+    { code: 1, name: 'GENERIC_FAILURE', description: 'Generic failure' },
+    { code: 80, name: 'INVALID_URL', description: 'Invalid URL format provided' },
+    { code: 81, name: 'INVALID_ARGUMENTS', description: 'Invalid command arguments' },
+    { code: 82, name: 'PERMISSION_DENIED', description: 'Insufficient permissions' },
+    { code: 83, name: 'RESOURCE_NOT_FOUND', description: 'Required resource not found' },
+    { code: 84, name: 'RESOURCE_BUSY', description: 'Resource is currently in use' },
+    {
+        code: 85,
+        name: 'OPERATION_NOT_PERMITTED',
+        description: 'Operation not permitted in current state',
+    },
+    { code: 86, name: 'DAEMON_ALREADY_RUNNING', description: 'Daemon is already running' },
+    { code: 100, name: 'CHROME_LAUNCH_FAILURE', description: 'Failed to launch Chrome browser' },
+    {
+        code: 101,
+        name: 'CDP_CONNECTION_FAILURE',
+        description: 'Failed to connect to Chrome DevTools Protocol',
+    },
+    { code: 102, name: 'CDP_TIMEOUT', description: 'CDP operation timed out' },
+    { code: 110, name: 'IPC_ERROR', description: 'Inter-process communication error' },
+];
+/**
+ * Generates capabilities summary.
+ *
+ * Dynamically calculates CDP and high-level command capabilities
+ * from protocol schema and task mappings.
+ *
+ * @returns Capabilities object
+ */
+function generateCapabilities() {
+    const domainSummaries = getAllDomainSummaries();
+    const taskMappings = getAllTaskMappings();
+    const totalMethods = domainSummaries.reduce((sum, domain) => sum + domain.commandCount, 0);
+    const commandList = extractCommandList(taskMappings);
+    return {
+        cdp: {
+            domains: domainSummaries.length,
+            methods: totalMethods.toString(),
+        },
+        highLevel: {
+            commands: commandList,
+            coverage: ['dom', 'network', 'console', 'session', 'monitoring'],
+        },
+    };
+}
+/**
+ * Generates machine-readable help from a Commander program.
+ *
+ * Includes comprehensive metadata for agent discovery:
+ * - Command structure and options
+ * - Exit codes with semantic meanings
+ * - Task-to-command mappings with CDP alternatives
+ * - Runtime state and command availability
+ * - Intent-based decision trees
+ * - Capabilities summary
+ *
+ * @param program - Commander program instance
+ * @returns Machine-readable help structure
+ *
+ * @example
+ * ```typescript
+ * import { program } from 'commander';
+ * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
+ *
+ * const help = generateMachineReadableHelp(program);
+ * console.log(JSON.stringify(help, null, 2));
+ * ```
+ */
+export function generateMachineReadableHelp(program) {
+    return {
+        name: program.name(),
+        version: program.version() ?? 'unknown',
+        description: program.description(),
+        command: convertCommand(program),
+        exitCodes: [...EXIT_CODE_DOCS],
+        taskMappings: getAllTaskMappings(),
+        runtimeState: generateRuntimeState(),
+        decisionTrees: getAllDecisionTrees(),
+        capabilities: generateCapabilities(),
+    };
+}
+/**
+ * Finds a subcommand by traversing the command path.
+ *
+ * @param program - Root Commander program instance
+ * @param commandPath - Array of command names to traverse (e.g., ['dom', 'query'])
+ * @returns The target Command if found, null otherwise
+ */
+function findSubcommand(program, commandPath) {
+    let current = program;
+    for (const name of commandPath) {
+        const found = current.commands.find((cmd) => cmd.name() === name || cmd.aliases().includes(name));
+        if (!found) {
+            return null;
+        }
+        current = found;
+    }
+    return current;
+}
+/**
+ * Generates machine-readable help for a specific subcommand.
+ *
+ * Returns the same structure as generateMachineReadableHelp but with
+ * the command field focused on the requested subcommand. If the subcommand
+ * is not found, falls back to full root help.
+ *
+ * @param program - Root Commander program instance
+ * @param commandPath - Array of command names (e.g., ['dom', 'query'])
+ * @returns Machine-readable help structure for the subcommand
+ *
+ * @example
+ * ```typescript
+ * // Get help for 'bdg dom query'
+ * const help = generateSubcommandHelp(program, ['dom', 'query']);
+ * console.log(help.command.name); // 'query'
+ * ```
+ */
+export function generateSubcommandHelp(program, commandPath) {
+    const targetCommand = findSubcommand(program, commandPath);
+    if (!targetCommand) {
+        return generateMachineReadableHelp(program);
+    }
+    return {
+        name: program.name(),
+        version: program.version() ?? 'unknown',
+        description: program.description(),
+        command: convertCommand(targetCommand),
+        exitCodes: [...EXIT_CODE_DOCS],
+        taskMappings: getAllTaskMappings(),
+        runtimeState: generateRuntimeState(),
+        decisionTrees: getAllDecisionTrees(),
+        capabilities: generateCapabilities(),
+    };
+}
+//# sourceMappingURL=helpJson.js.map

package/dist/commands/helpJson.js.map

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

package/dist/commands/machineReadableHelp.d.ts

@@ -83,8 +83,8 @@ export interface Capabilities {
     };
     /** High-level command capabilities */
     highLevel: {
-        /** Number of high-level commands */
-        commands: number;
+        /** List of high-level commands available */
+        commands: string[];
         /** Domain coverage areas */
         coverage: string[];
     };
@@ -143,4 +143,23 @@ export interface MachineReadableHelp {
  * ```
  */
 export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+/**
+ * Generates machine-readable help for a specific subcommand.
+ *
+ * Returns the same structure as generateMachineReadableHelp but with
+ * the command field focused on the requested subcommand. If the subcommand
+ * is not found, falls back to full root help.
+ *
+ * @param program - Root Commander program instance
+ * @param commandPath - Array of command names (e.g., ['dom', 'query'])
+ * @returns Machine-readable help structure for the subcommand
+ *
+ * @example
+ * ```typescript
+ * // Get help for 'bdg dom query'
+ * const help = generateSubcommandHelp(program, ['dom', 'query']);
+ * console.log(help.command.name); // 'query'
+ * ```
+ */
+export declare function generateSubcommandHelp(program: Command, commandPath: string[]): MachineReadableHelp;
 //# sourceMappingURL=machineReadableHelp.d.ts.map