@litmers/cursorflow-orchestrator 0.1.8 → 0.1.12

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

@@ -1,18 +1,29 @@
 {
   "baseBranch": "main",
-  "branchPrefix": "cursorflow/demo-",
-  "executor": "cursor-agent",
-  "autoCreatePr": false,
-  "pollInterval": 10,
+  "branchPrefix": "cursorflow/demo-tests-",
+  "timeout": 300000,
+  "enableIntervention": false,
   "dependencyPolicy": {
     "allowDependencyChange": false,
     "lockfileReadOnly": true
   },
+  "enableReview": true,
+  "reviewModel": "sonnet-4.5-thinking",
+  "maxReviewIterations": 2,
+  "laneNumber": 2,
+  "devPort": 3002,
   "tasks": [
     {
-      "name": "add-tests",
+      "name": "implement",
       "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"
+      "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\n## Important\n- Double-check all test cases before finishing",
+      "acceptanceCriteria": [
+        "src/utils.test.js file exists",
+        "Tests for capitalize function",
+        "Tests for sum function",
+        "Tests for unique function",
+        "Clear pass/fail output"
+      ]
     }
   ]
 }

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

@@ -2,53 +2,70 @@
 
 This directory contains test tasks for demonstrating CursorFlow with real LLM execution.
 
+## Alternative: Generate with Prepare Command
+
+Instead of using these pre-made files, you can generate similar tasks using:
+
+```bash
+# Simple approach
+cursorflow prepare CreateUtils --preset simple --prompt "Create src/utils.js with capitalize, sum, unique functions"
+cursorflow prepare AddTests --preset simple --prompt "Create src/utils.test.js with tests for utils"
+
+# Or use a single complex task
+cursorflow prepare UtilsWithTests --preset complex --prompt "Create utility module with tests"
+```
+
 ## Tasks Overview
 
 ### 01-create-utils.json
 Creates a utility module with basic functions:
-- capitalize(str)
-- sum(arr)
-- unique(arr)
+- `capitalize(str)` - Capitalizes first letter
+- `sum(arr)` - Sums array of numbers
+- `unique(arr)` - Returns unique elements
 
 **Model**: sonnet-4.5
 **Estimated time**: 1-2 minutes
+**Acceptance Criteria**: 5 criteria including function verification
 
 ### 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
+**Acceptance Criteria**: 5 criteria including test coverage
 
 ## Running the Demo
 
 ### Prerequisites
 - cursor-agent CLI installed (`npm install -g @cursor/agent`)
-- Valid Cursor API key configured
+- Valid Cursor authentication (sign in via Cursor IDE)
 
-### Run the test
+### 1. Validate first
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
+```
 
+### 2. Run the test
 ```bash
-# From your project directory (after cursorflow init)
 cursorflow run _cursorflow/tasks/demo-test/
 ```
 
-### Monitor execution
-
-In a separate terminal:
+### 3. Monitor execution
 ```bash
-# Watch mode (updates every 2 seconds)
+# Interactive dashboard (recommended)
+cursorflow monitor latest
+
+# Or watch mode
 cursorflow monitor --watch --interval 2
 ```
 
-### Check results
-
-After completion:
+### 4. Check results
 ```bash
-# View the logs
-ls -la _cursorflow/logs/runs/
-
-# Check the latest run
+# View lane status
 cursorflow monitor
+
+# Check git branches
+git branch | grep cursorflow
 ```
 
 ## What to Expect
@@ -56,14 +73,16 @@ cursorflow monitor
 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.)
+   - Create a branch (`cursorflow/demo-utils-*`, `cursorflow/demo-tests-*`)
    - Execute the LLM agent with the prompt
+   - Run AI code review (if enabled)
    - Commit changes
    - Push the branch
 3. **Monitor** will show:
-   - Lane status (running, completed, failed)
+   - Lane status (pending, running, completed, failed)
    - Progress (current task / total tasks)
-   - Real-time updates in watch mode
+   - Dependencies (if any)
+   - Real-time updates
 
 ## Expected Output Structure
 
@@ -88,6 +107,16 @@ _cursorflow/
         └── README.md (this file)
 ```
 
+## Cleanup
+
+After testing:
+```bash
+# Clean branches and worktrees
+cursorflow clean branches --dry-run  # Preview
+cursorflow clean branches            # Execute
+cursorflow clean worktrees           # Clean worktrees
+```
+
 ## Troubleshooting
 
 ### If cursor-agent is not found
