@bhooai/nexus-cli 2.0.2 → 2.0.4

package/src/devServiceManager.ts

@@ -0,0 +1,229 @@
+/**
+ * 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';
+import { nextFreePort } from './util.js';
+import { readRegistry, writeRegistry, type PortRegistry } from './ports.js';
+
+export type ServiceStatus = 'starting' | 'running' | 'stopped' | 'crashed';
+
+export interface ServiceSpec {
+  name: string;
+  cmd: string;
+  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 {
+  status: ServiceStatus;
+  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;
+}
+
+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[]>();
+  private projectRoot: string;
+
+  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, lastCrashLog: [], 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', async (code, signal) => {
+      const exitInfo = { code, signal };
+      svc.child = null;
+      svc.pid = null;
+      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;
+      }
+      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;
+
+  /** 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);
+    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

@@ -6,6 +6,7 @@
  */
 import { parseArgs } from './util.js';
 import { closePrompts } from './prompts.js';
+import { launchWelcome } from './launcher.js';
 
 export interface CommandContext {
   argv: string[];
@@ -25,8 +26,28 @@ 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 {
+    // Bare `nexus` → full-screen welcome launcher.
+    if (!cmd) {
+      await launchWelcome();
+      return;
+    }
     if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
       printHelp();
       return;
@@ -54,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 };