@calmo/task-runner 3.4.1 → 3.5.0

package/dist/WorkflowExecutor.js

@@ -51,7 +51,8 @@ export class WorkflowExecutor {
             // Initial pass
             this.processLoop(executingPromises, signal);
             while (this.stateManager.hasPendingTasks() ||
-                this.stateManager.hasRunningTasks()) {
+                this.stateManager.hasRunningTasks() ||
+                executingPromises.size > 0) {
                 // Safety check: if no tasks are running and we still have pending tasks,
                 // it means we are stuck (e.g. cycle or unhandled dependency).
                 // Since valid graphs shouldn't have this, we break to avoid infinite loop.
@@ -98,13 +99,53 @@ export class WorkflowExecutor {
                 break;
             }
             const step = this.readyQueue.shift();
-            this.stateManager.markRunning(step);
-            const taskPromise = this.strategy
-                .execute(step, this.context, signal)
-                .then((result) => {
-                this.stateManager.markCompleted(step, result);
-            })
-                .finally(() => {
+            const taskPromise = (async () => {
+                try {
+                    if (step.condition) {
+                        const check = step.condition(this.context);
+                        const shouldRun = check instanceof Promise ? await check : check;
+                        if (signal?.aborted) {
+                            this.stateManager.markCompleted(step, {
+                                status: "cancelled",
+                                message: "Cancelled during condition evaluation.",
+                            });
+                            return;
+                        }
+                        if (!shouldRun) {
+                            const result = {
+                                status: "skipped",
+                                message: "Skipped by condition evaluation.",
+                            };
+                            this.stateManager.markSkipped(step, result);
+                            return;
+                        }
+                    }
+                }
+                catch (error) {
+                    const result = {
+                        status: "failure",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Condition evaluation failed",
+                        error: error instanceof Error ? error.message : String(error),
+                    };
+                    this.stateManager.markCompleted(step, result);
+                    return;
+                }
+                if (signal?.aborted) {
+                    this.stateManager.markCompleted(step, {
+                        status: "cancelled",
+                        message: "Cancelled before execution started.",
+                    });
+                    return;
+                }
+                this.stateManager.markRunning(step);
+                await this.strategy
+                    .execute(step, this.context, signal)
+                    .then((result) => {
+                    this.stateManager.markCompleted(step, result);
+                });
+            })().finally(() => {
                 executingPromises.delete(taskPromise);
                 // When a task finishes, we try to run more
                 this.processLoop(executingPromises, signal);

package/dist/WorkflowExecutor.js.map

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

package/openspec/changes/archive/2026-01-18-feat-conditional-execution/proposal.md

@@ -0,0 +1,35 @@
+# Feature: Conditional Task Execution
+
+## 🎯 User Story
+
+"As a developer, I want to define a condition for a task so that it only executes when specific criteria are met (e.g., only on CI, or only if a previous task generated a specific output), avoiding unnecessary execution and manual checks inside the task logic."
+
+## ❓ Why
+
+Currently, to skip a task based on context, a developer must implement the check inside the `run` method and return `{ status: 'skipped' }`. This has downsides:
+
+1.  **Late Binding**: The task is already "started" (event emitted) before it decides to skip itself.
+2.  **Boilerplate**: Every task needs `if (!shouldRun) return { status: 'skipped' }`.
+3.  **Clarity**: Examining the task definition (e.g. `TaskStep` object) doesn't reveal *when* it runs, only *what* it does. A declarative `condition` property makes the workflow logic more transparent.
+4.  **Dry Run Accuracy**: In a dry run, we might want to know if a task *would* run. If the logic is inside `run`, strictly disjoint from the runner, a dry run (which skips `run`) cannot predict if the task would be skipped.
+
+## 🛠️ What Changes
+
+1.  **Interface Update**: Update `TaskStep<T>` to accept an optional `condition` property:
+    ```typescript
+    condition?: (context: T) => boolean | Promise<boolean>;
+    ```
+2.  **State Manager/Workflow Executor Update**:
+    - Before marking a task as `running`, evaluate `condition(context)`.
+    - If `false`, mark the task as `skipped` immediately without calling `run()`.
+    - Emit `taskSkipped` event.
+    - Consistency: Ensure that skipping a task triggers the standard skip propagation for dependent tasks (as currently documented in README).
+
+## ✅ Acceptance Criteria
+
+- [ ] A task with `condition: () => false` must result in a `skipped` status.
+- [ ] The `run` method of a conditionally skipped task must **not** be called.
+- [ ] A task with `condition: () => true` (or undefined) must execute normally.
+- [ ] The `condition` function receives the current `context`.
+- [ ] Async `condition` functions are awaited.
+- [ ] `taskSkipped` event is emitted when condition fails.

package/openspec/changes/archive/2026-01-18-feat-conditional-execution/tasks.md

@@ -0,0 +1,32 @@
+# Engineering Tasks
+
+- [ ] **Task 1: Update Interface**
+  - Modify `src/TaskStep.ts` to add `condition?: (context: T) => boolean | Promise<boolean>;` to the `TaskStep` interface.
+  - Add JSDoc to explain that if condition returns false, the task is skipped.
+
+- [ ] **Task 2: Implement Conditional Logic in TaskStateManager**
+  - Analyze `src/TaskStateManager.ts` and `src/WorkflowExecutor.ts`.
+  - Determine the best place to evaluate the condition. Likely in `WorkflowExecutor` before calling `strategy.execute`, OR in `TaskStateManager` when processing dependencies?
+  - Actually, `WorkflowExecutor.processLoop` calls `stateManager.markRunning(step)`.
+  - It should probably be:
+    ```typescript
+    const shouldRun = await evaluateCondition(step, context);
+    if (!shouldRun) {
+        stateManager.markResult(step, { status: 'skipped' });
+        // emit skipped event
+        return;
+    }
+    stateManager.markRunning(step);
+    strategy.execute(...)
+    ```
+  - Note: `evaluateCondition` needs to handle both sync and async results.
+
+- [ ] **Task 3: Unit Tests**
+  - Create `tests/conditional.test.ts` (or add to `tests/TaskRunner.test.ts`).
+  - Test: Task with condition `() => false` is skipped.
+  - Test: Task with condition `() => true` runs.
+  - Test: Task with async condition skipping.
+  - Test: Dependent tasks are also skipped (or handle skip propagation correctly).
+
+- [ ] **Task 4: Verify Dry Run Behavior**
+  - Ensure Dry Run strategy still respects condition if possible, OR clarify in spec that condition is evaluated normally even in dry run (since it's a predicate, not side-effect).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "description": "",
   "repository": {
     "type": "git",
@@ -20,6 +20,7 @@
     "test": "tsc --noEmit -p tsconfig.test.json && vitest run --coverage",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "all": "pnpm run build && pnpm run test && pnpm run lint",
     "format": "prettier --write .",
     "prepare": "husky",
     "commit": "git add . &&git-cz"

package/src/TaskStateManager.ts

@@ -55,8 +55,7 @@ export class TaskStateManager<TContext> {
           status: "skipped",
           message: `Skipped because dependency '${failedDep}' failed${depError}`,
         };
-        this.results.set(step.name, result);
-        this.eventBus.emit("taskSkipped", { step, result });
+        this.markSkipped(step, result);
         toRemove.push(step);
       } else if (!blocked) {
         toRun.push(step);
@@ -139,4 +138,15 @@ export class TaskStateManager<TContext> {
   hasPendingTasks(): boolean {
     return this.pendingSteps.size > 0;
   }
+
+  /**
+   * 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 {
+    this.running.delete(step.name);
+    this.results.set(step.name, result);
+    this.eventBus.emit("taskSkipped", { step, result });
+  }
 }

package/src/TaskStep.ts

@@ -12,6 +12,12 @@ export interface TaskStep<TContext> {
   dependencies?: string[];
   /** Optional retry configuration for the task. */
   retry?: TaskRetryConfig;
+  /**
+   * Optional function to determine if the task should run.
+   * If it returns false (synchronously or asynchronously), the task is skipped.
+   */
+  condition?: (context: TContext) => boolean | Promise<boolean>;
+
   /**
    * The core logic of the task.
    * @param context The shared context object, allowing for state to be passed between tasks.

package/src/WorkflowExecutor.ts

@@ -66,7 +66,8 @@ export class WorkflowExecutor<TContext> {
 
       while (
         this.stateManager.hasPendingTasks() ||
-        this.stateManager.hasRunningTasks()
+        this.stateManager.hasRunningTasks() ||
+        executingPromises.size > 0
       ) {
         // Safety check: if no tasks are running and we still have pending tasks,
         // it means we are stuck (e.g. cycle or unhandled dependency).
@@ -124,18 +125,62 @@ export class WorkflowExecutor<TContext> {
 
       const step = this.readyQueue.shift()!;
 
-      this.stateManager.markRunning(step);
-
-      const taskPromise = this.strategy
-        .execute(step, this.context, signal)
-        .then((result) => {
+      const taskPromise = (async () => {
+        try {
+          if (step.condition) {
+            const check = step.condition(this.context);
+            const shouldRun = check instanceof Promise ? await check : check;
+
+            if (signal?.aborted) {
+              this.stateManager.markCompleted(step, {
+                status: "cancelled",
+                message: "Cancelled during condition evaluation.",
+              });
+              return;
+            }
+
+            if (!shouldRun) {
+              const result: TaskResult = {
+                status: "skipped",
+                message: "Skipped by condition evaluation.",
+              };
+              this.stateManager.markSkipped(step, result);
+              return;
+            }
+          }
+        } catch (error) {
+          const result: TaskResult = {
+            status: "failure",
+            message:
+              error instanceof Error
+                ? error.message
+                : "Condition evaluation failed",
+            error: error instanceof Error ? error.message : String(error),
+          };
           this.stateManager.markCompleted(step, result);
-        })
-        .finally(() => {
-          executingPromises.delete(taskPromise);
-          // When a task finishes, we try to run more
-          this.processLoop(executingPromises, signal);
-        });
+          return;
+        }
+
+        if (signal?.aborted) {
+          this.stateManager.markCompleted(step, {
+            status: "cancelled",
+            message: "Cancelled before execution started.",
+          });
+          return;
+        }
+
+        this.stateManager.markRunning(step);
+
+        await this.strategy
+          .execute(step, this.context, signal)
+          .then((result) => {
+            this.stateManager.markCompleted(step, result);
+          });
+      })().finally(() => {
+        executingPromises.delete(taskPromise);
+        // When a task finishes, we try to run more
+        this.processLoop(executingPromises, signal);
+      });
 
       executingPromises.add(taskPromise);
     }