@bhooai/nexus-core 2.0.13 → 2.0.16

package/src/app/authModule.ts

@@ -44,11 +44,18 @@ import {
   type FacebookOAuthConfig,
 } from '@bhooai/nexus-auth';
 import { ConflictError, AuthenticationError, ValidationError } from '../index.js';
-import { ObjectId } from '@bhooai/nexus-data';
-import { initUserModel, getUserModel, findUserForLogin, upsertOAuthUser, type UserInstance } from './userModel.js';
+import { getUserStore, type StoredUser } from './userStore.js';
 
-const sessions = new MemorySessionStore();
-const oauthState = new MemoryOAuthStateStore();
+let sessions: InstanceType<typeof MemorySessionStore> | undefined;
+let oauthState: InstanceType<typeof MemoryOAuthStateStore> | undefined;
+function getSessions() {
+  if (!sessions) sessions = new MemorySessionStore();
+  return sessions;
+}
+function getOauthState() {
+  if (!oauthState) oauthState = new MemoryOAuthStateStore();
+  return oauthState;
+}
 
 function origin(config: NexusConfig): string {
   const proto = config.server.https ? 'https' : 'http';
@@ -67,12 +74,13 @@ function jwtOptions(config: NexusConfig) {
 }
 
 function authService(config: NexusConfig): AuthService {
-  return new AuthService(jwtOptions(config), sessions);
+  return new AuthService(jwtOptions(config), getSessions());
 }
 
-/** Register /auth/* routes onto the given router. Call after `connect()` + `initUserModel()`. */
+/** Register /auth/* routes onto the given router. The user store is initialized
+ *  by `createNexusApp()` (or lazily falls back to Mongo on first use). */
 export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCreated?: () => void): AuthService {
-  initUserModel();
+  const users = getUserStore();
   const service = authService(config);
 
   // POST /auth/register
@@ -81,18 +89,17 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
     if (!body.email || !body.password) throw new ValidationError('email and password are required');
     if (body.password.length < 8) throw new ValidationError('password must be at least 8 characters');
 
-    const User = getUserModel();
-    const existing = await User.findOne({ email: body.email.toLowerCase() }).lean();
+    const existing = await users.findByEmail(body.email);
     if (existing) throw new ConflictError('A user with that email already exists');
 
     const passwordHash = await hashPassword(body.password);
     // Bootstrap: the very first registered user becomes an admin.
-    const userCount = await User.countDocuments();
+    const userCount = await users.count();
     const roles = userCount === 0 ? ['admin'] : ['user'];
-    const [user] = await User.create({ email: body.email, name: body.name, passwordHash, roles });
+    const user = await users.create({ email: body.email, name: body.name, passwordHash, roles });
     // Notify subscribers (e.g. a GraphQL `userCount` subscription) if wired.
     onUserCreated?.();
-    const pair = await service.login({ userId: String((user as UserInstance)._id), roles: (user as UserInstance).roles, meta: { ip: ctx.req.socket.remoteAddress } });
+    const pair = await service.login({ userId: String(user._id), roles: user.roles, meta: { ip: ctx.req.socket.remoteAddress } });
     setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
     ctx.json({ user: publicUser(user), accessToken: pair.accessToken, refreshToken: pair.refreshToken });
   });
