bhooai-nexus 2.0.11 → 2.0.12

package/docs/ARCHITECTURE.md

@@ -60,7 +60,7 @@ the registry via `lookupPort()` at scaffold time and bake the port into
 
 1. `loadConfigAuto()` — config stack: code defaults < nexus.config.ts <
    nexus.runtime.json < NEXUS_* env vars < CLI flags
-2. `discoverBackend(srcRoot)` — walks 14 folder patterns:
+ 2. `discoverBackend(srcRoot)` — walks 14 flat folder patterns:
 
    | Folder          | Pattern                          | Used as |
    |-----------------|----------------------------------|---------|
@@ -81,6 +81,8 @@ the registry via `lookupPort()` at scaffold time and bake the port into
    | plugins/<n>/    | `index.ts`                       | Local plugins |
    | config/         | `*.ts`                           | Merged into app config |
 
+   Flat workflow with dot-namespaced types: `src/types/blog.post.types.ts`, `src/middleware/validatePost.ts`, `src/models/Post.ts`, `src/services/PostService.ts`. Example: `blog-crud` uses `src/types/blog.post.types.ts` + `src/middleware/validatePost.ts` + `src/routes/posts.ts` (thin → `PostService`). `discover` also still scans legacy `src/modules/*/…` via `collectWithModules` for backward compat.
+
 3. Configures cross-cutting services:
    - `configureStorageFromEnv()` — Storage facade with `local` + `s3` disks
    - `configureQueue()` — Job queue adapter (in-memory default, Redis-ready)

package/docs/CONVENTIONS.md

@@ -49,6 +49,26 @@ export const prefix = '/api/v2';
 
 Optional per-route fields: `middleware`, `upload`, `rateLimit`, `public`, `request`.
 
+Routes are **thin** — handlers live in `src/handlers/`:
+
+```ts
+// handlers/chat.handler.ts
+import type { RequestContext } from '@bhooai/nexus-core';
+import { Message } from '../models/Message.js';
+export async function listMessages(ctx: RequestContext) { /* ... */ }
+export async function sendMessage(ctx: RequestContext) { /* ... */ }
+
+// routes/chat.ts
+import { defineRoutes } from '@bhooai/nexus-core';
+import { validateMessage } from '../middleware/validateMessage.js';
+import { listMessages, sendMessage } from '../handlers/chat.handler.js';
+export default defineRoutes([
+  { method:'GET', path:'/api/chat/rooms/:roomId/messages', handler: listMessages },
+  { method:'POST', path:'/api/chat/rooms/:roomId/messages', middleware:[validateMessage], handler: sendMessage },
+]);
+```
+Generate with `nexus make:handler chat` → `src/handlers/chat.handler.ts` (`handlers/<name>.handler.ts` — not auto-discovered, imported by routes).
+
 ## graphql/
 
 Files matching `*.graph.ts` export typeDefs + resolvers:
@@ -155,21 +175,51 @@ Run with `nexus queue:work --queue mail`.
 `register(container)` wires DI singletons; `boot(container)` runs async init
 after all providers are registered.
 
-## models/, services/, repositories/, controllers/, middleware/, validators/, requests/, resources/
+## handlers/ — route handlers (separate folder)
 
-These are NOT auto-wired — import them yourself from routes/jobs/listeners.
-They exist so your routes stay thin:
+`src/handlers/<name>.handler.ts` exports plain `Handler` functions (`(ctx: RequestContext)=>...`). **Not auto-discovered** — routes import them. Prefer one file per domain (`chat.handler.ts` with `listMessages, sendMessage`, `blog.handler.ts` with `listPosts, createPost, ...`). Keeps `routes/` declarative (10–20 LOC) and testable.
 
 ```
-routes/users.ts      → controllers/UserController.ts    (route action)
-                     → services/UserService.ts          (business rules)
-                     → repositories/UserRepository.ts   (Mongo queries)
-                     → models/User.ts                   (ODM model)
-                     → validators/user.schema.ts        (zod)
-                     → requests/CreateUserRequest.ts    (zod + authorize)
-                     → resources/UserResource.ts        (response shape)
+src/handlers/
+  chat.handler.ts       # listMessages, sendMessage
+  blog.handler.ts       # listPosts, createPost, getPost, updatePost, deletePost, createComment
+  checkout.handler.ts   # createOrder, webhook
+  file.handler.ts       # listFiles, uploadPublic, …
 ```
 
