@unifiedcommerce/core 0.2.0 → 0.2.1

package/src/kernel/plugin/manifest.ts

@@ -0,0 +1,271 @@
+import type { Hono } from "hono";
+import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
+import type { PluginDb } from "../database/plugin-types.js";
+import type { DatabaseAdapter } from "../database/adapter.js";
+import type {
+  CommerceConfig,
+  CommercePlugin,
+  MCPTool,
+} from "../../config/types.js";
+
+// ─── Plugin Logger ────────────────────────────────────────────────────
+
+export interface PluginLogger {
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+
+// ─── Plugin Registration Types ────────────────────────────────────────
+
+/**
+ * Plugin route registration. Supports two modes:
+ *
+ * 1. Legacy: { method, path, handler } — works, but invisible to OpenAPI spec.
+ * 2. OpenAPI: { openapi, handler } — validated by Zod, appears in /api/doc.
+ *
+ * Use mode 2 for any route that accepts a request body or returns structured data.
+ * Mode 1 is acceptable for simple routes (health checks, redirects, file serving).
+ */
+export type PluginRouteRegistration =
+  | { method: string; path: string; handler: (...args: unknown[]) => unknown }
+  | { openapi: RouteConfig; handler: (...args: unknown[]) => unknown };
+
+export interface PluginHookRegistration {
+  key: string;
+  handler: (...args: unknown[]) => unknown;
+}
+
+// ─── Plugin Context (available to routes/mcpTools at boot time) ───────
+
+export interface PluginContext {
+  config: CommerceConfig;
+  services: Record<string, unknown>;
+  database: {
+    /** Drizzle database instance — use for queries, inserts, updates, deletes */
+    db: PluginDb;
+    transaction<T>(fn: (tx: PluginDb) => Promise<T>): Promise<T>;
+  };
+  logger: PluginLogger;
+}
+
+// ─── Plugin Manifest (input to defineCommercePlugin) ──────────────────
+
+/**
+ * Permission scope declared by a plugin.
+ * Collected at boot time and available via GET /api/admin/permissions.
+ */
+export interface PluginPermission {
+  /** Permission scope string, e.g., "wishlist:write", "marketplace:admin" */
+  scope: string;
+  /** Human-readable description for admin UIs */
+  description: string;
+}
+
+export interface CommercePluginManifest {
+  id: string;
+  version: string;
+  /**
+   * IDs of plugins that must be registered before this one.
+   * If any required plugin is missing at registration time,
+   * defineCommercePlugin will throw with a clear message.
+   */
+  requires?: string[];
+  /**
+   * Permission scopes this plugin introduces.
+   * Used by admin UIs to build role editors, and validated at boot time
+   * against .permission() calls in routes.
+   */
+  permissions?: PluginPermission[];
+  /**
+   * Returns Drizzle `pgTable` objects that this plugin needs.
+   * These are collected into `config.customSchemas[]` and merged with core
+   * schema by `buildSchema(config)`. Each key becomes a named export in the
+   * merged schema; names must not collide with core table exports.
+   */
+  schema?: () => Record<string, unknown>;
+  hooks?: () => PluginHookRegistration[];
+  routes?: (ctx: PluginContext) => PluginRouteRegistration[];
+  mcpTools?: (ctx: PluginContext) => MCPTool[];
+  analyticsModels?: () => unknown[];
+}
+
+// ─── Plugin Dependency Tracking ──────────────────────────────────────
+// Accumulates plugin IDs as they register during defineConfig().
+// Reset at the start of each defineConfig() call.
+export const _registeredPlugins = new Set<string>();
+
+/** @internal — called by defineConfig() before applying plugins */
+export function _resetRegisteredPlugins(): void {
+  _registeredPlugins.clear();
+}
+
+/**
+ * Converts a plugin manifest into a config transform function.
+ *
+ * - `schema` → pushed into `config.customSchemas`
+ * - `hooks` → merged into `config.hooks` flat map
+ * - `routes` → chained onto `config.routes` (evaluated at boot with kernel)
+ * - `mcpTools` → chained onto `config.mcpTools` (evaluated at boot with kernel)
+ * - `analyticsModels` → pushed into `config.analytics.models`
+ */
+export function defineCommercePlugin(
+  manifest: CommercePluginManifest,
+): CommercePlugin {
+  return (config: CommerceConfig): CommerceConfig => {
+    // ── Dependency check ───────────────────────────────────────────
+    // In test/development, warn instead of throwing so plugins can be
+    // tested in isolation via createPluginTestApp() without installing
+    // all dependencies. In production, this is a hard error.
+    if (manifest.requires) {
+      for (const dep of manifest.requires) {
+        if (!_registeredPlugins.has(dep)) {
+          const msg = `Plugin "${manifest.id}" requires "${dep}" to be installed before it. Add ${dep}Plugin() before ${manifest.id}Plugin() in your config.plugins array.`;
+          if (process.env.NODE_ENV === "production") {
+            throw new Error(msg);
+          }
+          // Non-production: log warning but continue (allows isolated testing)
+          console.warn(`[plugin:${manifest.id}] WARNING: ${msg}`);
+        }
+      }
+    }
+    _registeredPlugins.add(manifest.id);
+    let result = { ...config };
+
+    // 1. Schema — push into customSchemas for kernel to register
+    if (manifest.schema) {
+      const schemas = manifest.schema();
+      result = {
+        ...result,
+        customSchemas: [...(result.customSchemas ?? []), schemas],
+      };
+    }
+
+    // 2. Hooks — merge into flat hooks map (kernel registers at boot)
+    if (manifest.hooks) {
+      const registrations = manifest.hooks();
+      const hookMap: Record<string, Array<(...args: unknown[]) => unknown>> = {
+        ...(result.hooks ?? {}),
+      };
+      for (const reg of registrations) {
+        hookMap[reg.key] = [...(hookMap[reg.key] ?? []), reg.handler];
+      }
+      result = { ...result, hooks: hookMap };
+    }
+
+    // 3. Routes — chain onto config.routes (deferred: needs kernel at boot)
+    if (manifest.routes) {
+      const existingRoutes = result.routes;
+      const pluginRoutes = manifest.routes;
+      result = {
+        ...result,
+        routes: (app: Hono, kernel: unknown) => {
+          existingRoutes?.(app, kernel);
+          const k = kernel as {
+            config: CommerceConfig;
+            services: Record<string, unknown>;
+            database: DatabaseAdapter;
+            logger: PluginLogger;
+          };
+          // Narrow DatabaseAdapter<unknown> → PluginContext.database once here.
+          // All plugin code receives typed PluginDb — no casts downstream.
+          const regs = pluginRoutes({
+            config: k.config,
+            services: k.services,
+            database: {
+              db: k.database.db as PluginDb,
+              transaction: k.database.transaction as PluginContext["database"]["transaction"],
+            },
+            logger: k.logger,
+          });
+          for (const route of regs) {
+            // ── Error boundary: wrap handler with plugin context ──
+            const originalHandler = route.handler;
+            const wrappedHandler = async (...args: unknown[]) => {
+              try {
+                return await originalHandler(...args);
+              } catch (err) {
+                // Try to extract logger from Hono context
+                const c = args[0] as Record<string, unknown>;
+                const logger = (c?.get as Function)?.("logger") as { error: Function } | undefined;
+                logger?.error?.(
+                  { err, plugin: manifest.id },
+                  `[plugin:${manifest.id}] route handler error`,
+                );
+                throw err; // re-throw so global handler still catches
+              }
+            };
+
+            if ("openapi" in route) {
+              // OpenAPI route: validated by Zod, appears in /api/doc
+              // Hono type interop — OpenAPIHono.openapi() expects strict RouteConfig+Handler
+              // generics that can't be statically resolved for dynamic plugin routes.
+              // @ts-expect-error -- dynamic plugin routes cannot satisfy Hono's strict handler generics
+              (app as OpenAPIHono).openapi(route.openapi, wrappedHandler);
+            } else {
+              // Legacy route: raw handler, invisible to OpenAPI spec.
+              // Explicit dispatch avoids casting Hono to a Record.
+              // Handler cast is a single `as any` (Hono's overloaded method
+              // signatures can't unify with our generic handler shape).
+              const h = wrappedHandler as any;
+              switch (route.method.toLowerCase()) {
+                case "get":     app.get(route.path, h); break;
+                case "post":    app.post(route.path, h); break;
+                case "put":     app.put(route.path, h); break;
+                case "patch":   app.patch(route.path, h); break;
+                case "delete":  app.delete(route.path, h); break;
+                case "options": app.options(route.path, h); break;
+                default:
+                  console.warn(`[plugin:${manifest.id}] unsupported HTTP method "${route.method}" for ${route.path}`);
+              }
+            }
+          }
+        },
+      };
+    }
+
+    // 4. MCP Tools — chain onto config.mcpTools (deferred: needs kernel)
+    if (manifest.mcpTools) {
+      const existingMcpTools = result.mcpTools;
+      const pluginMcpTools = manifest.mcpTools;
+      result = {
+        ...result,
+        mcpTools: (kernel: unknown) => {
+          const existing = existingMcpTools?.(kernel) ?? [];
+          const k = kernel as {
+            config: CommerceConfig;
+            services: Record<string, unknown>;
+            database: DatabaseAdapter;
+            logger: PluginLogger;
+          };
+          return [
+            ...existing,
+            ...pluginMcpTools({
+              config: k.config,
+              services: k.services,
+              database: {
+                db: k.database.db as PluginDb,
+                transaction: k.database.transaction as PluginContext["database"]["transaction"],
+              },
+              logger: k.logger,
+            }),
+          ];
+        },
+      };
+    }
+
+    // 5. Analytics models — push into config.analytics.models
+    if (manifest.analyticsModels) {
+      const models = manifest.analyticsModels();
+      result = {
+        ...result,
+        analytics: {
+          ...result.analytics,
+          models: [...(result.analytics?.models ?? []), ...models],
+        },
+      };
+    }
+
+    return result;
+  };
+}

package/src/kernel/query/executor.ts

@@ -0,0 +1,184 @@
+import { CommerceNotFoundError } from "../errors.js";
+import type {
+  QueryRegistry,
+  EntityDefinition,
+  RelationDefinition,
+} from "./registry.js";
+
+export interface QueryInput {
+  entity: string;
+  id?: string;
+  filters?: Record<string, unknown>;
+  include?: string[];
+  pagination?: { limit?: number; offset?: number };
+}
+
+export interface QueryResult<T = Record<string, unknown>> {
+  data: T[];
+  total?: number | undefined;
+}
+
+/**
+ * Executes a query against the registry, resolving includes via
+ * batched dataloader-style fetches (one WHERE IN per relation).
+ */
+export async function executeQuery<T = Record<string, unknown>>(
+  registry: QueryRegistry,
+  services: Record<string, unknown>,
+  input: QueryInput,
+): Promise<QueryResult<T>> {
+  const definition = registry.get(input.entity);
+  if (!definition) {
+    throw new CommerceNotFoundError(
+      `No entity registered with name "${input.entity}".`,
+    );
+  }
+
+  const service = services[definition.service] as Record<
+    string,
+    (...args: unknown[]) => Promise<unknown>
+  >;
+
+  // 1. Fetch primary records
+  let rows: Record<string, unknown>[];
+  let total: number | undefined;
+
+  if (input.id) {
+    const result = (await service[definition.getByIdMethod]!(
+      input.id,
+    )) as { ok?: boolean; value?: unknown };
+    const value = result?.value ?? result;
+    rows = value != null ? [value as Record<string, unknown>] : [];
+  } else {
+    const result = (await service[definition.listMethod]!(
+      input.filters ?? {},
+      input.pagination,
+    )) as {
+      ok?: boolean;
+      value?: { items?: unknown[]; total?: number };
+    };
+    const resolved = result?.value ?? result;
+    if (resolved && typeof resolved === "object" && "items" in resolved) {
+      rows = (resolved.items ?? []) as Record<string, unknown>[];
+      total = resolved.total;
+    } else if (Array.isArray(resolved)) {
+      rows = resolved as Record<string, unknown>[];
+    } else {
+      rows = [];
+    }
+  }
+
+  // 2. Resolve includes
+  if (input.include?.length) {
+    await resolveIncludes(rows, input.include, definition, services, registry);
+  }
+
+  return { data: rows as T[], total };
+}
+
+async function resolveIncludes(
+  rows: Record<string, unknown>[],
+  includes: string[],
+  definition: EntityDefinition,
+  services: Record<string, unknown>,
+  registry: QueryRegistry,
+): Promise<void> {
+  // Group includes by top-level segment
+  const topLevel = new Map<string, string[]>();
+  for (const path of includes) {
+    const dot = path.indexOf(".");
+    if (dot === -1) {
+      if (!topLevel.has(path)) topLevel.set(path, []);
+    } else {
+      const parent = path.substring(0, dot);
+      const child = path.substring(dot + 1);
+      const existing = topLevel.get(parent) ?? [];
+      existing.push(child);
+      topLevel.set(parent, existing);
+    }
+  }
+
+  for (const [relationName, nestedIncludes] of topLevel) {
+    const relation = definition.relations[relationName];
+    if (!relation) continue;
+
+    const targetService = services[relation.targetService] as
+      | Record<string, (...args: unknown[]) => Promise<unknown>>
+      | undefined;
+    if (!targetService) continue;
+
+    // Collect foreign key values (deduplicated)
+    const ids = [
+      ...new Set(
+        rows
+          .map((r) => r[relation.foreignKey])
+          .filter((v): v is string => v != null && typeof v === "string"),
+      ),
+    ];
+    if (ids.length === 0) continue;
+
+    // One batched query
+    const batchFn = targetService[relation.batchMethod];
+    if (!batchFn) continue;
+
+    const relatedResult = await batchFn(ids);
+    const relatedRows = extractRows(relatedResult);
+
+    // Build lookup
+    const map = new Map<string, unknown>();
+    for (const related of relatedRows) {
+      const rec = related as Record<string, unknown>;
+      if (relation.isList) {
+        const key = rec[relation.foreignKey] as string;
+        if (!map.has(key)) map.set(key, []);
+        (map.get(key) as unknown[]).push(rec);
+      } else {
+        map.set(rec["id"] as string, rec);
+      }
+    }
+
+    // Attach to parent rows
+    for (const row of rows) {
+      const fkValue = row[relation.foreignKey] as string | undefined;
+      if (!fkValue) continue;
+      row[relation.attachAs] =
+        map.get(fkValue) ?? (relation.isList ? [] : null);
+    }
+
+    // Resolve nested includes
+    if (nestedIncludes.length > 0) {
+      const targetDef = registry.get(relation.targetService);
+      if (targetDef) {
+        const nestedRows = relation.isList
+          ? rows.flatMap(
+              (r) =>
+                (r[relation.attachAs] as Record<string, unknown>[]) ?? [],
+            )
+          : rows
+              .map((r) => r[relation.attachAs] as Record<string, unknown>)
+              .filter(Boolean);
+        await resolveIncludes(
+          nestedRows,
+          nestedIncludes,
+          targetDef,
+          services,
+          registry,
+        );
+      }
+    }
+  }
+}
+
+function extractRows(result: unknown): unknown[] {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object") {
+    const r = result as { ok?: boolean; value?: unknown };
+    if (r.value != null) {
+      if (Array.isArray(r.value)) return r.value;
+      if (typeof r.value === "object" && "items" in r.value) {
+        return (r.value as { items: unknown[] }).items;
+      }
+    }
+  }
+  return [];
+}

