@bhooai/nexus-cli 2.0.2 → 2.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/nexus-cli",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "BhooAI Nexus v2 CLI — init, dev, build, test, scaffolding, plugins, queue, db.",
   "license": "MIT",
   "type": "module",

package/src/commands/dev.ts

@@ -1,26 +1,18 @@
 /**
- * nexus dev — start the dev services:
- *   every apps/backend-* (tsx watch), frontend(s) (vite), admin (vite), ai-server (python).
+ * nexus dev — start the dev services.
  *
- * Sub-process supervision with log prefixing, auto-restart, and clean shutdown
- * on Ctrl+C.
+ * In an interactive TTY this opens the full-screen Nexus Console control panel
+ * (services start/stop/restart + a palette that runs every other CLI command).
+ * When stdout isn't a TTY (CI, piped) it falls back to plain prefixed log
+ * streaming. Pass `--no-panel` to force plain mode in a TTY.
  */
-import { spawn, type ChildProcess } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
-import { resolve, join } from 'node:path';
+import { join } from 'node:path';
 import type { CommandContext } from '../dispatcher.js';
 import { ensurePort } from '../ports.js';
-
-interface Service {
-  name: string;
-  cmd: string;
-  args: string[];
-  cwd: string;
-  color: string;
-  enabled: boolean;
-  port: number;
-}
+import { ServiceManager, type ServiceSpec } from '../devServiceManager.js';
+import { startDevPanel } from '../devPanel.js';
 
 const COLORS = ['\x1b[36m', '\x1b[33m', '\x1b[35m', '\x1b[32m', '\x1b[34m', '\x1b[31m', '\x1b[37m', '\x1b[90m'];
 const RESET = '\x1b[0m';
