builderman 1.2.0 → 1.3.0

package/dist/modules/signal-handler.js

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

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

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

package/dist/modules/task-executor.js

@@ -0,0 +1,313 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { $TASK_INTERNAL } from "../constants.js";
+import { createTaskGraph } from "../graph.js";
+import { PipelineError } from "../pipeline-error.js";
+/**
+ * Executes a task (either a regular task or a nested pipeline).
+ */
+export function executeTask(task, executorConfig) {
+    // Check if signal is aborted before starting new tasks
+    if (executorConfig.signal?.aborted) {
+        executorConfig.failPipeline(new PipelineError("Aborted", PipelineError.InvalidSignal));
+        return;
+    }
+    const { name: taskName, [$TASK_INTERNAL]: { id: taskId, pipeline: nestedPipeline }, } = task;
+    if (executorConfig.runningTasks.has(taskId))
+        return;
+    // Handle pipeline tasks
+    if (nestedPipeline) {
+        executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig);
+        return;
+    }
+    // Regular task execution
+    executeRegularTask(task, taskId, taskName, executorConfig);
+}
+function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig) {
+    const { config, runningPipelines, pipelineTasksCache, failPipeline, advanceScheduler, updateTaskStatus, } = executorConfig;
+    // 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;
+    const commandName = (config?.command ?? process.env.NODE_ENV === "production") ? "build" : "dev";
+    // Mark as ready immediately (pipeline entry nodes will handle their own ready state)
+    const startedAt = Date.now();
+    updateTaskStatus(taskId, {
+        status: "running",
+        command: commandName,
+        startedAt,
+    });
+    advanceScheduler({ type: "ready", taskId });
+    config?.onTaskBegin?.(taskName);
+    // 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 with signal propagation
+    nestedPipeline
+        .run({
+        spawn: executorConfig.spawn,
+        command: config?.command,
+        strict: config?.strict,
+        signal: executorConfig.signal, // Pass signal to nested pipeline
+        onTaskBegin: (nestedTaskName) => {
+            if (pipelineStopped)
+                return;
+            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);
+        },
+    })
+        .then((result) => {
+        if (pipelineStopped)
+            return;
+        runningPipelines.delete(taskId);
+        if (!result.ok) {
+            // Nested pipeline failed
+            const finishedAt = Date.now();
+            updateTaskStatus(taskId, {
+                status: "failed",
+                finishedAt,
+                durationMs: finishedAt - startedAt,
+                error: result.error,
+            });
+            failPipeline(result.error);
+            return;
+        }
+        // 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 above)
+        if (nestedSkippedCount === nestedTotalTasks && nestedTotalTasks > 0) {
+            // All tasks were skipped
+            const finishedAt = Date.now();
+            updateTaskStatus(taskId, {
+                status: "skipped",
+                finishedAt,
+                durationMs: finishedAt - startedAt,
+            });
+            config?.onTaskSkipped?.(taskName, commandName);
+            setImmediate(() => {
+                advanceScheduler({ type: "skip", taskId });
+            });
+        }
+        else {
+            // Some tasks ran (and completed successfully)
+            const finishedAt = Date.now();
+            updateTaskStatus(taskId, {
+                status: "completed",
+                finishedAt,
+                durationMs: finishedAt - startedAt,
+            });
+            config?.onTaskComplete?.(taskName);
+            advanceScheduler({ type: "complete", taskId });
+        }
+    });
+}
+function executeRegularTask(task, taskId, taskName, executorConfig) {
+    const { spawn: spawnFn, signal, config, runningTasks, teardownManager, failPipeline, advanceScheduler, updateTaskStatus, } = executorConfig;
+    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) {
+            const error = new PipelineError(`[${taskName}] No command for "${commandName}" and strict mode is enabled`, PipelineError.TaskFailed, taskName);
+            const finishedAt = Date.now();
+            updateTaskStatus(taskId, {
+                status: "failed",
+                command: commandName,
+                finishedAt,
+                error,
+            });
+            failPipeline(error);
+            return;
+        }
+        // Skip the task
+        const finishedAt = Date.now();
+        updateTaskStatus(taskId, {
+            status: "skipped",
+            command: commandName,
+            finishedAt,
+            durationMs: 0,
+        });
+        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 finishedAt = Date.now();
+        const pipelineError = new PipelineError(`[${taskName}] Working directory does not exist: ${taskCwd}`, PipelineError.InvalidTask, taskName);
+        updateTaskStatus(taskId, {
+            status: "failed",
+            command: commandName,
+            finishedAt,
+            durationMs: 0,
+            error: pipelineError,
+        });
+        failPipeline(pipelineError);
+        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 child = spawnFn(command, {
+        cwd: taskCwd,
+        stdio: ["inherit", "pipe", "pipe"],
+        shell: true,
+        env,
+    });
+    runningTasks.set(taskId, child);
+    const startedAt = Date.now();
+    updateTaskStatus(taskId, {
+        status: "running",
+        command: commandName,
+        startedAt,
+    });
+    // Store teardown command if provided
+    if (teardown) {
+        teardownManager.register(taskId, {
+            command: teardown,
+            cwd: taskCwd,
+            taskName,
+        });
+    }
+    config?.onTaskBegin?.(taskName);
+    let didMarkReady = false;
+    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) {
+                const finishedAt = Date.now();
+                const pipelineError = new PipelineError(`[${taskName}] Task did not become ready within ${readyTimeout}ms`, PipelineError.TaskFailed, taskName);
+                updateTaskStatus(taskId, {
+                    status: "failed",
+                    finishedAt,
+                    durationMs: finishedAt - startedAt,
+                    error: pipelineError,
+                });
+                failPipeline(pipelineError);
+            }
+        }, 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 && readyWhen && readyWhen(output)) {
+            if (readyTimeoutId) {
+                clearTimeout(readyTimeoutId);
+                readyTimeoutId = null;
+            }
+            advanceScheduler({ type: "ready", taskId });
+            didMarkReady = true;
+        }
+    });
+    child.stderr?.on("data", (buf) => {
+        process.stderr.write(buf);
+    });
+    child.on("error", (error) => {
+        // Task failed before entering running state, so don't execute teardown
+        // Remove teardown from map since it was never actually running
+        teardownManager.unregister(taskId);
+        // Clear ready timeout if it exists
+        if (readyTimeoutId) {
+            clearTimeout(readyTimeoutId);
+            readyTimeoutId = null;
+        }
+        const finishedAt = Date.now();
+        const pipelineError = new PipelineError(`[${taskName}] Failed to start: ${error.message}`, PipelineError.TaskFailed, taskName);
+        updateTaskStatus(taskId, {
+            status: "failed",
+            finishedAt,
+            durationMs: finishedAt - startedAt,
+            error: pipelineError,
+        });
+        failPipeline(pipelineError);
+    });
+    child.on("exit", (code, signal) => {
+        runningTasks.delete(taskId);
+        // Clear ready timeout if it exists
+        if (readyTimeoutId) {
+            clearTimeout(readyTimeoutId);
+            readyTimeoutId = null;
+        }
+        const finishedAt = Date.now();
+        const durationMs = finishedAt - startedAt;
+        // Don't execute teardown immediately - it will be executed in reverse dependency order
+        // when the pipeline completes or fails
+        if (code !== 0 || signal) {
+            const pipelineError = new PipelineError(`[${taskName}] Task failed with non-zero exit code: ${code ?? signal}`, PipelineError.TaskFailed, taskName);
+            updateTaskStatus(taskId, {
+                status: "failed",
+                finishedAt,
+                durationMs,
+                exitCode: code ?? undefined,
+                signal: signal ?? undefined,
+                error: pipelineError,
+            });
+            failPipeline(pipelineError);
+            return;
+        }
+        updateTaskStatus(taskId, {
+            status: "completed",
+            finishedAt,
+            durationMs,
+            exitCode: code ?? 0,
+        });
+        config?.onTaskComplete?.(taskName);
+        // 🔑 Notify scheduler and drain newly runnable tasks
+        advanceScheduler({ type: "complete", taskId });
+    });
+}

