bhooai-nexus 0.1.2

package/README.md

@@ -0,0 +1,184 @@
+# BhooAI Nexus
+
+A Node-based full-stack framework: websockets, GraphQL federation (no Apollo), inbuilt CSRF/CORS, a from-scratch ODM on the MongoDB driver, Google/Facebook OAuth, five payment gateways, email, public/private certificate generation, Redis cache, Google Ads, WebRTC live streaming, a Python AI server (OpenAI + Ollama), an admin project, and a plugin system — all driven by a single `nexus.config.ts` and a `/bin` CLI.
+
+This directory is the package and workspace root. Its `package.json` and
+`package-lock.json` live here; the parent `BhooAI-Nexus/` directory is only a
+container and is not an npm project.
+
+The `apps/admin/` panel is built into this package and shared by every project created
+with `nexus init`. Generated projects only contain a launcher; the common panel
+source remains owned by this package.
+
+## Layout
+
+```
+packages/   scoped framework packages (@bhooai/nexus-*)
+apps/       backend (Node), frontend (React+Vite+Tailwind), ai-server (Python FastAPI)
+apps/admin/ admin project (React+Vite+TS) — manages config, plugins, the user project
+bin/        CLI entry — `node bin/nexus.js <command>`
+contracts/  Node↔Python contract (single source of truth)
+plugins/    user-created plugins
+tests/      cross-service e2e (Playwright) driving the real backend
+logs/ certs/ generated at runtime (gitignored)
+```
+
+## Quick start
+
+```bash
+npm install              # install workspaces
+npm run doctor           # verify node/python/mongo/redis
+npm run dev              # start the four terminals under the supervisor
+npm test                 # vitest (Node) + pytest (Python)
+```
+
+## Use as an npm package
+
+Publish the public workspace packages together from the framework repository:
+
+```bash
+npm publish
+```
+
+Then a new app can be created without copying the framework repository:
+
+```bash
+mkdir my-app
+cd my-app
+npm init -y
+npm install C:\server\BhooAI\BhooAI-Nexus\BhooAI-Nexus\bhooai-nexus
+npx nexus init .
+npm run doctor
+npm run dev
+```
+
+`bhooai-nexus` installs the `nexus` executable. `nexus init` copies the backend, frontend, AI,
+admin, config, and `uploads/` scaffold into the current directory, then automatically runs
+`npm install` for React, Vite, the admin workspace, and framework packages. Use
+`nexus init . --skip-install` when dependency installation should be deferred.
+
+Four terminals boot under one supervisor: backend (`:4000`), frontend (`:3000`),
+admin (`:3001`), and the Python AI server (`:8000`). Each is also runnable standalone.
+
+## Scaffold a new project
+
+```bash
+node bin/nexus.js init ./my-app
+cd my-app
+npm run doctor   # check the environment
+npm run dev      # start all four terminals
+```
+
+`init` copies a real, runnable project tree from `packages/nexus-cli/templates/`
+— the generated backend boots a Nexus HTTP server with the full security stack
+(CSRF/CORS/security headers) and serves `/health`, `/csrf-token`, `/echo`, and the CSRF-protected
+multipart upload endpoint `/uploads`. Uploaded files are stored below the project-local `uploads/`
+directory and served at `/uploads/<generated-name>`.
+
+## Configuration
+
+Edit `nexus.config.ts`. Precedence (low → high): code defaults < `nexus.config.ts`
+< `nexus.runtime.json` (admin write-back, gitignored) < env vars < CLI flags.
+Put secrets directly in a project-root `.env` (no `.env.example` — the framework
+loads `.env` itself). Admin overrides write only to
+`nexus.runtime.json` so the human config file stays clean.
+
+## Admin console
+
+The admin app (`apps/admin/`, Vite on `:3001`, backend-adjacent) is an `admin`-role
+login gate plus a glass dashboard. Overview, Processes, Configuration, Environment,
+Plugins, Users, Monitoring, Payments, Databases, and AI Schema.
+
+- **Theme & mode** — three themes (Aurora, Midnight, Violet) and three interface
+  modes (Workspace, Compact, Focus), persisted in browser local storage and applied
+  to the login screen too. Desktop shell is a fixed 80% of the actual screen width;
+  responsive down to a full-width mobile drawer.
+- **Configuration** — grouped key/value editor (add-key box on top, autoloads the
+  current config) writing to `nexus.runtime.json`, plus an effective merged view
+  and a raw source editor for `nexus.config.ts`.
+- **Environment** — masked grouped key/value editor for `.env`; secrets stay on
+  disk and are never returned to the browser.
+- **Safety** — custom restart-required dialog after config/env saves and a
+  confirmation dialog for destructive database/collection drops; writes are
+  schema-validated with atomic file replacement.
+
+See [`apps/admin/README.md`](apps/admin/README.md) for full details and routes.
+
+## Testing & CI
+
+- **Unit/integration:** `npx vitest run` across all workspace packages (real MongoDB
+  via `.env`; Redis optional). Frontend client tests run under `apps/frontend`.
+- **Python:** `pytest` in `apps/ai-server` (FastAPI contract tests).
+- **E2E:** `npx playwright test --config=playwright.config.ts` boots the real backend
+  on a throwaway port + DB and drives auth → CSRF → GraphQL → payments end to end.
+- **CI:** `workflows/ci.yml` runs a **Linux** job (full suite with Mongo + Redis
+  service containers, pytest, Playwright e2e) and a **Windows** job (build, the
+  Mongo/Redis-free unit suites, frontend tests, and `nexus init`/`doctor` verification).
+
+## Documentation
+
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — full architecture, data flow, and
+  component deep-dives (federation, ODM, plugins).
+- [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — improvements made during the build,
+  28 suggested next steps, and an honest seams table.
+- Per-package READMEs under `packages/nexus-*/README.md`.
+- [`apps/admin/README.md`](apps/admin/README.md) — admin console UI, theme, and config/env editing.
+
+## Status — complete (12/12 phases)
+
+- ✅ Phase 0 — Foundations (config loader + precedence, DI, telemetry, CLI doctor/init, supervisor)
+- ✅ Phase 1 — HTTP + Security (custom `node:http` server, trie router, CSRF/CORS/headers/rate-limit)
+- ✅ Phase 2 — Data layer (custom ODM on the `mongodb` driver — schemas, hooks, populate, transactions, indexes)
+- ✅ Phase 3 — Auth (local JWT+refresh+sessions, Google + Facebook OAuth2, CSRF on auth + WS upgrade)
+- ✅ Phase 4 — Realtime + WebRTC signaling (WS rooms, Redis adapter, WS auth, mediasoup SFU)
+- ✅ Phase 5 — GraphQL (single subgraph, `_service`/`_entities`, subscriptions over WS)
+- ✅ Phase 6 — Federation (composition, supergraph SDL, query planner, entity joins, `@provides`/`@requires`)
+- ✅ Phase 7 — Payments (Razorpay + PayPal full, PayU/Skrill/Payoneer happy-path) + Email + Crypto (keypair/X.509/CSR) + Cache + Ads
+- ✅ Phase 8 — Plugins (trusted in-process + sandboxed worker_threads, capability policy, admin extensions)
+- ✅ Phase 9 — Python AI server (FastAPI, OpenAI + Ollama, SSE) + Node AI client
+- ✅ Phase 10 — Admin + supervisor (process control API, config editor → runtime.json, plugins, users, monitoring)
+- ✅ Phase 11 — Frontend (React + Vite + Tailwind; auth UI, non-Apollo graphql client, WS client, checkout, live-stream viewer)
+- ✅ Phase 12 — Hardening, docs, e2e, release (Playwright e2e, Win+Linux CI, `nexus init` upgrade, docs)
+
+## Dependency policy
+
+Built from scratch where it matters: **no Apollo**, **no mongoose**, **no express**.
+Allowed: `graphql` (graphql-js core), `mongodb`, `ws`, `nodemailer`, `node-redis`,
+`bcrypt`, `jose`, `mediasoup`/`mediasoup-client`, `google-ads-api`. The federation
+layer, ODM, HTTP server, and plugin sandbox are all hand-rolled.
+
+
+## Docker Windows
+
+In project directory, open PowerShell and run:
+```bash
+`.\docker.ps1 run`          # start the container
+`.\docker.ps1 build`        # build the image first
+`.\docker.ps1 run -f`       # start + follow logs
+`.\docker.ps1 logs`         # tail logs
+`.\docker.ps1 stop`         # stop container
+`.\docker.ps1 rm`           # stop + remove
+```
+
+Or from cmd:
+```bash
+`docker.bat build`
+`docker.bat run`
+```
+
+Note: if PowerShell blocks it, allow first with:
+Set-ExecutionPolicy -Scope Process Bypass
+After run, access: 
+```ps1
+  frontend  http://localhost:3000
+  admin     http://localhost:3001
+  backend   http://localhost:4000/health
+```
+
+## Docker Linux
+
+```bash
+cd project-directory
+./docker.sh build
+./docker.sh run
+```

package/apps/admin/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>BhooAI Nexus Admin</title>
+  </head>
+  <body class="bg-mesh text-slate-100">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/apps/admin/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@bhooai/admin-host",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 3300",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.13",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.0"
+  }
+}

