cursorflow 1.3.7__py3-none-any.whl → 2.0.0__py3-none-any.whl

cursorflow/core/hmr_detector.py

@@ -0,0 +1,439 @@
+"""
+CursorFlow v2.0 Hot Module Replacement (HMR) Detection System
+
+This module provides intelligent detection and monitoring of Hot Module Replacement
+events across different development frameworks, enabling precision timing for CSS
+iteration workflows.
+
+Core Philosophy: Pure observation of HMR events - we listen but never trigger.
+"""
+
+import asyncio
+import json
+import logging
+import time
+from typing import Dict, List, Optional, Any, Callable
+from urllib.parse import urlparse
+import websockets
+from websockets.exceptions import ConnectionClosed, InvalidURI
+
+
+class HMRDetector:
+    """
+    v2.0 Enhancement: Intelligent Hot Module Replacement event detection
+    
+    Supports auto-detection and monitoring for:
+    - Vite (port 5173, WebSocket path /__vite_hmr)
+    - Webpack Dev Server (port 3000, WebSocket path /sockjs-node)
+    - Next.js (port 3000, WebSocket path /_next/webpack-hmr)
+    - Parcel (port 1234, WebSocket path /hmr)
+    - Laravel Mix (port 3000, WebSocket path /browser-sync/socket.io)
+    """
+    
+    def __init__(self, base_url: str):
+        self.base_url = base_url
+        self.logger = logging.getLogger(self.__class__.__name__)
+        
+        # Parse the base URL to get host and port
+        parsed_url = urlparse(base_url)
+        self.host = parsed_url.hostname or 'localhost'
+        self.port = parsed_url.port or 3000
+        
+        # HMR detection state
+        self.detected_framework = None
+        self.hmr_config = None
+        self.websocket = None
+        self.is_monitoring = False
+        self.hmr_events = []
+        self.event_callbacks = []
+        
+        # Framework configurations
+        self.framework_configs = {
+            'vite': {
+                'name': 'Vite',
+                'default_port': 5173,
+                'ws_paths': ['/__vite_hmr', '/vite-hmr'],
+                'event_patterns': ['vite:beforeUpdate', 'vite:afterUpdate', 'css-update'],
+                'css_update_indicators': ['css-update', 'style-update']
+            },
+            'webpack': {
+                'name': 'Webpack Dev Server',
+                'default_port': 3000,
+                'ws_paths': ['/sockjs-node', '/webpack-hmr', '/ws'],
+                'event_patterns': ['webpackHotUpdate', 'hot', 'hash'],
+                'css_update_indicators': ['css', 'style', 'hot-update']
+            },
+            'nextjs': {
+                'name': 'Next.js',
+                'default_port': 3000,
+                'ws_paths': ['/_next/webpack-hmr', '/_next/static/hmr'],
+                'event_patterns': ['building', 'built', 'sync'],
+                'css_update_indicators': ['css', 'style']
+            },
+            'parcel': {
+                'name': 'Parcel',
+                'default_port': 1234,
+                'ws_paths': ['/hmr', '/parcel-hmr'],
+                'event_patterns': ['buildSuccess', 'buildError', 'hmr:update'],
+                'css_update_indicators': ['css', 'style']
+            },
+            'laravel_mix': {
+                'name': 'Laravel Mix',
+                'default_port': 3000,
+                'ws_paths': ['/browser-sync/socket.io', '/browsersync'],
+                'event_patterns': ['file:changed', 'browser:reload'],
+                'css_update_indicators': ['css', 'scss', 'sass']
+            }
+        }
+    
+    async def auto_detect_framework(self) -> Optional[str]:
+        """
+        Auto-detect the development framework by probing WebSocket endpoints
+        
+        Returns the detected framework key or None if no framework detected
+        """
+        self.logger.info(f"Auto-detecting HMR framework for {self.base_url}")
+        
+        # Try to detect based on port first
+        port_hints = {
+            5173: ['vite'],
+            3000: ['webpack', 'nextjs', 'laravel_mix'],
+            1234: ['parcel']
+        }
+        
+        frameworks_to_check = port_hints.get(self.port, list(self.framework_configs.keys()))
+        
+        for framework_key in frameworks_to_check:
+            config = self.framework_configs[framework_key]
+            
+            # Test WebSocket connections for this framework
+            for ws_path in config['ws_paths']:
+                ws_url = f"ws://{self.host}:{self.port}{ws_path}"
+                
+                try:
+                    self.logger.debug(f"Testing WebSocket connection: {ws_url}")
+                    
+                    # Quick connection test with timeout
+                    websocket = await asyncio.wait_for(
+                        websockets.connect(ws_url, ping_interval=None),
+                        timeout=2.0
+                    )
+                    
+                    # Connection successful - this is likely our framework
+                    await websocket.close()
+                    
+                    self.detected_framework = framework_key
+                    self.hmr_config = {
+                        'framework': framework_key,
+                        'name': config['name'],
+                        'ws_url': ws_url,
+                        'ws_path': ws_path,
+                        'event_patterns': config['event_patterns'],
+                        'css_indicators': config['css_update_indicators']
+                    }
+                    
+                    self.logger.info(f"✅ Detected HMR framework: {config['name']} at {ws_url}")
+                    return framework_key
+                    
+                except (ConnectionClosed, InvalidURI, OSError, asyncio.TimeoutError) as e:
+                    self.logger.debug(f"WebSocket test failed for {ws_url}: {e}")
+                    continue
+        
+        self.logger.warning("❌ No HMR framework detected - CSS iteration will use fallback timing")
+        return None
+    
+    async def start_monitoring(self, on_hmr_event: Optional[Callable] = None) -> bool:
+        """
+        Start monitoring HMR events
+        
+        Args:
+            on_hmr_event: Optional callback function for HMR events
+            
+        Returns:
+            True if monitoring started successfully, False otherwise
+        """
+        if not self.hmr_config:
+            await self.auto_detect_framework()
+        
+        if not self.hmr_config:
+            self.logger.warning("Cannot start HMR monitoring - no framework detected")
+            return False
+        
+        try:
+            ws_url = self.hmr_config['ws_url']
+            self.logger.info(f"Starting HMR monitoring for {self.hmr_config['name']} at {ws_url}")
+            
+            self.websocket = await websockets.connect(ws_url, ping_interval=20)
+            self.is_monitoring = True
+            
+            if on_hmr_event:
+                self.event_callbacks.append(on_hmr_event)
+            
+            # Start the monitoring loop
+            asyncio.create_task(self._monitor_hmr_events())
+            
+            self.logger.info("✅ HMR monitoring started successfully")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"Failed to start HMR monitoring: {e}")
+            self.is_monitoring = False
+            return False
+    
+    async def _monitor_hmr_events(self):
+        """Internal method to monitor WebSocket messages for HMR events"""
+        try:
+            async for message in self.websocket:
+                await self._process_hmr_message(message)
+                
+        except ConnectionClosed:
+            self.logger.info("HMR WebSocket connection closed")
+            self.is_monitoring = False
+        except Exception as e:
+            self.logger.error(f"HMR monitoring error: {e}")
+            self.is_monitoring = False
+    
+    async def _process_hmr_message(self, message: str):
+        """Process incoming HMR WebSocket messages"""
+        try:
+            # Parse message (could be JSON or plain text depending on framework)
+            try:
+                data = json.loads(message)
+                message_type = 'json'
+            except json.JSONDecodeError:
+                data = message
+                message_type = 'text'
+            
+            # Create HMR event record
+            hmr_event = {
+                'timestamp': time.time(),
+                'framework': self.hmr_config['framework'],
+                'message_type': message_type,
+                'raw_message': message,
+                'parsed_data': data if message_type == 'json' else None,
+                'event_type': self._classify_hmr_event(data, message),
+                'is_css_update': self._is_css_update(data, message)
+            }
+            
+            # Store the event
+            self.hmr_events.append(hmr_event)
+            
+            # Keep only last 100 events to prevent memory issues
+            if len(self.hmr_events) > 100:
+                self.hmr_events = self.hmr_events[-100:]
+            
+            # Notify callbacks
+            for callback in self.event_callbacks:
+                try:
+                    await callback(hmr_event)
+                except Exception as e:
+                    self.logger.error(f"HMR event callback error: {e}")
+            
+            # Log important events
+            if hmr_event['is_css_update']:
+                self.logger.info(f"🎨 CSS update detected: {hmr_event['event_type']}")
+            elif hmr_event['event_type'] != 'heartbeat':
+                self.logger.debug(f"HMR event: {hmr_event['event_type']}")
+                
+        except Exception as e:
+            self.logger.error(f"Error processing HMR message: {e}")
+    
+    def _classify_hmr_event(self, data: Any, raw_message: str) -> str:
+        """Classify the type of HMR event based on message content"""
+        if not self.hmr_config:
+            return 'unknown'
+        
+        framework = self.hmr_config['framework']
+        event_patterns = self.hmr_config['event_patterns']
+        
+        # Convert to string for pattern matching
+        message_str = str(data).lower() if data else raw_message.lower()
+        
+        # Framework-specific event classification
+        if framework == 'vite':
+            if 'vite:beforeupdate' in message_str:
+                return 'build_start'
+            elif 'vite:afterupdate' in message_str or 'css-update' in message_str:
+                return 'css_update'
+            elif 'connected' in message_str:
+                return 'connection'
+            elif 'ping' in message_str or 'pong' in message_str:
+                return 'heartbeat'
+                
+        elif framework == 'webpack':
+            if 'webpackhotupdate' in message_str:
+                return 'hot_update'
+            elif 'building' in message_str:
+                return 'build_start'
+            elif 'built' in message_str:
+                return 'build_complete'
+            elif 'hash' in message_str:
+                return 'hash_update'
+                
+        elif framework == 'nextjs':
+            if 'building' in message_str:
+                return 'build_start'
+            elif 'built' in message_str:
+                return 'build_complete'
+            elif 'sync' in message_str:
+                return 'sync'
+                
+        elif framework == 'parcel':
+            if 'buildsuccess' in message_str:
+                return 'build_success'
+            elif 'builderror' in message_str:
+                return 'build_error'
+            elif 'hmr:update' in message_str:
+                return 'hmr_update'
+                
+        elif framework == 'laravel_mix':
+            if 'file:changed' in message_str:
+                return 'file_change'
+            elif 'browser:reload' in message_str:
+                return 'browser_reload'
+        
+        # Check against general patterns
+        for pattern in event_patterns:
+            if pattern.lower() in message_str:
+                return pattern
+        
+        return 'unknown'
+    
+    def _is_css_update(self, data: Any, raw_message: str) -> bool:
+        """Determine if this HMR event represents a CSS update"""
+        if not self.hmr_config:
+            return False
+        
+        css_indicators = self.hmr_config['css_indicators']
+        message_str = str(data).lower() if data else raw_message.lower()
+        
+        # Check for CSS-specific indicators
+        for indicator in css_indicators:
+            if indicator in message_str:
+                return True
+        
+        # Additional CSS detection patterns
+        css_patterns = ['.css', '.scss', '.sass', '.less', 'style', 'stylesheet']
+        for pattern in css_patterns:
+            if pattern in message_str:
+                return True
+        
+        return False
+    
+    async def wait_for_css_update(self, timeout: float = 10.0) -> Optional[Dict]:
+        """
+        Wait for the next CSS update event with precision timing
+        
+        This is the key method that replaces arbitrary waits in CSS iteration:
+        
+        OLD WAY:
+        await page.screenshot("before.png")
+        # ... developer makes CSS changes ...
+        await page.wait_for_timeout(2000)  # Arbitrary wait
+        await page.screenshot("after.png")
+        
+        NEW WAY:
+        await page.screenshot("before.png")
+        # ... developer makes CSS changes ...
+        css_event = await hmr_detector.wait_for_css_update()  # Precise timing
+        await page.screenshot("after.png")
+        
+        Args:
+            timeout: Maximum time to wait for CSS update (seconds)
+            
+        Returns:
+            HMR event dict if CSS update detected, None if timeout
+        """
+        if not self.is_monitoring:
+            self.logger.warning("HMR monitoring not active - cannot wait for CSS updates")
+            return None
+        
+        start_time = time.time()
+        initial_event_count = len(self.hmr_events)
+        
+        self.logger.info(f"⏱️  Waiting for CSS update (timeout: {timeout}s)")
+        
+        while time.time() - start_time < timeout:
+            # Check for new CSS update events
+            for event in self.hmr_events[initial_event_count:]:
+                if event['is_css_update']:
+                    self.logger.info(f"✅ CSS update detected after {time.time() - start_time:.2f}s")
+                    return event
+            
+            # Short sleep to prevent busy waiting
+            await asyncio.sleep(0.1)
+        
+        self.logger.warning(f"⏰ CSS update wait timeout after {timeout}s")
+        return None
+    
+    async def wait_for_build_complete(self, timeout: float = 30.0) -> Optional[Dict]:
+        """
+        Wait for build completion (useful for more complex changes)
+        
+        Args:
+            timeout: Maximum time to wait for build completion (seconds)
+            
+        Returns:
+            HMR event dict if build completed, None if timeout
+        """
+        if not self.is_monitoring:
+            self.logger.warning("HMR monitoring not active - cannot wait for build completion")
+            return None
+        
+        start_time = time.time()
+        initial_event_count = len(self.hmr_events)
+        
+        self.logger.info(f"⏱️  Waiting for build completion (timeout: {timeout}s)")
+        
+        build_complete_indicators = ['build_complete', 'build_success', 'css_update', 'hot_update']
+        
+        while time.time() - start_time < timeout:
+            # Check for build completion events
+            for event in self.hmr_events[initial_event_count:]:
+                if event['event_type'] in build_complete_indicators:
+                    self.logger.info(f"✅ Build completed after {time.time() - start_time:.2f}s")
+                    return event
+            
+            await asyncio.sleep(0.1)
+        
+        self.logger.warning(f"⏰ Build completion wait timeout after {timeout}s")
+        return None
+    
+    async def stop_monitoring(self):
+        """Stop HMR monitoring and close WebSocket connection"""
+        self.is_monitoring = False
+        
+        if self.websocket:
+            try:
+                await self.websocket.close()
+                self.logger.info("HMR monitoring stopped")
+            except Exception as e:
+                self.logger.error(f"Error stopping HMR monitoring: {e}")
+        
+        self.websocket = None
+    
+    def get_hmr_status(self) -> Dict[str, Any]:
+        """Get current HMR detection and monitoring status"""
+        return {
+            'framework_detected': self.detected_framework,
+            'framework_name': self.hmr_config['name'] if self.hmr_config else None,
+            'is_monitoring': self.is_monitoring,
+            'websocket_url': self.hmr_config['ws_url'] if self.hmr_config else None,
+            'total_events': len(self.hmr_events),
+            'css_events': len([e for e in self.hmr_events if e['is_css_update']]),
+            'recent_events': self.hmr_events[-5:] if self.hmr_events else []
+        }
+    
+    def get_framework_info(self) -> Dict[str, Any]:
+        """Get information about the detected framework"""
+        if not self.hmr_config:
+            return {'detected': False, 'supported_frameworks': list(self.framework_configs.keys())}
+        
+        return {
+            'detected': True,
+            'framework': self.hmr_config['framework'],
+            'name': self.hmr_config['name'],
+            'websocket_path': self.hmr_config['ws_path'],
+            'css_indicators': self.hmr_config['css_indicators'],
+            'event_patterns': self.hmr_config['event_patterns']
+        }

