cursorflow 2.7.6__tar.gz → 2.7.8__tar.gz

{cursorflow-2.7.6 → cursorflow-2.7.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.6
+Version: 2.7.8
 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
@@ -144,6 +144,57 @@ cursorflow cleanup --all --dry-run
 
 ---
 
+## 🔐 Authentication & Testing Protected Pages
+
+Test authenticated pages with automatic session management:
+
+```bash
+# 1. Configure auth in .cursorflow/config.json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button"
+  }
+}
+
+# 2. Login once and save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# 3. Reuse session for protected pages (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+**Supports:**
+- Form authentication (username/password)
+- Cookie authentication (JWT tokens, session cookies)
+- Header authentication (Bearer tokens, API keys)
+- SSO authentication (Google, Microsoft, Okta, Auth0)
+
+**SSO/OAuth Quick Start:**
+```bash
+# Capture SSO auth (opens browser for manual login)
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output google-sso.json
+
+# Use captured auth
+# (Copy cookies from google-sso.json to .cursorflow/config.json)
+cursorflow test --use-session "sso-user" --path /dashboard
+```
+
+**See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
+
+---
+
 ## 🚀 Complete Page Intelligence
 
 Every test captures everything needed for debugging:
@@ -157,7 +208,7 @@ Every test captures everything needed for debugging:
 - **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 authenticated browser state (requires auth_config)
+- **Sessions**: Save/restore authenticated browser state (requires auth_config - see Authentication below)
 
 ### **🔄 Hot Reload Intelligence**
 - **Framework auto-detection** (Vite, Webpack, Next.js, Parcel, Laravel Mix)

{cursorflow-2.7.6 → cursorflow-2.7.8}/README.md

@@ -99,6 +99,57 @@ cursorflow cleanup --all --dry-run
 
 ---
 
+## 🔐 Authentication & Testing Protected Pages
+
+Test authenticated pages with automatic session management:
+
+```bash
+# 1. Configure auth in .cursorflow/config.json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button"
+  }
+}
+
+# 2. Login once and save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# 3. Reuse session for protected pages (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+**Supports:**
+- Form authentication (username/password)
+- Cookie authentication (JWT tokens, session cookies)
+- Header authentication (Bearer tokens, API keys)
+- SSO authentication (Google, Microsoft, Okta, Auth0)
+
+**SSO/OAuth Quick Start:**
+```bash
+# Capture SSO auth (opens browser for manual login)
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output google-sso.json
+
+# Use captured auth
+# (Copy cookies from google-sso.json to .cursorflow/config.json)
+cursorflow test --use-session "sso-user" --path /dashboard
+```
+
+**See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
+
+---
+
 ## 🚀 Complete Page Intelligence
 
 Every test captures everything needed for debugging:
@@ -112,7 +163,7 @@ Every test captures everything needed for debugging:
 - **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 authenticated browser state (requires auth_config)
+- **Sessions**: Save/restore authenticated browser state (requires auth_config - see Authentication below)
 
 ### **🔄 Hot Reload Intelligence**
 - **Framework auto-detection** (Vite, Webpack, Next.js, Parcel, Laravel Mix)

{cursorflow-2.7.6 → cursorflow-2.7.8}/cursorflow/cli.py

@@ -1116,6 +1116,158 @@ def sessions(subcommand, name):
         else:
             console.print(f"[yellow]⚠️  Session not found: {name}[/yellow]")
 
