numux 0.0.1 → 1.0.0

package/src/config/interpolate.ts

@@ -0,0 +1,50 @@
+/**
+ * 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

@@ -0,0 +1,76 @@
+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`
+	)
+}

package/src/config/resolver.ts

@@ -0,0 +1,67 @@
+import type { ResolvedNumuxConfig } from '../types'
+
+/**
+ * Kahn's topological sort — groups processes into tiers.
+ * Tier 0: no deps, Tier 1: deps all in tier 0, etc.
+ * Throws if a cycle is detected.
+ */
+export function resolveDependencyTiers(config: ResolvedNumuxConfig): string[][] {
+	const names = Object.keys(config.processes)
+	const inDegree = new Map<string, number>()
+	const dependents = new Map<string, string[]>()
+
+	for (const name of names) {
+		inDegree.set(name, 0)
+		dependents.set(name, [])
+	}
+
+	for (const name of names) {
+		const deps = config.processes[name].dependsOn ?? []
+		inDegree.set(name, deps.length)
+		for (const dep of deps) {
+			dependents.get(dep)!.push(name)
+		}
+	}
+
+	const tiers: string[][] = []
+	const remaining = new Set(names)
+
+	while (remaining.size > 0) {
+		const tier = [...remaining].filter(n => inDegree.get(n) === 0)
+
+		if (tier.length === 0) {
+			const cycle = findCycle(remaining, config)
+			throw new Error(`Dependency cycle detected: ${cycle.join(' → ')} → ${cycle[0]}`)
+		}
+
+		tiers.push(tier)
+
+		for (const name of tier) {
+			remaining.delete(name)
+			for (const dep of dependents.get(name)!) {
+				inDegree.set(dep, inDegree.get(dep)! - 1)
+			}
+		}
+	}
+
+	return tiers
+}
+
+/** Trace from any node in `remaining` to find one cycle. */
+function findCycle(remaining: Set<string>, config: ResolvedNumuxConfig): string[] {
+	const start = remaining.values().next().value!
+	const visited = new Set<string>()
+	const path: string[] = []
+
+	let current = start
+	while (!visited.has(current)) {
+		visited.add(current)
+		path.push(current)
+		const deps = (config.processes[current].dependsOn ?? []).filter(d => remaining.has(d))
+		current = deps[0]
+	}
+
+	// `current` is where the cycle starts — trim the path to just the cycle
+	const cycleStart = path.indexOf(current)
+	return path.slice(cycleStart)
+}

package/src/config/validator.ts