package/apps/admin/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/apps/admin/public/anime-girl.svg

@@ -0,0 +1,84 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 1000" role="img" aria-labelledby="title desc">
+  <title id="title">Anime girl portrait</title>
+  <desc id="desc">A colorful anime-style girl portrait with violet hair and teal eyes.</desc>
+  <defs>
+    <linearGradient id="sky" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#17133d"/>
+      <stop offset="0.52" stop-color="#5c2e83"/>
+      <stop offset="1" stop-color="#f08cae"/>
+    </linearGradient>
+    <linearGradient id="hair" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#b9a1ff"/>
+      <stop offset="0.5" stop-color="#6848bf"/>
+      <stop offset="1" stop-color="#35246e"/>
+    </linearGradient>
+    <linearGradient id="shirt" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f8f6ff"/>
+      <stop offset="1" stop-color="#b6c7ff"/>
+    </linearGradient>
+    <filter id="blur"><feGaussianBlur stdDeviation="28"/></filter>
+    <filter id="glow"><feGaussianBlur stdDeviation="7"/></filter>
+  </defs>
+
+  <rect width="800" height="1000" fill="url(#sky)"/>
+  <circle cx="110" cy="180" r="150" fill="#6ee7f9" opacity=".2" filter="url(#blur)"/>
+  <circle cx="690" cy="690" r="220" fill="#f9a8d4" opacity=".25" filter="url(#blur)"/>
+  <circle cx="650" cy="140" r="5" fill="#fff" opacity=".9"/>
+  <circle cx="140" cy="430" r="4" fill="#fff" opacity=".8"/>
+  <circle cx="710" cy="360" r="3" fill="#fff" opacity=".8"/>
+  <path d="M88 260l5 12 13 5-13 5-5 13-5-13-13-5 13-5zM670 230l4 10 11 4-11 4-4 11-4-11-11-4 11-4z" fill="#ffe4f0" opacity=".9"/>
+
+  <!-- soft halo -->
+  <ellipse cx="400" cy="390" rx="260" ry="280" fill="#d8c4ff" opacity=".28" filter="url(#glow)"/>
+
+  <!-- shoulders and sailor collar -->
+  <path d="M135 1000c12-160 85-245 190-275h150c105 30 178 115 190 275z" fill="url(#shirt)"/>
+  <path d="M320 736l80 112 80-112 75 38-74 127H319l-74-127z" fill="#5343a8" opacity=".9"/>
+  <path d="M328 742l72 103 72-103 23 12-95 140-95-140z" fill="#f7d6ff"/>
+  <path d="M355 835h90l-18 165h-54z" fill="#4d3b98" opacity=".8"/>
+
+  <!-- neck -->
+  <path d="M332 660h136v118c-25 45-111 45-136 0z" fill="#f3b39f"/>
+  <path d="M332 669c30 28 95 35 136 0v62c-37 38-101 34-136 0z" fill="#d88982" opacity=".35"/>
+
+  <!-- hair behind face -->
+  <path d="M190 390c-16-180 85-300 218-300 155 0 246 111 205 300l-25 280c-37 73-102 104-151 87l-42-95H334l-42 95c-52 18-120-20-151-91z" fill="url(#hair)" stroke="#2b1d5f" stroke-width="9"/>
+  <path d="M208 382c-21-128 61-257 197-257 130 0 215 92 203 226-35-102-102-149-187-159-63 77-133 134-213 190z" fill="#9b83ed" opacity=".5"/>
+  <path d="M202 448c-38 75-31 183 8 242 16-84 44-137 79-171l-22-111zM598 443c38 77 31 186-8 247-16-87-43-140-80-174l21-109z" fill="#48318d"/>
+
+  <!-- face -->
+  <path d="M273 337c0-105 57-171 127-171 82 0 129 68 129 171v166c-18 109-74 170-129 170s-111-61-127-170z" fill="#f8c2ae" stroke="#dc8f8b" stroke-width="5"/>
+  <path d="M274 438c18 88 59 133 126 133s108-45 128-133v69c-17 111-72 166-128 166s-111-55-126-166z" fill="#e89e96" opacity=".24"/>
+
+  <!-- bangs -->
+  <path d="M230 361c5-128 66-219 170-219 116 0 164 94 169 201-37-60-74-84-116-90-20 45-53 84-83 103l9-105c-48 59-92 91-149 110z" fill="url(#hair)" stroke="#2b1d5f" stroke-width="8" stroke-linejoin="round"/>
+  <path d="M287 276c36-69 77-94 117-105-25 35-40 70-45 108 52-36 91-70 109-108 25 31 37 66 42 106-67-31-141-23-223-1z" fill="#c5b5ff" opacity=".35"/>
+
+  <!-- ears and earrings -->
+  <ellipse cx="267" cy="472" rx="18" ry="36" fill="#f1af9f"/>
+  <ellipse cx="533" cy="472" rx="18" ry="36" fill="#f1af9f"/>
+  <circle cx="260" cy="509" r="8" fill="#6ee7f9"/>
+  <circle cx="540" cy="509" r="8" fill="#6ee7f9"/>
+
+  <!-- eyes -->
+  <path d="M302 444c24-25 60-22 82 2-20 35-63 40-82-2z" fill="#fff" stroke="#38276f" stroke-width="7"/>
+  <ellipse cx="348" cy="447" rx="17" ry="25" fill="#24c7c8"/>
+  <ellipse cx="350" cy="451" rx="8" ry="14" fill="#173c72"/>
+  <circle cx="356" cy="438" r="5" fill="#fff"/>
+  <path d="M416 446c23-24 59-27 82-2-19 42-62 37-82 2z" fill="#fff" stroke="#38276f" stroke-width="7"/>
+  <ellipse cx="452" cy="447" rx="17" ry="25" fill="#24c7c8"/>
+  <ellipse cx="450" cy="451" rx="8" ry="14" fill="#173c72"/>
+  <circle cx="456" cy="438" r="5" fill="#fff"/>
+  <path d="M300 416c26-22 60-24 86-3M414 413c28-23 61-20 87 4" fill="none" stroke="#3b2873" stroke-width="10" stroke-linecap="round"/>
+
+  <!-- nose and smile -->
+  <path d="M398 461l-12 48 17 5" fill="none" stroke="#ca7d7c" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M365 554c22 19 49 19 71 0" fill="none" stroke="#ad596e" stroke-width="6" stroke-linecap="round"/>
+  <path d="M372 557c18 8 39 8 57 0-7 24-49 24-57 0z" fill="#e7829a" opacity=".8"/>
+  <ellipse cx="299" cy="529" rx="31" ry="13" fill="#f98f9f" opacity=".25"/>
+  <ellipse cx="501" cy="529" rx="31" ry="13" fill="#f98f9f" opacity=".25"/>
+
+  <!-- foreground sparkles -->
+  <path d="M128 730l8 20 20 8-20 8-8 20-8-20-20-8 20-8zM674 800l7 17 17 7-17 7-7 17-7-17-17-7 17-7z" fill="#fff" opacity=".82"/>
+  <path d="M595 710c22-20 45-20 67 0-22 20-45 20-67 0z" fill="#8be9f2" opacity=".7"/>
+</svg>

