@calmo/task-runner 3.1.0 → 3.3.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,yBAAyB,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/strategies/RetryingExecutionStrategy.d.ts

@@ -0,0 +1,12 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Execution strategy that retries tasks upon failure based on their retry configuration.
+ */
+export declare class RetryingExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+    private innerStrategy;
+    constructor(innerStrategy: IExecutionStrategy<TContext>);
+    execute(step: TaskStep<TContext>, context: TContext, signal?: AbortSignal): Promise<TaskResult>;
+    private sleep;
+}

package/dist/strategies/RetryingExecutionStrategy.js

@@ -0,0 +1,74 @@
+/**
+ * Execution strategy that retries tasks upon failure based on their retry configuration.
+ */
+export class RetryingExecutionStrategy {
+    innerStrategy;
+    constructor(innerStrategy) {
+        this.innerStrategy = innerStrategy;
+    }
+    async execute(step, context, signal) {
+        const config = step.retry;
+        if (!config) {
+            return this.innerStrategy.execute(step, context, signal);
+        }
+        let attempt = 0;
+        while (true) {
+            // Check for cancellation before execution
+            if (signal?.aborted) {
+                return {
+                    status: "cancelled",
+                    message: "Task cancelled before execution",
+                };
+            }
+            const result = await this.innerStrategy.execute(step, context, signal);
+            if (result.status === "success" || result.status === "cancelled" || result.status === "skipped") {
+                return result;
+            }
+            // Task failed, check if we should retry
+            if (attempt >= config.attempts) {
+                return result; // Max attempts reached, return failure
+            }
+            attempt++;
+            // Calculate delay
+            let delay = config.delay;
+            if (config.backoff === "exponential") {
+                delay = config.delay * Math.pow(2, attempt - 1);
+            }
+            // Wait for delay, respecting cancellation
+            try {
+                await this.sleep(delay, signal);
+            }
+            catch (e) {
+                if (signal?.aborted) {
+                    return {
+                        status: "cancelled",
+                        message: "Task cancelled during retry delay",
+                    };
+                }
+                throw e;
+            }
+        }
+    }
+    sleep(ms, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new Error("AbortError"));
+                return;
+            }
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, ms);
+            const onAbort = () => {
+                clearTimeout(timer);
+                cleanup();
+                reject(new Error("AbortError"));
+            };
+            const cleanup = () => {
+                signal?.removeEventListener("abort", onAbort);
+            };
+            signal?.addEventListener("abort", onAbort);
+        });
+    }
+}
+//# sourceMappingURL=RetryingExecutionStrategy.js.map

package/dist/strategies/RetryingExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetryingExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/RetryingExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,yBAAyB;IAChB;IAApB,YAAoB,aAA2C;QAA3C,kBAAa,GAAb,aAAa,CAA8B;IAAG,CAAC;IAEnE,KAAK,CAAC,OAAO,CACX,IAAwB,EACxB,OAAiB,EACjB,MAAoB;QAEpB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3D,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,OAAO,IAAI,EAAE,CAAC;YACZ,0CAA0C;YAC1C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,OAAO;oBACL,MAAM,EAAE,WAAW;oBACnB,OAAO,EAAE,iCAAiC;iBAC3C,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YAEvE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAChG,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,wCAAwC;YACxC,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBAC/B,OAAO,MAAM,CAAC,CAAC,uCAAuC;YACxD,CAAC;YAED,OAAO,EAAE,CAAC;YAEV,kBAAkB;YAClB,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;YACzB,IAAI,MAAM,CAAC,OAAO,KAAK,aAAa,EAAE,CAAC;gBACrC,KAAK,GAAG,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;YAClD,CAAC;YAED,0CAA0C;YAC1C,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACb,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACpB,OAAO;wBACL,MAAM,EAAE,WAAW;wBACnB,OAAO,EAAE,mCAAmC;qBAC7C,CAAC;gBACJ,CAAC;gBACD,MAAM,CAAC,CAAC;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,EAAU,EAAE,MAAoB;QAC5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;gBAChC,OAAO;YACT,CAAC;YAED,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,OAAO,EAAE,CAAC;gBACV,OAAO,EAAE,CAAC;YACZ,CAAC,EAAE,EAAE,CAAC,CAAC;YAEP,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,EAAE,CAAC;gBACV,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;YAClC,CAAC,CAAC;YAEF,MAAM,OAAO,GAAG,GAAG,EAAE;gBACnB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChD,CAAC,CAAC;YAEF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

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

