@bhooai/nexus-cli 2.0.11 → 2.0.13

package/package.json

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

package/src/commands/add.ts

@@ -81,24 +81,16 @@ export async function run(ctx: CommandContext): Promise<void> {
   }
 }
 
-async function addBackend(ctx: CommandContext): Promise<void> {
-  const name = ctx.args._[1];
-  if (!name) {
-    console.error('Usage: nexus add backend <name>');
-    process.exitCode = 1;
-    return;
-  }
+/**
+ * Programmatic backend creator — used by CLI and example _setup.mjs.
+ * If the directory already exists but is incomplete (e.g. overlay-only),
+ * missing files are filled in and port is ensured.
+ */
+export async function createBackendApp(projectRoot: string, name: string): Promise<{ appName: string; port: number; created: boolean }> {
   const slug = slugify(name);
   const appName = `backend-${slug}`;
-  const projectRoot = process.cwd();
   const appDir = join(projectRoot, 'apps', appName);
-
-  if (existsSync(appDir)) {
-    console.error(`✗ ${appName} already exists`);
-    process.exitCode = 1;
-    return;
-  }
-
+  const existed = existsSync(appDir);
   const port = await ensurePort(projectRoot, appName);
 
   // Create directory structure (shared with init.ts's BACKEND_FOLDERS constant)
@@ -106,73 +98,101 @@ async function addBackend(ctx: CommandContext): Promise<void> {
     await mkdir(join(appDir, f), { recursive: true });
   }
 
-  // main.ts — pass the assigned port via env (NEXUS_PORT) so dev and prod use the same.
-  await writeFile(join(appDir, 'src', 'main.ts'),
-    BACKEND_MAIN_TEMPLATE.replace(/<%= appName %>/g, appName));
+  // main.ts — only if missing (preserve user edits on re-run)
+  const mainPath = join(appDir, 'src', 'main.ts');
+  if (!existsSync(mainPath)) {
+    await writeFile(mainPath, BACKEND_MAIN_TEMPLATE.replace(/<%= appName %>/g, appName));
+  }
 
-  // routes/index.ts
-  await writeFile(join(appDir, 'src', 'routes', 'index.ts'),
-    BACKEND_ROUTE_TEMPLATE.replace(/<%= appName %>/g, appName));
+  // routes/index.ts — only if missing
+  const routePath = join(appDir, 'src', 'routes', 'index.ts');
+  if (!existsSync(routePath)) {
+    await writeFile(routePath, BACKEND_ROUTE_TEMPLATE.replace(/<%= appName %>/g, appName));
+  }
 
-  // package.json
-  await writeFile(join(appDir, 'package.json'), JSON.stringify({
-    name: `@${slug}/${appName}`,
-    private: true,
-    version: '0.1.0',
-    type: 'module',
-    scripts: { dev: 'tsx watch src/main.ts' },
-  }, null, 2));
+  // package.json — only if missing
+  const pkgPath = join(appDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    await writeFile(pkgPath, JSON.stringify({
+      name: `@${slug}/${appName}`,
+      private: true,
+      version: '0.1.0',
+      type: 'module',
+      scripts: { dev: 'tsx watch src/main.ts' },
+    }, null, 2));
+  }
 
-  console.log(`✓ Created apps/${appName}`);
-  console.log(`  srcRoot: apps/${appName}/src`);
-  console.log(`  port:    ${port} (persisted in .nexus-ports.json)`);
-  console.log(`\nAdd to apps/dev list when you want \`nexus dev\` to pick it up.`);
+  return { appName, port, created: !existed };
 }
 
-async function addFrontend(ctx: CommandContext): Promise<void> {
+async function addBackend(ctx: CommandContext): Promise<void> {
   const name = ctx.args._[1];
   if (!name) {
-    console.error('Usage: nexus add frontend <name> [--for <backend>]');
+    console.error('Usage: nexus add backend <name>');
     process.exitCode = 1;
     return;
   }
   const slug = slugify(name);
-  const appName = `frontend-${slug}`;
+  const appName = `backend-${slug}`;
   const projectRoot = process.cwd();
   const appDir = join(projectRoot, 'apps', appName);
 
-  if (existsSync(appDir)) {
+  if (existsSync(appDir) && existsSync(join(appDir, 'src', 'main.ts')) && existsSync(join(appDir, 'package.json'))) {
     console.error(`✗ ${appName} already exists`);
     process.exitCode = 1;
     return;
   }
 
-  // Pick backend target
-  let backend = ctx.args.flags.for as string | undefined;
+  const { port, created } = await createBackendApp(projectRoot, name);
+  if (created) {
+    console.log(`✓ Created apps/${appName}`);
+  } else {
+    console.log(`✓ Repaired apps/${appName} (filled missing scaffold files)`);
+  }
+  console.log(`  srcRoot: apps/${appName}/src`);
+  console.log(`  port:    ${port} (persisted in .nexus-ports.json)`);
+  console.log(`\nAdd to apps/dev list when you want \`nexus dev\` to pick it up.`);
+}
+
+/**
+ * Programmatic frontend creator — used by CLI and example _setup.mjs.
+ * If the directory already exists but is incomplete, missing files are filled in.
+ */
+export async function createFrontendApp(projectRoot: string, name: string, opts: { for?: string } = {}): Promise<{ appName: string; port: number; backend: string; backendPort: number; created: boolean }> {
+  const slug = slugify(name);
+  const appName = `frontend-${slug}`;
+  const appDir = join(projectRoot, 'apps', appName);
+  const existed = existsSync(appDir);
+
+  let backend = opts.for;
   if (!backend && isInteractive()) {
     backend = await pickBackend(projectRoot);
   }
-  backend = backend ?? 'backend-main';
+  backend = backend ?? 'backend';
 
   const port = await ensurePort(projectRoot, appName);
-
   await mkdir(join(appDir, 'src'), { recursive: true });
 
-  // package.json
-  await writeFile(join(appDir, 'package.json'), JSON.stringify({
-    name: `@${slug}/${appName}`,
-    private: true,
-    version: '0.1.0',
-    type: 'module',
-    scripts: {
-      dev: `vite --port ${port}`,
-      build: 'vite build',
-    },
-  }, null, 2));
+  // package.json — only if missing
+  const pkgPath = join(appDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    await writeFile(pkgPath, JSON.stringify({
+      name: `@${slug}/${appName}`,
+      private: true,
+      version: '0.1.0',
+      type: 'module',
+      scripts: {
+        dev: `vite --port ${port}`,
+        build: 'vite build',
+      },
+    }, null, 2));
+  }
 
-  // vite.config.ts — resolve the backend's port from the registry.
-  const backendPort = (await lookupPort(projectRoot, backend)) ?? await ensurePort(projectRoot, backend);
-  await writeFile(join(appDir, 'vite.config.ts'), `import { defineConfig } from 'vite';
+  // vite.config.ts — only if missing (preserve user edits)
+  const vitePath = join(appDir, 'vite.config.ts');
+  if (!existsSync(vitePath)) {
+    const backendPort = (await lookupPort(projectRoot, backend)) ?? await ensurePort(projectRoot, backend);
+    await writeFile(vitePath, `import { defineConfig } from 'vite';
 
 // Backend host the dev proxy targets. Override with NEXUS_BACKEND_HOST when
 // deploying to a VPS (or running the backend on another machine). Defaults to
@@ -190,16 +210,25 @@ export default defineConfig({
   },
 });
 `);
+  }
 
-  // index.html + main.tsx
-  await writeFile(join(appDir, 'index.html'), `<!doctype html>
+  // index.html — only if missing
+  const htmlPath = join(appDir, 'index.html');
+  if (!existsSync(htmlPath)) {
+    await writeFile(htmlPath, `<!doctype html>
 <html lang="en">
 <head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>${name}</title></head>
 <body><div id="root"></div><script type="module" src="/src/main.tsx"></script></body>
 </html>
 `);
+  }
 
-  await writeFile(join(appDir, 'src', 'main.tsx'), `import React from 'react';
+  // src/main.tsx — only if missing
+  const mainPath = join(appDir, 'src', 'main.tsx');
+  if (!existsSync(mainPath)) {
+    const backendPort = (await lookupPort(projectRoot, backend)) ?? port;
+    void backendPort;
+    await writeFile(mainPath, `import React from 'react';
 import { createRoot } from 'react-dom/client';
 
 function App() {
@@ -212,8 +241,42 @@ function App() {
 const el = document.getElementById('root');
 if (el) createRoot(el).render(<App />);
 `);
+  }
 
-  console.log(`✓ Created apps/${appName} (port ${port}, proxying to ${backend}:${backendPort})`);
+  const backendPort = (await lookupPort(projectRoot, backend)) ?? await ensurePort(projectRoot, backend);
+  return { appName, port, backend, backendPort, created: !existed };
+}
+
+async function addFrontend(ctx: CommandContext): Promise<void> {
+  const name = ctx.args._[1];
+  if (!name) {
+    console.error('Usage: nexus add frontend <name> [--for <backend>]');
+    process.exitCode = 1;
+    return;
+  }
+  const slug = slugify(name);
+  const appName = `frontend-${slug}`;
+  const projectRoot = process.cwd();
+  const appDir = join(projectRoot, 'apps', appName);
+
+  if (existsSync(appDir) && existsSync(join(appDir, 'package.json')) && existsSync(join(appDir, 'vite.config.ts'))) {
+    console.error(`✗ ${appName} already exists`);
+    process.exitCode = 1;
+    return;
+  }
+
+  let backend = ctx.args.flags.for as string | undefined;
+  if (!backend && isInteractive()) {
+    backend = await pickBackend(projectRoot);
+  }
+  backend = backend ?? 'backend';
+
+  const { port, backendPort, created } = await createFrontendApp(projectRoot, name, { for: backend });
+  if (created) {
+    console.log(`✓ Created apps/${appName} (port ${port}, proxying to ${backend}:${backendPort})`);
+  } else {
+    console.log(`✓ Repaired apps/${appName} (port ${port}, proxying to ${backend}:${backendPort})`);
+  }
 }
 
 async function addRoute(ctx: CommandContext): Promise<void> {

package/src/commands/init.ts

@@ -3,16 +3,19 @@
  *
  *   nexus init              open the full-screen setup wizard
  *   nexus init my-app       open the wizard with the name pre-filled
+ *   nexus init --dev my-app point bhooai-nexus + @bhooai/* to local file: (live symlink)
  *
  * Always interactive (the wizard). Requires a TTY; in a non-interactive
  * context it prints a message and exits non-zero. `--no-install` skips the
  * dependency install, `--force` overwrites an existing target directory.
+ * `--dev` rewrites bhooai-nexus + @bhooai/* to file:../../PACKAGES/bhooai-nexus
+ * (relative) and runs `npm link` for live symlink.
  */
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join, resolve, dirname, relative, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import type { CommandContext } from '../dispatcher.js';
 import { confirm } from '../prompts.js';
 import { randomSecret } from '../util.js';
@@ -41,6 +44,12 @@ interface InitVars {
 
 export async function run(ctx: CommandContext): Promise<void> {
   const args = ctx.args;
+  // Support --dev before or after name: `nexus init --dev myapp` and `nexus init myapp --dev`
+  const isDev = !!args.flags.dev;
+  // If --dev was parsed as positional (unlikely), also check raw argv
+  const rawHasDev = ctx.argv.includes('--dev');
+  const devMode = isDev || rawHasDev;
+  // Normalize name when --dev is before name: args._[0] is still the name (parseArgs strips flags)
   const prefillName = (args._[0] as string) ?? '';
 
   // `nexus init` is always the guided wizard — it needs a terminal.
@@ -108,11 +117,46 @@ export async function run(ctx: CommandContext): Promise<void> {
   // 2b. Create the full Laravel-style folder tree for the default backend.
   await ensureBackendFolderTree(join(targetDir, 'apps', 'backend'));
 
+  // 2c. Run example _setup.mjs before overlay (if present) — e.g. multi-app scaffolds extra apps.
+  // Warn-and-continue on failure; excluded from template copy.
+  if (vars.example && vars.example !== 'empty' && result.examplesDir) {
+    const exampleDir = join(result.examplesDir, vars.example);
+    const setupPath = join(exampleDir, '_setup.mjs');
+    if (existsSync(setupPath)) {
+      try {
+        const mod = await import(pathToFileURL(setupPath).href);
+        const fn = (mod as { default?: (ctx: SetupContext) => Promise<void> }).default ?? (mod as { setup?: (ctx: SetupContext) => Promise<void> }).setup;
+        if (typeof fn === 'function') {
+          const { createBackendApp, createFrontendApp } = await import('./add.js');
+          const ctx: SetupContext = {
+            targetDir,
+            projectRoot: targetDir,
+            vars,
+            utils: {
+              addBackend: (name: string) => createBackendApp(targetDir, name),
+              addFrontend: (name: string, opts?: { for?: string }) => createFrontendApp(targetDir, name, opts),
+              log: (msg: string) => console.log(msg),
+            },
+          };
+          await fn(ctx);
+          console.log(`✓ Example setup script ran: ${vars.example}/_setup.mjs`);
+        } else {
+          console.warn(`! Example setup script has no default export: ${setupPath}`);
+        }
+      } catch (e) {
+        console.warn(`! Example setup script failed for "${vars.example}": ${(e as Error).message} — continuing.`);
+      }
+    }
+  }
+
   // 3. Apply example overlay (if not 'empty').
   if (vars.example && vars.example !== 'empty') {
     const exampleDir = join(result.examplesDir, vars.example);
     if (result.examplesDir && existsSync(exampleDir)) {
-      await renderTemplateTree(exampleDir, targetDir, vars as unknown as Record<string, unknown>);
+      // Exclude the setup script itself from being copied into the project
+      await renderTemplateTree(exampleDir, targetDir, vars as unknown as Record<string, unknown>, {
+        exclude: (rel) => rel === '_setup.mjs' || rel === '_setup.js' || rel.endsWith('/_setup.mjs') || rel.endsWith('/_setup.js'),
+      });
       console.log(`✓ Applied example: ${vars.example}`);
     } else {
       console.warn(`! Example "${vars.example}" not found — continuing with empty scaffold.`);
@@ -133,10 +177,22 @@ export async function run(ctx: CommandContext): Promise<void> {
     await writeFile(envPath, buildEnvFile(vars), 'utf-8');
   }
 
+  // 4b. --dev: rewrite bhooai-nexus + @bhooai/* to local file: + live symlink
+  if (devMode) {
+    const rewrote = await rewriteToLocalFileDeps(targetDir);
+    if (rewrote.count > 0) {
+      console.log(`\n[dev] Rewrote ${rewrote.count} deps to local file: (${rewrote.root})`);
+      for (const { name, spec } of rewrote.entries) console.log(`  ${name} → ${spec}`);
+    } else {
+      console.warn(`\n[dev] No local bhooai-nexus found — keeping registry versions.`);
+    }
+  }
+
   // 5. Install dependencies (unless --no-install).
   const skipInstall = !!args.flags['no-install'];
   if (skipInstall) {
     console.log(`\n( --no-install given — run \`npm install\` in ${targetDir} manually. )`);
+    if (devMode) console.log(`[dev] After manual install, run: npm link --prefix "${targetDir}" bhooai-nexus && npm link --prefix "${targetDir}" @bhooai/* (or re-run with --dev)`);
   } else {
     console.log(`\nInstalling dependencies in ${targetDir}...\n`);
     const code = await runNpmInstall(targetDir);
@@ -145,6 +201,12 @@ export async function run(ctx: CommandContext): Promise<void> {
       process.exitCode = code ?? 1;
     } else {
       console.log('\n✓ Dependencies installed.');
+      if (devMode) {
+        console.log(`\n[dev] Linking local packages for live symlink...\n`);
+        const linkCode = await runNpmLinkForDev(targetDir);
+        if (linkCode === 0) console.log(`\n[dev] Live symlink ready — edits in ${resolveLocalBhooaiNexusRoot() ?? 'PACKAGES/bhooai-nexus'} reflect instantly.`);
+        else console.warn(`\n[dev] npm link failed (code ${linkCode}) — fallback to file: copy (re-run npm install after edits).`);
+      }
     }
   }
 
@@ -182,6 +244,96 @@ function runNpmInstall(dir: string): Promise<number> {
   });
 }
 
+function resolveLocalBhooaiNexusRoot(): string | null {
+  // Candidates in dev machine order — first existing wins
+  const candidates = [
+    resolve(HERE, '..', '..', '..', '..'), // from packages/nexus-cli/src/commands -> repo root (PACKAGES/bhooai-nexus)
+    'C:/server/PACKAGES/bhooai-nexus',
+    'C:\\server\\PACKAGES\\bhooai-nexus',
+    resolve(process.cwd(), 'PACKAGES/bhooai-nexus'),
+    resolve(process.cwd(), '../PACKAGES/bhooai-nexus'),
+  ];
+  for (const p of candidates) {
+    try { if (existsSync(join(p, 'package.json')) && existsSync(join(p, 'packages', 'nexus-core', 'package.json'))) return p; } catch {}
+  }
+  return null;
+}
+
+async function rewriteToLocalFileDeps(targetDir: string): Promise<{ count: number; root: string; entries: Array<{ name: string; spec: string }> }> {
+  const localRoot = resolveLocalBhooaiNexusRoot();
+  if (!localRoot) return { count: 0, root: '', entries: [] };
+  const pkgPath = join(targetDir, 'package.json');
+  let raw: string;
+  try { raw = await readFile(pkgPath, 'utf8'); } catch { return { count: 0, root: localRoot, entries: [] }; }
+  let pkg: any;
+  try { pkg = JSON.parse(raw); } catch { return { count: 0, root: localRoot, entries: [] }; }
+  const entries: Array<{ name: string; spec: string }> = [];
+  const toFileSpec = (abs: string) => {
+    let rel = relative(targetDir, abs).replace(/\\/g, '/');
+    if (!rel.startsWith('.')) rel = './' + rel;
+    // Use forward slashes for file: spec (npm supports both, but posix is more portable)
+    return `file:${rel}`;
+  };
+  const maybeRewrite = (obj: Record<string, string> | undefined) => {
+    if (!obj) return;
+    for (const name of Object.keys(obj)) {
+      if (name === 'bhooai-nexus') {
+        const spec = toFileSpec(localRoot);
+        obj[name] = spec;
+        entries.push({ name, spec });
+      } else if (name.startsWith('@bhooai/')) {
+        const short = name.replace('@bhooai/', '');
+        // Map @bhooai/nexus-* -> packages/nexus-<short> ; @bhooai/nexus -> packages/nexus-core? but we keep generic
+        const pkgDir = join(localRoot, 'packages', short === 'nexus' ? 'nexus-core' : short.startsWith('nexus-') ? short : `nexus-${short}`);
+        // Fallback: try packages/<name without @bhooai/> and packages/nexus-<name>
+        const candidates = [join(localRoot, 'packages', name.replace('@bhooai/', '')), join(localRoot, 'packages', `nexus-${short}`), pkgDir];
+        let found: string | null = null;
+        for (const c of candidates) if (existsSync(join(c, 'package.json'))) { found = c; break; }
+        if (found) {
+          const spec = toFileSpec(found);
+          obj[name] = spec;
+          entries.push({ name, spec });
+        }
+      }
+    }
+  };
+  maybeRewrite(pkg.dependencies);
+  maybeRewrite(pkg.devDependencies);
+  if (entries.length) await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  return { count: entries.length, root: localRoot, entries };
+}
+
+async function runNpmLinkForDev(targetDir: string): Promise<number> {
+  const localRoot = resolveLocalBhooaiNexusRoot();
+  if (!localRoot) return 1;
+  // Ensure global link exists for bhooai-nexus (best-effort)
+  const linkRoot = await new Promise<number>((resolve) => {
+    const c = spawn('npm', ['link'], { cwd: localRoot, stdio: 'inherit', shell: process.platform === 'win32' });
+    c.on('error', () => resolve(1));
+    c.on('exit', (code) => resolve(code ?? 1));
+  });
+  if (linkRoot !== 0) console.warn(`[dev] npm link in ${localRoot} failed — continuing with file: only`);
+  // Link bhooai-nexus into target
+  const linkTarget = await new Promise<number>((resolve) => {
+    const c = spawn('npm', ['link', 'bhooai-nexus'], { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
+    c.on('error', () => resolve(1));
+    c.on('exit', (code) => resolve(code ?? 1));
+  });
+  // Also link each @bhooai/* that we rewrote to file: (best-effort, ignore failures)
+  try {
+    const pkgRaw = await readFile(join(targetDir, 'package.json'), 'utf8');
+    const pkg = JSON.parse(pkgRaw);
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    for (const name of Object.keys(allDeps)) if (name.startsWith('@bhooai/')) {
+      await new Promise<void>((r) => {
+        const c = spawn('npm', ['link', name], { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
+        c.on('exit', () => r()); c.on('error', () => r());
+      });
+    }
+  } catch {}
+  return linkTarget;
+}
+
 /** The canonical 26-folder Laravel-style tree under a backend's src/. Exported for `add.ts`. */
 export const BACKEND_FOLDERS = [
   'src/routes', 'src/graphql', 'src/ws',
@@ -196,6 +348,17 @@ export const BACKEND_FOLDERS = [
   'storage', 'storage/uploads', 'storage/private', 'storage/temp', 'storage/cache', 'storage/logs',
 ];
 
+export interface SetupContext {
+  targetDir: string;
+  projectRoot: string;
+  vars: InitVars;
+  utils: {
+    addBackend: (name: string) => Promise<{ appName: string; port: number; created: boolean }>;
+    addFrontend: (name: string, opts?: { for?: string }) => Promise<{ appName: string; port: number; backend: string; backendPort: number; created: boolean }>;
+    log: (msg: string) => void;
+  };
+}
+
 async function ensureBackendFolderTree(backendDir: string): Promise<void> {
   for (const f of BACKEND_FOLDERS) {
     await mkdir(join(backendDir, f), { recursive: true });
@@ -236,5 +399,5 @@ ${vars.aiProviders.filter((p) => p !== 'ollama').map((p) => `# NEXUS_AI_${p.toUp
 `;
 }
 
-export const description = 'Scaffold a new Nexus project (guided wizard)';
-export const usage = 'nexus init [name] [--no-install] [--force]';
+export const description = 'Scaffold a new Nexus project (guided wizard) — --dev uses local file: + npm link';
+export const usage = 'nexus init [name] [--dev] [--no-install] [--force]';

package/src/devPanel.ts

@@ -35,6 +35,8 @@ export interface DevPanelOptions {
 
 type Tab = 'services' | 'logs' | 'commands' | 'features' | 'settings';
 
+let isCapturing = false;
+
 const TABS: Array<{ id: Tab; label: string }> = [
   { id: 'services', label: 'Services' },
   { id: 'logs', label: 'Logs' },
@@ -121,16 +123,27 @@ export async function startDevPanel(opts: DevPanelOptions): Promise<void> {
   };
 
   let lastRender = 0;
+  let throttleTimer: ReturnType<typeof setTimeout> | null = null;
 
   function throttledRender(): void {
+    if (isCapturing || state.quit) return;
     const now = Date.now();
-    if (now - lastRender < 80) return;
+    if (now - lastRender < 80) {
+      if (!throttleTimer) {
+        throttleTimer = setTimeout(() => {
+          throttleTimer = null;
+          lastRender = Date.now();
+          render();
+        }, 80);
+      }
+      return;
+    }
     lastRender = now;
     render();
   }
 
   function render(): void {
-    if (state.quit) return;
+    if (state.quit || isCapturing) return;
     tui.draw(buildRows(state, services, palette, projectRoot), helpText(state));
   }
 
@@ -146,6 +159,7 @@ export async function startDevPanel(opts: DevPanelOptions): Promise<void> {
   render();
 
   await tui.wait();
+  if (throttleTimer) { clearTimeout(throttleTimer); throttleTimer = null; }
   tui.exit();
   services.onLog = null;
   opts.onQuit?.();
@@ -206,12 +220,6 @@ function onKey(state: PanelState, str: string, key: KeyInfo, ctx: Ctx): void {
     ctx.redraw();
     return;
   }
-  if (key.name === 'q') {
-    state.confirmQuit = true;
-    state.quitIndex = 0;
-    ctx.redraw();
-    return;
-  }
   if (key.name === 'escape') {
     if (state.tab === 'commands' && state.cmdFilter) {
       state.cmdFilter = '';
@@ -231,7 +239,8 @@ function onKey(state: PanelState, str: string, key: KeyInfo, ctx: Ctx): void {
   }
   if (state.showHelp) return;
 
-  // Type-to-filter in the Commands tab.
+  // Type-to-filter in the Commands tab — must be before single-letter shortcuts
+  // so 'q','s','t','r','l','a','d' act as filter characters instead of hotkeys.
   if (state.tab === 'commands' && str && !key.ctrl && !key.meta && str.length === 1 && str !== '?') {
     state.cmdFilter += str;
     const fp = filteredPalette(ctx.palette, state.cmdFilter);
@@ -255,6 +264,12 @@ function onKey(state: PanelState, str: string, key: KeyInfo, ctx: Ctx): void {
     ctx.redraw();
     return;
   }
+  if (key.name === 'q') {
+    state.confirmQuit = true;
+    state.quitIndex = 0;
+    ctx.redraw();
+    return;
+  }
 
   switch (key.name) {
     case 'tab': {
@@ -286,13 +301,13 @@ function onKey(state: PanelState, str: string, key: KeyInfo, ctx: Ctx): void {
       void activate(state, ctx);
       break;
     case 's':
-      ctx.services.start(ctx.services.services[state.svcIndex]?.name ?? '');
+      if (state.tab === 'services' || state.tab === 'logs') ctx.services.start(ctx.services.services[state.svcIndex]?.name ?? '');
       break;
     case 't':
-      ctx.services.stop(ctx.services.services[state.svcIndex]?.name ?? '');
+      if (state.tab === 'services' || state.tab === 'logs') ctx.services.stop(ctx.services.services[state.svcIndex]?.name ?? '');
       break;
     case 'r':
-      ctx.services.restart(ctx.services.services[state.svcIndex]?.name ?? '');
+      if (state.tab === 'services' || state.tab === 'logs') ctx.services.restart(ctx.services.services[state.svcIndex]?.name ?? '');
       break;
     case 'l':
       state.tab = 'logs';
@@ -394,7 +409,10 @@ async function runSelectedCommand(state: PanelState, cmd: CommandItem, inlineArg
   ctx.redraw();
 
   if (cmd.interactive) {
-    // Suspend panel → real TTY → resume.
+    // Suspend panel → real TTY → resume. Suppress log redraws while suspended
+    const prevLog = ctx.services.onLog;
+    ctx.services.onLog = null;
+    isCapturing = true;
     ctx.tui.suspend();
     try {
       const bin = resolveCliBin();
@@ -404,6 +422,8 @@ async function runSelectedCommand(state: PanelState, cmd: CommandItem, inlineArg
       push(state, `✗ ${cmd.name} failed: ${(err as Error).message}`);
     }
     ctx.tui.resume();
+    isCapturing = false;
+    ctx.services.onLog = prevLog;
     ctx.redraw();
     return;
   }
@@ -411,6 +431,9 @@ async function runSelectedCommand(state: PanelState, cmd: CommandItem, inlineArg
   const argv = inlineArgs ? inlineArgs.trim().split(/\s+/) : [];
   const origOut = process.stdout.write.bind(process.stdout);
   const origErr = process.stderr.write.bind(process.stderr);
+  const prevLog2 = ctx.services.onLog;
+  isCapturing = true;
+  ctx.services.onLog = null;
   const sink = (chunk: string | Buffer) => {
     push(state, String(chunk));
     return true;
@@ -425,6 +448,8 @@ async function runSelectedCommand(state: PanelState, cmd: CommandItem, inlineArg
   } finally {
     (process.stdout as unknown as { write: Function }).write = origOut;
     (process.stderr as unknown as { write: Function }).write = origErr;
+    isCapturing = false;
+    ctx.services.onLog = prevLog2;
   }
   ctx.redraw();
 }
@@ -437,12 +462,17 @@ function push(state: PanelState, text: string): void {
 }
 
 async function runSpawned(cmd: string, args: string[], ctx: Ctx): Promise<void> {
+  const prevLog = ctx.services.onLog;
+  ctx.services.onLog = null;
+  isCapturing = true;
   ctx.tui.suspend();
   try {
     const bin = resolveCliBin();
     await spawnNode(bin, [cmd, ...args]);
   } catch { /* ignore */ }
   ctx.tui.resume();
+  isCapturing = false;
+  ctx.services.onLog = prevLog;
   ctx.redraw();
 }
 
@@ -530,23 +560,6 @@ function prevSelectable(list: PaletteRow[], current: number, dir: number): numbe
 function filteredPalette(palette: PaletteRow[], filter: string): PaletteRow[] {
   if (!filter) return palette;
   const q = filter.toLowerCase();
-  const result: PaletteRow[] = [];
-  let currentHeader: PaletteRow | null = null;
-  let headerHasMatch = false;
-  for (const row of palette) {
-    if (row.kind === 'header') {
-      if (currentHeader && headerHasMatch) result.push(currentHeader);
-      currentHeader = row;
-      headerHasMatch = false;
-      continue;
-    }
-    if (row.cmd.name.toLowerCase().includes(q) || row.cmd.desc.toLowerCase().includes(q)) {
-      headerHasMatch = true;
-      result.push(row);
-    }
-  }
-  if (currentHeader && headerHasMatch) result.push(currentHeader);
-  // Re-headers got pushed to the end; rebuild with headers in the right place.
   const ordered: PaletteRow[] = [];
   let pendingHeader: PaletteRow | null = null;
   for (const row of palette) {
@@ -819,5 +832,5 @@ function helpText(state: PanelState): string {
 }
 
 function clamp(n: number, lo: number, hi: number): number {
-  return Math.min(Math.max(n, lo), Math.max(lo, hi));
+  return Math.min(Math.max(n, lo), hi);
 }

package/src/devServiceManager.ts

@@ -219,12 +219,23 @@ export class ServiceManager {
   }
 
   private push(svc: ManagedService, text: string, source: 'stdout' | 'stderr' | 'system' = 'stdout'): void {
-    const lines = text.split(/\r?\n/);
+    // Sanitize terminal control sequences that would otherwise move the cursor
+    // when rendered in the TUI panel (e.g. \r progress bars, clear lines, alt buffer)
+    const sanitized = text
+      .replace(/\r/g, '')
+      .replace(/\x1b\[\?25[hl]/g, '')
+      .replace(/\x1b\[\?1049[hl]/g, '')
+      .replace(/\x1b\[2[JK]/g, '')
+      .replace(/\x1b\[[0-9;]*[ABCDGKHf]/g, '');
+    const lines = sanitized.split(/\n/);
     for (const line of lines) {
       if (!line.trim()) continue;
+      // Keep color codes for panel rendering, but strip for level detection
+      const stripped = line.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
+      if (!stripped.trim()) continue;
       svc.logBuffer.push(line);
       if (svc.logBuffer.length > MAX_LOG_LINES) svc.logBuffer.shift();
-      this.allLogs.push({ service: svc.name, ts: Date.now(), source, level: detectLevel(line), line });
+      this.allLogs.push({ service: svc.name, ts: Date.now(), source, level: detectLevel(stripped), line });
       if (this.allLogs.length > MAX_ALL_LOGS) this.allLogs.shift();
     }
     this.onLog?.(svc.name);

package/src/dispatcher.ts

@@ -75,7 +75,7 @@ function printHelp(): void {
 Usage: nexus <command> [options]
 
 Project lifecycle:
-  init [name] [--no-install] [--force]            Scaffold a new project (guided wizard)
+  init [name] [--dev] [--no-install] [--force]    Scaffold a new project (guided wizard) — --dev uses local file: + npm link
   dev [--only a,b]                                 Start dev services
   build [--target <app>|all]                       Build for production
   test [--watch|--e2e]                             Run tests

package/src/launcher.ts

@@ -95,10 +95,22 @@ function handleMenuKey(state: MenuState, items: MenuItem[], tui: Tui, _str: stri
     return;
   }
   if (key.name === 'up') {
-    state.index = Math.max(0, state.index - 1);
+    let next = state.index;
+    for (let i = 0; i < items.length; i++) {
+      next = Math.max(0, next - 1);
+      if (items[next]?.enabled) break;
+      if (next === 0) break;
+    }
+    state.index = next;
     renderMenu(state, items, tui);
   } else if (key.name === 'down') {
-    state.index = Math.min(items.length - 1, state.index + 1);
+    let next = state.index;
+    for (let i = 0; i < items.length; i++) {
+      next = Math.min(items.length - 1, next + 1);
+      if (items[next]?.enabled) break;
+      if (next === items.length - 1) break;
+    }
+    state.index = next;
     renderMenu(state, items, tui);
   } else if (key.name === 'return' || key.name === 'enter') {
     const item = items[state.index];

package/src/templating/tree.ts

@@ -42,7 +42,9 @@ async function renderDir(
     const childRel = rel ? `${rel}/${e.name}` : e.name;
     if (opts.exclude?.(childRel)) continue;
 
-    const renderedName = isTemplateName(e.name) ? stripTemplateSuffix(e.name) : e.name;
+    // Mail runtime EJS (mail/templates/*.ejs) must be copied verbatim, not rendered with InitVars
+    const isMailRuntimeEjs = (src.includes('mail') && src.includes('templates') && e.name.endsWith('.ejs')) || childRel.includes('mail/templates/');
+    const renderedName = isMailRuntimeEjs ? e.name : (isTemplateName(e.name) ? stripTemplateSuffix(e.name) : e.name);
     const fileName = renderedName === 'gitignore' ? '.gitignore'
       : renderedName === 'dockerignore' ? '.dockerignore'
       : renderedName;
@@ -54,7 +56,7 @@ async function renderDir(
     } else if (e.isFile()) {
       try {
         const raw = await readFile(src, 'utf-8');
-        const isTemplate = isTemplateName(e.name) || raw.includes('<%');
+        const isTemplate = !isMailRuntimeEjs && (isTemplateName(e.name) || raw.includes('<%'));
         const content = isTemplate ? renderString(raw, vars) : raw;
         await mkdir(dirname(dest), { recursive: true });
         await writeFile(dest, content, 'utf-8');

package/src/tui.ts

@@ -91,27 +91,40 @@ export class Tui {
       readline.emitKeypressEvents(input);
       input.on('keypress', this.keypress);
     }
-    output.write(ANSI.altOn + ANSI.hideCursor);
+    if (output.isTTY) output.write(ANSI.altOn + ANSI.hideCursor + ANSI.clear);
     process.on('SIGINT', this.onSignal);
     process.on('SIGTERM', this.onSignal);
   }
 
   /** Leave the screen so a child process can own the TTY. */
   suspend(): void {
-    input.setRawMode?.(false);
-    output.write(ANSI.altOff + ANSI.showCursor);
+    input.removeListener('keypress', this.keypress);
+    process.removeListener('SIGINT', this.onSignal);
+    process.removeListener('SIGTERM', this.onSignal);
+    if (input.isTTY) input.setRawMode?.(false);
+    if (output.isTTY) output.write(ANSI.altOff + ANSI.showCursor);
   }
 
   resume(): void {
-    input.setRawMode?.(true);
-    input.resume?.();
-    output.write(ANSI.altOn + ANSI.hideCursor);
+    // Ensure idempotent — remove stale handlers before re-adding.
+    input.removeListener('keypress', this.keypress);
+    process.removeListener('SIGINT', this.onSignal);
+    process.removeListener('SIGTERM', this.onSignal);
+    if (input.isTTY) {
+      input.setRawMode?.(true);
+      input.resume?.();
+      readline.emitKeypressEvents(input);
+      input.on('keypress', this.keypress);
+    }
+    process.on('SIGINT', this.onSignal);
+    process.on('SIGTERM', this.onSignal);
+    if (output.isTTY) output.write(ANSI.altOn + ANSI.hideCursor + ANSI.clear);
   }
 
   exit(): void {
     input.removeListener('keypress', this.keypress);
-    input.setRawMode?.(false);
-    output.write(ANSI.altOff + ANSI.showCursor);
+    if (input.isTTY) input.setRawMode?.(false);
+    if (output.isTTY) output.write(ANSI.altOff + ANSI.showCursor);
     process.removeListener('SIGINT', this.onSignal);
     process.removeListener('SIGTERM', this.onSignal);
   }
@@ -119,25 +132,71 @@ export class Tui {
   /** Paint a frame. `rows` are the body; `footer` is the final status line. */
   draw(rows: string[], footer = ''): void {
     const H = output.rows || 24;
+    const W = output.columns || 80;
     const body = fitLines(rows);
-    let out = ANSI.clear;
+    const clippedFooter = footer ? clipAnsi(footer, W) : '';
+    let out = '';
+    if (output.isTTY) out += ANSI.clear;
     out += body.join('\n');
-    out += ANSI.move(H, 1);
-    out += footer;
-    output.write(out);
+    // Pad body to H-1 lines so previous longer frames don't leave stale lines.
+    const bodyLines = body.length;
+    if (bodyLines < H - 1) out += '\n'.repeat(H - 1 - bodyLines);
+    out += ANSI.move(H, 1) + '\x1b[2K';
+    if (clippedFooter) out += clippedFooter;
+    if (output.isTTY) output.write(out);
+    else output.write(body.join('\n') + (clippedFooter ? '\n' + stripAnsi(clippedFooter) : '') + '\n');
   }
 
   /** Resolve once `quit` becomes true. */
   async wait(): Promise<void> {
     while (!this._quit) {
-      await new Promise((r) => setTimeout(r, 100));
+      await new Promise((r) => setTimeout(r, 50));
     }
   }
 }
 
-/** Strip ANSI color codes from a string. */
+/** Strip ANSI escape codes from a string (SGR + CSI + ESC sequences). */
 export function stripAnsi(text: string): string {
-  return text.replace(/\x1b\[[0-9;]*m/g, '');
+  return text
+    .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '')
+    .replace(/\x1b\][^\x07]*\x07/g, '')
+    .replace(/\x1b\(B/g, '')
+    .replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/** Clip an ANSI-colored string to `width` visible columns, preserving leading color. */
+function clipAnsi(text: string, width: number): string {
+  if (stripAnsi(text).length <= width) return text;
+  let out = '';
+  let used = 0;
+  let i = 0;
+  let sawColor = false;
+  while (i < text.length && used < width) {
+    const ch = text[i]!;
+    if (ch === '\x1b') {
+      let j = i + 1;
+      if (text.charCodeAt(j) === 0x5b) {
+        j++;
+        while (j < text.length) {
+          const c = text.charCodeAt(j);
+          if (c >= 0x20 && c <= 0x3f) { j++; continue; }
+          break;
+        }
+        if (j < text.length) j++;
+      } else if (j < text.length) {
+        j++;
+      }
+      out += text.slice(i, j);
+      sawColor = true;
+      i = j;
+    } else {
+      out += ch;
+      used++;
+      i++;
+    }
+  }
+  if (sawColor && !out.endsWith(ANSI.reset)) out += ANSI.reset;
+  return out;
 }
 
 /** Spawn `node <bin> <args>` with inherited stdio (used for interactive CLI commands). */

package/src/util.ts

@@ -14,18 +14,24 @@ export interface ParsedArgs {
 export function parseArgs(argv: string[]): ParsedArgs {
   const _: string[] = [];
   const flags: Record<string, string | boolean> = {};
+  // Flags that are always boolean and should not consume the next arg
+  const booleanFlags = new Set(['dev', 'force', 'no-install', 'help', 'h', 'version', 'v']);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
     if (a.startsWith('--')) {
       const eq = a.indexOf('=');
       if (eq === -1) {
         const key = a.slice(2);
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith('-')) {
-          flags[key] = next;
-          i++;
-        } else {
+        if (booleanFlags.has(key)) {
           flags[key] = true;
+        } else {
+          const next = argv[i + 1];
+          if (next !== undefined && !next.startsWith('-')) {
+            flags[key] = next;
+            i++;
+          } else {
+            flags[key] = true;
+          }
         }
       } else {
         flags[a.slice(2, eq)] = a.slice(eq + 1);

package/src/wizard.ts

@@ -300,10 +300,9 @@ function pageExamples(state: WizardState, key: KeyInfo, tui: Tui): void {
 }
 
 function pageAdmin(state: WizardState, str: string, key: KeyInfo): void {
-  const isYes = state.features.has('admin');
   if (key.name === 'left' || key.name === 'right' || key.name === 'up' || key.name === 'down') {
-    state.features.add('admin');
-    if (isYes) state.features.delete('admin');
+    if (state.features.has('admin')) state.features.delete('admin');
+    else state.features.add('admin');
   } else if (key.name === 'return' || key.name === 'enter') {
     state.page = 'features';
   } else if (str && /y/i.test(str)) {
@@ -318,7 +317,7 @@ function pageFeatures(state: WizardState, key: KeyInfo): void {
     state.featureIndex = Math.max(0, state.featureIndex - 1);
   } else if (key.name === 'down') {
     state.featureIndex = Math.min(FEATURES.length - 1, state.featureIndex + 1);
-  } else if (key.name === ' ') {
+  } else if (key.name === 'space' || key.sequence === ' ' || key.name === ' ') {
     const id = FEATURES[state.featureIndex]?.id;
     if (id) {
       if (state.features.has(id)) state.features.delete(id);
@@ -501,7 +500,7 @@ function titleBar(state: WizardState, W: number): string {
   const n = stepIndex(state.page) + 1;
   const right = `${ANSI.dim}Step ${n} of ${STEPS.length}${ANSI.reset}`;
   const gap = Math.max(1, W - visibleWidth(left) - visibleWidth(right));
-  return `${left}${' '.repeat(gap)}${right}`;
+  return clipVisible(`${left}${' '.repeat(gap)}${right}`, W);
 }
 
 function progressDots(state: WizardState): string {

package/templates/base/package.json.ejs

@@ -25,7 +25,8 @@
     "@bhooai/nexus-ai-client": "^2.0.1",
     "@bhooai/nexus-graphql": "^2.0.1",
     "@bhooai/nexus-telemetry": "^2.0.1",
-    "tsx": "^4.19.0"
+    "tsx": "^4.19.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "bhooai-nexus": "^2.0.1",

package/templates/features/realtime/apps/backend/src/ws/chat.room.ts

@@ -2,55 +2,54 @@
  * Realtime feature — WebSocket chat room. Auto-discovered from ws/*.room.ts
  * and mounted on the /ws endpoint.
  *
- * Client protocol:
- *   → join  { roomId, username }
- *   ← presence  { type, username }
- *   → msg   { roomId, text }
+ * Client protocol (supports both legacy roomId and generic room):
+ *   → join  { roomId|room, username }
+ *   ← presence  { type, username }  (via broadcast)
+ *   → msg   { roomId|room, text }
  *   ← msg   { from, text, at }
- *   → typing { roomId }
+ *   → typing { roomId|room }
  *   ← typing { username }
  */
 export default {
   name: 'chat',
 
-  async onJoin(socket: any, payload: { roomId: string; username: string }) {
+  async onJoin(socket: any, payload: { roomId?: string; room?: string; username: string }) {
+    const roomId = payload.roomId ?? payload.room ?? 'lobby';
+    socket.data = socket.data ?? {};
     socket.data.username = payload.username;
-    socket.join(`chat:${payload.roomId}`);
-    socket.to(`chat:${payload.roomId}`).emit('presence', {
-      type: 'join',
-      username: payload.username,
-    });
+    try { socket.join?.(`chat:${roomId}`); } catch {}
+    try { socket.join?.(roomId); } catch {}
+    const data = { type: 'join', username: payload.username };
+    try { socket.to?.(`chat:${roomId}`)?.emit?.('presence', data); } catch {}
+    try { socket.to?.(roomId)?.emit?.('presence', data); } catch {}
   },
 
-  async onLeave(socket: any, payload: { roomId: string }) {
-    socket.to(`chat:${payload.roomId}`).emit('presence', {
-      type: 'leave',
-      username: socket.data?.username,
-    });
+  async onLeave(socket: any, payload: { roomId?: string; room?: string }) {
+    const roomId = payload.roomId ?? payload.room ?? 'lobby';
+    const data = { type: 'leave', username: socket.data?.username };
+    try { socket.to?.(`chat:${roomId}`)?.emit?.('presence', data); } catch {}
+    try { socket.to?.(roomId)?.emit?.('presence', data); } catch {}
   },
 
   onMessage: {
-    'msg': async (socket: any, payload: { roomId: string; text: string }, ctx: any) => {
-      const msg = {
-        from: socket.data?.username ?? 'anon',
-        text: payload.text,
-        at: new Date().toISOString(),
-      };
+    'msg': async (socket: any, payload: { roomId?: string; room?: string; text: string }, ctx: any) => {
+      const roomId = payload.roomId ?? payload.room ?? 'lobby';
+      const msg = { from: socket.data?.username ?? 'anon', text: payload.text, at: new Date().toISOString() };
       try {
         const { Message } = await import('../models/Message.js');
-        await Message.create({
-          roomId: payload.roomId,
-          userId: socket.data?.userId ?? 'anon',
-          username: msg.from,
-          text: msg.text,
-        });
-      } catch { /* non-fatal */ }
-      ctx.server.to(`chat:${payload.roomId}`).emit('msg', msg);
+        await Message.create({ roomId, userId: socket.data?.userId ?? 'anon', username: msg.from, text: msg.text });
+      } catch {}
+      try { ctx.server.to?.(`chat:${roomId}`)?.emit?.('msg', msg); } catch {}
+      try { ctx.server.to?.(roomId)?.emit?.('msg', msg); } catch {}
+      try { ctx.server.broadcast?.(roomId, 'msg', msg); } catch {}
+      try { ctx.server.broadcast?.(`chat:${roomId}`, 'msg', msg); } catch {}
     },
-    'typing': (socket: any, payload: { roomId: string }, ctx: any) => {
-      socket.to(`chat:${payload.roomId}`).emit('typing', {
-        username: socket.data?.username,
-      });
+    'typing': (socket: any, payload: { roomId?: string; room?: string }, ctx: any) => {
+      const roomId = payload.roomId ?? payload.room ?? 'lobby';
+      const data = { username: socket.data?.username };
+      try { socket.to?.(`chat:${roomId}`)?.emit?.('typing', data); } catch {}
+      try { socket.to?.(roomId)?.emit?.('typing', data); } catch {}
+      try { ctx.server.broadcast?.(roomId, 'typing', data); } catch {}
     },
   },
-};
+};