bhooai-nexus 0.1.5 → 2.0.1

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,289 +1,168 @@
-# BhooAI Nexus
+# BhooAI Nexus v2
 
-Build full-stack Node.js applications with one CLI and one configuration file. BhooAI Nexus includes an HTTP server, WebSockets, GraphQL federation, MongoDB data access, authentication, CSRF/CORS protection, payments, email, WebRTC, Python AI services, plugins, an admin console, and master/slave cluster orchestration.
+A production-ready Node.js full-stack framework. One config file, one CLI, multi-app monorepo.
 
-## Features
+> v2 is a fresh workspace at `C:\server\PACKAGES\bhooai-nexus\` — reuses v1's packages, removes the
+> cluster subsystem (Docker handles scaling), rewrites the CLI, and adds a Laravel-style
+> convention layer on top.
 
-- Node.js HTTP server with trie routing, middleware, uploads, static files, security headers, CORS, CSRF, and rate limiting
-- MongoDB ODM with schemas, hooks, indexes, populate, and transactions
-- JWT access tokens, refresh tokens, sessions, Google OAuth, Facebook OAuth, and role-based access control
-- WebSockets, Redis adapters, WebRTC signaling, and mediasoup SFU integration
-- GraphQL subscriptions, federation composition, entity joins, `@provides`, and `@requires`
-- Razorpay, PayPal, PayU, Skrill, and Payoneer integrations
-- Email, certificate generation, Redis cache, Google Ads, and plugin extensions
-- Python FastAPI AI server with OpenAI-compatible chat, embeddings, Ollama, and SSE streaming
-- Admin console with configuration, environment, process, monitoring, database, AI, and cluster management
-- Master/slave cluster mesh with load balancing, node agents, request allocation, health checks, and upload path pinning
-- Tailwind CSS + `@bhooai/nexus-postcss` preset with PostCSS pipeline, design tokens, and dark theme baseline for every scaffolded frontend
+## Quick start
 
-## Requirements
-
-- Node.js `>=20.10`
-- npm, included with Node.js
-- MongoDB 7 or newer, running locally or reachable through `MONGODB_URI`
-- Redis 7 or newer, running locally or reachable through `REDIS_URL`
-- Python 3.10 or newer for the optional AI server
-- A virtual environment is recommended for Python dependencies
-
-The Python service dependencies are listed in [`apps/ai-server/requirements.txt`](apps/ai-server/requirements.txt): FastAPI, Uvicorn, HTTPX, pytest, and pytest-asyncio.
-
-MongoDB and Redis can be started with Docker, system services, or managed cloud providers. The AI server is optional when AI features are not used.
-
-## Install
+`nexus init` scaffolds the project **and installs its dependencies** in one step.
 
 ```bash
-npm install bhooai-nexus
-npx nexus init my-app
+# One-time: install the CLI (or use npx without installing)
+npm install -g bhooai-nexus
+
+# New project (zero prompts — opinionated defaults)
+nexus init my-app
 cd my-app
-npm run doctor
 npm run dev
 ```
 
-Initialize the current directory with `npx nexus init .`. Use `npx nexus init . --skip-install` to defer dependency installation.
-
-## Quick Start
+Prefer `npx` over a global install? `nexus init` auto-installs deps either way:
 
 ```bash
-npm install bhooai-nexus
 npx nexus init my-app
 cd my-app
