numux 1.25.0 → 2.0.0

package/README.md

@@ -1,6 +1,8 @@
 # numux
 
-Terminal multiplexer with dependency orchestration. Run multiple processes in a tabbed TUI with a dependency graph controlling startup order.
+Terminal multiplexer with dependency orchestration. Run multiple processes in a tabbed TUI with a dependency graph controlling startup order, readiness detection, and output capture between processes.
+
+Works with zero configuration — pass commands as arguments, run a script across monorepo workspaces with `-w`, or match multiple scripts with glob patterns like `'dev:*'`. For advanced setups, define a typed config with conditional processes, file watching with auto-restart, error detection, log persistence, and output capture — e.g. extract a port from one process's stdout and pass it to another process's command or env.
 
 Inspired by `sst dev` and `concurrently`
 
@@ -38,7 +40,6 @@ export default defineConfig({
     migrate: {
       command: 'bun run migrate',
       dependsOn: ['db'],
-      persistent: false,
     },
     api: {
       command: 'bun run dev:api',
@@ -51,7 +52,6 @@ export default defineConfig({
     confirm: {
       command: 'sh -c "printf \'Deploy to staging? [y/n] \' && read answer && echo $answer"',
       interactive: true,
-      persistent: false,
     },
   },
 })
@@ -164,8 +164,9 @@ Template properties (color, env, dependsOn, etc.) are inherited by all matched p
 | `-p, --prefix` | Prefixed output mode (no TUI, for CI/scripts) |
 | `--only <a,b,...>` | Only run these processes (+ their dependencies) |
 | `--exclude <a,b,...>` | Exclude these processes |
-| `--kill-others` | Kill all processes when any exits |
-| `--no-restart` | Disable auto-restart for crashed processes |
+| `--kill-others` | Kill all processes when any exits (regardless of exit code) |
+| `--kill-others-on-fail` | Kill all processes when any exits with a non-zero exit code |
+| `--max-restarts <n>` | Max auto-restarts for crashed processes |
 | `-s, --sort <mode>` | Tab display order: `config` (default), `alphabetical`, `topological` |
 | `--no-watch` | Disable file watching even if config has `watch` patterns |
 | `-t, --timestamps` | Add `[HH:MM:SS]` timestamps to prefixed output |
@@ -196,8 +197,7 @@ Top-level options apply to all processes (process-level settings override):
 | `env` | `Record<string, string>` | Environment variables merged into all processes (process `env` overrides per key) |
 | `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`) |
-| `persistent` | `boolean` | Set to `false` to make all processes one-shot by default (default: `true`) |
-| `maxRestarts` | `number` | Restart limit for all processes (default: `Infinity`) |
+| `maxRestarts` | `number` | Restart limit for all processes (default: `0`) |
 | `readyTimeout` | `number` | Ready timeout in ms for all processes |
 | `stopSignal` | `'SIGTERM' \| 'SIGINT' \| 'SIGHUP'` | Stop signal for all processes (default: `'SIGTERM'`) |
 | `errorMatcher` | `boolean \| string` | Error detection for all processes (`true` = ANSI red, string = regex) |
@@ -229,8 +229,7 @@ Each process accepts:
 | `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 |
-| `persistent` | `boolean` | `true` | `false` for one-shot commands (exit 0 = ready) |
-| `maxRestarts` | `number` | `Infinity` | Max auto-restart attempts before giving up |
+| `maxRestarts` | `number` | `0` | Max auto-restart attempts on non-zero exit (0 = no restarts) |
 | `delay` | `number` | — | Milliseconds to wait before starting the process |
 | `condition` | `string` | — | Env var name; process skipped if falsy. Prefix with `!` to negate |
 | `platform` | `string \| string[]` | — | OS(es) this process runs on (e.g. `'darwin'`, `'linux'`). Non-matching processes are removed; dependents still start |
@@ -298,7 +297,6 @@ export default defineConfig({
   processes: {
     seed: {
       command: 'bun run seed',
-      persistent: false,
       condition: 'SEED_DB',    // only runs when SEED_DB is set and truthy
     },
     storybook: {
@@ -316,11 +314,10 @@ Falsy values: unset, empty string, `"0"`, `"false"`, `"no"`, `"off"` (case-insen
 Each process starts as soon as its declared `dependsOn` dependencies are ready — it does not wait for unrelated processes. If a process fails, its dependents are skipped.
 
 A process becomes **ready** when:
-- **persistent + readyPattern** — the pattern matches in stdout
-- **persistent + no readyPattern** — immediately after spawn
-- **non-persistent** — exits with code 0
+- **Has `readyPattern`** — the pattern matches in stdout (long-running server)
+- **No `readyPattern`** — exits with code 0 (one-shot task)
 
-Persistent processes that crash are auto-restarted with exponential backoff (1s–30s). Backoff resets after 10s of uptime.
+Processes that crash (non-zero exit) can be auto-restarted by setting `maxRestarts` (default: `0`). Restarts use exponential backoff (1s–30s), which resets after 10s of uptime.
 
 ### Dependency output capture
 

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.25.0",
+    version: "2.0.0",
     description: "Terminal multiplexer with dependency orchestration",
     type: "module",
     license: "MIT",
@@ -192,13 +192,27 @@ var FLAGS = [
     type: "boolean",
     long: "--kill-others",
     key: "killOthers",
-    description: "Kill all processes when any exits"
+    description: "Kill all processes when any exits (regardless of exit code)"
   },
   {
     type: "boolean",
-    long: "--no-restart",
-    key: "noRestart",
-    description: "Disable auto-restart for crashed processes"
+    long: "--kill-others-on-fail",
+    key: "killOthersOnFail",
+    description: "Kill all processes when any exits with non-zero code"
+  },
+  {
+    type: "value",
+    long: "--max-restarts",
+    key: "maxRestarts",
+    description: "Max auto-restarts for crashed processes",
+    valueName: "<n>",
+    completionHint: "none",
+    parse(raw, flag) {
+      const n = Number(raw);
+      if (!Number.isInteger(n) || n < 0)
+        throw new Error(`${flag} must be a non-negative integer, got "${raw}"`);
+      return n;
+    }
   },
   {
     type: "boolean",
@@ -342,8 +356,8 @@ function parseArgs(argv) {
     exec: false,
     prefix: false,
     killOthers: false,
+    killOthersOnFail: false,
     timestamps: false,
-    noRestart: false,
     noWatch: false,
     autoColors: false,
     configPath: undefined,
@@ -390,12 +404,11 @@ function parseArgs(argv) {
 }
 function buildConfigFromArgs(commands, named, options) {
   const processes = {};
-  const maxRestarts = options?.noRestart ? 0 : undefined;
   const colors = options?.colors;
   let colorIndex = 0;
   for (const { name, command } of named) {
     const color = colors?.[colorIndex++ % colors.length];
-    processes[name] = { command, persistent: true, maxRestarts, ...color ? { color } : {} };
+    processes[name] = { command, ...color ? { color } : {} };
   }
   for (let i = 0;i < commands.length; i++) {
     const cmd = commands[i];
@@ -404,7 +417,7 @@ function buildConfigFromArgs(commands, named, options) {
       name = `${name}-${i}`;
     }
     const color = colors?.[colorIndex++ % colors.length];
-    processes[name] = { command: cmd, persistent: true, maxRestarts, ...color ? { color } : {} };
+    processes[name] = { command: cmd, ...color ? { color } : {} };
   }
   return { processes };
 }
@@ -1028,7 +1041,7 @@ function buildProcessHexColorMap(names, config) {
 }
 
 // src/config/validator.ts
-function validateConfig(raw, warnings) {
+function validateConfig(raw, _warnings) {
   if (!raw || typeof raw !== "object") {
     throw new Error("Config must be an object");
   }
@@ -1046,7 +1059,6 @@ function validateConfig(raw, warnings) {
   const globalEnvFile = validateEnvFile(config.envFile);
   const globalMaxRestarts = typeof config.maxRestarts === "number" && config.maxRestarts >= 0 ? config.maxRestarts : undefined;
   const globalReadyTimeout = typeof config.readyTimeout === "number" && config.readyTimeout > 0 ? config.readyTimeout : undefined;
-  const globalPersistent = typeof config.persistent === "boolean" ? config.persistent : undefined;
   const globalStopSignal = validateStopSignal(config.stopSignal);
   const globalErrorMatcher = validateErrorMatcher("(global)", config.errorMatcher);
   const globalWatch = validateStringOrStringArray(config.watch);
@@ -1063,6 +1075,7 @@ function validateConfig(raw, warnings) {
   const prefix = config.prefix === true ? true : undefined;
   const timestamps = config.timestamps === true ? true : undefined;
   const killOthers = config.killOthers === true ? true : undefined;
+  const killOthersOnFail = config.killOthersOnFail === true ? true : undefined;
   const noWatch = config.noWatch === true ? true : undefined;
   const logDir = typeof config.logDir === "string" && config.logDir.trim() ? config.logDir.trim() : undefined;
   const validated = {};
@@ -1107,7 +1120,6 @@ function validateConfig(raw, warnings) {
         }
       }
     }
-    const persistent = typeof p.persistent === "boolean" ? p.persistent : globalPersistent ?? true;
     const readyPattern = p.readyPattern instanceof RegExp ? p.readyPattern : typeof p.readyPattern === "string" ? p.readyPattern : undefined;
     if (typeof readyPattern === "string") {
       try {
@@ -1118,12 +1130,6 @@ function validateConfig(raw, warnings) {
         });
       }
     }
-    if (readyPattern && !persistent) {
-      warnings?.push({
-        process: name,
-        message: "readyPattern is ignored on non-persistent processes (readiness is determined by exit code)"
-      });
-    }
     if (p.env && typeof p.env === "object") {
       for (const [k, v] of Object.entries(p.env)) {
         if (typeof v !== "string") {
@@ -1148,8 +1154,7 @@ function validateConfig(raw, warnings) {
       envFile: processEnvFile ?? globalEnvFile,
       dependsOn: Array.isArray(p.dependsOn) ? p.dependsOn : undefined,
       readyPattern,
-      persistent,
-      maxRestarts: processMaxRestarts ?? globalMaxRestarts,
+      maxRestarts: processMaxRestarts ?? globalMaxRestarts ?? 0,
       readyTimeout: processReadyTimeout ?? globalReadyTimeout,
       delay: typeof p.delay === "number" && p.delay > 0 ? p.delay : undefined,
       condition: typeof p.condition === "string" && p.condition.trim() ? p.condition.trim() : undefined,
@@ -1167,6 +1172,7 @@ function validateConfig(raw, warnings) {
     ...prefix ? { prefix } : {},
     ...timestamps ? { timestamps } : {},
     ...killOthers ? { killOthers } : {},
+    ...killOthersOnFail ? { killOthersOnFail } : {},
     ...noWatch ? { noWatch } : {},
     ...logDir ? { logDir } : {},
     processes: validated
@@ -1284,8 +1290,7 @@ function resolveWorkspaceProcesses(script, cwd) {
     usedNames.add(name);
     processes[name] = {
       command: `${pm} run ${script}`,
-      cwd: dir,
-      persistent: true
+      cwd: dir
     };
   }
   if (Object.keys(processes).length === 0) {
@@ -1458,12 +1463,11 @@ function extractCaptures(match) {
 function createReadinessChecker(config) {
   const shouldCapture = config.readyPattern instanceof RegExp;
   const pattern = config.readyPattern ? config.readyPattern instanceof RegExp ? config.readyPattern : new RegExp(config.readyPattern) : null;
-  const persistent = config.persistent !== false;
   let outputBuffer = "";
   let _captures = null;
   return {
     feedOutput(data) {
-      if (!(persistent && pattern))
+      if (!pattern)
         return false;
       outputBuffer += data;
       if (outputBuffer.length > BUFFER_CAP2) {
@@ -1482,11 +1486,8 @@ function createReadinessChecker(config) {
     get captures() {
       return _captures;
     },
-    get isImmediatelyReady() {
-      return persistent && !pattern;
-    },
     get dependsOnExit() {
-      return !persistent;
+      return !pattern;
     }
   };
 }
@@ -1576,10 +1577,7 @@ class ProcessRunner {
 `;
       this.handler.onOutput(encoder.encode(msg));
     }
