@litmers/cursorflow-orchestrator 0.1.3 → 0.1.6

package/examples/README.md

@@ -0,0 +1,155 @@
+# CursorFlow Examples
+
+This directory contains example projects and configurations to help you get started with CursorFlow.
+
+## 📁 Available Examples
+
+### 1. Demo Project (`demo-project/`)
+
+A complete demonstration of CursorFlow's core features.
+
+**What it includes:**
+- 2 parallel tasks (create utils + add tests)
+- Real LLM execution with Claude 3.5 Sonnet
+- Complete documentation
+- Expected time: ~2-4 minutes
+
+**Best for:**
+- First-time users
+- Understanding the basics
+- Testing your setup
+
+**Quick start:**
+```bash
+# See demo-project/README.md for detailed instructions
+cd your-project
+cursorflow init
+cp -r path/to/cursorflow/examples/demo-project/_cursorflow/tasks/demo-test _cursorflow/tasks/
+cursorflow run _cursorflow/tasks/demo-test/
+```
+
+## 🎯 How to Use Examples
+
+### Option 1: Copy to Your Project
+
+1. Initialize CursorFlow in your project:
+   ```bash
+   cd your-project
+   cursorflow init
+   ```
+
+2. Copy example tasks:
+   ```bash
+   cp -r examples/demo-project/_cursorflow/tasks/demo-test _cursorflow/tasks/
+   ```
+
+3. Run the example:
+   ```bash
+   cursorflow run _cursorflow/tasks/demo-test/
+   ```
+
+### Option 2: Use as Reference
+
+Browse the example files to understand:
+- Task JSON structure
+- Prompt engineering best practices
+- Configuration options
+- Expected outcomes
+
+## 📚 Example Structure
+
+Each example includes:
+
+- **Task configurations** (`*.json`) - Defines what the AI will do
+- **README.md** - Detailed instructions and explanations
+- **Expected results** - What you should see after running
+
+## 🔍 What's in a Task File?
+
+```json
+{
+  "baseBranch": "main",
+  "branchPrefix": "cursorflow/demo-",
+  "executor": "cursor-agent",
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "tasks": [
+    {
+      "name": "task-name",
+      "model": "claude-3.5-sonnet",
+      "prompt": "Detailed instructions for the AI..."
+    }
+  ]
+}
+```
+
+## 🚀 Prerequisites
+
+Before running examples:
+
+1. **Install CursorFlow**
+   ```bash
+   npm install -g @litmers/cursorflow-orchestrator
+   ```
+
+2. **Install cursor-agent**
+   ```bash
+   npm install -g @cursor/agent
+   ```
+
+3. **Authenticate Cursor**
+   - Open Cursor IDE
+   - Sign in to your account
+   - Verify AI features work
+
+4. **Check authentication** (optional)
+   ```bash
+   node test-auth.js
+   ```
+
+## 💡 Tips
+
+- **Start with demo-project** - It's the simplest example
+- **Monitor execution** - Use `cursorflow monitor --watch` to see real-time progress
+- **Check logs** - Inspect `_cursorflow/logs/` after execution
+- **Experiment** - Modify prompts to test different scenarios
+- **Clean up** - Remove worktrees and branches after testing
+
+## 📖 Learn More
+
+- **Main Documentation**: [README.md](../README.md)
+- **Configuration Guide**: Check `cursorflow.config.js` in your project
+- **Task Format**: See individual example task files
+- **Monitoring**: [Monitor Command](../commands/cursorflow-monitor.md)
+
+## 🐛 Troubleshooting
+
+If you encounter issues:
+
+1. Check prerequisites are installed
+2. Verify Cursor authentication
+3. Ensure you're in a Git repository
+4. Check you have at least one commit
+5. See example README for specific troubleshooting
+
+## 🤝 Contributing Examples
+
+Have a useful example? Contributions are welcome!
+
+Please include:
+- Complete task configurations
+- Detailed README
+- Expected results documentation
+- Troubleshooting tips
+
+## 📝 Notes
+
+- Examples use real LLM API calls
+- Small API usage will occur
+- Internet connection required
+- Make sure you have Cursor subscription active
+
+Happy learning! 🎉
+

