@unifiedcommerce/core 0.2.0 → 0.2.1

package/src/runtime/logger.ts

@@ -0,0 +1,36 @@
+import pino from "pino";
+import type { CommerceConfig } from "../config/types.js";
+
+export type Logger = pino.Logger;
+
+/**
+ * Create a structured JSON logger for the commerce engine.
+ *
+ * Automatically redacts sensitive fields (authorization, password, token, etc.)
+ * from all log output. Uses Pino for high-performance, newline-delimited JSON.
+ */
+export function createLogger(config: CommerceConfig): Logger {
+  return pino({
+    level: config.logLevel ?? "info",
+    redact: {
+      paths: [
+        "req.headers.authorization",
+        "req.headers.cookie",
+        "*.password",
+        "*.secret",
+        "*.apiKey",
+        "*.creditCard",
+        "*.token",
+        "*.apiToken",
+      ],
+      censor: "[REDACTED]",
+    },
+    serializers: {
+      req: pino.stdSerializers.req,
+      err: pino.stdSerializers.err,
+    },
+    formatters: {
+      level: (label) => ({ level: label }),
+    },
+  });
+}

package/src/runtime/server.ts

@@ -0,0 +1,355 @@
+import { Hono } from "hono";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { cors } from "hono/cors";
+import { csrf } from "hono/csrf";
+import { bodyLimit } from "hono/body-limit";
+import { rateLimiter } from "hono-rate-limiter";
+import type { Actor } from "../auth/types.js";
+import type { AuthInstance } from "../auth/setup.js";
+import type { CommerceConfig } from "../config/types.js";
+import { authMiddleware } from "../auth/middleware.js";
+import { createMCPHandler } from "../interfaces/mcp/transport.js";
+import { createRestRoutes } from "../interfaces/rest/index.js";
+import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
+import { createKernel } from "./kernel.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+import { createLogger, type Logger } from "./logger.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import { createCommerce, type CommerceInstance } from "./commerce.js";
+
+type ServerEnv = {
+  Variables: {
+    auth: AuthInstance;
+    actor: Actor | null;
+    requestId: string;
+    logger: Logger;
+  };
+};
+
+/**
+ * Create a full HTTP server (Hono) with all REST routes, auth, and middleware.
+ *
+ * For server-side frameworks (Next.js, TanStack Start, SvelteKit), use
+ * `createCommerce()` instead — it gives you a local API without HTTP overhead.
+ */
+export async function createServer(config: CommerceConfig) {
+  const commerce = await createCommerce(config);
+  const { kernel, auth, logger } = commerce;
+  const isProdEnv = process.env.NODE_ENV === "production";
+
+
+  console.log("config", config);
+  console.log("isProdEnv", isProdEnv);
+  
+  const app = new OpenAPIHono<ServerEnv>({
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        return c.json({
+          error: {
+            code: "VALIDATION_FAILED",
+            message: isProdEnv
+              ? "Invalid input."
+              : result.error.issues
+                  .map((i) => `${i.path.join(".")}: ${i.message}`)
+                  .join("; "),
+          },
+        }, 422);
+      }
+    },
+  });
+
+  // ─── Security Guards ──────────────────────────────────────────────
+  if (config.auth?.enableDevKey && process.env.NODE_ENV === "production") {
+    throw new Error(
+      "FATAL: Dev key MUST NOT be enabled in production. " +
+      "Set auth.enableDevKey: false in production config.",
+    );
+  }
+  if (config.auth?.enableDevKey && process.env.NODE_ENV !== "development") {
+    logger.warn(
+      "Dev key is enabled outside NODE_ENV=development. " +
+      "Set auth.enableDevKey: false in production config to disable the dev backdoor.",
+    );
+  }
+
+  // ─── Process Crash Handlers (F4) ─────────────────────────────────────
+  process.on("unhandledRejection", (reason) => {
+    logger.fatal({ err: reason }, "unhandled promise rejection -- exiting");
+    process.exit(1);
+  });
+
+  process.on("uncaughtException", (err) => {
+    logger.fatal({ err }, "uncaught exception -- exiting");
+    process.exit(1);
+  });
+
+  // ─── Security Response Headers ──────────────────────────────────────
+  app.use("*", async (c, next) => {
+    c.header("X-Content-Type-Options", "nosniff");
+    c.header("X-Frame-Options", "DENY");
+    c.header("Referrer-Policy", "strict-origin-when-cross-origin");
+    c.header("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
+    if (isProdEnv) {
+      c.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+    }
+    await next();
+  });
+
+  // ─── Request ID + Logging (F2, F12) ──────────────────────────────────
+  app.use("*", async (c, next) => {
+    const requestId = c.req.header("x-request-id") ?? crypto.randomUUID();
+    c.header("x-request-id", requestId);
+    c.set("requestId", requestId);
+    const child = logger.child({ requestId, method: c.req.method, path: c.req.path });
+    c.set("logger", child);
+
+    const start = performance.now();
+    await next();
+
+    // Sanitize ZodError responses in production.
+    // @hono/zod-openapi returns { success: false, error: { name: "ZodError" } }
+    // which leaks schema details. The library does not respect defaultHook for
+    // this format, so we intercept at the response level.
+    if (isProdEnv && c.res.status >= 400 && c.res.status < 500) {
+      const ct = c.res.headers.get("content-type");
+      if (ct?.includes("json")) {
+        try {
+          const body = await c.res.clone().json();
+          if (body?.error?.name === "ZodError") {
+            c.res = new Response(
+              JSON.stringify({ error: { code: "VALIDATION_FAILED", message: "Invalid input." } }),
+              { status: 422, headers: { "content-type": "application/json" } },
+            );
+          }
+        } catch { /* non-parseable, skip */ }
+      }
+    }
+
+    const duration = Math.round(performance.now() - start);
+
+    child.info({ status: c.res.status, durationMs: duration }, "request completed");
+  });
+
+  // ─── CORS (hardened by default) ──────────────────────────────────────
+  const trustedOrigins = config.auth?.trustedOrigins ?? [];
+  app.use("*", cors({
+    origin: trustedOrigins.length > 0
+      ? trustedOrigins
+      : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+    credentials: true,
+    allowMethods: ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization", "x-api-key", "x-request-id"],
+    maxAge: 86400,
+  }));
+
+  // ─── CSRF Protection (F14) ──────────────────────────────────────────
+  app.use("/api/*", csrf({
+    origin: trustedOrigins.length > 0
+      ? trustedOrigins
+      : (process.env.NODE_ENV === "production" ? [] : ["http://localhost:*"]),
+  }));
+
+  // ─── Body Size Limit (F6) ──────────────────────────────────────────
+  app.use("*", bodyLimit({
+    maxSize: 1024 * 1024,  // 1 MB default
+    onError: (c) => c.json({
+      error: { code: "PAYLOAD_TOO_LARGE", message: "Request body exceeds 1MB limit." },
+    }, 413),
+  }));
+
+  // ─── Rate Limiting (F1) ──────────────────────────────────────────────
+  // Trust X-Forwarded-For ONLY from a known reverse proxy IP.
+  // Set TRUSTED_PROXY_IP env var to the proxy's IP (e.g., "127.0.0.1").
+  const trustedProxyIp = process.env.TRUSTED_PROXY_IP;
+  const getClientIp = (c: { req: { raw: unknown; header: (name: string) => string | undefined } }): string => {
+    const raw = c.req.raw as { socket?: { remoteAddress?: string } };
+    const remoteAddress = raw.socket?.remoteAddress;
+    // Only trust X-Forwarded-For when the direct connection is from a trusted proxy
+    if (trustedProxyIp && remoteAddress === trustedProxyIp) {
+      const xff = c.req.header("x-forwarded-for")?.split(",")[0]?.trim();
+      if (xff) return xff;
+    }
+    return remoteAddress ?? "unknown";
+  };
+  const keyGenerator = getClientIp;
+
+  app.use("/api/auth/*", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.auth ?? 10,
+    keyGenerator,
+  }));
+
+  app.use("/api/checkout", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.checkout ?? 5,
+    keyGenerator,
+  }));
+
+  app.use("/api/*", rateLimiter({
+    windowMs: 60 * 1000,
+    limit: config.rateLimits?.api ?? 100,
+    keyGenerator,
+  }));
+
+  // ─── Custom Middleware ──────────────────────────────────────────────
+  if (config.middleware) {
+    for (const middleware of config.middleware) {
+      app.use("*", middleware);
+    }
+  }
+
+  // ─── Auth ──────────────────────────────────────────────────────────
+  app.use("/api/auth/*", async (c, next) => {
+    if (c.req.path.startsWith("/api/auth/pos/")) {
+      await next();
+      return;
+    }
+    return auth.handler(c.req.raw);
+  });
+
+  app.use("*", authMiddleware(auth, config));
+  app.use("*", async (c, next) => {
+    c.set("auth", auth);
+    await next();
+  });
+
+  // ─── Global Error Handler ─────────────────────────────────────────
+  // Sanitize errors in production — no stack traces, no class names, no schema details
+  const isProd = process.env.NODE_ENV === "production";
+  app.onError((err, c) => {
+    // Catch ZodError from @hono/zod-openapi validation (bypasses defaultHook)
+    if (err.constructor?.name === "ZodError" || "issues" in err) {
+      if (isProd) {
+        return c.json(
+          { error: { code: "VALIDATION_FAILED", message: "Invalid input." } },
+          422,
+        );
+      }
+      const issues = (err as { issues?: Array<{ path: string[]; message: string }> }).issues ?? [];
+      return c.json(
+        {
+          error: {
+            code: "VALIDATION_FAILED",
+            message: issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "),
+          },
+        },
+        422,
+      );
+    }
+
+    if (isProd) {
+      logger.error({ err }, "unhandled request error");
+      return c.json(
+        { error: { code: "INTERNAL_ERROR", message: "An unexpected error occurred." } },
+        500,
+      );
+    }
+    return c.json(
+      { error: { code: "INTERNAL_ERROR", message: err.message } },
+      500,
+    );
+  });
+
+  // ─── Routes ──────────────────────────────────────────────────────────
+  app.route("/api", createRestRoutes(kernel));
+  app.route("/mcp", createMCPHandler(kernel));
+  app.route("/api/me", createCustomerPortalRoutes(kernel));
+
+  if (config.routes) {
+    config.routes(app, kernel);
+  }
+
+  // OpenAPI spec — disabled in production unless explicitly enabled
+  const exposeSpec = config.exposeOpenApiSpec ?? !isProd;
+  if (exposeSpec) {
+    app.doc("/api/doc", {
+      openapi: "3.0.0",
+      info: {
+        title: "UnifiedCommerce API",
+        version: config.version ?? "0.0.1",
+        description: "Headless commerce engine REST API. Includes core and plugin endpoints.",
+      },
+    });
+  } else {
+    app.get("/api/doc", (c) => c.json({ error: { code: "NOT_FOUND", message: "Not found." } }, 404));
+  }
+
+  // ─── Job Queue ───────────────────────────────────────────────────────
+  // Background job processing: webhook delivery, scheduled orders, email tasks.
+  //
+  // Three runner strategies (inspired by Payload CMS):
+  //   1. autorun: in-process polling (long-running servers)
+  //   2. GET /api/jobs/run: cron endpoint (serverless — Vercel, Cloudflare)
+  //   3. runPendingJobs() export (custom worker process)
+
+  const { runPendingJobs } = await import("../kernel/jobs/runner.js");
+  const taskMap = new Map<string, unknown>();
+  for (const task of config.jobs?.tasks ?? []) {
+    const t = task as { slug?: string; name?: string };
+    taskMap.set(t.slug ?? t.name ?? "", task);
+  }
+
+  const runJobs = async (queue?: string, limit?: number) => {
+    return runPendingJobs({
+      db: kernel.database.db as DrizzleDatabase,
+      tasks: taskMap as Parameters<typeof runPendingJobs>[0]["tasks"],
+      queue: queue ?? "default",
+      limit: limit ?? 10,
+      logger: {
+        info: (msg: string, data?: unknown) => logger.info(data != null ? { data } : {}, msg),
+        warn: (msg: string, data?: unknown) => logger.warn(data != null ? { data } : {}, msg),
+        error: (msg: string, data?: unknown) => logger.error(data != null ? { data } : {}, msg),
+      },
+      services: kernel.services as Parameters<typeof runPendingJobs>[0]["services"],
+    });
+  };
+
+  // Strategy 1: Built-in cron endpoint for serverless deployments.
+  // Point Vercel Cron or Cloudflare Cron Trigger at GET /api/jobs/run
+  // Optional query params: ?queue=emails&limit=20
+  app.get("/api/jobs/run", async (c) => {
+    // Always require admin — cron triggers must authenticate
+    const actor = c.get("actor") as { permissions?: string[] } | null;
+    if (!actor?.permissions?.includes("*:*")) {
+      return c.json({ error: { code: "FORBIDDEN", message: "Job runner requires admin access" } }, 403);
+    }
+
+    const queue = c.req.query("queue") ?? "default";
+    const limit = parseInt(c.req.query("limit") ?? "10", 10);
+
+    try {
+      const result = await runJobs(queue, limit);
+      return c.json({ data: result });
+    } catch (err) {
+      logger.error({ err }, "Job runner endpoint failed");
+      return c.json({ error: { code: "INTERNAL_ERROR", message: "Job processing failed" } }, 500);
+    }
+  });
+
+  // Strategy 2: In-process polling for long-running servers (ECS, Cloud Run, Docker).
+  // Enable via config.jobs.autorun.enabled = true
+  if (config.jobs?.autorun?.enabled) {
+    const intervalMs = config.jobs.autorun.intervalMs ?? 10_000;
+
+    const jobInterval = setInterval(async () => {
+      try {
+        await runJobs();
+      } catch (err) {
+        logger.error({ err }, "Job runner iteration failed");
+      }
+    }, intervalMs);
+
+    const cleanup = () => clearInterval(jobInterval);
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+
+    logger.info({ intervalMs }, "Job queue autorun started (in-process polling)");
+  } else {
+    logger.info(
+      "Job queue autorun disabled. Use GET /api/jobs/run for serverless cron, " +
+      "or set config.jobs.autorun.enabled = true for in-process polling.",
+    );
+  }
+
+  return { app, kernel, logger, commerce };
+}

