@litmers/cursorflow-orchestrator 0.1.0

package/commands/cursorflow-run.md

@@ -0,0 +1,129 @@
+# CursorFlow Run
+
+## Overview
+준비된 태스크를 실행합니다. 단일 레인 또는 멀티 레인 오케스트레이션을 수행합니다.
+
+## Steps
+
+1. **태스크 디렉토리 확인**
+   ```bash
+   ls _cursorflow/tasks/
+   ```
+
+2. **멀티 레인 실행**
+   ```bash
+   cursorflow run _cursorflow/tasks/MyFeature/
+   ```
+
+3. **단일 레인 실행**
+   ```bash
+   cursorflow lane _cursorflow/tasks/MyFeature/01-task.json
+   ```
+
+4. **Dry run (실행 계획 확인)**
+   ```bash
+   cursorflow run _cursorflow/tasks/MyFeature/ --dry-run
+   ```
+
+5. **실행 모니터링**
+   
+   실행 중에는 다른 터미널에서 모니터링:
+   ```bash
+   cursorflow monitor --watch
+   ```
+
+## 옵션
+
+| 옵션 | 설명 |
+|------|------|
+| `--dry-run` | 실제 실행 없이 계획만 확인 |
+| `--executor <type>` | 실행 방식 (cursor-agent \| cloud) |
+| `--no-review` | 코드 리뷰 비활성화 |
+| `--config <path>` | 커스텀 설정 파일 경로 |
+
+## 예제
+
+### 기본 실행
+```bash
+cursorflow run _cursorflow/tasks/2512191700_MyFeature/
+```
+
+### Cloud 실행 (API 키 필요)
+```bash
+export CURSOR_API_KEY=your_key
+cursorflow run _cursorflow/tasks/MyFeature/ --executor cloud
+```
+
+### 리뷰 없이 빠른 실행
+```bash
+cursorflow run _cursorflow/tasks/MyFeature/ --no-review
+```
+
+## 실행 프로세스
+
+1. **초기화**
+   - 설정 로드
+   - cursor-agent CLI 확인
+   - Git 저장소 확인
+
+2. **레인 준비**
+   - Worktree 생성
+   - 브랜치 체크아웃
+   - 환경 설정
+
+3. **태스크 실행**
+   - 순차적으로 태스크 수행
+   - 각 태스크 완료 후 커밋
+   - 리뷰 활성화 시 자동 리뷰
+
+4. **완료**
+   - 변경사항 푸시
+   - PR 생성 (설정에 따라)
+   - 로그 저장
+
+## 로그 위치
+
+실행 로그는 `_cursorflow/logs/runs/` 에 저장됩니다:
+
+```
+_cursorflow/logs/runs/<lane>-<timestamp>/
+├── state.json              # 레인 상태
+├── results.json            # 태스크 결과
+├── conversation.jsonl      # 에이전트 대화
+├── git-operations.jsonl    # Git 작업 로그
+└── events.jsonl            # 이벤트 로그
+```
+
+## Checklist
+- [ ] cursor-agent CLI가 설치되어 있는가?
+- [ ] Git worktree가 사용 가능한가?
+- [ ] 태스크 파일이 올바른가?
+- [ ] 브랜치 이름이 충돌하지 않는가?
+- [ ] 필요한 환경 변수가 설정되었는가? (Cloud 실행 시)
+
+## 트러블슈팅
+
+### 브랜치 충돌
+```bash
+# 기존 브랜치 정리
+cursorflow clean branches --pattern "feature/my-*"
+```
+
+### Worktree 충돌
+```bash
+# 기존 worktree 정리
+cursorflow clean worktrees --all
+```
+
+### 실행 실패
+```bash
+# 로그 확인
+cursorflow monitor
+# 또는
+cat _cursorflow/logs/runs/latest/*/state.json
+```
+
+## Next Steps
+1. `cursorflow monitor --watch`로 진행 상황 모니터링
+2. 완료 후 PR 확인 및 리뷰
+3. 실패 시 `cursorflow resume <lane>`로 재개

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@litmers/cursorflow-orchestrator",
+  "version": "0.1.0",
+  "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": {
+    "test": "node test/run.js",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "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/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Post-install script
+ * 
+ * Shows a message after package installation
+ */
+
+console.log(`
+📦 CursorFlow installed successfully!
+
+To get started:
+
+  1. Initialize CursorFlow in your project:
+     npx cursorflow init
+
+  2. Install Cursor commands:
+     npx cursorflow-setup
+
+  3. Start using CursorFlow:
+     cursorflow run _cursorflow/tasks/example/
+
+Documentation:
+  https://github.com/eungjin-cigro/cursorflow#readme
+
+Need help?
+  cursorflow --help
+`);

package/src/cli/clean.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow clean command (stub)
+ */
+
+const logger = require('../utils/logger');
+
+function parseArgs(args) {
+  return {
+    type: args[0], // branches | worktrees | logs | all
+    pattern: null,
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+  };
+}
+
+async function clean(args) {
+  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}`);
+  
+  logger.warn('\n⚠️  Implementation pending');
+  logger.info('This will clean branches, worktrees, and logs');
+}
+
+module.exports = clean;

package/src/cli/index.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow CLI - Main entry point
+ */
+
+const logger = require('../utils/logger');
+
+const COMMANDS = {
+  init: require('./init'),
+  run: require('./run'),
+  monitor: require('./monitor'),
+  clean: require('./clean'),
+  resume: require('./resume'),
+};
+
+function printHelp() {
+  console.log(`
+CursorFlow - Git worktree-based parallel AI agent orchestration
+
+Usage: cursorflow <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
+
+Global Options:
+  --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
+
+Documentation:
+  https://github.com/eungjin-cigro/cursorflow#readme
+  `);
+}
+
+function printVersion() {
+  const pkg = require('../../package.json');
+  console.log(`CursorFlow v${pkg.version}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  
+  if (args.includes('--version') || args.includes('-v')) {
+    printVersion();
+    process.exit(0);
+  }
+  
+  const command = args[0];
+  const commandArgs = args.slice(1);
+  
+  if (!COMMANDS[command]) {
+    logger.error(`Unknown command: ${command}`);
+    console.log('\nRun "cursorflow --help" for usage information.');
+    process.exit(1);
+  }
+  
+  try {
+    await COMMANDS[command](commandArgs);
+  } catch (error) {
+    logger.error(error.message);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch(error => {
+    logger.error(`Fatal error: ${error.message}`);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  });
+}
+
+module.exports = main;

package/src/cli/init.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow init command
+ * 
+ * Initialize CursorFlow in a project
+ */
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../utils/logger');
+const { findProjectRoot, createDefaultConfig } = require('../utils/config');
+const { setupCommands } = require('./setup-commands');
+
+function parseArgs(args) {
+  const options = {
+    example: false,
+    withCommands: true,
+    configOnly: false,
+    force: false,
+  };
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    switch (arg) {
+      case '--example':
+        options.example = true;
+        break;
+      case '--with-commands':
+        options.withCommands = true;
+        break;
+      case '--no-commands':
+        options.withCommands = false;
+        break;
+      case '--config-only':
+        options.configOnly = true;
+        break;
+      case '--force':
+        options.force = true;
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+        break;
+    }
+  }
+  
+  return options;
+}
+
+function printHelp() {
+  console.log(`
+Usage: cursorflow init [options]
+
+Initialize CursorFlow in your project
+
+Options:
+  --example           Create example tasks
+  --with-commands     Install Cursor commands (default: true)
+  --no-commands       Skip Cursor commands installation
+  --config-only       Only create config file
+  --force             Overwrite existing files
+  --help, -h          Show help
+
+Examples:
+  cursorflow init
+  cursorflow init --example
+  cursorflow init --config-only
+  `);
+}
+
+function createDirectories(projectRoot, config) {
+  const tasksDir = path.join(projectRoot, config.tasksDir);
+  const logsDir = path.join(projectRoot, config.logsDir);
+  
+  if (!fs.existsSync(tasksDir)) {
+    fs.mkdirSync(tasksDir, { recursive: true });
+    logger.success(`Created directory: ${config.tasksDir}`);
+  } else {
+    logger.info(`Directory already exists: ${config.tasksDir}`);
+  }
+  
+  if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+    logger.success(`Created directory: ${config.logsDir}`);
+  } else {
+    logger.info(`Directory already exists: ${config.logsDir}`);
+  }
+}
+
+function createExampleTasks(projectRoot, config) {
+  const exampleDir = path.join(projectRoot, config.tasksDir, 'example');
+  
+  if (!fs.existsSync(exampleDir)) {
+    fs.mkdirSync(exampleDir, { recursive: true });
+  }
+  
+  const exampleTask = {
+    repository: "https://github.com/your-org/your-repo",
+    baseBranch: "main",
+    branchPrefix: "cursorflow/example-",
+    executor: "cursor-agent",
+    autoCreatePr: false,
+    pollInterval: 60,
+    tasks: [
+      {
+        name: "hello",
+        model: "sonnet-4.5",
+        prompt: `# Example Task
+
+## Goal
+Create a simple hello.txt file with a greeting message.
+
+## Steps
+1. Create a file called hello.txt
+2. Write "Hello from CursorFlow!" in the file
+3. Commit the change with message: "feat: add hello file"
+`
+      }
+    ]
+  };
+  
+  const taskPath = path.join(exampleDir, '01-hello.json');
+  fs.writeFileSync(taskPath, JSON.stringify(exampleTask, null, 2) + '\n', 'utf8');
+  
+  logger.success(`Created example task: ${path.relative(projectRoot, taskPath)}`);
+  
+  // Create README
+  const readmePath = path.join(exampleDir, 'README.md');
+  const readme = `# Example Task
+
+This is an example CursorFlow task to help you get started.
+
+## Running the example
+
+\`\`\`bash
+cursorflow run ${config.tasksDir}/example/
+\`\`\`
+
+## What it does
+
+- Creates a simple hello.txt file
+- Demonstrates basic task structure
+- Shows how to write task prompts
+
+## Next steps
+
+1. Review the task configuration in \`01-hello.json\`
+2. Run the task to see CursorFlow in action
+3. Create your own tasks based on this example
+`;
+  
+  fs.writeFileSync(readmePath, readme, 'utf8');
+  logger.success(`Created example README: ${path.relative(projectRoot, readmePath)}`);
+}
+
+async function init(args) {
+  logger.section('🚀 Initializing CursorFlow');
+  
+  const options = parseArgs(args);
+  const projectRoot = findProjectRoot();
+  
+  logger.info(`Project root: ${projectRoot}`);
+  
+  // 1. Create config file
+  const configPath = path.join(projectRoot, 'cursorflow.config.js');
+  const configExists = fs.existsSync(configPath);
+  
+  if (configExists && !options.force) {
+    logger.warn(`Config file already exists: ${configPath}`);
+    logger.info('Use --force to overwrite');
+  } else {
+    try {
+      createDefaultConfig(projectRoot);
+      logger.success(`Created config file: cursorflow.config.js`);
+    } catch (error) {
+      if (error.message.includes('already exists') && !options.force) {
+        logger.warn(error.message);
+      } else {
+        throw error;
+      }
+    }
+  }
+  
+  const config = require(configPath);
+  
+  if (options.configOnly) {
+    logger.section('✅ Configuration initialized');
+    logger.info('\nNext steps:');
+    logger.info('  1. Review cursorflow.config.js');
+    logger.info('  2. Run: cursorflow init (without --config-only) to set up directories');
+    return;
+  }
+  
+  // 2. Create directories
+  logger.info('\n📁 Creating directories...');
+  createDirectories(projectRoot, config);
+  
+  // 3. Install Cursor commands
+  if (options.withCommands) {
+    logger.info('\n📋 Installing Cursor commands...');
+    try {
+      await setupCommands({ force: options.force, silent: false });
+    } catch (error) {
+      logger.warn(`Failed to install Cursor commands: ${error.message}`);
+      logger.info('You can install them later with: npx cursorflow-setup');
+    }
+  }
+  
+  // 4. Create example tasks
+  if (options.example) {
+    logger.info('\n📝 Creating example tasks...');
+    createExampleTasks(projectRoot, config);
+  }
+  
+  // 5. Summary
+  logger.section('✅ CursorFlow initialized successfully!');
+  
+  console.log('\n📚 Next steps:\n');
+  console.log('  1. Review cursorflow.config.js');
+  console.log('  2. Type "/" in Cursor IDE to see available commands');
+  
+  if (options.example) {
+    console.log(`  3. Run: cursorflow run ${config.tasksDir}/example/`);
+  } else {
+    console.log('  3. Create tasks with: cursorflow prepare MyFeature');
+  }
+  
+  console.log('\n📖 Documentation:');
+  console.log('  https://github.com/eungjin-cigro/cursorflow#readme');
+  console.log('');
+}
+
+module.exports = init;

