bhooai-nexus 2.0.13 → 3.0.4

package/README.md

@@ -2,9 +2,19 @@
 
 A production-ready Node.js full-stack framework. One config file, one CLI, multi-app monorepo.
 
-> v2 is a fresh workspace — reuses v1's packages, removes the
-> cluster subsystem (Docker handles scaling), rewrites the CLI, and adds a Laravel-style
-> convention layer on top.
+> **v3.0.x** — a fresh workspace that reuses v1's packages, drops the cluster
+> subsystem (Docker handles scaling), rewrites the CLI, and adds a Laravel-style
+> convention layer on top. It also ships **Fusion**, a from-scratch embedded
+> database, and the zero-build **future** stack (`live()`).
+
+## Highlights
+
+- **Multi-app monorepo** — N backends × N frontends, one admin SPA, config-driven ports.
+- **Auto-discovery** — drop files in `routes/`, `graphql/`, `ws/`, `models/`, … and they mount.
+- **Two data engines** — a Mongo-style ODM (`nexus-data`) **and** an embedded Rust-backed DB (`nexus-fusion`).
+- **Batteries included** — auth (JWT/OAuth), GraphQL federation, WebSocket realtime, payments, email, storage (local/S3), AI client, WebRTC, telemetry, admin.
+- **Zero-build `future` stack** — `live()` server functions, HTML + auto-WS updates, AI streaming, no VDOM.
+- **Docker-native scaling** — `docker compose up --scale backend=4`.
 
 ## Quick start
 
@@ -28,7 +38,7 @@ cd my-app
 npm run dev
 ```
 
-The wizard walks you through: project name, starter (empty or one of 10 examples), whether to include the admin panel, optional features (auth, realtime, GraphQL, payments, email, storage, queue, AI), port detection + auto-assignment, and infrastructure (MongoDB / Redis / AI providers). Run bare `nexus` for a welcome launcher.
+The wizard walks you through: project name, starter (empty or one of **18 examples**), whether to include the admin panel, optional features (auth, realtime, GraphQL, payments, email, storage, queue, AI server), port detection + auto-assignment, and infrastructure (MongoDB / Redis / AI providers). Run bare `nexus` for a welcome launcher.
 
 Skip dependency install for offline use:
 
@@ -38,7 +48,7 @@ nexus init my-app --no-install
 
 ## Architecture at a glance
 
-N backends × N frontends, all discovered by a single admin SPA. Each backend is an isolated `createNexusApp()` instance with its own port, routes folder, storage root, and per-app config. Docker handles horizontal scaling — `docker compose up --scale backend-main=4` — so the v1 cluster subsystem (master/slave mesh, node agents, autoscaler, load balancer) is gone entirely.
+N backends × N frontends, all discovered by a single admin SPA. Each backend is an isolated `createNexusApp()` instance with its own port, routes folder, storage root, and per-app config. Docker handles horizontal scaling — `docker compose up --scale backend=4` — so the v1 cluster subsystem (master/slave mesh, node agents, autoscaler, load balancer) is gone entirely.
 
 ```
 ┌─────────────────────── Docker Host ───────────────────────┐
@@ -57,11 +67,11 @@ N backends × N frontends, all discovered by a single admin SPA. Each backend is
 │         └──────────┬───────┴──────────────────┘            │
 │                    ▼                                       │
 │   ┌────────┬────────┬──────────┬─────────┬───────────┐     │
-│   │ MongoDB│ Redis  │ storage/ │ S3/CDN  │  queue    │     │
+│   │ MongoDB│ Fusion │ Redis    │ storage/│  S3/CDN   │     │
+│   │ (opt.) │ (opt.) │ (opt.)   │         │           │     │
 │   └────────┴────────┴──────────┴─────────┴───────────┘     │
 │                                                            │
-│   .nexus-ports.json   ← stable port registry               │
-│   nexus.config.ts     ← single source of truth             │
+│   nexus.config.ts     ← single source of truth (incl. apps[])│
 │   docker-compose.yml  ← orchestration                      │
 └────────────────────────────────────────────────────────────┘
 ```
@@ -78,6 +88,8 @@ apps/
 └── ai-server/        FastAPI sidecar (optional)
 ```
 