-npm run doctor
 npm run dev
 ```
 
-Default development services:
-
-| Service | Default port |
-| --- | ---: |
-| Backend API | `4000` |
-| Frontend | `3000` |
-| Admin console | `3300` |
-| Python AI server | `8000` |
-| Cluster load balancer | `8080` |
-| Node agent | `7575` |
-
-`nexus dev` automatically moves a configured port to the next available port, allowing master and slave projects to run side by side on one machine.
-
-## Screenshots
-
-### Admin login
-
-![BhooAI Nexus admin login](docs/screenshots/login.png)
-
-### Overview dashboard
-
-![BhooAI Nexus overview dashboard](docs/screenshots/overview.png)
-
-### Master cluster management
-
-![BhooAI Nexus master cluster management](docs/screenshots/cluster-master.png)
-
-### Slave node agent and roles
-
-![BhooAI Nexus slave node agent](docs/screenshots/cluster-slave.png)
-
-### Connected cluster nodes
-
-![Connected cluster nodes](docs/screenshots/cluster-nodes.png)
-
-### AI agents
-
-![AI agents](docs/screenshots/ai-agents.png)
-
-### AI providers
-
-![AI agent providers](docs/screenshots/ai-agents-providers.png)
-
-### AI playground
-
-![AI playground](docs/screenshots/ai-agents-playground.png)
-
-### Monitoring
-
-![Monitoring dashboard](docs/screenshots/monitoring.png)
-
-### Settings
-
-![Settings](docs/screenshots/settings.png)
-
-### Themes
-
-![Theme selection](docs/screenshots/themes.png)
-
-### Appearance
-
-![Appearance settings](docs/screenshots/appearance.png)
-
-### Search
-
-![Admin search](docs/screenshots/search-bar.png)
-
-### Notifications
-
-![Notifications](docs/screenshots/notification.png)
-
-### AI log summary
-
-![AI log summary](docs/screenshots/logs-ai-summary.png)
-
-### Nexus development services
-
-![Nexus development services](docs/screenshots/nexus-dev.png)
-
-### Nexus initialization
-
-![Nexus initialization](docs/screenshots/nexus-init.png)
-
-## Cluster Mesh
-
-BhooAI Nexus supports a central master and one or more slave nodes.
-
-Initialize a master:
-
 ```bash
-npx nexus init master --as=root
+# Wizard with example picker
+nexus init my-app --interactive
+# or, named example:
+nexus init my-app --example chat
 ```
 
-Initialize a slave with a built-in role:
+Skip dependency install for CI/offline use:
 
 ```bash
