@porulle/core 0.1.0

package/src/runtime/kernel-register-hooks.ts

@@ -0,0 +1,63 @@
+import type { CommerceConfig } from "../config/types.js";
+import { HookRegistry, type HookHandler } from "../kernel/hooks/registry.js";
+import { deliverWebhooks } from "../modules/webhooks/hook.js";
+import { syncToSearchIndex } from "../modules/search/hooks.js";
+import { auditHooks } from "../modules/audit/hooks.js";
+import { sendOrderStatusEmail } from "../hooks/order-emails.js";
+
+export function registerConfiguredKernelHooks(
+  config: CommerceConfig,
+  hooks: HookRegistry,
+): void {
+  for (const [entityType, entityConfig] of Object.entries(
+    config.entities ?? {},
+  )) {
+    const entityHooks = entityConfig.hooks ?? {};
+    for (const [hookName, handlers] of Object.entries(entityHooks)) {
+      hooks.registerConfigHooks(
+        `catalog.${entityType}.${hookName}`,
+        handlers ?? [],
+      );
+    }
+  }
+
+  for (const [moduleName, moduleConfig] of [
+    ["cart", config.cart],
+    ["checkout", config.checkout],
+    ["orders", config.orders],
+    ["inventory", config.inventory],
+  ] as const) {
+    const hooksObject = moduleConfig?.hooks;
+    if (!hooksObject) continue;
+    for (const [hookName, handlers] of Object.entries(hooksObject)) {
+      const normalizedHandlers = (Array.isArray(handlers) ? handlers : []) as HookHandler[];
+      hooks.registerConfigHooks(
+        `${moduleName}.${hookName}`,
+        normalizedHandlers,
+      );
+    }
+  }
+
+  hooks.append("orders.afterCreate", deliverWebhooks);
+  hooks.append("orders.afterStatusChange", deliverWebhooks);
+  hooks.append("orders.afterStatusChange", sendOrderStatusEmail as (...args: unknown[]) => unknown);
+  hooks.append("catalog.afterCreate", deliverWebhooks);
+  hooks.append("catalog.afterUpdate", deliverWebhooks);
+  hooks.append("catalog.afterDelete", deliverWebhooks);
+  hooks.append("inventory.afterAdjust", deliverWebhooks);
+  hooks.append("customers.afterCreate", deliverWebhooks);
+  hooks.append("customers.afterUpdate", deliverWebhooks);
+  hooks.append("pricing.afterCreate", deliverWebhooks);
+  hooks.append("pricing.afterUpdate", deliverWebhooks);
+  hooks.append("promotions.afterCreate", deliverWebhooks);
+  hooks.append("promotions.afterUpdate", deliverWebhooks);
+  hooks.append("fulfillment.afterCreate", deliverWebhooks);
+  hooks.append("cart.afterAddItem", deliverWebhooks);
+
+  hooks.append("catalog.afterCreate", syncToSearchIndex);
+  hooks.append("catalog.afterUpdate", syncToSearchIndex);
+
+  for (const [key, handler] of Object.entries(auditHooks)) {
+    hooks.append(key, handler);
+  }
+}

package/src/runtime/kernel-types.ts

