@calmo/task-runner 1.2.1 → 1.2.3

package/dist/TaskRunner.d.ts

@@ -1,33 +1,7 @@
 import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
-/**
- * Define the payload for every possible event in the lifecycle.
- */
-export interface RunnerEventPayloads<TContext> {
-    workflowStart: {
-        context: TContext;
-        steps: TaskStep<TContext>[];
-    };
-    workflowEnd: {
-        context: TContext;
-        results: Map<string, TaskResult>;
-    };
-    taskStart: {
-        step: TaskStep<TContext>;
-    };
-    taskEnd: {
-        step: TaskStep<TContext>;
-        result: TaskResult;
-    };
-    taskSkipped: {
-        step: TaskStep<TContext>;
-        result: TaskResult;
-    };
-}
-/**
- * A generic listener type that maps the event key to its specific payload.
- */
-export type RunnerEventListener<TContext, K extends keyof RunnerEventPayloads<TContext>> = (data: RunnerEventPayloads<TContext>[K]) => void | Promise<void>;
+import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+export { RunnerEventPayloads, RunnerEventListener };
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -35,8 +9,7 @@ export type RunnerEventListener<TContext, K extends keyof RunnerEventPayloads<TC
  */
 export declare class TaskRunner<TContext> {
     private context;
-    private running;
-    private listeners;
+    private eventBus;
     private validator;
     /**
      * @param context The shared context object to be passed to each task.
@@ -54,12 +27,6 @@ export declare class TaskRunner<TContext> {
      * @param callback The callback to remove.
      */
     off<K extends keyof RunnerEventPayloads<TContext>>(event: K, callback: RunnerEventListener<TContext, K>): void;
-    /**
-     * Emit an event to all subscribers.
-     * @param event The event name.
-     * @param data The payload for the event.
-     */
-    private emit;
     /**
      * Executes a list of tasks, respecting their dependencies and running
      * independent tasks in parallel.

package/dist/TaskRunner.js

@@ -1,4 +1,6 @@
 import { TaskGraphValidator } from "./TaskGraphValidator.js";
+import { EventBus } from "./EventBus.js";
+import { WorkflowExecutor } from "./WorkflowExecutor.js";
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -6,8 +8,7 @@ import { TaskGraphValidator } from "./TaskGraphValidator.js";
  */
 export class TaskRunner {
     context;
-    running = new Set();
-    listeners = {};
+    eventBus = new EventBus();
     validator = new TaskGraphValidator();
     /**
      * @param context The shared context object to be passed to each task.
@@ -21,13 +22,7 @@ export class TaskRunner {
      * @param callback The callback to execute when the event is emitted.
      */
     on(event, callback) {
-        if (!this.listeners[event]) {
-            // Type assertion needed because TypeScript cannot verify that the generic K
-            // matches the specific key in the mapped type during assignment.
-            this.listeners[event] = new Set();
-        }
-        // Type assertion needed to tell TS that this specific Set matches the callback type
-        this.listeners[event].add(callback);
+        this.eventBus.on(event, callback);
     }
     /**
      * Unsubscribe from an event.
@@ -35,28 +30,7 @@ export class TaskRunner {
      * @param callback The callback to remove.
      */
     off(event, callback) {
-        if (this.listeners[event]) {
-            this.listeners[event].delete(callback);
-        }
-    }
-    /**
-     * Emit an event to all subscribers.
-     * @param event The event name.
-     * @param data The payload for the event.
-     */
-    emit(event, data) {
-        const listeners = this.listeners[event];
-        if (listeners) {
-            for (const listener of listeners) {
-                try {
-                    listener(data);
-                }
-                catch (error) {
-                    // Prevent listener errors from bubbling up
-                    console.error(`Error in event listener for ${String(event)}:`, error);
-                }
-            }
-        }
+        this.eventBus.off(event, callback);
     }
     /**
      * Executes a list of tasks, respecting their dependencies and running
@@ -75,103 +49,10 @@ export class TaskRunner {
         };
         const validationResult = this.validator.validate(taskGraph);
         if (!validationResult.isValid) {
-            // Construct error message compatible with legacy tests
-            const affectedTasks = new Set();
-            const errorDetails = [];
-            for (const error of validationResult.errors) {
-                errorDetails.push(error.message);
-                switch (error.type) {
-                    case "cycle": {
-                        // details is { cyclePath: string[] }
-                        const path = error.details.cyclePath;
-                        // The last element duplicates the first in the path representation, so valid unique tasks are slice(0, -1) or just all as Set handles uniq
-                        path.forEach((t) => affectedTasks.add(t));
-                        break;
-                    }
-                    case "missing_dependency": {
-                        // details is { taskId: string, missingDependencyId: string }
-                        const d = error.details;
-                        affectedTasks.add(d.taskId);
-                        break;
-                    }
-                    case "duplicate_task": {
-                        const d = error.details;
-                        affectedTasks.add(d.taskId);
-                        break;
-                    }
-                }
-            }
-            // Legacy error format: "Circular dependency or missing dependency detected. Unable to run tasks: A, B"
-            const taskList = Array.from(affectedTasks).join(", ");
-            const legacyMessage = `Circular dependency or missing dependency detected. Unable to run tasks: ${taskList}`;
-            const detailedMessage = `Task graph validation failed: ${errorDetails.join("; ")}`;
-            // Combine them to satisfy both legacy tests (checking for legacy message) and new requirements (clear details)
-            throw new Error(`${legacyMessage} | ${detailedMessage}`);
-        }
-        this.emit("workflowStart", { context: this.context, steps });
-        const results = new Map();
-        const executingPromises = new Set();
-        // Helper to process pending steps and launch ready ones
-        const processPendingSteps = () => {
-            const pendingSteps = steps.filter((step) => !results.has(step.name) && !this.running.has(step.name));
-            // 1. Identify and mark skipped tasks
-            for (const step of pendingSteps) {
-                const deps = step.dependencies ?? [];
-                const failedDep = deps.find((dep) => results.has(dep) && results.get(dep)?.status !== "success");
-                if (failedDep) {
-                    const result = {
-                        status: "skipped",
-                        message: `Skipped due to failed dependency: ${failedDep}`,
-                    };
-                    results.set(step.name, result);
-                    this.emit("taskSkipped", { step, result });
-                }
-            }
-            // Re-filter pending steps as some might have been skipped above
-            const readySteps = steps.filter((step) => {
-                if (results.has(step.name) || this.running.has(step.name))
-                    return false;
-                const deps = step.dependencies ?? [];
-                return deps.every((dep) => results.has(dep) && results.get(dep)?.status === "success");
-            });
-            // 2. Launch ready tasks
-            for (const step of readySteps) {
-                this.running.add(step.name);
-                this.emit("taskStart", { step });
-                const taskPromise = (async () => {
-                    try {
-                        const result = await step.run(this.context);
-                        results.set(step.name, result);
-                    }
-                    catch (e) {
-                        results.set(step.name, {
-                            status: "failure",
-                            error: e instanceof Error ? e.message : String(e),
-                        });
-                    }
-                    finally {
-                        this.running.delete(step.name);
-                        const result = results.get(step.name);
-                        this.emit("taskEnd", { step, result });
-                    }
-                })();
-                // Wrap the task promise to ensure we can track it in the Set
-                const trackedPromise = taskPromise.then(() => {
-                    executingPromises.delete(trackedPromise);
-                });
-                executingPromises.add(trackedPromise);
-            }
-        };
-        // Initial check to start independent tasks
-        processPendingSteps();
-        while (results.size < steps.length && executingPromises.size > 0) {
-            // Wait for the next task to finish
-            await Promise.race(executingPromises);
-            // After a task finishes, check for new work
-            processPendingSteps();
+            throw new Error(this.validator.createErrorMessage(validationResult));
         }
-        this.emit("workflowEnd", { context: this.context, results });
-        return results;
+        const executor = new WorkflowExecutor(this.context, this.eventBus);
+        return executor.execute(steps);
     }
 }
 //# sourceMappingURL=TaskRunner.js.map

package/dist/TaskRunner.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskRunner.js","sourceRoot":"","sources":["../src/TaskRunner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AA6C7D;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAQD;IAPZ,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5B,SAAS,GAA0B,EAAE,CAAC;IACtC,SAAS,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAE7C;;OAEG;IACH,YAAoB,OAAiB;QAAjB,YAAO,GAAP,OAAO,CAAU;IAAG,CAAC;IAEzC;;;;OAIG;IACI,EAAE,CACP,KAAQ,EACR,QAA0C;QAE1C,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,4EAA4E;YAC5E,iEAAiE;YACjE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,EAAyC,CAAC;QAC3E,CAAC;QACD,oFAAoF;QACnF,IAAI,CAAC,SAAS,CAAC,KAAK,CAA2C,CAAC,GAAG,CAClE,QAAQ,CACT,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACI,GAAG,CACR,KAAQ,EACR,QAA0C;QAE1C,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,CAAC,KAAK,CAA2C,CAAC,MAAM,CACrE,QAAQ,CACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;OAIG;IACK,IAAI,CACV,KAAQ,EACR,IAAsC;QAEtC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAEzB,CAAC;QACd,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACH,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACjB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,2CAA2C;oBAC3C,OAAO,CAAC,KAAK,CACX,+BAA+B,MAAM,CAAC,KAAK,CAAC,GAAG,EAC/C,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAA2B;QACvC,2CAA2C;QAC3C,MAAM,SAAS,GAAc;YAC3B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC1B,EAAE,EAAE,IAAI,CAAC,IAAI;gBACb,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;aACtC,CAAC,CAAC;SACJ,CAAC;QAEF,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;YAC9B,uDAAuD;YACvD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;YACxC,MAAM,YAAY,GAAa,EAAE,CAAC;YAElC,KAAK,MAAM,KAAK,IAAI,gBAAgB,CAAC,MAAM,EAAE,CAAC;gBAC5C,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACnB,KAAK,OAAO,CAAC,CAAC,CAAC;wBACb,qCAAqC;wBACrC,MAAM,IAAI,GAAI,KAAK,CAAC,OAAmC,CAAC,SAAS,CAAC;wBAClE,2IAA2I;wBAC3I,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1C,MAAM;oBACR,CAAC;oBACD,KAAK,oBAAoB,CAAC,CAAC,CAAC;wBAC1B,6DAA6D;wBAC7D,MAAM,CAAC,GAAG,KAAK,CAAC,OAA6B,CAAC;wBAC9C,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;wBAC5B,MAAM;oBACR,CAAC;oBACD,KAAK,gBAAgB,CAAC,CAAC,CAAC;wBACtB,MAAM,CAAC,GAAG,KAAK,CAAC,OAA6B,CAAC;wBAC9C,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;wBAC5B,MAAM;oBACR,CAAC;gBACH,CAAC;YACH,CAAC;YAED,uGAAuG;YACvG,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,MAAM,aAAa,GAAG,4EAA4E,QAAQ,EAAE,CAAC;YAC7G,MAAM,eAAe,GAAG,iCAAiC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAEnF,+GAA+G;YAC/G,MAAM,IAAI,KAAK,CAAC,GAAG,aAAa,MAAM,eAAe,EAAE,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAE7D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;QAC9C,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAiB,CAAC;QAEnD,wDAAwD;QACxD,MAAM,mBAAmB,GAAG,GAAG,EAAE;YAC/B,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAC/B,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAClE,CAAC;YAEF,qCAAqC;YACrC,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;gBAChC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;gBACrC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CACzB,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,SAAS,CACpE,CAAC;gBACF,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,MAAM,GAAe;wBACzB,MAAM,EAAE,SAAS;wBACjB,OAAO,EAAE,qCAAqC,SAAS,EAAE;qBAC1D,CAAC;oBACF,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;oBAC/B,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC7C,CAAC;YACH,CAAC;YAED,gEAAgE;YAChE,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;gBACvC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACxE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;gBACrC,OAAO,IAAI,CAAC,KAAK,CACf,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,SAAS,CACpE,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,wBAAwB;YACxB,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC5B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBAEjC,MAAM,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;oBAC9B,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;wBAC5C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;oBACjC,CAAC;oBAAC,OAAO,CAAC,EAAE,CAAC;wBACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE;4BACrB,MAAM,EAAE,SAAS;4BACjB,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;yBAClD,CAAC,CAAC;oBACL,CAAC;4BAAS,CAAC;wBACT,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;wBAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAE,CAAC;wBACvC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;oBACzC,CAAC;gBACH,CAAC,CAAC,EAAE,CAAC;gBAEL,6DAA6D;gBAC7D,MAAM,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE;oBAC3C,iBAAiB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;gBAC3C,CAAC,CAAC,CAAC;gBACH,iBAAiB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;YACxC,CAAC;QACH,CAAC,CAAC;QAEF,2CAA2C;QAC3C,mBAAmB,EAAE,CAAC;QAEtB,OAAO,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,IAAI,iBAAiB,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACjE,mCAAmC;YACnC,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YACtC,4CAA4C;YAC5C,mBAAmB,EAAE,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QAC7D,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}
+{"version":3,"file":"TaskRunner.js","sourceRoot":"","sources":["../src/TaskRunner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAKzD;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAOD;IANZ,QAAQ,GAAG,IAAI,QAAQ,EAAY,CAAC;IACpC,SAAS,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAE7C;;OAEG;IACH,YAAoB,OAAiB;QAAjB,YAAO,GAAP,OAAO,CAAU;IAAG,CAAC;IAEzC;;;;OAIG;IACI,EAAE,CACP,KAAQ,EACR,QAA0C;QAE1C,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACI,GAAG,CACR,KAAQ,EACR,QAA0C;QAE1C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAA2B;QACvC,2CAA2C;QAC3C,MAAM,SAAS,GAAc;YAC3B,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC1B,EAAE,EAAE,IAAI,CAAC,IAAI;gBACb,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;aACtC,CAAC,CAAC;SACJ,CAAC;QAEF,MAAM,gBAAgB,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAC5D,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnE,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;CACF"}

package/dist/WorkflowExecutor.d.ts

@@ -0,0 +1,32 @@
+import { TaskStep } from "./TaskStep.js";
+import { TaskResult } from "./TaskResult.js";
+import { EventBus } from "./EventBus.js";
+/**
+ * Handles the execution of the workflow steps.
+ * @template TContext The shape of the shared context object.
+ */
+export declare class WorkflowExecutor<TContext> {
+    private context;
+    private eventBus;
+    private running;
+    /**
+     * @param context The shared context object.
+     * @param eventBus The event bus to emit events.
+     */
+    constructor(context: TContext, eventBus: EventBus<TContext>);
+    /**
+     * Executes the given steps.
+     * @param steps The list of steps to execute.
+     * @returns A Promise that resolves to a map of task results.
+     */
+    execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>>;
+    /**
+     * Logic to identify tasks that can be started or must be skipped.
+     * Iterate only over pending steps to avoid O(N^2) checks on completed tasks.
+     */
+    private processQueue;
+    /**
+     * Handles the lifecycle of a single task execution.
+     */
+    private runStep;
+}

package/dist/WorkflowExecutor.js

@@ -0,0 +1,109 @@
+/**
+ * Handles the execution of the workflow steps.
+ * @template TContext The shape of the shared context object.
+ */
+export class WorkflowExecutor {
+    context;
+    eventBus;
+    running = new Set();
+    /**
+     * @param context The shared context object.
+     * @param eventBus The event bus to emit events.
+     */
+    constructor(context, eventBus) {
+        this.context = context;
+        this.eventBus = eventBus;
+    }
+    /**
+     * Executes the given steps.
+     * @param steps The list of steps to execute.
+     * @returns A Promise that resolves to a map of task results.
+     */
+    async execute(steps) {
+        this.eventBus.emit("workflowStart", { context: this.context, steps });
+        const results = new Map();
+        const executingPromises = new Set();
+        const pendingSteps = new Set(steps);
+        // Initial pass
+        this.processQueue(pendingSteps, results, executingPromises);
+        while (results.size < steps.length && executingPromises.size > 0) {
+            // Wait for the next task to finish
+            await Promise.race(executingPromises);
+            // After a task finishes, check for new work
+            this.processQueue(pendingSteps, results, executingPromises);
+        }
+        this.eventBus.emit("workflowEnd", { context: this.context, results });
+        return results;
+    }
+    /**
+     * Logic to identify tasks that can be started or must be skipped.
+     * Iterate only over pending steps to avoid O(N^2) checks on completed tasks.
+     */
+    processQueue(pendingSteps, results, executingPromises) {
+        const toRemove = [];
+        const toRun = [];
+        for (const step of pendingSteps) {
+            const deps = step.dependencies ?? [];
+            let blocked = false;
+            let failedDep;
+            for (const dep of deps) {
+                const depResult = results.get(dep);
+                if (!depResult) {
+                    // Dependency not finished yet
+                    blocked = true;
+                }
+                else if (depResult.status !== "success") {
+                    failedDep = dep;
+                    break;
+                }
+            }
+            if (failedDep) {
+                const result = {
+                    status: "skipped",
+                    message: `Skipped due to failed dependency: ${failedDep}`,
+                };
+                results.set(step.name, result);
+                this.eventBus.emit("taskSkipped", { step, result });
+                toRemove.push(step);
+            }
+            else if (!blocked) {
+                toRun.push(step);
+                toRemove.push(step);
+            }
+        }
+        // Cleanup pending set
+        for (const step of toRemove) {
+            pendingSteps.delete(step);
+        }
+        // Execute ready tasks
+        for (const step of toRun) {
+            const taskPromise = this.runStep(step, results).then(() => {
+                executingPromises.delete(taskPromise);
+            });
+            executingPromises.add(taskPromise);
+        }
+    }
+    /**
+     * Handles the lifecycle of a single task execution.
+     */
+    async runStep(step, results) {
+        this.running.add(step.name);
+        this.eventBus.emit("taskStart", { step });
+        try {
+            const result = await step.run(this.context);
+            results.set(step.name, result);
+        }
+        catch (e) {
+            results.set(step.name, {
+                status: "failure",
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+        finally {
+            this.running.delete(step.name);
+            const result = results.get(step.name);
+            this.eventBus.emit("taskEnd", { step, result });
+        }
+    }
+}
+//# sourceMappingURL=WorkflowExecutor.js.map

package/dist/WorkflowExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowExecutor.js","sourceRoot":"","sources":["../src/WorkflowExecutor.ts"],"names":[],"mappings":"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"}

package/dist/contracts/ITaskGraphValidator.d.ts

@@ -10,4 +10,10 @@ export interface ITaskGraphValidator {
      * @returns A ValidationResult object indicating the outcome of the validation.
      */
     validate(taskGraph: TaskGraph): ValidationResult;
+    /**
+     * Creates a human-readable error message from a validation result.
+     * @param result The validation result containing errors.
+     * @returns A formatted error string.
+     */
+    createErrorMessage(result: ValidationResult): string;
 }

package/dist/contracts/RunnerEvents.d.ts

@@ -0,0 +1,36 @@
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Define the payload for every possible event in the lifecycle.
+ */
+export interface RunnerEventPayloads<TContext> {
+    workflowStart: {
+        context: TContext;
+        steps: TaskStep<TContext>[];
+    };
+    workflowEnd: {
+        context: TContext;
+        results: Map<string, TaskResult>;
+    };
+    taskStart: {
+        step: TaskStep<TContext>;
+    };
+    taskEnd: {
+        step: TaskStep<TContext>;
+        result: TaskResult;
+    };
+    taskSkipped: {
+        step: TaskStep<TContext>;
+        result: TaskResult;
+    };
+}
+/**
+ * A generic listener type that maps the event key to its specific payload.
+ */
+export type RunnerEventListener<TContext, K extends keyof RunnerEventPayloads<TContext>> = (data: RunnerEventPayloads<TContext>[K]) => void | Promise<void>;
+/**
+ * Helper type for the listeners map.
+ */
+export type ListenerMap<TContext> = {
+    [K in keyof RunnerEventPayloads<TContext>]?: Set<RunnerEventListener<TContext, K>>;
+};

package/dist/contracts/RunnerEvents.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=RunnerEvents.js.map

package/dist/contracts/RunnerEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunnerEvents.js","sourceRoot":"","sources":["../../src/contracts/RunnerEvents.ts"],"names":[],"mappings":""}