builderman 1.3.0 → 1.4.0

package/README.md

@@ -10,28 +10,29 @@ It is designed for monorepos, long-running development processes, and CI/CD pipe
 
 ## Table of Contents
 
-- [Key Features](#key-features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-  - [Tasks](#tasks)
-  - [Commands & Modes](#commands--modes)
-  - [Dependencies](#dependencies)
-  - [Pipelines](#pipelines)
-  - [Pipeline Composition](#pipeline-composition)
-- [Error Handling Guarantees](#error-handling-guarantees)
-- [Cancellation](#cancellation)
-- [Teardown](#teardown)
-  - [Basic Teardown](#basic-teardown)
-  - [Teardown Callbacks](#teardown-callbacks)
-  - [Teardown Execution Rules](#teardown-execution-rules)
-- [Skipping Tasks](#skipping-tasks)
-  - [Strict Mode](#strict-mode)
-  - [Task-Level Skip Override](#task-level-skip-override)
-- [Execution Statistics](#execution-statistics)
-  - [Pipeline Statistics](#pipeline-statistics)
-  - [Task Statistics](#task-statistics)
-- [When Should I Use builderman?](#when-should-i-use-builderman)
+> - [Key Features](#key-features)
+> - [Installation](#installation)
+> - [Quick Start](#quick-start)
+> - [Core Concepts](#core-concepts)
+>   - [Tasks](#tasks)
+>   - [Commands & Modes](#commands--modes)
+>   - [Environment Variables](#environment-variables)
+>   - [Dependencies](#dependencies)
+>   - [Pipelines](#pipelines)
+>   - [Pipeline Composition](#pipeline-composition)
+> - [Error Handling Guarantees](#error-handling-guarantees)
+> - [Cancellation](#cancellation)
+> - [Teardown](#teardown)
+>   - [Basic Teardown](#basic-teardown)
+>   - [Teardown Callbacks](#teardown-callbacks)
+>   - [Teardown Execution Rules](#teardown-execution-rules)
+> - [Skipping Tasks](#skipping-tasks)
+>   - [Strict Mode](#strict-mode)
+>   - [Task-Level Skip Override](#task-level-skip-override)
+> - [Execution Statistics](#execution-statistics)
+>   - [Pipeline Statistics](#pipeline-statistics)
+>   - [Task Statistics](#task-statistics)
+> - [When Should I Use builderman?](#when-should-i-use-builderman)
 
 ## Key Features
 
@@ -62,17 +63,19 @@ import { task, pipeline } from "builderman"
 const build = task({
   name: "build",
   commands: { build: "tsc" },
-  cwd: ".",
+  cwd: "packages/my-package", // Optional: defaults to "."
 })
 
 const test = task({
   name: "test",
   commands: { build: "npm test" },
-  cwd: ".",
   dependencies: [build],
+  cwd: "packages/my-package",
 })
 
-const result = await pipeline([build, test]).run()
+const result = await pipeline([build, test]).run({
+  command: "build",
+})
 
 if (!result.ok) {
   console.error("Pipeline failed:", result.error.message)
@@ -93,6 +96,7 @@ A **task** represents a unit of work. Each task:
 - Defines commands for one or more modes
 - May depend on other tasks
 - May register teardown logic
+- Has an optional working directory (`cwd`, defaults to `"."`)
 
 ```ts
 import { task } from "builderman"
@@ -130,6 +134,89 @@ Commands may be:
   - `run`: the command to execute
   - `readyWhen`: a predicate that marks the task as ready
   - `teardown`: cleanup logic to run after completion
+  - `env`: environment variables specific to this command
+
+---
+
+### Environment Variables
+
+Environment variables can be provided at multiple levels, with more specific levels overriding less specific ones:
+
+**Precedence order (highest to lowest):**
+
+1. Command-level `env` (in command config)
+2. Task-level `env` (in task config)
+3. Pipeline-level `env` (in `pipeline.run()`)
+4. Process environment variables
+
+#### Command-Level Environment Variables
+
+```ts
+const apiTask = task({
+  name: "api",
+  commands: {
+    dev: {
+      run: "npm run dev",
+      env: {
+        PORT: "3000",
+        NODE_ENV: "development",
+      },
+    },
+  },
+})
+```
+
+#### Task-Level Environment Variables
+
+```ts
+const apiTask = task({
+  name: "api",
+  commands: {
+    dev: "npm run dev",
+    build: "npm run build",
+  },
+  env: {
+    API_URL: "http://localhost:3000",
+    LOG_LEVEL: "debug",
+  },
+})
+```
+
+#### Pipeline-Level Environment Variables
+
+```ts
+const result = await pipeline([apiTask]).run({
+  env: {
+    DATABASE_URL: "postgres://localhost/mydb",
+    REDIS_URL: "redis://localhost:6379",
+  },
+})
+```
+
+#### Nested Pipeline Environment Variables
+
+When converting a pipeline to a task, you can provide environment variables that will be merged with the outer pipeline's environment:
+
+```ts
+const innerPipeline = pipeline([
+  /* ... */
+])
+const innerTask = innerPipeline.toTask({
+  name: "inner",
+  env: {
+    INNER_VAR: "inner-value",
+  },
+})
+
+const outerPipeline = pipeline([innerTask])
+const result = await outerPipeline.run({
+  env: {
+    OUTER_VAR: "outer-value",
+  },
+})
+```
+
+In this example, tasks in `innerPipeline` will receive both `INNER_VAR` and `OUTER_VAR`, with `INNER_VAR` taking precedence if there's a conflict.
 
 ---
 
@@ -187,7 +274,11 @@ const deploy = pipeline([
 ])
 
 const buildTask = build.toTask({ name: "build" })
-const testTask = test.toTask({ name: "test", dependencies: [buildTask] })
+const testTask = test.toTask({
+  name: "test",
+  dependencies: [buildTask],
+  env: { TEST_ENV: "test-value" }, // Optional: env for nested pipeline
+})
 const deployTask = deploy.toTask({ name: "deploy", dependencies: [testTask] })
 
 const ci = pipeline([buildTask, testTask, deployTask])
@@ -278,7 +369,6 @@ const dbTask = task({
     },
     build: "echo build",
   },
-  cwd: ".",
 })
 ```
 
@@ -336,7 +426,6 @@ const dbTask = task({
   commands: {
     dev: "docker-compose up",
   },
-  cwd: ".",
 })
 
 const apiTask = task({
@@ -345,7 +434,6 @@ const apiTask = task({
     dev: "npm run dev",
     build: "npm run build",
   },
-  cwd: ".",
   dependencies: [dbTask],
 })
 
@@ -386,7 +474,6 @@ const dbTask = task({
   commands: {
     dev: "docker-compose up",
   },
-  cwd: ".",
   allowSkip: true,
 })
 

package/dist/modules/task-executor.js

@@ -17,13 +17,13 @@ export function executeTask(task, executorConfig) {
         return;
     // Handle pipeline tasks
     if (nestedPipeline) {
-        executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig);
+        executeNestedPipeline(task, taskId, taskName, nestedPipeline, executorConfig);
         return;
     }
     // Regular task execution
     executeRegularTask(task, taskId, taskName, executorConfig);
 }
-function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig) {
+function executeNestedPipeline(task, taskId, taskName, nestedPipeline, executorConfig) {
     const { config, runningPipelines, pipelineTasksCache, failPipeline, advanceScheduler, updateTaskStatus, } = executorConfig;
     // Track nested pipeline state for skip behavior
     let nestedSkippedCount = 0;
@@ -33,7 +33,7 @@ function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig)
     const nestedTotalTasks = nestedTasks
         ? createTaskGraph(nestedTasks).nodes.size
         : 0;
-    const commandName = (config?.command ?? process.env.NODE_ENV === "production") ? "build" : "dev";
+    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, {
@@ -51,6 +51,13 @@ function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig)
         // In a more sophisticated implementation, we could propagate stop signals
     };
     runningPipelines.set(taskId, { stop: stopPipeline });
+    // Merge environment variables: pipeline.env -> task.env (from pipeline.toTask config)
+    const taskEnv = task[$TASK_INTERNAL].env;
+    const pipelineEnv = config?.env ?? {};
+    const mergedEnv = {
+        ...pipelineEnv,
+        ...taskEnv,
+    };
     // Run the nested pipeline with signal propagation
     nestedPipeline
         .run({
@@ -58,6 +65,7 @@ function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig)
         command: config?.command,
         strict: config?.strict,
         signal: executorConfig.signal, // Pass signal to nested pipeline
+        env: mergedEnv, // Pass merged env to nested pipeline
         onTaskBegin: (nestedTaskName) => {
             if (pipelineStopped)
                 return;
@@ -124,11 +132,11 @@ function executeNestedPipeline(taskId, taskName, nestedPipeline, executorConfig)
 }
 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];
+    const { allowSkip, commands, cwd, env: taskEnv } = task[$TASK_INTERNAL];
+    const commandName = config?.command ?? process.env.NODE_ENV === "production" ? "build" : "dev";
+    const commandConfig = 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) {
@@ -159,13 +167,21 @@ function executeRegularTask(task, taskId, taskName, executorConfig) {
         });
         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];
+    let command;
+    let readyWhen;
+    let readyTimeout = Infinity;
+    let teardown;
+    let commandEnv = {};
+    if (typeof commandConfig === "string") {
+        command = commandConfig;
+    }
+    else {
+        command = commandConfig.run;
+        readyWhen = commandConfig.readyWhen;
+        readyTimeout = commandConfig.readyTimeout ?? Infinity;
+        teardown = commandConfig.teardown;
+        commandEnv = commandConfig.env ?? {};
+    }
     const taskCwd = path.isAbsolute(cwd) ? cwd : path.resolve(process.cwd(), cwd);
     if (!fs.existsSync(taskCwd)) {
         const finishedAt = Date.now();
@@ -187,16 +203,20 @@ function executeRegularTask(task, taskId, taskName, executorConfig) {
     ]
         .filter(Boolean)
         .join(process.platform === "win32" ? ";" : ":");
-    const env = {
+    // Merge environment variables in order: process.env -> pipeline.env -> task.env -> command.env
+    const accumulatedEnv = {
         ...process.env,
         PATH: accumulatedPath,
         Path: accumulatedPath,
+        ...config?.env,
+        ...taskEnv,
+        ...commandEnv,
     };
     const child = spawnFn(command, {
         cwd: taskCwd,
         stdio: ["inherit", "pipe", "pipe"],
         shell: true,
-        env,
+        env: accumulatedEnv,
     });
     runningTasks.set(taskId, child);
     const startedAt = Date.now();

package/dist/pipeline.js

@@ -26,12 +26,12 @@ export function pipeline(tasks) {
     graph.validate();
     graph.simplify();
     const pipelineImpl = {
-        toTask({ name, dependencies }) {
+        toTask({ name, dependencies, env }) {
             const syntheticTask = task({
                 name,
                 commands: {},
-                cwd: ".",
                 dependencies,
+                env,
             });
             // Mark this task as a pipeline task so it can be detected by the executor
             syntheticTask[$TASK_INTERNAL].pipeline = pipelineImpl;

package/dist/task.js

@@ -10,18 +10,26 @@ import { validateTasks } from "./util.js";
  * await pipeline([build, deploy]).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,
+            name,
+            cwd,
+            dependencies: dependenciesClone,
+            env: { ...env },
+            allowSkip,
             id: crypto.randomUUID(),
-            commands: Object.fromEntries(Object.entries(config.commands).map(([key, value]) => [
-                key,
-                typeof value === "string" ? value : { ...value },
-            ])),
-            dependencies: [...(config.dependencies || [])],
+            commands: commandsClone,
         },
     };
-    return taskInstance;
 }

package/dist/types.d.ts

@@ -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: string;
+    cwd: string;
     dependencies: Task[];
+    env: Record<string, string>;
     pipeline?: Pipeline;
 }
 /**
@@ -99,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.
@@ -156,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.

package/package.json

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