+## models/, services/, repositories/, controllers/, middleware/, validators/, requests/, resources/, types/ — flat src/<folder> (canonical)
+
+These are **not auto-wired** — import them yourself from `routes/handlers/jobs/listeners`. They exist so routes+handlers stay thin. Use **flat** `src/<folder>` with **dot-namespaced types** for domain separation (no extra `modules/` folder):
+
+```
+src/
+  models/{Post.ts, User.ts, Team.ts}              # ODM — model('posts', schema)
+  types/blog.post.types.ts                        # DTOs + Zod (PostDto, CreatePostInput) — dot namespaced
+  types/blog.author.types.ts
+  types/chat.message.types.ts
+  types/saas.team.types.ts
+  types/checkout.order.types.ts
+  routes/posts.ts                                 # defineRoutes (thin → services)
+  services/PostService.ts                         # business logic
+  repositories/PostRepository.ts                  # Mongo queries (Db)
+  middleware/validatePost.ts                      # Middleware (ctx,next)
+  middleware/validateMessage.ts
+  middleware/auth.ts
+  validators/post.schema.ts                       # Zod
+  graphql/post.graph.ts                           # defineSubgraph (imports ../models/Post.js)
+  ws/chat.room.ts
+
+routes/posts.ts      → services/PostService.ts
+                     → repositories/PostRepository.ts
+                     → models/Post.ts
+                     → types/blog.post.types.ts   # `import { CreatePostInput } from '../types/blog.post.types.js'`
+                     → validators/post.schema.ts
+                     → middleware/validatePost.ts  # `import { validatePost } from '../middleware/validatePost.js'`
+                     → resources/PostResource.ts
+```
+
+Generate with flat commands: `nexus make:model Post`, `nexus make:types blog.post`, `nexus make:middleware validatePost`, `nexus make:route posts`, `nexus make:service PostService`. No `--module` flag. Legacy `src/modules/*` is still discovered via `collectWithModules` (`discover.ts:115`) for backward compat but not recommended.
+
 ## database/
 
 - `seeds/*Seeder.ts` — classes extending `Seeder`. `nexus db:seed`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bhooai-nexus",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "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",
@@ -56,6 +56,9 @@
     "./postcss": "./packages/nexus-postcss/src/index.js",
     "./postcss/theme.css": "./packages/nexus-postcss/src/theme.css",
     "./examples": "./packages/nexus-examples/src/index.ts",
