builderman 1.1.0 → 1.3.0

package/README.md

@@ -1,86 +1,179 @@
-# **builderman**
+# builderman
 
-#### _A simple task runner for building and developing projects._
+#### A dependency-aware task runner for building, developing, and orchestrating complex workflows.
 
-<br />
+**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)
+  - [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: ".",
+})
+
+const test = task({
+  name: "test",
+  commands: { build: "npm test" },
+  cwd: ".",
+  dependencies: [build],
+})
+
+const result = await pipeline([build, test]).run()
+
+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
+
+```ts
+import { task } from "builderman"
+
+const libTask = task({
   name: "lib:build",
   commands: {
-    dev: "tsc --watch",
     build: "tsc",
+    dev: {
+      run: "tsc --watch",
+      readyWhen: (stdout) => stdout.includes("Watching for file changes."),
+    },
   },
   cwd: "packages/lib",
-  isReady: (stdout) => {
-    // mark this this task as ready when the process is watching for file changes
-    return stdout.includes("Watching for file changes.")
-  },
 })
+```
+
+---
+
+### 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
 
-const task2 = task({
+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
+
+---
+
+### 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: {
-    dev: "npm run dev",
     build: "npm run build",
+    dev: "npm run dev",
   },
   cwd: "packages/consumer",
-  dependencies: [task1],
-})
-
-await pipeline([task1, task2]).run({
-  onTaskError: (taskName, error) => {
-    console.error(`[${taskName}] Error: ${error.message}`)
-  },
-  onTaskComplete: (taskName) => {
-    console.log(`[${taskName}] Complete!`)
-  },
-  onPipelineComplete: () => {
-    console.log("All tasks complete! 🎉")
-  },
-  onPipelineError: (error) => {
-    console.error(`Pipeline error: ${error.message}`)
-  },
+  dependencies: [libTask],
 })
 ```
 
-## Pipeline Composition
-
-Build complex workflows by composing tasks and pipelines together.
+---
 
-### Task Chaining
+### Pipelines
 
-Chain tasks together using `andThen()` to create a pipeline that will run the tasks in order:
+A **pipeline** executes a set of tasks according to their dependency graph.
 
 ```ts
-import { task, pipeline } from "builderman"
+import { pipeline } from "builderman"
 