package/apps/admin/public/bhooai-nexus-logo.svg

@@ -0,0 +1,135 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="1920"
+  height="1024"
+  viewBox="0 0 1920 1024"
+  role="img"
+  aria-labelledby="title desc"
+>
+  <title id="title">BhooAI Nexus</title>
+  <desc id="desc">BhooAI Nexus futuristic hexagonal logo and wordmark.</desc>
+  <defs>
+    <linearGradient
+      id="edge"
+      x1="140"
+      y1="120"
+      x2="820"
+      y2="900"
+      gradientUnits="userSpaceOnUse"
+    >
+      <stop stop-color="#67e8f9" />
+      <stop offset=".5" stop-color="#818cf8" />
+      <stop offset="1" stop-color="#d8b4fe" />
+    </linearGradient>
+    <linearGradient
+      id="word"
+      x1="900"
+      y1="360"
+      x2="1740"
+      y2="680"
+      gradientUnits="userSpaceOnUse"
+    >
+      <stop stop-color="#fff" />
+      <stop offset=".55" stop-color="#a5f3fc" />
+      <stop offset="1" stop-color="#c4b5fd" />
+    </linearGradient>
+    <radialGradient id="core" cx="50%" cy="42%" r="65%">
+      <stop stop-color="#172554" />
+      <stop offset=".72" stop-color="#081326" />
+      <stop offset="1" stop-color="#030712" />
+    </radialGradient>
+    <filter id="glow" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="16" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+  <g transform="translate(95 72)">
+    <path
+      d="M385 0 770 222v444L385 888 0 666V222z"
+      fill="url(#core)"
+      stroke="url(#edge)"
+      stroke-width="18"
+      stroke-linejoin="round"
+    />
+    <path
+      d="M385 58 710 246v376L385 810 60 622V246z"
+      fill="none"
+      stroke="#67e8f9"
+      stroke-opacity=".22"
+      stroke-width="6"
+    />
+    <path
+      d="M385 118 654 273v318L385 746 116 591V273z"
+      fill="none"
+      stroke="#a78bfa"
+      stroke-opacity=".16"
+      stroke-width="4"
+    />
+    <path
+      d="M192 660V240l386 420V240"
+      fill="none"
+      stroke="url(#edge)"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="76"
+      filter="url(#glow)"
+    />
+    <path
+      d="M192 660V240l386 420V240"
+      fill="none"
+      stroke="#071225"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="38"
+    />
+    <circle cx="192" cy="240" r="30" fill="#67e8f9" filter="url(#glow)" />
+    <circle cx="578" cy="660" r="30" fill="#f0abfc" filter="url(#glow)" />
+    <circle cx="192" cy="240" r="12" fill="#fff" />
+    <circle cx="578" cy="660" r="12" fill="#fff" />
+  </g>
+  <g transform="translate(980 250)">
+    <text
+      x="0"
+      y="270"
+      fill="url(#word)"
+      font-family="Arial, Helvetica, sans-serif"
+      font-size="230"
+      font-weight="800"
+      letter-spacing="10"
+    >
+      BhooAI
+    </text>
+    <text
+      x="16"
+      y="465"
+      fill="url(#edge)"
+      font-family="Arial, Helvetica, sans-serif"
+      font-size="126"
+      font-weight="700"
+      letter-spacing="38"
+    >
+      NEXUS
+    </text>
+    <path
+      d="M18 550h840"
+      stroke="url(#edge)"
+      stroke-width="8"
+      stroke-linecap="round"
+    />
+    <circle cx="890" cy="550" r="11" fill="#d8b4fe" />
+    <text
+      x="18"
+      y="620"
+      fill="#9ab0c9"
+      font-family="Arial, Helvetica, sans-serif"
+      font-size="27"
+      font-weight="500"
+      letter-spacing="8"
+    >
+      ONE RUNTIME. EVERY SIGNAL.
+    </text>
+  </g>
+</svg>