package/dist/modules/teardown-manager.d.ts

@@ -0,0 +1,22 @@
+import type { TaskGraph } from "../types.js";
+export interface TeardownCommand {
+    command: string;
+    cwd: string;
+    taskName: string;
+}
+export interface TeardownManagerConfig {
+    spawn: typeof import("node:child_process").spawn;
+    onTaskTeardown?: (taskName: string) => void;
+    onTaskTeardownError?: (taskName: string, error: Error) => void;
+    updateTaskTeardownStatus: (taskId: string, status: "not-run" | "completed" | "failed", error?: Error) => void;
+}
+export interface TeardownManager {
+    register(taskId: string, teardown: TeardownCommand): void;
+    unregister(taskId: string): void;
+    executeAll(graph: TaskGraph): Promise<void>;
+}
+/**
+ * Creates a teardown manager for a pipeline.
+ * Manages teardown commands for tasks, handling execution order and error reporting.
+ */
+export declare function createTeardownManager(config: TeardownManagerConfig): TeardownManager;

package/dist/modules/teardown-manager.js

@@ -0,0 +1,157 @@
+/**
+ * Creates a teardown manager for a pipeline.
+ * Manages teardown commands for tasks, handling execution order and error reporting.
+ */
+export function createTeardownManager(config) {
+    const teardownCommands = new Map();
+    /**
+     * Executes a single teardown command.
+     */
+    const executeTeardown = (taskId) => {
+        const teardown = teardownCommands.get(taskId);
+        if (!teardown) {
+            // No teardown registered, mark as not-run
+            config.updateTaskTeardownStatus(taskId, "not-run");
+            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 = config.spawn(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);
+                    config.updateTaskTeardownStatus(taskId, "failed", 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);
+                        config.updateTaskTeardownStatus(taskId, "failed", teardownError);
+                    }
+                    else {
+                        config.updateTaskTeardownStatus(taskId, "completed");
+                    }
+                    resolveOnce();
+                });
+            }
+            catch (error) {
+                const teardownError = new Error(`[${teardown.taskName}] Teardown failed to start: ${error.message}`);
+                config.onTaskTeardownError?.(teardown.taskName, teardownError);
+                config.updateTaskTeardownStatus(taskId, "failed", teardownError);
+                resolve();
+            }
+        });
+    };
+    return {
+        /**
+         * Registers a teardown command for a task.
+         */
+        register(taskId, teardown) {
+            teardownCommands.set(taskId, teardown);
+        },
+        /**
+         * Removes a teardown command (e.g., if task failed before starting).
+         */
+        unregister(taskId) {
+            teardownCommands.delete(taskId);
+        },
+        /**
+         * Executes all registered teardowns in reverse dependency order.
+         * Tasks with dependents are torn down before their dependencies.
+         */
+        async executeAll(graph) {
+            const taskIdsWithTeardown = Array.from(teardownCommands.keys());
+            if (taskIdsWithTeardown.length === 0) {
+                return;
+            }
+            // Calculate reverse topological order
+            const teardownOrder = getReverseDependencyOrder(taskIdsWithTeardown, graph);
+            // Execute teardowns sequentially in reverse dependency order
+            for (const taskId of teardownOrder) {
+                await executeTeardown(taskId);
+            }
+            // Mark any remaining tasks (that had teardown registered but weren't in the order) as not-run
+            for (const taskId of teardownCommands.keys()) {
+                config.updateTaskTeardownStatus(taskId, "not-run");
+            }
+        },
+    };
+}
+/**
+ * Calculates the reverse dependency order for teardown execution.
+ * Tasks that have dependents should be torn down first.
+ * If api depends on db, we want: api first, then db.
+ */
+function getReverseDependencyOrder(taskIds, graph) {
+    const taskIdSet = new Set(taskIds);
+    // 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
+    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;
+}

package/dist/pipeline-error.d.ts

@@ -0,0 +1,11 @@
+export 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;
+}

package/dist/pipeline-error.js

@@ -0,0 +1,50 @@
+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/pipeline.d.ts

@@ -9,15 +9,3 @@ import type { Pipeline, Task } from "./types.js";
  * 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 {};