@bhooai/nexus-cli 0.1.0

package/PLAN.md

@@ -0,0 +1,141 @@
+# Plan: `nexus init` — all-in-one setup wizard
+
+## Goal
+Turn `nexus init` into a single interactive command that, when it finishes, leaves a
+fully bootable stack: Node backend, frontend, admin, Python AI server, Mongo + Redis
+wired, JWT secret, AI provider keys, and the cluster token. After running it once,
+`npm run dev` starts everything.
+
+## Current state (source of truth)
+
+`nexus init` (`packages/nexus-cli/src/commands/init.ts`) today:
+1. Scaffolds templates (`listFiles(TEMPLATES)` -> write each)
+2. `wireFrameworkDependency()` — workspace paths + `file:` dep + Vite/Tailwind patching
+3. `allocateProjectPorts()` — auto-pick free ports for server/frontend/admin/ai/lb/agent
+4. `ensureJwtSecret()` — generate `NEXUS_AUTH_JWT_SECRET`, add empty AI/payment env keys
+5. `chooseKind()` — interactive root/node prompt (the only wizard step today)
+6. `applyClusterConfig()` — write cluster section into `nexus.config.ts`
+7. `installDependencies()` — `npm install`
+8. `printSetup()` — onboarding text
+
+Gaps that prevent "everything at once":
+- Python deps never installed (separate `nexus pysetup` command, forgotten by users)
+- No Mongo/Redis reachability check before scaffolding -> silent failures at `npm run dev`
+- No way to customize DB URI / Redis URL / AI provider keys during init (empty placeholders only)
+- No final verification that the scaffolded project actually loads
+- `.env` doesn't get `MONGODB_URI`/`REDIS_URL` (Python AI server can't connect)
+
+`pysetup.ts` is non-interactive (one-shot pip install). `doctor.ts` has reusable check
+logic (`tcpReachable`, `versionOf`, `parseHostPort`) but it's a monolithic `doctor()`
+function, not exported helpers.
+
+## Wizard flow (interactive when stdin is a TTY; flag-driven otherwise)
+
+```
+nexus init [target] [--as=root|node] [--no-interactive] [--no-venv] [--no-install] [--skip-mongo-check]
+```
+
+| # | Step | Interactive prompt | Non-interactive fallback |
+|---|------|--------------------|--------------------------|
+| 0 | Banner — "BhooAI Nexus — project setup wizard" + what it'll do | shown | shown |
+| 1 | Prerequisite scan — detect node, npm, python, git, Mongo TCP, Redis TCP. Blocks on missing node/python (critical); warns on missing Mongo/Redis (asks to continue) | shown, "Continue anyway?" if Mongo/Redis down | `--skip-mongo-check` skips; missing node/python -> exit 1 |
+| 2 | Project name -> `package.json` name + Mongo db name | prompt, default = dir basename | `--name <x>` or dir basename |
+| 3 | Server kind root/node (existing `chooseKind`) | prompt | `--as=root\|node` |
+| 4 | Cluster role + port (if node) | prompt role, default `backend` | `--role` `--port` |
+| 5 | Ports — auto-allocate (existing) OR custom | "Auto-allocate free ports? Y/n" | auto (existing) |
+| 6 | Mongo URI — confirm or edit, DB name from step 2 | prompt, default `mongodb://localhost:27017/<name>` | `--mongo-uri` |
+| 7 | Redis URL — confirm or edit | prompt, default `redis://localhost:6379` | `--redis-url` |
+| 8 | AI providers — multi-select (openai/ollama/anthropic/google/groq/...), then enter API key for each selected (written to `.env`). Ollama/lmstudio need no key. | multi-select + per-key prompt | `--ai-providers openai,ollama` (keys via env or `--ai-key <id>=<val>`) |
+| 9 | Python venv — "Create a virtualenv for the AI server? Y/n" | prompt | `--no-venv` skips; `--venv` forces |
+| 10 | Review summary — table of all chosen values; "Proceed? Y/n" | shown | proceeds |
+| 11 | Scaffold templates (existing) | — | — |
+| 12 | Wire framework (existing) | — | — |
+| 13 | Allocate ports (existing) | — | — |
+| 14 | Write config — patch `nexus.config.ts` with chosen Mongo URI / Redis URL / AI serverUrl + `applyClusterConfig` (existing) | — | — |
+| 15 | Generate `.env` — JWT secret (existing) + `MONGODB_URI` + `REDIS_URL` + AI provider keys from step 8 + cluster token + payment placeholders (existing) | — | — |
+| 16 | npm install (existing) | — | — |
+| 17 | Python setup — invoke `pysetup(['--venv'\|--no-venv])` -> creates `apps/ai-server/.venv` + `pip install -r requirements.txt` | — | — |
+| 18 | Verify — run an in-process mini-doctor on the new project: load `nexus.config.ts`, TCP-check Mongo/Redis, check backend/frontend/admin/ai ports free, sign+verify a JWT. Print pass/fail table. | — | — |
+| 19 | Next steps — print URLs (backend `:port/health`, frontend, admin, ai `127.0.0.1:port`), pairing token, and `npm run dev` | shown | shown |
+
+## Files to change (8)
+
+### Framework — CLI
+
+1. **`packages/nexus-cli/src/wizard.ts`** (NEW) — shared wizard primitives used by `init`
+   and `pysetup`:
+   - `isInteractive()` — `process.stdin.isTTY && !process.env.CI`
+   - `prompt(q, default?)`, `confirm(q, default?)`, `select(q, options)`, `multiSelect(q, options)`
+   - `banner(title, lines)`, `summaryTable(rows)`, `statusIcon(ok)`
+   - Built on `node:readline/promises` (already used by `chooseKind`)
+   - No new deps
+
+2. **`packages/nexus-cli/src/commands/init.ts`** (rewrite) — orchestrate the 20-step flow
+   above. Keep existing helpers (`wireFrameworkDependency`, `allocateProjectPorts`,
+   `ensureJwtSecret`, `applyClusterConfig`, `installDependencies`, `printSetup`); insert
+   prerequisite scan, prompts (steps 2/6/7/8/9), review, pysetup call, verify. Extract
+   `ensureJwtSecret`'s env-key writing into a reusable `writeEnv(target, entries)` so the
+   new `.env` step is one call. Add flags: `--name`, `--mongo-uri`, `--redis-url`,
+   `--ai-providers`, `--ai-key`, `--venv`/`--no-venv`, `--no-interactive`,
+   `--skip-mongo-check`.
+
+3. **`packages/nexus-cli/src/commands/pysetup.ts`** (extend) — accept an `--interactive`
+   flag that, when set and TTY, prompts for venv y/n + python path before installing.
+   Expose `pysetup(args)` so `init` can call it programmatically (already exported). No
+   behavior change for direct `nexus pysetup` invocation unless `--interactive` passed.
+
+4. **`packages/nexus-cli/src/commands/doctor.ts`** (refactor) — extract the reusable
+   prerequisite scan into exported helpers in `util.ts` so `init` step 1 reuses them:
+   `scanRuntimes()` (node/npm/python/git versions), `scanServices(cfg)` (Mongo/Redis/AI
+   TCP + port-free checks). `doctor()` becomes a thin renderer over these. No output change.
+
+5. **`packages/nexus-cli/src/util.ts`** — add `scanRuntimes()`, `scanServices(cfg)`,
+   `tcpReachable` (exists), `versionOf` (exists). Move the runtime + service check logic
+   out of `doctor.ts` so both `doctor` and `init` share one implementation.
+
+6. **`packages/nexus-cli/src/index.ts`** — update `init` help line to list new flags; no
+   dispatch change (init already wired at `index.ts:20`).
+
+### Framework — templates
+
+7. **`packages/nexus-cli/templates/package.json`** — add `"pysetup": "nexus pysetup"`
+   script so users can re-run it easily. (Optional; the wizard runs it automatically.)
+
+8. **`packages/nexus-cli/templates/nexus.config.ts`** — no structural change, but the
+   wizard patches it at step 14 with the chosen Mongo URI / Redis URL / AI serverUrl.
+   (Patch logic lives in `init.ts`, not the template.)
+
+## Security / correctness invariants
+
+- **Python AI server binds `127.0.0.1`** — wizard writes `AI_HOST=127.0.0.1` into `.env`
+  and the template `settings.py` reads it (pairs with the `/py-server` plan; if that plan
+  hasn't run yet, the wizard still sets the env so a future `settings.py` picks it up).
+- **`.env` is the single secrets sink** — JWT secret, Mongo URI, Redis URL, AI keys,
+  cluster token all land there. `nexus.config.ts` stays clean (no secrets), matching the
+  existing precedence comment.
+- **No external exposure of Python** — only Node binds `0.0.0.0`; AI server stays
+  loopback. Wizard's verify step asserts `ai.serverUrl` host is `127.0.0.1` or `localhost`.
+- **Idempotent** — re-running `nexus init .` in an existing project updates config +
+  `.env` without clobbering secrets (existing `ensureJwtSecret` pattern preserved).
+
+## Verification (after execution)
+
+1. `nexus init test-app` (interactive) -> walk through prompts -> all 20 steps complete.
+2. `cd test-app && npm run doctor` -> all green.
+3. `cd test-app && npm run dev` -> backend, frontend, admin, AI server all start;
+   `http://localhost:<port>/health` returns ok.
+4. `nexus init test-app --no-interactive --name ci-app --mongo-uri mongodb://localhost:27017/ci-app --ai-providers ollama --venv`
+   -> fully non-interactive, exit 0.
+5. Re-run `nexus init .` inside `test-app` -> secrets preserved, config updated.
+6. Existing `cli.test.ts` (`run('init', [dir, '--skip-install'])`) still exits 0 and
+   scaffolds the four-terminal tree (non-interactive mode, no pysetup).
+
+## Decisions (confirmed)
+
+- Wizard interactivity auto-detected via TTY + `!CI`; `--no-interactive` forces flags-only.
+- Mongo/Redis down at init -> warn + "Continue anyway?" (default yes). Hard requirement
+  only for node/python.
+- AI provider keys typed inline during the wizard (hidden echo). Left blank = fill later.
+- Python venv default **yes** (deps don't pollute global site-packages).
+- `--skip-install` skips BOTH npm install and pysetup (so tests/CI don't hang on pip).
+- Plan saved here at `packages/nexus-cli/PLAN.md` (matches repo `PLAN.md` convention).

package/README.md

@@ -0,0 +1,34 @@
+# @bhooai/nexus-cli
+
+The `nexus` CLI: `init`, `dev`, `doctor`, and a multi-process supervisor.
+
+## Commands
+
+| command | what it does |
+| --- | --- |
+| `init [target] [--force]` | scaffold a new Nexus project from `templates/` |
+| `dev [--only a,b]` | start backend + frontend + AI + admin under the supervisor |
+| `doctor` | verify node/python versions and mongo/redis reachability (advisory) |
+| `build` / `test` / `plugin` / `add` | reserved/forwarded to the workspace tools |
+
+## Templates
+
+`templates/` holds the real project files copied by `init` — a runnable backend
+(boots `NexusServer` with the security stack + `/health`, `/csrf-token`, `/echo`),
+a React+Vite frontend, a Python FastAPI AI server, an admin shell, and the CLI
+`bin/nexus.js` shim. `init` is idempotent (skips existing files unless `--force`).
+
+## Supervisor
+
+`Supervisor` owns the four child processes, streams prefixed logs, handles
+graceful Ctrl-C, and exposes a localhost HTTP control API (start/stop/restart/
+status/logs-tail) that the admin app consumes — decoupling admin from
+OS-specific process management.
+
+## Usage
+
+```bash
+node bin/nexus.js init ./my-app
+node bin/nexus.js doctor
+node bin/nexus.js dev
+```

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@bhooai/nexus-cli",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "nexus": "./bin/nexus.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@bhooai/nexus-cluster": "^0.1.0",
+    "@bhooai/nexus-core": "^0.1.0",
+    "@bhooai/nexus-data": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/src/commands/cluster.ts

@@ -0,0 +1,133 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import { ClusterManager } from '@bhooai/nexus-cluster';
+import type { DeepPartial, NexusConfig } from '@bhooai/nexus-core';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * `nexus cluster <subcommand>` - central-side mesh orchestration.
+ *
+ *   cluster status            list linked nodes + LB RPS
+ *   cluster link <url>        handshake + register a node by its agent URL
+ *   cluster unlink <id>       forget a node
+ *   cluster start|stop|restart|kill <id>
+ *   cluster scale <n>         target exactly n backend nodes
+ *   cluster serve             hold process: LB + autoscaler (foreground)
+ *   cluster check             poll every node once (health + metrics)
+ */
+export async function cluster(args: string[]): Promise<number> {
+  const cfg = await loadConfigAuto({ root: process.cwd() });
+  const [sub, a, b] = args;
+
+  // `serve` is the explicit "start the cluster" command - if a prior admin
+  // stop wrote {cluster:{enabled:false}} into nexus.runtime.json, that
+  // override wins over nexus.config.ts and would silently keep the cluster
+  // off. Re-enable it in runtime.json so the LB actually starts.
+  if (sub === 'serve' && !cfg.cluster.enabled) {
+    enableClusterInRuntime(process.cwd());
+    console.log(`${YELLOW}cluster was disabled in nexus.runtime.json - re-enabling${RESET}`);
+  }
+
+  // For non-serve commands, warn (don't block) when the cluster is off.
+  if (sub !== 'serve' && !cfg.cluster.enabled) {
+    console.warn(`${RED}cluster.enabled is false${RESET} - run ${CYAN}nexus cluster serve${RESET} to start it, or set cluster: { enabled: true } in nexus.config.ts`);
+  }
+
+  const manager = new ClusterManager({ config: cfg.cluster, root: process.cwd(), aiServerUrl: cfg.ai.serverUrl });
+
+  switch (sub ?? 'help') {
+    case 'status': {
+      const nodes = manager.list();
+      const rps = manager.rps();
+      console.log(`${CYAN}cluster${RESET} - ${nodes.length} linked node(s)`);
+      for (const n of nodes) {
+        const color = n.status === 'ready' ? GREEN : n.status === 'unreachable' ? RED : CYAN;
+        console.log(`  ${color}${n.status}${RESET} ${DIM}${n.identity.id}${RESET} role=${n.identity.role} tier=${n.identity.tier} enabled=${n.enabled} rps=${rps[n.identity.id] ?? 0}${n.lastMetrics ? ` cpu=${n.lastMetrics.cpu}% mem=${n.lastMetrics.memoryMb}MiB` : ''}`);
+      }
+      return 0;
+    }
+    case 'link': {
+      if (!a) { console.error('cluster link <agent-url>'); return 1; }
+      try {
+        const node = await manager.link(a);
+        const color = node.status === 'ready' ? GREEN : CYAN;
+        console.log(`${color}linked${RESET} ${node.identity.id} role=${node.identity.role} base=${node.identity.baseUrl}`);
+        return 0;
+      } catch (err) {
+        console.error(`${RED}link failed${RESET}: ${(err as Error).message}`);
+        return 1;
+      }
+    }
+    case 'unlink': {
+      if (!a) { console.error('cluster unlink <id>'); return 1; }
+      return manager.unlink(a) ? (console.log(`removed ${a}`), 0) : (console.error(`no such node: ${a}`), 1);
+    }
+    case 'start':
+    case 'stop':
+    case 'restart':
+    case 'kill': {
+      if (!a) { console.error(`cluster ${sub} <id>`); return 1; }
+      await manager.exec(a, sub === 'kill' ? 'stop' : sub);
+      console.log(`${sub} ${a}`);
+      return 0;
+    }
+    case 'scale': {
+      if (!a || !Number.isFinite(Number(a))) { console.error('cluster scale <n>'); return 1; }
+      try {
+        await manager.scaleTo(Number(a));
+        console.log(`scaled to ${a} backend node(s)`);
+        return 0;
+      } catch (err) {
+        console.error(`${RED}${(err as Error).message}${RESET}`);
+        return 1;
+      }
+    }
+    case 'check': {
+      await manager.pollAll();
+      console.log(`checked ${manager.list().length} node(s)`);
+      return 0;
+    }
+    case 'serve': {
+      console.log(`${CYAN}cluster${RESET} LB on ${cfg.cluster.lbHost}:${cfg.cluster.lbPort}${RESET}`);
+      await manager.listenLb(cfg.cluster.lbHost);
+      manager.autoscaler.start(10_000);
+      setInterval(() => void manager.pollAll().catch(() => {}), 15_000);
+      return 0;
+    }
+    case 'help':
+    default:
+      console.log(`Usage: nexus cluster <status|link|unlink|start|stop|restart|kill|scale|check|serve>`);
+      return 0;
+  }
+}
+
+/**
+ * Patch `nexus.runtime.json` to set `cluster.enabled = true`. The admin
+ * "stop cluster" endpoint writes `{cluster:{enabled:false}}` there, and that
+ * override beats `nexus.config.ts` in the loader precedence - so `nexus
+ * cluster serve` would read `enabled:false` and the LB would never bind.
+ * This removes the stale override so `serve` actually starts the cluster.
+ */
+function enableClusterInRuntime(root: string): void {
+  const runtimePath = resolve(root, 'nexus.runtime.json');
+  let runtime: Record<string, unknown> = {};
+  if (existsSync(runtimePath)) {
+    try {
+      runtime = JSON.parse(readFileSync(runtimePath, 'utf8')) as Record<string, unknown>;
+    } catch {
+      // corrupt runtime file - start fresh
+      runtime = {};
+    }
+  }
+  const cluster = (runtime['cluster'] ?? {}) as Record<string, unknown>;
+  cluster['enabled'] = true;
+  runtime['cluster'] = cluster;
+  writeFileSync(runtimePath, `${JSON.stringify(runtime, null, 2)}\n`);
+}

package/src/commands/dev.ts

@@ -0,0 +1,133 @@
+import { ServiceSpec, Supervisor } from '../supervisor.js';
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import { configChangedSinceSync, syncConfig } from '../config-sync.js';
+
+const COLORS = {
+  backend: '\x1b[32m',
+  frontend: '\x1b[36m',
+  'ai-server': '\x1b[33m',
+  admin: '\x1b[35m',
+};
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/** `nexus dev` - start the four terminals under the supervisor. */
+export async function dev(args: string[] = []): Promise<number> {  const cfg = await loadConfigAuto({ root: process.cwd() });
+  const onlyIdx = args.indexOf('--only');
+  const only = onlyIdx >= 0 ? args[onlyIdx + 1]?.split(',') : undefined;
+  const cpIdx = args.indexOf('--control-port');
+  const controlPort = cpIdx >= 0 && Number.isFinite(Number(args[cpIdx + 1])) ? Number(args[cpIdx + 1]) : 7474;
+
+  // If nexus.config.* changed since the last sync, rewrite every derived
+  // artifact (Dockerfile, docker.*, serve-all.mjs, admin pkg, project DB)
+  // before booting so the whole stack runs on the new values.
+  if (!args.includes('--no-sync')) {
+    if (configChangedSinceSync(process.cwd(), cfg)) {
+      process.stdout.write(`\n  ${BOLD}Config changed - re-syncing derived artifacts...${RESET}\n`);
+      const report = await syncConfig(process.cwd(), cfg);
+      const changed = report.files.filter((f) => f.status === 'updated').map((f) => f.file);
+      process.stdout.write(
+        `  ${DIM}updated: ${changed.length > 0 ? changed.join(', ') : 'none'}  |  db: ${report.db}${RESET}\n`,
+      );
+    }
+  }
+
+  const all: ServiceSpec[] = [
+    {
+      name: 'backend',
+      command: ['tsx', 'watch', 'apps/backend/src/main.ts'],
+      cwd: '',
+      color: COLORS.backend,
+    },
+    {
+      name: 'frontend',
+      command: ['vite', '--port', String(cfg.frontend.port), '--host', cfg.frontend.host],
+      cwd: 'apps/frontend',
+      color: COLORS.frontend,
+      optional: true,
+    },
+    {
+      name: 'ai-server',
+      command: ['python', 'main.py'],
+      cwd: 'apps/ai-server',
+      color: COLORS['ai-server'],
+      optional: true,
+      env: { AI_PORT: aiPort(cfg.ai.serverUrl) },
+    },
+    {
+      name: 'admin',
+      command: ['vite', '--port', String(cfg.admin.port), '--host', cfg.admin.host],
+      cwd: 'apps/admin',
+      color: COLORS.admin,
+      optional: true,
+    },
+  ];
+
+  // Drop services the config disables (unless an explicit --only pins them).
+  const enabled = all.filter((s) => {
+    if (only) return only.includes(s.name);
+    if (s.name === 'frontend') return cfg.frontend.enabled;
+    if (s.name === 'admin') return cfg.admin.enabled;
+    return true;
+  });
+  const services = enabled;
+
+  // Startup banner - show host:port for every service about to start.
+  process.stdout.write(`\n${BOLD}  *  BhooAI Nexus${RESET} - ${services.map((s) => s.name).join(', ')}\n\n`);
+  process.stdout.write(`  ${DIM}Service          Host           Port${RESET}\n`);
+  process.stdout.write(`  ${DIM}-----------      ---------      ----${RESET}\n`);
+
+  for (const s of services) {
+    let host = '';
+    let port = '';
+    switch (s.name) {
+      case 'backend':
+        host = cfg.server.host;
+        port = String(cfg.server.port);
+        break;
+      case 'frontend':
+        host = cfg.frontend.host;
+        port = String(cfg.frontend.port);
+        break;
+      case 'admin':
+        host = cfg.admin.host;
+        port = String(cfg.admin.port);
+        break;
+      case 'ai-server':
+        host = '0.0.0.0';
+        port = aiPort(cfg.ai.serverUrl);
+        break;
+    }
+    const padName = s.name.padEnd(15);
+    const padHost = host.padEnd(16);
+    process.stdout.write(`  ${s.color}${padName}${RESET}${padHost}${port}\n`);
+  }
+  process.stdout.write(`\n`);
+
+  const supervisor = new Supervisor(services, process.cwd(), controlPort);
+  await supervisor.start();
+
+  // After services spawn, print quick-start URLs.
+  setTimeout(() => {
+    process.stdout.write(`\n  ${BOLD}Visit:${RESET}\n`);
+    process.stdout.write(`  http://localhost:${cfg.frontend.port}  (frontend)\n`);
+    process.stdout.write(`  http://localhost:${cfg.admin.port}  (admin)\n`);
+    process.stdout.write(`  http://localhost:${cfg.server.port}/health  (backend)\n`);
+    process.stdout.write(`\n`);
+  }, 2000);
+
+  // Keep the process alive; supervisor handles SIGINT/SIGTERM.
+  return 0;
+}
+
+/** Port parsed from the configured AI server URL (defaults 8000). */
+function aiPort(serverUrl: string): string {
+  try {
+    const port = new URL(serverUrl).port;
+    return port || '80';
+  } catch {
+    return '8000';
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,199 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { loadConfigAuto } from '../../../nexus-core/src/index.js';
+import { CheckResult, scanRuntimes, scanServices } from '../util.js';
+
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+/** Critical dependency names that must be present. */
+const CRITICAL = new Set(['node', 'config', 'jwt-secret', 'jwt token', 'package.json', 'nexus.config']);
+
+/** Compute total directory size in bytes (shallow - does not recurse). */
+function dirSize(dir: string): number {
+  try {
+    let size = 0;
+    for (const entry of readdirSync(dir)) {
+      try { size += statSync(join(dir, entry)).size; } catch { /* skip */ }
+    }
+    return size;
+  } catch {
+    return 0;
+  }
+}
+
+/** Check whether a directory exists and contains at least one entry. */
+function dirPopulated(root: string, rel: string): { ok: boolean; detail: string } {
+  const abs = join(root, rel);
+  if (!existsSync(abs)) return { ok: false, detail: `${rel}/ missing` };
+  try {
+    const count = readdirSync(abs).filter((e) => e !== '.gitkeep').length;
+    return { ok: count > 0, detail: count > 0 ? `${count} file(s)` : 'empty' };
+  } catch {
+    return { ok: false, detail: `${rel}/ unreadable` };
+  }
+}
+
+/** Check whether node_modules exists and has at least 10 packages. */
+function depsInstalled(root: string, rel: string): { ok: boolean; detail: string } {
+  const mod = join(root, rel, 'node_modules');
+  if (!existsSync(mod)) return { ok: false, detail: `${rel}/node_modules missing` };
+  try {
+    const count = readdirSync(mod).filter((e) => !e.startsWith('.')).length;
+    return { ok: count >= 10, detail: count >= 10 ? `${count} pkgs` : `only ${count} pkgs` };
+  } catch {
+    return { ok: false, detail: `${rel}/node_modules unreadable` };
+  }
+}
+
+/** Verify the environment comprehensively. */
+export async function doctor(): Promise<number> {
+  const root = process.cwd();
+  const results: CheckResult[] = [];
+
+  // -- runtime versions (shared with `nexus init`) ----------------
+  const runtimes = await scanRuntimes();
+  results.push(...runtimes.map((r) => ({ name: r.name, ok: r.ok, detail: r.detail })));
+
+  // -- project files ------------------------------------------------
+  const pkgJson = existsSync(join(root, 'package.json'));
+  results.push({ name: 'package.json', ok: pkgJson, detail: pkgJson ? 'exists' : 'missing - not a nexus project' });
+
+  const configExists = ['ts', 'js', 'mjs', 'cjs'].some((ext) => existsSync(join(root, `nexus.config.${ext}`)));
+  const configExt = ['ts', 'js', 'mjs', 'cjs'].find((ext) => existsSync(join(root, `nexus.config.${ext}`)));
+  results.push({ name: 'nexus.config', ok: configExists, detail: configExists ? `nexus.config.${configExt}` : 'missing' });
+
+  const envExists = existsSync(join(root, '.env'));
+  results.push({ name: '.env', ok: envExists, detail: envExists ? 'exists' : 'missing - secrets not loaded' });
+
+  // -- project structure -------------------------------------------
+  const structDirs: Array<{ rel: string; label: string }> = [
+    { rel: 'apps/backend', label: 'apps/backend' },
+    { rel: 'apps/frontend', label: 'apps/frontend' },
+    { rel: 'apps/admin', label: 'apps/admin' },
+    { rel: 'apps/ai-server', label: 'ai-server' },
+    { rel: 'packages', label: 'packages' },
+    { rel: 'bin', label: 'bin' },
+    { rel: 'uploads', label: 'uploads' },
+    { rel: 'plugins', label: 'plugins' },
+    { rel: 'certs', label: 'certs' },
+    { rel: 'logs', label: 'logs' },
+  ];
+  for (const d of structDirs) {
+    const r = dirPopulated(root, d.rel);
+    results.push({ name: d.label, ok: r.ok, detail: r.detail });
+  }
+
+  // -- dependencies ------------------------------------------------
+  const depTargets = [
+    { rel: '', label: 'root deps' },
+    { rel: 'apps/backend', label: 'backend deps' },
+    { rel: 'apps/frontend', label: 'frontend deps' },
+    { rel: 'apps/admin', label: 'admin deps' },
+  ];
+  for (const d of depTargets) {
+    const r = depsInstalled(root, d.rel);
+    results.push({ name: d.label, ok: r.ok, detail: r.detail });
+  }
+
+  // -- disk space ---------------------------------------------------
+  const uploadsDir = join(root, 'uploads');
+  const uploadsSize = dirSize(uploadsDir);
+  results.push({ name: 'uploads size', ok: true, detail: existsSync(uploadsDir) ? `${(uploadsSize / 1024 / 1024).toFixed(1)} MB` : 'no dir' });
+
+  const logsDir = join(root, 'logs');
+  const logsSize = dirSize(logsDir);
+  results.push({ name: 'logs size', ok: true, detail: existsSync(logsDir) ? `${(logsSize / 1024 / 1024).toFixed(1)} MB` : 'no dir' });
+
+  // -- config + services --------------------------------------------
+  try {
+    const cfg = await loadConfigAuto({ root });
+
+    // config validation
+    results.push({ name: 'config load', ok: true, detail: `env=${cfg.env} server=${cfg.server.host}:${cfg.server.port}` });
+
+    // -- services (shared with `nexus init`) -----------------------
+    const services = await scanServices(cfg);
+    results.push(...services.map((r) => ({ name: r.name, ok: r.ok, detail: r.detail })));
+
+    // jwt secret + token round-trip
+    if (cfg.auth.jwt.secret === 'change-me-please') {
+      results.push({ name: 'jwt-secret', ok: false, detail: 'still the default - set NEXUS_AUTH_JWT_SECRET in .env' });
+      results.push({ name: 'jwt token', ok: false, detail: 'skipped - secret not configured' });
+    } else {
+      results.push({ name: 'jwt-secret', ok: true, detail: 'configured' });
+      // Sign + verify a test access token to validate the JWT pipeline end-to-end.
+      try {
+        const { SignJWT, jwtVerify } = await import('jose');
+        const testToken = await new SignJWT({ sub: 'doctor-test', roles: ['admin'], iat: Math.floor(Date.now() / 1000) })
+          .setProtectedHeader({ alg: 'HS256' })
+          .setIssuer(cfg.auth.jwt.issuer ?? 'bhooai-nexus')
+          .setAudience(cfg.auth.jwt.audience ?? 'bhooai-nexus-client')
+          .setExpirationTime('15m')
+          .sign(new TextEncoder().encode(cfg.auth.jwt.secret));
+        const { payload } = await jwtVerify(testToken, new TextEncoder().encode(cfg.auth.jwt.secret));
+        const ok = payload.sub === 'doctor-test' && payload.roles?.[0] === 'admin';
+        results.push({ name: 'jwt token', ok, detail: ok ? `HS256 sign+verify OK (sub=${payload.sub})` : 'token payload mismatch' });
+      } catch (err) {
+        results.push({ name: 'jwt token', ok: false, detail: `sign/verify failed - ${(err as Error).message}` });
+      }
+    }
+
+    // graphql + ws paths
+    results.push({ name: 'graphql', ok: true, detail: `path=${cfg.graphql.path} federation=${cfg.graphql.federation}` });
+    results.push({ name: 'websocket', ok: true, detail: `path=${cfg.ws.path} csrf=${cfg.ws.requireCsrf}` });
+
+    // frontend/admin enabled
+    results.push({ name: 'frontend', ok: cfg.frontend.enabled, detail: cfg.frontend.enabled ? `enabled :${cfg.frontend.port}` : 'disabled' });
+    results.push({ name: 'admin', ok: cfg.admin.enabled, detail: cfg.admin.enabled ? `enabled :${cfg.admin.port}` : 'disabled' });
+
+    // cluster
+    results.push({ name: 'cluster', ok: true, detail: cfg.cluster.enabled ? `enabled (LB :${cfg.cluster.lbPort})` : 'disabled' });
+
+    // payments
+    results.push({ name: 'payments', ok: true, detail: `currency=${cfg.payments.currency}` });
+
+    // email
+    results.push({ name: 'email', ok: true, detail: `provider=${cfg.email.provider}` });
+  } catch (err) {
+    results.push({ name: 'config', ok: false, detail: String((err as Error).message) });
+  }
+
+  // -- render ------------------------------------------------------
+  console.log(`\n${BOLD}  *  BhooAI Nexus Doctor${RESET}  ${DIM}${new Date().toLocaleString()}${RESET}\n`);
+
+  let criticalOk = true;
+  let warnings = 0;
+  let passed = 0;
+  let failed = 0;
+
+  for (const r of results) {
+    const icon = r.ok ? `${GREEN}[OK]${RESET}` : `${RED}[X]${RESET}`;
+    const label = r.name.padEnd(16);
+    if (r.ok) {
+      passed++;
+      console.log(`  ${icon} ${CYAN}${label}${RESET} ${DIM}${r.detail}${RESET}`);
+    } else {
+      failed++;
+      const warn = CRITICAL.has(r.name) ? RED : YELLOW;
+      if (!CRITICAL.has(r.name)) warnings++;
+      console.log(`  ${icon} ${warn}${label}${RESET} ${r.detail}`);
+      if (CRITICAL.has(r.name)) criticalOk = false;
+    }
+  }
+
+  console.log(`\n  ${BOLD}${passed} passed${RESET}, ${YELLOW}${warnings} warnings${RESET}, ${RED}${failed - warnings} errors${RESET}\n`);
+
+  if (criticalOk) {
+    console.log(`${GREEN}  Nexus environment looks ready.${RESET}\n`);
+  } else {
+    console.log(`${RED}  Critical issues found - cannot start.${RESET}\n`);
+  }
+  return 0; // doctor never hard-fails
+}