numux 1.4.0 → 1.5.1

package/dist/config.d.ts

@@ -0,0 +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;

package/dist/config.js

@@ -0,0 +1,7 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};

package/dist/types.d.ts

@@ -0,0 +1,53 @@
+export interface NumuxProcessConfig {
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    envFile?: string | string[];
+    dependsOn?: string[];
+    readyPattern?: string;
+    persistent?: boolean;
+    maxRestarts?: number;
+    readyTimeout?: number;
+    delay?: number;
+    condition?: string;
+    stopSignal?: 'SIGTERM' | 'SIGINT' | 'SIGHUP';
+    color?: string | string[];
+    watch?: string | string[];
+    interactive?: boolean;
+}
+/** Config for npm: wildcard entries — command is derived from package.json scripts */
+export type NumuxScriptPattern = Omit<NumuxProcessConfig, 'command'> & {
+    command?: never;
+};
+/** Raw config as authored — processes can be string shorthand, full objects, or wildcard patterns */
+export interface NumuxConfig {
+    cwd?: string;
+    env?: Record<string, string>;
+    envFile?: string | string[];
+    processes: Record<string, NumuxProcessConfig | NumuxScriptPattern | string>;
+}
+/** Validated config with all shorthand expanded to full objects */
+export interface ResolvedNumuxConfig {
+    processes: Record<string, NumuxProcessConfig>;
+}
+export type ProcessStatus = 'pending' | 'starting' | 'ready' | 'running' | 'stopping' | 'stopped' | 'finished' | 'failed' | 'skipped';
+export interface ProcessState {
+    name: string;
+    config: NumuxProcessConfig;
+    status: ProcessStatus;
+    exitCode: number | null;
+    restartCount: number;
+}
+export type ProcessEvent = {
+    type: 'status';
+    name: string;
+    status: ProcessStatus;
+} | {
+    type: 'output';
+    name: string;
+    data: Uint8Array;
+} | {
+    type: 'exit';
+    name: string;
+    code: number | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "numux",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Terminal multiplexer with dependency orchestration",
   "type": "module",
   "license": "MIT",
@@ -18,29 +18,33 @@
     "orchestration"
   ],
   "engines": {
-    "bun": ">=1.0"
+    "bun": ">=1.0",
+    "node": ">=18"
   },
   "bin": {
-    "numux": "src/index.ts"
+    "numux": "dist/bin.js"
   },
   "exports": {
-    ".": "./src/config.ts"
+    ".": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    }
   },
   "scripts": {
-    "dev": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outfile dist/bin.js --target bun --packages external && bun build src/config.ts --outfile dist/config.js --packages external && bunx tsc src/config.ts src/types.ts --emitDeclarationOnly --declaration --outDir dist --target ESNext --module ESNext --moduleResolution bundler",
+    "prepublishOnly": "bun run build",
+    "dev": "cd example && bun run dev --debug",
     "test": "bun test",
     "typecheck": "bunx tsc --noEmit",
     "lint": "biome check .",
     "fix": "biome check . --fix --unsafe"
   },
   "files": [
-    "src/**/*.ts",
-    "!src/**/*.test.ts"
+    "dist/"
   ],
   "dependencies": {
     "@opentui/core": "^0.1.81",
-    "ghostty-opentui": "^1.4.3",
-    "yaml": "^2.8.2"
+    "ghostty-opentui": "^1.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/cli.ts

@@ -1,217 +0,0 @@
-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[]
-	colors?: 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 === '--config') {
-			result.configPath = consumeValue(arg)
-		} else if (arg === '-c' || arg === '--color') {
-			result.colors = consumeValue(arg)
-				.split(',')
-				.map(s => s.trim())
-				.filter(Boolean)
-		} 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; colors?: string[] }
-): ResolvedNumuxConfig {
-	const processes: ResolvedNumuxConfig['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 } : {}) }
-	}
-
-	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}`
-		}
-		const color = colors?.[colorIndex++ % colors.length]
-		processes[name] = { command: cmd, persistent: true, maxRestarts, ...(color ? { color } : {}) }
-	}
-
-	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

@@ -1,121 +0,0 @@
-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
-    --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 --color --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 --color)'{-c,--color}'[Comma-separated colors for processes]' \\
-    '--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 color -r -d 'Comma-separated colors for processes'
-complete -c numux -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'`
-}

