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

cursorflow/__init__.py

@@ -56,7 +56,7 @@ def _get_version():
         pass
     
     # Fallback version - should match pyproject.toml
-    return "2.1.3"
+    return "2.1.5"
 
 __version__ = _get_version()
 __author__ = "GeekWarrior Development"

cursorflow/auto_init.py

@@ -0,0 +1,147 @@
+"""
+Auto-initialization for CursorFlow
+
+Detects uninitialized projects and offers to set them up automatically.
+Makes the setup process seamless for both humans and AI agents.
+"""
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def is_project_initialized(project_dir: Optional[str] = None) -> bool:
+    """
+    Check if CursorFlow is initialized in the project
+    
+    Returns True if:
+    - .cursor/rules/ contains CursorFlow rules
+    - cursorflow-config.json exists
+    - .cursorflow/ directory exists
+    """
+    if project_dir is None:
+        project_dir = os.getcwd()
+    
+    project_path = Path(project_dir)
+    
+    # Check for key indicators
+    has_rules = (project_path / ".cursor" / "rules" / "cursorflow-usage.mdc").exists()
+    has_config = (project_path / "cursorflow-config.json").exists()
+    has_artifacts_dir = (project_path / ".cursorflow").exists()
+    
+    # Need at least rules and config
+    return has_rules and has_config
+
+
+def auto_initialize_if_needed(project_dir: Optional[str] = None, interactive: bool = True) -> bool:
+    """
+    Auto-initialize CursorFlow in project if not already initialized
+    
+    Args:
+        project_dir: Project directory (defaults to cwd)
+        interactive: If True, ask user for confirmation. If False, auto-initialize silently.
+        
+    Returns:
+        True if initialized (or already was), False if user declined or error occurred
+    """
+    if is_project_initialized(project_dir):
+        return True
+    
+    if project_dir is None:
+        project_dir = os.getcwd()
+    
+    project_path = Path(project_dir)
+    
+    # If non-interactive (e.g., running via Cursor), just do it
+    if not interactive:
+        try:
+            from .install_cursorflow_rules import install_cursorflow_rules
+            return install_cursorflow_rules(project_dir, force=False)
+        except Exception as e:
+            print(f"⚠️  Auto-initialization failed: {e}", file=sys.stderr)
+            print(f"💡 Run manually: cursorflow install-rules", file=sys.stderr)
+            return False
+    
+    # Interactive mode: ask user
+    print("\n🎯 CursorFlow is not initialized in this project yet.")
+    print(f"📁 Project directory: {project_path}")
+    print("\nTo use CursorFlow, we need to set up:")
+    print("  • Cursor AI rules in .cursor/rules/")
+    print("  • Configuration file: cursorflow-config.json")
+    print("  • Artifacts directory: .cursorflow/")
+    print("  • .gitignore entries for CursorFlow artifacts")
+    
+    response = input("\n🚀 Initialize CursorFlow now? [Y/n]: ").strip().lower()
+    
+    if response in ('', 'y', 'yes'):
+        try:
+            from .install_cursorflow_rules import install_cursorflow_rules
+            success = install_cursorflow_rules(project_dir, force=False)
+            
+            if success:
+                print("\n✅ CursorFlow is ready to use!")
+                print("💡 Start testing with: cursorflow test --help")
+            
+            return success
+            
+        except Exception as e:
+            print(f"\n❌ Initialization failed: {e}", file=sys.stderr)
+            print(f"💡 Try manually: cursorflow install-rules", file=sys.stderr)
+            return False
+    else:
+        print("\n⏭️  Skipped initialization.")
+        print("💡 Run later with: cursorflow install-rules")
+        return False
+
+
+def get_initialization_warning() -> str:
+    """Get a friendly warning message for uninitialized projects"""
+    
+    return """
+╔════════════════════════════════════════════════════════════════╗
+║  🎯 CursorFlow Not Initialized                                 ║
+╠════════════════════════════════════════════════════════════════╣
+║                                                                 ║
+║  CursorFlow requires project-specific setup to work properly.  ║
+║                                                                 ║
+║  Quick fix:                                                     ║
+║    cursorflow install-rules                                     ║
+║                                                                 ║
+║  This creates:                                                  ║
+║    • .cursor/rules/ (Cursor AI integration)                     ║
+║    • cursorflow-config.json (project configuration)             ║
+║    • .cursorflow/ (artifacts and sessions)                      ║
+║    • .gitignore entries                                         ║
+║                                                                 ║
+╚════════════════════════════════════════════════════════════════╝
+"""
+
+
+def ensure_initialized(project_dir: Optional[str] = None, auto_init: bool = False) -> None:
+    """
+    Ensure project is initialized, or raise helpful error
+    
+    Args:
+        project_dir: Project directory
+        auto_init: If True, automatically initialize without asking
+        
+    Raises:
+        RuntimeError: If not initialized and user declines/can't initialize
+    """
+    if is_project_initialized(project_dir):
+        return
+    
+    # Try auto-initialization
+    interactive = not auto_init and sys.stdin.isatty()
+    
+    if auto_initialize_if_needed(project_dir, interactive=interactive):
+        return
+    
+    # Failed to initialize
+    print(get_initialization_warning(), file=sys.stderr)
+    raise RuntimeError(
+        "CursorFlow not initialized in this project. "
+        "Run: cursorflow install-rules"
+    )
+

