chrome-cdp-cli 1.0.2 → 1.2.0

package/README.md

@@ -2,17 +2,47 @@
 
 A powerful command-line tool for controlling Chrome browser instances via the Chrome DevTools Protocol (CDP). This tool provides programmatic access to browser automation, debugging, and inspection capabilities without requiring a graphical interface.
 
+## Implementation Status
+
+### ✅ Fully Implemented Features
+
+- 🔗 **Connection Management**: Connect to local or remote Chrome instances with auto-discovery
+- ⚡ **JavaScript Execution**: Execute JavaScript code in browser context with full async support and file execution
+- 📸 **Visual Capture**: Take screenshots and capture complete DOM snapshots with layout information
+- 📊 **Console Monitoring**: Real-time console message capture with filtering and storage
+- 🌐 **Network Monitoring**: Real-time network request/response monitoring with comprehensive filtering
+- 🔧 **CLI Interface**: Full command-line interface with argument parsing and routing
+- 🛠️ **IDE Integration**: Install Cursor commands and Claude skills with directory validation and --force option
+- 📦 **Build System**: Complete TypeScript build pipeline with testing framework
+
+### 🚧 Eval Workaround Available
+
+These features are not directly implemented but can be achieved using the `eval` command:
+
+- 📄 **Page Navigation**: `eval "window.location.href = 'https://example.com'"`
+- 🖱️ **Element Interaction**: `eval "document.querySelector('#btn').click()"`
+- 📝 **Form Filling**: `eval "document.querySelector('#input').value = 'text'"`
+- 📄 **HTML Content**: `eval "document.documentElement.outerHTML"`
+- 🚀 **Performance Data**: `eval "performance.now()"` or `eval "performance.getEntriesByType('navigation')"`
+- 📱 **User Agent**: `eval "navigator.userAgent"`
+- 🌐 **Network Requests**: `eval "fetch('/api').then(r => r.json())"`
+
+### ⏳ Not Yet Implemented
+
+- 📄 **Direct Page Management**: Native commands for creating, closing, listing, and selecting tabs
+- 🖱️ **Direct Element Interaction**: Native click, hover, drag, and form filling commands
+- 🚀 **Performance Analysis**: Native performance profiling and metrics collection
+- 📱 **Device Emulation**: Native device and network condition simulation
+- 📊 **Output Formatting**: Advanced JSON/text formatting with quiet/verbose modes
+
 ## Features
 
 - 🔗 **Connection Management**: Connect to local or remote Chrome instances
-- 📄 **Page Management**: Navigate, create, close, and manage browser tabs
 - ⚡ **JavaScript Execution**: Execute JavaScript code in browser context with full async support
 - 📸 **Visual Capture**: Take screenshots and capture HTML content
-- 🖱️ **Element Interaction**: Click, hover, fill forms, and interact with page elements
 - 📊 **Monitoring**: Monitor console messages and network requests in real-time
-- 🚀 **Performance Analysis**: Profile page performance and analyze metrics
-- 📱 **Device Emulation**: Simulate different devices and network conditions
 - 🔧 **Flexible Output**: Support for JSON and human-readable text output formats
+- 🚧 **Eval Workarounds**: Many advanced features available through JavaScript execution
 
 ## Installation
 
@@ -77,17 +107,30 @@ chrome-cdp-cli eval "document.title"
 # Or use with npx (no installation needed)
 npx chrome-cdp-cli eval "document.title"
 
-# Navigate to a website
-chrome-cdp-cli navigate_page "https://example.com"
+# Navigate to a website (via eval)
+chrome-cdp-cli eval "window.location.href = 'https://example.com'"
 
 # Take a screenshot
 chrome-cdp-cli screenshot --filename screenshot.png
 
