@bhooai/nexus-cli 2.0.3 → 2.0.4

package/src/devServiceManager.ts

@@ -7,6 +7,8 @@
  */
 import { spawn, type ChildProcess } from 'node:child_process';
 import type { Readable } from 'node:stream';
+import { nextFreePort } from './util.js';
+import { readRegistry, writeRegistry, type PortRegistry } from './ports.js';
 
 export type ServiceStatus = 'starting' | 'running' | 'stopped' | 'crashed';
 
@@ -16,6 +18,8 @@ export interface ServiceSpec {
   args: string[];
   cwd: string;
   port: number;
+  /** Index into args[] that holds the port value (for vite --port). Undefined = no editable port arg (backend uses env). */
+  portArgIndex?: number;
 }
 
 export interface ManagedService extends ServiceSpec {
@@ -23,6 +27,8 @@ export interface ManagedService extends ServiceSpec {
   pid: number | null;
   restarts: number;
   lastExit: { code: number | null; signal: NodeJS.Signals | null } | null;
+  /** Last log lines captured before crash (for inline display in the panel). */
+  lastCrashLog: string[];
   logBuffer: string[];
   child: ChildProcess | null;
 }
@@ -34,10 +40,12 @@ const CRASH_WINDOW_MS = 30_000;
 export class ServiceManager {
   readonly services: ManagedService[] = [];
   private crashTimes = new Map<string, number[]>();
+  private projectRoot: string;
 
-  constructor(specs: ServiceSpec[]) {
+  constructor(specs: ServiceSpec[], projectRoot: string) {
+    this.projectRoot = projectRoot;
     for (const spec of specs) {
-      this.services.push({ ...spec, status: 'stopped', pid: null, restarts: 0, lastExit: null, logBuffer: [], child: null });
+      this.services.push({ ...spec, status: 'stopped', pid: null, restarts: 0, lastExit: null, lastCrashLog: [], logBuffer: [], child: null });
     }
   }
 
@@ -103,13 +111,29 @@ export class ServiceManager {
       svc.status = 'running';
     });
 
-    child.on('exit', (code, signal) => {
+    child.on('exit', async (code, signal) => {
+      const exitInfo = { code, signal };
       svc.child = null;
       svc.pid = null;
-      svc.lastExit = { code, signal };
+      svc.lastExit = exitInfo;
+
+      // --- EADDRINUSE: auto-bump port and restart ---
+      const recentLogs = svc.logBuffer.slice(-20).join('\n');
+      if (/\bEADDRINUSE\b/i.test(recentLogs)) {
+        const bump = await this.bumpPort(svc);
+        if (bump) {
+          this.push(svc, `⚡ Port ${bump.oldPort} busy → bumped to ${bump.newPort}, restarting ${svc.name}`);
+          svc.status = 'stopped';
+          setTimeout(() => this.start(svc.name), 300);
+          return;
+        }
+      }
+
+      // --- Crash-loop guard ---
       const wasCrashed = this.isCrashLooping(svc.name);
       if (wasCrashed) {
         svc.status = 'crashed';
+        svc.lastCrashLog = svc.logBuffer.slice(-8);
         this.push(svc, `✗ ${svc.name} crashed repeatedly — press s to start again`);
         return;
       }
@@ -162,6 +186,28 @@ export class ServiceManager {
   /** Called whenever a service's log buffer changes (for panel redraw). */
   onLog: ((serviceName: string) => void) | null = null;
 
+  /** Bump a service's port on EADDRINUSE and persist the new port to the registry. */
+  private async bumpPort(svc: ManagedService): Promise<{ oldPort: number; newPort: number } | null> {
+    const oldPort = svc.port;
+    const newPort = await nextFreePort(oldPort + 1);
+
+    // Update the args array if the service has an editable port arg (vite).
+    if (svc.portArgIndex !== undefined && svc.portArgIndex < svc.args.length) {
+      svc.args[svc.portArgIndex] = String(newPort);
+    }
+    // Update the port field (used by env var and registry).
+    svc.port = newPort;
+
+    // Persist to registry so the next run keeps the bumped port.
+    try {
+      const reg: PortRegistry = await readRegistry(this.projectRoot);
+      reg[svc.name] = newPort;
+      await writeRegistry(this.projectRoot, reg);
+    } catch { /* non-fatal */ }
+
+    return { oldPort, newPort };
+  }
+
   private recordCrashWindow(name: string): void {
     const now = Date.now();
     const list = (this.crashTimes.get(name) ?? []).filter((t) => now - t < CRASH_WINDOW_MS);

package/src/dispatcher.ts

@@ -6,6 +6,7 @@
  */
 import { parseArgs } from './util.js';
 import { closePrompts } from './prompts.js';
+import { launchWelcome } from './launcher.js';
 
 export interface CommandContext {
   argv: string[];
@@ -42,6 +43,11 @@ export async function runCommand(name: string, argv: string[]): Promise<void> {
 
 export async function run(cmd: string, argv: string[]): Promise<void> {
   try {
+    // Bare `nexus` → full-screen welcome launcher.
+    if (!cmd) {
+      await launchWelcome();
+      return;
+    }
     if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
       printHelp();
       return;
@@ -69,7 +75,7 @@ function printHelp(): void {
 Usage: nexus <command> [options]
 
 Project lifecycle:
-  init [dir] [--example <name>] [--interactive]   Scaffold a new project
+  init [name] [--no-install] [--force]            Scaffold a new project (guided wizard)
   dev [--only a,b]                                 Start dev services
   build [--target <app>|all]                       Build for production
   test [--watch|--e2e]                             Run tests

package/src/examples.ts

@@ -0,0 +1,90 @@
+/**
+ * Examples resolution + on-demand install.
+ *
+ * Examples ship bundled inside `bhooai-nexus` at
+ * `packages/nexus-examples/examples`. In a normal install that dir is present
+ * and the wizard reads it directly. If it's missing (a stripped/custom
+ * install), `ensureExamples()` falls back to installing
+ * `@bhooai/nexus-examples` into a persistent temp cache and reads from there.
+ */
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Bundled examples dir: packages/nexus-examples/examples (2-up from src/). */
+export const BUNDLED_EXAMPLES_DIR = resolve(HERE, '..', '..', 'nexus-examples', 'examples');
+
+/** Persistent cache dir for the on-demand install fallback. */
+const CACHE_DIR = join(tmpdir(), 'nexus-examples-cache');
+const CACHE_EXAMPLES_DIR = join(CACHE_DIR, 'node_modules', '@bhooai', 'nexus-examples', 'examples');
+
+/** List example names (subdirectories) inside a resolved examples dir. */
+export async function listExamplesFrom(dir: string): Promise<string[]> {
+  if (!existsSync(dir)) return [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Synchronously return the bundled examples dir if it has examples, else null. */
+export function resolveExamplesDir(): string | null {
+  if (existsSync(BUNDLED_EXAMPLES_DIR)) return BUNDLED_EXAMPLES_DIR;
+  if (existsSync(CACHE_EXAMPLES_DIR)) return CACHE_EXAMPLES_DIR;
+  return null;
+}
+
+export interface EnsureExamplesResult {
+  dir: string;
+  list: string[];
+  installed: boolean;
+}
+
+/**
+ * Ensure the examples are available, installing @bhooai/nexus-examples on
+ * demand when the bundled dir is missing. Returns the resolved dir + list.
+ */
+export async function ensureExamples(): Promise<EnsureExamplesResult | { error: string }> {
+  // Bundled first.
+  const bundled = await listExamplesFrom(BUNDLED_EXAMPLES_DIR);
+  if (bundled.length > 0) {
+    return { dir: BUNDLED_EXAMPLES_DIR, list: bundled, installed: false };
+  }
+
+  // Cached install already present?
+  const cached = await listExamplesFrom(CACHE_EXAMPLES_DIR);
+  if (cached.length > 0) {
+    return { dir: CACHE_EXAMPLES_DIR, list: cached, installed: false };
+  }
+
+  // On-demand install into the cache.
+  const code = await runNpmInstall(CACHE_DIR, '@bhooai/nexus-examples');
+  if (code !== 0) {
+    return { error: 'Failed to install @bhooai/nexus-examples (network or npm error).' };
+  }
+  const list = await listExamplesFrom(CACHE_EXAMPLES_DIR);
+  if (list.length === 0) {
+    return { error: '@bhooai/nexus-examples installed but no examples were found inside it.' };
+  }
+  return { dir: CACHE_EXAMPLES_DIR, list, installed: true };
+}
+
+/** Run `npm install <pkg>` in a directory; returns the exit code. */
+function runNpmInstall(dir: string, pkg: string): Promise<number> {
+  return new Promise((res) => {
+    const child = spawn('npm', ['install', '--no-audit', '--no-fund', '--prefix', dir, pkg], {
+      cwd: dir,
+      stdio: 'ignore',
+      shell: process.platform === 'win32',
+    });
+    child.on('error', () => res(1));
+    child.on('exit', (code) => res(code ?? 1));
+  });
+}

package/src/features.ts

@@ -0,0 +1,261 @@
+/**
+ * Feature catalog + installer.
+ *
+ * A single source of truth shared by the init wizard (feature picker) and the
+ * dev console's Features tab. Each feature either:
+ *   - provides a whole app folder (frontend / admin / ai-server) rendered from
+ *     the base template tree, or
+ *   - overlays starter code (routes / models / ws rooms / graphql / jobs / …)
+ *     from templates/features/<id> into an existing project.
+ *
+ * Env keys are appended to `.env` (as placeholders) when a feature is installed.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, readdir, writeFile, appendFile } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderTemplateTree } from './templating/tree.js';
+import { ensurePort, readRegistry } from './ports.js';
+import { slugify } from './util.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = resolve(HERE, '..', 'templates');
+const FEATURES_TEMPLATES = join(TEMPLATES_DIR, 'features');
+const BASE_TEMPLATES = join(TEMPLATES_DIR, 'base');
+
+export interface Feature {
+  id: string;
+  name: string;
+  desc: string;
+  category: 'frontend' | 'backend' | 'infra';
+  /** App folder this feature provides (rendered from templates/base/apps/<app>). */
+  app?: 'frontend' | 'admin' | 'ai-server';
+  /** Overlay template dir under templates/features/<id>. */
+  templateDir?: string;
+  envKeys: string[];
+}
+
+export const FEATURES: Feature[] = [
+  {
+    id: 'frontend',
+    name: 'React Frontend',
+    desc: 'Vite + React SPA that proxies /api, /uploads and /ws to the backend.',
+    category: 'frontend',
+    app: 'frontend',
+    envKeys: [],
+  },
+  {
+    id: 'admin',
+    name: 'Admin Panel',
+    desc: 'Nexus admin console (apps/admin) with live service registry + users.',
+    category: 'frontend',
+    app: 'admin',
+    envKeys: [],
+  },
+  {
+    id: 'ai-server',
+    name: 'AI Server',
+    desc: 'Python FastAPI server behind the /ai proxy, plus provider API keys.',
+    category: 'infra',
+    app: 'ai-server',
+    envKeys: ['NEXUS_AI_OPENAI_API_KEY', 'NEXUS_AI_OLLAMA_API_KEY', 'NEXUS_AI_ANTHROPIC_API_KEY'],
+  },
+  {
+    id: 'auth',
+    name: 'Auth Starter',
+    desc: 'register / login / me routes, a User model and JWT sessions.',
+    category: 'backend',
+    templateDir: 'auth',
+    envKeys: [],
+  },
+  {
+    id: 'realtime',
+    name: 'Realtime',
+    desc: 'A WebSocket chat room (presence, typing) on the /ws endpoint.',
+    category: 'backend',
+    templateDir: 'realtime',
+    envKeys: [],
+  },
+  {
+    id: 'graphql',
+    name: 'GraphQL',
+    desc: 'Federation subgraph starter (posts + authors) under /graphql.',
+    category: 'backend',
+    templateDir: 'graphql',
+    envKeys: [],
+  },
+  {
+    id: 'payments',
+    name: 'Payments',
+    desc: 'Checkout + webhook routes wired for Razorpay and PayPal.',
+    category: 'backend',
+    templateDir: 'payments',
+    envKeys: [
+      'NEXUS_PAYMENTS_RAZORPAY_KEY_ID',
+      'NEXUS_PAYMENTS_RAZORPAY_KEY_SECRET',
+      'NEXUS_PAYMENTS_PAYPAL_CLIENT_ID',
+      'NEXUS_PAYMENTS_PAYPAL_CLIENT_SECRET',
+    ],
+  },
+  {
+    id: 'email',
+    name: 'Email',
+    desc: 'A Welcome Mailable + EJS template, rendered via the log provider.',
+    category: 'backend',
+    templateDir: 'email',
+    envKeys: [],
+  },
+  {
+    id: 'storage',
+    name: 'File Storage',
+    desc: 'Upload route + signed private URLs + local/S3 disk config.',
+    category: 'backend',
+    templateDir: 'storage',
+    envKeys: [
+      'NEXUS_STORAGE_S3_BUCKET',
+      'NEXUS_STORAGE_S3_REGION',
+      'NEXUS_STORAGE_S3_ENDPOINT',
+      'NEXUS_STORAGE_S3_CDN',
+    ],
+  },
+  {
+    id: 'queue',
+    name: 'Queue & Jobs',
+    desc: 'Example job + listener, dispatched to the Redis queue.',
+    category: 'backend',
+    templateDir: 'queue',
+    envKeys: [],
+  },
+];
+
+export function getFeature(id: string): Feature | undefined {
+  return FEATURES.find((f) => f.id === id);
+}
+
+/** Features that ship as a whole app folder under templates/base/apps. */
+export function appFeatures(): Feature[] {
+  return FEATURES.filter((f): f is Feature & { app: NonNullable<Feature['app']> } => !!f.app);
+}
+
+/** Features that overlay starter code under apps/backend/src. */
+export function backendFeatures(): Feature[] {
+  return FEATURES.filter((f) => !!f.templateDir);
+}
+
+/** Vars needed to render base app templates against an existing project. */
+export interface ProjectVars {
+  name: string;
+  nameSlug: string;
+  backendPort: number;
+  frontendPort: number;
+  adminPort: number;
+  aiPort: number;
+}
+
+/** Derive render vars for a feature install from the project's package.json + port registry. */
+export async function projectVars(projectRoot: string): Promise<ProjectVars> {
+  let name = 'app';
+  try {
+    const raw = await readFile(join(projectRoot, 'package.json'), 'utf-8');
+    const pkg = JSON.parse(raw) as { name?: string };
+    name = pkg.name ?? 'app';
+  } catch { /* leave default */ }
+  const reg = await readRegistry(projectRoot);
+  return {
+    name,
+    nameSlug: slugify(name),
+    backendPort: reg.backend ?? 4000,
+    frontendPort: reg.frontend ?? 3000,
+    adminPort: reg.admin ?? 3300,
+    aiPort: reg['ai-server'] ?? 8000,
+  };
+}
+
+/** Detect which catalog features are already installed in a project. */
+export async function detectFeatures(projectRoot: string): Promise<Set<string>> {
+  const installed = new Set<string>();
+  const apps = join(projectRoot, 'apps');
+  const backendSrc = join(apps, 'backend', 'src');
+
+  const has = (p: string) => existsSync(join(projectRoot, p));
+  const hasInDir = async (dir: string, predicate: (name: string) => boolean): Promise<boolean> => {
+    if (!existsSync(dir)) return false;
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      return entries.some((e) => predicate(e.name));
+    } catch {
+      return false;
+    }
+  };
+
+  if (has('apps/frontend/package.json')) installed.add('frontend');
+  if (has('apps/admin/package.json')) installed.add('admin');
+  if (has('apps/ai-server/main.py')) installed.add('ai-server');
+
+  if (has('apps/backend/src/routes/auth.ts')) installed.add('auth');
+  if (await hasInDir(join(backendSrc, 'ws'), (n) => n.endsWith('.room.ts'))) installed.add('realtime');
+  if (await hasInDir(join(backendSrc, 'graphql'), (n) => n.endsWith('.graph.ts'))) installed.add('graphql');
+  if (has('apps/backend/src/routes/payments.ts')) installed.add('payments');
+  if (await hasInDir(join(backendSrc, 'mail', 'mailables'), (n) => n.endsWith('.ts'))) installed.add('email');
+  if (has('apps/backend/src/routes/uploads.ts')) installed.add('storage');
+  if (await hasInDir(join(backendSrc, 'jobs'), (n) => n.endsWith('Job.ts'))) installed.add('queue');
+
+  return installed;
+}
+
+export interface InstallResult {
+  messages: string[];
+  addedApps: string[];
+}
+
+/**
+ * Install a feature into an existing project. Creates app folders / overlays
+ * starter code, ensures ports are registered and appends env-key placeholders.
+ */
+export async function installFeature(projectRoot: string, id: string): Promise<InstallResult> {
+  const feature = getFeature(id);
+  const messages: string[] = [];
+  const addedApps: string[] = [];
+  if (!feature) {
+    messages.push(`✗ Unknown feature: ${id}`);
+    return { messages, addedApps };
+  }
+  const vars = (await projectVars(projectRoot)) as unknown as Record<string, unknown>;
+
+  if (feature.app) {
+    const appDir = join(projectRoot, 'apps', feature.app);
+    if (existsSync(appDir)) {
+      messages.push(`• ${feature.name} — apps/${feature.app} already exists`);
+    } else {
+      await renderTemplateTree(join(BASE_TEMPLATES, 'apps', feature.app), appDir, vars);
+      await ensurePort(projectRoot, feature.app);
+      addedApps.push(feature.app);
+      messages.push(`✓ ${feature.name} — created apps/${feature.app}`);
+    }
+  }
+
+  if (feature.templateDir) {
+    await renderTemplateTree(join(FEATURES_TEMPLATES, feature.templateDir), projectRoot, vars);
+    messages.push(`✓ ${feature.name} — starter code added under apps/backend/src`);
+  }
+
+  await appendEnvKeys(projectRoot, feature.envKeys);
+  return { messages, addedApps };
+}
+
+/** Append commented env-key placeholders to .env when they are not present. */
+async function appendEnvKeys(projectRoot: string, keys: string[]): Promise<void> {
+  if (keys.length === 0) return;
+  const envPath = join(projectRoot, '.env');
+  if (!existsSync(envPath)) await writeFile(envPath, '# BhooAI Nexus — generated .env\n', 'utf-8');
+  const current = existsSync(envPath) ? await readFile(envPath, 'utf-8') : '';
+  const lines: string[] = [];
+  for (const key of keys) {
+    if (current.includes(key)) continue;
+    lines.push(`# ${key}=`);
+  }
+  if (lines.length > 0) await appendFile(envPath, '\n' + lines.join('\n') + '\n', 'utf-8');
+}
+
+/** Read the current port registry (exported for the Settings tab). */
+export { readRegistry };

package/src/launcher.ts

@@ -0,0 +1,164 @@
+/**
+ * Welcome launcher — full-screen menu shown when `nexus` runs with no
+ * command. Offers project init (runs the guided wizard), opening an existing
+ * project, an environment check, docs, and quit.
+ *
+ * Exits its screen before running any action so the sub-command owns the TTY.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { stdout as output } from 'node:process';
+import { ANSI, Tui, isTty, type KeyInfo } from './tui.js';
+import { boxAround, fitCell } from './layout.js';
+import { runCommand } from './dispatcher.js';
+
+type MenuAction = 'init' | 'open' | 'doctor' | 'docs' | 'quit';
+
+interface MenuItem {
+  id: MenuAction;
+  label: string;
+  desc: string;
+  enabled: boolean;
+}
+
+const BANNER = `${ANSI.cyan}${ANSI.bold}BhooAI Nexus${ANSI.reset}`;
+
+interface MenuState {
+  index: number;
+  result: MenuAction | null;
+}
+
+export async function launchWelcome(): Promise<void> {
+  for (;;) {
+    const choice = await showMenu();
+    switch (choice) {
+      case 'init':
+        await runCommand('init', []);
+        return; // init scaffolds + can open dev; back to the shell.
+      case 'open':
+        await runCommand('dev', []);
+        break;
+      case 'doctor':
+        await runCommand('doctor', []);
+        await pause();
+        break;
+      case 'docs':
+        printDocs();
+        await pause();
+        break;
+      case 'quit':
+      case null:
+        return;
+    }
+  }
+}
+
+async function showMenu(): Promise<MenuAction | null> {
+  if (!isTty()) {
+    console.log(BANNER);
+    console.log('  Welcome to BhooAI Nexus! (full-screen launcher needs a TTY)\n');
+    console.log('  nexus init [name]   Guided project setup');
+    console.log('  nexus dev           Run the dev console');
+    console.log('  nexus doctor        Environment check');
+    console.log('  nexus help          CLI reference\n');
+    return null;
+  }
+
+  const hasProject = existsSync(join(process.cwd(), 'apps'));
+  const items: MenuItem[] = [
+    { id: 'init', label: 'Init project', desc: 'Scaffold a new Nexus project (guided wizard)', enabled: true },
+    { id: 'open', label: 'Open project', desc: 'Run the dev console for this directory', enabled: hasProject },
+    { id: 'doctor', label: 'Environment check', desc: 'Verify Node, npm, MongoDB and Redis', enabled: true },
+    { id: 'docs', label: 'Docs', desc: 'Show the CLI overview', enabled: true },
+    { id: 'quit', label: 'Quit', desc: 'Exit', enabled: true },
+  ];
+
+  const state: MenuState = { index: 0, result: null };
+  const tui = new Tui((str, key) => handleMenuKey(state, items, tui, str, key));
+  tui.enter();
+  renderMenu(state, items, tui);
+  await tui.wait();
+  tui.exit();
+  return state.result;
+}
+
+function handleMenuKey(state: MenuState, items: MenuItem[], tui: Tui, _str: string, key: KeyInfo): void {
+  void _str;
+  if (key.name === 'c' && key.ctrl) {
+    state.result = 'quit';
+    tui.quit = true;
+    return;
+  }
+  if (key.name === 'q' || key.name === 'escape') {
+    state.result = 'quit';
+    tui.quit = true;
+    return;
+  }
+  if (key.name === 'up') {
+    state.index = Math.max(0, state.index - 1);
+    renderMenu(state, items, tui);
+  } else if (key.name === 'down') {
+    state.index = Math.min(items.length - 1, state.index + 1);
+    renderMenu(state, items, tui);
+  } else if (key.name === 'return' || key.name === 'enter') {
+    const item = items[state.index];
+    if (!item?.enabled) return;
+    state.result = item.id;
+    tui.quit = true;
+  }
+}
+
+function renderMenu(state: MenuState, items: MenuItem[], tui: Tui): void {
+  const W = output.columns || 80;
+  const innerW = Math.min(Math.max(W - 6, 40), 64);
+
+  const inner: string[] = [
+    `${ANSI.bold}${ANSI.cyan}BhooAI Nexus${ANSI.reset}`,
+    `${ANSI.dim}Full-stack framework — one config, one CLI, multi-app monorepo${ANSI.reset}`,
+    '',
+    `${ANSI.bold}${ANSI.green}Welcome!${ANSI.reset} ${ANSI.dim}What do you want to do?${ANSI.reset}`,
+    '',
+  ];
+
+  const labelW = 18;
+  items.forEach((item, i) => {
+    const sel = i === state.index;
+    const marker = sel ? `${ANSI.cyan}▶${ANSI.reset}` : ' ';
+    const label = sel ? `${ANSI.bold}${item.label}${ANSI.reset}` : item.label;
+    const color = item.enabled ? '' : ANSI.dimGray;
+    const desc = item.enabled ? item.desc : '— not available here —';
+    inner.push(`${color} ${marker} ${fitCell(label, labelW)} ${ANSI.dim}${desc}${ANSI.reset}`);
+  });
+
+  const rows = ['', ...boxAround(inner, innerW), ''];
+  rows.push(`${ANSI.dim}  ↑/↓ move · Enter select · q quit${ANSI.reset}`);
+  tui.draw(rows);
+}
+
+function printDocs(): void {
+  console.log(`
+nexus — BhooAI Nexus CLI (v2)
+
+Project lifecycle:
+  init [name]                    Scaffold a new project (guided wizard)
+  dev                            Start dev services (console)
+  build [--target <app>|all]     Build for production
+  test [--watch|--e2e]           Run tests
+  doctor                         Environment health check
+
+Multi-app scaffolding:
+  add backend <name>   ·   add frontend <name>   ·   add route <name> --app <backend>
+
+Generators (make:*): route, controller, model, service, repository, middleware,
+  validator, job, event, listener, policy, resource, request, mail, room,
+  subgraph, seeder, migration, provider, plugin
+
+Data / queue: db:seed · db:migrate · db:rollback · queue:work · queue:retry
+
+Run \`nexus <command> --help\` for flags (where implemented).
+`);
+}
+
+async function pause(): Promise<void> {
+  await new Promise((r) => setTimeout(r, 600));
+}