+Ports are declared in `nexus.config.ts` under `apps[]` (`{ name, port, enabled }`) — the single source of truth for `nexus dev`. There is no `.nexus-ports.json` registry.
+
 ### Per-backend `src/` convention (Laravel-style)
 
 Each backend lives under `apps/<backend>/` and follows a flat, auto-discovered folder convention inspired by Laravel. `createNexusApp()` scans these folders at boot — no manual registration.
@@ -102,6 +114,7 @@ apps/<backend>/src/
 ├── services/                # business logic layer
 ├── repositories/            # DB query layer (encapsulates ODM calls)
 ├── controllers/             # optional route extraction (thin handlers)
+├── handlers/                # extracted route handlers — *.handler.ts
 ├── middleware/              # route-level middleware
 ├── validators/              # zod schemas
 ├── jobs/                    # queue jobs — *Job.ts
@@ -119,7 +132,7 @@ apps/<backend>/src/
 │
 ├── providers/               # *ServiceProvider.ts — DI registration (register + boot)
 ├── plugins/                 # project-local plugins — <name>/index.ts
-├── types/                   # shared TS types
+├── types/                   # shared TS types — *.types.ts
 └── constants/               # app constants
 ```
 
@@ -144,21 +157,22 @@ apps/<backend>/src/
 | `plugins/<name>/index.ts` | folder | Local plugins |
 | `config/*.ts` | folder | Merged into app config |
 
-**Sibling `storage/`** (gitignored, per-backend):
+**Per-backend `storage/` only** (gitignored, no `storage/` at project root or `src/storage`):
 
 ```
-apps/<backend>/storage/
-├── uploads/             # PUBLIC — served at GET /uploads/*
+apps/<backend>/storage/          ← only storage (no project-root storage)
+├── uploads/             # PUBLIC — GET /uploads/*
 ├── private/             # signed-URL only — GET /files/:id?sig=…
 ├── temp/                # multipart assembly chunks (cleaned up)
 ├── cache/
 └── logs/
 ```
+`sha256` dedup — single `uploads` doc per content, `placements[]` per directory, physical symlink to canonical (Local; S3 reuses key). Placeholder `POST /api/files` is always mounted.
 
 ## CLI
 
 ```
-Project    init · dev · build · test · doctor · sync · uninstall · down · up
+Project    init · dev · build · test · doctor · sync · uninstall · pysetup · down · up
 Multi-app  add backend <name>
            add frontend <name> [--for <backend>]
            add route <name> --app <backend>
@@ -167,30 +181,39 @@ Multi-app  add backend <name>
 Data       db:seed · db:migrate · db:rollback
 Queue      queue:work · queue:retry
 Plugins    plugin new · install · remove · list
+License    license add · status · verify · remove
 
-Generators (make:*) — 21 total:
+Generators (make:*) — 22 total:
 route · controller · model · service · repository · middleware · validator ·
-job · event · listener · policy · resource · request · mail · room · subgraph ·
-seeder · migration · provider · plugin
+handler · types · job · event · listener · policy · resource · request · mail ·
+room · subgraph · seeder · migration · provider · plugin
 ```
 
 ## Examples
 
-10 examples ship in `packages/nexus-examples/` and are overlayable via `nexus init --example`:
+**18 examples** ship in `packages/nexus-examples/` (plus the `empty` bare scaffold) and are overlayable via `nexus init --example`:
 
 | 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 |
+| `video-call` | WebRTC signaling + mediasoup SFU, 1:1 call |
+| `checkout` | Razorpay + PayPal payments, mailables, HMAC webhook verify |
+| `livestream` | broadcaster/viewer roles via mediasoup + chat overlay |
+| `ai-chat` | streaming LLM via nexus-ai-client + provider switching |
+| `saas-starter` | auth + billing + teams + policies + admin tab |
+| `blog-crud` | ODM models deep dive + GraphQL federation subgraph |
+| `dashboard` | admin-metrics demo, telemetry dashboards |
+| `file-storage` | local + S3 storage, signed private URLs, image variants |
+| `image-lab` | resize / upscale (Real-ESRGAN) / quality via PythonBridge |
 | `multi-app` | two backends, two frontends, one admin |
+| `future-more` | `future` stack — 7 live pages with shared navbar |
+| `morph-ui` | canvas FLIP morphing — kanban / list / cards |
+| `emotion-garden` | mood (LLM) + time + weather morph a canvas garden |
+| `mario-platformer` | full-page Three.js side-scroller |
+| `python-bridge` | React page ↔ backend bridge → Python chat/stream/embeddings |
+| `python-bridge-future` | `future` live() chat with store + SSE via PythonBridge |
+| `fusion-tree` | interactive `@bhooai/nexus-fusion` explorer + licensed AI |
 
 ### Multi-app example — how to use
 
@@ -203,7 +226,7 @@ npx nexus init my-platform
 # wizard: Starter -> Examples -> pick "multi-app" -> Admin? Yes -> Features/Ports/Infra -> Review & create
 cd my-platform
 
-# scaffold the extra backends (ports auto-assigned in .nexus-ports.json)
+# scaffold the extra backends (ports are added to nexus.config.ts apps[])
 npx nexus add backend shop
 npx nexus add backend api
 
@@ -242,17 +265,41 @@ apps/
 
 Each `apps/backend-*` is an isolated `createNexusApp()` with its own `src/routes`, `src/ws`, `src/models`, etc. auto-discovered. Verify with `curl http://localhost:4010/api/products` and `curl http://localhost:4011/api/users` after `nexus dev` prints the port map. See `packages/nexus-examples/examples/multi-app/README.md`.
 
-## Storage
+## Fusion — embedded database
 
-Per-backend `storage/` folder with `local` + `s3` drivers shipped:
+`@bhooai/nexus-fusion` is a from-scratch embedded database: a **Rust core** (branched decomposition tree, append-only WAL with a binary format + field-name interning, query engine, LRU/TTL cache, sortable id generation) exposed through a **Firebase-style TypeScript API**.
+
+```ts
+import { fusion } from 'bhooai-nexus/fusion';
+
+const db = fusion('main', 'prod', { dir: 'storage/fusion' });
+const users = db.collection('users');
+await users.add({ name: 'Ada', city: 'London' });
+
+const q = users.where('city', '==', 'London').orderByField('name').limit(10);
+q.onSnapshot((snap) => console.log(snap.docs));
+```
+
+- **Offline queue** — optimistic overlay with retry/sync (`queueSet`/`queueUpdate`/`sync`).
+- **Security rules** — pattern DSL with `{param}` capture, most-specific match, default-deny.
+- **Declarative schemas** — `@bhooai/nexus-fusion/schemas` for auth / cms / ecommerce field specs.
+- **`FusionCache`** — a Redis-like API (strings, hashes, lists, sets, `keys`/`expire`) over the same engine, on-disk or in-RAM (`bhooai-nexus/fusion`).
+- **Adapters** — optional `MongoMirror` and `RedisBridge` for migration / fan-out.
+- **Playground** — a 3D tree explorer + JSON command console, shipped in the `fusion-tree` example.
+
+Config lives under `db.active: 'mongodb' | 'fusion'` plus `fusion`/`cache` blocks in `nexus.config.ts`. See `docs/FUSION.md` and `docs/fusion-stores-and-cache.md`.
+
+## Storage (per-backend only)
+
+Per-backend `storage/` folder (`apps/<backend>/storage`, no project-root `storage/`) with `local` + `s3` drivers:
 
 ```ts
 import { storage } from 'bhooai-nexus';
-await storage.disk('uploads').put('avatars', file);
+await storage.disk('uploads').put('avatars', file); // → apps/backend/storage/uploads/avatars/YYYY/MM/<id>
 const url = await storage.disk('private').signedUrl('invoices/1.pdf');
 ```
 
-UUID filenames + `YYYY/MM` sharding. EXIF-stripped. sharp-driven image transforms.
+Per-placement `YYYY/MM` + `sha256` single `uploads` doc (`placements[]` per directory, symlink to canonical, millions-scale). EXIF-stripped. Python Pillow + Real-ESRGAN (no sharp) via `POST /images/variants` (`NEXUS_IMAGES_URL`), placeholder `POST /api/files` always mounted.
 
 ## Importing the framework
 
@@ -263,26 +310,29 @@ import { createNexusApp, storage, model, Schema, AiClient, defineRoutes } from '
 ```
 
 Prefer narrower imports for smaller bundles? Use the sub-path exports
-(`bhooai-nexus/core`, `bhooai-nexus/data`, `bhooai-nexus/ai-client`, …) or the
+(`bhooai-nexus/core`, `bhooai-nexus/data`, `bhooai-nexus/ai-client`, `bhooai-nexus/fusion`, …) or the
 scoped packages (`@bhooai/nexus-core`, `@bhooai/nexus-data`, …) directly.
 
 ## Packages
 
-18 workspace packages ship under `packages/`, each independently versioned and re-exported by the umbrella `bhooai-nexus` package.
+**21 workspace packages** ship under `packages/`, each independently versioned and re-exported by the umbrella `bhooai-nexus` package.
 
 | Package | Scope | Import path | Purpose |
 |---|---|---|---|
-| nexus-admin | `@bhooai/nexus-admin` | `bhooai-nexus/admin` | Admin SPA — Apps-tab-first, live registry/health/logs/config/users/payments/AI |
+| nexus-admin | `@bhooai/nexus-admin` | `bhooai-nexus/admin` | Admin SPA — Apps-tab-first, live registry/health/logs/config/users/payments/AI/uploads |
 | nexus-ads | `@bhooai/nexus-ads` | — | Advertising module |
 | nexus-ai-client | `@bhooai/nexus-ai-client` | `bhooai-nexus/ai-client` | AI provider client (streaming, provider switching) |
 | nexus-auth | `@bhooai/nexus-auth` | `bhooai-nexus/auth` | Authentication (JWT, OAuth, sessions, refresh tokens) |
 | nexus-cache | `@bhooai/nexus-cache` | `bhooai-nexus/cache` | Caching layer (Redis-backed) |
-| nexus-cli | `@bhooai/nexus-cli` | `bhooai-nexus/cli` | CLI — init, dev, build, test, scaffolding, plugins, queue, db |
+| nexus-cli | `@bhooai/nexus-cli` | `bhooai-nexus/cli` | CLI — init, dev, build, test, scaffolding, plugins, queue, db, license |
 | nexus-core | `@bhooai/nexus-core` | `bhooai-nexus/core` | Core — `createNexusApp()`, auto-discovery, HTTP, storage facade, abstractions |
-| nexus-crypto | `@bhooai/nexus-crypto` | `bhooai-nexus/crypto` | Cryptography utilities |
+| nexus-crypto | `@bhooai/nexus-crypto` | `bhooai-nexus/crypto` | Cryptography utilities + license key derivation (HKDF-SHA256) |
 | nexus-data | `@bhooai/nexus-data` | `bhooai-nexus/data` | Custom ODM for MongoDB (schemas, hooks, populate) |
 | nexus-email | `@bhooai/nexus-email` | `bhooai-nexus/email` | Email sending (Mailable classes, EJS templates) |
-| nexus-examples | `@bhooai/nexus-examples` | `bhooai-nexus/examples` | 10 working examples, each demoing a framework slice |
+| nexus-examples | `@bhooai/nexus-examples` | `bhooai-nexus/examples` | 18 working examples, each demoing a framework slice |
+| nexus-fusion | `@bhooai/nexus-fusion` | `bhooai-nexus/fusion` | Embedded database — Firebase-style TS API (onSnapshot, offline queue, rules) over a Rust core |
+| nexus-fusion-core | `nexus-fusion-core` | — | The Rust crate (NAPI addon) powering `nexus-fusion` |
+| nexus-future | `@bhooai/nexus-future` | `bhooai-nexus/future` | Zero-build stack — `live()` HTML + auto-WS updates + AI streaming, signals, `page()`, `autoui()` |
 | nexus-graphql | `@bhooai/nexus-graphql` | `bhooai-nexus/graphql` | GraphQL federation layer (subgraphs, supergraph) |
 | nexus-payments | `@bhooai/nexus-payments` | `bhooai-nexus/payments` | Payments (Razorpay, PayPal, HMAC webhook verify) |
 | nexus-plugins | `@bhooai/nexus-plugins` | `bhooai-nexus/plugins` | Plugin system (new/install/remove/list) |
@@ -291,6 +341,19 @@ scoped packages (`@bhooai/nexus-core`, `@bhooai/nexus-data`, …) directly.
 | nexus-safe-goto | `@bhooai/nexus-safe-goto` | `bhooai-nexus/safe-goto` | Safe external-link navigation (noopener/noreferrer, confirm dialog) |
 | nexus-telemetry | `@bhooai/nexus-telemetry` | `bhooai-nexus/telemetry` | Telemetry / observability |
 
+Two greenfield libraries also ship alongside the packages: the Python `bhooai-nexus-ai` service (`libraries/python`, FastAPI: chat/embeddings/models/lint/preflight + Pillow/Real-ESRGAN images) and the Node `@bhooai/nexus-bridge` client (`libraries/node/nexus-bridge`). See `docs/LIBRARIES.md`.
+
+## License system
+
+`nexus-crypto` implements the framework-side license flow: a master key is verified against the authority and stored at `~/.nexus/license.json`, then each package derives its own key with HKDF-SHA256. Gated features (payments, AI) call `requireLicense()` and throw until a key is present. Minting happens only in the site backend; the framework only consumes/verifies.
+
+```bash
+nexus license add <key>   # verify against the authority, then cache
+nexus license status      # source, fingerprint, live validity
+nexus license verify      # re-check the stored key
+nexus license remove      # delete the stored key
+```
+
 ## Maintenance mode
 
 ```
@@ -303,19 +366,26 @@ All requests return 503 + Retry-After except `/health`.
 ## Tests
 
 ```bash
-npx vitest run
+npx vitest run                                  # root suite (tests/)
+npx vitest run --root packages/nexus-fusion     # per-package suites
 ```
 
-Current suite covers: app factory, event bus, policies, generators name normalization,
-EJS templating. 27 tests, all green.
+The root suite covers app factory, event bus, policies, generators, templating,
+examples, layout, features, and ports (**51 tests**). Per-package suites cover
+core, auth, crypto, data, fusion, graphql, payments, realtime, and more.
+
+> Known stale tests: `tests/unit/features.test.ts` still asserts the removed
+> `defaultPortFor()` helper (from the `.nexus-ports.json` → config `apps[]`
+> migration) — 3 assertions fail, tracked for cleanup.
 
 ## Status
 
 - P0–P12 shipped (skeleton, app factory, abstractions, storage, CLI, plugins, db, queue,
-  generators, port registry, examples, docker, admin strip + Apps tab)
-- 18 workspace packages under `packages/` (see § Packages above)
-- Admin rebuilt as a fresh Apps-tab-first SPA with live backend endpoints
-  (registry, health, request logs, config, users, payments, AI proxy)
+  generators, port registry → config `apps[]`, examples, docker, admin strip + Apps tab)
+- Fusion embedded database shipped (`nexus-fusion` + `nexus-fusion-core`) — WAL v3,
+  repeat-query cache, and a licensed AI layer
+- License system (`nexus-crypto`) + `nexus license` CLI
+- `future` zero-build stack (`live()`, `page()`, `autoui()`) with its own examples
 - `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)
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "bhooai-nexus",
-  "version": "2.0.13",
+  "version": "3.0.4",
   "description": "BhooAI Nexus - a Node-based full-stack framework (websockets, GraphQL federation, inbuilt security, custom ODM, OAuth, payments, WebRTC, AI, plugins). v2: multi-app, Laravel-style folders, Docker-based scaling.",
   "license": "MIT",
-  "author": "BhooAI",
+  "author": "BhooAI - oravianando",
   "keywords": [
     "fullstack",
     "framework",
@@ -18,25 +18,26 @@
     "ai",
     "admin",
     "cli",
+    "monorepo",
     "scaffold"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/bhooai/nexus.git"
+    "url": "https://github.com/oravianando/BhooAI-Nexus.git"
   },
-  "homepage": "https://github.com/bhooai/nexus#readme",
+  "homepage": "https://github.com/oravianando/BhooAI-Nexus#readme",
   "bugs": {
-    "url": "https://github.com/bhooai/nexus/issues"
+    "url": "https://github.com/oravianando/BhooAI-Nexus/issues"
   },
   "funding": {
     "type": "github",
-    "url": "https://github.com/sponsors/bhooai"
+    "url": "https://github.com/sponsors/oravianando"
   },
   "bin": {
     "nexus": "bin/nexus.js"
   },
   "exports": {
-    ".": "./src/index.ts",
+    ".": "./src/index.js",
     "./core": "./packages/nexus-core/src/index.ts",
     "./core/http": "./packages/nexus-core/src/http/index.ts",
     "./auth": "./packages/nexus-auth/src/index.ts",
@@ -59,6 +60,16 @@
     "./graphql": "./packages/nexus-graphql/src/index.ts",
     "./graphql/hello": "./packages/nexus-graphql/src/builtin/helloSubgraph.ts",
     "./graphql/builtin": "./packages/nexus-graphql/src/builtin/index.ts",
+    "./future": "./packages/nexus-future/src/index.js",
+    "./future/html": "./packages/nexus-future/src/html/index.js",
+    "./future/live": "./packages/nexus-future/src/live/index.js",
+    "./future/page": "./packages/nexus-future/src/page/index.js",
+    "./future/ai": "./packages/nexus-future/src/ai/index.js",
+    "./future/server": "./packages/nexus-future/src/server/mount.js",
+    "./future/mock": "./packages/nexus-future/src/ai/mock.js",
+    "./future/ui": "./packages/nexus-future/src/ui/index.js",
+    "./fusion": "./packages/nexus-fusion/src/index.ts",
+    "./fusion/schemas": "./packages/nexus-fusion/src/schemas/index.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -68,8 +79,7 @@
     "packages/*/src/**",
     "packages/*/package.json",
     "packages/nexus-cli/templates/**",