package/src/kernel/query/registry.ts

@@ -0,0 +1,46 @@
+/**
+ * Defines a relation from a parent entity to a related entity.
+ * Used by the query executor to batch-load related records.
+ */
+export interface RelationDefinition {
+  foreignKey: string;
+  targetService: string;
+  batchMethod: string;
+  attachAs: string;
+  isList?: boolean;
+}
+
+/**
+ * Defines an entity that can be queried via kernel.query().
+ */
+export interface EntityDefinition {
+  service: string;
+  getByIdMethod: string;
+  listMethod: string;
+  relations: Record<string, RelationDefinition>;
+}
+
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export class QueryRegistry {
+  private entities = new Map<string, EntityDefinition>();
+
+  register(name: string, definition: EntityDefinition): void {
+    this.entities.set(name, definition);
+  }
+
+  get(name: string): EntityDefinition | undefined {
+    return this.entities.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.entities.has(name);
+  }
+
+  listEntities(): string[] {
+    return [...this.entities.keys()];
+  }
+}

package/src/kernel/result.ts

@@ -0,0 +1,33 @@
+import type { CommerceError } from "./errors.js";
+
+export type Result<T, E = CommerceError> =
+  | { ok: true; value: T; meta?: Record<string, unknown> }
+  | { ok: false; error: E };
+
+/**
+ * Simplified Result types for plugin services.
+ * Plugin services return `PluginResult<T>` instead of `Result<T, CommerceError>`.
+ * This matches the `{ ok: true; value: T } | { ok: false; error: string }` pattern
+ * that every plugin has been copy-pasting.
+ */
+export type PluginResult<T> = { ok: true; value: T } | { ok: false; error: string; code?: string };
+export type PluginResultErr = { ok: false; error: string; code?: string };
+
+export function Ok<T>(value: T, meta?: Record<string, unknown>): Result<T, never> {
+  if (meta !== undefined) {
+    return { ok: true, value, meta };
+  }
+  return { ok: true, value };
+}
+
+export function Err<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export function PluginErr(error: string, code?: string): PluginResultErr {
+  return code ? { ok: false, error, code } : { ok: false, error };
+}

