browser-debugger-cli/dist/commands/helpJson.d.ts

DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.

/**
 * 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';
/**
 * Behavioral metadata for self-documenting options.
 *
 * Provides rich context for agents to understand option effects
 * without trial-and-error or source code inspection.
 */
export interface OptionBehavior {
    /** What happens by default when option is not specified */
    default?: string;
    /** What happens when option is enabled/specified */
    whenEnabled?: string;
    /** What happens when option is disabled (for --no-* flags) */
    whenDisabled?: string;
    /** Automatic behaviors that may override user intent */
    automaticBehavior?: string;
    /** Token cost implications for AI agents */
    tokenImpact?: string;
}
/**
 * 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[];
    /** Rich behavioral metadata for agent discovery */
    behavior?: OptionBehavior;
}
/**
 * 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