builderman 1.2.0 → 1.4.0

package/dist/scheduler.d.ts

@@ -1,17 +1,17 @@
 import type { TaskGraph } from "./types.js";
 export type SchedulerInput = {
     type: "complete";
-    taskId: number;
+    taskId: string;
 } | {
     type: "ready";
-    taskId: number;
+    taskId: string;
 } | {
     type: "skip";
-    taskId: number;
+    taskId: string;
 };
 export type SchedulerOutput = {
     type: "run";
-    taskId: number;
+    taskId: string;
 } | {
     type: "idle";
 };

package/dist/scheduler.js

@@ -32,9 +32,9 @@ export function* createScheduler(graph) {
         if (input?.taskId === undefined)
             continue;
         markDependencyReady(input.taskId);
-        if (input.type === "ready")
-            continue;
-        completed++;
+        if (input.type === "complete" || input.type === "skip") {
+            completed++;
+        }
     }
     return { type: "done" };
 }

package/dist/task.d.ts

@@ -7,10 +7,5 @@ import type { TaskConfig, Task } from "./types.js";
  * const build = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
  * const deploy = task({ name: "deploy", commands: { build: "npm run deploy" }, cwd: ".", dependencies: [build] })
  * await pipeline([build, deploy]).run()
- *
- * // alternatively, you can use the andThen method to chain tasks together:
- * const buildAndDeploy = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
- *   .andThen({ name: "deploy", commands: { build: "npm run deploy" }, cwd: "." })
- * await buildAndDeploy.run()
  */
 export declare function task(config: TaskConfig): Task;

package/dist/task.js

@@ -1,7 +1,5 @@
 import { $TASK_INTERNAL } from "./constants.js";
 import { validateTasks } from "./util.js";
-import { pipeline } from "./pipeline.js";
-let taskId = 0;
 /**
  * Creates a task configuration.
  * @param config - The configuration for the task.
@@ -10,30 +8,28 @@ let taskId = 0;
  * const build = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
  * const deploy = task({ name: "deploy", commands: { build: "npm run deploy" }, cwd: ".", dependencies: [build] })
  * await pipeline([build, deploy]).run()
- *
- * // alternatively, you can use the andThen method to chain tasks together:
- * const buildAndDeploy = task({ name: "build", commands: { build: "npm run build" }, cwd: "." })
- *   .andThen({ name: "deploy", commands: { build: "npm run deploy" }, cwd: "." })
- * await buildAndDeploy.run()
  */
 export function task(config) {
-    validateTasks(config.dependencies);
-    const taskInstance = {
-        name: config.name,
+    const { name, commands, cwd = ".", dependencies = [], env, allowSkip, } = config;
+    const dependenciesClone = [...dependencies];
+    validateTasks(dependenciesClone);
+    const commandsClone = Object.fromEntries(Object.entries(commands).map(([key, command]) => {
+        if (typeof command === "string") {
+            return [key, command];
+        }
+        const { run, readyWhen, readyTimeout, teardown, env } = command;
+        return [key, { run, readyWhen, readyTimeout, teardown, env: { ...env } }];
+    }));
+    return {
+        name,
         [$TASK_INTERNAL]: {
-            ...config,
-            id: taskId++,
-            dependencies: [...(config.dependencies || [])],
-        },
-        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]);
+            name,
+            cwd,
+            dependencies: dependenciesClone,
+            env: { ...env },
+            allowSkip,
+            id: crypto.randomUUID(),
+            commands: commandsClone,
         },
     };
-    return taskInstance;
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { $TASK_INTERNAL } from "./constants.js";
-import { PipelineError } from "./pipeline.js";
+import { PipelineError } from "./pipeline-error.js";
 /**
  * Configuration for a command to be executed as part of a task.
  */
@@ -25,6 +25,11 @@ export interface CommandConfig {
      * Optional command to run during teardown (e.g., to stop a server).
      */
     teardown?: string;
+    /**
+     * Optional environment variables to set for the process spawned by this command.
+     * Overrides environment variables inherited from the parent process & task config.
+     */
+    env?: Record<string, string>;
 }
 /**
  * A command can be either a simple string or a CommandConfig object.
@@ -57,8 +62,9 @@ export interface TaskConfig {
     /**
      * Working directory for the task's commands.
      * Can be absolute or relative to the current working directory.
+     * @default "."
      */
-    cwd: string;
+    cwd?: string;
     /**
      * Optional array of tasks that must complete before this task can start.
      * Dependencies are executed in parallel when possible.
@@ -69,10 +75,17 @@ export interface TaskConfig {
      * Use this to explicitly mark tasks that are intentionally mode-specific.
      */
     allowSkip?: boolean;
