builderman 1.0.8 → 1.1.0

package/README.md

@@ -1,5 +1,107 @@
 # **builderman**
 
-#### _An awesome new package._
+#### _A simple task runner for building and developing projects._
 
 <br />
+
+## Installation
+
+```bash
+npm install builderman
+```
+
+## Usage
+
+```ts
+import { task, pipeline } from "builderman"
+
+const task1 = task({
+  name: "lib:build",
+  commands: {
+    dev: "tsc --watch",
+    build: "tsc",
+  },
+  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",
+  },
+  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}`)
+  },
+})
+```
+
+## 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:
+
+```ts
+import { task, 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",
+})
+
+await build.run()
+```
+
+### Composing Pipelines as Tasks
+
+Convert pipelines to tasks and compose them with explicit dependencies:
+
+```ts
+const build = pipeline([
+  /* ... */
+])
+const test = pipeline([
+  /* ... */
+])
+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])
+
+await ci.run()
+```
+
+**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.

package/dist/graph.d.ts

@@ -0,0 +1,2 @@
+import type { TaskGraph, Task } from "./types.js";
+export declare function createTaskGraph(tasks: Task[]): TaskGraph;

package/dist/graph.js

@@ -0,0 +1,97 @@
+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];
+        nodes.set(taskId, {
+            task,
+            dependencies: new Set(),
+            dependents: new Set(),
+        });
+    }
+    // Build dependency relationships
+    for (const task of tasks) {
+        const { id: taskId, name: taskName, dependencies } = task[$TASK_INTERNAL];
+        const node = nodes.get(taskId);
+        for (const dep of dependencies) {
+            const { id: depId, name: depName } = dep[$TASK_INTERNAL];
+            if (!nodes.has(depId)) {
+                throw new Error(`Task "${taskName}" depends on "${depName}" which is not in the pipeline`);
+            }
+            node.dependencies.add(depId);
+            nodes.get(depId).dependents.add(taskId);
+        }
+    }
+    return {
+        nodes,
+        validate() {
+            // Use DFS to detect cycles
+            const visited = new Set();
+            const recursionStack = new Set();
+            const visit = (nodeId, path) => {
+                if (recursionStack.has(nodeId)) {
+                    // Found a cycle - build the cycle path
+                    const cycleStart = path.indexOf(nodeId);
+                    const cycle = [...path.slice(cycleStart), nodeId];
+                    throw new Error(`Circular dependency detected: ${cycle.join(" -> ")}`);
+                }
+                if (visited.has(nodeId)) {
+                    return;
+                }
+                visited.add(nodeId);
+                recursionStack.add(nodeId);
+                const node = nodes.get(nodeId);
+                for (const depId of node.dependencies) {
+                    visit(depId, [...path, nodeId]);
+                }
+                recursionStack.delete(nodeId);
+            };
+            for (const nodeId of nodes.keys()) {
+                if (!visited.has(nodeId)) {
+                    visit(nodeId, []);
+                }
+            }
+        },
+        simplify() {
+            // Remove transitive dependencies using Floyd-Warshall approach
+            // For each node, if there's a path through another node, remove the direct edge
+            const reachable = new Map();
+            // Initialize reachable sets with direct dependencies
+            for (const [id, node] of nodes) {
+                reachable.set(id, new Set(node.dependencies));
+            }
+            // Compute transitive closure
+            for (const k of nodes.keys()) {
+                for (const i of nodes.keys()) {
+                    if (reachable.get(i).has(k)) {
+                        for (const j of nodes.keys()) {
+                            if (reachable.get(k).has(j)) {
+                                reachable.get(i).add(j);
+                            }
+                        }
+                    }
+                }
+            }
+            // Remove transitive edges
+            for (const [nodeId, node] of nodes) {
+                const toRemove = new Set();
+                for (const depId of node.dependencies) {
+                    // Check if there's a path from this node to dep through another dependency
+                    for (const otherDep of node.dependencies) {
+                        if (otherDep !== depId && reachable.get(otherDep).has(depId)) {
+                            // dep is reachable through otherDep, so it's transitive
+                            toRemove.add(depId);
+                        }
+                    }
+                }
+                for (const depId of toRemove) {
+                    node.dependencies.delete(depId);
+                    nodes.get(depId).dependents.delete(nodeId);
+                }
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./task.js";
-export * from "./pipeline.js";
+export { task } from "./task.js";
+export { pipeline } from "./pipeline.js";
 export type { Task, Pipeline, TaskConfig } from "./types.js";

package/dist/index.js

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

package/dist/pipeline.js

@@ -1,174 +1,234 @@
 import { spawn } from "node:child_process";
-import { EventEmitter } from "node:events";
 import * as path from "node:path";
+import * as fs from "node:fs";
 import { $TASK_INTERNAL } from "./constants.js";
+import { createTaskGraph } from "./graph.js";
+import { createScheduler } from "./scheduler.js";
+import { task } from "./task.js";
+import { validateTasks } from "./util.js";
+// Module-level cache for pipeline-to-task conversions
+// Key: Pipeline, Value: Map of name -> Task
+const pipelineTaskCache = new WeakMap();
 /**
  * Creates a pipeline that manages task execution with dependency-based coordination.
  */
 export function pipeline(tasks) {
-    return {
-        async run() {
-            const eventEmitter = new EventEmitter();
+    const graph = createTaskGraph(tasks);
+    graph.validate();
+    graph.simplify();
+    const pipelineImpl = {
+        toTask(config) {
+            validateTasks(config.dependencies);
+            const syntheticTask = task({
+                name: config.name,
+                commands: { dev: ":", build: ":" }, // Dummy commands (no-op)
+                cwd: ".", // Dummy cwd
+                dependencies: [...(config.dependencies || [])],
+            });
+            // Mark this task as a pipeline task
+            syntheticTask[$TASK_INTERNAL].pipeline = pipelineImpl;
+            // Cache this conversion
+            let cache = pipelineTaskCache.get(pipelineImpl);
+            if (!cache) {
+                cache = new Map();
+                pipelineTaskCache.set(pipelineImpl, cache);
+            }
+            cache.set(config.name, syntheticTask);
+            return syntheticTask;
+        },
+        async run(config) {
+            const spawnFn = config?.spawn ?? spawn;
             const runningTasks = new Map();
-            const completedTasks = new Set();
-            const readyTasks = new Set();
-            // Determine which command to use based on NODE_ENV
-            const isProduction = process.env.NODE_ENV === "production";
-            const getCommand = (task) => {
-                return isProduction
-                    ? task[$TASK_INTERNAL].commands.build
-                    : task[$TASK_INTERNAL].commands.dev;
-            };
-            // Function to check if a task's dependencies are satisfied
-            const canStart = async (task) => {
-                if (runningTasks.has(task.name) || completedTasks.has(task.name)) {
-                    return false;
-                }
-                const { dependsOn: dependencies } = task[$TASK_INTERNAL];
-                if (!dependencies || dependencies.length === 0) {
-                    return true;
-                }
-                // Wait for all dependencies
-                for (const dep of dependencies) {
-                    if (typeof dep === "function") {
-                        await dep();
+            const runningPipelines = new Map();
+            let failed = false;
+            const scheduler = createScheduler(graph);
+            let completionResolver = null;
+            let completionRejector = null;
+            const completionPromise = new Promise((resolve, reject) => {
+                completionResolver = resolve;
+                completionRejector = reject;
+            });
+            const failPipeline = (error) => {
+                if (failed)
+                    return;
+                failed = true;
+                for (const child of runningTasks.values()) {
+                    try {
+                        child.kill("SIGTERM");
                     }
-                    else {
-                        await dep;
+                    catch { }
+                }
+                // Stop nested pipelines
+                for (const { stop } of runningPipelines.values()) {
+                    try {
+                        stop();
                     }
+                    catch { }
                 }
-                return true;
+                config?.onPipelineError?.(error);
+                completionRejector?.(error);
             };
-            // Function to start a task
-            const startTask = async (task) => {
-                if (runningTasks.has(task.name)) {
+            const startTask = (task) => {
+                const { name: taskName, [$TASK_INTERNAL]: { id: taskId, pipeline: nestedPipeline }, } = task;
+                if (runningTasks.has(taskId))
+                    return;
+                // Handle pipeline tasks
+                if (nestedPipeline) {
+                    // Mark as ready immediately (pipeline entry nodes will handle their own ready state)
+                    advanceScheduler({ type: "ready", taskId });
+                    // Create an abort controller to stop the nested pipeline if needed
+                    let pipelineStopped = false;
+                    const stopPipeline = () => {
+                        pipelineStopped = true;
+                        // The nested pipeline will continue running, but we've marked it as stopped
+                        // In a more sophisticated implementation, we could propagate stop signals
+                    };
+                    runningPipelines.set(taskId, { stop: stopPipeline });
+                    // Run the nested pipeline
+                    nestedPipeline
+                        .run({
+                        spawn: spawnFn,
+                        onTaskError: (nestedTaskName, error) => {
+                            if (pipelineStopped)
+                                return;
+                            config?.onTaskError?.(`${taskName}:${nestedTaskName}`, error);
+                        },
+                        onTaskComplete: (nestedTaskName) => {
+                            if (pipelineStopped)
+                                return;
+                            config?.onTaskComplete?.(`${taskName}:${nestedTaskName}`);
+                        },
+                        onPipelineError: (error) => {
+                            if (pipelineStopped)
+                                return;
+                            runningPipelines.delete(taskId);
+                            const e = new Error(`[${taskName}] Pipeline failed: ${error.message}`);
+                            config?.onTaskError?.(taskName, e);
+                            failPipeline(e);
+                        },
+                        onPipelineComplete: () => {
+                            if (pipelineStopped)
+                                return;
+                            runningPipelines.delete(taskId);
+                            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);
+                    });
                     return;
                 }
-                const command = getCommand(task);
-                const { cwd, readyOn, markComplete, markReady } = task[$TASK_INTERNAL];
-                // Ensure node_modules/.bin is in PATH for local dependencies
+                // 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 taskCwd = path.isAbsolute(cwd)
                     ? cwd
                     : path.resolve(process.cwd(), cwd);
-                const localBinPath = path.join(taskCwd, "node_modules", ".bin");
-                // Build PATH with local node_modules/.bin first
-                const existingPath = process.env.PATH || process.env.Path || "";
-                const pathSeparator = process.platform === "win32" ? ";" : ":";
-                const binPaths = [localBinPath];
-                const rootBinPath = path.join(process.cwd(), "node_modules", ".bin");
-                if (rootBinPath !== localBinPath) {
-                    binPaths.push(rootBinPath);
-                }
-                if (existingPath) {
-                    binPaths.push(existingPath);
+                if (!fs.existsSync(taskCwd)) {
+                    const e = new Error(`[${taskName}] Working directory does not exist: ${taskCwd}`);
+                    config?.onTaskError?.(taskName, e);
+                    failPipeline(e);
+                    return;
                 }
-                const newPath = binPaths.join(pathSeparator);
+                const accumulatedPath = [
+                    path.join(taskCwd, "node_modules", ".bin"),
+                    path.join(process.cwd(), "node_modules", ".bin"),
+                    process.env.PATH,
+                ]
+                    .filter(Boolean)
+                    .join(process.platform === "win32" ? ";" : ":");
                 const env = {
                     ...process.env,
-                    PATH: newPath,
-                    Path: newPath,
+                    PATH: accumulatedPath,
+                    Path: accumulatedPath,
                 };
-                const child = spawn(command, {
-                    cwd,
+                const child = spawnFn(command, {
+                    cwd: taskCwd,
                     stdio: ["inherit", "pipe", "pipe"],
                     shell: true,
                     env,
                 });
-                // Handle spawn errors
-                child.on("error", (error) => {
-                    console.error(`[${task.name}] Failed to start:`, error.message);
-                    runningTasks.delete(task.name);
-                    completedTasks.add(task.name);
-                    markComplete();
-                    process.exitCode = 1;
-                    eventEmitter.emit("taskCompleted", task.name);
-                });
-                runningTasks.set(task.name, child);
-                // If task doesn't have readyOn, mark as ready immediately
-                if (!readyOn) {
-                    readyTasks.add(task.name);
-                    markReady();
-                    eventEmitter.emit("taskReady", task.name);
+                runningTasks.set(taskId, child);
+                let didMarkReady = false;
+                if (!shouldStdoutMarkReady) {
+                    advanceScheduler({ type: "ready", taskId });
+                    didMarkReady = true;
                 }
-                // Monitor stdout for readiness
-                let stdoutBuffer = "";
-                let allOutput = "";
-                child.stdout?.on("data", (data) => {
-                    const chunk = data.toString();
-                    allOutput += chunk;
-                    stdoutBuffer += chunk;
-                    const lines = stdoutBuffer.split("\n");
-                    stdoutBuffer = lines.pop() || "";
-                    for (const line of lines) {
-                        // Check if task is ready based on readyOn callback
-                        if (readyOn && !readyTasks.has(task.name)) {
-                            if (readyOn(allOutput)) {
-                                readyTasks.add(task.name);
-                                markReady();
-                                eventEmitter.emit("taskReady", task.name);
-                            }
-                        }
-                        // Forward stdout to parent
-                        process.stdout.write(line + "\n");
+                let output = "";
+                child.stdout?.on("data", (buf) => {
+                    const chunk = buf.toString();
+                    output += chunk;
+                    process.stdout.write(chunk);
+                    if (!didMarkReady && shouldStdoutMarkReady(output)) {
+                        advanceScheduler({ type: "ready", taskId });
+                        didMarkReady = true;
                     }
                 });
-                // Forward any remaining buffer on end
-                child.stdout?.on("end", () => {
-                    if (stdoutBuffer) {
-                        process.stdout.write(stdoutBuffer);
-                    }
+                child.stderr?.on("data", (buf) => {
+                    process.stderr.write(buf);
                 });
-                // Forward stderr
-                child.stderr?.on("data", (data) => {
-                    process.stderr.write(data);
+                child.on("error", (error) => {
+                    const e = new Error(`[${taskName}] Failed to start: ${error.message}`);
+                    config?.onTaskError?.(taskName, e);
+                    failPipeline(e);
                 });
-                // Handle task completion
                 child.on("exit", (code) => {
-                    runningTasks.delete(task.name);
-                    completedTasks.add(task.name);
-                    markComplete();
+                    runningTasks.delete(taskId);
                     if (code !== 0) {
-                        process.exitCode = code || 1;
+                        const e = new Error(`[${taskName}] Task failed with exit code ${code ?? 1}`);
+                        config?.onTaskError?.(taskName, e);
+                        failPipeline(e);
+                        return;
                     }
-                    eventEmitter.emit("taskCompleted", task.name);
+                    config?.onTaskComplete?.(taskName);
+                    // 🔑 Notify scheduler and drain newly runnable tasks
+                    advanceScheduler({ type: "complete", taskId });
                 });
             };
-            // Function to try starting tasks when dependencies are ready
-            const tryStartTasks = async () => {
-                for (const task of tasks) {
-                    if (await canStart(task)) {
-                        await startTask(task);
+            const advanceScheduler = (input) => {
+                let result = input ? scheduler.next(input) : scheduler.next();
+                while (true) {
+                    const event = result.value;
+                    const isFinished = result.done && result.value.type === "done";
+                    if (isFinished) {
+                        config?.onPipelineComplete?.();
+                        completionResolver?.();
+                        return;
+                    }
+                    if (event.type === "run") {
+                        startTask(graph.nodes.get(event.taskId).task);
+                        result = scheduler.next();
+                        continue;
+                    }
+                    if (event.type === "idle") {
+                        return;
                     }
                 }
             };
-            // Listen for task readiness and completion to start dependent tasks
-            eventEmitter.on("taskReady", tryStartTasks);
-            eventEmitter.on("taskCompleted", tryStartTasks);
-            // Start tasks that don't have dependencies
-            await tryStartTasks();
-            // Wait for all tasks to complete
-            return new Promise((resolve, reject) => {
-                const checkCompletion = () => {
-                    if (runningTasks.size === 0) {
-                        resolve();
-                    }
+            // Handle termination signals
+            const cleanups = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGBREAK"].map((signal) => {
+                const handleSignal = () => {
+                    failPipeline(new Error(`Received ${signal}`));
                 };
-                eventEmitter.on("taskCompleted", checkCompletion);
-                checkCompletion();
-                // Handle process termination
-                process.on("SIGINT", () => {
-                    for (const child of runningTasks.values()) {
-                        child.kill("SIGINT");
-                    }
-                    reject(new Error("Process interrupted"));
-                });
-                process.on("SIGTERM", () => {
-                    for (const child of runningTasks.values()) {
-                        child.kill("SIGTERM");
-                    }
-                    reject(new Error("Process terminated"));
-                });
+                process.once(signal, handleSignal);
+                return () => {
+                    process.removeListener(signal, handleSignal);
+                };
+            });
+            // 🚀 Kick off initial runnable tasks
+            advanceScheduler();
+            await completionPromise.finally(() => {
+                cleanups.forEach((cleanup) => cleanup());
             });
         },
     };
+    return pipelineImpl;
 }

package/dist/pipeline.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scheduler.d.ts

@@ -0,0 +1,17 @@
+import type { TaskGraph } from "./types.js";
+export type SchedulerInput = {
+    type: "complete";
+    taskId: number;
+} | {
+    type: "ready";
+    taskId: number;
+};
+export type SchedulerOutput = {
+    type: "run";
+    taskId: number;
+} | {
+    type: "idle";
+};
+export declare function createScheduler(graph: TaskGraph): Generator<SchedulerOutput, {
+    type: "done";
+}, SchedulerInput>;

package/dist/scheduler.js

@@ -0,0 +1,48 @@
+export function* createScheduler(graph) {
+    const remainingReadyDeps = new Map();
+    const readyTasks = new Set(); // Track which tasks are already ready
+    const runnable = [];
+    let completed = 0;
+    for (const [id, node] of graph.nodes) {
+        remainingReadyDeps.set(id, node.dependencies.size);
+        if (node.dependencies.size === 0) {
+            runnable.push(id);
+        }
+    }
+    const markDependencyReady = (taskId) => {
+        if (readyTasks.has(taskId)) {
+            return; // Already marked as ready, don't double-count
+        }
+        readyTasks.add(taskId);
+        // A dependency became ready, check if dependents can now run
+        const node = graph.nodes.get(taskId);
+        for (const depId of node.dependents) {
+            const next = (remainingReadyDeps.get(depId) ?? 0) - 1;
+            remainingReadyDeps.set(depId, next);
+            if (next === 0)
+                runnable.push(depId);
+        }
+    };
+    while (completed < graph.nodes.size) {
+        if (runnable.length > 0) {
+            yield { type: "run", taskId: runnable.shift() };
+            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
+            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
+            continue;
+        }
+    }
+    return { type: "done" };
+}

package/dist/task.js

@@ -1,39 +1,29 @@
 import { $TASK_INTERNAL } from "./constants.js";
+import { validateTasks } from "./util.js";
+import { pipeline } from "./pipeline.js";
+let taskId = 0;
 /**
  * Creates a task configuration.
  */
 export function task(config) {
-    let resolveReady = null;
-    const readyPromise = new Promise((resolve) => {
-        resolveReady = resolve;
-    });
-    let isReady = false;
-    let isComplete = false;
-    return {
+    validateTasks(config.dependencies);
+    const taskInstance = {
         name: config.name,
-        readyOrComplete() {
-            return readyPromise;
-        },
         [$TASK_INTERNAL]: {
             ...config,
-            dependsOn: config.dependsOn || [],
-            isReady: () => isReady,
-            isComplete: () => isComplete,
-            markReady: () => {
-                if (!isReady && resolveReady) {
-                    isReady = true;
-                    resolveReady();
-                }
-            },
-            markComplete: () => {
-                if (!isComplete) {
-                    isComplete = true;
-                    if (!isReady && resolveReady) {
-                        isReady = true;
-                        resolveReady();
-                    }
-                }
-            },
+            id: taskId++,
+            dependencies: [...(config.dependencies || [])],
+            shouldStdoutMarkReady: config.isReady,
+        },
+        andThen(nextConfig) {
+            // Create the next task with the current task as a dependency
+            const nextTask = task({
+                ...nextConfig,
+                dependencies: [taskInstance],
+            });
+            // Return a pipeline containing both tasks
+            return pipeline([taskInstance, nextTask]);
         },
     };
+    return taskInstance;
 }

package/dist/types.d.ts

@@ -7,23 +7,55 @@ export interface TaskConfig {
     name: string;
     commands: Commands;
     cwd: string;
-    readyOn?: (output: string) => boolean;
-    dependsOn?: Dependency[];
+    isReady?: (stdout: string) => boolean;
+    dependencies?: Task[];
 }
-export type Dependency = Promise<void> | (() => Promise<void>);
-interface TaskInternal extends TaskConfig {
-    dependsOn: Dependency[];
-    isReady: () => boolean;
-    isComplete: () => boolean;
-    markReady: () => void;
-    markComplete: () => void;
+interface TaskInternal extends Omit<TaskConfig, "isReady"> {
+    id: number;
+    dependencies: Task[];
+    shouldStdoutMarkReady?: (stdout: string) => boolean;
+    pipeline?: Pipeline;
 }
 export interface Task {
     name: string;
-    readyOrComplete(): Promise<void>;
     [$TASK_INTERNAL]: TaskInternal;
+    andThen(config: Omit<TaskConfig, "dependencies">): Pipeline;
+}
+export interface PipelineRunConfig {
+    /**
+     * 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;
+    onTaskComplete?: (taskName: string) => void;
+    onPipelineError?: (error: Error) => void;
+    onPipelineComplete?: () => void;
+}
+export interface PipelineTaskConfig {
+    name: string;
+    dependencies?: Task[];
 }
 export interface Pipeline {
-    run(): Promise<void>;
+    run(config?: PipelineRunConfig): Promise<void>;
+    toTask(config: PipelineTaskConfig): Task;
+}
+export interface TaskNode {
+    task: Task;
+    dependencies: Set<number>;
+    dependents: Set<number>;
+}
+export interface TaskGraph {
+    nodes: Map<number, TaskNode>;
+    /**
+     * Validates the graph for circular dependencies.
+     * @throws Error if circular dependencies are detected
+     */
+    validate(): void;
+    /**
+     * Simplifies the graph by removing transitive dependencies.
+     * If A depends on B and B depends on C, then A->C is transitive and can be removed.
+     */
+    simplify(): void;
 }
 export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/util.d.ts

@@ -0,0 +1,2 @@
+import type { Task } from "./types.js";
+export declare function validateTasks(tasks?: Task[]): void;

package/dist/util.js

@@ -0,0 +1,6 @@
+import { $TASK_INTERNAL } from "./constants.js";
+export function validateTasks(tasks) {
+    if (tasks?.some((dep) => !($TASK_INTERNAL in dep))) {
+        throw new Error("Invalid dependency: must be a task or a pipeline converted to a task");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "builderman",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "description": "Simple task runner for building and developing projects.",
   "main": "dist/index.js",
   "type": "module",
@@ -21,7 +21,7 @@
     "@types/node": "^25.0.8"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\"",
+    "test": "node --test ./dist/pipeline.test.js",
     "build": "rm -rf dist && tsc",
     "dev": "tsc --watch"
   }