@bhooai/nexus-core 0.1.0

package/src/config/schema.ts

@@ -0,0 +1,178 @@
+import { z } from 'zod';
+
+/**
+ * Zod validation schema for the merged `NexusConfig`. Validates types and the
+ * most error-prone fields (ports, URLs, TTLs). Provider sub-configs use a
+ * permissive record so custom keys flow through.
+ */
+const providerConfig = z
+  .object({ enabled: z.boolean().default(false), sandbox: z.boolean().default(true) })
+  .passthrough();
+
+export const nexusConfigSchema = z.object({
+  env: z.enum(['development', 'production', 'test']).default('development'),
+  server: z.object({
+    port: z.number().int().min(1).max(65535),
+    host: z.string().min(1),
+    https: z.boolean(),
+    certFile: z.string().optional(),
+    keyFile: z.string().optional(),
+    trustProxy: z.union([z.boolean(), z.number().int().nonnegative()]),
+    bodyLimit: z.number().int().positive(),
+  }),
+  uploads: z.object({
+    dir: z.string().min(1),
+    path: z.string().startsWith('/'),
+    maxFileSize: z.number().int().positive(),
+    maxFiles: z.number().int().positive(),
+    allowedTypes: z.array(z.string()),
+  }),
+  db: z.object({
+    uri: z.string().min(1),
+    name: z.string().optional(),
+    maxPoolSize: z.number().int().positive(),
+    autoIndex: z.boolean(),
+  }),
+  redis: z.object({ url: z.string().min(1), keyPrefix: z.string() }),
+  graphql: z.object({
+    path: z.string().min(1),
+    federation: z.enum(['in-process', 'distributed']),
+    subscriptions: z.boolean(),
+    introspection: z.boolean(),
+  }),
+  ws: z.object({
+    path: z.string().min(1),
+    heartbeatMs: z.number().int().positive(),
+    requireCsrf: z.boolean(),
+  }),
+  auth: z.object({
+    jwt: z.object({
+      secret: z.string().min(8, 'jwt.secret must be at least 8 characters'),
+      accessTtl: z.number().int().positive(),
+      refreshTtl: z.number().int().positive(),
+      issuer: z.string(),
+      audience: z.string(),
+    }),
+    cookieName: z.string(),
+    refreshCookieName: z.string(),
+    google: z
+      .object({
+        clientId: z.string(),
+        clientSecret: z.string(),
+        callbackPath: z.string(),
+        scope: z.string(),
+      })
+      .optional(),
+    facebook: z
+      .object({
+        clientId: z.string(),
+        clientSecret: z.string(),
+        callbackPath: z.string(),
+        scope: z.string(),
+      })
+      .optional(),
+    requireEmailVerification: z.boolean(),
+  }),
+  payments: z.object({
+    razorpay: providerConfig.optional(),
+    paypal: providerConfig.optional(),
+    payu: providerConfig.optional(),
+    skrill: providerConfig.optional(),
+    payoneer: providerConfig.optional(),
+    webhookPath: z.string(),
+    currency: z.string().length(3),
+  }),
+  email: z.object({
+    provider: z.enum(['smtp', 'log']),
+    smtp: z
+      .object({
+        host: z.string(),
+        port: z.number().int().min(1).max(65535),
+        secure: z.boolean(),
+        user: z.string(),
+        pass: z.string(),
+      })
+      .optional(),
+    from: z.string(),
+  }),
+  certs: z.object({
+    dir: z.string(),
+    keyType: z.enum(['rsa', 'ec']),
+    rsaModulus: z.number().int().positive(),
+    ecCurve: z.enum(['prime256v1', 'secp384r1', 'secp521r1']),
+    validityDays: z.number().int().positive(),
+  }),
+  ads: z.object({
+    enabled: z.boolean(),
+    developerToken: z.string(),
+    clientId: z.string(),
+    clientSecret: z.string(),
+    refreshToken: z.string(),
+    customerId: z.string(),
+  }),
+  webrtc: z.object({
+    rtcMinPort: z.number().int().min(1).max(65535),
+    rtcMaxPort: z.number().int().min(1).max(65535),
+    announceIp: z.string(),
+  }),
+  ai: z.object({
+    serverUrl: z.string().url(),
+    timeoutMs: z.number().int().positive(),
+    defaultProvider: z.enum(['openai', 'ollama', 'auto']),
+    schemaModel: z.string().min(1).optional(),
+    providers: z.array(z.object({
+      id: z.string().min(1),
+      label: z.string().min(1),
+      baseUrl: z.string(),
+      enabled: z.boolean(),
+      apiKey: z.string().optional(),
+      defaultModel: z.string().optional(),
+    })).optional(),
+  }),
+  logging: z.object({
+    level: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']),
+    format: z.enum(['json', 'pretty']),
+    console: z.boolean(),
+    dir: z.string(),
+    maxFileSize: z.number().int().positive(),
+    maxFiles: z.number().int().positive(),
+  }),
+  plugins: z.object({
+    dir: z.string(),
+    entries: z.array(
+      z.object({ path: z.string(), enabled: z.boolean(), config: z.record(z.unknown()).optional() }),
+    ),
+  }),
+  frontend: z.object({
+    port: z.number().int().min(1).max(65535),
+    host: z.string().min(1),
+    enabled: z.boolean(),
+  }),
+  admin: z.object({
+    port: z.number().int().min(1).max(65535),
+    host: z.string().min(1),
+    enabled: z.boolean(),
+  }),
+  cluster: z.object({
+    enabled: z.boolean(),
+    failOpenSingleNode: z.boolean(),
+    lbHost: z.string().min(1),
+    lbPort: z.number().int().min(1).max(65535),
+    nodeAgentHost: z.string().min(1),
+    nodeAgentPort: z.number().int().min(1).max(65535),
+    registryFile: z.string().min(1),
+    token: z.string(),
+    autoscale: z.object({
+      enabled: z.boolean(),
+      mode: z.enum(['auto', 'manual']),
+      minNodes: z.number().int().min(1),
+      maxNodes: z.number().int().min(1),
+      cooldownMs: z.number().int().nonnegative(),
+      cpuHigh: z.number().min(0).max(100),
+      rpsPerNodeHigh: z.number().nonnegative(),
+      rpsPerNodeLow: z.number().nonnegative(),
+    }),
+  }),
+});
+
+export type ValidatedNexusConfig = z.infer<typeof nexusConfigSchema>;

