numux 0.0.1 → 1.0.0

package/src/ui/prefix.ts

@@ -0,0 +1,199 @@
+import type { ProcessManager } from '../process/manager'
+import type { ProcessEvent, ProcessStatus, ResolvedNumuxConfig } from '../types'
+import { ANSI_RESET, buildProcessColorMap, STATUS_ANSI, stripAnsi } from '../utils/color'
+import type { LogWriter } from '../utils/log-writer'
+
+const RESET = ANSI_RESET
+const DIM = '\x1b[90m'
+
+/**
+ * Concurrently-style prefixed output mode for CI and headless environments.
+ * Prints all process output interleaved with colored [name] prefixes.
+ */
+export interface PrefixDisplayOptions {
+	logWriter?: LogWriter
+	killOthers?: boolean
+	timestamps?: boolean
+}
+
+export class PrefixDisplay {
+	private manager: ProcessManager
+	private colors: Map<string, string>
+	private noColor: boolean
+	private decoders = new Map<string, TextDecoder>()
+	private buffers = new Map<string, string>()
+	private maxNameLen: number
+	private logWriter?: LogWriter
+	private killOthers: boolean
+	private timestamps: boolean
+	private stopping = false
+
+	constructor(manager: ProcessManager, config: ResolvedNumuxConfig, options: PrefixDisplayOptions = {}) {
+		this.manager = manager
+		this.logWriter = options.logWriter
+		this.killOthers = options.killOthers ?? false
+		this.timestamps = options.timestamps ?? false
+		this.noColor = 'NO_COLOR' in process.env
+		const names = manager.getProcessNames()
+		this.maxNameLen = Math.max(...names.map(n => n.length))
+		this.colors = buildProcessColorMap(names, config)
+		for (const name of names) {
+			this.decoders.set(name, new TextDecoder('utf-8', { fatal: false }))
+			this.buffers.set(name, '')
+		}
+	}
+
+	async start(): Promise<void> {
+		const handler = (event: ProcessEvent) => {
+			this.logWriter?.handleEvent(event)
+			this.handleEvent(event)
+		}
+		this.manager.on(handler)
+
+		process.on('SIGINT', () => this.shutdown())
+		process.on('SIGTERM', () => this.shutdown())
+		process.on('uncaughtException', err => {
+			process.stderr.write(`numux: unexpected error: ${err?.stack ?? err}\n`)
+			this.shutdown()
+		})
+		process.on('unhandledRejection', (reason: unknown) => {
+			const message = reason instanceof Error ? reason.message : String(reason)
+			process.stderr.write(`numux: unhandled rejection: ${message}\n`)
+			this.shutdown()
+		})
+
+		const cols = process.stdout.columns || 80
+		const rows = process.stdout.rows || 24
+		await this.manager.startAll(cols, rows)
+
+		// After all processes started, check if any are non-persistent
+		// If all non-persistent processes have exited, we're done
+		this.checkAllDone()
+	}
+
+	private handleEvent(event: ProcessEvent): void {
+		if (event.type === 'output') {
+			this.handleOutput(event.name, event.data)
+		} else if (event.type === 'status') {
+			this.handleStatus(event.name, event.status)
+		} else if (event.type === 'exit') {
+			// Flush remaining buffer
+			this.flushBuffer(event.name)
+			if (this.killOthers) {
+				this.killAllAndExit(event.name)
+			} else {
+				this.checkAllDone()
+			}
+		}
+	}
+
+	private handleOutput(name: string, data: Uint8Array): void {
+		const decoder = this.decoders.get(name) ?? new TextDecoder()
+		const text = decoder.decode(data, { stream: true })
+		const buffer = (this.buffers.get(name) ?? '') + text
+		const lines = buffer.split(/\r?\n/)
+
+		// Keep the last element (incomplete line) in the buffer
+		this.buffers.set(name, lines.pop() ?? '')
+
+		for (const line of lines) {
+			this.printLine(name, line)
+		}
+	}
+
+	private handleStatus(name: string, status: ProcessStatus): void {
+		if (status === 'ready' || status === 'failed' || status === 'stopped' || status === 'skipped') {
+			if (this.noColor) {
+				this.printLine(name, `→ ${status}`)
+			} else {
+				const ansi = STATUS_ANSI[status]
+				const statusText = ansi ? `${ansi}${status}${RESET}` : status
+				this.printLine(name, `${DIM}→ ${statusText}${DIM}${RESET}`)
+			}
+		}
+	}
+
+	private formatTimestamp(): string {
+		const now = new Date()
+		const h = String(now.getHours()).padStart(2, '0')
+		const m = String(now.getMinutes()).padStart(2, '0')
+		const s = String(now.getSeconds()).padStart(2, '0')
+		return `${h}:${m}:${s}`
+	}
+
+	private printLine(name: string, line: string): void {
+		const padded = name.padEnd(this.maxNameLen)
+		const ts = this.timestamps ? `${DIM}[${this.formatTimestamp()}]${RESET} ` : ''
+		const tsPlain = this.timestamps ? `[${this.formatTimestamp()}] ` : ''
+		if (this.noColor) {
+			process.stdout.write(`${tsPlain}[${padded}] ${stripAnsi(line)}\n`)
+		} else {
+			const color = this.colors.get(name) ?? ''
+			process.stdout.write(`${ts}${color}[${padded}]${RESET} ${line}\n`)
+		}
+	}
+
+	private flushBuffer(name: string): void {
+		const remaining = this.buffers.get(name) ?? ''
+		if (remaining.length > 0) {
+			this.printLine(name, remaining)
+			this.buffers.set(name, '')
+		}
+	}
+
+	private checkAllDone(): void {
+		if (this.stopping) return
+		const states = this.manager.getAllStates()
+		const allDone = states.every(s => s.status === 'stopped' || s.status === 'failed' || s.status === 'skipped')
+		if (allDone) {
+			this.printSummary()
+			this.logWriter?.close()
+			const anyFailed = states.some(s => s.status === 'failed')
+			process.exit(anyFailed ? 1 : 0)
+		}
+	}
+
+	private killAllAndExit(exitedName: string): void {
+		if (this.stopping) return
+		this.stopping = true
+		const state = this.manager.getState(exitedName)
+		const code = state?.exitCode ?? 1
+		this.manager.stopAll().then(() => {
+			for (const name of this.manager.getProcessNames()) {
+				this.flushBuffer(name)
+			}
+			this.printSummary()
+			this.logWriter?.close()
+			process.exit(code === 0 ? 0 : 1)
+		})
+	}
+
+	private printSummary(): void {
+		const states = this.manager.getAllStates()
+		const namePad = Math.max(...states.map(s => s.name.length))
+		process.stdout.write('\n')
+		for (const s of states) {
+			const name = s.name.padEnd(namePad)
+			const exitStr = s.exitCode !== null ? `exit ${s.exitCode}` : ''
+			if (this.noColor) {
+				process.stdout.write(`  ${name}  ${s.status}${exitStr ? `  (${exitStr})` : ''}\n`)
+			} else {
+				const ansi = STATUS_ANSI[s.status] ?? ''
+				const statusText = ansi ? `${ansi}${s.status}${RESET}` : s.status
+				process.stdout.write(`  ${name}  ${statusText}${exitStr ? `  ${DIM}(${exitStr})${RESET}` : ''}\n`)
+			}
+		}
+	}
+
+	async shutdown(): Promise<void> {
+		if (this.stopping) return
+		this.stopping = true
+		await this.manager.stopAll()
+		for (const name of this.manager.getProcessNames()) {
+			this.flushBuffer(name)
+		}
+		this.logWriter?.close()
+		const anyFailed = this.manager.getAllStates().some(s => s.status === 'failed')
+		process.exit(anyFailed ? 1 : 0)
+	}
+}

