@bhooai/nexus-core 0.1.6 → 2.0.0

package/src/app/defineRoutes.ts

@@ -0,0 +1,48 @@
+/**
+ * defineRoutes — declarative route collector used by routes/*.ts files.
+ *
+ * Auto-discovered by `createNexusApp()` from the backend's src/routes/
+ * folder. Each file's default export is consumed by the framework.
+ */
+import type { Handler, Middleware } from '../http/context.js';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+
+export interface UploadSpec {
+  field: string;
+  disk?: string;
+  dir?: string;
+  maxSize?: number;
+  mime?: string[];
+  maxFiles?: number;
+  transform?: {
+    width?: number;
+    height?: number;
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+    format?: 'webp' | 'jpeg' | 'png' | 'avif';
+  };
+}
+
+export interface RouteDef {
+  method: HttpMethod;
+  path: string;
+  handler: Handler;
+  middleware?: Middleware[];
+  /** Route-level upload handler configuration. */
+  upload?: UploadSpec;
+  /** Per-route rate limit override (requests per minute). */
+  rateLimit?: number;
+  /** Marks the route as public, bypassing auth middleware. */
+  public?: boolean;
+}
+
+export interface RoutesFile {
+  routes: RouteDef[];
+  /** Optional URL prefix applied to every route in this file. */
+  prefix?: string;
+}
+
+/** Build a RoutesFile from a list of route definitions. */
+export function defineRoutes(routes: RouteDef[], opts?: { prefix?: string }): RoutesFile {
+  return opts?.prefix ? { routes, prefix: opts.prefix } : { routes };
+}

package/src/app/discover.ts

