chrome-cdp-cli 1.2.2 → 1.3.0

package/dist/handlers/InstallCursorCommandHandler.js

@@ -63,7 +63,7 @@ Examples:
                     };
                 }
             }
-            await this.ensureDirectory(targetDir);
+            await this.ensureDirectoryPath(targetDir);
             const commands = this.generateCursorCommands();
             const createdFiles = [];
             for (const command of commands) {
@@ -109,89 +109,175 @@ Examples:
             logger_1.logger.info(`Created directory: ${dirPath}`);
         }
     }
+    async ensureDirectoryPath(targetPath) {
+        if (targetPath.includes('.cursor/commands') || targetPath.endsWith('.cursor/commands')) {
+            const cursorDir = targetPath.includes('.cursor/commands')
+                ? targetPath.substring(0, targetPath.indexOf('.cursor') + 7)
+                : path.dirname(targetPath);
+            await this.ensureDirectory(cursorDir);
+            const commandsDir = path.join(cursorDir, 'commands');
+            await this.ensureDirectory(commandsDir);
+        }
+        else {
+            await this.ensureDirectory(targetPath);
+        }
+    }
     generateCursorCommands() {
         return [
             {
                 name: 'cdp-cli',
                 description: 'Chrome DevTools Protocol CLI 工具',
-                instructions: `通过 Chrome DevTools Protocol 控制 Chrome 浏览器，支持多种自动化操作。
-
-## 功能列表
-
-### 1. JavaScript 执行 (eval)
-执行 JavaScript 代码并返回结果，支持异步代码和 Promise。
-
-**用途：**
-- 获取页面信息（标题、URL、元素等）
-- 修改页面内容和样式
-- 执行复杂的 JavaScript 逻辑
-- 与页面元素交互
-
-**示例：**
-- \`chrome-cdp-cli eval "document.title"\`
-- \`chrome-cdp-cli eval "window.location.href"\`
-- \`chrome-cdp-cli eval "document.querySelector('#button').click()"\`
-- \`chrome-cdp-cli eval "fetch('/api/data').then(r => r.json())"\`
-
-### 2. 页面截图 (screenshot)
-捕获当前页面的截图并保存到指定文件。
-
-**功能：**
-- 指定文件名和路径
-- 全页面截图或视口截图
-- 自定义图片质量和格式
-- 输出 PNG 格式文件
-
-**示例：**
-- \`chrome-cdp-cli screenshot --filename screenshot.png\`
-- \`chrome-cdp-cli screenshot --filename fullpage.png --full-page\`
-- \`chrome-cdp-cli screenshot --filename reports/page-capture.png\`
-
-### 3. DOM 快照 (snapshot)
-捕获包含 DOM 结构、样式和布局信息的完整快照。
-
-**包含内容：**
-- 完整的 DOM 树结构
-- 计算后的 CSS 样式
-- 元素布局信息
-- 元素属性和文本内容
-
-**示例：**
-- \`chrome-cdp-cli snapshot --filename dom-snapshot.json\`
-- \`chrome-cdp-cli snapshot --filename page-structure.json\`
-
-### 4. 控制台监控 (console)
-获取浏览器控制台的消息，包括日志、警告和错误。
-
-**功能：**
-- 获取最新的控制台消息
-- 列出所有控制台消息
-- 按类型过滤消息（log、warn、error）
-- 调试和监控页面运行状态
-
-**示例：**
-- \`chrome-cdp-cli get_console_message\`
-- \`chrome-cdp-cli list_console_messages --type error\`
-
-### 5. 网络请求监控 (network)
-监控和获取页面的网络请求信息。
-
-**功能：**
-- 获取最新的网络请求
-- 列出所有网络请求
-- 按方法过滤请求（GET、POST 等）
-- 查看请求和响应详情
-- 分析页面的网络行为和 API 调用
-
-**示例：**
-- \`chrome-cdp-cli get_network_request\`
-- \`chrome-cdp-cli list_network_requests --method POST\`
+                instructions: `通过 Chrome DevTools Protocol 控制 Chrome 浏览器，支持完整的自动化操作。
+
+## 完整命令列表
+
+### 1. JavaScript 执行
+- **eval** - 执行 JavaScript 代码并返回结果，支持异步代码和 Promise
+  \`chrome-cdp-cli eval "document.title"\`
+  \`chrome-cdp-cli eval "fetch('/api/data').then(r => r.json())"\`
+
+### 2. 页面截图和快照
+- **screenshot** - 捕获页面截图并保存到文件
+  \`chrome-cdp-cli screenshot --filename page.png\`
+  \`chrome-cdp-cli screenshot --filename fullpage.png --full-page\`
+
+- **snapshot** - 捕获完整 DOM 快照（包含结构、样式、布局）
+  \`chrome-cdp-cli snapshot --filename dom-snapshot.json\`
+
+### 3. 元素交互
+- **click** - 点击页面元素
+  \`chrome-cdp-cli click "#submit-button"\`
+  \`chrome-cdp-cli click ".menu-item" --timeout 10000\`
+
+- **hover** - 鼠标悬停在元素上
+  \`chrome-cdp-cli hover "#dropdown-trigger"\`
+
+- **fill** - 填充表单字段
+  \`chrome-cdp-cli fill "#username" "john@example.com"\`
+  \`chrome-cdp-cli fill "input[name='password']" "secret123"\`
+
+- **fill_form** - 批量填充表单
+  \`chrome-cdp-cli fill_form '{"#username": "john", "#password": "secret"}'\`
+
+### 4. 高级交互
+- **drag** - 拖拽操作
+  \`chrome-cdp-cli drag "#draggable" "#dropzone"\`
+
+- **press_key** - 模拟键盘输入
+  \`chrome-cdp-cli press_key "Enter"\`
+  \`chrome-cdp-cli press_key "a" --modifiers Ctrl --selector "#input"\`
+
+- **upload_file** - 文件上传
+  \`chrome-cdp-cli upload_file "input[type='file']" "./document.pdf"\`
+
+- **wait_for** - 等待元素出现或满足条件
+  \`chrome-cdp-cli wait_for "#loading" --condition hidden\`
+  \`chrome-cdp-cli wait_for "#submit-btn" --condition enabled\`
+
+- **handle_dialog** - 处理浏览器对话框
+  \`chrome-cdp-cli handle_dialog accept\`
+  \`chrome-cdp-cli handle_dialog accept --text "user input"\`
+
+### 5. 监控功能
+- **get_console_message** - 获取最新控制台消息
+  \`chrome-cdp-cli get_console_message\`
+
+- **list_console_messages** - 列出所有控制台消息
+  \`chrome-cdp-cli list_console_messages --type error\`
+
+- **get_network_request** - 获取最新网络请求
+  \`chrome-cdp-cli get_network_request\`
+
+- **list_network_requests** - 列出所有网络请求
+  \`chrome-cdp-cli list_network_requests --method POST\`
+
+### 6. IDE 集成
+- **install_cursor_command** - 安装 Cursor 命令
+  \`chrome-cdp-cli install_cursor_command\`
+
+- **install_claude_skill** - 安装 Claude 技能
+  \`chrome-cdp-cli install_claude_skill --skill-type personal\`
+
+## 常用工作流程
+
+### 完整的表单测试流程
+\`\`\`bash
+# 1. 等待页面加载
+chrome-cdp-cli wait_for "#login-form" --condition visible
+
+# 2. 填写表单
+chrome-cdp-cli fill "#email" "test@example.com"
+chrome-cdp-cli fill "#password" "password123"
+
+# 3. 提交表单
+chrome-cdp-cli click "#submit-button"
+
+# 4. 等待结果并截图
+chrome-cdp-cli wait_for "#success-message" --condition visible
+chrome-cdp-cli screenshot --filename login-success.png
+
+# 5. 检查控制台错误
+chrome-cdp-cli list_console_messages --type error
+\`\`\`
+
+### 文件上传测试
+\`\`\`bash
+# 1. 点击上传按钮
+chrome-cdp-cli click "#upload-trigger"
+
+# 2. 上传文件
+chrome-cdp-cli upload_file "input[type='file']" "./test-document.pdf"
+
+# 3. 等待上传完成
+chrome-cdp-cli wait_for ".upload-success" --condition visible
+
+# 4. 验证结果
+chrome-cdp-cli eval "document.querySelector('.file-name').textContent"
+\`\`\`
+
+### 拖拽交互测试
+\`\`\`bash
+# 1. 等待元素可用
+chrome-cdp-cli wait_for "#draggable-item" --condition visible
+chrome-cdp-cli wait_for "#drop-zone" --condition visible
+
+# 2. 执行拖拽
+chrome-cdp-cli drag "#draggable-item" "#drop-zone"
+
+# 3. 验证拖拽结果
+chrome-cdp-cli eval "document.querySelector('#drop-zone').children.length"
+\`\`\`
+
+### 键盘导航测试
+\`\`\`bash
+# 1. 聚焦到输入框
+chrome-cdp-cli click "#search-input"
+
+# 2. 输入文本
+chrome-cdp-cli press_key "t"
+chrome-cdp-cli press_key "e"
+chrome-cdp-cli press_key "s"
+chrome-cdp-cli press_key "t"
+
+# 3. 使用快捷键
+chrome-cdp-cli press_key "a" --modifiers Ctrl  # 全选
+chrome-cdp-cli press_key "Enter"  # 提交
+
+# 4. 处理可能的确认对话框
+chrome-cdp-cli handle_dialog accept
+\`\`\`
 
 命令会自动连接到运行在 localhost:9222 的 Chrome 实例。`,
                 examples: [
                     'chrome-cdp-cli eval "document.title"',
                     'chrome-cdp-cli screenshot --filename page.png',
-                    'chrome-cdp-cli snapshot --filename dom.json',
+                    'chrome-cdp-cli click "#submit-button"',
+                    'chrome-cdp-cli fill "#username" "test@example.com"',
+                    'chrome-cdp-cli drag "#item" "#target"',
+                    'chrome-cdp-cli press_key "Enter"',
+                    'chrome-cdp-cli upload_file "input[type=file]" "./doc.pdf"',
+                    'chrome-cdp-cli wait_for "#loading" --condition hidden',
+                    'chrome-cdp-cli handle_dialog accept',
                     'chrome-cdp-cli get_console_message',
                     'chrome-cdp-cli list_network_requests'
                 ]
@@ -274,6 +360,54 @@ chrome-cdp-cli snapshot --filename page-analysis.json
 # 3. 检查控制台错误
 chrome-cdp-cli list_console_messages --type error
 \`\`\`
+`;
+    }
+    getHelp() {
+        return `
+install-cursor-command - Install Cursor IDE commands for Chrome browser automation
+
+Usage:
+  install-cursor-command
+  install-cursor-command --target-directory /path/to/.cursor/commands
+  install-cursor-command --force
+
+Arguments:
+  --target-directory <path>   Custom installation directory (default: .cursor/commands)
+  --include-examples          Include example usage (default: true)
+  --force                     Force installation without directory validation
+
+Description:
+  Installs a unified Cursor command file (cdp-cli.md) that provides Chrome browser
+  automation capabilities directly within Cursor IDE. The command includes:
+
+  • JavaScript execution in browser context
+  • Screenshot capture and DOM snapshots
+  • Console and network monitoring
+  • Complete automation workflows
+  • Comprehensive examples and documentation
+
+Directory Validation:
+  By default, the command checks for a .cursor directory to ensure you're in a
+  Cursor project root. Use --force to bypass this validation or --target-directory
+  to specify a custom location.
+
+Examples:
+  # Install in current project (requires .cursor directory)
+  install-cursor-command
+
+  # Install with custom directory
+  install-cursor-command --target-directory /path/to/.cursor/commands
+
+  # Force install without validation
+  install-cursor-command --force
+
+  # After installation, use in Cursor with:
+  /cdp-cli
+
+Note:
+  The installed command provides powerful browser automation through the eval
+  approach, which is ideal for LLM-assisted development as it allows writing
+  and testing JavaScript automation scripts quickly and flexibly.
 `;
     }
 }

package/dist/handlers/PressKeyHandler.js

@@ -0,0 +1,337 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PressKeyHandler = void 0;
+class PressKeyHandler {
+    constructor() {
+        this.name = 'press_key';
+    }
+    async execute(client, args) {
+        const keyArgs = args;
+        if (!keyArgs.key) {
+            return {
+                success: false,
+                error: 'Key is required for press_key command'
+            };
+        }
+        if (typeof keyArgs.key !== 'string') {
+            return {
+                success: false,
+                error: 'Key must be a string'
+            };
+        }
+        try {
+            await client.send('Runtime.enable');
+            const timeout = keyArgs.timeout || 5000;
+            const waitForElement = keyArgs.waitForElement !== false;
+            if (keyArgs.selector) {
+                if (waitForElement) {
+                    const elementFound = await this.waitForElement(client, keyArgs.selector, timeout);
+                    if (!elementFound) {
+                        return {
+                            success: false,
+                            error: `Element with selector "${keyArgs.selector}" not found within ${timeout}ms`
+                        };
+                    }
+                }
+                const focusResult = await this.focusElement(client, keyArgs.selector);
+                if (!focusResult.success) {
+                    return focusResult;
+                }
+            }
+            const result = await this.pressKeyViaEval(client, keyArgs.key, keyArgs.modifiers || [], keyArgs.selector);
+            return result;
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    async waitForElement(client, selector, timeout) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            try {
+                const result = await client.send('Runtime.evaluate', {
+                    expression: `document.querySelector('${selector.replace(/'/g, "\\'")}') !== null`,
+                    returnByValue: true
+                });
+                if (result.result.value) {
+                    return true;
+                }
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+            catch (error) {
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+        return false;
+    }
+    async focusElement(client, selector) {
+        try {
+            const escapedSelector = selector.replace(/'/g, "\\'").replace(/"/g, '\\"');
+            const expression = `
+        (function() {
+          const element = document.querySelector('${escapedSelector}');
+          if (!element) {
+            throw new Error('Element with selector "${escapedSelector}" not found');
+          }
+          
+          element.focus();
+          
+          return {
+            success: true,
+            tagName: element.tagName,
+            id: element.id,
+            className: element.className
+          };
+        })()
+      `;
+            const response = await client.send('Runtime.evaluate', {
+                expression: expression,
+                returnByValue: true,
+                userGesture: true
+            });
+            if (response.exceptionDetails) {
+                return {
+                    success: false,
+                    error: response.exceptionDetails.exception?.description || response.exceptionDetails.text
+                };
+            }
+            return {
+                success: true,
+                data: response.result.value
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Focus failed: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    async pressKeyViaEval(client, key, modifiers, selector) {
+        try {
+            const escapedKey = key.replace(/'/g, "\\'").replace(/"/g, '\\"');
+            const modifierFlags = {
+                ctrlKey: modifiers.includes('Ctrl') || modifiers.includes('Control'),
+                altKey: modifiers.includes('Alt'),
+                shiftKey: modifiers.includes('Shift'),
+                metaKey: modifiers.includes('Meta') || modifiers.includes('Cmd')
+            };
+            const expression = `
+        (function() {
+          const key = '${escapedKey}';
+          const modifiers = ${JSON.stringify(modifierFlags)};
+          
+          // Determine target element
+          let targetElement = document.activeElement;
+          ${selector ? `
+          const specifiedElement = document.querySelector('${selector.replace(/'/g, "\\'")}');
+          if (specifiedElement) {
+            targetElement = specifiedElement;
+          }
+          ` : ''}
+          
+          if (!targetElement) {
+            targetElement = document.body;
+          }
+          
+          // Create keyboard event options
+          const eventOptions = {
+            key: key,
+            code: key.length === 1 ? 'Key' + key.toUpperCase() : key,
+            bubbles: true,
+            cancelable: true,
+            view: window,
+            ctrlKey: modifiers.ctrlKey,
+            altKey: modifiers.altKey,
+            shiftKey: modifiers.shiftKey,
+            metaKey: modifiers.metaKey
+          };
+          
+          // Handle special keys
+          const specialKeys = {
+            'Enter': { code: 'Enter', keyCode: 13 },
+            'Escape': { code: 'Escape', keyCode: 27 },
+            'Tab': { code: 'Tab', keyCode: 9 },
+            'Backspace': { code: 'Backspace', keyCode: 8 },
+            'Delete': { code: 'Delete', keyCode: 46 },
+            'ArrowUp': { code: 'ArrowUp', keyCode: 38 },
+            'ArrowDown': { code: 'ArrowDown', keyCode: 40 },
+            'ArrowLeft': { code: 'ArrowLeft', keyCode: 37 },
+            'ArrowRight': { code: 'ArrowRight', keyCode: 39 },
+            'Home': { code: 'Home', keyCode: 36 },
+            'End': { code: 'End', keyCode: 35 },
+            'PageUp': { code: 'PageUp', keyCode: 33 },
+            'PageDown': { code: 'PageDown', keyCode: 34 },
+            'Space': { code: 'Space', keyCode: 32, key: ' ' }
+          };
+          
+          if (specialKeys[key]) {
+            eventOptions.code = specialKeys[key].code;
+            eventOptions.keyCode = specialKeys[key].keyCode;
+            if (specialKeys[key].key) {
+              eventOptions.key = specialKeys[key].key;
+            }
+          }
+          
+          // Create and dispatch keydown event
+          const keydownEvent = new KeyboardEvent('keydown', eventOptions);
+          targetElement.dispatchEvent(keydownEvent);
+          
+          // Create and dispatch keypress event (for printable characters)
+          if (key.length === 1 || key === 'Enter' || key === 'Space') {
+            const keypressEvent = new KeyboardEvent('keypress', eventOptions);
+            targetElement.dispatchEvent(keypressEvent);
+          }
+          
+          // Create and dispatch keyup event
+          const keyupEvent = new KeyboardEvent('keyup', eventOptions);
+          targetElement.dispatchEvent(keyupEvent);
+          
+          // For input elements, also trigger input event if it's a printable character
+          if ((targetElement.tagName === 'INPUT' || targetElement.tagName === 'TEXTAREA') && 
+              key.length === 1 && !modifiers.ctrlKey && !modifiers.altKey && !modifiers.metaKey) {
+            // Add character to input value
+            const currentValue = targetElement.value || '';
+            const cursorPos = targetElement.selectionStart || currentValue.length;
+            const newValue = currentValue.slice(0, cursorPos) + key + currentValue.slice(cursorPos);
+            targetElement.value = newValue;
+            targetElement.selectionStart = targetElement.selectionEnd = cursorPos + 1;
+            
+            // Trigger input and change events
+            targetElement.dispatchEvent(new Event('input', { bubbles: true }));
+            targetElement.dispatchEvent(new Event('change', { bubbles: true }));
+          }
+          
+          return {
+            success: true,
+            key: key,
+            modifiers: modifiers,
+            target: {
+              tagName: targetElement.tagName,
+              id: targetElement.id,
+              className: targetElement.className,
+              value: targetElement.value || null
+            }
+          };
+        })()
+      `;
+            const response = await client.send('Runtime.evaluate', {
+                expression: expression,
+                returnByValue: true,
+                userGesture: true
+            });
+            if (response.exceptionDetails) {
+                return {
+                    success: false,
+                    error: response.exceptionDetails.exception?.description || response.exceptionDetails.text
+                };
+            }
+            return {
+                success: true,
+                data: {
+                    key: key,
+                    modifiers: modifiers,
+                    selector: selector,
+                    result: response.result.value
+                }
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Key press failed: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    validateArgs(args) {
+        if (typeof args !== 'object' || args === null) {
+            return false;
+        }
+        const keyArgs = args;
+        if (!keyArgs.key || typeof keyArgs.key !== 'string') {
+            return false;
+        }
+        if (keyArgs.selector !== undefined && typeof keyArgs.selector !== 'string') {
+            return false;
+        }
+        if (keyArgs.modifiers !== undefined && !Array.isArray(keyArgs.modifiers)) {
+            return false;
+        }
+        if (keyArgs.modifiers && !keyArgs.modifiers.every(mod => typeof mod === 'string')) {
+            return false;
+        }
+        if (keyArgs.waitForElement !== undefined && typeof keyArgs.waitForElement !== 'boolean') {
+            return false;
+        }
+        if (keyArgs.timeout !== undefined && typeof keyArgs.timeout !== 'number') {
+            return false;
+        }
+        return true;
+    }
+    getHelp() {
+        return `
+press_key - Simulate keyboard input
+
+Usage:
+  press_key <key>
+  press_key <key> --selector <selector>
+  press_key <key> --modifiers Ctrl,Shift
+  press_key "Enter" --selector "#input-field"
+
+Arguments:
+  <key>                   Key to press (e.g., 'Enter', 'Escape', 'a', 'ArrowDown')
+
+Options:
+  --selector <selector>   CSS selector to focus element first
+  --modifiers <list>      Comma-separated modifiers: Ctrl, Alt, Shift, Meta
+  --wait-for-element      Wait for element to be available if selector provided (default: true)
+  --no-wait              Don't wait for element
+  --timeout <ms>         Timeout for waiting for element (default: 5000ms)
+
+Examples:
+  # Press Enter key
+  press_key "Enter"
+
+  # Press Enter in a specific input field
+  press_key "Enter" --selector "#search-input"
+
+  # Press Ctrl+A to select all
+  press_key "a" --modifiers Ctrl
+
+  # Press Escape key
+  press_key "Escape"
+
+  # Press arrow keys for navigation
+  press_key "ArrowDown"
+  press_key "ArrowUp"
+
+  # Type a character in focused element
+  press_key "a"
+
+  # Press Tab to navigate
+  press_key "Tab"
+
+  # Press with multiple modifiers
+  press_key "s" --modifiers Ctrl,Shift
+
+Supported Keys:
+  - Letters: a-z, A-Z
+  - Numbers: 0-9
+  - Special: Enter, Escape, Tab, Backspace, Delete, Space
+  - Arrows: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
+  - Navigation: Home, End, PageUp, PageDown
+  - Modifiers: Ctrl, Alt, Shift, Meta
+
+Note:
+  - Uses JavaScript KeyboardEvent simulation
+  - Dispatches keydown, keypress (for printable chars), and keyup events
+  - For input fields, automatically updates value and triggers input/change events
+  - If selector is provided, focuses the element first
+  - Works with keyboard event listeners and form validation
+`;
+    }
+}
+exports.PressKeyHandler = PressKeyHandler;