+@main.command()
+@click.option('--base-url', '-u', required=True, help='Base URL of your application')
+@click.option('--path', '-p', default='/', help='Path to navigate to after login (e.g., /dashboard)')
+@click.option('--output', '-o', default='auth-capture.json', help='Output file for captured auth state')
+@click.option('--wait', type=int, default=60, help='Seconds to wait for manual login (default: 60)')
+def capture_auth(base_url, path, output, wait):
+    """
+    Capture authentication state after manual SSO/OAuth login
+    
+    Opens a browser, waits for you to complete SSO login manually,
+    then captures all cookies, localStorage, and sessionStorage.
+    Perfect for Google/Microsoft/Okta SSO authentication.
+    
+    \b
+    Process:
+      1. Browser opens to your app
+      2. Complete SSO login manually (Google, Microsoft, Okta, etc.)
+      3. Navigate to a protected page (e.g., /dashboard)
+      4. CursorFlow captures all auth state
+      5. Auth state saved to JSON file
+      6. Use in .cursorflow/config.json as cookie authentication
+    
+    \b
+    Examples:
+      # Capture Google SSO auth
+      cursorflow capture-auth --base-url http://localhost:3000 --path /dashboard
+      
+      # Capture with custom wait time
+      cursorflow capture-auth -u http://localhost:3000 -p /dashboard --wait 120
+      
+      # Save to custom file
+      cursorflow capture-auth -u http://localhost:3000 --output google-sso.json
+    """
+    console.print(f"\n🔐 SSO Authentication Capture")
+    console.print(f"📍 Base URL: [cyan]{base_url}[/cyan]")
+    console.print(f"🎯 Target path: [cyan]{path}[/cyan]")
+    console.print(f"⏱️  Wait time: [yellow]{wait}[/yellow] seconds")
+    console.print(f"📄 Output file: [green]{output}[/green]\n")
+    
+    console.print("📋 [bold]Instructions:[/bold]")
+    console.print("  1. Browser will open to your application")
+    console.print("  2. [yellow]Complete SSO login manually[/yellow] (Google, Microsoft, Okta, etc.)")
+    console.print("  3. Navigate to a protected page (e.g., /dashboard)")
+    console.print("  4. [green]Press Enter[/green] when fully logged in")
+    console.print("  5. CursorFlow will capture all auth state\n")
+    
+    input("Press Enter to open browser and start capture...")
+    
+    try:
+        from playwright.async_api import async_playwright
+        import json
+        
+        async def capture_process():
+            async with async_playwright() as p:
+                # Launch browser in HEADED mode (user needs to interact)
+                browser = await p.chromium.launch(headless=False)
+                context = await browser.new_context()
+                page = await context.new_page()
+                
+                console.print(f"\n🌐 Opening browser to: [cyan]{base_url}[/cyan]")
+                await page.goto(base_url)
+                
+                console.print(f"\n⏳ [yellow]Complete your SSO login in the browser...[/yellow]")
+                console.print(f"   Waiting up to {wait} seconds...")
+                console.print(f"   [bold]Press Enter in this terminal when logged in and on {path}[/bold]\n")
+                
+                # Wait for user to complete login
+                import sys
+                import select
+                
+                # Simple blocking wait for Enter key
+                input("Press Enter after completing login... ")
+                
+                # Navigate to target path to ensure we're at the right place
+                if path != '/':
+                    console.print(f"📍 Navigating to: [cyan]{path}[/cyan]")
+                    await page.goto(f"{base_url.rstrip('/')}{path}")
+                    await page.wait_for_load_state("networkidle")
+                
+                console.print("\n📸 Capturing authentication state...")
+                
+                # Capture all authentication data
+                storage_state = await context.storage_state()
+                
+                # Get localStorage
+                local_storage = await page.evaluate("""
+                    () => {
+                        const storage = {};
+                        for (let i = 0; i < localStorage.length; i++) {
+                            const key = localStorage.key(i);
+                            storage[key] = localStorage.getItem(key);
+                        }
+                        return storage;
+                    }
+                """)
+                
+                # Get sessionStorage
+                session_storage = await page.evaluate("""
+                    () => {
+                        const storage = {};
+                        for (let i = 0; i < sessionStorage.length; i++) {
+                            const key = sessionStorage.key(i);
+                            storage[key] = sessionStorage.getItem(key);
+                        }
+                        return storage;
+                    }
+                """)
+                
+                # Organize captured data
+                auth_data = {
+                    "captured_at": time.strftime("%Y-%m-%d %H:%M:%S"),
+                    "base_url": base_url,
+                    "current_url": page.url,
+                    "method": "cookies",
+                    "cookies": storage_state.get("cookies", []),
+                    "localStorage": local_storage,
+                    "sessionStorage": session_storage,
+                    "usage_instructions": {
+                        "1": "Copy the 'cookies' array below",
+                        "2": "Add to .cursorflow/config.json under auth.cookies",
+                        "3": "Set auth.method to 'cookies'",
+                        "4": "Use with: cursorflow test --use-session <name>"
+                    }
+                }
+                
+                # Save to file
+                output_path = Path(output)
+                with open(output_path, 'w') as f:
+                    json.dump(auth_data, f, indent=2)
+                
+                console.print(f"\n✅ Authentication state captured!")
+                console.print(f"📄 Saved to: [green]{output_path.absolute()}[/green]")
+                console.print(f"🍪 Captured {len(auth_data['cookies'])} cookies")
+                console.print(f"💾 localStorage: {len(local_storage)} items")
+                console.print(f"💾 sessionStorage: {len(session_storage)} items")
+                
+                console.print(f"\n📋 [bold]Next steps:[/bold]")
+                console.print(f"  1. Open: [cyan]{output}[/cyan]")
+                console.print(f"  2. Copy the 'cookies' array")
+                console.print(f"  3. Add to .cursorflow/config.json:")
+                console.print(f'\n  {{\n    "auth": {{\n      "method": "cookies",\n      "cookies": [... paste here ...]\n    }}\n  }}\n')
+                console.print(f"  4. Test with: [cyan]cursorflow test --use-session sso-user[/cyan]\n")
+                
+                await browser.close()
+        
+        asyncio.run(capture_process())
+        
+    except KeyboardInterrupt:
+        console.print("\n[yellow]⚠️  Capture cancelled by user[/yellow]")
+    except Exception as e:
+        console.print(f"[red]❌ Error capturing auth: {escape(str(e))}[/red]")
+
 @main.command()
 @click.option('--base-url', '-u', required=True)
 @click.option('--path', '-p', default='/', help='Path to navigate to')

{cursorflow-2.7.6 → cursorflow-2.7.8}/cursorflow/rules/cursorflow-usage.mdc