package/src/config/types.ts

@@ -0,0 +1,342 @@
+/**
+ * BhooAI Nexus — root configuration types.
+ *
+ * The single config file (`nexus.config.ts`) is typed by `NexusConfig`.
+ * Precedence (low → high): code defaults < nexus.config.ts < nexus.runtime.json
+ * < environment variables < CLI flags.
+ */
+
+export type Env = 'development' | 'production' | 'test';
+
+export interface ServerConfig {
+  port: number;
+  host: string;
+  /** When true, serve over HTTPS using the certs from `certs`. */
+  https: boolean;
+  /** Path to a generated TLS cert/key pair (relative to project root). */
+  certFile?: string;
+  keyFile?: string;
+  /** Trust proxy headers (X-Forwarded-*) — set to the number of hops or true. */
+  trustProxy: boolean | number;
+  /** Maximum request body size in bytes. */
+  bodyLimit: number;
+}
+
+export interface UploadsConfig {
+  /** Directory for persisted files, relative to the project root. */
+  dir: string;
+  /** Public URL path for upload and download requests. */
+  path: string;
+  /** Maximum size of one uploaded file in bytes. */
+  maxFileSize: number;
+  /** Maximum number of files accepted in one request. */
+  maxFiles: number;
+  /** Empty means all MIME types are accepted. */
+  allowedTypes: string[];
+}
+
+export interface DbConfig {
+  uri: string;
+  /** Database name override; otherwise taken from the URI. */
+  name?: string;
+  /** Connection pool size. */
+  maxPoolSize: number;
+  /** Auto-create indexes declared in schemas on boot. */
+  autoIndex: boolean;
+}
+
+export interface RedisConfig {
+  url: string;
+  /** Key prefix for namespacing. */
+  keyPrefix: string;
+}
+
+export interface JwtConfig {
+  secret: string;
+  /** Access token TTL in seconds. */
+  accessTtl: number;
+  /** Refresh token TTL in seconds. */
+  refreshTtl: number;
+  issuer: string;
+  audience: string;
+}
+
+export interface OAuthProviderConfig {
+  clientId: string;
+  clientSecret: string;
+  /** OAuth redirect path relative to the server root, e.g. "/auth/google/callback". */
+  callbackPath: string;
+  /** Space-separated OAuth scopes. */
+  scope: string;
+}
+
+export interface AuthConfig {
+  jwt: JwtConfig;
+  /** Cookie name for the session/access token. */
+  cookieName: string;
+  /** Cookie name for the refresh token. */
+  refreshCookieName: string;
+  google?: OAuthProviderConfig;
+  facebook?: OAuthProviderConfig;
+  /** Require email verification before login. */
+  requireEmailVerification: boolean;
+}
+
+export interface PaymentsProviderConfig {
+  enabled: boolean;
+  /** Sandbox/test mode. */
+  sandbox: boolean;
+  [key: string]: unknown;
+}
+
+export interface PaymentsConfig {
+  razorpay?: PaymentsProviderConfig;
+  paypal?: PaymentsProviderConfig;
+  payu?: PaymentsProviderConfig;
+  skrill?: PaymentsProviderConfig;
+  payoneer?: PaymentsProviderConfig;
+  /** Path on which payment webhooks are mounted, e.g. "/payments/webhook/:provider". */
+  webhookPath: string;
+  /** Default currency (ISO 4217). */
+  currency: string;
+}
+
+export interface EmailConfig {
+  provider: 'smtp' | 'log';
+  smtp?: {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+  };
+  from: string;
+}
+
+export interface CertsConfig {
+  /** Directory (relative to project root) where generated certs/keys are written. */
+  dir: string;
+  /** Default key type for new keypairs. */
+  keyType: 'rsa' | 'ec';
+  /** RSA key size in bits. */
+  rsaModulus: number;
+  /** EC curve name. */
+  ecCurve: 'prime256v1' | 'secp384r1' | 'secp521r1';
+  /** Self-signed cert validity in days. */
+  validityDays: number;
+}
+
+export interface AdsConfig {
+  enabled: boolean;
+  developerToken: string;
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+  customerId: string;
+}
+
+export interface WebRtcConfig {
+  /** mediasoup worker RTC listen IPs. */
+  rtcMinPort: number;
+  rtcMaxPort: number;
+  /** IP announced to clients (must be reachable from the browser). */
+  announceIp: string;
+}
+
+export interface GraphqlConfig {
+  /** Path on which GraphQL is mounted. */
+  path: string;
+  /** Federation mode: "in-process" (monolith) or "distributed" (HTTP subgraphs). */
+  federation: 'in-process' | 'distributed';
+  /** Enable GraphQL over WebSocket (subscriptions). */
+  subscriptions: boolean;
+  /** Introspection enabled (disable in production). */
+  introspection: boolean;
+}
+
+export interface WsConfig {
+  /** Path on which the WebSocket server listens. */
+  path: string;
+  /** Heartbeat ping interval in ms. */
+  heartbeatMs: number;
+  /** Require CSRF token + origin check on the WS upgrade. */
+  requireCsrf: boolean;
+}
+
+export interface AiProviderConfig {
+  /** Unique id for this provider (e.g. "openai", "ollama", "anthropic"). */
+  id: string;
+  /** Human-readable label. */
+  label: string;
+  /** API base URL the AI server should call. */
+  baseUrl: string;
+  /** Whether this provider is enabled (has a valid API key and is selectable). */
+  enabled: boolean;
+  /** API key stored in .env as NEXUS_AI_<ID>_API_KEY (never in config). */
+  apiKey?: string;
+  /** Default model for this provider. */
+  defaultModel?: string;
+}
+
+export interface AiConfig {
+  /** Python AI server base URL. */
+  serverUrl: string;
+  /** Request timeout in ms. */
+  timeoutMs: number;
+  /** Default provider: "openai" | "ollama" | "auto". */
+  defaultProvider: 'openai' | 'ollama' | 'auto';
+  /** Model used by the admin AI schema generator (e.g. "gpt-4o-mini"). */
+  schemaModel: string;
+  /** Configured AI providers with API keys + enable state. Optional —
+   *  defaults are provided in code. */
+  providers?: AiProviderConfig[];
+}
+
+export interface LoggingConfig {
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  /** "json" (machine) or "pretty" (colored, dev). */
+  format: 'json' | 'pretty';
+  /** Write logs to stdout in addition to file. */
+  console: boolean;
+  /** Directory for rotating log files. */
+  dir: string;
+  /** Max log file size in bytes before rotation. */
+  maxFileSize: number;
+  /** Number of rotated files to keep. */
+  maxFiles: number;
+}
+
+export interface PluginEntry {
+  /** Package or path to the plugin. */
+  path: string;
+  enabled: boolean;
+  /** Plugin-specific config. */
+  config?: Record<string, unknown>;
+}
+
+export interface PluginsConfig {
+  /** Directory holding local plugins. */
+  dir: string;
+  entries: PluginEntry[];
+}
+
+export interface FrontendConfig {
+  /** Vite dev server port. */
+  port: number;
+  /** Vite dev server bind host. "localhost" = loopback only, "0.0.0.0" = LAN. */
+  host: string;
+  /** Launch the frontend dev server under `nexus dev`. */
+  enabled: boolean;
+}
+
+export interface AdminConfig {
+  /** Vite dev server port for the admin app. */
+  port: number;
+  /** Vite dev server bind host. */
+  host: string;
+  /** Launch the admin dev server under `nexus dev`. */
+  enabled: boolean;
+}
+
+/** Node type — the service profile a node advertises and exposes. */
+export type NodeRole = 'backend' | 'files' | 'database' | 'ai';
+
+/** A registered remote node in the central registry. */
+export interface NodeInfo {
+  /** Stable node id (hostname-derived slug or caller-provided). */
+  id: string;
+  /** Base URL that reaches the node's agent, e.g. "https://node.example.com:7575". */
+  baseUrl: string;
+  /** The node's role profile. */
+  role: NodeRole;
+  /** Node reported version string. */
+  version?: string;
+  /** First successful registration time (ISO). */
+  registeredAt: string;
+  /** Last successful health/link time (ISO). */
+  lastSeenAt: string;
+  /** Last known metric sample. */
+  lastMetrics?: NodeMetrics;
+  /** Linked (discovered yet unverified) vs ready nodes. */
+  status: 'pending' | 'ready' | 'unreachable';
+}
+
+/** Rolling snapshot of a node's load, sampled by the central autoscaler. */
+export interface NodeMetrics {
+  /** Requests per second the node reports receiving (if role exposes it). */
+  rps: number;
+  /** CPU usage of the node process (0-100). */
+  cpu: number;
+  /** Memory usage of the node process in MiB. */
+  memoryMb: number;
+  /** Unix ms timestamp the sample was taken. */
+  sampledAt: number;
+}
+
+export interface ClusterAutoscaleConfig {
+  /** Enable the autoscaler entirely. */
+  enabled: boolean;
+  /** Scale decision mode: "auto" (deterministic + AI) or "manual". */
+  mode: 'auto' | 'manual';
+  /** Minimum number of backend nodes the LB keeps ready. */
+  minNodes: number;
+  /** Maximum number of backend nodes the LB may scale to. */
+  maxNodes: number;
+  /** Minimum wait (ms) between two autoscale decisions. */
+  cooldownMs: number;
+  /** CPU% at/above which the cluster considers a node overloaded. */
+  cpuHigh: number;
+  /** RPS per backend node at/above which the cluster scales up. */
+  rpsPerNodeHigh: number;
+  /** RPS per backend node below which the cluster scales down. */
+  rpsPerNodeLow: number;
+}
+
+export interface ClusterConfig {
+  /** Turn the cluster (registry + LB + autoscaler) on. */
+  enabled: boolean;
+  /** When false, the LB fails open to a single direct node (no scaling). */
+  failOpenSingleNode: boolean;
+  /** Bind address of the central cluster's public load balancer. */
+  lbHost: string;
+  /** Port of the central cluster's public load balancer. */
+  lbPort: number;
+  /** Bind address of the node agent's control API (per node side). */
+  nodeAgentHost: string;
+  /** Port of the node agent's control API (per node side). */
+  nodeAgentPort: number;
+  /** File path (relative to this config's root) for the persisted registry. */
+  registryFile: string;
+  /** Shared pairing secret minted at node setup; pasted into the central. */
+  token: string;
+  autoscale: ClusterAutoscaleConfig;
+}
+
+export interface NexusConfig {
+  env: Env;
+  server: ServerConfig;
+  uploads: UploadsConfig;
+  db: DbConfig;
+  redis: RedisConfig;
+  graphql: GraphqlConfig;
+  ws: WsConfig;
+  auth: AuthConfig;
+  payments: PaymentsConfig;
+  email: EmailConfig;
+  certs: CertsConfig;
+  ads: AdsConfig;
+  webrtc: WebRtcConfig;
+  ai: AiConfig;
+  logging: LoggingConfig;
+  plugins: PluginsConfig;
+  frontend: FrontendConfig;
+  admin: AdminConfig;
+  cluster: ClusterConfig;
+}
+
+/** Deep partial used for user config files and runtime overrides. */
+export type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export type UserNexusConfig = DeepPartial<NexusConfig>;

