@litmers/cursorflow-orchestrator 0.1.8 → 0.1.9

package/src/cli/clean.ts

@@ -1,36 +1,156 @@
 /**
- * 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;
 }
 
 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'),
   };
 }
 
 async function clean(args: string[]): Promise<void> {
-  logger.section('🧹 Cleaning CursorFlow Resources');
-  
   const options = parseArgs(args);
+  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);
   
-  logger.info('This command will be fully implemented in the next phase');
-  logger.info(`Clean type: ${options.type}`);
-  logger.info(`Dry run: ${options.dryRun}`);
+  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/index.ts

@@ -20,45 +20,45 @@ const COMMANDS: Record<string, CommandFn> = {
 
 function printHelp(): void {
   console.log(`
-CursorFlow - Git worktree-based parallel AI agent orchestration
+\x1b[1m\x1b[36mCursorFlow\x1b[0m - Git worktree-based parallel AI agent orchestration
 
-Usage: cursorflow <command> [options]
+\x1b[1mUSAGE\x1b[0m
+  $ \x1b[32mcursorflow\x1b[0m <command> [options]
 
-Commands:
-  init [options]              Initialize CursorFlow in project
-  run <tasks-dir> [options]   Run orchestration
-  monitor [run-dir] [options] Monitor lane execution
-  clean <type> [options]      Clean branches/worktrees/logs
-  resume <lane> [options]     Resume interrupted lane
-  doctor [options]            Check environment and preflight
-  signal <lane> <msg>         Directly intervene in a running lane
+\x1b[1mCOMMANDS\x1b[0m
+  \x1b[33minit\x1b[0m [options]              Initialize CursorFlow in project
+  \x1b[33mrun\x1b[0m <tasks-dir> [options]   Run orchestration (DAG-based)
+  \x1b[33mmonitor\x1b[0m [run-dir] [options] \x1b[36mInteractive\x1b[0m lane dashboard
+  \x1b[33mclean\x1b[0m <type> [options]      Clean branches/worktrees/logs
+  \x1b[33mresume\x1b[0m <lane> [options]     Resume interrupted lane
+  \x1b[33mdoctor\x1b[0m [options]            Check environment and preflight
+  \x1b[33msignal\x1b[0m <lane> <msg>         Directly intervene in a running lane
 
-Global Options:
+\x1b[1mGLOBAL OPTIONS\x1b[0m
   --config <path>             Config file path
   --help, -h                  Show help
   --version, -v               Show version
 
-Examples:
-  cursorflow init --example
-  cursorflow run _cursorflow/tasks/MyFeature/
-  cursorflow monitor --watch
-  cursorflow clean branches --all
-  cursorflow doctor
+\x1b[1mEXAMPLES\x1b[0m
+  $ \x1b[32mcursorflow init --example\x1b[0m
+  $ \x1b[32mcursorflow run _cursorflow/tasks/MyFeature/\x1b[0m
+  $ \x1b[32mcursorflow monitor latest\x1b[0m
+  $ \x1b[32mcursorflow signal lane-1 "Please use pnpm instead of npm"\x1b[0m
 
-Documentation:
+\x1b[1mDOCUMENTATION\x1b[0m
   https://github.com/eungjin-cigro/cursorflow#readme
   `);
 }
 
 function printVersion(): void {
   const pkg = require('../../package.json');
-  console.log(`CursorFlow v${pkg.version}`);
+  console.log(`\x1b[1m\x1b[36mCursorFlow\x1b[0m v${pkg.version}`);
 }
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   
-  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  if (args.length === 0 || args.includes('--help') || args.includes('-h') || args[0] === 'help') {
     printHelp();
     return;
   }

package/src/cli/monitor.ts

@@ -44,6 +44,7 @@ class InteractiveMonitor {
   private terminalScrollOffset: number = 0;
   private lastTerminalTotalLines: number = 0;
   private interventionInput: string = '';
+  private notification: { message: string; type: 'info' | 'error' | 'success'; time: number } | null = null;
 
   constructor(runDir: string, interval: number) {
     this.runDir = runDir;
@@ -155,6 +156,9 @@ class InteractiveMonitor {
         this.terminalScrollOffset = 0;
         this.render();
         break;
+      case 'k':
+        this.killLane();
+        break;
       case 'i':
         const lane = this.lanes.find(l => l.name === this.selectedLaneName);
         if (lane) {
@@ -304,10 +308,43 @@ class InteractiveMonitor {
     this.render();
   }
 
+  private killLane() {
+    if (!this.selectedLaneName) return;
+    const lane = this.lanes.find(l => l.name === this.selectedLaneName);
+    if (!lane) return;
+
+    const status = this.getLaneStatus(lane.path, lane.name);
+    if (status.pid && status.status === 'running') {
+      try {
+        process.kill(status.pid, 'SIGTERM');
+        this.showNotification(`Sent SIGTERM to PID ${status.pid}`, 'success');
+      } catch (e) {
+        this.showNotification(`Failed to kill PID ${status.pid}`, 'error');
+      }
+    } else {
+      this.showNotification(`No running process found for ${this.selectedLaneName}`, 'info');
+    }
+  }
+
+  private showNotification(message: string, type: 'info' | 'error' | 'success') {
+    this.notification = { message, type, time: Date.now() };
+    this.render();
+  }
+
   private render() {
     // Clear screen
     process.stdout.write('\x1Bc');
     
+    // Clear old notifications
+    if (this.notification && Date.now() - this.notification.time > 3000) {
+      this.notification = null;
+    }
+
+    if (this.notification) {
+      const color = this.notification.type === 'error' ? '\x1b[31m' : this.notification.type === 'success' ? '\x1b[32m' : '\x1b[36m';
+      console.log(`${color}🔔 ${this.notification.message}\x1b[0m\n`);
+    }
+    
     switch (this.view) {
       case View.LIST:
         this.renderList();
@@ -413,6 +450,7 @@ class InteractiveMonitor {
     console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
 
     process.stdout.write(`  Status:    ${this.getStatusIcon(status.status)} ${status.status}\n`);
+    process.stdout.write(`  PID:       ${status.pid || '-'}\n`);
     process.stdout.write(`  Progress:  ${status.progress} (${status.currentTask}/${status.totalTasks} tasks)\n`);
     process.stdout.write(`  Time:      ${this.formatDuration(status.duration)}\n`);
     process.stdout.write(`  Branch:    ${status.pipelineBranch}\n`);
@@ -429,7 +467,7 @@ class InteractiveMonitor {
 
     console.log('\n💬 Conversation History (Select to see full details):');
     console.log('─'.repeat(80));
-    process.stdout.write('  [↑/↓] Browse | [→/Enter] Full Msg | [I] Intervene | [T] Live Terminal | [Esc/←] Back\n\n');
+    process.stdout.write('  [↑/↓] Browse | [→/Enter] Full Msg | [I] Intervene | [K] Kill | [T] Live Terminal | [Esc/←] Back\n\n');
 
     if (this.currentLogs.length === 0) {
       console.log('  (No messages yet)');
@@ -670,6 +708,7 @@ class InteractiveMonitor {
       dependsOn,
       duration,
       error: state.error,
+      pid: state.pid
     };
   }
 

package/src/core/runner.ts

@@ -107,15 +107,79 @@ function parseJsonFromStdout(stdout: string): any {
   return null;
 }
 
+/** Default timeout: 5 minutes */
+const DEFAULT_TIMEOUT_MS = 300000;
+
+/** Heartbeat interval: 30 seconds */
+const HEARTBEAT_INTERVAL_MS = 30000;
+
+/**
+ * Validate task configuration
+ * @throws Error if validation fails
+ */
+export function validateTaskConfig(config: RunnerConfig): void {
+  if (!config.tasks || !Array.isArray(config.tasks)) {
+    throw new Error('Invalid config: "tasks" must be an array');
+  }
+  
+  if (config.tasks.length === 0) {
+    throw new Error('Invalid config: "tasks" array is empty');
+  }
+  
+  for (let i = 0; i < config.tasks.length; i++) {
+    const task = config.tasks[i];
+    const taskNum = i + 1;
+    
+    if (!task) {
+      throw new Error(`Invalid config: Task ${taskNum} is null or undefined`);
+    }
+    
+    if (!task.name || typeof task.name !== 'string') {
+      throw new Error(
+        `Invalid config: Task ${taskNum} missing required "name" field.\n` +
+        `  Found: ${JSON.stringify(task, null, 2).substring(0, 200)}...\n` +
+        `  Expected: { "name": "task-name", "prompt": "..." }`
+      );
+    }
+    
+    if (!task.prompt || typeof task.prompt !== 'string') {
+      throw new Error(
+        `Invalid config: Task "${task.name}" (${taskNum}) missing required "prompt" field`
+      );
+    }
+    
+    // Validate task name format (no spaces, special chars that could break branch names)
+    if (!/^[a-zA-Z0-9_-]+$/.test(task.name)) {
+      throw new Error(
+        `Invalid config: Task name "${task.name}" contains invalid characters.\n` +
+        `  Task names must only contain: letters, numbers, underscore (_), hyphen (-)`
+      );
+    }
+  }
+  
+  // Validate timeout if provided
+  if (config.timeout !== undefined) {
+    if (typeof config.timeout !== 'number' || config.timeout <= 0) {
+      throw new Error(
+        `Invalid config: "timeout" must be a positive number (milliseconds).\n` +
+        `  Found: ${config.timeout}`
+      );
+    }
+  }
+}
+
 /**
  * Execute cursor-agent command with streaming and better error handling
  */
