builderman 1.5.0 → 1.5.2

package/README.md

@@ -538,7 +538,7 @@ console.log(result.stats.summary.running)
 Each task provides detailed per-task data:
 
 ```ts
-for (const task of Object.values(result.stats.tasks)) {
+for (const task of result.stats.tasks) {
   console.log(task.name, task.status)
   console.log(task.durationMs)
 
@@ -550,6 +550,13 @@ for (const task of Object.values(result.stats.tasks)) {
   if (task.teardown) {
     console.log("Teardown:", task.teardown.status)
   }
+
+  // when using pipeline.toTask() to convert a pipeline into a task, the task will have subtasks
+  if (task.subtasks) {
+    for (const subtask of task.subtasks) {
+      // ...
+    }
+  }
 }
 ```
 

package/dist/internal/task-executor.js

@@ -2,6 +2,7 @@ import * as path from "node:path";
 import * as fs from "node:fs";
 import { $TASK_INTERNAL, $PIPELINE_INTERNAL } from "./constants.js";
 import { PipelineError } from "../errors.js";
+import { parseCommandLine } from "./util.js";
 /**
  * Executes a task (either a regular task or a nested pipeline).
  */
@@ -25,6 +26,10 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
     // Track nested pipeline state for skip behavior
     let nestedSkippedCount = 0;
     let nestedCompletedCount = 0;
+    // Track unique tasks that are ready, complete, or skipped
+    // A task can be both ready and complete, so we use Sets to avoid double-counting
+    const readyOrCompleteTasks = new Set();
+    let didMarkOuterReady = false;
     // Get total tasks from nested pipeline
     const nestedTotalTasks = nestedPipeline[$PIPELINE_INTERNAL].graph.nodes.size;
     const commandName = config?.command ?? (process.env.NODE_ENV === "production" ? "build" : "dev");
@@ -37,7 +42,7 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
         command: commandName,
         startedAt,
     });
-    config?.onTaskBegin?.(taskName);
+    config?.onTaskBegin?.(taskName, taskId);
     // Create an abort controller to stop the nested pipeline if needed
     let pipelineStopped = false;
     // Merge environment variables: pipeline.env -> task.env (from pipeline.toTask config)
@@ -47,6 +52,19 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
         ...pipelineEnv,
         ...taskEnv,
     };
+    // Helper to check if all inner tasks are ready/complete/skipped
+    const checkAllInnerTasksReady = () => {
+        if (didMarkOuterReady)
+            return;
+        // Count unique tasks: ready (via readyWhen), complete, or skipped
+        // A task can be both ready and complete, so we use a Set to track unique tasks
+        const totalFinished = readyOrCompleteTasks.size + nestedSkippedCount;
+        if (totalFinished === nestedTotalTasks && nestedTotalTasks > 0) {
+            didMarkOuterReady = true;
+            // Mark outer task as ready - this allows dependents to proceed
+            callbacks.onTaskReady(taskId);
+        }
+    };
     // Run the nested pipeline with signal propagation
     // Pass the command from parent pipeline to nested pipeline
     // If undefined, nested pipeline will use its own default (build/dev based on NODE_ENV)
@@ -57,22 +75,35 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
         strict: config?.strict,
         signal: context.signal, // Pass signal to nested pipeline
         env: mergedEnv, // Pass merged env to nested pipeline