@@ -0,0 +1,140 @@
+import type { NumuxProcessConfig, ResolvedNumuxConfig } from '../types'
+import { HEX_COLOR_RE } from '../utils/color'
+
+export type ValidationWarning = { process: string; message: string }
+
+export function validateConfig(raw: unknown, warnings?: ValidationWarning[]): ResolvedNumuxConfig {
+	if (!raw || typeof raw !== 'object') {
+		throw new Error('Config must be an object')
+	}
+
+	const config = raw as Record<string, unknown>
+	if (!config.processes || typeof config.processes !== 'object') {
+		throw new Error('Config must have a "processes" object')
+	}
+
+	const processes = config.processes as Record<string, unknown>
+	const names = Object.keys(processes)
+
+	if (names.length === 0) {
+		throw new Error('Config must define at least one process')
+	}
+
+	// Extract global options
+	const globalCwd = typeof config.cwd === 'string' ? config.cwd : undefined
+	const globalEnvFile = validateStringOrStringArray(config.envFile)
+	let globalEnv: Record<string, string> | undefined
+	if (config.env && typeof config.env === 'object') {
+		for (const [k, v] of Object.entries(config.env as Record<string, unknown>)) {
+			if (typeof v !== 'string') {
+				throw new Error(`env.${k} must be a string, got ${typeof v}`)
+			}
+		}
+		globalEnv = config.env as Record<string, string>
+	}
+
+	const validated: Record<string, NumuxProcessConfig> = {}
+
+	for (const name of names) {
+		let proc = processes[name]
+
+		// String shorthand: "command" → { command: "command" }
+		if (typeof proc === 'string') {
+			proc = { command: proc }
+		}
+
+		if (!proc || typeof proc !== 'object') {
+			throw new Error(`Process "${name}" must be an object or a command string`)
+		}
+
+		const p = proc as Record<string, unknown>
+
+		if (typeof p.command !== 'string' || !p.command.trim()) {
+			throw new Error(`Process "${name}" must have a non-empty "command" string`)
+		}
+
+		// Validate dependsOn references
+		if (p.dependsOn !== undefined) {
+			if (!Array.isArray(p.dependsOn)) {
+				throw new Error(`Process "${name}".dependsOn must be an array`)
+			}
+			for (const dep of p.dependsOn) {
+				if (typeof dep !== 'string') {
+					throw new Error(`Process "${name}".dependsOn entries must be strings`)
+				}
+				if (!names.includes(dep)) {
+					throw new Error(`Process "${name}" depends on unknown process "${dep}"`)
+				}
+				if (dep === name) {
+					throw new Error(`Process "${name}" cannot depend on itself`)
+				}
+			}
+		}
+
+		// Validate color hex format
+		if (typeof p.color === 'string' && !HEX_COLOR_RE.test(p.color)) {
+			throw new Error(`Process "${name}".color must be a valid hex color (e.g. "#ff8800"), got "${p.color}"`)
+		}
+
+		const persistent = typeof p.persistent === 'boolean' ? p.persistent : true
+		const readyPattern = typeof p.readyPattern === 'string' ? p.readyPattern : undefined
+
+		// Warn when readyPattern is set on non-persistent processes (it's ignored at runtime)
+		if (readyPattern && !persistent) {
+			warnings?.push({
+				process: name,
+				message: 'readyPattern is ignored on non-persistent processes (readiness is determined by exit code)'
+			})
+		}
+
+		// Validate env values are strings
+		if (p.env && typeof p.env === 'object') {
+			for (const [k, v] of Object.entries(p.env as Record<string, unknown>)) {
+				if (typeof v !== 'string') {
+					throw new Error(`Process "${name}".env.${k} must be a string, got ${typeof v}`)
+				}
+			}
+		}
+
+		const processCwd = typeof p.cwd === 'string' ? p.cwd : undefined
+		const processEnv = p.env && typeof p.env === 'object' ? (p.env as Record<string, string>) : undefined
+		const processEnvFile = validateEnvFile(p.envFile)
+
+		validated[name] = {
+			command: p.command,
+			cwd: processCwd ?? globalCwd,
+			env: globalEnv || processEnv ? { ...globalEnv, ...processEnv } : undefined,
+			envFile: processEnvFile ?? globalEnvFile,
+			dependsOn: Array.isArray(p.dependsOn) ? (p.dependsOn as string[]) : undefined,
+			readyPattern,
+			persistent,
+			maxRestarts: typeof p.maxRestarts === 'number' && p.maxRestarts >= 0 ? p.maxRestarts : undefined,
+			readyTimeout: typeof p.readyTimeout === 'number' && p.readyTimeout > 0 ? p.readyTimeout : undefined,
+			delay: typeof p.delay === 'number' && p.delay > 0 ? p.delay : undefined,
+			condition: typeof p.condition === 'string' && p.condition.trim() ? p.condition.trim() : undefined,
+			stopSignal: validateStopSignal(p.stopSignal),
+			color: typeof p.color === 'string' ? p.color : undefined,
+			watch: validateStringOrStringArray(p.watch),
+			interactive: typeof p.interactive === 'boolean' ? p.interactive : false
+		}
+	}
+
+	return { processes: validated }
+}
+
+function validateStringOrStringArray(value: unknown): string | string[] | undefined {
+	if (typeof value === 'string') return value
+	if (Array.isArray(value) && value.every(v => typeof v === 'string')) return value as string[]
+	return undefined
+}
+
+const validateEnvFile = validateStringOrStringArray
+
+const VALID_STOP_SIGNALS = new Set(['SIGTERM', 'SIGINT', 'SIGHUP'])
+
+function validateStopSignal(value: unknown): 'SIGTERM' | 'SIGINT' | 'SIGHUP' | undefined {
+	if (typeof value === 'string' && VALID_STOP_SIGNALS.has(value)) {
+		return value as 'SIGTERM' | 'SIGINT' | 'SIGHUP'
+	}
+	return undefined
+}

