bhooai-nexus 2.0.11 → 2.0.13

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.13",
   "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.14",
   "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,117 @@ 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;
+
+  // Build a directly-openable explorer URL (backend origin + path). The admin
+  // and backend share a host in local dev, so use the browser origin + the
+  // backend port from the merged config.
+  const serverCfg = (cfg?.config?.server ?? {}) as { port?: number };
+  const backendPort = serverCfg.port ?? 4000;
+  const explorerUrl = `${window.location.protocol}//${window.location.hostname}:${backendPort}/graphiql`;
+
+  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">Open the explorer</h3>
+        <p className="text-xs text-slate-500">Jump straight into the interactive GraphiQL sandbox on the backend.</p>
+        <div className="flex flex-wrap items-center gap-3">
+          <a
+            href={explorerUrl}
+            target="_blank"
+            rel="noreferrer"
+            className="glass-chip-btn-primary inline-flex items-center gap-2 px-4 py-2 text-sm"
+          >
+            <Icon name="gitFork" size={14} /> Open GraphQL explorer <Icon name="externalLink" size={12} />
+          </a>
+          <code className="font-mono text-xs text-slate-400">{explorerUrl}</code>
+        </div>
+      </section>
+
+      <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.12",
     "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.12",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-auth/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-auth",
-    "version": "2.0.10",
+    "version": "2.0.12",
     "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.12",
     "publishConfig": {
         "access": "public"
     },

package/packages/nexus-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bhooai/nexus-cli",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "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

@@ -8,10 +8,11 @@
  * Always interactive (the wizard). Requires a TTY; in a non-interactive
  * context it prints a message and exits non-zero. `--no-install` skips the
  * dependency install, `--force` overwrites an existing target directory.
- * `--dev` rewrites bhooai-nexus + @bhooai/* to file:../../PACKAGES/bhooai-nexus
+ * `--dev` rewrites bhooai-nexus + @bhooai/* (incl. the admin app's
+ * @bhooai/nexus-admin + @bhooai/nexus-safe-goto) to file:../../PACKAGES/bhooai-nexus
  * (relative) and runs `npm link` for live symlink.
  */
