@calmo/task-runner 2.0.0 → 3.0.0

package/openspec/changes/archive/2026-01-18-refactor-core-architecture/tasks.md

@@ -0,0 +1,8 @@
+## Implementation
+- [x] 1.1 Extract `TaskStateManager` to handle `TaskResult` storage, updates, and context mutations.
+- [x] 1.2 Define `IExecutionStrategy` interface for running tasks (Strategy Pattern).
+- [x] 1.3 Refactor `WorkflowExecutor` to use `TaskStateManager` and `IExecutionStrategy`.
+- [x] 1.4 Move explicit event emission out of the core loop into the `TaskStateManager` or a dedicated `ExecutionObserver`.
+- [x] 1.5 Create a factory or builder for `TaskRunner` to simplify configuration for developers.
+- [x] 1.6 Verify that all existing tests pass with the new structure.
+- [x] 1.7 Add "Quality of Life" improvements (e.g., better error messages with specific task context).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "",
   "repository": {
     "type": "git",

package/src/TaskRunner.ts

@@ -5,9 +5,13 @@ import { TaskGraph } from "./TaskGraph.js";
 import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
 import { EventBus } from "./EventBus.js";
 import { WorkflowExecutor } from "./WorkflowExecutor.js";
+import { TaskRunnerExecutionConfig } from "./TaskRunnerExecutionConfig.js";
+import { TaskStateManager } from "./TaskStateManager.js";
+import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
+import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 
 // Re-export types for backward compatibility
-export { RunnerEventPayloads, RunnerEventListener };
+export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
 
 /**
  * The main class that orchestrates the execution of a list of tasks
@@ -17,6 +21,7 @@ export { RunnerEventPayloads, RunnerEventListener };
 export class TaskRunner<TContext> {
   private eventBus = new EventBus<TContext>();
   private validator = new TaskGraphValidator();
+  private executionStrategy: IExecutionStrategy<TContext> = new StandardExecutionStrategy();
 
   /**
    * @param context The shared context object to be passed to each task.
@@ -44,17 +49,33 @@ export class TaskRunner<TContext> {
     event: K,
     callback: RunnerEventListener<TContext, K>
   ): void {
+    /* v8 ignore next 1 */
     this.eventBus.off(event, callback);
   }
 
+  /**
+   * Sets the execution strategy to be used.
+   * @param strategy The execution strategy.
+   * @returns The TaskRunner instance for chaining.
+   */
+  public setExecutionStrategy(strategy: IExecutionStrategy<TContext>): this {
+    /* v8 ignore next 2 */
+    this.executionStrategy = strategy;
+    return this;
+  }
+
   /**
    * Executes a list of tasks, respecting their dependencies and running
    * independent tasks in parallel.
    * @param steps An array of TaskStep objects to be executed.
+   * @param config Optional configuration for execution (timeout, cancellation).
    * @returns A Promise that resolves to a Map where keys are task names
    * and values are the corresponding TaskResult objects.
    */