@@ -0,0 +1,144 @@
+/**
+ * Loader — auto-discovers convention folders under a backend's src/.
+ *
+ * Scans a backend src/ root for the standard Nexus folders and imports
+ * matching files. Each folder has a defined matching pattern. Returns a
+ * manifest of discovered modules.
+ *
+ * Discovery is synchronous for simplicity — the dynamic imports happen lazily
+ * via `await import()` inside the discovery methods.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, resolve, extname, basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { existsSync } from 'node:fs';
+
+export interface DiscoveredFile {
+  /** Absolute file path. */
+  path: string;
+  /** File name without extension (e.g. "users" from routes/users.ts). */
+  name: string;
+  /** Subdirectory inside the convention folder ("" for direct children). */
+  subdir: string;
+}
+
+async function listRecursive(dir: string, subdir: string = ''): Promise<DiscoveredFile[]> {
+  const out: DiscoveredFile[] = [];
+  if (!existsSync(dir)) return out;
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      const children = await listRecursive(full, subdir ? `${subdir}/${e.name}` : e.name);
+      out.push(...children);
+    } else if (e.isFile()) {
+      const ext = extname(e.name);
+      if (ext !== '.ts' && ext !== '.js' && ext !== '.mts' && ext !== '.mjs') continue;
+      const name = basename(e.name, ext);
+      out.push({ path: full, name, subdir });
+    }
+  }
+  return out;
+}
+
+async function* iterateFiles(dir: string, pattern?: RegExp) {
+  const files = await listRecursive(dir);
+  for (const f of files) {
+    if (pattern && !pattern.test(f.name)) continue;
+    yield f;
+  }
+}
+
+export interface DiscoveryResult {
+  routes: DiscoveredFile[];
+  graphql: DiscoveredFile[];
+  rooms: DiscoveredFile[];
+  mailables: DiscoveredFile[];
+  errorHandler: DiscoveredFile | null;
+  errorPages: DiscoveredFile[];
+  events: DiscoveredFile[];
+  listeners: DiscoveredFile[];
+  jobs: DiscoveredFile[];
+  policies: DiscoveredFile[];
+  providers: DiscoveredFile[];
+  seeds: DiscoveredFile[];
+  migrations: DiscoveredFile[];
+  plugins: DiscoveredFile[];
+  config: DiscoveredFile[];
+}
+
+/**
+ * Walk a backend src/ root and produce a manifest of all auto-discovered
+ * convention folders. Missing folders are simply absent from the result.
+ */
+export async function discoverBackend(srcRoot: string): Promise<DiscoveryResult> {
+  const abs = resolve(srcRoot);
+
+  const [routes, graphql, rooms, mailables, errorPages, events, listeners, jobs, policies, providers, seeds, migrations, plugins, config] =
+    await Promise.all([
+      collect(join(abs, 'routes'), /\.(ts|js)$/),
+      collect(join(abs, 'graphql'), /\.graph\.(ts|js)$/),
+      collect(join(abs, 'ws'), /\.room\.(ts|js)$/),
+      collect(join(abs, 'mail', 'mailables'), /\.(ts|js)$/),
+      collect(join(abs, 'errors', 'pages'), /\.html$/),
+      collect(join(abs, 'events'), /\.(ts|js)$/),
+      collect(join(abs, 'listeners'), /^On.*\.(ts|js)$/),
+      collect(join(abs, 'jobs'), /Job\.(ts|js)$/),
+      collect(join(abs, 'policies'), /Policy\.(ts|js)$/),
+      collect(join(abs, 'providers'), /ServiceProvider\.(ts|js)$/),
+      collect(join(abs, 'database', 'seeds'), /Seeder\.(ts|js)$/),
+      collect(join(abs, 'database', 'migrations'), /^\d{4}_\d{2}_\d{2}_\d{6}_.*\.(ts|js)$/),
+      collectPluginDirs(join(abs, 'plugins')),
+      collect(join(abs, 'config'), /\.(ts|js)$/),
+    ]);
+
+  // errors/Handler.ts is a single well-known file.
+  const errorHandlerPath = join(abs, 'errors', 'Handler.ts');
+  const errorHandler: DiscoveredFile | null = existsSync(errorHandlerPath)
+    ? { path: errorHandlerPath, name: 'Handler', subdir: '' }
+    : null;
+
+  return { routes, graphql, rooms, mailables, errorPages, events, listeners, jobs, policies, providers, seeds, migrations, plugins, config, errorHandler };
+}
+
+async function collect(dir: string, pattern: RegExp): Promise<DiscoveredFile[]> {
+  if (!existsSync(dir)) return [];
+  const out: DiscoveredFile[] = [];
+  for await (const f of iterateFiles(dir)) {
+    // Apply pattern to filename only (not full path)
+    if (!pattern.test(basename(f.path))) continue;
+    out.push(f);
+  }
+  return out;
+}
+
+async function collectPluginDirs(dir: string): Promise<DiscoveredFile[]> {
+  if (!existsSync(dir)) return [];
+  const out: DiscoveredFile[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const entry = join(dir, e.name, 'index.ts');
+    if (existsSync(entry)) {
+      out.push({ path: entry, name: e.name, subdir: '' });
+      continue;
+    }
+    const entryJs = join(dir, e.name, 'index.js');
+    if (existsSync(entryJs)) {
+      out.push({ path: entryJs, name: e.name, subdir: '' });
+    }
+  }
+  return out;
+}
+
+/** Import a discovered file via dynamic import. */
+export async function importDiscovered(file: DiscoveredFile): Promise<unknown> {
+  const url = pathToFileURL(file.path).href;
+  return await import(url);
+}
+
+/** Import a discovered file and return its default export. */
+export async function importDefault<T = unknown>(file: DiscoveredFile): Promise<T> {
+  const mod: any = await importDiscovered(file);
+  return (mod?.default ?? mod) as T;
+}

package/src/app/errorPages/_base.html

