@calmo/task-runner 3.8.4 → 4.0.4

package/openspec/changes/feat-per-task-timeout/specs/task-runner/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Per-Task Timeout
+
+The `TaskStep` interface SHALL support an optional `timeout` property, and the `StandardExecutionStrategy` SHALL enforce this timeout.
+
+#### Scenario: Task completes within timeout
+
+- **GIVEN** a task with `timeout: 100` (ms)
+- **WHEN** the task execution takes 50ms
+- **THEN** the task SHALL complete successfully.
+- **AND** the timeout timer SHALL be cleared immediately.
+
+#### Scenario: Task exceeds timeout
+
+- **GIVEN** a task with `timeout: 100` (ms)
+- **WHEN** the task execution attempts to run longer than 100ms
+- **THEN** the task execution SHALL be aborted with an error indicating a timeout.
+- **AND** the `TaskResult` status SHALL be 'failure' (or 'cancelled' if appropriate, but typically 'failure' due to timeout error).
+- **AND** the `AbortSignal` passed to the task's `run` method SHALL be triggered.
+
+#### Scenario: Global cancellation overrides task timeout
+
+- **GIVEN** a task with `timeout: 5000` (ms)
+- **WHEN** the workflow's global `AbortSignal` is triggered at 100ms
+- **THEN** the task SHALL receive the abort signal immediately (at 100ms).
+- **AND** the task SHALL NOT wait for the 5000ms timeout.
+- **AND** the `TaskResult` status SHALL be 'cancelled'.
+
+#### Scenario: Task without timeout
+
+- **GIVEN** a task without a `timeout` property
+- **WHEN** it executes
+- **THEN** it SHALL NOT be subject to any local timeout constraints (only global workflow timeout).

package/openspec/changes/feat-task-metrics/specs/001-generic-task-runner/spec.md

@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### 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/openspec/specs/task-runner/spec.md

