@unifiedcommerce/core 0.4.4 → 0.5.0

package/dist/kernel/plugin/manifest.d.ts

@@ -0,0 +1,90 @@
+import type { RouteConfig } from "@hono/zod-openapi";
+import type { PluginDb } from "../database/plugin-types.js";
+import type { CommerceConfig, CommercePlugin, MCPTool } from "../../config/types.js";
+export interface PluginLogger {
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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[];
+}
+export declare const _registeredPlugins: Set<string>;
+/** @internal — called by defineConfig() before applying plugins */
+export declare function _resetRegisteredPlugins(): void;
+/**
+ * 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 declare function defineCommercePlugin(manifest: CommercePluginManifest): CommercePlugin;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/kernel/plugin/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/kernel/plugin/manifest.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,OAAO,EACR,MAAM,uBAAuB,CAAC;AAI/B,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAID;;;;;;;;GAQG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,GAC1E;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CAC1C;AAID,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,QAAQ,EAAE;QACR,6EAA6E;QAC7E,EAAE,EAAE,QAAQ,CAAC;QACb,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KAC9D,CAAC;IACF,MAAM,EAAE,YAAY,CAAC;CACtB;AAID;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,sBAAsB,EAAE,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,uBAAuB,EAAE,CAAC;IAC3D,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,OAAO,EAAE,CAAC;IAC7C,eAAe,CAAC,EAAE,MAAM,OAAO,EAAE,CAAC;CACnC;AAKD,eAAO,MAAM,kBAAkB,aAAoB,CAAC;AAEpD,mEAAmE;AACnE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,sBAAsB,GAC/B,cAAc,CA6JhB"}

package/dist/kernel/plugin/manifest.js

@@ -0,0 +1,169 @@
+// ─── Plugin Dependency Tracking ──────────────────────────────────────
+// Accumulates plugin IDs as they register during defineConfig().
+// Reset at the start of each defineConfig() call.
+export const _registeredPlugins = new Set();
+/** @internal — called by defineConfig() before applying plugins */
+export function _resetRegisteredPlugins() {
+    _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) {
+    return (config) => {
+        // ── 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 = {
+                ...(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, kernel) => {
+                    existingRoutes?.(app, kernel);
+                    const k = kernel;
+                    // 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,
+                            transaction: k.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) => {
+                            try {
+                                return await originalHandler(...args);
+                            }
+                            catch (err) {
+                                // Try to extract logger from Hono context
+                                const c = args[0];
+                                const logger = c?.get?.("logger");
+                                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.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;
+                            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) => {
+                    const existing = existingMcpTools?.(kernel) ?? [];
+                    const k = kernel;
+                    return [
+                        ...existing,
+                        ...pluginMcpTools({
+                            config: k.config,
+                            services: k.services,
+                            database: {
+                                db: k.database.db,
+                                transaction: k.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/dist/kernel/query/executor.d.ts

@@ -0,0 +1,21 @@
+import type { QueryRegistry } 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 declare function executeQuery<T = Record<string, unknown>>(registry: QueryRegistry, services: Record<string, unknown>, input: QueryInput): Promise<QueryResult<T>>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/kernel/query/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/kernel/query/executor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EAGd,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAgDzB"}

package/dist/kernel/query/executor.js

@@ -0,0 +1,128 @@
+import { CommerceNotFoundError } from "../errors.js";
+/**
+ * Executes a query against the registry, resolving includes via
+ * batched dataloader-style fetches (one WHERE IN per relation).
+ */
+export async function executeQuery(registry, services, input) {
+    const definition = registry.get(input.entity);
+    if (!definition) {
+        throw new CommerceNotFoundError(`No entity registered with name "${input.entity}".`);
+    }
+    const service = services[definition.service];
+    // 1. Fetch primary records
+    let rows;
+    let total;
+    if (input.id) {
+        const result = (await service[definition.getByIdMethod](input.id));
+        const value = result?.value ?? result;
+        rows = value != null ? [value] : [];
+    }
+    else {
+        const result = (await service[definition.listMethod](input.filters ?? {}, input.pagination));
+        const resolved = result?.value ?? result;
+        if (resolved && typeof resolved === "object" && "items" in resolved) {
+            rows = (resolved.items ?? []);
+            total = resolved.total;
+        }
+        else if (Array.isArray(resolved)) {
+            rows = resolved;
+        }
+        else {
+            rows = [];
+        }
+    }
+    // 2. Resolve includes
+    if (input.include?.length) {
+        await resolveIncludes(rows, input.include, definition, services, registry);
+    }
+    return { data: rows, total };
+}
+async function resolveIncludes(rows, includes, definition, services, registry) {
+    // Group includes by top-level segment
+    const topLevel = new Map();
+    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];
+        if (!targetService)
+            continue;
+        // Collect foreign key values (deduplicated)
+        const ids = [
+            ...new Set(rows
+                .map((r) => r[relation.foreignKey])
+                .filter((v) => 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();
+        for (const related of relatedRows) {
+            const rec = related;
+            if (relation.isList) {
+                const key = rec[relation.foreignKey];
+                if (!map.has(key))
+                    map.set(key, []);
+                map.get(key).push(rec);
+            }
+            else {
+                map.set(rec["id"], rec);
+            }
+        }
+        // Attach to parent rows
+        for (const row of rows) {
+            const fkValue = row[relation.foreignKey];
+            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] ?? [])
+                    : rows
+                        .map((r) => r[relation.attachAs])
+                        .filter(Boolean);
+                await resolveIncludes(nestedRows, nestedIncludes, targetDef, services, registry);
+            }
+        }
+    }
+}
+function extractRows(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object") {
+        const r = result;
+        if (r.value != null) {
+            if (Array.isArray(r.value))
+                return r.value;
+            if (typeof r.value === "object" && "items" in r.value) {
+                return r.value.items;
+            }
+        }
+    }
+    return [];
+}

package/dist/kernel/query/registry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 declare class QueryRegistry {
+    private entities;
+    register(name: string, definition: EntityDefinition): void;
+    get(name: string): EntityDefinition | undefined;
+    has(name: string): boolean;
+    listEntities(): string[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/kernel/query/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/kernel/query/registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC/C;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAuC;IAEvD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAI1D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAI/C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,YAAY,IAAI,MAAM,EAAE;CAGzB"}

package/dist/kernel/query/registry.js

@@ -0,0 +1,20 @@
+/**
+ * Registry of queryable entities and their relations.
+ * Modules register their entities at kernel boot.
+ * Plugins can register additional entities.
+ */
+export class QueryRegistry {
+    entities = new Map();
+    register(name, definition) {
+        this.entities.set(name, definition);
+    }
+    get(name) {
+        return this.entities.get(name);
+    }
+    has(name) {
+        return this.entities.has(name);
+    }
+    listEntities() {
+        return [...this.entities.keys()];
+    }
+}

package/dist/kernel/result.d.ts

@@ -0,0 +1,36 @@
+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 declare function Ok<T>(value: T, meta?: Record<string, unknown>): Result<T, never>;
+export declare function Err<E>(error: E): Result<never, E>;
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export declare function PluginErr(error: string, code?: string): PluginResultErr;
+//# sourceMappingURL=result.d.ts.map

package/dist/kernel/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/kernel/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,aAAa,IACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACnG,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1E,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAKhF;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAEjD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAEvE"}

package/dist/kernel/result.js

@@ -0,0 +1,16 @@
+export function Ok(value, meta) {
+    if (meta !== undefined) {
+        return { ok: true, value, meta };
+    }
+    return { ok: true, value };
+}
+export function Err(error) {
+    return { ok: false, error };
+}
+/**
+ * String-based Err for plugin services.
+ * Usage: `return PluginErr("Not found", "NOT_FOUND")`
+ */
+export function PluginErr(error, code) {
+    return code ? { ok: false, error, code } : { ok: false, error };
+}

package/dist/kernel/schema/extra-columns.d.ts

@@ -0,0 +1,23 @@
+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 declare function mergeExtraColumns<TBase extends Record<string, unknown>>(baseColumns: TBase, extraColumnsFn?: (base: TBase) => Record<string, PgColumnBuilderBase>): TBase & Record<string, PgColumnBuilderBase>;
+//# sourceMappingURL=extra-columns.d.ts.map

package/dist/kernel/schema/extra-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extra-columns.d.ts","sourceRoot":"","sources":["../../../src/kernel/schema/extra-columns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB,CAAC,YAAY,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9E,YAAY,CAAC,EAAE,CACb,WAAW,EAAE,YAAY,KACtB,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAErC,WAAW,EAAE,KAAK,EAClB,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GACpE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAI7C"}

package/dist/kernel/schema/extra-columns.js

@@ -0,0 +1,10 @@
+/**
+ * Merges base columns with optional extra columns from configuration.
+ * Returns the combined column definitions for use in `pgTable()`.
+ */
+export function mergeExtraColumns(baseColumns, extraColumnsFn) {
+    if (!extraColumnsFn)
+        return baseColumns;
+    const extra = extraColumnsFn(baseColumns);
+    return { ...baseColumns, ...extra };
+}