package/src/config/expand-scripts.ts

@@ -1,96 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import type { NumuxConfig, NumuxProcessConfig } from '../types'
-
-type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun'
-
-const LOCKFILE_PM: [string, PackageManager][] = [
-	['bun.lockb', 'bun'],
-	['bun.lock', 'bun'],
-	['yarn.lock', 'yarn'],
-	['pnpm-lock.yaml', 'pnpm'],
-	['package-lock.json', 'npm']
-]
-
-export function detectPackageManager(pkgJson: Record<string, unknown>, cwd: string): PackageManager {
-	const field = pkgJson.packageManager
-	if (typeof field === 'string') {
-		const name = field.split('@')[0] as PackageManager
-		if (['npm', 'yarn', 'pnpm', 'bun'].includes(name)) return name
-	}
-	for (const [file, pm] of LOCKFILE_PM) {
-		if (existsSync(resolve(cwd, file))) return pm
-	}
-	return 'npm'
-}
-
-export function expandScriptPatterns(config: NumuxConfig, cwd?: string): NumuxConfig {
-	const entries = Object.entries(config.processes)
-	const hasWildcard = entries.some(([name]) => name.startsWith('npm:'))
-	if (!hasWildcard) return config
-
-	const dir = config.cwd ?? cwd ?? process.cwd()
-	const pkgPath = resolve(dir, 'package.json')
-
-	if (!existsSync(pkgPath)) {
-		throw new Error(`npm: patterns require a package.json (looked in ${dir})`)
-	}
-
-	const pkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8')) as Record<string, unknown>
-	const scripts = pkgJson.scripts as Record<string, string> | undefined
-	if (!scripts || typeof scripts !== 'object') {
-		throw new Error('package.json has no "scripts" field')
-	}
-
-	const scriptNames = Object.keys(scripts)
-	const pm = detectPackageManager(pkgJson, dir)
-
-	const expanded: Record<string, NumuxProcessConfig | string> = {}
-
-	for (const [name, value] of entries) {
-		if (!name.startsWith('npm:')) {
-			expanded[name] = value as NumuxProcessConfig | string
-			continue
-		}
-
-		const pattern = name.slice(4) // strip "npm:"
-		const template = (value ?? {}) as Partial<NumuxProcessConfig>
-
-		if (template.command) {
-			throw new Error(
-				`"${name}": wildcard processes cannot have a "command" field (commands come from package.json scripts)`
-			)
-		}
-
-		const glob = new Bun.Glob(pattern)
-		const matches = scriptNames.filter(s => glob.match(s))
-
-		if (matches.length === 0) {
-			throw new Error(
-				`"${name}": no scripts matched pattern "${pattern}". Available scripts: ${scriptNames.join(', ')}`
-			)
-		}
-
-		const colors = Array.isArray(template.color) ? template.color : undefined
-		const singleColor = typeof template.color === 'string' ? template.color : undefined
-
-		for (let i = 0; i < matches.length; i++) {
-			const scriptName = matches[i]
-
-			if (expanded[scriptName]) {
-				throw new Error(`"${name}": expanded script "${scriptName}" collides with an existing process name`)
-			}
-
-			const color = colors ? colors[i % colors.length] : singleColor
-
-			const { color: _color, ...rest } = template
-			expanded[scriptName] = {
-				...rest,
-				command: `${pm} run ${scriptName}`,
-				...(color ? { color } : {})
-			} as NumuxProcessConfig
-		}
-	}
-
-	return { ...config, processes: expanded }
-}

package/src/config/interpolate.ts