package/src/kernel/schema/extra-columns.ts

@@ -0,0 +1,37 @@
+import type { PgColumnBuilderBase } from "drizzle-orm/pg-core";
+
+/**
+ * Options for modules that support schema extension via extra columns.
+ *
+ * Usage:
+ * ```typescript
+ * const catalogModule = createCatalogModule({
+ *   extraColumns: (base) => ({
+ *     supplierCode: text("supplier_code"),
+ *     gtin: text("gtin").unique(),
+ *   }),
+ * });
+ * ```
+ */
+export interface ExtraColumnsOption<TBaseColumns extends Record<string, unknown>> {
+  extraColumns?: (
+    baseColumns: TBaseColumns,
+  ) => Record<string, PgColumnBuilderBase>;
+}
+
+/**
+ * Merges base columns with optional extra columns from configuration.
+ * Returns the combined column definitions for use in `pgTable()`.
+ */
+export function mergeExtraColumns<
+  TBase extends Record<string, unknown>,
+>(
+  baseColumns: TBase,
+  extraColumnsFn?: (base: TBase) => Record<string, PgColumnBuilderBase>,
+): TBase & Record<string, PgColumnBuilderBase> {
+  if (!extraColumnsFn) return baseColumns as TBase & Record<string, PgColumnBuilderBase>;
+  const extra = extraColumnsFn(baseColumns);
+  return { ...baseColumns, ...extra };
+}
+
+

