@calmo/task-runner 3.4.1 → 3.5.0

package/AGENTS.md

@@ -27,6 +27,21 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 - Always prefer to add more tests instead of simply bypassing coverage validation with comments.
 - Its forbidden to have coverage drop below 100%, thats non negotiable.
 
+## Operational Protocols
+
+- **Critic-First Generation**: Every code block you generate must undergo an internal "Reflection" pass. Explicitly flag potential race conditions, security flaws (OWASP Top 10), or architectural debt.
+- **Verification Gatekeeping**: You are STRICTLY FORBIDDEN from claiming a task is "finished" until you provide terminal output of a passing test suite, a successful build log and a successful lint log.
+- **Planning Sparring**: For any task >20 lines, you must first output a blueprint and validate it. You will not write implementation code until the user approves the blueprint.
+- **Tool-Augmented Research**: Use `/search` and `/read` to understand the entire context of the project. Do not assume; verify existing utility functions to ensure DRY (Don't Repeat Yourself) compliance.
+- **The Confession Rule**: If you hit a logic error or a hallucination, you must immediately halt and state: "I have identified an inconsist- - **Atomic Commits for Complex Features:** When working on complex multi-task features, you MUST commit after completing each distinct task. Before each commit, ensure that `pnpm build`, `pnpm lint`, and `pnpm test` pass. This creates safe rollback points and prevents restarting the entire feature if issues arise.
+
+## Style & Tone
+
+- **Tone**: Professional, technical, and high-density.
+- **Zero Politeness Fluff**: No "I'd be happy to," "Great question," etc.
+- **Architectural Comparisons**: Use markdown tables for comparing architectural trade-offs.
+- **Hypothesis Labeling**: Label speculative thoughts clearly as `[ARCHITECTURAL_HYPOTHESIS]`.
+
 # task-runner Development Guidelines
 
 Auto-generated from all feature plans. Last updated: 2026-01-17
@@ -62,19 +77,3 @@ tests/
 - 005-concurrency-control: Added TypeScript 5.9.3 + vitest 4.0.17
 - 002-task-cancellation: Added TypeScript 5.9.3 + vitest 4.0.17, AbortSignal/AbortController (standard Web APIs)
 - 004-pre-execution-validation: Added TypeScript 5.9.3 + vitest 4.0.17 (for testing)
-
-<!-- MANUAL ADDITIONS START -->
-
-- **Atomic Commits for Complex Features:** When working on complex multi-task features, you MUST commit after completing each distinct task. Before each commit, ensure that `pnpm build`, `pnpm lint`, and `pnpm test` pass. This creates safe rollback points and prevents restarting the entire feature if issues arise.
-- Never edit CHANGELOG.md manually. This file is for semantic release and is filled automatically.
-
-Before marking a task as concluded, YOU MUST:
-
-1. run pnpm install
-2. run pnpm build
-3. run pnpm test
-4. run pnpm lint
-
-If any of those command fail, review your changes.
-
-<!-- MANUAL ADDITIONS END -->

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.5.0 (2026-01-18)
+
+* Merge pull request #69 from thalesraymond/feat/conditional-execution ([dd1dd8d](https://github.com/thalesraymond/task-runner/commit/dd1dd8d)), closes [#69](https://github.com/thalesraymond/task-runner/issues/69)
+* Update README.md ([8808f94](https://github.com/thalesraymond/task-runner/commit/8808f94))
+* docs: ✏️ archive conditional specs since its implemented ([b3db067](https://github.com/thalesraymond/task-runner/commit/b3db067))
+* docs: ✏️ conditional execution spec ([5a670c4](https://github.com/thalesraymond/task-runner/commit/5a670c4))
+* docs: ✏️ fix typo ([d969ff5](https://github.com/thalesraymond/task-runner/commit/d969ff5))
+* docs: ✏️ rewriting readme with latest changes ([c968fc3](https://github.com/thalesraymond/task-runner/commit/c968fc3))
+* docs: ✏️ update readme with example of conditional execution ([da9a818](https://github.com/thalesraymond/task-runner/commit/da9a818))
+* feat: 🎸 new conditional execution feature ([e936ad7](https://github.com/thalesraymond/task-runner/commit/e936ad7))
+* chore: 🤖 add AI skills ([5feacc6](https://github.com/thalesraymond/task-runner/commit/5feacc6))
+* chore: 🤖 removed skill md file, general skills moved to workspa ([5a8bd0e](https://github.com/thalesraymond/task-runner/commit/5a8bd0e))
+* chore: 🤖 removed workspace skills ([e819e00](https://github.com/thalesraymond/task-runner/commit/e819e00))
+
 ## <small>3.4.1 (2026-01-18)</small>
 
 * Merge pull request #65 from thalesraymond/perf/async-event-listeners-3002139613350975332 ([77edbc7](https://github.com/thalesraymond/task-runner/commit/77edbc7)), closes [#65](https://github.com/thalesraymond/task-runner/issues/65)

package/README.md

@@ -13,30 +13,24 @@ A lightweight, type-safe, and domain-agnostic task orchestration engine. It reso
 - **Type-Safe Context**: Fully typed shared state using TypeScript Generics.
 - **Parallel Execution**: Automatically identifies and runs independent steps concurrently.
 - **Dependency Management**: Enforces execution order based on dependencies.
-- **Error Handling & Skipping**: robustly handles failures and automatically skips dependent steps.
-- **Event System**: Subscribe to lifecycle events (`workflowStart`, `taskStart`, `taskEnd`, etc.) for logging or monitoring.
-- **Runtime Validation**: Automatically detects circular dependencies and missing dependencies before execution loops.
-
-## Event System
-
-The `TaskRunner` implements an Observer Pattern, allowing you to subscribe to various lifecycle events.
-
-```typescript
-runner.on("taskStart", ({ step }) => {
-  console.log(`Starting step: ${step.name}`);
-});
-
-runner.on("taskEnd", ({ step, result }) => {
-  console.log(`Step ${step.name} finished with status: ${result.status}`);
-});
-```
+- **Automatic Retries**: Configurable retry logic for flaky tasks.
+- **Dry Run Mode**: Simulate workflow execution to verify dependency graphs.
+- **Visualization**: Generate Mermaid.js diagrams of your task graph.
+- **Event System**: Subscribe to lifecycle events for logging or monitoring.
+- **Runtime Validation**: Automatically detects circular dependencies and missing dependencies.
+- **Conditional Execution**: Skip tasks dynamically based on context state.
 
 ## Usage Example
 
-Here is a simple example showing how to define a context, create steps, and execute them.
+The library now provides a fluent `TaskRunnerBuilder` for easy configuration.
 
 ```typescript
-import { TaskRunner, TaskStep } from "./src";
+import {
+  TaskRunnerBuilder,
+  TaskStep,
+  RetryingExecutionStrategy,
+  StandardExecutionStrategy
+} from "@calmo/task-runner";
 
 // 1. Define your domain-specific context
 interface ValidationContext {
@@ -51,16 +45,21 @@ interface ValidationContext {
 const UrlFormatStep: TaskStep<ValidationContext> = {
   name: "UrlFormatStep",
   run: async (ctx) => {
-    const valid = ctx.issueBody.includes("github.com");
-    return valid
-      ? { status: "success" }
-      : { status: "failure", error: "Invalid URL" };
+    if (!ctx.issueBody.includes("github.com")) {
+      return { status: "failure", error: "Invalid URL" };
+    }
+    return { status: "success" };
   },
 };
 
 const DataLoaderStep: TaskStep<ValidationContext> = {
   name: "DataLoaderStep",
   dependencies: ["UrlFormatStep"],
+  retry: {
+      attempts: 3,
+      delay: 1000,
+      backoff: "exponential"
+  },
   run: async (ctx) => {
     // Simulate API call
     ctx.prData = { additions: 20, ciStatus: "success" };
@@ -68,29 +67,25 @@ const DataLoaderStep: TaskStep<ValidationContext> = {
   },
 };
 
-const MaxChangesStep: TaskStep<ValidationContext> = {
-  name: "MaxChangesStep",
-  dependencies: ["DataLoaderStep"],
-  run: async (ctx) => {
-    // Safe access because dependencies ensured execution order
-    if (!ctx.prData) return { status: "failure", error: "Missing PR Data" };
-
-    return ctx.prData.additions < 50
-      ? { status: "success" }
-      : { status: "failure", error: "Too many changes" };
-  },
-};
-
-// 3. Execute the runner
+// 3. Configure and Build the Runner
 async function main() {
   const context: ValidationContext = {
     issueBody: "https://github.com/org/repo/pull/1",
   };
 
-  const runner = new TaskRunner(context);
+  const runner = new TaskRunnerBuilder(context)
+    .useStrategy(new RetryingExecutionStrategy(new StandardExecutionStrategy()))
+    .on("taskStart", ({ step }) => console.log(`Starting: ${step.name}`))
+    .on("taskEnd", ({ step, result }) => console.log(`Finished: ${step.name} -> ${result.status}`))
+    .build();
 
-  const steps = [UrlFormatStep, DataLoaderStep, MaxChangesStep];
-  const results = await runner.execute(steps);
+  const steps = [UrlFormatStep, DataLoaderStep];
+  
+  // 4. Execute with options
+  const results = await runner.execute(steps, {
+      concurrency: 5, // Run up to 5 tasks in parallel
+      timeout: 30000  // 30s timeout for the whole workflow
+  });
 
   console.table(Object.fromEntries(results));
 }
@@ -98,67 +93,79 @@ async function main() {
 main();
 ```
 
-## Skip Propagation
+## Advanced Configuration
 
-If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites, saving resources and preventing cascading errors.
+### Execution Strategies
 
-## Context Hydration
+The `TaskRunner` is built on top of composable execution strategies.
 
-One nice thing to do is to avoid optional parameters and excessive use of `!` operator, with task dependencies we can chain our steps and context usages to make sure steps are executed only when pre requisites are met.
+- **StandardExecutionStrategy**: The default strategy that simply runs the task.
+- **RetryingExecutionStrategy**: Wraps another strategy to add retry logic. Configured via the `retry` property on `TaskStep`.
+- **DryRunExecutionStrategy**: Simulates execution without running the actual task logic. Useful for validating your graph or testing conditions.
 
-This decouples **Data Loading** from **Business Logic**.
+You can set a strategy globally using the `TaskRunnerBuilder`:
 
-### Scenario: User Profile Validation
+```typescript
+runnerBuilder.useStrategy(new DryRunExecutionStrategy());
+```
+
+### Execution Options
 
-Imagine you need to validate if a user is a "Pro" member. You shouldn't mix the API fetching logic with the validation logic.
+When calling `execute`, you can provide a configuration object:
 
-1.  **Initial State**: The context starts with only a `userId`.
-2.  **Hydration Step**: A `UserLoaderStep` runs first. It fetches data from an API and attaches it to the context.
-3.  **Logic Step**: A `PremiumCheckStep` runs next. It doesn't need to know _how_ the data was fetched; it simply checks the `isPro` flag in the context.
+- **concurrency**: Limits the number of tasks running in parallel. Defaults to unlimited.
+- **timeout**: Sets a maximum execution time for the entire workflow.
+- **signal**: Accepts an `AbortSignal` to cancel the workflow programmatically.
+- **dryRun**: Overrides the current strategy with `DryRunExecutionStrategy` for this execution.
 
 ```typescript
-interface MyProjectContext {
-  rawInput: string;
-}
+await runner.execute(steps, {
+    concurrency: 2,
+    dryRun: true
+});
+```
 
-interface MyProjectFullContext extends MyProjectContext {
-  apiData: {
-    user: string;
-    isPro: boolean;
-  };
-}
+## Visualization
 
-// Step 1: Hydrate the context
-class UserLoaderStep implements TaskStep<MyProjectContext> {
-  name = "UserLoaderStep";
-  async run(ctx: MyProjectContext & Partial<MyProjectFullContext>) {
-    // Fetch data and update context
-    ctx.apiData = { user: "john_doe", isPro: true };
-    return { status: "success" };
-  }
-}
+You can generate a [Mermaid.js](https://mermaid.js.org/) diagram to visualize your task dependencies.
 
-// Step 2: Use the hydrated data
-class PremiumCheckStep implements TaskStep<MyProjectContext> {
-  name = "PremiumCheckStep";
-  dependencies = ["UserLoaderStep"]; // Ensures data is ready
+```typescript
+import { TaskRunner } from "@calmo/task-runner";
 
-  async run(ctx: MyProjectFullContext) {
-    return ctx.apiData.isPro
-      ? { status: "success" }
-      : { status: "failure", error: "User is not a Pro member" };
-  }
-}
+const graph = TaskRunner.getMermaidGraph(steps);
+console.log(graph);
+// Output: graph TD; A-->B; ...
 ```
 
-This approach allows `PremiumCheckStep` to be easily tested with mock data, as it doesn't depend on the actual API loader.
+## Skip Propagation
+
+If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites.
+
+## Conditional Execution
+
+You can define a `condition` function for a task. If it returns `false`, the task is marked as `skipped`, and its dependencies are also skipped.
+
+```typescript
+const deployStep: TaskStep<MyContext> = {
+  name: "deploy",
+  condition: (ctx) => ctx.env === "production",
+  run: async () => {
+    // Deploy logic
+    return { status: "success" };
+  }
+};
+```
 
 ## Why I did this?
 
-In my company I have a Github Issue validation engine that checks **a lot** of stuff and I wanted to make a package that encapsulates the "validation engine" logic for use outside that niche case. I don't know if someone will find it useful but here it is.
+In my current job I have a Github Issue validation engine that checks **a lot** of stuff and I wanted to make a package that encapsulates the "validation engine" logic for use outside that use case. I also wanted to try to make a package that is not tied to a specific scenario. I don't know if someone will find it useful but here it is. 
+
+## AI Usage
+
+One of the reasons this project exists is to test 'vibe coding' tools, so yes, this is vibe coded (like, A LOT, I've added myself only specs and some conflict resolutions). This repository serves as a testbed for these tools. It's a way to create a real life scenario showcasing the capabilities of agentic AI development.
 
-## What is .gemini and .specify
+## Contributing and General Usage
 
-One of the reasons this project exists is to test 'code vibing' tools, so yes, this is vibe coded. My goal is to not touch the code and see if works.
+Feel free to open issues and PRs. I'm open to feedback and suggestions. I can't promise to act on them but I'll try my best. If you want to play with it, feel free to fork it, change it and use it in your own projects.
 
 ---