@bhooai/nexus-cli 0.1.0

package/templates/apps/backend/src/modules/payments/paymentStore.ts

@@ -0,0 +1,172 @@
+/**
+ * Persistent store for payment orders + transactions.
+ *
+ * Orders are created/updated from the checkout routes (paymentRoutes.ts); raw
+ * provider webhook events are appended as transactions (main.ts). Both are
+ * exposed to the admin app under /admin/payments/*.
+ *
+ * Models register lazily on the default connection, so they work from both the
+ * app bootstrap and the admin routes regardless of call order.
+ */
+import { Schema, model, ObjectId, type DocumentInstance, type Model } from '@bhooai/nexus-data';
+import type { Order, WebhookEvent } from '@bhooai/nexus-payments';
+
+export interface OrderDoc {
+  _id?: ObjectId;
+  /** Provider name (razorpay, paypal, payu, skrill, payoneer). */
+  provider: string;
+  /** Provider order id (e.g. PayPal order id / Razorpay order id). */
+  orderId: string;
+  /** Merchant reference echoed back on the order. */
+  reference: string;
+  status: string;
+  amount: number;
+  currency: string;
+  paymentUrl?: string;
+  paymentId?: string;
+  customer?: Record<string, unknown>;
+  description?: string;
+  raw?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface TransactionDoc {
+  _id?: ObjectId;
+  provider: string;
+  /** Normalized event (e.g. "payment.captured", "refund.created"). */
+  event: string;
+  verified: boolean;
+  orderId?: string;
+  paymentId?: string;
+  amount?: number;
+  currency?: string;
+  status?: string;
+  raw?: Record<string, unknown>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export type OrderInstance = DocumentInstance & OrderDoc;
+export type TransactionInstance = DocumentInstance & TransactionDoc;
+
+const orderSchema = new Schema<OrderDoc>(
+  {
+    provider: { type: String, required: true },
+    orderId: { type: String, required: true },
+    reference: { type: String },
+    status: { type: String, default: 'created' },
+    amount: { type: Number },
+    currency: { type: String, default: 'USD' },
+    paymentUrl: { type: String },
+    paymentId: { type: String },
+    customer: { type: Object },
+    description: { type: String },
+    raw: { type: Object },
+  },
+  { timestamps: true, collection: 'payment_orders' },
+);
+orderSchema.indexes.push({ spec: { provider: 1, orderId: 1 }, options: { unique: true } });
+
+const transactionSchema = new Schema<TransactionDoc>(
+  {
+    provider: { type: String, required: true },
+    event: { type: String, required: true },
+    verified: { type: Boolean, default: false },
+    orderId: { type: String },
+    paymentId: { type: String },
+    amount: { type: Number },
+    currency: { type: String },
+    status: { type: String },
+    raw: { type: Object },
+  },
+  { timestamps: true, collection: 'payment_transactions' },
+);
+transactionSchema.indexes.push({ spec: { createdAt: -1 }, options: {} });
+
+let Order: OrderModel | undefined;
+let Transaction: TransactionModel | undefined;
+
+/** Register both payment models on the default connection (idempotent). */
+export function initPaymentModels(): void {
+  if (Transaction) return;
+  Order = model<OrderInstance>('PaymentOrder', orderSchema);
+  Transaction = model<TransactionInstance>('PaymentTransaction', transactionSchema);
+}
+
+export function getOrderModel(): Model<OrderInstance> {
+  if (!Order) initPaymentModels();
+  if (!Order) throw new Error('Payment order model unavailable');
+  return Order;
+}
+
+export function getTransactionModel(): Model<TransactionInstance> {
+  if (!Transaction) initPaymentModels();
+  if (!Transaction) throw new Error('Payment transaction model unavailable');
+  return Transaction;
+}
+
+/** Upsert an order from a provider response so we always keep the latest status. */
+export async function upsertOrder(
+  order: Order,
+  provider: string,
+  meta: { customer?: Record<string, unknown>; description?: string } = {},
+): Promise<void> {
+  await getOrderModel().findOneAndUpdate(
+    { provider, orderId: order.id },
+    {
+      $set: {
+        provider,
+        orderId: order.id,
+        reference: order.reference,
+        status: order.status,
+        amount: order.amount,
+        currency: order.currency,
+        paymentUrl: order.paymentUrl ?? null,
+        paymentId: order.paymentId ?? null,
+        customer: meta.customer ?? null,
+        description: meta.description ?? null,
+        raw: order.raw ?? null,
+      },
+    },
+    { upsert: true },
+  );
+}
+
+/** Append a normalized webhook event as a transaction. */
+export async function recordTransaction(provider: string, event: WebhookEvent): Promise<void> {
+  const data = (event.data ?? {}) as Record<string, unknown>;
+  const fields: Record<string, unknown> = {
+    provider,
+    event: event.event ?? 'unknown',
+    verified: !!event.verified,
+    orderId: firstStr(data, 'orderId', 'order_id', 'orderReference'),
+    paymentId: firstStr(data, 'paymentId', 'payment_id', 'id'),
+    amount: firstNum(data, 'amount', 'gross_amount', 'total_paid'),
+    currency: firstStr(data, 'currency'),
+    status: firstStr(data, 'status', 'payment_status', 'state'),
+    raw: data,
+  };
+  await getTransactionModel().create(fields);
+}
+
+function firstStr(data: Record<string, unknown>, ...keys: string[]): string | undefined {
+  for (const k of keys) {
+    const v = data[k];
+    if (typeof v === 'string' && v.length) return v;
+    if (typeof v === 'number') return String(v);
+  }
+  return undefined;
+}
+
+function firstNum(data: Record<string, unknown>, ...keys: string[]): number | undefined {
+  for (const k of keys) {
+    const v = data[k];
+    if (typeof v === 'number') return v;
+    if (typeof v === 'string' && !Number.isNaN(Number(v))) return Number(v);
+  }
+  return undefined;
+}
+
+export type OrderModel = Model<OrderInstance>;
+export type TransactionModel = Model<TransactionInstance>;

package/templates/apps/backend/src/modules/requests/requestLog.ts

@@ -0,0 +1,175 @@
+import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { WriteStream } from 'node:fs';
+
+/**
+ * Datewise, append-only HTTP request log.
+ *
+ * Each request is written as a single JSON line to a date-stamped file
+ * (`requests-YYYY-MM-DD.log`) inside the project's logging dir, so a day's
+ * traffic is easy to inspect and long ranges can be aggregated on the fly.
+ *
+ * Written by the backend request middleware (main.ts) and read by the admin
+ * endpoints under /admin/requests (adminRoutes.ts).
+ */
+
+export interface RequestLogEntry {
+  time: number;
+  method: string;
+  path: string;
+  url?: string;
+  status: number;
+  durationMs: number;
+  ip?: string;
+  referer?: string;
+  userAgent?: string;
+  origin?: string;
+  requestId?: string;
+  route?: string;
+}
+
+export type RequestSeriesRange = 'today' | '5d' | 'week' | 'month' | 'year';
+
+export interface RequestSeries {
+  range: RequestSeriesRange;
+  bucketMs: number;
+  start: number;
+  end: number;
+  total: number;
+  points: Array<{ t: number; count: number }>;
+}
+
+let stream: WriteStream | null = null;
+let streamDate = '';
+let streamDir = '';
+
+function dateKey(d = new Date()): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+function fileNameFor(date: string): string {
+  return `requests-${date}.log`;
+}
+
+function ensureStream(dir: string, date: string): WriteStream {
+  if (stream && streamDate === date && streamDir === dir) return stream;
+  if (stream) {
+    stream.end();
+    stream = null;
+  }
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  stream = createWriteStream(join(dir, fileNameFor(date)), { flags: 'a' });
+  stream.on('error', () => {
+    stream = null;
+  });
+  streamDate = date;
+  streamDir = dir;
+  return stream;
+}
+
+/** Append one JSON line for a completed request. Safe to call from the hot path. */
+export function appendRequestLog(dir: string, entry: RequestLogEntry): void {
+  try {
+    ensureStream(dir, dateKey()).write(JSON.stringify(entry) + '\n');
+  } catch {
+    // never let logging break the request path
+  }
+}
+
+/** Close the active stream (used on shutdown). */
+export function closeRequestLog(): void {
+  if (stream) {
+    stream.end();
+    stream = null;
+  }
+}
+
+function listLogFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => /^requests-\d{4}-\d{2}-\d{2}\.log$/.test(f))
+    .sort();
+}
+
+function fileDate(file: string): number {
+  const match = /^requests-(\d{4}-\d{2}-\d{2})\.log$/.exec(file);
+  if (!match) return 0;
+  return Date.parse(match[1]);
+}
+
+function readEntries(dir: string, from: number): RequestLogEntry[] {
+  const out: RequestLogEntry[] = [];
+  for (const file of listLogFiles(dir)) {
+    if (fileDate(file) < from) continue;
+    let text: string;
+    try {
+      text = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line) as RequestLogEntry;
+        if (typeof e.time === 'number' && e.time >= from) out.push(e);
+      } catch {
+        // skip malformed lines
+      }
+    }
+  }
+  return out;
+}
+
+const RANGE_PARAMS: Record<RequestSeriesRange, { bucketMs: number; back: number }> = {
+  today: { bucketMs: 5 * 60_000, back: 24 * 60 * 60_000 },
+  '5d': { bucketMs: 60 * 60_000, back: 5 * 24 * 60 * 60_000 },
+  week: { bucketMs: 6 * 60 * 60_000, back: 7 * 24 * 60 * 60_000 },
+  month: { bucketMs: 24 * 60 * 60_000, back: 31 * 24 * 60 * 60_000 },
+  year: { bucketMs: 7 * 24 * 60 * 60_000, back: 365 * 24 * 60 * 60_000 },
+};
+
+/** Aggregate request logs into coarse buckets for the requested range. */
+export function readRequestSeries(dir: string, range: RequestSeriesRange): RequestSeries {
+  const { bucketMs, back } = RANGE_PARAMS[range];
+  const end = Date.now();
+  const start = end - back;
+  const entries = readEntries(dir, start);
+  const buckets = new Map<number, number>();
+  let total = 0;
+  for (const e of entries) {
+    const idx = Math.floor((e.time - start) / bucketMs);
+    buckets.set(idx, (buckets.get(idx) ?? 0) + 1);
+    total += 1;
+  }
+  const points = [...buckets.entries()]
+    .map(([idx, count]) => ({ t: start + idx * bucketMs, count }))
+    .sort((a, b) => a.t - b.t);
+  return { range, bucketMs, start, end, total, points };
+}
+
+/** Tail the newest request entries, reading back across days to satisfy the limit. */
+export function tailRequestLogs(dir: string, limit: number): RequestLogEntry[] {
+  const out: RequestLogEntry[] = [];
+  const files = listLogFiles(dir).reverse();
+  for (const file of files) {
+    if (out.length >= limit) break;
+    try {
+      const text = readFileSync(join(dir, file), 'utf8');
+      const lines = text.split('\n').filter((l) => l.trim());
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          out.push(JSON.parse(lines[i]) as RequestLogEntry);
+        } catch {
+          // skip
+        }
+        if (out.length >= limit) break;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}

package/templates/apps/backend/src/modules/users/userGraph.ts

@@ -0,0 +1,83 @@
+import { defineSubgraph, type Resolvers, type GraphQLContext, type EntityRepresentation } from '@bhooai/nexus-graphql';
+import { getUserModel } from './userModel.js';
+
+/**
+ * Users subgraph (single-subgraph Phase 5). Exposes User as a federation
+ * entity (`@key(fields: "id")`) plus `me`/`user`/`users` queries. Resolvers
+ * use the User ODM model. `me` requires an authenticated context (`ctx.user.sub`).
+ */
+const typeDefs = /* graphql */ `
+  type User @key(fields: "id") {
+    id: ID!
+    email: String!
+    name: String
+    roles: [String!]!
+    emailVerified: Boolean!
+    createdAt: String
+    updatedAt: String
+  }
+
+  type Query {
+    me: User
+    user(id: ID!): User
+    users(limit: Int = 50): [User!]!
+  }
+
+  type Subscription {
+    userCount: Int!
+  }
+`;
+
+function toGraphUser(doc: any): Record<string, unknown> | null {
+  if (!doc) return null;
+  const obj = doc.toObject ? doc.toObject() : doc;
+  return {
+    id: String(obj._id ?? obj.id),
+    email: obj.email,
+    name: obj.name ?? null,
+    roles: obj.roles ?? [],
+    emailVerified: obj.emailVerified ?? false,
+    createdAt: obj.createdAt ? new Date(obj.createdAt).toISOString() : null,
+    updatedAt: obj.updatedAt ? new Date(obj.updatedAt).toISOString() : null,
+  };
+}
+
+export function buildUsersSubgraph() {
+  const resolvers: Resolvers = {
+    Query: {
+      me: async (_parent, _args, ctx: GraphQLContext) => {
+        if (!ctx.user?.sub) return null;
+        const User = getUserModel();
+        const doc = await User.findById(ctx.user.sub).lean();
+        return toGraphUser(doc);
+      },
+      user: async (_parent, args: { id: string }) => {
+        const User = getUserModel();
+        return toGraphUser(await User.findById(args.id).lean());
+      },
+      users: async (_parent, args: { limit: number }) => {
+        const User = getUserModel();
+        const docs = await User.find().limit(args.limit ?? 50).lean();
+        return docs.map(toGraphUser);
+      },
+    },
+    Subscription: {
+      // The payload is the new count; the host publishes 'USER_COUNT' after a
+      // user is created. ctx.pubsub is injected by main.ts (HTTP + WS contexts).
+      userCount: {
+        subscribe: (_parent, _args, ctx: GraphQLContext) => (ctx.pubsub as any).asyncIterator('USER_COUNT'),
+        resolve: async () => {
+          const User = getUserModel();
+          return await User.countDocuments();
+        },
+      },
+    },
+  };
+
+  const entityResolver = async (rep: EntityRepresentation) => {
+    const User = getUserModel();
+    return toGraphUser(await User.findById(String(rep.id)).lean());
+  };
+
+  return defineSubgraph({ name: 'users', typeDefs, resolvers, entityResolver });
+}

package/templates/apps/backend/src/modules/users/userModel.ts

@@ -0,0 +1,88 @@
+import { Schema, model, ObjectId, type DocumentInstance, type Model } from '@bhooai/nexus-data';
+
+/** Persisted user document. `passwordHash` is select:false so it is excluded from normal queries. */
+export interface UserDoc {
+  _id?: ObjectId;
+  email: string;
+  passwordHash?: string;
+  name?: string;
+  roles: string[];
+  emailVerified: boolean;
+  /** Linked OAuth identities (for account linking). */
+  oauthAccounts: Array<{ provider: string; providerUserId: string }>;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export type UserInstance = DocumentInstance & UserDoc;
+export type UserModel = Model<UserInstance>;
+
+export const userSchema = new Schema<UserDoc>(
+  {
+    email: { type: String, required: true, unique: true, match: /.+@.+\..+/, transform: (v) => String(v).toLowerCase() },
+    passwordHash: { type: String, select: false },
+    name: { type: String },
+    roles: { type: [String], default: () => ['user'] },
+    emailVerified: { type: Boolean, default: false },
+    oauthAccounts: { type: Array, default: () => [] },
+  },
+  { timestamps: true, collection: 'users' },
+);
+
+let User: UserModel | undefined;
+
+/** Register the User model on the default connection (call after `connect()`). */
+export function initUserModel(): UserModel {
+  if (User) return User;
+  User = model<UserInstance>('User', userSchema);
+  return User;
+}
+
+export function getUserModel(): UserModel {
+  if (!User) throw new Error('User model not initialized — call initUserModel() after connect().');
+  return User;
+}
+
+/** Fetch a user by email INCLUDING the select:false passwordHash (raw driver lookup). */
+export async function findUserForLogin(email: string): Promise<UserInstance | null> {
+  const User = getUserModel();
+  const coll = await User.collection;
+  const raw = await coll.findOne({ email: String(email).toLowerCase() });
+  return raw ? (User.hydrate(raw) as UserInstance) : null;
+}
+
+/** Find-or-create a user from an OAuth profile (account linking by provider+id). */
+export async function upsertOAuthUser(profile: {
+  provider: string;
+  providerUserId: string;
+  email?: string;
+  name?: string;
+}): Promise<UserInstance> {
+  const User = getUserModel();
+  const coll = await User.collection;
+  const existing = await coll.findOne({
+    oauthAccounts: { $elemMatch: { provider: profile.provider, providerUserId: profile.providerUserId } },
+  });
+  if (existing) return User.hydrate(existing) as UserInstance;
+
+  // Link to an existing email account if present, else create a new one.
+  if (profile.email) {
+    const byEmail = await coll.findOne({ email: profile.email.toLowerCase() });
+    if (byEmail) {
+      await User.updateOne({ _id: byEmail._id }, {
+        $addToSet: { oauthAccounts: { provider: profile.provider, providerUserId: profile.providerUserId } },
+      });
+      const refreshed = await coll.findOne({ _id: byEmail._id });
+      return User.hydrate(refreshed!) as UserInstance;
+    }
+  }
+
+  const [created] = await User.create({
+    email: profile.email ?? `${profile.provider}-${profile.providerUserId}@oauth.local`,
+    name: profile.name,
+    emailVerified: true,
+    oauthAccounts: [{ provider: profile.provider, providerUserId: profile.providerUserId }],
+    roles: ['user'],
+  });
+  return created;
+}

package/templates/apps/backend/src/plugins/CronScheduler.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal in-process cron scheduler for plugins. Supports a subset of 5-field
+ * cron at minute resolution: star, star-slash-N (every N minutes), and specific
+ * numbers for each field. Honest v1 subset — full cron (ranges, lists, L/W) is
+ * Phase 12.
+ */
+interface Job {
+  name: string;
+  cron: string;
+  fn: () => void | Promise<void>;
+  parts: number[]; // [minute, hour, dom, month, dow] matcher encoded as -1 = any, else value (step handled inline)
+  step: number; // minute step for */N, else 0
+}
+
+function parseField(field: string, min: number, max: number): { value: number; step: number } {
+  if (field === '*') return { value: -1, step: 0 };
+  const m = /^\*\/(\d+)$/.exec(field);
+  if (m) return { value: -1, step: Number(m[1]) };
+  return { value: Number(field), step: 0 };
+}
+
+export class CronScheduler {
+  private jobs = new Map<string, Job>();
+  private timer: NodeJS.Timeout | null = null;
+
+  schedule(name: string, cron: string, fn: () => void | Promise<void>): void {
+    const [min, hour, dom, month, dow] = cron.trim().split(/\s+/);
+    const mf = parseField(min!, 0, 59);
+    const hf = parseField(hour!, 0, 23);
+    this.jobs.set(name, {
+      name, cron, fn,
+      parts: [hf.value, parseField(dom!, 1, 31).value, parseField(month!, 1, 12).value, parseField(dow!, 0, 6).value],
+      step: mf.step,
+    });
+    if (this.jobs.size === 1) this.start();
+  }
+
+  cancel(name: string): void {
+    this.jobs.delete(name);
+    if (this.jobs.size === 0 && this.timer) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  private start(): void {
+    this.timer = setInterval(() => this.tick(), 60_000);
+  }
+
+  private async tick(): Promise<void> {
+    const now = new Date();
+    for (const job of this.jobs.values()) {
+      const [hour, dom, month, dow] = job.parts;
+      const m = now.getMinutes();
+      // minute: */N matches when m % step === 0; specific value matches equality; '*' always.
+      const minOk = job.step > 0 ? m % job.step === 0 : true; // step 0 → '*' → any minute
+      if (!minOk) continue;
+      if (hour !== -1 && hour !== now.getHours()) continue;
+      if (month !== -1 && month !== now.getMonth() + 1) continue;
+      if (dom !== -1 && dom !== now.getDate()) continue;
+      if (dow !== -1 && dow !== now.getDay()) continue;
+      try { await job.fn(); } catch { /* swallow job errors */ }
+    }
+  }
+
+  close(): void {
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+    this.jobs.clear();
+  }
+
+  has(name: string): boolean { return this.jobs.has(name); }
+}

package/templates/apps/backend/src/plugins/loadPlugins.ts

@@ -0,0 +1,107 @@
+import { join, resolve } from 'node:path';
+import { PluginHost, AdminExtensions, HookBus, ServiceContainer, type HostBindings } from '@bhooai/nexus-plugins';
+import type { Router } from '@bhooai/nexus-core';
+import type { Logger } from '@bhooai/nexus-telemetry';
+import type { RealtimeServer } from '@bhooai/nexus-realtime';
+import { CronScheduler } from './CronScheduler.js';
+
+export interface LoadPluginsDeps {
+  router: Router;
+  log: Logger;
+  realtime: RealtimeServer;
+  pluginsDir: string;
+  /** Map of plugin name → config, merged from nexus.config plugins.entries. */
+  configByPlugin?: Record<string, unknown>;
+  /** sandbox limits by plugin name. */
+  limitsByPlugin?: Record<string, unknown>;
+}
+
+export interface LoadedPlugins {
+  host: PluginHost;
+  adminExtensions: AdminExtensions;
+  hookBus: HookBus;
+  services: ServiceContainer;
+  scheduler: CronScheduler;
+}
+
+/**
+ * Build real HostBindings backed by the running services, discover + load
+ * plugins from the plugins dir, and run install → init → start in dependency
+ * order. Returns handles the app keeps for shutdown + admin rendering.
+ */
+export async function loadPlugins(deps: LoadPluginsDeps): Promise<LoadedPlugins> {
+  const { router, log, realtime, pluginsDir } = deps;
+  const adminExtensions = new AdminExtensions();
+  const hookBus = new HookBus();
+  const services = new ServiceContainer();
+  const scheduler = new CronScheduler();
+
+  const pluginLog = log.child({ component: 'plugins' });
+  const bindings: HostBindings = {
+    http: {
+      addRoute: (method, path, handler) => { router.add(method, path, handler); },
+      addMiddleware: (mw, phase) => { router.use(mw); },
+    },
+    graphql: {
+      // Runtime subgraph recompose + hot-swap is a Phase 12 hardening item; in v1
+      // trusted plugins add subgraphs at boot via the gateway builder. Calling
+      // addSubgraph at runtime logs a notice rather than recomposing the live gateway.
+      addSubgraph: async (sg) => { pluginLog.warn('runtime graphql.addSubgraph deferred to Phase 12', { subgraph: sg.name }); },
+      removeSubgraph: async (name) => { pluginLog.warn('runtime graphql.removeSubgraph deferred to Phase 12', { subgraph: name }); },
+    },
+    data: {
+      registerModel: (_n, _s) => { pluginLog.warn('plugin data.registerModel is a v1 stub (models register via nexus-data directly)'); return undefined; },
+      getModel: (n) => { pluginLog.warn('plugin data.getModel is a v1 stub', { model: n }); return undefined; },
+    },
+    realtime: {
+      join: (_room, _connId) => { /* plugins don't join on behalf of connections in v1 */ },
+      broadcast: (room, msg) => { (realtime as any).broadcastRoom?.(room, { type: 'broadcast', room, event: 'plugin', data: msg }); },
+    },
+    scheduler: {
+      schedule: (name, cron, fn) => scheduler.schedule(name, cron, fn),
+      cancel: (name) => scheduler.cancel(name),
+    },
+    events: {
+      publish: (topic, payload) => hookBus.publish(topic, payload),
+      subscribe: (topic, handler) => hookBus.subscribe(topic, handler),
+    },
+    admin: {
+      registerAdminPage: (page) => adminExtensions.registerPage('<plugin>', page),
+      registerSlot: (slot) => adminExtensions.registerSlot('<plugin>', slot),
+    },
+    services: {
+      register: (name, svc) => services.register(name, svc),
+      get: (name) => services.get(name),
+    },
+    config: {
+      get: (pluginName) => deps.configByPlugin?.[pluginName],
+      set: (_pluginName, _cfg) => { /* admin writes nexus.runtime.json, not here */ },
+    },
+    logger: {
+      child: (meta) => {
+        const child = pluginLog.child(meta);
+        return {
+          info: (m: string, _meta?: unknown) => child.info(m),
+          warn: (m: string, _meta?: unknown) => child.warn(m),
+          error: (m: string, _meta?: unknown) => child.error(m),
+        };
+      },
+    },
+  };
+
+  const host = new PluginHost(bindings, resolve(pluginsDir));
+  const order = await host.load(deps.configByPlugin ?? {}, deps.limitsByPlugin ?? {});
+  if (order.length === 0) {
+    pluginLog.info('no plugins found', { dir: pluginsDir });
+    return { host, adminExtensions, hookBus, services, scheduler };
+  }
+  pluginLog.info('plugins loaded', { order });
+  await host.install();
+  await host.init();
+  await host.start();
+  pluginLog.info('plugins started', { count: order.length });
+
+  // Patch admin page/slot registration to attribute by plugin name: the host
+  // can't easily know which plugin issued each call, so we re-walk handles.
+  return { host, adminExtensions, hookBus, services, scheduler };
+}