+    /**
+     * Optional environment variables to set for the process spawned by this task.
+     * Overrides environment variables inherited from the parent process.
+     */
+    env?: Record<string, string>;
 }
 interface TaskInternal extends TaskConfig {
-    id: number;
+    id: string;
+    cwd: string;
     dependencies: Task[];
+    env: Record<string, string>;
     pipeline?: Pipeline;
 }
 /**
@@ -89,13 +102,6 @@ export interface Task {
      * @internal
      */
     [$TASK_INTERNAL]: TaskInternal;
-    /**
-     * Creates a new pipeline that starts after this task completes.
-     * This allows for chaining tasks together.
-     * @param config Task configuration for the next task in the chain.
-     * @returns A new pipeline starting with the configured task.
-     */
-    andThen(config: Omit<TaskConfig, "dependencies">): Pipeline;
 }
 /**
  * Configuration options for running a pipeline.
@@ -106,6 +112,11 @@ export interface PipelineRunConfig {
      * @default process.env.NODE_ENV === "production" ? "build" : "dev"
      */
     command?: string;
+    /**
+     * Optional environment variables to set for processes spawned by this pipeline.
+     * Overrides environment variables inherited from the parent process.
+     */
+    env?: Record<string, string>;
     /**
      * Provides a custom abort signal for the pipeline.
      * Aborting the signal will cause the pipeline to fail.
@@ -149,16 +160,6 @@ export interface PipelineRunConfig {
      * @param error The error that occurred during teardown.
      */
     onTaskTeardownError?: (taskName: string, error: Error) => void;
-    /**
-     * Callback invoked when the pipeline encounters an error and fails.
-     * @param error The PipelineError that caused the pipeline to fail.
-     */
-    onPipelineError?: (error: PipelineError) => void;
-    /**
-     * Callback invoked when the pipeline completes successfully.
-     * This is called after all tasks have completed and all teardowns have finished.
-     */
-    onPipelineComplete?: () => void;
 }
 /**
  * Configuration for converting a pipeline into a task.
@@ -173,6 +174,11 @@ export interface PipelineTaskConfig {
      * Optional array of tasks that must complete before this pipeline task can start.
      */
     dependencies?: Task[];
+    /**
+     * Optional environment variables to set for the process spawned by this pipeline task.
+     * Overrides environment variables inherited from the parent process.
+     */
+    env?: Record<string, string>;
 }
 /**
  * A pipeline manages the execution of tasks with dependency-based coordination.
@@ -184,10 +190,10 @@ export interface Pipeline {
      * Tasks with no dependencies start immediately, and tasks with dependencies
      * wait for their dependencies to complete before starting.
      * @param config Optional configuration for pipeline execution.
-     * @returns A promise that resolves when all tasks complete successfully,
-     *          or rejects if any task fails or the pipeline is aborted.
+     * @returns A promise that resolves with a RunResult containing execution stats.
+     *          The result will have `ok: false` if any task fails or the pipeline is aborted.
      */
-    run(config?: PipelineRunConfig): Promise<void>;
+    run(config?: PipelineRunConfig): Promise<RunResult>;
     /**
      * Converts this pipeline into a task that can be used as a dependency
      * in another pipeline. This enables nested pipelines.
@@ -198,11 +204,11 @@ export interface Pipeline {
 }
 export interface TaskNode {
     task: Task;
-    dependencies: Set<number>;
-    dependents: Set<number>;
+    dependencies: Set<string>;
+    dependents: Set<string>;
 }
 export interface TaskGraph {
-    nodes: Map<number, TaskNode>;
+    nodes: Map<string, TaskNode>;
     /**
      * Validates the graph for circular dependencies.
      * @throws Error if circular dependencies are detected
@@ -214,4 +220,204 @@ export interface TaskGraph {
      */
     simplify(): void;
 }