@@ -963,21 +963,192 @@ cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dash
 cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "after"}]'
 ```
 
-## Authentication Testing
+## Authentication & Session Management
 
+### **Critical: Most Real Apps Need Auth**
+
+Testing sophisticated applications requires authentication to access:
+- User dashboards and protected pages
+- Admin panels and settings
+- Role-based features
+- Shopping carts and user data
+- Personalized content
+
+### **Three Authentication Methods**
+
+#### **Method 1: Form Authentication (Automatic)**
+
+Configure in `.cursorflow/config.json`:
+```json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "form",
+    "username": "test@example.com",
+    "password": "testpass",
+    "username_selector": "#email",
+    "password_selector": "#password",
+    "submit_selector": "#login-button",
+    "success_indicators": ["dashboard", "profile"],
+    "auth_check_selectors": [".user-menu"]
+  }
+}
+```
+
+Then use session management:
 ```bash
-cursorflow test \
-  --base-url http://localhost:3000 \
-  --actions '[
-    {"navigate": "/login"},
-    {"fill": {"selector": "#username", "value": "test@example.com"}},
-    {"fill": {"selector": "#password", "value": "testpass"}},
-    {"click": "#login-button"},
-    {"wait_for": ".dashboard"},
-    {"navigate": "/protected-page"},
-    {"wait_for": "#protected-content"},
-    {"screenshot": "authenticated"}
-  ]'
+# Login once, save session
+cursorflow test --base-url http://localhost:3000 \
+  --path /login \
+  --save-session "user"
+
+# Reuse session (no re-login!)
+cursorflow test --use-session "user" \
+  --path /dashboard \
+  --screenshot "dashboard"
+```
+
+#### **Method 2: Cookie Authentication**
+
+For JWT tokens, session cookies, or cookies from DevTools:
+```json
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "session_token",
+        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "domain": "example.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true
+      }
+    ]
+  }
+}
+```
+
+#### **Method 3: Header Authentication**
+
+For API tokens and Bearer authentication:
+```json
+{
+  "auth": {
+    "method": "headers",
+    "headers": {
+      "Authorization": "Bearer your-api-token",
+      "X-API-Key": "your-api-key"
+    }
+  }
+}
+```
+
+### **Session Management Benefits**
+
+**Without sessions**: Re-login on every test (slow, server load)
+**With sessions**: Login once, reuse state (fast, efficient)
+
+```bash
+# Save sessions for different roles
+cursorflow test --path /login --save-session "admin"
+cursorflow test --path /login --save-session "user"
+
+# Reuse as needed
+cursorflow test --use-session "admin" --path /admin/settings
+cursorflow test --use-session "user" --path /dashboard
+```
+
+### **Manual Authentication (Complex Flows)**
+
+For 2FA, OAuth, or complex flows, use explicit actions:
+```bash
+cursorflow test --actions '[
+  {"navigate": "/login"},
+  {"fill": {"selector": "#email", "value": "test@example.com"}},
+  {"fill": {"selector": "#password", "value": "testpass"}},
+  {"click": "#login-button"},
+  {"wait_for": "#otp-input"},
+  {"fill": {"selector": "#otp-input", "value": "123456"}},
+  {"click": "#verify-button"},
+  {"wait_for": ".dashboard"},
+  {"screenshot": "authenticated"}
+]' --save-session "2fa-user"
+```
+
+### **SSO Authentication (Google, Microsoft, Okta)**
+
+**SSO requires manual capture** because of external identity providers:
+
+```bash
+# 1. Capture SSO auth (opens browser, you login manually)
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output google-sso.json
+
+# Browser opens, you complete SSO login, CursorFlow captures cookies
+
+# 2. Copy cookies from google-sso.json to .cursorflow/config.json:
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [/* paste from google-sso.json */]
+  }
+}
+
+# 3. Use captured auth
+cursorflow test --use-session "sso-user" --path /dashboard
+```
+
+**SSO providers supported:**
+- Google OAuth
+- Microsoft Azure AD
+- Okta
+- Auth0
+- Any OAuth/SAML provider
+
+**When SSO tokens expire:**
+```bash
+# Re-capture auth (SSO tokens typically expire in 1-24 hours)
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output sso-refreshed.json
+```
+
+### **Troubleshooting Auth**
+
+**Auth failing?**
+```bash
+# Inspect login form to get correct selectors
+cursorflow inspect --base-url http://localhost:3000 \
+  --path /login \
+  --selector "input[type='email']"
+
+# Test with verbose logging
+cursorflow test --path /login \
+  --save-session "test" \
+  --verbose
+```
+
+**Session not working?**
+```bash
+# Check saved session
+cat .cursorflow/sessions/user_session.json
+
+# Force fresh login
+cursorflow test --use-session "user" --fresh-session
+```
+
+**SSO not working?**
+```bash
+# Re-capture auth state
+cursorflow capture-auth --base-url http://localhost:3000 --path /dashboard
+
+# Check if localStorage has tokens (some SSO stores tokens there)
+cat auth-capture.json | grep localStorage
+
+# Test immediately after capture
+cursorflow test --use-session "sso-user" --path /dashboard
 ```
 
 ## Best Practices