@litmers/cursorflow-orchestrator 0.1.0

package/src/core/runner.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * Core Runner - Execute tasks sequentially in a lane
+ * 
+ * Adapted from sequential-agent-runner.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const git = require('../utils/git');
+const logger = require('../utils/logger');
+const { ensureCursorAgent, checkCursorApiKey } = require('../utils/cursor-agent');
+const { saveState, loadState, appendLog, createConversationEntry, createGitLogEntry } = require('../utils/state');
+
+/**
+ * Execute cursor-agent command
+ */
+function cursorAgentCreateChat() {
+  const { execSync } = require('child_process');
+  const out = execSync('cursor-agent create-chat', {
+    encoding: 'utf8',
+    stdio: 'pipe',
+  });
+  const lines = out.split('\n').filter(Boolean);
+  return lines[lines.length - 1] || null;
+}
+
+function parseJsonFromStdout(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return null;
+  const lines = text.split('\n').filter(Boolean);
+  
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (line.startsWith('{') && line.endsWith('}')) {
+      try {
+        return JSON.parse(line);
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+function cursorAgentSend({ workspaceDir, chatId, prompt, model }) {
+  const { spawnSync } = require('child_process');
+  
+  const args = [
+    '--print',
+    '--output-format', 'json',
+    '--workspace', workspaceDir,
+    ...(model ? ['--model', model] : []),
+    '--resume', chatId,
+    prompt,
+  ];
+  
+  const res = spawnSync('cursor-agent', args, {
+    encoding: 'utf8',
+    stdio: 'pipe',
+  });
+  
+  const json = parseJsonFromStdout(res.stdout);
+  
+  if (res.status !== 0 || !json || json.type !== 'result') {
+    const msg = res.stderr?.trim() || res.stdout?.trim() || `exit=${res.status}`;
+    return {
+      ok: false,
+      exitCode: res.status,
+      error: msg,
+    };
+  }
+  
+  return {
+    ok: !json.is_error,
+    exitCode: res.status,
+    sessionId: json.session_id || chatId,
+    resultText: json.result || '',
+  };
+}
+
+/**
+ * Extract dependency change request from agent response
+ */
+function extractDependencyRequest(text) {
+  const t = String(text || '');
+  const marker = 'DEPENDENCY_CHANGE_REQUIRED';
+  
+  if (!t.includes(marker)) {
+    return { required: false };
+  }
+  
+  const after = t.split(marker).slice(1).join(marker);
+  const match = after.match(/\{[\s\S]*?\}/);
+  
+  if (match) {
+    try {
+      return {
+        required: true,
+        plan: JSON.parse(match[0]),
+        raw: t,
+      };
+    } catch {
+      return { required: true, raw: t };
+    }
+  }
+  
+  return { required: true, raw: t };
+}
+
+/**
+ * Wrap prompt with dependency policy
+ */
+function wrapPromptForDependencyPolicy(prompt, policy) {
+  if (policy.allowDependencyChange && !policy.lockfileReadOnly) {
+    return prompt;
+  }
+  
+  return `# Dependency Policy (MUST FOLLOW)
+
+You are running in a restricted lane.
+
+- allowDependencyChange: ${policy.allowDependencyChange}
+- lockfileReadOnly: ${policy.lockfileReadOnly}
+
+Rules:
+- BEFORE making any code changes, decide whether dependency changes are required.
+- If dependency changes are required, DO NOT change any files. Instead reply with:
+
+DEPENDENCY_CHANGE_REQUIRED
+\`\`\`json
+{ "reason": "...", "changes": [...], "commands": ["pnpm add ..."], "notes": "..." }
+\`\`\`
+
+Then STOP.
+- If dependency changes are NOT required, proceed normally.
+
+---
+
+${prompt}`;
+}
+
+/**
+ * Apply file permissions based on dependency policy
+ */
+function applyDependencyFilePermissions(worktreeDir, policy) {
+  const targets = [];
+  
+  if (!policy.allowDependencyChange) {
+    targets.push('package.json');
+  }
+  
+  if (policy.lockfileReadOnly) {
+    targets.push('pnpm-lock.yaml', 'package-lock.json', 'yarn.lock');
+  }
+  
+  for (const file of targets) {
+    const filePath = path.join(worktreeDir, file);
+    if (!fs.existsSync(filePath)) continue;
+    
+    try {
+      const stats = fs.statSync(filePath);
+      const mode = stats.mode & 0o777;
+      fs.chmodSync(filePath, mode & ~0o222); // Remove write bits
+    } catch {
+      // Best effort
+    }
+  }
+}
+
+/**
+ * Run a single task
+ */
+async function runTask({
+  task,
+  config,
+  index,
+  worktreeDir,
+  pipelineBranch,
+  taskBranch,
+  chatId,
+  runDir,
+}) {
+  const model = task.model || config.model || 'sonnet-4.5';
+  const convoPath = path.join(runDir, 'conversation.jsonl');
+  
+  logger.section(`[${index + 1}/${config.tasks.length}] ${task.name}`);
+  logger.info(`Model: ${model}`);
+  logger.info(`Branch: ${taskBranch}`);
+  
+  // Checkout task branch
+  git.runGit(['checkout', '-B', taskBranch], { cwd: worktreeDir });
+  
+  // Apply dependency permissions
+  applyDependencyFilePermissions(worktreeDir, config.dependencyPolicy);
+  
+  // Run prompt
+  const prompt1 = wrapPromptForDependencyPolicy(task.prompt, config.dependencyPolicy);
+  
+  appendLog(convoPath, createConversationEntry('user', prompt1, {
+    task: task.name,
+    model,
+  }));
+  
+  logger.info('Sending prompt to agent...');
+  const r1 = cursorAgentSend({
+    workspaceDir: worktreeDir,
+    chatId,
+    prompt: prompt1,
+    model,
+  });
+  
+  appendLog(convoPath, createConversationEntry('assistant', r1.resultText || r1.error, {
+    task: task.name,
+    model,
+  }));
+  
+  if (!r1.ok) {
+    return {
+      taskName: task.name,
+      taskBranch,
+      status: 'ERROR',
+      error: r1.error,
+    };
+  }
+  
+  // Check for dependency request
+  const depReq = extractDependencyRequest(r1.resultText);
+  if (depReq.required && !config.dependencyPolicy.allowDependencyChange) {
+    return {
+      taskName: task.name,
+      taskBranch,
+      status: 'BLOCKED_DEPENDENCY',
+      dependencyRequest: depReq.plan || null,
+    };
+  }
+  
+  // Push task branch
+  git.push(taskBranch, { cwd: worktreeDir, setUpstream: true });
+  
+  return {
+    taskName: task.name,
+    taskBranch,
+    status: 'FINISHED',
+  };
+}
+
+/**
+ * Run all tasks in sequence
+ */
+async function runTasks(config, runDir) {
+  ensureCursorAgent();
+  
+  const repoRoot = git.getRepoRoot();
+  const pipelineBranch = config.pipelineBranch || `${config.branchPrefix}${Date.now().toString(36)}`;
+  const worktreeDir = path.join(repoRoot, config.worktreeRoot || '_cursorflow/worktrees', pipelineBranch);
+  
+  logger.section('🚀 Starting Pipeline');
+  logger.info(`Pipeline Branch: ${pipelineBranch}`);
+  logger.info(`Worktree: ${worktreeDir}`);
+  logger.info(`Tasks: ${config.tasks.length}`);
+  
+  // Create worktree
+  git.createWorktree(worktreeDir, pipelineBranch, {
+    baseBranch: config.baseBranch || 'main',
+    cwd: repoRoot,
+  });
+  
+  // Create chat
+  const chatId = cursorAgentCreateChat();
+  
+  // Save initial state
+  const state = {
+    status: 'running',
+    pipelineBranch,
+    worktreeDir,
+    chatId,
+    totalTasks: config.tasks.length,
+    currentTaskIndex: 0,
+  };
+  
+  saveState(path.join(runDir, 'state.json'), state);
+  
+  // Run tasks
+  const results = [];
+  
+  for (let i = 0; i < config.tasks.length; i++) {
+    const task = config.tasks[i];
+    const taskBranch = `${pipelineBranch}--${String(i + 1).padStart(2, '0')}-${task.name}`;
+    
+    const result = await runTask({
+      task,
+      config,
+      index: i,
+      worktreeDir,
+      pipelineBranch,
+      taskBranch,
+      chatId,
+      runDir,
+    });
+    
+    results.push(result);
+    
+    // Update state
+    state.currentTaskIndex = i + 1;
+    saveState(path.join(runDir, 'state.json'), state);
+    
+    // Handle blocked or error
+    if (result.status === 'BLOCKED_DEPENDENCY') {
+      state.status = 'blocked_dependency';
+      state.dependencyRequest = result.dependencyRequest;
+      saveState(path.join(runDir, 'state.json'), state);
+      logger.warn('Task blocked on dependency change');
+      process.exit(2);
+    }
+    
+    if (result.status !== 'FINISHED') {
+      state.status = 'failed';
+      saveState(path.join(runDir, 'state.json'), state);
+      logger.error(`Task failed: ${result.error}`);
+      process.exit(1);
+    }
+    
+    // Merge into pipeline
+    logger.info(`Merging ${taskBranch} → ${pipelineBranch}`);
+    git.merge(taskBranch, { cwd: worktreeDir, noFf: true });
+    git.push(pipelineBranch, { cwd: worktreeDir });
+  }
+  
+  // Complete
+  state.status = 'completed';
+  saveState(path.join(runDir, 'state.json'), state);
+  
+  logger.success('All tasks completed!');
+  return results;
+}
+
+module.exports = {
+  runTasks,
+  runTask,
+};

package/src/utils/config.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Configuration loader for CursorFlow
+ * 
+ * Finds project root and loads user configuration with defaults
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Find project root by looking for package.json
+ */
+function findProjectRoot(cwd = process.cwd()) {
+  let current = cwd;
+  
+  while (current !== path.parse(current).root) {
+    const packagePath = path.join(current, 'package.json');
+    if (fs.existsSync(packagePath)) {
+      return current;
+    }
+    current = path.dirname(current);
+  }
+  
+  throw new Error('Cannot find project root with package.json');
+}
+
+/**
+ * Load configuration with defaults
+ */
+function loadConfig(projectRoot = null) {
+  if (!projectRoot) {
+    projectRoot = findProjectRoot();
+  }
+  
+  const configPath = path.join(projectRoot, 'cursorflow.config.js');
+  
+  // Default configuration
+  const defaults = {
+    // Directories
+    tasksDir: '_cursorflow/tasks',
+    logsDir: '_cursorflow/logs',
+    
+    // Git
+    baseBranch: 'main',
+    branchPrefix: 'feature/',
+    
+    // Execution
+    executor: 'cursor-agent',  // 'cursor-agent' | 'cloud'
+    pollInterval: 60,          // seconds
+    
+    // Dependencies
+    allowDependencyChange: false,
+    lockfileReadOnly: true,
+    
+    // Review
+    enableReview: false,
+    reviewModel: 'sonnet-4.5-thinking',
+    maxReviewIterations: 3,
+    
+    // Lane defaults
+    defaultLaneConfig: {
+      devPort: 3001,           // 3000 + laneNumber
+      autoCreatePr: false,
+    },
+    
+    // Logging
+    logLevel: 'info',          // 'error' | 'warn' | 'info' | 'debug'
+    verboseGit: false,
+    
+    // Advanced
+    worktreePrefix: 'cursorflow-',
+    maxConcurrentLanes: 10,
+    
+    // Internal
+    projectRoot,
+  };
+  
+  // Try to load user config
+  if (fs.existsSync(configPath)) {
+    try {
+      const userConfig = require(configPath);
+      return { ...defaults, ...userConfig, projectRoot };
+    } catch (error) {
+      console.warn(`Warning: Failed to load config from ${configPath}: ${error.message}`);
+      console.warn('Using default configuration...');
+    }
+  }
+  
+  return defaults;
+}
+
+/**
+ * Get absolute path for tasks directory
+ */
+function getTasksDir(config) {
+  return path.join(config.projectRoot, config.tasksDir);
+}
+
+/**
+ * Get absolute path for logs directory
+ */
+function getLogsDir(config) {
+  return path.join(config.projectRoot, config.logsDir);
+}
+
+/**
+ * Validate configuration
+ */
+function validateConfig(config) {
+  const errors = [];
+  
+  if (!config.tasksDir) {
+    errors.push('tasksDir is required');
+  }
+  
+  if (!config.logsDir) {
+    errors.push('logsDir is required');
+  }
+  
+  if (!['cursor-agent', 'cloud'].includes(config.executor)) {
+    errors.push('executor must be "cursor-agent" or "cloud"');
+  }
+  
+  if (config.pollInterval < 1) {
+    errors.push('pollInterval must be >= 1');
+  }
+  
+  if (errors.length > 0) {
+    throw new Error(`Configuration validation failed:\n${errors.join('\n')}`);
+  }
+  
+  return true;
+}
+
+/**
+ * Create default config file
+ */
+function createDefaultConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'cursorflow.config.js');
+  
+  if (fs.existsSync(configPath)) {
+    throw new Error(`Config file already exists: ${configPath}`);
+  }
+  
+  const template = `module.exports = {
+  // Directory configuration
+  tasksDir: '_cursorflow/tasks',
+  logsDir: '_cursorflow/logs',
+  
+  // Git configuration
+  baseBranch: 'main',
+  branchPrefix: 'feature/',
+  
+  // Execution configuration
+  executor: 'cursor-agent',  // 'cursor-agent' | 'cloud'
+  pollInterval: 60,          // seconds
+  
+  // Dependency management
+  allowDependencyChange: false,
+  lockfileReadOnly: true,
+  
+  // Review configuration
+  enableReview: false,
+  reviewModel: 'sonnet-4.5-thinking',
+  maxReviewIterations: 3,
+  
+  // Lane configuration
+  defaultLaneConfig: {
+    devPort: 3001,           // 3000 + laneNumber
+    autoCreatePr: false,
+  },
+  
+  // Logging
+  logLevel: 'info',          // 'error' | 'warn' | 'info' | 'debug'
+  verboseGit: false,
+  
+  // Advanced
+  worktreePrefix: 'cursorflow-',
+  maxConcurrentLanes: 10,
+};
+`;
+  
+  fs.writeFileSync(configPath, template, 'utf8');
+  return configPath;
+}
+
+module.exports = {
+  findProjectRoot,
+  loadConfig,
+  getTasksDir,
+  getLogsDir,
+  validateConfig,
+  createDefaultConfig,
+};

package/src/utils/cursor-agent.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Cursor Agent CLI wrapper and utilities
+ */
+
+const { execSync, spawnSync } = require('child_process');
+
+/**
+ * Check if cursor-agent CLI is installed
+ */
+function checkCursorAgentInstalled() {
+  try {
+    execSync('cursor-agent --version', { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get cursor-agent version
+ */
+function getCursorAgentVersion() {
+  try {
+    const version = execSync('cursor-agent --version', {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    }).trim();
+    return version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure cursor-agent is installed, exit with error message if not
+ */
+function ensureCursorAgent() {
+  if (!checkCursorAgentInstalled()) {
+    console.error(`
+❌ cursor-agent CLI is not installed
+
+Installation:
+  npm install -g @cursor/agent
+  # or
+  pnpm add -g @cursor/agent
+  # or
+  yarn global add @cursor/agent
+
+More info: https://docs.cursor.com/agent
+    `);
+    process.exit(1);
+  }
+}
+
+/**
+ * Print installation guide
+ */
+function printInstallationGuide() {
+  console.log(`
+📦 cursor-agent CLI Installation Guide
+
+The cursor-agent CLI is required to run CursorFlow orchestration.
+
+Installation methods:
+
+  npm install -g @cursor/agent
+  pnpm add -g @cursor/agent
+  yarn global add @cursor/agent
+
+Verification:
+
+  cursor-agent --version
+
+Documentation:
+
+  https://docs.cursor.com/agent
+
+After installation, run your command again.
+  `);
+}
+
+/**
+ * Check if CURSOR_API_KEY is set (for cloud execution)
+ */
+function checkCursorApiKey() {
+  return !!process.env.CURSOR_API_KEY;
+}
+
+/**
+ * Validate cursor-agent setup for given executor type
+ */
+function validateSetup(executor = 'cursor-agent') {
+  const errors = [];
+  
+  if (executor === 'cursor-agent') {
+    if (!checkCursorAgentInstalled()) {
+      errors.push('cursor-agent CLI is not installed');
+    }
+  }
+  
+  if (executor === 'cloud') {
+    if (!checkCursorApiKey()) {
+      errors.push('CURSOR_API_KEY environment variable is not set');
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Get available models (if cursor-agent supports it)
+ */
+function getAvailableModels() {
+  try {
+    // This is a placeholder - actual implementation depends on cursor-agent API
+    const result = execSync('cursor-agent --model invalid "test"', {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    
+    // Parse models from error message
+    // This is an example - actual parsing depends on cursor-agent output
+    return [];
+  } catch (error) {
+    // Parse from error message
+    const output = error.stderr || error.stdout || '';
+    // Extract model names from output
+    return parseModelsFromOutput(output);
+  }
+}
+
+/**
+ * Parse model names from cursor-agent output
+ */
+function parseModelsFromOutput(output) {
+  // This is a placeholder implementation
+  // Actual parsing depends on cursor-agent CLI output format
+  const models = [];
+  
+  // Example parsing logic
+  const lines = output.split('\n');
+  for (const line of lines) {
+    if (line.includes('sonnet') || line.includes('opus') || line.includes('gpt')) {
+      const match = line.match(/['"]([^'"]+)['"]/);
+      if (match) {
+        models.push(match[1]);
+      }
+    }
+  }
+  
+  return models;
+}
+
+/**
+ * Test cursor-agent with a simple command
+ */
+function testCursorAgent() {
+  try {
+    const result = spawnSync('cursor-agent', ['--help'], {
+      encoding: 'utf8',
+      stdio: 'pipe',
+    });
+    
+    return {
+      success: result.status === 0,
+      output: result.stdout,
+      error: result.stderr,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+
+module.exports = {
+  checkCursorAgentInstalled,
+  getCursorAgentVersion,
+  ensureCursorAgent,
+  printInstallationGuide,
+  checkCursorApiKey,
+  validateSetup,
+  getAvailableModels,
+  testCursorAgent,
+};