numux 0.0.1 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyldmo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,293 @@
 # numux
+
+Terminal multiplexer with dependency orchestration. Run multiple processes in a tabbed TUI with a dependency graph controlling startup order.
+
+## Install
+
+Requires [Bun](https://bun.sh) >= 1.0.
+
+```sh
+bun install -g numux
+```
+
+## Usage
+
+### Quick start
+
+```sh
+numux init
+```
+
+This creates a starter `numux.config.ts` with commented-out examples. Edit it, then run `numux`.
+
+### Config file
+
+Create `numux.config.ts` (or `.js`, `.yaml`, `.yml`, `.json`, or a `"numux"` key in `package.json`):
+
+```ts
+import { defineConfig } from 'numux'
+
+export default defineConfig({
+  processes: {
+    db: {
+      command: 'docker compose up postgres',
+      readyPattern: 'ready to accept connections',
+    },
+    migrate: {
+      command: 'bun run migrate',
+      dependsOn: ['db'],
+      persistent: false,
+    },
+    api: {
+      command: 'bun run dev:api',
+      dependsOn: ['migrate'],
+      readyPattern: 'listening on port 3000',
+    },
+    // String shorthand for simple processes
+    web: 'bun run dev:web',
+    // Interactive process — keyboard input is forwarded
+    confirm: {
+      command: 'sh -c "printf \'Deploy to staging? [y/n] \' && read answer && echo $answer"',
+      interactive: true,
+      persistent: false,
+    },
+  },
+})
+```
+
+The `defineConfig()` helper is optional — it provides type checking for your config.
+
+Processes can be a string (shorthand for `{ command: "..." }`) or a full config object.
+
+Then run:
+
+```sh
+numux
+```
+
+### Subcommands
+
+```sh
+numux init                         # Create a starter numux.config.ts
+numux validate                     # Validate config and show process dependency graph
+numux exec <name> [--] <command>   # Run a command in a process's environment
+numux completions <shell>          # Generate shell completions (bash, zsh, fish)
+```
+
+`validate` respects `--only`/`--exclude` filters and shows processes grouped by dependency tiers.
+
+`exec` runs a one-off command using a process's configured `cwd`, `env`, and `envFile` — useful for migrations, scripts, or any command that needs the same environment:
+
+```sh
+numux exec api -- npx prisma migrate
+numux exec web npm run build
+```
+
+Set up completions for your shell:
+
+```sh
+# Bash (add to ~/.bashrc)
+eval "$(numux completions bash)"
+
+# Zsh (add to ~/.zshrc)
+eval "$(numux completions zsh)"
+
+# Fish
+numux completions fish | source
+# Or save permanently:
+numux completions fish > ~/.config/fish/completions/numux.fish
+```
+
+### Ad-hoc commands
+
+```sh
+# Unnamed (name derived from command)
+numux "bun dev:api" "bun dev:web"
+
+# Named
+numux -n api="bun dev:api" -n web="bun dev:web"
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-c, --config <path>` | Explicit config file path |
+| `-n, --name <name=cmd>` | Add a named process (repeatable) |
+| `-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 |
+| `--no-watch` | Disable file watching even if config has `watch` patterns |
+| `-t, --timestamps` | Add `[HH:MM:SS]` timestamps to prefixed output |
+| `--log-dir <path>` | Write per-process output to `<path>/<name>.log` |
+| `--debug` | Log to `.numux/debug.log` |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Prefix mode
+
+Use `--prefix` (`-p`) for CI or headless environments. Output is printed with colored `[name]` prefixes instead of the TUI:
+
+```sh
+numux --prefix
+```
+
+Auto-exits when all processes finish. Exit code 1 if any process failed.
+
+## Config reference
+
+### Global options
+
+Top-level options apply to all processes (process-level settings override):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `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) |
+
+```ts
+export default defineConfig({
+  cwd: './packages/backend',
+  env: { NODE_ENV: 'development' },
+  envFile: '.env',
+  processes: {
+    api: { command: 'node server.js' },           // inherits cwd, env, envFile
+    web: { command: 'vite', cwd: './packages/web' }, // overrides cwd
+  },
+})
+```
+
+### Process options
+
+Each process accepts:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `command` | `string` | *required* | Shell command to run |
+| `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`) |
+| `dependsOn` | `string[]` | — | Processes that must be ready first |
+| `readyPattern` | `string` | — | Regex matched against stdout to signal readiness |
+| `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 |
+| `delay` | `number` | — | Milliseconds to wait before starting the process |
+| `condition` | `string` | — | Env var name; process skipped if falsy. Prefix with `!` to negate |
+| `stopSignal` | `string` | `SIGTERM` | Signal for graceful stop (`SIGTERM`, `SIGINT`, or `SIGHUP`) |
+| `color` | `string` | auto | Hex color for tab icon and status bar (e.g. `"#ff6600"`) |
+| `watch` | `string \| string[]` | — | Glob patterns — restart process when matching files change |
+| `interactive` | `boolean` | `false` | When `true`, keyboard input is forwarded to the process |
+
+### File watching
+
+Use `watch` to automatically restart a process when source files change:
+
+```ts
+export default defineConfig({
+  processes: {
+    api: {
+      command: 'node server.js',
+      watch: 'src/**/*.ts',
+    },
+    styles: {
+      command: 'sass --watch src:dist',
+      watch: ['src/**/*.scss', 'src/**/*.css'],
+    },
+  },
+})
+```
+
+Patterns are matched relative to the process's `cwd` (or the project root). Changes in `node_modules` and `.git` are always ignored. Rapid file changes are debounced (300ms) to avoid restart storms.
+
+A watched process is only restarted if it's currently running, ready, or failed — manually stopped processes are not affected.
+
+### Environment variable interpolation
+
+Config values support `${VAR}` syntax for environment variable substitution:
+
+```yaml
+processes:
+  api:
+    command: node server.js --port ${PORT:-3000}
+    env:
+      DATABASE_URL: ${DATABASE_URL:?DATABASE_URL must be set}
+```
+
+| Syntax | Behavior |
+|--------|----------|
+| `${VAR}` | Value of `VAR`, or empty string if unset |
+| `${VAR:-default}` | Value of `VAR`, or `default` if unset |
+| `${VAR:?error}` | Value of `VAR`, or error with message if unset |
+
+Interpolation applies to all string values in the config (command, cwd, env, envFile, readyPattern, etc.).
+
+### Conditional processes
+
+Use `condition` to run a process only when an environment variable is set:
+
+```yaml
+processes:
+  seed:
+    command: bun run seed
+    persistent: false
+    condition: SEED_DB        # only runs when SEED_DB is set and truthy
+  storybook:
+    command: bun run storybook
+    condition: "!CI"           # skipped in CI environments
+```
+
+Falsy values: unset, empty string, `"0"`, `"false"`, `"no"`, `"off"` (case-insensitive). If a conditional process is skipped, its dependents are also skipped.
+
+### Dependency orchestration
+
+Processes are grouped into tiers by topological sort. Each tier starts after the previous tier is ready. 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
+
+Persistent processes that crash are auto-restarted with exponential backoff (1s–30s). Backoff resets after 10s of uptime.
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+C` | Quit (graceful shutdown) |
+| `Alt+R` | Restart active process |
+| `Alt+Shift+R` | Restart all processes |
+| `Alt+S` | Stop/start active process |
+| `Alt+L` | Clear active pane output |
+| `Alt+1`–`Alt+9` | Jump to tab |
+| `Alt+Left/Right` | Cycle tabs |
+| `Up/Down` | Scroll output 1 line (non-interactive panes) |
+| `PageUp/PageDown` | Scroll output by page (non-interactive panes) |
+| `Home/End` | Scroll to top/bottom (non-interactive panes) |
+| `Alt+PageUp/PageDown` | Scroll output up/down |
+| `Alt+Home/End` | Scroll to top/bottom |
+| `Alt+F` | Search in active pane output |
+
+While searching: type to filter, `Enter`/`Shift+Enter` to navigate matches, `Escape` to close.
+
+Panes are readonly by default — keyboard input is not forwarded to processes. Set `interactive: true` on processes that need stdin (REPLs, shells, etc.).
+
+## Tab icons
+
+| Icon | Status |
+|------|--------|
+| ○ | Pending |
+| ◐ | Starting |
+| ◉ | Running |
+| ● | Ready |
+| ◑ | Stopping |
+| ■ | Stopped |
+| ✖ | Failed |
+| ⊘ | Skipped |
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,49 @@
 {
   "name": "numux",
-  "version": "0.0.1",
-  "packageManager": "yarn@4.12.0",
+  "version": "1.1.0",
+  "description": "Terminal multiplexer with dependency orchestration",
+  "type": "module",
+  "license": "MIT",
+  "author": "hyldmo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hyldmo/numux.git"
+  },
+  "keywords": [
+    "terminal",
+    "multiplexer",
+    "process-manager",
+    "tui",
+    "dev-tools",
+    "orchestration"
+  ],
+  "engines": {
+    "bun": ">=1.0"
+  },
+  "bin": {
+    "numux": "src/index.ts"
+  },
+  "exports": {
+    ".": "./src/config.ts"
+  },
   "scripts": {
+    "dev": "bun run src/index.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "lint": "biome check .",
     "fix": "biome check . --fix --unsafe"
   },
   "files": [
-    "README.md"
-  ]
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "dependencies": {
+    "@opentui/core": "^0.1.81",
+    "ghostty-opentui": "^1.4.3",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/bun": "^1.3.9"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,207 @@
+import type { ResolvedNumuxConfig } from './types'
+
+export interface ParsedArgs {
+	help: boolean
+	version: boolean
+	debug: boolean
+	init: boolean
+	validate: boolean
+	exec: boolean
+	execName?: string
+	execCommand?: string
+	completions?: string
+	prefix: boolean
+	killOthers: boolean
+	timestamps: boolean
+	noRestart: boolean
+	noWatch: boolean
+	configPath?: string
+	logDir?: string
+	only?: string[]
+	exclude?: string[]
+	commands: string[]
+	named: Array<{ name: string; command: string }>
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+	const result: ParsedArgs = {
+		help: false,
+		version: false,
+		debug: false,
+		init: false,
+		validate: false,
+		exec: false,
+		prefix: false,
+		killOthers: false,
+		timestamps: false,
+		noRestart: false,
+		noWatch: false,
+		configPath: undefined,
+		commands: [],
+		named: []
+	}
+
+	const args = argv.slice(2) // skip bun + script
+	let i = 0
+
+	/** Consume the next argument as a value for the given flag, erroring if missing */
+	const consumeValue = (flag: string): string => {
+		const next = args[++i]
+		if (next === undefined) {
+			throw new Error(`Missing value for ${flag}`)
+		}
+		return next
+	}
+
+	while (i < args.length) {
+		const arg = args[i]
+
+		if (arg === '-h' || arg === '--help') {
+			result.help = true
+		} else if (arg === '-v' || arg === '--version') {
+			result.version = true
+		} else if (arg === '--debug') {
+			result.debug = true
+		} else if (arg === '-p' || arg === '--prefix') {
+			result.prefix = true
+		} else if (arg === '--kill-others') {
+			result.killOthers = true
+		} else if (arg === '-t' || arg === '--timestamps') {
+			result.timestamps = true
+		} else if (arg === '--no-restart') {
+			result.noRestart = true
+		} else if (arg === '--no-watch') {
+			result.noWatch = true
+		} else if (arg === '-c' || arg === '--config') {
+			result.configPath = consumeValue(arg)
+		} else if (arg === '--log-dir') {
+			result.logDir = consumeValue(arg)
+		} else if (arg === '--only') {
+			result.only = consumeValue(arg)
+				.split(',')
+				.map(s => s.trim())
+				.filter(Boolean)
+		} else if (arg === '--exclude') {
+			result.exclude = consumeValue(arg)
+				.split(',')
+				.map(s => s.trim())
+				.filter(Boolean)
+		} else if (arg === '-n' || arg === '--name') {
+			const value = consumeValue(arg)
+			const eq = value.indexOf('=')
+			if (eq < 1) {
+				throw new Error(`Invalid --name value: expected "name=command", got "${value}"`)
+			}
+			result.named.push({
+				name: value.slice(0, eq),
+				command: value.slice(eq + 1)
+			})
+		} else if (arg === 'init' && result.commands.length === 0) {
+			result.init = true
+		} else if (arg === 'validate' && result.commands.length === 0) {
+			result.validate = true
+		} else if (arg === 'exec' && result.commands.length === 0) {
+			result.exec = true
+			const name = args[++i]
+			if (!name) throw new Error('exec requires a process name')
+			result.execName = name
+			// Skip optional --
+			if (args[i + 1] === '--') i++
+			const rest = args.slice(i + 1)
+			if (rest.length === 0) throw new Error('exec requires a command to run')
+			result.execCommand = rest.join(' ')
+			break
+		} else if (arg === 'completions' && result.commands.length === 0) {
+			result.completions = consumeValue(arg)
+		} else if (!arg.startsWith('-')) {
+			result.commands.push(arg)
+		} else {
+			throw new Error(`Unknown option: ${arg}`)
+		}
+
+		i++
+	}
+
+	return result
+}
+
+export function buildConfigFromArgs(
+	commands: string[],
+	named: Array<{ name: string; command: string }>,
+	options?: { noRestart?: boolean }
+): ResolvedNumuxConfig {
+	const processes: ResolvedNumuxConfig['processes'] = {}
+	const maxRestarts = options?.noRestart ? 0 : undefined
+
+	for (const { name, command } of named) {
+		processes[name] = { command, persistent: true, maxRestarts }
+	}
+
+	for (let i = 0; i < commands.length; i++) {
+		const cmd = commands[i]
+		// Derive name from command: first word, deduplicated
+		let name = cmd.split(/\s+/)[0].split('/').pop()!
+		if (processes[name]) {
+			name = `${name}-${i}`
+		}
+		processes[name] = { command: cmd, persistent: true, maxRestarts }
+	}
+
+	return { processes }
+}
+
+/** Filter a config to include/exclude specific processes. --only also pulls in transitive dependencies. */
+export function filterConfig(config: ResolvedNumuxConfig, only?: string[], exclude?: string[]): ResolvedNumuxConfig {
+	const allNames = Object.keys(config.processes)
+
+	let selected: Set<string>
+
+	if (only && only.length > 0) {
+		// Validate names exist
+		for (const name of only) {
+			if (!allNames.includes(name)) {
+				throw new Error(`--only: unknown process "${name}"`)
+			}
+		}
+		// Collect transitive dependencies
+		selected = new Set<string>()
+		const queue = [...only]
+		while (queue.length > 0) {
+			const name = queue.pop()!
+			if (selected.has(name)) continue
+			selected.add(name)
+			const deps = config.processes[name].dependsOn ?? []
+			for (const dep of deps) {
+				if (!selected.has(dep)) queue.push(dep)
+			}
+		}
+	} else {
+		selected = new Set(allNames)
+	}
+
+	if (exclude && exclude.length > 0) {
+		for (const name of exclude) {
+			if (!allNames.includes(name)) {
+				throw new Error(`--exclude: unknown process "${name}"`)
+			}
+			selected.delete(name)
+		}
+	}
+
+	if (selected.size === 0) {
+		throw new Error('No processes left after filtering')
+	}
+
+	const processes: ResolvedNumuxConfig['processes'] = {}
+	for (const name of selected) {
+		const proc = { ...config.processes[name] }
+		// Remove deps that were filtered out
+		if (proc.dependsOn) {
+			proc.dependsOn = proc.dependsOn.filter(d => selected.has(d))
+			if (proc.dependsOn.length === 0) proc.dependsOn = undefined
+		}
+		processes[name] = proc
+	}
+
+	return { processes }
+}

package/src/completions.ts

@@ -0,0 +1,119 @@
+const SUPPORTED_SHELLS = ['bash', 'zsh', 'fish'] as const
+
+export function generateCompletions(shell: string): string {
+	switch (shell) {
+		case 'bash':
+			return bashCompletions()
+		case 'zsh':
+			return zshCompletions()
+		case 'fish':
+			return fishCompletions()
+		default:
+			throw new Error(`Unknown shell: "${shell}". Supported: ${SUPPORTED_SHELLS.join(', ')}`)
+	}
+}
+
+function bashCompletions(): string {
+	return `# numux bash completions
+# Add to ~/.bashrc: eval "$(numux completions bash)"
+_numux() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  case "$prev" in
+    -c|--config)
+      COMPREPLY=( $(compgen -f -- "$cur") )
+      return ;;
+    --log-dir)
+      COMPREPLY=( $(compgen -d -- "$cur") )
+      return ;;
+    --only|--exclude)
+      return ;;
+    -n|--name)
+      return ;;
+    completions)
+      COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+      return ;;
+  esac
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "-h --help -v --version -c --config -n --name -p --prefix --only --exclude --kill-others --no-restart --no-watch -t --timestamps --log-dir --debug" -- "$cur") )
+  else
+    local subcmds="init validate exec completions"
+    COMPREPLY=( $(compgen -W "$subcmds" -- "$cur") )
+  fi
+}
+complete -F _numux numux`
+}
+
+function zshCompletions(): string {
+	return `#compdef numux
+# numux zsh completions
+# Add to ~/.zshrc: eval "$(numux completions zsh)"
+_numux() {
+  local -a subcmds
+  subcmds=(
+    'init:Create a starter config file'
+    'validate:Validate config and show process graph'
+    'exec:Run a command in a process environment'
+    'completions:Generate shell completions'
+  )
+
+  _arguments -s \\
+    '(-h --help)'{-h,--help}'[Show help]' \\
+    '(-v --version)'{-v,--version}'[Show version]' \\
+    '(-c --config)'{-c,--config}'[Config file path]:file:_files' \\
+    '(-n --name)'{-n,--name}'[Named process (name=command)]:named process' \\
+    '(-p --prefix)'{-p,--prefix}'[Prefixed output mode]' \\
+    '--only[Only run these processes]:processes' \\
+    '--exclude[Exclude these processes]:processes' \\
+    '--kill-others[Kill all when any exits]' \\
+    '--no-restart[Disable auto-restart]' \\
+    '--no-watch[Disable file watching]' \\
+    '(-t --timestamps)'{-t,--timestamps}'[Add timestamps to output]' \\
+    '--log-dir[Log directory]:directory:_directories' \\
+    '--debug[Enable debug logging]' \\
+    '1:subcommand:->subcmd' \\
+    '*:command' \\
+    && return
+
+  case "$state" in
+    subcmd)
+      _describe 'subcommand' subcmds
+      ;;
+  esac
+}
+_numux`
+}
+
+function fishCompletions(): string {
+	return `# numux fish completions
+# Add to fish: numux completions fish | source
+# Or save to: ~/.config/fish/completions/numux.fish
+complete -c numux -f
+
+# Subcommands
+complete -c numux -n __fish_use_subcommand -a init -d 'Create a starter config file'
+complete -c numux -n __fish_use_subcommand -a validate -d 'Validate config and show process graph'
+complete -c numux -n __fish_use_subcommand -a exec -d 'Run a command in a process environment'
+complete -c numux -n __fish_use_subcommand -a completions -d 'Generate shell completions'
+
+# Completions subcommand
+complete -c numux -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
+
+# Options
+complete -c numux -s h -l help -d 'Show help'
+complete -c numux -s v -l version -d 'Show version'
+complete -c numux -s c -l config -rF -d 'Config file path'
+complete -c numux -s n -l name -r -d 'Named process (name=command)'
+complete -c numux -s p -l prefix -d 'Prefixed output mode'
+complete -c numux -l only -r -d 'Only run these processes'
+complete -c numux -l exclude -r -d 'Exclude these processes'
+complete -c numux -l kill-others -d 'Kill all when any exits'
+complete -c numux -l no-restart -d 'Disable auto-restart'
+complete -c numux -l no-watch -d 'Disable file watching'
+complete -c numux -s t -l timestamps -d 'Add timestamps to output'
+complete -c numux -l log-dir -ra '(__fish_complete_directories)' -d 'Log directory'
+complete -c numux -l debug -d 'Enable debug logging'`
+}