package/src/di/Container.ts

@@ -0,0 +1,98 @@
+/**
+ * A minimal inbuilt dependency-injection container.
+ *
+ * Supports factory-based registration (factories receive the container and any
+ * declared dependencies), singletons, and transient resolution. Intentionally
+ * small — this is the service backbone used by the framework and plugins.
+ */
+export type Factory<T> = (container: Container, ...deps: unknown[]) => T | Promise<T>;
+export type Lifetime = 'singleton' | 'transient';
+
+interface Registration<T = unknown> {
+  factory: Factory<T>;
+  lifetime: Lifetime;
+  deps: readonly string[];
+}
+
+export class Container {
+  private registrations = new Map<string, Registration>();
+  private singletons = new Map<string, unknown>();
+  private resolving = new Set<string>();
+
+  /** Register a service with explicit dependency ids. */
+  register<T>(
+    id: string,
+    factory: Factory<T>,
+    options: { lifetime?: Lifetime; deps?: readonly string[] } = {},
+  ): this {
+    this.registrations.set(id, {
+      factory,
+      lifetime: options.lifetime ?? 'singleton',
+      deps: options.deps ?? [],
+    });
+    return this;
+  }
+
+  /** Register an already-constructed value as a singleton. */
+  instance<T>(id: string, value: T): this {
+    this.singletons.set(id, value);
+    return this;
+  }
+
+  has(id: string): boolean {
+    return this.registrations.has(id) || this.singletons.has(id);
+  }
+
+  /** Resolve a service, throwing if it isn't registered. */
+  resolve<T>(id: string): T {
+    if (this.singletons.has(id)) return this.singletons.get(id) as T;
+
+    const reg = this.registrations.get(id);
+    if (!reg) throw new ResolutionError(id, `Service "${id}" is not registered.`);
+
+    if (this.resolving.has(id)) {
+      throw new ResolutionError(id, `Circular dependency detected while resolving "${id}".`);
+    }
+    this.resolving.add(id);
+    try {
+      const deps = reg.deps.map((d) => this.resolve(d));
+      const value = reg.factory(this, ...deps);
+      if (reg.lifetime === 'singleton') this.singletons.set(id, value);
+      return value as T;
+    } finally {
+      this.resolving.delete(id);
+    }
+  }
+
+  /** Resolve a possibly-async factory. */
+  async resolveAsync<T>(id: string): Promise<T> {
+    if (this.singletons.has(id)) return this.singletons.get(id) as T;
+    const value = this.resolve<unknown>(id);
+    const resolved = await Promise.resolve(value as T | Promise<T>);
+    if (this.registrations.get(id)?.lifetime === 'singleton') {
+      this.singletons.set(id, resolved);
+    }
+    return resolved as T;
+  }
+
+  child(): Container {
+    // A child container inherits registrations/values but can override locally.
+    const child = new Container();
+    for (const [id, value] of this.singletons) child.singletons.set(id, value);
+    for (const [id, reg] of this.registrations) child.registrations.set(id, reg);
+    return child;
+  }
+
+  clear(): void {
+    this.registrations.clear();
+    this.singletons.clear();
+    this.resolving.clear();
+  }
+}
+
+export class ResolutionError extends Error {
+  constructor(public readonly serviceId: string, message: string) {
+    super(message);
+    this.name = 'ResolutionError';
+  }
+}

