@calmo/task-runner 3.4.1 → 3.6.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,35 @@
+name: Bug Report
+description: File a bug report
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    attributes:
+      label: Description
+      description: What happened?
+      placeholder: Describe the bug...
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Reproduction Steps
+      description: How do we reproduce it?
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+  - type: textarea
+    attributes:
+      label: Environment
+      description: OS, Node version, etc.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature Request
+description: Suggest a new feature
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature!
+  - type: textarea
+    attributes:
+      label: Description
+      description: What is the problem you are trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Proposed Solution
+      description: Describe the solution you'd like
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Alternatives Considered
+      description: Any other approaches?

package/.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
         run: pnpm test
 
       - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@v6
+        uses: SonarSource/sonarqube-scan-action@v7
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 

package/.github/workflows/codeql.yml

@@ -0,0 +1,101 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '18 8 * * 3'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

package/.github/workflows/release.yml

@@ -16,12 +16,12 @@ jobs:
       id-token: write # to enable use of OIDC for npm provenance
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
         with:
           version: 10.28.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,30 @@
+## 3.6.0 (2026-01-19)
+
+* Add CodeQL analysis workflow configuration ([b2ee976](https://github.com/thalesraymond/task-runner/commit/b2ee976))
+* Merge pull request #66 from thalesraymond/dependabot/github_actions/actions/checkout-6 ([cb6e75f](https://github.com/thalesraymond/task-runner/commit/cb6e75f)), closes [#66](https://github.com/thalesraymond/task-runner/issues/66)
+* Merge pull request #67 from thalesraymond/dependabot/github_actions/pnpm/action-setup-4 ([4c9e9f3](https://github.com/thalesraymond/task-runner/commit/4c9e9f3)), closes [#67](https://github.com/thalesraymond/task-runner/issues/67)
+* Merge pull request #68 from thalesraymond/dependabot/github_actions/SonarSource/sonarqube-scan-actio ([9980f4d](https://github.com/thalesraymond/task-runner/commit/9980f4d)), closes [#68](https://github.com/thalesraymond/task-runner/issues/68)
+* Merge pull request #71 from thalesraymond/chore/codeQLworkflow ([db4f46a](https://github.com/thalesraymond/task-runner/commit/db4f46a)), closes [#71](https://github.com/thalesraymond/task-runner/issues/71)
+* Merge pull request #72 from thalesraymond/setup-issue-templates-6661562951039014259 ([f3281bf](https://github.com/thalesraymond/task-runner/commit/f3281bf)), closes [#72](https://github.com/thalesraymond/task-runner/issues/72)
+* feat: add issue templates ([6ff97f1](https://github.com/thalesraymond/task-runner/commit/6ff97f1))
+* chore(deps): bump actions/checkout from 4 to 6 ([f0b2f0e](https://github.com/thalesraymond/task-runner/commit/f0b2f0e))
+* chore(deps): bump pnpm/action-setup from 2 to 4 ([2a5c3e1](https://github.com/thalesraymond/task-runner/commit/2a5c3e1))
+* chore(deps): bump SonarSource/sonarqube-scan-action from 6 to 7 ([df236cd](https://github.com/thalesraymond/task-runner/commit/df236cd))
+
+## 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.
 
 ---