@porulle/core 0.1.0

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

@@ -0,0 +1,151 @@
+/**
+ * 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 "@porulle/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";
+import { mapErrorToStatus } from "../kernel/error-mapper.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);
+
+  // 8. Error handler matching production server.ts — maps CommerceError
+  //    subclasses (CommerceForbiddenError, CommerceNotFoundError, etc.)
+  //    to their proper HTTP status codes (403, 404, 409, 422, 503).
+  //    Without this, route handlers that throw assertPermission() etc.
+  //    surface as 500 in tests, masking real status assertions.
+  app.onError((err, c) => {
+    if (err instanceof Error && "code" in err && typeof (err as { code?: unknown }).code === "string") {
+      const status = mapErrorToStatus(err);
+      if (status !== 500) {
+        const errorCode = (err as { code: string }).code;
+        return c.json(
+          { error: { code: errorCode, message: err.message } },
+          status,
+        );
+      }
+    }
+    return c.json(
+      { error: { code: "INTERNAL_ERROR", message: err.message } },
+      500,
+    );
+  });
+
+  return {
+    app,
+    kernel,
+    db: kernel.database.db as PgDatabase<PgQueryResultHKT, Record<string, unknown>>,
+  };
+}

package/src/test-utils/create-repository-test-harness.ts

@@ -0,0 +1,16 @@
+import type { CommerceConfig } from "../config/types.js";
+import { createTestConfig } from "./create-test-config.js";
+import { createKernel } from "../runtime/kernel.js";
+
+export interface RepositoryTestHarness {
+  config: CommerceConfig;
+  kernel: ReturnType<typeof createKernel>;
+}
+
+export async function createRepositoryTestHarness(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<RepositoryTestHarness> {
+  const config = await createTestConfig(overrides);
+  const kernel = createKernel(config);
+  return { config, kernel };
+}

package/src/test-utils/create-test-config.ts

@@ -0,0 +1,188 @@
+import { defineConfig } from "../config/define-config.js";
+import type { CommerceConfig } from "../config/types.js";
+import { Ok } from "../kernel/result.js";
+import type { StorageAdapter } from "../modules/media/adapter.js";
+
+function createInMemoryStorageAdapter(): StorageAdapter {
+  const files = new Map<string, { data: ArrayBuffer; contentType: string }>();
+  const baseUrl = "http://localhost:3000/test-assets";
+
+  return {
+    providerId: "test-memory-storage",
+    async upload(key, data, contentType) {
+      const body =
+        data instanceof ArrayBuffer
+          ? data
+          : await new Response(data).arrayBuffer();
+      files.set(key, { data: body, contentType });
+      return Ok({
+        key,
+        url: `${baseUrl}/${key}`,
+        contentType,
+        size: body.byteLength,
+      });
+    },
+    async getUrl(key) {
+      return Ok(`${baseUrl}/${key}`);
+    },
+    async getSignedUrl(key, expiresIn) {
+      return Ok(`${baseUrl}/${key}?expiresIn=${expiresIn}`);
+    },
+    async delete(key) {
+      files.delete(key);
+      return Ok(undefined);
+    },
+    async list(prefix) {
+      return Ok(
+        Array.from(files.entries())
+          .filter(([key]) => key.startsWith(prefix))
+          .map(([key, file]) => ({
+            key,
+            url: `${baseUrl}/${key}`,
+            contentType: file.contentType,
+            size: file.data.byteLength,
+          })),
+      );
+    },
+  };
+}
+
+export async function createTestConfig(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<CommerceConfig> {
+  // Auto-provision PGlite when no databaseAdapter is provided
+  if (!overrides.databaseAdapter) {
+    const { createPGliteTestAdapter } = await import("./create-pglite-adapter.js");
+    const { adapter } = await createPGliteTestAdapter();
+    overrides = { ...overrides, databaseAdapter: adapter };
+  }
+
+  return defineConfig({
+    version: "0.0.1-test",
+    storeName: "Test Store",
+    database: {
+      provider: "postgresql",
+    },
+    auth: {
+      defaultOrganizationId: "org_default",
+      requireEmailVerification: false,
+      apiKeys: { enabled: true, defaultPermissions: ["catalog:read"] },
+      posPin: { enabled: true },
+      roles: {
+        owner: { permissions: ["*:*"] },
+        admin: { permissions: ["*:*"] },
+        staff: {
+          permissions: [
+            "catalog:create",
+            "catalog:update",
+            "catalog:delete",
+            "catalog:read",
+            "inventory:adjust",
+            "orders:create",
+            "orders:read",
+            "orders:update",
+            "cart:create",
+            "cart:update",
+            "customers:update:self",
+          ],
+        },
+        ai_agent: {
+          permissions: [
+            "catalog:read",
+            "catalog:create",
+            "inventory:read",
+          "inventory:adjust",
+          "orders:read",
+          "cart:create",
+          "cart:update",
+        ],
+      },
+      },
+      customerPermissions: [
+        "catalog:read",
+        "cart:create",
+        "cart:read",
+        "cart:update",
+        "orders:create",
+        "orders:read:own",
+        "customers:read:self",
+        "customers:update:self",
+      ],
+    },
+    entities: {
+      product: {
+        fields: [
+          { name: "weight", type: "number" },
+          { name: "brand", type: "text" },
+        ],
+        variants: { enabled: true, optionTypes: ["size", "color"] },
+        fulfillment: "physical",
+      },
+      digitalDownload: {
+        fields: [{ name: "fileAssetId", type: "text" }],
+        variants: { enabled: false },
+        fulfillment: "digital-download",
+      },
+      course: {
+        fields: [{ name: "modules", type: "json" }],
+        variants: { enabled: false },
+        fulfillment: "digital-access",
+      },
+    },
+    cart: {
+      ttlMinutes: 5,
+      hooks: {},
+    },
+    checkout: {
+      hooks: {
+        beforeCreate: [],
+        afterCreate: [],
+      },
+    },
+    orders: {
+      hooks: {
+        beforeCreate: [],
+        afterCreate: [],
+        beforeStatusChange: [],
+        afterStatusChange: [],
+      },
+    },
+    inventory: {
+      hooks: {
+        afterAdjust: [],
+      },
+    },
+    email: {
+      async send() {
+        // no-op for tests
+      },
+    },
+    storage: createInMemoryStorageAdapter(),
+    ...overrides,
+  });
+}
+
+/**
+ * Creates a test config backed by PGlite (in-memory PostgreSQL).
+ *
+ * This provides production parity for tests by using real SQL execution
+ * and PostgreSQL behavior while remaining fast and self-contained.
+ *
+ * @param overrides - Optional config overrides
+ * @returns A promise resolving to an object containing:
+ *   - config: The CommerceConfig to pass to createKernel
+ *   - cleanup: Async function to reset data between tests
+ */
+export async function createPGliteTestConfig(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<{ config: CommerceConfig; cleanup: () => Promise<void> }> {
+  const { createPGliteTestAdapter } = await import("./create-pglite-adapter.js");
+  const { adapter, cleanup } = await createPGliteTestAdapter();
+
+  const config = await createTestConfig({
+    databaseAdapter: adapter,
+    ...overrides,
+  });
+
+  return { config, cleanup };
+}

package/src/test-utils/create-test-kernel.ts

@@ -0,0 +1,7 @@
+import type { CommerceConfig } from "../config/types.js";
+import { createKernel } from "../runtime/kernel.js";
+import { createTestConfig } from "./create-test-config.js";
+
+export async function createTestKernel(overrides: Partial<CommerceConfig> = {}) {
+  return createKernel(await createTestConfig(overrides));
+}

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

@@ -0,0 +1,66 @@
+import { HookRegistry } from "../kernel/hooks/registry.js";
+import { createLogger } from "../utils/logger.js";
+import { createTestConfig } from "./create-test-config.js";
+import type { CommerceConfig } from "../config/types.js";
+
+interface PluginContextShape {
+  hooks: HookRegistry;
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+  routes: { add(method: string, path: string, handler: (...args: unknown[]) => unknown): void };
+  analytics: { registerModel(model: unknown): void };
+  database: {
+    registerSchema(schema: Record<string, unknown>): void;
+    query: unknown;
+    transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T>;
+  };
+  logger: { info(message: string, data?: unknown): void; warn(message: string, data?: unknown): void; error(message: string, data?: unknown): void };
+}
+
+export interface TestPluginContext extends PluginContextShape {
+  registeredRoutes: Array<{ method: string; path: string; handler: (...args: unknown[]) => unknown }>;
+  registeredAnalyticsModels: unknown[];
+  registeredSchemas: Array<Record<string, unknown>>;
+}
+
+export async function createTestPluginContext(options?: {
+  config?: Partial<CommerceConfig>;
+  services?: Record<string, unknown>;
+}): Promise<TestPluginContext> {
+  const hooks = new HookRegistry();
+  const config = await createTestConfig(options?.config ?? {});
+  const services = options?.services ?? {};
+
+  const registeredRoutes: TestPluginContext["registeredRoutes"] = [];
+  const registeredAnalyticsModels: unknown[] = [];
+  const registeredSchemas: Array<Record<string, unknown>> = [];
+
+  return {
+    hooks,
+    config,
+    services,
+    routes: {
+      add(method, path, handler) {
+        registeredRoutes.push({ method: method.toUpperCase(), path, handler });
+      },
+    },
+    analytics: {
+      registerModel(model) {
+        registeredAnalyticsModels.push(model);
+      },
+    },
+    database: {
+      registerSchema(schema) {
+        registeredSchemas.push(schema);
+      },
+      query: {},
+      async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+        return fn({});
+      },
+    },
+    logger: createLogger("test-plugin-context"),
+    registeredRoutes,
+    registeredAnalyticsModels,
+    registeredSchemas,
+  };
+}

