Merge pull request #93 from hyldmo/hyldmo/optional-process-config

Author: hyldmo

CLAUDE.md

@@ -43,6 +43,7 @@ src/
 - Non-interactive panes hide the terminal cursor
 - Set `errorMatcher: true` to detect ANSI red output, or a regex string to match custom patterns — shows a red indicator on the tab while the process keeps running
 - `readyPattern` accepts `string` (simple match) or `RegExp` (match + capture groups). RegExp captures are expanded into dependent `command` and `env` values via `$dep.group` syntax (e.g. `$odoo.url`)
+- `optional: true` makes a process visible as a tab but not auto-started (starts in `stopped` state). Alt+S starts it manually. Unlike `condition`, optional does not cascade to dependents
 - `platform` restricts a process to specific OS(es) (e.g. `'darwin'`, `'linux'`). Non-matching processes are removed; their dependents still start with the dependency stripped (unlike `condition` which cascades)
 
 ## Commits

README.md

@@ -256,6 +256,7 @@ Each process accepts:
 | `readyTimeout` | `number` | — | Milliseconds to wait for `readyPattern` before failing |
 | `maxRestarts` | `number` | `0` | Max auto-restart attempts on non-zero exit (0 = no restarts) |
 | `delay` | `number` | — | Milliseconds to wait before starting the process |
+| `optional` | `boolean` | `false` | Process is visible as a tab but not started automatically. Use Alt+S to start manually |
 | `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 |
 | `stopSignal` | `string` | `SIGTERM` | Signal for graceful stop (`SIGTERM`, `SIGINT`, or `SIGHUP`) |
@@ -360,6 +361,24 @@ export default defineConfig({
 
 Falsy values: unset, empty string, `"0"`, `"false"`, `"no"`, `"off"` (case-insensitive). If a conditional process is skipped, its dependents are also skipped.
 
+### Optional processes
+
+Use `optional` for tools you want visible in tabs but not auto-started (e.g. Prisma Studio, debug servers):
+
+```ts
+export default defineConfig({
+  processes: {
+    app: { command: 'bun run dev' },
+    studio: {
+      command: 'bunx prisma studio',
+      optional: true,  // shows as stopped tab, start with Alt+S
+    },
+  },
+})
+```
+
+Unlike `condition`, optional processes don't cascade — their dependents still start normally.
+
 ### Dependency orchestration
 
 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.

src/config/validator.test.ts

@@ -49,6 +49,24 @@ describe('validateConfig', () => {
 		expect(() => validateConfig({ processes: {} })).toThrow('at least one process')
 	})
 
+	test('passes through optional: true', () => {
+		const config = validateConfig({
+			processes: {
+				studio: { command: 'prisma studio', optional: true }
+			}
+		})
+		expect(config.processes.studio.optional).toBe(true)
+	})
+
+	test('ignores non-boolean optional values', () => {
+		const config = validateConfig({
+			processes: {
+				studio: { command: 'prisma studio', optional: 'yes' }
+			}
+		})
+		expect(config.processes.studio.optional).toBeUndefined()
+	})
+
 	test('throws on missing command', () => {
 		expect(() => validateConfig({ processes: { web: {} } })).toThrow('non-empty "command" string')
 	})

src/config/validator.ts

@@ -149,6 +149,7 @@ export function validateConfig(raw: unknown, _warnings?: ValidationWarning[]): R
 
 		validated[name] = {
 			command: p.command,
+			...(p.optional === true ? { optional: true } : {}),
 			cwd: processCwd ?? globalCwd,
 			env: globalEnv || processEnv ? { ...globalEnv, ...processEnv } : undefined,
 			envFile: processEnvFile ?? globalEnvFile,

src/process/manager.test.ts

@@ -741,6 +741,58 @@ describe('ProcessManager — delay', () => {
 	}, 5000)
 })
 
+describe('ProcessManager — optional', () => {
+	test('optional process starts as stopped', async () => {
+		const config: ResolvedNumuxConfig = {
+			processes: {
+				studio: { command: 'sleep 60', optional: true }
+			}
+		}
+		const mgr = new ProcessManager(config)
+		await mgr.startAll(80, 24)
+
+		expect(mgr.getState('studio')?.status).toBe('stopped')
+		await mgr.stopAll()
+	}, 5000)
+
+	test('optional process can be manually started', async () => {
+		const config: ResolvedNumuxConfig = {
+			processes: {
+				studio: { command: 'true', optional: true }
+			}
+		}
+		const mgr = new ProcessManager(config)
+		await mgr.startAll(80, 24)
+
+		expect(mgr.getState('studio')?.status).toBe('stopped')
+
+		mgr.start('studio', 80, 24)
+		await new Promise(r => setTimeout(r, 500))
+
+		const status = mgr.getState('studio')?.status
+		expect(status === 'finished' || status === 'ready').toBe(true)
+		await mgr.stopAll()
+	}, 5000)
+
+	test('optional process does not block dependents', async () => {
+		const config: ResolvedNumuxConfig = {
+			processes: {
+				studio: { command: 'sleep 60', optional: true },
+				child: { command: 'true', dependsOn: ['studio'] }
+			}
+		}
+		const mgr = new ProcessManager(config)
+		await mgr.startAll(80, 24)
+
+		expect(mgr.getState('studio')?.status).toBe('stopped')
+		// child should have started and finished — not blocked by optional dep
+		const childStatus = mgr.getState('child')?.status
+		expect(childStatus).not.toBe('pending')
+		expect(childStatus).not.toBe('skipped')
+		await mgr.stopAll()
+	}, 5000)
+})
+
 describe('ProcessManager — condition', () => {
 	test('skips process when condition env var is unset', async () => {
 		delete process.env.NUMUX_TEST_CONDITION

src/process/manager.ts

@@ -93,6 +93,14 @@ export class ProcessManager {
 			const proc = this.config.processes[name]
 			const resolve = readyResolvers.get(name)!
 
+			// Optional processes start as stopped — resolve immediately so dependents aren't blocked
+			if (proc.optional) {
+				this.updateStatus(name, 'stopped')
+				this.createRunner(name)
+				resolve()
+				return
+			}
+
 			// Wait for declared dependencies only
 			const deps = proc.dependsOn ?? []
 			if (deps.length > 0) {

src/types.ts

@@ -44,6 +44,8 @@ export interface NumuxProcessConfig<K extends string = string> {
 	 * @default false
 	 */
 	interactive?: boolean
+	/** Process is visible but not started automatically. Use Alt+S to start manually */
+	optional?: boolean
 	/** `true` = detect ANSI red output, string = regex pattern */
 	errorMatcher?: boolean | string
 	/**