cursorflow 1.3.2__py3-none-any.whl → 1.3.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cursorflow/install_cursorflow_rules.py +2 -2
- cursorflow/rules/__init__.py +18 -0
- cursorflow/rules/cursorflow-installation.mdc +297 -0
- cursorflow/rules/cursorflow-usage.mdc +423 -0
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/METADATA +1 -1
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/RECORD +10 -7
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/WHEEL +0 -0
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/entry_points.txt +0 -0
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/licenses/LICENSE +0 -0
- {cursorflow-1.3.2.dist-info → cursorflow-1.3.3.dist-info}/top_level.txt +0 -0
@@ -32,12 +32,12 @@ def install_cursorflow_rules(project_dir: str = "."):
|
|
32
32
|
# Find CursorFlow package location
|
33
33
|
try:
|
34
34
|
import cursorflow
|
35
|
-
package_dir = Path(cursorflow.__file__).parent
|
35
|
+
package_dir = Path(cursorflow.__file__).parent
|
36
36
|
rules_source_dir = package_dir / "rules"
|
37
37
|
except ImportError:
|
38
38
|
# Fallback: look for rules in current directory structure
|
39
39
|
current_dir = Path(__file__).parent
|
40
|
-
rules_source_dir = current_dir
|
40
|
+
rules_source_dir = current_dir / "rules" # Now rules are in cursorflow/rules/
|
41
41
|
|
42
42
|
if not rules_source_dir.exists():
|
43
43
|
print(f"❌ Could not find CursorFlow rules directory at: {rules_source_dir}")
|
@@ -0,0 +1,18 @@
|
|
1
|
+
"""
|
2
|
+
CursorFlow Rules for Cursor AI Integration
|
3
|
+
|
4
|
+
This package contains the Cursor rules files that provide guidance
|
5
|
+
to Cursor AI on how to use CursorFlow effectively.
|
6
|
+
"""
|
7
|
+
|
8
|
+
import os
|
9
|
+
from pathlib import Path
|
10
|
+
|
11
|
+
def get_rules_directory():
|
12
|
+
"""Get the path to the rules directory"""
|
13
|
+
return Path(__file__).parent
|
14
|
+
|
15
|
+
def get_rule_files():
|
16
|
+
"""Get list of available rule files"""
|
17
|
+
rules_dir = get_rules_directory()
|
18
|
+
return list(rules_dir.glob("*.mdc"))
|
@@ -0,0 +1,297 @@
|
|
1
|
+
---
|
2
|
+
title: CursorFlow CLI Installation & Setup Guide for Cursor
|
3
|
+
description: How to install and configure CursorFlow CLI in any project for autonomous UI testing
|
4
|
+
---
|
5
|
+
|
6
|
+
# CursorFlow CLI Installation & Setup Guide for Cursor
|
7
|
+
|
8
|
+
## 🚀 **When to Install CursorFlow**
|
9
|
+
|
10
|
+
### **Automatically Install When:**
|
11
|
+
- User mentions UI testing, visual debugging, or layout issues
|
12
|
+
- User asks to "test this component" or "check if this works"
|
13
|
+
- User is working on CSS/layout modifications
|
14
|
+
- User reports frontend bugs or authentication issues
|
15
|
+
- New project setup where UI testing would be valuable
|
16
|
+
|
17
|
+
### **Project Types That Benefit:**
|
18
|
+
- Web applications (React, Vue, Angular, PHP, Django, Rails)
|
19
|
+
- Component libraries and design systems
|
20
|
+
- E-commerce sites with complex user flows
|
21
|
+
- Admin dashboards and data visualization
|
22
|
+
- Any project with user authentication
|
23
|
+
|
24
|
+
## 📦 **Installation Steps**
|
25
|
+
|
26
|
+
### **1. Install CursorFlow CLI:**
|
27
|
+
```bash
|
28
|
+
# Install the universal testing CLI
|
29
|
+
pip install cursorflow
|
30
|
+
|
31
|
+
# Install browser automation dependencies
|
32
|
+
cursorflow install-deps
|
33
|
+
|
34
|
+
# Verify installation
|
35
|
+
cursorflow --version
|
36
|
+
```
|
37
|
+
|
38
|
+
### **2. Initialize Project:**
|
39
|
+
```bash
|
40
|
+
# Initialize CursorFlow in the project (creates config + installs rules)
|
41
|
+
cursorflow init .
|
42
|
+
|
43
|
+
# This automatically:
|
44
|
+
# - Creates cursor-test-config.json with smart defaults
|
45
|
+
# - Sets up .cursorflow/ directory structure
|
46
|
+
# - Configures for your web technology
|
47
|
+
```
|
48
|
+
|
49
|
+
### **3. Verify Installation:**
|
50
|
+
```bash
|
51
|
+
# Test basic functionality
|
52
|
+
cursorflow test --base-url http://localhost:3000 --path "/"
|
53
|
+
|
54
|
+
# Check configuration
|
55
|
+
cat cursor-test-config.json
|
56
|
+
|
57
|
+
# Verify artifacts directory
|
58
|
+
ls -la .cursorflow/
|
59
|
+
```
|
60
|
+
|
61
|
+
## ⚙️ **Auto-Generated Configuration**
|
62
|
+
|
63
|
+
CursorFlow creates smart defaults based on your project:
|
64
|
+
|
65
|
+
```json
|
66
|
+
{
|
67
|
+
"environments": {
|
68
|
+
"local": {
|
69
|
+
"base_url": "http://localhost:3000",
|
70
|
+
"logs": "local",
|
71
|
+
"log_paths": {
|
72
|
+
"app": "logs/app.log"
|
73
|
+
}
|
74
|
+
},
|
75
|
+
"staging": {
|
76
|
+
"base_url": "https://staging.example.com",
|
77
|
+
"logs": "ssh",
|
78
|
+
"ssh_config": {
|
79
|
+
"hostname": "staging-server",
|
80
|
+
"username": "deploy"
|
81
|
+
},
|
82
|
+
"log_paths": {
|
83
|
+
"app_error": "/var/log/app/error.log"
|
84
|
+
}
|
85
|
+
}
|
86
|
+
}
|
87
|
+
}
|
88
|
+
```
|
89
|
+
|
90
|
+
## 🎯 **Quick Start Examples**
|
91
|
+
|
92
|
+
### **Test a Component:**
|
93
|
+
```bash
|
94
|
+
# Test any UI component
|
95
|
+
cursorflow test dashboard --base-url http://localhost:3000
|
96
|
+
|
97
|
+
# Results in structured JSON + artifacts:
|
98
|
+
# - Browser interaction timeline
|
99
|
+
# - Screenshots in .cursorflow/artifacts/
|
100
|
+
# - Console logs and server logs
|
101
|
+
# - Network requests and responses
|
102
|
+
```
|
103
|
+
|
104
|
+
### **Debug Authentication:**
|
105
|
+
```bash
|
106
|
+
# Test login flow
|
107
|
+
cursorflow test login-form --base-url http://localhost:3000
|
108
|
+
|
109
|
+
# Analyze output for:
|
110
|
+
# - Authentication errors in timeline
|
111
|
+
# - Session state issues
|
112
|
+
# - Server response patterns
|
113
|
+
```
|
114
|
+
|
115
|
+
### **CSS Iteration:**
|
116
|
+
```bash
|
117
|
+
# Before: Test current state
|
118
|
+
cursorflow test dashboard --base-url http://localhost:3000
|
119
|
+
|
120
|
+
# Apply CSS changes to actual files
|
121
|
+
# After: Test improved state
|
122
|
+
cursorflow test dashboard --base-url http://localhost:3000
|
123
|
+
|
124
|
+
# Compare screenshots in .cursorflow/artifacts/
|
125
|
+
```
|
126
|
+
|
127
|
+
## 🌍 **Environment-Specific Setup**
|
128
|
+
|
129
|
+
### **Local Development:**
|
130
|
+
```json
|
131
|
+
{
|
132
|
+
"local": {
|
133
|
+
"base_url": "http://localhost:3000",
|
134
|
+
"logs": "local",
|
135
|
+
"log_paths": {"app": "logs/app.log"}
|
136
|
+
}
|
137
|
+
}
|
138
|
+
```
|
139
|
+
|
140
|
+
### **Staging/Production Testing:**
|
141
|
+
```json
|
142
|
+
{
|
143
|
+
"staging": {
|
144
|
+
"base_url": "https://staging.example.com",
|
145
|
+
"logs": "ssh",
|
146
|
+
"ssh_config": {
|
147
|
+
"hostname": "staging-server",
|
148
|
+
"username": "deploy",
|
149
|
+
"key_file": "~/.ssh/staging_key"
|
150
|
+
},
|
151
|
+
"log_paths": {
|
152
|
+
"app_error": "/var/log/app/error.log",
|
153
|
+
"access_log": "/var/log/nginx/access.log"
|
154
|
+
}
|
155
|
+
}
|
156
|
+
}
|
157
|
+
```
|
158
|
+
|
159
|
+
## 📋 **Verification Steps**
|
160
|
+
|
161
|
+
### **Test CLI Installation:**
|
162
|
+
```bash
|
163
|
+
# Check version
|
164
|
+
cursorflow --version
|
165
|
+
|
166
|
+
# View available commands
|
167
|
+
cursorflow --help
|
168
|
+
|
169
|
+
# Test project initialization
|
170
|
+
cursorflow init test-project
|
171
|
+
|
172
|
+
# Verify config creation
|
173
|
+
cat test-project/cursor-test-config.json
|
174
|
+
```
|
175
|
+
|
176
|
+
### **Test Component Testing:**
|
177
|
+
```bash
|
178
|
+
# Test any component (requires running dev server)
|
179
|
+
cursorflow test component-name --base-url http://localhost:3000
|
180
|
+
|
181
|
+
# Check artifacts were created
|
182
|
+
ls -la .cursorflow/artifacts/sessions/
|
183
|
+
|
184
|
+
# Verify JSON output structure
|
185
|
+
# Should contain: timeline, artifacts, summary
|
186
|
+
```
|
187
|
+
|
188
|
+
## 🚨 **Troubleshooting Common Issues**
|
189
|
+
|
190
|
+
### **Installation Problems:**
|
191
|
+
```bash
|
192
|
+
# If pip install fails
|
193
|
+
pip install --upgrade pip
|
194
|
+
pip install cursorflow --no-cache-dir
|
195
|
+
|
196
|
+
# If browser dependencies missing
|
197
|
+
cursorflow install-deps
|
198
|
+
|
199
|
+
# If permission issues
|
200
|
+
pip install --user cursorflow
|
201
|
+
```
|
202
|
+
|
203
|
+
### **Configuration Issues:**
|
204
|
+
```bash
|
205
|
+
# Re-initialize project
|
206
|
+
rm cursor-test-config.json
|
207
|
+
cursorflow init .
|
208
|
+
|
209
|
+
# Check config validity
|
210
|
+
cat cursor-test-config.json
|
211
|
+
|
212
|
+
# Test with explicit URL
|
213
|
+
cursorflow test homepage --base-url http://localhost:3000
|
214
|
+
```
|
215
|
+
|
216
|
+
### **Testing Issues:**
|
217
|
+
```bash
|
218
|
+
# Verify dev server is running
|
219
|
+
curl http://localhost:3000
|
220
|
+
|
221
|
+
# Check artifacts directory permissions
|
222
|
+
ls -la .cursorflow/
|
223
|
+
|
224
|
+
# View detailed help
|
225
|
+
cursorflow test --help
|
226
|
+
```
|
227
|
+
|
228
|
+
## 💡 **Best Practices for Installation**
|
229
|
+
|
230
|
+
### **1. Project-Specific Setup**
|
231
|
+
- Always run `cursorflow init .` in each project
|
232
|
+
- Customize cursor-test-config.json for your stack
|
233
|
+
- Test locally before staging/production
|
234
|
+
|
235
|
+
### **2. Team Setup**
|
236
|
+
- Add cursor-test-config.json to version control
|
237
|
+
- Document environment-specific settings
|
238
|
+
- Share CLI commands for common workflows
|
239
|
+
|
240
|
+
### **3. Maintenance**
|
241
|
+
```bash
|
242
|
+
# Check for updates
|
243
|
+
cursorflow check-updates
|
244
|
+
|
245
|
+
# Update CursorFlow and rules
|
246
|
+
cursorflow update
|
247
|
+
|
248
|
+
# Keep browser dependencies current
|
249
|
+
cursorflow install-deps
|
250
|
+
```
|
251
|
+
|
252
|
+
## 🎪 **Essential CLI Commands**
|
253
|
+
|
254
|
+
### **Setup:**
|
255
|
+
```bash
|
256
|
+
pip install cursorflow # Install CLI
|
257
|
+
cursorflow init . # Initialize project
|
258
|
+
cursorflow install-deps # Install browser automation
|
259
|
+
```
|
260
|
+
|
261
|
+
### **Testing:**
|
262
|
+
```bash
|
263
|
+
cursorflow test component --base-url http://localhost:3000
|
264
|
+
cursorflow auto-test # Auto-detect and test
|
265
|
+
```
|
266
|
+
|
267
|
+
### **Maintenance:**
|
268
|
+
```bash
|
269
|
+
cursorflow check-updates # Check for new versions
|
270
|
+
cursorflow update # Update package and rules
|
271
|
+
cursorflow --help # View all commands
|
272
|
+
```
|
273
|
+
|
274
|
+
## 🎯 **Success Criteria**
|
275
|
+
|
276
|
+
### **Installation Complete When:**
|
277
|
+
- `cursorflow --version` shows current version
|
278
|
+
- `cursorflow init .` creates cursor-test-config.json
|
279
|
+
- `cursorflow test component` returns structured JSON
|
280
|
+
- `.cursorflow/artifacts/` directory contains test results
|
281
|
+
|
282
|
+
### **Ready for Autonomous Operation When:**
|
283
|
+
- All CLI commands work without errors
|
284
|
+
- Configuration matches your development environment
|
285
|
+
- Test artifacts are created and organized properly
|
286
|
+
- Cursor can use `cursorflow test` for any component
|
287
|
+
|
288
|
+
## 🌟 **Result: Cursor Superpowers Activated!**
|
289
|
+
|
290
|
+
Once installed, Cursor can autonomously:
|
291
|
+
- Test any UI component with simple CLI commands
|
292
|
+
- Collect comprehensive browser and server data
|
293
|
+
- Analyze results and make informed decisions
|
294
|
+
- Iterate on designs with visual feedback
|
295
|
+
- Debug issues with complete visibility
|
296
|
+
|
297
|
+
**Installation complete = Development superpowers activated!** 🚀
|
@@ -0,0 +1,423 @@
|
|
1
|
+
# CursorFlow Usage Rules for Cursor AI
|
2
|
+
|
3
|
+
## 🔥 **PRIMARY USE CASE: Hot Reload CSS Iteration**
|
4
|
+
|
5
|
+
**ALWAYS USE `css_iteration_persistent()` for CSS/UI work** - this is CursorFlow's core strength:
|
6
|
+
|
7
|
+
- 🚀 **3-5x faster** than normal testing with hot reload integration
|
8
|
+
- 🎯 **Preserves application state** during CSS iterations
|
9
|
+
- 🔥 **Automatic hot reload detection** (Webpack HMR, Vite, Next.js, etc.)
|
10
|
+
- ⚡ **Instant visual feedback** without page reloads
|
11
|
+
- 🧠 **Intelligent session management** with automatic cleanup
|
12
|
+
|
13
|
+
## When to Use CursorFlow
|
14
|
+
|
15
|
+
### **CSS/UI Development (PRIORITY 1 - Use Persistent Sessions)**
|
16
|
+
- CSS styling, layout adjustments, responsive design
|
17
|
+
- Visual hierarchy improvements, spacing, typography
|
18
|
+
- Component styling and design system work
|
19
|
+
- UI bug fixes and visual improvements
|
20
|
+
- Design iteration and rapid prototyping
|
21
|
+
|
22
|
+
### **UI Testing & Debugging (Use CLI)**
|
23
|
+
- Form submissions and user interactions
|
24
|
+
- Authentication flows and session handling
|
25
|
+
- Frontend-backend interaction problems
|
26
|
+
- Error reproduction and debugging
|
27
|
+
- Cross-browser compatibility testing
|
28
|
+
|
29
|
+
## 🔥 **Hot Reload CSS Iteration (PRIMARY METHOD)**
|
30
|
+
|
31
|
+
### **Ultra-Fast CSS Iteration Pattern**
|
32
|
+
```python
|
33
|
+
from cursorflow import CursorFlow
|
34
|
+
|
35
|
+
# Initialize with hot reload support
|
36
|
+
flow = CursorFlow(
|
37
|
+
base_url="http://localhost:3000", # Your dev server
|
38
|
+
log_config={"source": "local", "paths": ["logs/app.log"]},
|
39
|
+
browser_config={"hot_reload_enabled": True, "keep_alive": True}
|
40
|
+
)
|
41
|
+
|
42
|
+
# CSS changes to test rapidly
|
43
|
+
css_changes = [
|
44
|
+
{
|
45
|
+
"name": "improve-spacing",
|
46
|
+
"css": ".container { gap: 2rem; padding: 1.5rem; }",
|
47
|
+
"rationale": "Better visual hierarchy"
|
48
|
+
},
|
49
|
+
{
|
50
|
+
"name": "add-shadows",
|
51
|
+
"css": ".card { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }",
|
52
|
+
"rationale": "Add depth and visual interest"
|
53
|
+
}
|
54
|
+
]
|
55
|
+
|
56
|
+
# Execute with persistent session - 3-5x faster!
|
57
|
+
results = await flow.css_iteration_persistent(
|
58
|
+
base_actions=[{"navigate": "/dashboard"}, {"wait_for": "#main-content"}],
|
59
|
+
css_changes=css_changes,
|
60
|
+
session_options={"hot_reload": True, "keep_session_alive": True}
|
61
|
+
)
|
62
|
+
|
63
|
+
# Analyze results
|
64
|
+
print(f"🔥 Hot reload used: {results.get('hot_reload_used')}")
|
65
|
+
print(f"⚡ Iterations/min: {results.get('persistent_analysis', {}).get('iteration_speed_metrics', {}).get('iterations_per_minute', 0):.1f}")
|
66
|
+
```
|
67
|
+
|
68
|
+
### **Session Continuation (No Page Reload!)**
|
69
|
+
```python
|
70
|
+
# First iteration - sets up persistent session
|
71
|
+
results1 = await flow.css_iteration_persistent(
|
72
|
+
base_actions=[{"navigate": "/page"}],
|
73
|
+
css_changes=[{"name": "initial", "css": ".container { display: flex; }"}],
|
74
|
+
session_options={"session_id": "my_session", "keep_session_alive": True}
|
75
|
+
)
|
76
|
+
|
77
|
+
# Continue with same session - INSTANT feedback!
|
78
|
+
results2 = await flow.css_iteration_persistent(
|
79
|
+
base_actions=[], # No base actions needed - session preserved!
|
80
|
+
css_changes=[{"name": "refine", "css": ".container { gap: 1rem; }"}],
|
81
|
+
session_options={"session_id": "my_session", "reuse_session": True}
|
82
|
+
)
|
83
|
+
```
|
84
|
+
|
85
|
+
### **Hot Reload Decision Framework**
|
86
|
+
1. **User mentions CSS/styling** → Use `css_iteration_persistent()`
|
87
|
+
2. **User wants UI improvements** → Use persistent sessions
|
88
|
+
3. **User asks to "test this component"** → Use hot reload iteration
|
89
|
+
4. **User reports layout issues** → Use CSS iteration with screenshots
|
90
|
+
5. **User wants responsive testing** → Use persistent sessions with viewport changes
|
91
|
+
|
92
|
+
## Basic CursorFlow CLI Usage
|
93
|
+
|
94
|
+
### Simple Tests
|
95
|
+
```bash
|
96
|
+
# Test with inline actions
|
97
|
+
cursorflow test \
|
98
|
+
--base-url http://localhost:3000 \
|
99
|
+
--actions '[
|
100
|
+
{"navigate": "/page"},
|
101
|
+
{"wait_for": "#element"},
|
102
|
+
{"screenshot": "state"}
|
103
|
+
]'
|
104
|
+
|
105
|
+
# Simple path test
|
106
|
+
cursorflow test --base-url http://localhost:3000 --path "/dashboard"
|
107
|
+
```
|
108
|
+
|
109
|
+
### Complex Tests
|
110
|
+
```bash
|
111
|
+
# Create action file first
|
112
|
+
cat > test-actions.json << 'EOF'
|
113
|
+
[
|
114
|
+
{"navigate": "/login"},
|
115
|
+
{"fill": {"selector": "#username", "value": "test@example.com"}},
|
116
|
+
{"fill": {"selector": "#password", "value": "testpass"}},
|
117
|
+
{"click": "#login-button"},
|
118
|
+
{"wait_for": ".dashboard"},
|
119
|
+
{"screenshot": "logged-in"}
|
120
|
+
]
|
121
|
+
EOF
|
122
|
+
|
123
|
+
# Run test
|
124
|
+
cursorflow test --base-url http://localhost:3000 --actions test-actions.json
|
125
|
+
```
|
126
|
+
|
127
|
+
## Available Actions
|
128
|
+
|
129
|
+
| Action | Syntax | Purpose |
|
130
|
+
|--------|--------|---------|
|
131
|
+
| `navigate` | `{"navigate": "/path"}` | Go to URL or path |
|
132
|
+
| `click` | `{"click": "#selector"}` | Click element |
|
133
|
+
| `fill` | `{"fill": {"selector": "#input", "value": "text"}}` | Fill form field |
|
134
|
+
| `wait` | `{"wait": 2}` | Wait seconds |
|
135
|
+
| `wait_for` | `{"wait_for": "#element"}` | Wait for element |
|
136
|
+
| `screenshot` | `{"screenshot": "name"}` | Take screenshot |
|
137
|
+
|
138
|
+
## Common Usage Patterns
|
139
|
+
|
140
|
+
### Form Testing
|
141
|
+
```bash
|
142
|
+
cursorflow test \
|
143
|
+
--base-url http://localhost:3000 \
|
144
|
+
--actions '[
|
145
|
+
{"navigate": "/contact"},
|
146
|
+
{"wait_for": "form"},
|
147
|
+
{"fill": {"selector": "#name", "value": "John Doe"}},
|
148
|
+
{"fill": {"selector": "#email", "value": "john@example.com"}},
|
149
|
+
{"click": "#submit"},
|
150
|
+
{"wait_for": ".success, .error"},
|
151
|
+
{"screenshot": "result"}
|
152
|
+
]'
|
153
|
+
```
|
154
|
+
|
155
|
+
### Login Flow Testing
|
156
|
+
```bash
|
157
|
+
cursorflow test \
|
158
|
+
--base-url http://localhost:3000 \
|
159
|
+
--actions '[
|
160
|
+
{"navigate": "/login"},
|
161
|
+
{"wait_for": "#login-form"},
|
162
|
+
{"fill": {"selector": "#username", "value": "testuser"}},
|
163
|
+
{"fill": {"selector": "#password", "value": "testpass"}},
|
164
|
+
{"click": "#login-button"},
|
165
|
+
{"wait_for": ".dashboard, .error-message"},
|
166
|
+
{"screenshot": "login-result"}
|
167
|
+
]'
|
168
|
+
```
|
169
|
+
|
170
|
+
### Shopping Cart Testing
|
171
|
+
```bash
|
172
|
+
cursorflow test \
|
173
|
+
--base-url http://localhost:3000 \
|
174
|
+
--actions '[
|
175
|
+
{"navigate": "/products"},
|
176
|
+
{"click": ".product:first-child .add-to-cart"},
|
177
|
+
{"wait_for": ".cart-notification"},
|
178
|
+
{"click": "#cart-icon"},
|
179
|
+
{"screenshot": "cart-contents"}
|
180
|
+
]'
|
181
|
+
```
|
182
|
+
|
183
|
+
## Analyzing Results
|
184
|
+
|
185
|
+
### **Hot Reload CSS Iteration Results**
|
186
|
+
CursorFlow generates comprehensive analysis optimized for CSS decisions:
|
187
|
+
|
188
|
+
```json
|
189
|
+
{
|
190
|
+
"session_id": "css_session_123",
|
191
|
+
"hot_reload_used": true,
|
192
|
+
"execution_time": 4.2,
|
193
|
+
|
194
|
+
"session_context": {
|
195
|
+
"session_persistent": true,
|
196
|
+
"hot_reload_available": true,
|
197
|
+
"iteration_count": 15
|
198
|
+
},
|
199
|
+
|
200
|
+
"persistent_analysis": {
|
201
|
+
"hot_reload_effectiveness": {
|
202
|
+
"hot_reload_usage_rate": 0.95,
|
203
|
+
"time_saved_seconds": 45.2,
|
204
|
+
"quality": "excellent"
|
205
|
+
},
|
206
|
+
"iteration_speed_metrics": {
|
207
|
+
"iterations_per_minute": 12.5,
|
208
|
+
"average_iteration_time": 4.8
|
209
|
+
}
|
210
|
+
},
|
211
|
+
|
212
|
+
"iterations": [
|
213
|
+
{
|
214
|
+
"name": "improve-spacing",
|
215
|
+
"hot_reload_used": true,
|
216
|
+
"screenshot": ".cursorflow/artifacts/improve-spacing.png",
|
217
|
+
"console_errors": [],
|
218
|
+
"performance_impact": {"render_time": 45}
|
219
|
+
}
|
220
|
+
],
|
221
|
+
|
222
|
+
"recommended_actions": [
|
223
|
+
{
|
224
|
+
"action": "implement_css_changes",
|
225
|
+
"css_to_apply": ".container { gap: 2rem; }",
|
226
|
+
"target_files": ["components/Dashboard.css"]
|
227
|
+
}
|
228
|
+
]
|
229
|
+
}
|
230
|
+
```
|
231
|
+
|
232
|
+
### **Key Analysis Points for CSS Iteration**
|
233
|
+
|
234
|
+
1. **Hot Reload Effectiveness**: Check `hot_reload_used` and `time_saved_seconds`
|
235
|
+
2. **Visual Quality**: Review screenshots for each iteration
|
236
|
+
3. **Performance Impact**: Monitor `render_time` and console errors
|
237
|
+
4. **Session Health**: Evaluate `session_persistent` and `iteration_count`
|
238
|
+
5. **Implementation Readiness**: Use `recommended_actions` for next steps
|
239
|
+
|
240
|
+
### **Traditional Test Results**
|
241
|
+
CLI tests generate `{test_name}_test_results.json` with:
|
242
|
+
|
243
|
+
- **browser_events**: UI interactions and console errors
|
244
|
+
- **server_logs**: Backend activity during the test
|
245
|
+
- **organized_timeline**: Chronological correlation of all events
|
246
|
+
- **artifacts**: Screenshots and network data
|
247
|
+
|
248
|
+
## The Request → Test → Analyze → Adjust → Repeat Pattern
|
249
|
+
|
250
|
+
### **🔥 HOT RELOAD CSS ITERATION PATTERN (PRIMARY)**
|
251
|
+
|
252
|
+
#### 1. REQUEST Phase
|
253
|
+
User mentions CSS, styling, layout, or visual improvements.
|
254
|
+
|
255
|
+
#### 2. TEST Phase (Persistent Session)
|
256
|
+
```python
|
257
|
+
results = await flow.css_iteration_persistent(
|
258
|
+
base_actions=[{"navigate": "/component"}],
|
259
|
+
css_changes=[
|
260
|
+
{"name": "fix-spacing", "css": ".container { gap: 2rem; }"},
|
261
|
+
{"name": "improve-typography", "css": "h1 { font-size: 2.5rem; }"}
|
262
|
+
],
|
263
|
+
session_options={"hot_reload": True, "keep_session_alive": True}
|
264
|
+
)
|
265
|
+
```
|
266
|
+
|
267
|
+
#### 3. ANALYZE Phase
|
268
|
+
Examine persistent session results:
|
269
|
+
- Check `hot_reload_used` for speed optimization
|
270
|
+
- Review screenshots for visual improvements
|
271
|
+
- Monitor `console_errors` for CSS issues
|
272
|
+
- Evaluate `iteration_speed_metrics` for efficiency
|
273
|
+
|
274
|
+
#### 4. ADJUST Phase
|
275
|
+
Apply recommended CSS to actual files:
|
276
|
+
```python
|
277
|
+
css_to_apply = results["recommended_actions"][0]["css_to_apply"]
|
278
|
+
target_files = results["recommended_actions"][0]["target_files"]
|
279
|
+
# Apply to actual CSS files
|
280
|
+
```
|
281
|
+
|
282
|
+
#### 5. REPEAT Phase (Session Continuation)
|
283
|
+
Continue with same session for additional refinements:
|
284
|
+
```python
|
285
|
+
results2 = await flow.css_iteration_persistent(
|
286
|
+
base_actions=[], # No reload needed!
|
287
|
+
css_changes=[{"name": "polish", "css": "..."}],
|
288
|
+
session_options={"session_id": "same_session", "reuse_session": True}
|
289
|
+
)
|
290
|
+
```
|
291
|
+
|
292
|
+
### **Traditional Test Pattern (For Non-CSS Work)**
|
293
|
+
|
294
|
+
#### 1. REQUEST → 2. TEST → 3. ANALYZE → 4. ADJUST → 5. REPEAT
|
295
|
+
```bash
|
296
|
+
cursorflow test --base-url http://localhost:3000 --actions 'JSON_ACTIONS'
|
297
|
+
# Examine results, make changes, re-test
|
298
|
+
```
|
299
|
+
|
300
|
+
## Common CLI Options
|
301
|
+
|
302
|
+
| Option | Purpose | Example |
|
303
|
+
|--------|---------|---------|
|
304
|
+
| `--actions` | Test actions (JSON) | `--actions '[{"navigate": "/"}]'` |
|
305
|
+
| `--base-url` | Target URL | `--base-url http://localhost:3000` |
|
306
|
+
| `--verbose` | Detailed output | `--verbose` |
|
307
|
+
| `--logs` | Log source | `--logs local` |
|
308
|
+
|
309
|
+
## Error Handling
|
310
|
+
|
311
|
+
When tests fail:
|
312
|
+
1. Check the JSON results for error details
|
313
|
+
2. Look at browser console errors
|
314
|
+
3. Examine server log entries
|
315
|
+
4. Review screenshots for visual clues
|
316
|
+
5. Identify the correlation between browser and server events
|
317
|
+
|
318
|
+
## CSS and Layout Testing
|
319
|
+
|
320
|
+
### **🔥 Hot Reload CSS Testing (RECOMMENDED)**
|
321
|
+
```python
|
322
|
+
# Ultra-fast CSS iteration with persistent sessions
|
323
|
+
css_changes = [
|
324
|
+
{"name": "spacing-fix", "css": ".dashboard { gap: 2rem; padding: 1.5rem; }"},
|
325
|
+
{"name": "responsive-grid", "css": ".grid { grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); }"}
|
326
|
+
]
|
327
|
+
|
328
|
+
results = await flow.css_iteration_persistent(
|
329
|
+
base_actions=[{"navigate": "/dashboard"}, {"screenshot": "baseline"}],
|
330
|
+
css_changes=css_changes,
|
331
|
+
session_options={"hot_reload": True, "keep_session_alive": True}
|
332
|
+
)
|
333
|
+
|
334
|
+
# Get instant visual feedback with preserved application state
|
335
|
+
best_iteration = results["summary"]["recommended_iteration"]
|
336
|
+
print(f"Best CSS approach: {best_iteration}")
|
337
|
+
```
|
338
|
+
|
339
|
+
### **Traditional CLI Testing (Legacy)**
|
340
|
+
```bash
|
341
|
+
# Before changes
|
342
|
+
cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "before"}]'
|
343
|
+
|
344
|
+
# After changes
|
345
|
+
cursorflow test --base-url http://localhost:3000 --actions '[{"navigate": "/dashboard"}, {"screenshot": "after"}]'
|
346
|
+
```
|
347
|
+
|
348
|
+
## Authentication Testing
|
349
|
+
|
350
|
+
```bash
|
351
|
+
cursorflow test \
|
352
|
+
--base-url http://localhost:3000 \
|
353
|
+
--actions '[
|
354
|
+
{"navigate": "/login"},
|
355
|
+
{"fill": {"selector": "#username", "value": "test@example.com"}},
|
356
|
+
{"fill": {"selector": "#password", "value": "testpass"}},
|
357
|
+
{"click": "#login-button"},
|
358
|
+
{"wait_for": ".dashboard"},
|
359
|
+
{"navigate": "/protected-page"},
|
360
|
+
{"wait_for": "#protected-content"},
|
361
|
+
{"screenshot": "authenticated"}
|
362
|
+
]'
|
363
|
+
```
|
364
|
+
|
365
|
+
## Best Practices
|
366
|
+
|
367
|
+
### **🔥 Hot Reload CSS Iteration Best Practices**
|
368
|
+
1. **Always use `css_iteration_persistent()` for CSS work** - 3-5x faster than CLI
|
369
|
+
2. **Keep sessions alive** - Set `keep_session_alive: True` for continued iteration
|
370
|
+
3. **Use descriptive CSS change names** - "spacing-fix", "responsive-layout", "color-theme"
|
371
|
+
4. **Test multiple approaches** - Include 2-3 CSS variations per iteration
|
372
|
+
5. **Continue sessions** - Reuse session_id for related styling work
|
373
|
+
6. **Monitor hot reload effectiveness** - Check `hot_reload_used` in results
|
374
|
+
|
375
|
+
### **Traditional CLI Best Practices**
|
376
|
+
1. **Use descriptive test names**: `login-flow`, `checkout-process`, `form-validation`
|
377
|
+
2. **Take screenshots at key moments**: Before and after important actions
|
378
|
+
3. **Wait for elements**: Use `wait_for` instead of arbitrary `wait` times
|
379
|
+
4. **Test error scenarios**: Include invalid inputs to test error handling
|
380
|
+
5. **Keep actions focused**: Test one specific flow per command
|
381
|
+
6. **Use action files for complex tests**: Easier to maintain and reuse
|
382
|
+
|
383
|
+
### **⚡ Performance Tips**
|
384
|
+
- **Hot reload detected**: Expect 3-5x faster iterations
|
385
|
+
- **Session continuation**: No page reloads = preserved application state
|
386
|
+
- **File monitoring**: CursorFlow syncs with your file changes automatically
|
387
|
+
- **Smart cleanup**: Sessions auto-optimize and clean up when needed
|
388
|
+
|
389
|
+
## Installation Commands
|
390
|
+
|
391
|
+
```bash
|
392
|
+
# Initial setup
|
393
|
+
pip install cursorflow
|
394
|
+
cursorflow init .
|
395
|
+
|
396
|
+
# Install Cursor rules
|
397
|
+
cursorflow install-rules
|
398
|
+
|
399
|
+
# Update when needed
|
400
|
+
cursorflow update
|
401
|
+
```
|
402
|
+
|
403
|
+
## 🎯 **CRITICAL REMINDERS FOR CURSOR AI**
|
404
|
+
|
405
|
+
### **🔥 PRIMARY WORKFLOW: Hot Reload CSS Iteration**
|
406
|
+
- **ALWAYS use `css_iteration_persistent()` for CSS/UI work**
|
407
|
+
- **3-5x faster than CLI** - enables rapid design exploration
|
408
|
+
- **Preserves application state** - no lost context during iteration
|
409
|
+
- **Auto-detects hot reload** - works with Webpack, Vite, Next.js, etc.
|
410
|
+
|
411
|
+
### **Decision Framework:**
|
412
|
+
- **User mentions CSS/styling/layout** → `css_iteration_persistent()`
|
413
|
+
- **User wants UI improvements** → Persistent sessions with hot reload
|
414
|
+
- **User asks to "test component"** → Hot reload CSS iteration
|
415
|
+
- **User reports form/auth issues** → Traditional CLI testing
|
416
|
+
|
417
|
+
### **Key Success Patterns:**
|
418
|
+
1. **Start persistent session** → Test multiple CSS approaches → Continue session → Apply best result
|
419
|
+
2. **Monitor `hot_reload_used`** → Expect 12+ iterations per minute when working
|
420
|
+
3. **Use session continuation** → Avoid page reloads → Maintain complex application state
|
421
|
+
4. **Apply recommended CSS** → Let CursorFlow identify target files → Implement changes
|
422
|
+
|
423
|
+
Remember: **CursorFlow's persistent sessions with hot reload are 3-5x faster than traditional testing.** Always prioritize this workflow for CSS/UI development to maximize iteration speed and preserve application state.
|
@@ -1,6 +1,6 @@
|
|
1
1
|
Metadata-Version: 2.4
|
2
2
|
Name: cursorflow
|
3
|
-
Version: 1.3.
|
3
|
+
Version: 1.3.3
|
4
4
|
Summary: Complete page intelligence for AI-driven development - captures DOM, network, console, and performance data
|
5
5
|
Author-email: GeekWarrior Development <support@cursorflow.dev>
|
6
6
|
License-Expression: MIT
|
@@ -1,7 +1,7 @@
|
|
1
1
|
cursorflow/__init__.py,sha256=nRmHnnnsbDH1A7_d3XkmzB5iJ44bt124zAQhaEhscyY,2450
|
2
2
|
cursorflow/auto_updater.py,sha256=oQ12TIMZ6Cm3HF-x9iRWFtvOLkRh-JWPqitS69-4roE,7851
|
3
3
|
cursorflow/cli.py,sha256=JRznfNAaXuthmCVwQX7yvX8FtAFrZYwemUA7BfvfFOo,25036
|
4
|
-
cursorflow/install_cursorflow_rules.py,sha256=
|
4
|
+
cursorflow/install_cursorflow_rules.py,sha256=ny4c-S1O-V2sITunZO2kk6sCf1yec42UJOEVZu1NCAA,9014
|
5
5
|
cursorflow/updater.py,sha256=pvbSZgg6hgWZBE5AAUPppS5Yzv0yNMp2X_CL2GALg_w,18783
|
6
6
|
cursorflow/core/agent.py,sha256=f3lecgEzDRDdGTVccAtorpLGfNJJ49bbsQAmgr0vNGg,10136
|
7
7
|
cursorflow/core/auth_handler.py,sha256=oRafO6ZdxoHryBIvHsrNV8TECed4GXpJsdEiH0KdPPk,17149
|
@@ -20,9 +20,12 @@ cursorflow/core/persistent_session.py,sha256=FsEHj4wKkycmdp6PFRHv3g333Y74yqra0x_
|
|
20
20
|
cursorflow/core/report_generator.py,sha256=-vosfyrnfVyWDbAIMlMurl90xOXqBae8d6aLd9sEqiY,10113
|
21
21
|
cursorflow/log_sources/local_file.py,sha256=SwA294n_Ozg76ZUF5nPn5W2Fts_XtSOHEcO2S65vnjc,6768
|
22
22
|
cursorflow/log_sources/ssh_remote.py,sha256=TrE9FZ4aI6Cz1vChjvG8RC2KrNlgRKtG0_hC1w8pGDA,7106
|
23
|
-
cursorflow
|
24
|
-
cursorflow-
|
25
|
-
cursorflow-
|
26
|
-
cursorflow-1.3.
|
27
|
-
cursorflow-1.3.
|
28
|
-
cursorflow-1.3.
|
23
|
+
cursorflow/rules/__init__.py,sha256=gPcA-IkhXj03sl7cvZV0wwo7CtEkcyuKs4y0F5oQbqE,458
|
24
|
+
cursorflow/rules/cursorflow-installation.mdc,sha256=Nnu7PuP5nGD6hGAV_x2SX5Y2_uPz3oNA5XUjNJBFC1M,6985
|
25
|
+
cursorflow/rules/cursorflow-usage.mdc,sha256=Zv0TWuo7S3iJHq8R6oBaHRI3V6h-T81pdb7vi-b8NoU,14157
|
26
|
+
cursorflow-1.3.3.dist-info/licenses/LICENSE,sha256=e4QbjAsj3bW-xgQOvQelr8sGLYDoqc48k6cKgCr_pBU,1080
|
27
|
+
cursorflow-1.3.3.dist-info/METADATA,sha256=NVZfDKpe9S5m8Za6lMRgqE9czq6bp-CGzyV41pcGkyk,7659
|
28
|
+
cursorflow-1.3.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
|
29
|
+
cursorflow-1.3.3.dist-info/entry_points.txt,sha256=-Ed_n4Uff7wClEtWS-Py6xmQabecB9f0QAOjX0w7ljA,51
|
30
|
+
cursorflow-1.3.3.dist-info/top_level.txt,sha256=t1UZwRyZP4u-ng2CEcNHmk_ZT4ibQxoihB2IjTF7ovc,11
|
31
|
+
cursorflow-1.3.3.dist-info/RECORD,,
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|