cursorflow 2.1.4__tar.gz → 2.1.5__tar.gz

cursorflow-2.1.5/FIRST_TIME_SETUP.md

@@ -0,0 +1,212 @@
+# CursorFlow First-Time Setup
+
+## 🎯 The Two-Step Installation Process
+
+CursorFlow requires **two separate installations**:
+
+### 1️⃣ Package Installation (Global)
+This installs the CursorFlow Python package and CLI tool into your Python environment:
+
+```bash
+pip install cursorflow
+playwright install chromium
+```
+
+**What this gives you:**
+- `cursorflow` command-line tool
+- Python API for programmatic usage
+- Core testing engine
+
+### 2️⃣ Project Initialization (Per-Project)
+This sets up CursorFlow in your specific project:
+
+```bash
+cd /path/to/your/project
+cursorflow install-rules
+```
+
+**What this creates:**
+- `.cursor/rules/` - Cursor AI integration rules (tells Cursor how to use CursorFlow)
+- `cursorflow-config.json` - Project-specific settings (base URL, log paths, etc.)
+- `.cursorflow/` - Artifacts directory (screenshots, sessions, test results)
+- `.gitignore` entries - Excludes CursorFlow artifacts from version control
+
+## 🤔 Why Two Steps?
+
+**Think of it like Git:**
+- `pip install cursorflow` = Installing the git CLI globally
+- `cursorflow install-rules` = Running `git init` in each project
+
+Each project needs its own CursorFlow configuration because:
+- Different base URLs (localhost:3000 vs localhost:8000)
+- Different log paths (Django logs vs React logs)
+- Different authentication setups
+- Different Cursor AI rules location per project
+
+## 🚀 Auto-Initialization
+
+If you forget step 2, CursorFlow will detect it and offer to initialize automatically:
+
+```bash
+$ cursorflow test --base-url http://localhost:3000
+
+⚠️  CursorFlow not initialized in this project
+This is a one-time setup that creates:
+  • .cursor/rules/ (Cursor AI integration)
+  • cursorflow-config.json (project configuration)
+  • .cursorflow/ (artifacts directory)
+
+🚀 Initialize CursorFlow now? [Y/n]: y
+
+✅ CursorFlow is ready to use!
+```
+
+## 📋 What Happens During Project Initialization?
+
+### 1. Cursor AI Integration (`.cursor/rules/`)
+Copies usage rules that teach Cursor AI how to use CursorFlow:
+- `cursorflow-usage.mdc` - How to run tests and analyze results
+- `cursorflow-installation.mdc` - Installation and setup guidance
+
+### 2. Configuration Template (`cursorflow-config.json`)
+Auto-detects your project type and creates smart defaults:
+
+```json
+{
+  "base_url": "http://localhost:3000",
+  "logs": {
+    "source": "local",
+    "paths": ["logs/app.log"]
+  },
+  "auth": {
+    "method": "form",
+    "username_selector": "#username",
+    "password_selector": "#password",
+    "submit_selector": "#login-button",
+    "session_storage": ".cursorflow/sessions/"
+  },
+  "browser": {
+    "headless": true,
+    "debug_mode": false
+  },
+  "_project_type": "react",
+  "_cursorflow_version": "2.1.5"
+}
+```
+
+### 3. Project Structure
+```
+your-project/
+├── .cursor/
+│   └── rules/
+│       ├── cursorflow-usage.mdc
+│       └── cursorflow-installation.mdc
+├── .cursorflow/
+│   ├── artifacts/
+│   ├── sessions/
+│   └── version_info.json
+├── cursorflow-config.json
+└── .gitignore (updated with CursorFlow entries)
+```
+
+## 🎪 Common Scenarios
+
+### New Team Member Setup
+```bash
+# They need both steps:
+pip install cursorflow
+playwright install chromium
+cd /path/to/existing/project
+# No need to run install-rules - config already exists!
+```
+
+### New Project
+```bash
+# Full setup:
+pip install cursorflow
+playwright install chromium
+cd /path/to/new/project
+cursorflow install-rules
+```
+
+### Multiple Projects
+```bash
+# Install once globally:
+pip install cursorflow
+playwright install chromium
+
+# Initialize each project:
+cd ~/projects/project-a && cursorflow install-rules
+cd ~/projects/project-b && cursorflow install-rules
+cd ~/projects/project-c && cursorflow install-rules
+```
+
+## 🔍 Verifying Setup
+
+### Check Package Installation
+```bash
+cursorflow --version
+# Should output: cursorflow, version 2.1.5
+```
+
+### Check Project Initialization
+```bash
+# From project directory:
+ls -la .cursor/rules/
+# Should show: cursorflow-usage.mdc, cursorflow-installation.mdc
+
+ls -la cursorflow-config.json
+# Should exist
+
+ls -la .cursorflow/
+# Should exist
+```
+
+## 🚨 Troubleshooting
+
+### "Command not found: cursorflow"
+**Problem:** Package not installed  
+**Solution:** `pip install cursorflow`
+
+### "CursorFlow not initialized in this project"
+**Problem:** Project not initialized  
+**Solution:** `cursorflow install-rules`
+
+### "Cursor doesn't know about CursorFlow"
+**Problem:** Rules not installed in project  
+**Solution:** `cursorflow install-rules` (creates `.cursor/rules/`)
+
+### "pip install worked but CursorFlow doesn't work"
+**Problem:** Missing step 2  
+**Solution:** Run `cursorflow install-rules` in your project
+
+## 💡 Pro Tips
+
+1. **Add to your project README:**
+   ```markdown
+   ## Development Setup
+   ```bash
+   pip install -r requirements.txt
+   cursorflow install-rules  # One-time CursorFlow setup
+   npm install
+   ```
+   ```
+
+2. **Add to onboarding checklist:**
+   - [ ] Clone repository
+   - [ ] Install dependencies
+   - [ ] **Run `cursorflow install-rules`** ← Don't forget!
+   - [ ] Run tests
+
+3. **Version control:**
+   - ✅ Commit `cursorflow-config.json` (team settings)
+   - ❌ Don't commit `.cursorflow/` (artifacts, generated per-developer)
+   - ✅ Commit `.cursor/rules/` (Cursor AI integration)
+
+## 🎯 Remember
+
+**Package Installation = Global tool**  
+**Project Initialization = Per-project setup**
+
+Just like `npm install -g typescript` vs `tsc --init`! 🚀
+

