builderman 1.0.9 → 1.1.0

package/README.md

@@ -53,3 +53,55 @@ await pipeline([task1, task2]).run({
   },
 })
 ```
+
+## 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,183 +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 {
-        run(config) {
-            return new Promise((resolvePipeline, rejectPipeline) => {
-                let hasFailed = false;
-                // Function to fail the pipeline and kill all running tasks
-                const failPipeline = (error) => {
-                    if (hasFailed)
-                        return;
-                    hasFailed = true;
-                    // Kill all running tasks
-                    for (const child of runningTasks.values()) {
-                        try {
-                            child.kill("SIGTERM");
-                        }
-                        catch (e) {
-                            // Ignore errors when killing
-                        }
-                    }
-                    rejectPipeline(error);
-                };
-                const eventEmitter = new EventEmitter();
-                const runningTasks = new Map();
-                const completedTasks = new Set();
-                const readyTasks = new Set();
-                const isProduction = process.env.NODE_ENV === "production";
-                const getCommand = (task) => {
-                    return isProduction
-                        ? task[$TASK_INTERNAL].commands.build
-                        : task[$TASK_INTERNAL].commands.dev;
-                };
-                const canStart = async (task) => {
-                    if (runningTasks.has(task.name) || completedTasks.has(task.name)) {
-                        return false;
+    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 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");
                     }
-                    const { dependencies } = task[$TASK_INTERNAL];
-                    if (!dependencies || dependencies.length === 0) {
-                        return true;
+                    catch { }
+                }
+                // Stop nested pipelines
+                for (const { stop } of runningPipelines.values()) {
+                    try {
+                        stop();
                     }
-                    await Promise.all(dependencies.map((task) => task[$TASK_INTERNAL].readyPromise));
-                    return true;
+                    catch { }
+                }
+                config?.onPipelineError?.(error);
+                completionRejector?.(error);
+            };
+            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;
+                }
+                // 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);
+                if (!fs.existsSync(taskCwd)) {
+                    const e = new Error(`[${taskName}] Working directory does not exist: ${taskCwd}`);
+                    config?.onTaskError?.(taskName, e);
+                    failPipeline(e);
+                    return;
+                }
+                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: accumulatedPath,
+                    Path: accumulatedPath,
                 };
-                const startTask = (task) => {
-                    if (runningTasks.has(task.name)) {
-                        return;
-                    }
-                    const command = getCommand(task);
-                    const { cwd, isReady: getIsReady, markComplete, markReady, } = task[$TASK_INTERNAL];
-                    // Ensure node_modules/.bin is in PATH for local dependencies
-                    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);
+                const child = spawnFn(command, {
+                    cwd: taskCwd,
+                    stdio: ["inherit", "pipe", "pipe"],
+                    shell: true,
+                    env,
+                });
+                runningTasks.set(taskId, child);
+                let didMarkReady = false;
+                if (!shouldStdoutMarkReady) {
+                    advanceScheduler({ type: "ready", taskId });
+                    didMarkReady = true;
+                }
+                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;
                     }
-                    if (existingPath) {
-                        binPaths.push(existingPath);
+                });
+                child.stderr?.on("data", (buf) => {
+                    process.stderr.write(buf);
+                });
+                child.on("error", (error) => {
+                    const e = new Error(`[${taskName}] Failed to start: ${error.message}`);
+                    config?.onTaskError?.(taskName, e);
+                    failPipeline(e);
+                });
+                child.on("exit", (code) => {
+                    runningTasks.delete(taskId);
+                    if (code !== 0) {
+                        const e = new Error(`[${taskName}] Task failed with exit code ${code ?? 1}`);
+                        config?.onTaskError?.(taskName, e);
+                        failPipeline(e);
+                        return;
                     }
-                    const newPath = binPaths.join(pathSeparator);
-                    const env = {
-                        ...process.env,
-                        PATH: newPath,
-                        Path: newPath,
-                    };
-                    // Validate that the cwd exists
-                    if (!fs.existsSync(taskCwd)) {
-                        const error = new Error(`[${task.name}] Working directory does not exist: ${taskCwd}`);
-                        config.onTaskError?.(task.name, error);
-                        failPipeline(error);
+                    config?.onTaskComplete?.(taskName);
+                    // 🔑 Notify scheduler and drain newly runnable tasks
+                    advanceScheduler({ type: "complete", taskId });
+                });
+            };
+            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;
                     }
-                    // Use the resolved absolute path for cwd
-                    const child = spawn(command, {
-                        cwd: taskCwd,
-                        stdio: ["inherit", "pipe", "pipe"],
-                        shell: true,
-                        env,
-                    });
-                    // Handle spawn errors
-                    child.on("error", (error) => {
-                        const errorMsg = `[${task.name}] Failed to start: ${error.message}\n  Command: ${command}\n  CWD: ${taskCwd}`;
-                        const e = new Error(errorMsg);
-                        config.onTaskError?.(task.name, e);
-                        failPipeline(e);
-                    });
-                    runningTasks.set(task.name, child);
-                    // If task doesn't have getIsReady, mark as ready immediately
-                    if (!getIsReady) {
-                        readyTasks.add(task.name);
-                        markReady();
-                        eventEmitter.emit("taskReady", task.name);
+                    if (event.type === "run") {
+                        startTask(graph.nodes.get(event.taskId).task);
+                        result = scheduler.next();
+                        continue;
                     }
-                    // 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 (getIsReady && !readyTasks.has(task.name)) {
-                                if (getIsReady(allOutput)) {
-                                    readyTasks.add(task.name);
-                                    markReady();
-                                    eventEmitter.emit("taskReady", task.name);
-                                }
-                            }
-                            // Forward stdout to parent
-                            process.stdout.write(line + "\n");
-                        }
-                    });
-                    // Forward any remaining buffer on end
-                    child.stdout?.on("end", () => {
-                        if (stdoutBuffer) {
-                            process.stdout.write(stdoutBuffer);
-                        }
-                    });
-                    // Forward stderr
-                    child.stderr?.on("data", (data) => {
-                        process.stderr.write(data);
-                    });
-                    // Handle task completion
-                    child.on("exit", (code) => {
-                        runningTasks.delete(task.name);
-                        completedTasks.add(task.name);
-                        if (code !== 0) {
-                            const error = new Error(`[${task.name}] Task failed with exit code ${code || 1}`);
-                            config.onTaskError?.(task.name, error);
-                            failPipeline(error);
-                        }
-                        else {
-                            markComplete();
-                            eventEmitter.emit("taskCompleted", task.name);
-                            config.onTaskComplete?.(task.name);
-                        }
-                    });
-                };
-                const tryStartTasks = async () => {
-                    for (const task of tasks) {
-                        if (await canStart(task)) {
-                            startTask(task);
-                        }
+                    if (event.type === "idle") {
+                        return;
                     }
+                }
+            };
+            // Handle termination signals
+            const cleanups = ["SIGINT", "SIGTERM", "SIGQUIT", "SIGBREAK"].map((signal) => {
+                const handleSignal = () => {
+                    failPipeline(new Error(`Received ${signal}`));
                 };
-                // Function to check completion (only resolve if no failures)
-                const checkCompletion = () => {
-                    if (completedTasks.size === tasks.length && !hasFailed) {
-                        config.onPipelineComplete?.();
-                        resolvePipeline();
-                    }
+                process.once(signal, handleSignal);
+                return () => {
+                    process.removeListener(signal, handleSignal);
                 };
-                ["SIGINT", "SIGBREAK", "SIGTERM", "SIGQUIT"].forEach((signal) => {
-                    process.once(signal, () => {
-                        const e = new Error(`Received ${signal} signal during pipeline execution`);
-                        config.onPipelineError?.(e);
-                        failPipeline(e);
-                    });
-                });
-                eventEmitter.on("taskReady", tryStartTasks);
-                eventEmitter.on("taskCompleted", tryStartTasks);
-                eventEmitter.on("taskCompleted", checkCompletion);
-                tryStartTasks().catch(failPipeline);
+            });
+            // 🚀 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,37 +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,
         [$TASK_INTERNAL]: {
             ...config,
-            readyPromise,
-            dependencies: config.dependencies || [],
-            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

@@ -10,25 +10,52 @@ export interface TaskConfig {
     isReady?: (stdout: string) => boolean;
     dependencies?: Task[];
 }
-interface TaskInternal extends TaskConfig {
-    readyPromise: Promise<void>;
+interface TaskInternal extends Omit<TaskConfig, "isReady"> {
+    id: number;
     dependencies: Task[];
-    isReady: (stdout: string) => boolean;
-    isComplete: () => boolean;
-    markReady: () => void;
-    markComplete: () => void;
+    shouldStdoutMarkReady?: (stdout: string) => boolean;
+    pipeline?: Pipeline;
 }
 export interface Task {
     name: string;
     [$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(config: PipelineRunConfig): 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.9",
+  "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"
   }