@@ -101,7 +108,7 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
   router.post('/auth/login', async (ctx) => {
     const body = (ctx.body ?? {}) as { email?: string; password?: string };
     if (!body.email || !body.password) throw new ValidationError('email and password are required');
-    const user = await findUserForLogin(body.email);
+    const user = await users.findForLogin(body.email);
     if (!user || !user.passwordHash) throw new AuthenticationError('Invalid email or password');
     const ok = await verifyPassword(body.password, user.passwordHash);
     if (!ok) throw new AuthenticationError('Invalid email or password');
@@ -132,9 +139,8 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
 
   // GET /auth/me
   router.get('/auth/me', async (ctx) => {
-    const User = getUserModel();
     const id = (ctx.state.user as { id: string }).id;
-    const user = await User.findById(id).lean();
+    const user = await users.findById(id);
     ctx.json({ user: publicUser(user) });
   }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
 
@@ -144,9 +150,7 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
     const name = typeof body.name === 'string' ? body.name.trim() : '';
     if (!name) throw new ValidationError('name is required');
     const id = (ctx.state.user as { id: string }).id;
-    const User = getUserModel();
-    await User.updateOne({ _id: id }, { $set: { name } });
-    const user = await User.findById(id).lean();
+    const user = await users.setName(id, name);
     ctx.json({ ok: true, user: publicUser(user) });
   }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
 
@@ -157,16 +161,12 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
     if (!body.newPassword || body.newPassword.length < 8) throw new ValidationError('password must be at least 8 characters');
 
     const id = (ctx.state.user as { id: string }).id;
-    const User = getUserModel();
-    const coll = await User.collection;
-    const raw = await coll.findOne({ _id: new ObjectId(id) });
-    if (!raw) throw new AuthenticationError('User not found');
-    const passwordHash = raw.passwordHash as string | undefined;
+    const passwordHash = await users.findPasswordHash(id);
     if (!passwordHash) throw new AuthenticationError('This account has no password (OAuth account)');
     const ok = await verifyPassword(body.currentPassword, passwordHash);
     if (!ok) throw new AuthenticationError('Current password is incorrect');
     const nextHash = await hashPassword(body.newPassword);
-    await User.updateOne({ _id: id }, { $set: { passwordHash: nextHash } });
+    await users.setPassword(id, nextHash);
     ctx.json({ ok: true });
   }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
 
@@ -181,18 +181,18 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
     router.get('/auth/google', async (ctx) => {
       const state = generateState();
       const verifier = generatePkceVerifier();
-      await oauthState.set(state, { provider: 'google', verifier }, 5 * 60_000);
+      await getOauthState().set(state, { provider: 'google', verifier }, 5 * 60_000);
       ctx.redirect(buildGoogleAuthUrl(google, { state, verifier }));
     });
     router.get(config.auth.google.callbackPath, async (ctx) => {
       const code = ctx.query.code as string | undefined;
       const state = ctx.query.state as string | undefined;
       if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
-      const data = await oauthState.consume(state);
+      const data = await getOauthState().consume(state);
       if (!data || data.provider !== 'google') throw new AuthenticationError('Invalid OAuth state');
       const tokens = await exchangeGoogleCode(code, google, data.verifier as string);
       const profile = await fetchGoogleProfile(tokens.accessToken);
-      const user = await upsertOAuthUser({ provider: 'google', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const user = await upsertOAuthUser(users, { provider: 'google', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
       const pair = await service.login({ userId: String(user._id), roles: user.roles });
       setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
       ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
@@ -209,18 +209,18 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
     };
     router.get('/auth/facebook', async (ctx) => {
       const state = generateState();
-      await oauthState.set(state, { provider: 'facebook' }, 5 * 60_000);
+      await getOauthState().set(state, { provider: 'facebook' }, 5 * 60_000);
       ctx.redirect(buildFacebookAuthUrl(facebook, state));
     });
     router.get(config.auth.facebook.callbackPath, async (ctx) => {
       const code = ctx.query.code as string | undefined;
       const state = ctx.query.state as string | undefined;
       if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
-      const data = await oauthState.consume(state);
+      const data = await getOauthState().consume(state);
       if (!data || data.provider !== 'facebook') throw new AuthenticationError('Invalid OAuth state');
       const tokens = await exchangeFacebookCode(code, facebook);
       const profile = await fetchFacebookProfile(tokens.accessToken);
-      const user = await upsertOAuthUser({ provider: 'facebook', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const user = await upsertOAuthUser(users, { provider: 'facebook', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
       const pair = await service.login({ userId: String(user._id), roles: user.roles });
       setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
       ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
@@ -230,6 +230,32 @@ export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCr
   return service;
 }
 
+/** Find-or-create a user from an OAuth profile (account linking by provider+id). */
+async function upsertOAuthUser(
+  users: ReturnType<typeof getUserStore>,
+  profile: { provider: string; providerUserId: string; email?: string; name?: string },
+): Promise<StoredUser> {
+  const existing = await users.findOAuthUser(profile.provider, profile.providerUserId);
+  if (existing) return existing;
+
+  // Link to an existing email account if present, else create a new one.
+  if (profile.email) {
+    const byEmail = await users.findByEmail(profile.email);
+    if (byEmail) {
+      const linked = await users.linkOAuth(String(byEmail._id), profile.provider, profile.providerUserId);
+      if (linked) return linked;
+    }
+  }
+
+  return users.create({
+    email: profile.email ?? `${profile.provider}-${profile.providerUserId}@oauth.local`,
+    name: profile.name,
+    emailVerified: true,
+    oauthAccounts: [{ provider: profile.provider, providerUserId: profile.providerUserId }],
+    roles: ['user'],
+  });
+}
+
 function publicUser(user: unknown): Record<string, unknown> | null {
   if (!user) return null;
   // DocumentInstance → use toObject() (avoids spreading the Proxy and its circular _model).

package/src/app/createNexusApp.ts

@@ -15,7 +15,7 @@
 import { existsSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
-import { loadConfigAuto, type NexusConfig } from '../config/index.js';
+import { loadConfigAuto, activeDatabase, mongoEnabled, mongoUri, fusionEnabled, type NexusConfig } from '../config/index.js';
 import { Container } from '../di/Container.js';
 import { Router } from '../http/Router.js';
 import { NexusServer } from '../http/Server.js';
@@ -25,6 +25,10 @@ import { discoverBackend, importDefault, type DiscoveryResult } from './discover
 import type { RoutesFile, RouteDef } from './defineRoutes.js';
 import { DefaultErrorHandler, ErrorHandler } from './ErrorHandler.js';
 import { ErrorPages } from './errorPages.js';
+import { ConfigError, NotFoundError, toNexusError } from '../errors.js';
+import { initUserModel } from './userModel.js';
+import { initUserStore, MongoUserStore, FusionUserStore } from './userStore.js';
+import { openAppFusion, closeAppFusion } from './fusionEngine.js';
 import { eventBus, type EventBus, type Listener } from './events.js';
 import { configureQueue, InMemoryQueueAdapter, type JobQueueAdapter } from './Job.js';
 import { configureMailDriver, configureMailRenderer, logMailDriver } from './Mailable.js';
@@ -36,12 +40,15 @@ import { createLazyDb, registerAdminRoutes, RequestLogBuffer } from './adminModu
 import { registerAuthRoutes } from './authModule.js';
 import { issueCsrfToken, getCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
 import { connect } from '@bhooai/nexus-data';
+import { ensureLicense } from '@bhooai/nexus-crypto';
 import { createGateway, createFederatedGateway, graphqlHttpHandler, getExplorerHtml, helloSubgraph, SubscriptionServer } from '@bhooai/nexus-graphql';
 import type { Subgraph, GraphQLContext } from '@bhooai/nexus-graphql';
 
 export interface CreateNexusAppOptions {
   /** Identifier for this backend, used in admin, telemetry, logs. */
   name?: string;
+  /** Stack: react = http+ws+graphql, future = live+canvas+ai+autoui. Auto-detected from src/live if omitted. */
+  tech?: 'react' | 'future';
   /** Path to the backend src/ folder. Defaults to `<cwd>/src`. */
   srcRoot?: string;
   /** Project root (where .nexus-down and storage/ live). Defaults to srcRoot/.. */
@@ -97,14 +104,37 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   const projectRoot = resolve(opts.projectRoot ?? dirname(srcRoot));
   let config = opts.config ?? (await loadConfigAuto({ root: projectRoot }));
 
+  // License check at project start — verify the token (signature via fetched
+  // JWKS + online status) with the authority. On failure the app still boots,
+  // but every request is answered with 402 LICENSE_REQUIRED (middleware below)
+  // instead of crashing — a crashed backend surfaces as an opaque HTTP 500
+  // through dev proxies.
+  let licenseError: string | null = null;
+  try {
+    await ensureLicense({ projectDir: projectRoot });
+  } catch (err) {
+    licenseError = (err as Error).message;
+    console.error(`[${name}] license check failed: ${licenseError}`);
+  }
+
   // ------------------------------------------------------------------
-  // Per-app ports: NEXUS_PORT env var (set by `nexus dev` per service) wins.
-  // Otherwise, config port is used. For multi-app backends this is the only
-  // way they don't all collide on 4000.
+  // Per-app ports: nexus.config.ts `apps[]` is authoritative. The app's own
+  // entry (matched by `opts.name`) wins over `server.port`. NEXUS_PORT (set
+  // by `nexus dev`, which resolves from the same config) is honored only as
+  // the ephemeral run-time value — e.g. after a coordinated step-up — and a
+  // mismatch is logged so silent drift is impossible to miss.
   // ------------------------------------------------------------------
+  const configuredPort = config.apps?.find((a) => a.name === name)?.port ?? config.server?.port;
   const envPort = process.env.NEXUS_PORT ? parseInt(process.env.NEXUS_PORT, 10) : null;
-  if (envPort && config.server) {
-    config = Object.freeze({ ...config, server: { ...config.server, port: envPort } }) as NexusConfig;
+  const finalPort = envPort && Number.isFinite(envPort) ? envPort : configuredPort;
+  if (envPort && Number.isFinite(envPort) && configuredPort != null && envPort !== configuredPort) {
+    console.warn(
+      `[${name}] NEXUS_PORT=${envPort} differs from configured port ${configuredPort} ` +
+      `(ephemeral step-up for this run — nexus.config.ts unchanged).`,
+    );
+  }
+  if (finalPort != null && config.server && finalPort !== config.server.port) {
+    config = Object.freeze({ ...config, server: { ...config.server, port: finalPort } }) as NexusConfig;
   }
 
   const container = new Container();
@@ -114,6 +144,8 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // Discover convention folders
   // ------------------------------------------------------------------
   const discovery = await discoverBackend(srcRoot);
+  const tech = opts.tech ?? (discovery.live.length > 0 ? 'future' : 'react');
+  console.log(`[${name}] stack: ${tech} (${tech === 'future' ? 'live+canvas+ai+autoui' : 'http+ws+graphql'})`);
 
   // ------------------------------------------------------------------
   // DB must be connected before importing routes/graphql that define models
@@ -121,8 +153,28 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // connect was only inside `if (admin.enabled)` after routes were mounted,
   // causing "Not connected — call connect(uri) first." and missing /api/posts)
   // ------------------------------------------------------------------
-  console.log(`[db] early connect ${config.db.uri} autoIndex=${config.db.autoIndex}`);
-  try { connect(config.db.uri, { autoIndex: config.db.autoIndex }); console.log(`[db] early connect ok`); } catch (e) { console.error(`[db] early connect failed`, e); }
+  console.log(`[db] early connect ${mongoUri(config)} autoIndex=${config.db.mongodb.autoIndex} enabled=${mongoEnabled(config)} active=${activeDatabase(config)}`);
+  if (mongoEnabled(config)) {
+    try { connect(mongoUri(config), { autoIndex: config.db.mongodb.autoIndex }); console.log(`[db] early connect ok`); } catch (e) { console.error(`[db] early connect failed`, e); }
+  } else {
+    console.log(`[db] mongodb disabled — skipping early connect`);
+  }
+
+  // ------------------------------------------------------------------
+  // User store — Mongo (default) or Fusion (db.active: 'fusion').
+  // ------------------------------------------------------------------
+  if (activeDatabase(config) === 'fusion') {
+    if (!fusionEnabled(config)) {
+      throw new ConfigError(
+        "db.active is 'fusion' but db.fusion.enabled is false — enable it in nexus.config.ts",
+      );
+    }
+    const fusionDb = await openAppFusion(projectRoot, config);
+    initUserStore(new FusionUserStore(fusionDb));
+  } else {
+    if (mongoEnabled(config)) initUserModel();
+    initUserStore(new MongoUserStore());
+  }
 
   // ------------------------------------------------------------------
   // Storage facade + queue + mail — always configured, even if minimal
@@ -135,7 +187,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // ------------------------------------------------------------------
   // Error pages + handler
   // ------------------------------------------------------------------
-  const errorPages = new ErrorPages(projectRoot);
+  const errorPages = new ErrorPages(projectRoot, srcRoot);
   let errorHandler: ErrorHandler = opts.errorHandler ?? new DefaultErrorHandler();
   if (discovery.errorHandler) {
     try {
@@ -219,6 +271,44 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
 
   for (const def of opts.additionalRoutes ?? []) registerRoute(router, def, '');
 
+  // ------------------------------------------------------------------
+  // Placeholder upload route for empty projects — keeps POST /api/files alive
+  // Ensures file upload works even before file-storage example is installed.
+  // ------------------------------------------------------------------
+  const hasUploadRoute = router.routes().some((r) => r.method === 'POST' && r.path === '/api/files');
+  if (!hasUploadRoute) {
+    router.add('POST', '/api/files', async (ctx) => {
+      try {
+        const { uploadedFiles } = await import('../http/uploads.js');
+        const files = uploadedFiles(ctx as any);
+        if (!files.length) {
+          (ctx as any).json({ error: { code: 'VALIDATION_ERROR', message: 'file is required' } }, 400);
+          return;
+        }
+        const f = files[0]!;
+        const stored = await storage.disk('uploads').put('media', { buffer: f.data, originalName: f.filename, mime: f.contentType });
+        (ctx as any).json({ file: stored }, 201);
+      } catch (e: any) {
+        (ctx as any).json({ error: { code: 'VALIDATION_ERROR', message: e.message ?? 'upload failed' } }, 400);
+      }
+    });
+    router.add('POST', '/api/files/private', async (ctx) => {
+      try {
+        const { uploadedFiles } = await import('../http/uploads.js');
+        const files = uploadedFiles(ctx as any);
+        if (!files.length) {
+          (ctx as any).json({ error: { code: 'VALIDATION_ERROR', message: 'file is required' } }, 400);
+          return;
+        }
+        const f = files[0]!;
+        const stored = await storage.disk('private').put('secure', { buffer: f.data, originalName: f.filename, mime: f.contentType });
+        (ctx as any).json({ file: stored }, 201);
+      } catch (e: any) {
+        (ctx as any).json({ error: { code: 'VALIDATION_ERROR', message: e.message ?? 'upload failed' } }, 400);
+      }
+    });
+  }
+
   // ------------------------------------------------------------------
   // Built-in: /health + /admin/_registry
   // ------------------------------------------------------------------
@@ -226,36 +316,30 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     ctx.json({ ok: true, name, time: new Date().toISOString() });
   });
 
-  // Apps registry — used by the admin SPA's Apps tab. Reads the CLI's
-  // .nexus-ports.json (when present) and reports per-app info. Apps that
-  // aren't running show healthy: false.
+  // Apps registry — used by the admin SPA's Apps tab. Ports come from
+  // nexus.config.ts `apps[]` (single source of truth). Apps that aren't
+  // running show healthy: false.
   router.get('/admin/_registry', async (ctx) => {
-    const apps: Array<{ name: string; port: number; source: 'registry' }> = [];
-    try {
-      const regPath = resolve(projectRoot, '.nexus-ports.json');
-      if (existsSync(regPath)) {
-        const raw = await readFile(regPath, 'utf-8');
-        const reg = JSON.parse(raw) as Record<string, number>;
-        for (const [appName, port] of Object.entries(reg)) {
-          apps.push({ name: appName, port, source: 'registry' });
-        }
-      }
-    } catch (err) {
-      void err; // fall through with empty list
+    const apps: Array<{ name: string; port: number; source: 'config' }> = [];
+    for (const entry of config.apps ?? []) {
+      if (entry.enabled === false) continue;
+      apps.push({ name: entry.name, port: entry.port, source: 'config' });
     }
     // Always include the current app if not listed
     if (!apps.some((a) => a.name === name)) {
-      apps.unshift({ name, port: config.server.port, source: 'registry' });
+      apps.unshift({ name, port: config.server.port, source: 'config' });
     }
     ctx.json({ apps });
   });
 
   // ------------------------------------------------------------------
   // GraphQL gateway — builtin hello + discovered subgraphs (federated)
+  // React stack only — future uses live+canvas
   // ------------------------------------------------------------------
   let graphqlMounted = false;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let graphqlGateway: any = null;
+  if (tech === 'react') {
   {
     const explorerEnabled = (config.graphql as unknown as { explorer?: boolean })?.explorer ?? true;
     const helloEnabled = (config.graphql as unknown as { hello?: boolean })?.hello !== false;
@@ -368,6 +452,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
       if (helloEnabled) graphqlMounted = true;
     }
   }
+  }
 
   // ------------------------------------------------------------------
   // Admin module — request log buffer, lazy DB, admin + AI proxy routes
@@ -377,9 +462,12 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
 
   if (config.admin.enabled) {
     // Connect to MongoDB + register the User model so /auth/* can work.
-    try {
-      connect(config.db.uri, { autoIndex: config.db.autoIndex });
-    } catch { /* Mongo unreachable — auth routes will fail lazily */ }
+    // Skipped when mongodb is disabled (fusion-active backends).
+    if (mongoEnabled(config)) {
+      try {
+        connect(mongoUri(config), { autoIndex: config.db.mongodb.autoIndex });
+      } catch { /* Mongo unreachable — auth routes will fail lazily */ }
+    }
 
     // Auth routes (register/login/refresh/logout/me + OAuth). Returns the
     // AuthService used to build the admin guard.
@@ -428,12 +516,37 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
       ? { certFile: config.server.certFile, keyFile: config.server.keyFile }
       : {}),
     onError: (err, ctx) => errorHandler.toApiError(err),
+    renderError: (err, ctx) => {
+      const ne = toNexusError(err);
+      const lookup = (status: number) =>
+        errorPages.render(status, { requestId: ctx.requestId, message: ne.message });
+      return errorHandler.render(err, ctx, lookup);
+    },
+    renderNotFound: (ctx) => {
+      const notFound = new NotFoundError(`No route for ${ctx.method} ${ctx.path}`);
+      const lookup = (status: number) =>
+        errorPages.render(status, { requestId: ctx.requestId, message: notFound.message });
+      return errorHandler.render(notFound, ctx, lookup);
+    },
   });
 
+  // License gate — when the project-start check failed, answer every request
+  // (except /health) with 402 so the UI can show the license error rather than
+  // an opaque 500 from a crashed backend.
+  if (licenseError) {
+    const message = licenseError;
+    server.use(async (ctx, next) => {
+      if (ctx.path === '/health') return next();
+      ctx.json({ error: { code: 'LICENSE_REQUIRED', message } }, 402);
+    });
+  }
+
   // ------------------------------------------------------------------
   // Realtime WS server — mount discovered ws/*.room.ts handlers (chat lobby)
+  // React stack only — future uses live canvas
   // ------------------------------------------------------------------
   let realtime: any = null;
+  if (tech === 'react') {
   try {
     const { RealtimeServer } = await import('@bhooai/nexus-realtime');
     realtime = new RealtimeServer({ httpServer: server.httpServer, path: '/ws' });
@@ -534,6 +647,60 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     // realtime optional — if not installed, ws lobby falls back to no-op
     if ((e as any)?.code !== 'ERR_MODULE_NOT_FOUND') console.warn('[realtime] ws init failed:', e);
   }
+  } // tech === react
+
+  // ------------------------------------------------------------------
+  // Live pages — mount discovered src/live/*.live.js (future runtime)
+  // Self-contained: state travels with definition, auto-subscribed.
+  // Shares the same httpServer/port as the existing backend.
+  // Future stack only — react uses http+ws+graphql
+  // ------------------------------------------------------------------
+  let liveServer: any = null;
+  if (tech === 'future') {
+  try {
+    // @ts-ignore — nexus-future is JS/JSDoc, no .d.ts (v3)
+    const { LiveServer } = await import('@bhooai/nexus-future/live');
+    liveServer = new LiveServer({ httpServer: server.httpServer, onLog: (m: string) => console.log(`[live] ${m}`) });
+    // Global sense() — adaptive vibe (time/weather/mood) broadcast to every live page
+    try {
+      // @ts-ignore — nexus-future is JS/JSDoc, no .d.ts (v3)
+      const { sense } = await import('@bhooai/nexus-future/ui');
+      const feel = sense();
+      (liveServer as any).attachSense(feel);
+      console.log(`[${name}] sense attached: ${JSON.stringify((feel.vibe() as any)?.period)}/${JSON.stringify((feel.vibe() as any)?.weather)} — vibe broadcasts live`);
+    } catch (e) {
+      console.warn('[live] sense not attached:', e);
+    }
+    for (const file of discovery.live) {
+      try {
+        const mod: any = await importDefault(file);
+        const def = mod?.default ?? mod;
+        if (def?.path && typeof def.render === 'function') {
+          liveServer.addPage(def); // state on def auto-subscribes
+          console.log(`[${name}] live page mounted: ${def.path} (${file.name})`);
+        } else {
+          console.warn(`[${name}] live file ${file.path} does not export live() — skipped`);
+        }
+      } catch (e) {
+        console.warn(`[${name}] failed to load live page ${file.path}:`, e);
+      }
+    }
+    // Wire live pages into the NexusServer pipeline — live pages share the
+    // same port as the backend. Check before other handlers.
+    if (liveServer) {
+      server.use(async (ctx, next) => {
+        try {
+          const handled = liveServer.handleRequest(ctx.req as any, ctx.res as any);
+          if (handled) return;
+        } catch {}
+        await next();
+      });
+    }
+  } catch (e) {
+    if ((e as any)?.code !== 'ERR_MODULE_NOT_FOUND') console.warn('[live] init failed:', e);
+  }
+  } // tech === future
+  void liveServer;
 
   // ------------------------------------------------------------------
   // GraphQL subscriptions over WebSocket — mount when a gateway exists
@@ -695,6 +862,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     },
     async close() {
       await server.close();
+      await closeAppFusion();
     },
   };