-# Click an element
-chrome-cdp-cli click "#submit-button"
+# Capture DOM snapshot
+chrome-cdp-cli snapshot --filename dom-snapshot.json
+
+# Click an element (via eval)
+chrome-cdp-cli eval "document.querySelector('#submit-button').click()"
+
+# Fill a form field (via eval)
+chrome-cdp-cli eval "document.querySelector('#email').value = 'user@example.com'"
+
+# Monitor console messages
+chrome-cdp-cli get_console_message
 
-# Fill a form field
-chrome-cdp-cli fill "#email" "user@example.com"
+# Monitor network requests
+chrome-cdp-cli get_network_request
+
+# Install IDE integrations
+chrome-cdp-cli install-cursor-command
+chrome-cdp-cli install-claude-skill --skill-type personal
 
 # Get help for all commands
 chrome-cdp-cli --help
@@ -112,7 +155,23 @@ All commands support these connection options:
 - `--quiet`: Suppress non-essential output
 - `--verbose`: Enable detailed logging
 
-### Core Commands
+## Command Reference
+
+### Connection Options
+
+All commands support these connection options:
+
+- `--host <host>`: Chrome host (default: localhost)
+- `--port <port>`: DevTools port (default: 9222)
+- `--timeout <ms>`: Command timeout in milliseconds (default: 30000)
+
+### Output Options
+
+- `--format <format>`: Output format - 'json' or 'text' (default: text)
+- `--quiet`: Suppress non-essential output
+- `--verbose`: Enable detailed logging
+
+### ✅ Implemented Commands
 
 #### JavaScript Execution
 ```bash
@@ -130,57 +189,325 @@ npx chrome-cdp-cli eval "document.title"
 npx chrome-cdp-cli eval --file script.js
 ```
 
+#### Visual Capture
+```bash
+# Take screenshot
+chrome-cdp-cli screenshot --filename screenshot.png
+
+# Full page screenshot  
+chrome-cdp-cli screenshot --full-page --filename fullpage.png
+
+# DOM snapshot with complete layout information
+chrome-cdp-cli snapshot --filename dom-snapshot.json
+
+# Custom dimensions
+chrome-cdp-cli screenshot --width 1920 --height 1080 --filename custom.png
+```
+
+#### Console Monitoring
+```bash
+# Get latest console message
+chrome-cdp-cli get_console_message
+
+# List all console messages
+chrome-cdp-cli list_console_messages
+
+# Filter console messages
+chrome-cdp-cli list_console_messages --filter '{"types":["error","warn"]}'
+```
+
+#### Network Monitoring
+```bash
+# Get latest network request
+chrome-cdp-cli get_network_request
+
+# List all network requests
+chrome-cdp-cli list_network_requests
+
+# Filter network requests
+chrome-cdp-cli list_network_requests --filter '{"methods":["POST"],"statusCodes":[200,201]}'
+```
+
+#### IDE Integration
+```bash
+# Install Cursor command (creates .cursor/commands/cdp-cli.md)
+chrome-cdp-cli install-cursor-command
+
+# Install Cursor command with --force (bypasses directory validation)
+chrome-cdp-cli install-cursor-command --force
+
+# Install Claude skill for project (creates .claude/skills/cdp-cli/SKILL.md)
+chrome-cdp-cli install-claude-skill
+
+# Install Claude skill for personal use (creates ~/.claude/skills/cdp-cli/SKILL.md)
+chrome-cdp-cli install-claude-skill --skill-type personal
+
+# Install Claude skill with examples and references
+chrome-cdp-cli install-claude-skill --include-examples --include-references
+
+# Install with custom directory
+chrome-cdp-cli install-cursor-command --target-directory /custom/path/.cursor/commands
+chrome-cdp-cli install-claude-skill --target-directory /custom/path/.claude/skills
+
+# Force install (bypasses directory validation)
+chrome-cdp-cli install-cursor-command --force
+chrome-cdp-cli install-claude-skill --force
+```
+
+### 🚧 Available via Eval Workarounds
+
 #### Page Management
 ```bash
 # Navigate to URL
-chrome-cdp-cli navigate_page "https://example.com"
+chrome-cdp-cli eval "window.location.href = 'https://example.com'"
 
-# Create new tab
-chrome-cdp-cli new_page
+# Get current URL
+chrome-cdp-cli eval "window.location.href"
 
-# List all pages
-chrome-cdp-cli list_pages
+# Reload page
+chrome-cdp-cli eval "window.location.reload()"
 
-# Close current page
-chrome-cdp-cli close_page
+# Go back
+chrome-cdp-cli eval "window.history.back()"
 
-# Switch to specific page
-chrome-cdp-cli select_page --id "page-id"
+# Go forward
+chrome-cdp-cli eval "window.history.forward()"
 ```
 
 #### Element Interaction
 ```bash
 # Click element
-chrome-cdp-cli click "#button"
+chrome-cdp-cli eval "document.querySelector('#button').click()"
 
 # Fill input field
-chrome-cdp-cli fill "#email" "user@example.com"
+chrome-cdp-cli eval "document.querySelector('#email').value = 'user@example.com'"
+
+# Hover over element (trigger mouseover event)
+chrome-cdp-cli eval "document.querySelector('.menu-item').dispatchEvent(new MouseEvent('mouseover'))"
+
+# Check if element exists
+chrome-cdp-cli eval "!!document.querySelector('#element')"
 
-# Hover over element
-chrome-cdp-cli hover ".menu-item"
+# Get element text
+chrome-cdp-cli eval "document.querySelector('#element').textContent"
 
-# Wait for element
-chrome-cdp-cli wait_for "#loading" --timeout 5000
+# Get element attributes
+chrome-cdp-cli eval "document.querySelector('#element').getAttribute('class')"
 ```
 