cursorflow/cli.py

@@ -22,9 +22,31 @@ console = Console()
 
 @click.group()
 @click.version_option(version=__version__)
-def main():
+@click.pass_context
+def main(ctx):
     """Universal UI testing framework for any web technology"""
-    pass
+    
+    # Skip initialization check for commands that don't need it
+    skip_init_check = ['install-rules', 'init', 'update', 'check-updates', 'install-deps']
+    
+    if ctx.invoked_subcommand in skip_init_check:
+        return
+    
+    # Check if project is initialized, offer to auto-initialize
+    from .auto_init import is_project_initialized, auto_initialize_if_needed
+    
+    if not is_project_initialized():
+        console.print("\n[yellow]⚠️  CursorFlow not initialized in this project[/yellow]")
+        console.print("This is a one-time setup that creates:")
+        console.print("  • .cursor/rules/ (Cursor AI integration)")
+        console.print("  • cursorflow-config.json (project configuration)")
+        console.print("  • .cursorflow/ (artifacts directory)")
+        
+        # Auto-initialize with confirmation
+        if not auto_initialize_if_needed(interactive=True):
+            console.print("\n[red]Cannot proceed without initialization.[/red]")
+            console.print("Run: [cyan]cursorflow install-rules[/cyan]")
+            ctx.exit(1)
 
 @main.command()
 @click.option('--base-url', '-u', required=True,

cursorflow/install_cursorflow_rules.py

@@ -125,9 +125,9 @@ def create_config_template(project_path: Path, force: bool = False):
     # Get current version
     try:
         import cursorflow
-        current_version = getattr(cursorflow, '__version__', '2.1.3')
+        current_version = getattr(cursorflow, '__version__', '2.1.5')
     except ImportError:
-        current_version = '2.1.3'
+        current_version = '2.1.5'
     
     if config_path.exists():
         if not force:
@@ -302,9 +302,9 @@ def setup_update_checking(project_path: Path):
     # Create initial version tracking
     try:
         import cursorflow
-        current_version = getattr(cursorflow, '__version__', '2.1.3')
+        current_version = getattr(cursorflow, '__version__', '2.1.5')
     except ImportError:
-        current_version = '2.1.3'
+        current_version = '2.1.5'
     
     version_info = {
         "installed_version": current_version,

cursorflow/log_sources/local_file.py

@@ -30,7 +30,13 @@ class LocalFileLogSource:
                     'next_server': '.next/trace.log'
                 }
         """
-        self.log_paths = log_paths
+        # Handle case where log_paths is a string instead of dict
+        if isinstance(log_paths, str):
+            self.log_paths = {"default": log_paths}
+        elif isinstance(log_paths, list):
+            self.log_paths = {f"log_{i}": path for i, path in enumerate(log_paths)}
+        else:
+            self.log_paths = log_paths
         self.log_queue = queue.Queue()
         self.tail_processes = {}
         self.monitoring = False

cursorflow/post_install.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+Post-install message for CursorFlow
+
+Shows important setup instructions after pip install.
+"""
+
+def show_post_install_message():
+    """Display post-install instructions"""
+    
+    message = """
+╔══════════════════════════════════════════════════════════════════════╗
+║                                                                      ║
+║  ✅ CursorFlow installed successfully!                               ║
+║                                                                      ║
+║  📋 IMPORTANT: One more step to enable CursorFlow in your project   ║
+║                                                                      ║
+║  Run this in your project directory:                                ║
+║                                                                      ║
+║    cd /path/to/your/project                                         ║
+║    cursorflow install-rules                                         ║
+║                                                                      ║
+║  This creates:                                                       ║
+║    • Cursor AI integration rules                                    ║
+║    • Project-specific configuration                                 ║
+║    • Artifacts directory structure                                  ║
+║                                                                      ║
+║  💡 Then install browser dependencies:                              ║
+║                                                                      ║
+║    playwright install chromium                                      ║
+║                                                                      ║
+║  🚀 After that, you can start testing:                              ║
+║                                                                      ║
+║    cursorflow test --base-url http://localhost:3000 --path /        ║
+║                                                                      ║
+║  📚 Documentation: https://github.com/haley-marketing-group/cursorflow ║
+║                                                                      ║
+╚══════════════════════════════════════════════════════════════════════╝
+"""
+    
+    print(message)
+
+
+if __name__ == "__main__":
+    show_post_install_message()
+

cursorflow/rules/cursorflow-installation.mdc

@@ -1,11 +1,32 @@
 ---
-title: CursorFlow 2.0.0 Installation & Setup Guide for Cursor
-description: How to install and configure CursorFlow 2.0.0 for complete page intelligence in AI-driven development
+title: CursorFlow Installation & Setup Guide for Cursor
+description: How to install and configure CursorFlow for complete page intelligence in AI-driven development
 ---
 
-# CursorFlow 2.0.0 Installation & Setup Guide for Cursor
+# CursorFlow Installation & Setup Guide for Cursor
 
-## 🚀 **When to Install CursorFlow 2.0.0**
+## ⚠️ **CRITICAL: Two-Step Installation Process**
+
+**If you are reading this file, Step 2 is already complete for this project.**
+
+CursorFlow requires **TWO installations**:
+
+1. **Step 1 - Package Installation** (once per Python environment):
+   ```bash
+   pip install cursorflow
+   playwright install chromium
+   ```
+
+2. **Step 2 - Project Initialization** (once per project):
+   ```bash
+   cursorflow install-rules
+   ```
+   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.
+
+## 🚀 **When to Install CursorFlow**
 
 ### **Automatically Install When:**
 - User mentions UI testing, visual debugging, or layout issues
@@ -24,10 +45,13 @@ description: How to install and configure CursorFlow 2.0.0 for complete page int
 
 ## 📦 **Installation Steps**
 
-### **1. Install CursorFlow 2.0.0:**
+### **1. Verify Package Installation:**
 ```bash
-# Install CursorFlow 2.0.0 with complete page intelligence
-pip install cursorflow
+# Check if CursorFlow is installed
+cursorflow --version
+
+# If not installed or outdated:
+pip install --upgrade cursorflow
 
 # Install browser automation dependencies
 playwright install chromium

cursorflow/rules/cursorflow-usage.mdc

@@ -1,6 +1,6 @@
 # CursorFlow Usage Rules for Cursor AI
 
-## 🔥 **CursorFlow 2.0.0: Complete Page Intelligence for AI-Driven Development**
+## 🔥 **CursorFlow 2.1.4: Complete Page Intelligence for AI-Driven Development**
 
 **CursorFlow provides comprehensive data collection for rapid UI iteration:**
 
@@ -9,6 +9,8 @@
 - 📊 **Comprehensive Page Analysis** - Fonts, animations, resources, storage state
 - 🎯 **Enhanced Error Context Collection** - Smart screenshot deduplication
 - ⚡ **Enhanced Browser Data Capture** - Playwright traces + network interception
+- 📱 **Parallel Viewport Testing** - Mobile, tablet, desktop responsive testing
+- 🖼️ **Enhanced Screenshot Options** - Clipping, masking, quality control
 
 ## When to Use CursorFlow
 
@@ -217,7 +219,7 @@ print(f"Performance metrics: {screenshot_data['performance_data']}")
 # Playwright trace available at: .cursorflow/artifacts/traces/session.zip
 ```
 
-## 🚀 **CursorFlow CLI Usage (v2.0.0)**
+## 🚀 **CursorFlow CLI Usage (v2.1.4)**
 
 ### **Basic Testing:**
 ```bash
@@ -233,12 +235,33 @@ cursorflow test \
     {"screenshot": "state"}
   ]'
 
+# 🆕 Parallel responsive testing (mobile, tablet, desktop)
+cursorflow test --base-url http://localhost:3000 --path "/dashboard" --responsive
+
+# 🆕 Enhanced screenshot options
+cursorflow test \
+  --base-url http://localhost:3000 \
+  --actions '[
+    {"navigate": "/page"},
+    {"screenshot": {
+      "name": "clipped-header",
+      "options": {
+        "clip": {"selector": "#header"},
+        "mask": [".user-email", ".sensitive-data"],
+        "full_page": false,
+        "quality": 90
+      }
+    }}
+  ]'
+
 # Results include:
 # - Hot Reload Intelligence status
 # - Advanced Element Intelligence (7 selector types)
 # - Comprehensive Page Analysis (fonts, animations, resources)
 # - Enhanced Error Context (smart deduplication)
 # - Enhanced Browser Data (Playwright traces)
+# - 🆕 Parallel Viewport Analysis (responsive testing)
+# - 🆕 Enhanced Screenshot Metadata (options used)
 ```
 
 ### **Available CLI Commands:**
@@ -260,7 +283,10 @@ cursorflow --help           # Show all commands and options
 | `fill` | `{"fill": {"selector": "#input", "value": "text"}}` | Fill form field |
 | `wait` | `{"wait": 2}` | Wait seconds |
 | `wait_for` | `{"wait_for": "#element"}` | Wait for element |
-| `screenshot` | `{"screenshot": "name"}` | Take screenshot |
+| `screenshot` | `{"screenshot": "name"}` | Take basic screenshot |
+| 🆕 `screenshot` | `{"screenshot": {"name": "test", "options": {"clip": {"selector": "#header"}}}}` | Enhanced screenshot with clipping |
+| 🆕 `screenshot` | `{"screenshot": {"name": "test", "options": {"mask": [".sensitive"]}}}` | Screenshot with masked elements |
+| 🆕 `screenshot` | `{"screenshot": {"name": "test.jpg", "options": {"quality": 90}}}` | JPEG screenshot with quality |
 
 ## Common Usage Patterns
 
@@ -279,6 +305,48 @@ cursorflow test \
   ]'
 ```
 
+### 🆕 Responsive Testing (Parallel Viewports)
+```bash
+# Simple responsive test across mobile, tablet, desktop
+cursorflow test --base-url http://localhost:3000 --path "/dashboard" --responsive
+
+# Custom responsive test with actions
+cursorflow test --base-url http://localhost:3000 --responsive --actions '[
+  {"navigate": "/dashboard"},
+  {"wait_for": "#main-content"},
+  {"screenshot": "responsive-dashboard"},
+  {"click": "#menu-toggle"},
+  {"screenshot": "responsive-menu"}
+]'
+
+# Results include:
+# - Performance comparison across viewports
+# - Layout differences analysis
+# - Responsive behavior insights
+# - Cross-viewport screenshots
+```
+
+### 🆕 Enhanced Screenshot Options
+```bash
+# Component-focused screenshots
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/page"},
+  {"screenshot": {"name": "header", "options": {"clip": {"selector": "#header"}}}}
+]'
+
+# Privacy-aware screenshots (mask sensitive data)
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/profile"},
+  {"screenshot": {"name": "profile", "options": {"mask": [".user-email", ".api-key"]}}}
+]'
+
+# High-quality JPEG screenshots
+cursorflow test --base-url http://localhost:3000 --actions '[
+  {"navigate": "/page"},
+  {"screenshot": {"name": "page.jpg", "options": {"quality": 95, "full_page": true}}}
+]'
+```
+
 ### Login Flow Testing
 ```bash
 cursorflow test \

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.1.3
+Version: 2.1.5
 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
