@bhooai/nexus-core 2.0.18 → 2.0.21

package/src/app/preflightModule.ts

@@ -1,6 +1,6 @@
 import { createConnection } from 'node:net';
 import type { Router, NexusConfig } from '../index.js';
-import { mongoEnabled, mongoUri } from '../config/dbAccess.js';
+import { mongoEnabled, mongoUri, redisCacheEnabled } from '../config/dbAccess.js';
 
 /**
  * Preflight diagnostics — native Node connectivity/latency probes.
@@ -235,7 +235,9 @@ export function registerPreflightRoutes(router: Router, config: NexusConfig, opt
     }
 
     const redisUrl = config.redis?.url ?? '';
-    if (redisUrl) {
+    // Probed only when redis is the active cache backend — fusion-active
+    // backends don't need a Redis server at all.
+    if (redisCacheEnabled(config) && redisUrl) {
       const redis = endpointFromUrl(redisUrl, 6379);
       targets.push({ name: 'Redis', kind: 'tcp', host: redis.host, port: redis.port, timeout: 2000 });
     }

package/src/app/userStore.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import type { FusionDatabase } from '@bhooai/nexus-fusion';
+import type { FusionLike } from '@bhooai/nexus-fusion';
 import { ObjectId } from '@bhooai/nexus-data';
 import { ConflictError } from '../errors.js';
 import { initUserModel, getUserModel, findUserForLogin, type UserInstance } from './userModel.js';
@@ -172,16 +172,16 @@ async function getDocOrNull<T>(ref: { get(): Promise<{ id: string; data: T } | n
 }
 
 /** Query paths throw on missing collections too — treat as empty. */