@@ -0,0 +1,109 @@
+import type {
+  CommerceConfig,
+  PluginPermission,
+} from "../config/types.js";
+import type { HookRegistry } from "../kernel/hooks/registry.js";
+import type { DatabaseAdapter } from "../kernel/database/adapter.js";
+import { CatalogServiceImpl } from "../modules/catalog/service.js";
+import { InventoryService } from "../modules/inventory/service.js";
+import { MediaService } from "../modules/media/service.js";
+import { CartService } from "../modules/cart/service.js";
+import { OrderService } from "../modules/orders/service.js";
+import { PaymentsService } from "../modules/payments/service.js";
+import { FulfillmentService } from "../modules/fulfillment/service.js";
+import { CustomerService } from "../modules/customers/service.js";
+import { WebhookService } from "../modules/webhooks/service.js";
+import { AnalyticsService } from "../modules/analytics/service.js";
+import { PricingService } from "../modules/pricing/service.js";
+import { PromotionService } from "../modules/promotions/service.js";
+import { TaxService } from "../modules/tax/service.js";
+import { ShippingService } from "../modules/shipping/service.js";
+import { SearchService } from "../modules/search/service.js";
+import type { AuditService } from "../modules/audit/service.js";
+import { OrganizationService } from "../modules/organization/service.js";
+import { createLogger } from "../utils/logger.js";
+import { CompensationFailuresRepository } from "../kernel/compensation/repository.js";
+
+export interface WebhookDeliveryPayload {
+  endpoint: { id: string; url: string; secret: string };
+  eventName: string;
+  payload: unknown;
+}
+
+export interface Kernel {
+  config: CommerceConfig;
+  hooks: HookRegistry;
+  database: DatabaseAdapter;
+  services: {
+    catalog: CatalogServiceImpl;
+    inventory: InventoryService;
+    media: MediaService;
+    cart: CartService;
+    orders: OrderService;
+    payments: PaymentsService;
+    fulfillment: FulfillmentService;
+    customers: CustomerService;
+    webhooks: WebhookService & {
+      enqueueDelivery(payload: WebhookDeliveryPayload): Promise<void>;
+    };
+    analytics: AnalyticsService;
+    pricing: PricingService;
+    promotions: PromotionService;
+    tax: TaxService;
+    shipping: ShippingService;
+    search: SearchService;
+    audit: AuditService;
+    compensationFailures: CompensationFailuresRepository;
+    email: CommerceConfig["email"];
+    organization: OrganizationService;
+  };
+  pluginPermissions: PluginPermission[];
+  logger: ReturnType<typeof createLogger>;
+}
+
+export const KERNEL_REQUIRED_SERVICE_KEYS = [
+  "catalog",
+  "inventory",
+  "media",
+  "cart",
+  "orders",
+  "payments",
+  "fulfillment",
+  "customers",
+  "webhooks",
+  "analytics",
+  "pricing",
+  "promotions",
+  "tax",
+  "shipping",
+  "search",
+  "audit",
+  "compensationFailures",
+] as const satisfies Array<keyof Kernel["services"]>;
+
+export function assertKernelServicesReady(
+  services: Partial<Kernel["services"]>,
+): asserts services is Kernel["services"] {
+  for (const key of KERNEL_REQUIRED_SERVICE_KEYS) {
+    if (services[key] === undefined) {
+      throw new Error(`Kernel service "${String(key)}" was not initialized.`);
+    }
+  }
+}
+
+export function assertSortedBefore(
+  topo: readonly string[],
+  a: string,
+  b: string,
+): void {
+  const ia = topo.indexOf(a);
+  const ib = topo.indexOf(b);
+  if (ia < 0 || ib < 0) {
+    throw new Error(`kernelModuleInstantiationOrder missing key: ${a} or ${b}`);
+  }
+  if (ia >= ib) {
+    throw new Error(
+      `Invalid kernel topo order: expected "${a}" before "${b}" (indices ${ia}, ${ib})`,
+    );
+  }
+}

package/src/runtime/kernel.ts

