@calmo/task-runner 3.4.0 → 3.4.1

package/openspec/changes/archive/2026-01-18-add-integration-tests/proposal.md

@@ -1,9 +1,11 @@
 # Change: Add Comprehensive Integration Tests
 
 ## Why
+
 The current test suite relies heavily on unit tests and mocks. To ensure robust behavior in real-world scenarios, we need comprehensive integration tests that execute full task graphs without mocks, validating complex configurations and interactions.
 
 ## What Changes
+
 - Create a dedicated `tests/integration-tests/` directory.
 - Implement 10-20 integration test scenarios covering:
   - Linear and branching dependencies.
@@ -14,5 +16,6 @@ The current test suite relies heavily on unit tests and mocks. To ensure robust
   - Error recovery (if retry policy is implemented, otherwise standard error states).
 
 ## Impact
+
 - Affected specs: `task-runner` (no functional changes to the runtime, but validates existing specs)
 - Affected code: `tests/integration-tests/*`

package/openspec/changes/archive/2026-01-18-add-integration-tests/tasks.md

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Setup `tests/integration-tests/` directory and test runner config if needed.
 - [x] 1.2 Implement Scenario 1: Basic linear workflow (A -> B -> C) success.
 - [x] 1.3 Implement Scenario 2: Branching workflow (A -> [B, C] -> D) success.

package/openspec/changes/archive/2026-01-18-add-task-retry-policy/proposal.md

@@ -1,9 +1,11 @@
 # Change: Add Task Retry Policy
 
 ## Why
+
 Tasks currently run once and fail immediately if they throw an error or return a failure status. Network glitches or transient issues can therefore cause an entire workflow to fail unnecessarily.
 
 ## What Changes
+
 - Add `TaskRetryConfig` interface to define retry behavior (attempts, delay, backoff).
 - Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
 - Implement `RetryingExecutionStrategy` which decorates any `IExecutionStrategy`.
@@ -12,5 +14,6 @@ Tasks currently run once and fail immediately if they throw an error or return a
   - It waits and re-executes the step if applicable.
 
 ## Impact
+
 - **New Components**: `RetryingExecutionStrategy`, `TaskRetryConfig`
 - **Affected Components**: `TaskStep` (interface update)

package/openspec/changes/archive/2026-01-18-add-task-retry-policy/tasks.md

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Create `TaskRetryConfig` interface with `attempts`, `delay`, and `backoff`.
 - [x] 1.2 Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
 - [x] 1.3 Update execution logic to catch task failures.

package/openspec/changes/archive/2026-01-18-add-workflow-preview/proposal.md

@@ -1,13 +1,16 @@
 # Change: Add Workflow Preview
 
 ## Why
+
 It can be difficult to understand the execution flow of complex dependency graphs just by looking at the code. Users also currently cannot easily verify the execution plan without running the side effects, which carries risk.
 
 ## What Changes
+
 - Add a `DryRunExecutionStrategy` which implements `IExecutionStrategy`. This allows `WorkflowExecutor` to simulate execution without side effects.
 - Add a standalone utility `generateMermaidGraph(steps: TaskStep[])` to generate a Mermaid.js diagram of the dependency graph.
 - Expose these features via the main `TaskRunner` facade if applicable, or as separate utilities.
 
 ## Impact
+
 - **New Components**: `DryRunExecutionStrategy`, `generateMermaidGraph`
 - **Affected Components**: `WorkflowExecutor` (indirectly, via strategy injection)

package/openspec/changes/archive/2026-01-18-add-workflow-preview/tasks.md

@@ -1,4 +1,5 @@
 ## Implementation
+
 - [x] 1.1 Update `TaskRunnerExecutionConfig` to include an optional `dryRun: boolean` property.
 - [x] 1.2 Implement `dryRun` logic in `WorkflowExecutor` (traverse graph, validate order, skip `step.run()`, return `skipped` or `success` pseudo-status).
 - [x] 1.3 Implement `getMermaidGraph(steps: TaskStep[])` method (can be static or instance method on `TaskRunner`).

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

@@ -1,14 +1,17 @@
 # Change: Refactor Core Architecture
 
 ## Why
+
 When multiple developers work on the project, conflicts arise due to tight coupling and poor separation of concerns. Large classes like `WorkflowExecutor` are taking on too many responsibilities, and there is duplicated logic around graph traversal and state management.
 
 ## What Changes