package/src/ui/status-bar.ts

@@ -0,0 +1,119 @@
+import {
+	type CliRenderer,
+	cyan,
+	fg,
+	green,
+	red,
+	reverse,
+	StyledText,
+	type TextChunk,
+	TextRenderable,
+	yellow
+} from '@opentui/core'
+import type { ProcessStatus } from '../types'
+
+const STATUS_STYLE: Partial<Record<ProcessStatus, (input: string) => TextChunk>> = {
+	ready: green,
+	running: cyan,
+	failed: red,
+	stopped: fg('#888'),
+	skipped: fg('#888')
+}
+
+function plain(text: string): TextChunk {
+	return { __isChunk: true, text } as TextChunk
+}
+
+export class StatusBar {
+	readonly renderable: TextRenderable
+	private statuses = new Map<string, ProcessStatus>()
+	private colors: Map<string, string>
+	private scrolledUp = false
+	private _searchMode = false
+	private _searchQuery = ''
+	private _searchMatchCount = 0
+	private _searchCurrentIndex = -1
+
+	constructor(renderer: CliRenderer, names: string[], colors?: Map<string, string>) {
+		this.colors = colors ?? new Map()
+		for (const name of names) {
+			this.statuses.set(name, 'pending')
+		}
+
+		this.renderable = new TextRenderable(renderer, {
+			id: 'status-bar',
+			width: '100%',
+			height: 1,
+			content: this.buildContent(),
+			bg: '#1a1a1a',
+			paddingX: 1
+		})
+	}
+
+	updateStatus(name: string, status: ProcessStatus): void {
+		this.statuses.set(name, status)
+		this.renderable.content = this.buildContent()
+	}
+
+	setScrollIndicator(scrolledUp: boolean): void {
+		if (this.scrolledUp === scrolledUp) return
+		this.scrolledUp = scrolledUp
+		this.renderable.content = this.buildContent()
+	}
+
+	setSearchMode(active: boolean, query = '', matchCount = 0, currentIndex = -1): void {
+		this._searchMode = active
+		this._searchQuery = query
+		this._searchMatchCount = matchCount
+		this._searchCurrentIndex = currentIndex
+		this.renderable.content = this.buildContent()
+	}
+
+	private buildContent(): StyledText {
+		if (this._searchMode) {
+			return this.buildSearchContent()
+		}
+		const chunks: TextChunk[] = []
+		let first = true
+		for (const [name, status] of this.statuses) {
+			if (!first) chunks.push(plain('  '))
+			first = false
+			const styleFn = STATUS_STYLE[status]
+			const hexColor = this.colors.get(name)
+			if (styleFn) {
+				chunks.push(styleFn(`${name}:${status}`))
+			} else if (hexColor) {
+				chunks.push(fg(hexColor)(`${name}:${status}`))
+			} else {
+				chunks.push(plain(`${name}:${status}`))
+			}
+		}
+		if (this.scrolledUp) {
+			chunks.push(plain('  '))
+			chunks.push(yellow('[scrolled]'))
+		}
+		chunks.push(
+			plain('  Alt+\u2190\u2192/1-9: tabs  Alt+PgUp/Dn: scroll  Alt+R: restart  Alt+S: stop/start  Ctrl+C: quit')
+		)
+		return new StyledText(chunks)
+	}
+
+	private buildSearchContent(): StyledText {
+		const chunks: TextChunk[] = []
+		chunks.push(yellow('/'))
+		if (this._searchQuery) chunks.push(plain(this._searchQuery))
+		chunks.push(reverse(' '))
+		if (this._searchMatchCount === 0 && this._searchQuery) {
+			chunks.push(plain('  '))
+			chunks.push(red('no matches'))
+			chunks.push(plain('  Esc: close'))
+		} else if (this._searchMatchCount > 0) {
+			chunks.push(plain('  '))
+			chunks.push(cyan(`${this._searchCurrentIndex + 1}/${this._searchMatchCount}`))
+			chunks.push(plain('  Enter/Shift+Enter: next/prev  Esc: close'))
+		} else {
+			chunks.push(plain('  Enter: next  Esc: close'))
+		}
+		return new StyledText(chunks)
+	}
+}