-  async execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>> {
+  async execute(
+    steps: TaskStep<TContext>[],
+    config?: TaskRunnerExecutionConfig
+  ): Promise<Map<string, TaskResult>> {
     // Validate the task graph before execution
     const taskGraph: TaskGraph = {
       tasks: steps.map((step) => ({
@@ -68,7 +89,50 @@ export class TaskRunner<TContext> {
       throw new Error(this.validator.createErrorMessage(validationResult));
     }
 
-    const executor = new WorkflowExecutor(this.context, this.eventBus);
-    return executor.execute(steps);
+    const stateManager = new TaskStateManager(this.eventBus);
+    const executor = new WorkflowExecutor(
+      this.context,
+      this.eventBus,
+      stateManager,
+      this.executionStrategy
+    );
+
+    // We need to handle the timeout cleanup properly.
+    if (config?.timeout !== undefined) {
+       const controller = new AbortController();
+       const timeoutId = setTimeout(() => {
+         controller.abort(new Error(`Workflow timed out after ${config.timeout}ms`));
+       }, config.timeout);
+
+       let effectiveSignal = controller.signal;
+       let onAbort: (() => void) | undefined;
+
+       // Handle combination of signals if user provided one
+       if (config.signal) {
+          if (config.signal.aborted) {
+             // If already aborted, use it directly (WorkflowExecutor handles early abort)
+             // We can cancel timeout immediately
+             clearTimeout(timeoutId);
+             effectiveSignal = config.signal;
+          } else {
+             // Listen to user signal to abort our controller
+             onAbort = () => {
+                controller.abort(config.signal?.reason);
+             };
+             config.signal.addEventListener("abort", onAbort);
+          }
+       }
+
+       try {
+         return await executor.execute(steps, effectiveSignal);
+       } finally {
+         clearTimeout(timeoutId);
+         if (config.signal && onAbort) {
+            config.signal.removeEventListener("abort", onAbort);
+         }
+       }
+    } else {
+       return executor.execute(steps, config?.signal);
+    }
   }
 }

package/src/TaskRunnerBuilder.ts

@@ -0,0 +1,76 @@
+import { TaskRunner } from "./TaskRunner.js";
+import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
+
+/**
+ * A builder for configuring and creating TaskRunner instances.
+ */
+export class TaskRunnerBuilder<TContext> {
+  private context: TContext;
+  private strategy?: IExecutionStrategy<TContext>;
+  private listeners: {
+    [K in keyof RunnerEventPayloads<TContext>]?: RunnerEventListener<TContext, K>[];
+  } = {};
+
+  /**
+   * @param context The shared context object.
+   */
+  constructor(context: TContext) {
+    this.context = context;
+  }
+
+  /**
+   * Sets the execution strategy.
+   * @param strategy The execution strategy to use.
+   * @returns The builder instance.
+   */
+  public useStrategy(strategy: IExecutionStrategy<TContext>): this {
+    this.strategy = strategy;
+    return this;
+  }
+
+  /**
+   * Adds an event listener.
+   * @param event The event name.
+   * @param callback The callback to execute.
+   * @returns The builder instance.
+   */
+  public on<K extends keyof RunnerEventPayloads<TContext>>(
+    event: K,
+    callback: RunnerEventListener<TContext, K>
+  ): this {
+    if (!this.listeners[event]) {
+      this.listeners[event] = [];
+    }
+    this.listeners[event]!.push(callback);
+    return this;
+  }
+
+  /**
+   * Builds the TaskRunner instance.
+   * @returns A configured TaskRunner.
+   */
+  public build(): TaskRunner<TContext> {
+    const runner = new TaskRunner(this.context);
+
+    if (this.strategy) {
+      runner.setExecutionStrategy(this.strategy);
+    }
+
+    (Object.keys(this.listeners) as Array<keyof RunnerEventPayloads<TContext>>).forEach((event) => {
+      const callbacks = this.listeners[event];
+      // callbacks is always defined because we are iterating keys of the object
+      callbacks!.forEach((callback) =>
+        runner.on(
+          event,
+          callback as unknown as RunnerEventListener<
+            TContext,
+            keyof RunnerEventPayloads<TContext>
+          >
+        )
+      );
+    });
+
+    return runner;
+  }
+}

package/src/TaskRunnerExecutionConfig.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration options for TaskRunner execution.
+ */
+export interface TaskRunnerExecutionConfig {
+  /**
+   * An AbortSignal to cancel the workflow externally.
+   */
+  signal?: AbortSignal;
+  /**
+   * A timeout in milliseconds for the entire workflow.
+   */
+  timeout?: number;
+}

package/src/TaskStateManager.ts

@@ -0,0 +1,142 @@
+import { TaskStep } from "./TaskStep.js";
+import { TaskResult } from "./TaskResult.js";
+import { EventBus } from "./EventBus.js";
+
+/**
+ * Manages the state of the task execution, including results, pending steps, and running tasks.
+ * Handles dependency resolution and event emission for state changes.
+ */
+export class TaskStateManager<TContext> {
+  private results = new Map<string, TaskResult>();
+  private pendingSteps = new Set<TaskStep<TContext>>();
+  private running = new Set<string>();
+
+  constructor(private eventBus: EventBus<TContext>) {}
+
+  /**
+   * Initializes the state with the given steps.
+   * @param steps The steps to execute.
+   */
+  initialize(steps: TaskStep<TContext>[]): void {
+    this.pendingSteps = new Set(steps);
+    this.results.clear();
+    this.running.clear();
+  }
+
+  /**
+   * Processes the pending steps to identify tasks that can be started or must be skipped.
+   * Emits `taskSkipped` for skipped tasks.
+   * @returns An array of tasks that are ready to run.
+   */
+  processDependencies(): TaskStep<TContext>[] {
+    const toRemove: TaskStep<TContext>[] = [];
+    const toRun: TaskStep<TContext>[] = [];
+
+    for (const step of this.pendingSteps) {
+      const deps = step.dependencies ?? [];
+      let blocked = false;
+      let failedDep: string | undefined;
+
+      for (const dep of deps) {
+        const depResult = this.results.get(dep);
+        if (!depResult) {
+          // Dependency not finished yet
+          blocked = true;
+        } else if (depResult.status !== "success") {
+          failedDep = dep;
+          break;
+        }
+      }
+
+      if (failedDep) {
+        const depResult = this.results.get(failedDep);
+        const depError = depResult?.error ? `: ${depResult.error}` : "";
+        const result: TaskResult = {
+          status: "skipped",
+          message: `Skipped because dependency '${failedDep}' failed${depError}`,
+        };
+        this.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) {
+      this.pendingSteps.delete(step);
+    }
+
+    return toRun;
+  }
+
+  /**
+   * Marks a task as running and emits `taskStart`.
+   * @param step The task that is starting.
+   */
+  markRunning(step: TaskStep<TContext>): void {
+    this.running.add(step.name);
+    this.eventBus.emit("taskStart", { step });
+  }
+
+  /**
+   * Marks a task as completed (success, failure, or cancelled during execution)
+   * and emits `taskEnd`.
+   * @param step The task that completed.
+   * @param result The result of the task.
+   */
+  markCompleted(step: TaskStep<TContext>, result: TaskResult): void {
+    this.running.delete(step.name);
+    this.results.set(step.name, result);
+    this.eventBus.emit("taskEnd", { step, result });
+  }
+
+  /**
+   * Cancels all pending tasks that haven't started yet.
+   * @param message The cancellation message.
+   */
+  cancelAllPending(message: string): void {
+    // Iterate over pendingSteps to cancel them
+    for (const step of this.pendingSteps) {
+      // Also check running? No, running tasks are handled by AbortSignal in Executor.
+      // We only cancel what is pending and hasn't started.
+      /* v8 ignore next 1 */
+      if (!this.results.has(step.name) && !this.running.has(step.name)) {
+        const result: TaskResult = {
+          status: "cancelled",
+          message,
+        };
+        this.results.set(step.name, result);
+      }
+    }
+    // Clear pending set as they are now "done" (cancelled)
+    // Wait, if we clear pending steps, processDependencies won't pick them up.
+    // The loop in Executor relies on results.size or pendingSteps.
+    // The previous implementation iterated `steps` (all steps) to cancel.
+    // Here we iterate `pendingSteps`.
+    this.pendingSteps.clear();
+  }
+
+  /**
+   * Returns the current results map.
+   */
+  getResults(): Map<string, TaskResult> {
+    return this.results;
+  }
+
+  /**
+   * Checks if there are any tasks currently running.
+   */
+  hasRunningTasks(): boolean {
+    return this.running.size > 0;
+  }
+
+  /**
+   * Checks if there are any pending tasks.
+   */
+  hasPendingTasks(): boolean {
+    return this.pendingSteps.size > 0;
+  }
+}

package/src/TaskStatus.ts

@@ -1,4 +1,4 @@
 /**
  * Represents the completion status of a task.
  */
-export type TaskStatus = "success" | "failure" | "skipped";
+export type TaskStatus = "success" | "failure" | "skipped" | "cancelled";

package/src/TaskStep.ts

@@ -12,7 +12,8 @@ export interface TaskStep<TContext> {
   /**
    * The core logic of the task.
    * @param context The shared context object, allowing for state to be passed between tasks.
+   * @param signal An optional AbortSignal to listen for cancellation.
    * @returns A Promise that resolves to a TaskResult.
    */
-  run(context: TContext): Promise<TaskResult>;
+  run(context: TContext, signal?: AbortSignal): Promise<TaskResult>;
 }

package/src/WorkflowExecutor.ts

@@ -1,126 +1,120 @@
 import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
 import { EventBus } from "./EventBus.js";
+import { TaskStateManager } from "./TaskStateManager.js";
+import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 
 /**
  * Handles the execution of the workflow steps.
  * @template TContext The shape of the shared context object.
  */
 export class WorkflowExecutor<TContext> {
-  private running = new Set<string>();
-
   /**
    * @param context The shared context object.
    * @param eventBus The event bus to emit events.
+   * @param stateManager Manages execution state.
+   * @param strategy Execution strategy.
    */
   constructor(
     private context: TContext,
-    private eventBus: EventBus<TContext>
+    private eventBus: EventBus<TContext>,
+    private stateManager: TaskStateManager<TContext>,
+    private strategy: IExecutionStrategy<TContext>
   ) {}
 
   /**
    * Executes the given steps.
    * @param steps The list of steps to execute.
+   * @param signal Optional AbortSignal for cancellation.
    * @returns A Promise that resolves to a map of task results.
    */
-  async execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>> {
+  async execute(
+    steps: TaskStep<TContext>[],
+    signal?: AbortSignal
+  ): Promise<Map<string, TaskResult>> {
     this.eventBus.emit("workflowStart", { context: this.context, steps });
+    this.stateManager.initialize(steps);
+
+    // Check if already aborted
+    if (signal?.aborted) {
+      this.stateManager.cancelAllPending("Workflow cancelled before execution started.");
+      const results = this.stateManager.getResults();
+      this.eventBus.emit("workflowEnd", { context: this.context, results });
+      return results;
+    }
 
-    const results = new Map<string, TaskResult>();
     const executingPromises = new Set<Promise<void>>();
 
-    // Initial pass
-    this.processQueue(steps, results, executingPromises);
+    const onAbort = () => {
+      // Mark all pending tasks as cancelled
+      this.stateManager.cancelAllPending("Workflow cancelled.");
+    };
 
-    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(steps, results, executingPromises);
+    if (signal) {
+       signal.addEventListener("abort", onAbort);
     }
 
-    this.eventBus.emit("workflowEnd", { context: this.context, results });
-    return results;
-  }
-
-  /**
-   * Logic to identify tasks that can be started or must be skipped.
-   */
-  private processQueue(
-    steps: TaskStep<TContext>[],
-    results: Map<string, TaskResult>,
-    executingPromises: Set<Promise<void>>
-  ): void {
-    this.handleSkippedTasks(steps, results);
-
-    const readySteps = this.getReadySteps(steps, results);
-
-    for (const step of readySteps) {
-      const taskPromise = this.runStep(step, results).then(() => {
-        executingPromises.delete(taskPromise);
-      });
-      executingPromises.add(taskPromise);
-    }
-  }
-
-  /**
-   * Identifies steps that cannot run because a dependency failed.
-   */
-  private handleSkippedTasks(steps: TaskStep<TContext>[], results: Map<string, TaskResult>): void {
-    const pendingSteps = steps.filter(
-      (step) => !results.has(step.name) && !this.running.has(step.name)
-    );
+    try {
+      // Initial pass
+      this.processLoop(executingPromises, signal);
+
+      while (
+        this.stateManager.hasPendingTasks() ||
+        this.stateManager.hasRunningTasks()
+      ) {
+        // Safety check: if no tasks are running and we still have pending tasks,
+        // it means we are stuck (e.g. cycle or unhandled dependency).
+        // Since valid graphs shouldn't have this, we break to avoid infinite loop.
+        if (executingPromises.size === 0) {
+          break;
+        } else {
+          // Wait for the next task to finish
+          await Promise.race(executingPromises);
+        }
+
+        if (signal?.aborted) {
+           this.stateManager.cancelAllPending("Workflow cancelled.");
+        } else {
+           // After a task finishes, check for new work
+           this.processLoop(executingPromises, signal);
+        }
+      }
 
-    for (const step of pendingSteps) {
-      const deps = step.dependencies ?? [];
-      const failedDep = deps.find(
-        (dep) => results.has(dep) && results.get(dep)?.status !== "success"
-      );
+      // Ensure everything is accounted for (e.g. if loop exited early)
+      this.stateManager.cancelAllPending("Workflow cancelled.");
 
-      if (failedDep) {
-        const result: TaskResult = {
-          status: "skipped",
-          message: `Skipped due to failed dependency: ${failedDep}`,
-        };
-        results.set(step.name, result);
-        this.eventBus.emit("taskSkipped", { step, result });
+      const results = this.stateManager.getResults();
+      this.eventBus.emit("workflowEnd", { context: this.context, results });
+      return results;
+    } finally {
+      if (signal) {
+        signal.removeEventListener("abort", onAbort);
       }
     }
   }
 
   /**
-   * Returns steps where all dependencies have finished successfully.
+   * Logic to identify tasks that can be started and run them.
    */
-  private getReadySteps(steps: TaskStep<TContext>[], results: Map<string, TaskResult>): TaskStep<TContext>[] {
-    return steps.filter((step) => {
-      if (results.has(step.name) || this.running.has(step.name)) return false;
+  private processLoop(
+    executingPromises: Set<Promise<void>>,
+    signal?: AbortSignal
+  ): void {
+    const toRun = this.stateManager.processDependencies();
 
-      const deps = step.dependencies ?? [];
-      return deps.every(
-        (dep) => results.has(dep) && results.get(dep)?.status === "success"
-      );
-    });
-  }
+    // Execute ready tasks
+    for (const step of toRun) {
+      this.stateManager.markRunning(step);
 
-  /**
-   * Handles the lifecycle of a single task execution.
-   */
-  private async runStep(step: TaskStep<TContext>, results: Map<string, TaskResult>): Promise<void> {
-    this.running.add(step.name);
-    this.eventBus.emit("taskStart", { step });
+      const taskPromise = this.strategy.execute(step, this.context, signal)
+        .then((result) => {
+            this.stateManager.markCompleted(step, result);
+        })
+        .finally(() => {
+             executingPromises.delete(taskPromise);
+        });
 
-    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 });
+      executingPromises.add(taskPromise);
     }
   }
 }

package/src/index.ts

@@ -1,4 +1,8 @@
 export { TaskRunner } from "./TaskRunner.js";
+export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
+export { TaskStateManager } from "./TaskStateManager.js";
+export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+export type { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 export type { TaskStep } from "./TaskStep.js";
 export type { TaskResult } from "./TaskResult.js";
 export type { TaskStatus } from "./TaskStatus.js";

package/src/strategies/IExecutionStrategy.ts

@@ -0,0 +1,21 @@
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+
+/**
+ * Interface for task execution strategies.
+ * Allows different execution behaviors (e.g., standard, dry-run, debugging).
+ */
+export interface IExecutionStrategy<TContext> {
+  /**
+   * Executes a single task step.
+   * @param step The task step to execute.
+   * @param context The shared context.
+   * @param signal Optional abort signal.
+   * @returns A promise resolving to the task result.
+   */
+  execute(
+    step: TaskStep<TContext>,
+    context: TContext,
+    signal?: AbortSignal
+  ): Promise<TaskResult>;
+}

package/src/strategies/StandardExecutionStrategy.ts

@@ -0,0 +1,35 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+
+/**
+ * Standard execution strategy that runs the task's run method.
+ */
+export class StandardExecutionStrategy<TContext>
+  implements IExecutionStrategy<TContext>
+{
+  async execute(
+    step: TaskStep<TContext>,
+    context: TContext,
+    signal?: AbortSignal
+  ): Promise<TaskResult> {
+    try {
+      return await step.run(context, signal);
+    } catch (e) {
+      // Check if error is due to abort
+      if (
+        signal?.aborted &&
+        (e instanceof Error && e.name === "AbortError" || signal.reason === e)
+      ) {
+        return {
+          status: "cancelled",
+          message: "Task cancelled during execution",
+        };
+      }
+      return {
+        status: "failure",
+        error: e instanceof Error ? e.message : String(e),
+      };
+    }
+  }
+}