cursorflow/core/trace_manager.py

@@ -0,0 +1,209 @@
+"""
+Trace Manager for CursorFlow v2.0
+
+Manages Playwright trace file recording for complete interaction history.
+Pure observation - records everything without modifying application behavior.
+"""
+
+import asyncio
+import time
+import logging
+from typing import Optional, Dict, Any
+from pathlib import Path
+from playwright.async_api import BrowserContext
+
+
+class TraceManager:
+    """
+    Manages Playwright trace recording for comprehensive debugging data
+    
+    Provides complete interaction history, screenshots, and network activity
+    in Playwright's native trace format for maximum debugging capability.
+    """
+    
+    def __init__(self, artifacts_base: Path):
+        """
+        Initialize trace manager
+        
+        Args:
+            artifacts_base: Base directory for storing trace files
+        """
+        self.artifacts_base = artifacts_base
+        self.traces_dir = artifacts_base / "traces"
+        self.traces_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.current_trace_path: Optional[Path] = None
+        self.is_recording = False
+        self.session_id: Optional[str] = None
+        
+        self.logger = logging.getLogger(__name__)
+    
+    async def start_trace(self, context: BrowserContext, session_id: str) -> str:
+        """
+        Start Playwright trace recording
+        
+        Args:
+            context: Browser context to record
+            session_id: Unique session identifier
+            
+        Returns:
+            Path where trace will be saved
+        """
+        try:
+            self.session_id = session_id
+            self.current_trace_path = self.traces_dir / f"{session_id}.zip"
+            
+            # Start comprehensive trace recording
+            await context.tracing.start(
+                screenshots=True,      # Capture screenshots at each action
+                snapshots=True,        # Capture DOM snapshots
+                sources=True,          # Include source code context
+                title=f"CursorFlow Session {session_id}"
+            )
+            
+            self.is_recording = True
+            self.logger.info(f"Started trace recording: {self.current_trace_path}")
+            
+            return str(self.current_trace_path)
+            
+        except Exception as e:
+            self.logger.error(f"Failed to start trace recording: {e}")
+            self.is_recording = False
+            raise
+    
+    async def stop_trace(self, context: BrowserContext) -> Optional[str]:
+        """
+        Stop trace recording and save file
+        
+        Args:
+            context: Browser context being recorded
+            
+        Returns:
+            Path to saved trace file, or None if recording wasn't active
+        """
+        if not self.is_recording or not self.current_trace_path:
+            return None
+        
+        try:
+            await context.tracing.stop(path=str(self.current_trace_path))
+            
+            trace_path = str(self.current_trace_path)
+            file_size = self.current_trace_path.stat().st_size if self.current_trace_path.exists() else 0
+            
+            self.logger.info(f"Trace recording saved: {trace_path} ({file_size:,} bytes)")
+            
+            # Reset state
+            self.is_recording = False
+            self.current_trace_path = None
+            self.session_id = None
+            
+            return trace_path
+            
+        except Exception as e:
+            self.logger.error(f"Failed to stop trace recording: {e}")
+            self.is_recording = False
+            return None
+    
+    async def stop_trace_on_error(self, context: BrowserContext, error: Exception) -> Optional[str]:
+        """
+        Stop trace recording when an error occurs, with error context
+        
+        Args:
+            context: Browser context being recorded
+            error: The error that occurred
+            
+        Returns:
+            Path to saved trace file with error context
+        """
+        if not self.is_recording or not self.current_trace_path:
+            return None
+        
+        try:
+            # Add error context to trace filename
+            error_trace_path = self.traces_dir / f"{self.session_id}_ERROR_{type(error).__name__}.zip"
+            
+            await context.tracing.stop(path=str(error_trace_path))
+            
+            file_size = error_trace_path.stat().st_size if error_trace_path.exists() else 0
+            
+            self.logger.info(f"Error trace saved: {error_trace_path} ({file_size:,} bytes)")
+            self.logger.info(f"View trace: playwright show-trace {error_trace_path}")
+            
+            # Reset state
+            self.is_recording = False
+            self.current_trace_path = None
+            self.session_id = None
+            
+            return str(error_trace_path)
+            
+        except Exception as trace_error:
+            self.logger.error(f"Failed to save error trace: {trace_error}")
+            self.is_recording = False
+            return None
+    
+    def get_trace_info(self) -> Dict[str, Any]:
+        """
+        Get current trace recording information
+        
+        Returns:
+            Dictionary with trace status and metadata
+        """
+        return {
+            "is_recording": self.is_recording,
+            "session_id": self.session_id,
+            "trace_path": str(self.current_trace_path) if self.current_trace_path else None,
+            "traces_directory": str(self.traces_dir),
+            "total_traces": len(list(self.traces_dir.glob("*.zip")))
+        }
+    
+    def cleanup_old_traces(self, max_traces: int = 50) -> int:
+        """
+        Clean up old trace files to prevent disk space issues
+        
+        Args:
+            max_traces: Maximum number of trace files to keep
+            
+        Returns:
+            Number of traces deleted
+        """
+        try:
+            trace_files = sorted(
+                self.traces_dir.glob("*.zip"),
+                key=lambda p: p.stat().st_mtime,
+                reverse=True  # Newest first
+            )
+            
+            if len(trace_files) <= max_traces:
+                return 0
+            
+            # Delete oldest traces
+            traces_to_delete = trace_files[max_traces:]
+            deleted_count = 0
+            
+            for trace_file in traces_to_delete:
+                try:
+                    trace_file.unlink()
+                    deleted_count += 1
+                except Exception as e:
+                    self.logger.warning(f"Failed to delete old trace {trace_file}: {e}")
+            
+            if deleted_count > 0:
+                self.logger.info(f"Cleaned up {deleted_count} old trace files")
+            
+            return deleted_count
+            
+        except Exception as e:
+            self.logger.error(f"Trace cleanup failed: {e}")
+            return 0
+    
+    def get_viewing_instructions(self, trace_path: str) -> str:
+        """
+        Get instructions for viewing a trace file
+        
+        Args:
+            trace_path: Path to the trace file
+            
+        Returns:
+            Command to view the trace
+        """
+        return f"playwright show-trace {trace_path}"