package/src/runtime/shutdown.ts

@@ -0,0 +1,43 @@
+import type { Logger } from "./logger.js";
+
+/**
+ * Sets up graceful shutdown handlers for SIGTERM and SIGINT.
+ *
+ * On signal:
+ * 1. Stops accepting new connections
+ * 2. Runs cleanup (close DB pool, flush logs)
+ * 3. Force-exits after timeout if cleanup hangs
+ */
+export function setupGracefulShutdown(opts: {
+  cleanup: () => Promise<void>;
+  logger: Logger;
+  timeoutMs?: number;
+}): void {
+  const { cleanup, logger, timeoutMs = 30_000 } = opts;
+  let isShuttingDown = false;
+
+  async function shutdown(signal: string) {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+
+    logger.info({ signal }, "shutdown signal received, draining connections");
+
+    const forceTimer = setTimeout(() => {
+      logger.error("shutdown timeout exceeded, forcing exit");
+      process.exit(1);
+    }, timeoutMs);
+    forceTimer.unref();
+
+    try {
+      await cleanup();
+      logger.info("graceful shutdown complete");
+      process.exit(0);
+    } catch (err) {
+      logger.error({ err }, "error during shutdown");
+      process.exit(1);
+    }
+  }
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+}

package/src/test-utils/create-pglite-adapter.ts

