@hamak/server-kernel

Generic multi-plugin Express server kernel — the backend counterpart of the frontend shell kernel (ui-shell / mountPrismApp). It assembles a microkernel Host plus any number of route-contributing plugins into one Express app and listens. See amah/app-framework#33.

Why

Every backend hand-rolls "build Host → register plugins → wire Express → app.listen". This package is the shared glue, mirroring the frontend's middleware-registry pattern.

Usage

import { createServer, ROUTE_REGISTRY_TOKEN, type IRouteRegistry } from '@hamak/server-kernel';
import { Router } from 'express';

// A backend plugin contributes routes in initialize().
function widgetsPlugin() {
  return {
    initialize(ctx) {
      const routes = ctx.resolve<IRouteRegistry>(ROUTE_REGISTRY_TOKEN);
      routes.register({ method: 'get', path: '/api/widgets', handler, priority: 10, plugin: 'widgets' });
      // …or mount a whole sub-router:
      routes.register({ path: '/fs', router: Router(), plugin: 'fs' });
    },
    activate() {},
  };
}

const { port, close } = await createServer({
  port: 3334,
  plugins: [widgetsPlugin() /* … */],
});

Registration discipline

Plugins register routes in initialize(); the http terminal plugin builds and mounts the Express app in activate(). The Host runs every plugin's initialize() before any activate(), so the RouteRegistry is fully populated by the time the terminal drains it — regardless of plugin order. The registry is drained by the terminal, never applied at registration time. (This is the exact ordering bug that bit ui-local-fs in 0.7.2.)

Routes are applied in descending priority (Express order is significant), ties broken by registration order.

API

• createServer(descriptor) → Promise<ServerHandle> — build + listen.
• createRouteRegistry() / ROUTE_REGISTRY_TOKEN — the shared route registry (Symbol.for('@hamak/server-kernel:RouteRegistry')).
• createHttpPlugin(options, onReady, onError) — the terminal plugin, if you drive the Host yourself.