package/src/config.ts

@@ -0,0 +1,8 @@
+import type { NumuxConfig } from './types'
+
+export type { NumuxConfig, NumuxProcessConfig } from './types'
+
+/** Type-safe helper for numux.config.ts files. */
+export function defineConfig(config: NumuxConfig): NumuxConfig {
+	return config
+}

package/src/index.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env bun
+import { existsSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { buildConfigFromArgs, filterConfig, parseArgs } from './cli'
+import { generateCompletions } from './completions'
+import { loadConfig } from './config/loader'
+import { resolveDependencyTiers } from './config/resolver'
+import { type ValidationWarning, validateConfig } from './config/validator'
+import { ProcessManager } from './process/manager'
+import type { ResolvedNumuxConfig } from './types'
+import { App } from './ui/app'
+import { PrefixDisplay } from './ui/prefix'
+import { loadEnvFiles } from './utils/env-file'
+import { LogWriter } from './utils/log-writer'
+import { enableDebugLog } from './utils/logger'
+import { setupShutdownHandlers } from './utils/shutdown'
+
+const HELP = `numux — terminal multiplexer with dependency orchestration
+
+Usage:
+  numux                          Run processes from config file
+  numux <cmd1> <cmd2> ...        Run ad-hoc commands in parallel
+  numux -n name1=cmd1 -n name2=cmd2  Named ad-hoc commands
+  numux init                     Create a starter config file
+  numux validate                 Validate config and show process graph
+  numux exec <name> [--] <cmd>   Run a command in a process's environment
+  numux completions <shell>      Generate shell completions (bash, zsh, fish)
+
+Options:
+  -n, --name <name=command>  Add a named process
+  -c, --config <path>        Config file path (default: auto-detect)
+  -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 timestamps to prefixed output lines
+  --log-dir <path>           Write per-process logs to directory
+  --debug                    Enable debug logging to .numux/debug.log
+  -h, --help                 Show this help
+  -v, --version              Show version
+
+Config files (auto-detected):
+  numux.config.ts, numux.config.js, numux.config.yaml,
+  numux.config.yml, numux.config.json,
+  or "numux" key in package.json`
+
+const INIT_TEMPLATE = `import { defineConfig } from 'numux'
+
+export default defineConfig({
+  // Global options (inherited by all processes):
+  // cwd: './packages/backend',
+  // env: { NODE_ENV: 'development' },
+  // envFile: '.env',
+
+  processes: {
+    // dev: 'npm run dev',
+    // api: {
+    //   command: 'npm run dev:api',
+    //   readyPattern: 'listening on port',
+    //   watch: 'src/**/*.ts',
+    // },
+    // web: {
+    //   command: 'npm run dev:web',
+    //   dependsOn: ['api'],
+    // },
+  },
+})
+`
+
+async function main() {
+	const parsed = parseArgs(process.argv)
+
+	if (parsed.help) {
+		console.info(HELP)
+		process.exit(0)
+	}
+
+	if (parsed.version) {
+		const pkg = await import('../package.json')
+		console.info(`numux v${(pkg.default ?? pkg).version}`)
+		process.exit(0)
+	}
+
+	if (parsed.init) {
+		const target = resolve('numux.config.ts')
+		if (existsSync(target)) {
+			console.error(`Already exists: ${target}`)
+			process.exit(1)
+		}
+		writeFileSync(target, INIT_TEMPLATE)
+		console.info(`Created ${target}`)
+		process.exit(0)
+	}
+
+	if (parsed.completions) {
+		console.info(generateCompletions(parsed.completions))
+		process.exit(0)
+	}
+
+	if (parsed.validate) {
+		const raw = await loadConfig(parsed.configPath)
+		const warnings: ValidationWarning[] = []
+		let config = validateConfig(raw, warnings)
+
+		if (parsed.only || parsed.exclude) {
+			config = filterConfig(config, parsed.only, parsed.exclude)
+		}
+
+		const tiers = resolveDependencyTiers(config)
+		const names = Object.keys(config.processes)
+		const filterNote = parsed.only || parsed.exclude ? ' (filtered)' : ''
+		console.info(`Config valid: ${names.length} process${names.length === 1 ? '' : 'es'}${filterNote}\n`)
+		for (let i = 0; i < tiers.length; i++) {
+			console.info(`Tier ${i}:`)
+			for (const name of tiers[i]) {
+				const proc = config.processes[name]
+				const flags: string[] = []
+				if (proc.dependsOn?.length) flags.push(`depends on: ${proc.dependsOn.join(', ')}`)
+				if (proc.readyPattern) flags.push(`ready: /${proc.readyPattern}/`)
+				if (proc.persistent === false) flags.push('one-shot')
+				if (proc.delay) flags.push(`delay: ${proc.delay}ms`)
+				if (proc.condition) flags.push(`if: ${proc.condition}`)
+				if (proc.watch) {
+					const patterns = Array.isArray(proc.watch) ? proc.watch : [proc.watch]
+					flags.push(`watch: ${patterns.join(', ')}`)
+				}
+				const suffix = flags.length > 0 ? `  (${flags.join(', ')})` : ''
+				console.info(`  ${name}: ${proc.command}${suffix}`)
+			}
+		}
+		printWarnings(warnings)
+		process.exit(0)
+	}
+
+	if (parsed.exec) {
+		const raw = await loadConfig(parsed.configPath)
+		const config = validateConfig(raw)
+		const proc = config.processes[parsed.execName!]
+		if (!proc) {
+			const names = Object.keys(config.processes)
+			throw new Error(`Unknown process "${parsed.execName}". Available: ${names.join(', ')}`)
+		}
+
+		const cwd = proc.cwd ? resolve(proc.cwd) : process.cwd()
+		const envFromFile = proc.envFile ? loadEnvFiles(proc.envFile, cwd) : {}
+		const env: Record<string, string> = {
+			...(process.env as Record<string, string>),
+			...envFromFile,
+			...proc.env
+		}
+
+		const child = Bun.spawn(['sh', '-c', parsed.execCommand!], {
+			cwd,
+			env,
+			stdout: 'inherit',
+			stdin: 'inherit',
+			stderr: 'inherit'
+		})
+		process.exit(await child.exited)
+	}
+
+	if (parsed.debug) {
+		enableDebugLog()
+	}
+
+	let config: ResolvedNumuxConfig
+	const warnings: ValidationWarning[] = []
+
+	if (parsed.commands.length > 0 || parsed.named.length > 0) {
+		config = buildConfigFromArgs(parsed.commands, parsed.named, { noRestart: parsed.noRestart })
+	} else {
+		const raw = await loadConfig(parsed.configPath)
+		config = validateConfig(raw, warnings)
+
+		if (parsed.noRestart) {
+			for (const proc of Object.values(config.processes)) {
+				proc.maxRestarts = 0
+			}
+		}
+	}
+
+	if (parsed.noWatch) {
+		for (const proc of Object.values(config.processes)) {
+			delete proc.watch
+		}
+	}
+
+	if (parsed.only || parsed.exclude) {
+		config = filterConfig(config, parsed.only, parsed.exclude)
+	}
+
+	const manager = new ProcessManager(config)
+
+	let logWriter: LogWriter | undefined
+	if (parsed.logDir) {
+		logWriter = new LogWriter(parsed.logDir)
+	}
+
+	printWarnings(warnings)
+
+	if (parsed.prefix) {
+		const display = new PrefixDisplay(manager, config, {
+			logWriter,
+			killOthers: parsed.killOthers,
+			timestamps: parsed.timestamps
+		})
+		await display.start()
+	} else {
+		if (logWriter) {
+			manager.on(logWriter.handleEvent)
+		}
+		const app = new App(manager, config)
+		setupShutdownHandlers(app, logWriter)
+		await app.start()
+	}
+}
+
+function printWarnings(warnings: ValidationWarning[]): void {
+	for (const w of warnings) {
+		console.warn(`Warning: process "${w.process}": ${w.message}`)
+	}
+}
+
+main().catch(err => {
+	console.error(err instanceof Error ? err.message : err)
+	process.exit(1)
+})