package/apps/admin/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from '@bhooai/admin';
+import '@bhooai/admin/style.css';
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/apps/admin/src/vite-env.d.ts

@@ -0,0 +1,18 @@
+// Ambient declarations for the admin host app. Self-contained: does not depend
+// on `vite/client` types being resolvable from the host workspace, so `@bhooai/admin`
+// imports (import.meta.env, *.svg) type-check consistently in every project.
+interface ImportMetaEnv {
+  readonly VITE_SUPERVISOR_URL?: string;
+  readonly [key: string]: string | undefined;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+declare module '*.svg' {
+  const src: string;
+  export default src;
+}
+declare module '*.png' {
+  const src: string;
+  export default src;
+}

package/apps/admin/tailwind.config.js

@@ -0,0 +1,10 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{ts,tsx}',
+    '../../packages/nexus-admin/src/**/*.{ts,tsx}',
+  ],
+  theme: { extend: {} },
+  plugins: [],
+};

package/apps/admin/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true
+  },
+  "include": ["src"]
+}

package/apps/admin/vite.config.ts

@@ -0,0 +1,68 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// Read the merged host/port values from the project's single nexus config file
+// (ts/js/mjs/cjs, discovery order matches the backend loader) plus NEXUS_*
+// env overrides, so this Vite dev server and its proxy target stay in one
+// source of truth: nexus.config.js.
+async function loadConfig() {
+  const exts = ['ts', 'js', 'mjs', 'cjs'];
+  let user: Record<string, any> = {};
+  for (const ext of exts) {
+    const file = join(PROJECT_ROOT, `nexus.config.${ext}`);
+    if (existsSync(file)) {
+      const mod = (await import(pathToFileURL(file).href + `?v=${Date.now()}`)) as Record<string, any>;
+      user = mod.default ?? mod.config ?? {};
+      break;
+    }
+  }
+  const num = (v: string | undefined, fallback: number) => (v !== undefined && Number.isFinite(Number(v)) ? Number(v) : fallback);
+  const str = (v: string | undefined, fallback: string) => (v !== undefined && v !== '' ? v : fallback);
+
+  return {
+    server: {
+      host: str(process.env.NEXUS_SERVER_HOST, user.server?.host ?? '0.0.0.0'),
+      port: num(process.env.NEXUS_SERVER_PORT, user.server?.port ?? 4000),
+    },
+    admin: {
+      host: str(process.env.NEXUS_ADMIN_HOST, user.admin?.host ?? 'localhost'),
+      port: num(process.env.NEXUS_ADMIN_PORT, user.admin?.port ?? 3300),
+      enabled: user.admin?.enabled ?? true,
+    },
+    frontend: {
+      host: str(process.env.NEXUS_FRONTEND_HOST, user.frontend?.host ?? 'localhost'),
+      port: num(process.env.NEXUS_FRONTEND_PORT, user.frontend?.port ?? 3000),
+      enabled: user.frontend?.enabled ?? true,
+    },
+  };
+}
+
+export default defineConfig(async () => {
+  const cfg = await loadConfig();
+  const backendHost = cfg.server.host === '0.0.0.0' || cfg.server.host === '::' ? '127.0.0.1' : cfg.server.host;
+  const target = `http://${backendHost}:${cfg.server.port}`;
+
+  return {
+    plugins: [react()],
+    server: {
+      port: cfg.admin.port,
+      host: cfg.admin.host,
+      proxy: {
+        '/admin': { target, changeOrigin: true },
+        '/auth': { target, changeOrigin: true },
+        '/payments': { target, changeOrigin: true },
+        '/csrf-token': { target, changeOrigin: true },
+        '/ai': { target, changeOrigin: true },
+      },
+    },
+    preview: {
+      host: cfg.admin.host,
+      allowedHosts: ['bhooai.com', 'admin.bhooai.com', '.bhooai.com'],
+    },
+  };
+});

