@bhooai/nexus-core 2.0.10 → 2.0.12

package/package.json

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

package/src/app/createNexusApp.ts

@@ -13,7 +13,7 @@
  *   await app.listen();
  */
 import { existsSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { loadConfigAuto, type NexusConfig } from '../config/index.js';
 import { Container } from '../di/Container.js';
@@ -29,13 +29,14 @@ import { eventBus, type EventBus, type Listener } from './events.js';
 import { configureQueue, InMemoryQueueAdapter, type JobQueueAdapter } from './Job.js';
 import { configureMailDriver, configureMailRenderer, logMailDriver } from './Mailable.js';
 import { policyRegistry } from './policies.js';
-import { configureStorageFromEnv } from './Storage.js';
+import { configureStorageFromEnv, storage } from './Storage.js';
 import { maintenanceMiddleware } from './maintenance.js';
+import { serveStatic } from '../http/static.js';
 import { createLazyDb, registerAdminRoutes, RequestLogBuffer } from './adminModule.js';
 import { registerAuthRoutes } from './authModule.js';
-import { issueCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
+import { issueCsrfToken, getCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
 import { connect } from '@bhooai/nexus-data';
-import { createGateway, graphqlHttpHandler } from '@bhooai/nexus-graphql';
+import { createGateway, createFederatedGateway, graphqlHttpHandler, getExplorerHtml, helloSubgraph } from '@bhooai/nexus-graphql';
 import type { Subgraph } from '@bhooai/nexus-graphql';
 
 export interface CreateNexusAppOptions {
@@ -109,6 +110,15 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // ------------------------------------------------------------------
   const discovery = await discoverBackend(srcRoot);
 
+  // ------------------------------------------------------------------
+  // DB must be connected before importing routes/graphql that define models
+  // (blog-crud Post/Author/Comment call model() at import time — previously
+  // connect was only inside `if (admin.enabled)` after routes were mounted,
+  // causing "Not connected — call connect(uri) first." and missing /api/posts)
+  // ------------------------------------------------------------------
+  console.log(`[db] early connect ${config.db.uri} autoIndex=${config.db.autoIndex}`);
+  try { connect(config.db.uri, { autoIndex: config.db.autoIndex }); console.log(`[db] early connect ok`); } catch (e) { console.error(`[db] early connect failed`, e); }
+
   // ------------------------------------------------------------------
   // Storage facade + queue + mail — always configured, even if minimal
   // ------------------------------------------------------------------
@@ -236,37 +246,118 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   });
 
   // ------------------------------------------------------------------
-  // GraphQL gateway — compose discovered subgraphs into a /graphql endpoint
+  // GraphQL gateway — builtin hello + discovered subgraphs (federated)
   // ------------------------------------------------------------------
   let graphqlMounted = false;
-  if (discovery.graphql.length > 0) {
+  {
+    const explorerEnabled = (config.graphql as unknown as { explorer?: boolean })?.explorer ?? true;
+    const helloEnabled = (config.graphql as unknown as { hello?: boolean })?.hello !== false;
     try {
-      const subgraphs: Subgraph[] = [];
+      const discovered: Subgraph[] = [];
       for (const file of discovery.graphql) {
-        const sg = await importDefault<Subgraph>(file);
-        if (sg && typeof sg === 'object' && 'sdl' in sg && 'resolvers' in sg) {
-          subgraphs.push(sg);
-        } else {
-          console.warn(`[${name}] graphql file ${file.path} does not export a subgraph — skipped`);
+        try {
+          const sg = await importDefault<Subgraph>(file);
+          if (sg && typeof sg === 'object' && 'sdl' in sg && 'resolvers' in sg) {
+            // Avoid duplicate hello if user created a hello subgraph
+            if (helloEnabled && (sg as unknown as { name?: string }).name === 'hello') {
+              console.warn(`[${name}] graphql file ${file.path} defines a 'hello' subgraph — overriding builtin hello`);
+            }
+            discovered.push(sg);
+          } else {
+            console.warn(`[${name}] graphql file ${file.path} does not export a subgraph — skipped`);
+          }
+        } catch (e) {
+          console.warn(`[${name}] failed to import graphql ${file.path}:`, e);
         }
       }
-      if (subgraphs.length === 1) {
-        const gateway = createGateway({ subgraph: subgraphs[0]! });
+
+      // Builtin hello is always first unless disabled or user already provides hello
+      const hasUserHello = discovered.some((s) => s.name === 'hello');
+      const subgraphs: Subgraph[] = [];
+      if (helloEnabled && !hasUserHello) subgraphs.push(helloSubgraph);
+      subgraphs.push(...discovered);
+
+      if (subgraphs.length > 0) {
         const graphqlPath = config.graphql?.path ?? '/graphql';
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let gateway: any;
+        let publicSdl: string;
+        if (subgraphs.length === 1) {
+          gateway = createGateway({ subgraph: subgraphs[0]! });
+          publicSdl = (subgraphs[0] as unknown as { sdl?: string })?.sdl ?? '';
+        } else {
+          gateway = createFederatedGateway(subgraphs);
+          // mergedSdl is client-facing SDL (no federation directives)
+          publicSdl = (gateway as unknown as { supergraph?: { mergedSdl?: string } })?.supergraph?.mergedSdl ?? subgraphs.map((s) => s.sdl).join('\n\n');
+          console.log(`[${name}] GraphQL federated gateway: ${subgraphs.map((s) => s.name).join(', ')} (hello builtin ${helloEnabled ? 'included' : 'disabled'})`);
+        }
         const handler = graphqlHttpHandler({
           gateway,
           introspection: config.graphql?.introspection ?? true,
+          requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true,
         });
-        router.add('GET', graphqlPath, handler);
+        if (explorerEnabled) {
+          const explorerHtml = getExplorerHtml({
+            endpoint: graphqlPath,
+            appName: name,
+            sdl: publicSdl,
+            introspection: config.graphql?.introspection ?? true,
+          });
+          const explorerHandler: Handler = async (ctx) => {
+            ctx.setHeader('access-control-allow-origin', '*');
+            ctx.html(explorerHtml);
+          };
+          router.add('GET', '/graphiql', explorerHandler);
+          router.add('GET', graphqlPath, handler);
+        } else {
+          router.add('GET', graphqlPath, handler);
+        }
         router.add('POST', graphqlPath, handler);
         graphqlMounted = true;
-        console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath}`);
-      } else if (subgraphs.length > 1) {
-        console.warn(`[${name}] found ${subgraphs.length} subgraphs — multi-subgraph federation is Phase 6; GraphQL not mounted`);
+        if (subgraphs.length === 1) {
+          console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath} (${subgraphs[0]!.name} subgraph${explorerEnabled ? ' + explorer at /graphiql' : ''})`);
+        } else {
+          console.log(`[${name}] GraphQL gateway mounted at ${graphqlPath}${explorerEnabled ? ' (+ explorer at /graphiql)' : ''}`);
+        }
       }
     } catch (err) {
       console.warn(`[${name}] failed to mount GraphQL gateway:`, err);
     }
+    // Fallback — should not happen because builtin hello guarantees a subgraph, but keep for hello:false
+    if (!graphqlMounted && explorerEnabled) {
+      const graphqlPath = config.graphql?.path ?? '/graphql';
+      const placeholderHtml = getExplorerHtml({
+        endpoint: graphqlPath,
+        appName: name,
+        sdl: helloEnabled ? helloSubgraph.sdl : '',
+        introspection: config.graphql?.introspection ?? true,
+      });
+      const placeholderHandler: Handler = async (ctx) => {
+        ctx.setHeader('access-control-allow-origin', '*');
+        ctx.html(placeholderHtml);
+      };
+      const graphqlPlaceholder: Handler = async (ctx) => {
+        if (helloEnabled) {
+          // hello is available even in fallback — route through its gateway
+          const gw = createGateway({ subgraph: helloSubgraph });
+          const h = graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true });
+          return h(ctx);
+        }
+        ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>  (then restart)' }] }, 404);
+      };
+      try { router.add('GET', '/graphiql', placeholderHandler); } catch {}
+      try { router.add('GET', graphqlPath, graphqlPlaceholder); } catch {}
+      try {
+        if (helloEnabled) {
+          const gw = createGateway({ subgraph: helloSubgraph });
+          router.add('POST', graphqlPath, graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true }));
+        } else {
+          router.add('POST', graphqlPath, async (ctx) => ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>' }] }, 404));
+        }
+      } catch {}
+      console.log(`[${name}] GraphQL explorer mounted at /graphiql${helloEnabled ? ' (hello builtin)' : ' (no schema — add a subgraph)'}`);
+      if (helloEnabled) graphqlMounted = true;
+    }
   }
 
   // ------------------------------------------------------------------