package/src/ui/tabs.ts

@@ -0,0 +1,90 @@
+import { type CliRenderer, SelectRenderable, SelectRenderableEvents } from '@opentui/core'
+import type { ProcessStatus } from '../types'
+
+const STATUS_ICONS: Record<ProcessStatus, string> = {
+	pending: '○',
+	starting: '◐',
+	running: '◉',
+	ready: '●',
+	stopping: '◑',
+	stopped: '■',
+	failed: '✖',
+	skipped: '⊘'
+}
+
+export class TabBar {
+	readonly renderable: SelectRenderable
+	private names: string[]
+	private statuses: Map<string, ProcessStatus>
+	private descriptions: Map<string, string>
+
+	constructor(renderer: CliRenderer, names: string[]) {
+		this.names = names
+		this.statuses = new Map(names.map(n => [n, 'pending' as ProcessStatus]))
+		this.descriptions = new Map(names.map(n => [n, 'pending']))
+
+		this.renderable = new SelectRenderable(renderer, {
+			id: 'tab-bar',
+			width: '100%',
+			height: '100%',
+			options: names.map(n => ({
+				name: this.formatTab(n, 'pending'),
+				description: 'pending'
+			})),
+			selectedBackgroundColor: '#334455',
+			selectedTextColor: '#fff',
+			textColor: '#888',
+			showDescription: true,
+			wrapSelection: true
+		})
+	}
+
+	onSelect(handler: (index: number, name: string) => void): void {
+		this.renderable.on(SelectRenderableEvents.ITEM_SELECTED, (index: number) => {
+			handler(index, this.names[index])
+		})
+	}
+
+	onSelectionChanged(handler: (index: number, name: string) => void): void {
+		this.renderable.on(SelectRenderableEvents.SELECTION_CHANGED, (index: number) => {
+			handler(index, this.names[index])
+		})
+	}
+
+	updateStatus(name: string, status: ProcessStatus, exitCode?: number | null, restartCount?: number): void {
+		this.statuses.set(name, status)
+		this.descriptions.set(name, this.formatDescription(status, exitCode, restartCount))
+		this.renderable.options = this.names.map(n => ({
+			name: this.formatTab(n, this.statuses.get(n)!),
+			description: this.descriptions.get(n)!
+		}))
+	}
+
+	private formatDescription(status: ProcessStatus, exitCode?: number | null, restartCount?: number): string {
+		let desc: string = status
+		if ((status === 'failed' || status === 'stopped') && exitCode != null && exitCode !== 0) {
+			desc = `exit ${exitCode}`
+		}
+		if (restartCount && restartCount > 0) {
+			desc += ` ×${restartCount}`
+		}
+		return desc
+	}
+
+	private formatTab(name: string, status: ProcessStatus): string {
+		const icon = STATUS_ICONS[status]
+		return `${icon} ${name}`
+	}
+
+	getSelectedIndex(): number {
+		return this.renderable.getSelectedIndex()
+	}
+
+	setSelectedIndex(index: number): void {
+		this.renderable.setSelectedIndex(index)
+	}
+
+	focus(): void {
+		this.renderable.focus()
+	}
+}