package/src/kernel/service-registry.ts

@@ -0,0 +1,76 @@
+/**
+ * ServiceRegistry -- typed surface of the kernel service container
+ * for plugin-to-plugin communication.
+ *
+ * Plugin services accept this as an optional constructor parameter
+ * to call core services without resorting to raw SQL.
+ *
+ * Core services are loosely typed here (method signatures use `unknown`)
+ * to avoid plugin packages depending on core's internal service types.
+ * Plugin authors cast the return values at the call site.
+ *
+ * Usage in a plugin service:
+ *
+ *   import type { ServiceRegistry } from "@unifiedcommerce/core";
+ *
+ *   class MyService {
+ *     constructor(private db: PluginDb, private services?: ServiceRegistry) {}
+ *
+ *     async doWork() {
+ *       const result = await this.services?.inventory.adjust({
+ *         entityId: "...", adjustment: -5, reason: "recipe deduction"
+ *       }, actor);
+ *     }
+ *   }
+ */
+
+export interface ServiceRegistry {
+  inventory: {
+    adjust(
+      input: {
+        entityId: string;
+        variantId?: string;
+        warehouseId?: string;
+        adjustment: number;
+        reason?: string;
+      },
+      actor?: unknown,
+    ): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    createWarehouse(
+      input: { name: string; code: string },
+      actor?: unknown,
+    ): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    reserve(input: unknown, actor?: unknown): Promise<unknown>;
+    release(input: unknown, actor?: unknown): Promise<unknown>;
+    getAvailable(input: unknown, actor?: unknown): Promise<unknown>;
+    [method: string]: unknown;
+  };
+  catalog: {
+    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    getById(id: string, options?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    publish(id: string, actor?: unknown): Promise<unknown>;
+    list(input?: unknown): Promise<unknown>;
+    [method: string]: unknown;
+  };
+  customers: {
+    getByUserId(userId: string, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    getById(id: string, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    [method: string]: unknown;
+  };
+  orders: {
+    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    changeStatus(input: unknown, actor?: unknown): Promise<unknown>;
+    [method: string]: unknown;
+  };
+  cart: {
+    create(input: unknown, actor?: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    [method: string]: unknown;
+  };
+  organization: {
+    create(input: unknown): Promise<{ ok: boolean; value?: unknown; error?: unknown }>;
+    getById(id: string): Promise<unknown>;
+    [method: string]: unknown;
+  };
+  /** Access plugin-registered services by plugin ID or service name */
+  [key: string]: unknown;
+}