package/src/di/index.ts

@@ -0,0 +1 @@
+export * from './Container.js';

package/src/errors.ts

@@ -0,0 +1,62 @@
+/** Framework-wide error base class with a stable `code` for programmatic handling. */
+export class NexusError extends Error {
+  code: string;
+  statusCode: number;
+  details?: unknown;
+  constructor(message: string, options: { code?: string; statusCode?: number; details?: unknown } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code ?? 'NEXUS_ERROR';
+    this.statusCode = options.statusCode ?? 500;
+    this.details = options.details;
+  }
+}
+
+export class ConfigError extends NexusError {
+  constructor(message: string, details?: unknown) {
+    super(message, { code: 'CONFIG_ERROR', statusCode: 500, details });
+  }
+}
+
+export class ValidationError extends NexusError {
+  constructor(message: string, details?: unknown) {
+    super(message, { code: 'VALIDATION_ERROR', statusCode: 400, details });
+  }
+}
+
+export class AuthenticationError extends NexusError {
+  constructor(message = 'Authentication required') {
+    super(message, { code: 'AUTHENTICATION_ERROR', statusCode: 401 });
+  }
+}
+
+export class AuthorizationError extends NexusError {
+  constructor(message = 'Insufficient permissions') {
+    super(message, { code: 'AUTHORIZATION_ERROR', statusCode: 403 });
+  }
+}
+
+export class NotFoundError extends NexusError {
+  constructor(message = 'Not found') {
+    super(message, { code: 'NOT_FOUND', statusCode: 404 });
+  }
+}
+
+export class ConflictError extends NexusError {
+  constructor(message: string, details?: unknown) {
+    super(message, { code: 'CONFLICT', statusCode: 409, details });
+  }
+}
+
+export class PaymentError extends NexusError {
+  constructor(message: string, details?: unknown) {
+    super(message, { code: 'PAYMENT_ERROR', statusCode: 402, details });
+  }
+}
+
+/** Normalize an unknown thrown value into a NexusError. */
+export function toNexusError(err: unknown): NexusError {
+  if (err instanceof NexusError) return err;
+  if (err instanceof Error) return new NexusError(err.message, { code: 'NEXUS_ERROR' });
+  return new NexusError(String(err));
+}