package/src/test-utils/rest-api-test-utils.ts

@@ -0,0 +1,266 @@
+/**
+ * Integration test utilities for REST API endpoints.
+ *
+ * Provides helper functions to test Hono routes with a real kernel,
+ * PGlite database, and authentication middleware.
+ */
+
+import { Hono } from "hono";
+import { createKernel } from "../runtime/kernel.js";
+import { createAuth } from "../auth/setup.js";
+import { authMiddleware } from "../auth/middleware.js";
+import { createRestRoutes } from "../interfaces/rest/index.js";
+import { createPGliteTestConfig } from "./create-test-config.js";
+import { CommerceValidationError } from "../kernel/errors.js";
+import { Ok, Err } from "../kernel/result.js";
+import type { CommerceConfig } from "../config/types.js";
+import type { Actor } from "../auth/types.js";
+import type { AuthInstance } from "../auth/setup.js";
+
+type ServerEnv = {
+  Variables: {
+    auth: AuthInstance;
+    actor: Actor | null;
+  };
+};
+
+const mockPaymentAdapter = {
+  providerId: "test-payments",
+  async createPaymentIntent(params: { amount: number; currency: string }) {
+    return Ok({
+      id: "pi_test_" + Date.now(),
+      status: "requires_capture",
+      amount: params.amount,
+      currency: params.currency,
+      clientSecret: "secret_test",
+    });
+  },
+  async capturePayment() {
+    return Ok({ id: "pi_test_" + Date.now(), status: "succeeded", amountCaptured: 1000 });
+  },
+  async refundPayment() {
+    return Ok({ id: "re_test_" + Date.now(), status: "succeeded", amountRefunded: 1000 });
+  },
+  async cancelPaymentIntent() {
+    return Ok(undefined);
+  },
+  async verifyWebhook(request: Request) {
+    // Extract signature from headers
+    const signature = request.headers.get("stripe-signature") || request.headers.get("webhook-signature");
+
+    // Extract payload from request body
+    let payload: Record<string, unknown> | undefined;
+    try {
+      payload = await request.clone().json();
+    } catch {
+      return Err(new CommerceValidationError("Webhook payload is invalid or missing"));
+    }
+
+    // Simulate signature verification for production-hardened testing
+    // Reject invalid signatures like "invalid_signature"
+    if (signature === "invalid_signature") {
+      return Err(new CommerceValidationError("Invalid webhook signature"));
+    }
+
+    // Reject requests with no required fields
+    if (!payload || !payload.type) {
+      return Err(new CommerceValidationError("Webhook payload is missing required fields"));
+    }
+
+    return Ok({ id: "evt_test_" + Date.now(), type: String(payload.type), data: (payload.data ?? {}) as unknown });
+  },
+};
+
+/**
+ * Creates a test server with PGlite-backed kernel for REST API testing.
+ */
+export async function createTestServer(
+  overrides: Partial<CommerceConfig> = {},
+): Promise<{
+  server: Hono<ServerEnv>;
+  kernel: ReturnType<typeof createKernel>;
+  auth: AuthInstance;
+  cleanup: () => Promise<void>;
+}> {
+  const { config, cleanup } = await createPGliteTestConfig({
+    payments: [mockPaymentAdapter],
+    ...overrides,
+  });
+
+  const kernel = createKernel(config);
+  const auth = createAuth(kernel.database, config);
+  const app = new Hono<ServerEnv>();
+
+  // Set auth in context (like createServer does)
+  app.use("*", async (c, next) => {
+    c.set("auth", auth);
+    await next();
+  });
+
+  // Test middleware: allow direct actor injection via x-test-actor header for testing
+  app.use("*", async (c, next) => {
+    const testActorHeader = c.req.header("x-test-actor");
+    if (testActorHeader) {
+      try {
+        const actor = JSON.parse(testActorHeader) as Actor;
+        c.set("actor", actor);
+        await next();
+        return;
+      } catch {
+        // Invalid JSON, continue to auth middleware
+      }
+    }
+    await next();
+  });
+
+  // Add auth middleware
+  app.use("*", authMiddleware(auth, config));
+
+  // Error handling middleware - catch thrown errors and convert to JSON
+  app.use("*", async (c, next) => {
+    try {
+      await next();
+    } catch (error) {
+      // Import error handling utilities
+      const { mapErrorToResponse, mapErrorToStatus } = await import("../interfaces/rest/utils.js");
+      return c.json(
+        mapErrorToResponse(error),
+        mapErrorToStatus(error),
+      );
+    }
+  });
+
+  // Add REST routes
+  app.route("/api", createRestRoutes(kernel));
+
+  return { server: app, kernel, auth, cleanup };
+}
+
+/**
+ * Helper to parse JSON response from Hono Response
+ */
+export async function parseJsonResponse<T = unknown>(response: Response): Promise<T> {
+  return response.json() as Promise<T>;
+}
+
+/**
+ * Common test actor with staff permissions
+ */
+export const testActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000001",
+  email: "test@example.com",
+  name: "Test Staff",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "staff",
+  permissions: [
+    "catalog:create",
+    "catalog:update",
+    "catalog:read",
+    "inventory:adjust",
+    "inventory:read",
+    "orders:create",
+    "orders:read",
+    "orders:update",
+    "cart:create",
+    "cart:update",
+    "cart:read",
+    "customers:update:self",
+    "webhooks:manage",
+    "pricing:manage",
+    "promotions:manage",
+    "promotions:read",
+    "audit:read",
+    "media:write",
+    "compensation:admin",
+  ],
+};
+
+/**
+ * Test actor with read-only permissions
+ */
+export const readonlyActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000002",
+  email: "readonly@example.com",
+  name: "Read Only User",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: ["catalog:read", "cart:read", "orders:read:own"],
+};
+
+/**
+ * Test actor with no permissions
+ */
+export const noPermActor: Actor = {
+  type: "user",
+  userId: "00000000-0000-0000-0000-000000000003",
+  email: "noperm@example.com",
+  name: "No Perm",
+  vendorId: null,
+  organizationId: "org_default",
+  role: "customer",
+  permissions: [],
+};
+
+/**
+ * Helper to create a mock request with actor context
+ */
+export function createMockRequest(server: Hono<ServerEnv>, options: {
+  method: string;
+  url: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+  actor?: Actor;
+}) {
+  const url = new URL(options.url, "http://localhost");
+
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    ...options.headers,
+  };
+
+  // Add actor as header for test middleware
+  if (options.actor) {
+    headers["x-test-actor"] = JSON.stringify(options.actor);
+  }
+
+  // Build the request
+  const requestInit: RequestInit = {
+    method: options.method,
+    headers,
+  };
+  if (options.body) {
+    requestInit.body = JSON.stringify(options.body);
+  }
+  const request = new Request(url, requestInit);
+
+  return request;
+}
+
+/**
+ * Helper to make authenticated requests to the test server
+ */
+export async function makeRequest(
+  server: Hono<ServerEnv>,
+  options: {
+    method: string;
+    url: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    actor?: Actor;
+  },
+) {
+  // Create request with actor header (defaults to testActor)
+  const request = createMockRequest(server, {
+    ...options,
+    actor: options.actor ?? testActor,
+  });
+
+  // Route the request through Hono
+  const response = await server.fetch(request);
+
+  return response;
+}