@@ -0,0 +1,159 @@
+import type { CommerceConfig } from "../config/types.js";
+import { HookRegistry, type HookHandler } from "../kernel/hooks/registry.js";
+import { createDatabaseConnection } from "../kernel/database/adapter.js";
+import type { DrizzleDatabase } from "../kernel/database/drizzle-db.js";
+import type { AppModule } from "../kernel/module/index.js";
+import { topoSortModules } from "../kernel/module/index.js";
+import { WebhookDeliveryWorker } from "../modules/webhooks/worker.js";
+import { WebhooksRepository } from "../modules/webhooks/repository/index.js";
+import { createLogger } from "../utils/logger.js";
+import { withTiming } from "../kernel/service-timing.js";
+import { setBootDefaultOrgId } from "../auth/org.js";
+import { setBootStrictOrgResolution } from "../auth/strict-org-resolution.js";
+import { DrizzleJobsAdapter } from "../kernel/jobs/drizzle-adapter.js";
+import { CompensationFailuresRepository } from "../kernel/compensation/repository.js";
+
+import {
+  KERNEL_ALL_MODULES,
+  kernelModulesForTopoSort,
+} from "./kernel-modules.js";
+import { registerConfiguredKernelHooks } from "./kernel-register-hooks.js";
+import {
+  assertKernelServicesReady,
+  assertSortedBefore,
+  type Kernel,
+  type WebhookDeliveryPayload,
+} from "./kernel-types.js";
+
+export type { Kernel, WebhookDeliveryPayload };
+export {
+  KERNEL_ALL_MODULES,
+  kernelModuleInstantiationOrder,
+} from "./kernel-modules.js";
+
+export function createKernel(config: CommerceConfig): Kernel {
+  const hooks = new HookRegistry();
+  const logger = createLogger("kernel");
+  hooks.setLogger({ error: (obj, msg) => logger.error(msg, obj) });
+
+  // Apply boot-time org resolution settings from config. Previously only
+  // createCommerce did this, which meant tests calling createKernel directly
+  // had services fall back to DEFAULT_ORG_ID with a deprecation warning even
+  // when config.auth.defaultOrganizationId was set.
+  setBootStrictOrgResolution(config.auth?.strictOrgResolution === true);
+  if (config.auth?.defaultOrganizationId) {
+    setBootDefaultOrgId(config.auth.defaultOrganizationId);
+  }
+
+  if (!config.storage) {
+    throw new Error(
+      "Storage adapter is required. Configure `storage` in defineConfig (for example: localStorageAdapter for development, or s3StorageAdapter/r2StorageAdapter for object storage).",
+    );
+  }
+
+  const database = createDatabaseConnection({
+    adapter: config.databaseAdapter ?? {
+      provider: config.database.provider,
+      db: {},
+      async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+        return fn({});
+      },
+    },
+  });
+  const services: Partial<Kernel["services"]> = {
+    email: config.email,
+  };
+
+  const serviceContainer = services as Record<string, unknown>;
+  serviceContainer.database = database;
+
+  const db = database.db as DrizzleDatabase;
+
+  const jobsTaskMap = new Map(
+    (config.jobs?.tasks ?? []).map((t) => [t.slug, t]),
+  );
+  const jobsAdapter = new DrizzleJobsAdapter(db, jobsTaskMap);
+  serviceContainer.jobs = jobsAdapter;
+
+  const topoGraph = kernelModulesForTopoSort();
+  const order = topoSortModules(topoGraph);
+  const moduleKeys = Object.keys(KERNEL_ALL_MODULES);
+  if (order.length !== moduleKeys.length) {
+    throw new Error(
+      `topoSortModules length mismatch: got ${order.length}, expected ${moduleKeys.length}`,
+    );
+  }
+  assertSortedBefore(order, "catalog", "inventory");
+  assertSortedBefore(order, "catalog", "pricing");
+
+  const moduleDeps = {
+    db: database,
+    hooks,
+    config,
+    logger,
+  };
+
+  for (const id of order) {
+    const mod = KERNEL_ALL_MODULES[id as keyof typeof KERNEL_ALL_MODULES];
+    const svc = (mod as AppModule<unknown, unknown, Record<string, unknown>>).service({
+      ...moduleDeps,
+      services: services as Record<string, unknown>,
+    });
+    (services as Record<string, unknown>)[id] = svc;
+  }
+
+  const baseWebhooks = services.webhooks!;
+  const webhookWorker = new WebhookDeliveryWorker({
+    repository: new WebhooksRepository(db),
+  });
+  services.webhooks = Object.assign(baseWebhooks, {
+    async enqueueDelivery(payload: WebhookDeliveryPayload) {
+      await webhookWorker.deliver(payload);
+    },
+  });
+
+  services.compensationFailures = new CompensationFailuresRepository(db);
+
+  assertKernelServicesReady(services);
+
+  if (process.env.NODE_ENV !== "test") {
+    const timedLogger = {
+      info: (obj: Record<string, unknown>, msg: string) => logger.info(msg, obj),
+      error: (obj: Record<string, unknown>, msg: string) => logger.error(msg, obj),
+    };
+    const serviceKeys = Object.keys(services) as Array<keyof typeof services>;
+    for (const key of serviceKeys) {
+      const svc = services[key];
+      if (svc && typeof svc === "object" && key !== "email") {
+        (services as Record<string, unknown>)[key] = withTiming(
+          svc as object,
+          key,
+          timedLogger,
+        );
+      }
+    }
+  }
+
+  registerConfiguredKernelHooks(config, hooks);
+
+  const kernel: Kernel = {
+    config,
+    hooks,
+    database,
+    services,
+    pluginPermissions: [...(config.pluginPermissions ?? [])],
+    logger,
+  };
+
+  for (const [key, handlers] of Object.entries(config.hooks ?? {})) {
+    for (const handler of handlers) {
+      hooks.append(key, handler as HookHandler);
+    }
+  }
+
+  for (const model of config.analytics?.models ?? []) {
+    services.analytics.registerModel(model);
+  }
+
+  return kernel;
+}

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 }),
+    },
+  });
+}