@porulle/core 0.1.0

package/dist/runtime/server.js

@@ -0,0 +1,398 @@
+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 { createHash } from "node:crypto";
+import { authMiddleware } from "../auth/middleware.js";
+import { createRestRoutes } from "../interfaces/rest/index.js";
+import { createCustomerPortalRoutes } from "../interfaces/rest/customer-portal.js";
+import { createCommerce } from "./commerce.js";
+import { rewriteCommerceAliasRequest } from "./url-alias-rewrite.js";
+import { mapErrorToResponse } from "../kernel/error-mapper.js";
+/**
+ * Returns true if running in a Node-like runtime that supports
+ * `process.on()` + `process.exit()`. Edge runtimes (Cloudflare Workers,
+ * Vercel Edge) return false — caller should skip process-crash handlers
+ * and defer unhandled errors to the platform.
+ *
+ * Exposed for direct unit testing — see test/server-edge-runtime.test.ts.
+ */
+export function isNodeRuntime() {
+    return (typeof process !== "undefined" &&
+        typeof process.on === "function" &&
+        typeof process.exit === "function");
+}
+function hashRateLimitEmail(email) {
+    return createHash("sha256")
+        .update(email.trim().toLowerCase())
+        .digest("hex");
+}
+function matchPathPattern(path, pattern) {
+    if (pattern.endsWith("*")) {
+        return path.startsWith(pattern.slice(0, -1));
+    }
+    return path === pattern;
+}
+/**
+ * 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) {
+    const commerce = await createCommerce(config);
+    const { kernel, auth, logger } = commerce;
+    const isProdEnv = process.env.NODE_ENV === "production";
+    const app = new OpenAPIHono({
+        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 !== undefined) {
+        throw new Error("FATAL: auth.enableDevKey has been removed. " +
+            "Use 'bunx @porulle/cli api-key create --scope admin' to generate a real API key. " +
+            "See RFC-050: https://github.com/octalpixel/unified-commerce/blob/main/RFC-050-AUTH-KEY-SCOPING.md");
+    }
+    if (config.auth?.devKey !== undefined) {
+        throw new Error("FATAL: auth.devKey has been removed. " +
+            "Use 'bunx @porulle/cli api-key create --scope admin' to generate a real API key. " +
+            "See RFC-050: https://github.com/octalpixel/unified-commerce/blob/main/RFC-050-AUTH-KEY-SCOPING.md");
+    }
+    // exposed for direct unit testing — see test/server-edge-runtime.test.ts
+    // ─── Process Crash Handlers (F4) ─────────────────────────────────────
+    if (isNodeRuntime()) {
+        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);
+        });
+    }
+    else {
+        logger.info("running on edge runtime — process crash handlers skipped");
+    }
+    // ─── 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 signInEmailRateKeyCache = new WeakMap();
+    const getClientIp = (c) => {
+        const raw = c.req.raw;
+        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/auth/sign-in/email", async (c, next) => {
+        if (c.req.method !== "POST") {
+            await next();
+            return;
+        }
+        try {
+            const payload = await c.req.raw.clone().json();
+            if (typeof payload.email === "string" && payload.email.trim().length > 0) {
+                signInEmailRateKeyCache.set(c.req.raw, hashRateLimitEmail(payload.email));
+            }
+        }
+        catch {
+            // Ignore parse failures; endpoint validation will handle malformed bodies.
+        }
+        await next();
+    });
+    app.use("/api/auth/sign-in/email", rateLimiter({
+        windowMs: 15 * 60 * 1000,
+        limit: config.rateLimits?.signInPerEmail ?? 10,
+        keyGenerator: (c) => signInEmailRateKeyCache.get(c.req.raw) ?? "signin-email:unknown",
+    }));
+    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,
+    }));
+    app.use("*", async (c, next) => {
+        await next();
+        const csp = config.security?.csp;
+        if (!csp)
+            return;
+        // Recommended checkout policy baseline (adjust provider domains):
+        // default-src 'self'; script-src 'self' https://js.stripe.com; frame-src https://js.stripe.com https://hooks.stripe.com; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+        const routePolicy = Object.entries(csp.perRoute ?? {}).find(([pattern]) => matchPathPattern(c.req.path, pattern))?.[1];
+        const policy = routePolicy ?? csp.default;
+        if (policy) {
+            c.header("Content-Security-Policy", policy);
+        }
+    });
+    // ─── 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 ─────────────────────────────────────────
+    const isProd = process.env.NODE_ENV === "production";
+    app.onError((err, c) => {
+        const { body, status } = mapErrorToResponse(err, isProd, logger);
+        return c.json(body, status);
+    });
+    // ─── Routes ──────────────────────────────────────────────────────────
+    app.route("/api", createRestRoutes(kernel));
+    // Mounted under /api so the auth middleware, rate limiter, CSRF, and
+    // body-limit stack apply (all are scoped to /api/*).
+    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.",
+            },
+            tags: [
+                // ── Entity aliases (generated from config.entities[type].alias) ──
+                ...Object.entries(config.entities ?? {})
+                    .filter(([, cfg]) => cfg.alias)
+                    .map(([type, cfg]) => {
+                    const name = cfg.alias.charAt(0).toUpperCase() + cfg.alias.slice(1);
+                    return { name, description: `Ergonomic alias for ${type} entities — CRUD, variants, attributes` };
+                }),
+                // ── Storefront ──
+                { name: "Catalog", description: "Products, categories, brands, variants, and option types (unified entity API)" },
+                { name: "Search", description: "Full-text search and typeahead suggestions" },
+                { name: "Pricing", description: "Base prices, price modifiers, and customer group pricing" },
+                { name: "Carts", description: "Shopping cart lifecycle — create, add items, update quantities" },
+                { name: "Checkout", description: "Convert a cart into a paid order" },
+                { name: "Promotions", description: "Discount codes, validation, and usage tracking" },
+                // ── Admin ──
+                { name: "Orders", description: "Order management — list, detail, status transitions, fulfillments" },
+                { name: "Customers", description: "Customer profiles, addresses, groups, and order history" },
+                { name: "Inventory", description: "Stock levels, warehouse management, adjustments, and reservations" },
+                { name: "Media", description: "File uploads, entity attachments, and signed URLs" },
+                { name: "Payments", description: "Payment provider webhooks and event processing" },
+                // ── Operations ──
+                { name: "Webhooks", description: "Outbound webhook endpoint registration and management" },
+                { name: "Audit", description: "Immutable audit log — who changed what and when" },
+                { name: "Admin Jobs", description: "Background job queue — view failed jobs and retry" },
+            ],
+        });
+        // Serve enriched spec with x-tagGroups vendor extension (Scalar/Redocly sidebar grouping)
+        const aliasTags = Object.values(config.entities ?? {})
+            .filter((cfg) => cfg.alias)
+            .map((cfg) => cfg.alias.charAt(0).toUpperCase() + cfg.alias.slice(1));
+        const tagGroups = [
+            ...(aliasTags.length > 0 ? [{ name: "Quick Access", tags: aliasTags }] : []),
+            { name: "Storefront", tags: ["Catalog", "Search", "Pricing", "Carts", "Checkout", "Promotions"] },
+            { name: "Admin", tags: ["Orders", "Customers", "Inventory", "Media", "Payments"] },
+            { name: "Operations", tags: ["Webhooks", "Audit", "Admin Jobs"] },
+        ];
+        app.get("/api/doc-ext", (c) => {
+            const spec = app.getOpenAPIDocument({ openapi: "3.0.0", info: { title: "UnifiedCommerce API", version: config.version ?? "0.0.1" } });
+            return c.json({ ...spec, "x-tagGroups": tagGroups });
+        });
+    }
+    else {
+        app.get("/api/doc", (c) => c.json({ error: { code: "NOT_FOUND", message: "Not found." } }, 404));
+    }
+    // ─── Job Queue ───────────────────────────────────────────────────────
+    // Background job processing: webhook delivery, stale-job reaper, scheduled work.
+    //
+    // 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 { runStaleJobReaper, getJobReapThresholdMs, getJobsReaperIntervalMs } = await import("../kernel/jobs/reaper.js");
+    const taskMap = new Map();
+    for (const task of config.jobs?.tasks ?? []) {
+        const t = task;
+        taskMap.set(t.slug ?? t.name ?? "", task);
+    }
+    const jobLogger = {
+        info: (msg, data) => logger.info(data != null ? { data } : {}, msg),
+        warn: (msg, data) => logger.warn(data != null ? { data } : {}, msg),
+        error: (msg, data) => logger.error(data != null ? { data } : {}, msg),
+    };
+    let lastStaleJobReaperAt = 0;
+    const maybeRunStaleJobReaper = async () => {
+        const interval = getJobsReaperIntervalMs();
+        const now = Date.now();
+        if (now - lastStaleJobReaperAt < interval)
+            return;
+        lastStaleJobReaperAt = now;
+        try {
+            await runStaleJobReaper(kernel.database.db, getJobReapThresholdMs(), jobLogger);
+        }
+        catch (err) {
+            logger.error({ err }, "Stale job reaper failed");
+        }
+    };
+    const runJobs = async (queue, limit) => {
+        await maybeRunStaleJobReaper();
+        return runPendingJobs({
+            db: kernel.database.db,
+            tasks: taskMap,
+            queue: queue ?? "default",
+            limit: limit ?? 10,
+            logger: jobLogger,
+            services: kernel.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");
+        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.");
+    }
+    const dispatchFetch = app.fetch.bind(app);
+    app.fetch = ((input, env, executionCtx) => {
+        const req = input instanceof Request ? input : new Request(input);
+        const rewritten = rewriteCommerceAliasRequest(req, config.entities);
+        return dispatchFetch(rewritten, env, executionCtx);
+    });
+    return { app, kernel, logger, commerce };
+}

package/dist/runtime/shutdown.d.ts

@@ -0,0 +1,15 @@
+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 declare function setupGracefulShutdown(opts: {
+    cleanup: () => Promise<void>;
+    logger: Logger;
+    timeoutMs?: number;
+}): void;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/runtime/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../src/runtime/shutdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CA4BP"}

package/dist/runtime/shutdown.js

@@ -0,0 +1,34 @@
+/**
+ * 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) {
+    const { cleanup, logger, timeoutMs = 30_000 } = opts;
+    let isShuttingDown = false;
+    async function shutdown(signal) {
+        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/dist/runtime/url-alias-rewrite.d.ts

@@ -0,0 +1,3 @@
+import type { CommerceConfig } from "../config/types.js";
+export declare function rewriteCommerceAliasRequest(request: Request, entities: CommerceConfig["entities"] | undefined): Request;
+//# sourceMappingURL=url-alias-rewrite.d.ts.map

package/dist/runtime/url-alias-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-alias-rewrite.d.ts","sourceRoot":"","sources":["../../src/runtime/url-alias-rewrite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,SAAS,GAC/C,OAAO,CAkCT"}

package/dist/runtime/url-alias-rewrite.js

@@ -0,0 +1,33 @@
+export function rewriteCommerceAliasRequest(request, entities) {
+    const url = new URL(request.url);
+    const path = url.pathname;
+    for (const [entityType, entityConfig] of Object.entries(entities ?? {})) {
+        if (!entityConfig.alias)
+            continue;
+        const alias = entityConfig.alias;
+        const prefix = `/api/${alias}`;
+        if (path === prefix) {
+            url.pathname = "/api/catalog/entities";
+            if (request.method === "GET") {
+                url.searchParams.set("type", entityType);
+            }
+            return new Request(url.toString(), request);
+        }
+        if (path.startsWith(`${prefix}/`)) {
+            url.pathname = path.replace(prefix, "/api/catalog/entities");
+            return new Request(url.toString(), request);
+        }
+    }
+    for (const [shortcut, target] of [["categories", "catalog/categories"], ["brands", "catalog/brands"]]) {
+        const prefix = `/api/${shortcut}`;
+        if (path === prefix) {
+            url.pathname = `/api/${target}`;
+            return new Request(url.toString(), request);
+        }
+        if (path.startsWith(`${prefix}/`)) {
+            url.pathname = path.replace(prefix, `/api/${target}`);
+            return new Request(url.toString(), request);
+        }
+    }
+    return request;
+}

package/dist/test-utils/create-pglite-adapter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+/**
+ * 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 declare function createPGliteTestAdapter(): Promise<{
+    adapter: DatabaseAdapter;
+    db: DrizzleDatabase;
+    cleanup: () => Promise<void>;
+}>;
+//# sourceMappingURL=create-pglite-adapter.d.ts.map

package/dist/test-utils/create-pglite-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-pglite-adapter.d.ts","sourceRoot":"","sources":["../../src/test-utils/create-pglite-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAMrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AA0BxE;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC;IACvD,OAAO,EAAE,eAAe,CAAC;IACzB,EAAE,EAAE,eAAe,CAAC;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC,CA+DD"}

package/dist/test-utils/create-pglite-adapter.js

@@ -0,0 +1,107 @@
+/**
+ * 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 { 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";
+// 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) {
+    const coreSchema = getSchema();
+    const drizzleKit = require("drizzle-kit/api");
+    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() {
+    // 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);
+    // 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(fn) {
+        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 = {
+        provider: "postgresql",
+        db,
+        transaction,
+    };
+    /**
+     * Cleanup function to reset data between tests.
+     * Truncates all tables in reverse dependency order with CASCADE.
+     */
+    async function cleanup() {
+        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 };
+}