@litmers/cursorflow-orchestrator 0.1.3 → 0.1.5

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.5",
+  "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"
+  ]
+}

package/scripts/ai-security-check.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { spawnSync } = require('child_process');
 
 // 색상 정의
 const colors = {
@@ -29,8 +29,10 @@ if (!OPENAI_API_KEY) {
 function getChangedFiles() {
   try {
     const baseBranch = process.env.GITHUB_BASE_REF || 'main';
-    const diffCommand = `git diff --name-only origin/${baseBranch}...HEAD`;
-    const files = execSync(diffCommand, { encoding: 'utf-8' })
+    const result = spawnSync('git', ['diff', '--name-only', `origin/${baseBranch}...HEAD`], { encoding: 'utf-8' });
+    if (result.status !== 0) throw new Error(result.stderr);
+    
+    const files = result.stdout
       .split('\n')
       .filter(f => f.endsWith('.js') || f.endsWith('.ts') || f.endsWith('.jsx') || f.endsWith('.tsx'))
       .filter(f => f && fs.existsSync(f));
@@ -38,7 +40,10 @@ function getChangedFiles() {
   } catch (error) {
     // PR이 아닌 경우 최근 커밋의 파일들
     try {
-      const files = execSync('git diff-tree --no-commit-id --name-only -r HEAD', { encoding: 'utf-8' })
+      const result = spawnSync('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD'], { encoding: 'utf-8' });
+      if (result.status !== 0) return [];
+      
+      const files = result.stdout
         .split('\n')
         .filter(f => f.endsWith('.js') || f.endsWith('.ts') || f.endsWith('.jsx') || f.endsWith('.tsx'))
         .filter(f => f && fs.existsSync(f));
@@ -71,6 +76,8 @@ Please analyze for:
 8. **Rate limiting or DoS vulnerabilities**
 9. **CSRF/SSRF vulnerabilities**
 10. **Any OWASP Top 10 issues**
+11. **CodeQL-specific patterns** (tainted data flow, improper input validation, dangerous sinks like eval or child_process.exec)
+12. **Code quality issues** that might trigger CodeQL's "Security and Quality" queries
 
 Respond in JSON format:
 {

package/scripts/local-security-gate.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+# 로컬 보안 게이트 (Local Security Gate)
+# 커밋 또는 푸시 전에 보안 취약점을 미리 검사합니다.
+
+set -e
+
+# 색상 정의
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+echo -e "${BLUE}🔍 Starting Local Security Gate...${NC}"
+
+# 1. 의존성 취약점 검사 (npm audit)
+echo -e "\n${BLUE}[1/4] Checking dependencies (npm audit)...${NC}"
+if npm audit --audit-level=high; then
+    echo -e "${GREEN}✅ No high-severity dependency issues found.${NC}"
+else
+    echo -e "${RED}❌ High-severity dependency issues found!${NC}"
+    echo -e "${YELLOW}Please run 'npm audit fix' to resolve them.${NC}"
+    exit 1
+fi
+
+# 2. 정적 코드 분석 (Semgrep - CodeQL 대안)
+echo -e "\n${BLUE}[2/4] Running static analysis (Semgrep)...${NC}"
+if command -v semgrep &> /dev/null; then
+    if semgrep --config=auto --error .; then
+        echo -e "${GREEN}✅ Semgrep analysis passed.${NC}"
+    else
+        echo -e "${RED}❌ Semgrep found potential security issues!${NC}"
+        echo -e "${YELLOW}CodeQL과 유사한 보안 이슈들입니다. 위 리포트를 확인하고 수정하세요.${NC}"
+        exit 1
+    fi
+else
+    echo -e "${YELLOW}⚠️  Semgrep not installed. Skipping static analysis.${NC}"
+    echo -e "Install it to catch CodeQL-like issues: pip install semgrep"
+fi
+
+# 3. 민감 정보 노출 검사 (Simple Secret Scan)
+echo -e "\n${BLUE}[3/4] Checking for hardcoded secrets...${NC}"
+# git에 추적되는 파일들 중 API 키나 비밀번호 패턴 검색
+# .cursorignore나 .gitignore에 있는 파일은 제외
+# .github, *.md, scripts/setup-security.sh 등은 제외
+# 변수 선언이나 에러 메시지에 포함된 키워드는 제외하도록 필터 강화
+SECRETS_FOUND=$(git grep -Ei "api[_-]?key|secret|password|token|bearer|private[_-]?key" -- ":!package-lock.json" ":!*.md" ":!scripts/setup-security.sh" ":!scripts/ai-security-check.js" ":!.github/*" ":!scripts/local-security-gate.sh" | grep -v "process.env" | grep -v "example" | grep -v "\${{" | grep -vE "stderr\.includes|checkCursorApiKey|CURSOR_API_KEY|api key|API_KEY" || true)
+
+if [ -z "$SECRETS_FOUND" ]; then
+    echo -e "${GREEN}✅ No obvious secrets found in tracked files.${NC}"
+else
+    echo -e "${YELLOW}⚠️  Possible secrets found:${NC}"
+    echo "$SECRETS_FOUND"
+    echo -e "\n${RED}❌ Please remove secrets or move them to .env file before pushing!${NC}"
+    exit 1
+fi
+
+# 4. AI 기반 코드 보안 분석 (선택적)
+echo -e "\n${BLUE}[4/4] AI-based security analysis...${NC}"
+if [ -z "$OPENAI_API_KEY" ]; then
+    echo -e "${YELLOW}⚠️  OPENAI_API_KEY not set. Skipping AI security check.${NC}"
+    echo -e "Set the environment variable to enable this step: export OPENAI_API_KEY=your-key"
+else
+    if node scripts/ai-security-check.js; then
+        echo -e "${GREEN}✅ AI security check passed.${NC}"
+    else
+        echo -e "${RED}❌ AI security check failed!${NC}"
+        exit 1
+    fi
+fi
+
+echo -e "\n${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}✅ All local security checks passed!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+