-const build = task({
-  name: "compile",
-  commands: { dev: "tsc --watch", build: "tsc" },
-  cwd: "packages/lib",
-}).andThen({
-  name: "bundle",
-  commands: { dev: "rollup --watch", build: "rollup" },
-  cwd: "packages/lib",
+const result = await pipeline([libTask, consumerTask]).run({
+  command: "dev",
+  onTaskBegin: (name) => {
+    console.log(`[${name}] starting`)
+  },
+  onTaskComplete: (name) => {
+    console.log(`[${name}] complete`)
+  },
 })
-
-await build.run()
 ```
 
-### Composing Pipelines as Tasks
+---
+
+### Pipeline Composition
 
-Convert pipelines to tasks and compose them with explicit dependencies:
+Pipelines can be converted into tasks and composed like any other unit of work.
 
 ```ts
 const build = pipeline([
@@ -93,15 +186,269 @@ const deploy = pipeline([
   /* ... */
 ])
 
-// 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] })
 
-// Compose into final pipeline
 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 result = await pipeline([libTask, consumerTask]).run()
+
+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()
 
-await ci.run()
+const runPromise = pipeline([libTask, consumerTask]).run({
+  signal: controller.signal,
+})
+
+// Cancel after 5 seconds
+setTimeout(() => {
+  controller.abort()
+}, 5000)
+
+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}`)
+}
 ```
 
-**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.
+---
+
+## Teardown
+
+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
+
+```ts
+const dbTask = task({
+  name: "database",
+  commands: {
+    dev: {
+      run: "docker-compose up",
+      teardown: "docker-compose down",
+    },
+    build: "echo build",
+  },
+  cwd: ".",
+})
+```
+
+---
+
+### Teardown Callbacks
+
+You can observe teardown execution using callbacks. Teardown failures do **not** cause the pipeline to fail — they are best-effort cleanup operations.
+
+```ts
+const result = await pipeline([dbTask]).run({
+  onTaskTeardown: (taskName) => {
+    console.log(`[${taskName}] starting teardown`)
+  },
+  onTaskTeardownError: (taskName, error) => {
+    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
+- The pipeline completes successfully
+- The pipeline fails after tasks have started
+
+Teardowns do **not** run when:
+
+- The task was skipped
+- The task failed before starting (spawn error)
+- The pipeline never began execution
+
+---
+
+## Skipping Tasks
+
+If a task does not define a command for the current mode, it is **skipped** by default.
+
+Skipped tasks:
+
+- 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",
+  },
+  cwd: ".",
+})
+
+const apiTask = task({
+  name: "api",
+  commands: {
+    dev: "npm run dev",
+    build: "npm run build",
+  },
+  cwd: ".",
+  dependencies: [dbTask],
+})
+
+const result = await pipeline([dbTask, apiTask]).run({
+  command: "build",
+  onTaskSkipped: (taskName, mode) => {
+    console.log(`[${taskName}] skipped (no "${mode}" command)`)
+  },
+})
+```
+
+---
+
+### Strict Mode
+
+In **strict mode**, missing commands cause the pipeline to fail. This is useful for CI and release pipelines.
+
+```ts
+const result = await pipeline([dbTask, apiTask]).run({
+  command: "build",
+  strict: true,
+})
+
+if (!result.ok) {
+  console.error("Pipeline failed in strict mode:", result.error.message)
+}
+```
+
+---
+
+### Task-Level Skip Override
+
+Tasks may explicitly allow skipping, even when strict mode is enabled.
+
+```ts
+const dbTask = task({
+  name: "database",
+  commands: {
+    dev: "docker-compose up",
+  },
+  cwd: ".",
+  allowSkip: true,
+})
+
+const result = await pipeline([dbTask]).run({
+  command: "build",
+  strict: true,
+})
+```
+
+---
+
+## Execution Statistics
+
+Every pipeline run returns detailed execution statistics.
+
+### Pipeline Statistics
+
+```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)
+```
+
+---
+
+### Task Statistics
+
+Each task provides detailed per-task data:
+
+```ts
+for (const task of Object.values(result.stats.tasks)) {
+  console.log(task.name, task.status)
+  console.log(task.durationMs)
+
+  if (task.status === "failed") {
+    console.error(task.error?.message)
+    console.error(task.exitCode)
+  }
+
+  if (task.teardown) {
+    console.log("Teardown:", task.teardown.status)
+  }
+}
+```
+
+---
+
+## When Should I Use builderman?
+
+**builderman** is a good fit when:
+
+- 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
+
+It may be overkill if:
+
+- You only need a few linear npm scripts
+- You do not need dependency graphs or teardown guarantees

package/dist/graph.js

@@ -1,8 +1,6 @@
 import { $TASK_INTERNAL } from "./constants.js";
-import { validateTasks } from "./util.js";
 export function createTaskGraph(tasks) {
     const nodes = new Map();
-    validateTasks(tasks);
     // Create nodes for all tasks
     for (const task of tasks) {
         const { id: taskId } = task[$TASK_INTERNAL];

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { task } from "./task.js";
 export { pipeline } from "./pipeline.js";
-export type { Task, Pipeline, TaskConfig } from "./types.js";
+export { PipelineError, type PipelineErrorCode } from "./pipeline-error.js";
+export type { Task, Pipeline, TaskConfig, Command, CommandConfig, Commands, PipelineRunConfig, PipelineTaskConfig, RunResult, PipelineStats, TaskStats, TaskStatus, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { task } from "./task.js";
 export { pipeline } from "./pipeline.js";
+export { PipelineError } from "./pipeline-error.js";

package/dist/modules/signal-handler.d.ts

@@ -0,0 +1,13 @@
+export interface SignalHandlerConfig {
+    abortSignal?: AbortSignal;
+    onProcessTerminated: (message: string) => void;
+    onAborted: () => void;
+}
+export interface SignalHandler {
+    cleanup(): void;
+}
+/**
+ * Creates a signal handler for pipeline execution.
+ * Handles process termination signals (SIGINT, SIGTERM, etc.) and abort signals.
+ */
+export declare function createSignalHandler({ abortSignal, onAborted, onProcessTerminated, }: SignalHandlerConfig): SignalHandler;

package/dist/modules/signal-handler.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a signal handler for pipeline execution.
+ * Handles process termination signals (SIGINT, SIGTERM, etc.) and abort signals.
+ */
+export function createSignalHandler({ abortSignal, onAborted, onProcessTerminated, }) {
+    // Handle termination signals
+    const processTerminationListenerCleanups = [
+        "SIGINT",
+        "SIGTERM",
+        "SIGQUIT",
+        "SIGBREAK",
+    ].map((sig) => {
+        const handleSignal = () => {
+            onProcessTerminated(`Received ${sig}`);
+        };
+        process.once(sig, handleSignal);
+        return () => {
+            process.removeListener(sig, handleSignal);
+        };
+    });
+    // Handle abort signal if provided
+    let signalCleanup = null;
+    if (abortSignal) {
+        abortSignal.addEventListener("abort", onAborted);
+        signalCleanup = () => {
+            abortSignal.removeEventListener("abort", onAborted);
+        };
+    }
+    return {
+        /**
+         * Cleans up all signal listeners.
+         */
+        cleanup() {
+            processTerminationListenerCleanups.forEach((cleanup) => cleanup());
+            signalCleanup?.();
+        },
+    };
+}

package/dist/modules/task-executor.d.ts

@@ -0,0 +1,25 @@
+import { type ChildProcess } from "node:child_process";
+import { PipelineError } from "../pipeline-error.js";
+import type { Task, Pipeline, PipelineRunConfig, TaskGraph, TaskStats } from "../types.js";
+import type { SchedulerInput } from "../scheduler.js";
+import type { TeardownManager } from "./teardown-manager.js";
+export interface TaskExecutorConfig {
+    spawn: typeof import("node:child_process").spawn;
+    signal?: AbortSignal;
+    config?: PipelineRunConfig;
+    graph: TaskGraph;
+    runningTasks: Map<string, ChildProcess>;
+    runningPipelines: Map<string, {
+        stop: () => void;
+    }>;
+    teardownManager: TeardownManager;
+    pipelineTasksCache: WeakMap<Pipeline, Task[]>;
+    failPipeline: (error: PipelineError) => Promise<void>;
+    advanceScheduler: (input?: SchedulerInput) => void;
+    updateTaskStatus: (taskId: string, updates: Partial<TaskStats>) => void;
+    taskStats: Map<string, TaskStats>;
+}
+/**
+ * Executes a task (either a regular task or a nested pipeline).
+ */
+export declare function executeTask(task: Task, executorConfig: TaskExecutorConfig): void;