chrome-cdp-cli 1.9.0 → 2.0.0

package/README.md

@@ -2,6 +2,19 @@
 
 A command-line tool for browser automation via Chrome DevTools Protocol (CDP). Designed for developers who need reliable, scriptable browser control with both dedicated commands and flexible JavaScript execution.
 
+## 🚀 Enhanced CLI Features
+
+**New in v2.0:** The CLI now includes a comprehensive refactored parameter system with:
+
+- 🔧 **Advanced Configuration Management**: YAML/JSON config files with profiles and precedence handling
+- ⚙️ **Enhanced Argument Parser**: Consistent option handling with validation and schema support  
+- 📚 **Comprehensive Help System**: Contextual help, advanced topics, and detailed examples
+- 🎯 **Standardized Output**: JSON/text formats with quiet/verbose modes and custom templates
+- 🔗 **Command Aliasing**: Built-in and custom aliases for efficient workflows
+- 🧩 **Plugin Architecture**: Extensible system for custom commands and functionality
+- 🖥️ **Interactive Mode**: Command prompt with tab completion and session management
+- ⚡ **Performance Optimizations**: Configuration caching and connection reuse
+
 ## 🤔 Why This Tool Exists
 
 **The honest story:** I started using `chrome-devtools-mcp` like everyone else. It worked great... until it didn't. One day it just stopped working - Cursor showed 26 tools available, everything looked normal, but every single tool call threw errors. Classic black box problem: you can't debug what you can't see inside.
@@ -882,27 +895,103 @@ For detailed documentation, see the [Form Filling Guide](docs/FORM_FILLING.md).
 
 ## Configuration
 
-### Configuration File
+The CLI supports comprehensive configuration management with multiple sources and precedence handling.
+
+### Quick Configuration
+
+Create a `.chrome-cdp-cli.yaml` file in your project root or home directory:
+
+```yaml
+# Basic configuration
+host: localhost
+port: 9222
+timeout: 30000
+outputFormat: text
+verbose: false
+
+# Profiles for different environments
+profiles:
+  development:
+    debug: true
+    verbose: true
+  production:
+    quiet: true
+    outputFormat: json
+
+# Command aliases
+aliases:
+  ss: screenshot
+  js: eval
+  health: eval "document.readyState === 'complete'"
+
+# Command-specific defaults
+commands:
+  screenshot:
+    defaults:
+      format: png
+      quality: 90
+```
 
-Create a `.chrome-cdp-cli.json` file in your project root or home directory:
+### Environment Variables
 