package/src/utils/color.ts

@@ -0,0 +1,85 @@
+/**
+ * Convert a hex color string (e.g. "#ff8800") to an ANSI true-color escape sequence.
+ * Returns an empty string if the hex is malformed.
+ */
+export function hexToAnsi(hex: string): string {
+	const h = hex.replace('#', '')
+	const r = Number.parseInt(h.slice(0, 2), 16)
+	const g = Number.parseInt(h.slice(2, 4), 16)
+	const b = Number.parseInt(h.slice(4, 6), 16)
+	if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return ''
+	return `\x1b[38;2;${r};${g};${b}m`
+}
+
+/** Regex matching a valid 6-digit hex color (with or without leading #) */
+export const HEX_COLOR_RE = /^#?[0-9a-fA-F]{6}$/
+
+import type { ProcessStatus, ResolvedNumuxConfig } from '../types'
+
+/** ANSI color codes for process statuses */
+export const STATUS_ANSI: Partial<Record<ProcessStatus, string>> = {
+	ready: '\x1b[32m',
+	running: '\x1b[36m',
+	failed: '\x1b[31m',
+	stopped: '\x1b[90m',
+	skipped: '\x1b[90m'
+}
+
+export const ANSI_RESET = '\x1b[0m'
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape stripping requires matching control chars
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()#][0-9A-Za-z]|\x1b[A-Za-z><=]/g
+
+/** Strip ANSI escape sequences from text */
+export function stripAnsi(str: string): string {
+	return str.replace(ANSI_RE, '')
+}
+
+/** Default palette as ANSI codes (for prefix mode stdout output) */
+const DEFAULT_ANSI_COLORS = [
+	'\x1b[36m',
+	'\x1b[33m',
+	'\x1b[35m',
+	'\x1b[34m',
+	'\x1b[32m',
+	'\x1b[91m',
+	'\x1b[93m',
+	'\x1b[95m'
+]
+
+/** Default palette as hex colors (for styled text rendering) */
+const DEFAULT_HEX_COLORS = ['#00cccc', '#cccc00', '#cc00cc', '#0000cc', '#00cc00', '#ff5555', '#ffff55', '#ff55ff']
+
+/** Build a map of process names to ANSI color codes, using explicit config colors or a default palette. */
+export function buildProcessColorMap(names: string[], config: ResolvedNumuxConfig): Map<string, string> {
+	const map = new Map<string, string>()
+	if ('NO_COLOR' in process.env) return map
+	let paletteIndex = 0
+	for (const name of names) {
+		const explicit = config.processes[name]?.color
+		if (explicit) {
+			map.set(name, hexToAnsi(explicit))
+		} else {
+			map.set(name, DEFAULT_ANSI_COLORS[paletteIndex % DEFAULT_ANSI_COLORS.length])
+			paletteIndex++
+		}
+	}
+	return map
+}
+
+/** Build a map of process names to hex color strings (for StyledText rendering). */
+export function buildProcessHexColorMap(names: string[], config: ResolvedNumuxConfig): Map<string, string> {
+	const map = new Map<string, string>()
+	if ('NO_COLOR' in process.env) return map
+	let paletteIndex = 0
+	for (const name of names) {
+		const explicit = config.processes[name]?.color
+		if (explicit) {
+			map.set(name, explicit.startsWith('#') ? explicit : `#${explicit}`)
+		} else {
+			map.set(name, DEFAULT_HEX_COLORS[paletteIndex % DEFAULT_HEX_COLORS.length])
+			paletteIndex++
+		}
+	}
+	return map
+}