@@ -28,8 +20,59 @@ const RESET = '\x1b[0m';
 export async function run(ctx: CommandContext): Promise<void> {
   const only = (ctx.args.flags.only as string)?.split(',').map((s) => s.trim()) ?? null;
   const projectRoot = process.cwd();
+  const noPanel = !!ctx.args.flags['no-panel'];
+  const isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  const specs = await discoverServices(projectRoot, only);
+  if (specs.length === 0) {
+    console.log('No services to start. Check that apps/* exist.');
+    return;
+  }
+
+  const manager = new ServiceManager(specs);
+
+  if (isTty && !noPanel) {
+    // Full-screen Nexus Console.
+    console.log(`nexus dev — ${specs.length} service(s). Opening console...\n`);
+    await startDevPanel({ services: manager, onQuit: () => manager.killAll() });
+    return;
+  }
+
+  // Plain mode (piped / CI / --no-panel): start all + stream prefixed logs.
+  console.log(`nexus dev — starting ${specs.length} service(s)\n`);
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    manager.killAll();
+    setTimeout(() => process.exit(0), 500);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Wire a plain log printer (prints only NEW lines per service).
+  const colors = new Map<string, string>();
+  specs.forEach((s, i) => colors.set(s.name, COLORS[i % COLORS.length]!));
+  const printed = new Map<string, number>();
+  manager.onLog = (name) => {
+    const svc = manager.get(name);
+    if (!svc) return;
+    const prefix = `${colors.get(name) ?? ''}[${name}]${RESET}`;
+    const from = printed.get(name) ?? 0;
+    const newLines = svc.logBuffer.slice(from);
+    printed.set(name, svc.logBuffer.length);
+    for (const line of newLines) {
+      process.stdout.write(`${prefix} ${line}\n`);
+    }
+  };
+
+  for (const spec of specs) manager.start(spec.name);
 
-  // Discover backends, frontends, admin, ai-server under apps/
+  // Keep the process alive.
+  await new Promise(() => {});
+}
+
+async function discoverServices(projectRoot: string, only: string[] | null): Promise<ServiceSpec[]> {
   const appsDir = join(projectRoot, 'apps');
   const appEntries = existsSync(appsDir) ? await readdir(appsDir, { withFileTypes: true }) : [];
   const backends  = appEntries.filter((e) => e.isDirectory() && e.name.startsWith('backend')).map((e) => e.name);
@@ -37,127 +80,33 @@ export async function run(ctx: CommandContext): Promise<void> {
   const admins    = appEntries.filter((e) => e.isDirectory() && e.name.startsWith('admin')).map((e) => e.name);
   const aiServers = appEntries.filter((e) => e.isDirectory() && e.name === 'ai-server').map((e) => e.name);
 
-  const services: Service[] = [];
-  let colorIdx = 0;
-
+  const specs: ServiceSpec[] = [];
   for (const b of backends) {
-    const mainPath = join(appsDir, b, 'src', 'main.ts');
-    if (!existsSync(mainPath)) continue;
+    if (!existsSync(join(appsDir, b, 'src', 'main.ts'))) continue;
     const port = await ensurePort(projectRoot, b);
-    services.push({
-      name: b,
-      cmd: 'npx',
-      args: ['tsx', 'watch', 'src/main.ts'],
-      cwd: join(appsDir, b),
-      color: COLORS[colorIdx++ % COLORS.length]!,
-      enabled: !only || only.includes(b),
-      port: port,
-    });
+    if (only && !only.includes(b)) continue;
+    specs.push({ name: b, cmd: 'npx', args: ['tsx', 'watch', 'src/main.ts'], cwd: join(appsDir, b), port });
   }
   for (const f of frontends) {
     if (!existsSync(join(appsDir, f, 'package.json'))) continue;
     const port = await ensurePort(projectRoot, f);
-    services.push({
-      name: f,
-      cmd: 'npx',
-      args: ['vite', '--port', String(port), '--strictPort'],
-      cwd: join(appsDir, f),
-      color: COLORS[colorIdx++ % COLORS.length]!,
-      enabled: !only || only.includes(f),
-      port,
-    });
+    if (only && !only.includes(f)) continue;
+    specs.push({ name: f, cmd: 'npx', args: ['vite', '--port', String(port), '--strictPort'], cwd: join(appsDir, f), port });
   }
   for (const a of admins) {
     if (!existsSync(join(appsDir, a, 'package.json'))) continue;
     const port = await ensurePort(projectRoot, a);
-    services.push({
-      name: a,
-      cmd: 'npx',
-      args: ['vite', '--port', String(port), '--strictPort'],
-      cwd: join(appsDir, a),
-      color: COLORS[colorIdx++ % COLORS.length]!,
-      enabled: !only || only.includes(a),
-      port,
-    });
+    if (only && !only.includes(a)) continue;
+    specs.push({ name: a, cmd: 'npx', args: ['vite', '--port', String(port), '--strictPort'], cwd: join(appsDir, a), port });
   }
   for (const ai of aiServers) {
-    const mainPy = join(appsDir, ai, 'main.py');
-    if (!existsSync(mainPy)) continue;
+    if (!existsSync(join(appsDir, ai, 'main.py'))) continue;
     const port = await ensurePort(projectRoot, ai);
-    services.push({
-      name: ai,
-      cmd: 'python',
-      args: ['main.py'],
-      cwd: join(appsDir, ai),
-      color: COLORS[colorIdx++ % COLORS.length]!,
-      enabled: !only || only.includes(ai),
-      port,
-    });
-  }
-
-  const active = services.filter((s) => s.enabled);
-  if (active.length === 0) {
-    console.log('No services to start. Check that apps/* exist.');
-    return;
-  }
-
-  console.log(`nexus dev — starting ${active.length} service(s)\n`);
-  for (const s of active) {
-    console.log(`  ${s.color}[${s.name}]${RESET} → :${s.port}`);
-  }
-  console.log('');
-
-  const procs: ChildProcess[] = [];
-  let shuttingDown = false;
-
-  const shutdown = () => {
-    if (shuttingDown) return;
-    shuttingDown = true;
-    console.log('\nShutting down...');
-    for (const p of procs) {
-      try {
-        p.kill('SIGTERM');
-      } catch { /* ignore */ }
-    }
-    setTimeout(() => process.exit(0), 500);
-  };
-
-  process.on('SIGINT', shutdown);
-  process.on('SIGTERM', shutdown);
-
-  for (const svc of active) {
-    const child = spawn(svc.cmd, svc.args, {
-      cwd: svc.cwd,
-      stdio: ['inherit', 'pipe', 'pipe'],
-      env: { ...process.env, FORCE_COLOR: '1', NEXUS_PORT: String(svc.port) },
-      shell: true,
-    });
-
-    const prefix = `${svc.color}[${svc.name}]${RESET}`;
-    child.stdout?.on('data', (chunk: Buffer) => {
-      const lines = chunk.toString().split('\n');
-      for (const line of lines) {
-        if (line.trim()) process.stdout.write(`${prefix} ${line}\n`);
-      }
-    });
-    child.stderr?.on('data', (chunk: Buffer) => {
-      const lines = chunk.toString().split('\n');
-      for (const line of lines) {
-        if (line.trim()) process.stderr.write(`${prefix} ${line}\n`);
-      }
-    });
-    child.on('exit', (code, signal) => {
-      if (shuttingDown) return;
-      console.log(`${prefix} exited (${code ?? signal}). Restarting in 1s...`);
-      setTimeout(() => {
-        if (!shuttingDown) {
-          procs.push(spawn(svc.cmd, svc.args, { cwd: svc.cwd, stdio: 'inherit', env: process.env, shell: true }));
-        }
-      }, 1000);
-    });
-    procs.push(child);
+    if (only && !only.includes(ai)) continue;
+    specs.push({ name: ai, cmd: 'python', args: ['main.py'], cwd: join(appsDir, ai), port });
   }
+  return specs;
 }
 
-export const description = 'Start dev services (all apps under ./apps)';
-export const usage = 'nexus dev [--only backend,frontend]';
+export const description = 'Start dev services (all apps under ./apps) — interactive console in a TTY';
+export const usage = 'nexus dev [--only a,b] [--no-panel]';

package/src/devPanel.ts

@@ -0,0 +1,440 @@
+/**
+ * devPanel — full-screen Nexus Console TUI.
+ *
+ * Three panes:
+ *   1. Services — managed by ServiceManager (start/stop/restart/logs)
+ *   2. Commands — palette auto-built from the command registry (getCommands())
+ *   3. Output — selected service logs OR command output
+ *
+ * Keybindings:
+ *   ↑/↓        move selection (within active list)
+ *   Enter      run selected command / start selected service
+ *   Tab        switch active pane (services ⇄ commands)
+ *   s / t / r  start / stop / restart selected service
+ *   l          cycle log source (service logs ⇄ command output)
+ *   q / Esc    quit (kills all services)
+ *   ?          help
+ *
+ * Zero dependencies: raw ANSI + readline keypress.
+ */
+import { stdin as input, stdout as output } from 'node:process';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import * as readline from 'node:readline';
+import { getCommands, runCommand } from './dispatcher.js';
+import { ServiceManager } from './devServiceManager.js';
+
+const ANSI = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  clear: '\x1b[2J\x1b[H',
+  altOn: '\x1b[?1049h',
+  altOff: '\x1b[?1049l',
+  hideCursor: '\x1b[?25l',
+  showCursor: '\x1b[?25h',
+  move: (r: number, c: number) => `\x1b[${r};${c}H`,
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  dimGray: '\x1b[90m',
+};
+
+export interface DevPanelOptions {
+  services: ServiceManager;
+  /** Invoked on quit (after the panel exits) — used to kill all services. */
+  onQuit?: () => void;
+}
+
+interface CommandItem {
+  name: string;
+  label: string;
+  desc: string;
+  needsArgs: boolean;
+  interactive: boolean;
+}
+
+/** Commands that need a real TTY (their own prompts) — suspend the panel. */
+const INTERACTIVE_COMMANDS = new Set(['init', 'add', 'plugin', 'queue:work']);
+
+/** Commands that take a positional/flag arg we should collect inline. */
+const ARG_COMMANDS = new Set([
+  'make:route', 'make:controller', 'make:model', 'make:service', 'make:repository',
+  'make:middleware', 'make:validator', 'make:job', 'make:event', 'make:listener',
+  'make:policy', 'make:resource', 'make:request', 'make:mail', 'make:room',
+  'make:subgraph', 'make:seeder', 'make:migration', 'make:provider', 'make:plugin',
+  'db:seed', 'db:migrate', 'db:rollback', 'queue:retry',
+]);
+
+function commandItems(): CommandItem[] {
+  return getCommands().map((c) => ({
+    name: c.name,
+    label: c.name,
+    desc: c.description ?? '',
+    needsArgs: ARG_COMMANDS.has(c.name),
+    interactive: INTERACTIVE_COMMANDS.has(c.name),
+  }));
+}
+
+/** Categorize commands for the palette grouping. */
+function groupOf(name: string): string {
+  if (name.startsWith('make:')) return 'make:*';
+  if (name.startsWith('db:')) return 'data';
+  if (name.startsWith('queue:')) return 'queue';
+  if (name.startsWith('plugin')) return 'plugins';
+  if (name === 'down' || name === 'up') return 'maintenance';
+  if (['init', 'dev', 'build', 'test', 'doctor'].includes(name)) return 'project';
+  return 'project';
+}
+
+const GROUPS = ['project', 'make:*', 'data', 'queue', 'plugins', 'maintenance'];
+
+export async function startDevPanel(opts: DevPanelOptions): Promise<void> {
+  const { services } = opts;
+  const items = commandItems();
+  const grouped = new Map<string, CommandItem[]>();
+  for (const g of GROUPS) grouped.set(g, []);
+  for (const item of items) {
+    const g = groupOf(item.name);
+    if (!grouped.has(g)) grouped.set(g, []);
+    grouped.get(g)!.push(item);
+  }
+
+  // Flatten palette (with group header markers).
+  type Row = { kind: 'header'; label: string } | { kind: 'cmd'; cmd: CommandItem };
+  const palette: Row[] = [];
+  for (const g of GROUPS) {
+    const list = grouped.get(g) ?? [];
+    if (list.length === 0) continue;
+    palette.push({ kind: 'header', label: g });
+    for (const cmd of list) palette.push({ kind: 'cmd', cmd });
+  }
+
+  // ---- state ----
+  let activePane: 'services' | 'commands' = 'services';
+  let svcIndex = 0;
+  let cmdIndex = 0;
+  let logSource: string | 'commands' = services.services[0]?.name ?? 'commands';
+  let commandOutput: string[] = [];
+  let argMode: { cmd: CommandItem; buffer: string } | null = null;
+  let showHelp = false;
+  let quit = false;
+  let lastRender = 0;
+
+  // ---- raw keyboard ----
+  input.setRawMode?.(true);
+  input.resume?.();
+  output.write(ANSI.altOn + ANSI.hideCursor);
+
+  const keypressHandler = (str: string, key: any) => {
+    if (argMode) {
+      if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+        argMode = null;
+        render();
+      } else if (key.name === 'return' || key.name === 'enter') {
+        const { cmd, buffer } = argMode;
+        argMode = null;
+        void runSelectedCommand(cmd, buffer);
+      } else if (key.name === 'backspace') {
+        argMode.buffer = argMode.buffer.slice(0, -1);
+      } else if (str && !key.ctrl && !key.meta) {
+        argMode.buffer += str;
+      }
+      render();
+      return;
+    }
+
+    if (key.name === 'c' && key.ctrl) {
+      quit = true;
+      return;
+    }
+    if (key.name === 'escape' || key.name === 'q') {
+      if (showHelp) showHelp = false;
+      else quit = true;
+      return;
+    }
+    if (key.name === '?') {
+      showHelp = !showHelp;
+    }
+    if (showHelp) return;
+
+    switch (key.name) {
+      case 'up':
+        if (activePane === 'services') svcIndex = Math.max(0, svcIndex - 1);
+        else cmdIndex = prevSelectable(cmdIndex, -1, palette);
+        break;
+      case 'down':
+        if (activePane === 'services') svcIndex = Math.min(services.services.length - 1, svcIndex + 1);
+        else cmdIndex = prevSelectable(cmdIndex, 1, palette);
+        break;
+      case 'tab':
+        activePane = activePane === 'services' ? 'commands' : 'services';
+        break;
+      case 'return':
+      case 'enter':
+        if (activePane === 'services') {
+          const svc = services.services[svcIndex];
+          if (svc) {
+            if (svc.status === 'stopped' || svc.status === 'crashed') services.start(svc.name);
+            else services.restart(svc.name);
+          }
+        } else {
+          const row = palette[cmdIndex];
+          if (row && row.kind === 'cmd') {
+            const cmd = row.cmd;
+            if (cmd.needsArgs) {
+              argMode = { cmd, buffer: '' };
+            } else {
+              void runSelectedCommand(cmd, '');
+            }
+          }
+        }
+        break;
+      case 's':
+        services.start(services.services[svcIndex]?.name ?? '');
+        break;
+      case 't':
+        services.stop(services.services[svcIndex]?.name ?? '');
+        break;
+      case 'r':
+        services.restart(services.services[svcIndex]?.name ?? '');
+        break;
+      case 'l':
+        cycleLogSource();
+        break;
+    }
+    render();
+  };
+
+  function prevSelectable(current: number, dir: number, list: Row[]): number {
+    let i = current;
+    for (let step = 0; step < list.length; step++) {
+      i = (i + dir + list.length) % list.length;
+      const row = list[i];
+      if (row && row.kind === 'cmd') return i;
+    }
+    return current;
+  }
+
+  function cycleLogSource(): void {
+    const names = services.services.map((s) => s.name);
+    const targets = [...names, 'commands'];
+    const idx = targets.indexOf(logSource);
+    logSource = targets[(idx + 1) % targets.length] ?? 'commands';
+  }
+
+  async function runSelectedCommand(cmd: CommandItem, inlineArgs: string): Promise<void> {
+    commandOutput = [];
+    setLogSource('commands');
+    render();
+
+    if (cmd.interactive) {
+      // Suspend panel → real TTY → resume.
+      suspend();
+      try {
+        const bin = resolveCliBin();
+        const args = inlineArgs ? [cmd.name, ...inlineArgs.trim().split(/\s+/)] : [cmd.name];
+        await spawnNode(bin, args);
+      } catch (err) {
+        pushCommandOutput(`✗ ${cmd.name} failed: ${(err as Error).message}`);
+      }
+      resume();
+      render();
+      return;
+    }
+
+    const argv = inlineArgs ? inlineArgs.trim().split(/\s+/) : [];
+    const origOut = process.stdout.write.bind(process.stdout);
+    const origErr = process.stderr.write.bind(process.stderr);
+    const sink = (chunk: string | Buffer, isErr = false) => {
+      const text = String(chunk);
+      pushCommandOutput(text);
+      return true;
+    };
+    (process.stdout as unknown as { write: Function }).write = (chunk: string | Buffer) => sink(chunk, false);
+    (process.stderr as unknown as { write: Function }).write = (chunk: string | Buffer) => sink(chunk, true);
+    try {
+      await runCommand(cmd.name, argv);
+      pushCommandOutput(`\n${ANSI.green}✓ ${cmd.name}${ANSI.reset} finished`);
+    } catch (err) {
+      pushCommandOutput(`\n${ANSI.red}✗ ${cmd.name} failed:${ANSI.reset} ${(err as Error).message}`);
+    } finally {
+      (process.stdout as unknown as { write: Function }).write = origOut;
+      (process.stderr as unknown as { write: Function }).write = origErr;
+    }
+    render();
+  }
+
+  function setLogSource(source: string): void {
+    logSource = source;
+  }
+
+  function pushCommandOutput(text: string): void {
+    const lines = text.split('\n');
+    for (const line of lines) {
+      commandOutput.push(stripAnsi(line));
+    }
+    if (commandOutput.length > 200) commandOutput.splice(0, commandOutput.length - 200);
+    throttledRender();
+  }
+
+  function suspend(): void {
+    input.setRawMode?.(false);
+    output.write(ANSI.altOff + ANSI.showCursor);
+  }
+
+  function resume(): void {
+    input.setRawMode?.(true);
+    input.resume?.();
+    output.write(ANSI.altOn + ANSI.hideCursor);
+  }
+
+  // ---- render ----
+  function throttledRender(): void {
+    const now = Date.now();
+    if (now - lastRender < 80) return;
+    lastRender = now;
+    render();
+  }
+
+  function render(): void {
+    if (quit) return;
+    if (!output.isTTY) return;
+    const { rows, columns } = output as unknown as { rows: number; columns: number };
+    const H = rows || 24;
+    const W = columns || 80;
+
+    const lines: string[] = [];
+    lines.push(`${ANSI.bold}${ANSI.cyan} Nexus Console ${ANSI.reset}${ANSI.dim}— BhooAI Nexus${ANSI.reset} ${ANSI.dim}(${services.services.length} services, ${palette.length - GROUPS.length} commands)${ANSI.reset}`);
+    lines.push('');
+
+    // --- Services pane ---
+    lines.push(`${ANSI.bold}${ANSI.blue} SERVICES ${ANSI.reset}`);
+    services.services.forEach((svc, i) => {
+      const sel = activePane === 'services' && i === svcIndex;
+      const marker = sel ? `${ANSI.cyan}▶${ANSI.reset}` : ' ';
+      const dot = statusDot(svc.status);
+      const name = sel ? `${ANSI.bold}${svc.name}${ANSI.reset}` : svc.name;
+      const pid = svc.pid ? String(svc.pid) : '—';
+      const restarts = svc.restarts ? String(svc.restarts) : '0';
+      lines.push(` ${marker} ${name.padEnd(18)} :${String(svc.port).padEnd(6)} ${dot} ${svc.status.padEnd(8)} ${pid.padEnd(7)} ${restarts}`);
+    });
+    lines.push('');
+
+    // --- Commands pane ---
+    lines.push(`${ANSI.bold}${ANSI.magenta} COMMANDS ${ANSI.reset}`);
+    const visible = palette.slice(0, Math.min(palette.length, H - lines.length - 8));
+    visible.forEach((row, i) => {
+      if (row.kind === 'header') {
+        lines.push(` ${ANSI.dim}${row.label.toUpperCase()}${ANSI.reset}`);
+      } else {
+        const isSelected = activePane === 'commands' && palette.indexOf(row) === cmdIndex;
+        const marker = isSelected ? `${ANSI.cyan}▶${ANSI.reset}` : ' ';
+        const label = isSelected ? `${ANSI.bold}${row.cmd.label}${ANSI.reset}` : row.cmd.label;
+        const desc = row.cmd.desc ? `${ANSI.dim}${row.cmd.desc}${ANSI.reset}` : '';
+        lines.push(` ${marker} ${label.padEnd(22)} ${desc}`);
+      }
+    });
+    lines.push('');
+
+    // --- Output pane ---
+    const outputTitle = logSource === 'commands' ? 'COMMAND OUTPUT' : `LOGS: ${logSource}`;
+    lines.push(`${ANSI.bold}${ANSI.yellow} ${outputTitle} ${ANSI.reset}`);
+    const src = logSource === 'commands' ? commandOutput : services.tail(logSource, 60);
+    const availH = H - lines.length - 3;
+    const tail = src.slice(-Math.max(availH, 1));
+    for (const line of tail) lines.push(` ${ANSI.dim}|${ANSI.reset} ${line}`);
+
+    // --- help bar ---
+    const helpText = showHelp
+      ? ` ↑/↓ select · Enter run/start · Tab pane · s start · t stop · r restart · l logs · q quit · ? help`
+      : `↑/↓ select · Enter run · Tab pane · s/t/r start/stop/restart · l logs · c cmds · q quit · ? help`;
+
+    // Arg prompt line
+    if (argMode) {
+      lines.push('');
+      lines.push(`${ANSI.cyan}${argMode.cmd.name}${ANSI.reset} ${argMode.buffer}█`);
+    }
+
+    // Assemble output: keep within terminal height.
+    const body = lines.slice(0, H - 1);
+    let out = ANSI.clear;
+    out += body.join('\n');
+    out += ANSI.move(H, 1);
+    out += `${ANSI.dim}${helpText}${ANSI.reset}`;
+    if (argMode) {
+      out += ANSI.move(H - 1, 1);
+    }
+    output.write(out);
+  }
+
+  function statusDot(status: string): string {
+    switch (status) {
+      case 'running': return `${ANSI.green}●${ANSI.reset}`;
+      case 'starting': return `${ANSI.yellow}◐${ANSI.reset}`;
+      case 'crashed': return `${ANSI.red}✗${ANSI.reset}`;
+      default: return `${ANSI.dimGray}○${ANSI.reset}`;
+    }
+  }
+
+  // wire service log redraws
+  services.onLog = () => throttledRender();
+
+  // ---- keypress wiring ----
+  readline.emitKeypressEvents(input);
+  input.on('keypress', keypressHandler);
+
+  // Intercept SIGINT/SIGTERM (Ctrl+C already handled by keypress ctrl-c).
+  const onSignal = () => {
+    quit = true;
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  render();
+
+  // Wait for quit.
+  while (!quit) {
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  // ---- cleanup ----
+  input.removeListener('keypress', keypressHandler);
+  input.setRawMode?.(false);
+  output.write(ANSI.altOff + ANSI.showCursor);
+  process.removeListener('SIGINT', onSignal);
+  process.removeListener('SIGTERM', onSignal);
+  opts.onQuit?.();
+}
+
+function spawnNode(bin: string, args: string[]): Promise<void> {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [bin, ...args], { stdio: 'inherit', cwd: process.cwd() });
+    child.on('exit', () => resolve());
+    child.on('error', () => resolve());
+  });
+}
+
+/**
+ * Resolve the CLI bin for suspend-mode commands.
+ *
+ * Works in the monorepo (packages/nexus-cli/src/devPanel.ts → bin/nexus.js)
+ * AND when installed as @bhooai/nexus-cli (its own bin/nexus.js), falling back
+ * to `npx` semantics.
+ */
+function resolveCliBin(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // From src/devPanel.ts: ../../bin/nexus.js reaches the CLI package's own bin.
+  const ownBin = join(here, '..', '..', 'bin', 'nexus.js');
+  if (existsSync(ownBin)) return ownBin;
+  return join(here, '..', '..', '..', '..', 'bin', 'nexus.js');
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, '');
+}