-```json
-{
-  "host": "localhost",
-  "port": 9222,
-  "timeout": 30000,
-  "outputFormat": "text",
-  "verbose": false,
-  "quiet": false
-}
+```bash
+export CHROME_CDP_CLI_HOST=localhost
+export CHROME_CDP_CLI_PORT=9222
+export CHROME_CDP_CLI_TIMEOUT=30000
+export CHROME_CDP_CLI_VERBOSE=true
+export CHROME_CDP_CLI_PROFILE=development
 ```
 
-### Environment Variables
+### Configuration Precedence
+
+Configuration values are resolved in order (highest to lowest priority):
+1. **Command-line arguments** (highest)
+2. **Environment variables**
+3. **Configuration files** (profile-specific, then default)
+4. **Default values** (lowest)
+
+### Advanced Configuration
+
+For comprehensive configuration options, see the [Configuration Guide](docs/CONFIGURATION.md).
+
+## Enhanced Help System
+
+The CLI includes a comprehensive help system with contextual assistance:
+
+```bash
+# General help with categorized commands
+chrome-cdp-cli help
+
+# Command-specific help with examples
+chrome-cdp-cli help eval
+chrome-cdp-cli help screenshot
+
+# Advanced help topics
+chrome-cdp-cli help topic configuration
+chrome-cdp-cli help topic selectors
+chrome-cdp-cli help topic automation
+chrome-cdp-cli help topic debugging
+
+# Contextual help (shown automatically on errors)
+chrome-cdp-cli click "#nonexistent"  # Shows selector help
+```
+
+## Plugin System
+
+Extend the CLI with custom commands and functionality:
+
+```bash
+# Install plugins
+npm install -g chrome-cdp-cli-plugin-form-automation
+
+# Load plugins from directory
+chrome-cdp-cli --plugin-dir ./plugins custom-command
+
+# List available plugins
+chrome-cdp-cli --show-plugins
+```
 
-- `CHROME_CLI_HOST`: Default Chrome host
-- `CHROME_CLI_PORT`: Default DevTools port
-- `CHROME_CLI_TIMEOUT`: Default command timeout
-- `CHROME_CLI_FORMAT`: Default output format
+For plugin development, see the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md).
 
 ## Development
 

package/dist/cli/ArgumentParser.js

@@ -0,0 +1,506 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArgumentParser = void 0;
+const HelpSystem_1 = require("./HelpSystem");
+class ArgumentParser {
+    constructor() {
+        this.commands = new Map();
+        this.aliases = new Map();
+        this.helpSystem = new HelpSystem_1.HelpSystem(undefined, this);
+    }
+    parseArguments(argv) {
+        try {
+            if (!Array.isArray(argv)) {
+                return this.createParseResult('help', {}, [], true);
+            }
+            const sliceStart = Math.max(0, Math.min(2, argv.length));
+            const args = argv.slice(sliceStart);
+            if (args.length === 0) {
+                return this.createParseResult('help', {}, [], true);
+            }
+            if (args.includes('--help')) {
+                return this.createParseResult('help', {}, [], true);
+            }
+            if (args.includes('--version') || args.includes('-V')) {
+                return this.createParseResult('version', {}, [], true);
+            }
+            let globalOptions;
+            let commandName;
+            let commandArgs;
+            try {
+                const parseResult = this.parseGlobalAndCommand(args);
+                globalOptions = parseResult.globalOptions;
+                commandName = parseResult.commandName;
+                commandArgs = parseResult.commandArgs;
+            }
+            catch (parseError) {
+                if (args.some(arg => arg === '--help' || arg === 'help')) {
+                    return this.createParseResult('help', {}, [], true);
+                }
+                throw parseError;
+            }
+            const resolvedCommand = this.resolveCommandName(commandName);
+            if (resolvedCommand === 'help') {
+                return this.createParseResult(resolvedCommand, globalOptions, [], true, commandArgs);
+            }
+            const commandDef = this.commands.get(resolvedCommand);
+            if (!commandDef) {
+                return this.createParseResult(resolvedCommand, globalOptions, [`Unknown command: ${commandName}. Use 'help' to see available commands.`], false);
+            }
+            const parseResult = this.parseCommandArguments(commandDef, commandArgs);
+            const allOptions = { ...globalOptions, ...parseResult.options };
+            return this.createParseResult(resolvedCommand, allOptions, parseResult.errors, parseResult.errors.length === 0, parseResult.arguments);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (process.env.DEBUG) {
+                console.error('Parse error details:', error);
+                if (error instanceof Error && error.stack) {
+                    console.error('Stack trace:', error.stack);
+                }
+            }
+            if (errorMessage.includes('Invalid count value')) {
+                return this.createParseResult('help', {}, [`Parse error: Invalid argument format. Please check your command syntax.`], false);
+            }
+            return this.createParseResult('help', {}, [`Parse error: ${errorMessage}`], false);
+        }
+    }
+    registerCommand(command) {
+        const validation = this.validateCommandDefinition(command);
+        if (!validation.valid) {
+            throw new Error(`Invalid command definition: ${validation.errors.join(', ')}`);
+        }
+        this.commands.set(command.name, command);
+        for (const alias of command.aliases) {
+            if (this.aliases.has(alias)) {
+                throw new Error(`Alias '${alias}' is already registered for command '${this.aliases.get(alias)}'`);
+            }
+            this.aliases.set(alias, command.name);
+        }
+    }
+    generateHelp(command) {
+        if (command) {
+            if (command.startsWith('topic ')) {
+                const topicName = command.substring(6);
+                return this.helpSystem.generateTopicHelp(topicName);
+            }
+            return this.helpSystem.generateCommandHelp(command);
+        }
+        return this.helpSystem.generateGeneralHelp();
+    }
+    validateArguments(command, args) {
+        const commandDef = this.commands.get(command);
+        if (!commandDef) {
+            return {
+                valid: false,
+                errors: [`Unknown command: ${command}`],
+                warnings: []
+            };
+        }
+        const errors = [];
+        const warnings = [];
+        for (const option of commandDef.options) {
+            if (option.required && !(option.name in args.options)) {
+                errors.push(`Required option --${option.name} is missing`);
+            }
+        }
+        const requiredArgs = commandDef.arguments.filter(arg => arg.required);
+        if (args.arguments.length < requiredArgs.length) {
+            const providedCount = Math.max(0, Math.min(args.arguments.length, requiredArgs.length));
+            const missingCount = Math.max(0, requiredArgs.length - providedCount);
+            if (missingCount > 0) {
+                const startIndex = Math.max(0, providedCount);
+                const endIndex = Math.min(requiredArgs.length, startIndex + missingCount);
+                if (startIndex < endIndex && startIndex >= 0 && endIndex <= requiredArgs.length) {
+                    const missingArgs = requiredArgs.slice(startIndex, endIndex).map(arg => arg.name);
+                    if (missingArgs.length > 0) {
+                        errors.push(`Missing required arguments: ${missingArgs.join(', ')}`);
+                    }
+                }
+            }
+        }
+        for (const [optionName, value] of Object.entries(args.options)) {
+            const optionDef = commandDef.options.find(opt => opt.name === optionName);
+            if (optionDef) {
+                const optionValidation = this.validateOptionValue(optionDef, value);
+                if (!optionValidation.valid) {
+                    errors.push(...optionValidation.errors);
+                }
+                warnings.push(...optionValidation.warnings);
+            }
+        }
+        for (let i = 0; i < args.arguments.length; i++) {
+            const argDef = commandDef.arguments[i];
+            if (argDef) {
+                const argValidation = this.validateArgumentValue(argDef, args.arguments[i]);
+                if (!argValidation.valid) {
+                    errors.push(...argValidation.errors);
+                }
+                warnings.push(...argValidation.warnings);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    parseGlobalAndCommand(args) {
+        if (args.includes('--help')) {
+            return { globalOptions: {}, commandName: 'help', commandArgs: [] };
+        }
+        const globalOptions = {};
+        let commandName = 'help';
+        let commandArgs = [];
+        let i = 0;
+        const globalOptionDefs = [
+            { name: 'host', short: 'h', type: 'string', description: 'Chrome host address', default: 'localhost' },
+            { name: 'port', short: 'p', type: 'number', description: 'DevTools port', default: 9222 },
+            { name: 'format', short: 'f', type: 'string', description: 'Output format', choices: ['json', 'text'], default: 'text' },
+            { name: 'verbose', short: 'v', type: 'boolean', description: 'Enable verbose logging', default: false },
+            { name: 'quiet', short: 'q', type: 'boolean', description: 'Enable quiet mode', default: false },
+            { name: 'timeout', short: 't', type: 'number', description: 'Command timeout in milliseconds', default: 30000 },
+            { name: 'debug', short: 'd', type: 'boolean', description: 'Enable debug logging', default: false },
+            { name: 'config', short: 'c', type: 'string', description: 'Configuration file path' }
+        ];
+        while (i < args.length) {
+            const arg = args[i];
+            if (arg.startsWith('--')) {
+                const { option, value, consumed } = this.parseLongOption(arg, args, i, globalOptionDefs);
+                if (option) {
+                    globalOptions[option.name] = value;
+                    const validConsumed = Math.max(1, Math.min(consumed, 2));
+                    i += validConsumed;
+                }
+                else {
+                    commandName = arg.substring(2);
+                    const nextIndex = i + 1;
+                    if (nextIndex >= 0 && nextIndex <= args.length) {
+                        commandArgs = args.slice(nextIndex);
+                    }
+                    else {
+                        commandArgs = [];
+                    }
+                    break;
+                }
+            }
+            else if (arg.startsWith('-') && arg.length > 1) {
+                const { option, value, consumed } = this.parseShortOption(arg, args, i, globalOptionDefs);
+                if (option) {
+                    globalOptions[option.name] = value;
+                    const validConsumed = Math.max(1, Math.min(consumed || 1, 2));
+                    i += validConsumed;
+                }
+                else {
+                    commandName = arg.substring(1);
+                    const nextIndex = i + 1;
+                    if (nextIndex >= 0 && nextIndex <= args.length) {
+                        commandArgs = args.slice(nextIndex);
+                    }
+                    else {
+                        commandArgs = [];
+                    }
+                    break;
+                }
+            }
+            else {
+                commandName = arg;
+                const nextIndex = i + 1;
+                if (nextIndex >= 0 && nextIndex <= args.length) {
+                    commandArgs = args.slice(nextIndex);
+                }
+                else {
+                    commandArgs = [];
+                }
+                break;
+            }
+        }
+        return { globalOptions, commandName, commandArgs };
+    }
+    parseLongOption(arg, args, index, optionDefs) {
+        let optionName = arg.substring(2);
+        let value;
+        let consumed = 1;
+        const equalIndex = optionName.indexOf('=');
+        if (equalIndex !== -1) {
+            value = optionName.substring(equalIndex + 1);
+            optionName = optionName.substring(0, equalIndex);
+        }
+        let isNegated = false;
+        if (optionName.startsWith('no-')) {
+            isNegated = true;
+            optionName = optionName.substring(3);
+        }
+        const optionDef = optionDefs.find(opt => opt.name === optionName);
+        if (!optionDef) {
+            return { option: null, value: null, consumed: 0 };
+        }
+        if (optionDef.type === 'boolean') {
+            value = !isNegated;
+        }
+        else if (value === undefined) {
+            if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+                value = args[index + 1];
+                consumed = 2;
+            }
+            else {
+                throw new Error(`Option --${optionName} requires a value`);
+            }
+        }
+        value = this.convertOptionValue(optionDef, value);
+        return { option: optionDef, value, consumed };
+    }
+    parseShortOption(arg, args, index, optionDefs) {
+        const shortName = arg.substring(1);
+        if (shortName.length > 1) {
+            return { option: null, value: null, consumed: 0 };
+        }
+        const optionDef = optionDefs.find(opt => opt.short === shortName);
+        if (!optionDef) {
+            return { option: null, value: null, consumed: 0 };
+        }
+        let value;
+        let consumed = 1;
+        if (optionDef.type === 'boolean') {
+            value = true;
+        }
+        else {
+            if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+                value = args[index + 1];
+                consumed = 2;
+            }
+            else {
+                throw new Error(`Option -${shortName} requires a value`);
+            }
+        }
+        try {
+            value = this.convertOptionValue(optionDef, value);
+        }
+        catch (error) {
+            throw new Error(`Invalid value for option -${shortName}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (consumed < 1 || consumed > 2) {
+            consumed = 1;
+        }
+        return { option: optionDef, value, consumed };
+    }
+    parseCommandArguments(commandDef, args) {
+        const options = {};
+        const arguments_ = [];
+        const errors = [];
+        let i = 0;
+        while (i < args.length) {
+            const arg = args[i];
+            if (arg.startsWith('--')) {
+                try {
+                    const { option, value, consumed } = this.parseLongOption(arg, args, i, commandDef.options);
+                    if (option) {
+                        options[option.name] = value;
+                        if (consumed > 0) {
+                            i += consumed;
+                        }
+                        else {
+                            i++;
+                        }
+                    }
+                    else {
+                        errors.push(`Unknown option: ${arg}`);
+                        i++;
+                    }
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error.message : String(error));
+                    i++;
+                }
+            }
+            else if (arg.startsWith('-') && arg.length > 1) {
+                try {
+                    const { option, value, consumed } = this.parseShortOption(arg, args, i, commandDef.options);
+                    if (option) {
+                        options[option.name] = value;
+                        if (consumed > 0) {
+                            i += consumed;
+                        }
+                        else {
+                            i++;
+                        }
+                    }
+                    else {
+                        errors.push(`Unknown option: ${arg}`);
+                        i++;
+                    }
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error.message : String(error));
+                    i++;
+                }
+            }
+            else {
+                arguments_.push(arg);
+                i++;
+            }
+        }
+        return { options, arguments: arguments_, errors };
+    }
+    convertOptionValue(optionDef, value) {
+        if (value === undefined || value === null) {
+            return optionDef.default;
+        }
+        const stringValue = String(value);
+        switch (optionDef.type) {
+            case 'number':
+                const numValue = Number(stringValue);
+                if (isNaN(numValue)) {
+                    throw new Error(`Option --${optionDef.name} must be a number, got: ${stringValue}`);
+                }
+                return numValue;
+            case 'boolean':
+                if (typeof value === 'boolean') {
+                    return value;
+                }
+                const lowerValue = stringValue.toLowerCase();
+                if (lowerValue === 'true' || lowerValue === '1' || lowerValue === 'yes') {
+                    return true;
+                }
+                if (lowerValue === 'false' || lowerValue === '0' || lowerValue === 'no') {
+                    return false;
+                }
+                throw new Error(`Option --${optionDef.name} must be a boolean, got: ${stringValue}`);
+            case 'array':
+                if (Array.isArray(value)) {
+                    return value;
+                }
+                return stringValue.split(',').map(s => s.trim());
+            case 'string':
+            default:
+                return stringValue;
+        }
+    }
+    validateOptionValue(optionDef, value) {
+        const errors = [];
+        const warnings = [];
+        if (optionDef.choices && optionDef.choices.length > 0) {
+            if (!optionDef.choices.includes(String(value))) {
+                errors.push(`Option --${optionDef.name} must be one of: ${optionDef.choices.join(', ')}`);
+            }
+        }
+        if (optionDef.validator) {
+            const validationResult = optionDef.validator(value);
+            if (!validationResult.valid) {
+                errors.push(...validationResult.errors);
+                warnings.push(...validationResult.warnings);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    validateArgumentValue(argDef, value) {
+        const errors = [];
+        const warnings = [];
+        switch (argDef.type) {
+            case 'number':
+                if (isNaN(Number(value))) {
+                    errors.push(`Argument ${argDef.name} must be a number, got: ${value}`);
+                }
+                break;
+            case 'file':
+                if (typeof value !== 'string' || value.trim().length === 0) {
+                    errors.push(`Argument ${argDef.name} must be a valid file path`);
+                }
+                break;
+            case 'url':
+                try {
+                    new URL(String(value));
+                }
+                catch {
+                    errors.push(`Argument ${argDef.name} must be a valid URL`);
+                }
+                break;
+        }
+        if (argDef.validator) {
+            const validationResult = argDef.validator(value);
+            if (!validationResult.valid) {
+                errors.push(...validationResult.errors);
+                warnings.push(...validationResult.warnings);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    resolveCommandName(commandName) {
+        return this.aliases.get(commandName) || commandName;
+    }
+    validateCommandDefinition(command) {
+        const errors = [];
+        if (!command.name || typeof command.name !== 'string') {
+            errors.push('Command name is required and must be a string');
+        }
+        if (!command.description || typeof command.description !== 'string') {
+            errors.push('Command description is required and must be a string');
+        }
+        if (!Array.isArray(command.aliases)) {
+            errors.push('Command aliases must be an array');
+        }
+        if (!Array.isArray(command.options)) {
+            errors.push('Command options must be an array');
+        }
+        if (!Array.isArray(command.arguments)) {
+            errors.push('Command arguments must be an array');
+        }
+        for (const option of command.options) {
+            if (!option.name || typeof option.name !== 'string') {
+                errors.push(`Option name is required and must be a string`);
+            }
+            if (!['string', 'number', 'boolean', 'array'].includes(option.type)) {
+                errors.push(`Option ${option.name} has invalid type: ${option.type}`);
+            }
+        }
+        for (const arg of command.arguments) {
+            if (!arg.name || typeof arg.name !== 'string') {
+                errors.push(`Argument name is required and must be a string`);
+            }
+            if (!['string', 'number', 'file', 'url'].includes(arg.type)) {
+                errors.push(`Argument ${arg.name} has invalid type: ${arg.type}`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings: []
+        };
+    }
+    createParseResult(command, options, errors, success, arguments_ = []) {
+        return {
+            success,
+            command,
+            options,
+            arguments: arguments_,
+            errors,
+            warnings: []
+        };
+    }
+    getCommands() {
+        return Array.from(this.commands.values());
+    }
+    getCommand(name) {
+        const resolvedName = this.resolveCommandName(name);
+        return this.commands.get(resolvedName);
+    }
+    hasCommand(name) {
+        const resolvedName = this.resolveCommandName(name);
+        return this.commands.has(resolvedName);
+    }
+    generateContextualHelp(error, commandName) {
+        return this.helpSystem.generateContextualHelp(error, commandName);
+    }
+    getHelpSystem() {
+        return this.helpSystem;
+    }
+}
+exports.ArgumentParser = ArgumentParser;