@bhooai/nexus-core 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @bhooai/nexus-core
+
+The framework core: config loading with full precedence, a dependency-injection
+container, typed error classes, and the inbuilt HTTP server.
+
+## Exports
+
+- **config** — `loadConfig({ root })` resolves defaults < `nexus.config.ts` <
+  `nexus.runtime.json` < `NEXUS_*` env vars into a typed `NexusConfig`.
+- **http** — `Router`, `NexusServer` (custom `node:http` server with a trie router,
+  params/wildcards, and a middleware pipeline), `bodyParser`, `RequestContext`.
+- **di** — `Container` (the inbuilt DI used by the plugin host and services).
+- **errors** — `HttpError`, `ValidationError`, `AuthenticationError`,
+  `ConflictError`, `NotFoundError`, etc.
+
+## Usage
+
+```ts
+import { loadConfig, Router, NexusServer, bodyParser } from '@bhooai/nexus-core';
+
+const router = new Router();
+router.get('/health', (ctx) => ctx.json({ status: 'ok' }));
+
+const server = new NexusServer({
+  router,
+  middleware: [bodyParser()],
+});
+await server.listen(4000, '0.0.0.0');
+```
+
+There is **no `server.use()`** — middleware is the `middleware` array passed to the
+`NexusServer` constructor. Route middleware is the 3rd argument to `router.method`,
+as an array, and runs before the handler.
+
+See `apps/backend/src/main.ts` for the full bootstrap.

package/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/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;
+}

package/src/config/defaults.ts