@@ -138,10 +138,26 @@ All data structured for AI consumption:
 
 ## 🚀 Quick Start
 
+### Step 1: Install CursorFlow Package
 ```bash
-# Install CursorFlow
 pip install cursorflow
+playwright install chromium
+```
 
+### Step 2: Initialize Your Project (One-Time Setup)
+```bash
+cd /path/to/your/project
+cursorflow install-rules
+```
+
+This creates:
+- `.cursor/rules/` - Cursor AI integration rules
+- `cursorflow-config.json` - Project-specific configuration
+- `.cursorflow/` - Artifacts and session storage
+- `.gitignore` entries for CursorFlow artifacts
+
+### Step 3: Start Testing
+```bash
 # Test real application behavior
 cursorflow test --base-url http://localhost:3000 --path "/dashboard"
 

{cursorflow-2.1.3.dist-info → cursorflow-2.1.5.dist-info}/RECORD

@@ -1,7 +1,9 @@
-cursorflow/__init__.py,sha256=R0EASl-kqgr62b-7tqb7TBpEvWMWtBQs5VqOBtLxLF4,2763
+cursorflow/__init__.py,sha256=PrqWlldzSIzubH8DN_iw08QPTmWUsMlkeWaEVp1mpdw,2763
+cursorflow/auto_init.py,sha256=NqS3zPC-ILyCAvjlhQ9cDhuxOgu2SbqQvI4rzrgbv2k,5916
 cursorflow/auto_updater.py,sha256=oQ12TIMZ6Cm3HF-x9iRWFtvOLkRh-JWPqitS69-4roE,7851
-cursorflow/cli.py,sha256=ca36aTHFLYpiaeQYoj3TB4o39CEfj3WWaePze8yNvdg,27280
-cursorflow/install_cursorflow_rules.py,sha256=YBLbpyZT-ZLgq_VXhlu_ilruyttcQybaHPPfHYz7LnQ,11792
+cursorflow/cli.py,sha256=mk8mr1pN4cHCDIPhzSIxk-Jho6aSU6ZwCPJA9PqcKv4,28375
+cursorflow/install_cursorflow_rules.py,sha256=hpe3otnJN4h51h5xxGEJ25PWmCkj3IBfSpieYcbLFPU,11792
+cursorflow/post_install.py,sha256=WieBiKWG0qBAQpF8iMVWUyb9Fr2Xky9qECTMPrlAbpE,2678
 cursorflow/updater.py,sha256=rAST7STjw-SgKxn_jsQJWOoyEMia-MQVxpKMwzPRnOA,19573
 cursorflow/core/agent.py,sha256=f3lecgEzDRDdGTVccAtorpLGfNJJ49bbsQAmgr0vNGg,10136
 cursorflow/core/auth_handler.py,sha256=oRafO6ZdxoHryBIvHsrNV8TECed4GXpJsdEiH0KdPPk,17149
@@ -21,14 +23,14 @@ cursorflow/core/mockup_comparator.py,sha256=VLfEEaTgbcY0oTb-bhBD2uTbXGjbnOV7LXNV
 cursorflow/core/persistent_session.py,sha256=FsEHj4wKkycmdp6PFRHv3g333Y74yqra0x_qhUTQpik,36075
 cursorflow/core/report_generator.py,sha256=-vosfyrnfVyWDbAIMlMurl90xOXqBae8d6aLd9sEqiY,10113
 cursorflow/core/trace_manager.py,sha256=Jj9ultZrL1atiZXfcRVI6ynCnnfqZM-X0_taxt-llJ0,7189
-cursorflow/log_sources/local_file.py,sha256=5Aa1qFe-GABydXr3Hskta6QCMjRrBOfrGGD3OJ9JBBw,7257
+cursorflow/log_sources/local_file.py,sha256=YAzF6oZRusNT_EOJduoeMTgP6dc1Av9wK96yNxmhSGA,7558
 cursorflow/log_sources/ssh_remote.py,sha256=xLLxm5B95kUcLqMC7-oZUA66e1rU5LLeeBiR6Mw5syc,7642
 cursorflow/rules/__init__.py,sha256=gPcA-IkhXj03sl7cvZV0wwo7CtEkcyuKs4y0F5oQbqE,458
-cursorflow/rules/cursorflow-installation.mdc,sha256=PZN4hHpy2_g3EzD8BxZYhXF9A6YCvtMGaD3uOA7UVSs,9511
-cursorflow/rules/cursorflow-usage.mdc,sha256=SAsJRmml8W1zE_jArZnRtygO9RmggjEzxGA6hxBJ-H4,18924
-cursorflow-2.1.3.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
-cursorflow-2.1.3.dist-info/METADATA,sha256=L-0-ZDt4lzJ9irtTBHAg1dPjKunBtew1GUy6ARzkIOc,12300
-cursorflow-2.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cursorflow-2.1.3.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
-cursorflow-2.1.3.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
-cursorflow-2.1.3.dist-info/RECORD,,
+cursorflow/rules/cursorflow-installation.mdc,sha256=WmllIgx8MLEaxZFCwn3FBD51PPOt0JOn1GoNLQGEQJI,10191
+cursorflow/rules/cursorflow-usage.mdc,sha256=jD5IrIP2eKIeQN2TS-ehnwD1u_J6lWSXQZZ9KSUcOUU,21449
+cursorflow-2.1.5.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
+cursorflow-2.1.5.dist-info/METADATA,sha256=H-7VwQ6Ay9YKkXfvMFHLJLm8t5fgdz9Ef3FmI652ApE,12721
+cursorflow-2.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cursorflow-2.1.5.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
+cursorflow-2.1.5.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
+cursorflow-2.1.5.dist-info/RECORD,,