package/bin/nexus.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * BhooAI Nexus CLI entry.
+ *
+ * Thin ESM shim: loads the compiled `@bhooai/nexus-cli` dist if present,
+ * otherwise runs the TypeScript source via tsx's programmatic API (which
+ * rewrites .js import specifiers to .ts). This keeps the framework usable
+ * with `node bin/nexus.js ...` and no build step.
+ */
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function main() {
+  const distEntry = join(__dirname, '..', 'packages', 'nexus-cli', 'dist', 'index.js');
+  const srcEntry = join(__dirname, '..', 'packages', 'nexus-cli', 'src', 'index.ts');
+  const { tsImport } = await import('tsx/esm/api');
+  let mod;
+  if (existsSync(srcEntry)) {
+    // Prefer source in the monorepo and in the published package so the CLI
+    // does not depend on a stale or omitted build artifact.
+    mod = await tsImport(pathToFileURL(srcEntry).href, import.meta.url);
+  } else if (existsSync(distEntry)) {
+    // Workspace packages export TypeScript sources with `.js` specifiers.
+    // Keep tsx in the chain even when the CLI dist exists so Node can resolve
+    // those source imports during development and after partial builds.
+    mod = await tsImport(pathToFileURL(distEntry).href, import.meta.url);
+  } else {
+    mod = await tsImport(pathToFileURL(srcEntry).href, import.meta.url);
+  }
+  const cmd = process.argv[2] ?? 'help';
+  const rest = process.argv.slice(3);
+  await mod.run(cmd, rest);
+}
+
+/** True when a rejected promise was the user pressing Ctrl+C during an
+ *  interactive prompt (node:readline/promises rejects the open question with an
+ *  AbortError). A cancelled wizard is not a failure — no error dump. */
+function isUserCancel(err) {
+  if (!err) return false;
+  if (err.name === 'AbortError') return true;
+  return err instanceof Error && /aborted with ctrl\+c/i.test(err.message);
+}
+
+main().catch((err) => {
+  if (isUserCancel(err)) process.exit(130);
+  console.error(err?.stack ?? err);
+  process.exit(1);
+});