@litmers/cursorflow-orchestrator 0.1.20 → 0.1.28

package/src/services/process/index.ts

@@ -0,0 +1,261 @@
+/**
+ * Process Management Service
+ * 
+ * Utilities for detecting and managing lane processes.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync, spawnSync } from 'child_process';
+
+export interface ProcessInfo {
+  pid: number;
+  exists: boolean;
+  isRunning: boolean;
+  command?: string;
+  uptime?: number;
+  cpuPercent?: number;
+  memoryMb?: number;
+}
+
+export interface LaneProcessStatus {
+  laneName: string;
+  pid: number | null;
+  processExists: boolean;
+  processRunning: boolean;
+  stateStatus: string;
+  actualStatus: 'running' | 'dead' | 'unknown' | 'completed' | 'failed' | 'pending';
+  startTime: number | null;
+  endTime: number | null;
+  duration: number;
+  isStale: boolean;
+  processInfo?: ProcessInfo;
+}
+
+/**
+ * Check if a process exists and is running
+ */
+export function checkProcess(pid: number): ProcessInfo {
+  const result: ProcessInfo = {
+    pid,
+    exists: false,
+    isRunning: false,
+  };
+
+  try {
+    // Send signal 0 to check if process exists
+    process.kill(pid, 0);
+    result.exists = true;
+    result.isRunning = true;
+
+    // Try to get more info on Linux/macOS
+    if (process.platform !== 'win32') {
+      try {
+        const psResult = spawnSync('ps', ['-p', pid.toString(), '-o', 'pid,stat,comm,etime,%cpu,%mem'], {
+          encoding: 'utf8',
+          timeout: 1000,
+        });
+
+        if (psResult.status === 0) {
+          const psOutput = psResult.stdout.trim();
+          const lines = psOutput.split('\n');
+          if (lines.length > 1) {
+            const fields = lines[1]!.trim().split(/\s+/);
+            if (fields.length >= 4) {
+              result.command = fields[2];
+              
+              // Parse elapsed time (formats: MM:SS, HH:MM:SS, D-HH:MM:SS)
+              const etime = fields[3]!;
+              result.uptime = parseElapsedTime(etime);
+              
+              if (fields.length >= 5) {
+                result.cpuPercent = parseFloat(fields[4]!);
+              }
+              if (fields.length >= 6) {
+                result.memoryMb = parseFloat(fields[5]!);
+              }
+            }
+          }
+        }
+      } catch {
+        // ps failed, but process exists
+      }
+    }
+  } catch (err: any) {
+    // ESRCH = no such process
+    // EPERM = permission denied but process exists
+    if (err.code === 'EPERM') {
+      result.exists = true;
+      result.isRunning = true;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse ps elapsed time format to milliseconds
+ */
+function parseElapsedTime(etime: string): number {
+  // Formats: SS, MM:SS, HH:MM:SS, D-HH:MM:SS
+  const parts = etime.split('-');
+  let days = 0;
+  let timeStr = etime;
+
+  if (parts.length === 2) {
+    days = parseInt(parts[0]!, 10);
+    timeStr = parts[1]!;
+  }
+
+  const timeParts = timeStr.split(':').reverse();
+  let seconds = 0;
+
+  if (timeParts.length >= 1) seconds += parseInt(timeParts[0]!, 10);
+  if (timeParts.length >= 2) seconds += parseInt(timeParts[1]!, 10) * 60;
+  if (timeParts.length >= 3) seconds += parseInt(timeParts[2]!, 10) * 3600;
+  seconds += days * 86400;
+
+  return seconds * 1000;
+}
+
+/**
+ * Get accurate lane process status
+ */
+export function getLaneProcessStatus(lanePath: string, laneName: string): LaneProcessStatus {
+  const statePath = path.join(lanePath, 'state.json');
+  
+  const result: LaneProcessStatus = {
+    laneName,
+    pid: null,
+    processExists: false,
+    processRunning: false,
+    stateStatus: 'unknown',
+    actualStatus: 'unknown',
+    startTime: null,
+    endTime: null,
+    duration: 0,
+    isStale: false,
+  };
+
+  if (!fs.existsSync(statePath)) {
+    result.stateStatus = 'pending';
+    result.actualStatus = 'pending';
+    return result;
+  }
+
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    result.stateStatus = state.status || 'unknown';
+    result.pid = state.pid || null;
+    result.startTime = state.startTime || null;
+    result.endTime = state.endTime || null;
+
+    // Calculate duration
+    if (result.startTime) {
+      if (result.endTime) {
+        result.duration = result.endTime - result.startTime;
+      } else if (result.stateStatus === 'running' || result.stateStatus === 'reviewing') {
+        result.duration = Date.now() - result.startTime;
+      }
+    }
+
+    // Determine actual status based on process check
+    if (result.stateStatus === 'completed') {
+      result.actualStatus = 'completed';
+    } else if (result.stateStatus === 'failed') {
+      result.actualStatus = 'failed';
+    } else if (result.stateStatus === 'pending' || result.stateStatus === 'waiting') {
+      result.actualStatus = 'pending';
+    } else if (result.pid) {
+      // Check if process is actually running
+      const processInfo = checkProcess(result.pid);
+      result.processInfo = processInfo;
+      result.processExists = processInfo.exists;
+      result.processRunning = processInfo.isRunning;
+
+      if (processInfo.isRunning) {
+        result.actualStatus = 'running';
+      } else {
+        // Process is gone but state says running - stale state
+        result.actualStatus = 'dead';
+        result.isStale = true;
+      }
+    } else {
+      // No PID but state says running
+      if (result.stateStatus === 'running') {
+        result.actualStatus = 'dead';
+        result.isStale = true;
+      } else {
+        result.actualStatus = 'pending';
+      }
+    }
+  } catch {
+    result.actualStatus = 'unknown';
+  }
+
+  return result;
+}
+
+/**
+ * Get all lane process statuses for a run directory
+ */
+export function getAllLaneProcessStatuses(runDir: string): LaneProcessStatus[] {
+  const lanesDir = path.join(runDir, 'lanes');
+  if (!fs.existsSync(lanesDir)) return [];
+
+  const lanes = fs.readdirSync(lanesDir).filter(name => {
+    const dirPath = path.join(lanesDir, name);
+    return fs.statSync(dirPath).isDirectory();
+  });
+
+  return lanes.map(laneName => {
+    const lanePath = path.join(lanesDir, laneName);
+    return getLaneProcessStatus(lanePath, laneName);
+  });
+}
+
+/**
+ * Check if any flow process is alive
+ */
+export function isFlowAlive(runDir: string): boolean {
+  const statuses = getAllLaneProcessStatuses(runDir);
+  return statuses.some(s => s.actualStatus === 'running');
+}
+
+/**
+ * Get flow status summary
+ */
+export function getFlowSummary(runDir: string): {
+  total: number;
+  running: number;
+  completed: number;
+  failed: number;
+  pending: number;
+  dead: number;
+  isAlive: boolean;
+} {
+  const statuses = getAllLaneProcessStatuses(runDir);
+  
+  return {
+    total: statuses.length,
+    running: statuses.filter(s => s.actualStatus === 'running').length,
+    completed: statuses.filter(s => s.actualStatus === 'completed').length,
+    failed: statuses.filter(s => s.actualStatus === 'failed').length,
+    pending: statuses.filter(s => s.actualStatus === 'pending').length,
+    dead: statuses.filter(s => s.actualStatus === 'dead').length,
+    isAlive: statuses.some(s => s.actualStatus === 'running'),
+  };
+}
+
+/**
+ * Kill a lane process
+ */
+export function killLaneProcess(pid: number, signal: NodeJS.Signals = 'SIGTERM'): boolean {
+  try {
+    process.kill(pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+

package/src/types/agent.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent-related type definitions
+ */
+
+export interface DependencyPolicy {
+  allowDependencyChange: boolean;
+  lockfileReadOnly: boolean;
+}
+
+export interface DependencyRequestPlan {
+  reason: string;
+  changes: string[];
+  commands: string[];
+  notes?: string;
+}
+
+export interface AgentSendResult {
+  ok: boolean;
+  exitCode: number;
+  error?: string;
+  sessionId?: string;
+  resultText?: string;
+}
+

package/src/types/config.ts

@@ -0,0 +1,79 @@
+/**
+ * Configuration-related type definitions
+ */
+
+export interface LaneConfig {
+  devPort: number;
+  autoCreatePr: boolean;
+}
+
+export interface WebhookConfig {
+  enabled?: boolean;
+  url: string;
+  secret?: string;
+  events?: string[]; // ['*'] for all, ['task.*'] for wildcards
+  headers?: Record<string, string>;
+  retries?: number;
+  timeoutMs?: number;
+}
+
+export interface EnhancedLogConfig {
+  /** Enable enhanced logging features (default: true) */
+  enabled: boolean;
+  
+  /** Strip ANSI escape codes from clean logs (default: true) */
+  stripAnsi: boolean;
+  
+  /** Add timestamps to each line (default: true) */
+  addTimestamps: boolean;
+  
+  /** Maximum size in bytes before rotation (default: 50MB) */
+  maxFileSize: number;
+  
+  /** Number of rotated files to keep (default: 5) */
+  maxFiles: number;
+  
+  /** Write raw output with ANSI codes to separate file (default: true) */
+  keepRawLogs: boolean;
+  
+  /** Keep absolute raw logs without any processing */
+  keepAbsoluteRawLogs?: boolean;
+  
+  /** Write structured JSON log entries (default: true) */
+  writeJsonLog: boolean;
+  
+  /** Timestamp format: 'iso' | 'relative' | 'short' (default: 'iso') */
+  timestampFormat: 'iso' | 'relative' | 'short';
+  
+  /** Raw output mode */
+  raw?: boolean;
+}
+
+export interface CursorFlowConfig {
+  tasksDir: string;
+  logsDir: string;
+  pofDir: string;
+  /** Base branch (optional, auto-detected from current branch if not specified) */
+  baseBranch?: string;
+  branchPrefix: string;
+  executor: 'cursor-agent' | 'cloud';
+  pollInterval: number;
+  allowDependencyChange: boolean;
+  lockfileReadOnly: boolean;
+  enableReview: boolean;
+  reviewModel: string;
+  reviewAllTasks?: boolean;
+  maxReviewIterations: number;
+  defaultLaneConfig: LaneConfig;
+  logLevel: string;
+  verboseGit: boolean;
+  worktreePrefix: string;
+  maxConcurrentLanes: number;
+  projectRoot: string;
+  /** Output format for cursor-agent (default: 'stream-json') */
+  agentOutputFormat: 'stream-json' | 'json' | 'plain';
+  webhooks?: WebhookConfig[];
+  /** Enhanced logging configuration */
+  enhancedLogging?: Partial<EnhancedLogConfig>;
+}
+

package/src/types/events.ts

@@ -0,0 +1,156 @@
+/**
+ * Event-related type definitions
+ */
+
+import type { DependencyRequestPlan } from './agent';
+
+export interface CursorFlowEvent<T = Record<string, any>> {
+  id: string;
+  type: string;
+  timestamp: string;
+  runId: string;
+  payload: T;
+}
+
+export type EventHandler<T = any> = (event: CursorFlowEvent<T>) => void | Promise<void>;
+
+// Orchestration Events
+export interface OrchestrationStartedPayload {
+  runId: string;
+  tasksDir: string;
+  laneCount: number;
+  runRoot: string;
+}
+
+export interface OrchestrationCompletedPayload {
+  runId: string;
+  laneCount: number;
+  completedCount: number;
+  failedCount: number;
+}
+
+export interface OrchestrationFailedPayload {
+  error: string;
+  blockedLanes?: string[];
+}
+
+// Lane Events
+export interface LaneStartedPayload {
+  laneName: string;
+  pid?: number;
+  logPath: string;
+}
+
+export interface LaneCompletedPayload {
+  laneName: string;
+  exitCode: number;
+}
+
+export interface LaneFailedPayload {
+  laneName: string;
+  exitCode: number;
+  error: string;
+}
+
+export interface LaneDependencyRequestedPayload {
+  laneName: string;
+  dependencyRequest: DependencyRequestPlan;
+}
+
+// Task Events
+export interface TaskStartedPayload {
+  taskName: string;
+  taskBranch: string;
+  index: number;
+}
+
+export interface TaskCompletedPayload {
+  taskName: string;
+  taskBranch: string;
+  status: string;
+}
+
+export interface TaskFailedPayload {
+  taskName: string;
+  taskBranch: string;
+  error: string;
+}
+
+// Agent Events
+export interface AgentPromptSentPayload {
+  taskName: string;
+  model: string;
+  promptLength: number;
+}
+
+export interface AgentResponseReceivedPayload {
+  taskName: string;
+  ok: boolean;
+  duration: number;
+  responseLength: number;
+  error?: string;
+}
+
+// Review Events
+export interface ReviewStartedPayload {
+  taskName: string;
+  taskBranch: string;
+}
+
+export interface ReviewCompletedPayload {
+  taskName: string;
+  status: 'approved' | 'needs_changes';
+  issueCount: number;
+  summary: string;
+  raw: string;
+}
+
+export interface ReviewApprovedPayload {
+  taskName: string;
+  iterations: number;
+}
+
+export interface ReviewRejectedPayload {
+  taskName: string;
+  reason: string;
+  iterations: number;
+}
+
+// Recovery Events
+export interface RecoveryContinueSignalPayload {
+  laneName: string;
+  idleSeconds: number;
+  signalCount: number;
+}
+
+export interface RecoveryStrongerPromptPayload {
+  laneName: string;
+  prompt?: string;
+}
+
+export interface RecoveryRestartPayload {
+  laneName: string;
+  restartCount: number;
+  maxRestarts: number;
+}
+
+export interface RecoveryDiagnosedPayload {
+  laneName: string;
+  diagnostic: {
+    timestamp?: number;
+    agentHealthy: boolean;
+    authHealthy: boolean;
+    systemHealthy?: boolean;
+    suggestedAction?: string;
+    details?: string;
+    issues?: string[];
+  };
+}
+
+export interface RecoveryConflictResolutionPayload {
+  success: boolean;
+  strategy: string;
+  resolvedCount: number;
+  unresolvedCount: number;
+}
+

package/src/types/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Central type definitions for CursorFlow
+ * Re-exports all types from separate modules
+ */
+
+// Config
+export * from './config';
+
+// Lane
+export * from './lane';
+
+// Task
+export * from './task';
+
+// Agent
+export * from './agent';
+
+// Review
+export * from './review';
+
+// Events
+export * from './events';
+
+// Logging
+export * from './logging';
+
+// Run
+export * from './run';
+

package/src/types/lane.ts

@@ -0,0 +1,56 @@
+/**
+ * Lane-related type definitions
+ */
+
+import type { DependencyRequestPlan } from './agent';
+
+export type LaneStatus = 
+  | 'pending' 
+  | 'running' 
+  | 'completed' 
+  | 'failed' 
+  | 'paused' 
+  | 'waiting' 
+  | 'reviewing';
+
+export interface LaneInfo {
+  name: string;
+  status: string;
+  currentTask: number;
+  totalTasks: number;
+  pid?: number;
+  pipelineBranch?: string;
+}
+
+export interface LaneState {
+  label: string;
+  status: LaneStatus;
+  currentTaskIndex: number;
+  totalTasks: number;
+  worktreeDir: string | null;
+  pipelineBranch: string | null;
+  startTime: number;
+  endTime: number | null;
+  error: string | null;
+  dependencyRequest: DependencyRequestPlan | null;
+  updatedAt?: number;
+  tasksFile?: string; // Original tasks file path
+  dependsOn?: string[];
+  pid?: number;
+  /** List of completed task names in this lane */
+  completedTasks?: string[];
+  /** Task-level dependencies currently being waited for (format: "lane:task") */
+  waitingFor?: string[];
+  /** Chat session ID */
+  chatId?: string;
+}
+
+export interface LaneFileInfo {
+  fileName: string;
+  laneName: string;
+  preset: string;
+  taskCount: number;
+  taskFlow: string;
+  dependsOn: string[];
+}
+

package/src/types/logging.ts

@@ -0,0 +1,96 @@
+/**
+ * Logging-related type definitions
+ */
+
+export enum LogImportance {
+  CRITICAL = 'critical',
+  HIGH = 'high',
+  MEDIUM = 'medium',
+  LOW = 'low',
+  INFO = 'info',
+  DEBUG = 'debug'
+}
+
+export type MessageType = 
+  | 'system' 
+  | 'user' 
+  | 'assistant' 
+  | 'tool' 
+  | 'tool_result' 
+  | 'result' 
+  | 'thinking'
+  | 'success'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'stdout'
+  | 'stderr';
+
+export interface ParsedMessage {
+  type: MessageType;
+  role: string;
+  content: string;
+  timestamp: number;
+  metadata?: Record<string, any>;
+}
+
+export interface JsonLogEntry {
+  timestamp: string;
+  type?: string;
+  level?: 'stdout' | 'stderr' | 'info' | 'error' | 'debug' | 'session';
+  source?: string;
+  task?: string;
+  lane?: string;
+  message?: string;
+  content?: string;
+  raw?: string;
+  metadata?: Record<string, any>;
+  [key: string]: any;
+}
+
+export interface BufferedLogEntry {
+  id: number;
+  timestamp: Date;
+  laneName: string;
+  level: string;
+  type: MessageType | string;
+  message: string;
+  raw?: JsonLogEntry;
+  importance: LogImportance;
+  laneColor: string;
+  metadata?: Record<string, any>;
+}
+
+// Re-export EnhancedLogConfig from config.ts
+export type { EnhancedLogConfig } from './config';
+
+export interface LogSession {
+  id: string;
+  laneName: string;
+  taskName?: string;
+  model?: string;
+  startTime: number;
+  metadata?: Record<string, any>;
+}
+
+export interface ConversationEntry {
+  timestamp: string;
+  role: 'user' | 'assistant' | 'reviewer' | 'system' | 'intervention';
+  task: string | null;
+  fullText: string;
+  textLength: number;
+  model: string | null;
+}
+
+export interface GitLogEntry {
+  timestamp: string;
+  operation: string;
+  [key: string]: any;
+}
+
+export interface EventEntry {
+  timestamp: string;
+  event: string;
+  [key: string]: any;
+}
+