builderman 1.2.0 → 1.4.0

package/README.md

@@ -1,129 +1,361 @@
-# **builderman**
-
-#### _A simple task runner for building and developing projects._
-
-<br />
+# builderman
+
+#### A dependency-aware task runner for building, developing, and orchestrating complex workflows.
+
+**builderman** lets you define tasks with explicit dependencies, lifecycle hooks, and multiple execution modes (`dev`, `build`, `deploy`, etc.), then compose them into pipelines that run **deterministically**, **observably**, and **safely**.
+
+It is designed for monorepos, long-running development processes, and CI/CD pipelines where **cleanup, cancellation, and failure handling matter**.
+
+---
+
+## Table of Contents
+
+> - [Key Features](#key-features)
+> - [Installation](#installation)
+> - [Quick Start](#quick-start)
+> - [Core Concepts](#core-concepts)
+>   - [Tasks](#tasks)
+>   - [Commands & Modes](#commands--modes)
+>   - [Environment Variables](#environment-variables)
+>   - [Dependencies](#dependencies)
+>   - [Pipelines](#pipelines)
+>   - [Pipeline Composition](#pipeline-composition)
+> - [Error Handling Guarantees](#error-handling-guarantees)
+> - [Cancellation](#cancellation)
+> - [Teardown](#teardown)
+>   - [Basic Teardown](#basic-teardown)
+>   - [Teardown Callbacks](#teardown-callbacks)
+>   - [Teardown Execution Rules](#teardown-execution-rules)
+> - [Skipping Tasks](#skipping-tasks)
+>   - [Strict Mode](#strict-mode)
+>   - [Task-Level Skip Override](#task-level-skip-override)
+> - [Execution Statistics](#execution-statistics)
+>   - [Pipeline Statistics](#pipeline-statistics)
+>   - [Task Statistics](#task-statistics)
+> - [When Should I Use builderman?](#when-should-i-use-builderman)
+
+## Key Features
+
+- 🧩 **Explicit dependency graph** — tasks run only when their dependencies are satisfied
+- 🔁 **Multi-mode commands** — `dev`, `build`, `deploy`, or any custom mode
+- ⏳ **Readiness detection** — wait for long-running processes to become “ready”
+- 🧹 **Guaranteed teardown** — automatic cleanup in reverse dependency order
+- 🛑 **Cancellation support** — abort pipelines using `AbortSignal`
+- 📊 **Rich execution statistics** — always available, even on failure
+- ❌ **Never throws** — failures are returned as structured results
+- 🧱 **Composable pipelines** — pipelines can be converted into tasks
+
+---
 
 ## Installation
 
-```bash
+```sh
 npm install builderman
 ```
 
-## Usage
+---
+
+## Quick Start
 
 ```ts
 import { task, pipeline } from "builderman"
 
-const task1 = task({
+const build = task({
+  name: "build",
+  commands: { build: "tsc" },
+  cwd: "packages/my-package", // Optional: defaults to "."
+})
+
+const test = task({
+  name: "test",
+  commands: { build: "npm test" },
+  dependencies: [build],
+  cwd: "packages/my-package",
+})
+
+const result = await pipeline([build, test]).run({
+  command: "build",
+})
+
+if (!result.ok) {
+  console.error("Pipeline failed:", result.error.message)
+}
+```
+
+This defines a simple dependency graph where `test` runs only after `build` completes successfully.
+
+---
+
+## Core Concepts
+
+### Tasks
+
+A **task** represents a unit of work. Each task:
+
+- Has a unique name
+- Defines commands for one or more modes
+- May depend on other tasks
+- May register teardown logic
+- Has an optional working directory (`cwd`, defaults to `"."`)
+
+```ts
+import { task } from "builderman"
+
+const libTask = task({
   name: "lib:build",
   commands: {
     build: "tsc",
     dev: {
       run: "tsc --watch",
-      readyWhen: (stdout) => {
-        // mark this task as ready when the process is watching for file changes
-        return stdout.includes("Watching for file changes.")
-      },
+      readyWhen: (stdout) => stdout.includes("Watching for file changes."),
     },
   },
   cwd: "packages/lib",
 })
+```
 
-const task2 = task({
-  name: "consumer:dev",
+---
+
+### Commands & Modes
+
+Each task can define commands for different **modes** (for example `dev`, `build`, `deploy`).
+
+When running a pipeline:
+
+- If `command` is provided, that mode is used
+- Otherwise:
+  - `"build"` is used when `NODE_ENV === "production"`
+  - `"dev"` is used in all other cases
+
+Commands may be:
+
+- A string (executed directly), or
+- An object with:
+  - `run`: the command to execute
+  - `readyWhen`: a predicate that marks the task as ready
+  - `teardown`: cleanup logic to run after completion
+  - `env`: environment variables specific to this command
+
+---
+
+### Environment Variables
+
+Environment variables can be provided at multiple levels, with more specific levels overriding less specific ones:
+
+**Precedence order (highest to lowest):**
+
+1. Command-level `env` (in command config)
+2. Task-level `env` (in task config)
+3. Pipeline-level `env` (in `pipeline.run()`)
+4. Process environment variables
+
+#### Command-Level Environment Variables
+
+```ts
+const apiTask = task({
+  name: "api",
+  commands: {
+    dev: {
+      run: "npm run dev",
+      env: {
+        PORT: "3000",
+        NODE_ENV: "development",
+      },
+    },
+  },
+})
+```
+
+#### Task-Level Environment Variables
+
+```ts
+const apiTask = task({
+  name: "api",
   commands: {
-    build: "npm run build",
     dev: "npm run dev",
-    deploy: "npm run deploy",
+    build: "npm run build",
+  },
+  env: {
+    API_URL: "http://localhost:3000",
+    LOG_LEVEL: "debug",
   },
-  cwd: "packages/consumer",
-  dependencies: [task1],
 })
+```
+
+#### Pipeline-Level Environment Variables
 
-await pipeline([task1, task2]).run({
-  // default command is "build" if process.NODE_ENV is "production", otherwise "dev".
-  command: "deploy",
-  onTaskBegin: (taskName) => {
-    console.log(`[${taskName}] Starting...`)
+```ts
+const result = await pipeline([apiTask]).run({
+  env: {
+    DATABASE_URL: "postgres://localhost/mydb",
+    REDIS_URL: "redis://localhost:6379",
   },
-  onTaskComplete: (taskName) => {
-    console.log(`[${taskName}] Complete!`)
+})
+```
+
+#### Nested Pipeline Environment Variables
+
+When converting a pipeline to a task, you can provide environment variables that will be merged with the outer pipeline's environment:
+
+```ts
+const innerPipeline = pipeline([
+  /* ... */
+])
+const innerTask = innerPipeline.toTask({
+  name: "inner",
+  env: {
+    INNER_VAR: "inner-value",
   },
-  onPipelineComplete: () => {
-    console.log("All tasks complete! 🎉")
+})
+
+const outerPipeline = pipeline([innerTask])
+const result = await outerPipeline.run({
+  env: {
+    OUTER_VAR: "outer-value",
   },
-  onPipelineError: (error) => {
-    console.error(`Pipeline error: ${error.message}`)
+})
+```
+
+In this example, tasks in `innerPipeline` will receive both `INNER_VAR` and `OUTER_VAR`, with `INNER_VAR` taking precedence if there's a conflict.
+
+---
+
+### Dependencies
+
+Tasks may depend on other tasks. A task will not start until all its dependencies have completed (or been skipped).
+
+```ts
+const consumerTask = task({
+  name: "consumer:dev",
+  commands: {
+    build: "npm run build",
+    dev: "npm run dev",
   },
+  cwd: "packages/consumer",
+  dependencies: [libTask],
 })
 ```
 
-## Error Handling
+---
+
+### Pipelines
 
-Pipeline errors are provided as `PipelineError` instances with error codes for easier handling:
+A **pipeline** executes a set of tasks according to their dependency graph.
 
 ```ts
-import { pipeline, PipelineError } from "builderman"
+import { pipeline } from "builderman"
 
-await pipeline([task1, task2]).run({
-  onPipelineError: (error) => {
-    switch (error.code) {
-      case PipelineError.Aborted:
-        console.error("Pipeline was cancelled")
-        break
-      case PipelineError.TaskFailed:
-        console.error(`Task failed: ${error.message}`)
-        break
-      case PipelineError.ProcessTerminated:
-        console.error("Process was terminated")
-        break
-      case PipelineError.InvalidTask:
-        console.error(`Invalid task configuration: ${error.message}`)
-        break
-      case PipelineError.InvalidSignal:
-        console.error("Invalid abort signal")
-        break
-    }
+const result = await pipeline([libTask, consumerTask]).run({
+  command: "dev",
+  onTaskBegin: (name) => {
+    console.log(`[${name}] starting`)
+  },
+  onTaskComplete: (name) => {
+    console.log(`[${name}] complete`)
   },
 })
 ```
 
-## Cancellation
+---
+
+### Pipeline Composition
 
-You can cancel a running pipeline by providing an `AbortSignal`:
+Pipelines can be converted into tasks and composed like any other unit of work.
+
+```ts
+const build = pipeline([
+  /* ... */
+])
+const test = pipeline([
+  /* ... */
+])
+const deploy = pipeline([
+  /* ... */
+])
+
+const buildTask = build.toTask({ name: "build" })
+const testTask = test.toTask({
+  name: "test",
+  dependencies: [buildTask],
+  env: { TEST_ENV: "test-value" }, // Optional: env for nested pipeline
+})
+const deployTask = deploy.toTask({ name: "deploy", dependencies: [testTask] })
+
+const ci = pipeline([buildTask, testTask, deployTask])
+const result = await ci.run()
+```
+
+When a pipeline is converted to a task, it becomes a **single node** in the dependency graph. The nested pipeline must fully complete before dependents can start.
+
+---
+
+## Error Handling Guarantees
+
+**builderman pipelines never throw.**
+
+All failures — including task errors, invalid configuration, cancellation, and process termination — are reported through a structured `RunResult`.
 
 ```ts
 import { pipeline, PipelineError } from "builderman"
 
-const abortController = new AbortController()
+const result = await pipeline([libTask, consumerTask]).run()
 
-const runPromise = pipeline([task1, task2]).run({
-  signal: abortController.signal,
-  onPipelineError: (error) => {
-    if (error.code === PipelineError.Aborted) {
+if (!result.ok) {
+  switch (result.error.code) {
+    case PipelineError.Aborted:
       console.error("Pipeline was cancelled")
-    }
-  },
+      break
+    case PipelineError.TaskFailed:
+      console.error(`Task failed: ${result.error.message}`)
+      break
+    case PipelineError.ProcessTerminated:
+      console.error("Process was terminated")
+      break
+    case PipelineError.InvalidTask:
+      console.error(`Invalid task configuration: ${result.error.message}`)
+      break
+    case PipelineError.InvalidSignal:
+      console.error("Invalid abort signal")
+      break
+  }
+}
+```
+
+Execution statistics are **always available**, even on failure.
+
+---
+
+## Cancellation
+
+You can cancel a running pipeline using an `AbortSignal`.
+
+```ts
+const controller = new AbortController()
+
+const runPromise = pipeline([libTask, consumerTask]).run({
+  signal: controller.signal,
 })
 
-// Cancel the pipeline after 5 seconds
+// Cancel after 5 seconds
 setTimeout(() => {
-  abortController.abort()
+  controller.abort()
 }, 5000)
 
-try {
-  await runPromise
-} catch (error) {
-  if (error instanceof PipelineError && error.code === PipelineError.Aborted) {
-    // Pipeline was cancelled
-  }
+const result = await runPromise
+
+if (!result.ok && result.error.code === PipelineError.Aborted) {
+  console.error("Pipeline was cancelled")
+  console.log(`Tasks still running: ${result.stats.summary.running}`)
 }
 ```
 
+---
+
 ## Teardown
 
-Tasks can specify teardown commands that run automatically when the task completes or fails. Teardowns are executed in reverse dependency order (dependents before dependencies) to ensure proper cleanup.
+Tasks may specify teardown commands that run automatically when a task completes or fails.
+
+Teardowns are executed **in reverse dependency order** (dependents before dependencies) to ensure safe cleanup.
 
 ### Basic Teardown
 
@@ -137,92 +369,63 @@ const dbTask = task({
     },
     build: "echo build",
   },
-  cwd: ".",
 })
 ```
 
+---
+
 ### Teardown Callbacks
 
-You can monitor teardown execution with callbacks. Note that teardown failures do not cause the pipeline to fail - they are fire-and-forget cleanup operations:
+You can observe teardown execution using callbacks. Teardown failures do **not** cause the pipeline to fail — they are best-effort cleanup operations.
 
 ```ts
-await pipeline([dbTask]).run({
+const result = await pipeline([dbTask]).run({
   onTaskTeardown: (taskName) => {
-    console.log(`[${taskName}] Starting teardown...`)
+    console.log(`[${taskName}] starting teardown`)
   },
   onTaskTeardownError: (taskName, error) => {
-    console.error(`[${taskName}] Teardown failed: ${error.message}`)
-    // error is a regular Error instance (not a PipelineError)
-    // Teardown failures do not affect pipeline success/failure
+    console.error(`[${taskName}] teardown failed: ${error.message}`)
   },
 })
 ```
 
+Teardown results are recorded in task statistics.
+
+---
+
 ### Teardown Execution Rules
 
 Teardowns run when:
 
-- ✅ The command entered the running state (regardless of success or failure)
-- ✅ The pipeline completes successfully
-- ✅ The pipeline fails after tasks have started
+- The command entered the running state
+- The pipeline completes successfully
+- The pipeline fails after tasks have started
 
 Teardowns do **not** run when:
 
-- ❌ The task was skipped (no command for the current mode)
-- ❌ The task failed before starting (spawn error)
-- ❌ The pipeline never began execution
+- The task was skipped
+- The task failed before starting (spawn error)
+- The pipeline never began execution
 
-### Reverse Dependency Order
-
-Teardowns execute in reverse dependency order to ensure dependents are cleaned up before their dependencies:
-
-```ts
-const db = task({
-  name: "db",
-  commands: {
-    dev: { run: "docker-compose up", teardown: "docker-compose down" },
-    build: "echo build",
-  },
-  cwd: ".",
-})
-
-const api = task({
-  name: "api",
-  commands: {
-    dev: { run: "npm run dev", teardown: "echo stopping api" },
-    build: "echo build",
-  },
-  cwd: ".",
-  dependencies: [db], // api depends on db
-})
-
-// Teardown order: api first, then db
-await pipeline([db, api]).run()
-```
+---
 
 ## Skipping Tasks
 
-Tasks can be automatically skipped when they don't have a command for the current mode. This is useful for multi-mode pipelines where some tasks are only relevant in certain contexts.
+If a task does not define a command for the current mode, it is **skipped** by default.
 
-### Default Behavior
+Skipped tasks:
 
-If a task has no command for the current mode, it is **skipped**:
-
-- ✅ The task participates in the dependency graph
-- ✅ The task resolves immediately (satisfies dependencies)
-- ✅ Dependents are unblocked
-- ❌ No command is executed
-- ❌ No teardown is registered
-- ❌ No readiness is waited for
+- Participate in the dependency graph
+- Resolve immediately
+- Unblock dependent tasks
+- Do not execute commands or teardowns
 
 ```ts
 const dbTask = task({
   name: "database",
   commands: {
     dev: "docker-compose up",
-    // No build command - will be skipped in build mode
   },
-  cwd: ".",
 })
 
 const apiTask = task({
@@ -231,131 +434,108 @@ const apiTask = task({
     dev: "npm run dev",
     build: "npm run build",
   },
-  cwd: ".",
-  dependencies: [dbTask], // dbTask will be skipped, but apiTask will still run
+  dependencies: [dbTask],
 })
 
-await pipeline([dbTask, apiTask]).run({
+const result = await pipeline([dbTask, apiTask]).run({
   command: "build",
   onTaskSkipped: (taskName, mode) => {
-    console.log(`[${taskName}] skipped (no command for mode "${mode}")`)
+    console.log(`[${taskName}] skipped (no "${mode}" command)`)
   },
 })
 ```
 
+---
+
 ### Strict Mode
 
-In strict mode, missing commands cause the pipeline to fail. Use this for CI/release pipelines where every task is expected to participate:
+In **strict mode**, missing commands cause the pipeline to fail. This is useful for CI and release pipelines.
 
 ```ts
-await pipeline([dbTask, apiTask]).run({
+const result = await pipeline([dbTask, apiTask]).run({
   command: "build",
-  strict: true, // Missing commands will cause pipeline to fail
+  strict: true,
 })
+
+if (!result.ok) {
+  console.error("Pipeline failed in strict mode:", result.error.message)
+}
 ```
 
-### Task-Level Override
+---
+
+### Task-Level Skip Override
 
-Even with global strict mode, you can explicitly allow a task to be skipped:
+Tasks may explicitly allow skipping, even when strict mode is enabled.
 
 ```ts
 const dbTask = task({
   name: "database",
   commands: {
     dev: "docker-compose up",
-    // No build command, but explicitly allowed to skip
   },
-  cwd: ".",
-  allowSkip: true, // Explicitly allow skipping even in strict mode
+  allowSkip: true,
 })
 
-await pipeline([dbTask]).run({
+const result = await pipeline([dbTask]).run({
   command: "build",
-  strict: true, // Global strict mode
-  // dbTask will still be skipped because allowSkip: true
+  strict: true,
 })
 ```
 
-### Nested Pipeline Behavior
-
-When a pipeline is converted to a task, skip behavior is preserved:
+---
 
-- If **all** inner tasks are skipped → outer task is skipped
-- If **some** run, some skip → outer task is completed
-- If **any** fail → outer task fails
+## Execution Statistics
 
-```ts
-const innerPipeline = pipeline([
-  task({ name: "inner1", commands: { dev: "..." }, cwd: "." }),
-  task({ name: "inner2", commands: { dev: "..." }, cwd: "." }),
-])
+Every pipeline run returns detailed execution statistics.
 
-const outerTask = innerPipeline.toTask({ name: "outer" })
+### Pipeline Statistics
 
-// If all inner tasks are skipped in build mode, outer task is also skipped
-await pipeline([outerTask]).run({ command: "build" })
+```ts
+console.log(result.stats.status) // "success" | "failed" | "aborted"
+console.log(result.stats.command) // Executed mode
+console.log(result.stats.durationMs) // Total execution time
+console.log(result.stats.summary.total)
+console.log(result.stats.summary.completed)
+console.log(result.stats.summary.failed)
+console.log(result.stats.summary.skipped)
+console.log(result.stats.summary.running)
 ```
 
-## Pipeline Composition
-
-Build complex workflows by composing tasks and pipelines together.
+---
 
-### Task Chaining
+### Task Statistics
 
-Chain tasks together using `andThen()` to create a pipeline that will run the tasks in order, automatically adding the previous task as a dependency:
+Each task provides detailed per-task data:
 
 ```ts
-import { task } from "builderman"
+for (const task of Object.values(result.stats.tasks)) {
+  console.log(task.name, task.status)
+  console.log(task.durationMs)
 
-const build = task({
-  name: "compile",
-  commands: {
-    build: "tsc",
-    dev: {
-      run: "tsc --watch",
-      readyWhen: (output) => output.includes("Watching for file changes."),
-    },
-  },
-  cwd: "packages/lib",
-}).andThen({
-  name: "bundle",
-  commands: {
-    build: "rollup",
-    dev: {
-      run: "rollup --watch",
-      readyWhen: (output) => output.includes("Watching for file changes."),
-    },
-  },
-  cwd: "packages/lib",
-})
+  if (task.status === "failed") {
+    console.error(task.error?.message)
+    console.error(task.exitCode)
+  }
 
-await build.run()
+  if (task.teardown) {
+    console.log("Teardown:", task.teardown.status)
+  }
+}
 ```
 
-### Composing Pipelines as Tasks
+---
 
-Convert pipelines to tasks and compose them with explicit dependencies:
+## When Should I Use builderman?
 
-```ts
-const build = pipeline([
-  /* ... */
-])
-const test = pipeline([
-  /* ... */
-])
-const deploy = pipeline([
-  /* ... */
-])
+**builderman** is a good fit when:
 
-// Convert to tasks first
-const buildTask = build.toTask({ name: "build" })
-const testTask = test.toTask({ name: "test", dependencies: [buildTask] })
-const deployTask = deploy.toTask({ name: "deploy", dependencies: [testTask] })
+- You have dependent tasks that must run in a strict order
+- You run long-lived dev processes that need readiness detection
+- Cleanup matters (databases, containers, servers)
+- You want structured results instead of log-scraping
 
-// Compose into final pipeline
-const ci = pipeline([buildTask, testTask, deployTask])
-
-await ci.run()
-```
+It may be overkill if:
 
-**Note:** When a pipeline is converted to a task, it becomes a single unit in the dependency graph. The nested pipeline will execute completely before any dependent tasks can start.
+- You only need a few linear npm scripts
+- You do not need dependency graphs or teardown guarantees