{cursorflow-2.1.4 → cursorflow-2.1.5}/MANIFEST.in

@@ -6,6 +6,8 @@ include README.md
 include LICENSE
 include pyproject.toml
 include setup.py
+include FIRST_TIME_SETUP.md
+include POST_INSTALL_MESSAGE.txt
 
 # INCLUDE: Core package code (automatically included by setuptools)
 recursive-include cursorflow *.py

{cursorflow-2.1.4 → cursorflow-2.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.1.4
+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.5/POST_INSTALL_MESSAGE.txt

@@ -0,0 +1,29 @@
+
+╔══════════════════════════════════════════════════════════════════════╗
+║                                                                      ║
+║  ✅ 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/yourrepo/cursorflow           ║
+║                                                                      ║
+╚══════════════════════════════════════════════════════════════════════╝
+

{cursorflow-2.1.4 → cursorflow-2.1.5}/README.md

@@ -93,10 +93,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.4 → cursorflow-2.1.5}/cursorflow/__init__.py

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

cursorflow-2.1.5/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-2.1.4 → cursorflow-2.1.5}/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-2.1.4 → cursorflow-2.1.5}/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.4')
+        current_version = getattr(cursorflow, '__version__', '2.1.5')
     except ImportError:
-        current_version = '2.1.4'
+        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.4')
+        current_version = getattr(cursorflow, '__version__', '2.1.5')
     except ImportError:
-        current_version = '2.1.4'
+        current_version = '2.1.5'
     
     version_info = {
         "installed_version": current_version,

cursorflow-2.1.5/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-2.1.4 → cursorflow-2.1.5}/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.1.4 Installation & Setup Guide for Cursor
+# CursorFlow Installation & Setup Guide for Cursor
 
-## 🚀 **When to Install CursorFlow 2.1.4**
+## ⚠️ **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-2.1.4 → cursorflow-2.1.5}/cursorflow.egg-info/SOURCES.txt

@@ -1,12 +1,16 @@
+FIRST_TIME_SETUP.md
 LICENSE
 MANIFEST.in
+POST_INSTALL_MESSAGE.txt
 README.md
 pyproject.toml
 setup.py
 cursorflow/__init__.py
+cursorflow/auto_init.py
 cursorflow/auto_updater.py
 cursorflow/cli.py
 cursorflow/install_cursorflow_rules.py
+cursorflow/post_install.py
 cursorflow/updater.py
 cursorflow/core/agent.py
 cursorflow/core/auth_handler.py

{cursorflow-2.1.4 → cursorflow-2.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.1.4"
+version = "2.1.5"
 description = "🔥 Complete page intelligence for AI-driven development with Hot Reload Intelligence - captures DOM, network, console, performance, HMR events, and comprehensive page analysis"
 authors = [
     {name = "GeekWarrior Development", email = "rbush@cooltheory.com"}
@@ -63,6 +63,9 @@ Repository = "https://github.com/haley-marketing-group/cursorflow"
 where = ["."]
 include = ["cursorflow*"]
 
+[tool.setuptools.package-data]
+cursorflow = ["rules/*.mdc", "rules/*.md"]
+
 
 [tool.black]
 line-length = 88