+
 - Decouple `WorkflowExecutor` from `EventBus` (pass a listener interface or use a mediating controller).
 - Extract `TaskExecutionStrategy` to allow pluggable execution modes (e.g., standard, dry-run, debug).
 - Centralize state management for task results and context, moving it out of the executor loop.
 - Standardize error handling and logging (QoL improvements).
 
 ## Impact
+
 - Affected specs: `task-runner` (no behavior change, but structural refactor)
 - Affected code: `src/WorkflowExecutor.ts`, `src/TaskRunner.ts`, new files for extracted logic.

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

@@ -1,4 +1,5 @@
 ## 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`.

package/openspec/changes/feat-per-task-timeout/proposal.md

@@ -1,25 +1,30 @@
 # Feature: Per-Task Timeout
 
 ## 🎯 User Story
+
 "As a developer, I want to define a maximum execution time for specific tasks so that a single hung task (e.g., a stalled network request) fails fast without blocking the rest of the independent tasks or waiting for the global workflow timeout."
 
 ## ❓ Why
+
 Currently, the `TaskRunner` allows a **global** timeout for the entire `execute()` call. However, this is insufficient for granular control:
+
 1.  **Varying Latency**: Some tasks are expected to be fast (local validation), others slow (data fetching). A global timeout of 30s is too loose for the fast ones.
 2.  **Boilerplate**: Developers currently have to manually implement `setTimeout`, `Promise.race`, and `AbortController` logic inside every `run()` method to handle timeouts properly.
 3.  **Resilience**: A single "zombie" task can hold up the entire pipeline until the global timeout kills everything. Per-task timeouts allow failing that specific task (and skipping its dependents) while letting other independent tasks continue.
 
 ## 🛠️ What Changes
+
 1.  **Interface Update**: Update `TaskStep<T>` to accept an optional `timeout` property (in milliseconds).
 2.  **Execution Strategy**: Update `StandardExecutionStrategy` to:
