@calmo/task-runner 4.0.4 → 4.1.0

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/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.1.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/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;
+  };
 }

package/src/TaskRunner.ts

@@ -78,19 +78,59 @@ export class TaskRunner<TContext> {
    */
   public static getMermaidGraph<T>(steps: TaskStep<T>[]): string {
     const graphLines = ["graph TD"];
+    const idMap = new Map<string, string>();
+    const usedIds = new Set<string>();
+    const baseIdCounters = new Map<string, number>();
 
-    const sanitize = (name: string) => this.sanitizeMermaidId(name);
+    const getUniqueId = (name: string) => {
+      if (idMap.has(name)) {
+        return idMap.get(name)!;
+      }
+
+      const sanitized = this.sanitizeMermaidId(name);
+      let uniqueId = sanitized;
+
+      // First check if the base sanitized ID is available
+      if (!usedIds.has(uniqueId)) {
+        usedIds.add(uniqueId);
+        idMap.set(name, uniqueId);
+        return uniqueId;
+      }
+
+      // If not, use the counter for this base ID
+      let counter = baseIdCounters.get(sanitized) || 1;
+
+      while (usedIds.has(uniqueId)) {
+        uniqueId = `${sanitized}_${counter}`;
+        counter++;
+      }
+
+      baseIdCounters.set(sanitized, counter);
+
+      usedIds.add(uniqueId);
+      idMap.set(name, uniqueId);
+      return uniqueId;
+    };
 
+    // Pre-calculate IDs for all steps to ensure stable generation order
+    // We sort steps by name to ensure deterministic ID generation regardless of input order if names clash
+    // But input order is usually significant in graph definition, so we'll stick to input order.
+    // However, we must process all step NAMES first.
     for (const step of steps) {
-      graphLines.push(
-        `  ${sanitize(step.name)}[${JSON.stringify(step.name)}]`
-      );
+      getUniqueId(step.name);
+    }
+
+    for (const step of steps) {
+      const stepId = getUniqueId(step.name);
+      graphLines.push(`  ${stepId}[${JSON.stringify(step.name)}]`);
     }
 
     for (const step of steps) {
       if (step.dependencies) {
+        const stepId = getUniqueId(step.name);
         for (const dep of step.dependencies) {
-          graphLines.push(`  ${sanitize(dep)} --> ${sanitize(step.name)}`);
+          const depId = getUniqueId(dep);
+          graphLines.push(`  ${depId} --> ${stepId}`);
         }
       }
     }
@@ -171,37 +211,16 @@ export class TaskRunner<TContext> {
     timeout: number,
     signal?: AbortSignal
   ): Promise<Map<string, TaskResult>> {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => {
-      controller.abort(new Error(`Workflow timed out after ${timeout}ms`));
-    }, timeout);
-
-    let effectiveSignal = controller.signal;
-    let onAbort: (() => void) | undefined;
-
-    // Handle combination of signals if user provided one
-    if (signal) {
-      if (signal.aborted) {
-        // If already aborted, use it directly (WorkflowExecutor handles early abort)
-        // We can cancel timeout immediately
-        clearTimeout(timeoutId);
-        effectiveSignal = signal;
-      } else {
-        // Listen to user signal to abort our controller
-        onAbort = () => {
-          controller.abort(signal.reason);
-        };
-        signal.addEventListener("abort", onAbort);
-      }
-    }
+    // Create a timeout signal that aborts after the specified time
+    const timeoutSignal = AbortSignal.timeout(timeout);
 
-    try {
-      return await executor.execute(steps, effectiveSignal);
-    } finally {
-      clearTimeout(timeoutId);
-      if (signal && onAbort) {
-        signal.removeEventListener("abort", onAbort);
-      }
-    }
+    // If there's a user-provided signal, combine them.
+    // Otherwise, use the timeout signal directly.
+    const effectiveSignal = signal
+      ? AbortSignal.any([signal, timeoutSignal])
+      : timeoutSignal;
+
+    return executor.execute(steps, effectiveSignal);
+    // No explicit clean up needed for AbortSignal.timeout as it is handled by the platform
   }
 }

package/src/TaskStateManager.ts