@@ -285,9 +376,12 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     // AuthService used to build the admin guard.
     const authService = registerAuthRoutes(router, config);
 
-    // CSRF token endpoint — mints a double-submit token cookie + returns it.
+    // CSRF token endpoint — returns the double-submit token. Reuses the existing
+    // cookie token when present (no rotation) so previously-issued tokens (e.g. a
+    // copied urlbar URL) keep matching; only mints a fresh one when none exists.
     router.get('/csrf-token', (ctx) => {
-      const token = issueCsrfToken(ctx);
+      const existing = getCsrfToken(ctx);
+      const token = existing ?? issueCsrfToken(ctx);
       ctx.json({ token });
     });
 
@@ -297,6 +391,13 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
       requireRole('admin'),
     ];
 
+    // When enabled, gate the GraphiQL explorer with the same admin guard used for
+    // /admin/* and plugin admin pages. Only /graphiql is protected; the /graphql
+    // JSON endpoint stays public.
+    if (config.graphql?.explorerRequireAuth) {
+      for (const mw of guard) router.use('/graphiql', mw);
+    }
+
     // CSRF protection (double-submit cookie) on the auth + admin surfaces.
     router.use('/auth', csrf());
     router.use('/admin', csrf());
@@ -320,6 +421,198 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     onError: (err, ctx) => errorHandler.toApiError(err),
   });
 