-function hasCollection(db: FusionDatabase, name: string): boolean {
+async function hasCollection(db: FusionLike, name: string): Promise<boolean> {
   try {
-    return db.listCollections().includes(name);
+    return (await db.listCollections()).includes(name);
   } catch {
     return false;
   }
 }
 
 export class FusionUserStore implements UserStore {
-  constructor(private db: FusionDatabase) {}
+  constructor(private db: FusionLike) {}
 
   private toStored(data: FusionUserData): StoredUser {
     return { _id: data.id, ...data };
@@ -197,7 +197,7 @@ export class FusionUserStore implements UserStore {
   }
 
   async findById(id: string): Promise<StoredUser | null> {
-    if (!hasCollection(this.db, USERS)) return null;
+    if (!(await hasCollection(this.db, USERS))) return null;
     const snap = await this.db.collection<FusionUserData>(USERS).where('id', '==', id).limit(1).get();
     const hit = snap.docs[0];
     return hit ? this.toStored(hit.data) : null;
@@ -255,20 +255,20 @@ export class FusionUserStore implements UserStore {
   }
 
   async count(): Promise<number> {
-    if (!hasCollection(this.db, USERS)) return 0;
+    if (!(await hasCollection(this.db, USERS))) return 0;
     const snap = await this.db.collection(USERS).get();
     return snap.size;
   }
 
   async countAdmins(): Promise<number> {
     // No array-contains op in the query compiler — filter the (small) users table.
-    if (!hasCollection(this.db, USERS)) return 0;
+    if (!(await hasCollection(this.db, USERS))) return 0;
     const snap = await this.db.collection<FusionUserData>(USERS).get();
     return snap.docs.filter((d) => (d.data.roles ?? []).includes('admin')).length;
   }
 
   async list(limit: number): Promise<StoredUser[]> {
-    if (!hasCollection(this.db, USERS)) return [];
+    if (!(await hasCollection(this.db, USERS))) return [];
     const snap = await this.db
       .collection<FusionUserData>(USERS)
       .orderByField('createdAt', 'desc')

package/src/config/ConfigLoader.ts

@@ -47,6 +47,23 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
     merged = deepMerge(merged, defaultConfig);
   }
 
+  // 1c. project identity — resolve `app.name` from every higher layer, then
+  //     derive auth identity, redis prefix and mail `from` from it. This layer
+  //     sits above the framework default but below the user config, so an
+  //     explicit value anywhere in nexus.config.ts / runtime.json / env still
+  //     wins while a project only has to declare its name once.
+  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
+  const runtime = readRuntimeObject(runtimePath);
+  const envLayer = configFromEnv(env);
+  const appName = resolveAppName({
+    userConfig: opts.userConfig,
+    runtime,
+    env: envLayer,
+    cli: opts.cli,
+    root,
+  });
+  merged = deepMerge(merged, deriveAppIdentity(appName));
+
   // 2. user config (nexus.config.ts / nexus.config.js)
   let userConfig = opts.userConfig;
   if (!userConfig && opts.userConfigPath) {
@@ -55,18 +72,10 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   if (userConfig) merged = deepMerge(merged, userConfig);
 
   // 3. runtime.json (admin write-back, gitignored)
-  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
-  if (existsSync(runtimePath)) {
-    try {
-      const runtime = JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
-      merged = deepMerge(merged, runtime);
-    } catch {
-      // A corrupt runtime file must not crash boot; ignore it.
-    }
-  }
+  if (runtime) merged = deepMerge(merged, runtime);
 
   // 4. env
-  merged = deepMerge(merged, configFromEnv(env));
+  merged = deepMerge(merged, envLayer);
 
   // 5. cli flags (highest)
   if (opts.cli) merged = deepMerge(merged, opts.cli);
@@ -76,6 +85,65 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   return Object.freeze(parsed) as NexusConfig;
 }
 
+/** Read nexus.runtime.json (DeepPartial) or an empty object when absent/corrupt. */
+function readRuntimeObject(runtimePath: string): DeepPartial<NexusConfig> {
+  if (!existsSync(runtimePath)) return {};
+  try {
+    return JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
+  } catch {
+    // A corrupt runtime file must not crash boot; ignore it.
+    return {};
+  }
+}
+
+/**
+ * Resolve the project slug used to derive identity/namespaces: an explicit
+ * `app.name` from the highest-precedence layer wins, else package.json `name`
+ * (scope stripped), else the project folder name.
+ */
+function resolveAppName(layers: {
+  userConfig?: UserNexusConfig;
+  runtime?: DeepPartial<NexusConfig>;
+  env?: DeepPartial<NexusConfig>;
+  cli?: DeepPartial<NexusConfig>;
+  root: string;
+}): string {
+  const explicit =
+    layers.cli?.app?.name ??
+    layers.env?.app?.name ??
+    layers.runtime?.app?.name ??
+    layers.userConfig?.app?.name;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(layers.root, 'package.json'), 'utf8')) as { name?: string };
+    if (pkg.name) return pkg.name.replace(/^@[^/]+\//, '').trim();
+  } catch {
+    // no package.json
+  }
+  return layers.root.split(/[\\/]/).filter(Boolean).pop() ?? 'nexus';
+}
+
+/**
+ * Derive the per-project identity fields from `app.name`. Values are only
+ * applied as a base layer — an explicit value in a higher config layer wins
+ * (including `NEXUS_DB_URI`, which maps to `db.mongodb.uri` via the legacy
+ * flat shape).
+ */
+function deriveAppIdentity(appName: string): DeepPartial<NexusConfig> {
+  return {
+    app: { name: appName },
+    auth: {
+      jwt: { issuer: appName, audience: `${appName}-client` },
+      cookieName: `${appName}_sid`,
+      refreshCookieName: `${appName}_rid`,
+    },
+    redis: { keyPrefix: `${appName}:` },
+    db: { mongodb: { uri: `mongodb://localhost:27017/${appName}` } },
+    email: { from: `no-reply@${appName}.local` },
+  };
+}
+
 async function importUserConfig(absPath: string): Promise<UserNexusConfig> {
   const url = pathToFileURL(absPath).href;
   const mod = (await import(url)) as Record<string, unknown>;
@@ -155,7 +223,13 @@ export async function loadConfigAuto(
   });
 }
 
-/** Read-only accessor for tests / bootstrap that don't need file loading. */
+/**
+ * Read-only accessor for tests / bootstrap that don't need file loading.
+ * When any source declares `app.name`, the derived identity fields are applied
+ * as a base layer (an explicit value in a later source still wins).
+ */
 export function mergeConfig(...sources: DeepPartial<NexusConfig>[]): NexusConfig {
-  return Object.freeze(nexusConfigSchema.parse(deepMerge(defaults, ...sources))) as NexusConfig;
+  const explicitName = [...sources].reverse().find((s) => s?.app?.name)?.app?.name;
+  const base = explicitName ? deepMerge(defaults, deriveAppIdentity(explicitName)) : defaults;
+  return Object.freeze(nexusConfigSchema.parse(deepMerge(base, ...sources))) as NexusConfig;
 }

package/src/config/current.ts

@@ -0,0 +1,28 @@
+/**
+ * Process-wide accessor for the loaded config.
+ *
+ * `createNexusApp()` registers the merged config here at boot so code paths
+ * that are not handed a `ctx` (subgraphs, services, listeners, jobs) can read
+ * the same identity/namespace values instead of hardcoding them.
+ *
+ * This is a convenience fallback, not a replacement for DI — prefer the
+ * `ctx.config` / resolver-context value when a request context is available.
+ */
+import type { NexusConfig } from './types.js';
+
+let current: NexusConfig | null = null;
+
+/** Register the config for this process (called by createNexusApp at boot). */
+export function setNexusConfig(config: NexusConfig): void {
+  current = config;
+}
+
+/** The config registered for this process, or null before boot. */
+export function getNexusConfig(): NexusConfig | null {
+  return current;
+}
+
+/** Reset the process config (tests / hot reload). */
+export function resetNexusConfig(): void {
+  current = null;
+}

package/src/config/dbAccess.ts

@@ -24,3 +24,24 @@ export function fusionEnabled(config: NexusConfig): boolean {
 export function fusionDir(config: NexusConfig): string {
   return config.db.fusion.dir;
 }
+
+/** True when the backend delegates to a standalone Fusion server over HTTP
+ *  (no in-process engine). Triggered by `db.fusion.remote` or a set `url`. */
+export function fusionRemote(config: NexusConfig): boolean {
+  return config.db.fusion.remote === true || !!config.db.fusion.url;
+}
+
+/** Standalone Fusion server base URL (empty when embedded). */
+export function fusionUrl(config: NexusConfig): string {
+  return config.db.fusion.url ?? '';
+}
+
+/** Which backend serves cache duties — 'fusion' (default) or 'redis'. */
+export function cacheActive(config: NexusConfig): 'fusion' | 'redis' {
+  return config.cache?.active ?? 'fusion';
+}
+
+/** True when the app uses an external Redis server for cache. */
+export function redisCacheEnabled(config: NexusConfig): boolean {
+  return cacheActive(config) === 'redis';
+}

package/src/config/defaults.ts

@@ -6,6 +6,11 @@ import type { NexusConfig } from './types.js';
  */
 export const defaults: NexusConfig = {
   env: 'development',
+  app: {
+    // Overridden by ConfigLoader with the project slug (package.json name or
+    // folder name) when not set explicitly in nexus.config.ts.
+    name: 'nexus',
+  },
   server: {
     port: 4000,
     host: 'localhost',
@@ -30,6 +35,8 @@ export const defaults: NexusConfig = {
     },
     fusion: {
       enabled: true,
+      remote: false,
+      url: '',
       dir: 'storage/fusion',
       persist: true,
       cacheCapacity: 10_000,
@@ -87,11 +94,10 @@ export const defaults: NexusConfig = {
   },
   ads: {
     enabled: false,
-    developerToken: '',
+    publisherId: '',
     clientId: '',
     clientSecret: '',
     refreshToken: '',
-    customerId: '',
   },
   webrtc: {
     rtcMinPort: 40000,
@@ -131,7 +137,7 @@ export const defaults: NexusConfig = {
     level: 'info',
     format: 'pretty',
     console: true,
-    dir: 'logs',
+    dir: 'storage/logs',
     maxFileSize: 10 * 1024 * 1024, // 10 MiB
     maxFiles: 7,
   },
@@ -149,14 +155,8 @@ export const defaults: NexusConfig = {
     host: 'localhost',
     enabled: true,
   },
-  fusion: {
-    dir: 'storage/fusion',
-    persist: true,
-    cacheCapacity: 10_000,
-    cacheTtlMs: 5_000,
-    walCompactThreshold: 1_000,
-  },
   cache: {
+    active: 'fusion',
     dir: 'storage/fusion/cache',
     persist: true,
     cacheCapacity: 10_000,

package/src/config/env.ts

@@ -50,6 +50,26 @@ function coerce(value: string): string | number | boolean {
   return v;
 }
 
+/**
+ * Runtime-only `NEXUS_*` variables that are NOT config keys.
+ *
+ * These are process controls injected by the CLI / supervisor (`nexus dev` sets
+ * NEXUS_PORT and NEXUS_PORT_STEP on every child) or read directly by the
+ * framework at boot. Mapping them into the config tree corrupts it — e.g.
+ * NEXUS_PORT creates `{ port: 4000 }` and NEXUS_PORT_STEP then tries to write
+ * `port.step` onto that number, throwing `Cannot create property 'step' on
+ * number` and killing backend boot whenever ports step up.
+ */
+const RUNTIME_ENV_VARS = new Set([
+  'NEXUS_PORT',          // per-service resolved port (read by createNexusApp)
+  'NEXUS_PORT_STEP',     // coordinated step-up delta (read by the CLI)
+  'NEXUS_HOST',          // bind host injected by the supervisor
+  'NEXUS_PROJECT_ROOT',  // license/config resolution root injected by the CLI
+  'NEXUS_TUI_NO_MOUSE',  // dev panel control
+  'NEXUS_TUI_DEBUG',     // dev panel control
+  'NEXUS_AI_FIX',        // `nexus dev --ai-fix` toggle
+]);
+
 /**
  * Two `_`-separated env segments that form ONE camelCase config field.
  * Generic splitting would turn `KEY_ID` into `key.id` (a nested object) —
@@ -69,6 +89,8 @@ const PAIR_FIELDS: Record<string, string> = {
   'webhook_secret': 'webhookSecret',
   'customer_id': 'customerId',
   'developer_token': 'developerToken',
+  'publisher_id': 'publisherId',
+  'account_id': 'accountId',
   'refresh_token': 'refreshToken',
   'access_ttl': 'accessTtl',
   'refresh_ttl': 'refreshTtl',
@@ -91,6 +113,7 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
   const out: Record<string, unknown> = {};
   for (const [rawKey, rawValue] of Object.entries(env)) {
     if (!rawKey.startsWith('NEXUS_') || rawValue === undefined) continue;
+    if (RUNTIME_ENV_VARS.has(rawKey)) continue;
     const path = rawKey.slice('NEXUS_'.length).toLowerCase().split('_');
     const last = path.length - 1;
     if (last >= 1) {
@@ -100,15 +123,37 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
       }
     }
     let node: Record<string, unknown> = out;
+    let conflict = false;
     for (let i = 0; i < path.length; i++) {
       const segment = path[i]!;
       if (i === path.length - 1) {
         node[segment] = coerce(rawValue);
       } else {
-        node[segment] = (node[segment] as Record<string, unknown>) ?? {};
-        node = node[segment] as Record<string, unknown>;
+        const existing = node[segment];
+        // A scalar here means two env vars disagree about the shape (e.g.
+        // NEXUS_SERVER_PORT=4000 plus NEXUS_SERVER_PORT_X). Overwriting would
+        // either crash (writing a property onto a primitive) or silently drop
+        // config, so skip the offending var and keep the first value.
+        if (existing !== undefined && (typeof existing !== 'object' || existing === null)) {
+          conflict = true;
+          break;
+        }
+        const child = existing ?? {};
+        node[segment] = child;
+        node = child as Record<string, unknown>;
       }
     }
+    if (conflict && !isKnownRuntimeVar(rawKey)) {
+      // Real config vars would silently vanish — make that visible.
+      console.warn(
+        `[config] ignoring ${rawKey}: its path collides with a scalar already set by another NEXUS_* var`,
+      );
+    }
   }
   return out as DeepPartial<NexusConfig>;
+}
+
+/** True for vars the framework consumes at runtime rather than as config. */
+function isKnownRuntimeVar(key: string): boolean {
+  return RUNTIME_ENV_VARS.has(key);
 }

package/src/config/index.ts

@@ -4,4 +4,5 @@ export * from './merge.js';
 export * from './env.js';
 export * from './schema.js';
 export * from './dbAccess.js';
-export * from './ConfigLoader.js';
+export * from './ConfigLoader.js';
+export * from './current.js';

package/src/config/schema.ts

@@ -11,6 +11,9 @@ const providerConfig = z
 
 export const nexusConfigSchema = z.object({
   env: z.enum(['development', 'production', 'test']).default('development'),
+  app: z.object({
+    name: z.string().min(1).default('nexus'),
+  }).default({ name: 'nexus' }),
   server: z.object({
     port: z.number().int().min(1).max(65535),
     host: z.string().min(1),
@@ -47,6 +50,8 @@ export const nexusConfigSchema = z.object({
       fusion: z
         .object({
           enabled: z.boolean().default(true),
+          remote: z.boolean().default(false),
+          url: z.string().default(''),
           dir: z.string().min(1),
           persist: z.boolean().default(true),
           cacheCapacity: z.number().int().positive(),
@@ -55,6 +60,8 @@ export const nexusConfigSchema = z.object({
         })
         .default({
           enabled: true,
+          remote: false,
+          url: '',
           dir: 'storage/fusion',
           persist: true,
           cacheCapacity: 10_000,
@@ -102,18 +109,21 @@ export const nexusConfigSchema = z.object({
     }),
     cookieName: z.string(),
     refreshCookieName: z.string(),
+    // NOTE: clientId/clientSecret use z.coerce.string() — env coercion turns
+    // all-digit values (e.g. numeric Meta App IDs) into numbers, and OAuth
+    // credential fields must accept them rather than crash the boot.
     google: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
       .optional(),
     facebook: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
@@ -151,11 +161,11 @@ export const nexusConfigSchema = z.object({
   }),
   ads: z.object({
     enabled: z.boolean(),
-    developerToken: z.string(),
+    publisherId: z.string(),
     clientId: z.string(),
     clientSecret: z.string(),
     refreshToken: z.string(),
-    customerId: z.string(),
+    accountId: z.string().optional(),
   }),
   webrtc: z.object({
     rtcMinPort: z.number().int().min(1).max(65535),
@@ -201,14 +211,8 @@ export const nexusConfigSchema = z.object({
     host: z.string().min(1),
     enabled: z.boolean(),
   }),
-  fusion: z.object({
-    dir: z.string().min(1).default('storage/fusion'),
-    persist: z.boolean().default(true),
-    cacheCapacity: z.number().int().positive().default(10_000),
-    cacheTtlMs: z.number().int().positive().default(5_000),
-    walCompactThreshold: z.number().int().positive().default(1_000),
-  }),
   cache: z.object({
+    active: z.enum(['fusion', 'redis']).default('fusion'),
     dir: z.string().min(1).default('storage/fusion/cache'),
     persist: z.boolean().default(true),
     cacheCapacity: z.number().int().positive().default(10_000),

package/src/config/types.ts

@@ -8,6 +8,16 @@
 
 export type Env = 'development' | 'production' | 'test';
 
+/**
+ * Project identity. `app.name` is the single source of truth for the project
+ * slug; cookie names, JWT issuer/audience, redis key prefix and mail `from`
+ * are derived from it when not set explicitly.
+ */
+export interface AppConfig {
+  /** Project slug, e.g. 'nexus-bhooai-com'. Derives auth identity + namespaces. */
+  name: string;
+}
+
 export interface ServerConfig {
   port: number;
   host: string;
@@ -23,7 +33,8 @@ export interface ServerConfig {
 }
 
 export interface UploadsConfig {
-  /** Directory for persisted files, relative to the project root. */
+  /** Directory for persisted files, relative to the storage root
+   *  (`createNexusApp`'s `storageRoot`, default = project root). */
   dir: string;
   /** Public URL path for upload and download requests. */
   path: string;
@@ -52,6 +63,17 @@ export interface MongoDbConfig {
 export interface FusionDbConfig {
   /** Open the Fusion engine at boot when true. Default true. */
   enabled: boolean;
+  /**
+   * Delegate to a **standalone Fusion server** instead of opening the engine
+   * in-process. When true (or when `url` is non-empty) the backend no longer
+   * owns `storage/fusion/fusion.wal`; every read/write goes over HTTP to the
+   * `fusion` service started by `nexus dev`. This lets several apps share one
+   * Fusion database and keeps the backend process free of the Rust engine.
+   */
+  remote: boolean;
+  /** Standalone Fusion server base URL, e.g. `http://127.0.0.1:5000`.
+   *  Empty (and `remote: false`) keeps the embedded in-process engine. */
+  url: string;
   /** Durable storage dir, relative to the project root. Omit/empty for in-memory. */
   dir: string;
   /** Persist the WAL to `dir` (persist=false runs purely in-memory). */
@@ -165,11 +187,11 @@ export interface CertsConfig {
 
 export interface AdsConfig {
   enabled: boolean;
-  developerToken: string;
+  publisherId: string;
   clientId: string;
   clientSecret: string;
   refreshToken: string;
-  customerId: string;
+  accountId?: string;
 }
 
 export interface WebRtcConfig {
@@ -303,22 +325,14 @@ export interface AppPortConfig {
   enabled?: boolean;
 }
 
-export interface FusionConfig {
-  /** Durable storage dir, resolved against the backend's projectRoot. Empty or
-   *  persist=false runs the engine purely in-memory. Default 'storage/fusion'. */
-  dir: string;
-  /** When false, ignore `dir` and run purely in-memory. Default true. */
-  persist: boolean;
-  /** L1 cache capacity (entries). Default 10_000. */
-  cacheCapacity: number;
-  /** L1 cache TTL in ms. Default 5_000. */
-  cacheTtlMs: number;
-  /** WAL compaction threshold (records). Default 1_000. */
-  walCompactThreshold: number;
-}
-
 /** Redis-like FusionCache settings (`@bhooai/nexus-fusion/cache`). */
 export interface CacheConfig {
+  /** Which backend serves cache duties — 'fusion' (embedded, zero-dep,
+   *  default) or 'redis' (external server at `redis.url`). Override with
+   *  NEXUS_CACHE_ACTIVE. Single-instance apps are fully served by fusion
+   *  (strings/hashes/lists/sets + TTL); pick 'redis' for multi-instance
+   *  pub/sub fan-out. */
+  active: 'fusion' | 'redis';
   /** Durable storage dir, resolved against the backend's projectRoot. Cache
    *  lives in its own subdir (default 'storage/fusion/cache') so it never
    *  shares a WAL with the main fusion engine. */
@@ -339,6 +353,7 @@ export interface CacheConfig {
 
 export interface NexusConfig {
   env: Env;
+  app: AppConfig;
   server: ServerConfig;
   uploads: UploadsConfig;
   db: DbConfig;
@@ -356,7 +371,6 @@ export interface NexusConfig {
   plugins: PluginsConfig;
   frontend: FrontendConfig;
   admin: AdminConfig;
-  fusion: FusionConfig;
   cache: CacheConfig;
   /** Multi-app port layout. Empty = every service uses its section default. */
   apps: AppPortConfig[];

package/src/http/Server.ts

@@ -5,6 +5,7 @@ import { randomUUID } from 'node:crypto';
 import type { Middleware, RequestContext } from './context.js';
 import { createContext } from './context.js';
 import type { Router } from './Router.js';
+import type { NexusConfig } from '../config/types.js';
 import { NexusError, toNexusError } from '../errors.js';
 
 /** Generate a request id (overridable for tests/injection). */
@@ -33,6 +34,8 @@ export interface ServerOptions {
   renderError?: (err: unknown, ctx: RequestContext) => Promise<void> | void;
   /** Custom 404 renderer for unmatched routes. Falls back to JSON. */
   renderNotFound?: (ctx: RequestContext) => Promise<void> | void;
+  /** Loaded project config, exposed to handlers as `ctx.config`. */
+  config?: NexusConfig;
 }
 
 /**
@@ -87,6 +90,7 @@ export class NexusServer {
     const requestId = (req.headers['x-request-id'] as string) ?? newRequestId();
     res.setHeader('x-request-id', requestId);
     const ctx = createContext(req, res, requestId);
+    ctx.config = this.opts.config ?? null;
 
     try {
       await this.runPipeline(ctx);

package/src/http/context.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Socket } from 'node:net';
+import type { NexusConfig } from '../config/types.js';
 
 /** Route path parameters extracted from the URL. */
 export type Params = Record<string, string>;
@@ -26,6 +27,11 @@ export interface RequestContext {
   body: unknown;
   /** Per-request state. */
   state: State;
+  /**
+   * The loaded project config. Injected by NexusServer at request time; may be
+   * null when a context is built standalone (e.g. in tests).
+   */
+  config?: NexusConfig | null;
   /** Request id (also in headers as x-request-id). */
   requestId: string;
   /** The matched route pattern, e.g. "/users/:id". */