@@ -11,6 +11,11 @@ export class TaskStateManager<TContext> {
   private pendingSteps = new Set<TaskStep<TContext>>();
   private running = new Set<string>();
 
+  // Optimization structures
+  private dependencyGraph = new Map<string, TaskStep<TContext>[]>();
+  private dependencyCounts = new Map<string, number>();
+  private readyQueue: TaskStep<TContext>[] = [];
+
   constructor(private eventBus: EventBus<TContext>) {}
 
   /**
@@ -21,50 +26,39 @@ export class TaskStateManager<TContext> {
     this.pendingSteps = new Set(steps);
     this.results.clear();
     this.running.clear();
-  }
+    this.readyQueue = [];
 
-  /**
-   * 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>[] = [];
+    this.dependencyGraph.clear();
+    this.dependencyCounts.clear();
 
-    for (const step of this.pendingSteps) {
+    for (const step of steps) {
       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;
+      this.dependencyCounts.set(step.name, deps.length);
+
+      if (deps.length === 0) {
+        this.readyQueue.push(step);
+      } else {
+        for (const dep of deps) {
+          if (!this.dependencyGraph.has(dep)) {
+            this.dependencyGraph.set(dep, []);
+          }
+          this.dependencyGraph.get(dep)!.push(step);
         }
       }
-
-      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.markSkipped(step, result);
-        toRemove.push(step);
-      } else if (!blocked) {
-        toRun.push(step);
-        toRemove.push(step);
-      }
     }
+  }
+
+  /**
+   * Processes the pending steps to identify tasks that can be started.
+   * Emits `taskSkipped` for skipped tasks (handled during cascade).
+   * @returns An array of tasks that are ready to run.
+   */
+  processDependencies(): TaskStep<TContext>[] {
+    const toRun = [...this.readyQueue];
+    this.readyQueue = [];
 
-    // Cleanup pending set
-    for (const step of toRemove) {
+    // Remove them from pendingSteps as they are now handed off to the executor
+    for (const step of toRun) {
       this.pendingSteps.delete(step);
     }
 
@@ -90,6 +84,39 @@ export class TaskStateManager<TContext> {
     this.running.delete(step.name);
     this.results.set(step.name, result);
     this.eventBus.emit("taskEnd", { step, result });
+
+    if (result.status === "success") {
+      this.handleSuccess(step.name);
+    } else {
+      this.cascadeFailure(step.name);
+    }
+  }
+
+  /**
+   * Marks a task as skipped and emits `taskSkipped`.
+   * @param step The task that was skipped.
+   * @param result The result object (status: skipped).
+   */
+  markSkipped(step: TaskStep<TContext>, result: TaskResult): void {
+    if (this.internalMarkSkipped(step, result)) {
+      this.cascadeFailure(step.name);
+    }
+  }
+
+  /**
+   * Internal method to mark skipped without triggering cascade (to be used inside cascade loop).
+   * Returns true if the task was actually marked skipped (was not already finished).
+   */
+  private internalMarkSkipped(step: TaskStep<TContext>, result: TaskResult): boolean {
+    if (this.results.has(step.name)) {
+      return false;
+    }
+
+    this.running.delete(step.name);
+    this.results.set(step.name, result);
+    this.pendingSteps.delete(step);
+    this.eventBus.emit("taskSkipped", { step, result });
+    return true;
   }
 
   /**
@@ -97,10 +124,10 @@ export class TaskStateManager<TContext> {
    * @param message The cancellation message.
    */
   cancelAllPending(message: string): void {
+    this.readyQueue = []; // Clear ready queue
+
     // 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.
       if (!this.results.has(step.name) && !this.running.has(step.name)) {
         const result: TaskResult = {
           status: "cancelled",
@@ -136,13 +163,54 @@ export class TaskStateManager<TContext> {
   }
 
   /**
-   * Marks a task as skipped and emits `taskSkipped`.
-   * @param step The task that was skipped.
-   * @param result The result object (status: skipped).
+   * Handles successful completion of a task by updating dependents.
    */
-  markSkipped(step: TaskStep<TContext>, result: TaskResult): void {
-    this.running.delete(step.name);
-    this.results.set(step.name, result);
-    this.eventBus.emit("taskSkipped", { step, result });
+  private handleSuccess(stepName: string): void {
+    const dependents = this.dependencyGraph.get(stepName);
+    if (!dependents) return;
+
+    for (const dependent of dependents) {
+      const currentCount = this.dependencyCounts.get(dependent.name)!;
+      const newCount = currentCount - 1;
+      this.dependencyCounts.set(dependent.name, newCount);
+
+      if (newCount === 0) {
+        // Task is ready. Ensure it's still pending.
+        if (this.pendingSteps.has(dependent)) {
+          this.readyQueue.push(dependent);
+        }
+      }
+    }
+  }
+
+  /**
+   * Cascades failure/skipping to dependents.
+   */
+  private cascadeFailure(failedStepName: string): void {
+    const queue = [failedStepName];
+    // Use a set to track visited nodes in this cascade pass to avoid redundant processing,
+    // although checking results.has() in internalMarkSkipped also prevents it.
+
+    while (queue.length > 0) {
+      const currentName = queue.shift()!;
+      const dependents = this.dependencyGraph.get(currentName);
+
+      if (!dependents) continue;
+
+      // Get the result of the failed/skipped dependency to propagate error info if available
+      const currentResult = this.results.get(currentName);
+      const depError = currentResult?.error ? `: ${currentResult.error}` : "";
+
+      for (const dependent of dependents) {
+        const result: TaskResult = {
+          status: "skipped",
+          message: `Skipped because dependency '${currentName}' failed${depError}`,
+        };
+
+        if (this.internalMarkSkipped(dependent, result)) {
+          queue.push(dependent.name);
+        }
+      }
+    }
   }
 }

package/src/WorkflowExecutor.ts

@@ -4,13 +4,14 @@ import { EventBus } from "./EventBus.js";
 import { TaskStateManager } from "./TaskStateManager.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { ExecutionConstants } from "./ExecutionConstants.js";
+import { PriorityQueue } from "./utils/PriorityQueue.js";
 
 /**
  * Handles the execution of the workflow steps.
  * @template TContext The shape of the shared context object.
  */
 export class WorkflowExecutor<TContext> {
-  private readyQueue: TaskStep<TContext>[] = [];
+  private readyQueue = new PriorityQueue<TaskStep<TContext>>();
 
   /**
    * @param context The shared context object.
@@ -114,14 +115,11 @@ export class WorkflowExecutor<TContext> {
 
     // Add newly ready tasks to the queue
     for (const task of newlyReady) {
-      this.readyQueue.push(task);
+      this.readyQueue.push(task, task.priority ?? 0);
     }
 
-    // Sort by priority (descending) once after adding new tasks
-    this.readyQueue.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
-
     // Execute ready tasks while respecting concurrency limit
-    while (this.readyQueue.length > 0) {
+    while (!this.readyQueue.isEmpty()) {
       if (
         this.concurrency !== undefined &&
         executingPromises.size >= this.concurrency
@@ -129,7 +127,7 @@ export class WorkflowExecutor<TContext> {
         break;
       }
 
-      const step = this.readyQueue.shift()!;
+      const step = this.readyQueue.pop()!;
 
       const taskPromise = this.executeTaskStep(step, signal)
         .finally(() => {
@@ -194,16 +192,28 @@ export class WorkflowExecutor<TContext> {
 
     this.stateManager.markRunning(step);
 
+    const startTime = performance.now();
+    let result: TaskResult;
+
     try {
-      const result = await this.strategy.execute(step, this.context, signal);
-      this.stateManager.markCompleted(step, result);
+      result = await this.strategy.execute(step, this.context, signal);
     } catch (error) {
-      const result: TaskResult = {
+      result = {
         status: "failure",
         message: ExecutionConstants.EXECUTION_STRATEGY_FAILED,
         error: error instanceof Error ? error.message : String(error),
       };
-      this.stateManager.markCompleted(step, result);
     }
+
+    const endTime = performance.now();
+
+    // Always inject metrics to ensure accuracy
+    result.metrics = {
+      startTime,
+      endTime,
+      duration: endTime - startTime,
+    };
+
+    this.stateManager.markCompleted(step, result);
   }
 }

package/src/strategies/DryRunExecutionStrategy.ts

@@ -16,8 +16,7 @@ export class DryRunExecutionStrategy<
    * @returns A promise resolving to a success result.
    */
   async execute(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _step: TaskStep<TContext>,
+    step: TaskStep<TContext>,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _context: TContext,
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -25,7 +24,7 @@ export class DryRunExecutionStrategy<
   ): Promise<TaskResult> {
     return Promise.resolve({
       status: "success",
-      message: "Dry run: simulated success",
+      message: "Dry run: simulated success " + step.name,
     });
   }
 }

package/src/utils/PriorityQueue.ts

@@ -0,0 +1,101 @@
+export class PriorityQueue<T> {
+  private heap: { item: T; priority: number; sequenceId: number }[] = [];
+  private sequenceCounter = 0;
+
+  push(item: T, priority: number): void {
+    const node = { item, priority, sequenceId: this.sequenceCounter++ };
+    this.heap.push(node);
+    this.bubbleUp();
+  }
+
+  pop(): T | undefined {
+    if (this.heap.length === 0) return undefined;
+    if (this.heap.length === 1) return this.heap.pop()!.item;
+
+    const top = this.heap[0];
+    this.heap[0] = this.heap.pop()!;
+    this.sinkDown();
+    return top.item;
+  }
+
+  peek(): T | undefined {
+    return this.heap[0]?.item;
+  }
+
+  size(): number {
+    return this.heap.length;
+  }
+
+  isEmpty(): boolean {
+    return this.heap.length === 0;
+  }
+
+  clear(): void {
+    this.heap = [];
+    this.sequenceCounter = 0;
+  }
+
+  private bubbleUp(): void {
+    let index = this.heap.length - 1;
+    const element = this.heap[index];
+
+    while (index > 0) {
+      const parentIndex = Math.floor((index - 1) / 2);
+      const parent = this.heap[parentIndex];
+
+      if (this.compare(element, parent) <= 0) break;
+
+      this.heap[index] = parent;
+      this.heap[parentIndex] = element;
+      index = parentIndex;
+    }
+  }
+
+  private sinkDown(): void {
+    let index = 0;
+    const length = this.heap.length;
+    const element = this.heap[0];
+
+    while (true) {
+      const leftChildIndex = 2 * index + 1;
+      const rightChildIndex = 2 * index + 2;
+      let swapIndex: number | null = null;
+
+      if (leftChildIndex < length) {
+        if (this.compare(this.heap[leftChildIndex], element) > 0) {
+          swapIndex = leftChildIndex;
+        }
+      }
+
+      if (rightChildIndex < length) {
+        const rightChild = this.heap[rightChildIndex];
+        const leftChild = this.heap[leftChildIndex];
+
+        if (
+          (swapIndex === null && this.compare(rightChild, element) > 0) ||
+          (swapIndex !== null && this.compare(rightChild, leftChild) > 0)
+        ) {
+          swapIndex = rightChildIndex;
+        }
+      }
+
+      if (swapIndex === null) break;
+
+      this.heap[index] = this.heap[swapIndex];
+      this.heap[swapIndex] = element;
+      index = swapIndex;
+    }
+  }
+
+  // Returns positive if a > b (a should come before b)
+  private compare(
+    a: { priority: number; sequenceId: number },
+    b: { priority: number; sequenceId: number }
+  ): number {
+    if (a.priority !== b.priority) {
+      return a.priority - b.priority;
+    }
+    // Lower sequenceId means earlier insertion, so it has higher priority
+    return b.sequenceId - a.sequenceId;
+  }
+}

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

@@ -1,6 +0,0 @@
-## 1. Implementation
-
-- [ ] 1.1 Update `TaskResult` interface in `src/TaskResult.ts` to include `metrics`.
-- [ ] 1.2 Update `WorkflowExecutor.ts` to capture start/end times and calculate duration.
-- [ ] 1.3 Update `WorkflowExecutor.ts` to inject metrics into the `TaskResult`.
-- [ ] 1.4 Add unit tests in `tests/TaskMetrics.test.ts` to verify metrics are present and correct.