bhooai-nexus 0.1.2

package/packages/nexus-plugins/src/host.ts

@@ -0,0 +1,105 @@
+import type { Capability, PluginManifest } from './manifest.js';
+
+/** Admin extension specs a plugin can register (consumed by the admin app). */
+export interface AdminPageSpec {
+  /** Route path in the admin app, e.g. "/plugins/analytics". */
+  path: string;
+  /** Nav label. */
+  title: string;
+  /** Slot group this page belongs to (for nav grouping). */
+  group?: string;
+  /** Optional icon name. */
+  icon?: string;
+  /** Optional order within its group. */
+  order?: number;
+}
+
+export interface SlotSpec {
+  /** Named insertion point in the admin UI, e.g. "dashboard:top". */
+  slot: string;
+  /** Component/module the admin should render there. */
+  component: string;
+  /** Optional ordering. */
+  order?: number;
+}
+
+/** A scheduler job descriptor. */
+export interface ScheduledJob {
+  name: string;
+  cron: string;
+}
+
+/**
+ * Host bindings — the actual implementation the app provides for each registrar.
+ * The plugin context (trusted or sandboxed) delegates to these. Sandbox mode
+ * intercepts calls to enforce capability policy before reaching the bindings.
+ *
+ * `ctx` params are deliberately `any` (the host's RequestContext type lives in
+ * nexus-core; plugins should not import it directly — they receive a
+ * PluginRequest via the sandbox proxy).
+ */
+export interface HostBindings {
+  http: {
+    addRoute(method: string, path: string, handler: (ctx: any) => void | Promise<void>): void;
+    addMiddleware(mw: (ctx: any, next: () => Promise<void>) => Promise<void>, phase?: 'before-route' | 'after-route'): void;
+  };
+  graphql: {
+    addSubgraph(subgraph: { name: string; typeDefs: string; resolvers: unknown }): Promise<void>;
+    removeSubgraph(name: string): Promise<void>;
+  };
+  data: { registerModel(name: string, schema: unknown): unknown; getModel(name: string): unknown };
+  realtime: { join(room: string, connId: string): void; broadcast(room: string, msg: unknown): void };
+  scheduler: { schedule(name: string, cron: string, fn: () => void | Promise<void>): void; cancel(name: string): void };
+  events: { publish(topic: string, payload: unknown): void; subscribe(topic: string, handler: (payload: unknown) => void): () => void };
+  admin: { registerAdminPage(page: AdminPageSpec): void; registerSlot(slot: SlotSpec): void };
+  services: { register(name: string, svc: unknown): void; get(name: string): unknown };
+  config: { get(pluginName: string): unknown; set(pluginName: string, cfg: unknown): void };
+  logger: { child(meta: Record<string, unknown>): { info(m: string, meta?: unknown): void; warn(m: string, meta?: unknown): void; error(m: string, meta?: unknown): void } };
+}
+
+/** The facade a plugin's lifecycle functions receive. */
+export interface PluginContext {
+  readonly pluginName: string;
+  readonly capabilities: Capability[];
+  readonly config: unknown;
+  readonly logger: { info(m: string, meta?: unknown): void; warn(m: string, meta?: unknown): void; error(m: string, meta?: unknown): void };
+  http: {
+    addRoute(method: string, path: string, handler: (ctx: any) => void | Promise<void>): void;
+    addMiddleware(mw: (ctx: any, next: () => Promise<void>) => Promise<void>, phase?: 'before-route' | 'after-route'): void;
+  };
+  graphql: { addSubgraph(subgraph: { name: string; typeDefs: string; resolvers: unknown }): Promise<void> };
+  data: { registerModel(name: string, schema: unknown): unknown; getModel(name: string): unknown };
+  realtime: { join(room: string, connId: string): void; broadcast(room: string, msg: unknown): void };
+  scheduler: { schedule(name: string, cron: string, fn: () => void | Promise<void>): void; cancel(name: string): void };
+  events: { publish(topic: string, payload: unknown): void; subscribe(topic: string, handler: (payload: unknown) => void): () => void };
+  admin: { registerAdminPage(page: AdminPageSpec): void; registerSlot(slot: SlotSpec): void };
+  services: { register(name: string, svc: unknown): void; get(name: string): unknown };
+  /** Filesystem access (only if 'fs' capability granted; sandboxed: allowlisted paths). */
+  fs?: { readFile(path: string): Promise<Buffer | string>; writeFile(path: string, data: string | Buffer): Promise<void> };
+  /** Network access (only if 'net' capability granted; sandboxed: allowlisted hosts). */
+  net?: { fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{ status: number; body: string }> };
+}
+
+/** Plugin module shape: a default export factory returning lifecycle handlers. */
+export interface PluginModule {
+  install?(ctx: PluginContext): Promise<void> | void;
+  init?(ctx: PluginContext): Promise<void> | void;
+  start?(ctx: PluginContext): Promise<void> | void;
+  /** Called when the plugin's runtime config changes. */
+  onConfigChange?(ctx: PluginContext, newConfig: unknown): Promise<void> | void;
+  stop?(ctx: PluginContext): Promise<void> | void;
+}
+
+/** A loaded plugin handle. */
+export interface PluginHandle {
+  manifest: PluginManifest;
+  state: 'loaded' | 'installed' | 'initialized' | 'started' | 'stopped' | 'errored';
+  install(): Promise<void>;
+  init(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /** Push a config change (re-validates + calls onConfigChange). */
+  updateConfig(cfg: unknown): Promise<void>;
+  /** Terminate the plugin (stop + for sandboxed, terminate the worker). */
+  unload(): Promise<void>;
+}

package/packages/nexus-plugins/src/index.ts

@@ -0,0 +1,8 @@
+export * from './manifest.js';
+export * from './HookBus.js';
+export * from './host.js';
+export * from './runtime/TrustedPlugin.js';
+export * from './sandbox/SandboxedPlugin.js';
+export * from './sandbox/capabilityPolicy.js';
+export * from './registry.js';
+export * from './admin/adminExtensions.js';

package/packages/nexus-plugins/src/manifest.ts

@@ -0,0 +1,73 @@
+/** Plugin manifest + capabilities. */
+
+/** A capability grants access to a host registrar or resource. */
+export type Capability =
+  | 'http' // register routes/middleware
+  | 'graphql' // add a subgraph
+  | 'data' // ODM models
+  | 'auth' // auth helpers
+  | 'realtime' // rooms/pubsub
+  | 'scheduler' // cron-style jobs
+  | 'events' // cross-plugin event bus
+  | 'admin' // admin pages/slots
+  | 'fs' // filesystem (allowlisted paths)
+  | 'net'; // network (allowlisted hosts)
+
+export const ALL_CAPABILITIES: Capability[] = [
+  'http', 'graphql', 'data', 'auth', 'realtime', 'scheduler', 'events', 'admin', 'fs', 'net',
+];
+
+/** Lifecycle hooks a plugin can implement. */
+export type LifecycleHook = 'install' | 'init' | 'start' | 'config:change' | 'stop';
+export const LIFECYCLE_HOOKS: LifecycleHook[] = ['install', 'init', 'start', 'config:change', 'stop'];
+
+export interface PluginManifest {
+  /** Unique plugin name (kebab-case). */
+  name: string;
+  /** Semver version. */
+  version: string;
+  /** Entry module path relative to the plugin dir, e.g. "index.js". */
+  entry: string;
+  /** 'trusted' runs in-process with full Node API; 'sandboxed' runs in a worker_thread. */
+  mode: 'trusted' | 'sandboxed';
+  /** Capabilities this plugin requests. Sandbox mode gates every registrar by these. */
+  capabilities: Capability[];
+  /** Optional JSON schema for the plugin's config (validated before init). */
+  configSchema?: Record<string, unknown>;
+  /** Lifecycle hooks the plugin implements (for documentation/manifest validation). */
+  hooks?: LifecycleHook[];
+  /** Other plugin names that must start first (topological ordering). */
+  dependencies?: string[];
+}
+
+/** Per-plugin sandbox limits (sandboxed mode only). */
+export interface SandboxLimits {
+  /** node:worker_threads resourceLimits. */
+  resourceLimits?: {
+    maxOldGenerationSizeMb?: number;
+    maxYoungGenerationSizeMb?: number;
+    codeRangeSizeMb?: number;
+    stackSizeMb?: number;
+  };
+  /** Heartbeat interval (ms); if a beat is missed within `heartbeatTimeoutMs` the worker is killed. */
+  heartbeatMs?: number;
+  heartbeatTimeoutMs?: number;
+  /** Filesystem paths the plugin may access (when 'fs' capability is granted). */
+  fsAllowPaths?: string[];
+  /** Hostnames the plugin may reach (when 'net' capability is granted). */
+  netAllowHosts?: string[];
+}
+
+/** Validate a manifest's shape; throws on missing/invalid fields. */
+export function validateManifest(m: PluginManifest): void {
+  if (!m.name || !/^[a-z0-9-]+$/.test(m.name)) throw new Error(`[nexus-plugins] invalid manifest name: ${m.name}`);
+  if (!m.version) throw new Error(`[nexus-plugins] manifest version required`);
+  if (m.mode !== 'trusted' && m.mode !== 'sandboxed') throw new Error(`[nexus-plugins] manifest mode must be trusted|sandboxed`);
+  if (!m.entry) throw new Error(`[nexus-plugins] manifest entry required`);
+  for (const c of m.capabilities ?? []) {
+    if (!ALL_CAPABILITIES.includes(c)) throw new Error(`[nexus-plugins] unknown capability: ${c}`);
+  }
+  for (const dep of m.dependencies ?? []) {
+    if (typeof dep !== 'string' || !dep.trim()) throw new Error(`[nexus-plugins] invalid dependency`);
+  }
+}

package/packages/nexus-plugins/src/registry.ts

@@ -0,0 +1,123 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { PluginManifest } from './manifest.js';
+import { validateManifest } from './manifest.js';
+import type { PluginHandle, HostBindings } from './host.js';
+import { TrustedPlugin } from './runtime/TrustedPlugin.js';
+import { SandboxedPlugin } from './sandbox/SandboxedPlugin.js';
+
+/**
+ * PluginHost: loads plugin manifests from a directory, constructs the right handle
+ * (trusted in-process vs sandboxed worker), orders them topologically by their
+ * declared `dependencies`, and drives the install → init → start → stop lifecycle
+ * in that order. Reload supports updating config and (for sandboxed) restarting.
+ */
+export class PluginHost {
+  private handles = new Map<string, PluginHandle>();
+  private readonly bindings: HostBindings;
+  private readonly pluginsDir: string;
+  private loadOrder: string[] = [];
+
+  constructor(bindings: HostBindings, pluginsDir: string) {
+    this.bindings = bindings;
+    this.pluginsDir = pluginsDir;
+  }
+
+  /** Discover and load (but not start) all plugins. Returns the load order. */
+  async load(configByPlugin: Record<string, unknown> = {}, limitsByPlugin: Record<string, unknown> = {}): Promise<string[]> {
+    let entries: string[] = [];
+    try { entries = await readdir(this.pluginsDir); } catch { /* no plugins dir */ }
+
+    const manifests = new Map<string, { manifest: PluginManifest; dir: string }>();
+    for (const entry of entries) {
+      const dir = join(this.pluginsDir, entry);
+      let isDir = false;
+      try { isDir = (await stat(dir)).isDirectory(); } catch { continue; }
+      if (!isDir) continue;
+      let raw: string;
+      try { raw = await readFile(join(dir, 'plugin.json'), 'utf8'); } catch { continue; }
+      const manifest = JSON.parse(raw) as PluginManifest;
+      validateManifest(manifest);
+      manifests.set(manifest.name, { manifest, dir });
+    }
+
+    this.loadOrder = this.topoSort(manifests);
+
+    for (const name of this.loadOrder) {
+      const { manifest, dir } = manifests.get(name)!;
+      const cfg = configByPlugin[name];
+      if (manifest.mode === 'trusted') {
+        this.handles.set(name, new TrustedPlugin(manifest, dir, this.bindings, cfg));
+      } else {
+        this.handles.set(name, new SandboxedPlugin(manifest, dir, this.bindings, cfg, (limitsByPlugin[name] ?? {}) as any));
+      }
+    }
+    return this.loadOrder;
+  }
+
+  /** Topologically sort manifest names by `dependencies`. Throws on cycles/missing deps. */
+  private topoSort(manifests: Map<string, { manifest: PluginManifest }>): string[] {
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+    const out: string[] = [];
+    const visit = (name: string) => {
+      if (visited.has(name)) return;
+      if (visiting.has(name)) throw new Error(`[nexus-plugins] dependency cycle at ${name}`);
+      const entry = manifests.get(name);
+      if (!entry) throw new Error(`[nexus-plugins] missing dependency target: ${name}`);
+      visiting.add(name);
+      for (const dep of entry.manifest.dependencies ?? []) visit(dep);
+      visiting.delete(name);
+      visited.add(name);
+      out.push(name);
+    };
+    for (const name of manifests.keys()) visit(name);
+    return out;
+  }
+
+  /** Run a lifecycle hook across all plugins in dependency order. */
+  async runLifecycle(hook: 'install' | 'init' | 'start' | 'stop'): Promise<void> {
+    const order = hook === 'stop' ? [...this.loadOrder].reverse() : this.loadOrder;
+    for (const name of order) {
+      const handle = this.handles.get(name)!;
+      try {
+        await handle[hook]();
+      } catch (err: any) {
+        handle.state = 'errored';
+        this.bindings.logger.child({ plugin: name }).error(`lifecycle ${hook} failed`, { error: String(err?.message ?? err) });
+        throw new Error(`[nexus-plugins] ${name} failed during ${hook}: ${err?.message ?? err}`);
+      }
+    }
+  }
+
+  async install(): Promise<void> { return this.runLifecycle('install'); }
+  async init(): Promise<void> { return this.runLifecycle('init'); }
+  async start(): Promise<void> { return this.runLifecycle('start'); }
+
+  async stop(): Promise<void> {
+    // Stop in reverse dependency order; never throw — best-effort shutdown.
+    const order = [...this.loadOrder].reverse();
+    for (const name of order) {
+      try { await this.handles.get(name)?.stop(); } catch { /* swallow */ }
+    }
+  }
+
+  /** Update a single plugin's config and notify it. */
+  async updateConfig(name: string, config: unknown): Promise<void> {
+    const handle = this.handles.get(name);
+    if (!handle) throw new Error(`[nexus-plugins] unknown plugin: ${name}`);
+    await handle.updateConfig(config);
+  }
+
+  async unload(name: string): Promise<void> {
+    const handle = this.handles.get(name);
+    if (!handle) return;
+    await handle.unload();
+    this.handles.delete(name);
+    this.loadOrder = this.loadOrder.filter((n) => n !== name);
+  }
+
+  get(name: string): PluginHandle | undefined { return this.handles.get(name); }
+  list(): PluginHandle[] { return this.loadOrder.map((n) => this.handles.get(n)!).filter(Boolean); }
+  order(): string[] { return [...this.loadOrder]; }
+}

package/packages/nexus-plugins/src/runtime/TrustedPlugin.ts

@@ -0,0 +1,134 @@
+import { pathToFileURL } from 'node:url';
+import type { PluginManifest } from '../manifest.js';
+import type { PluginContext, PluginModule, PluginHandle, HostBindings } from '../host.js';
+
+/**
+ * Trusted in-process plugin: the entry module is imported directly into the host
+ * and its lifecycle functions run with full Node API access. Every registrar on
+ * the context is checked against the manifest's capabilities (defense in depth —
+ * a trusted plugin could reach the host directly, but going through the context
+ * keeps the contract uniform with sandboxed plugins and lets the app audit usage).
+ */
+export class TrustedPlugin implements PluginHandle {
+  readonly manifest: PluginManifest;
+  state: PluginHandle['state'] = 'loaded';
+  private readonly bindings: HostBindings;
+  private readonly pluginDir: string;
+  private module: PluginModule | null = null;
+  private ctx: PluginContext | null = null;
+  private config: unknown;
+
+  constructor(manifest: PluginManifest, pluginDir: string, bindings: HostBindings, config: unknown) {
+    this.manifest = manifest;
+    this.bindings = bindings;
+    this.pluginDir = pluginDir;
+    this.config = config;
+  }
+
+  private requireCap(cap: string): void {
+    if (!this.manifest.capabilities.includes(cap as any)) {
+      throw new Error(`[nexus-plugins] ${this.manifest.name} lacks capability: ${cap}`);
+    }
+  }
+
+  private buildContext(): PluginContext {
+    const self = this;
+    const logger = this.bindings.logger.child({ plugin: this.manifest.name });
+    const has = (c: string) => this.manifest.capabilities.includes(c as any);
+    const ctx: PluginContext = {
+      pluginName: this.manifest.name,
+      capabilities: this.manifest.capabilities,
+      config: this.config,
+      logger,
+      http: {
+        addRoute: (method, path, handler) => { self.requireCap('http'); self.bindings.http.addRoute(method, path, handler); },
+        addMiddleware: (mw, phase) => { self.requireCap('http'); self.bindings.http.addMiddleware(mw, phase); },
+      },
+      graphql: { addSubgraph: async (sg) => { self.requireCap('graphql'); await self.bindings.graphql.addSubgraph(sg); } },
+      data: {
+        registerModel: (n, s) => { self.requireCap('data'); return self.bindings.data.registerModel(n, s); },
+        getModel: (n) => { self.requireCap('data'); return self.bindings.data.getModel(n); },
+      },
+      realtime: {
+        join: (r, c) => { self.requireCap('realtime'); self.bindings.realtime.join(r, c); },
+        broadcast: (r, m) => { self.requireCap('realtime'); self.bindings.realtime.broadcast(r, m); },
+      },
+      scheduler: {
+        schedule: (n, cron, fn) => { self.requireCap('scheduler'); self.bindings.scheduler.schedule(n, cron, fn); },
+        cancel: (n) => { self.requireCap('scheduler'); self.bindings.scheduler.cancel(n); },
+      },
+      events: {
+        publish: (t, p) => { self.requireCap('events'); self.bindings.events.publish(t, p); },
+        subscribe: (t, h) => { self.requireCap('events'); return self.bindings.events.subscribe(t, h); },
+      },
+      admin: {
+        registerAdminPage: (p) => { self.requireCap('admin'); self.bindings.admin.registerAdminPage(p); },
+        registerSlot: (s) => { self.requireCap('admin'); self.bindings.admin.registerSlot(s); },
+      },
+      services: {
+        register: (n, s) => { self.requireCap('events'); self.bindings.services.register(n, s); },
+        get: (n) => { self.requireCap('events'); return self.bindings.services.get(n); },
+      },
+    };
+    if (has('fs')) {
+      ctx.fs = {
+        readFile: async (p) => { self.requireCap('fs'); return import('node:fs/promises').then((f) => f.readFile(p)); },
+        writeFile: async (p, d) => { self.requireCap('fs'); return import('node:fs/promises').then((f) => f.writeFile(p, d)); },
+      };
+    }
+    if (has('net')) {
+      ctx.net = {
+        fetch: async (url, init) => { self.requireCap('net'); const r = await fetch(url, { method: init?.method, headers: init?.headers, body: init?.body }); return { status: r.status, body: await r.text() }; },
+      };
+    }
+    this.ctx = ctx;
+    return ctx;
+  }
+
+  private async loadModule(): Promise<PluginModule> {
+    if (this.module) return this.module;
+    const entryUrl = pathToFileURL(`${this.pluginDir}/${this.manifest.entry}`).href;
+    const mod = await import(entryUrl);
+    this.module = (mod.default ?? mod) as PluginModule;
+    return this.module;
+  }
+
+  async install(): Promise<void> {
+    const mod = await this.loadModule();
+    const ctx = this.buildContext();
+    if (mod.install) await mod.install(ctx);
+    this.state = 'installed';
+  }
+
+  async init(): Promise<void> {
+    const mod = this.module ?? (await this.loadModule());
+    const ctx = this.ctx ?? this.buildContext();
+    if (mod.init) await mod.init(ctx);
+    this.state = 'initialized';
+  }
+
+  async start(): Promise<void> {
+    const mod = this.module ?? (await this.loadModule());
+    const ctx = this.ctx ?? this.buildContext();
+    if (mod.start) await mod.start(ctx);
+    this.state = 'started';
+  }
+
+  async stop(): Promise<void> {
+    if (this.module?.stop && this.ctx) await this.module.stop(this.ctx);
+    this.state = 'stopped';
+  }
+
+  async updateConfig(cfg: unknown): Promise<void> {
+    this.config = cfg;
+    if (this.ctx) (this.ctx as { config: unknown }).config = cfg;
+    if (this.module?.onConfigChange && this.ctx) await this.module.onConfigChange(this.ctx, cfg);
+  }
+
+  async unload(): Promise<void> {
+    await this.stop();
+    this.module = null;
+    this.ctx = null;
+    this.state = 'stopped';
+  }
+}