-#### Visual Capture
+#### Form Handling
 ```bash
-# Take screenshot
-chrome-cdp-cli screenshot --filename screenshot.png
+# Fill multiple form fields
+chrome-cdp-cli eval "
+document.querySelector('#name').value = 'John Doe';
+document.querySelector('#email').value = 'john@example.com';
+document.querySelector('#phone').value = '123-456-7890';
+"
 
-# Full page screenshot  
-chrome-cdp-cli screenshot --full-page --filename fullpage.png
+# Submit form
+chrome-cdp-cli eval "document.querySelector('#myform').submit()"
 
-# DOM snapshot
-chrome-cdp-cli snapshot --filename dom-snapshot.json
+# Select dropdown option
+chrome-cdp-cli eval "document.querySelector('#dropdown').value = 'option1'"
 
-# Custom dimensions
-chrome-cdp-cli screenshot --width 1920 --height 1080 --filename custom.png
+# Check checkbox
+chrome-cdp-cli eval "document.querySelector('#checkbox').checked = true"
+```
+
+#### Content Extraction
+```bash
+# Get page HTML
+chrome-cdp-cli eval "document.documentElement.outerHTML"
+
+# Get page title
+chrome-cdp-cli eval "document.title"
+
+# Get all links
+chrome-cdp-cli eval "Array.from(document.querySelectorAll('a')).map(a => a.href)"
 
-# Get HTML content
-chrome-cdp-cli get_html --output page.html
+# Get all images
+chrome-cdp-cli eval "Array.from(document.querySelectorAll('img')).map(img => img.src)"
+
+# Extract table data
+chrome-cdp-cli eval "Array.from(document.querySelectorAll('table tr')).map(row => Array.from(row.cells).map(cell => cell.textContent))"
+```
+
+#### Performance Monitoring
+```bash
+# Get performance timing
+chrome-cdp-cli eval "performance.timing"
+
+# Get navigation entries
+chrome-cdp-cli eval "performance.getEntriesByType('navigation')"
+
+# Get resource entries
+chrome-cdp-cli eval "performance.getEntriesByType('resource')"
+
+# Get current timestamp
+chrome-cdp-cli eval "performance.now()"
+
+# Measure performance
+chrome-cdp-cli eval "
+performance.mark('start');
+// ... some operation ...
+performance.mark('end');
+performance.measure('operation', 'start', 'end');
+performance.getEntriesByName('operation')[0].duration;
+"
+```
+
+#### Network Operations
+```bash
+# Make HTTP request
+chrome-cdp-cli eval "fetch('/api/data').then(r => r.json())"
+
+# POST data
+chrome-cdp-cli eval "
+fetch('/api/users', {
+  method: 'POST',
+  headers: {'Content-Type': 'application/json'},
+  body: JSON.stringify({name: 'John', email: 'john@example.com'})
+}).then(r => r.json())
+"
+
+# Check network connectivity
+chrome-cdp-cli eval "navigator.onLine"
 ```
 
