@bhooai/nexus-core 2.0.1 → 2.0.3

package/package.json

@@ -1,28 +1,28 @@
 {
-    "name":  "@bhooai/nexus-core",
-    "version":  "2.0.1",
-    "publishConfig":  {
-                          "access":  "public"
-                      },
-    "type":  "module",
-    "main":  "./src/index.ts",
-    "types":  "./src/index.ts",
-    "exports":  {
-                    ".":  "./src/index.ts",
-                    "./config":  "./src/config/index.ts",
-                    "./di":  "./src/di/index.ts",
-                    "./http":  "./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"
-                        }
-}
+    "name": "@bhooai/nexus-core",
+    "version": "2.0.3",
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": "./src/index.ts",
+        "./config": "./src/config/index.ts",
+        "./di": "./src/di/index.ts",
+        "./http": "./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/app/adminModule.ts

@@ -0,0 +1,613 @@
+/**
+ * adminModule — framework-provided admin backend routes.
+ *
+ * Auto-mounted by `createNexusApp()` when `config.admin.enabled`. Serves the
+ * admin SPA's tabs: registry, health/services, per-app cards, request logs,
+ * config, users, payments, AI proxy, AI provider CRUD, and .env management.
+ *
+ * Routes:
+ *   GET    /admin/health/services          — TCP probes for infra services
+ *   GET    /admin/apps                     — registry + per-app /health probe
+ *   GET    /admin/logs/tail                — recent request logs
+ *   POST   /admin/logs/clear               — clear the log buffer
+ *   GET    /admin/config                   — read-only redacted config
+ *   PUT    /admin/config                   — write overrides to nexus.runtime.json
+ *   GET    /admin/env                      — read .env entries (values masked)
+ *   PUT    /admin/env                      — update .env entries (API keys etc)
+ *   GET    /admin/users                    — lazy Mongo
+ *   GET    /admin/payments                 — lazy Mongo
+ *   GET    /ai/models                      — proxy to Python AI server
+ *   POST   /ai/chat                        — proxy to Python AI server
+ *   GET    /admin/ai/status                — probe AI server + list providers
+ *   GET    /admin/ai/providers             — list configured providers (keys masked)
+ *   PUT    /admin/ai/providers/:id         — update a provider
+ *   POST   /admin/ai/providers             — add a custom provider
+ *   DELETE /admin/ai/providers/:id         — remove a provider + .env key
+ *   POST   /admin/ai/providers/:id/test    — probe provider connectivity
+ *
+ * All DB-backed routes are lazy: Mongo is only connected when a route is hit,
+ * so boot is never blocked and single-node apps without Mongo still work
+ * (endpoints return { ok: false, reason: '...' }).
+ */
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createConnection } from 'node:net';
+import { join, resolve } from 'node:path';
+import type { NexusConfig } from '../config/types.js';
+import type { AiProviderConfig } from '../config/types.js';
+import type { Router } from '../http/Router.js';
+import type { RequestContext } from '../http/context.js';
+import { AiClient } from '@bhooai/nexus-ai-client';
+import { readRuntimeJson, writeRuntimeJson, mergeRuntimeJson } from '../config/runtimeJson.js';
+import { readEnvFile, writeEnvEntries, writeEnvKey, deleteEnvKey } from '../config/envFile.js';
+
+export interface AdminModuleOptions {
+  name: string;
+  config: NexusConfig;
+  projectRoot: string;
+}
+
+export interface LazyDb {
+  /** Resolve a connected DB, or null if Mongo is unreachable. */
+  db(): Promise<import('mongodb').Db | null>;
+}
+
+/** A bounded in-memory request log entry. */
+export interface RequestLogEntry {
+  ts: number;
+  method: string;
+  path: string;
+  status: number;
+  latencyMs: number;
+}
+
+const MAX_LOG_ENTRIES = 1000;
+
+/** In-memory ring buffer of recent requests (source for /admin/logs/tail). */
+export class RequestLogBuffer {
+  private entries: RequestLogEntry[] = [];
+
+  push(entry: RequestLogEntry): void {
+    this.entries.push(entry);
+    if (this.entries.length > MAX_LOG_ENTRIES) {
+      this.entries.splice(0, this.entries.length - MAX_LOG_ENTRIES);
+    }
+  }
+
+  tail(lines: number, level?: string): RequestLogEntry[] {
+    const n = Math.min(Math.max(lines, 1), MAX_LOG_ENTRIES);
+    const slice = this.entries.slice(-n);
+    if (!level) return slice;
+    return slice.filter((e) => levelOf(e.status) === level);
+  }
+
+  clear(): void {
+    this.entries = [];
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+}
+
+function levelOf(status: number): string {
+  if (status >= 500) return 'error';
+  if (status >= 400) return 'warn';
+  return 'info';
+}
+
+/** Probe a TCP port with a short timeout. */
+function tcpReachable(host: string, port: number, timeoutMs = 1200): Promise<boolean> {
+  return new Promise((res) => {
+    const socket = createConnection({ host, port, timeout: timeoutMs });
+    socket.once('connect', () => { socket.end(); res(true); });
+    socket.once('error', () => res(false));
+    socket.once('timeout', () => { socket.destroy(); res(false); });
+  });
+}
+
+/** Register all admin + AI proxy routes onto the router. */
+export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, logBuffer: RequestLogBuffer, lazy: LazyDb): void {
+  const { config, projectRoot } = opts;
+
+  // ------------------------------------------------------------------
+  // /admin/health/services — TCP probes for infra services
+  // ------------------------------------------------------------------
+  router.get('/admin/health/services', async (ctx) => {
+    const mongoHost = hostOf(config.db.uri, 'localhost');
+    const mongoPort = portOf(config.db.uri, 27017);
+    const redisHost = hostOf(config.redis.url, 'localhost');
+    const redisPort = portOf(config.redis.url, 6379);
+    const aiPort = portOf(config.ai.serverUrl, 8000);
+
+    const [mongo, redis, ai] = await Promise.all([
+      tcpReachable(mongoHost, mongoPort),
+      tcpReachable(redisHost, redisPort),
+      tcpReachable('127.0.0.1', aiPort),
+    ]);
+
+    ctx.json({
+      services: [
+        { id: 'mongo', label: 'MongoDB', ok: mongo, detail: `${mongoHost}:${mongoPort}` },
+        { id: 'redis', label: 'Redis', ok: redis, detail: `${redisHost}:${redisPort}` },
+        { id: 'ai', label: 'AI server', ok: ai, detail: `127.0.0.1:${aiPort}` },
+        { id: 'storage', label: 'Storage', ok: true, detail: 'local disks configured' },
+      ],
+    });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/apps — registry + per-app /health probe
+  // ------------------------------------------------------------------
+  router.get('/admin/apps', async (ctx) => {
+    const registry = await readRegistry(projectRoot);
+    const apps = await Promise.all(
+      Object.entries(registry).map(async ([appName, port]) => {
+        const kind = kindOf(appName);
+        const probe = await probeHealth(port, kind);
+        return {
+          name: appName,
+          port,
+          healthy: probe.ok,
+          uptimeSec: probe.uptimeSec ?? null,
+          kind,
+        };
+      }),
+    );
+    ctx.json({ apps });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/logs/tail — recent request logs
+  // ------------------------------------------------------------------
+  router.get('/admin/logs/tail', (ctx) => {
+    const lines = parseInt(String(ctx.query.lines ?? '100'), 10) || 100;
+    const level = (ctx.query.level as string) || undefined;
+    ctx.json({ entries: logBuffer.tail(lines, level) });
+  });
+
+  router.post('/admin/logs/clear', (ctx) => {
+    logBuffer.clear();
+    ctx.json({ ok: true });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/config — read-only, redacted
+  // ------------------------------------------------------------------
+  router.get('/admin/config', (ctx) => {
+    ctx.json({ config: redactConfig(config) });
+  });
+
+  // ------------------------------------------------------------------
+  // /admin/users + /admin/payments — lazy Mongo
+  // ------------------------------------------------------------------
+  router.get('/admin/users', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) {
+      ctx.json({ ok: false, reason: 'MongoDB not reachable' });
+      return;
+    }
+    try {
+      const users = await db.collection('users').find({}).sort({ createdAt: -1 }).limit(200).toArray();
+      ctx.json({
+        ok: true,
+        users: users.map((u) => ({
+          id: String(u._id),
+          email: u.email,
+          name: u.name,
+          roles: u.roles ?? ['user'],
+          createdAt: u.createdAt,
+        })),
+      });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+
+  router.get('/admin/payments', async (ctx) => {
+    const db = await lazy.db();
+    if (!db) {
+      ctx.json({ ok: false, reason: 'MongoDB not reachable' });
+      return;
+    }
+    try {
+      const orders = await db.collection('orders').find({}).sort({ createdAt: -1 }).limit(50).toArray();
+      ctx.json({
+        ok: true,
+        orders: orders.map((o) => ({
+          id: String(o._id),
+          userId: o.userId,
+          provider: o.provider,
+          amount: o.amount,
+          currency: o.currency,
+          status: o.status,
+          createdAt: o.createdAt,
+        })),
+        providers: providerStatus(config),
+      });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // /ai/* — proxy to the Python AI server via AiClient
+  // ------------------------------------------------------------------
+  const aiClient = new AiClient({
+    serverUrl: config.ai.serverUrl,
+    timeoutMs: config.ai.timeoutMs,
+  });
+
+  router.get('/ai/models', async (ctx) => {
+    try {
+      const models = await aiClient.listModels();
+      ctx.json({ ok: true, models });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+
+  router.post('/ai/chat', async (ctx) => {
+    const body = ctx.body as { model?: string; messages?: unknown[]; temperature?: number; max_tokens?: number; provider?: string };
+    if (!body?.messages) {
+      ctx.json({ ok: false, reason: 'messages is required' }, 400);
+      return;
+    }
+    try {
+      const providerId = body.provider ?? config.ai.defaultProvider;
+      const provider = providers.find((p) => p.id === providerId);
+      const defaultModel = provider?.defaultModel ?? config.ai.schemaModel;
+      const res = await aiClient.chat({
+        model: body.model ?? defaultModel,
+        messages: body.messages as never,
+        temperature: body.temperature,
+        max_tokens: body.max_tokens,
+        provider: providerId,
+      });
+      ctx.json({ ok: true, ...res });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // AI provider management
+  // ------------------------------------------------------------------
+
+  // Mutable providers array — shared across routes, updated in-place.
+  const providers: AiProviderConfig[] = config.ai.providers ? [...config.ai.providers] : [];
+
+  // On boot, load any persisted API keys from .env into the in-memory providers.
+  for (const p of providers) {
+    const envKey = providerEnvKey(p.id);
+    const envVal = process.env[envKey];
+    if (envVal) p.apiKey = envVal;
+  }
+
+  /** Persist providers (sans API keys) to nexus.runtime.json. */
+  const persistProviders = async (): Promise<void> => {
+    try {
+      const existing = await readRuntimeJson(projectRoot);
+      const ai = (existing.ai ?? {}) as Record<string, unknown>;
+      ai.providers = providers.map((p) => ({
+        id: p.id, label: p.label, baseUrl: p.baseUrl,
+        enabled: p.enabled,
+        ...(p.defaultModel ? { defaultModel: p.defaultModel } : {}),
+      }));
+      existing.ai = ai;
+      await writeRuntimeJson(projectRoot, existing);
+    } catch { /* non-fatal */ }
+  };
+
+  /** GET /admin/ai/providers — list all configured providers (keys masked). */
+  router.get('/admin/ai/providers', async (ctx) => {
+    ctx.json({
+      providers: providers.map((p) => ({
+        ...p,
+        apiKey: p.apiKey ? '••••••••' : '',
+        hasApiKey: !!p.apiKey,
+      })),
+    });
+  });
+
+  /** GET /admin/ai/status — probe the Python AI server + per-provider health. */
+  router.get('/admin/ai/status', async (ctx) => {
+    const probe = async <T>(fn: () => Promise<T>): Promise<{ ok: boolean; error?: string; detail?: T }> => {
+      try {
+        return { ok: true, detail: await fn() };
+      } catch (e) {
+        return { ok: false, error: (e as Error).message || 'unknown error' };
+      }
+    };
+
+    // Probe the Python AI server
+    const aiServer = await probe(async () => {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 10_000);
+      try {
+        const res = await fetch(`${config.ai.serverUrl.replace(/\/+$/, '')}/health`, { signal: ctrl.signal });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return (await res.json()) as { status?: string; providers?: string[] };
+      } finally { clearTimeout(timer); }
+    });
+
+    ctx.json({
+      checkedAt: new Date().toISOString(),
+      aiServer,
+      defaultProvider: config.ai.defaultProvider,
+      schemaModel: config.ai.schemaModel,
+      serverUrl: config.ai.serverUrl,
+      timeoutMs: config.ai.timeoutMs,
+    });
+  });
+
+  /** PUT /admin/ai/providers/:id — update a provider. */
+  router.put('/admin/ai/providers/:id', async (ctx) => {
+    const id = ctx.params.id ?? '';
+    const body = (ctx.body ?? {}) as Record<string, unknown>;
+    const provider = providers.find((p) => p.id === id);
+    if (!provider) { ctx.json({ error: `provider "${id}" not found` }, 404); return; }
+    if (typeof body.enabled === 'boolean') provider.enabled = body.enabled;
+    if (typeof body.defaultModel === 'string' && body.defaultModel.trim()) provider.defaultModel = body.defaultModel.trim();
+    if (typeof body.label === 'string' && body.label.trim()) provider.label = body.label.trim();
+    if (typeof body.baseUrl === 'string' && body.baseUrl.trim()) provider.baseUrl = body.baseUrl.trim();
+    const newKey = typeof body.apiKey === 'string' ? body.apiKey : undefined;
+    if (newKey && newKey !== '••••••••') {
+      provider.apiKey = newKey;
+      try {
+        await writeEnvKey(projectRoot, providerEnvKey(id), newKey);
+        process.env[providerEnvKey(id)] = newKey;
+      } catch { /* non-fatal — in-memory key still works */ }
+    }
+    await persistProviders();
+    ctx.json({
+      ok: true,
+      provider: { ...provider, apiKey: provider.apiKey ? '••••••••' : '', hasApiKey: !!provider.apiKey },
+    });
+  });
+
+  /** POST /admin/ai/providers — add a custom provider. */
+  router.post('/admin/ai/providers', async (ctx) => {
+    const body = (ctx.body ?? {}) as Record<string, unknown>;
+    const id = typeof body.id === 'string' ? body.id.trim().toLowerCase() : '';
+    const label = typeof body.label === 'string' ? body.label.trim() : '';
+    const baseUrl = typeof body.baseUrl === 'string' ? body.baseUrl.trim() : '';
+    if (!id || !label || !baseUrl) { ctx.json({ error: 'id, label and baseUrl are required' }, 400); return; }
+    if (providers.find((p) => p.id === id)) { ctx.json({ error: `provider "${id}" already exists` }, 409); return; }
+    const apiKey = typeof body.apiKey === 'string' && body.apiKey ? body.apiKey : undefined;
+    const provider: AiProviderConfig = {
+      id, label, baseUrl,
+      enabled: typeof body.enabled === 'boolean' ? body.enabled : true,
+      apiKey,
+      defaultModel: typeof body.defaultModel === 'string' && body.defaultModel.trim() ? body.defaultModel.trim() : undefined,
+    };
+    providers.push(provider);
+    if (apiKey) {
+      try {
+        await writeEnvKey(projectRoot, providerEnvKey(id), apiKey);
+        process.env[providerEnvKey(id)] = apiKey;
+      } catch { /* non-fatal */ }
+    }
+    await persistProviders();
+    ctx.json({
+      ok: true,
+      provider: { ...provider, apiKey: provider.apiKey ? '••••••••' : '', hasApiKey: !!provider.apiKey },
+    });
+  });
+
+  /** DELETE /admin/ai/providers/:id — remove a provider + its .env key. */
+  router.delete('/admin/ai/providers/:id', async (ctx) => {
+    const id = ctx.params.id ?? '';
+    const idx = providers.findIndex((p) => p.id === id);
+    if (idx === -1) { ctx.json({ error: `provider "${id}" not found` }, 404); return; }
+    providers.splice(idx, 1);
+    try { await deleteEnvKey(projectRoot, providerEnvKey(id)); } catch { /* non-fatal */ }
+    await persistProviders();
+    ctx.json({ ok: true });
+  });
+
+  /** POST /admin/ai/providers/:id/test — probe a single provider's connectivity. */
+  router.post('/admin/ai/providers/:id/test', async (ctx) => {
+    const id = ctx.params.id ?? '';
+    const provider = providers.find((p) => p.id === id);
+    if (!provider) { ctx.json({ error: `provider "${id}" not found` }, 404); return; }
+    try {
+      const client = new AiClient({ serverUrl: config.ai.serverUrl, timeoutMs: 8_000 });
+      const res = await client.listModels(id);
+      const models = (res.data ?? []).map((m) => String(m.id ?? m)).slice(0, 20);
+      ctx.json({
+        ok: true,
+        provider: id,
+        modelCount: (res.data ?? []).length,
+        models,
+        checkedAt: new Date().toISOString(),
+      });
+    } catch (e) {
+      ctx.json({
+        ok: false,
+        provider: id,
+        error: (e as Error).message || 'unknown error',
+        checkedAt: new Date().toISOString(),
+      });
+    }
+  });
+
+  // ------------------------------------------------------------------
+  // Config write-back + .env management
+  // ------------------------------------------------------------------
+
+  /** PUT /admin/config — write DeepPartial overrides to nexus.runtime.json. */
+  router.put('/admin/config', async (ctx) => {
+    const patch = (ctx.body ?? {}) as Record<string, unknown>;
+    if (!patch || typeof patch !== 'object') {
+      ctx.json({ error: 'request body must be a JSON object' }, 400);
+      return;
+    }
+    try {
+      await mergeRuntimeJson(projectRoot, patch);
+      ctx.json({ ok: true });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) }, 500);
+    }
+  });
+
+  /** GET /admin/env — read .env entries (values masked). */
+  router.get('/admin/env', async (ctx) => {
+    try {
+      const entries = await readEnvFile(projectRoot, true);
+      ctx.json({ ok: true, entries });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+
+  /** PUT /admin/env — update .env entries (API keys etc). */
+  router.put('/admin/env', async (ctx) => {
+    const body = (ctx.body ?? {}) as Record<string, unknown>;
+    const entries = body.entries;
+    if (!Array.isArray(entries)) {
+      ctx.json({ error: 'entries (array of {key, value}) is required' }, 400);
+      return;
+    }
+    try {
+      // Filter out masked values — don't write •••••••• back to .env
+      const toWrite = (entries as Array<Record<string, unknown>>)
+        .filter((e) => typeof e.key === 'string' && typeof e.value === 'string' && e.value !== '••••••••')
+        .map((e) => ({ key: e.key as string, value: e.value as string }));
+      if (toWrite.length > 0) {
+        await writeEnvEntries(projectRoot, toWrite);
+        // Also update process.env so changes are live
+        for (const { key, value } of toWrite) {
+          process.env[key] = value;
+        }
+      }
+      ctx.json({ ok: true, updated: toWrite.length });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) }, 500);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function kindOf(appName: string): string {
+  if (appName.startsWith('backend')) return 'backend';
+  if (appName.startsWith('frontend')) return 'frontend';
+  if (appName.startsWith('admin')) return 'admin';
+  return 'other';
+}
+
+/**
+ * Probe a registered app's liveness.
+ *
+ * Backend / ai-server / other apps expose a JSON /health with `{ ok: true }`.
+ * Frontend and admin are Vite SPAs — they return HTML for any path (history
+ * fallback), so a bare 200 on `/` means the dev server is up.
+ */
+async function probeHealth(port: number, kind: string): Promise<{ ok: boolean; uptimeSec?: number }> {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    const isSpa = kind === 'frontend' || kind === 'admin';
+    const path = isSpa ? '/' : '/health';
+    const res = await fetch(`http://127.0.0.1:${port}${path}`, { signal: controller.signal });
+    clearTimeout(timer);
+    if (isSpa) return { ok: res.ok };
+    const data = (await res.json()) as { ok?: boolean };
+    return { ok: !!data.ok };
+  } catch {
+    return { ok: false };
+  }
+}
+
+async function readRegistry(projectRoot: string): Promise<Record<string, number>> {
+  const p = resolve(projectRoot, '.nexus-ports.json');
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(await readFile(p, 'utf-8')) as Record<string, number>;
+  } catch {
+    return {};
+  }
+}
+
+function hostOf(uri: string, fallback: string): string {
+  try {
+    const u = new URL(uri);
+    return u.hostname || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function portOf(uri: string, fallback: number): number {
+  try {
+    const u = new URL(uri);
+    return u.port ? parseInt(u.port, 10) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/** Deep-clone config, masking secret-ish fields. */
+function redactConfig(config: NexusConfig): Record<string, unknown> {
+  const clone = JSON.parse(JSON.stringify(config)) as Record<string, unknown>;
+  redact(clone, /(secret|token|clientsecret|apikey|keyid|password|pass|refresh)/i);
+  return clone;
+}
+
+function redact(obj: unknown, pattern: RegExp): void {
+  if (!obj || typeof obj !== 'object') return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) redact(item, pattern);
+    return;
+  }
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === 'string' && pattern.test(k)) {
+      (obj as Record<string, unknown>)[k] = '••••••••';
+    } else if (v && typeof v === 'object') {
+      redact(v, pattern);
+    }
+  }
+}
+
+function providerStatus(config: NexusConfig): Array<{ id: string; enabled: boolean; sandbox: boolean }> {
+  const p = config.payments as unknown as Record<string, unknown>;
+  const out: Array<{ id: string; enabled: boolean; sandbox: boolean }> = [];
+  for (const [id, val] of Object.entries(p)) {
+    if (typeof val === 'object' && val !== null) {
+      const v = val as { enabled?: boolean; sandbox?: boolean };
+      if (typeof v.enabled === 'boolean') {
+        out.push({ id, enabled: v.enabled, sandbox: !!v.sandbox });
+      }
+    }
+  }
+  return out;
+}
+
+/** Env var name for a provider's API key (e.g. "together" → "NEXUS_AI_TOGETHER_API_KEY"). */
+function providerEnvKey(providerId: string): string {
+  return `NEXUS_AI_${providerId.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_API_KEY`;
+}
+
+/** Convenience for wiring: create a lazy Mongo db resolver from a config. */
+export function createLazyDb(config: NexusConfig): LazyDb {
+  let cached: import('mongodb').Db | null | undefined;
+  return {
+    async db() {
+      if (cached !== undefined) return cached;
+      try {
+        const { connect } = await import('@bhooai/nexus-data');
+        const connection = connect(config.db.uri, { maxPoolSize: 2 });
+        cached = await connection.db;
+        return cached;
+      } catch (err) {
+        cached = null;
+        return null;
+      }
+    },
+  };
+}
+
+export type { RequestContext };

package/src/app/createNexusApp.ts

@@ -19,6 +19,7 @@ import { loadConfigAuto, type NexusConfig } from '../config/index.js';
 import { Container } from '../di/Container.js';
 import { Router } from '../http/Router.js';
 import { NexusServer } from '../http/Server.js';
+import { bodyParser } from '../http/bodyParser.js';
 import type { Handler, Middleware } from '../http/context.js';
 import { discoverBackend, importDefault, type DiscoveryResult } from './discover.js';
 import type { RoutesFile, RouteDef } from './defineRoutes.js';
@@ -30,6 +31,7 @@ import { configureMailDriver, configureMailRenderer, logMailDriver } from './Mai
 import { policyRegistry } from './policies.js';
 import { configureStorageFromEnv } from './Storage.js';
 import { maintenanceMiddleware } from './maintenance.js';
+import { createLazyDb, registerAdminRoutes, RequestLogBuffer } from './adminModule.js';
 
 export interface CreateNexusAppOptions {
   /** Identifier for this backend, used in admin, telemetry, logs. */
@@ -228,6 +230,16 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     ctx.json({ apps });
   });
 
+  // ------------------------------------------------------------------
+  // Admin module — request log buffer, lazy DB, admin + AI proxy routes
+  // ------------------------------------------------------------------
+  const logBuffer = new RequestLogBuffer();
+  const lazyDb = createLazyDb(config);
+
+  if (config.admin.enabled) {
+    registerAdminRoutes(router, { name, config, projectRoot }, logBuffer, lazyDb);
+  }
+
   // ------------------------------------------------------------------
   // HTTP server with error handler + maintenance middleware wired in
   // ------------------------------------------------------------------
@@ -241,9 +253,33 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     onError: (err, ctx) => errorHandler.toApiError(err),
   });
 
+  // Body parsing (JSON / urlencoded / multipart) — before everything else so
+  // POST/PUT/PATCH handlers see ctx.body.
+  server.use(bodyParser(config.server.bodyLimit));
+
   // Maintenance mode (checked first)
   server.use(maintenanceMiddleware({ projectRoot }));
 
+  // Request logging into the ring buffer (source for /admin/logs/tail).
+  server.use(async (ctx, next) => {
+    const start = performance.now();
+    const res = ctx.res;
+    const originalEnd = res.end.bind(res);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (res as any).end = (...args: any[]) => {
+      const latencyMs = Math.round(performance.now() - start);
+      logBuffer.push({
+        ts: Date.now(),
+        method: ctx.method,
+        path: ctx.path,
+        status: res.statusCode,
+        latencyMs,
+      });
+      return originalEnd(...args);
+    };
+    await next();
+  });
+
   // User-supplied global middleware
   for (const mw of opts.middleware ?? []) server.use(mw);
 

package/src/app/index.ts

@@ -12,3 +12,4 @@ export * from './ErrorHandler.js';
 export * from './Seeder.js';
 export * from './Storage.js';
 export * from './maintenance.js';
+export * from './adminModule.js';

package/src/config/defaults.ts

@@ -85,10 +85,10 @@ export const defaults: NexusConfig = {
   ai: {
     serverUrl: 'http://localhost:8000',
     timeoutMs: 60_000,
-    defaultProvider: 'auto',
-    schemaModel: 'gpt-4o-mini',
+    defaultProvider: 'ollama',
+    schemaModel: 'llama3.1:8b',
     providers: [
-      { id: 'ollama', label: 'Ollama (local)', baseUrl: 'http://localhost:11434', enabled: true, defaultModel: 'llama3:latest' },
+      { id: 'ollama', label: 'Ollama (local)', baseUrl: 'http://localhost:11434', enabled: true, defaultModel: 'llama3.1:8b' },
       { 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' },

package/src/config/envFile.ts

@@ -0,0 +1,112 @@
+/**
+ * Read / write helpers for `.env` files.
+ *
+ * Used by the admin API to let users manage AI provider API keys and other
+ * secrets without touching the source config file.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, rename } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export interface EnvEntry {
+  key: string;
+  /** The raw value.  When returned from `readEnvFile` in "masked" mode the
+   *  value is replaced with `••••••••`. */
+  value: string;
+  /** Whether the value was masked (never true on write). */
+  masked?: boolean;
+}
+
+/**
+ * Read all key=value pairs from the project's `.env` file.
+ *
+ * When `masked` is true, values that look like secrets (contain >4 chars and
+ * match common patterns) are replaced with `••••••••`.
+ */
+export async function readEnvFile(projectRoot: string, masked = true): Promise<EnvEntry[]> {
+  const p = resolve(projectRoot, '.env');
+  if (!existsSync(p)) return [];
+  const content = await readFile(p, 'utf8');
+  return content.split(/\r?\n/).reduce<EnvEntry[]>((acc, line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return acc;
+    // Strip optional `export ` prefix
+    const clean = trimmed.replace(/^export\s+/, '');
+    const eq = clean.indexOf('=');
+    if (eq === -1) return acc;
+    const key = clean.slice(0, eq).trim();
+    let value = clean.slice(eq + 1).trim();
+    // Strip surrounding quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    const isSecret = masked && looksLikeSecret(key) && value.length > 0;
+    acc.push({ key, value: isSecret ? '••••••••' : value, masked: isSecret });
+    return acc;
+  }, []);
+}
+
+/** Write (add or update) entries in the `.env` file. */
+export async function writeEnvEntries(projectRoot: string, updates: EnvEntry[]): Promise<void> {
+  const p = resolve(projectRoot, '.env');
+  const lines = existsSync(p) ? (await readFile(p, 'utf8')).split(/\r?\n/) : [];
+
+  for (const { key, value } of updates) {
+    const regex = new RegExp(`^(\\s*export\\s+)?${escapeRegex(key)}\\s*=`);
+    let found = false;
+    for (let i = 0; i < lines.length; i++) {
+      if (regex.test(lines[i]!)) {
+        lines[i] = `${key}=${value}`;
+        found = true;
+        break;
+      }
+    }
+    if (!found) {
+      // Append before trailing empty line, or at end
+      if (lines.length > 0 && lines[lines.length - 1] === '') {
+        lines.splice(lines.length - 1, 0, `${key}=${value}`);
+      } else {
+        lines.push(`${key}=${value}`);
+      }
+    }
+  }
+
+  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, `${lines.join('\n')}\n`, 'utf8');
+  try {
+    await rename(tmp, p);
+  } catch {
+    // Fallback: write directly
+    await writeFile(p, `${lines.join('\n')}\n`, 'utf8');
+  }
+}
+
+/** Delete a key from the `.env` file. */
+export async function deleteEnvKey(projectRoot: string, key: string): Promise<void> {
+  const p = resolve(projectRoot, '.env');
+  if (!existsSync(p)) return;
+  const content = await readFile(p, 'utf8');
+  const regex = new RegExp(`^(\\s*export\\s+)?${escapeRegex(key)}\\s*=`);
+  const output = content.split(/\r?\n/).filter((line) => !regex.test(line));
+  if (output.length === content.split(/\r?\n/).length) return; // nothing removed
+  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, `${output.join('\n')}\n`, 'utf8');
+  try {
+    await rename(tmp, p);
+  } catch {
+    await writeFile(p, `${output.join('\n')}\n`, 'utf8');
+  }
+}
+
+/** Write a single env key=value (convenience wrapper). */
+export async function writeEnvKey(projectRoot: string, key: string, value: string): Promise<void> {
+  return writeEnvEntries(projectRoot, [{ key, value }]);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function looksLikeSecret(key: string): boolean {
+  return /(secret|token|apikey|key|password|credential)/i.test(key);
+}

package/src/config/runtimeJson.ts

@@ -0,0 +1,55 @@
+/**
+ * Read / write helpers for `nexus.runtime.json`.
+ *
+ * The runtime file stores DeepPartial config overrides that survive restarts
+ * without touching the human-authored `nexus.config.ts`.  API keys are NEVER
+ * written here — they live in `.env`.
+ */
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const FILENAME = 'nexus.runtime.json';
+
+export function runtimePath(projectRoot: string): string {
+  return join(projectRoot, FILENAME);
+}
+
+export async function readRuntimeJson(projectRoot: string): Promise<Record<string, unknown>> {
+  const p = runtimePath(projectRoot);
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(await readFile(p, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeRuntimeJson(projectRoot: string, data: Record<string, unknown>): Promise<void> {
+  const p = runtimePath(projectRoot);
+  const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  try {
+    await rename(tmp, p);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'EEXIST' && code !== 'EPERM') throw err;
+    await unlink(p).catch(() => undefined);
+    await rename(tmp, p);
+  }
+}
+
+/**
+ * Merge a partial update into the runtime JSON (deep merge on `ai.providers`,
+ * shallow merge everywhere else).
+ */
+export async function mergeRuntimeJson(projectRoot: string, patch: Record<string, unknown>): Promise<void> {
+  const existing = await readRuntimeJson(projectRoot);
+  const merged = { ...existing, ...patch };
+  // If both have ai.providers, prefer the patch's value (caller controls the
+  // full array).  If patch only has other ai fields, spread them.
+  if (patch.ai && typeof patch.ai === 'object' && existing.ai && typeof existing.ai === 'object') {
+    merged.ai = { ...(existing as { ai: Record<string, unknown> }).ai, ...(patch.ai as Record<string, unknown>) };
+  }
+  await writeRuntimeJson(projectRoot, merged);
+}