@ebowwa/workflows 0.1.0

package/src/runner.ts

@@ -0,0 +1,308 @@
+/**
+ * Workflow Runner - Execution Engine
+ *
+ * Orchestrates workflow execution with job scheduling,
+ * step execution, and event emission for real-time updates.
+ */
+
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import type {
+  Workflow,
+  WorkflowRun,
+  JobRun,
+  StepRun,
+  Trigger,
+  WorkflowEvent,
+  WorkflowRunStatus,
+  JobRunStatus,
+  StepRunStatus,
+  LogEntry,
+} from './types.js';
+import { ProcessSandbox, evaluateCondition } from './sandbox.js';
+import { JobScheduler } from './scheduler.js';
+
+export interface RunnerOptions {
+  /** Default workspace directory */
+  workspace?: string;
+  /** Default environment variables */
+  env?: Record<string, string>;
+  /** Maximum concurrent jobs */
+  maxConcurrentJobs?: number;
+}
+
+export interface RunOptions {
+  /** Trigger that initiated this run */
+  trigger?: Trigger;
+  /** Environment variables for this run */
+  env?: Record<string, string>;
+  /** Workspace override */
+  workspace?: string;
+  /** Pre-generated run ID (optional) */
+  runId?: string;
+}
+
+/**
+ * Workflow Runner - executes workflows with process isolation
+ */
+export class WorkflowRunner extends EventEmitter {
+  private sandbox: ProcessSandbox;
+  private workspace: string;
+  private env: Record<string, string>;
+  private maxConcurrentJobs: number;
+  private activeRuns = new Map<string, { cancelled: boolean }>();
+
+  constructor(options: RunnerOptions = {}) {
+    super();
+    this.workspace = options.workspace ?? process.cwd();
+    this.env = options.env ?? {};
+    this.maxConcurrentJobs = options.maxConcurrentJobs ?? 4;
+
+    // Create sandbox with log forwarding
+    this.sandbox = new ProcessSandbox({
+      onLog: (entry) => this.emitLog(entry),
+    });
+  }
+
+  /**
+   * Run a workflow
+   */
+  async runWorkflow(workflow: Workflow, options: RunOptions = {}): Promise<WorkflowRun> {
+    const runId = options.runId ?? randomUUID();
+    const trigger: Trigger = options.trigger ?? { type: 'manual' };
+    const workspace = options.workspace ?? this.workspace;
+    const env = { ...this.env, ...workflow.env, ...options.env };
+
+    // Track this run
+    this.activeRuns.set(runId, { cancelled: false });
+
+    // Initialize run state
+    const run: WorkflowRun = {
+      id: runId,
+      workflowId: workflow.id,
+      status: 'pending',
+      trigger,
+      jobs: {},
+      startedAt: new Date(),
+      env,
+    };
+
+    // Initialize job runs
+    const scheduler = new JobScheduler(workflow.jobs);
+
+    for (const jobId of scheduler.getJobIds()) {
+      const job = workflow.jobs[jobId];
+      run.jobs[jobId] = {
+        id: randomUUID(),
+        jobId,
+        status: 'pending',
+        steps: job.steps.map((step, index) => ({
+          id: step.id ?? `step-${index}`,
+          stepId: step.id ?? `step-${index}`,
+          status: 'pending' as StepRunStatus,
+        })),
+      };
+    }
+
+    // Check for cycles
+    if (scheduler.hasCycles()) {
+      run.status = 'failed';
+      run.finishedAt = new Date();
+      this.activeRuns.delete(runId);
+      return run;
+    }
+
+    // Emit workflow started
+    this.emitEvent('workflow:started', runId);
+
+    // Start execution
+    run.status = 'running';
+
+    try {
+      await this.executeJobs(workflow, run, scheduler, workspace, env);
+    } catch (error) {
+      run.status = 'failed';
+    }
+
+    // Determine final status
+    if (this.activeRuns.get(runId)?.cancelled) {
+      run.status = 'cancelled';
+    } else {
+      const allSuccess = Object.values(run.jobs).every(j => j.status === 'success');
+      const anyFailed = Object.values(run.jobs).some(j => j.status === 'failed');
+      run.status = anyFailed ? 'failed' : allSuccess ? 'success' : 'cancelled';
+    }
+
+    run.finishedAt = new Date();
+
+    // Emit workflow finished
+    this.emitEvent('workflow:finished', runId, { status: run.status });
+
+    this.activeRuns.delete(runId);
+    return run;
+  }
+
+  private async executeJobs(
+    workflow: Workflow,
+    run: WorkflowRun,
+    scheduler: JobScheduler,
+    workspace: string,
+    env: Record<string, string>
+  ): Promise<void> {
+    const runState = this.activeRuns.get(run.id);
+    if (!runState) return;
+
+    // Execute jobs in waves based on dependencies
+    while (!scheduler.isComplete() && !runState.cancelled) {
+      // Get jobs ready to run
+      const readyJobs = scheduler.getReadyJobs();
+
+      if (readyJobs.length === 0) {
+        // No jobs ready - either all done or deadlock
+        break;
+      }
+
+      // Execute ready jobs (up to max concurrent)
+      const toExecute = readyJobs.slice(0, this.maxConcurrentJobs);
+
+      await Promise.all(
+        toExecute.map(jobId => this.executeJob(workflow, run, jobId, scheduler, workspace, env))
+      );
+    }
+  }
+
+  private async executeJob(
+    workflow: Workflow,
+    run: WorkflowRun,
+    jobId: string,
+    scheduler: JobScheduler,
+    workspace: string,
+    env: Record<string, string>
+  ): Promise<void> {
+    const runState = this.activeRuns.get(run.id);
+    if (!runState || runState.cancelled) return;
+
+    const job = workflow.jobs[jobId];
+    const jobRun = run.jobs[jobId];
+
+    if (!job || !jobRun) return;
+
+    // Check if dependencies failed
+    const depsFailed = (job.needs ?? []).some(depId => run.jobs[depId]?.status === 'failed');
+    if (depsFailed) {
+      jobRun.status = 'skipped';
+      scheduler.skipJob(jobId);
+      return;
+    }
+
+    // Mark as started
+    scheduler.startJob(jobId);
+    jobRun.status = 'running';
+    jobRun.startedAt = new Date();
+
+    this.emitEvent('job:started', run.id, { jobId });
+
+    // Execute steps
+    let allStepsSuccess = true;
+    const previousSteps: { succeeded: boolean }[] = [];
+
+    for (let i = 0; i < job.steps.length; i++) {
+      if (runState.cancelled) {
+        jobRun.status = 'cancelled';
+        break;
+      }
+
+      const step = job.steps[i];
+      const stepRun = jobRun.steps[i];
+
+      // Evaluate condition
+      const shouldRun = evaluateCondition(step.condition, { previousSteps });
+
+      if (!shouldRun) {
+        stepRun.status = 'skipped';
+        previousSteps.push({ succeeded: true }); // Skipped counts as success for subsequent conditions
+        continue;
+      }
+
+      // Execute step
+      stepRun.status = 'running';
+      stepRun.startedAt = new Date();
+
+      this.emitEvent('step:started', run.id, { jobId, stepId: stepRun.stepId });
+
+      const result = await this.sandbox.executeStep(step, {
+        workspace,
+        env: { ...env, ...job.env },
+        jobId,
+        stepIndex: i,
+        runId: run.id,
+      });
+
+      stepRun.exitCode = result.exitCode;
+      stepRun.duration = result.duration;
+      stepRun.status = result.succeeded ? 'success' : 'failed';
+      stepRun.finishedAt = new Date();
+
+      this.emitEvent('step:finished', run.id, {
+        jobId,
+        stepId: stepRun.stepId,
+        data: { exitCode: result.exitCode, duration: result.duration },
+      });
+
+      previousSteps.push({ succeeded: result.succeeded });
+
+      if (!result.succeeded) {
+        allStepsSuccess = false;
+        break; // Stop on first failure
+      }
+    }
+
+    // Mark job as complete
+    jobRun.status = allStepsSuccess ? 'success' : 'failed';
+    jobRun.finishedAt = new Date();
+    scheduler.completeJob(jobId, allStepsSuccess);
+
+    this.emitEvent('job:finished', run.id, { jobId, data: { status: jobRun.status } });
+  }
+
+  /**
+   * Cancel a running workflow
+   */
+  cancelRun(runId: string): boolean {
+    const runState = this.activeRuns.get(runId);
+    if (!runState) return false;
+
+    runState.cancelled = true;
+    this.sandbox.cancelRun(runId);
+    return true;
+  }
+
+  /**
+   * Check if a run is active
+   */
+  isRunActive(runId: string): boolean {
+    return this.activeRuns.has(runId);
+  }
+
+  /**
+   * Get all active run IDs
+   */
+  getActiveRuns(): string[] {
+    return Array.from(this.activeRuns.keys());
+  }
+
+  private emitEvent(type: WorkflowEvent['type'], runId: string, data?: unknown): void {
+    this.emit('event', { type, runId, data } as WorkflowEvent);
+  }
+
+  private emitLog(entry: LogEntry): void {
+    this.emit('log', entry);
+  }
+}
+
+/**
+ * Create a workflow runner
+ */
+export function createRunner(options?: RunnerOptions): WorkflowRunner {
+  return new WorkflowRunner(options);
+}