+#### Browser Information
+```bash
+# Get user agent
+chrome-cdp-cli eval "navigator.userAgent"
+
+# Get viewport size
+chrome-cdp-cli eval "{width: window.innerWidth, height: window.innerHeight}"
+
+# Get screen resolution
+chrome-cdp-cli eval "{width: screen.width, height: screen.height}"
+
+# Get browser language
+chrome-cdp-cli eval "navigator.language"
+
+# Get cookies
+chrome-cdp-cli eval "document.cookie"
+```
+
+### ⏳ Not Yet Implemented
+
+These features require dedicated handlers and are not yet available:
+
+- Native page management commands (new_page, close_page, list_pages, select_page)
+- Native element interaction commands (click, hover, fill, drag)
+- Native performance profiling commands
+- Native device emulation commands
+- Advanced output formatting options
+
+## The Power of Eval
+
+The `eval` command is the most powerful feature of this CLI tool. It allows you to execute any JavaScript code in the browser context, making it possible to achieve almost any browser automation task. Here are some advanced examples:
+
+### Advanced Automation Examples
+
+```bash
+# Wait for element to appear
+chrome-cdp-cli eval "
+new Promise(resolve => {
+  const check = () => {
+    const element = document.querySelector('#dynamic-content');
+    if (element) resolve(element.textContent);
+    else setTimeout(check, 100);
+  };
+  check();
+})
+"
+
+# Scroll to element
+chrome-cdp-cli eval "
+document.querySelector('#target').scrollIntoView({behavior: 'smooth'});
+"
+
+# Take element screenshot (get element bounds for screenshot)
+chrome-cdp-cli eval "
+const element = document.querySelector('#target');
+const rect = element.getBoundingClientRect();
+({x: rect.x, y: rect.y, width: rect.width, height: rect.height})
+"
+
+# Simulate complex user interactions
+chrome-cdp-cli eval "
+const element = document.querySelector('#button');
+element.dispatchEvent(new MouseEvent('mousedown'));
+setTimeout(() => element.dispatchEvent(new MouseEvent('mouseup')), 100);
+"
+
+# Extract structured data
+chrome-cdp-cli eval "
+Array.from(document.querySelectorAll('.product')).map(product => ({
+  name: product.querySelector('.name').textContent,
+  price: product.querySelector('.price').textContent,
+  image: product.querySelector('img').src
+}))
+"
+
+# Monitor page changes
+chrome-cdp-cli eval "
+new Promise(resolve => {
+  const observer = new MutationObserver(mutations => {
+    resolve(mutations.length + ' changes detected');
+    observer.disconnect();
+  });
+  observer.observe(document.body, {childList: true, subtree: true});
+  setTimeout(() => {
+    observer.disconnect();
+    resolve('No changes in 5 seconds');
+  }, 5000);
+})
+"
+```
+
+## Current Limitations & Roadmap
+
+### Current Limitations
+
+- **No native page management**: Creating, closing, and switching between tabs requires manual implementation
+- **No native element interaction**: Clicking, hovering, and form filling must be done via eval
+- **No performance profiling**: Advanced performance analysis requires manual JavaScript
+- **No device emulation**: Mobile/tablet simulation not yet implemented
+- **Basic output formatting**: Advanced JSON/text formatting options not available
+
+### Upcoming Features
+
+1. **Native Page Management Commands**
+   - `new_page`, `close_page`, `list_pages`, `select_page`
+   - Direct CDP Target domain integration
+
+2. **Native Element Interaction**
+   - `click`, `hover`, `fill`, `drag` commands
+   - CSS selector-based element targeting
+
+3. **Performance Analysis**
+   - `performance_start_trace`, `performance_stop_trace`
+   - Built-in performance metrics and analysis
+
+4. **Device Emulation**
+   - `emulate` command for device simulation
+   - Network condition simulation
+
+5. **Advanced Output Formatting**
+   - Enhanced JSON/text formatting
+   - Quiet and verbose modes
+   - Custom output templates
+
+### Why Use Eval Workarounds?
+
+The eval approach offers several advantages:
+
+- **Immediate availability**: No waiting for feature implementation
+- **Maximum flexibility**: Any JavaScript operation is possible
+- **Learning opportunity**: Better understanding of browser APIs
+- **Custom solutions**: Tailor automation to specific needs
+- **Future-proof**: Works with any web technology
+
 ## Configuration
 
 ### Configuration File

