cursorflow 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

cursorflow/core/config_validator.py

@@ -0,0 +1,216 @@
+"""
+Configuration Validation
+
+Validates user-provided configuration against Playwright API.
+Provides clear error messages with links to documentation.
+"""
+
+from typing import Dict, Any, Set
+import logging
+
+
+class ConfigValidationError(Exception):
+    """Raised when configuration is invalid"""
+    pass
+
+
+class ConfigValidator:
+    """
+    Validates CursorFlow and Playwright configuration
+    
+    Strategy: We don't strictly validate - we warn about likely errors
+    and let Playwright do final validation. This keeps us forward-compatible.
+    """
+    
+    # Common browser launch options (for helpful warnings)
+    # See: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch
+    KNOWN_BROWSER_OPTIONS = {
+        'args', 'channel', 'chromium_sandbox', 'devtools', 'downloads_path',
+        'env', 'executable_path', 'firefox_user_prefs', 'handle_sigint',
+        'handle_sigterm', 'handle_sighup', 'headless', 'ignore_default_args',
+        'proxy', 'slow_mo', 'timeout', 'traces_dir'
+    }
+    
+    # Common context options (for helpful warnings)
+    # See: https://playwright.dev/python/docs/api/class-browser#browser-new-context
+    KNOWN_CONTEXT_OPTIONS = {
+        'accept_downloads', 'base_url', 'bypass_csp', 'color_scheme',
+        'device_scale_factor', 'extra_http_headers', 'forced_colors',
+        'geolocation', 'has_touch', 'http_credentials', 'ignore_https_errors',
+        'is_mobile', 'java_script_enabled', 'locale', 'no_viewport',
+        'offline', 'permissions', 'proxy', 'record_har_content',
+        'record_har_mode', 'record_har_omit_content', 'record_har_path',
+        'record_har_url_filter', 'record_video_dir', 'record_video_size',
+        'reduced_motion', 'screen', 'service_workers', 'storage_state',
+        'strict_selectors', 'timezone_id', 'user_agent', 'viewport'
+    }
+    
+    @classmethod
+    def validate_browser_options(cls, options: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate browser launch options
+        
+        Args:
+            options: User-provided browser options
+            
+        Returns:
+            Validated options (unchanged - just warnings logged)
+        """
+        logger = logging.getLogger(__name__)
+        
+        # Warn about unknown options (might be typos)
+        for key in options.keys():
+            if key not in cls.KNOWN_BROWSER_OPTIONS:
+                logger.warning(
+                    f"Unknown browser option '{key}' - will pass to Playwright anyway. "
+                    f"Check spelling or see: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch"
+                )
+        
+        # Validate specific option types
+        if 'headless' in options and not isinstance(options['headless'], bool):
+            raise ConfigValidationError(
+                f"'headless' must be boolean, got {type(options['headless']).__name__}: {options['headless']}"
+            )
+        
+        if 'timeout' in options and not isinstance(options['timeout'], (int, float)):
+            raise ConfigValidationError(
+                f"'timeout' must be number, got {type(options['timeout']).__name__}: {options['timeout']}"
+            )
+        
+        if 'args' in options and not isinstance(options['args'], list):
+            raise ConfigValidationError(
+                f"'args' must be list of strings, got {type(options['args']).__name__}"
+            )
+        
+        return options
+    
+    @classmethod
+    def validate_context_options(cls, options: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Validate browser context options
+        
+        Args:
+            options: User-provided context options
+            
+        Returns:
+            Validated options (unchanged - just warnings logged)
+        """
+        logger = logging.getLogger(__name__)
+        
+        # Warn about unknown options
+        for key in options.keys():
+            if key not in cls.KNOWN_CONTEXT_OPTIONS:
+                logger.warning(
+                    f"Unknown context option '{key}' - will pass to Playwright anyway. "
+                    f"Check spelling or see: https://playwright.dev/python/docs/api/class-browser#browser-new-context"
+                )
+        
+        # Validate specific option types
+        if 'viewport' in options:
+            viewport = options['viewport']
+            if not isinstance(viewport, dict):
+                raise ConfigValidationError(
+                    f"'viewport' must be dict with width/height, got {type(viewport).__name__}"
+                )
+            if 'width' in viewport and not isinstance(viewport['width'], int):
+                raise ConfigValidationError(
+                    f"viewport width must be integer, got {type(viewport['width']).__name__}"
+                )
+            if 'height' in viewport and not isinstance(viewport['height'], int):
+                raise ConfigValidationError(
+                    f"viewport height must be integer, got {type(viewport['height']).__name__}"
+                )
+        
+        if 'geolocation' in options:
+            geo = options['geolocation']
+            if not isinstance(geo, dict) or 'latitude' not in geo or 'longitude' not in geo:
+                raise ConfigValidationError(
+                    f"'geolocation' must be dict with latitude/longitude: "
+                    f"{{'latitude': 40.7128, 'longitude': -74.0060}}"
+                )
+        
+        if 'timezone_id' in options and not isinstance(options['timezone_id'], str):
+            raise ConfigValidationError(
+                f"'timezone_id' must be string like 'America/New_York', got {type(options['timezone_id']).__name__}"
+            )
+        
+        return options
+    
+    @classmethod
+    def get_config_examples(cls) -> str:
+        """Get example configurations for documentation"""
+        return """
+Browser Configuration Examples:
+
+  Enable DevTools (non-headless):
+    {
+      "headless": false,
+      "browser_launch_options": {
+        "devtools": true
+      }
+    }
+  
+  Use specific Chrome channel:
+    {
+      "browser_launch_options": {
+        "channel": "chrome"
+      }
+    }
+  
+  Custom proxy:
+    {
+      "browser_launch_options": {
+        "proxy": {
+          "server": "http://myproxy.com:3128",
+          "username": "user",
+          "password": "pass"
+        }
+      }
+    }
+
+Context Configuration Examples:
+
+  Test in dark mode:
+    {
+      "context_options": {
+        "color_scheme": "dark"
+      }
+    }
+  
+  Test with geolocation:
+    {
+      "context_options": {
+        "geolocation": {"latitude": 40.7128, "longitude": -74.0060},
+        "permissions": ["geolocation"]
+      }
+    }
+  
+  Test offline behavior:
+    {
+      "context_options": {
+        "offline": true
+      }
+    }
+  
+  Custom timezone:
+    {
+      "context_options": {
+        "timezone_id": "America/Los_Angeles"
+      }
+    }
+  
+  HTTP authentication:
+    {
+      "context_options": {
+        "http_credentials": {
+          "username": "admin",
+          "password": "secret"
+        }
+      }
+    }
+
+See Playwright documentation for all available options:
+  Browser: https://playwright.dev/python/docs/api/class-browsertype#browser-type-launch
+  Context: https://playwright.dev/python/docs/api/class-browser#browser-new-context
+"""
+

cursorflow/core/cursorflow.py

@@ -669,6 +669,15 @@ class CursorFlow:
     
     async def _execute_actions(self, actions: List[Dict]) -> bool:
         """Execute list of declarative actions"""
+        # Validate all actions before execution
+        from .action_validator import ActionValidator, ActionValidationError
+        
+        try:
+            actions = ActionValidator.validate_list(actions)
+        except ActionValidationError as e:
+            self.logger.error(f"Action validation failed: {e}")
+            return False
+        
         try:
             for action in actions:
                 await self._execute_single_action(action)
@@ -678,44 +687,26 @@ class CursorFlow:
             return False
     
     async def _execute_single_action(self, action: Dict):
-        """Execute a single declarative action and track it"""
+        """
+        Execute a single declarative action and track it
+        
+        Pass-through architecture: CursorFlow handles a few special actions,
+        then passes everything else directly to Playwright Page API.
+        """
         action_start = time.time()
         
         try:
-            # Navigation actions
-            if "navigate" in action:
+            # Extract action type
+            action_type = action.get('type') or list(action.keys())[0]
+            
+            # CursorFlow-specific actions (not direct Playwright methods)
+            if action_type == "navigate":
                 url = action["navigate"]
                 if isinstance(url, dict):
                     url = url["url"]
                 await self.browser.navigate(url)
                 
-            # Interaction actions
-            elif "click" in action:
-                selector = action["click"]
-                if isinstance(selector, dict):
-                    selector = selector["selector"]
-                await self.browser.click(selector)
-                
-            elif "fill" in action:
-                config = action["fill"]
-                await self.browser.fill(config["selector"], config["value"])
-                
-            elif "type" in action:
-                config = action["type"]
-                await self.browser.type(config["selector"], config["text"])
-                
-            # Waiting actions
-            elif "wait" in action:
-                await asyncio.sleep(action["wait"])
-                
-            elif "wait_for" in action:
-                selector = action["wait_for"]
-                if isinstance(selector, dict):
-                    selector = selector["selector"]
-                await self.browser.wait_for_element(selector)
-                
-            # Capture actions
-            elif "screenshot" in action:
+            elif action_type == "screenshot":
                 screenshot_config = action["screenshot"]
                 
                 # Handle both string and dict formats
@@ -734,15 +725,19 @@ class CursorFlow:
                 screenshot_data = await self.browser.screenshot(name, options)
                 self.artifacts["screenshots"].append(screenshot_data)
                 
-            elif "authenticate" in action:
+            elif action_type == "authenticate":
                 if self.auth_handler:
                     await self.auth_handler.authenticate(self.browser.page, action["authenticate"])
+            
+            # Pass-through to Playwright Page API (hover, dblclick, press, etc.)
+            else:
+                await self._execute_playwright_action(action_type, action)
                     
             # Record action in timeline
             self.timeline.append({
                 "timestamp": action_start,
                 "type": "browser",
-                "event": list(action.keys())[0],
+                "event": action_type,
                 "data": action,
                 "duration": time.time() - action_start
             })
@@ -751,6 +746,47 @@ class CursorFlow:
             self.logger.error(f"Action failed: {action}, error: {e}")
             raise
     
+    async def _execute_playwright_action(self, action_type: str, action: Dict):
+        """
+        Pass-through to Playwright Page API
+        
+        Enables using any Playwright method without hardcoding them:
+        - hover, dblclick, drag_and_drop
+        - press, focus, blur, check, uncheck
+        - evaluate, route, expose_function
+        - And 90+ more methods
+        
+        See: https://playwright.dev/python/docs/api/class-page
+        """
+        # Get the action config
+        action_config = action.get(action_type)
+        
+        # Check if method exists on Playwright Page
+        if hasattr(self.browser.page, action_type):
+            method = getattr(self.browser.page, action_type)
+            
+            # Call with appropriate args based on config format
+            if isinstance(action_config, str):
+                # Simple format: {"hover": ".selector"}
+                await method(action_config)
+            elif isinstance(action_config, dict):
+                # Config format: {"hover": {"selector": ".item", "timeout": 5000}}
+                await method(**action_config)
+            elif action_config is None:
+                # No args: {"reload": null}
+                await method()
+            else:
+                # Numeric or other: {"wait": 2}
+                await method(action_config)
+        else:
+            # Method doesn't exist on Page - provide helpful error
+            available_methods = [m for m in dir(self.browser.page) if not m.startswith('_') and callable(getattr(self.browser.page, m))]
+            raise AttributeError(
+                f"Unknown Playwright action: '{action_type}'\n"
+                f"Available methods: {', '.join(sorted(available_methods[:20]))}...\n"
+                f"Full API: https://playwright.dev/python/docs/api/class-page"
+            )
+    
     async def _cleanup_session(self, session_options: Dict):
         """Clean up browser session"""
         try:

cursorflow/install_cursorflow_rules.py

@@ -80,10 +80,9 @@ def install_cursorflow_rules(project_dir: str = ".", force: bool = False):
     setup_update_checking(project_path)
     
     print(f"\n📝 Next steps:")
-    print(f"   1. Review cursorflow-config.json and update for your project")
-    print(f"   2. Install CursorFlow: pip install cursorflow")
-    print(f"   3. Install Playwright: playwright install chromium")
-    print(f"   4. Start using CursorFlow for UI testing and CSS iteration!")
+    print(f"   1. Review .cursorflow/config.json and update for your project")
+    print(f"   2. Install Playwright: playwright install chromium")
+    print(f"   3. Start using CursorFlow for UI testing and CSS iteration!")
     print(f"\n🔄 Update commands:")
     print(f"   - Check for updates: python -m cursorflow check-updates")
     print(f"   - Update CursorFlow: python -m cursorflow update")
@@ -120,18 +119,22 @@ cursorflow_session_*.json
 def create_config_template(project_path: Path, force: bool = False):
     """Create or update CursorFlow configuration template"""
     
-    config_path = project_path / "cursorflow-config.json"
+    # Create .cursorflow directory if it doesn't exist
+    cursorflow_dir = project_path / ".cursorflow"
+    cursorflow_dir.mkdir(exist_ok=True)
+    
+    config_path = cursorflow_dir / "config.json"
     
     # Get current version
     try:
         import cursorflow
-        current_version = getattr(cursorflow, '__version__', '2.1.5')
+        current_version = getattr(cursorflow, '__version__', '2.2.0')
     except ImportError:
-        current_version = '2.1.5'
+        current_version = '2.2.0'
     
     if config_path.exists():
         if not force:
-            print("ℹ️  cursorflow-config.json already exists (use --force to recreate)")
+            print("ℹ️  .cursorflow/config.json already exists (use --force to recreate)")
             # Smart update: only update version and add missing fields
             try:
                 with open(config_path) as f:
@@ -198,7 +201,7 @@ def create_config_template(project_path: Path, force: bool = False):
         json.dump(config_template, f, indent=2)
     
     action = "Recreated" if force else "Created"
-    print(f"✅ {action} configuration template: cursorflow-config.json")
+    print(f"✅ {action} configuration: .cursorflow/config.json")
     print(f"   Detected project type: {project_type}")
     print(f"   CursorFlow version: {current_version}")
 
@@ -302,9 +305,9 @@ def setup_update_checking(project_path: Path):
     # Create initial version tracking
     try:
         import cursorflow
-        current_version = getattr(cursorflow, '__version__', '2.1.5')
+        current_version = getattr(cursorflow, '__version__', '2.2.0')
     except ImportError:
-        current_version = '2.1.5'
+        current_version = '2.2.0'
     
     version_info = {
         "installed_version": current_version,

cursorflow/log_sources/local_file.py

@@ -168,8 +168,27 @@ class LocalFileLogSource:
         """Connect to log sources - compatibility method for log_collector"""
         return await self.start_monitoring()
     
+    async def get_new_entries(self) -> List[Dict]:
+        """
+        Get new log entries since last call (required interface method)
+        
+        Returns:
+            List of log entry dicts with timestamp, content, source
+        """
+        new_entries = []
+        
+        # Drain queue of all available entries
+        while not self.log_queue.empty():
+            try:
+                log_entry = self.log_queue.get_nowait()
+                new_entries.append(log_entry)
+            except queue.Empty:
+                break
+        
+        return new_entries
+    
     def get_recent_logs(self, seconds: int = 10) -> List[Dict]:
-        """Get logs from the last N seconds"""
+        """Get logs from the last N seconds (non-destructive)"""
         from datetime import timedelta
         
         cutoff_time = datetime.now() - timedelta(seconds=seconds)

cursorflow/log_sources/ssh_remote.py

@@ -165,6 +165,25 @@ class SSHRemoteLogSource:
         """Connect to SSH log sources - compatibility method for log_collector"""
         return await self.start_monitoring()
     
+    async def get_new_entries(self) -> List[Dict]:
+        """
+        Get new log entries since last call (required interface method)
+        
+        Returns:
+            List of log entry dicts with timestamp, content, source
+        """
+        new_entries = []
+        
+        # Drain queue of all available entries
+        while not self.log_queue.empty():
+            try:
+                log_entry = self.log_queue.get_nowait()
+                new_entries.append(log_entry)
+            except queue.Empty:
+                break
+        
+        return new_entries
+    
     def get_recent_logs(self, seconds: int = 10) -> List[Dict]:
         """Get logs from the last N seconds without stopping monitoring"""
         

cursorflow/rules/cursorflow-installation.mdc

@@ -1,6 +1,7 @@
 ---
 title: CursorFlow Installation & Setup Guide for Cursor
 description: How to install and configure CursorFlow for complete page intelligence in AI-driven development
+alwaysApply: true
 ---
 
 # CursorFlow Installation & Setup Guide for Cursor
@@ -24,7 +25,7 @@ CursorFlow requires **TWO installations**:
    This step created THIS FILE you're reading right now.
 
 **If Cursor reports "command not found: cursorflow"**, the user needs Step 1.  
-**If you can run cursorflow but tests fail**, check `cursorflow-config.json` in project root.
+**If you can run cursorflow but tests fail**, check `.cursorflow/config.json` configuration.
 
 ## 🚀 **When to Install CursorFlow**
 

cursorflow/rules/cursorflow-usage.mdc

@@ -1,6 +1,12 @@
+---
+title: CursorFlow CLI Usage Guide for Cursor AI
+description: Complete guide for using CursorFlow CLI with comprehensive page intelligence and data collection
+alwaysApply: true
+---
+
 # CursorFlow Usage Rules for Cursor AI
 
-## 🔥 **CursorFlow 2.1.4: Complete Page Intelligence for AI-Driven Development**
+## 🔥 **CursorFlow: Complete Page Intelligence for AI-Driven Development**
 
 **CursorFlow provides comprehensive data collection for rapid UI iteration:**
 

cursorflow/updater.py

@@ -363,7 +363,7 @@ class CursorFlowUpdater:
     
     async def _migrate_configuration(self) -> bool:
         """Migrate configuration to new format if needed"""
-        config_file = self.project_dir / "cursorflow-config.json"
+        config_file = self.project_dir / ".cursorflow" / "config.json"
         
         if not config_file.exists():
             return True
@@ -417,9 +417,10 @@ class CursorFlowUpdater:
         backup_path = backup_dir / backup_name
         
         # Backup configuration and rules
-        if (self.project_dir / "cursorflow-config.json").exists():
+        config_file = self.project_dir / ".cursorflow" / "config.json"
+        if config_file.exists():
             shutil.copy2(
-                self.project_dir / "cursorflow-config.json",
+                config_file,
                 backup_path.with_suffix('.config.json')
             )
         

{cursorflow-2.1.5.dist-info → cursorflow-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.1.5
+Version: 2.2.0
 Summary: 🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis
 Author-email: GeekWarrior Development <rbush@cooltheory.com>
 License-Expression: MIT
@@ -82,20 +82,57 @@ When CursorFlow reports `"average_response_time": 416.58ms`, you can tell stakeh
 
 **Documentary vs Movie:** Both are valuable, but if you're trying to understand reality, you watch the documentary. CursorFlow is the documentary of web testing.
 
+## 🎯 Pass-Through Architecture
+
+CursorFlow doesn't limit you - it exposes the full power of Playwright:
+
+**94+ Playwright actions available:**
+```bash
+# Any Playwright Page method works
+cursorflow test --actions '[
+  {"hover": ".menu"},
+  {"dblclick": ".editable"},
+  {"press": "Enter"},
+  {"drag_and_drop": {"source": ".item", "target": ".zone"}},
+  {"check": "#checkbox"},
+  {"evaluate": "window.scrollTo(0, 500)"}
+]'
+```
+
+**Full configuration pass-through:**
+```json
+{
+  "browser_config": {
+    "browser_launch_options": {"devtools": true, "channel": "chrome"}
+  },
+  "context_options": {
+    "color_scheme": "dark",
+    "geolocation": {"latitude": 40.7128, "longitude": -74.0060},
+    "timezone_id": "America/Los_Angeles"
+  }
+}
+```
+
+**Forward-compatible:** New Playwright features work immediately without CursorFlow updates.
+
+**See:** [Playwright API Documentation](https://playwright.dev/python/docs/api/class-page)
+
+---
+
 ## 🚀 Complete Page Intelligence
 
-Every screenshot captures everything your AI needs to make intelligent decisions:
+Every test captures everything needed for debugging:
 
 ### **📊 Comprehensive Data Collection**
-- **DOM**: All elements with 7 selector strategies each
-- **Network**: All requests, responses, and complete response bodies  
-- **Console**: All logs, errors, and smart error correlation
-- **Performance**: Load times, memory usage, with reliability indicators
-- **Visual**: Screenshots with pixel-perfect comparisons and enhanced options
-- **Fonts**: Loading status, performance, and usage analysis
-- **Animations**: Active animations and transitions tracking
-- **Resources**: Complete resource loading analysis
-- **Storage**: localStorage, sessionStorage, cookies, IndexedDB state
+- **DOM**: All elements with 7 selector strategies + event handlers
+- **Network**: Requests, responses, and complete request/response bodies  
+- **Console**: All logs, errors, warnings - displayed prominently
+- **JavaScript**: Global functions, variables, specific window objects
+- **Storage**: localStorage, sessionStorage, cookies (sensitive data masked)
+- **Forms**: All field values at capture time (passwords masked)
+- **Performance**: Load times, memory usage, reliability indicators
+- **Visual**: Screenshots with comprehensive page analysis
+- **Sessions**: Save/restore browser state for authenticated testing
 
 ### **🔄 Hot Reload Intelligence**
 - **Framework auto-detection** (Vite, Webpack, Next.js, Parcel, Laravel Mix)
@@ -148,20 +185,38 @@ playwright install chromium
 ```bash
 cd /path/to/your/project
 cursorflow install-rules
+
+# Or skip prompts for automation/CI
+cursorflow install-rules --yes
 ```
 
 This creates:
 - `.cursor/rules/` - Cursor AI integration rules
-- `cursorflow-config.json` - Project-specific configuration
+- `.cursorflow/config.json` - Project-specific configuration
 - `.cursorflow/` - Artifacts and session storage
 - `.gitignore` entries for CursorFlow artifacts
 
 ### Step 3: Start Testing
+
+**Simple page capture:**
 ```bash
-# Test real application behavior
-cursorflow test --base-url http://localhost:3000 --path "/dashboard"
+cursorflow test --base-url http://localhost:3000 --path /dashboard
+```
 
-# Get complete intelligence with custom actions
+**Interactive testing with inline actions:**
+```bash
+cursorflow test --base-url http://localhost:3000 \
+  --path /messages \
+  --wait-for ".message-item" \
+  --hover ".message-item:first-child" \
+  --click ".message-item:first-child" \
+  --screenshot "clicked" \
+  --show-console \
+  --open-trace
+```
+
+**Custom actions with JSON:**
+```bash
 cursorflow test --base-url http://localhost:3000 --actions '[
   {"navigate": "/login"},
   {"fill": {"selector": "#email", "value": "test@example.com"}},