@@ -0,0 +1,129 @@
+/**
+ * PGlite-backed test adapter for real PostgreSQL behavior in tests.
+ *
+ * Creates an in-memory PGlite (WASM PostgreSQL) instance, pushes the
+ * core Drizzle schema programmatically via drizzle-kit/api, and provides
+ * a cleanup function to reset data between tests.
+ *
+ * Benefits over in-memory repository doubles:
+ * - Real SQL execution (Drizzle query generation)
+ * - PostgreSQL type coercion and constraint enforcement
+ * - Real transaction rollback semantics
+ * - Production parity for query edge cases
+ */
+
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+import { sql } from "drizzle-orm";
+import { createRequire } from "node:module";
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import { getSchema } from "../kernel/database/migrate.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+
+// Single barrel import --- includes all core modules + auth tables
+import * as fullSchema from "../kernel/database/schema.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+
+// drizzle-kit/api uses CJS internally; createRequire provides ESM compat.
+const require = createRequire(import.meta.url);
+
+/**
+ * Pushes the core Drizzle schema to the database using drizzle-kit/api.
+ *
+ * drizzle-kit introspects the live database via information_schema, diffs
+ * against the pgTable definitions, and generates the minimal DDL needed.
+ * Typed as DrizzleDatabase (our concrete schema type) to avoid the
+ * PGlite → PgDatabase<HKT> invariance cast — drizzle-kit accepts any
+ * Drizzle instance at runtime regardless of the schema generic.
+ */
+async function pushCoreSchema(db: DrizzleDatabase): Promise<void> {
+  const coreSchema = getSchema();
+  const drizzleKit = require("drizzle-kit/api") as {
+    pushSchema(
+      imports: Record<string, unknown>,
+      drizzleInstance: DrizzleDatabase,
+    ): Promise<{ apply: () => Promise<void> }>;
+  };
+  const { apply } = await drizzleKit.pushSchema(coreSchema, db);
+  await apply();
+}
+
+/**
+ * Creates a PGlite-backed database adapter for testing.
+ *
+ * Each call creates a new isolated PGlite instance with its own
+ * in-memory database. Core schema is pushed once during initialization.
+ *
+ * @returns A promise resolving to an object containing:
+ *   - adapter: The DatabaseAdapter for use with createKernel
+ *   - db: The Drizzle ORM instance for direct queries
+ *   - cleanup: Function to truncate all tables (call between tests)
+ */
+export async function createPGliteTestAdapter(): Promise<{
+  adapter: DatabaseAdapter;
+  db: DrizzleDatabase;
+  cleanup: () => Promise<void>;
+}> {
+  // Create in-memory PGlite instance
+  const pg = new PGlite();
+
+  // Wrap with Drizzle ORM first (pushSchema needs the Drizzle instance)
+  const db = drizzle(pg, { schema: fullSchema });
+
+  // Push core schema via drizzle-kit/api (no migration files needed)
+  // PgliteDatabase<Schema> and DrizzleDatabase share the same Schema type;
+  // the HKT parameter differs (PgliteQueryResultHKT vs PgQueryResultHKT)
+  // but drizzle-kit's pushSchema doesn't use it at runtime.
+  await pushCoreSchema(db as DrizzleDatabase);
+
+  // Ensure the default organization exists for all tests
+  await ensureDefaultOrg(db);
+
+  /**
+   * PGlite-compatible transaction wrapper.
+   *
+   * Drizzle's transaction() method can hang with PGlite due to how
+   * the adapter manages transaction state. This implementation uses
+   * manual BEGIN/COMMIT control which works more reliably.
+   */
+  async function transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+    await pg.exec("BEGIN");
+    try {
+      const result = await fn(db);
+      await pg.exec("COMMIT");
+      return result;
+    } catch (error) {
+      await pg.exec("ROLLBACK");
+      throw error;
+    }
+  }
+
+  const adapter: DatabaseAdapter = {
+    provider: "postgresql",
+    db,
+    transaction,
+  };
+
+  /**
+   * Cleanup function to reset data between tests.
+   * Truncates all tables in reverse dependency order with CASCADE.
+   */
+  async function cleanup(): Promise<void> {
+    await db.execute(sql`
+      DO $$ DECLARE
+        r RECORD;
+      BEGIN
+        FOR r IN (
+          SELECT tablename FROM pg_tables
+          WHERE schemaname = 'public'
+        ) LOOP
+          EXECUTE 'TRUNCATE TABLE ' || quote_ident(r.tablename) || ' CASCADE';
+        END LOOP;
+      END $$;
+    `);
+    // Re-insert default org after truncation (CASCADE wipes it)
+    await ensureDefaultOrg(db);
+  }
+
+  return { adapter, db, cleanup };
+}