package/src/sandbox.ts

@@ -0,0 +1,305 @@
+/**
+ * Process-level isolation for step execution
+ *
+ * Provides secure execution of workflow steps with process isolation,
+ * timeout handling, retry logic, and real-time log streaming.
+ */
+
+import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
+import type { Step, StepContext, StepResult, LogEntry } from './types.js';
+
+export interface SandboxOptions {
+  /** Default timeout for steps (ms) */
+  defaultTimeout?: number;
+  /** Default retry count */
+  defaultRetry?: number;
+  /** Log callback for real-time streaming */
+  onLog?: (entry: LogEntry) => void;
+}
+
+export interface ActiveProcess {
+  pid: number;
+  jobId: string;
+  stepId: string;
+  process: ChildProcess;
+  cancelled: boolean;
+}
+
+/**
+ * Process Sandbox for isolated step execution
+ */
+export class ProcessSandbox {
+  private activeProcesses = new Map<string, ActiveProcess>();
+  private defaultTimeout: number;
+  private defaultRetry: number;
+  private onLog?: (entry: LogEntry) => void;
+
+  constructor(options: SandboxOptions = {}) {
+    this.defaultTimeout = options.defaultTimeout ?? 300000; // 5 minutes default
+    this.defaultRetry = options.defaultRetry ?? 0;
+    this.onLog = options.onLog;
+  }
+
+  /**
+   * Execute a step in an isolated process
+   */
+  async executeStep(
+    step: Step,
+    context: StepContext
+  ): Promise<StepResult> {
+    const stepId = step.id ?? `step-${context.stepIndex}`;
+    const timeout = step.timeout ?? this.defaultTimeout;
+    const maxRetries = step.retry ?? this.defaultRetry;
+
+    let lastResult: StepResult = {
+      exitCode: 1,
+      stdout: '',
+      stderr: '',
+      duration: 0,
+      succeeded: false,
+    };
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      lastResult = await this.executeStepOnce(step, context, stepId, timeout);
+
+      if (lastResult.succeeded) {
+        return lastResult;
+      }
+
+      // Log retry attempt
+      if (attempt < maxRetries) {
+        this.emitLog({
+          timestamp: new Date(),
+          jobId: context.jobId,
+          stepId,
+          stream: 'stderr',
+          content: `[RETRY] Attempt ${attempt + 1}/${maxRetries} failed, retrying...\n`,
+        });
+      }
+    }
+
+    return lastResult;
+  }
+
+  private async executeStepOnce(
+    step: Step,
+    context: StepContext,
+    stepId: string,
+    timeout: number
+  ): Promise<StepResult> {
+    const startTime = Date.now();
+    const processKey = `${context.runId}:${context.jobId}:${stepId}`;
+
+    return new Promise((resolve) => {
+      let stdout = '';
+      let stderr = '';
+      let cancelled = false;
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+      // Determine shell based on runs-on (from job context, default to bash)
+      const shell = process.env.SHELL ?? '/bin/bash';
+
+      // Merge environment variables
+      const env = {
+        ...process.env,
+        ...context.env,
+        ...step.env,
+        // Add workflow context variables
+        WORKFLOW_RUN_ID: context.runId,
+        WORKFLOW_JOB_ID: context.jobId,
+        WORKFLOW_STEP_ID: stepId,
+        WORKFLOW_WORKSPACE: context.workspace,
+      };
+
+      // Spawn process with isolation
+      const proc = spawn(step.run, [], {
+        cwd: step.cwd ?? context.workspace,
+        env,
+        shell,
+        detached: false, // Process-level isolation (not process group)
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      // Track active process
+      const activeProcess: ActiveProcess = {
+        pid: proc.pid ?? 0,
+        jobId: context.jobId,
+        stepId,
+        process: proc,
+        cancelled: false,
+      };
+      this.activeProcesses.set(processKey, activeProcess);
+
+      // Set timeout
+      timeoutId = setTimeout(() => {
+        cancelled = true;
+        this.emitLog({
+          timestamp: new Date(),
+          jobId: context.jobId,
+          stepId,
+          stream: 'stderr',
+          content: `[TIMEOUT] Step exceeded ${timeout}ms, terminating...\n`,
+        });
+        this.killProcess(proc, processKey);
+      }, timeout);
+
+      // Stream stdout
+      if (proc.stdout) {
+        proc.stdout.on('data', (data: Buffer) => {
+          const content = data.toString();
+          stdout += content;
+          this.emitLog({
+            timestamp: new Date(),
+            jobId: context.jobId,
+            stepId,
+            stream: 'stdout',
+            content,
+          });
+        });
+      }
+
+      // Stream stderr
+      if (proc.stderr) {
+        proc.stderr.on('data', (data: Buffer) => {
+          const content = data.toString();
+          stderr += content;
+          this.emitLog({
+            timestamp: new Date(),
+            jobId: context.jobId,
+            stepId,
+            stream: 'stderr',
+            content,
+          });
+        });
+      }
+
+      // Handle process completion
+      proc.on('close', (code) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        this.activeProcesses.delete(processKey);
+
+        const duration = Date.now() - startTime;
+        const exitCode = code ?? (cancelled ? 137 : 1);
+        const succeeded = exitCode === 0;
+
+        resolve({
+          exitCode,
+          stdout,
+          stderr,
+          duration,
+          succeeded,
+        });
+      });
+
+      // Handle process errors
+      proc.on('error', (err) => {
+        if (timeoutId) clearTimeout(timeoutId);
+        this.activeProcesses.delete(processKey);
+
+        const duration = Date.now() - startTime;
+        stderr += `Process error: ${err.message}\n`;
+
+        resolve({
+          exitCode: 1,
+          stdout,
+          stderr,
+          duration,
+          succeeded: false,
+        });
+      });
+    });
+  }
+
+  /**
+   * Cancel a running step
+   */
+  cancelStep(runId: string, jobId: string, stepId: string): boolean {
+    const processKey = `${runId}:${jobId}:${stepId}`;
+    const active = this.activeProcesses.get(processKey);
+
+    if (active) {
+      active.cancelled = true;
+      this.killProcess(active.process, processKey);
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Cancel all steps for a run
+   */
+  cancelRun(runId: string): number {
+    let cancelled = 0;
+
+    for (const [key, active] of this.activeProcesses) {
+      if (key.startsWith(`${runId}:`)) {
+        active.cancelled = true;
+        this.killProcess(active.process, key);
+        cancelled++;
+      }
+    }
+
+    return cancelled;
+  }
+
+  /**
+   * Get all active processes
+   */
+  getActiveProcesses(): ActiveProcess[] {
+    return Array.from(this.activeProcesses.values());
+  }
+
+  private killProcess(proc: ChildProcess, key: string): void {
+    try {
+      // Try graceful termination first
+      proc.kill('SIGTERM');
+
+      // Force kill after 5 seconds
+      setTimeout(() => {
+        if (this.activeProcesses.has(key)) {
+          proc.kill('SIGKILL');
+        }
+      }, 5000);
+    } catch {
+      // Process may already be dead
+    }
+  }
+
+  private emitLog(entry: LogEntry): void {
+    if (this.onLog) {
+      this.onLog(entry);
+    }
+  }
+}
+
+/**
+ * Evaluate a condition expression
+ * Supports simple expressions like "success()", "failure()", "always()"
+ * and basic comparisons
+ */
+export function evaluateCondition(
+  condition: string | undefined,
+  context: { previousSteps: { succeeded: boolean }[] }
+): boolean {
+  if (!condition) return true;
+
+  const expr = condition.trim().toLowerCase();
+
+  // Built-in functions
+  if (expr === 'always()') return true;
+  if (expr === 'success()') return context.previousSteps.every(s => s.succeeded);
+  if (expr === 'failure()') return context.previousSteps.some(s => !s.succeeded);
+
+  // Basic comparison (env vars, etc.) - could be extended
+  // For now, just return true for unknown expressions
+  return true;
+}
+
+/**
+ * Create a sandbox instance with log streaming
+ */
+export function createSandbox(onLog?: (entry: LogEntry) => void): ProcessSandbox {
+  return new ProcessSandbox({ onLog });
+}