-        onTaskBegin: (nestedTaskName) => {
+        onTaskBegin: (nestedTaskName, nestedTaskId) => {
             if (pipelineStopped)
                 return;
-            config?.onTaskBegin?.(`${taskName}:${nestedTaskName}`);
+            config?.onTaskBegin?.(`${taskName}:${nestedTaskName}`, nestedTaskId);
         },
-        onTaskComplete: (nestedTaskName) => {
+        onTaskReady: (_, nestedTaskId) => {
+            if (pipelineStopped)
+                return;
+            // Track this task as ready (it may later become complete, but we only count it once)
+            readyOrCompleteTasks.add(nestedTaskId);
+            checkAllInnerTasksReady();
+            // Note: We don't call config?.onTaskReady here because the nested pipeline
+            // already handles that internally. We only track readiness for the outer task.
+        },
+        onTaskComplete: (nestedTaskName, nestedTaskId) => {
             if (pipelineStopped)
                 return;
             nestedCompletedCount++;
-            config?.onTaskComplete?.(`${taskName}:${nestedTaskName}`);
+            // Track this task as complete (if it was already ready, the Set prevents double-counting)
+            readyOrCompleteTasks.add(nestedTaskId);
+            checkAllInnerTasksReady();
+            config?.onTaskComplete?.(`${taskName}:${nestedTaskName}`, nestedTaskId);
         },
-        onTaskSkipped: (nestedTaskName, mode) => {
+        onTaskSkipped: (nestedTaskName, nestedTaskId, mode) => {
             if (pipelineStopped)
                 return;
             nestedSkippedCount++;
-            config?.onTaskSkipped?.(`${taskName}:${nestedTaskName}`, mode);
+            checkAllInnerTasksReady();
+            config?.onTaskSkipped?.(`${taskName}:${nestedTaskName}`, nestedTaskId, mode);
         },
     })
         .then((result) => {
@@ -81,15 +112,20 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
         if (!result.ok) {
             // Nested pipeline failed
             const finishedAt = Date.now();
+            // Capture nested pipeline task stats even on failure
+            const nestedTaskStats = result.stats.tasks;
             context.updateTaskStatus(taskId, {
                 status: "failed",
                 finishedAt,
                 durationMs: finishedAt - startedAt,
                 error: result.error,
+                subtasks: nestedTaskStats,
             });
             callbacks.onTaskFailed(taskId, result.error);
             return;
         }
+        // Capture nested pipeline task stats for subtasks field
+        const nestedTaskStats = result.stats.tasks;
         // 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
@@ -101,8 +137,9 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
                 status: "skipped",
                 finishedAt,
                 durationMs: finishedAt - startedAt,
+                subtasks: nestedTaskStats,
             });
-            config?.onTaskSkipped?.(taskName, commandName);
+            config?.onTaskSkipped?.(taskName, taskId, commandName);
             setImmediate(() => {
                 callbacks.onTaskSkipped(taskId);
             });
@@ -114,8 +151,9 @@ function executeNestedPipeline(task, taskId, taskName, nestedPipeline, context,
                 status: "completed",
                 finishedAt,
                 durationMs: finishedAt - startedAt,
+                subtasks: nestedTaskStats,
             });
-            config?.onTaskComplete?.(taskName);
+            config?.onTaskComplete?.(taskName, taskId);
             // Mark as complete - this will update dependent tasks and allow them to start
             callbacks.onTaskComplete(taskId);
         }
@@ -150,7 +188,7 @@ function executeRegularTask(task, taskId, taskName, context, callbacks) {
             finishedAt,
             durationMs: 0,
         });
-        config?.onTaskSkipped?.(taskName, commandName);
+        config?.onTaskSkipped?.(taskName, taskId, commandName);
         // Mark as skipped - this satisfies dependencies and unblocks dependents
         // Use setImmediate to ensure scheduler is at idle yield before receiving skip
         setImmediate(() => {
@@ -158,23 +196,25 @@ function executeRegularTask(task, taskId, taskName, context, callbacks) {
         });
         return;
     }
-    let command;
+    let commandString;
     let readyWhen;
     let readyTimeout = Infinity;
     let completedTimeout = Infinity;
     let teardown;
     let commandEnv = {};
     if (typeof commandConfig === "string") {
-        command = commandConfig;
+        commandString = commandConfig;
     }
     else {
-        command = commandConfig.run;
+        commandString = commandConfig.run;
         readyWhen = commandConfig.readyWhen;
         readyTimeout = commandConfig.readyTimeout ?? Infinity;
         completedTimeout = commandConfig.completedTimeout ?? Infinity;
         teardown = commandConfig.teardown;
         commandEnv = commandConfig.env ?? {};
     }