package/src/devServiceManager.ts

@@ -0,0 +1,183 @@
+/**
+ * devServiceManager — supervises the app services started by `nexus dev`.
+ *
+ * Owns each service's process + state and provides start/stop/restart with a
+ * crash-loop guard. Log output is captured into a per-service ring buffer so
+ * the control panel can render live logs.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { Readable } from 'node:stream';
+
+export type ServiceStatus = 'starting' | 'running' | 'stopped' | 'crashed';
+
+export interface ServiceSpec {
+  name: string;
+  cmd: string;
+  args: string[];
+  cwd: string;
+  port: number;
+}
+
+export interface ManagedService extends ServiceSpec {
+  status: ServiceStatus;
+  pid: number | null;
+  restarts: number;
+  lastExit: { code: number | null; signal: NodeJS.Signals | null } | null;
+  logBuffer: string[];
+  child: ChildProcess | null;
+}
+
+const MAX_LOG_LINES = 200;
+const CRASH_THRESHOLD = 5;
+const CRASH_WINDOW_MS = 30_000;
+
+export class ServiceManager {
+  readonly services: ManagedService[] = [];
+  private crashTimes = new Map<string, number[]>();
+
+  constructor(specs: ServiceSpec[]) {
+    for (const spec of specs) {
+      this.services.push({ ...spec, status: 'stopped', pid: null, restarts: 0, lastExit: null, logBuffer: [], child: null });
+    }
+  }
+
+  /** Get a service by name. */
+  get(name: string): ManagedService | null {
+    return this.services.find((s) => s.name === name) ?? null;
+  }
+
+  /** Start a service (idempotent). */
+  start(name: string): void {
+    const svc = this.get(name);
+    if (!svc || svc.child) return;
+    this.spawnChild(svc);
+  }
+
+  /** Stop a service (SIGTERM, then SIGKILL after a grace period). */
+  stop(name: string): void {
+    const svc = this.get(name);
+    if (!svc || !svc.child) return;
+    this.killChild(svc, 'SIGTERM');
+  }
+
+  /** Restart a service. */
+  restart(name: string): void {
+    const svc = this.get(name);
+    if (!svc) return;
+    if (svc.child) this.killChild(svc, 'SIGTERM');
+    // Restart after a short delay so the port frees up.
+    setTimeout(() => this.start(name), 250);
+  }
+
+  /** Kill all services (used on panel quit). */
+  killAll(): void {
+    for (const svc of this.services) {
+      if (svc.child) this.killChild(svc, 'SIGTERM');
+    }
+  }
+
+  private spawnChild(svc: ManagedService): void {
+    svc.status = 'starting';
+    svc.restarts++;
+    this.recordCrashWindow(svc.name);
+
+    // On Windows with shell:true, a cmd path containing spaces must be quoted
+    // or the shell splits it ('C:\Program' is not recognized).
+    const cmd = process.platform === 'win32' && svc.cmd.includes(' ')
+      ? `"${svc.cmd}"`
+      : svc.cmd;
+
+    const child = spawn(cmd, svc.args, {
+      cwd: svc.cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, FORCE_COLOR: '1', NEXUS_PORT: String(svc.port) },
+      shell: process.platform === 'win32',
+    });
+    svc.child = child;
+    svc.pid = child.pid ?? null;
+
+    this.pipe(child.stdout, svc);
+    this.pipe(child.stderr, svc);
+
+    child.once('spawn', () => {
+      svc.status = 'running';
+    });
+
+    child.on('exit', (code, signal) => {
+      svc.child = null;
+      svc.pid = null;
+      svc.lastExit = { code, signal };
+      const wasCrashed = this.isCrashLooping(svc.name);
+      if (wasCrashed) {
+        svc.status = 'crashed';
+        this.push(svc, `✗ ${svc.name} crashed repeatedly — press s to start again`);
+        return;
+      }
+      svc.status = 'stopped';
+      if (svc.restarts > 0 && !this.explicitlyStopping) {
+        this.push(svc, `↻ ${svc.name} exited (${code ?? signal}) — restarting in 1s`);
+        setTimeout(() => this.start(svc.name), 1000);
+      }
+    });
+  }
+
+  private explicitlyStopping = false;
+
+  private killChild(svc: ManagedService, signal: NodeJS.Signals): void {
+    this.explicitlyStopping = true;
+    const child = svc.child;
+    if (!child) return;
+    try {
+      child.kill(signal);
+    } catch { /* ignore */ }
+    // Force-kill if it lingers.
+    setTimeout(() => {
+      if (svc.child && svc.pid) {
+        try { process.kill(svc.pid, 'SIGKILL'); } catch { /* ignore */ }
+      }
+    }, 3000);
+    setTimeout(() => {
+      this.explicitlyStopping = false;
+    }, 3500);
+  }
+
+  private pipe(stream: Readable | null, svc: ManagedService): void {
+    if (!stream) return;
+    stream.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      this.push(svc, text);
+    });
+  }
+
+  private push(svc: ManagedService, text: string): void {
+    const lines = text.split('\n');
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      svc.logBuffer.push(line);
+      if (svc.logBuffer.length > MAX_LOG_LINES) svc.logBuffer.shift();
+    }
+    this.onLog?.(svc.name);
+  }
+
+  /** Called whenever a service's log buffer changes (for panel redraw). */
+  onLog: ((serviceName: string) => void) | null = null;
+
+  private recordCrashWindow(name: string): void {
+    const now = Date.now();
+    const list = (this.crashTimes.get(name) ?? []).filter((t) => now - t < CRASH_WINDOW_MS);
+    list.push(now);
+    this.crashTimes.set(name, list);
+  }
+
+  private isCrashLooping(name: string): boolean {
+    const list = this.crashTimes.get(name) ?? [];
+    return list.length >= CRASH_THRESHOLD;
+  }
+
+  /** Latest log lines for a service. */
+  tail(name: string, lines = 50): string[] {
+    const svc = this.get(name);
+    if (!svc) return [];
+    return svc.logBuffer.slice(-lines);
+  }
+}

package/src/dispatcher.ts

@@ -25,6 +25,21 @@ export function registerCommand(cmd: Command): void {
   COMMANDS.push(cmd);
 }
 
+/** All registered commands (for the panel's command palette). */
+export function getCommands(): Command[] {
+  return [...COMMANDS];
+}
+
+/** Invoke a registered command by name with an argv list (skips help/version). */
+export async function runCommand(name: string, argv: string[]): Promise<void> {
+  const found = COMMANDS.find((c) => c.name === name);
+  if (!found) {
+    console.error(`Unknown command: ${name}`);
+    return;
+  }
+  await found.run({ argv, args: parseArgs(argv) });
+}
+
 export async function run(cmd: string, argv: string[]): Promise<void> {
   try {
     if (cmd === 'help' || cmd === '--help' || cmd === '-h') {