@@ -0,0 +1,162 @@
+# task-runner Specification
+
+## Purpose
+
+TBD - created by archiving change add-external-task-cancellation. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: TaskRunner Execution
+
+The `TaskRunner` SHALL execute a sequence of `TaskStep`s based on their dependencies, processing inputs and producing outputs.
+
+#### Scenario: Successful execution
+
+- **WHEN** all `TaskStep`s complete successfully
+- **THEN** the `TaskRunner` returns a successful workflow result.
+
+#### Scenario: Execution with AbortSignal
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal`
+- **THEN** the `TaskRunner` monitors the `AbortSignal` for cancellation requests.
+
+#### Scenario: Execution with Global Timeout
+
+- **WHEN** `TaskRunner.execute` is called with a `timeout` option
+- **THEN** the `TaskRunner` monitors the elapsed time for the workflow.
+
+### Requirement: External Workflow Cancellation
+
+The `TaskRunner` SHALL allow external cancellation of an ongoing workflow.
+
+#### Scenario: Workflow cancelled by AbortSignal
+
+- **WHEN** an `AbortSignal` provided to `TaskRunner.execute` is triggered
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Workflow cancelled by Global Timeout
+
+- **WHEN** the specified global `timeout` for `TaskRunner.execute` is reached
+- **THEN** the `TaskRunner` immediately attempts to stop execution of current and pending tasks.
+
+#### Scenario: Tasks marked as cancelled
+
+- **WHEN** a workflow is cancelled (by `AbortSignal` or `timeout`)
+- **THEN** all unexecuted `TaskStep`s SHALL be marked with a 'cancelled' status in the final result.
+
+#### Scenario: Pre-aborted workflow
+
+- **WHEN** `TaskRunner.execute` is called with an `AbortSignal` that is already aborted
+- **THEN** the `TaskRunner` SHALL return immediately with all tasks marked as cancelled, without executing any steps.
+
+#### Scenario: Graceful interruption of current task
+
+- **WHEN** a workflow is cancelled and a `TaskStep` is currently executing
+- **THEN** the `TaskStep` SHALL receive the cancellation signal (e.g., via `AbortSignal` context) to allow for graceful interruption.
+
+### Requirement: Cancellation Conflict Resolution
+
+The `TaskRunner` SHALL handle scenarios where both `AbortSignal` and global `timeout` are provided.
+
+#### Scenario: AbortSignal precedes Timeout
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `AbortSignal` is triggered first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `AbortSignal`, ignoring the `timeout`.
+
+#### Scenario: Timeout precedes AbortSignal
+
+- **WHEN** both `AbortSignal` and `timeout` are provided, and `timeout` is reached first
+- **THEN** the `TaskRunner` SHALL cancel the workflow based on the `timeout`, ignoring the `AbortSignal`.
+
+### Requirement: Integration Verification
+
+The system's integrity SHALL be verified through comprehensive integration scenarios executed against the real runtime environment without mocks.
+
+#### Scenario: Complex Graph Execution
+
+- **WHEN** a complex task graph (diamonds, sequences, parallel branches) is executed
+- **THEN** the system SHALL respect all dependency constraints and execution orders.
+- **AND** the final state MUST reflect the cumulative side effects of all successful tasks.
+
+#### Scenario: Failure Propagation
+
+- **WHEN** a task fails in a complex graph
+- **THEN** ONLY dependent tasks SHALL be skipped
+- **AND** independent branches SHALL continue to execute to completion.
+
+#### Scenario: Context Integrity
+
+- **WHEN** multiple tasks mutate the shared context
+- **THEN** state changes MUST be propagated correctly to downstream tasks.
+
+### Requirement: Modular Execution Architecture
+
+The system SHALL support pluggable execution strategies and decoupled state management.
+
+#### Scenario: Pluggable Strategy
+
+- **WHEN** configured with a custom execution strategy
+- **THEN** the `TaskRunner` SHALL delegate the execution logic to that strategy.
+
+### Requirement: Dry Run Execution Strategy
+
+The system SHALL provide a `DryRunExecutionStrategy` that implements `IExecutionStrategy`.
+
+#### Scenario: Simulating execution
+
+- **WHEN** `WorkflowExecutor` is configured with `DryRunExecutionStrategy`
+- **AND** `execute` is called
+- **THEN** it SHALL traverse the dependency graph respecting order
+- **AND** it SHALL NOT execute the actual work of the `TaskStep`.
+- **AND** it SHALL return `TaskResult`s with a status indicating successful simulation (e.g., `simulated` or `success`).
+
+### Requirement: Mermaid Visualization
+
+The system SHALL provide a utility to generate a Mermaid.js graph from task steps.
+
+#### Scenario: Generate Mermaid Graph
+
+- **GIVEN** a list of `TaskStep`s with dependencies
+- **WHEN** `generateMermaidGraph` is called
+- **THEN** it SHALL return a valid Mermaid flowchart syntax string.
+- **AND** dependencies SHALL be represented as arrows (`-->`).
+- **AND** independent tasks SHALL appear as nodes.
+
+### Requirement: Task Retry Configuration
+
+The `TaskStep` interface SHALL support an optional `retry` property of type `TaskRetryConfig`.
+
+#### Scenario: Retry Config Structure
+
+- **GIVEN** a `TaskRetryConfig` object
+- **THEN** it SHALL support:
+  - `attempts`: Number of retry attempts (default: 0).
+  - `delay`: Base delay in milliseconds (default: 0).
+  - `backoff`: Backoff strategy ('fixed' | 'exponential') (default: 'fixed').
+
+### Requirement: Retrying Execution Strategy
+
+The system SHALL provide a `RetryingExecutionStrategy` that implements `IExecutionStrategy` and wraps another `IExecutionStrategy`.
+
+#### Scenario: Successful execution
+
+- **WHEN** the inner strategy returns a successful `TaskResult`
+- **THEN** `RetryingExecutionStrategy` SHALL return that result immediately.
+
+#### Scenario: Retry on failure
+
+- **WHEN** the inner strategy throws or returns a failed `TaskResult`
+- **AND** the task has `retry.attempts > 0`
+- **THEN** it SHALL wait for the configured `delay`.
+- **AND** it SHALL re-execute the task using the inner strategy.
+- **AND** it SHALL decrement the remaining attempts.
+
+#### Scenario: Max attempts reached
+
+- **WHEN** the task fails and no attempts remain
+- **THEN** it SHALL return the failed result (or throw).
+
+#### Scenario: Exponential Backoff
+
+- **WHEN** `retry.backoff` is 'exponential'
+- **THEN** the delay SHALL increase for each attempt (e.g., `delay * 2^attempt`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "3.8.4",
+  "version": "4.0.4",
   "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",
@@ -15,16 +15,6 @@
     }
   },
   "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "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"
-  },
   "config": {
     "commitizen": {
       "path": "git-cz"
@@ -44,17 +34,10 @@
   ],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.28.0",
   "devDependencies": {
     "@commitlint/cli": "^20.3.1",
     "@commitlint/config-conventional": "^20.3.1",
     "@eslint/js": "^9.39.2",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^12.0.2",
-    "@semantic-release/npm": "^13.1.3",
-    "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/node": "^25.0.9",
     "@vitest/coverage-v8": "4.0.17",
     "eslint": "^9.39.2",
@@ -62,9 +45,17 @@
     "git-cz": "^4.9.0",
     "husky": "^9.1.7",
     "prettier": "^3.8.0",
-    "semantic-release": "^25.0.2",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.53.0",
     "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsc",
+    "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 .",
+    "commit": "git add . &&git-cz"
   }
-}
+}

package/release-please-config.json

@@ -0,0 +1,9 @@
+{
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@calmo/task-runner"
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

package/.gemini/commands/speckit.analyze.toml

@@ -1,188 +0,0 @@
-description = "Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation."
-
-prompt = """
----
-description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Goal
-
-Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`.
-
-## Operating Constraints
-
-**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
-
-**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`.
-
-## Execution Steps
-
-### 1. Initialize Analysis Context
-
-Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
-
-- SPEC = FEATURE_DIR/spec.md
-- PLAN = FEATURE_DIR/plan.md
-- TASKS = FEATURE_DIR/tasks.md
-
-Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
-For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\\''m Groot' (or double-quote if possible: "I'm Groot").
-
-### 2. Load Artifacts (Progressive Disclosure)
-
-Load only the minimal necessary context from each artifact:
-
-**From spec.md:**
-
-- Overview/Context
-- Functional Requirements
-- Non-Functional Requirements
-- User Stories
-- Edge Cases (if present)
-
-**From plan.md:**
-
-- Architecture/stack choices
-- Data Model references
-- Phases
-- Technical constraints
-
-**From tasks.md:**
-
-- Task IDs
-- Descriptions
-- Phase grouping
-- Parallel markers [P]
-- Referenced file paths
-
-**From constitution:**
-
-- Load `.specify/memory/constitution.md` for principle validation
-
-### 3. Build Semantic Models
-
-Create internal representations (do not include raw artifacts in output):
-
-- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
-- **User story/action inventory**: Discrete user actions with acceptance criteria
-- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
-- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
-
-### 4. Detection Passes (Token-Efficient Analysis)
-
-Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
-
-#### A. Duplication Detection
-
-- Identify near-duplicate requirements
-- Mark lower-quality phrasing for consolidation
-
-#### B. Ambiguity Detection
-
-- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
-- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
-
-#### C. Underspecification
-
-- Requirements with verbs but missing object or measurable outcome
-- User stories missing acceptance criteria alignment
-- Tasks referencing files or components not defined in spec/plan
-
-#### D. Constitution Alignment
-
-- Any requirement or plan element conflicting with a MUST principle
-- Missing mandated sections or quality gates from constitution
-
-#### E. Coverage Gaps
-
-- Requirements with zero associated tasks
-- Tasks with no mapped requirement/story
-- Non-functional requirements not reflected in tasks (e.g., performance, security)
-
-#### F. Inconsistency
-
-- Terminology drift (same concept named differently across files)
-- Data entities referenced in plan but absent in spec (or vice versa)
-- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
-- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
-
-### 5. Severity Assignment
-
-Use this heuristic to prioritize findings:
-
-- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
-- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
-- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
-- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
-
-### 6. Produce Compact Analysis Report
-
-Output a Markdown report (no file writes) with the following structure:
-
-## Specification Analysis Report
-
-| ID | Category | Severity | Location(s) | Summary | Recommendation |
-|----|----------|----------|-------------|---------|----------------|
-| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
-
-(Add one row per finding; generate stable IDs prefixed by category initial.)
-
-**Coverage Summary Table:**
-
-| Requirement Key | Has Task? | Task IDs | Notes |
-|-----------------|-----------|----------|-------|
-
-**Constitution Alignment Issues:** (if any)
-
-**Unmapped Tasks:** (if any)
-
-**Metrics:**
-
-- Total Requirements
-- Total Tasks
-- Coverage % (requirements with >=1 task)
-- Ambiguity Count
-- Duplication Count
-- Critical Issues Count
-
-### 7. Provide Next Actions
-
-At end of report, output a concise Next Actions block:
-
-- If CRITICAL issues exist: Recommend resolving before `/speckit.implement`
-- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
-- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
-
-### 8. Offer Remediation
-
-Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
-
-## Operating Principles
-
-### Context Efficiency
-
-- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
-- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
-- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
-- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
-
-### Analysis Guidelines
-
-- **NEVER modify files** (this is read-only analysis)
-- **NEVER hallucinate missing sections** (if absent, report them accurately)
-- **Prioritize constitution violations** (these are always CRITICAL)
-- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
-- **Report zero issues gracefully** (emit success report with coverage statistics)
-
-## Context
-
-{{args}}
-"""