package/src/cli/monitor.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow monitor command (stub)
+ */
+
+const logger = require('../utils/logger');
+
+function parseArgs(args) {
+  return {
+    runDir: args[0],
+    watch: args.includes('--watch'),
+    interval: 2,
+  };
+}
+
+async function monitor(args) {
+  logger.section('📡 Monitoring Lane Execution');
+  
+  const options = parseArgs(args);
+  
+  logger.info('This command will be fully implemented in the next phase');
+  logger.info(`Run directory: ${options.runDir || 'latest'}`);
+  logger.info(`Watch mode: ${options.watch}`);
+  
+  logger.warn('\n⚠️  Implementation pending');
+  logger.info('This will show real-time lane status from logs');
+}
+
+module.exports = monitor;

package/src/cli/resume.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow resume command (stub)
+ */
+
+const logger = require('../utils/logger');
+
+function parseArgs(args) {
+  return {
+    lane: args[0],
+    runDir: null,
+    clean: args.includes('--clean'),
+    restart: args.includes('--restart'),
+  };
+}
+
+async function resume(args) {
+  logger.section('🔁 Resuming Lane');
+  
+  const options = parseArgs(args);
+  
+  logger.info('This command will be fully implemented in the next phase');
+  logger.info(`Lane: ${options.lane}`);
+  logger.info(`Clean: ${options.clean}`);
+  logger.info(`Restart: ${options.restart}`);
+  
+  logger.warn('\n⚠️  Implementation pending');
+  logger.info('This will resume interrupted lanes');
+}
+
+module.exports = resume;