package/src/utils/env-file.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+/** Parse a .env file into key-value pairs. Supports comments, quotes, and empty lines. */
+export function parseEnvFile(content: string): Record<string, string> {
+	const vars: Record<string, string> = {}
+
+	for (const line of content.split(/\r?\n/)) {
+		const trimmed = line.trim()
+		if (!trimmed || trimmed.startsWith('#')) continue
+
+		const eqIndex = trimmed.indexOf('=')
+		if (eqIndex < 1) continue
+
+		const key = trimmed.slice(0, eqIndex).trim()
+		let value = trimmed.slice(eqIndex + 1).trim()
+
+		// Strip surrounding quotes (no inline comment stripping for quoted values)
+		if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+			value = value.slice(1, -1)
+		} else {
+			// Strip inline comments for unquoted values
+			const commentIndex = value.indexOf(' #')
+			if (commentIndex !== -1) {
+				value = value.slice(0, commentIndex).trimEnd()
+			}
+		}
+
+		vars[key] = value
+	}
+
+	return vars
+}
+
+/** Load one or more .env files and merge them into a single Record. Later files override earlier ones. */
+export function loadEnvFiles(envFile: string | string[], cwd: string): Record<string, string> {
+	const files = Array.isArray(envFile) ? envFile : [envFile]
+	const merged: Record<string, string> = {}
+
+	for (const file of files) {
+		const path = resolve(cwd, file)
+		let content: string
+		try {
+			content = readFileSync(path, 'utf-8')
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') {
+				throw new Error(`envFile not found: ${path}`, { cause: err })
+			}
+			throw new Error(`Failed to read envFile "${path}": ${err instanceof Error ? err.message : err}`, {
+				cause: err
+			})
+		}
+		Object.assign(merged, parseEnvFile(content))
+	}
+
+	return merged
+}