+/**
+ * Status of a task in the pipeline.
+ * - "pending": Task has not started yet
+ * - "skipped": Task was skipped (e.g., no command for the current mode)
+ * - "running": Task is currently executing
+ * - "completed": Task completed successfully
+ * - "failed": Task failed during execution
+ * - "aborted": Task was aborted (e.g., due to pipeline cancellation)
+ */
+export type TaskStatus = "pending" | "skipped" | "running" | "completed" | "failed" | "aborted";
+/**
+ * Statistics for a single task in the pipeline.
+ */
+export interface TaskStats {
+    /**
+     * Unique identifier for the task.
+     */
+    id: string;
+    /**
+     * Human-readable name of the task.
+     */
+    name: string;
+    /**
+     * Current status of the task.
+     */
+    status: TaskStatus;
+    /**
+     * Command name that was executed (e.g., "dev", "build").
+     * Only present if the task was executed or skipped (not if it's still pending).
+     */
+    command?: string;
+    /**
+     * Timestamp (milliseconds since epoch) when the task started execution.
+     * Only present if the task started running.
+     */
+    startedAt?: number;
+    /**
+     * Timestamp (milliseconds since epoch) when the task finished execution.
+     * Only present if the task completed, failed, was skipped, or was aborted.
+     */
+    finishedAt?: number;
+    /**
+     * Duration of task execution in milliseconds.
+     * Only present if the task has finished (completed, failed, skipped, or aborted).
+     */
+    durationMs?: number;
+    /**
+     * Exit code of the task's process.
+     * Only present if the task completed or failed.
+     * Typically 0 for success, non-zero for failure.
+     */
+    exitCode?: number;
+    /**
+     * Signal that terminated the task's process (e.g., "SIGTERM", "SIGKILL").
+     * Only present if the task was terminated by a signal.
+     */
+    signal?: string;
+    /**
+     * Error that occurred during task execution.
+     * Only present if the task failed or was aborted.
+     */
+    error?: Error;
+    /**
+     * Teardown command execution status.
+     * Only present if the task had a teardown command configured.
+     */
+    teardown?: {
+        /**
+         * Status of the teardown command execution.
+         * - "not-run": Teardown was registered but never executed (e.g., task failed before starting)
+         * - "completed": Teardown executed successfully
+         * - "failed": Teardown execution failed
+         */
+        status: "not-run" | "completed" | "failed";
+        /**
+         * Error that occurred during teardown execution.
+         * Only present if teardown status is "failed".
+         */
+        error?: Error;
+    };
+    /**
+     * Array of task IDs that this task depends on.
+     * These tasks must complete before this task can start.
+     */
+    dependencies: string[];
+    /**
+     * Array of task IDs that depend on this task.
+     * These tasks cannot start until this task completes.
+     */
+    dependents: string[];
+}
+/**
+ * Statistics for the entire pipeline execution.
+ */
+export interface PipelineStats {
+    /**
+     * Command name that was executed for this pipeline run (e.g., "dev", "build").
+     */
+    command: string;
+    /**
+     * Timestamp (milliseconds since epoch) when the pipeline started.
+     */
+    startedAt: number;
+    /**
+     * Timestamp (milliseconds since epoch) when the pipeline finished.
+     */
+    finishedAt: number;
+    /**
+     * Total duration of pipeline execution in milliseconds.
+     */
+    durationMs: number;
+    /**
+     * Overall status of the pipeline.
+     * - "success": All tasks completed successfully
+     * - "failed": One or more tasks failed
+     * - "aborted": Pipeline was aborted (e.g., due to signal cancellation)
+     */
+    status: "success" | "failed" | "aborted";
+    /**
+     * Map of task IDs to their statistics.
+     * Contains statistics for all tasks in the pipeline, regardless of their status.
+     */
+    tasks: Record<string, TaskStats>;
+    /**
+     * Summary of task execution counts.
+     */
+    summary: {
+        /**
+         * Total number of tasks in the pipeline.
+         */
+        total: number;
+        /**
+         * Number of tasks that completed successfully.
+         */
+        completed: number;
+        /**
+         * Number of tasks that failed.
+         */
+        failed: number;
+        /**
+         * Number of tasks that were skipped.
+         */
+        skipped: number;
+        /**
+         * Number of tasks that were still running when the pipeline ended.
+         * This is useful when the pipeline was aborted - it indicates how many
+         * tasks were in progress and had to be terminated.
+         */
+        running: number;
+    };
+}
+/**
+ * Result of running a pipeline.
+ * The pipeline never throws - it always returns a RunResult with detailed statistics.
+ *
+ * @example
+ * ```ts
+ * const result = await pipeline(tasks).run({ command: "dev" })
+ *
+ * if (!result.ok) {
+ *   console.error("Pipeline failed:", result.error)
+ * }
+ *
+ * console.log("Pipeline stats:", result.stats)
+ * console.log(`Completed: ${result.stats.summary.completed}`)
+ * console.log(`Failed: ${result.stats.summary.failed}`)
+ * ```
+ */
+export type RunResult = {
+    /**
+     * Indicates the pipeline completed successfully.
+     * When true, `error` is always `null`.
+     */
+    ok: true;
+    /**
+     * Always `null` when `ok` is `true`.
+     */
+    error: null;
+    /**
+     * Pipeline execution statistics.
+     */
+    stats: PipelineStats;
+} | {
+    /**
+     * Indicates the pipeline failed or was aborted.
+     * When false, `error` contains the PipelineError that caused the failure.
+     */
+    ok: false;
+    /**
+     * The error that caused the pipeline to fail.
+     * Check `error.code` to determine the error type (e.g., `PipelineError.TaskFailed`).
+     */
+    error: PipelineError;
+    /**
+     * Pipeline execution statistics.
+     * Even when the pipeline fails, stats contain information about all tasks,
+     * including which ones completed, failed, or were still running.
+     */
+    stats: PipelineStats;
+};
 export {};

package/package.json

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

package/dist/pipeline.test.d.ts

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