-export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, signalDir }: { 
+export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, signalDir, timeout, enableIntervention }: { 
   workspaceDir: string; 
   chatId: string; 
   prompt: string; 
   model?: string; 
   signalDir?: string;
+  timeout?: number;
+  /** Enable stdin piping for intervention feature (may cause buffering issues on some systems) */
+  enableIntervention?: boolean;
 }): Promise<AgentSendResult> {
   const args = [
     '--print',
@@ -126,17 +190,67 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     prompt,
   ];
   
-  logger.info('Executing cursor-agent...');
+  const timeoutMs = timeout || DEFAULT_TIMEOUT_MS;
+  logger.info(`Executing cursor-agent... (timeout: ${Math.round(timeoutMs / 1000)}s)`);
+  
+  // Determine stdio mode based on intervention setting
+  // When intervention is enabled, we pipe stdin for message injection
+  // When disabled (default), we ignore stdin to avoid buffering issues
+  const stdinMode = enableIntervention ? 'pipe' : 'ignore';
+  
+  if (enableIntervention) {
+    logger.info('Intervention mode enabled (stdin piped)');
+  }
   
   return new Promise((resolve) => {
+    // Build environment, preserving user's NODE_OPTIONS but disabling problematic flags
+    const childEnv = { ...process.env };
+    
+    // Only filter out specific problematic NODE_OPTIONS, don't clear entirely
+    if (childEnv.NODE_OPTIONS) {
+      // Remove flags that might interfere with cursor-agent
+      const filtered = childEnv.NODE_OPTIONS
+        .split(' ')
+        .filter(opt => !opt.includes('--inspect') && !opt.includes('--debug'))
+        .join(' ');
+      childEnv.NODE_OPTIONS = filtered;
+    }
+    
+    // Disable Python buffering in case cursor-agent uses Python
+    childEnv.PYTHONUNBUFFERED = '1';
+    
     const child = spawn('cursor-agent', args, {
-      stdio: ['pipe', 'pipe', 'pipe'], // Enable stdin piping
-      env: process.env,
+      stdio: [stdinMode, 'pipe', 'pipe'],
+      env: childEnv,
     });
 
+    // Save PID to state if possible
+    if (child.pid && signalDir) {
+      try {
+        const statePath = path.join(signalDir, 'state.json');
+        if (fs.existsSync(statePath)) {
+          const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+          state.pid = child.pid;
+          fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+        }
+      } catch (e) {
+        // Best effort
+      }
+    }
+
     let fullStdout = '';
     let fullStderr = '';
 
+    // Heartbeat logging to show progress
+    let lastHeartbeat = Date.now();
+    let bytesReceived = 0;
+    const heartbeatInterval = setInterval(() => {
+      const elapsed = Math.round((Date.now() - lastHeartbeat) / 1000);
+      const totalElapsed = Math.round((Date.now() - startTime) / 1000);
+      logger.info(`⏱ Heartbeat: ${totalElapsed}s elapsed, ${bytesReceived} bytes received`);
+    }, HEARTBEAT_INTERVAL_MS);
+    const startTime = Date.now();
+
     // Watch for "intervention.txt" signal file if any
     const interventionPath = signalDir ? path.join(signalDir, 'intervention.txt') : null;
     let interventionWatcher: fs.FSWatcher | null = null;
@@ -147,8 +261,13 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
           try {
             const message = fs.readFileSync(interventionPath, 'utf8').trim();
             if (message) {
-              logger.info(`Injecting intervention: ${message}`);
-              child.stdin.write(message + '\n');
+              if (enableIntervention && child.stdin) {
+                logger.info(`Injecting intervention: ${message}`);
+                child.stdin.write(message + '\n');
+              } else {
+                logger.warn(`Intervention requested but stdin not available: ${message}`);
+                logger.warn('To enable intervention, set enableIntervention: true in config');
+              }
               fs.unlinkSync(interventionPath); // Clear it
             }
           } catch (e) {
@@ -158,30 +277,38 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
       });
     }
 
-    child.stdout.on('data', (data) => {
-      const str = data.toString();
-      fullStdout += str;
-      // Also pipe to our own stdout so it goes to terminal.log
-      process.stdout.write(data);
-    });
+    if (child.stdout) {
+      child.stdout.on('data', (data) => {
+        const str = data.toString();
+        fullStdout += str;
+        bytesReceived += data.length;
+        // Also pipe to our own stdout so it goes to terminal.log
+        process.stdout.write(data);
+      });
+    }
 
-    child.stderr.on('data', (data) => {
-      fullStderr += data.toString();
-      // Pipe to our own stderr so it goes to terminal.log
-      process.stderr.write(data);
-    });
+    if (child.stderr) {
+      child.stderr.on('data', (data) => {
+        fullStderr += data.toString();
+        // Pipe to our own stderr so it goes to terminal.log
+        process.stderr.write(data);
+      });
+    }
 
-    const timeout = setTimeout(() => {
+    const timeoutHandle = setTimeout(() => {
+      clearInterval(heartbeatInterval);
       child.kill();
+      const timeoutSec = Math.round(timeoutMs / 1000);
       resolve({
         ok: false,
         exitCode: -1,
-        error: 'cursor-agent timed out after 5 minutes. The LLM request may be taking too long or there may be network issues.',
+        error: `cursor-agent timed out after ${timeoutSec} seconds. The LLM request may be taking too long or there may be network issues.`,
       });
-    }, 300000);
+    }, timeoutMs);
 
     child.on('close', (code) => {
-      clearTimeout(timeout);
+      clearTimeout(timeoutHandle);
+      clearInterval(heartbeatInterval);
       if (interventionWatcher) interventionWatcher.close();
       
       const json = parseJsonFromStdout(fullStdout);
@@ -214,7 +341,8 @@ export async function cursorAgentSend({ workspaceDir, chatId, prompt, model, sig
     });
 
     child.on('error', (err) => {
-      clearTimeout(timeout);
+      clearTimeout(timeoutHandle);
+      clearInterval(heartbeatInterval);
       resolve({
         ok: false,
         exitCode: -1,
@@ -361,7 +489,9 @@ export async function runTask({
     chatId,
     prompt: prompt1,
     model,
-    signalDir: runDir
+    signalDir: runDir,
+    timeout: config.timeout,
+    enableIntervention: config.enableIntervention,
   });
   
   appendLog(convoPath, createConversationEntry('assistant', r1.resultText || r1.error || 'No response', {
@@ -405,6 +535,17 @@ export async function runTask({
 export async function runTasks(tasksFile: string, config: RunnerConfig, runDir: string, options: { startIndex?: number } = {}): Promise<TaskExecutionResult[]> {
   const startIndex = options.startIndex || 0;
   
+  // Validate configuration before starting
+  logger.info('Validating task configuration...');
+  try {
+    validateTaskConfig(config);
+    logger.success('✓ Configuration valid');
+  } catch (validationError: any) {
+    logger.error('❌ Configuration validation failed');
+    logger.error(`   ${validationError.message}`);
+    throw validationError;
+  }
+  
   // Ensure cursor-agent is installed
   ensureCursorAgent();
   

package/src/utils/types.ts

@@ -50,6 +50,14 @@ export interface RunnerConfig {
   reviewModel?: string;
   maxReviewIterations?: number;
   acceptanceCriteria?: string[];
+  /** Task execution timeout in milliseconds. Default: 300000 (5 minutes) */
+  timeout?: number;
+  /** 
+   * Enable intervention feature (stdin piping for message injection).
+   * Warning: May cause stdout buffering issues on some systems.
+   * Default: false
+   */
+  enableIntervention?: boolean;
 }
 
 export interface DependencyRequestPlan {
@@ -111,6 +119,7 @@ export interface LaneState {
   updatedAt?: number;
   tasksFile?: string; // Original tasks file path
   dependsOn?: string[];
+  pid?: number;
 }
 
 export interface ConversationEntry {