+  // ------------------------------------------------------------------
+  // Realtime WS server — mount discovered ws/*.room.ts handlers (chat lobby)
+  // ------------------------------------------------------------------
+  let realtime: any = null;
+  try {
+    const { RealtimeServer } = await import('@bhooai/nexus-realtime');
+    realtime = new RealtimeServer({ httpServer: server.httpServer, path: '/ws' });
+    // Load custom ws rooms (e.g. chat) for persistence + presence bridging
+    const roomHandlers = new Map<string, any>();
+    for (const file of discovery.rooms) {
+      try {
+        const mod: any = await importDefault(file);
+        const def = mod?.default ?? mod;
+        if (def?.name) roomHandlers.set(def.name, def);
+      } catch (e) {
+        console.warn(`[realtime] failed to load ws room ${file.path}:`, e);
+      }
+    }
+    // Bridge custom chat protocol (roomId/msg/typing) to generic realtime (room/broadcast)
+    // so lobby works with both old clients (roomId) and new (room/broadcast).
+    const chatRoom = roomHandlers.get('chat');
+    if (chatRoom) {
+      const origOnMessage = (realtime as any).onMessage.bind(realtime);
+      (realtime as any).onMessage = async (conn: any, raw: string) => {
+        let msg: any;
+        try { msg = JSON.parse(raw); } catch { return origOnMessage(conn, raw); }
+        // Normalize join with roomId/username (chat) → generic join with room
+        if (msg.type === 'join' && (msg.roomId || msg.room)) {
+          const room = msg.room ?? msg.roomId;
+          (conn as any).data = (conn as any).data ?? {};
+          if (msg.username) (conn as any).data.username = msg.username;
+          // Persist room for later msg attribution
+          (conn as any).username = msg.username ?? (conn as any).username;
+          // Only call custom onJoin for side-effects, but suppress its broadcast (generic will handle presence)
+          try {
+            const sockLike: any = { data: (conn as any).data, join: () => {}, to: () => ({ emit: () => {} }) };
+            const ctxNoop: any = { server: { to: () => ({ emit: () => {} }), broadcast: () => {} } };
+            await chatRoom.onJoin?.(sockLike, { roomId: room, room, username: msg.username }, ctxNoop);
+          } catch {}
+          msg.room = room;
+          return origOnMessage(conn, JSON.stringify(msg));
+        }
+        // Custom msg → persist + single broadcast as 'msg' (legacy) — also visible to generic broadcast listeners
+        if (msg.type === 'msg' && (msg.roomId || msg.room) && msg.text) {
+          const room = msg.roomId ?? msg.room;
+          const from = (conn as any).data?.username ?? msg.username ?? (conn as any).username ?? 'anon';
+          const at = new Date().toISOString();
+          // Persist via chat handler (Message.create) without double-broadcast
+          if (chatRoom?.onMessage?.['msg']) {
+            try {
+              const sockLike: any = { data: (conn as any).data ?? { username: from } };
+              const ctxNoop: any = { server: { to: () => ({ emit: () => {} }), broadcast: () => {} } };
+              await chatRoom.onMessage['msg'](sockLike, { roomId: room, room, text: msg.text }, ctxNoop);
+            } catch {}
+          }
+          // Single publish as 'msg' — include room so deliverRoom can route to all members (including sender, since origin undefined)
+          const payload: any = { type: 'msg', room, from, text: msg.text, at, payload: { from, text: msg.text, at } };
+          try { (realtime as any).adapter.publish(`room:${room}`, JSON.stringify(payload)); } catch {}
+          try { (realtime as any).adapter.publish(`room:chat:${room}`, JSON.stringify(payload)); } catch {}
+          return;
+        }
+        if (msg.type === 'typing' && (msg.roomId || msg.room)) {
+          const room = msg.roomId ?? msg.room;
+          const username = (conn as any).data?.username ?? msg.username ?? 'anon';
+          const payload: any = { type: 'typing', room, username, payload: { username } };
+          try { (realtime as any).adapter.publish(`room:${room}`, JSON.stringify(payload)); } catch {}
+          try { (realtime as any).adapter.publish(`room:chat:${room}`, JSON.stringify(payload)); } catch {}
+          return;
+        }
+        // Handle generic broadcast with event:msg (from new clients) → persist + re-broadcast as msg
+        if (msg.type === 'broadcast' && msg.event === 'msg' && msg.data?.text) {
+          const room = msg.room;
+          const from = msg.data.from ?? (conn as any).data?.username ?? 'anon';
+          const text = msg.data.text;
+          const at = msg.data.at ?? new Date().toISOString();
+          if (chatRoom?.onMessage?.['msg']) {
+            try {
+              const sockLike: any = { data: (conn as any).data ?? { username: from } };
+              const ctxNoop: any = { server: { to: () => ({ emit: () => {} }), broadcast: () => {} } };
+              await chatRoom.onMessage['msg'](sockLike, { roomId: room, room, text }, ctxNoop);
+            } catch {}
+          }
+          const payload: any = { type: 'msg', room, from, text, at, payload: { from, text, at } };
+          try { (realtime as any).adapter.publish(`room:${room}`, JSON.stringify(payload)); } catch {}
+          try { (realtime as any).adapter.publish(`room:chat:${room}`, JSON.stringify(payload)); } catch {}
+          return;
+        }
+        if (msg.type === 'broadcast' && msg.event === 'typing') {
+          const room = msg.room;
+          const username = msg.data?.username ?? (conn as any).data?.username ?? 'anon';
+          const payload: any = { type: 'typing', room, username, payload: { username } };
+          try { (realtime as any).adapter.publish(`room:${room}`, JSON.stringify(payload)); } catch {}
+          try { (realtime as any).adapter.publish(`room:chat:${room}`, JSON.stringify(payload)); } catch {}
+          return;
+        }
+        // Normalize roomId → room for generic handling
+        if (msg.roomId && !msg.room) msg.room = msg.roomId;
+        return origOnMessage(conn, JSON.stringify(msg));
+      };
+    }
+  } catch (e) {
+    // realtime optional — if not installed, ws lobby falls back to no-op
+    if ((e as any)?.code !== 'ERR_MODULE_NOT_FOUND') console.warn('[realtime] ws init failed:', e);
+  }
+
+  // Public uploads: serve GET /uploads/* from storage/uploads (file-storage example).
+  // This was missing — 404 `No route for GET /uploads/media/...`.
+  server.use(serveStatic(join(projectRoot, 'storage', 'uploads'), { prefix: '/uploads' }));
+
+  // Signed private files: GET /files/<encodedPath>?expires=&sig=
+  // Handles LocalDisk.signedUrl() URLs (HMAC, 5min TTL). Streams from whichever local disk holds the file.
+  server.use(async (ctx, next) => {
+    if ((ctx.method !== 'GET' && ctx.method !== 'HEAD') || (!ctx.path.startsWith('/files/') && ctx.path !== '/files')) {
+      await next();
+      return;
+    }
+    const encoded = ctx.path.slice('/files/'.length);
+    if (!encoded) {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'missing file path' } }, 404);
+      return;
+    }
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(encoded);
+    } catch {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid file path' } }, 400);
+      return;
+    }
+    // Block traversal
+    if (decoded.includes('..') || decoded.includes('\\') || decoded.startsWith('/')) {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid file path' } }, 400);
+      return;
+    }
+    const expiresRaw = ctx.query.expires;
+    const sigRaw = ctx.query.sig;
+    const expiresStr = Array.isArray(expiresRaw) ? expiresRaw[0] : (expiresRaw as string | undefined);
+    const sig = Array.isArray(sigRaw) ? sigRaw[0] : (sigRaw as string | undefined);
+    if (!expiresStr || !sig) {
+      ctx.json({ error: { code: 'UNAUTHORIZED', message: 'missing signature' } }, 401);
+      return;
+    }
+    const expires = parseInt(String(expiresStr), 10);
+    if (!Number.isFinite(expires)) {
+      ctx.json({ error: { code: 'BAD_REQUEST', message: 'invalid expires' } }, 400);
+      return;
+    }
+    const localUploads = storage.local('uploads');
+    const localPrivate = storage.local('private');
+    const verifier = localUploads ?? localPrivate;
+    const isValid = verifier ? verifier.verifySignedUrl(decoded, expires, String(sig)) : false;
+    // Fallback: also accept signature valid for private disk if uploads verifier fails (same secret, so same result — but check both)
+    const isValidAlt = !isValid && localPrivate && localUploads ? localPrivate.verifySignedUrl(decoded, expires, String(sig)) : false;
+    if (!isValid && !isValidAlt) {
+      ctx.json({ error: { code: 'FORBIDDEN', message: 'invalid or expired signature' } }, 403);
+      return;
+    }
+    // Find disk holding the file (private first, then uploads)
+    const candidates = [localPrivate, localUploads].filter(Boolean) as Array<NonNullable<typeof localPrivate>>;
+    let disk: (typeof candidates)[number] | null = null;
+    for (const d of candidates) {
+      try {
+        if (await d.exists(decoded)) { disk = d; break; }
+      } catch {}
+    }
+    if (!disk) {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'file not found' } }, 404);
+      return;
+    }
+    try {
+      if (ctx.method === 'HEAD') {
+        ctx.status(200);
+        return;
+      }
+      const stream = disk.stream(decoded);
+      const ext = decoded.includes('.') ? `.${decoded.split('.').pop()!.toLowerCase()}` : '';
+      const MIME: Record<string, string> = {
+        '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif',
+        '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+        '.txt': 'text/plain; charset=utf-8', '.json': 'application/json; charset=utf-8',
+      };
+      ctx.setHeader('content-type', MIME[ext] ?? 'application/octet-stream');
+      await new Promise<void>((resolveStream, rejectStream) => {
+        stream.on('error', rejectStream);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (stream as any).pipe(ctx.res);
+        stream.on('end', resolveStream);
+      });
+    } catch {
+      ctx.json({ error: { code: 'NOT_FOUND', message: 'file not found' } }, 404);
+    }
+  });
+
   // Body parsing (JSON / urlencoded / multipart) — before everything else so
   // POST/PUT/PATCH handlers see ctx.body.
   server.use(bodyParser(config.server.bodyLimit));