-import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { mkdir, writeFile, readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { join, resolve, dirname, relative, sep } from 'node:path';
@@ -204,7 +205,7 @@ export async function run(ctx: CommandContext): Promise<void> {
       if (devMode) {
         console.log(`\n[dev] Linking local packages for live symlink...\n`);
         const linkCode = await runNpmLinkForDev(targetDir);
-        if (linkCode === 0) console.log(`\n[dev] Live symlink ready — edits in ${resolveLocalBhooaiNexusRoot() ?? 'PACKAGES/bhooai-nexus'} reflect instantly.`);
+        if (linkCode === 0) console.log(`\n[dev] Live symlink ready — edits in ${resolveLocalBhooaiNexusRoot() ?? 'PACKAGES/bhooai-nexus'} (incl. admin) reflect instantly.`);
         else console.warn(`\n[dev] npm link failed (code ${linkCode}) — fallback to file: copy (re-run npm install after edits).`);
       }
     }
@@ -212,7 +213,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 +224,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. */
@@ -259,47 +261,79 @@ function resolveLocalBhooaiNexusRoot(): string | null {
   return null;
 }
 
-async function rewriteToLocalFileDeps(targetDir: string): Promise<{ count: number; root: string; entries: Array<{ name: string; spec: string }> }> {
-  const localRoot = resolveLocalBhooaiNexusRoot();
+/**
+ * Rewrite bhooai-nexus + @bhooai/* deps to local `file:` specs in the root
+ * package.json AND every app workspace package.json (notably apps/admin, which
+ * depends on @bhooai/nexus-admin + @bhooai/nexus-safe-goto). This ensures a
+ * `--dev` scaffold serves the local admin source, not the published npm copy.
+ *
+ * `localRootOverride` lets tests pin the local repo root; when omitted it is
+ * resolved automatically.
+ */
+export async function rewriteToLocalFileDeps(
+  targetDir: string,
+  localRootOverride?: string,
+): Promise<{ count: number; root: string; entries: Array<{ name: string; spec: string }> }> {
+  const localRoot = localRootOverride ?? resolveLocalBhooaiNexusRoot();
   if (!localRoot) return { count: 0, root: '', entries: [] };
-  const pkgPath = join(targetDir, 'package.json');
-  let raw: string;
-  try { raw = await readFile(pkgPath, 'utf8'); } catch { return { count: 0, root: localRoot, entries: [] }; }
-  let pkg: any;
-  try { pkg = JSON.parse(raw); } catch { return { count: 0, root: localRoot, entries: [] }; }
   const entries: Array<{ name: string; spec: string }> = [];
-  const toFileSpec = (abs: string) => {
-    let rel = relative(targetDir, abs).replace(/\\/g, '/');
-    if (!rel.startsWith('.')) rel = './' + rel;
-    // Use forward slashes for file: spec (npm supports both, but posix is more portable)
-    return `file:${rel}`;
-  };
-  const maybeRewrite = (obj: Record<string, string> | undefined) => {
-    if (!obj) return;
-    for (const name of Object.keys(obj)) {
-      if (name === 'bhooai-nexus') {
-        const spec = toFileSpec(localRoot);
-        obj[name] = spec;
-        entries.push({ name, spec });
-      } else if (name.startsWith('@bhooai/')) {
-        const short = name.replace('@bhooai/', '');
-        // Map @bhooai/nexus-* -> packages/nexus-<short> ; @bhooai/nexus -> packages/nexus-core? but we keep generic
-        const pkgDir = join(localRoot, 'packages', short === 'nexus' ? 'nexus-core' : short.startsWith('nexus-') ? short : `nexus-${short}`);
-        // Fallback: try packages/<name without @bhooai/> and packages/nexus-<name>
-        const candidates = [join(localRoot, 'packages', name.replace('@bhooai/', '')), join(localRoot, 'packages', `nexus-${short}`), pkgDir];
-        let found: string | null = null;
-        for (const c of candidates) if (existsSync(join(c, 'package.json'))) { found = c; break; }
-        if (found) {
-          const spec = toFileSpec(found);
+
+  const rewritePackageJson = async (pkgPath: string): Promise<void> => {
+    const appDir = dirname(pkgPath);
+    let raw: string;
+    try { raw = await readFile(pkgPath, 'utf8'); } catch { return; }
+    let pkg: any;
+    try { pkg = JSON.parse(raw); } catch { return; }
+    const toFileSpec = (abs: string) => {
+      let rel = relative(appDir, abs).replace(/\\/g, '/');
+      if (!rel.startsWith('.')) rel = './' + rel;
+      // Use forward slashes for file: spec (npm supports both, but posix is more portable)
+      return `file:${rel}`;
+    };
+    let changed = false;
+    const maybeRewrite = (obj: Record<string, string> | undefined) => {
+      if (!obj) return;
+      for (const name of Object.keys(obj)) {
+        if (name === 'bhooai-nexus') {
+          const spec = toFileSpec(localRoot);
           obj[name] = spec;
           entries.push({ name, spec });
+          changed = true;
+        } else if (name.startsWith('@bhooai/')) {
+          const short = name.replace('@bhooai/', '');
+          // Map @bhooai/nexus-* -> packages/nexus-<short> ; @bhooai/nexus -> packages/nexus-core
+          const pkgDir = join(localRoot, 'packages', short === 'nexus' ? 'nexus-core' : short.startsWith('nexus-') ? short : `nexus-${short}`);
+          // Fallback: try packages/<name without @bhooai/> and packages/nexus-<name>
+          const candidates = [join(localRoot, 'packages', name.replace('@bhooai/', '')), join(localRoot, 'packages', `nexus-${short}`), pkgDir];
+          let found: string | null = null;
+          for (const c of candidates) if (existsSync(join(c, 'package.json'))) { found = c; break; }
+          if (found) {
+            const spec = toFileSpec(found);
+            obj[name] = spec;
+            entries.push({ name, spec });
+            changed = true;
+          }
         }
       }
-    }
+    };
+    maybeRewrite(pkg.dependencies);
+    maybeRewrite(pkg.devDependencies);
+    if (changed) await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
   };
-  maybeRewrite(pkg.dependencies);
-  maybeRewrite(pkg.devDependencies);
-  if (entries.length) await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+
+  // Root package.json first, then every app workspace package.json.
+  await rewritePackageJson(join(targetDir, 'package.json'));
+  const appsDir = join(targetDir, 'apps');
+  if (existsSync(appsDir)) {
+    let appEntries: import('node:fs').Dirent[] = [];
+    try { appEntries = await readdir(appsDir, { withFileTypes: true }); } catch {}
+    for (const e of appEntries) {
+      if (!e.isDirectory()) continue;
+      const appPkg = join(appsDir, e.name, 'package.json');
+      if (existsSync(appPkg)) await rewritePackageJson(appPkg);
+    }
+  }
+
   return { count: entries.length, root: localRoot, entries };
 }
 
@@ -319,18 +353,29 @@ async function runNpmLinkForDev(targetDir: string): Promise<number> {
     c.on('error', () => resolve(1));
     c.on('exit', (code) => resolve(code ?? 1));
   });
-  // Also link each @bhooai/* that we rewrote to file: (best-effort, ignore failures)
-  try {
-    const pkgRaw = await readFile(join(targetDir, 'package.json'), 'utf8');
-    const pkg = JSON.parse(pkgRaw);
-    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
-    for (const name of Object.keys(allDeps)) if (name.startsWith('@bhooai/')) {
-      await new Promise<void>((r) => {
-        const c = spawn('npm', ['link', name], { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
-        c.on('exit', () => r()); c.on('error', () => r());
-      });
+  // Also link each @bhooai/* that we rewrote to file: in the root AND app
+  // workspace package.json (e.g. apps/admin's @bhooai/nexus-admin) — best-effort.
+  const collectBhooaiDeps = async (): Promise<string[]> => {
+    const names = new Set<string>();
+    const roots = [join(targetDir, 'package.json'), join(targetDir, 'apps', 'admin', 'package.json')];
+    for (const p of roots) {
+      try {
+        const raw = await readFile(p, 'utf8');
+        const pkg = JSON.parse(raw);
+        for (const obj of [pkg.dependencies ?? {}, pkg.devDependencies ?? {}]) {
+          for (const name of Object.keys(obj)) if (name.startsWith('@bhooai/')) names.add(name);
+        }
+      } catch {}
     }
-  } catch {}
+    return [...names];
+  };
+  const bhooaiDeps = await collectBhooaiDeps();
+  for (const name of bhooaiDeps) {
+    await new Promise<void>((r) => {
+      const c = spawn('npm', ['link', name], { cwd: targetDir, stdio: 'inherit', shell: process.platform === 'win32' });
+      c.on('exit', () => r()); c.on('error', () => r());
+    });
+  }
   return linkTarget;
 }