numux 1.17.0 → 1.19.0

package/README.md

@@ -191,7 +191,8 @@ Top-level options apply to all processes (process-level settings override):
 |-------|------|-------------|
 | `cwd` | `string` | Working directory for all processes (process `cwd` overrides) |
 | `env` | `Record<string, string>` | Environment variables merged into all processes (process `env` overrides per key) |
-| `envFile` | `string \| string[]` | `.env` file(s) for all processes (process `envFile` replaces if set) |
+| `envFile` | `string \| string[] \| false` | `.env` file(s) for all processes (process `envFile` replaces if set; `false` disables) |
+| `showCommand` | `boolean` | Print the command being run as the first line of output (default: `true`) |
 
 ```ts
 export default defineConfig({
@@ -211,10 +212,10 @@ Each process accepts:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `command` | `string` | *required* | Shell command to run |
+| `command` | `string` | *required* | Shell command to run. Supports `$dep.group` references from dependency capture groups |
 | `cwd` | `string` | `process.cwd()` | Working directory |
-| `env` | `Record<string, string>` | — | Extra environment variables |
-| `envFile` | `string \| string[]` | — | `.env` file path(s) to load (relative to `cwd`) |
+| `env` | `Record<string, string>` | — | Extra environment variables. Values support `$dep.group` references from dependency capture groups |
+| `envFile` | `string \| string[] \| false` | — | `.env` file path(s) to load (relative to `cwd`); `false` disables inherited envFile |
 | `dependsOn` | `string[]` | — | Processes that must be ready first |
 | `readyPattern` | `string \| RegExp` | — | Regex matched against stdout to signal readiness. Use `RegExp` to capture groups (see below) |
 | `readyTimeout` | `number` | — | Milliseconds to wait for `readyPattern` before failing |
@@ -227,6 +228,7 @@ Each process accepts:
 | `watch` | `string \| string[]` | — | Glob patterns — restart process when matching files change |
 | `interactive` | `boolean` | `false` | When `true`, keyboard input is forwarded to the process |
 | `errorMatcher` | `boolean \| string` | — | `true` detects ANSI red output, string = regex pattern — shows error indicator on tab |
+| `showCommand` | `boolean` | `true` | Print the command being run as the first line of output |
 
 ### File watching
 
@@ -311,7 +313,7 @@ Persistent processes that crash are auto-restarted with exponential backoff (1s
 
 ### Dependency output capture
 
-When `readyPattern` is a `RegExp` (not a string), capture groups are extracted on match and expanded into dependent process commands using `$process.group` syntax:
+When `readyPattern` is a `RegExp` (not a string), capture groups are extracted on match and expanded into dependent process `command` and `env` values using `$process.group` syntax:
 
 ```ts
 export default defineConfig({
@@ -323,6 +325,7 @@ export default defineConfig({
     api: {
       command: 'node server.js --db-port $db.port',
       dependsOn: ['db'],
+      env: { DB_PORT: '$db.port' },
     },
   },
 })

package/dist/config.d.ts

@@ -1,4 +1,4 @@
 import type { NumuxConfig } from './types';
 export type { NumuxConfig, NumuxProcessConfig } from './types';
 /** Type-safe helper for numux.config.ts files. */
-export declare function defineConfig(config: NumuxConfig): NumuxConfig;
+export declare function defineConfig<K extends string>(config: NumuxConfig<K>): NumuxConfig<K>;

package/dist/numux.js

@@ -36,7 +36,7 @@ var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports,
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "numux",
-    version: "1.17.0",
+    version: "1.19.0",
     description: "Terminal multiplexer with dependency orchestration",
     type: "module",
     license: "MIT",
@@ -1030,8 +1030,10 @@ function validateConfig(raw, warnings) {
       throw new Error(`Process "${name}" must have a non-empty "command" string`);
     }
     if (p.dependsOn !== undefined) {
+      if (typeof p.dependsOn === "string")
+        p.dependsOn = [p.dependsOn];
       if (!Array.isArray(p.dependsOn)) {
-        throw new Error(`Process "${name}".dependsOn must be an array`);
+        throw new Error(`Process "${name}".dependsOn must be a string or array`);
       }
       for (const dep of p.dependsOn) {
         if (typeof dep !== "string") {
@@ -1419,6 +1421,7 @@ class ProcessRunner {
   restarting = false;
   readyTimedOut = false;
   commandOverride;
+  envOverride;
   constructor(name, config, handler) {
     this.name = name;
     this.config = config;
@@ -1432,9 +1435,11 @@ class ProcessRunner {
   get signal() {
     return this.config.stopSignal ?? "SIGTERM";
   }
-  start(cols, rows, commandOverride) {
+  start(cols, rows, commandOverride, envOverride) {
     if (commandOverride !== undefined)
       this.commandOverride = commandOverride;
+    if (envOverride !== undefined)
+      this.envOverride = envOverride;
     const command = this.commandOverride ?? this.config.command;
     const gen = ++this.generation;
     this.stopping = false;
@@ -1449,7 +1454,7 @@ class ProcessRunner {
         ...noColor ? {} : { FORCE_COLOR: "1" },
         TERM: "xterm-256color",
         ...envFromFile,
-        ...this.config.env
+        ...this.envOverride ?? this.config.env
       };
       this.proc = Bun.spawn(["sh", "-c", command], {
         cwd,
@@ -1567,7 +1572,7 @@ class ProcessRunner {
     this.handler.onStatus("ready");
     this.handler.onReady(this.readiness.captures);
   }
-  async restart(cols, rows, commandOverride) {
+  async restart(cols, rows, commandOverride, envOverride) {
     if (this.restarting)
       return;
     this.restarting = true;
@@ -1592,7 +1597,7 @@ class ProcessRunner {
     this.readyTimedOut = false;
     this.readiness = createReadinessChecker(this.config);
     this.errorChecker = createErrorChecker(this.config);
-    this.start(cols, rows, commandOverride);
+    this.start(cols, rows, commandOverride, envOverride);
   }
   async stop(timeoutMs = 5000) {
     if (!this.proc)
@@ -1737,7 +1742,7 @@ class ProcessManager {
     this.setupWatchers();
   }
   startProcess(name, cols, rows) {
-    const commandOverride = this.expandDependencyCaptures(name);
+    const { command, env } = this.expandDependencyCaptures(name);
     const delay = this.config.processes[name].delay;
     if (delay) {
       log(`[${name}] Delaying start by ${delay}ms`);
@@ -1746,12 +1751,12 @@ class ProcessManager {
         if (this.stopping)
           return;
         this.startTimes.set(name, Date.now());
-        this.runners.get(name).start(cols, rows, commandOverride);
+        this.runners.get(name).start(cols, rows, command, env);
       }, delay);
       this.restartTimers.set(name, timer);
     } else {
       this.startTimes.set(name, Date.now());
-      this.runners.get(name).start(cols, rows, commandOverride);
+      this.runners.get(name).start(cols, rows, command, env);
     }
   }
   createRunner(name, onInitialReady) {
@@ -1860,7 +1865,7 @@ class ProcessManager {
     const proc = this.config.processes[name];
     const deps = proc.dependsOn;
     if (!deps?.length)
-      return;
+      return {};
     const allCaptures = new Map;
     for (const dep of deps) {
       const captures = this.readyCaptures.get(dep);
@@ -1868,19 +1873,33 @@ class ProcessManager {
         allCaptures.set(dep, captures);
     }
     if (allCaptures.size === 0)
-      return;
+      return {};
     const depNames = [...allCaptures.keys()].map((n) => escapeRegExp(n)).join("|");
     const refPattern = new RegExp(`\\$(${depNames})\\.(\\w+)`, "g");
-    let hadReplacement = false;
-    const expanded = proc.command.replace(refPattern, (match, dep, key) => {
+    const replacer = (match, dep, key) => {
       const captures = allCaptures.get(dep);
-      if (captures && key in captures) {
-        hadReplacement = true;
+      if (captures && key in captures)
         return captures[key];
-      }
       return match;
-    });
-    return hadReplacement ? expanded : undefined;
+    };
+    let command;
+    const expandedCmd = proc.command.replace(refPattern, replacer);
+    if (expandedCmd !== proc.command)
+      command = expandedCmd;
+    let env;
+    if (proc.env) {
+      const expandedEnv = {};
+      let hadReplacement = false;
+      for (const [k, v] of Object.entries(proc.env)) {
+        const expanded = v.replace(refPattern, replacer);
+        expandedEnv[k] = expanded;
+        if (expanded !== v)
+          hadReplacement = true;
+      }
+      if (hadReplacement)
+        env = expandedEnv;
+    }
+    return { command, env };
   }
   updateStatus(name, status) {
     const state = this.states.get(name);
@@ -1908,7 +1927,8 @@ class ProcessManager {
     state.exitCode = null;
     state.restartCount++;
     this.startTimes.set(name, Date.now());
-    runner.restart(cols, rows, this.expandDependencyCaptures(name));
+    const { command, env } = this.expandDependencyCaptures(name);
+    runner.restart(cols, rows, command, env);
   }
   async stop(name) {
     const state = this.states.get(name);
@@ -1946,7 +1966,8 @@ class ProcessManager {
     state.exitCode = null;
     state.restartCount++;
     this.startTimes.set(name, Date.now());
-    this.runners.get(name)?.restart(cols, rows, this.expandDependencyCaptures(name));
+    const { command, env } = this.expandDependencyCaptures(name);
+    this.runners.get(name)?.restart(cols, rows, command, env);
   }
   restartAll(cols, rows) {
     log("Restarting all processes");

package/dist/types.d.ts

@@ -1,42 +1,89 @@
-export interface NumuxProcessConfig {
+export interface NumuxProcessConfig<K extends string = string> {
+    /** Shell command to run. Supports `$dep.group` references from dependency capture groups */
     command: string;
+    /** Working directory for the process */
     cwd?: string;
+    /**
+     * Extra environment variables. Values support `$dep.group` references
+     * from dependency capture groups.
+     * @example { DB_PORT: '$db.port' }
+     */
     env?: Record<string, string>;
+    /** .env file path(s) to load, or `false` to disable */
     envFile?: string | string[] | false;
-    dependsOn?: string[];
+    /** Processes that must be ready before this one starts */
+    dependsOn?: NoInfer<K> | NoInfer<K>[];
+    /** Regex matched against stdout to signal readiness. Use `RegExp` to capture groups for `$dep.group` expansion */
     readyPattern?: string | RegExp;
+    /**
+     * Set to `false` for one-shot processes
+     * @default true
+     */
     persistent?: boolean;
+    /**
+     * Limit auto-restart attempts
+     * @default Infinity
+     */
     maxRestarts?: number;
+    /** Milliseconds to wait for readyPattern before failing */
     readyTimeout?: number;
+    /** Milliseconds to wait before starting the process */
     delay?: number;
+    /** Env var name (prefix with `!` to negate); process skipped if condition is falsy */
     condition?: string;
+    /**
+     * Signal for graceful stop
+     * @default 'SIGTERM'
+     */
     stopSignal?: 'SIGTERM' | 'SIGINT' | 'SIGHUP';
+    /** Hex color (e.g. `"#ff6600"`) or color name. Array for round-robin in script patterns */
     color?: string | string[];
+    /** Glob patterns — restart process when matching files change */
     watch?: string | string[];
+    /**
+     * When true, keyboard input is forwarded to the process
+     * @default false
+     */
     interactive?: boolean;
+    /** `true` = detect ANSI red output, string = regex pattern */
     errorMatcher?: boolean | string;
+    /**
+     * Print the command being run as the first line of output
+     * @default true
+     */
     showCommand?: boolean;
 }
 /** Config for npm: wildcard entries — command is derived from package.json scripts */
-export type NumuxScriptPattern = Omit<NumuxProcessConfig, 'command'> & {
+export type NumuxScriptPattern<K extends string = string> = Omit<NumuxProcessConfig<K>, 'command'> & {
     command?: never;
 };
 /** Raw config as authored — processes can be string shorthand, full objects, or wildcard patterns */
-export interface NumuxConfig {
+export interface NumuxConfig<K extends string = string> {
+    /** Global working directory, inherited by all processes */
     cwd?: string;
+    /** Global env vars, merged into each process (process-level overrides) */
     env?: Record<string, string>;
+    /** Global .env file(s), inherited by processes without their own envFile; `false` disables */
     envFile?: string | string[] | false;
+    /**
+     * Global showCommand flag, inherited by all processes
+     * @default true
+     */
     showCommand?: boolean;
-    processes: Record<string, NumuxProcessConfig | NumuxScriptPattern | string>;
+    processes: Record<K, NumuxProcessConfig<K> | NumuxScriptPattern<K> | string>;
+}
+/** Process config after validation — dependsOn is always normalized to an array */
+export interface ResolvedProcessConfig extends Omit<NumuxProcessConfig, 'dependsOn'> {
+    dependsOn?: string[];
 }
 /** Validated config with all shorthand expanded to full objects */
 export interface ResolvedNumuxConfig {
-    processes: Record<string, NumuxProcessConfig>;
+    processes: Record<string, ResolvedProcessConfig>;
 }
 export type ProcessStatus = 'pending' | 'starting' | 'ready' | 'running' | 'stopping' | 'stopped' | 'finished' | 'failed' | 'skipped';
 export interface ProcessState {
     name: string;
-    config: NumuxProcessConfig;
+    config: ResolvedProcessConfig;
     status: ProcessStatus;
     exitCode: number | null;
     restartCount: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numux",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Terminal multiplexer with dependency orchestration",
   "type": "module",
   "license": "MIT",