@@ -0,0 +1,10 @@
+## 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.
+- [x] 1.4 Implement retry loop/recursion checking `attempts` count.
+- [x] 1.5 Implement delay logic with support for `fixed` and `exponential` backoff.
+- [x] 1.6 Ensure `TaskResult` reflects the final status after retries (success if eventually succeeds, failure if all attempts fail).
+- [x] 1.7 Add unit tests for successful retry after failure.
+- [x] 1.8 Add unit tests for exhaustion of retry attempts (final failure).
+- [x] 1.9 Add unit tests for backoff timing (mock timers).

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

@@ -0,0 +1,7 @@
+## 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`).
+- [x] 1.4 Ensure `dryRun` respects other configs like `concurrency` (if applicable) to simulate actual timing/order if possible, or just strict topological order.
+- [x] 1.5 Add unit tests for `dryRun` ensuring no side effects occur.
+- [x] 1.6 Add unit tests for `getMermaidGraph` output correctness (nodes and edges).

package/openspec/project.md

@@ -23,6 +23,7 @@ The project follows a modular architecture with distinct components for managing
 -   **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`

package/package.json

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

package/src/TaskRunner.ts

@@ -9,6 +9,7 @@ import { TaskRunnerExecutionConfig } from "./TaskRunnerExecutionConfig.js";
 import { TaskStateManager } from "./TaskStateManager.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+import { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
 import { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
 
 // Re-export types for backward compatibility
@@ -22,7 +23,9 @@ export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
 export class TaskRunner<TContext> {
   private eventBus = new EventBus<TContext>();
   private validator = new TaskGraphValidator();
-  private executionStrategy: IExecutionStrategy<TContext> = new StandardExecutionStrategy();
+  private executionStrategy: IExecutionStrategy<TContext> = new RetryingExecutionStrategy(
+    new StandardExecutionStrategy()
+  );
 
   /**
    * @param context The shared context object to be passed to each task.
@@ -149,7 +152,8 @@ export class TaskRunner<TContext> {
       this.context,
       this.eventBus,
       stateManager,
-      strategy
+      strategy,
+      config?.concurrency
     );
 
     // We need to handle the timeout cleanup properly.

package/src/TaskRunnerExecutionConfig.ts

@@ -15,4 +15,9 @@ export interface TaskRunnerExecutionConfig {
    * Useful for verifying the execution order and graph structure.
    */
   dryRun?: boolean;
+  /**
+   * The maximum number of tasks to run concurrently.
+   * If undefined, all ready tasks will be run in parallel.
+   */
+  concurrency?: number;
 }

package/src/TaskStep.ts

@@ -1,4 +1,5 @@
 import { TaskResult } from "./TaskResult.js";
+import { TaskRetryConfig } from "./contracts/TaskRetryConfig.js";
 
 /**
  * Represents a single, executable step within a workflow.
@@ -9,6 +10,8 @@ export interface TaskStep<TContext> {
   name: string;
   /** An optional list of task names that must complete successfully before this step can run. */
   dependencies?: string[];
+  /** Optional retry configuration for the task. */
+  retry?: TaskRetryConfig;
   /**
    * The core logic of the task.
    * @param context The shared context object, allowing for state to be passed between tasks.

package/src/WorkflowExecutor.ts

@@ -9,17 +9,21 @@ import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
  * @template TContext The shape of the shared context object.
  */
 export class WorkflowExecutor<TContext> {
+  private readyQueue: TaskStep<TContext>[] = [];
+
   /**
    * @param context The shared context object.
    * @param eventBus The event bus to emit events.
    * @param stateManager Manages execution state.
    * @param strategy Execution strategy.
+   * @param concurrency Maximum number of concurrent tasks.
    */
   constructor(
     private context: TContext,
     private eventBus: EventBus<TContext>,
     private stateManager: TaskStateManager<TContext>,
-    private strategy: IExecutionStrategy<TContext>
+    private strategy: IExecutionStrategy<TContext>,
+    private concurrency?: number
   ) {}
 
   /**
@@ -100,10 +104,24 @@ export class WorkflowExecutor<TContext> {
     executingPromises: Set<Promise<void>>,
     signal?: AbortSignal
   ): void {
-    const toRun = this.stateManager.processDependencies();
+    const newlyReady = this.stateManager.processDependencies();
+
+    // Add newly ready tasks to the queue
+    for (const task of newlyReady) {
+      this.readyQueue.push(task);
+    }
+
+    // Execute ready tasks while respecting concurrency limit
+    while (this.readyQueue.length > 0) {
+      if (
+        this.concurrency !== undefined &&
+        executingPromises.size >= this.concurrency
+      ) {
+        break;
+      }
+
+      const step = this.readyQueue.shift()!;
 
-    // Execute ready tasks
-    for (const step of toRun) {
       this.stateManager.markRunning(step);
 
       const taskPromise = this.strategy.execute(step, this.context, signal)
@@ -112,6 +130,8 @@ export class WorkflowExecutor<TContext> {
         })
         .finally(() => {
              executingPromises.delete(taskPromise);
+             // When a task finishes, we try to run more
+             this.processLoop(executingPromises, signal);
         });
 
       executingPromises.add(taskPromise);

package/src/contracts/TaskRetryConfig.ts

@@ -0,0 +1,8 @@
+export interface TaskRetryConfig {
+  /** Number of retries (excluding the initial run). */
+  attempts: number;
+  /** Delay in milliseconds between retries. */
+  delay: number;
+  /** Backoff strategy: 'fixed' (default) or 'exponential'. */
+  backoff?: "fixed" | "exponential";
+}

package/src/index.ts

@@ -2,7 +2,9 @@ export { TaskRunner } from "./TaskRunner.js";
 export { TaskRunnerBuilder } from "./TaskRunnerBuilder.js";
 export { TaskStateManager } from "./TaskStateManager.js";
 export { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+export { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
 export type { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
+export type { TaskRetryConfig } from "./contracts/TaskRetryConfig.js";
 export type { TaskStep } from "./TaskStep.js";
 export type { TaskResult } from "./TaskResult.js";
 export type { TaskStatus } from "./TaskStatus.js";

package/src/strategies/RetryingExecutionStrategy.ts

@@ -0,0 +1,90 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+
+/**
+ * Execution strategy that retries tasks upon failure based on their retry configuration.
+ */
+export class RetryingExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+  constructor(private innerStrategy: IExecutionStrategy<TContext>) {}
+
+  async execute(
+    step: TaskStep<TContext>,
+    context: TContext,
+    signal?: AbortSignal
+  ): Promise<TaskResult> {
+    const config = step.retry;
+    if (!config) {
+      return this.innerStrategy.execute(step, context, signal);
+    }
+
+    let attempt = 0;
+    while (true) {
+      // Check for cancellation before execution
+      if (signal?.aborted) {
+        return {
+          status: "cancelled",
+          message: "Task cancelled before execution",
+        };
+      }
+
+      const result = await this.innerStrategy.execute(step, context, signal);
+
+      if (result.status === "success" || result.status === "cancelled" || result.status === "skipped") {
+        return result;
+      }
+
+      // Task failed, check if we should retry
+      if (attempt >= config.attempts) {
+        return result; // Max attempts reached, return failure
+      }
+
+      attempt++;
+
+      // Calculate delay
+      let delay = config.delay;
+      if (config.backoff === "exponential") {
+        delay = config.delay * Math.pow(2, attempt - 1);
+      }
+
+      // Wait for delay, respecting cancellation
+      try {
+        await this.sleep(delay, signal);
+      } catch (e) {
+      if (signal?.aborted) {
+        return {
+          status: "cancelled",
+          message: "Task cancelled during retry delay",
+        };
+      }
+      throw e;
+      }
+    }
+  }
+
+  private sleep(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error("AbortError"));
+        return;
+      }
+
+      const timer = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, ms);
+
+      const onAbort = () => {
+        clearTimeout(timer);
+        cleanup();
+        reject(new Error("AbortError"));
+      };
+
+      const cleanup = () => {
+        signal?.removeEventListener("abort", onAbort);
+      };
+
+      signal?.addEventListener("abort", onAbort);
+    });
+  }
+}