package/src/cli/run.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * CursorFlow run command
+ */
+
+const path = require('path');
+const fs = require('fs');
+const logger = require('../utils/logger');
+const { orchestrate } = require('../core/orchestrator');
+const { loadConfig } = require('../utils/config');
+
+function parseArgs(args) {
+  return {
+    tasksDir: args.find(a => !a.startsWith('--')),
+    dryRun: args.includes('--dry-run'),
+    executor: args[args.indexOf('--executor') + 1] || null,
+  };
+}
+
+async function run(args) {
+  const options = parseArgs(args);
+  
+  if (!options.tasksDir) {
+    logger.error('Tasks directory required');
+    console.log('\nUsage: cursorflow run <tasks-dir> [options]');
+    process.exit(1);
+  }
+  
+  if (!fs.existsSync(options.tasksDir)) {
+    logger.error(`Tasks directory not found: ${options.tasksDir}`);
+    process.exit(1);
+  }
+  
+  const config = loadConfig();
+  
+  try {
+    await orchestrate(options.tasksDir, {
+      executor: options.executor || config.executor,
+      pollInterval: config.pollInterval * 1000,
+      runDir: path.join(config.logsDir, 'runs', `run-${Date.now()}`),
+    });
+  } catch (error) {
+    logger.error(`Orchestration failed: ${error.message}`);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+module.exports = run;