@litmers/cursorflow-orchestrator 0.1.31 → 0.1.36

package/src/utils/flow.ts

@@ -0,0 +1,42 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { safeJoin } from './path';
+
+/**
+ * Find flow directory by name in the flows directory.
+ * Matches by exact name or by suffix (ignoring ID prefix like '001_').
+ * 
+ * @param flowsDir The base flows directory (e.g., _cursorflow/flows)
+ * @param flowName The name of the flow to find
+ * @returns The absolute path to the flow directory, or null if not found
+ */
+export function findFlowDir(flowsDir: string, flowName: string): string | null {
+  if (!fs.existsSync(flowsDir)) {
+    return null;
+  }
+
+  const dirs = fs.readdirSync(flowsDir)
+    .filter(name => {
+      const dirPath = safeJoin(flowsDir, name);
+      try {
+        return fs.statSync(dirPath).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .filter(name => {
+      // Match by exact name or by suffix (ignoring ID prefix)
+      const match = name.match(/^\d+_(.+)$/);
+      return match ? match[1] === flowName : name === flowName;
+    });
+
+  if (dirs.length === 0) {
+    return null;
+  }
+
+  // Return the most recent one (highest ID / alphabetical)
+  dirs.sort((a, b) => b.localeCompare(a));
+  return safeJoin(flowsDir, dirs[0]!);
+}
+
+

package/src/utils/git.ts

@@ -6,6 +6,16 @@ import { execSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { safeJoin } from './path';
+import * as logger from './logger';
+
+let verboseGitEnabled = true;
+
+/**
+ * Enable or disable verbose git logging
+ */
+export function setVerboseGit(enabled: boolean): void {
+  verboseGitEnabled = enabled;
+}
 
 /**
  * Acquire a file-based lock for Git operations
@@ -132,8 +142,11 @@ function filterGitStderr(stderr: string): string {
 export function runGit(args: string[], options: GitRunOptions = {}): string {
   const { cwd, silent = false } = options;
   
-  if (process.env['DEBUG_GIT']) {
-    console.log(`[DEBUG_GIT] Running: git ${args.join(' ')} (cwd: ${cwd || process.cwd()})`);
+  if (verboseGitEnabled || process.env['DEBUG_GIT']) {
+    logger.debug(`Running: git ${args.join(' ')}`, { context: 'git', emoji: '🛠️' });
+    if (cwd) {
+      logger.debug(`  cwd: ${cwd}`, { context: 'git' });
+    }
   }
   
   try {
@@ -182,8 +195,11 @@ export function runGit(args: string[], options: GitRunOptions = {}): string {
 export function runGitResult(args: string[], options: GitRunOptions = {}): GitResult {
   const { cwd } = options;
   
-  if (process.env['DEBUG_GIT']) {
-    console.log(`[DEBUG_GIT] Running: git ${args.join(' ')} (result mode, cwd: ${cwd || process.cwd()})`);
+  if (verboseGitEnabled || process.env['DEBUG_GIT']) {
+    logger.debug(`Running: git ${args.join(' ')} (result mode)`, { context: 'git', emoji: '🛠️' });
+    if (cwd) {
+      logger.debug(`  cwd: ${cwd}`, { context: 'git' });
+    }
   }
 
   const result = spawnSync('git', args, {
@@ -267,7 +283,8 @@ export function createWorktree(worktreePath: string, branchName: string, options
   }
 
   // Ensure baseBranch is unambiguous (branch name rather than tag)
-  const unambiguousBase = (baseBranch.startsWith('refs/') || baseBranch.includes('/')) 
+  // Special case: HEAD should not be prefixed with refs/heads/
+  const unambiguousBase = (baseBranch === 'HEAD' || baseBranch.startsWith('refs/') || baseBranch.includes('/')) 
     ? baseBranch 
     : `refs/heads/${baseBranch}`;
 
@@ -588,6 +605,129 @@ export interface SafeMergeResult {
   aborted: boolean;
 }
 
+/**
+ * Check if merging a branch would cause conflicts (dry-run)
+ * This does NOT actually perform the merge - it only checks for potential conflicts
+ */
+export function checkMergeConflict(branchName: string, options: { cwd?: string } = {}): {
+  willConflict: boolean;
+  conflictingFiles: string[];
+  error?: string;
+} {
+  const { cwd } = options;
+  
+  // Use merge-tree to check for conflicts without actually merging
+  // First, get the merge base
+  const mergeBaseResult = runGitResult(['merge-base', 'HEAD', branchName], { cwd });
+  if (!mergeBaseResult.success) {
+    return { willConflict: false, conflictingFiles: [], error: `Cannot find merge base: ${mergeBaseResult.stderr}` };
+  }
+  
+  const mergeBase = mergeBaseResult.stdout.trim();
+  
+  // Use merge-tree to simulate the merge
+  const mergeTreeResult = runGitResult(['merge-tree', mergeBase, 'HEAD', branchName], { cwd });
+  
+  // Check for conflict markers in the output
+  const output = mergeTreeResult.stdout;
+  const hasConflict = output.includes('<<<<<<<') || output.includes('>>>>>>>') || output.includes('=======');
+  
+  if (hasConflict) {
+    // Extract conflicting file names from merge-tree output
+    const conflictingFiles: string[] = [];
+    const lines = output.split('\n');
+    let currentFile = '';
+    
+    for (const line of lines) {
+      // merge-tree output format includes file paths
+      if (line.startsWith('changed in both')) {
+        const match = line.match(/changed in both\s+(.+)/);
+        if (match) {
+          conflictingFiles.push(match[1]!.trim());
+        }
+      } else if (line.match(/^[a-f0-9]+ [a-f0-9]+ [a-f0-9]+\t(.+)$/)) {
+        const match = line.match(/\t(.+)$/);
+        if (match) {
+          currentFile = match[1]!;
+        }
+      } else if (line.includes('<<<<<<<') && currentFile) {
+        if (!conflictingFiles.includes(currentFile)) {
+          conflictingFiles.push(currentFile);
+        }
+      }
+    }
+    
+    return { willConflict: true, conflictingFiles };
+  }
+  
+  return { willConflict: false, conflictingFiles: [] };
+}
+
+/**
+ * Sync local branch with remote before starting work
+ * Fetches the latest from remote and fast-forwards if possible
+ */
+export function syncBranchWithRemote(branchName: string, options: { 
+  cwd?: string;
+  createIfMissing?: boolean;
+} = {}): { 
+  success: boolean; 
+  updated: boolean;
+  error?: string;
+  ahead?: number;
+  behind?: number;
+} {
+  const { cwd, createIfMissing = false } = options;
+  
+  // Fetch the branch from origin
+  const fetchResult = runGitResult(['fetch', 'origin', branchName], { cwd });
+  
+  if (!fetchResult.success) {
+    // Branch might not exist on remote yet
+    if (createIfMissing || fetchResult.stderr.includes("couldn't find remote ref")) {
+      return { success: true, updated: false };
+    }
+    return { success: false, updated: false, error: fetchResult.stderr };
+  }
+  
+  // Check if we're ahead/behind
+  const statusResult = runGitResult(['rev-list', '--left-right', '--count', `${branchName}...origin/${branchName}`], { cwd });
+  
+  if (!statusResult.success) {
+    // Remote tracking branch might not exist
+    return { success: true, updated: false };
+  }
+  
+  const [aheadStr, behindStr] = statusResult.stdout.trim().split(/\s+/);
+  const ahead = parseInt(aheadStr || '0');
+  const behind = parseInt(behindStr || '0');
+  
+  if (behind === 0) {
+    // Already up to date or ahead
+    return { success: true, updated: false, ahead, behind };
+  }
+  
+  if (ahead > 0 && behind > 0) {
+    // Diverged - cannot fast-forward
+    return { 
+      success: false, 
+      updated: false, 
+      ahead, 
+      behind,
+      error: `Branch has diverged: ${ahead} commits ahead, ${behind} commits behind. Manual resolution required.`
+    };
+  }
+  
+  // Can fast-forward
+  const mergeResult = runGitResult(['merge', '--ff-only', `origin/${branchName}`], { cwd });
+  
+  if (mergeResult.success) {
+    return { success: true, updated: true, ahead: 0, behind: 0 };
+  }
+  
+  return { success: false, updated: false, error: mergeResult.stderr };
+}
+
 /**
  * Safely merge a branch with conflict detection and auto-abort
  */

package/src/utils/state.ts

@@ -333,7 +333,6 @@ export function repairLaneState(statePath: string): LaneState | null {
     error: null,
     dependencyRequest: null,
     tasksFile: state.tasksFile,
-    dependsOn: state.dependsOn || [],
     completedTasks: state.completedTasks || [],
     updatedAt: Date.now(),
   };
@@ -465,7 +464,6 @@ export function createLaneState(
     error: null,
     dependencyRequest: null,
     tasksFile,
-    dependsOn: config.dependsOn || [],
   };
 }
 

package/src/utils/task-service.ts

@@ -106,7 +106,6 @@ export class TaskService {
         
         const laneName = this.extractLaneName(fileName);
         const tasks = content.tasks || [];
-        const dependsOn = content.dependsOn || [];
         const preset = this.detectPreset(tasks);
         const taskFlow = this.generateTaskFlow(tasks);
 
@@ -116,7 +115,6 @@ export class TaskService {
           preset,
           taskCount: tasks.length,
           taskFlow,
-          dependsOn,
         });
       } catch (error) {
         logger.debug(`Failed to parse lane file ${fileName}: ${error}`);
@@ -224,16 +222,6 @@ export class TaskService {
         errors.push(`Lane ${lane.fileName} has no tasks defined`);
       }
 
-      // Check dependencies exist
-      for (const dep of lane.dependsOn) {
-        const depExists = taskInfo.lanes.some(l => 
-          l.laneName === dep || l.fileName === dep || l.fileName === `${dep}.json`
-        );
-        if (!depExists) {
-          warnings.push(`Lane ${lane.fileName} depends on unknown lane: ${dep}`);
-        }
-      }
-
       // Validate lane file structure
       try {
         const filePath = path.join(taskInfo.path, lane.fileName);
@@ -259,10 +247,10 @@ export class TaskService {
       }
     }
 
-    // Check for circular dependencies
-    const circularDeps = this.detectCircularDependencies(taskInfo.lanes);
+    // Check for circular task-level dependencies
+    const circularDeps = this.detectTaskCircularDependencies(taskInfo);
     if (circularDeps.length > 0) {
-      errors.push(`Circular dependencies detected: ${circularDeps.join(' -> ')}`);
+      errors.push(`Circular task dependencies detected: ${circularDeps.join(' -> ')}`);
     }
 
     // Determine overall status
@@ -289,45 +277,65 @@ export class TaskService {
   }
 
   /**
-   * Detect circular dependencies in lane dependency graph
+   * Detect circular dependencies in task-level dependency graph
    */
-  private detectCircularDependencies(lanes: LaneFileInfo[]): string[] {
+  private detectTaskCircularDependencies(taskInfo: TaskDirInfo): string[] {
+    // Build task graph from all lane files
+    const taskGraph = new Map<string, string[]>(); // taskId -> dependencies
+    
+    for (const lane of taskInfo.lanes) {
+      try {
+        const filePath = path.join(taskInfo.path, lane.fileName);
+        const content = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        const laneName = lane.fileName.replace('.json', '');
+        
+        if (Array.isArray(content.tasks)) {
+          for (const task of content.tasks) {
+            const taskId = `${laneName}:${task.name}`;
+            const deps = task.dependsOn || [];
+            taskGraph.set(taskId, deps);
+          }
+        }
+      } catch {
+        // Skip invalid files
+      }
+    }
+    
+    // DFS to detect cycles
     const visited = new Set<string>();
     const stack = new Set<string>();
     const cycle: string[] = [];
-
-    const dfs = (laneName: string): boolean => {
-      if (stack.has(laneName)) {
-        cycle.push(laneName);
-        return true; // Cycle found
+    
+    const dfs = (taskId: string): boolean => {
+      if (stack.has(taskId)) {
+        cycle.push(taskId);
+        return true;
       }
-      if (visited.has(laneName)) {
+      if (visited.has(taskId)) {
         return false;
       }
-
-      visited.add(laneName);
-      stack.add(laneName);
-
-      const lane = lanes.find(l => l.laneName === laneName);
-      if (lane) {
-        for (const dep of lane.dependsOn) {
-          if (dfs(dep)) {
-            cycle.unshift(laneName);
-            return true;
-          }
+      
+      visited.add(taskId);
+      stack.add(taskId);
+      
+      const deps = taskGraph.get(taskId) || [];
+      for (const dep of deps) {
+        if (dfs(dep)) {
+          cycle.unshift(taskId);
+          return true;
         }
       }
-
-      stack.delete(laneName);
+      
+      stack.delete(taskId);
       return false;
     };
-
-    for (const lane of lanes) {
-      if (dfs(lane.laneName)) {
+    
+    for (const taskId of taskGraph.keys()) {
+      if (dfs(taskId)) {
         break;
       }
     }
-
+    
     return cycle;
   }
 

package/commands/cursorflow-review.md

@@ -1,56 +0,0 @@
-# CursorFlow Automatic Review
-
-## Overview
-CursorFlow features an integrated AI-powered code review system. It automatically validates task results against your defined acceptance criteria and can provide feedback to the agent for iterative improvements.
-
-## Configuration
-
-### Project-wide Settings
-Enable and configure the review process in your `cursorflow.config.js`:
-
-```javascript
-module.exports = {
-  enableReview: true,               // Enable automatic reviews
-  reviewModel: 'sonnet-4.5-thinking', // Model to use for reviewing
-  maxReviewIterations: 3,           // Number of fix/re-review cycles
-  // ...
-};
-```
-
-### Task-level Criteria
-Add `acceptanceCriteria` to your task JSON to guide the reviewer:
-
-```json
-{
-  "tasks": [
-    {
-      "name": "implement-logic",
-      "acceptanceCriteria": [
-        "No build errors",
-        "Tests in src/tests/ pass",
-        "Code follows project style guide"
-      ],
-      "prompt": "..."
-    }
-  ]
-}
-```
-
-## The Review Process
-
-1. **Completion**: When an agent finishes a task, CursorFlow spawns a reviewer agent.
-2. **Analysis**: The reviewer checks the worktree against the `acceptanceCriteria` using the `reviewModel`.
-3. **Verdict**:
-   - **Approved**: The lane proceeds to the next task.
-   - **Needs Changes**: The reviewer's feedback is sent back to the original agent.
-4. **Fix Loop**: The agent attempts to fix the issues based on the feedback. This repeats up to `maxReviewIterations`.
-
-## Monitoring Reviews
-You can track the review process in real-time using `cursorflow monitor`.
-- The lane status will change to **`reviewing`** (`👀`).
-- Reviewer feedback appears in the conversation history as a **`REVIEWER`** message.
-
-## Best Practices
-- **Specific Criteria**: Use clear, measurable criteria (e.g., "Build succeeds with `npm run build`").
-- **Thinking Models**: Use reasoning-heavy models like `sonnet-4.5-thinking` for reviews to get better results.
-- **Reasonable Iterations**: Set `maxReviewIterations` to 2 or 3 to prevent infinite loops.

package/commands/cursorflow-runs.md

@@ -1,59 +0,0 @@
-# CursorFlow Runs
-
-## Overview
-List and view detailed information about CursorFlow runs.
-
-## Usage
-
-```bash
-cursorflow runs [run-id] [options]
-```
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `[run-id]` | View details of a specific run |
-| `--running` | Filter to show only running runs |
-| `--status <status>` | Filter by status: `running`, `completed`, `failed`, `partial`, `pending` |
-| `--json` | Output in JSON format |
-| `--help`, `-h` | Show help |
-
-## Examples
-
-### List all runs
-```bash
-cursorflow runs
-```
-
-### List only running runs
-```bash
-cursorflow runs --running
-```
-
-### View details of a specific run
-```bash
-cursorflow runs run-1734873132
-```
-
-### Export runs to JSON
-```bash
-cursorflow runs --json > runs.json
-```
-
-## Output Format
-
-### List View
-```
-    Run ID              Task            Status     Lanes     Duration
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  ▶ run-20251222-153012 AuthSystem      🔄 running  2/3       15m 23s
-    run-20251222-143052 UserProfile     ✅ done     3/3       45m 12s
-```
-
-### Detail View
-The detail view includes:
-- Task name and overall status
-- Start time and duration
-- Individual lane statuses and PIDs
-- Associated Git branches and worktrees

package/dist/cli/runs.d.ts

@@ -1,5 +0,0 @@
-/**
- * CursorFlow runs command - List and view run details
- */
-declare function runs(args: string[]): Promise<void>;
-export = runs;