@litmers/cursorflow-orchestrator 0.1.0 → 0.1.2
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.
- package/README.md +375 -310
- package/commands/cursorflow-clean.md +162 -162
- package/commands/cursorflow-init.md +67 -67
- package/commands/cursorflow-monitor.md +131 -131
- package/commands/cursorflow-prepare.md +134 -134
- package/commands/cursorflow-resume.md +181 -181
- package/commands/cursorflow-review.md +220 -220
- package/commands/cursorflow-run.md +129 -129
- package/package.json +13 -4
- package/scripts/ai-security-check.js +224 -0
- package/scripts/release.sh +109 -0
- package/scripts/setup-security.sh +105 -0
- package/src/cli/init.js +69 -4
- package/src/cli/monitor.js +196 -9
- package/src/core/runner.js +187 -9
- package/src/utils/config.js +2 -2
- package/src/utils/cursor-agent.js +96 -0
package/README.md
CHANGED
|
@@ -1,310 +1,375 @@
|
|
|
1
|
-
# CursorFlow
|
|
2
|
-
|
|
3
|
-
>
|
|
4
|
-
|
|
5
|
-
[](https://www.npmjs.com/package/@litmers/cursorflow-orchestrator)
|
|
6
|
+
[](https://github.com/eungjin-cigro/cursorflow/actions/workflows/ci.yml)
|
|
7
|
+
[](https://github.com/eungjin-cigro/cursorflow/actions/workflows/security.yml)
|
|
8
|
+
[](https://github.com/eungjin-cigro/cursorflow/actions/workflows/npm-publish.yml)
|
|
9
|
+
[](https://opensource.org/licenses/MIT)
|
|
10
|
+
[](https://nodejs.org/)
|
|
11
|
+
|
|
12
|
+
## Key Features
|
|
13
|
+
|
|
14
|
+
- 🚀 **Parallel execution**: Run multiple lanes concurrently with Git worktrees
|
|
15
|
+
- 🔍 **Automatic review**: AI-powered code review with iterative feedback
|
|
16
|
+
- 📝 **Detailed logging**: Capture conversations, commits, and Git operations
|
|
17
|
+
- 🔀 **Dependency management**: Automatic dependency gating and resume support
|
|
18
|
+
- 🎯 **Per-lane ports**: Unique dev server ports for each lane
|
|
19
|
+
- 💻 **Cursor integration**: Manage workflows directly inside the IDE with custom commands
|
|
20
|
+
- 🛠️ **Config-driven**: Flexible project-specific configuration
|
|
21
|
+
- 🔒 **Security-first**: Multi-layer automated security scanning before deployment
|
|
22
|
+
|
|
23
|
+
## Quick Start
|
|
24
|
+
|
|
25
|
+
### Install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# npm
|
|
29
|
+
npm install -g @litmers/cursorflow-orchestrator
|
|
30
|
+
|
|
31
|
+
# pnpm (recommended)
|
|
32
|
+
pnpm add -g @litmers/cursorflow-orchestrator
|
|
33
|
+
|
|
34
|
+
# yarn
|
|
35
|
+
yarn global add @litmers/cursorflow-orchestrator
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Requirements
|
|
39
|
+
|
|
40
|
+
- **Node.js** >= 18.0.0
|
|
41
|
+
- **Git** with worktree support
|
|
42
|
+
- **cursor-agent CLI**: `npm install -g @cursor/agent`
|
|
43
|
+
|
|
44
|
+
### Initialize a project
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
cd your-project
|
|
48
|
+
cursorflow init --example
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
This command:
|
|
52
|
+
1. Creates the `cursorflow.config.js` config file
|
|
53
|
+
2. Creates `_cursorflow/tasks/` and `_cursorflow/logs/` directories
|
|
54
|
+
3. Installs Cursor IDE commands
|
|
55
|
+
4. Generates example tasks when `--example` is provided
|
|
56
|
+
|
|
57
|
+
### Run the example
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
# Run example tasks
|
|
61
|
+
cursorflow run _cursorflow/tasks/example/
|
|
62
|
+
|
|
63
|
+
# Monitor from another terminal
|
|
64
|
+
cursorflow monitor --watch
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## 🧪 Testing CursorFlow
|
|
68
|
+
|
|
69
|
+
A complete demo project is included for testing with real LLM execution.
|
|
70
|
+
|
|
71
|
+
### Quick Test
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# From the CursorFlow repository root
|
|
75
|
+
./test-cursorflow.sh setup # Verify prerequisites
|
|
76
|
+
./test-cursorflow.sh run # Run demo with LLM
|
|
77
|
+
./test-cursorflow.sh watch # Monitor in real-time
|
|
78
|
+
./test-cursorflow.sh clean # Clean up after test
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### What Gets Tested
|
|
82
|
+
|
|
83
|
+
- ✅ Task orchestration with 2 parallel lanes
|
|
84
|
+
- ✅ Git worktree creation and management
|
|
85
|
+
- ✅ Real LLM execution (Claude Sonnet 4.5 via cursor-agent)
|
|
86
|
+
- ✅ Branch creation and commits
|
|
87
|
+
- ✅ Real-time monitoring with status updates
|
|
88
|
+
- ✅ Complete log capture (conversation + terminal)
|
|
89
|
+
|
|
90
|
+
### Demo Tasks
|
|
91
|
+
|
|
92
|
+
1. **create-utils**: Creates `src/utils.js` with utility functions
|
|
93
|
+
2. **add-tests**: Creates `src/utils.test.js` with simple tests
|
|
94
|
+
|
|
95
|
+
Each task runs ~1-2 minutes, demonstrating the full CursorFlow workflow.
|
|
96
|
+
|
|
97
|
+
**See**: `test-projects/demo-project/README.md` for detailed documentation.
|
|
98
|
+
|
|
99
|
+
## 📚 Examples
|
|
100
|
+
|
|
101
|
+
Ready-to-use examples are included in the `examples/` directory.
|
|
102
|
+
|
|
103
|
+
### Demo Project
|
|
104
|
+
|
|
105
|
+
A complete example demonstrating CursorFlow's core features:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# Copy example tasks to your project
|
|
109
|
+
cd your-project
|
|
110
|
+
cursorflow init
|
|
111
|
+
cp -r /path/to/cursorflow/examples/demo-project/_cursorflow/tasks/demo-test _cursorflow/tasks/
|
|
112
|
+
|
|
113
|
+
# Run the demo
|
|
114
|
+
cursorflow run _cursorflow/tasks/demo-test/
|
|
115
|
+
|
|
116
|
+
# Monitor in real-time
|
|
117
|
+
cursorflow monitor --watch
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
**Includes:**
|
|
121
|
+
- 2 parallel tasks with real LLM execution
|
|
122
|
+
- Complete documentation and setup instructions
|
|
123
|
+
- Expected results and troubleshooting guide
|
|
124
|
+
|
|
125
|
+
**See**: `examples/demo-project/README.md` for detailed instructions.
|
|
126
|
+
|
|
127
|
+
**Browse more examples**: `examples/README.md`
|
|
128
|
+
|
|
129
|
+
## Cursor IDE Integration
|
|
130
|
+
|
|
131
|
+
CursorFlow ships custom commands that are available directly inside Cursor IDE.
|
|
132
|
+
|
|
133
|
+
### Install commands
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# Installed automatically during init
|
|
137
|
+
cursorflow init
|
|
138
|
+
|
|
139
|
+
# Or install manually
|
|
140
|
+
npx cursorflow-setup
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Usage
|
|
144
|
+
|
|
145
|
+
Type `/` in Cursor chat and use:
|
|
146
|
+
|
|
147
|
+
- `/cursorflow-init` - initialize a project
|
|
148
|
+
- `/cursorflow-prepare` - prepare tasks
|
|
149
|
+
- `/cursorflow-run` - run orchestration
|
|
150
|
+
- `/cursorflow-monitor` - monitor runs
|
|
151
|
+
- `/cursorflow-clean` - clean resources
|
|
152
|
+
- `/cursorflow-resume` - resume a lane
|
|
153
|
+
- `/cursorflow-review` - configure or check reviews
|
|
154
|
+
|
|
155
|
+
## CLI Commands
|
|
156
|
+
|
|
157
|
+
### Init
|
|
158
|
+
```bash
|
|
159
|
+
cursorflow init [options]
|
|
160
|
+
--example Create example tasks
|
|
161
|
+
--with-commands Install Cursor commands (default: true)
|
|
162
|
+
--config-only Generate config file only
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Prepare tasks
|
|
166
|
+
```bash
|
|
167
|
+
cursorflow prepare <feature> [options]
|
|
168
|
+
--lanes <number> Number of lanes
|
|
169
|
+
--template <path> Template file path
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### Run
|
|
173
|
+
```bash
|
|
174
|
+
cursorflow run <tasks-dir> [options]
|
|
175
|
+
--dry-run Show the execution plan only
|
|
176
|
+
--executor <type> cursor-agent | cloud
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
### Monitor
|
|
180
|
+
```bash
|
|
181
|
+
cursorflow monitor [run-dir] [options]
|
|
182
|
+
--watch Live monitoring
|
|
183
|
+
--interval <sec> Refresh interval
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Clean
|
|
187
|
+
```bash
|
|
188
|
+
cursorflow clean <type> [options]
|
|
189
|
+
branches Clean branches
|
|
190
|
+
worktrees Clean worktrees
|
|
191
|
+
logs Clean logs
|
|
192
|
+
all Clean everything
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Resume
|
|
196
|
+
```bash
|
|
197
|
+
cursorflow resume <lane> [options]
|
|
198
|
+
--clean Clean branches before restart
|
|
199
|
+
--restart Restart from the beginning
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Configuration
|
|
203
|
+
|
|
204
|
+
### Config file (cursorflow.config.js)
|
|
205
|
+
|
|
206
|
+
```javascript
|
|
207
|
+
module.exports = {
|
|
208
|
+
// Directories
|
|
209
|
+
tasksDir: '_cursorflow/tasks',
|
|
210
|
+
logsDir: '_cursorflow/logs',
|
|
211
|
+
|
|
212
|
+
// Git settings
|
|
213
|
+
baseBranch: 'main',
|
|
214
|
+
branchPrefix: 'feature/',
|
|
215
|
+
|
|
216
|
+
// Run settings
|
|
217
|
+
executor: 'cursor-agent', // 'cursor-agent' | 'cloud'
|
|
218
|
+
pollInterval: 60,
|
|
219
|
+
|
|
220
|
+
// Dependency management
|
|
221
|
+
allowDependencyChange: false,
|
|
222
|
+
lockfileReadOnly: true,
|
|
223
|
+
|
|
224
|
+
// Review settings
|
|
225
|
+
enableReview: true,
|
|
226
|
+
reviewModel: 'sonnet-4.5-thinking',
|
|
227
|
+
maxReviewIterations: 3,
|
|
228
|
+
|
|
229
|
+
// Default lane settings
|
|
230
|
+
defaultLaneConfig: {
|
|
231
|
+
devPort: 3001,
|
|
232
|
+
autoCreatePr: false,
|
|
233
|
+
},
|
|
234
|
+
|
|
235
|
+
// Logging
|
|
236
|
+
logLevel: 'info',
|
|
237
|
+
verboseGit: false,
|
|
238
|
+
};
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Task file (JSON)
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"repository": "https://github.com/your-org/your-repo",
|
|
246
|
+
"baseBranch": "main",
|
|
247
|
+
"branchPrefix": "feature/my-",
|
|
248
|
+
"executor": "cursor-agent",
|
|
249
|
+
"laneNumber": 1,
|
|
250
|
+
"devPort": 3001,
|
|
251
|
+
"enableReview": true,
|
|
252
|
+
"tasks": [
|
|
253
|
+
{
|
|
254
|
+
"name": "implement",
|
|
255
|
+
"model": "sonnet-4.5",
|
|
256
|
+
"acceptanceCriteria": [
|
|
257
|
+
"No build errors",
|
|
258
|
+
"Key features implemented"
|
|
259
|
+
],
|
|
260
|
+
"prompt": "Implementation instructions..."
|
|
261
|
+
}
|
|
262
|
+
]
|
|
263
|
+
}
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
## Usage Examples
|
|
267
|
+
|
|
268
|
+
### Single feature development
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
# 1. Prepare tasks
|
|
272
|
+
cursorflow prepare AddUserAuth --lanes 1
|
|
273
|
+
|
|
274
|
+
# 2. Edit the task JSON
|
|
275
|
+
# _cursorflow/tasks/2512191830_AddUserAuth/01-task.json
|
|
276
|
+
|
|
277
|
+
# 3. Run
|
|
278
|
+
cursorflow run _cursorflow/tasks/2512191830_AddUserAuth/
|
|
279
|
+
|
|
280
|
+
# 4. Monitor
|
|
281
|
+
cursorflow monitor --watch
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
### Multi-domain parallel development
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
# 1. Prepare tasks (5 lanes)
|
|
288
|
+
cursorflow prepare AdminDashboard --lanes 5
|
|
289
|
+
|
|
290
|
+
# 2. Configure each lane
|
|
291
|
+
# 01-dashboard.json, 02-clients.json, ...
|
|
292
|
+
|
|
293
|
+
# 3. Run in parallel
|
|
294
|
+
cursorflow run _cursorflow/tasks/2512191830_AdminDashboard/
|
|
295
|
+
|
|
296
|
+
# 4. Live monitor
|
|
297
|
+
cursorflow monitor --watch --interval 5
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## Architecture
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
┌─────────────────────────────────────────────────────────┐
|
|
304
|
+
│ CursorFlow CLI │
|
|
305
|
+
└──────────────────┬──────────────────────────────────────┘
|
|
306
|
+
│
|
|
307
|
+
┌──────────┴──────────┐
|
|
308
|
+
│ │
|
|
309
|
+
┌────▼────┐ ┌────▼────┐
|
|
310
|
+
│ Config │ │ Core │
|
|
311
|
+
│ System │ │ Engine │
|
|
312
|
+
└────┬────┘ └────┬────┘
|
|
313
|
+
│ │
|
|
314
|
+
│ ┌──────────┼──────────┐
|
|
315
|
+
│ │ │ │
|
|
316
|
+
┌────▼────┐ ┌─▼──┐ ┌────▼────┐ ┌─▼─────┐
|
|
317
|
+
│ Git │ │Run │ │ Monitor │ │Review │
|
|
318
|
+
│ Utils │ │ner │ │ │ │ │
|
|
319
|
+
└─────────┘ └─┬──┘ └─────────┘ └───────┘
|
|
320
|
+
│
|
|
321
|
+
┌────────┼────────┐
|
|
322
|
+
│ │ │
|
|
323
|
+
┌────▼───┐ ┌─▼──────┐ │
|
|
324
|
+
│Worktree│ │ Cursor │ │
|
|
325
|
+
│ │ │ Agent │ │
|
|
326
|
+
└────────┘ └────────┘ │
|
|
327
|
+
│
|
|
328
|
+
┌────▼────┐
|
|
329
|
+
│ Logs │
|
|
330
|
+
│ State │
|
|
331
|
+
└─────────┘
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
## Documentation
|
|
335
|
+
|
|
336
|
+
- [📖 User Guide](docs/GUIDE.md) - Detailed usage instructions
|
|
337
|
+
- [📋 API Reference](docs/API.md) - CLI and config API
|
|
338
|
+
- [🎨 Command Guide](docs/COMMANDS.md) - Cursor command usage
|
|
339
|
+
- [🏗️ Architecture](docs/ARCHITECTURE.md) - System structure
|
|
340
|
+
- [🔧 Troubleshooting](docs/TROUBLESHOOTING.md) - Issue resolution
|
|
341
|
+
- [📦 Examples](examples/) - Practical examples
|
|
342
|
+
|
|
343
|
+
## Roadmap
|
|
344
|
+
|
|
345
|
+
- [ ] v1.0: Core features and base docs
|
|
346
|
+
- [ ] v1.1: Enhanced review system
|
|
347
|
+
- [ ] v1.2: Improved cloud execution
|
|
348
|
+
- [ ] v1.3: Plugin system
|
|
349
|
+
- [ ] v2.0: GUI tool
|
|
350
|
+
|
|
351
|
+
## Contributing
|
|
352
|
+
|
|
353
|
+
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
354
|
+
|
|
355
|
+
### Set up dev environment
|
|
356
|
+
```bash
|
|
357
|
+
git clone https://github.com/eungjin-cigro/cursorflow.git
|
|
358
|
+
cd cursorflow
|
|
359
|
+
pnpm install
|
|
360
|
+
pnpm test
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
## License
|
|
364
|
+
|
|
365
|
+
MIT © Eugene Jin
|
|
366
|
+
|
|
367
|
+
## Support
|
|
368
|
+
|
|
369
|
+
- 🐛 [Issue Tracker](https://github.com/eungjin-cigro/cursorflow/issues)
|
|
370
|
+
- 💬 [Discussions](https://github.com/eungjin-cigro/cursorflow/discussions)
|
|
371
|
+
- 📧 Email: eungjin.cigro@gmail.com
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
**Made with ❤️ for Cursor IDE users**
|