package/src/app/discover.ts

@@ -76,16 +76,16 @@ export async function discoverBackend(srcRoot: string): Promise<DiscoveryResult>
 
   const [routes, graphql, rooms, mailables, errorPages, events, listeners, jobs, policies, providers, seeds, migrations, plugins, config] =
     await Promise.all([
-      collect(join(abs, 'routes'), /\.(ts|js)$/),
-      collect(join(abs, 'graphql'), /\.graph\.(ts|js)$/),
-      collect(join(abs, 'ws'), /\.room\.(ts|js)$/),
+      collectWithModules(abs, 'routes', /\.(ts|js)$/),
+      collectWithModules(abs, 'graphql', /\.graph\.(ts|js)$/),
+      collectWithModules(abs, 'ws', /\.room\.(ts|js)$/),
       collect(join(abs, 'mail', 'mailables'), /\.(ts|js)$/),
       collect(join(abs, 'errors', 'pages'), /\.html$/),
-      collect(join(abs, 'events'), /\.(ts|js)$/),
-      collect(join(abs, 'listeners'), /^On.*\.(ts|js)$/),
-      collect(join(abs, 'jobs'), /Job\.(ts|js)$/),
-      collect(join(abs, 'policies'), /Policy\.(ts|js)$/),
-      collect(join(abs, 'providers'), /ServiceProvider\.(ts|js)$/),
+      collectWithModules(abs, 'events', /\.(ts|js)$/),
+      collectWithModules(abs, 'listeners', /^On.*\.(ts|js)$/),
+      collectWithModules(abs, 'jobs', /Job\.(ts|js)$/),
+      collectWithModules(abs, 'policies', /Policy\.(ts|js)$/),
+      collectWithModules(abs, 'providers', /ServiceProvider\.(ts|js)$/),
       collect(join(abs, 'database', 'seeds'), /Seeder\.(ts|js)$/),
       collect(join(abs, 'database', 'migrations'), /^\d{4}_\d{2}_\d{2}_\d{6}_.*\.(ts|js)$/),
       collectPluginDirs(join(abs, 'plugins')),
@@ -112,6 +112,37 @@ async function collect(dir: string, pattern: RegExp): Promise<DiscoveredFile[]>
   return out;
 }
 
+/** Collect from flat root + modules/<domain>/<sub> — keeps modular workflow discoverable. */
+async function collectWithModules(abs: string, sub: string, pattern: RegExp): Promise<DiscoveredFile[]> {
+  const flat = await collect(join(abs, sub), pattern);
+  const modulesRoot = join(abs, 'modules');
+  if (!existsSync(modulesRoot)) return dedupeByPath(flat);
+  const mods = await readdir(modulesRoot, { withFileTypes: true });
+  const moduleFiles: DiscoveredFile[] = [];
+  for (const m of mods) {
+    if (!m.isDirectory()) continue;
+    const modSub = join(modulesRoot, m.name, sub);
+    const files = await collect(modSub, pattern);
+    for (const f of files) {
+      moduleFiles.push({ ...f, subdir: f.subdir ? `${m.name}/${f.subdir}` : m.name });
+    }
+  }
+  // Prefer modular file when same `name` exists in both flat and modular (flat is deprecated shim)
+  if (moduleFiles.length > 0) {
+    const moduleNames = new Set(moduleFiles.map((f) => f.name));
+    const filteredFlat = flat.filter((f) => !moduleNames.has(f.name));
+    return dedupeByPath([...filteredFlat, ...moduleFiles]);
+  }
+  return dedupeByPath([...flat, ...moduleFiles]);
+}
+
+function dedupeByPath(files: DiscoveredFile[]): DiscoveredFile[] {
+  const seen = new Set<string>();
+  const out: DiscoveredFile[] = [];
+  for (const f of files) if (!seen.has(f.path)) { seen.add(f.path); out.push(f); }
+  return out;
+}
+
 async function collectPluginDirs(dir: string): Promise<DiscoveredFile[]> {
   if (!existsSync(dir)) return [];
   const out: DiscoveredFile[] = [];

package/src/config/defaults.ts

@@ -34,6 +34,10 @@ export const defaults: NexusConfig = {
     federation: 'in-process',
     subscriptions: true,
     introspection: true,
+    explorer: true,
+    hello: true,
+    requireMutationCsrf: true,
+    explorerRequireAuth: false,
   },
   ws: {
     path: '/ws',

package/src/config/schema.ts

@@ -39,6 +39,10 @@ export const nexusConfigSchema = z.object({
     federation: z.enum(['in-process', 'distributed']),
     subscriptions: z.boolean(),
     introspection: z.boolean(),
+    explorer: z.boolean().optional(),
+    hello: z.boolean().optional(),
+    requireMutationCsrf: z.boolean(),
+    explorerRequireAuth: z.boolean().optional(),
   }),
   ws: z.object({
     path: z.string().min(1),

package/src/config/types.ts

@@ -154,6 +154,14 @@ export interface GraphqlConfig {
   subscriptions: boolean;
   /** Introspection enabled (disable in production). */
   introspection: boolean;
+  /** Serve the interactive sandbox at GET /graphiql. */
+  explorer?: boolean;
+  /** Include builtin hello/ping subgraph in every app (default true). Disable with `hello: false`. */
+  hello?: boolean;
+  /** Require a matching CSRF token to execute mutation operations on /graphql (default true). */
+  requireMutationCsrf?: boolean;
+  /** Require an admin access token (JWT) to open the GraphiQL explorer at /graphiql (default false). */
+  explorerRequireAuth?: boolean;
 }
 
 export interface WsConfig {