package/examples/demo-project/README.md

@@ -0,0 +1,262 @@
+# CursorFlow Demo Project
+
+A complete example project demonstrating CursorFlow's capabilities with real LLM execution.
+
+## 🎯 Purpose
+
+This demo project shows how to use CursorFlow to orchestrate parallel AI tasks, including:
+- Task creation and configuration
+- Git worktree management
+- LLM agent execution
+- Real-time monitoring
+- Complete log capture
+
+## 📦 Setup
+
+### 1. Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Git** with worktree support
+- **cursor-agent** CLI: `npm install -g @cursor/agent`
+- **Cursor IDE** with valid authentication
+
+### 2. Initialize Your Project
+
+```bash
+# Create a new project
+mkdir my-cursorflow-test
+cd my-cursorflow-test
+git init
+git config user.email "you@example.com"
+git config user.name "Your Name"
+
+# Create initial files
+echo '{"name":"my-test","version":"1.0.0"}' > package.json
+echo "# My Test Project" > README.md
+git add .
+git commit -m "Initial commit"
+
+# Rename branch to main (if needed)
+git branch -m main
+```
+
+### 3. Initialize CursorFlow
+
+```bash
+# Install cursorflow globally (if not already)
+npm install -g @litmers/cursorflow-orchestrator
+
+# Initialize in your project
+cursorflow init
+```
+
+### 4. Copy Demo Tasks
+
+Copy the `_cursorflow/tasks/demo-test/` directory from this example to your project:
+
+```bash
+# From the cursorflow repository
+cp -r examples/demo-project/_cursorflow/tasks/demo-test your-project/_cursorflow/tasks/
+```
+
+## 🚀 Running the Demo
+
+### Run the Tasks
+
+```bash
+cursorflow run _cursorflow/tasks/demo-test/
+```
+
+### Monitor in Real-Time
+
+In a separate terminal:
+
+```bash
+# Single check
+cursorflow monitor
+
+# Watch mode (updates every 2 seconds)
+cursorflow monitor --watch --interval 2
+```
+
+## 📋 Demo Tasks
+
+This demo includes 2 tasks that run in parallel:
+
+### Task 1: Create Utils (`01-create-utils.json`)
+- **Goal**: Create `src/utils.js` with utility functions
+- **Functions**: capitalize, sum, unique
+- **Model**: Sonnet 4.5
+- **Time**: ~1-2 minutes
+
+### Task 2: Add Tests (`02-add-tests.json`)
+- **Goal**: Create `src/utils.test.js` with simple tests
+- **Tests**: Manual console.log tests for all utils
+- **Model**: Sonnet 4.5
+- **Time**: ~1-2 minutes
+
+## 📊 Expected Results
+
+After completion, you'll see:
+
+### 1. Source Files
+```
+src/
+├── utils.js          # Created by Task 1
+└── utils.test.js     # Created by Task 2
+```
+
+### 2. Git Branches
+```bash
+git branch | grep cursorflow
+# cursorflow/demo-XXXXX--01-create-utils
+# cursorflow/demo-XXXXX--02-add-tests
+```
+
+### 3. Logs
+```
+_cursorflow/logs/runs/run-XXXXX/
+└── lanes/
+    ├── 01-create-utils/
+    │   ├── state.json
+    │   ├── conversation.jsonl
+    │   └── terminal.log
+    └── 02-add-tests/
+        ├── state.json
+        ├── conversation.jsonl
+        └── terminal.log
+```
+
+### 4. Monitor Output
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 Run: run-1234567890123
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Lane             Status            Progress  Tasks
+───────────────  ────────────────  ────────  ──────────
+01-create-utils  ✅ completed      100%      1/1
+02-add-tests     ✅ completed      100%      1/1
+```
+
+## 🔍 Inspecting Results
+
+### View Conversation Logs
+```bash
+cat _cursorflow/logs/runs/run-*/lanes/01-create-utils/conversation.jsonl
+```
+
+### View Terminal Output
+```bash
+cat _cursorflow/logs/runs/run-*/lanes/01-create-utils/terminal.log
+```
+
+### View Lane State
+```bash
+cat _cursorflow/logs/runs/run-*/lanes/01-create-utils/state.json
+```
+
+### View Branch Changes
+```bash
+# List branches
+git branch | grep cursorflow
+
+# View commits
+git log cursorflow/demo-XXXXX--01-create-utils
+
+# View diff
+git diff main cursorflow/demo-XXXXX--01-create-utils
+```
+
+## 🧹 Cleanup
+
+After testing, clean up the worktrees and branches:
+
+```bash
+# Remove worktrees
+git worktree list | grep cursorflow | awk '{print $1}' | xargs -I {} git worktree remove {} --force
+
+# Delete branches
+git branch | grep cursorflow | xargs -I {} git branch -D {}
+```
+
+Or use the clean command (if available):
+
+```bash
+cursorflow clean branches --all
+cursorflow clean worktrees --all
+```
+
+## 🐛 Troubleshooting
+
+### Authentication Failed
+```
+Error: Cursor authentication failed
+```
+
+**Solution**:
+1. Open Cursor IDE
+2. Sign in to your account
+3. Verify AI features work
+4. Run `node test-auth.js` to check authentication
+
+### cursor-agent Not Found
+```
+Error: cursor-agent CLI not found
+```
+
+**Solution**:
+```bash
+npm install -g @cursor/agent
+```
+
+### Timeout Errors
+```
+Error: cursor-agent timed out
+```
+
+**Solution**:
+- Check internet connection
+- Verify Cursor IDE is signed in
+- Check if firewall/VPN is blocking
+
+### Worktree Creation Failed
+```
+Error: failed to create worktree
+```
+
+**Solution**:
+- Ensure you have at least one commit: `git log`
+- Check you're on the main branch: `git branch`
+
+## 📖 Learn More
+
+- **CursorFlow Documentation**: [Main README](../../README.md)
+- **Task Configuration**: See task JSON files for structure
+- **Configuration Options**: Check `cursorflow.config.js`
+
+## 💡 Next Steps
+
+After running this demo:
+
+1. **Examine the logs** to understand execution flow
+2. **Check the branches** to see what the LLM created
+3. **Modify prompts** to test different scenarios
+4. **Create your own tasks** for real projects
+5. **Explore parallel execution** with more complex workflows
+
+## ⏱️ Timing
+
+- Setup: ~5 minutes
+- Task execution: ~2-4 minutes
+- Total: ~10 minutes
+
+## ⚠️ Notes
+
+- Real LLM API calls will be made
+- Small API usage will occur (~2 requests)
+- Internet connection required
+- Cursor authentication required
+
+Happy testing! 🚀
+

package/examples/demo-project/_cursorflow/tasks/demo-test/01-create-utils.json

@@ -0,0 +1,18 @@
+{
+  "baseBranch": "main",
+  "branchPrefix": "cursorflow/demo-",
+  "executor": "cursor-agent",
+  "autoCreatePr": false,
+  "pollInterval": 10,
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "tasks": [
+    {
+      "name": "create-utils",
+      "model": "sonnet-4.5",
+      "prompt": "# Task: Create a simple utility module\n\n## Goal\nCreate a `src/utils.js` file with basic utility functions.\n\n## Requirements\n1. Create `src/` directory if it doesn't exist\n2. Create `src/utils.js` with the following functions:\n   - `capitalize(str)`: Capitalizes the first letter of a string\n   - `sum(arr)`: Returns the sum of an array of numbers\n   - `unique(arr)`: Returns unique elements from an array\n\n## Steps\n1. Create the src directory\n2. Write the utils.js file with proper JSDoc comments\n3. Add module.exports at the end\n4. Commit with message: \"feat: add utility functions\"\n\n## Important\n- Use modern JavaScript (ES6+)\n- Add JSDoc comments for each function\n- Make sure all functions are exported\n"
+    }
+  ]
+}

package/examples/demo-project/_cursorflow/tasks/demo-test/02-add-tests.json

@@ -0,0 +1,18 @@
+{
+  "baseBranch": "main",
+  "branchPrefix": "cursorflow/demo-",
+  "executor": "cursor-agent",
+  "autoCreatePr": false,
+  "pollInterval": 10,
+  "dependencyPolicy": {
+    "allowDependencyChange": false,
+    "lockfileReadOnly": true
+  },
+  "tasks": [
+    {
+      "name": "add-tests",
+      "model": "sonnet-4.5",
+      "prompt": "# Task: Add simple tests for utility functions\n\n## Goal\nCreate a `src/utils.test.js` file with basic tests.\n\n## Requirements\n1. Create `src/utils.test.js`\n2. Add simple manual tests (no testing framework needed)\n3. Test all three utility functions:\n   - Test `capitalize()` with a few examples\n   - Test `sum()` with different arrays\n   - Test `unique()` with arrays containing duplicates\n\n## Steps\n1. Create the test file\n2. Import the utils module\n3. Write simple console.log tests that show expected vs actual\n4. Add a success message at the end if all tests pass\n5. Commit with message: \"test: add basic tests for utils\"\n\n## Example Format\n```javascript\nconst utils = require('./utils');\n\nconsole.log('Testing capitalize...');\nconst result1 = utils.capitalize('hello');\nconsole.log('Expected: Hello, Got:', result1);\nconsole.log(result1 === 'Hello' ? '✓ Pass' : '✗ Fail');\n```\n"
+    }
+  ]
+}

package/examples/demo-project/_cursorflow/tasks/demo-test/README.md

@@ -0,0 +1,109 @@
+# CursorFlow Demo Test
+
+This directory contains test tasks for demonstrating CursorFlow with real LLM execution.
+
+## Tasks Overview
+
+### 01-create-utils.json
+Creates a utility module with basic functions:
+- capitalize(str)
+- sum(arr)
+- unique(arr)
+
+**Model**: sonnet-4.5
+**Estimated time**: 1-2 minutes
+
+### 02-add-tests.json
+Adds simple tests for the utility functions without requiring any testing framework.
+
+**Model**: sonnet-4.5
+**Estimated time**: 1-2 minutes
+
+## Running the Demo
+
+### Prerequisites
+- cursor-agent CLI installed (`npm install -g @cursor/agent`)
+- Valid Cursor API key configured
+
+### Run the test
+
+```bash
+# From your project directory (after cursorflow init)
+cursorflow run _cursorflow/tasks/demo-test/
+```
+
+### Monitor execution
+
+In a separate terminal:
+```bash
+# Watch mode (updates every 2 seconds)
+cursorflow monitor --watch --interval 2
+```
+
+### Check results
+
+After completion:
+```bash
+# View the logs
+ls -la _cursorflow/logs/runs/
+
+# Check the latest run
+cursorflow monitor
+```
+
+## What to Expect
+
+1. **Orchestrator** will create 2 lanes (one per task)
+2. **Each lane** will:
+   - Create a Git worktree
+   - Create a branch (`cursorflow/demo-XXXXX--01-create-utils`, etc.)
+   - Execute the LLM agent with the prompt
+   - Commit changes
+   - Push the branch
+3. **Monitor** will show:
+   - Lane status (running, completed, failed)
+   - Progress (current task / total tasks)
+   - Real-time updates in watch mode
+
+## Expected Output Structure
+
+```
+_cursorflow/
+├── logs/
+│   └── runs/
+│       └── run-XXXXX/
+│           └── lanes/
+│               ├── 01-create-utils/
+│               │   ├── state.json
+│               │   ├── conversation.jsonl
+│               │   └── terminal.log
+│               └── 02-add-tests/
+│                   ├── state.json
+│                   ├── conversation.jsonl
+│                   └── terminal.log
+└── tasks/
+    └── demo-test/
+        ├── 01-create-utils.json
+        ├── 02-add-tests.json
+        └── README.md (this file)
+```
+
+## Troubleshooting
+
+### If cursor-agent is not found
+```bash
+npm install -g @cursor/agent
+```
+
+### If API key is missing
+Check your Cursor IDE settings and ensure you're authenticated.
+
+### If worktree creation fails
+Make sure you're in a Git repository with at least one commit.
+
+## Notes
+
+- These tasks are designed to be simple and quick
+- No external dependencies required
+- All operations are Git-safe (branches only, no main changes)
+- Logs are preserved for inspection

package/package.json

@@ -1,61 +1,71 @@
-{
-  "name": "@litmers/cursorflow-orchestrator",
-  "version": "0.1.3",
-  "description": "Git worktree-based parallel AI agent orchestration system for Cursor",
-  "main": "src/cli/index.js",
-  "bin": {
-    "cursorflow": "src/cli/index.js",
-    "cursorflow-setup": "src/cli/setup-commands.js"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "prepublishOnly": "npm run validate",
-    "validate": "npm pack --dry-run",
-    "release": "scripts/release.sh",
-    "release:patch": "scripts/release.sh patch",
-    "release:minor": "scripts/release.sh minor",
-    "release:major": "scripts/release.sh major",
-    "security:check": "npm audit && node scripts/ai-security-check.js",
-    "security:audit": "npm audit",
-    "security:audit:fix": "npm audit fix",
-    "security:setup": "scripts/setup-security.sh"
-  },
-  "keywords": [
-    "cursor",
-    "cursor-ide",
-    "ai-agent",
-    "orchestration",
-    "git-worktree",
-    "parallel-execution",
-    "code-review",
-    "automation",
-    "devops",
-    "ci-cd"
-  ],
-  "author": "Eugene Jin <eungjin.cigro@gmail.com>",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/eungjin-cigro/cursorflow.git"
-  },
-  "bugs": {
-    "url": "https://github.com/eungjin-cigro/cursorflow/issues"
-  },
-  "homepage": "https://github.com/eungjin-cigro/cursorflow#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {},
-  "devDependencies": {},
-  "peerDependencies": {},
-  "files": [
-    "src/",
-    "scripts/",
-    "commands/",
-    "templates/",
-    "examples/",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ]
-}
+{
+  "name": "@litmers/cursorflow-orchestrator",
+  "version": "0.1.6",
+  "description": "Git worktree-based parallel AI agent orchestration system for Cursor",
+  "main": "dist/cli/index.js",
+  "bin": {
+    "cursorflow": "dist/cli/index.js",
+    "cursorflow-setup": "dist/cli/setup-commands.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "test": "jest",
+    "prepublishOnly": "npm run build && npm run validate",
+    "postinstall": "node scripts/postinstall.js",
+    "validate": "npm pack --dry-run",
+    "release": "scripts/release.sh",
+    "release:patch": "scripts/release.sh patch",
+    "release:minor": "scripts/release.sh minor",
+    "release:major": "scripts/release.sh major",
+    "security:check": "scripts/local-security-gate.sh",
+    "security:audit": "npm audit",
+    "security:audit:fix": "npm audit fix",
+    "security:setup": "scripts/setup-security.sh",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "cursor",
+    "cursor-ide",
+    "ai-agent",
+    "orchestration",
+    "git-worktree",
+    "parallel-execution",
+    "code-review",
+    "automation",
+    "devops",
+    "ci-cd"
+  ],
+  "author": "Eugene Jin <eungjin.cigro@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eungjin-cigro/cursorflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eungjin-cigro/cursorflow/issues"
+  },
+  "homepage": "https://github.com/eungjin-cigro/cursorflow#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "scripts/",
+    "commands/",
+    "templates/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}