@ebowwa/workflows 0.1.0

package/src/scheduler.ts

@@ -0,0 +1,287 @@
+/**
+ * Job Scheduler with dependency resolution
+ *
+ * Handles job ordering, parallel execution where possible,
+ * and dependency graph management.
+ */
+
+import type { Job, JobRun, JobRunStatus, StepRunStatus } from './types.js';
+
+export interface JobNode {
+  id: string;
+  job: Job;
+  dependencies: string[];
+  dependents: string[];
+}
+
+export interface ExecutionPlan {
+  /** Jobs that can run in parallel, grouped by level */
+  levels: string[][];
+  /** Total number of jobs */
+  total: number;
+  /** Whether the graph has cycles */
+  hasCycles: boolean;
+}
+
+/**
+ * Build a dependency graph from jobs
+ */
+export function buildDependencyGraph(jobs: Record<string, Job>): Map<string, JobNode> {
+  const graph = new Map<string, JobNode>();
+
+  // Create nodes
+  for (const [id, job] of Object.entries(jobs)) {
+    graph.set(id, {
+      id,
+      job,
+      dependencies: job.needs ?? [],
+      dependents: [],
+    });
+  }
+
+  // Build reverse dependencies (dependents)
+  for (const [id, node] of graph) {
+    for (const depId of node.dependencies) {
+      const depNode = graph.get(depId);
+      if (depNode) {
+        depNode.dependents.push(id);
+      }
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Create an execution plan from jobs
+ * Groups jobs by dependency level for parallel execution
+ */
+export function createExecutionPlan(jobs: Record<string, Job>): ExecutionPlan {
+  const graph = buildDependencyGraph(jobs);
+  const levels: string[][] = [];
+  const visited = new Set<string>();
+  const inProgress = new Set<string>();
+
+  // Detect cycles using DFS
+  let hasCycles = false;
+  function detectCycles(nodeId: string, path: string[]): boolean {
+    if (path.includes(nodeId)) {
+      hasCycles = true;
+      return true;
+    }
+    if (visited.has(nodeId)) return false;
+
+    const node = graph.get(nodeId);
+    if (!node) return false;
+
+    path.push(nodeId);
+    for (const depId of node.dependencies) {
+      if (detectCycles(depId, [...path])) {
+        return true;
+      }
+    }
+    visited.add(nodeId);
+    return false;
+  }
+
+  // Check for cycles
+  for (const nodeId of graph.keys()) {
+    if (!visited.has(nodeId)) {
+      detectCycles(nodeId, []);
+    }
+  }
+
+  // Reset visited for level calculation
+  visited.clear();
+
+  // Calculate levels using topological sort
+  function getLevel(nodeId: string): number {
+    if (visited.has(nodeId)) {
+      return levels.findIndex(level => level.includes(nodeId));
+    }
+
+    const node = graph.get(nodeId);
+    if (!node) return 0;
+
+    // If no dependencies, level 0
+    if (node.dependencies.length === 0) {
+      return 0;
+    }
+
+    // Level = max(dependency levels) + 1
+    let maxDepLevel = -1;
+    for (const depId of node.dependencies) {
+      const depLevel = getLevel(depId);
+      maxDepLevel = Math.max(maxDepLevel, depLevel);
+    }
+
+    return maxDepLevel + 1;
+  }
+
+  // Group nodes by level
+  for (const nodeId of graph.keys()) {
+    const level = getLevel(nodeId);
+
+    while (levels.length <= level) {
+      levels.push([]);
+    }
+
+    levels[level].push(nodeId);
+    visited.add(nodeId);
+  }
+
+  return {
+    levels,
+    total: graph.size,
+    hasCycles,
+  };
+}
+
+/**
+ * Get jobs that are ready to run (all dependencies satisfied)
+ */
+export function getReadyJobs(
+  graph: Map<string, JobNode>,
+  completed: Set<string>,
+  running: Set<string>,
+  failed: Set<string>
+): string[] {
+  const ready: string[] = [];
+
+  for (const [id, node] of graph) {
+    // Skip if already completed, running, or failed
+    if (completed.has(id) || running.has(id) || failed.has(id)) {
+      continue;
+    }
+
+    // Check if all dependencies are satisfied
+    const depsSatisfied = node.dependencies.every(depId => completed.has(depId));
+    const depsFailed = node.dependencies.some(depId => failed.has(depId));
+
+    // If any dependency failed, this job should be skipped
+    if (depsFailed) {
+      // Mark as failed (will be skipped)
+      continue;
+    }
+
+    if (depsSatisfied) {
+      ready.push(id);
+    }
+  }
+
+  return ready;
+}
+
+/**
+ * Job Scheduler class
+ */
+export class JobScheduler {
+  private graph: Map<string, JobNode>;
+  private completed = new Set<string>();
+  private running = new Set<string>();
+  private failed = new Set<string>();
+  private skipped = new Set<string>();
+
+  constructor(jobs: Record<string, Job>) {
+    this.graph = buildDependencyGraph(jobs);
+  }
+
+  /**
+   * Get the execution plan
+   */
+  getPlan(): ExecutionPlan {
+    const jobs: Record<string, Job> = {};
+    for (const [id, node] of this.graph) {
+      jobs[id] = node.job;
+    }
+    return createExecutionPlan(jobs);
+  }
+
+  /**
+   * Get jobs ready to run
+   */
+  getReadyJobs(): string[] {
+    return getReadyJobs(this.graph, this.completed, this.running, this.failed);
+  }
+
+  /**
+   * Mark a job as started
+   */
+  startJob(jobId: string): void {
+    this.running.add(jobId);
+  }
+
+  /**
+   * Mark a job as completed
+   */
+  completeJob(jobId: string, success: boolean): void {
+    this.running.delete(jobId);
+
+    if (success) {
+      this.completed.add(jobId);
+    } else {
+      this.failed.add(jobId);
+    }
+  }
+
+  /**
+   * Skip a job (due to failed dependencies)
+   */
+  skipJob(jobId: string): void {
+    this.skipped.add(jobId);
+  }
+
+  /**
+   * Check if all jobs are done
+   */
+  isComplete(): boolean {
+    const total = this.graph.size;
+    const done = this.completed.size + this.failed.size + this.skipped.size;
+    return done === total;
+  }
+
+  /**
+   * Get status summary
+   */
+  getStatus(): {
+    total: number;
+    completed: number;
+    running: number;
+    failed: number;
+    skipped: number;
+    pending: number;
+  } {
+    const total = this.graph.size;
+    const pending = total - this.completed.size - this.running.size - this.failed.size - this.skipped.size;
+
+    return {
+      total,
+      completed: this.completed.size,
+      running: this.running.size,
+      failed: this.failed.size,
+      skipped: this.skipped.size,
+      pending,
+    };
+  }
+
+  /**
+   * Get job by ID
+   */
+  getJob(jobId: string): Job | undefined {
+    return this.graph.get(jobId)?.job;
+  }
+
+  /**
+   * Get all job IDs
+   */
+  getJobIds(): string[] {
+    return Array.from(this.graph.keys());
+  }
+
+  /**
+   * Check for cycles in the dependency graph
+   */
+  hasCycles(): boolean {
+    return this.getPlan().hasCycles;
+  }
+}

package/src/types.ts

@@ -0,0 +1,218 @@
+/**
+ * Core types for CI/CD Workflow System
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Trigger Types
+// ============================================================================
+
+export const TriggerSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('manual') }),
+  z.object({ type: z.literal('schedule'), cron: z.string() }),
+  z.object({ type: z.literal('webhook'), path: z.string() }),
+  z.object({ type: z.literal('git'), events: z.array(z.enum(['push', 'pr', 'merge'])) }),
+]);
+
+export type Trigger = z.infer<typeof TriggerSchema>;
+
+// ============================================================================
+// Step Types
+// ============================================================================
+
+export const StepSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  run: z.string(),
+  cwd: z.string().optional(),
+  env: z.record(z.string()).optional(),
+  condition: z.string().optional(),  // Expression for conditional execution
+  retry: z.number().optional(),
+  timeout: z.number().optional(),
+});
+
+export type Step = z.infer<typeof StepSchema>;
+
+// ============================================================================
+// Job Types
+// ============================================================================
+
+export const JobSchema = z.object({
+  name: z.string(),
+  runsOn: z.enum(['bun', 'tsx', 'rust', 'bash']),
+  steps: z.array(StepSchema),
+  needs: z.array(z.string()).optional(),  // Job dependencies
+  env: z.record(z.string()).optional(),
+  timeout: z.number().optional(),
+});
+
+export type Job = z.infer<typeof JobSchema>;
+
+// ============================================================================
+// Workflow Types
+// ============================================================================
+
+export const WorkflowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  triggers: z.array(TriggerSchema),
+  jobs: z.record(z.string(), JobSchema),
+  env: z.record(z.string()).optional(),
+});
+
+export type Workflow = z.infer<typeof WorkflowSchema>;
+
+// ============================================================================
+// Run Types (Execution State)
+// ============================================================================
+
+export const StepRunStatusSchema = z.enum(['pending', 'running', 'success', 'failed', 'skipped']);
+export type StepRunStatus = z.infer<typeof StepRunStatusSchema>;
+
+export const JobRunStatusSchema = z.enum(['pending', 'running', 'success', 'failed', 'skipped', 'cancelled']);
+export type JobRunStatus = z.infer<typeof JobRunStatusSchema>;
+
+export const WorkflowRunStatusSchema = z.enum(['pending', 'running', 'success', 'failed', 'cancelled']);
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+
+export const StepRunSchema = z.object({
+  id: z.string(),
+  stepId: z.string(),
+  status: StepRunStatusSchema,
+  exitCode: z.number().optional(),
+  duration: z.number().optional(),
+  startedAt: z.date().optional(),
+  finishedAt: z.date().optional(),
+});
+
+export type StepRun = z.infer<typeof StepRunSchema>;
+
+export const LogEntrySchema = z.object({
+  timestamp: z.date(),
+  jobId: z.string(),
+  stepId: z.string(),
+  stream: z.enum(['stdout', 'stderr']),
+  content: z.string(),
+});
+
+export type LogEntry = z.infer<typeof LogEntrySchema>;
+
+export const JobRunSchema = z.object({
+  id: z.string(),
+  jobId: z.string(),
+  status: JobRunStatusSchema,
+  steps: z.array(StepRunSchema),
+  logs: z.array(LogEntrySchema).optional(),
+  startedAt: z.date().optional(),
+  finishedAt: z.date().optional(),
+});
+
+export type JobRun = z.infer<typeof JobRunSchema>;
+
+export const WorkflowRunSchema = z.object({
+  id: z.string(),
+  workflowId: z.string(),
+  status: WorkflowRunStatusSchema,
+  trigger: TriggerSchema,
+  jobs: z.record(z.string(), JobRunSchema),
+  startedAt: z.date(),
+  finishedAt: z.date().optional(),
+  env: z.record(z.string()).optional(),
+});
+
+export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
+
+// ============================================================================
+// Execution Context Types
+// ============================================================================
+
+export interface StepContext {
+  workspace: string;
+  env: Record<string, string>;
+  jobId: string;
+  stepIndex: number;
+  runId: string;
+}
+
+export interface JobContext {
+  workspace: string;
+  env: Record<string, string>;
+  runId: string;
+  jobId: string;
+}
+
+export interface StepResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  duration: number;
+  succeeded: boolean;
+}
+
+// ============================================================================
+// WebSocket Message Types
+// ============================================================================
+
+export const ServerMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('job_started'), jobId: z.string() }),
+  z.object({ type: z.literal('step_started'), jobId: z.string(), stepId: z.string() }),
+  z.object({ type: z.literal('log'), jobId: z.string(), stepId: z.string(), content: z.string(), stream: z.enum(['stdout', 'stderr']) }),
+  z.object({ type: z.literal('step_finished'), jobId: z.string(), stepId: z.string(), exitCode: z.number(), duration: z.number() }),
+  z.object({ type: z.literal('job_finished'), jobId: z.string(), status: z.string() }),
+  z.object({ type: z.literal('workflow_finished'), status: z.string() }),
+]);
+
+export type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+export const ClientMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('subscribe'), runId: z.string() }),
+  z.object({ type: z.literal('cancel') }),
+]);
+
+export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+
+// ============================================================================
+// Event Emitter Types
+// ============================================================================
+
+export type WorkflowEventType =
+  | 'workflow:started'
+  | 'workflow:finished'
+  | 'job:started'
+  | 'job:finished'
+  | 'step:started'
+  | 'step:log'
+  | 'step:finished';
+
+export interface WorkflowEvent {
+  type: WorkflowEventType;
+  runId: string;
+  jobId?: string;
+  stepId?: string;
+  data?: unknown;
+}
+
+// ============================================================================
+// API Types
+// ============================================================================
+
+export interface CreateWorkflowRequest {
+  workflow: Workflow;
+}
+
+export interface TriggerWorkflowRequest {
+  trigger?: Trigger;
+  env?: Record<string, string>;
+}
+
+export interface WorkflowListResponse {
+  workflows: Workflow[];
+  total: number;
+}
+
+export interface RunListResponse {
+  runs: WorkflowRun[];
+  total: number;
+}