@bhooai/nexus-core 2.0.1 → 2.0.2

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.2",
+    "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,365 @@
+/**
+ * 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,
+ * read-only config, users, payments, and the AI proxy.
+ *
+ * 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 { Router } from '../http/Router.js';
+import type { RequestContext } from '../http/context.js';
+import { AiClient } from '@bhooai/nexus-ai-client';
+
+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?: 'openai' | 'ollama' | 'auto' };
+    if (!body?.messages) {
+      ctx.json({ ok: false, reason: 'messages is required' }, 400);
+      return;
+    }
+    try {
+      const res = await aiClient.chat({
+        model: body.model ?? config.ai.schemaModel,
+        messages: body.messages as never,
+        temperature: body.temperature,
+        max_tokens: body.max_tokens,
+        provider: body.provider,
+      });
+      ctx.json({ ok: true, ...res });
+    } catch (err) {
+      ctx.json({ ok: false, reason: String((err as Error).message) });
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+/** 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

@@ -30,6 +30,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 +229,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
   // ------------------------------------------------------------------
@@ -244,6 +255,26 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // 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';