cursorflow 2.7.7__tar.gz → 2.7.9__tar.gz

{cursorflow-2.7.7 → cursorflow-2.7.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cursorflow
-Version: 2.7.7
+Version: 2.7.9
 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
@@ -177,6 +177,22 @@ cursorflow test --use-session "user" \
 - 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 \
+  --browser chrome \
+  --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
+```
+
+**Tip:** Use `--browser chrome` on macOS for better window visibility
 
 **See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
 

{cursorflow-2.7.7 → cursorflow-2.7.9}/README.md

@@ -132,6 +132,22 @@ cursorflow test --use-session "user" \
 - 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 \
+  --browser chrome \
+  --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
+```
+
+**Tip:** Use `--browser chrome` on macOS for better window visibility
 
 **See:** [Complete Authentication Guide](docs/user/USAGE_GUIDE.md#authentication--session-management)
 

{cursorflow-2.7.7 → cursorflow-2.7.9}/cursorflow/cli.py

@@ -1116,6 +1116,203 @@ 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)')
+@click.option('--browser', type=click.Choice(['chromium', 'chrome', 'firefox']), default='chromium', help='Browser to use (default: chromium)')
+def capture_auth(base_url, path, output, wait, browser):
+    """
+    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
+      
+      # Use system Chrome (more visible on macOS)
+      cursorflow capture-auth -u http://localhost:3000 --browser chrome
+      
+      # 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🔐 [bold]SSO Authentication Capture[/bold]")
+    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 yellow]Instructions:[/bold yellow]")
+    console.print("  1. [bold]A Chromium browser window will open[/bold]")
+    console.print("  2. [yellow]Complete SSO login manually[/yellow] in that browser window")
+    console.print("  3. Navigate to a protected page (e.g., /dashboard)")
+    console.print("  4. Return here and [green]press Enter[/green] when fully logged in")
+    console.print("  5. CursorFlow will capture all auth state\n")
+    
+    console.print("[bold red]⚠️  Look for the browser window - it may open behind other windows![/bold red]\n")
+    
+    input("Press Enter to open browser and start capture...")
+    
+    try:
+        from playwright.async_api import async_playwright
+        import json
+        
+        async def capture_process():
+            console.print("\n🚀 Starting Playwright...")
+            async with async_playwright() as p:
+                # Select browser based on user choice
+                if browser == 'chrome':
+                    browser_type = p.chromium
+                    channel = 'chrome'  # Use system Chrome if available
+                elif browser == 'firefox':
+                    browser_type = p.firefox
+                    channel = None
+                else:  # chromium
+                    browser_type = p.chromium
+                    channel = None
+                
+                # Launch browser in HEADED mode (user needs to interact)
+                console.print(f"🌐 Launching [bold]{browser}[/bold] browser (headed mode)...")
+                console.print("[yellow]👀 Watch for browser window - it should appear shortly...[/yellow]")
+                
+                try:
+                    launch_options = {
+                        'headless': False,
+                        'slow_mo': 50,
+                        'args': ['--start-maximized']
+                    }
+                    if channel:
+                        launch_options['channel'] = channel
+                    
+                    browser_instance = await browser_type.launch(**launch_options)
+                except Exception as e:
+                    console.print(f"[red]❌ Failed to launch browser: {e}[/red]")
+                    console.print("\n💡 Try installing Chromium:")
+                    console.print("   [cyan]playwright install chromium[/cyan]")
+                    raise
+                
+                # Create context with viewport to ensure it's visible
+                context = await browser_instance.new_context(
+                    viewport={'width': 1280, 'height': 720}
+                )
+                page = await context.new_page()
+                
+                # Bring page to front
+                await page.bring_to_front()
+                
+                console.print(f"\n✅ [bold green]Browser window opened![/bold green]")
+                console.print(f"   👉 [bold]If you don't see it, check behind other windows or different desktop spaces[/bold]")
+                console.print(f"\n🌐 Navigating to: [cyan]{base_url}[/cyan]...")
+                await page.goto(base_url)
+                console.print(f"✅ Page loaded!")
+                
+                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_instance.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.7 → cursorflow-2.7.9}/cursorflow/rules/cursorflow-usage.mdc

@@ -1076,6 +1076,47 @@ cursorflow test --actions '[
 ]' --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 \
+  --browser chrome \
+  --output google-sso.json
+
+# Browser opens (use --browser chrome for better visibility on macOS)
+# 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?**
@@ -1100,6 +1141,18 @@ cat .cursorflow/sessions/user_session.json
 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
 
 ### **🔥 Hot Reload CSS Iteration Best Practices**

{cursorflow-2.7.7 → cursorflow-2.7.9}/docs/user/USAGE_GUIDE.md

@@ -1056,6 +1056,31 @@ Clicked submit: button[type='submit']
 cat .cursorflow/sessions/test_session.json | python3 -m json.tool
 ```
 
+**Problem: "Browser not appearing" (capture-auth)**
+
+**Solution:**
+
+The browser IS launching but may be hidden by macOS window management:
+
+1. **Use system Chrome** (more visible):
+```bash
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --browser chrome \
+  --path /dashboard
+```
+
+2. **Check all desktop spaces**: 
+   - Press F3 or swipe up with 3 fingers (Mission Control)
+   - Look for Chromium/Chrome window
+
+3. **Check your Dock**:
+   - Look for Chromium icon that appeared
+   - Click to bring window forward
+
+4. **Verify browser launched**:
+   - Look for "✅ Browser opened!" in terminal output
+   - If you see this, browser is running somewhere
+
 ---
 
 #### **Advanced Authentication Scenarios**
@@ -1134,6 +1159,192 @@ cursorflow test --use-session "regular-user" \
 3. Look at Response Headers for `Set-Cookie`
 4. Copy cookie details to config
 
+##### **SSO Authentication (OAuth, SAML, Google/Microsoft Login)**
+
+SSO authentication is complex because it involves external identity providers and multi-step flows. CursorFlow handles this by capturing the final authenticated state.
+
+**The SSO Challenge:**
+- Involves external domains (accounts.google.com, login.microsoftonline.com, etc.)
+- Complex token exchanges and redirects
+- CSRF tokens and state parameters
+- May use multiple cookies across domains
+
+**Solution: Capture After Manual Login**
+
+CursorFlow provides a helper to capture your authenticated state after manually logging in:
+
+**Step 1: Login manually in Chrome**
+```bash
+# Open your app and complete the SSO login manually
+# This handles all the OAuth redirects, token exchanges, etc.
+```
+
+**Step 2: Capture authentication state**
+```bash
+# Capture all cookies and storage from your logged-in session
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output sso-auth.json
+
+# Use system Chrome for better visibility (recommended for macOS)
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --browser chrome \
+  --output sso-auth.json
+
+# This opens a browser, lets you login, then captures:
+# - All cookies (including third-party cookies if needed)
+# - localStorage state
+# - sessionStorage state
+# - Any tokens or auth data
+```
+
+**Command Options:**
+- `--base-url`: Your application URL
+- `--path`: Page to navigate to after login (default: `/`)
+- `--output`: File to save auth state (default: `auth-capture.json`)
+- `--browser`: Browser to use - `chromium`, `chrome`, or `firefox` (default: `chromium`)
+- `--wait`: Maximum seconds to wait for login (default: `60`)
+
+**Browser Visibility:**
+- Use `--browser chrome` on macOS for better window visibility
+- Browser opens maximized in headed mode
+- If you don't see it, check other desktop spaces or behind windows
+
+**Step 3: Use captured auth in config**
+```json
+{
+  "base_url": "http://localhost:3000",
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      // Automatically populated from capture-auth
+      {
+        "name": "auth_token",
+        "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "domain": "yourapp.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true
+      },
+      {
+        "name": "refresh_token",
+        "value": "abc123...",
+        "domain": "yourapp.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true
+      }
+    ]
+  }
+}
+```
+
+**Alternative: Manual Cookie Extraction**
+
+If `capture-auth` is not available, extract cookies manually:
+
+**For Google SSO:**
+```bash
+# 1. Login via Google in Chrome
+# 2. DevTools (F12) → Application → Cookies
+# 3. Look for cookies from BOTH domains:
+#    - yourapp.com (your application cookies)
+#    - accounts.google.com (Google auth cookies, if needed)
+# 4. Copy all authentication-related cookies:
+```
+
+**For Microsoft/Azure AD SSO:**
+```bash
+# Same process, look for:
+# - yourapp.com cookies
+# - login.microsoftonline.com cookies (if needed)
+# - Any cookies with names like: auth_token, id_token, access_token
+```
+
+**For Okta/Auth0:**
+```bash
+# Look for cookies like:
+# - okta-oauth-redirect-params
+# - okta-oauth-state
+# - sid (session ID)
+# - dt (device token)
+```
+
+**Complete cookie capture example:**
+```json
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {
+        "name": "appSession",
+        "value": "long-base64-encoded-value...",
+        "domain": "yourapp.com",
+        "path": "/",
+        "httpOnly": true,
+        "secure": true,
+        "sameSite": "Lax"
+      },
+      {
+        "name": "identity.token",
+        "value": "another-long-token...",
+        "domain": "yourapp.com",
+        "path": "/",
+        "httpOnly": false,
+        "secure": true,
+        "sameSite": "None"
+      }
+    ]
+  }
+}
+```
+
+**SSO Best Practices:**
+
+1. **Capture all cookies**: SSO often uses multiple cookies
+2. **Check localStorage**: Some SSO solutions store tokens in localStorage
+3. **Watch for expiration**: SSO tokens typically expire (1 hour - 24 hours)
+4. **Test token validity**: 
+```bash
+cursorflow test --use-session "sso-user" --path /dashboard
+# If fails, capture fresh session
+```
+
+5. **Multi-domain considerations**: Some SSO requires cookies on multiple domains
+```json
+{
+  "auth": {
+    "method": "cookies",
+    "cookies": [
+      {"name": "app_session", "domain": "yourapp.com", "value": "..."},
+      {"name": "sso_token", "domain": "sso.yourapp.com", "value": "..."}
+    ]
+  }
+}
+```
+
+**Refreshing SSO Tokens:**
+
+SSO tokens expire. When they do:
+```bash
+# 1. Clear old session
+cursorflow sessions delete "sso-user"
+
+# 2. Manually login again in Chrome
+
+# 3. Capture new auth state
+cursorflow capture-auth --base-url http://localhost:3000 \
+  --path /dashboard \
+  --output sso-auth-refreshed.json
+
+# 4. Update config with new tokens
+```
+
+**Programmatic SSO (Advanced):**
+
+For automated SSO without manual login, you need service account credentials from your identity provider. This is complex and varies by provider - consult your SSO provider's documentation for headless authentication flows.
+
 ##### **Environment-Specific Auth**
 
 Different credentials for local/staging/production:

{cursorflow-2.7.7 → cursorflow-2.7.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cursorflow"
-version = "2.7.7"
+version = "2.7.9"
 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"}