@@ -0,0 +1,155 @@
+import type { NexusConfig } from './types.js';
+
+/**
+ * Code-level defaults — the lowest-precedence layer of the config stack.
+ * Every field is present so a config that supplies nothing still boots.
+ */
+export const defaults: NexusConfig = {
+  env: 'development',
+  server: {
+    port: 4000,
+    host: '127.0.0.1',
+    https: false,
+    trustProxy: false,
+     bodyLimit: 12 * 1024 * 1024, // 12 MiB, allowing a 10 MiB upload plus multipart overhead
+   },
+  uploads: {
+    dir: 'uploads',
+    path: '/uploads',
+    maxFileSize: 10 * 1024 * 1024,
+    maxFiles: 20,
+    allowedTypes: [],
+  },
+  db: {
+    uri: 'mongodb://localhost:27017/nexus',
+    maxPoolSize: 10,
+    autoIndex: true,
+  },
+  redis: {
+    url: 'redis://localhost:6379',
+    keyPrefix: 'nexus:',
+  },
+  graphql: {
+    path: '/graphql',
+    federation: 'in-process',
+    subscriptions: true,
+    introspection: true,
+  },
+  ws: {
+    path: '/ws',
+    heartbeatMs: 30_000,
+    requireCsrf: true,
+  },
+  auth: {
+    jwt: {
+      secret: 'change-me-please',
+      accessTtl: 60 * 15, // 15 min
+      refreshTtl: 60 * 60 * 24 * 30, // 30 days
+      issuer: 'bhooai-nexus',
+      audience: 'bhooai-nexus-client',
+    },
+    cookieName: 'nexus_sid',
+    refreshCookieName: 'nexus_rid',
+    requireEmailVerification: false,
+    google: { clientId: '', clientSecret: '', callbackPath: '/auth/google/callback', scope: 'openid email profile' },
+    facebook: { clientId: '', clientSecret: '', callbackPath: '/auth/facebook/callback', scope: 'email' },
+  },
+  payments: {
+    webhookPath: '/payments/webhook/:provider',
+    currency: 'INR',
+  },
+  email: {
+    provider: 'log',
+    from: 'no-reply@nexus.local',
+  },
+  certs: {
+    dir: 'certs',
+    keyType: 'rsa',
+    rsaModulus: 2048,
+    ecCurve: 'prime256v1',
+    validityDays: 365,
+  },
+  ads: {
+    enabled: false,
+    developerToken: '',
+    clientId: '',
+    clientSecret: '',
+    refreshToken: '',
+    customerId: '',
+  },
+  webrtc: {
+    rtcMinPort: 40000,
+    rtcMaxPort: 40100,
+    announceIp: '127.0.0.1',
+  },
+  ai: {
+    serverUrl: 'http://localhost:8000',
+    timeoutMs: 60_000,
+    defaultProvider: 'auto',
+    schemaModel: 'gpt-4o-mini',
+    providers: [
+      { id: 'ollama', label: 'Ollama (local)', baseUrl: 'http://localhost:11434', enabled: true, defaultModel: 'llama3:latest' },
+      { id: 'openai', label: 'OpenAI', baseUrl: 'https://api.openai.com/v1', enabled: false, defaultModel: 'gpt-4o-mini' },
+      { id: 'anthropic', label: 'Anthropic Claude', baseUrl: 'https://api.anthropic.com/v1', enabled: false, defaultModel: 'claude-sonnet-4-20250514' },
+      { id: 'google', label: 'Google Gemini', baseUrl: 'https://generativelanguage.googleapis.com/v1', enabled: false, defaultModel: 'gemini-2.0-flash' },
+      { id: 'groq', label: 'Groq', baseUrl: 'https://api.groq.com/openai/v1', enabled: false, defaultModel: 'llama-3.3-70b-versatile' },
+      { id: 'mistral', label: 'Mistral AI', baseUrl: 'https://api.mistral.ai/v1', enabled: false, defaultModel: 'mistral-large-latest' },
+      { id: 'cohere', label: 'Cohere', baseUrl: 'https://api.cohere.ai/v1', enabled: false, defaultModel: 'command-r-plus' },
+      { id: 'together', label: 'Together AI', baseUrl: 'https://api.together.xyz/v1', enabled: false, defaultModel: 'meta-llama/Llama-3-70b-chat-hf' },
+      { id: 'fireworks', label: 'Fireworks AI', baseUrl: 'https://api.fireworks.ai/inference/v1', enabled: false, defaultModel: 'accounts/fireworks/models/llama-v3-70b-instruct' },
+      { id: 'deepseek', label: 'DeepSeek', baseUrl: 'https://api.deepseek.com/v1', enabled: false, defaultModel: 'deepseek-chat' },
+      { id: 'perplexity', label: 'Perplexity', baseUrl: 'https://api.perplexity.ai', enabled: false, defaultModel: 'llama-3.1-sonar-large-128k-online' },
+      { id: 'xai', label: 'xAI (Grok)', baseUrl: 'https://api.x.ai/v1', enabled: false, defaultModel: 'grok-2-latest' },
+      { id: 'replicate', label: 'Replicate', baseUrl: 'https://api.replicate.com/v1', enabled: false, defaultModel: 'meta/llama-3-70b-instruct' },
+      { id: 'huggingface', label: 'Hugging Face', baseUrl: 'https://api-inference.huggingface.co/models', enabled: false, defaultModel: 'meta-llama/Llama-3-70b-chat-hf' },
+      { id: 'nvidia', label: 'NVIDIA NIM', baseUrl: 'https://integrate.api.nvidia.com/v1', enabled: false, defaultModel: 'meta/llama-3.1-70b-instruct' },
+      { id: 'openrouter', label: 'OpenRouter', baseUrl: 'https://openrouter.ai/api/v1', enabled: false, defaultModel: 'openai/gpt-4o-mini' },
+      { id: 'lmstudio', label: 'LM Studio (local)', baseUrl: 'http://localhost:1234/v1', enabled: false, defaultModel: 'local-model' },
+      { id: 'alephalpha', label: 'Aleph Alpha', baseUrl: 'https://api.aleph-alpha.com/v1', enabled: false, defaultModel: 'luminous-supreme-control' },
+      { id: 'stability', label: 'Stability AI', baseUrl: 'https://api.stability.ai/v1', enabled: false, defaultModel: 'stable-diffusion-xl' },
+      { id: 'azure', label: 'Azure OpenAI', baseUrl: 'https://your-resource.openai.azure.com', enabled: false, defaultModel: 'gpt-4o-mini' },
+    ],
+  },
+  logging: {
+    level: 'info',
+    format: 'pretty',
+    console: true,
+    dir: 'logs',
+    maxFileSize: 10 * 1024 * 1024, // 10 MiB
+    maxFiles: 7,
+  },
+  plugins: {
+    dir: 'plugins',
+    entries: [],
+  },
+  frontend: {
+    port: 3000,
+    host: 'localhost',
+    enabled: true,
+  },
+  admin: {
+    port: 3001,
+    host: 'localhost',
+    enabled: true,
+  },
+  cluster: {
+    enabled: false,
+    failOpenSingleNode: true,
+    lbHost: '127.0.0.1',
+    lbPort: 8080,
+    nodeAgentHost: '127.0.0.1',
+    nodeAgentPort: 7575,
+    registryFile: 'cluster.runtime.json',
+    token: '',
+    autoscale: {
+      enabled: true,
+      mode: 'auto',
+      minNodes: 1,
+      maxNodes: 4,
+      cooldownMs: 60_000,
+      cpuHigh: 80,
+      rpsPerNodeHigh: 15,
+      rpsPerNodeLow: 5,
+    },
+  },
+};