package/dist/cli/CLIApplication.js

@@ -17,6 +17,12 @@ class CLIApplication {
         this.cli.registerHandler(new handlers_1.EvaluateScriptHandler());
         this.cli.registerHandler(new handlers_1.TakeScreenshotHandler());
         this.cli.registerHandler(new handlers_1.TakeSnapshotHandler());
+        this.cli.registerHandler(new handlers_1.GetConsoleMessageHandler());
+        this.cli.registerHandler(new handlers_1.ListConsoleMessagesHandler());
+        this.cli.registerHandler(new handlers_1.GetNetworkRequestHandler());
+        this.cli.registerHandler(new handlers_1.ListNetworkRequestsHandler());
+        this.cli.registerHandler(new handlers_1.InstallCursorCommandHandler());
+        this.cli.registerHandler(new handlers_1.InstallClaudeSkillHandler());
     }
     async run(argv) {
         try {
@@ -35,7 +41,13 @@ class CLIApplication {
         }
     }
     needsConnection(commandName) {
-        const noConnectionCommands = ['help', 'connect', 'disconnect'];
+        const noConnectionCommands = [
+            'help',
+            'connect',
+            'disconnect',
+            'install_cursor_command',
+            'install_claude_skill'
+        ];
         return !noConnectionCommands.includes(commandName);
     }
     async ensureConnection(command) {

package/dist/cli/CLIInterface.js

@@ -291,6 +291,26 @@ class CLIInterface {
                 if (args[0])
                     commandArgs.command = args[0];
                 break;
+            case 'install_cursor_command':
+                if (options['target-directory'])
+                    commandArgs.targetDirectory = options['target-directory'];
+                if (options['include-examples'] !== undefined)
+                    commandArgs.includeExamples = options['include-examples'] !== 'false';
+                if (options['force'])
+                    commandArgs.force = true;
+                break;
+            case 'install_claude_skill':
+                if (options['skill-type'])
+                    commandArgs.skillType = options['skill-type'];
+                if (options['target-directory'])
+                    commandArgs.targetDirectory = options['target-directory'];
+                if (options['include-examples'] !== undefined)
+                    commandArgs.includeExamples = options['include-examples'] !== 'false';
+                if (options['include-references'] !== undefined)
+                    commandArgs.includeReferences = options['include-references'] !== 'false';
+                if (options['force'])
+                    commandArgs.force = true;
+                break;
             default:
                 args.forEach((arg, index) => {
                     commandArgs[`arg${index}`] = arg;

package/dist/cli/CommandRouter.js

@@ -69,7 +69,13 @@ class CommandRouter {
         }
     }
     isSpecialCommand(commandName) {
-        const specialCommands = ['help', 'connect', 'disconnect'];
+        const specialCommands = [
+            'help',
+            'connect',
+            'disconnect',
+            'install_cursor_command',
+            'install_claude_skill'
+        ];
         return specialCommands.includes(commandName);
     }
     async executeSpecialCommand(command) {
@@ -80,6 +86,17 @@ class CommandRouter {
                 return this.executeConnectCommand(command);
             case 'disconnect':
                 return this.executeDisconnectCommand();
+            case 'install_cursor_command':
+            case 'install_claude_skill':
+                const handler = this.registry.get(command.name);
+                if (!handler) {
+                    return {
+                        success: false,
+                        error: `Handler not found for command: ${command.name}`,
+                        exitCode: ExitCode.INVALID_COMMAND
+                    };
+                }
+                return await handler.execute(null, command.args);
             default:
                 return {
                     success: false,
@@ -229,6 +246,8 @@ For more information about a specific command, use:
             'snapshot': 'Capture DOM snapshot with structure and styles',
             'console-messages': 'Get console messages',
             'network-requests': 'Get network requests',
+            'install_cursor_command': 'Install Cursor IDE commands for Chrome automation',
+            'install_claude_skill': 'Install Claude Code skill for Chrome automation',
             'help': 'Show help information'
         };
         return descriptions[commandName] || 'No description available';

package/dist/handlers/GetConsoleMessageHandler.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetConsoleMessageHandler = void 0;
+const ConsoleMonitor_1 = require("../monitors/ConsoleMonitor");
+class GetConsoleMessageHandler {
+    constructor() {
+        this.name = 'get_console_message';
+        this.consoleMonitor = null;
+    }
+    async execute(client, args) {
+        try {
+            const params = args;
+            if (!this.consoleMonitor) {
+                this.consoleMonitor = new ConsoleMonitor_1.ConsoleMonitor(client);
+            }
+            if (params.startMonitoring || !this.consoleMonitor.isActive()) {
+                await this.consoleMonitor.startMonitoring();
+            }
+            const filter = {};
+            if (params.type) {
+                filter.types = [params.type];
+            }
+            if (params.textPattern) {
+                filter.textPattern = params.textPattern;
+            }
+            const latestMessage = this.consoleMonitor.getLatestMessage(filter);
+            if (!latestMessage) {
+                return {
+                    success: true,
+                    data: null
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    type: latestMessage.type,
+                    text: latestMessage.text,
+                    args: latestMessage.args,
+                    timestamp: latestMessage.timestamp,
+                    stackTrace: latestMessage.stackTrace
+                }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error occurred'
+            };
+        }
+    }
+    validateArgs(args) {
+        if (!args || typeof args !== 'object') {
+            return true;
+        }
+        const params = args;
+        if (params.type !== undefined) {
+            if (typeof params.type !== 'string') {
+                return false;
+            }
+            const validTypes = ['log', 'info', 'warn', 'error', 'debug'];
+            if (!validTypes.includes(params.type)) {
+                return false;
+            }
+        }
+        if (params.textPattern !== undefined && typeof params.textPattern !== 'string') {
+            return false;
+        }
+        if (params.startMonitoring !== undefined && typeof params.startMonitoring !== 'boolean') {
+            return false;
+        }
+        return true;
+    }
+    getHelp() {
+        return `get_console_message - Get the latest console message
+    
+Usage:
+  get_console_message [options]
+  
+Options:
+  --type <type>           Filter by message type (log, info, warn, error, debug)
+  --textPattern <pattern> Filter by text pattern (regex)
+  --startMonitoring       Start monitoring if not already active
+  
+Examples:
+  get_console_message
+  get_console_message --type error
+  get_console_message --textPattern "API"
+  get_console_message --startMonitoring`;
+    }
+}
+exports.GetConsoleMessageHandler = GetConsoleMessageHandler;