@calmo/task-runner 4.0.4 → 4.2.0

package/openspec/changes/feat-conditional-retries/specs/task-runner/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Conditional Retries
+
+The system SHALL support conditional retries where a user-defined predicate determines if a task failure warrants a retry attempt.
+
+#### Scenario: Retry allowed by predicate
+- **GIVEN** a task configured with retries and a `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **AND** the `shouldRetry` predicate returns `true` for that error
+- **THEN** the system SHALL proceed with the retry logic (respecting attempt limits and delays).
+
+#### Scenario: Retry denied by predicate
+- **GIVEN** a task configured with retries and a `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **AND** the `shouldRetry` predicate returns `false` for that error
+- **THEN** the system SHALL NOT retry the task.
+- **AND** the task status SHALL be immediately marked as 'failure'.
+
+#### Scenario: Default retry behavior
+- **GIVEN** a task configured with retries but NO `shouldRetry` predicate
+- **WHEN** the task fails with an error
+- **THEN** the system SHALL retry the task (respecting attempt limits and delays), preserving backward compatibility.

package/openspec/changes/feat-conditional-retries/tasks.md

@@ -0,0 +1,37 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update TaskRetryConfig Interface**
+  - Modify `src/contracts/TaskRetryConfig.ts`.
+  - Add `shouldRetry?: (error: unknown) => boolean;` to the `TaskRetryConfig` interface.
+  - Document the property with JSDoc explaining its purpose (return true to retry, false to abort).
+
+- [ ] **Task 2: Update RetryingExecutionStrategy Logic**
+  - Modify `src/strategies/RetryingExecutionStrategy.ts`.
+  - Inside the `execute` loop, after receiving a "failure" result:
+    - Check if `config.shouldRetry` is defined.
+    - If defined, call it with `result.error`.
+    - If it returns `false`, break the loop and return the failure result immediately.
+    - If it returns `true` (or is undefined), proceed with the existing retry logic (check attempts, delay).
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/strategies/RetryingExecutionStrategy.conditional.test.ts` (or add to existing test file if small).
+  - **Scenario 1**: `shouldRetry` returns `true`.
+    - Setup a task that fails 2 times then succeeds.
+    - Configure `shouldRetry: () => true`.
+    - Verify it retries and eventually succeeds.
+  - **Scenario 2**: `shouldRetry` returns `false`.
+    - Setup a task that fails with a specific error "FatalError".
+    - Configure `shouldRetry: (err) => err !== "FatalError"`.
+    - Verify it does *not* retry and returns failure immediately after the first attempt.
+  - **Scenario 3**: `shouldRetry` is undefined (Legacy behavior).
+    - Setup a failing task.
+    - Verify it retries up to max attempts.
+
+- [ ] **Task 4: Integration Test**
+  - Create `tests/integration-tests/conditional-retries.test.ts`.
+  - Define a workflow with two tasks:
+    - Task A: Fails with "Transient" error (retries allowed).
+    - Task B: Fails with "Permanent" error (retries blocked by predicate).
+  - Execute workflow.
+  - Verify Task A consumed its retries (or succeeded).
+  - Verify Task B failed immediately (did not consume retries).

package/openspec/changes/feat-state-persistence/specs/task-runner/spec.md

@@ -0,0 +1,47 @@
+# Workflow State Persistence Specification
+
+## Purpose
+
+Enables the `TaskRunner` to save its execution state and resume from that state later, allowing for recovery from failures or pausing long-running workflows without re-executing completed tasks.
+
+## Requirements
+
+### Requirement: State Snapshot Exposure
+
+The system SHALL provide a mechanism to retrieve the current execution state of a workflow.
+
+#### Scenario: Retrieving state from TaskRunner 
+- **WHEN** a workflow is running or completed
+- **THEN** the `TaskRunner` (or its underlying `TaskStateManager`) SHALL expose a method to retrieve a snapshot of the current state.
+- **AND** the snapshot SHALL contain the `results` of all executed tasks.
+- **AND** the snapshot SHALL be serializable (e.g., to JSON).
+
+### Requirement: Hydrated Initialization
+
+The system SHALL allow initializing a `TaskRunner` with a pre-existing state snapshot.
+
+#### Scenario: Initializing with a snapshot
+- **GIVEN** a valid state snapshot from a previous execution
+- **WHEN** the `TaskRunner` is built using `TaskRunnerBuilder`
+- **THEN** the builder SHALL accept the snapshot as an initial state.
+- **AND** the `TaskRunner` SHALL start with the internal state reflecting the snapshot (i.e., known task results).
+
+### Requirement: Resumable Execution Logic
+
+The `WorkflowExecutor` SHALL respect the initial hydrated state during execution, skipping already completed tasks.
+
+#### Scenario: Skipping successful tasks
+- **GIVEN** a `TaskRunner` initialized with a snapshot where Task A is marked as `success`
+- **WHEN** `execute()` is called
+- **THEN** Task A SHALL NOT be executed again.
+- **AND** Task A SHALL be considered completed for the purpose of checking dependencies of downstream tasks.
+
+#### Scenario: Re-running non-successful tasks
+- **GIVEN** a `TaskRunner` initialized with a snapshot where Task B is marked as `failure`, `cancelled`, or `skipped`
+- **WHEN** `execute()` is called
+- **THEN** Task B SHOULD be evaluated for execution (subject to dependency checks).
+
+#### Scenario: Handling Context
+- **GIVEN** a resumed workflow
+- **THEN** it is the caller's responsibility to provide the necessary `Context` for task execution.
+- **AND** the `TaskRunner` SHALL NOT attempt to automatically restore the context object from the state snapshot (as it may contain non-serializable data).

package/openspec/changes/feat-task-loop/proposal.md

@@ -0,0 +1,22 @@
+# Change: feat-task-loop
+
+## Why
+
+Users often need to orchestrate tasks that involve waiting for a condition to be met, such as polling an API for a deployment status or waiting for a database to be healthy. Currently, this logic must be implemented imperatively within the `run` method of a task, which obscures the intent and mixes orchestration concerns with business logic.
+
+## What Changes
+
+- Add a `loop` configuration to the `TaskStep` interface.
+- Introduce a `LoopingExecutionStrategy` that wraps other strategies to handle conditional re-execution.
+- The `loop` configuration will support:
+    - `interval`: Time in milliseconds to wait between iterations.
+    - `maxIterations`: Maximum number of times to run the task.
+    - `until`: A predicate function `(context, result) => boolean` that determines when the loop should stop.
+
+## Impact
+
+- **Affected Specs**: `task-runner`
+- **Affected Code**:
+    - `src/TaskStep.ts`: Update interface.
+    - `src/strategies/LoopingExecutionStrategy.ts`: New file.
+    - `src/TaskRunnerBuilder.ts`: Integrate the new strategy.

package/openspec/changes/feat-task-loop/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Task Looping
+
+The `TaskStep` interface SHALL support an optional `loop` property of type `TaskLoopConfig` to enable conditional re-execution of a task (polling).
+
+#### Scenario: Loop until condition met
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the `loop.until` predicate returns `false`
+- **THEN** the task SHALL re-execute after the specified `interval`.
+- **WHEN** the `loop.until` predicate returns `true`
+- **THEN** the task SHALL complete successfully with the last result.
+
+#### Scenario: Max iterations reached
+
+- **GIVEN** a task with a `loop` configuration
+- **AND** the task has re-executed `maxIterations` times without the predicate returning `true`
+- **THEN** the task SHALL fail with an error indicating the loop limit was reached.
+
+#### Scenario: Integration with Retries
+
+- **GIVEN** a task with both `retry` and `loop` configurations
+- **WHEN** the task fails (throws an error)
+- **THEN** the `RetryingExecutionStrategy` SHALL handle the retry logic first.
+- **AND** the loop iteration SHALL only count once the task executes successfully (or fails after retries).
+
+#### Scenario: Loop Config Structure
+
+- **GIVEN** a `TaskLoopConfig` object
+- **THEN** it SHALL support:
+  - `interval`: Time in milliseconds to wait between iterations (default: 0).
+  - `maxIterations`: Maximum number of iterations (default: 1).
+  - `until`: A predicate function `(context: TContext, result: TaskResult) => boolean`.

package/openspec/changes/feat-task-loop/tasks.md

@@ -0,0 +1,8 @@
+## 1. Implementation
+
+- [ ] 1.1 Define `TaskLoopConfig` interface in `src/contracts/TaskLoopConfig.ts`.
+- [ ] 1.2 Update `TaskStep` interface in `src/TaskStep.ts` to include optional `loop: TaskLoopConfig`.
+- [ ] 1.3 Implement `LoopingExecutionStrategy` in `src/strategies/LoopingExecutionStrategy.ts`.
+- [ ] 1.4 Update `TaskRunnerBuilder` in `src/TaskRunnerBuilder.ts` to include `LoopingExecutionStrategy`.
+- [ ] 1.5 Add unit tests for `LoopingExecutionStrategy`.
+- [ ] 1.6 Verify integration with `RetryingExecutionStrategy` (looping should happen outside retries).

package/openspec/specs/plugin-context/spec.md

@@ -0,0 +1,19 @@
+# plugin-context Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Expose EventBus to plugins
+
+The `PluginContext` passed to `install` MUST expose the `EventBus` (or equivalent API) to allow listening to events.
+
+#### Scenario: Listening to task events
+Given a plugin is being installed
+When it accesses `context.events`
+Then it can subscribe to `taskStart` and `taskEnd` events
+
+#### Scenario: Emitting custom events (Future)
+Given a plugin
+When it has access to the event bus
+Then it should be able to emit events (if allowed by design)
+

package/openspec/specs/plugin-loading/spec.md

@@ -0,0 +1,29 @@
+# plugin-loading Specification
+
+## Purpose
+TBD - created by archiving change implement-plugin-system. Update Purpose after archive.
+## Requirements
+### Requirement: Support registering plugins
+
+The `TaskRunner` MUST allow registering plugins via a `use` method or configuration.
+
+#### Scenario: Registering a valid plugin
+Given a `TaskRunner` instance
+When I call `use` with a valid plugin object
+Then the plugin is added to the internal plugin list
+
+#### Scenario: Registering an invalid plugin
+Given a `TaskRunner` instance
+When I call `use` with an invalid object (missing install method)
+Then it should throw an error or reject the plugin
+
+### Requirement: Initialize plugins before execution
+
+Plugins MUST be initialized (have their `install` method called) before the workflow starts.
+
+#### Scenario: Plugin initialization
+Given a registered plugin
+When `execute` is called on the `TaskRunner`
+Then the plugin's `install` method is called with the plugin context
+And the workflow execution proceeds only after `install` completes
+

package/openspec/specs/release-pr/spec.md

@@ -0,0 +1,31 @@
+# release-pr Specification
+
+## Purpose
+TBD - created by archiving change adopt-release-pr. Update Purpose after archive.
+## Requirements
+### Requirement: Release PR Generation
+The system MUST automatically maintain a "Release PR" that targets the `main` branch. This PR must accumulate all conventional changes since the last release, calculating the next semantic version and generating a corresponding changelog entry.
+
+#### Scenario: Feature commit triggers PR update
+Given the latest release is `v1.0.0`
+And a developer merges a commit with message `feat: add awesome feature` to `main`
+Then the system should create or update the Release PR
+And the PR title should be `chore: release 1.1.0`
+And the PR body should contain the changelog entry for "add awesome feature"
+And the `package.json` version in the PR should be `1.1.0`
+
+#### Scenario: Fix commit triggers patch update
+Given the latest release is `v1.0.0`
+And a developer merges a commit `fix: urgent bug` to `main`
+Then the Release PR should be updated to target version `1.0.1`
+
+### Requirement: Release Publication
+The system MUST execute the release process (git tag, GitHub Release, npm publish) ONLY when the Release PR is merged into `main`.
+
+#### Scenario: Merge triggers publish
+Given the Release PR for `v1.1.0` exists
+When a maintainer merges the PR into `main`
+Then the system should create a GitHub Release `v1.1.0`
+And the system should publish the package to the configured registry (NPM)
+And the system should NOT publish any other commits merged to `main` until the next Release PR merge
+

package/openspec/specs/task-runner/spec.md

@@ -160,3 +160,15 @@ The system SHALL provide a `RetryingExecutionStrategy` that implements `IExecuti
 
 - **WHEN** `retry.backoff` is 'exponential'
 - **THEN** the delay SHALL increase for each attempt (e.g., `delay * 2^attempt`).