+    "./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",
     "./package.json": "./package.json"
   },
   "files": [

package/packages/nexus-admin/package.json

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

package/packages/nexus-admin/src/App.tsx

@@ -19,7 +19,7 @@ import {
 } from './api.js';
 
 
-type Tab = 'overview' | 'processes' | 'logs' | 'config' | 'env' | 'plugins' | 'users' | 'monitoring' | 'payments' | 'databases' | 'schema' | 'ai' | 'theme';
+type Tab = 'overview' | 'processes' | 'logs' | 'config' | 'env' | 'plugins' | 'users' | 'monitoring' | 'payments' | 'databases' | 'schema' | 'ai' | 'graphql' | 'theme';
 type AdminTheme = 'aurora' | 'midnight' | 'violet';
 type UiMode = 'workspace' | 'compact' | 'focus';
 type ToggleStyle = 'chip' | 'neon' | 'icon' | 'orb' | 'track';
@@ -459,6 +459,7 @@ function Dashboard({ user, onUserChange, onLogout }: { user: AdminUser | null; o
     { id: 'databases', label: 'Databases', icon: 'database', keywords: ['mongo', 'mongodb', 'collections', 'data', 'tables', 'docs'], desc: 'Databases, collections and their documents.' },
     { id: 'schema', label: 'AI Schema', icon: 'sparkles', keywords: ['generate', 'ai', 'model', 'json schema', 'validator'], desc: 'Generate MongoDB schemas from plain English.' },
     { id: 'ai', label: 'AI Agents', icon: 'bot', keywords: ['providers', 'chat', 'playground', 'ollama', 'openai', 'models', 'settings'], desc: 'AI settings, providers and chat playground.' },
+    { id: 'graphql', label: 'GraphQL', icon: 'gitFork', keywords: ['graphiql', 'explorer', 'schema', 'playground', 'graphql', 'api'], desc: 'GraphQL explorer and access control.' },
     { id: 'theme', label: 'Theme Centre', icon: 'palette', keywords: ['appearance', 'colors', 'palette', 'ui', 'customize', 'surface'], desc: 'Curated themes, palettes and surface tuning.' },
   ];
   const searchResults = useMemo(() => {
@@ -645,6 +646,7 @@ function Dashboard({ user, onUserChange, onLogout }: { user: AdminUser | null; o
             {tab === 'databases' && <Databases />}
             {tab === 'schema' && <Schema />}
             {tab === 'ai' && <AiAgents toggle={customTheme.toggle} />}
+            {tab === 'graphql' && <GraphQLSettings onNavigate={setTab} />}
             {tab === 'theme' && <ThemeCentre theme={theme} onThemeChange={(value) => { setTheme(value); window.localStorage.setItem('nexus-admin-theme', value); }} uiMode={uiMode} onUiModeChange={(value) => { setUiMode(value); window.localStorage.setItem('nexus-admin-ui', value); }} custom={customTheme} onCustom={updateCustomTheme} particles={particles} onParticles={updateParticles} />}
           </main>
           <aside className="admin-inspector">
@@ -2173,7 +2175,7 @@ function AiProviders({ toggle }: { toggle: ToggleStyle }) {
   const [showAdd, setShowAdd] = useState(false);
   const [newProvider, setNewProvider] = useState({ id: '', label: '', baseUrl: '', apiKey: '', defaultModel: '' });
   const [query, setQuery] = useState('');
-  const [filter, setFilter] = useState<ProviderFilter>('enabled');
+  const [filter, setFilter] = useState<ProviderFilter>('all');
   const [testingId, setTestingId] = useState<string | null>(null);
   const [testResults, setTestResults] = useState<Record<string, AiProviderTestResult>>({});
   const [keyEditorProvider, setKeyEditorProvider] = useState<AiProviderView | null>(null);
@@ -2185,7 +2187,14 @@ function AiProviders({ toggle }: { toggle: ToggleStyle }) {
   const wait = (ms: number) => new Promise<void>((resolve) => window.setTimeout(resolve, ms));
 
   const loadProviders = async () => {
-    try { const r = await getAiProviders(); setProviders(r.providers ?? []); } catch { /* non-fatal */ }
+    try {
+      const r = await getAiProviders();
+      setProviders(r.providers ?? []);
+      if (!r.providers?.length) setMsg('No providers returned — is the backend running and are you logged in as admin?');
+      else setMsg('');
+    } catch (e: any) {
+      setMsg(`Failed to load providers: ${String(e?.message ?? e)} — ensure you are logged in as admin (403 = not admin, 401 = not logged in).`);
+    }
   };
 
   const persistenceNote = (persistence?: AiProviderPersistence): string => {
@@ -2349,6 +2358,11 @@ function AiProviders({ toggle }: { toggle: ToggleStyle }) {
             <button onClick={() => setShowAdd(true)} disabled={busy} className="glass-chip-btn">+ add provider</button>
           </div>
         </div>
+        {msg && (
+          <div role="status" className={`rounded-lg border px-3 py-2 text-xs ${msg.includes('Failed') || msg.includes('No providers') ? 'border-amber-500/30 bg-amber-500/10 text-amber-300' : 'border-sky-400/20 bg-sky-400/10 text-sky-300'}`}>
+            {msg}
+          </div>
+        )}
 
         {/* Filter bar */}
         <div className="provider-filter-bar">
@@ -3229,6 +3243,94 @@ function Plugins() {
   );
 }
 
+function GraphQLSettings({ onNavigate }: { onNavigate?: (tab: Tab) => void }) {
+  const [cfg, setCfg] = useState<AdminConfig | null>(null);
+  const [explorer, setExplorer] = useState(true);
+  const [requireAuth, setRequireAuth] = useState(false);
+  const [msg, setMsg] = useAdminAlert('graphql');
+  const [busy, setBusy] = useState(false);
+  const [restartDialog, setRestartDialog] = useState(false);
+
+  const load = async () => {
+    try {
+      const c = await getAdminConfig();
+      setCfg(c);
+      const g = (c.config?.graphql ?? {}) as Record<string, unknown>;
+      setExplorer(g.explorer !== false);
+      setRequireAuth(!!g.explorerRequireAuth);
+    } catch (e: any) { setMsg(String(e?.message ?? e)); }
+  };
+  useEffect(() => { load(); }, []);
+
+  const save = async () => {
+    setBusy(true); setMsg('');
+    try {
+      await putAdminConfig({ graphql: { explorer, explorerRequireAuth: requireAuth } });
+      setMsg('Saved to nexus.runtime.json. Restart services to apply changes.');
+      setRestartDialog(true);
+    } catch (e: any) { setMsg(`Error: ${e?.message ?? e}`); }
+    finally { setBusy(false); }
+  };
+
+  const g = (cfg?.config?.graphql ?? {}) as Record<string, unknown>;
+  const path = (g.path as string) ?? '/graphql';
+  const introspection = g.introspection !== false;
+
+  return (
+    <div className="space-y-6">
+      <PageHead title="GraphQL" />
+      <PageHero kicker="GRAPHQL WORKSPACE" title={<>Explore your <em>schema.</em></>} desc="Control the GraphiQL explorer and gate it behind an admin access token." glyph="gitFork" art="grid" />
+
+      <section className="glass-card space-y-3">
+        <h3 className="glass-h3">GraphiQL explorer</h3>
+        <p className="text-xs text-slate-500">The interactive sandbox is served at <code className="font-mono text-slate-300">{path}</code> (page) and <code className="font-mono text-slate-300">/graphiql</code>. The <code className="font-mono text-slate-300">/graphql</code> JSON endpoint is always public.</p>
+        <div className="grid grid-cols-1 gap-3 md:grid-cols-2">
+          <div className="glass flex items-center justify-between rounded-xl px-3 py-2">
+            <div>
+              <span className="admin-overline">EXPLORER</span>
+              <div className="text-sm text-slate-200">Enable GraphiQL</div>
+            </div>
+            <button onClick={() => setExplorer(!explorer)} className={`glass-chip-btn ${explorer ? 'is-on' : ''}`}>{explorer ? 'On' : 'Off'}</button>
+          </div>
+          <div className="glass flex items-center justify-between rounded-xl px-3 py-2">
+            <div>
+              <span className="admin-overline">ACCESS</span>
+              <div className="text-sm text-slate-200">Require admin token</div>
+            </div>
+            <button onClick={() => setRequireAuth(!requireAuth)} className={`glass-chip-btn ${requireAuth ? 'is-on' : ''}`}>{requireAuth ? 'On' : 'Off'}</button>
+          </div>
+        </div>
+        <div className="grid grid-cols-1 gap-3 md:grid-cols-2">
+          {([
+            ['Endpoint', path],
+            ['Introspection', introspection ? 'enabled' : 'disabled'],
+          ] as const).map(([label, value]) => (
+            <div key={label} className="glass rounded-xl px-3 py-2">
+              <span className="admin-overline">{label}</span>
+              <code className="block mt-1 truncate font-mono text-sm text-slate-200">{value}</code>
+            </div>
+          ))}
+        </div>
+        {requireAuth && <p className="text-xs text-amber-400">When enabled, opening /graphiql requires an active admin session (same guard as /admin/*).</p>}
+        {msg && <p className="text-xs text-slate-400">{msg}</p>}
+        <div className="flex items-center justify-end gap-2">
+          <button onClick={load} className="glass-chip-btn"><Icon name="refresh" size={12} /> Reload</button>
+          <button onClick={save} disabled={busy} className="glass-chip-btn-primary shrink-0">{busy ? 'Saving…' : 'Save'} <span>→</span></button>
+        </div>
+      </section>
+
+      <ConfirmDialog
+        open={restartDialog}
+        title="Restart required"
+        message="Your GraphQL settings have been saved. Restart the backend services to apply the new configuration."
+        confirmLabel="Open services"
+        onConfirm={() => { setRestartDialog(false); onNavigate?.('processes'); }}
+        onCancel={() => setRestartDialog(false)}
+      />
+    </div>
+  );
+}
+
 function Users({ currentUserEmail }: { currentUserEmail?: string }) {
   const [data, setData] = useState<{ users: UserRecord[] } | null>(null);
   const [roles, setRoles] = useState<RoleDefinition[]>([]);

package/packages/nexus-ads/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-ads",
-    "version": "2.0.10",
+    "version": "2.0.11",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-ai-client/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-ai-client",
-    "version": "2.0.10",
+    "version": "2.0.11",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-auth/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-auth",
-    "version": "2.0.10",
+    "version": "2.0.11",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-auth/src/csrf.ts

@@ -68,6 +68,29 @@ export function issueCsrfToken(ctx: RequestContext, options: CsrfOptions = {}):
   return issueToken(ctx, options.cookieName ?? 'nexus_csrf', options.cookie ?? { path: '/', sameSite: 'lax', secure: false });
 }
 
+/**
+ * Read the existing double-submit cookie token WITHOUT rotating it. Returns the
+ * current `nexus_csrf` value, or undefined when no cookie is present. Use this
+ * (not `issueCsrfToken`) when you only need to expose the token, so the cookie
+ * stays stable and previously-issued tokens keep matching.
+ */
+export function getCsrfToken(ctx: RequestContext, options: CsrfOptions = {}): string | undefined {
+  return readCookie(ctx, options.cookieName ?? 'nexus_csrf');
+}
+
+/**
+ * Verify a mutation's CSRF token against the double-submit cookie. The token may
+ * be carried either as an argument (`csrf`) or in the `X-CSRF-Token` header; only
+ * one needs to match the cookie (never both). Both channels stay cookie-bound:
+ * the provided token must equal the `nexus_csrf` cookie value.
+ */
+export function verifyMutationCsrf(ctx: RequestContext, argToken: string | undefined, headerToken?: string | undefined, options: CsrfOptions = {}): boolean {
+  const cookieToken = readCookie(ctx, options.cookieName ?? 'nexus_csrf');
+  if (!cookieToken) return false;
+  const provided = argToken ?? headerToken;
+  return !!provided && timingSafeEqual(cookieToken, provided);
+}
+
 /** CSRF + origin check for the WebSocket upgrade request (no CORS preflight). */
 export function checkWsUpgrade(headers: Record<string, string | string[] | undefined>, options: CsrfOptions = {}): void {
   const trusted = options.trustedOrigins ?? [];

package/packages/nexus-cache/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-cache",
-    "version": "2.0.10",
+    "version": "2.0.11",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/nexus-cli",
-  "version": "2.0.12",
+  "version": "2.0.13",
   "description": "BhooAI Nexus v2 CLI — init, dev, build, test, scaffolding, plugins, queue, db.",
   "license": "MIT",
   "type": "module",

package/packages/nexus-cli/src/commands/add.ts

@@ -205,6 +205,7 @@ export default defineConfig({
     proxy: {
       '/api':     { target: \`http://\${backendHost}:${backendPort}\`, changeOrigin: true },
       '/uploads': { target: \`http://\${backendHost}:${backendPort}\`, changeOrigin: true },
+      '/files':   { target: \`http://\${backendHost}:${backendPort}\`, changeOrigin: true },
       '/ws':      { target: \`ws://\${backendHost}:${backendPort}\`, ws: true },
     },
   },

package/packages/nexus-cli/src/commands/init.ts

@@ -212,7 +212,7 @@ export async function run(ctx: CommandContext): Promise<void> {
 
   // 6. Summary
   console.log(`
-✓ Project scaffolded at ${targetDir}
+ ✓ Project scaffolded at ${targetDir}
 
 Next steps:
   cd ${name}
@@ -223,9 +223,10 @@ Ports allocated:
   Frontend  : ${includeFrontend ? vars.frontendPort : '(not included)'}
   Admin     : ${includeAdmin ? vars.adminPort : '(not included)'}
   AI server : ${includeAi ? vars.aiPort : '(not included)'}
-`);
-
+ `);
 
+  // Ensure stdin is paused so Node can drain naturally after TUI exit (even on npm failure → exit to shell).
+  try { process.stdin.pause(); } catch {}
 }
 
 /** Run `npm install` in a directory; returns the exit code. */