package/src/utils/log-writer.ts

@@ -0,0 +1,48 @@
+import { closeSync, mkdirSync, openSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ProcessEvent } from '../types'
+import { stripAnsi } from './color'
+
+/** Writes process output to per-process log files in the given directory. */
+export class LogWriter {
+	private dir: string
+	private files = new Map<string, number>()
+	private decoder = new TextDecoder()
+	private encoder = new TextEncoder()
+
+	constructor(dir: string) {
+		this.dir = dir
+		mkdirSync(dir, { recursive: true })
+	}
+
+	private errored = false
+
+	/** Event listener — pass to ProcessManager.on() */
+	handleEvent = (event: ProcessEvent): void => {
+		if (event.type !== 'output' || this.errored) return
+
+		try {
+			let fd = this.files.get(event.name)
+			if (fd === undefined) {
+				const path = join(this.dir, `${event.name}.log`)
+				fd = openSync(path, 'w')
+				this.files.set(event.name, fd)
+			}
+
+			const text = this.decoder.decode(event.data, { stream: true })
+			const clean = stripAnsi(text)
+			writeSync(fd, this.encoder.encode(clean))
+		} catch {
+			// Disk full, permissions, deleted dir — warn once and stop writing
+			this.errored = true
+			process.stderr.write(`numux: log writing failed for ${this.dir}, disabling log output\n`)
+		}
+	}
+
+	close(): void {
+		for (const fd of this.files.values()) {
+			closeSync(fd)
+		}
+		this.files.clear()
+	}
+}

package/src/utils/logger.ts

@@ -0,0 +1,32 @@
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+let enabled = false
+let logFile = ''
+
+export function enableDebugLog(dir?: string): void {
+	const logDir = dir ?? resolve(process.cwd(), '.numux')
+	logFile = resolve(logDir, 'debug.log')
+	if (!existsSync(logDir)) {
+		mkdirSync(logDir, { recursive: true })
+	}
+	enabled = true
+}
+
+export function log(message: string, ...args: unknown[]): void {
+	if (!enabled) return
+	try {
+		const timestamp = new Date().toISOString()
+		const formatted = args.length > 0 ? `${message} ${args.map(a => JSON.stringify(a)).join(' ')}` : message
+		appendFileSync(logFile, `[${timestamp}] ${formatted}\n`)
+	} catch {
+		// Disk errors in debug logging should not crash the app
+		enabled = false
+	}
+}
+
+/** Reset logger state (for testing only) */
+export function _resetLogger(): void {
+	enabled = false
+	logFile = ''
+}

package/src/utils/shutdown.ts

@@ -0,0 +1,39 @@
+import type { App } from '../ui/app'
+import type { LogWriter } from './log-writer'
+import { log } from './logger'
+
+export function setupShutdownHandlers(app: App, logWriter?: LogWriter): void {
+	let shuttingDown = false
+
+	const shutdown = () => {
+		if (shuttingDown) {
+			process.exit(1)
+		}
+		shuttingDown = true
+		app.shutdown().finally(() => {
+			logWriter?.close()
+			process.exit(app.hasFailures() ? 1 : 0)
+		})
+	}
+
+	process.on('SIGINT', shutdown)
+	process.on('SIGTERM', shutdown)
+	process.on('uncaughtException', err => {
+		log('Uncaught exception:', err?.message ?? err)
+		process.stderr.write(`numux: unexpected error: ${err?.stack ?? err}\n`)
+		app.shutdown().finally(() => {
+			logWriter?.close()
+			process.exit(1)
+		})
+	})
+
+	process.on('unhandledRejection', (reason: unknown) => {
+		const message = reason instanceof Error ? reason.message : String(reason)
+		log('Unhandled rejection:', message)
+		process.stderr.write(`numux: unhandled rejection: ${message}\n`)
+		app.shutdown().finally(() => {
+			logWriter?.close()
+			process.exit(1)
+		})
+	})
+}