+
+### Requirement: Task Execution Metrics
+
+The system SHALL record timing metrics for each executed task, including start time, end time, and duration.
+
+#### Scenario: Successful execution
+- **WHEN** a task completes successfully
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds
+
+#### Scenario: Failed execution
+- **WHEN** a task fails
+- **THEN** the task result contains the start timestamp, end timestamp, and duration in milliseconds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "4.0.4",
+  "version": "4.2.0",
   "description": "A lightweight, type-safe, and domain-agnostic task orchestration engine. It resolves a Directed Acyclic Graph (DAG) of steps, executes independent tasks in parallel, and manages a shared context across the pipeline.",
   "repository": {
     "type": "git",

package/src/EventBus.ts

@@ -61,11 +61,10 @@ export class EventBus<TContext> {
       | undefined;
     if (listeners) {
       for (const listener of listeners) {
-        // We use Promise.resolve().then() to schedule the listener on the microtask queue,
+        // We use queueMicrotask() to schedule the listener on the microtask queue,
         // ensuring the emit method remains non-blocking.
-        // The final .catch() ensures that any errors in the promise infrastructure itself are logged.
-        Promise.resolve()
-          .then(() => {
+        queueMicrotask(() => {
+          try {
             try {
               const result = listener(data);
               if (result instanceof Promise) {
@@ -84,14 +83,14 @@ export class EventBus<TContext> {
                 error
               );
             }
-          })
-          .catch((error) => {
-            // detailed handling for the promise chain itself
+          } catch (error) {
+            // detailed handling for the microtask execution itself
             console.error(
               `Unexpected error in event bus execution for ${String(event)}:`,
               error
             );
-          });
+          }
+        });
       }
     }
   }

package/src/PluginManager.ts

@@ -0,0 +1,41 @@
+import { Plugin, PluginContext } from "./contracts/Plugin.js";
+
+/**
+ * Manages the lifecycle of plugins.
+ */
+export class PluginManager<TContext> {
+  private plugins: Plugin<TContext>[] = [];
+
+  constructor(private context: PluginContext<TContext>) {}
+
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register.
+   */
+  public use(plugin: Plugin<TContext>): void {
+    // Check if plugin is already registered
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      // For now, we allow overwriting or just warn?
+      // Let's just allow it but maybe log it if we had a logger.
+      // Strict check: don't allow duplicate names.
+      throw new Error(`Plugin with name '${plugin.name}' is already registered.`);
+    }
+    this.plugins.push(plugin);
+  }
+
+  /**
+   * Initializes all registered plugins.
+   */
+  public async initialize(): Promise<void> {
+    for (const plugin of this.plugins) {
+      await plugin.install(this.context);
+    }
+  }
+
+  /**
+   * Returns the list of registered plugins.
+   */
+  public getPlugins(): ReadonlyArray<Plugin<TContext>> {
+    return this.plugins;
+  }
+}

package/src/TaskGraphValidator.ts

@@ -1,7 +1,7 @@
 import { ITaskGraphValidator } from "./contracts/ITaskGraphValidator.js";
 import { ValidationResult } from "./contracts/ValidationResult.js";
 import { ValidationError } from "./contracts/ValidationError.js";
-import { TaskGraph } from "./TaskGraph.js";
+import { TaskGraph, Task } from "./TaskGraph.js";
 import {
   ERROR_CYCLE,
   ERROR_DUPLICATE_TASK,
@@ -22,11 +22,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
   validate(taskGraph: TaskGraph): ValidationResult {
     const errors: ValidationError[] = [];
 
-    // 1. Check for duplicate tasks
-    const taskIds = this.checkDuplicateTasks(taskGraph, errors);
+    // 1. Build Map and Check Duplicates (Single Pass)
+    const taskMap = this.buildTaskMapAndCheckDuplicates(taskGraph, errors);
 
     // 2. Check for missing dependencies
-    this.checkMissingDependencies(taskGraph, taskIds, errors);
+    this.checkMissingDependencies(taskGraph, taskMap, errors);
 
     // 3. Check for cycles
     // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
@@ -35,7 +35,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     );
 
     if (!hasMissingDependencies) {
-      this.checkCycles(taskGraph, errors);
+      this.checkCycles(taskGraph, taskMap, errors);
     }
 
     return {
@@ -54,33 +54,33 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     return `Task graph validation failed: ${errorDetails.join("; ")}`;
   }
 
-  private checkDuplicateTasks(
+  private buildTaskMapAndCheckDuplicates(
     taskGraph: TaskGraph,
     errors: ValidationError[]
-  ): Set<string> {
-    const taskIds = new Set<string>();
+  ): Map<string, Task> {
+    const taskMap = new Map<string, Task>();
     for (const task of taskGraph.tasks) {
-      if (taskIds.has(task.id)) {
+      if (taskMap.has(task.id)) {
         errors.push({
           type: ERROR_DUPLICATE_TASK,
           message: `Duplicate task detected with ID: ${task.id}`,
           details: { taskId: task.id },
         });
       } else {
-        taskIds.add(task.id);
+        taskMap.set(task.id, task);
       }
     }
-    return taskIds;
+    return taskMap;
   }
 
   private checkMissingDependencies(
     taskGraph: TaskGraph,
-    taskIds: Set<string>,
+    taskMap: Map<string, Task>,
     errors: ValidationError[]
   ): void {
     for (const task of taskGraph.tasks) {
       for (const dependenceId of task.dependencies) {
-        if (!taskIds.has(dependenceId)) {
+        if (!taskMap.has(dependenceId)) {
           errors.push({
             type: ERROR_MISSING_DEPENDENCY,
             message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
@@ -91,13 +91,11 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     }
   }
 
-  private checkCycles(taskGraph: TaskGraph, errors: ValidationError[]): void {
-    // Build adjacency list
-    const adjacencyList = new Map<string, string[]>();
-    for (const task of taskGraph.tasks) {
-      adjacencyList.set(task.id, task.dependencies);
-    }
-
+  private checkCycles(
+    taskGraph: TaskGraph,
+    taskMap: Map<string, Task>,
+    errors: ValidationError[]
+  ): void {
     const visited = new Set<string>();
     const recursionStack = new Set<string>();
 
@@ -108,7 +106,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
 
       const path: string[] = [];
       if (
-        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+        this.detectCycle(task.id, path, visited, recursionStack, taskMap)
       ) {
         // 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)
@@ -132,7 +130,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     path: string[],
     visited: Set<string>,
     recursionStack: Set<string>,
-    adjacencyList: Map<string, string[]>
+    taskMap: Map<string, Task>
   ): boolean {
     // Use an explicit stack to avoid maximum call stack size exceeded errors
     const stack: { taskId: string; index: number; dependencies: string[] }[] =
@@ -145,7 +143,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
     stack.push({
       taskId: startTaskId,
       index: 0,
-      dependencies: adjacencyList.get(startTaskId)!,
+      dependencies: taskMap.get(startTaskId)!.dependencies,
     });
 
     while (stack.length > 0) {
@@ -170,7 +168,7 @@ export class TaskGraphValidator implements ITaskGraphValidator {
           stack.push({
             taskId: dependenceId,
             index: 0,
-            dependencies: adjacencyList.get(dependenceId)!,
+            dependencies: taskMap.get(dependenceId)!.dependencies,
           });
         }
       } else {

package/src/TaskResult.ts

@@ -12,4 +12,13 @@ export interface TaskResult {
   error?: string;
   /** Optional data produced by the step for later inspection. */
   data?: unknown;
+  /** Optional execution metrics for the task. */
+  metrics?: {
+    /** Start time in milliseconds (performance.now). */
+    startTime: number;
+    /** End time in milliseconds (performance.now). */
+    endTime: number;
+    /** Duration in milliseconds. */
+    duration: number;
+  };
 }