@calmo/task-runner 3.0.0 → 3.1.0

package/dist/TaskRunner.d.ts

@@ -36,6 +36,18 @@ export declare class TaskRunner<TContext> {
      * @returns The TaskRunner instance for chaining.
      */
     setExecutionStrategy(strategy: IExecutionStrategy<TContext>): this;
+    /**
+     * Generates a Mermaid.js graph representation of the task workflow.
+     * @param steps The list of tasks to visualize.
+     * @returns A string containing the Mermaid graph definition.
+     */
+    static getMermaidGraph<T>(steps: TaskStep<T>[]): string;
+    /**
+     * Sanitizes a string for use as a Mermaid node ID.
+     * @param id The string to sanitize.
+     * @returns The sanitized string.
+     */
+    private static sanitizeMermaidId;
     /**
      * Executes a list of tasks, respecting their dependencies and running
      * independent tasks in parallel.

package/dist/TaskRunner.js

@@ -3,6 +3,7 @@ import { EventBus } from "./EventBus.js";
 import { WorkflowExecutor } from "./WorkflowExecutor.js";
 import { TaskStateManager } from "./TaskStateManager.js";
 import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
+import { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -46,6 +47,45 @@ export class TaskRunner {
         this.executionStrategy = strategy;
         return this;
     }
+    /**
+     * Generates a Mermaid.js graph representation of the task workflow.
+     * @param steps The list of tasks to visualize.
+     * @returns A string containing the Mermaid graph definition.
+     */
+    static getMermaidGraph(steps) {
+        const graphLines = ["graph TD"];
+        // Helper to sanitize node names or wrap them if needed
+        // For simplicity, we just wrap in quotes and use the name as ID if it's simple
+        // or generate an ID if strictly needed. Here we assume names are unique IDs.
+        // We will wrap names in quotes for the label, but use the name as the ID.
+        // Actually, Mermaid ID cannot have spaces without quotes.
+        const safeId = (name) => JSON.stringify(name);
+        const sanitize = (name) => this.sanitizeMermaidId(name);
+        // Add all nodes first to ensure they exist
+        for (const step of steps) {
+            // Using the name as both ID and Label for simplicity
+            // Format: ID["Label"]
+            // safeId returns a quoted string (e.g. "Task Name"), so we use it directly as the label
+            graphLines.push(`  ${sanitize(step.name)}[${safeId(step.name)}]`);
+        }
+        // Add edges
+        for (const step of steps) {
+            if (step.dependencies) {
+                for (const dep of step.dependencies) {
+                    graphLines.push(`  ${sanitize(dep)} --> ${sanitize(step.name)}`);
+                }
+            }
+        }
+        return [...new Set(graphLines)].join("\n");
+    }
+    /**
+     * Sanitizes a string for use as a Mermaid node ID.
+     * @param id The string to sanitize.
+     * @returns The sanitized string.
+     */
+    static sanitizeMermaidId(id) {
+        return id.replaceAll(/ /g, "_").replaceAll(/:/g, "_").replaceAll(/"/g, "_");
+    }
     /**
      * Executes a list of tasks, respecting their dependencies and running
      * independent tasks in parallel.
@@ -67,7 +107,11 @@ export class TaskRunner {
             throw new Error(this.validator.createErrorMessage(validationResult));
         }
         const stateManager = new TaskStateManager(this.eventBus);
-        const executor = new WorkflowExecutor(this.context, this.eventBus, stateManager, this.executionStrategy);
+        let strategy = this.executionStrategy;
+        if (config?.dryRun) {
+            strategy = new DryRunExecutionStrategy();
+        }
+        const executor = new WorkflowExecutor(this.context, this.eventBus, stateManager, strategy);
         // We need to handle the timeout cleanup properly.
         if (config?.timeout !== undefined) {
             const controller = new AbortController();

package/dist/TaskRunner.js.map

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

package/dist/TaskRunnerExecutionConfig.d.ts

@@ -10,4 +10,9 @@ export interface TaskRunnerExecutionConfig {
      * A timeout in milliseconds for the entire workflow.
      */
     timeout?: number;
+    /**
+     * If true, the runner will simulate execution without running the actual tasks.
+     * Useful for verifying the execution order and graph structure.
+     */
+    dryRun?: boolean;
 }

package/dist/strategies/DryRunExecutionStrategy.d.ts

@@ -0,0 +1,16 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+/**
+ * Execution strategy that simulates task execution without running the actual logic.
+ */
+export declare class DryRunExecutionStrategy<TContext> implements IExecutionStrategy<TContext> {
+    /**
+     * Simulates execution by returning a success result immediately.
+     * @param step The task step (ignored).
+     * @param context The shared context (ignored).
+     * @param signal Optional abort signal (ignored).
+     * @returns A promise resolving to a success result.
+     */
+    execute(_step: TaskStep<TContext>, _context: TContext, _signal?: AbortSignal): Promise<TaskResult>;
+}

package/dist/strategies/DryRunExecutionStrategy.js

@@ -0,0 +1,25 @@
+/**
+ * Execution strategy that simulates task execution without running the actual logic.
+ */
+export class DryRunExecutionStrategy {
+    /**
+     * Simulates execution by returning a success result immediately.
+     * @param step The task step (ignored).
+     * @param context The shared context (ignored).
+     * @param signal Optional abort signal (ignored).
+     * @returns A promise resolving to a success result.
+     */
+    async execute(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _step, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _context, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _signal) {
+        return Promise.resolve({
+            status: "success",
+            message: "Dry run: simulated success",
+        });
+    }
+}
+//# sourceMappingURL=DryRunExecutionStrategy.js.map

package/dist/strategies/DryRunExecutionStrategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DryRunExecutionStrategy.js","sourceRoot":"","sources":["../../src/strategies/DryRunExecutionStrategy.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAGlC;;;;;;OAMG;IACH,KAAK,CAAC,OAAO;IACX,6DAA6D;IAC7D,KAAyB;IACzB,6DAA6D;IAC7D,QAAkB;IAClB,6DAA6D;IAC7D,OAAqB;QAErB,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,4BAA4B;SACtC,CAAC,CAAC;IACL,CAAC;CACF"}

package/openspec/changes/add-concurrency-control/proposal.md

@@ -4,11 +4,11 @@
 The current implementation executes *all* independent tasks in parallel. In large graphs with many independent nodes, this could overwhelm system resources (CPU, memory) or trigger external API rate limits.
 
 ## What Changes
-- Add a concurrency control mechanism to the `TaskRunner`.
-- Add `concurrency: number` to the `TaskRunnerExecutionConfig`.
-- Implement a task queue to hold tasks that are ready but waiting for a free slot.
-- Update `WorkflowExecutor` to respect the concurrency limit.
+- Add `concurrency: number` optional property to `WorkflowExecutor`.
+- Modify `WorkflowExecutor.processLoop` to respect the concurrency limit.
+    - Track the active promise count.
+    - Only start new tasks from the ready queue if `active < concurrency`.
+    - Continue to defer ready tasks until slots open up.
 
 ## Impact
-- Affected specs: `task-runner`
-- Affected code: `src/TaskRunner.ts`, `src/WorkflowExecutor.ts`, `src/TaskRunnerExecutionConfig.ts`
+- **Affected Components**: `WorkflowExecutor`

package/openspec/changes/add-task-retry-policy/proposal.md

@@ -4,10 +4,13 @@
 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
-- Allow tasks to define a retry policy.
-- Update `TaskStep` interface to include optional `retry` configuration.
-- Implement logic in `TaskRunner` (or `WorkflowExecutor`) to catch failures, check the retry policy, and re-execute the task after the specified delay.
+- Add `TaskRetryConfig` interface to define retry behavior (attempts, delay, backoff).
+- Update `TaskStep` interface to include optional `retry: TaskRetryConfig`.
+- Implement `RetryingExecutionStrategy` which decorates any `IExecutionStrategy`.
+  - It catches failures from the inner strategy.
+  - It checks the retry policy.
+  - It waits and re-executes the step if applicable.
 
 ## Impact
-- Affected specs: `task-runner`
-- Affected code: `src/TaskStep.ts`, `src/WorkflowExecutor.ts` (or `TaskRunner.ts`), `src/contracts/TaskRetryConfig.ts`
+- **New Components**: `RetryingExecutionStrategy`, `TaskRetryConfig`
+- **Affected Components**: `TaskStep` (interface update)

package/openspec/changes/add-workflow-preview/proposal.md

@@ -4,9 +4,10 @@
 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 `dryRun` execution mode to `TaskRunner`.
-- Add a helper method `getMermaidGraph(steps)` to generate a Mermaid.js diagram of the dependency graph.
+- 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
-- Affected specs: `task-runner`
-- Affected code: `src/TaskRunner.ts`, `src/TaskRunnerExecutionConfig.ts`
+- **New Components**: `DryRunExecutionStrategy`, `generateMermaidGraph`
+- **Affected Components**: `WorkflowExecutor` (indirectly, via strategy injection)

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

@@ -0,0 +1,25 @@
+# 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.
+
+## ✅ 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.

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

@@ -0,0 +1,27 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update Interface**
+  - Modify `src/TaskStep.ts` to add `timeout?: number;` to the `TaskStep` interface.
+  - Document the property (milliseconds).
+
+- [ ] **Task 2: Add Timeout Logic to StandardExecutionStrategy**
+  - Modify `src/strategies/StandardExecutionStrategy.ts`.
+  - Inside `execute`:
+    - Check if `step.timeout` is defined.
+    - 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**: Clean up the timer (`clearTimeout`) in a `finally` block.
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/strategies/StandardExecutionStrategy.timeout.test.ts`.
+  - Test case: Task finishes before timeout (success).
+  - Test case: Task runs longer than timeout (failure/error).
+  - Test case: Task receives AbortSignal on timeout.
+  - Test case: Global cancellation overrides local timeout.
+
+- [ ] **Task 4: Integration Test**
+  - Update `tests/TaskRunner.test.ts` or create `tests/timeouts.test.ts`.
+  - Define a workflow with a slow task and a short timeout.
+  - Verify that the slow task fails, dependents are skipped, and independent tasks still complete (if any).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.0.0",
+  "version": "3.1.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 { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
 
 // Re-export types for backward compatibility
 export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
@@ -64,6 +65,54 @@ export class TaskRunner<TContext> {
     return this;
   }
 
+  /**
+   * Generates a Mermaid.js graph representation of the task workflow.
+   * @param steps The list of tasks to visualize.
+   * @returns A string containing the Mermaid graph definition.
+   */
+  public static getMermaidGraph<T>(steps: TaskStep<T>[]): string {
+    const graphLines = ["graph TD"];
+
+    // Helper to sanitize node names or wrap them if needed
+    // For simplicity, we just wrap in quotes and use the name as ID if it's simple
+    // or generate an ID if strictly needed. Here we assume names are unique IDs.
+    // We will wrap names in quotes for the label, but use the name as the ID.
+    // Actually, Mermaid ID cannot have spaces without quotes.
+    const safeId = (name: string) => JSON.stringify(name);
+    const sanitize = (name: string) => this.sanitizeMermaidId(name);
+
+
+    // Add all nodes first to ensure they exist
+    for (const step of steps) {
+      // Using the name as both ID and Label for simplicity
+      // Format: ID["Label"]
+      // safeId returns a quoted string (e.g. "Task Name"), so we use it directly as the label
+      graphLines.push(`  ${sanitize(step.name)}[${safeId(step.name)}]`);
+    }
+
+    // Add edges
+    for (const step of steps) {
+      if (step.dependencies) {
+        for (const dep of step.dependencies) {
+          graphLines.push(
+            `  ${sanitize(dep)} --> ${sanitize(step.name)}`
+          );
+        }
+      }
+    }
+
+    return [...new Set(graphLines)].join("\n");
+  }
+
+  /**
+   * Sanitizes a string for use as a Mermaid node ID.
+   * @param id The string to sanitize.
+   * @returns The sanitized string.
+   */
+  private static sanitizeMermaidId(id: string): string {
+    return id.replaceAll(/ /g, "_").replaceAll(/:/g, "_").replaceAll(/"/g, "_");
+  }
+
   /**
    * Executes a list of tasks, respecting their dependencies and running
    * independent tasks in parallel.
@@ -90,11 +139,17 @@ export class TaskRunner<TContext> {
     }
 
     const stateManager = new TaskStateManager(this.eventBus);
+
+    let strategy = this.executionStrategy;
+    if (config?.dryRun) {
+      strategy = new DryRunExecutionStrategy<TContext>();
+    }
+
     const executor = new WorkflowExecutor(
       this.context,
       this.eventBus,
       stateManager,
-      this.executionStrategy
+      strategy
     );
 
     // We need to handle the timeout cleanup properly.

package/src/TaskRunnerExecutionConfig.ts

@@ -10,4 +10,9 @@ export interface TaskRunnerExecutionConfig {
    * A timeout in milliseconds for the entire workflow.
    */
   timeout?: number;
+  /**
+   * If true, the runner will simulate execution without running the actual tasks.
+   * Useful for verifying the execution order and graph structure.
+   */
+  dryRun?: boolean;
 }

package/src/strategies/DryRunExecutionStrategy.ts

@@ -0,0 +1,31 @@
+import { IExecutionStrategy } from "./IExecutionStrategy.js";
+import { TaskStep } from "../TaskStep.js";
+import { TaskResult } from "../TaskResult.js";
+
+/**
+ * Execution strategy that simulates task execution without running the actual logic.
+ */
+export class DryRunExecutionStrategy<TContext>
+  implements IExecutionStrategy<TContext>
+{
+  /**
+   * Simulates execution by returning a success result immediately.
+   * @param step The task step (ignored).
+   * @param context The shared context (ignored).
+   * @param signal Optional abort signal (ignored).
+   * @returns A promise resolving to a success result.
+   */
+  async execute(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _step: TaskStep<TContext>,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _context: TContext,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _signal?: AbortSignal
+  ): Promise<TaskResult> {
+    return Promise.resolve({
+      status: "success",
+      message: "Dry run: simulated success",
+    });
+  }
+}