@bhooai/nexus-core 0.1.6 → 2.0.0

package/src/app/Storage.ts

@@ -0,0 +1,366 @@
+/**
+ * Storage — disk abstraction. Drivers: local + s3 (the latter via @aws-sdk
+ * when installed). Apps call `storage.disk(name)`; route upload specs use
+ * the same facade.
+ *
+ *   await storage.disk('uploads').put('avatars', file);
+ *   const url = await storage.disk('private').signedUrl('invoices/1.pdf', { ttl: 300 });
+ */
+import { createHash, createHmac, randomUUID } from 'node:crypto';
+import { mkdir, readFile, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import type { Readable } from 'node:stream';
+
+export interface StoredFile {
+  id: string;
+  path: string;
+  url: string;
+  disk: string;
+  size: number;
+  mime: string;
+  originalName: string;
+  sha256: string;
+}
+
+export interface SignedUrlOptions {
+  /** Seconds the URL stays valid. */
+  ttl?: number;
+}
+
+export interface Disk {
+  name: string;
+  put(dir: string, source: Buffer | Readable | { buffer: Buffer; originalName?: string; mime?: string }): Promise<StoredFile>;
+  get(path: string): Promise<Buffer>;
+  stream(path: string): Readable;
+  delete(path: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  url(path: string): string;
+  signedUrl(path: string, opts?: SignedUrlOptions): Promise<string>;
+}
+
+export interface DiskConfig {
+  driver: 'local' | 's3';
+  /** local: filesystem root. */
+  root?: string;
+  /** local: public serve path prefix (e.g. /uploads). */
+  servePath?: string;
+  /** s3: bucket. */
+  bucket?: string;
+  /** s3: region. */
+  region?: string;
+  /** s3: optional endpoint (MinIO/R2/B2). */
+  endpoint?: string;
+  /** s3: optional public CDN base URL. */
+  cdnUrl?: string;
+}
+
+export interface StorageConfig {
+  disks: Record<string, DiskConfig>;
+  default?: string;
+  /** HMAC secret used to sign local private URLs. Falls back to auth jwt secret. */
+  signingSecret?: string;
+  imageTransform?: {
+    enabled: boolean;
+    formats: string[];
+    sizes: Record<string, number>;
+    stripMetadata?: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Local driver
+// ---------------------------------------------------------------------------
+
+class LocalDisk implements Disk {
+  constructor(readonly name: string, private cfg: DiskConfig, private signingSecret: string) {}
+
+  private resolveRoot(): string {
+    if (!this.cfg.root) throw new Error(`disk "${this.name}" missing root`);
+    return resolve(this.cfg.root);
+  }
+
+  private abs(p: string): string {
+    return join(this.resolveRoot(), p);
+  }
+
+  async put(
+    dir: string,
+    source: Buffer | Readable | { buffer: Buffer; originalName?: string; mime?: string },
+  ): Promise<StoredFile> {
+    const buffer = await sourceToBuffer(source);
+    const meta = sourceAsMeta(source);
+    const originalName = meta.originalName ?? 'file';
+    const ext = extname(originalName) || '';
+    const id = randomUUID();
+    const date = new Date();
+    const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+    const rel = join(dir, shard, `${id}${ext}`).replace(/\\/g, '/');
+    const abs = this.abs(rel);
+
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, buffer);
+
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    return {
+      id,
+      path: rel,
+      url: this.url(rel),
+      disk: this.name,
+      size: buffer.length,
+      mime: meta.mime ?? 'application/octet-stream',
+      originalName,
+      sha256,
+    };
+  }
+
+  async get(path: string): Promise<Buffer> {
+    return readFile(this.abs(path));
+  }
+
+  stream(path: string): Readable {
+    return createReadStream(this.abs(path));
+  }
+
+  async delete(path: string): Promise<void> {
+    try {
+      await unlink(this.abs(path));
+    } catch {
+      /* swallow — deletes are idempotent */
+    }
+  }
+
+  async exists(path: string): Promise<boolean> {
+    try {
+      await fsStat(this.abs(path));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  url(path: string): string {
+    const base = this.cfg.servePath ?? `/${this.name}`;
+    return `${base.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+  }
+
+  async signedUrl(path: string, opts: SignedUrlOptions = {}): Promise<string> {
+    const ttl = opts.ttl ?? 300;
+    const expires = Math.floor(Date.now() / 1000) + ttl;
+    const toSign = `${path}:${expires}`;
+    const sig = createHmac('sha256', this.signingSecret).update(toSign).digest('base64url');
+    const base = `/files/${encodeURIComponent(path)}`;
+    return `${base}?expires=${expires}&sig=${sig}`;
+  }
+
+  verifySignedUrl(path: string, expires: number, sig: string): boolean {
+    if (Math.floor(Date.now() / 1000) > expires) return false;
+    const expected = createHmac('sha256', this.signingSecret).update(`${path}:${expires}`).digest('base64url');
+    return expected === sig;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// S3 driver (dynamically loaded if @aws-sdk/client-s3 installed)
+// ---------------------------------------------------------------------------
+
+class S3Disk implements Disk {
+  private client: any;
+  private ready = false;
+
+  constructor(readonly name: string, private cfg: DiskConfig) {}
+
+  private async ensure(): Promise<void> {
+    if (this.ready) return;
+    const mod = await import('@aws-sdk/client-s3' as string).catch(() => null);
+    if (!mod) throw new Error('S3 driver requires @aws-sdk/client-s3 — install it as an optional dep');
+    const { S3Client } = mod as any;
+    this.client = new S3Client({
+      region: this.cfg.region,
+      ...(this.cfg.endpoint ? { endpoint: this.cfg.endpoint, forcePathStyle: true } : {}),
+    });
+    this.ready = true;
+  }
+
+  async put(dir: string, source: Buffer | Readable | { buffer: Buffer; originalName?: string; mime?: string }): Promise<StoredFile> {
+    await this.ensure();
+    const { PutObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
+    const buffer = await sourceToBuffer(source);
+    const meta = sourceAsMeta(source);
+    const originalName = meta.originalName ?? 'file';
+    const ext = extname(originalName) || '';
+    const id = randomUUID();
+    const date = new Date();
+    const shard = `${date.getUTCFullYear()}/${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+    const rel = `${dir}/${shard}/${id}${ext}`;
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.cfg.bucket,
+      Key: rel,
+      Body: buffer,
+      ContentType: meta.mime ?? 'application/octet-stream',
+    }));
+    const sha256 = createHash('sha256').update(buffer).digest('hex');
+    return {
+      id,
+      path: rel,
+      url: this.url(rel),
+      disk: this.name,
+      size: buffer.length,
+      mime: meta.mime ?? 'application/octet-stream',
+      originalName,
+      sha256,
+    };
+  }
+
+  async get(path: string): Promise<Buffer> {
+    await this.ensure();
+    const { GetObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
+    const out = await this.client.send(new GetObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+    const chunks: Buffer[] = [];
+    for await (const chunk of out.Body as AsyncIterable<Buffer>) chunks.push(chunk);
+    return Buffer.concat(chunks);
+  }
+
+  stream(_path: string): Readable {
+    throw new Error('S3 stream() not yet implemented — use get()');
+  }
+
+  async delete(path: string): Promise<void> {
+    await this.ensure();
+    const { DeleteObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+  }
+
+  async exists(path: string): Promise<boolean> {
+    await this.ensure();
+    const { HeadObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: this.cfg.bucket, Key: path }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  url(path: string): string {
+    if (this.cfg.cdnUrl) return `${this.cfg.cdnUrl.replace(/\/+$/, '')}/${path}`;
+    if (this.cfg.endpoint) return `${this.cfg.endpoint.replace(/\/+$/, '')}/${this.cfg.bucket}/${path}`;
+    return `https://${this.cfg.bucket}.s3.${this.cfg.region}.amazonaws.com/${path}`;
+  }
+
+  async signedUrl(path: string, opts: SignedUrlOptions = {}): Promise<string> {
+    await this.ensure();
+    const presigner = await import('@aws-sdk/s3-request-presigner' as string).catch(() => null);
+    if (!presigner) throw new Error('S3 presigned URLs require @aws-sdk/s3-request-presigner');
+    const { getSignedUrl } = presigner as any;
+    const { GetObjectCommand } = (await import('@aws-sdk/client-s3' as string)) as any;
+    return await getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.cfg.bucket, Key: path }), {
+      expiresIn: opts.ttl ?? 300,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function sourceToBuffer(
+  source: Buffer | Readable | { buffer: Buffer; originalName?: string; mime?: string },
+): Promise<Buffer> {
+  if (Buffer.isBuffer(source)) return source;
+  if (typeof source === 'object' && 'buffer' in source) return source.buffer;
+  const chunks: Buffer[] = [];
+  for await (const chunk of source as AsyncIterable<Buffer>) chunks.push(chunk);
+  return Buffer.concat(chunks);
+}
+
+function sourceAsMeta(
+  source: Buffer | Readable | { buffer: Buffer; originalName?: string; mime?: string },
+): { originalName?: string; mime?: string } {
+  if (typeof source === 'object' && !Buffer.isBuffer(source) && 'buffer' in source) {
+    const out: { originalName?: string; mime?: string } = {};
+    if (source.originalName) out.originalName = source.originalName;
+    if (source.mime) out.mime = source.mime;
+    return out;
+  }
+  return {};
+}
+
+// ---------------------------------------------------------------------------
+// Facade
+// ---------------------------------------------------------------------------
+
+class StorageFacade {
+  private disks = new Map<string, Disk>();
+  private cfg: StorageConfig | null = null;
+  private signingSecret: string = '';
+
+  configure(cfg: StorageConfig, signingSecret: string): void {
+    this.cfg = cfg;
+    this.signingSecret = signingSecret || cfg.signingSecret || 'nexus-insecure';
+    for (const [name, diskCfg] of Object.entries(cfg.disks ?? {})) {
+      if (diskCfg.driver === 'local') {
+        this.disks.set(name, new LocalDisk(name, diskCfg, this.signingSecret));
+      } else if (diskCfg.driver === 's3') {
+        this.disks.set(name, new S3Disk(name, diskCfg));
+      }
+    }
+  }
+
+  disk(name?: string): Disk {
+    const key = name ?? this.cfg?.default ?? Object.keys(this.cfg?.disks ?? {})[0];
+    if (!key) throw new Error('Storage has no disks configured');
+    const d = this.disks.get(key);
+    if (!d) throw new Error(`Storage disk "${key}" not configured`);
+    return d;
+  }
+
+  local(name: string): LocalDisk | null {
+    const d = this.disks.get(name);
+    return d instanceof LocalDisk ? d : null;
+  }
+}
+
+export const storage = new StorageFacade();
+
+/** Auto-configure from env — used by createNexusApp() boot. */
+export function configureStorageFromEnv(root: string, signingSecret: string): void {
+  const cfg: StorageConfig = {
+    default: 'uploads',
+    disks: {
+      uploads: {
+        driver: 'local',
+        root: join(root, 'storage', 'uploads'),
+        servePath: '/uploads',
+      },
+      private: {
+        driver: 'local',
+        root: join(root, 'storage', 'private'),
+      },
+      ...(process.env.NEXUS_STORAGE_S3_BUCKET
+        ? {
+            s3media: {
+              driver: 's3' as const,
+              bucket: process.env.NEXUS_STORAGE_S3_BUCKET,
+              region: process.env.NEXUS_STORAGE_S3_REGION,
+              ...(process.env.NEXUS_STORAGE_S3_ENDPOINT ? { endpoint: process.env.NEXUS_STORAGE_S3_ENDPOINT } : {}),
+              ...(process.env.NEXUS_STORAGE_S3_CDN ? { cdnUrl: process.env.NEXUS_STORAGE_S3_CDN } : {}),
+            },
+          }
+        : {}),
+    },
+    signingSecret,
+  };
+  storage.configure(cfg, signingSecret);
+
+  // Ensure directories exist
+  for (const d of Object.values(cfg.disks ?? {})) {
+    if (d.driver === 'local' && d.root) {
+      const abs = resolve(d.root);
+      if (!existsSync(abs)) {
+        void mkdir(abs, { recursive: true }).catch(() => {});
+      }
+    }
+  }
+}

package/src/app/createNexusApp.ts

@@ -0,0 +1,325 @@
+/**
+ * createNexusApp — opinionated bootstrap that wires a Nexus backend from
+ * conventional folders under src/.
+ *
+ * Discovers routes/, graphql/, ws/, mail/, errors/, events/, listeners/,
+ * jobs/, policies/, providers/, database/seeds+migrations, plugins/, and
+ * config/. Replaces manual wiring of Routers, GraphQL gateways, Realtime
+ * servers, etc.
+ *
+ * Usage:
+ *   import { createNexusApp } from '@bhooai/nexus-core';
+ *   const app = await createNexusApp({ name: 'backend-main' });
+ *   await app.listen();
+ */
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+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 type { Handler, Middleware } from '../http/context.js';
+import { discoverBackend, importDefault, type DiscoveryResult } from './discover.js';
+import type { RoutesFile, RouteDef } from './defineRoutes.js';
+import { DefaultErrorHandler, ErrorHandler } from './ErrorHandler.js';
+import { ErrorPages } from './errorPages.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';
+import { policyRegistry } from './policies.js';
+import { configureStorageFromEnv } from './Storage.js';
+import { maintenanceMiddleware } from './maintenance.js';
+
+export interface CreateNexusAppOptions {
+  /** Identifier for this backend, used in admin, telemetry, logs. */
+  name?: string;
+  /** Path to the backend src/ folder. Defaults to `<cwd>/src`. */
+  srcRoot?: string;
+  /** Project root (where .nexus-down and storage/ live). Defaults to srcRoot/.. */
+  projectRoot?: string;
+  /** Override the auto-discovered config (for tests). */
+  config?: NexusConfig;
+  /** Additional global middleware applied after built-ins. */
+  middleware?: Middleware[];
+  /** Manual route registrations in addition to routes/ discovery. */
+  additionalRoutes?: RouteDef[];
+  /** Custom queue adapter (default: InMemoryQueueAdapter). */
+  queueAdapter?: JobQueueAdapter;
+  /** Custom error handler (default: DefaultErrorHandler). */
+  errorHandler?: ErrorHandler;
+  /** Hooks for extending boot. */
+  beforeStart?: (app: NexusApp) => Promise<void> | void;
+  afterStart?: (app: NexusApp) => Promise<void> | void;
+}
+
+export interface NexusApp {
+  /** Backend identifier (from options.name). */
+  name: string;
+  /** Loaded config. */
+  config: NexusConfig;
+  /** DI container. */
+  container: Container;
+  /** HTTP router (mounted under /). */
+  router: Router;
+  /** HTTP server. */
+  server: NexusServer;
+  /** Discovery manifest — what was found under src/. */
+  discovery: DiscoveryResult;
+  /** Domain event bus for this app. */
+  events: EventBus;
+  /** Register an additional middleware after built-ins. */
+  use(mw: Middleware): this;
+  /** Register an additional route at runtime. */
+  route(def: RouteDef): this;
+  /** Start listening. Resolves when the server is bound. */
+  listen(): Promise<void>;
+  /** Graceful shutdown. */
+  close(): Promise<void>;
+}
+
+export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<NexusApp> {
+  const name = opts.name ?? 'backend';
+  const srcRoot = resolve(opts.srcRoot ?? resolve(process.cwd(), 'src'));
+  const projectRoot = resolve(opts.projectRoot ?? dirname(srcRoot));
+  let config = opts.config ?? (await loadConfigAuto({ root: projectRoot }));
+
+  // ------------------------------------------------------------------
+  // 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.
+  // ------------------------------------------------------------------
+  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 container = new Container();
+  const router = new Router();
+
+  // ------------------------------------------------------------------
+  // Discover convention folders
+  // ------------------------------------------------------------------
+  const discovery = await discoverBackend(srcRoot);
+
+  // ------------------------------------------------------------------
+  // Storage facade + queue + mail — always configured, even if minimal
+  // ------------------------------------------------------------------
+  configureStorageFromEnv(projectRoot, config.auth?.jwt?.secret ?? 'nexus-insecure');
+  configureQueue(opts.queueAdapter ?? new InMemoryQueueAdapter());
+  configureMailDriver(logMailDriver);
+  configureMailRenderer(async (templateName, data) => renderMailTemplate(projectRoot, templateName, data));
+
+  // ------------------------------------------------------------------
+  // Error pages + handler
+  // ------------------------------------------------------------------
+  const errorPages = new ErrorPages(projectRoot);
+  let errorHandler: ErrorHandler = opts.errorHandler ?? new DefaultErrorHandler();
+  if (discovery.errorHandler) {
+    try {
+      const custom = await importDefault<new () => ErrorHandler>(discovery.errorHandler);
+      if (typeof custom === 'function') errorHandler = new custom();
+    } catch (err) {
+      console.warn(`[${name}] failed to load errors/Handler.ts — falling back to DefaultErrorHandler:`, err);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Events + listeners auto-wire (convention: On<Foo> listens for <Foo>)
+  // ------------------------------------------------------------------
+  const events: EventBus = eventBus;
+  const eventsByName = new Map<string, unknown>();
+  for (const file of discovery.events) {
+    try {
+      const Evt = await importDefault(file);
+      eventsByName.set((Evt as { name?: string })?.name ?? file.name, Evt);
+    } catch { /* ignore bad event file */ }
+  }
+  for (const file of discovery.listeners) {
+    try {
+      const Lst = await importDefault<new () => Listener>(file);
+      if (typeof Lst !== 'function') continue;
+      // Convention: On<Foo> listens for <Foo>
+      const short = file.name.replace(/^On/, '');
+      const Evt = eventsByName.get(short);
+      if (Evt && typeof Evt === 'function') {
+        events.register(Lst, Evt as never);
+      }
+    } catch { /* ignore */ }
+  }
+
+  // ------------------------------------------------------------------
+  // Policies (per-resource registry)
+  // ------------------------------------------------------------------
+  for (const file of discovery.policies) {
+    try {
+      const Pol = await importDefault<new () => Record<string, unknown>>(file);
+      if (typeof Pol === 'function') {
+        // Without a ResourceCtor hint in the discovery file we can't fully
+        // auto-bind; users typically register manually inside the policy class.
+        // Skip auto-wire — explicit registration wins.
+        void Pol;
+      }
+    } catch { /* ignore */ }
+  }
+  void policyRegistry;
+
+  // ------------------------------------------------------------------
+  // Providers: register phase
+  // ------------------------------------------------------------------
+  const providerInstances: Array<{ register?: (c: Container) => void; boot?: (c: Container) => Promise<void> | void }> = [];
+  for (const file of discovery.providers) {
+    try {
+      const ProviderCtor = await importDefault<new () => { register?: (c: Container) => void; boot?: (c: Container) => Promise<void> | void }>(file);
+      if (typeof ProviderCtor !== 'function') continue;
+      const inst = new ProviderCtor();
+      providerInstances.push(inst);
+      if (typeof inst.register === 'function') inst.register(container);
+    } catch { /* ignore */ }
+  }
+
+  // ------------------------------------------------------------------
+  // Mount discovered routes
+  // ------------------------------------------------------------------
+  for (const file of discovery.routes) {
+    try {
+      const mod: any = await importDefault(file);
+      const routesFile: RoutesFile | undefined = mod && typeof mod === 'object' && 'routes' in mod ? mod : undefined;
+      if (!routesFile) continue;
+      const prefix = (routesFile.prefix ?? (mod as any)?.prefix ?? '') as string;
+      for (const def of routesFile.routes) {
+        registerRoute(router, def, prefix);
+      }
+    } catch (err) {
+      console.warn(`[${name}] failed to mount routes from ${file.path}:`, err);
+    }
+  }
+
+  for (const def of opts.additionalRoutes ?? []) registerRoute(router, def, '');
+
+  // ------------------------------------------------------------------
+  // Built-in: /health + /admin/_registry
+  // ------------------------------------------------------------------
+  router.get('/health', async (ctx) => {
+    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.
+  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
+    }
+    // Always include the current app if not listed
+    if (!apps.some((a) => a.name === name)) {
+      apps.unshift({ name, port: config.server.port, source: 'registry' });
+    }
+    ctx.json({ apps });
+  });
+
+  // ------------------------------------------------------------------
+  // HTTP server with error handler + maintenance middleware wired in
+  // ------------------------------------------------------------------
+  const server = new NexusServer({
+    router,
+    bodyLimit: config.server.bodyLimit,
+    trustProxy: config.server.trustProxy,
+    ...(config.server.https && config.server.certFile && config.server.keyFile
+      ? { certFile: config.server.certFile, keyFile: config.server.keyFile }
+      : {}),
+    onError: (err, ctx) => errorHandler.toApiError(err),
+  });
+
+  // Maintenance mode (checked first)
+  server.use(maintenanceMiddleware({ projectRoot }));
+
+  // User-supplied global middleware
+  for (const mw of opts.middleware ?? []) server.use(mw);
+
+  // ------------------------------------------------------------------
+  // Providers: boot phase
+  // ------------------------------------------------------------------
+  for (const inst of providerInstances) {
+    if (typeof inst.boot === 'function') await inst.boot(container);
+  }
+
+  const app: NexusApp = {
+    name,
+    config,
+    container,
+    router,
+    server,
+    discovery,
+    events,
+    use(mw) { server.use(mw); return this; },
+    route(def) { registerRoute(router, def, ''); return this; },
+    async listen() {
+      if (opts.beforeStart) await opts.beforeStart(app);
+      await server.listen(config.server.port, config.server.host);
+      if (opts.afterStart) await opts.afterStart(app);
+    },
+    async close() {
+      await server.close();
+    },
+  };
+
+  return app;
+}
+
+async function renderMailTemplate(
+  projectRoot: string,
+  templateName: string,
+  data: Record<string, unknown>,
+): Promise<{ html: string; text?: string }> {
+  const candidates = [
+    resolve(projectRoot, 'src', 'mail', 'templates', `${templateName}.ejs`),
+    resolve(projectRoot, 'src', 'mail', 'templates', `${templateName}.html`),
+    resolve(projectRoot, 'mail', 'templates', `${templateName}.ejs`),
+  ];
+  for (const cand of candidates) {
+    if (!existsSync(cand)) continue;
+    const raw = await readFile(cand, 'utf-8');
+    const html = substitute(raw, data);
+    return { html, text: stripTags(html) };
+  }
+  return { html: `<p>${templateName}</p>`, text: templateName };
+}
+
+function substitute(template: string, vars: Record<string, unknown>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_m, k: string) => {
+    const v = vars[k];
+    return v === undefined || v === null ? '' : String(v);
+  });
+}
+
+function stripTags(html: string): string {
+  return html.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function registerRoute(router: Router, def: RouteDef, prefix: string): void {
+  const full = normalizePath(prefix, def.path);
+  const mw: Middleware[] = [];
+  if (def.middleware) mw.push(...def.middleware);
+  // upload spec, rateLimit, etc. — wired in later phases
+  router.add(def.method, full, def.handler as Handler, mw);
+}
+
+function normalizePath(prefix: string, path: string): string {
+  const p = prefix.replace(/\/+$/, '');
+  const s = path.startsWith('/') ? path : `/${path}`;
+  return p ? `${p}${s}` : s;
+}
+
+export type { RoutesFile, RouteDef } from './defineRoutes.js';
+export { defineRoutes } from './defineRoutes.js';