package/src/test-utils/create-plugin-test-app.ts

@@ -0,0 +1,128 @@
+/**
+ * One-call plugin E2E test setup.
+ *
+ * Boots a PGlite kernel (or real PG if overridden), programmatically pushes
+ * the merged schema (core + plugin tables) via drizzle-kit/api, mounts the
+ * test actor middleware on an OpenAPIHono instance, and registers all plugin
+ * routes --- matching the production server.ts boot sequence.
+ *
+ * Usage:
+ *   import { createPluginTestApp, jsonHeaders, testAdminActor } from "@unifiedcommerce/core";
+ *   const { app } = await createPluginTestApp(myPlugin());
+ *   const res = await app.request("/api/my-route", {
+ *     method: "POST",
+ *     headers: jsonHeaders(testAdminActor),
+ *     body: JSON.stringify({ ... }),
+ *   });
+ *   expect(res.status).toBe(201);
+ */
+
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { createRequire } from "node:module";
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+import type { CommerceConfig, CommercePlugin } from "../config/types.js";
+import type { Actor } from "../auth/types.js";
+import { createTestConfig } from "./create-test-config.js";
+import { createKernel } from "../runtime/kernel.js";
+import type { Kernel } from "../runtime/kernel.js";
+import { buildSchema } from "../kernel/database/migrate.js";
+import { ensureDefaultOrg } from "../auth/org.js";
+
+// drizzle-kit/api uses CJS internally; createRequire provides ESM compat.
+const require = createRequire(import.meta.url);
+
+type DrizzleKitPushResult = {
+  hasDataLoss: boolean;
+  warnings: string[];
+  statementsToExecute: string[];
+  apply: () => Promise<void>;
+};
+
+/**
+ * Hono environment type for the test app. Declares the `actor` context
+ * variable so c.set("actor", ...) / c.get("actor") are properly typed
+ * without `as never` casts.
+ */
+export type TestAppEnv = {
+  Variables: {
+    actor: Actor | null;
+  };
+};
+
+export interface PluginTestApp {
+  /** OpenAPIHono instance with test actor middleware and all plugin routes registered. */
+  app: OpenAPIHono<TestAppEnv>;
+  /** The booted kernel with database, services, and config. */
+  kernel: Kernel;
+  /** Drizzle database instance for direct queries in test assertions. */
+  db: PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+}
+
+/**
+ * Creates a fully-wired test application for plugin E2E testing.
+ *
+ * @param plugin - The plugin under test (e.g., `appointmentPlugin()`)
+ * @param configOverrides - Optional config overrides. Pass `databaseAdapter`
+ *   to use a real PostgreSQL instance instead of PGlite.
+ */
+export async function createPluginTestApp(
+  plugin: CommercePlugin,
+  configOverrides: Partial<CommerceConfig> = {},
+): Promise<PluginTestApp> {
+  // 1. Build config with plugin applied (PGlite auto-provisioned if no adapter)
+  const config = await createTestConfig({
+    plugins: [plugin],
+    ...configOverrides,
+  });
+
+  // 2. Boot kernel (creates core services, hook registry)
+  const kernel = createKernel(config);
+
+  // 3. Merge core + plugin schemas
+  const mergedSchema = buildSchema(config);
+
+  // 4. Programmatic schema push via drizzle-kit/api
+  //    Diffs current DB state against pgTable definitions, generates DDL, applies it.
+  //    On fresh PGlite: creates all tables. On existing DB: creates only missing tables.
+  const drizzleKit = require("drizzle-kit/api") as {
+    pushSchema(
+      imports: Record<string, unknown>,
+      drizzleInstance: PgDatabase<PgQueryResultHKT>,
+    ): Promise<DrizzleKitPushResult>;
+  };
+  const { apply } = await drizzleKit.pushSchema(
+    mergedSchema,
+    kernel.database.db as PgDatabase<PgQueryResultHKT>,
+  );
+  await apply();
+
+  // Ensure the default organization exists for plugin tests
+  await ensureDefaultOrg(kernel.database.db);
+
+  // 5. Create OpenAPIHono --- matching production server.ts
+  //    Plugin routes register via manifest.ts which calls app.openapi().
+  const app = new OpenAPIHono<TestAppEnv>();
+
+  // 6. Test actor middleware: parse x-test-actor header -> set on context
+  app.use("*", async (c, next) => {
+    const header = c.req.header("x-test-actor");
+    if (header) {
+      try {
+        c.set("actor", JSON.parse(header) as Actor);
+      } catch { /* malformed JSON --- fall through without actor */ }
+    }
+    await next();
+  });
+
+  // 7. Register plugin routes (deferred via config.routes)
+  const routes = config.routes as
+    | ((app: unknown, kernel: unknown) => void)
+    | undefined;
+  routes?.(app, kernel);
+
+  return {
+    app,
+    kernel,
+    db: kernel.database.db as PgDatabase<PgQueryResultHKT, Record<string, unknown>>,
+  };
+}