chrometools-mcp 1.9.1 → 2.3.2

package/CHANGELOG.md

@@ -2,6 +2,311 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.3.2] - 2025-12-25
+
+### Changed
+- **appendScenarioToFile** - Simplified architecture: MCP server no longer reads test files
+  - Removed `FileAppender.validateFile()` and `FileAppender.readFile()` calls
+  - Removed `generator.appendTest()` call - no longer merges content server-side
+  - Returns only test code (without imports) via `testCode` field
+  - Changed `action: "write_file"` → `action: "append_test"` (more accurate description)
+  - Claude Code now responsible for reading file, appending test, and writing back
+  - Clearer separation of concerns: MCP generates code, Claude Code handles file I/O
+  - Location: `index.js:2126-2215`
+
+## [2.3.1] - 2024-12-25
+
+### Fixed
+- **executeScenario** - Fixed scenario execution when current page URL doesn't match scenario's entryUrl
+  - Added automatic navigation to entryUrl before executing scenario
+  - Normalizes URLs for comparison (ignores trailing slashes, query params like `nr`, `redirect_ts`)
+  - Prevents timeout errors when scenario expects different page than currently open
+  - Example: If scenario recorded on `ya.ru` but current page is `ya.ru/search/`, automatically navigates to `ya.ru`
+  - Logs navigation events to console for debugging
+  - Location: `index.js:1951-1987`
+
+- **appendScenarioToFile** - Unified response format with exportScenarioAsCode for better Claude Code compatibility
+  - Changed `action: "append_to_file"` → `action: "write_file"` (clearer action)
+  - Changed `updatedContent` → `testCode` (same field name as exportScenarioAsCode)
+  - Added `content` field (duplicate of testCode for compatibility)
+  - Simplified instruction: single-step "Write the testCode..." instead of two-step "Read... then write..."
+  - Improved error message when file not found: now suggests using exportScenarioAsCode instead
+  - Location: `index.js:2191-2229`
+
+## [2.3.0] - 2024-12-25
+
+### Breaking Changes
+- **exportScenarioAsCode** - Removed append-to-file functionality to eliminate confusion
+  - **REMOVED** parameters: `appendToFile`, `testName`, `insertPosition`, `referenceTestName`
+  - Now exclusively creates NEW test files (returns JSON with `action: "create_new_file"`)
+  - Returns JSON format with `action`, `suggestedFileName`, `testCode`, `instruction` fields
+  - Claude Code writes files based on returned JSON (MCP server no longer writes files directly)
+  - Migration: Use new `appendScenarioToFile` tool instead of `appendToFile` parameter
+
+### Added
+- **appendScenarioToFile** - NEW tool for appending tests to existing files
+  - Parameters: `scenarioName`, `language`, `targetFile` (required)
+  - Optional: `testName`, `insertPosition`, `referenceTestName`, `cleanSelectors`, `includeComments`, `generatePageObject`, `pageObjectClassName`
+  - Returns JSON with `action: "append_to_file"`, `targetFile`, `updatedContent`, `instruction`
+  - Safely appends tests without overwriting existing tests
+  - Claude Code writes updated file content based on returned JSON
+  - Location: `index.js:2041-2186`, `server/tool-definitions.js:577-628`
+
+### Changed
+- **exportScenarioAsCode** - Changed return format from plain text to structured JSON
+  - Returns: `{action, suggestedFileName, testCode, instruction, pageObject?}`
+  - Suggests filename based on scenario name and language
+  - Includes clear instructions for Claude Code to create files
+  - Location: `index.js:2188-2357`, `server/tool-definitions.js:542-576`
+- **File writing responsibility** - Moved from MCP server to Claude Code
+  - MCP tools now return JSON with file content + instructions
+  - Claude Code uses Write tool to create/update files
+  - Eliminates risk of MCP server directly overwriting files
+
+### Documentation
+- **README.md** - Split exportScenarioAsCode documentation into two sections
+  - exportScenarioAsCode: For creating new test files
+  - appendScenarioToFile: For appending to existing files
+  - Updated tool count: 39+ → 40+ tools
+  - Added clear examples for both tools with JSON response formats
+  - Location: `README.md:11,17,652-806`
+
+## [2.2.1] - 2024-12-24
+
+### Improved
+- **exportScenarioAsCode** - Clarified tool description to prevent accidental test file overwrites
+  - Added explicit warning: default mode (without `appendToFile`) returns code for NEW file
+  - Emphasized that `appendToFile` parameter is **REQUIRED** to safely add tests to existing files
+  - Updated `appendToFile` parameter description to highlight safety aspect
+  - Updated `insertPosition` and `referenceTestName` descriptions to clarify they only work with `appendToFile`
+  - Added warning section in README.md documentation
+  - Location: `server/tool-definitions.js:544,575-589`, `README.md:667-669`
+
+## [2.2.0] - 2025-12-21
+
+### Added
+- **Page Object Model (POM) Generator** - New `generatePageObject` MCP tool for automated Page Object creation
+  - Analyzes current page and extracts interactive elements (inputs, buttons, links, etc.)
+  - Smart selector generation: prioritizes id > name > data-testid > unique class > CSS path
+  - Auto-generates meaningful element names from labels, placeholders, text content
+  - Groups elements by semantic sections (header, nav, form, footer, etc.)
+  - Supports 4 frameworks: Playwright TypeScript/Python, Selenium Python/Java
+  - Generates helper methods automatically (fill/click methods for common actions)
+  - Example: `generatePageObject({ framework: 'playwright-typescript' })`
+  - Location: `recorder/page-object-generator.js`, `index.js:46,2098-2136`
+
+- **Page Object Integration in exportScenarioAsCode** - Optional Page Object generation when exporting scenarios
+  - New parameter `generatePageObject` (default: false) to generate both test code and Page Object class
+  - New parameter `pageObjectClassName` for custom Page Object class names
+  - Opens scenario's entry URL and analyzes page structure automatically
+  - Returns JSON with both `testCode` and `pageObjectCode` when enabled
+  - Example: `exportScenarioAsCode({ scenarioName: "login", language: "playwright-typescript", generatePageObject: true })`
+  - Location: `index.js:2090-2186`, `server/tool-schemas.js:281-282`, `server/tool-definitions.js:565-572`
+
+- **Append Mode for exportScenarioAsCode** - Ability to append generated tests to existing test files
+  - New parameter `appendToFile`: Path to existing test file to append to (enables append mode)
+  - New parameter `testName`: Override test name (default: from scenario name)
+  - New parameter `insertPosition`: Where to insert test - 'end' (default), 'before', or 'after' a reference test
+  - New parameter `referenceTestName`: Reference test name for 'before'/'after' insertion
+  - Supports all 4 frameworks: Playwright TypeScript/Python, Selenium Python/Java
+  - Automatic file validation (extension must match language)
+  - Automatic backup before file modification (.backup extension)
+  - Smart test name conversion (camelCase for Java, snake_case for Python, kebab-case for TypeScript)
+  - Framework-specific parsing: brace counting for TypeScript/Java, indentation-based for Python
+  - PEP 8 compliance: 2 blank lines between Python functions
+  - Example: `exportScenarioAsCode({ scenarioName: "new_test", language: "playwright-typescript", appendToFile: "./tests/suite.spec.ts" })`
+  - Location: `utils/code-generators/file-appender.js` (new 177 lines), `index.js:2044-2116`, `server/tool-schemas.js:283-286`, `utils/code-generators/*.js`
+
+### Fixed
+- **Dependency Resolution with projectId** - Fixed collision errors when executing scenarios with dependencies
+  - Dependencies now correctly inherit parent scenario's projectId when not explicitly specified
+  - Explicit dependency projectId in metadata takes precedence over inherited value
+  - Fixes error: "Dependency 'test': Multiple scenarios named 'test' found"
+  - Location: `recorder/scenario-executor.js:63-119`
+
+## [2.1.1] - 2025-12-21
+
+### Fixed
+- **executeScenario Timeout Fix** - Prevents hanging when no browser tab is attached
+  - Auto-opens browser at scenario's entryUrl if no page is open
+  - Added timeout protection (1s) for page state checks to prevent hanging on `isClosed()`
+  - Added 30s timeout for browser opening operation
+  - Added 5min timeout for scenario execution with clear error messages
+  - Location: `browser/page-manager.js:255-290`, `index.js:1875-1955`
+
+- **URL Validation Fix** - Fixed false negative in scenario exit URL validation
+  - Added 500ms wait before URL check to allow navigation/redirects to complete
+  - Changed from `page.url()` to `page.evaluate(() => window.location.href)` for more reliable current URL
+  - Fixes issue where correct URL was reported as wrong due to timing
+  - Location: `recorder/scenario-executor.js:186-191`
+
+- **Global Timeout Protection** - All MCP tools now protected from hanging
+  - Added `executeToolWithTimeout()` wrapper for all tool calls
+  - Default timeout: 2 minutes for regular tools, 6 minutes for executeScenario
+  - Tools return clear error messages instead of hanging indefinitely
+  - Location: `index.js:183-217`
+
+### Changed
+- **Code Refactoring** - Reduced index.js from 3761 to 2093 lines (-44%)
+  - Extracted tool schemas to `server/tool-schemas.js` (34 schemas, 282 lines)
+  - Extracted tool definitions to `server/tool-definitions.js` (41 tools, 569 lines)
+  - Extracted browser management to `browser/browser-manager.js` (207 lines)
+  - Extracted page management to `browser/page-manager.js` (268 lines)
+  - Extracted image processing to `utils/image-processing.js` (254 lines)
+  - Extracted CSS utilities to `utils/css-utils.js` (163 lines)
+  - Extracted platform utilities to `utils/platform-utils.js` (63 lines)
+  - Better code organization and maintainability
+
+## [2.1.0] - 2025-12-21
+
+### Added
+- **Name Collision Detection** - Smart handling of scenarios with same name across different projects
+  - `executeScenario` now detects when multiple scenarios share the same name
+  - Returns helpful error with list of available `projectId` values
+  - Optional `projectId` parameter to disambiguate: `executeScenario({ name: "login", projectId: "google" })`
+  - Location: `recorder/scenario-storage.js:111-163`, `recorder/scenario-executor.js:33,49-61,86-90`, `index.js:1677,3558-3571,3597-3600`
+
+### Changed
+- **URL-Based Scenario Organization** - Scenarios now organized by website domain instead of file system project
+  - Project ID automatically extracted from URL where recording starts: `https://google.com` → `google`
+  - Main domain only (subdomains stripped): `mail.google.com` → `google`
+  - Ports included for ALL domains: `localhost:3000` → `localhost-3000`, `example.com:8080` → `example-8080`
+  - Protocol ignored: `http` and `https` both map to same projectId
+  - File URLs: `file:///` → `local`
+  - Location: `utils/url-to-project.js`, `recorder/recorder-script.js:30-78`
+
+- **Global Scenario Access** - All tools now return scenarios from ALL websites
+  - `listScenarios()` returns ALL scenarios with `projectId`, `entryUrl`, `exitUrl` metadata
+  - `searchScenarios()` searches ALL scenarios across all websites
+  - Agent can filter results by `projectId`, `entryUrl`, or `exitUrl` as needed
+  - Removed `allProjects` parameter (no longer needed, always returns all)
+  - Location: `index.js:3586-3610`
+
+- **Simplified API** - Recorder no longer depends on file system project detection
+  - `injectRecorder()` signature changed from `(page, projectDir, projectId, projectPath)` to `(page)`
+  - Project ID determined automatically from page URL in browser context
+  - Removed dependency on `utils/project-detector.js`
+  - Location: `recorder/recorder-script.js:1710-1763`, `index.js:3512-3533`
+
+### Added
+- **URL Normalization Utilities** - New module for extracting project ID from URLs
+  - `urlToProjectId(url)` - Extract and sanitize domain-based project ID
+  - `sanitizeProjectId(id)` - Clean project IDs (lowercase, alphanumeric, hyphens)
+  - Browser-compatible version injected into recorder widget
+  - Location: `utils/url-to-project.js`
+
+### Migration
+- **Automatic v2.1.0 Migration** - Old project-based scenarios removed on first run
+  - Deletes `~/.config/chrometools-mcp/projects/` directory from v2.0
+  - Deletes old global index
+  - Creates `.migration-v2.1.0-done` flag file
+  - One-time migration, starts fresh with URL-based organization
+  - Location: `index.js:780-811`
+
+### Removed
+- **Removed `utils/project-detector.js`** - No longer needed for URL-based organization
+- **Removed helper functions** - `getProjectId()`, `getProjectDir()`, `getCurrentProjectDir()`
+- **Removed old scenarios** - All v2.0 scenarios deleted during migration
+
+### Documentation
+- **Updated README.md** - Complete rewrite of Recorder Tools section
+  - Explained URL-based storage approach with examples
+  - Updated all tool descriptions and examples
+  - Documented domain extraction rules
+  - Added filtering examples for agents
+  - Location: `README.md:507-618`
+
+## [2.0.2] - 2025-12-21
+
+### Fixed
+- **Project Detection for VS Code** - Improved project root detection for IDE environments
+  - Added support for `INIT_CWD` and `npm_config_local_prefix` environment variables
+  - Added `findProjectRootByMarkers()` to detect project by package.json, pom.xml, etc.
+  - Walks up parent directories to find Git root when cwd is IDE installation
+  - Now correctly detects `C:\prj\automation` instead of `Microsoft VS Code` when running in VS Code
+  - Location: `utils/project-detector.js:38-68`, `utils/project-detector.js:85-140`
+
+### Added
+- **Enhanced Project Detection Strategy** - Multiple fallback mechanisms for project root detection
+  - Priority: CLAUDE_PROJECT_DIR → PROJECT_DIR → INIT_CWD → npm prefix → Git root → markers → parent Git → cwd
+  - Supports 8+ project markers: package.json, pom.xml, build.gradle, Cargo.toml, go.mod, etc.
+  - Better logging with `console.error` for debugging project detection
+
+### Documentation
+- **VS Code Setup Guide** - Add instructions for setting PROJECT_DIR in MCP config for VS Code users
+
+## [2.0.1] - 2025-12-21
+
+### Fixed
+- **Recorder Auto-Reinjection** - Fixed critical bug where recorder widget didn't reinject after page navigation
+  - Updated `setupRecorderAutoReinjection()` to use new v2.0 API signature
+  - Fixed both navigation (`framenavigated`) and reload (`load`) event handlers
+  - Recorder now correctly passes `projectDir`, `projectId`, and `projectPath` instead of deprecated `baseDir`
+  - Location: `index.js:483-486`, `index.js:499-502`
+
+## [2.0.0] - 2025-12-21
+
+### Breaking Changes
+- **Project-Based Scenario Storage** - Complete restructuring of scenario storage system
+  - Scenarios now stored in `~/.config/chrometools-mcp/projects/{projectName}/scenarios/`
+  - Each project has its own isolated scenario storage
+  - Automatic project detection via `detectProjectRoot()` (CLAUDE_PROJECT_DIR → PROJECT_DIR → git root → cwd)
+  - Global index file at `~/.config/chrometools-mcp/index.json` for fast scenario discovery
+  - Scenarios include `projectId` and `projectPath` in metadata
+  - Old scenarios in `~/.config/chrometools-mcp/scenarios/` will no longer be accessible
+  - Location: `index.js:66-159`, `recorder/scenario-storage.js`
+
+- **Removed `directory` parameter** - All scenario tools no longer accept explicit directory parameter
+  - Removed from: `enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`
+  - Project directory is now automatically determined
+  - Simplifies API and improves consistency
+  - Location: `index.js:1659-1750` (tool definitions)
+
+### Added
+- **Global Scenario Index** - Fast O(1) scenario lookups without filesystem scanning
+  - Location: `~/.config/chrometools-mcp/index.json`
+  - Contains all projects and their scenarios
+  - Enables quick discovery of scenarios across all projects
+  - AI-friendly: agents can read global index to understand all available scenarios
+  - Location: `index.js:103-159`, `recorder/scenario-storage.js:23-136`
+
+- **Multi-Project Filtering** - New `allProjects` parameter for `listScenarios` and `searchScenarios`
+  - `allProjects: false` (default) - shows only current project's scenarios
+  - `allProjects: true` - shows scenarios from all projects
+  - Enables cross-project scenario discovery and reuse
+  - Location: `index.js:1685`, `index.js:1697`, `recorder/scenario-storage.js:385-453`
+
+- **Cross-Project Dependency Support** - Scenarios can depend on scenarios from other projects
+  - Dependencies automatically resolved across projects via global index
+  - Enables scenario reuse between projects
+  - Location: `recorder/scenario-executor.js:27-121`
+
+- **Storage Path in Tool Descriptions** - All scenario tools now document storage location
+  - Every tool description includes: "Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/"
+  - Helps AI agents understand where to find scenarios
+  - Includes reference to global index location
+  - Location: `index.js:1660`, `index.js:1668`, `index.js:1681`, etc.
+
+### Changed
+- **Scenario Storage Functions** - Updated all storage functions for new architecture
+  - `saveScenario(scenario, projectId, projectPath)` - now requires project info instead of baseDir
+  - `loadScenario(name, includeSecrets, projectId)` - searches globally, optional project filter
+  - `listScenarios(projectId, allProjects)` - reads from global index
+  - `searchScenarios(query, projectId, allProjects)` - searches global index
+  - `deleteScenario(name, projectId)` - finds and deletes from correct project
+  - Location: `recorder/scenario-storage.js:191-500`
+
+- **Recorder Injection** - Updated to pass project information
+  - `injectRecorder(page, projectDir, projectId, projectPath)` - now accepts project details
+  - Scenarios saved with project context automatically
+  - Location: `recorder/recorder-script.js:1659`
+
+### Migration Guide
+- **Old scenarios are inaccessible** - Scenarios in `~/.config/chrometools-mcp/scenarios/` will no longer be found
+  - To migrate: Manually move scenarios to new structure or re-record them
+  - New structure: `~/.config/chrometools-mcp/projects/{projectName}/scenarios/`
+- **No code changes needed** - All changes are internal, MCP tool interface remains compatible (except removed `directory` parameter)
+
 ## [1.9.1] - 2025-12-19
 
 ### Fixed