@@ -95,15 +124,27 @@ _cursorflow/
 npm install -g @cursor/agent
 ```
 
-### If API key is missing
-Check your Cursor IDE settings and ensure you're authenticated.
+### If authentication fails
+1. Open Cursor IDE
+2. Sign in to your account
+3. Verify AI features work in the IDE
+4. Run `cursorflow doctor` to check
 
 ### If worktree creation fails
-Make sure you're in a Git repository with at least one commit.
+Make sure you're in a Git repository with at least one commit:
+```bash
+git log --oneline -1
+```
+
+### If branch conflicts occur
+```bash
+cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
+```
 
 ## Notes
 
-- These tasks are designed to be simple and quick
-- No external dependencies required
+- These tasks run in parallel (no dependencies)
+- Each task creates its own isolated branch
+- AI code review is enabled by default
 - All operations are Git-safe (branches only, no main changes)
 - Logs are preserved for inspection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litmers/cursorflow-orchestrator",
-  "version": "0.1.8",
+  "version": "0.1.12",
   "description": "Git worktree-based parallel AI agent orchestration system for Cursor",
   "main": "dist/cli/index.js",
   "bin": {

package/scripts/patches/test-cursor-agent.js

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Direct cursor-agent spawn test script
+ * 
+ * This script tests cursor-agent directly to compare behavior with CursorFlow.
+ * It helps identify if the issue is in how CursorFlow spawns the agent.
+ * 
+ * Usage:
+ *   node scripts/patches/test-cursor-agent.js [--stdio-mode <mode>]
+ * 
+ * Modes:
+ *   - pipe: Full pipe mode (default, same as CursorFlow)
+ *   - inherit-stdin: Inherit stdin, pipe stdout/stderr
+ *   - inherit-all: Inherit all (like running directly in terminal)
+ */
+
+const { spawn, spawnSync } = require('child_process');
+const path = require('path');
+
+// Parse args
+const args = process.argv.slice(2);
+const stdioModeIdx = args.indexOf('--stdio-mode');
+const stdioMode = stdioModeIdx >= 0 ? args[stdioModeIdx + 1] : 'pipe';
+
+console.log('='.repeat(60));
+console.log('cursor-agent Direct Spawn Test');
+console.log('='.repeat(60));
+console.log(`stdio mode: ${stdioMode}`);
+console.log('');
+
+// Step 1: Check cursor-agent is available
+console.log('1. Checking cursor-agent availability...');
+const whichResult = spawnSync('which', ['cursor-agent']);
+if (whichResult.status !== 0) {
+  console.error('   ❌ cursor-agent not found in PATH');
+  process.exit(1);
+}
+console.log(`   ✓ Found at: ${whichResult.stdout.toString().trim()}`);
+
+// Step 2: Create a chat session
+console.log('\n2. Creating chat session...');
+const createChatResult = spawnSync('cursor-agent', ['create-chat'], {
+  encoding: 'utf8',
+  stdio: 'pipe',
+  timeout: 30000,
+});
+
+if (createChatResult.status !== 0) {
+  console.error('   ❌ Failed to create chat:');
+  console.error(createChatResult.stderr || createChatResult.stdout);
+  process.exit(1);
+}
+
+const chatIdLines = createChatResult.stdout.trim().split('\n');
+const chatId = chatIdLines[chatIdLines.length - 1];
+console.log(`   ✓ Chat ID: ${chatId}`);
+
+// Step 3: Configure stdio based on mode
+let stdioConfig;
+switch (stdioMode) {
+  case 'inherit-stdin':
+    stdioConfig = ['inherit', 'pipe', 'pipe'];
+    break;
+  case 'inherit-all':
+    stdioConfig = 'inherit';
+    break;
+  case 'ignore-stdin':
+    stdioConfig = ['ignore', 'pipe', 'pipe'];
+    break;
+  case 'pipe':
+  default:
+    stdioConfig = ['pipe', 'pipe', 'pipe'];
+    break;
+}
+
+console.log(`\n3. Testing with stdio: ${JSON.stringify(stdioConfig)}`);
+
+// Step 4: Send a simple prompt
+const testPrompt = 'Just respond with: Hello World. Nothing else.';
+const workspace = process.cwd();
+
+const agentArgs = [
+  '--print',
+  '--output-format', 'json',
+  '--workspace', workspace,
+  '--model', 'gemini-3-flash',
+  '--resume', chatId,
+  testPrompt,
+];
+
+console.log(`   Workspace: ${workspace}`);
+console.log(`   Prompt: "${testPrompt}"`);
+console.log('');
+console.log('4. Spawning cursor-agent...');
+console.log(`   Command: cursor-agent ${agentArgs.join(' ').substring(0, 80)}...`);
+console.log('');
+
+const startTime = Date.now();
+
+const child = spawn('cursor-agent', agentArgs, {
+  stdio: stdioConfig,
+  env: {
+    ...process.env,
+    // Disable Python buffering if cursor-agent uses Python
+    PYTHONUNBUFFERED: '1',
+    // Disable Node.js experimental warnings
+    NODE_OPTIONS: '',
+  },
+});
+
+let fullStdout = '';
+let fullStderr = '';
+let gotData = false;
+
+// Track first byte time
+let firstByteTime = null;
+
+if (child.stdout) {
+  child.stdout.on('data', (data) => {
+    if (!firstByteTime) {
+      firstByteTime = Date.now();
+      console.log(`   [+${((firstByteTime - startTime) / 1000).toFixed(2)}s] First stdout byte received`);
+    }
+    gotData = true;
+    const str = data.toString();
+    fullStdout += str;
+    process.stdout.write(`   [stdout] ${str}`);
+  });
+}
+
+if (child.stderr) {
+  child.stderr.on('data', (data) => {
+    const str = data.toString();
+    fullStderr += str;
+    process.stderr.write(`   [stderr] ${str}`);
+  });
+}
+
+// Set timeout
+const timeout = setTimeout(() => {
+  console.log('\n   ⏰ TIMEOUT after 60 seconds');
+  console.log(`   Got any data: ${gotData}`);
+  console.log(`   Stdout length: ${fullStdout.length}`);
+  console.log(`   Stderr length: ${fullStderr.length}`);
+  child.kill('SIGTERM');
+}, 60000);
+
+child.on('close', (code) => {
+  clearTimeout(timeout);
+  const elapsed = (Date.now() - startTime) / 1000;
+  
+  console.log('\n' + '-'.repeat(60));
+  console.log('RESULT');
+  console.log('-'.repeat(60));
+  console.log(`Exit code: ${code}`);
+  console.log(`Duration: ${elapsed.toFixed(2)}s`);
+  console.log(`First byte: ${firstByteTime ? ((firstByteTime - startTime) / 1000).toFixed(2) + 's' : 'never'}`);
+  console.log(`Stdout bytes: ${fullStdout.length}`);
+  console.log(`Stderr bytes: ${fullStderr.length}`);
+  
+  if (fullStdout.length > 0) {
+    console.log('\nStdout content:');
+    console.log(fullStdout);
+  }
+  
+  if (fullStderr.length > 0) {
+    console.log('\nStderr content:');
+    console.log(fullStderr);
+  }
+  
+  // Try to parse JSON
+  const lines = fullStdout.split('\n').filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line.startsWith('{') && line.endsWith('}')) {
+      try {
+        const json = JSON.parse(line);
+        console.log('\nParsed JSON response:');
+        console.log(JSON.stringify(json, null, 2));
+        break;
+      } catch {
+        continue;
+      }
+    }
+  }
+  
+  console.log('\n' + '='.repeat(60));
+  if (code === 0 && fullStdout.includes('result')) {
+    console.log('✓ SUCCESS - cursor-agent responded correctly');
+  } else if (gotData) {
+    console.log('⚠ PARTIAL - Got data but may not have completed');
+  } else {
+    console.log('❌ FAILURE - No data received');
+  }
+  console.log('='.repeat(60));
+});
+
+child.on('error', (err) => {
+  clearTimeout(timeout);
+  console.error(`\n❌ Spawn error: ${err.message}`);
+  process.exit(1);
+});
+

package/src/cli/clean.ts

@@ -1,36 +1,183 @@
 /**
- * CursorFlow clean command (stub)
+ * CursorFlow clean command
+ * 
+ * Clean up worktrees, branches, and logs created by CursorFlow
  */
 
+import * as fs from 'fs';
+import * as path from 'path';
 import * as logger from '../utils/logger';
+import * as git from '../utils/git';
+import { loadConfig, getLogsDir } from '../utils/config';
 
 interface CleanOptions {
   type?: string;
   pattern: string | null;
   dryRun: boolean;
   force: boolean;
+  all: boolean;
+  help: boolean;
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: cursorflow clean <type> [options]
+
+Clean up resources created by CursorFlow.
+
+Types:
+  branches               Remove local feature branches
+  worktrees              Remove temporary Git worktrees
+  logs                   Clear log directories
+  all                    Remove all of the above (default)
+
+Options:
+  --dry-run              Show what would be removed without deleting
+  --force                Force removal (ignore uncommitted changes)
+  --help, -h             Show help
+  `);
 }
 
 function parseArgs(args: string[]): CleanOptions {
   return {
-    type: args[0], // branches | worktrees | logs | all
+    type: args.find(a => ['branches', 'worktrees', 'logs', 'all'].includes(a)),
     pattern: null,
     dryRun: args.includes('--dry-run'),
     force: args.includes('--force'),
+    all: args.includes('--all'),
+    help: args.includes('--help') || args.includes('-h'),
   };
 }
 
 async function clean(args: string[]): Promise<void> {
-  logger.section('🧹 Cleaning CursorFlow Resources');
-  
   const options = parseArgs(args);
   
-  logger.info('This command will be fully implemented in the next phase');
-  logger.info(`Clean type: ${options.type}`);
-  logger.info(`Dry run: ${options.dryRun}`);
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  const config = loadConfig();
+  const repoRoot = git.getRepoRoot();
+
+  logger.section('🧹 Cleaning CursorFlow Resources');
+
+  const type = options.type || 'all';
+
+  if (type === 'all') {
+    await cleanWorktrees(config, repoRoot, options);
+    await cleanBranches(config, repoRoot, options);
+    await cleanLogs(config, options);
+  } else if (type === 'worktrees') {
+    await cleanWorktrees(config, repoRoot, options);
+  } else if (type === 'branches') {
+    await cleanBranches(config, repoRoot, options);
+  } else if (type === 'logs') {
+    await cleanLogs(config, options);
+  }
+
+  logger.success('\n✨ Cleaning complete!');
+}
+
+async function cleanWorktrees(config: any, repoRoot: string, options: CleanOptions) {
+  logger.info('\nChecking worktrees...');
+  const worktrees = git.listWorktrees(repoRoot);
+  
+  const worktreeRoot = path.join(repoRoot, config.worktreeRoot || '_cursorflow/worktrees');
+  const toRemove = worktrees.filter(wt => {
+    // Skip main worktree
+    if (wt.path === repoRoot) return false;
+    
+    const isInsideRoot = wt.path.startsWith(worktreeRoot);
+    const hasPrefix = path.basename(wt.path).startsWith(config.worktreePrefix || 'cursorflow-');
+    
+    return isInsideRoot || hasPrefix;
+  });
+
+  if (toRemove.length === 0) {
+    logger.info('  No worktrees found to clean.');
+    return;
+  }
+
+  for (const wt of toRemove) {
+    if (options.dryRun) {
+      logger.info(`  [DRY RUN] Would remove worktree: ${wt.path} (${wt.branch || 'no branch'})`);
+    } else {
+      try {
+        logger.info(`  Removing worktree: ${wt.path}...`);
+        git.removeWorktree(wt.path, { cwd: repoRoot, force: options.force });
+        
+        // Git worktree remove might leave the directory if it has untracked files
+        if (fs.existsSync(wt.path)) {
+           if (options.force) {
+             fs.rmSync(wt.path, { recursive: true, force: true });
+             logger.info(`  (Forced removal of directory)`);
+           } else {
+             logger.warn(`  Directory still exists: ${wt.path} (contains untracked files). Use --force to delete anyway.`);
+           }
+        }
+      } catch (e: any) {
+        logger.error(`  Failed to remove worktree ${wt.path}: ${e.message}`);
+      }
+    }
+  }
+}
+
+async function cleanBranches(config: any, repoRoot: string, options: CleanOptions) {
+  logger.info('\nChecking branches...');
   
-  logger.warn('\n⚠️  Implementation pending');
-  logger.info('This will clean branches, worktrees, and logs');
+  // List all local branches
+  const result = git.runGitResult(['branch', '--list'], { cwd: repoRoot });
+  if (!result.success) return;
+
+  const branches = result.stdout
+    .split('\n')
+    .map(b => b.replace('*', '').trim())
+    .filter(b => b && b !== 'main' && b !== 'master');
+
+  const prefix = config.branchPrefix || 'feature/';
+  const toDelete = branches.filter(b => b.startsWith(prefix));
+
+  if (toDelete.length === 0) {
+    logger.info('  No branches found to clean.');
+    return;
+  }
+
+  for (const branch of toDelete) {
+    if (options.dryRun) {
+      logger.info(`  [DRY RUN] Would delete branch: ${branch}`);
+    } else {
+      try {
+        logger.info(`  Deleting branch: ${branch}...`);
+        git.deleteBranch(branch, { cwd: repoRoot, force: options.force || options.all });
+      } catch (e: any) {
+        logger.warn(`  Could not delete branch ${branch}: ${e.message}. Use --force if it's not merged.`);
+      }
+    }
+  }
+}
+
+async function cleanLogs(config: any, options: CleanOptions) {
+  const logsDir = getLogsDir(config);
+  logger.info(`\nChecking logs in ${logsDir}...`);
+
+  if (!fs.existsSync(logsDir)) {
+    logger.info('  Logs directory does not exist.');
+    return;
+  }
+
+  if (options.dryRun) {
+    logger.info(`  [DRY RUN] Would remove logs directory: ${logsDir}`);
+  } else {
+    try {
+      logger.info(`  Removing logs...`);
+      fs.rmSync(logsDir, { recursive: true, force: true });
+      fs.mkdirSync(logsDir, { recursive: true });
+      logger.info(`  Logs cleared.`);
+    } catch (e: any) {
+      logger.error(`  Failed to clean logs: ${e.message}`);
+    }
+  }
 }
 
 export = clean;