-    this.handler.onStatus(this.config.persistent !== false ? "running" : "starting");
-    if (this.readiness.isImmediatelyReady) {
-      this.markReady();
-    }
+    this.handler.onStatus(this.config.readyPattern ? "running" : "starting");
     this.startReadyTimeout(gen);
     this.proc.exited.then((code) => {
       if (this.generation !== gen)
@@ -1627,7 +1625,7 @@ class ProcessRunner {
   }
   startReadyTimeout(gen) {
     const timeout = this.config.readyTimeout;
-    if (!(timeout && this.config.readyPattern) || this.config.persistent === false)
+    if (!(timeout && this.config.readyPattern))
       return;
     this.readyTimer = setTimeout(() => {
       this.readyTimer = null;
@@ -1885,8 +1883,6 @@ class ProcessManager {
     if (this.stopping)
       return;
     const proc = this.config.processes[name];
-    if (proc.persistent === false)
-      return;
     if (exitCode === 0)
       return;
     if (exitCode === null)
@@ -1897,8 +1893,8 @@ class ProcessManager {
       this.restartAttempts.set(name, 0);
     }
     const attempt = this.restartAttempts.get(name) ?? 0;
-    const maxRestarts = proc.maxRestarts;
-    if (maxRestarts !== undefined && attempt >= maxRestarts) {
+    const maxRestarts = proc.maxRestarts ?? 0;
+    if (attempt >= maxRestarts) {
       log(`[${name}] Reached maxRestarts limit (${maxRestarts}), not restarting`);
       if (maxRestarts > 0) {
         const encoder2 = new TextEncoder;
@@ -1913,7 +1909,7 @@ class ProcessManager {
     this.restartAttempts.set(name, attempt + 1);
     const encoder = new TextEncoder;
     const msg = `\r
-\x1B[33m[numux] restarting in ${(delay / 1000).toFixed(0)}s (attempt ${attempt + 1}${maxRestarts !== undefined ? `/${maxRestarts}` : ""})...\x1B[0m\r
+\x1B[33m[numux] restarting in ${(delay / 1000).toFixed(0)}s (attempt ${attempt + 1}${Number.isFinite(maxRestarts) ? `/${maxRestarts}` : ""})...\x1B[0m\r
 `;
     this.emit({ type: "output", name, data: encoder.encode(msg) });
     const timer = setTimeout(() => {
@@ -1944,7 +1940,7 @@ class ProcessManager {
         const state = this.states.get(name);
         if (!state)
           return;
-        if (state.status === "pending" || state.status === "stopped" || state.status === "finished" || state.status === "stopping" || state.status === "skipped")
+        if (state.status === "pending" || state.status === "stopped" || state.status === "stopping" || state.status === "skipped")
           return;
         log(`[${name}] File changed: ${changedFile}, restarting`);
         const msg = `\r
@@ -2187,10 +2183,14 @@ function openLink(link) {
 }
 
 // src/ui/pane.ts
+var MAX_SCROLLBACK_LINES = 50000;
+var MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+
 class Pane {
   scrollBox;
   terminal;
   decoder = new TextDecoder;
+  bytesFed = 0;
   _onScroll = null;
   _onCopy = null;
   _onLinkClick = null;
@@ -2238,6 +2238,11 @@ class Pane {
     this.scrollBox.add(this.terminal);
   }
   feed(data) {
+    this.bytesFed += data.length;
+    if (this.terminal.lineCount > MAX_SCROLLBACK_LINES || this.bytesFed > MAX_BUFFER_BYTES) {
+      this.terminal.reset();
+      this.bytesFed = 0;
+    }
     const text = this.decoder.decode(data, { stream: true });
     this.terminal.feed(text);
   }
@@ -2315,6 +2320,7 @@ class Pane {
   }
   clear() {
     this.terminal.reset();
+    this.bytesFed = 0;
   }
   destroy() {
     this.terminal.destroy();
@@ -3185,6 +3191,7 @@ class PrefixDisplay {
   buffers = new Map;
   logWriter;
   killOthers;
+  killOthersOnFail;
   timestamps;
   stopping = false;
   startTime = 0;
@@ -3192,6 +3199,7 @@ class PrefixDisplay {
     this.manager = manager;
     this.logWriter = options.logWriter;
     this.killOthers = options.killOthers ?? false;
+    this.killOthersOnFail = options.killOthersOnFail ?? false;
     this.timestamps = options.timestamps ?? false;
     this.noColor = "NO_COLOR" in process.env;
     const names = manager.getProcessNames();
@@ -3233,7 +3241,8 @@ class PrefixDisplay {
       this.handleStatus(event.name, event.status);
     } else if (event.type === "exit") {
       this.flushBuffer(event.name);
-      if (this.killOthers) {
+      const exitCode = this.manager.getState(event.name)?.exitCode ?? null;
+      if (this.killOthers || this.killOthersOnFail && exitCode !== 0) {
         this.killAllAndExit(event.name);
       } else {
         this.checkAllDone();
@@ -3662,7 +3671,7 @@ async function main() {
           flags.push(`depends on: ${proc.dependsOn.join(", ")}`);
         if (proc.readyPattern)
           flags.push(`ready: /${proc.readyPattern}/`);
-        if (proc.persistent === false)
+        if (!proc.readyPattern)
           flags.push("one-shot");
         if (proc.delay)
           flags.push(`delay: ${proc.delay}ms`);
@@ -3739,7 +3748,6 @@ async function main() {
       config = validateConfig(expanded, warnings);
     } else {
       config = buildConfigFromArgs(parsed.commands, parsed.named, {
-        noRestart: parsed.noRestart,
         colors: parsed.colors
       });
     }
@@ -3753,8 +3761,6 @@ async function main() {
             suffix++;
           finalName = `${finalName}-${suffix}`;
         }
-        if (parsed.noRestart)
-          proc.maxRestarts = 0;
         config.processes[finalName] = proc;
       }
     }
@@ -3762,11 +3768,6 @@ async function main() {
     const raw = expandScriptPatterns(await loadConfig(parsed.configPath));
     config = validateConfig(raw, warnings);
     config = filterByPlatform(config);
-    if (parsed.noRestart) {
-      for (const proc of Object.values(config.processes)) {
-        proc.maxRestarts = 0;
-      }
-    }
   }
   if (parsed.sort) {
     config.sort = parsed.sort;
@@ -3776,6 +3777,11 @@ async function main() {
       proc.envFile = parsed.envFile;
     }
   }
+  if (parsed.maxRestarts !== undefined) {
+    for (const proc of Object.values(config.processes)) {
+      proc.maxRestarts = parsed.maxRestarts;
+    }
+  }
   if (parsed.noWatch || config.noWatch) {
     for (const proc of Object.values(config.processes)) {
       delete proc.watch;
@@ -3797,14 +3803,10 @@ async function main() {
   printWarnings(warnings);
   const usePrefix = parsed.prefix || config.prefix;
   if (usePrefix) {
-    if (!parsed.noRestart) {
-      for (const proc of Object.values(config.processes)) {
-        proc.maxRestarts ??= 0;
-      }
-    }
     const display = new PrefixDisplay(manager, config, {
       logWriter,
       killOthers: parsed.killOthers || config.killOthers,
+      killOthersOnFail: parsed.killOthersOnFail || config.killOthersOnFail,
       timestamps: parsed.timestamps || config.timestamps
     });
     await display.start();

package/dist/types.d.ts

@@ -17,13 +17,8 @@ export interface NumuxProcessConfig<K extends string = string> {
     /** 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
+     * Limit auto-restart attempts (only restarts on non-zero exit)
+     * @default 0
      */
     maxRestarts?: number;
     /** Milliseconds to wait for readyPattern before failing */
@@ -74,18 +69,12 @@ export interface NumuxConfig<K extends string = string> {
      */
     showCommand?: boolean;
     /**
-     * Global restart limit, inherited by all processes
-     * @default Infinity
+     * Global restart limit, inherited by all processes (only restarts on non-zero exit)
+     * @default 0
      */
     maxRestarts?: number;
     /** Global ready timeout (ms), inherited by all processes */
     readyTimeout?: number;
-    /**
-     * Set to `false` to make all processes non-persistent (one-shot) by default.
-     * Individual processes can still override with their own `persistent` value.
-     * @default true
-     */
-    persistent?: boolean;
     /**
      * Global stop signal, inherited by all processes
      * @default 'SIGTERM'
@@ -109,10 +98,15 @@ export interface NumuxConfig<K extends string = string> {
     /** Add timestamps to prefixed output lines (only applies when `prefix` is true) */
     timestamps?: boolean;
     /**
-     * Kill all processes when any one exits
+     * Kill all processes when any one exits (regardless of exit code)
      * @default false
      */
     killOthers?: boolean;
+    /**
+     * Kill all processes when any one exits with a non-zero exit code
+     * @default false
+     */
+    killOthersOnFail?: boolean;
     /**
      * Disable file watching even if processes have watch patterns
      * @default false
@@ -133,6 +127,7 @@ export interface ResolvedNumuxConfig {
     prefix?: boolean;
     timestamps?: boolean;
     killOthers?: boolean;
+    killOthersOnFail?: boolean;
     noWatch?: boolean;
     logDir?: string;
     processes: Record<string, ResolvedProcessConfig>;

package/package.json

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