-npx nexus init slave-1 --as=node --role=backend --port=7575
-npx nexus init slave-2 --as=node --role=files --port=7576
+nexus init my-app --no-install
 ```
 
-Supported node roles are `backend`, `files`, `database`, and `ai`.
-
-After `npm run dev`, a node project automatically starts its node agent. The agent exposes the control API and advertises the node's development backend without starting a duplicate backend process.
-
-The master load balancer listens on port `8080` and distributes traffic across ready backend nodes. Authentication routes are pinned to the master:
+## Architecture at a glance
 
-- `/auth/*`
-- `/csrf-token`
-
-Use the same `NEXUS_AUTH_JWT_SECRET` on all nodes so slaves can verify master-issued access tokens.
-
-### Upload path allocation
+```
+┌──────────────── Multi-app monorepo ─────────────────┐
+│  apps/backend/        ← Node.js, auto-discovery      │
+│  apps/backend-shop/   ← add via `nexus add backend`  │
+│  apps/frontend/       ← Vite + React                 │
+│  apps/frontend-shop/  ← add via `nexus add frontend` │
+│  apps/admin/          ← wraps @bhooai/nexus-admin    │
+│  apps/ai-server/      ← FastAPI (optional)           │
+│  .nexus-ports.json    ← stable port registry         │
+│  nexus.config.ts                                      │
+│  docker-compose.yml                                   │
+└──────────────────────────────────────────────────────┘
+```
 
-The master admin console includes **Cluster → Path routing**. Pin URL prefixes to specific nodes:
+Each backend follows a Laravel-style convention under `src/`:
 
-```text
-/uploads/images  ->  slave-1
-/uploads/files   ->  slave-2
+```
+src/
+├── main.ts              # 20-line createNexusApp()
+├── routes/              # HTTP endpoints (auto-discovered)
+├── graphql/             # *.graph.ts (federation)
+├── ws/                  # *.room.ts (WebSocket rooms)
+├── mail/templates/      # *.ejs
+├── mail/mailables/      # classes
+├── errors/pages/        # 404.html / 500.html / ...
+├── errors/Handler.ts
+├── models/ services/ repositories/ controllers/
+├── middleware/ validators/ jobs/ listeners/ events/
+├── policies/ resources/ requests/ helpers/ config/
+├── database/{seeds,migrations}/ providers/ plugins/ types/ constants/
 ```
 
-Path pins use longest-prefix matching. A pinned request is sent only to its configured node. If the pinned node is unavailable, the load balancer returns `503 pinned_node_down` instead of silently sending the request to another node.
-
-When no slave nodes are linked, the load balancer fails open to the master's own backend if `cluster.failOpenSingleNode` is enabled. This keeps a cluster-enabled master usable as a single-node installation.
+## CLI
 
-Upload endpoints accept both `/uploads` and sub-paths such as `/uploads/images`. The upload directory is created automatically on the node that handles the request.
+```
+Project    init · dev · build · test · doctor · sync · uninstall · down · up
+Multi-app  add backend <name>
+           add frontend <name> [--for <backend>]
+           add route <name> --app <backend>
+           add module <payments|ai|admin|uploads|graphql-subgraph>
+
+Data       db:seed · db:migrate · db:rollback
+Queue      queue:work · queue:retry
+Plugins    plugin new · install · remove · list
+
+Generators (make:*) — 21 total:
+route · controller · model · service · repository · middleware · validator ·
+job · event · listener · policy · resource · request · mail · room · subgraph ·
+seeder · migration · provider · plugin
+```
 
-## Admin Console
+## Examples
 
-Open the admin console at `http://localhost:3300` during development. The console provides overview, processes, logs, configuration, environment, plugins, users, monitoring, payments, databases, schema, AI, and cluster management.
+10 examples ship in `packages/nexus-examples/` and are overlayable via `nexus init --example`:
 
-The Cluster tab includes connected-node cards with request allocation percentage, CPU, memory, freshness, service health, test, enable, restart, and unlink controls. Slave mode includes role selection, node-agent status, pairing tokens, node IDs, and copyable serve/link commands. Master mode includes path-prefix routing for uploads and other services.
+| Example | Demos |
+|---|---|
+| `empty` | bare scaffold |
+| `chat` | realtime rooms, presence, typing |
+| `video-call` | WebRTC signaling, 1:1 RTCPeerConnection |
+| `checkout` | payments + mailables + HMAC webhook verify |
+| `livestream` | broadcaster/viewer roles, streaming |
+| `ai-chat` | streaming LLM via SSE |
+| `saas-starter` | auth + teams + projects + policies + events |
+| `blog-crud` | ODM models, GraphQL federation subgraph |
+| `dashboard` | admin-metrics demo, CSS-only viz |
+| `file-storage` | local + S3 storage, signed private URLs |
+| `multi-app` | two backends, two frontends, one admin |
 
-## Configuration
+## Storage
 
-Edit `nexus.config.ts`. Configuration precedence is:
+Per-backend `storage/` folder with `local` + `s3` drivers shipped:
 
-```text
-code defaults < nexus.config.ts < nexus.runtime.json < NEXUS_* environment variables < CLI flags
+```ts
+import { storage } from 'bhooai-nexus';
+await storage.disk('uploads').put('avatars', file);
+const url = await storage.disk('private').signedUrl('invoices/1.pdf');
 ```
 
-Admin changes are written to the gitignored `nexus.runtime.json` file. Store secrets in the project `.env` file:
-
-```env
-MONGODB_URI=mongodb://localhost:27017/my-app
-REDIS_URL=redis://localhost:6379
-NEXUS_AUTH_JWT_SECRET=replace-with-a-long-random-secret
-```
+UUID filenames + `YYYY/MM` sharding. EXIF-stripped. sharp-driven image transforms.
 
-Common port overrides include `NEXUS_SERVER_PORT`, `NEXUS_FRONTEND_PORT`, `NEXUS_ADMIN_PORT`, `NEXUS_CLUSTER_LBPORT`, `NEXUS_CLUSTER_NODEAGENTPORT`, and `AI_PORT`.
+## Importing the framework
 
-## Uninstall
+`bhooai-nexus` is the umbrella package — one import surfaces the whole API:
 
-Preview changes:
-
-```bash
-npx nexus uninstall --dry-run
+```ts
+import { createNexusApp, storage, model, Schema, AiClient, defineRoutes } from 'bhooai-nexus';
 ```
 
-Remove the project database and registration while keeping files:
-
-```bash
-npx nexus uninstall
-```
+Prefer narrower imports for smaller bundles? Use the sub-path exports
+(`bhooai-nexus/core`, `bhooai-nexus/data`, `bhooai-nexus/ai-client`, …) or the
+scoped packages (`@bhooai/nexus-core`, `@bhooai/nexus-data`, …) directly.
 
-Remove the database, registration, and project directory:
+## Maintenance mode
 
-```bash
-npx nexus uninstall --purge
 ```
-
-Skip confirmations or keep the database:
-
-```bash
-npx nexus uninstall --purge --force
-npx nexus uninstall --keep-db
+nexus down --message "Quick upgrade"
+nexus up
 ```
 
-Uninstall does not remove the framework package, MongoDB's `nexus_projects` database, or other projects.
-
-## Project Layout
-
-```text
-packages/       Framework packages (@bhooai/nexus-*)
-apps/backend/   Node.js backend
-apps/frontend/  React + Vite frontend
-apps/admin/     React + Vite admin host
-apps/ai-server/ Python FastAPI AI service
-bin/            CLI entry point
-contracts/      Node-to-Python API contracts
-plugins/        Project plugins
-tests/          Cross-service tests
-docs/           Architecture, improvements, and screenshots
-```
+All requests return 503 + Retry-After except `/health`.
 
-## Testing
+## Tests
 
 ```bash
 npx vitest run
-cd apps/ai-server
-python -m pip install -r requirements.txt
-pytest
 ```
 
-Run Playwright end-to-end tests from the framework root:
-
-```bash
-npx playwright test --config=playwright.config.ts
-```
-
-## Docker
-
-```powershell
-.\docker.ps1 build
-.\docker.ps1 run
-.\docker.ps1 logs
-.\docker.ps1 stop
-```
-
-Development endpoints are frontend `http://localhost:3000`, admin `http://localhost:3300`, and backend `http://localhost:4000/health`.
-
-## Documentation
-
-- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — architecture and data flow
-- [`docs/IMPROVEMENTS.md`](docs/IMPROVEMENTS.md) — improvement history
-- [`docs/troubleshooting.html`](docs/troubleshooting.html) — common errors and fixes
-- [`docs/screenshots/README.md`](docs/screenshots/README.md) — screenshot catalog
-- [`apps/ai-server/README.md`](apps/ai-server/README.md) — Python AI service
-- Package documentation under `packages/nexus-*/README.md`
+Current suite covers: app factory, event bus, policies, generators name normalization,
+EJS templating. 27 tests, all green.
 
-## Design Principles
+## Status
 
-BhooAI Nexus avoids Apollo, Express, and Mongoose where direct control is required. The HTTP server, trie router, ODM, federation layer, and plugin sandbox are implemented in the workspace. Established libraries are used for standards and infrastructure, including GraphQL.js, MongoDB, Redis, WebSockets, Nodemailer, Jose, and mediasoup.
+- P0–P12 shipped (skeleton, app factory, abstractions, storage, CLI, plugins, db, queue,
+  generators, port registry, examples, docker, admin strip + Apps tab)
+- Admin rebuilt as a fresh Apps-tab-first SPA with live backend endpoints
+  (registry, health, request logs, config, users, payments, AI proxy)
+- `bhooai-nexus` is the publishable main package — umbrella import + auto-installing init
+- v1's test suite has 97 pre-existing tsc errors (unrelated to v2 src; tracked separately)
 
 ## License
 
-BhooAI Nexus is released under the [MIT License](LICENSE).
+MIT

package/bin/nexus.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
- * BhooAI Nexus CLI entry.
+ * BhooAI Nexus v2 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.
+ * Thin ESM shim: loads compiled `packages/nexus-cli/dist/index.js` if
+ * present, otherwise runs the TypeScript source via tsx (which rewrites .js
+ * import specifiers to .ts). Keeps `node bin/nexus.js ...` working with
+ * no build step.
  */
 import { pathToFileURL } from 'node:url';
 import { existsSync } from 'node:fs';
@@ -20,13 +20,8 @@ async function main() {
   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);
@@ -36,9 +31,6 @@ async function main() {
   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;