@@ -1,50 +0,0 @@
-/**
- * Environment variable interpolation for config values.
- * Supports ${VAR}, ${VAR:-default}, and ${VAR:?error} syntax.
- */
-
-// Matches ${VAR}, ${VAR:-default}, ${VAR:?error message}
-const VAR_RE = /\$\{([^}:]+)(?::([-?])([^}]*))?\}/g
-
-/** Recursively interpolate environment variables in all string values of a config object */
-export function interpolateConfig<T>(config: T): T {
-	return interpolateValue(config) as T
-}
-
-function interpolateValue(value: unknown): unknown {
-	if (typeof value === 'string') {
-		return interpolateString(value)
-	}
-	if (Array.isArray(value)) {
-		return value.map(interpolateValue)
-	}
-	if (value && typeof value === 'object') {
-		const result: Record<string, unknown> = {}
-		for (const [k, v] of Object.entries(value)) {
-			result[k] = interpolateValue(v)
-		}
-		return result
-	}
-	return value
-}
-
-function interpolateString(str: string): string {
-	return str.replace(VAR_RE, (_match, name: string, operator?: string, operand?: string) => {
-		const value = process.env[name]
-
-		if (value !== undefined && value !== '') {
-			return value
-		}
-
-		if (operator === '-') {
-			return operand ?? ''
-		}
-
-		if (operator === '?') {
-			throw new Error(operand || `Required variable ${name} is not set`)
-		}
-
-		// Unset with no operator → empty string
-		return ''
-	})
-}

package/src/config/loader.ts

@@ -1,76 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs'
-import { extname, resolve } from 'node:path'
-import { parse as parseYaml } from 'yaml'
-import type { NumuxConfig } from '../types'
-import { log } from '../utils/logger'
-import { interpolateConfig } from './interpolate'
-
-const CONFIG_FILES = [
-	'numux.config.ts',
-	'numux.config.js',
-	'numux.config.yaml',
-	'numux.config.yml',
-	'numux.config.json'
-] as const
-
-export async function loadConfig(configPath?: string, cwd?: string): Promise<NumuxConfig> {
-	if (configPath) {
-		return loadExplicitConfig(configPath)
-	}
-	return autoDetectConfig(cwd ?? process.cwd())
-}
-
-async function loadFile(path: string): Promise<NumuxConfig> {
-	const ext = extname(path)
-	let config: NumuxConfig
-	if (ext === '.yaml' || ext === '.yml') {
-		const content = readFileSync(path, 'utf-8')
-		try {
-			config = parseYaml(content) as NumuxConfig
-		} catch (err) {
-			throw new Error(`Failed to parse ${path}: ${err instanceof Error ? err.message : err}`, { cause: err })
-		}
-	} else {
-		try {
-			const mod = await import(path)
-			config = mod.default ?? mod
-		} catch (err) {
-			throw new Error(`Failed to load ${path}: ${err instanceof Error ? err.message : err}`, { cause: err })
-		}
-	}
-	return interpolateConfig(config)
-}
-
-async function loadExplicitConfig(configPath: string): Promise<NumuxConfig> {
-	const path = resolve(configPath)
-	if (!existsSync(path)) {
-		throw new Error(`Config file not found: ${path}`)
-	}
-	log(`Loading explicit config: ${path}`)
-	return loadFile(path)
-}
-
-async function autoDetectConfig(cwd: string): Promise<NumuxConfig> {
-	for (const file of CONFIG_FILES) {
-		const path = resolve(cwd, file)
-		if (existsSync(path)) {
-			log(`Found config file: ${path}`)
-			return loadFile(path)
-		}
-	}
-
-	// Try package.json "numux" key
-	const pkgPath = resolve(cwd, 'package.json')
-	if (existsSync(pkgPath)) {
-		const pkg = await import(pkgPath)
-		const config = (pkg.default ?? pkg).numux
-		if (config) {
-			log('Found config in package.json "numux" key')
-			return interpolateConfig(config as NumuxConfig)
-		}
-	}
-
-	throw new Error(
-		`No numux config found. Create one of: ${CONFIG_FILES.join(', ')} or add a "numux" key to package.json`
-	)
-}