package/src/cli/doctor.ts

@@ -13,13 +13,15 @@
  */
 
 import * as logger from '../utils/logger';
-import { runDoctor } from '../utils/doctor';
+import { runDoctor, saveDoctorStatus } from '../utils/doctor';
+import { runInteractiveAgentTest } from '../utils/cursor-agent';
 
 interface DoctorCliOptions {
   json: boolean;
   tasksDir: string | null;
   executor: string | null;
   includeCursorAgentChecks: boolean;
+  testAgent: boolean;
 }
 
 function printHelp(): void {
@@ -33,12 +35,13 @@ Options:
   --tasks-dir <path>     Also validate lane files (run preflight)
   --executor <type>      cursor-agent | cloud
   --no-cursor            Skip Cursor Agent install/auth checks
+  --test-agent           Run interactive agent test (to approve MCP/permissions)
   --help, -h             Show help
 
 Examples:
   cursorflow doctor
+  cursorflow doctor --test-agent
   cursorflow doctor --tasks-dir _cursorflow/tasks/demo-test/
-  cursorflow doctor --json
   `);
 }
 
@@ -51,6 +54,7 @@ function parseArgs(args: string[]): DoctorCliOptions {
     tasksDir: tasksDirIdx >= 0 ? (args[tasksDirIdx + 1] || null) : null,
     executor: executorIdx >= 0 ? (args[executorIdx + 1] || null) : null,
     includeCursorAgentChecks: !args.includes('--no-cursor'),
+    testAgent: args.includes('--test-agent'),
   };
 
   if (args.includes('--help') || args.includes('-h')) {
@@ -69,6 +73,8 @@ function printHumanReport(report: ReturnType<typeof runDoctor>): void {
 
   if (report.issues.length === 0) {
     logger.success('All checks passed');
+    console.log('\n💡 Tip: If this is your first run, we recommend running:');
+    console.log('   cursorflow doctor --test-agent\n');
     return;
   }
 
@@ -106,6 +112,11 @@ function printHumanReport(report: ReturnType<typeof runDoctor>): void {
 async function doctor(args: string[]): Promise<void> {
   const options = parseArgs(args);
 
+  if (options.testAgent) {
+    const success = runInteractiveAgentTest();
+    process.exit(success ? 0 : 1);
+  }
+
   const report = runDoctor({
     cwd: process.cwd(),
     tasksDir: options.tasksDir || undefined,
@@ -119,6 +130,11 @@ async function doctor(args: string[]): Promise<void> {
     printHumanReport(report);
   }
 
+  // Save successful doctor run status
+  if (report.ok && report.context.repoRoot) {
+    saveDoctorStatus(report.context.repoRoot, report);
+  }
+
   process.exit(report.ok ? 0 : 1);
 }