bhooai-nexus 0.1.2

package/packages/nexus-cli/templates/apps/backend/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "target": "ES2022",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/packages/nexus-cli/templates/apps/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Nexus App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/packages/nexus-cli/templates/apps/frontend/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "my-nexus-frontend",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.4.0"
+  }
+}

package/packages/nexus-cli/templates/apps/frontend/src/main.tsx

@@ -0,0 +1,64 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+// Generated placeholder frontend. The framework's own apps/frontend has the full
+// auth / GraphQL / streaming / checkout UI — copy what you need from there.
+async function pingHealth() {
+  try {
+    const res = await fetch('/health');
+    const body = await res.json();
+    document.getElementById('status')!.textContent = `${body.status} @ ${new Date(body.time).toLocaleTimeString()}`;
+  } catch {
+    document.getElementById('status')!.textContent = 'backend not reachable';
+  }
+}
+
+function App() {
+  const [file, setFile] = React.useState<File | null>(null);
+  const [uploadStatus, setUploadStatus] = React.useState('');
+
+  React.useEffect(() => {
+    pingHealth();
+    const id = setInterval(pingHealth, 5000);
+    return () => clearInterval(id);
+  }, []);
+
+  async function uploadFile() {
+    if (!file) return;
+    setUploadStatus('uploading...');
+    try {
+      const csrfResponse = await fetch('/csrf-token', { credentials: 'include' });
+      const { token } = await csrfResponse.json() as { token: string };
+      const form = new FormData();
+      form.append('file', file);
+      const response = await fetch('/uploads', {
+        method: 'POST',
+        body: form,
+        credentials: 'include',
+        headers: { 'x-csrf-token': token },
+      });
+      const body = await response.json() as { files?: Array<{ url: string }>; error?: { message?: string } };
+      if (!response.ok) throw new Error(body.error?.message ?? 'upload failed');
+      setUploadStatus(`uploaded: ${body.files?.[0]?.url ?? 'ok'}`);
+    } catch (error) {
+      setUploadStatus(error instanceof Error ? error.message : 'upload failed');
+    }
+  }
+
+  return (
+    <main style={{ fontFamily: 'system-ui, sans-serif', padding: '2rem' }}>
+      <h1>My Nexus App</h1>
+      <p>Backend health: <span id="status">checking…</span></p>
+      <h2>Upload a file</h2>
+      <input type="file" onChange={(event) => setFile(event.target.files?.[0] ?? null)} />
+      <button type="button" onClick={uploadFile} disabled={!file}>Upload</button>
+      <p>{uploadStatus}</p>
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/packages/nexus-cli/templates/apps/frontend/vite.config.ts

@@ -0,0 +1,72 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// Read the merged host/port values from the project's single nexus config file
+// (ts/js/mjs/cjs, discovery order matches the backend loader) plus NEXUS_*
+// env overrides, so this Vite dev server and its proxy stay in one source of
+// truth: nexus.config.js.
+async function loadConfig() {
+  const exts = ['ts', 'js', 'mjs', 'cjs'];
+  let user: Record<string, any> = {};
+  for (const ext of exts) {
+    const file = join(PROJECT_ROOT, `nexus.config.${ext}`);
+    if (existsSync(file)) {
+      const mod = (await import(pathToFileURL(file).href + `?v=${Date.now()}`)) as Record<string, any>;
+      user = mod.default ?? mod.config ?? {};
+      break;
+    }
+  }
+  const num = (v: string | undefined, fallback: number) => (v !== undefined && Number.isFinite(Number(v)) ? Number(v) : fallback);
+  const str = (v: string | undefined, fallback: string) => (v !== undefined && v !== '' ? v : fallback);
+
+  return {
+    server: {
+      host: str(process.env.NEXUS_SERVER_HOST, user.server?.host ?? '0.0.0.0'),
+      port: num(process.env.NEXUS_SERVER_PORT, user.server?.port ?? 4000),
+    },
+    frontend: {
+      host: str(process.env.NEXUS_FRONTEND_HOST, user.frontend?.host ?? 'localhost'),
+      port: num(process.env.NEXUS_FRONTEND_PORT, user.frontend?.port ?? 3000),
+      enabled: user.frontend?.enabled ?? true,
+    },
+    cluster: {
+      enabled: user.cluster?.enabled ?? false,
+      lbPort: num(process.env.NEXUS_CLUSTER_LBPORT, user.cluster?.lbPort ?? 8080),
+    },
+  };
+}
+
+export default defineConfig(async () => {
+  const cfg = await loadConfig();
+  const backendHost = cfg.server.host === '0.0.0.0' || cfg.server.host === '::' ? '127.0.0.1' : cfg.server.host;
+  const backend = `http://${backendHost}:${cfg.server.port}`;
+  const backendWs = `ws://${backendHost}:${cfg.server.port}`;
+  // When the cluster is enabled, route /uploads through the load balancer so
+  // path-pin routing (/uploads/images -> slave-1, /uploads/files -> slave-2)
+  // actually applies. Otherwise fall back to the local backend directly.
+  const lbTarget = `http://${backendHost}:${cfg.cluster.lbPort}`;
+  const uploadsTarget = cfg.cluster.enabled ? lbTarget : backend;
+
+  return {
+    plugins: [react()],
+    server: {
+      port: cfg.frontend.port,
+      host: cfg.frontend.host,
+      proxy: {
+        '/health': { target: backend, changeOrigin: true },
+        '/auth': { target: backend, changeOrigin: true },
+        '/csrf-token': { target: backend, changeOrigin: true },
+        '/graphql': { target: backend, changeOrigin: true, ws: true },
+        '/ai': { target: backend, changeOrigin: true },
+        '/payments': { target: backend, changeOrigin: true },
+        '/uploads': { target: uploadsTarget, changeOrigin: true },
+        '/ws': { target: backendWs, ws: true, changeOrigin: true },
+      },
+    },
+  };
+});

package/packages/nexus-cli/templates/bin/nexus.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Generated Nexus CLI entry. Resolves the `@bhooai/nexus-cli` package and
+ * dispatches the command. The CLI package's main points at TypeScript source
+ * (run via tsx) so there is no build step; if a compiled dist is present it is
+ * used directly.
+ */
+import { existsSync } from 'node:fs';
+import { extname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+async function main() {
+  // Resolve the CLI through the installed package exports. In a freshly init'd
+  // project the CLI is vendored under packages/nexus-cli, so this resolves to
+  // the vendored TypeScript source (no junction into the framework required).
+  const cliEntry = require.resolve('@bhooai/nexus-cli');
+  let mod;
+  if (existsSync(cliEntry) && extname(cliEntry) === '.js') {
+    mod = await import(pathToFileURL(cliEntry).href);
+  } else {
+    const { tsImport } = await import('tsx/esm/api');
+    mod = await tsImport(pathToFileURL(cliEntry).href, import.meta.url);
+  }
+  const cmd = process.argv[2] ?? 'help';
+  const rest = process.argv.slice(3);
+  await mod.run(cmd, rest);
+}
+
+main().catch((err) => {
+  console.error(err?.stack ?? err);
+  process.exit(1);
+});

package/packages/nexus-cli/templates/bin/serve-all.mjs

@@ -0,0 +1,45 @@
+// Runs the whole Nexus stack in one process tree (used as the Docker CMD):
+//   backend  -> nexus node serve --role=backend --port=<NEXUS_NODE_PORT|7575>
+//               (cluster node agent on :7575 + backend role service)
+//   frontend -> vite preview on :3000          (built SPA, proxies API)
+//   admin    -> vite preview on :3300          (built admin SPA, proxies API)
+// Forwards signals / reaps children so `docker stop` shuts down cleanly.
+import { spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+const node = process.execPath;
+const nodePort = process.env.NEXUS_NODE_PORT ?? '7575';
+const children = [];
+let shuttingDown = false;
+
+function run(name, cwd, cmd, args) {
+  const p = spawn(cmd, args, { cwd, stdio: ['ignore', 'inherit', 'inherit'], env: process.env });
+  children.push(p);
+  p.on('exit', (code) => {
+    if (shuttingDown) return;
+    console.error(`[serve-all] ${name} exited with code ${code ?? 1}`);
+    shutdown(code ?? 1);
+  });
+  p.on('error', (err) => {
+    if (shuttingDown) return;
+    console.error(`[serve-all] ${name} failed to start: ${err.message}`);
+    shutdown(1);
+  });
+}
+
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const c of children) c.kill('SIGTERM');
+  setTimeout(() => process.exit(code), 3000);
+}
+
+process.on('SIGINT', () => shutdown(0));
+process.on('SIGTERM', () => shutdown(0));
+
+run('backend', root, node, ['bin/nexus.js', 'node', 'serve', '--role=backend', `--port=${nodePort}`]);
+run('frontend', join(root, 'apps', 'frontend'), npm, ['run', 'preview', '--', '--host', '0.0.0.0', '--port', '3000']);
+run('admin', join(root, 'apps', 'admin'), npm, ['run', 'preview', '--', '--host', '0.0.0.0', '--port', '3300']);

package/packages/nexus-cli/templates/dockerignore

@@ -0,0 +1,15 @@
+node_modules/
+**/node_modules/
+dist/
+logs/
+*.log
+.env
+nexus.runtime.json
+.nexus-sync.json
+.git/
+.DS_Store
+README.md
+PROGRESS.md
+.dockerignore
+Dockerfile
+*.tsbuildinfo

package/packages/nexus-cli/templates/gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.env
+nexus.runtime.json
+.nexus-sync.json
+cluster.runtime.json
+logs/
+certs/
+uploads/*
+!uploads/.gitkeep
+__pycache__/
+.venv/

package/packages/nexus-cli/templates/nexus.config.ts

@@ -0,0 +1,69 @@
+import type { NexusConfig } from '@bhooai/nexus-core';
+
+/**
+ * THE single, human-edited config file for every server host/port.
+ *
+ * Precedence (low → high): code defaults < this file < nexus.runtime.json
+ * (admin, gitignored) < NEXUS_* env vars < CLI flags. Admin writes only
+ * `nexus.runtime.json`, so this file stays clean.
+ *
+ * The backend, MongoDB, Redis, the AI server, the frontend and admin Vite
+ * dev servers, and the node mesh all read their host/port from here. The
+ * Vite dev servers (apps/admin/vite.config.ts, apps/frontend/vite.config.ts)
+ * open the SAME file, so change host/port in ONE place.
+ */
+const config: Partial<NexusConfig> = {
+  env: 'development',
+  
+  // The HTTP API server the browser/cluster proxy to.
+  server: { port: 4000, host: '0.0.0.0', https: false, trustProxy: false, bodyLimit: 12 * 1024 * 1024 },
+  // Vite dev server for the frontend — hosts guests visit.
+  frontend: { port: 3000, host: 'localhost', enabled: true },
+  // Python AI server (first /ai/* proxy hops to this).
+  ai: { serverUrl: 'http://localhost:8000', timeoutMs: 60_000, defaultProvider: 'auto', schemaModel: 'llama3:latest' },
+  // Vite dev server for the admin app.
+  admin: { port: 3300, host: 'localhost', enabled: true },
+  // Node mesh: set kind via —as=root|node at init (this file stays minimal).
+  cluster: { enabled: false, failOpenSingleNode: true, lbHost: '0.0.0.0', lbPort: 8080, nodeAgentHost: '0.0.0.0', nodeAgentPort: 7575, registryFile: 'cluster.runtime.json', token: '' },
+  
+  // File uploads.
+  uploads: { dir: 'uploads', path: '/uploads', maxFileSize: 10 * 1024 * 1024, maxFiles: 20, allowedTypes: [] },
+  // MongoDB host/port/database.
+  db: { uri: 'mongodb://localhost:27017/acme-app', maxPoolSize: 10, autoIndex: true },
+  // Redis host/port.
+  redis: { url: 'redis://localhost:6379', keyPrefix: 'acme:' },
+  // GraphQL API server (first /graphql proxy hops to this).
+  graphql: { path: '/graphql', federation: 'in-process', subscriptions: true, introspection: true },
+  //Web Socket server for the browser/cluster proxy to.
+  ws: { path: '/ws', heartbeatMs: 30_000, requireCsrf: true },
+
+  auth: {
+    // JWT secret comes ONLY from NEXUS_AUTH_JWT_SECRET in .env — never here.
+    jwt: { accessTtl: 60 * 15, refreshTtl: 60 * 60 * 24 * 30 },
+    cookieName: 'nexus_sid',
+    refreshCookieName: 'nexus_rid',
+    requireEmailVerification: false,
+  },
+
+  payments: { webhookPath: '/payments/webhook/:provider', currency: 'INR',
+    razorpay: { enabled: false, sandbox: true },
+    paypal: { enabled: false, sandbox: true },
+    payu: { enabled: false, sandbox: true },
+    skrill: { enabled: false, sandbox: true },
+    payoneer: { enabled: false, sandbox: true },
+   },
+  email: { provider: 'log', from: 'no-reply@acme.local' },
+  // Certificates for HTTPS, WebRTC, etc.
+  certs: { dir: 'certs', keyType: 'rsa', rsaModulus: 2048, ecCurve: 'prime256v1', validityDays: 365 },
+  // Google Ads API (first /ads proxy hops to this).
+  ads: { enabled: false, developerToken: '', clientId: '', clientSecret: '', refreshToken: '', customerId: '' },
+  // WebRTC server (first /webrtc proxy hops to this).
+  webrtc: { rtcMinPort: 40000, rtcMaxPort: 40100, announceIp: '127.0.0.1' },
+
+
+  // Logging and plugins.
+  logging: { level: 'info', format: 'pretty', console: true, dir: 'logs', maxFileSize: 10 * 1024 * 1024, maxFiles: 7 },
+  plugins: { dir: 'plugins', entries: [] },
+};
+
+export default config;

package/packages/nexus-cli/templates/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "my-nexus-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "../bhooai-nexus/packages/*",
+    "apps/backend",
+    "apps/admin",
+    "apps/frontend"
+  ],
+  "scripts": {
+    "init": "nexus init .",
+    "dev": "nexus dev",
+    "build": "nexus build",
+    "test": "nexus test",
+    "doctor": "nexus doctor",
+    "pysetup": "nexus pysetup",
+    "uninstall": "nexus uninstall",
+    "start": "tsx apps/backend/src/main.ts"
+  },
+  "dependencies": {
+    "bhooai-nexus": "file:../bhooai-nexus",
+    "@bhooai/admin": "*",
+    "@bhooai/nexus-cli": "*",
+    "@bhooai/nexus-core": "*",
+    "@bhooai/nexus-auth": "*",
+    "@bhooai/nexus-data": "*",
+    "@bhooai/nexus-telemetry": "*",
+    "@bhooai/nexus-realtime": "*",
+    "@bhooai/nexus-graphql": "*",
+    "@bhooai/nexus-cache": "*",
+    "@bhooai/nexus-email": "*",
+    "@bhooai/nexus-payments": "*",
+    "@bhooai/nexus-crypto": "*",
+    "@bhooai/nexus-cluster": "*",
+    "@bhooai/nexus-ads": "*",
+    "@bhooai/nexus-plugins": "*",
+    "@bhooai/nexus-ai-client": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^2.1.0"
+  }
+}

package/packages/nexus-cli/templates/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["apps/**/*", "nexus.config.ts"]
+}

package/packages/nexus-core/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@bhooai/nexus-core",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./config": {
+      "types": "./src/config/index.ts",
+      "import": "./src/config/index.ts"
+    },
+    "./di": {
+      "types": "./src/di/index.ts",
+      "import": "./src/di/index.ts"
+    },
+    "./http": {
+      "types": "./src/http/index.ts",
+      "import": "./src/http/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}

package/packages/nexus-core/src/config/ConfigLoader.ts

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { defaults } from './defaults.js';
+import { deepMerge } from './merge.js';
+import { configFromEnv, loadEnvFile } from './env.js';
+import { nexusConfigSchema } from './schema.js';
+import type { DeepPartial, NexusConfig, UserNexusConfig } from './types.js';
+
+export interface LoadOptions {
+  /** The imported user config object (from `nexus.config.ts`). */
+  userConfig?: UserNexusConfig;
+  /** Path to a `nexus.config.ts`/`.js` to import dynamically if `userConfig` not given. */
+  userConfigPath?: string;
+  /** Path to a shipped default config (the framework's `nexus/nexus.config.ts`) merged right
+   *  after the code defaults and before the user config. */
+  defaultConfigPath?: string;
+  /** Path to `nexus.runtime.json` (admin write-back). Defaults to `<root>/nexus.runtime.json`. */
+  runtimePath?: string;
+  /** Project root used to resolve relative paths. Defaults to cwd. */
+  root?: string;
+  /** Env override (for tests). */
+  env?: NodeJS.ProcessEnv;
+  /** CLI flag overrides (highest precedence). */
+  cli?: DeepPartial<NexusConfig>;
+}
+
+/**
+ * Load and merge configuration in precedence order:
+ *   defaults < userConfig (nexus.config.ts) < runtime.json < env < cli
+ * Then validate with the zod schema and return a frozen, typed config.
+ */
+export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
+  const root = resolve(opts.root ?? process.cwd());
+  const env = opts.env ?? process.env;
+
+  // 0. project .env — merged into the env object BEFORE env-var mapping below.
+  //    Skipped when a caller passes its own env (tests), which must stay pure.
+  if (!opts.env) loadEnvFile(root, env);
+
+  // 1. defaults
+  let merged: unknown = defaults;
+
+  // 1b. shipped default config (the framework's nexus.config.ts) — base layer above code defaults
+  if (opts.defaultConfigPath && existsSync(resolve(opts.defaultConfigPath))) {
+    const defaultConfig = await importUserConfig(resolve(opts.defaultConfigPath));
+    merged = deepMerge(merged, defaultConfig);
+  }
+
+  // 2. user config (nexus.config.ts / nexus.config.js)
+  let userConfig = opts.userConfig;
+  if (!userConfig && opts.userConfigPath) {
+    userConfig = await importUserConfig(resolve(opts.userConfigPath));
+  }
+  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.
+    }
+  }
+
+  // 4. env
+  merged = deepMerge(merged, configFromEnv(env));
+
+  // 5. cli flags (highest)
+  if (opts.cli) merged = deepMerge(merged, opts.cli);
+
+  // validate
+  const parsed = nexusConfigSchema.parse(merged);
+  return Object.freeze(parsed) as NexusConfig;
+}
+
+async function importUserConfig(absPath: string): Promise<UserNexusConfig> {
+  const url = pathToFileURL(absPath).href;
+  const mod = (await import(url)) as Record<string, unknown>;
+  const cfg = (mod.default ?? mod.config) as UserNexusConfig | undefined;
+  if (!cfg) {
+    throw new Error(
+      `Expected ${absPath} to export a config object as the default export or named "config".`,
+    );
+  }
+  return cfg;
+}
+
+/** Resolve a path relative to the project root. */
+export function resolvePath(cfg: NexusConfig, rel: string): string {
+  return resolve(rel);
+}
+
+const CONFIG_EXTENSIONS = ['ts', 'js', 'mjs', 'cjs'] as const;
+
+/**
+ * Path to the framework's own shipped `nexus.config.ts` (at the framework workspace root).
+ * Resolved relative to THIS file so it works from both `src/` (run via tsx) and `dist/`
+ * (compiled). When `@bhooai/nexus-core` is installed inside a user app's `node_modules/`,
+ * this resolves to a non-existent path under `node_modules/` — so it is simply skipped there
+ * (a user app does not inherit the framework's example config).
+ */
+export function frameworkDefaultConfigPath(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  // src/config/  ->  src  ->  <pkg>  ->  packages  ->  <framework root>  (4 levels up)
+  return resolve(here, '..', '..', '..', '..', 'nexus.config.ts');
+}
+
+/**
+ * First `nexus.config.{ts,js,mjs,cjs}` found walking UP from `root`, skipping `exclude`.
+ * Standard find-first discovery; stops at the filesystem root.
+ */
+export function discoverUserConfigPath(root: string, exclude?: string): string | undefined {
+  let dir = resolve(root);
+  const excl = exclude ? resolve(exclude) : undefined;
+  for (let i = 0; i < 24; i++) {
+    for (const ext of CONFIG_EXTENSIONS) {
+      const cand = join(dir, `nexus.config.${ext}`);
+      if (existsSync(cand) && (!excl || resolve(cand) !== excl)) return cand;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root
+    dir = parent;
+  }
+  return undefined;
+}
+
+/**
+ * Auto-discover and load config with the framework's two-level model:
+ *   defaults  <  framework default (`nexus/nexus.config.ts`)  <  user config  <  runtime.json  <  env  <  cli
+ *
+ * The framework default is located via `frameworkDefaultConfigPath()` (the shipped
+ * `nexus/nexus.config.ts`). The user config is the nearest `nexus.config.{ts,js,...}` walking
+ * up from `root`, SKIPPING that default — so when running the framework's own app (cwd =
+ * `nexus/`), the discovery walks past `nexus/nexus.config.ts` and finds the user-editable
+ * `nexus.config.js` at the project root, which overrides the default. When running a user app,
+ * the framework default path does not exist, so only that app's own config is loaded.
+ */
+export async function loadConfigAuto(
+  opts: Omit<LoadOptions, 'userConfig' | 'userConfigPath' | 'defaultConfigPath'> = {},
+): Promise<NexusConfig> {
+  const root = resolve(opts.root ?? process.cwd());
+  const defaultPath = frameworkDefaultConfigPath();
+  const defaultExists = existsSync(defaultPath);
+  const userPath = defaultExists
+    ? discoverUserConfigPath(root, defaultPath)
+    : discoverUserConfigPath(root);
+  return loadConfig({
+    ...opts,
+    root,
+    defaultConfigPath: defaultExists ? defaultPath : undefined,
+    userConfigPath: userPath,
+  });
+}
+
+/** Read-only accessor for tests / bootstrap that don't need file loading. */
+export function mergeConfig(...sources: DeepPartial<NexusConfig>[]): NexusConfig {
+  return Object.freeze(nexusConfigSchema.parse(deepMerge(defaults, ...sources))) as NexusConfig;
+}