+    // Parse commandSpec into cmd + args
+    const { cmd, args } = parseCommandLine(commandString);
     const taskCwd = path.isAbsolute(cwd) ? cwd : path.resolve(process.cwd(), cwd);
     if (!fs.existsSync(taskCwd)) {
         const finishedAt = Date.now();
@@ -205,10 +245,10 @@ function executeRegularTask(task, taskId, taskName, context, callbacks) {
         ...taskEnv,
         ...commandEnv,
     };
-    const child = spawnFn(command, {
+    const child = spawnFn(cmd, args, {
         cwd: taskCwd,
         stdio: ["inherit", "pipe", "pipe"],
-        shell: true,
+        shell: false,
         env: accumulatedEnv,
     });
     // Update the running task execution with the process
@@ -224,28 +264,20 @@ function executeRegularTask(task, taskId, taskName, context, callbacks) {
     });
     // Store teardown command if provided
     if (teardown) {
+        const teardownSpec = parseCommandLine(teardown);
         teardownManager.register(taskId, {
-            command: teardown,
+            cmd: teardownSpec.cmd,
+            args: teardownSpec.args,
             cwd: taskCwd,
             taskName,
         });
     }
-    config?.onTaskBegin?.(taskName);
+    config?.onTaskBegin?.(taskName, taskId);
     let didMarkReady = false;
-    if (!readyWhen) {
-        // For tasks without readyWhen, mark as ready after a microtask
-        // This ensures the task has actually started before we update dependents
-        // This prevents race conditions where a task fails immediately after starting
-        setImmediate(() => {
-            // Check if task hasn't failed before marking as ready
-            const currentStats = context.taskStats.get(taskId);
-            if (currentStats?.status !== "failed" && !context.isAborted()) {
-                callbacks.onTaskReady(taskId);
-                didMarkReady = true;
-            }
-        });
-    }
-    else if (readyTimeout !== Infinity) {
+    // For tasks without readyWhen, we wait for the process to exit successfully
+    // before allowing dependent tasks to start. This ensures dependencies are
+    // fully completed before dependents begin execution.
+    if (readyWhen && readyTimeout !== Infinity) {
         // Set up timeout for readyWhen condition using TimeoutManager
         timeoutManager.setReadyTimeout(taskId, readyTimeout, () => {
             if (!didMarkReady) {
@@ -358,7 +390,7 @@ function executeRegularTask(task, taskId, taskName, context, callbacks) {
             durationMs,
             exitCode: code ?? 0,
         });
-        config?.onTaskComplete?.(taskName);
+        config?.onTaskComplete?.(taskName, taskId);
         // 🔑 Notify scheduler and drain newly runnable tasks
         callbacks.onTaskComplete(taskId);
     });

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

@@ -1,13 +1,14 @@
 import type { TaskGraph } from "../types.js";
 export interface TeardownCommand {
-    command: string;
+    cmd: string;
+    args: 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;
+    onTaskTeardown?: (taskName: string, taskId: string) => void;
+    onTaskTeardownError?: (taskName: string, taskId: string, error: Error) => void;
     updateTaskTeardownStatus: (taskId: string, status: "not-run" | "completed" | "failed", error?: Error) => void;
 }
 export interface TeardownManager {

package/dist/internal/teardown-manager.js

@@ -16,13 +16,13 @@ export function createTeardownManager(config) {
         }
         // Remove from map so it doesn't run again
         teardownCommands.delete(taskId);
-        config.onTaskTeardown?.(teardown.taskName);
+        config.onTaskTeardown?.(teardown.taskName, taskId);
         return new Promise((resolve) => {
             try {
-                const teardownProcess = config.spawn(teardown.command, {
+                const teardownProcess = config.spawn(teardown.cmd, teardown.args, {
                     cwd: teardown.cwd,
                     stdio: "inherit",
-                    shell: true,
+                    shell: false,
                 });
                 let resolved = false;
                 const resolveOnce = () => {
@@ -33,14 +33,14 @@ export function createTeardownManager(config) {
                 };
                 teardownProcess.on("error", (error) => {
                     const teardownError = new Error(`[${teardown.taskName}] Teardown failed: ${error.message}`);
-                    config.onTaskTeardownError?.(teardown.taskName, teardownError);
+                    config.onTaskTeardownError?.(teardown.taskName, taskId, 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.onTaskTeardownError?.(teardown.taskName, taskId, teardownError);
                         config.updateTaskTeardownStatus(taskId, "failed", teardownError);
                     }
                     else {
@@ -51,7 +51,7 @@ export function createTeardownManager(config) {
             }
             catch (error) {
                 const teardownError = new Error(`[${teardown.taskName}] Teardown failed to start: ${error.message}`);
-                config.onTaskTeardownError?.(teardown.taskName, teardownError);
+                config.onTaskTeardownError?.(teardown.taskName, taskId, teardownError);
                 config.updateTaskTeardownStatus(taskId, "failed", teardownError);
                 resolve();
             }

package/dist/internal/util.d.ts

@@ -1,2 +1,16 @@
 import type { Task } from "../types.js";
 export declare function validateTasks(tasks?: Task[]): void;
+/**
+ * Very small, cross-platform command-line parser for our default spawn wrapper.
+ * - Splits on whitespace outside of single/double quotes
+ * - Strips the surrounding quotes
+ * - Does NOT implement full shell semantics (no pipes, redirects, etc.)
+ *
+ * This is sufficient for commands like:
+ * - `"node path/to/script.js"`
+ * - `"\"C:\\Program Files\\nodejs\\node.exe\" \"C:\\path with spaces\\script.js\""`
+ */
+export declare function parseCommandLine(command: string): {
+    cmd: string;
+    args: string[];
+};

package/dist/internal/util.js

@@ -4,3 +4,53 @@ export function validateTasks(tasks) {
         throw new Error("Invalid dependency: must be a task or a pipeline converted to a task");
     }
 }
+/**
+ * Very small, cross-platform command-line parser for our default spawn wrapper.
+ * - Splits on whitespace outside of single/double quotes
+ * - Strips the surrounding quotes
+ * - Does NOT implement full shell semantics (no pipes, redirects, etc.)
+ *
+ * This is sufficient for commands like:
+ * - `"node path/to/script.js"`
+ * - `"\"C:\\Program Files\\nodejs\\node.exe\" \"C:\\path with spaces\\script.js\""`
+ */
+export function parseCommandLine(command) {
+    const tokens = [];
+    let current = "";
+    let inQuotes = false;
+    let quoteChar = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (ch === '"' || ch === "'") {
+            if (!inQuotes) {
+                inQuotes = true;
+                quoteChar = ch;
+                continue;
+            }
+            if (quoteChar === ch) {
+                inQuotes = false;
+                quoteChar = null;
+                continue;
+            }
+            // Different quote type inside current quotes – treat as literal
+            current += ch;
+            continue;
+        }
+        if (!inQuotes && /\s/.test(ch)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+    if (tokens.length === 0) {
+        throw new Error(`Invalid command: "${command}"`);
+    }
+    const [cmd, ...args] = tokens;
+    return { cmd, args };
+}

package/dist/pipeline.js

@@ -144,6 +144,10 @@ export function pipeline(tasks) {
                     // Task is ready (via readyWhen) - update dependent tasks immediately
                     // Only process ready tasks if pipeline hasn't failed
                     if (!isPipelineFailed()) {
+                        const taskName = taskStats.get(taskId)?.name;
+                        if (taskName) {
+                            config?.onTaskReady?.(taskName, taskId);
+                        }
                         queueManager.markRunningTaskReady(taskId);
                         // Process newly ready tasks immediately
                         processReadyTasks();
@@ -171,10 +175,16 @@ export function pipeline(tasks) {
             const isPipelineFailed = () => {
                 return failed || queueManager.hasFailed();
             };
-            // Helper to safely kill a process (ignores errors if process is already dead)
+            // Helper to safely kill a process (ignores errors if process is already dead).
+            // With shell:false and direct child processes, a single SIGTERM is usually enough;
+            // we avoid force-killing from the outside so the child has a chance to run its
+            // own signal handlers and exit cleanly.
             const safeKillProcess = (process) => {
+                if (!process)
+                    return;
                 try {
-                    process?.kill("SIGTERM");
+                    // Try a graceful SIGTERM and let the child handle it.
+                    process.kill("SIGTERM");
                 }
                 catch {
                     // Process might already be dead, ignore
@@ -236,7 +246,7 @@ export function pipeline(tasks) {
             const signalHandler = createSignalHandler({
                 abortSignal: signal,
                 onAborted: () => failPipeline(new PipelineError("Aborted", PipelineError.Aborted)),
-                onProcessTerminated: (message) => new PipelineError(message, PipelineError.ProcessTerminated),
+                onProcessTerminated: (message) => failPipeline(new PipelineError(message, PipelineError.ProcessTerminated)),
             });
             // 🚀 Start processing ready tasks
             processReadyTasks();
@@ -268,11 +278,8 @@ export function pipeline(tasks) {
 function buildResult(error, startedAt, command, taskStats, status) {
     const finishedAt = Date.now();
     const durationMs = finishedAt - startedAt;
-    // Convert task stats map to record
-    const tasks = {};
-    for (const [taskId, stats] of taskStats) {
-        tasks[taskId] = stats;
-    }
+    // Convert task stats map to array
+    const tasks = Array.from(taskStats.values());
     // Calculate summary
     let completed = 0;
     let failed = 0;

package/dist/types.d.ts

@@ -145,31 +145,42 @@ export interface PipelineRunConfig {
     /**
      * Callback invoked when a task begins execution.
      * @param taskName The name of the task that started.
+     * @param taskId The id of the task that started.
      */
-    onTaskBegin?: (taskName: string) => void;
+    onTaskBegin?: (taskName: string, taskId: string) => void;
+    /**
+     * Callback invoked when a task becomes ready (via readyWhen condition).
+     * This is called when a task with a `readyWhen` function satisfies its condition.
+     * @param taskName The name of the task that became ready.
+     * @param taskId The id of the task that became ready.
+     */
+    onTaskReady?: (taskName: string, taskId: string) => void;
     /**
      * Callback invoked when a task completes successfully.
      * @param taskName The name of the task that completed.
+     * @param taskId The id of the task that completed.
      */
-    onTaskComplete?: (taskName: string) => void;
+    onTaskComplete?: (taskName: string, taskId: string) => 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 taskId The id of the task that was skipped.
      * @param mode The command mode that was requested (e.g., "dev", "build").
      */
-    onTaskSkipped?: (taskName: string, mode: string) => void;
+    onTaskSkipped?: (taskName: string, taskId: 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.
+     * @param taskId The id of the task whose teardown is running.
      */
-    onTaskTeardown?: (taskName: string) => void;
+    onTaskTeardown?: (taskName: string, taskId: 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;
+    onTaskTeardownError?: (taskName: string, taskId: string, error: Error) => void;
 }
 /**
  * Configuration for converting a pipeline into a task.
@@ -329,6 +340,12 @@ export interface TaskStats {
      * These tasks cannot start until this task completes.
      */
     dependents: string[];
+    /**
+     * Statistics for nested tasks when this task represents a pipeline
+     * (created via pipeline.toTask()). Only present for pipeline-tasks.
+     * Contains statistics for all tasks within the nested pipeline.
+     */
+    subtasks?: TaskStats[];
 }
 /**
  * Statistics for the entire pipeline execution.
@@ -358,10 +375,10 @@ export interface PipelineStats {
      */
     status: "success" | "failed" | "aborted";
     /**
-     * Map of task IDs to their statistics.
+     * Array of task statistics.
      * Contains statistics for all tasks in the pipeline, regardless of their status.
      */
-    tasks: Record<string, TaskStats>;
+    tasks: TaskStats[];
     /**
      * Summary of task execution counts.
      */

package/package.json

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