package/src/config/env.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { DeepPartial, NexusConfig } from './types.js';
+
+/**
+ * Load `<root>/.env` into `env` WITHOUT overriding variables that are already
+ * set (a real environment value always wins). Dependency-free: `KEY=VALUE`
+ * (optional `export ` prefix), `#` comments, blank lines, optional quotes.
+ *
+ * The CLI used to be the only `.env` loader, so a backend started directly
+ * (tsx, plain node) never saw `.env` secrets. Every config consumer now loads
+ * the project `.env` itself; double-loading is harmless (idempotent).
+ */
+export function loadEnvFile(root: string, env: NodeJS.ProcessEnv): void {
+  const file = resolve(root, '.env');
+  if (!existsSync(file)) return;
+  let content: string;
+  try {
+    content = readFileSync(file, 'utf8');
+  } catch {
+    return;
+  }
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const key = m[1]!;
+    if (env[key] !== undefined) continue; // real env always wins
+    let value = m[2]!.trim();
+    if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+      value = value.slice(1, -1);
+    }
+    env[key] = value;
+  }
+}
+
+/**
+ * Build a config-override object from `NEXUS_*` environment variables.
+ * Nested keys use `_` as a separator, e.g. `NEXUS_SERVER_PORT` -> { server: { port } }.
+ *
+ * Type coercion: integers for numeric fields, booleans for true/false,
+ * comma lists for arrays where applicable (heuristic by key).
+ */
+function coerce(value: string): string | number | boolean {
+  const v = value.trim();
+  if (/^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  if (v.toLowerCase() === 'true') return true;
+  if (v.toLowerCase() === 'false') return false;
+  return v;
+}
+
+/**
+ * Two `_`-separated env segments that form ONE camelCase config field.
+ * Generic splitting would turn `KEY_ID` into `key.id` (a nested object) —
+ * these known compounds collapse into a single tree key:
+ *   NEXUS_PAYMENTS_RAZORPAY_KEY_ID   -> payments.razorpay.keyId
+ *   NEXUS_AUTH_GOOGLE_CLIENT_SECRET  -> auth.google.clientSecret
+ */
+const PAIR_FIELDS: Record<string, string> = {
+  'key_id': 'keyId',
+  'key_secret': 'keySecret',
+  'client_id': 'clientId',
+  'client_secret': 'clientSecret',
+  'merchant_key': 'merchantKey',
+  'merchant_email': 'merchantEmail',
+  'program_id': 'programId',
+  'api_key': 'apiKey',
+  'webhook_secret': 'webhookSecret',
+  'customer_id': 'customerId',
+  'developer_token': 'developerToken',
+  'refresh_token': 'refreshToken',
+  'access_ttl': 'accessTtl',
+  'refresh_ttl': 'refreshTtl',
+  'callback_path': 'callbackPath',
+  'lb_port': 'lbPort',
+  'lb_host': 'lbHost',
+  'node_agent_port': 'nodeAgentPort',
+  'node_agent_host': 'nodeAgentHost',
+  'registry_file': 'registryFile',
+  'min_nodes': 'minNodes',
+  'max_nodes': 'maxNodes',
+  'cooldown_ms': 'cooldownMs',
+  'cpu_high': 'cpuHigh',
+  'rps_per_node_high': 'rpsPerNodeHigh',
+  'rps_per_node_low': 'rpsPerNodeLow',
+};
+
+export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial<NexusConfig> {
+  const out: Record<string, unknown> = {};
+  for (const [rawKey, rawValue] of Object.entries(env)) {
+    if (!rawKey.startsWith('NEXUS_') || rawValue === undefined) continue;
+    const path = rawKey.slice('NEXUS_'.length).toLowerCase().split('_');
+    const last = path.length - 1;
+    if (last >= 1) {
+      const compound = PAIR_FIELDS[`${path[last - 1]}_${path[last]}`];
+      if (compound) {
+        path.splice(last - 1, 2, compound);
+      }
+    }
+    let node: Record<string, unknown> = out;
+    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>;
+      }
+    }
+  }
+  return out as DeepPartial<NexusConfig>;
+}

package/src/config/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js';
+export * from './defaults.js';
+export * from './merge.js';
+export * from './env.js';
+export * from './schema.js';
+export * from './ConfigLoader.js';

package/src/config/merge.ts

@@ -0,0 +1,28 @@
+/**
+ * Deep merge of plain objects. Later sources win. Arrays are replaced, not
+ * concatenated (config arrays are declarative). Non-plain objects (e.g. Date,
+ * RegExp) are assigned by reference.
+ */
+export function isPlainObject(v: unknown): v is Record<string, unknown> {
+  if (v === null || typeof v !== 'object') return false;
+  const proto = Object.getPrototypeOf(v) as unknown;
+  return proto === Object.prototype || proto === null;
+}
+
+export function deepMerge<T>(base: T, ...sources: unknown[]): T {
+  if (!isPlainObject(base)) return (sources.at(-1) as T) ?? base;
+  const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+  for (const source of sources) {
+    if (!isPlainObject(source)) continue;
+    for (const [key, value] of Object.entries(source)) {
+      if (value === undefined) continue;
+      const current = out[key];
+      if (isPlainObject(current) && isPlainObject(value)) {
+        out[key] = deepMerge(current, value);
+      } else {
+        out[key] = value;
+      }
+    }
+  }
+  return out as T;
+}