-    -   Create a local timeout timer for the task.
-    -   Create a combined `AbortSignal` (merging the workflow's signal and the local timeout).
-    -   Race the task execution against the timer.
-    -   Return a specific failure result if the timeout wins.
+    - Create a local timeout timer for the task.
+    - Create a combined `AbortSignal` (merging the workflow's signal and the local timeout).
+    - Race the task execution against the timer.
+    - Return a specific failure result if the timeout wins.
 
 ## ✅ Acceptance Criteria
+
 - [ ] A task with `timeout: 100` must fail if the `run` method takes > 100ms.
 - [ ] The error message for a timed-out task should clearly state "Task timed out after 100ms".
 - [ ] The `AbortSignal` passed to the task's `run` method must be triggered when the timeout occurs.
-- [ ] If the Global Workflow is cancelled *before* the task times out, the task should receive the cancellation signal immediately.
-- [ ] A task completing *before* the timeout should clear the timer to prevent open handles.
+- [ ] If the Global Workflow is cancelled _before_ the task times out, the task should receive the cancellation signal immediately.
+- [ ] A task completing _before_ the timeout should clear the timer to prevent open handles.

package/openspec/changes/feat-per-task-timeout/tasks.md

@@ -11,7 +11,7 @@
     - If yes, create an `AbortController`.
     - Set a `setTimeout` to trigger the controller.
     - Use `Promise.race` (or simply pass the new signal and wait) to handle the timeout.
-    - **Crucial**: Ensure the new signal respects the *parent* `signal` (if global cancel happens, local signal must also abort).
+    - **Crucial**: Ensure the new signal respects the _parent_ `signal` (if global cancel happens, local signal must also abort).
     - **Crucial**: Clean up the timer (`clearTimeout`) in a `finally` block.
 
 - [ ] **Task 3: Unit Tests**

package/openspec/project.md

@@ -1,32 +1,38 @@
 # Project: Task Runner
 
 ## Overview
+
 The 'task-runner' project is a TypeScript-based utility designed to manage and execute tasks. It incorporates features such as task cancellation, pre-execution validation, and concurrency control, providing a robust framework for workflow automation.
 
 ## Tech Stack
+
 - **Languages:** TypeScript 5.9.3
 - **Testing:** Vitest 4.0.17
 - **Core APIs:** AbortSignal/AbortController (Standard Web APIs for cancellation)
 - **Package Manager:** pnpm
 
 ## Architecture
+
 The project follows a modular architecture with distinct components for managing different aspects of task execution:
--   `EventBus.ts`: Handles event propagation within the system.
--   `TaskGraph.ts`: Represents the structure and dependencies of tasks.
--   `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
--   `TaskRunner.ts`: Orchestrates the execution of tasks.
--   `WorkflowExecutor.ts`: Manages the overall workflow.
--   `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
+
+- `EventBus.ts`: Handles event propagation within the system.
+- `TaskGraph.ts`: Represents the structure and dependencies of tasks.
+- `TaskGraphValidator.ts`: Ensures the validity of task graphs before execution.
+- `TaskRunner.ts`: Orchestrates the execution of tasks.
+- `WorkflowExecutor.ts`: Manages the overall workflow.
+- `contracts/`: Defines interfaces and types for various components, promoting loose coupling and clear API boundaries.
 
 ## Conventions
--   **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
--   **Commit Messages:** Follows conventional commits enforced by Commitlint.
--   **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
--   **Testing:** Uses Vitest for unit and integration testing.
--   **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
+
+- **Coding Style:** Adheres to standard TypeScript conventions, enforced by ESLint and Prettier.
+- **Commit Messages:** Follows conventional commits enforced by Commitlint.
+- **Git Hooks:** Utilizes Husky for pre-commit and commit-msg hooks.
+- **Testing:** Uses Vitest for unit and integration testing.
+- **Atomic Commits:** When working on complex multi-task features, commit after each distinct task, ensuring build, lint, and test success to establish safe rollback points.
 
 ## Build/Test/Run Commands
--   **Install Dependencies:** `pnpm install`
--   **Build Project:** `pnpm build`
--   **Run Tests:** `pnpm test`
--   **Lint Code:** `pnpm lint`
+
+- **Install Dependencies:** `pnpm install`
+- **Build Project:** `pnpm build`
+- **Run Tests:** `pnpm test`
+- **Lint Code:** `pnpm lint`

package/package.json

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

package/src/EventBus.ts

@@ -61,23 +61,25 @@ export class EventBus<TContext> {
       | undefined;
     if (listeners) {
       for (const listener of listeners) {
-        try {
-          const result = listener(data);
-          if (result instanceof Promise) {
-            result.catch((error) => {
-              console.error(
-                `Error in event listener for ${String(event)}:`,
-                error
-              );
-            });
+        Promise.resolve().then(() => {
+          try {
+            const result = listener(data);
+            if (result instanceof Promise) {
+              result.catch((error) => {
+                console.error(
+                  `Error in event listener for ${String(event)}:`,
+                  error
+                );
+              });
+            }
+          } catch (error) {
+            // Prevent listener errors from bubbling up
+            console.error(
+              `Error in event listener for ${String(event)}:`,
+              error
+            );
           }
-        } catch (error) {
-          // Prevent listener errors from bubbling up
-          console.error(
-            `Error in event listener for ${String(event)}:`,
-            error
-          );
-        }
+        });
       }
     }
   }

package/src/TaskGraph.ts

@@ -2,18 +2,18 @@
  * Represents a single task in the task graph.
  */
 export interface Task {
-    /** Unique identifier for the task. */
-    id: string;
-    /** An array of task IDs that this task directly depends on. */
-    dependencies: string[];
-    /** Allows for any other properties specific to the task's payload or configuration. */
-    [key: string]: unknown;
+  /** Unique identifier for the task. */
+  id: string;
+  /** An array of task IDs that this task directly depends on. */
+  dependencies: string[];
+  /** Allows for any other properties specific to the task's payload or configuration. */
+  [key: string]: unknown;
 }
 
 /**
  * Represents the entire collection of tasks and their interdependencies.
  */
 export interface TaskGraph {
-    /** An array of tasks that make up the graph. */
-    tasks: Task[];
+  /** An array of tasks that make up the graph. */
+  tasks: Task[];
 }

package/src/TaskGraphValidationError.ts

@@ -5,7 +5,10 @@ import { ValidationResult } from "./contracts/ValidationResult.js";
  * Contains the validation result with detailed error information.
  */
 export class TaskGraphValidationError extends Error {
-  constructor(public result: ValidationResult, message: string) {
+  constructor(
+    public result: ValidationResult,
+    message: string
+  ) {
     super(message);
     this.name = "TaskGraphValidationError";
   }

package/src/TaskGraphValidator.ts

@@ -4,160 +4,165 @@ import { ValidationError } from "./contracts/ValidationError.js";
 import { TaskGraph } from "./TaskGraph.js";
 
 export class TaskGraphValidator implements ITaskGraphValidator {
-    /**
-     * Validates a given task graph for structural integrity.
-     * Checks for:
-     * 1. Duplicate task IDs.
-     * 2. Missing dependencies (tasks that depend on non-existent IDs).
-     * 3. Circular dependencies (cycles in the graph).
-     *
-     * @param taskGraph The task graph to validate.
-     * @returns A ValidationResult object indicating the outcome of the validation.
-     */
-    validate(taskGraph: TaskGraph): ValidationResult {
-        const errors: ValidationError[] = [];
-
-        // 1. Check for duplicate tasks
-        const taskIds = new Set<string>();
-        for (const task of taskGraph.tasks) {
-            if (taskIds.has(task.id)) {
-                errors.push({
-                    type: "duplicate_task",
-                    message: `Duplicate task detected with ID: ${task.id}`,
-                    details: { taskId: task.id }
-                });
-            } else {
-                taskIds.add(task.id);
-            }
-        }
+  /**
+   * Validates a given task graph for structural integrity.
+   * Checks for:
+   * 1. Duplicate task IDs.
+   * 2. Missing dependencies (tasks that depend on non-existent IDs).
+   * 3. Circular dependencies (cycles in the graph).
+   *
+   * @param taskGraph The task graph to validate.
+   * @returns A ValidationResult object indicating the outcome of the validation.
+   */
+  validate(taskGraph: TaskGraph): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // 1. Check for duplicate tasks
+    const taskIds = new Set<string>();
+    for (const task of taskGraph.tasks) {
+      if (taskIds.has(task.id)) {
+        errors.push({
+          type: "duplicate_task",
+          message: `Duplicate task detected with ID: ${task.id}`,
+          details: { taskId: task.id },
+        });
+      } else {
+        taskIds.add(task.id);
+      }
+    }
 
-        // 2. Check for missing dependencies
-        for (const task of taskGraph.tasks) {
-            for (const dependenceId of task.dependencies) {
-                if (!taskIds.has(dependenceId)) {
-                    errors.push({
-                        type: "missing_dependency",
-                        message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
-                        details: { taskId: task.id, missingDependencyId: dependenceId }
-                    });
-                }
-            }
+    // 2. Check for missing dependencies
+    for (const task of taskGraph.tasks) {
+      for (const dependenceId of task.dependencies) {
+        if (!taskIds.has(dependenceId)) {
+          errors.push({
+            type: "missing_dependency",
+            message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
+            details: { taskId: task.id, missingDependencyId: dependenceId },
+          });
         }
+      }
+    }
 
-        // 3. Check for cycles
-        // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
-        const hasMissingDependencies = errors.some(e => e.type === "missing_dependency");
+    // 3. Check for cycles
+    // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
+    const hasMissingDependencies = errors.some(
+      (e) => e.type === "missing_dependency"
+    );
+
+    if (hasMissingDependencies) {
+      return {
+        isValid: errors.length === 0,
+        errors,
+      };
+    }
 
-        if (hasMissingDependencies) {
-            return {
-                isValid: errors.length === 0,
-                errors
-            };
-        }
+    // Build adjacency list
+    const adjacencyList = new Map<string, string[]>();
+    for (const task of taskGraph.tasks) {
+      adjacencyList.set(task.id, task.dependencies);
+    }
 
-        // Build adjacency list
-        const adjacencyList = new Map<string, string[]>();
-        for (const task of taskGraph.tasks) {
-            adjacencyList.set(task.id, task.dependencies);
-        }
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    for (const task of taskGraph.tasks) {
+      if (visited.has(task.id)) {
+        continue;
+      }
+
+      const path: string[] = [];
+      if (
+        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+      ) {
+        // Extract the actual cycle from the path
+        // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
+        const cycleStart = path[path.length - 1];
+        const cycleStartIndex = path.indexOf(cycleStart);
+        const cyclePath = path.slice(cycleStartIndex);
+
+        errors.push({
+          type: "cycle",
+          message: `Cycle detected: ${cyclePath.join(" -> ")}`,
+          details: { cyclePath },
+        });
+        // Break after first cycle found to avoid spamming similar errors
+        break;
+      }
+    }
 
-        const visited = new Set<string>();
-        const recursionStack = new Set<string>();
-
-        for (const task of taskGraph.tasks) {
-            if (visited.has(task.id)) {
-                continue;
-            }
-
-            const path: string[] = [];
-            if (this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)) {
-                // Extract the actual cycle from the path
-                // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
-                const cycleStart = path[path.length - 1];
-                const cycleStartIndex = path.indexOf(cycleStart);
-                const cyclePath = path.slice(cycleStartIndex);
-
-                errors.push({
-                    type: "cycle",
-                    message: `Cycle detected: ${cyclePath.join(" -> ")}`,
-                    details: { cyclePath }
-                });
-                // Break after first cycle found to avoid spamming similar errors
-                break;
-            }
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * 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 {
+    const errorDetails = result.errors.map((e) => e.message);
+    return `Task graph validation failed: ${errorDetails.join("; ")}`;
+  }
+
+  private detectCycle(
+    startTaskId: string,
+    path: string[],
+    visited: Set<string>,
+    recursionStack: Set<string>,
+    adjacencyList: Map<string, string[]>
+  ): boolean {
+    // Use an explicit stack to avoid maximum call stack size exceeded errors
+    const stack: { taskId: string; index: number; dependencies: string[] }[] =
+      [];
+
+    visited.add(startTaskId);
+    recursionStack.add(startTaskId);
+    path.push(startTaskId);
+
+    stack.push({
+      taskId: startTaskId,
+      index: 0,
+      /* v8 ignore next */
+      dependencies: adjacencyList.get(startTaskId) ?? [],
+    });
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const { taskId, dependencies } = frame;
+
+      if (frame.index < dependencies.length) {
+        const dependenceId = dependencies[frame.index];
+        frame.index++;
+
+        if (recursionStack.has(dependenceId)) {
+          // Cycle detected
+          path.push(dependenceId);
+          return true;
         }
 
-        return {
-            isValid: errors.length === 0,
-            errors
-        };
-    }
-
-    /**
-     * 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 {
-        const errorDetails = result.errors.map(e => e.message);
-        return `Task graph validation failed: ${errorDetails.join("; ")}`;
-    }
+        if (!visited.has(dependenceId)) {
+          visited.add(dependenceId);
+          recursionStack.add(dependenceId);
+          path.push(dependenceId);
 
-    private detectCycle(
-        startTaskId: string,
-        path: string[],
-        visited: Set<string>,
-        recursionStack: Set<string>,
-        adjacencyList: Map<string, string[]>
-    ): boolean {
-        // Use an explicit stack to avoid maximum call stack size exceeded errors
-        const stack: { taskId: string; index: number; dependencies: string[] }[] = [];
-
-        visited.add(startTaskId);
-        recursionStack.add(startTaskId);
-        path.push(startTaskId);
-
-        stack.push({
-            taskId: startTaskId,
+          stack.push({
+            taskId: dependenceId,
             index: 0,
             /* v8 ignore next */
-            dependencies: adjacencyList.get(startTaskId) ?? []
-        });
-
-        while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
-            const { taskId, dependencies } = frame;
-
-            if (frame.index < dependencies.length) {
-                const dependenceId = dependencies[frame.index];
-                frame.index++;
-
-                if (recursionStack.has(dependenceId)) {
-                    // Cycle detected
-                    path.push(dependenceId);
-                    return true;
-                }
-
-                if (!visited.has(dependenceId)) {
-                    visited.add(dependenceId);
-                    recursionStack.add(dependenceId);
-                    path.push(dependenceId);
-
-                    stack.push({
-                        taskId: dependenceId,
-                        index: 0,
-                        /* v8 ignore next */
-                        dependencies: adjacencyList.get(dependenceId) ?? []
-                    });
-                }
-            } else {
-                // Finished all dependencies for this node
-                recursionStack.delete(taskId);
-                path.pop();
-                stack.pop();
-            }
+            dependencies: adjacencyList.get(dependenceId) ?? [],
+          });
         }
-
-        return false;
+      } else {
+        // Finished all dependencies for this node
+        recursionStack.delete(taskId);
+        path.pop();
+        stack.pop();
+      }
     }
+
+    return false;
+  }
 }