@@ -0,0 +1,121 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>{{STATUS}} — {{TITLE}}</title>
+<style>
+  :root {
+    --nx-bg: #0b1220;
+    --nx-fg: #e2e8f0;
+    --nx-muted: #94a3b8;
+    --nx-accent: #60a5fa;
+    --nx-card: #0f172a;
+    --nx-border: #1e293b;
+  }
+  @media (prefers-color-scheme: light) {
+    :root {
+      --nx-bg: #f8fafc;
+      --nx-fg: #0b1220;
+      --nx-muted: #475569;
+      --nx-accent: #2563eb;
+      --nx-card: #ffffff;
+      --nx-border: #e2e8f0;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    background: var(--nx-bg);
+    color: var(--nx-fg);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 2rem;
+  }
+  .card {
+    background: var(--nx-card);
+    border: 1px solid var(--nx-border);
+    border-radius: 12px;
+    padding: 3rem 2.5rem;
+    max-width: 34rem;
+    width: 100%;
+    text-align: center;
+    box-shadow: 0 8px 24px rgba(0,0,0,0.12);
+  }
+  .code {
+    font-size: 4rem;
+    font-weight: 700;
+    color: var(--nx-accent);
+    letter-spacing: -0.04em;
+    margin: 0 0 0.5rem 0;
+    line-height: 1;
+  }
+  h1 {
+    font-size: 1.5rem;
+    margin: 0 0 1rem 0;
+    font-weight: 600;
+  }
+  p {
+    color: var(--nx-muted);
+    margin: 0 0 1.5rem 0;
+    line-height: 1.5;
+  }
+  .actions {
+    display: flex;
+    gap: 0.75rem;
+    justify-content: center;
+    flex-wrap: wrap;
+  }
+  .btn {
+    display: inline-block;
+    padding: 0.625rem 1.125rem;
+    border-radius: 8px;
+    text-decoration: none;
+    font-weight: 500;
+    font-size: 0.9375rem;
+    transition: opacity 0.15s ease;
+    cursor: pointer;
+    border: none;
+  }
+  .btn-primary {
+    background: var(--nx-accent);
+    color: white;
+  }
+  .btn-primary:hover { opacity: 0.9; }
+  .btn-ghost {
+    background: transparent;
+    color: var(--nx-fg);
+    border: 1px solid var(--nx-border);
+  }
+  .btn-ghost:hover { background: rgba(148,163,184,0.08); }
+  .foot {
+    margin-top: 2rem;
+    font-size: 0.8125rem;
+    color: var(--nx-muted);
+    opacity: 0.7;
+  }
+  code {
+    background: rgba(148,163,184,0.15);
+    padding: 0.125rem 0.375rem;
+    border-radius: 4px;
+    font-size: 0.875em;
+  }
+</style>
+</head>
+<body>
+  <main class="card">
+    <div class="code">{{CODE}}</div>
+    <h1>{{TITLE}}</h1>
+    <p>{{MESSAGE}}</p>
+    <div class="actions">
+      <a class="btn btn-primary" href="/">Home</a>
+      <button class="btn btn-ghost" onclick="location.reload()">Retry</button>
+    </div>
+    {{#REQUEST_ID}}
+    <div class="foot">Request ID: <code>{{REQUEST_ID}}</code></div>
+    {{/REQUEST_ID}}
+  </main>
+</body>
+</html>

package/src/app/errorPages.ts

@@ -0,0 +1,117 @@
+/**
+ * ErrorPages — renders a templated HTML page for a given HTTP status.
+ *
+ * Reads `mail/pages/<status>.html` (project-level) if present, else falls back
+ * to the framework default template. Substitutes simple {{PLACEHOLDER}}
+ * markers. Production-safe (no stack traces).
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const DEFAULT_MESSAGES: Record<number, { title: string; message: string }> = {
+  400: { title: 'Bad Request', message: 'The request could not be understood. Check the body and try again.' },
+  401: { title: 'Unauthorized', message: 'Authentication is required to access this resource.' },
+  403: { title: 'Forbidden', message: 'You do not have permission to access this resource.' },
+  404: { title: 'Not Found', message: 'The page you were looking for does not exist.' },
+  405: { title: 'Method Not Allowed', message: 'The requested method is not supported on this endpoint.' },
+  408: { title: 'Request Timeout', message: 'The server timed out waiting for the request.' },
+  409: { title: 'Conflict', message: 'The request conflicts with the current state of the resource.' },
+  413: { title: 'Payload Too Large', message: 'The uploaded file or body exceeds the allowed size.' },
+  422: { title: 'Unprocessable Entity', message: 'The request was well-formed but could not be processed.' },
+  429: { title: 'Too Many Requests', message: 'Rate limit exceeded. Please slow down and retry.' },
+  500: { title: 'Internal Server Error', message: 'Something went wrong on our side. We are looking into it.' },
+  502: { title: 'Bad Gateway', message: 'Received an invalid response from an upstream service.' },
+  503: { title: 'Service Unavailable', message: 'Service is temporarily down. Please retry shortly.' },
+  504: { title: 'Gateway Timeout', message: 'Upstream service did not respond in time.' },
+};
+
+export interface ErrorPageRenderContext {
+  requestId?: string;
+  /** Override default message (e.g. from a caught error). */
+  message?: string;
+  [key: string]: unknown;
+}
+
+export class ErrorPages {
+  constructor(private projectRoot: string) {}
+
+  /** Render the HTML for a given status. */
+  async render(status: number, ctx: ErrorPageRenderContext = {}): Promise<string> {
+    const custom = await this.tryCustomPage(status);
+    const template = custom ?? (await this.defaultTemplate());
+    const defaults = DEFAULT_MESSAGES[status] ?? {
+      title: `Error ${status}`,
+      message: 'An unexpected error occurred.',
+    };
+    const message = ctx.message ?? defaults.message;
+    return substitute(template, {
+      CODE: String(status),
+      STATUS: String(status),
+      TITLE: defaults.title,
+      MESSAGE: message,
+      REQUEST_ID: ctx.requestId ?? '',
+    });
+  }
+
+  private async tryCustomPage(status: number): Promise<string | null> {
+    const candidates = [
+      join(this.projectRoot, 'src', 'errors', 'pages', `${status}.html`),
+      join(this.projectRoot, 'src', 'errors', 'pages', 'error.html'),   // generic catch-all
+    ];
+    for (const cand of candidates) {
+      if (existsSync(cand)) {
+        try {
+          return await readFile(cand, 'utf-8');
+        } catch { /* ignore */ }
+      }
+    }
+    return null;
+  }
+
+  private async defaultTemplate(): Promise<string> {
+    // Bundled next to this module at errorPages/_base.html.
+    const candidate = join(HERE, 'errorPages', '_base.html');
+    if (existsSync(candidate)) {
+      try { return await readFile(candidate, 'utf-8'); } catch { /* ignore */ }
+    }
+    return INLINE_FALLBACK;
+  }
+}
+
+/** Substitute {{KEY}} markers + handle {{#KEY}}…{{/KEY}} blocks. */
+function substitute(template: string, vars: Record<string, unknown>): string {
+  let out = template;
+  // Conditional blocks: {{#KEY}}content{{/KEY}} — shown only when KEY is truthy
+  out = out.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_m, key: string, content: string) => {
+    const v = vars[key];
+    if (v === undefined || v === null || v === '' || v === false) return '';
+    return substitute(content, vars);
+  });
+  // Simple {{KEY}}
+  out = out.replace(/\{\{(\w+)\}\}/g, (_m, key: string) => {
+    const v = vars[key];
+    return v === undefined || v === null ? '' : escapeHtml(String(v));
+  });
+  return out;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+const INLINE_FALLBACK = `<!doctype html><html><head><meta charset="utf-8"><title>{{CODE}}</title><style>
+body{font-family:system-ui;background:#0b1220;color:#e2e8f0;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0;padding:2rem}
+main{max-width:32rem;text-align:center;background:#0f172a;border:1px solid #1e293b;border-radius:12px;padding:3rem 2rem}
+.c{font-size:4rem;color:#60a5fa;margin:0 0 .5rem;font-weight:700;letter-spacing:-.04em}
+h1{font-size:1.5rem;margin:0 0 1rem;font-weight:600} p{color:#94a3b8;line-height:1.5;margin:0 0 1.5rem}
+a{display:inline-block;padding:.625rem 1.125rem;border-radius:8px;background:#60a5fa;color:#fff;text-decoration:none}
+</style></head><body><main><div class="c">{{CODE}}</div><h1>{{TITLE}}</h1><p>{{MESSAGE}}</p><a href="/">Home</a></main></body></html>`;

package/src/app/events.ts

@@ -0,0 +1,81 @@
+/**
+ * Domain events + in-process event bus.
+ *
+ * Events are plain classes; Listeners subscribe via class reference.
+ * The bus supports sync + async handlers, with isolated error capture so a
+ * failing listener does not break the dispatcher's request path.
+ */
+
+type AnyEvent = object;
+
+export interface EventListener<T extends AnyEvent = AnyEvent> {
+  /** Handle the event. May be async. */
+  handle(event: T): Promise<void> | void;
+}
+
+type EventClass<T extends AnyEvent = AnyEvent> = new (...args: never[]) => T;
+type ListenerClass<T extends AnyEvent = AnyEvent> = new () => EventListener<T>;
+
+interface Sub {
+  eventName: string;
+  listener: EventListener<AnyEvent>;
+}
+
+/**
+ * In-process event bus. For cross-process / cross-replica eventing, swap the
+ * in-memory registry for a Redis-backed adapter (same API).
+ */
+export class EventBus {
+  private subs: Sub[] = [];
+
+  /** Subscribe a listener instance to an event class. */
+  on<T extends AnyEvent>(event: EventClass<T>, listener: EventListener<T>): this {
+    this.subs.push({ eventName: event.name, listener: listener as EventListener<AnyEvent> });
+    return this;
+  }
+
+  /** Register a listener class (instantiated lazily on first event). */
+  register<T extends AnyEvent>(ListenerCtor: ListenerClass<T>, EventCtor: EventClass<T>): this {
+    const listener = new ListenerCtor();
+    return this.on(EventCtor, listener);
+  }
+
+  /** Dispatch synchronously; listener errors are logged but not thrown. */
+  async dispatch<T extends AnyEvent>(event: T): Promise<void> {
+    const name = (event as { constructor: { name: string } }).constructor.name;
+    const target = this.subs.filter((s) => s.eventName === name);
+    for (const { listener } of target) {
+      try {
+        await listener.handle(event);
+      } catch (err) {
+        // Listener errors must not break the request path.
+        console.error(`[events] listener for ${name} failed:`, err);
+      }
+    }
+  }
+
+  /** Synchronous dispatch; fires-and-forgets with attached catch. */
+  dispatchSync<T extends AnyEvent>(event: T): void {
+    void this.dispatch(event).catch((err) => {
+      console.error('[events] dispatch failed:', err);
+    });
+  }
+
+  /** Number of registered listeners (any event). */
+  get size(): number {
+    return this.subs.length;
+  }
+}
+
+/** Base class for domain events. Subclassing is optional — plain objects work too. */
+export abstract class DomainEvent {
+  readonly occurredAt: Date = new Date();
+}
+
+/** Base listener class. Subclass + implement `handle`. */
+export abstract class Listener<T extends AnyEvent = AnyEvent> implements EventListener<T> {
+  abstract handle(event: T): Promise<void> | void;
+}
+
+/** Global default bus. Apps may construct their own for isolation. */
+export const eventBus = new EventBus();

package/src/app/index.ts

@@ -0,0 +1,14 @@
+export * from './createNexusApp.js';
+export * from './defineRoutes.js';
+export * from './discover.js';
+export * from './events.js';
+export * from './policies.js';
+export * from './FormRequest.js';
+export * from './Resource.js';
+export * from './ServiceProvider.js';
+export * from './Job.js';
+export * from './Mailable.js';
+export * from './ErrorHandler.js';
+export * from './Seeder.js';
+export * from './Storage.js';
+export * from './maintenance.js';

package/src/app/maintenance.ts

@@ -0,0 +1,80 @@
+/**
+ * Maintenance mode (`nexus down`/`nexus up`).
+ *
+ * When active, middleware intercepts requests and serves the branded
+ * maintenance page (errors/pages/maintenance.html) with status 503 and a
+ * Retry-After hint. Health checks stay reachable for orchestrators.
+ *
+ * State lives in `.nexus-down` file at project root (touch = on, rm = off).
+ */
+import { existsSync } from 'node:fs';
+import { writeFile, unlink, mkdir } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import type { Middleware } from '../http/context.js';
+
+const FLAG_NAME = '.nexus-down';
+
+export function maintenanceFlagPath(projectRoot: string): string {
+  return join(resolve(projectRoot), FLAG_NAME);
+}
+
+export async function setMaintenance(projectRoot: string, on: boolean, message?: string): Promise<void> {
+  const flag = maintenanceFlagPath(projectRoot);
+  if (on) {
+    await mkdir(dirname(flag), { recursive: true });
+    const payload = JSON.stringify({ since: new Date().toISOString(), message: message ?? 'Under maintenance' });
+    await writeFile(flag, payload, 'utf-8');
+  } else {
+    if (existsSync(flag)) await unlink(flag);
+  }
+}
+
+export function isMaintenance(projectRoot: string): boolean {
+  return existsSync(maintenanceFlagPath(projectRoot));
+}
+
+export async function maintenanceMessage(projectRoot: string): Promise<string> {
+  if (!isMaintenance(projectRoot)) return '';
+  try {
+    const raw = await readFile(maintenanceFlagPath(projectRoot), 'utf-8');
+    const parsed = JSON.parse(raw) as { message?: string };
+    return parsed.message ?? 'Under maintenance';
+  } catch {
+    return 'Under maintenance';
+  }
+}
+
+export interface MaintenanceMiddlewareOpts {
+  projectRoot: string;
+  /** Paths always allowed through (defaults include /health). */
+  allowPaths?: string[];
+  /** HTML body for maintenance responses. Falls back to a tiny inline page. */
+  pageHtml?: string;
+  /** seconds; defaults to 60. */
+  retryAfter?: number;
+}
+
+export function maintenanceMiddleware(opts: MaintenanceMiddlewareOpts): Middleware {
+  const allow = new Set(opts.allowPaths ?? ['/health', '/favicon.ico']);
+  return async (ctx, next) => {
+    if (!isMaintenance(opts.projectRoot)) return next();
+    if (allow.has(ctx.path)) return next();
+    const acceptsHtml = ((ctx.headers.accept as string) ?? '').includes('text/html');
+    ctx.setHeader('retry-after', String(opts.retryAfter ?? 60));
+    ctx.setHeader('cache-control', 'no-store');
+    if (acceptsHtml) {
+      const html = opts.pageHtml ?? defaultPage();
+      ctx.html(html, 503);
+    } else {
+      ctx.json({ error: { code: 'MAINTENANCE', message: 'Service under maintenance' } }, 503);
+    }
+  };
+}
+
+function defaultPage(): string {
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Maintenance</title>
+<style>body{font-family:system-ui;background:#0b1220;color:#e2e8f0;display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+main{max-width:32rem;text-align:center}h1{font-size:2rem;margin:0 0 1rem}p{color:#94a3b8}</style></head>
+<body><main><h1>We'll be right back</h1><p>Service under maintenance. Please retry shortly.</p></main></body></html>`;
+}

package/src/app/policies.ts

@@ -0,0 +1,53 @@
+/**
+ * Policies — Laravel-style authorization rules keyed by resource type.
+ *
+ * Usage:
+ *   class UserPolicy extends Policy<User> {
+ *     view(actor, target)  { return actor.id === target.id || actor.role === 'admin'; }
+ *     update(actor, target) { return actor.id === target.id; }
+ *     delete(actor, target) { return actor.role === 'admin'; }
+ *   }
+ *
+ *   policyRegistry.register(User, new UserPolicy());
+ *   ctx.authorize('update', targetUser);   // throws 403 if denied
+ */
+
+export type PolicyAbility<TSubject, TResource> = (actor: TSubject, resource: TResource) => boolean | Promise<boolean>;
+
+export abstract class Policy<TSubject = unknown, TResource = unknown> {
+  /** Default deny-all if ability not defined. Subclasses override any method. */
+  [ability: string]: unknown;
+}
+
+interface PolicyEntry {
+  resourceKey: { name: string };
+  policy: Record<string, PolicyAbility<unknown, unknown>>;
+}
+
+export class PolicyRegistry {
+  private entries: PolicyEntry[] = [];
+
+  register<TResource>(ResourceCtor: new (...args: never[]) => TResource, policy: Record<string, PolicyAbility<unknown, unknown>>): this {
+    this.entries.push({ resourceKey: ResourceCtor, policy });
+    return this;
+  }
+
+  /** Run a policy check. Returns true if allowed, false if denied, null if no policy matched. */
+  async check<TSubject, TResource>(
+    ability: string,
+    actor: TSubject,
+    resource: TResource,
+  ): Promise<boolean | null> {
+    if (resource === null || resource === undefined) return null;
+    const ctor = (resource as { constructor?: { name: string } }).constructor;
+    if (!ctor) return null;
+    const found = this.entries.find((e) => e.resourceKey.name === ctor.name);
+    if (!found) return null;
+    const fn = found.policy[ability];
+    if (!fn) return false;                       // deny-by-default on missing ability
+    return !!(await fn(actor, resource));
+  }
+}
+
+/** Default singleton registry. */
+export const policyRegistry = new PolicyRegistry();

package/src/config/defaults.ts

@@ -132,24 +132,4 @@ export const defaults: NexusConfig = {
     host: 'localhost',
     enabled: true,
   },
-  cluster: {
-    enabled: false,
-    failOpenSingleNode: true,
-    lbHost: '127.0.0.1',
-    lbPort: 8080,
-    nodeAgentHost: '127.0.0.1',
-    nodeAgentPort: 7575,
-    registryFile: 'cluster.runtime.json',
-    token: '',
-    autoscale: {
-      enabled: true,
-      mode: 'auto',
-      minNodes: 1,
-      maxNodes: 4,
-      cooldownMs: 60_000,
-      cpuHigh: 80,
-      rpsPerNodeHigh: 15,
-      rpsPerNodeLow: 5,
-    },
-  },
 };