builderman 1.1.0 → 1.2.0

package/README.md

@@ -18,29 +18,34 @@ import { task, pipeline } from "builderman"
 const task1 = task({
   name: "lib:build",
   commands: {
-    dev: "tsc --watch",
     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.")
+      },
+    },
   },
   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.")
-  },
 })
 
 const task2 = task({
   name: "consumer:dev",
   commands: {
-    dev: "npm run dev",
     build: "npm run build",
+    dev: "npm run dev",
+    deploy: "npm run deploy",
   },
   cwd: "packages/consumer",
   dependencies: [task1],
 })
 
 await pipeline([task1, task2]).run({
-  onTaskError: (taskName, error) => {
-    console.error(`[${taskName}] Error: ${error.message}`)
+  // default command is "build" if process.NODE_ENV is "production", otherwise "dev".
+  command: "deploy",
+  onTaskBegin: (taskName) => {
+    console.log(`[${taskName}] Starting...`)
   },
   onTaskComplete: (taskName) => {
     console.log(`[${taskName}] Complete!`)
@@ -54,24 +59,273 @@ await pipeline([task1, task2]).run({
 })
 ```
 
+## Error Handling
+
+Pipeline errors are provided as `PipelineError` instances with error codes for easier handling:
+
+```ts
+import { pipeline, PipelineError } 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
+    }
+  },
+})
+```
+
+## Cancellation
+
+You can cancel a running pipeline by providing an `AbortSignal`:
+
+```ts
+import { pipeline, PipelineError } from "builderman"
+
+const abortController = new AbortController()
+
+const runPromise = pipeline([task1, task2]).run({
+  signal: abortController.signal,
+  onPipelineError: (error) => {
+    if (error.code === PipelineError.Aborted) {
+      console.error("Pipeline was cancelled")
+    }
+  },
+})
+
+// Cancel the pipeline after 5 seconds
+setTimeout(() => {
+  abortController.abort()
+}, 5000)
+
+try {
+  await runPromise
+} catch (error) {
+  if (error instanceof PipelineError && error.code === PipelineError.Aborted) {
+    // Pipeline was cancelled
+  }
+}
+```
+
+## 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.
+
+### 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 monitor teardown execution with callbacks. Note that teardown failures do not cause the pipeline to fail - they are fire-and-forget cleanup operations:
+
+```ts
+await pipeline([dbTask]).run({
+  onTaskTeardown: (taskName) => {
+    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
+  },
+})
+```
+
+### 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
+
+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
+
+### 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.
+
+### Default Behavior
+
+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
+
+```ts
+const dbTask = task({
+  name: "database",
+  commands: {
+    dev: "docker-compose up",
+    // No build command - will be skipped in build mode
+  },
+  cwd: ".",
+})
+
+const apiTask = task({
+  name: "api",
+  commands: {
+    dev: "npm run dev",
+    build: "npm run build",
+  },
+  cwd: ".",
+  dependencies: [dbTask], // dbTask will be skipped, but apiTask will still run
+})
+
+await pipeline([dbTask, apiTask]).run({
+  command: "build",
+  onTaskSkipped: (taskName, mode) => {
+    console.log(`[${taskName}] skipped (no command for mode "${mode}")`)
+  },
+})
+```
+
+### 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:
+
+```ts
+await pipeline([dbTask, apiTask]).run({
+  command: "build",
+  strict: true, // Missing commands will cause pipeline to fail
+})
+```
+
+### Task-Level Override
+
+Even with global strict mode, you can explicitly allow a task to be skipped:
+
+```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
+})
+
+await pipeline([dbTask]).run({
+  command: "build",
+  strict: true, // Global strict mode
+  // dbTask will still be skipped because allowSkip: 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
+
+```ts
+const innerPipeline = pipeline([
+  task({ name: "inner1", commands: { dev: "..." }, cwd: "." }),
+  task({ name: "inner2", commands: { dev: "..." }, cwd: "." }),
+])
+
+const outerTask = innerPipeline.toTask({ name: "outer" })
+
+// If all inner tasks are skipped in build mode, outer task is also skipped
+await pipeline([outerTask]).run({ command: "build" })
+```
+
 ## Pipeline Composition
 
 Build complex workflows by composing tasks and pipelines together.
 
 ### Task Chaining
 
-Chain tasks together using `andThen()` to create a pipeline that will run the tasks in order:
+Chain tasks together using `andThen()` to create a pipeline that will run the tasks in order, automatically adding the previous task as a dependency:
 
 ```ts
-import { task, pipeline } from "builderman"
+import { task } from "builderman"
 
 const build = task({
   name: "compile",
-  commands: { dev: "tsc --watch", build: "tsc" },
+  commands: {
+    build: "tsc",
+    dev: {
+      run: "tsc --watch",
+      readyWhen: (output) => output.includes("Watching for file changes."),
+    },
+  },
   cwd: "packages/lib",
 }).andThen({
   name: "bundle",
-  commands: { dev: "rollup --watch", build: "rollup" },
+  commands: {
+    build: "rollup",
+    dev: {
+      run: "rollup --watch",
+      readyWhen: (output) => output.includes("Watching for file changes."),
+    },
+  },
   cwd: "packages/lib",
 })
 

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/pipeline.d.ts

@@ -1,5 +1,23 @@
 import type { Pipeline, Task } from "./types.js";
 /**
  * Creates a pipeline that manages task execution with dependency-based coordination.
+ * @param tasks - The tasks to include in the pipeline.
+ * @returns A pipeline that can be used to execute the tasks.
+ * @example
+ * const task1 = task({ name: "task1", commands: { dev: "echo task1" }, cwd: "." })
+ * const task2 = task({ name: "task2", commands: { dev: "echo task2" }, cwd: ".", dependencies: [task1] })
+ * await pipeline([task1, task2]).run()
  */
 export declare function pipeline(tasks: Task[]): Pipeline;
+type PipelineErrorCode = typeof PipelineError.Aborted | typeof PipelineError.ProcessTerminated | typeof PipelineError.TaskFailed | typeof PipelineError.InvalidSignal | typeof PipelineError.InvalidTask;
+export declare class PipelineError extends Error {
+    readonly code: PipelineErrorCode;
+    readonly taskName?: string;
+    constructor(message: string, code: PipelineErrorCode, taskName?: string);
+    static Aborted: 0;
+    static ProcessTerminated: 1;
+    static TaskFailed: 2;
+    static InvalidSignal: 3;
+    static InvalidTask: 4;
+}
+export {};

package/dist/pipeline.js

@@ -9,8 +9,16 @@ import { validateTasks } from "./util.js";
 // Module-level cache for pipeline-to-task conversions
 // Key: Pipeline, Value: Map of name -> Task
 const pipelineTaskCache = new WeakMap();
+// Store tasks for each pipeline (for nested pipeline skip tracking)
+const pipelineTasksCache = new WeakMap();
 /**
  * Creates a pipeline that manages task execution with dependency-based coordination.
+ * @param tasks - The tasks to include in the pipeline.
+ * @returns A pipeline that can be used to execute the tasks.
+ * @example
+ * const task1 = task({ name: "task1", commands: { dev: "echo task1" }, cwd: "." })
+ * const task2 = task({ name: "task2", commands: { dev: "echo task2" }, cwd: ".", dependencies: [task1] })
+ * await pipeline([task1, task2]).run()
  */
 export function pipeline(tasks) {
     const graph = createTaskGraph(tasks);
@@ -21,7 +29,7 @@ export function pipeline(tasks) {
             validateTasks(config.dependencies);
             const syntheticTask = task({
                 name: config.name,
-                commands: { dev: ":", build: ":" }, // Dummy commands (no-op)
+                commands: {},
                 cwd: ".", // Dummy cwd
                 dependencies: [...(config.dependencies || [])],
             });
@@ -38,9 +46,15 @@ export function pipeline(tasks) {
         },
         async run(config) {
             const spawnFn = config?.spawn ?? spawn;
+            const signal = config?.signal;
             const runningTasks = new Map();
             const runningPipelines = new Map();
+            const teardownCommands = new Map();
             let failed = false;
+            // Check if signal is already aborted
+            if (signal?.aborted) {
+                throw new PipelineError("Aborted", PipelineError.Aborted);
+            }
             const scheduler = createScheduler(graph);
             let completionResolver = null;
             let completionRejector = null;
@@ -48,7 +62,127 @@ export function pipeline(tasks) {
                 completionResolver = resolve;
                 completionRejector = reject;
             });
-            const failPipeline = (error) => {
+            const executeTeardown = (taskId) => {
+                const teardown = teardownCommands.get(taskId);
+                if (!teardown)
+                    return Promise.resolve();
+                // Remove from map so it doesn't run again
+                teardownCommands.delete(taskId);
+                config?.onTaskTeardown?.(teardown.taskName);
+                return new Promise((resolve) => {
+                    try {
+                        const teardownProcess = spawnFn(teardown.command, {
+                            cwd: teardown.cwd,
+                            stdio: "inherit",
+                            shell: true,
+                        });
+                        let resolved = false;
+                        const resolveOnce = () => {
+                            if (!resolved) {
+                                resolved = true;
+                                resolve();
+                            }
+                        };
+                        teardownProcess.on("error", (error) => {
+                            const teardownError = new Error(`[${teardown.taskName}] Teardown failed: ${error.message}`);
+                            config?.onTaskTeardownError?.(teardown.taskName, teardownError);
+                            resolveOnce();
+                        });
+                        teardownProcess.on("exit", (code) => {
+                            if (code !== 0) {
+                                const teardownError = new Error(`[${teardown.taskName}] Teardown failed with exit code ${code ?? 1}`);
+                                config?.onTaskTeardownError?.(teardown.taskName, teardownError);
+                            }
+                            resolveOnce();
+                        });
+                    }
+                    catch (error) {
+                        const teardownError = new Error(`[${teardown.taskName}] Teardown failed to start: ${error.message}`);
+                        config?.onTaskTeardownError?.(teardown.taskName, teardownError);
+                        resolve();
+                    }
+                });
+            };
+            const executeAllTeardowns = async () => {
+                // Execute teardowns in reverse dependency order
+                // Tasks with dependents should be torn down before their dependencies
+                const taskIdsWithTeardown = Array.from(teardownCommands.keys());
+                if (taskIdsWithTeardown.length === 0) {
+                    return;
+                }
+                // Calculate reverse topological order
+                // Tasks that have dependents should be torn down first
+                const teardownOrder = getReverseDependencyOrder(taskIdsWithTeardown, graph);
+                // Execute teardowns sequentially in reverse dependency order
+                // This ensures dependents are torn down before their dependencies
+                for (const taskId of teardownOrder) {
+                    await executeTeardown(taskId);
+                }
+            };
+            const getReverseDependencyOrder = (taskIds, graph) => {
+                // Create a set for quick lookup
+                const taskIdSet = new Set(taskIds);
+                // For reverse dependency order, we want to tear down dependents before dependencies
+                // If api depends on db, we want: api first, then db
+                // This is the reverse of normal execution order
+                // Count how many dependencies each task has (within the teardown set)
+                const dependencyCount = new Map();
+                for (const taskId of taskIds) {
+                    const node = graph.nodes.get(taskId);
+                    if (node) {
+                        let count = 0;
+                        for (const depId of node.dependencies) {
+                            if (taskIdSet.has(depId)) {
+                                count++;
+                            }
+                        }
+                        dependencyCount.set(taskId, count);
+                    }
+                }
+                // Build result in reverse order
+                // Start with tasks that have no dependencies (leaf nodes) - these go LAST
+                const result = [];
+                const visited = new Set();
+                const queue = [];
+                // Find leaf nodes (tasks with no dependencies in teardown set)
+                for (const taskId of taskIds) {
+                    if (dependencyCount.get(taskId) === 0) {
+                        queue.push(taskId);
+                    }
+                }
+                // Process in reverse topological order
+                while (queue.length > 0) {
+                    const taskId = queue.shift();
+                    if (visited.has(taskId))
+                        continue;
+                    visited.add(taskId);
+                    // Add to front (so we get reverse order: dependents before dependencies)
+                    result.unshift(taskId);
+                    // Find tasks that depend on this one (dependents)
+                    const node = graph.nodes.get(taskId);
+                    if (node) {
+                        for (const dependentId of node.dependents) {
+                            if (taskIdSet.has(dependentId) && !visited.has(dependentId)) {
+                                const currentCount = dependencyCount.get(dependentId) ?? 0;
+                                const newCount = currentCount - 1;
+                                dependencyCount.set(dependentId, newCount);
+                                // When a dependent has no more dependencies to wait for, add it to queue
+                                if (newCount === 0) {
+                                    queue.push(dependentId);
+                                }
+                            }
+                        }
+                    }
+                }
+                // Add any remaining tasks (shouldn't happen in a valid graph, but handle it)
+                for (const taskId of taskIds) {
+                    if (!visited.has(taskId)) {
+                        result.unshift(taskId);
+                    }
+                }
+                return result;
+            };
+            const failPipeline = async (error) => {
                 if (failed)
                     return;
                 failed = true;
@@ -65,17 +199,40 @@ export function pipeline(tasks) {
                     }
                     catch { }
                 }
+                // Execute all teardown commands and wait for them to complete
+                // Even if teardowns fail, we still want to reject the pipeline
+                try {
+                    await executeAllTeardowns();
+                }
+                catch (teardownError) {
+                    // Teardown errors are already reported via onTaskTeardownError
+                    // We continue to reject the pipeline with the original error
+                }
                 config?.onPipelineError?.(error);
                 completionRejector?.(error);
             };
             const startTask = (task) => {
+                // Check if signal is aborted before starting new tasks
+                if (signal?.aborted) {
+                    failPipeline(new PipelineError("Aborted", PipelineError.InvalidSignal));
+                    return;
+                }
                 const { name: taskName, [$TASK_INTERNAL]: { id: taskId, pipeline: nestedPipeline }, } = task;
                 if (runningTasks.has(taskId))
                     return;
                 // Handle pipeline tasks
                 if (nestedPipeline) {
+                    // Track nested pipeline state for skip behavior
+                    let nestedSkippedCount = 0;
+                    let nestedCompletedCount = 0;
+                    // Get total tasks from nested pipeline
+                    const nestedTasks = pipelineTasksCache.get(nestedPipeline);
+                    const nestedTotalTasks = nestedTasks
+                        ? createTaskGraph(nestedTasks).nodes.size
+                        : 0;
                     // Mark as ready immediately (pipeline entry nodes will handle their own ready state)
                     advanceScheduler({ type: "ready", taskId });
+                    config?.onTaskBegin?.(taskName);
                     // Create an abort controller to stop the nested pipeline if needed
                     let pipelineStopped = false;
                     const stopPipeline = () => {
@@ -84,58 +241,110 @@ export function pipeline(tasks) {
                         // In a more sophisticated implementation, we could propagate stop signals
                     };
                     runningPipelines.set(taskId, { stop: stopPipeline });
-                    // Run the nested pipeline
+                    // Run the nested pipeline with signal propagation
                     nestedPipeline
                         .run({
                         spawn: spawnFn,
-                        onTaskError: (nestedTaskName, error) => {
+                        command: config?.command,
+                        strict: config?.strict,
+                        signal, // Pass signal to nested pipeline
+                        onTaskBegin: (nestedTaskName) => {
                             if (pipelineStopped)
                                 return;
-                            config?.onTaskError?.(`${taskName}:${nestedTaskName}`, error);
+                            config?.onTaskBegin?.(`${taskName}:${nestedTaskName}`);
                         },
                         onTaskComplete: (nestedTaskName) => {
                             if (pipelineStopped)
                                 return;
+                            nestedCompletedCount++;
                             config?.onTaskComplete?.(`${taskName}:${nestedTaskName}`);
                         },
+                        onTaskSkipped: (nestedTaskName, mode) => {
+                            if (pipelineStopped)
+                                return;
+                            nestedSkippedCount++;
+                            config?.onTaskSkipped?.(`${taskName}:${nestedTaskName}`, mode);
+                        },
                         onPipelineError: (error) => {
                             if (pipelineStopped)
                                 return;
                             runningPipelines.delete(taskId);
-                            const e = new Error(`[${taskName}] Pipeline failed: ${error.message}`);
-                            config?.onTaskError?.(taskName, e);
-                            failPipeline(e);
+                            // error is already a PipelineError
+                            failPipeline(error);
                         },
                         onPipelineComplete: () => {
                             if (pipelineStopped)
                                 return;
                             runningPipelines.delete(taskId);
-                            config?.onTaskComplete?.(taskName);
-                            advanceScheduler({ type: "complete", taskId });
+                            // Determine nested pipeline result based on skip behavior:
+                            // - 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 (handled in onPipelineError)
+                            const commandName = config?.command ?? process.env.NODE_ENV === "production"
+                                ? "build"
+                                : "dev";
+                            if (nestedSkippedCount === nestedTotalTasks &&
+                                nestedTotalTasks > 0) {
+                                // All tasks were skipped
+                                console.log(`[${taskName}] skipped (all nested tasks skipped)`);
+                                config?.onTaskSkipped?.(taskName, commandName);
+                                setImmediate(() => {
+                                    advanceScheduler({ type: "skip", taskId });
+                                });
+                            }
+                            else {
+                                // Some tasks ran (and completed successfully)
+                                config?.onTaskComplete?.(taskName);
+                                advanceScheduler({ type: "complete", taskId });
+                            }
                         },
                     })
                         .catch((error) => {
                         if (pipelineStopped)
                             return;
                         runningPipelines.delete(taskId);
-                        const e = new Error(`[${taskName}] Pipeline failed: ${error.message}`);
-                        config?.onTaskError?.(taskName, e);
-                        failPipeline(e);
+                        failPipeline(error);
                     });
                     return;
                 }
                 // Regular task execution
-                const command = process.env.NODE_ENV === "production"
-                    ? task[$TASK_INTERNAL].commands.build
-                    : task[$TASK_INTERNAL].commands.dev;
-                const { cwd, shouldStdoutMarkReady } = task[$TASK_INTERNAL];
+                const commandName = config?.command ?? process.env.NODE_ENV === "production"
+                    ? "build"
+                    : "dev";
+                const commandConfig = task[$TASK_INTERNAL].commands[commandName];
+                // Check if command exists
+                if (commandConfig === undefined) {
+                    const allowSkip = task[$TASK_INTERNAL].allowSkip ?? false;
+                    const strict = config?.strict ?? false;
+                    // If strict mode and not explicitly allowed to skip, fail
+                    if (strict && !allowSkip) {
+                        failPipeline(new PipelineError(`[${taskName}] No command for "${commandName}" and strict mode is enabled`, PipelineError.TaskFailed));
+                        return;
+                    }
+                    // Skip the task
+                    console.log(`[${taskName}] skipped "${commandName}"`);
+                    config?.onTaskSkipped?.(taskName, commandName);
+                    // Mark as skipped - this satisfies dependencies and unblocks dependents
+                    // Use setImmediate to ensure scheduler is at idle yield before receiving skip
+                    setImmediate(() => {
+                        advanceScheduler({ type: "skip", taskId });
+                    });
+                    return;
+                }
+                const command = typeof commandConfig === "string" ? commandConfig : commandConfig.run;
+                const readyWhen = typeof commandConfig === "string"
+                    ? undefined
+                    : commandConfig.readyWhen;
+                const readyTimeout = typeof commandConfig === "string"
+                    ? Infinity
+                    : commandConfig.readyTimeout ?? Infinity;
+                const teardown = typeof commandConfig === "string" ? undefined : commandConfig.teardown;
+                const { cwd } = task[$TASK_INTERNAL];
                 const taskCwd = path.isAbsolute(cwd)
                     ? cwd
                     : path.resolve(process.cwd(), cwd);
                 if (!fs.existsSync(taskCwd)) {
-                    const e = new Error(`[${taskName}] Working directory does not exist: ${taskCwd}`);
-                    config?.onTaskError?.(taskName, e);
-                    failPipeline(e);
+                    failPipeline(new PipelineError(`[${taskName}] Working directory does not exist: ${taskCwd}`, PipelineError.InvalidTask));
                     return;
                 }
                 const accumulatedPath = [
@@ -157,17 +366,43 @@ export function pipeline(tasks) {
                     env,
                 });
                 runningTasks.set(taskId, child);
+                // Store teardown command if provided
+                if (teardown) {
+                    teardownCommands.set(taskId, {
+                        command: teardown,
+                        cwd: taskCwd,
+                        taskName,
+                    });
+                }
+                config?.onTaskBegin?.(taskName);
                 let didMarkReady = false;
-                if (!shouldStdoutMarkReady) {
+                let readyTimeoutId = null;
+                if (!readyWhen) {
                     advanceScheduler({ type: "ready", taskId });
                     didMarkReady = true;
                 }
+                else if (readyTimeout !== Infinity) {
+                    // Set up timeout for readyWhen condition
+                    readyTimeoutId = setTimeout(() => {
+                        if (!didMarkReady) {
+                            failPipeline(new PipelineError(`[${taskName}] Task did not become ready within ${readyTimeout}ms`, PipelineError.TaskFailed));
+                        }
+                    }, readyTimeout);
+                }
                 let output = "";
                 child.stdout?.on("data", (buf) => {
+                    // Check if signal is aborted before processing stdout
+                    if (signal?.aborted) {
+                        return;
+                    }
                     const chunk = buf.toString();
                     output += chunk;
                     process.stdout.write(chunk);
-                    if (!didMarkReady && shouldStdoutMarkReady(output)) {
+                    if (!didMarkReady && readyWhen && readyWhen(output)) {
+                        if (readyTimeoutId) {
+                            clearTimeout(readyTimeoutId);
+                            readyTimeoutId = null;
+                        }
                         advanceScheduler({ type: "ready", taskId });
                         didMarkReady = true;
                     }
@@ -176,16 +411,27 @@ export function pipeline(tasks) {
                     process.stderr.write(buf);
                 });
                 child.on("error", (error) => {
-                    const e = new Error(`[${taskName}] Failed to start: ${error.message}`);
-                    config?.onTaskError?.(taskName, e);
-                    failPipeline(e);
+                    // Task failed before entering running state, so don't execute teardown
+                    // Remove teardown from map since it was never actually running
+                    teardownCommands.delete(taskId);
+                    // Clear ready timeout if it exists
+                    if (readyTimeoutId) {
+                        clearTimeout(readyTimeoutId);
+                        readyTimeoutId = null;
+                    }
+                    failPipeline(new PipelineError(`[${taskName}] Failed to start: ${error.message}`, PipelineError.TaskFailed));
                 });
                 child.on("exit", (code) => {
                     runningTasks.delete(taskId);
+                    // Clear ready timeout if it exists
+                    if (readyTimeoutId) {
+                        clearTimeout(readyTimeoutId);
+                        readyTimeoutId = null;
+                    }
+                    // Don't execute teardown immediately - it will be executed in reverse dependency order
+                    // when the pipeline completes or fails
                     if (code !== 0) {
-                        const e = new Error(`[${taskName}] Task failed with exit code ${code ?? 1}`);
-                        config?.onTaskError?.(taskName, e);
-                        failPipeline(e);
+                        failPipeline(new PipelineError(`[${taskName}] Task failed with exit code ${code ?? 1}`, PipelineError.TaskFailed));
                         return;
                     }
                     config?.onTaskComplete?.(taskName);
@@ -194,8 +440,25 @@ export function pipeline(tasks) {
                 });
             };
             const advanceScheduler = (input) => {
+                // Check if signal is aborted before advancing scheduler
+                if (signal?.aborted) {
+                    failPipeline(new PipelineError("Aborted", PipelineError.Aborted));
+                    return;
+                }
                 let result = input ? scheduler.next(input) : scheduler.next();
+                // If we passed skip/complete input and got "idle", the generator processed it
+                // but returned the old yield. Call next() again to get the result after processing.
+                if (input &&
+                    (input.type === "skip" || input.type === "complete") &&
+                    result.value?.type === "idle") {
+                    result = scheduler.next();
+                }
                 while (true) {
+                    // Check signal again in the loop
+                    if (signal?.aborted) {
+                        failPipeline(new PipelineError("Aborted", PipelineError.Aborted));
+                        return;
+                    }
                     const event = result.value;
                     const isFinished = result.done && result.value.type === "done";
                     if (isFinished) {
@@ -214,21 +477,104 @@ export function pipeline(tasks) {
                 }
             };
             // Handle termination signals
-            const cleanups = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGBREAK"].map((signal) => {
+            const processTerminationListenerCleanups = [
+                "SIGINT",
+                "SIGTERM",
+                "SIGQUIT",
+                "SIGBREAK",
+            ].map((sig) => {
                 const handleSignal = () => {
-                    failPipeline(new Error(`Received ${signal}`));
+                    failPipeline(new PipelineError(`Received ${sig}`, PipelineError.ProcessTerminated));
                 };
-                process.once(signal, handleSignal);
+                process.once(sig, handleSignal);
                 return () => {
-                    process.removeListener(signal, handleSignal);
+                    process.removeListener(sig, handleSignal);
                 };
             });
+            // Handle abort signal if provided
+            let signalCleanup = null;
+            if (signal) {
+                const handleAbort = () => {
+                    failPipeline(new PipelineError("Aborted", PipelineError.Aborted));
+                };
+                signal.addEventListener("abort", handleAbort);
+                signalCleanup = () => {
+                    signal.removeEventListener("abort", handleAbort);
+                };
+            }
             // 🚀 Kick off initial runnable tasks
             advanceScheduler();
-            await completionPromise.finally(() => {
-                cleanups.forEach((cleanup) => cleanup());
+            await completionPromise
+                .then(async () => {
+                // Pipeline completed successfully - execute any remaining teardowns
+                // (for tasks that completed successfully) and wait for them to complete
+                // Even if teardowns fail, the pipeline still resolves successfully
+                // (teardown errors are reported via onTaskTeardownError)
+                try {
+                    await executeAllTeardowns();
+                }
+                catch (teardownError) {
+                    // Teardown errors are already reported via onTaskTeardownError
+                    // The pipeline still resolves successfully
+                }
+            })
+                .finally(() => {
+                processTerminationListenerCleanups.forEach((cleanup) => cleanup());
+                signalCleanup?.();
             });
         },
     };
+    // Store tasks for nested pipeline skip tracking
+    pipelineTasksCache.set(pipelineImpl, tasks);
     return pipelineImpl;
 }
+export class PipelineError extends Error {
+    constructor(message, code, taskName) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "taskName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "PipelineError";
+        this.code = code;
+        this.taskName = taskName;
+    }
+}
+Object.defineProperty(PipelineError, "Aborted", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 0
+});
+Object.defineProperty(PipelineError, "ProcessTerminated", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 1
+});
+Object.defineProperty(PipelineError, "TaskFailed", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 2
+});
+Object.defineProperty(PipelineError, "InvalidSignal", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 3
+});
+Object.defineProperty(PipelineError, "InvalidTask", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 4
+});

package/dist/scheduler.d.ts

@@ -5,6 +5,9 @@ export type SchedulerInput = {
 } | {
     type: "ready";
     taskId: number;
+} | {
+    type: "skip";
+    taskId: number;
 };
 export type SchedulerOutput = {
     type: "run";

package/dist/scheduler.js

@@ -29,20 +29,12 @@ export function* createScheduler(graph) {
             continue;
         }
         const input = yield { type: "idle" };
-        if (input?.type === "ready" && input.taskId !== undefined) {
-            markDependencyReady(input.taskId);
-            // After marking a dependency as ready, continue the loop to check for newly runnable tasks
-            // This ensures that if dependents become runnable, they are yielded immediately
+        if (input?.taskId === undefined)
             continue;
-        }
-        else if (input?.type === "complete" && input.taskId !== undefined) {
-            completed++;
-            // When a task completes, it's also ready (if it wasn't already)
-            // This handles the case where a task completes without a ready check
-            markDependencyReady(input.taskId);
-            // Continue the loop to check for newly runnable tasks
+        markDependencyReady(input.taskId);
+        if (input.type === "ready")
             continue;
-        }
+        completed++;
     }
     return { type: "done" };
 }

package/dist/task.d.ts

@@ -1,5 +1,16 @@
 import type { TaskConfig, Task } from "./types.js";
 /**
  * Creates a task configuration.
+ * @param config - The configuration for the task.
+ * @returns A task instance.
+ * @example
+ * const build = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
+ * const deploy = task({ name: "deploy", commands: { build: "npm run deploy" }, cwd: ".", dependencies: [build] })
+ * await pipeline([build, deploy]).run()
+ *
+ * // alternatively, you can use the andThen method to chain tasks together:
+ * const buildAndDeploy = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
+ *   .andThen({ name: "deploy", commands: { build: "npm run deploy" }, cwd: "." })
+ * await buildAndDeploy.run()
  */
 export declare function task(config: TaskConfig): Task;

package/dist/task.js

@@ -4,6 +4,17 @@ import { pipeline } from "./pipeline.js";
 let taskId = 0;
 /**
  * Creates a task configuration.
+ * @param config - The configuration for the task.
+ * @returns A task instance.
+ * @example
+ * const build = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
+ * const deploy = task({ name: "deploy", commands: { build: "npm run deploy" }, cwd: ".", dependencies: [build] })
+ * await pipeline([build, deploy]).run()
+ *
+ * // alternatively, you can use the andThen method to chain tasks together:
+ * const buildAndDeploy = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
+ *   .andThen({ name: "deploy", commands: { build: "npm run deploy" }, cwd: "." })
+ * await buildAndDeploy.run()
  */
 export function task(config) {
     validateTasks(config.dependencies);
@@ -13,7 +24,6 @@ export function task(config) {
             ...config,
             id: taskId++,
             dependencies: [...(config.dependencies || [])],
-            shouldStdoutMarkReady: config.isReady,
         },
         andThen(nextConfig) {
             // Create the next task with the current task as a dependency

package/dist/types.d.ts

@@ -1,43 +1,199 @@
 import type { $TASK_INTERNAL } from "./constants.js";
+import { PipelineError } from "./pipeline.js";
+/**
+ * Configuration for a command to be executed as part of a task.
+ */
+export interface CommandConfig {
+    /**
+     * The command string to execute (e.g., "npm run dev" or "node server.js").
+     */
+    run: string;
+    /**
+     * Optional function that determines when the command is considered "ready".
+     * The function receives the accumulated stdout output and should return true
+     * when the command has reached a ready state (e.g., server has started).
+     * If not provided, the task is marked as ready immediately after the command starts.
+     */
+    readyWhen?: (stdout: string) => boolean;
+    /**
+     * Maximum time in milliseconds to wait for the command to become ready.
+     * Only applies when `readyWhen` is provided.
+     * @default Infinity
+     */
+    readyTimeout?: number;
+    /**
+     * Optional command to run during teardown (e.g., to stop a server).
+     */
+    teardown?: string;
+}
+/**
+ * A command can be either a simple string or a CommandConfig object.
+ * When a string is provided, it's equivalent to `{ run: string }`.
+ */
+export type Command = string | CommandConfig;
+/**
+ * A map of command names to their configurations.
+ * Common command names include "dev", "build", "test", etc.
+ * The command name is selected based on the pipeline's run configuration.
+ * If a matching command is not found, the task is skipped.
+ */
 export interface Commands {
-    dev: string;
-    build: string;
+    [key: string]: Command;
 }
+/**
+ * Configuration for creating a task in the pipeline.
+ */
 export interface TaskConfig {
+    /**
+     * The name of the task. Used for logging and identification.
+     */
     name: string;
+    /**
+     * Map of command names to their configurations.
+     * The pipeline will select a command based on the run configuration
+     * (defaults to "dev" in development, "build" in production).
+     */
     commands: Commands;
+    /**
+     * Working directory for the task's commands.
+     * Can be absolute or relative to the current working directory.
+     */
     cwd: string;
-    isReady?: (stdout: string) => boolean;
+    /**
+     * Optional array of tasks that must complete before this task can start.
+     * Dependencies are executed in parallel when possible.
+     */
     dependencies?: Task[];
+    /**
+     * Allows this task to be skipped even in strict mode.
+     * Use this to explicitly mark tasks that are intentionally mode-specific.
+     */
+    allowSkip?: boolean;
 }
-interface TaskInternal extends Omit<TaskConfig, "isReady"> {
+interface TaskInternal extends TaskConfig {
     id: number;
     dependencies: Task[];
-    shouldStdoutMarkReady?: (stdout: string) => boolean;
     pipeline?: Pipeline;
 }
+/**
+ * A task to be executed in a pipeline. Tasks are created using the `task()` function.
+ * Tasks can have dependencies on other tasks and define commands to execute in a specific mode.
+ */
 export interface Task {
+    /**
+     * The name of the task.
+     */
     name: string;
+    /**
+     * Internal task data. This property is for internal use only.
+     * @internal
+     */
     [$TASK_INTERNAL]: TaskInternal;
+    /**
+     * Creates a new pipeline that starts after this task completes.
+     * This allows for chaining tasks together.
+     * @param config Task configuration for the next task in the chain.
+     * @returns A new pipeline starting with the configured task.
+     */
     andThen(config: Omit<TaskConfig, "dependencies">): Pipeline;
 }
+/**
+ * Configuration options for running a pipeline.
+ */
 export interface PipelineRunConfig {
+    /**
+     * Provides a custom command for the pipeline.
+     * @default process.env.NODE_ENV === "production" ? "build" : "dev"
+     */
+    command?: string;
+    /**
+     * Provides a custom abort signal for the pipeline.
+     * Aborting the signal will cause the pipeline to fail.
+     */
+    signal?: AbortSignal;
     /**
      * Provides a custom spawn function for the pipeline.
      * @default import("node:child_process").spawn
      */
     spawn?: typeof import("node:child_process").spawn;
-    onTaskError?: (taskName: string, error: Error) => void;
+    /**
+     * If true, missing commands will cause the pipeline to fail.
+     * Use this for CI/release pipelines where every task is expected to participate.
+     */
+    strict?: boolean;
+    /**
+     * Callback invoked when a task begins execution.
+     * @param taskName The name of the task that started.
+     */
+    onTaskBegin?: (taskName: string) => void;
+    /**
+     * Callback invoked when a task completes successfully.
+     * @param taskName The name of the task that completed.
+     */
     onTaskComplete?: (taskName: string) => void;
-    onPipelineError?: (error: Error) => void;
+    /**
+     * Callback invoked when a task is skipped (e.g., when a command doesn't exist for the current mode).
+     * @param taskName The name of the task that was skipped.
+     * @param mode The command mode that was requested (e.g., "dev", "build").
+     */
+    onTaskSkipped?: (taskName: string, mode: string) => void;
+    /**
+     * Callback invoked when a task's teardown command begins execution.
+     * @param taskName The name of the task whose teardown is running.
+     */
+    onTaskTeardown?: (taskName: string) => void;
+    /**
+     * Callback invoked when a task's teardown command fails.
+     * Note: Teardown failures do not cause the pipeline to fail.
+     * @param taskName The name of the task whose teardown failed.
+     * @param error The error that occurred during teardown.
+     */
+    onTaskTeardownError?: (taskName: string, error: Error) => void;
+    /**
+     * Callback invoked when the pipeline encounters an error and fails.
+     * @param error The PipelineError that caused the pipeline to fail.
+     */
+    onPipelineError?: (error: PipelineError) => void;
+    /**
+     * Callback invoked when the pipeline completes successfully.
+     * This is called after all tasks have completed and all teardowns have finished.
+     */
     onPipelineComplete?: () => void;
 }
+/**
+ * Configuration for converting a pipeline into a task.
+ * This allows pipelines to be used as dependencies in other pipelines.
+ */
 export interface PipelineTaskConfig {
+    /**
+     * The name for the task that represents this pipeline.
+     */
     name: string;
+    /**
+     * Optional array of tasks that must complete before this pipeline task can start.
+     */
     dependencies?: Task[];
 }
+/**
+ * A pipeline manages the execution of tasks with dependency-based coordination.
+ * Pipelines are created using the `pipeline()` function.
+ */
 export interface Pipeline {
+    /**
+     * Runs the pipeline, executing all tasks according to their dependencies.
+     * Tasks with no dependencies start immediately, and tasks with dependencies
+     * wait for their dependencies to complete before starting.
+     * @param config Optional configuration for pipeline execution.
+     * @returns A promise that resolves when all tasks complete successfully,
+     *          or rejects if any task fails or the pipeline is aborted.
+     */
     run(config?: PipelineRunConfig): Promise<void>;
+    /**
+     * Converts this pipeline into a task that can be used as a dependency
+     * in another pipeline. This enables nested pipelines.
+     * @param config Configuration for the task representation of this pipeline.
+     * @returns A task that represents this pipeline.
+     */
     toTask(config: PipelineTaskConfig): Task;
 }
 export interface TaskNode {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "builderman",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Simple task runner for building and developing projects.",
   "main": "dist/index.js",
   "type": "module",