-    "packages/nexus-examples/examples/**",
-    "docs/"
+    "packages/nexus-examples/examples/**"
   ],
   "type": "module",
   "engines": {
@@ -77,7 +87,8 @@
   },
   "workspaces": [
     "packages/*",
-    "apps/*"
+    "apps/*",
+    "libraries/node/*"
   ],
   "scripts": {
     "build": "node bin/nexus.js build",
@@ -101,7 +112,9 @@
     "@bhooai/nexus-graphql": "^2.0.1",
     "@bhooai/nexus-telemetry": "^2.0.1",
     "@bhooai/nexus-admin": "^2.0.1",
+    "@bhooai/nexus-future": "^3.0.0",
     "@bhooai/nexus-examples": "^2.0.1",
+    "@bhooai/nexus-fusion": "^0.1.0",
     "bcryptjs": "^2.4.3",
     "jose": "^5.9.6",
     "mongodb": "^6.9.0",
@@ -109,13 +122,9 @@
     "zod": "^3.23.8"
   },
   "peerDependencies": {
-    "sharp": "^0.33.0",
     "@aws-sdk/client-s3": "^3.0.0"
   },
   "peerDependenciesMeta": {
-    "sharp": {
-      "optional": true
-    },
     "@aws-sdk/client-s3": {
       "optional": true
     }

package/packages/nexus-admin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/nexus-admin",
-  "version": "2.0.14",
+  "version": "2.0.17",
   "description": "BhooAI Nexus v2 admin SPA — Apps-tab-first, live registry/health/logs/config/users/payments/AI",
   "type": "module",
   "license": "MIT",