@usebetterdev/plugin 0.5.0 → 0.6.0

package/dist/hook-registry.d.ts

@@ -0,0 +1,68 @@
+import type { HookContract, HookHandlers } from "./types.js";
+/**
+ * Error captured when a plugin hook handler fails during `invokeAfter`.
+ */
+export interface PluginError {
+    pluginId: string;
+    hook: string;
+    error: unknown;
+}
+/**
+ * Error thrown by `invokeBefore` when a plugin hook handler fails.
+ * Wraps the original error with plugin and hook context so callers
+ * can identify which plugin caused the failure.
+ */
+export declare class PluginInvokeError extends Error {
+    readonly name = "PluginInvokeError";
+    readonly pluginId: string;
+    readonly hook: string;
+    constructor(pluginId: string, hook: string, cause: unknown);
+}
+/**
+ * Runtime registry that products use to register plugin hooks and invoke them
+ * at lifecycle points.
+ *
+ * Generic over THooks so products get type-safe hook names and payloads.
+ */
+export declare class HookRegistry<THooks extends HookContract> {
+    private hooks;
+    private registeredPlugins;
+    /**
+     * Register all hooks declared by a plugin. Skips entries whose value is not
+     * a function (defensive against partial/optional declarations).
+     *
+     * Throws if a plugin with the same ID has already been registered.
+     */
+    register(pluginId: string, hooks: Partial<HookHandlers<THooks>>): void;
+    /**
+     * Sequential, fail-fast invocation — for "before" hooks.
+     * Runs handlers in registration order. Aborts on first throw and wraps
+     * the error in a {@link PluginInvokeError} so the caller knows which
+     * plugin failed. Later handlers are **not** called.
+     *
+     * Uses a snapshot of the handler list so that registrations during
+     * async execution do not affect the current invocation.
+     */
+    invokeBefore<K extends keyof THooks & string>(hook: K, payload: THooks[K]): Promise<void>;
+    /**
+     * Sequential, collect-errors invocation — for "after" hooks.
+     * Runs **all** handlers even when some fail. Failures are wrapped in
+     * {@link PluginError} and returned as an array. Returns an empty array
+     * when all handlers succeed or when no handlers are registered.
+     *
+     * Uses a snapshot of the handler list so that registrations during
+     * async execution do not affect the current invocation.
+     */
+    invokeAfter<K extends keyof THooks & string>(hook: K, payload: THooks[K]): Promise<PluginError[]>;
+    /**
+     * Calls a stored handler with the given payload.
+     *
+     * Handlers are stored as `(payload: never) => …` for variance compatibility
+     * (see {@link RegisteredHook}). At runtime the payload always matches
+     * `THooks[K]` — guaranteed by the generic constraint on {@link register}.
+     * This single assertion is the only place where TypeScript's type system
+     * cannot statically verify the heterogeneous map access.
+     */
+    private callHandler;
+}
+//# sourceMappingURL=hook-registry.d.ts.map

package/dist/hook-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.d.ts","sourceRoot":"","sources":["../src/hook-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAQ3D;AAYD;;;;;GAKG;AACH,qBAAa,YAAY,CAAC,MAAM,SAAS,YAAY;IACnD,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,iBAAiB,CAAqB;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI;IAoBtE;;;;;;;;OAQG;IACG,YAAY,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAChD,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,GACjB,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,SAAS,MAAM,MAAM,GAAG,MAAM,EAC/C,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,GACjB,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAMpB"}

package/dist/index.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,5 +19,215 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/index.ts
 var index_exports = {};
+__export(index_exports, {
+  HookRegistry: () => HookRegistry,
+  PluginInitError: () => PluginInitError,
+  PluginInvokeError: () => PluginInvokeError,
+  assertDefined: () => assertDefined,
+  assertOneOf: () => assertOneOf,
+  mergeSchemas: () => mergeSchemas,
+  resolvePlugins: () => resolvePlugins
+});
 module.exports = __toCommonJS(index_exports);
+
+// src/hook-registry.ts
+var PluginInvokeError = class extends Error {
+  name = "PluginInvokeError";
+  pluginId;
+  hook;
+  constructor(pluginId, hook, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Plugin "${pluginId}" failed on hook "${hook}": ${detail}`, {
+      cause
+    });
+    this.pluginId = pluginId;
+    this.hook = hook;
+  }
+};
+var HookRegistry = class {
+  hooks = /* @__PURE__ */ new Map();
+  registeredPlugins = /* @__PURE__ */ new Set();
+  /**
+   * Register all hooks declared by a plugin. Skips entries whose value is not
+   * a function (defensive against partial/optional declarations).
+   *
+   * Throws if a plugin with the same ID has already been registered.
+   */
+  register(pluginId, hooks) {
+    if (this.registeredPlugins.has(pluginId)) {
+      throw new Error(`Plugin "${pluginId}" is already registered`);
+    }
+    this.registeredPlugins.add(pluginId);
+    for (const [key, handler] of Object.entries(hooks)) {
+      if (typeof handler !== "function") {
+        continue;
+      }
+      let list = this.hooks.get(key);
+      if (list === void 0) {
+        list = [];
+        this.hooks.set(key, list);
+      }
+      list.push({ pluginId, handler });
+    }
+  }
+  /**
+   * Sequential, fail-fast invocation — for "before" hooks.
+   * Runs handlers in registration order. Aborts on first throw and wraps
+   * the error in a {@link PluginInvokeError} so the caller knows which
+   * plugin failed. Later handlers are **not** called.
+   *
+   * Uses a snapshot of the handler list so that registrations during
+   * async execution do not affect the current invocation.
+   */
+  async invokeBefore(hook, payload) {
+    const list = this.hooks.get(hook);
+    if (list === void 0) {
+      return;
+    }
+    const snapshot = [...list];
+    for (const entry of snapshot) {
+      try {
+        await this.callHandler(entry.handler, payload);
+      } catch (error) {
+        throw new PluginInvokeError(entry.pluginId, hook, error);
+      }
+    }
+  }
+  /**
+   * Sequential, collect-errors invocation — for "after" hooks.
+   * Runs **all** handlers even when some fail. Failures are wrapped in
+   * {@link PluginError} and returned as an array. Returns an empty array
+   * when all handlers succeed or when no handlers are registered.
+   *
+   * Uses a snapshot of the handler list so that registrations during
+   * async execution do not affect the current invocation.
+   */
+  async invokeAfter(hook, payload) {
+    const list = this.hooks.get(hook);
+    if (list === void 0) {
+      return [];
+    }
+    const errors = [];
+    const snapshot = [...list];
+    for (const entry of snapshot) {
+      try {
+        await this.callHandler(entry.handler, payload);
+      } catch (error) {
+        errors.push({
+          pluginId: entry.pluginId,
+          hook,
+          error
+        });
+      }
+    }
+    return errors;
+  }
+  /**
+   * Calls a stored handler with the given payload.
+   *
+   * Handlers are stored as `(payload: never) => …` for variance compatibility
+   * (see {@link RegisteredHook}). At runtime the payload always matches
+   * `THooks[K]` — guaranteed by the generic constraint on {@link register}.
+   * This single assertion is the only place where TypeScript's type system
+   * cannot statically verify the heterogeneous map access.
+   */
+  callHandler(handler, payload) {
+    return handler(payload);
+  }
+};
+
+// src/validation.ts
+function assertDefined(value, name) {
+  if (value === void 0) {
+    throw new Error(`Plugin config error: "${name}" is required`);
+  }
+}
+function assertOneOf(value, allowed, name) {
+  if (!allowed.includes(value)) {
+    const allowedStr = allowed.join(", ");
+    throw new Error(
+      `Plugin config error: "${name}" must be one of: ${allowedStr} (got: ${String(value)})`
+    );
+  }
+}
+
+// src/schema.ts
+function mergeSchemas(_plugins) {
+  return { tables: {}, extend: {} };
+}
+
+// src/resolve-plugins.ts
+var PluginInitError = class extends Error {
+  name = "PluginInitError";
+  pluginId;
+  constructor(pluginId, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Plugin "${pluginId}" failed during init: ${detail}`, { cause });
+    this.pluginId = pluginId;
+  }
+};
+async function resolvePlugins(productId, plugins, config) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    if (!plugin.id || !plugin.id.trim()) {
+      throw new Error('Plugin config error: "id" is required');
+    }
+    if (plugin.id !== plugin.id.trim()) {
+      throw new Error(
+        `Plugin config error: "id" must not have leading or trailing whitespace (got: "${plugin.id}")`
+      );
+    }
+    if (seen.has(plugin.id)) {
+      throw new Error(`Duplicate plugin ID: "${plugin.id}"`);
+    }
+    seen.add(plugin.id);
+  }
+  const hookRegistry = new HookRegistry();
+  for (const plugin of plugins) {
+    if (plugin.hooks) {
+      hookRegistry.register(plugin.id, plugin.hooks);
+    }
+  }
+  const endpoints = [];
+  for (const plugin of plugins) {
+    if (plugin.endpoints) {
+      for (const ep of plugin.endpoints) {
+        if (!ep.path || !ep.path.startsWith("/")) {
+          throw new Error(
+            `Plugin "${plugin.id}" endpoint path must start with "/" (got: "${ep.path}")`
+          );
+        }
+        endpoints.push({ ...ep, pluginId: plugin.id });
+      }
+    }
+  }
+  const schema = mergeSchemas(plugins);
+  const pluginIds = plugins.map((p) => p.id);
+  const frozenConfig = Object.freeze({ ...config });
+  const context = {
+    productId,
+    hasPlugin: (id) => seen.has(id),
+    config: frozenConfig
+  };
+  for (const plugin of plugins) {
+    if (plugin.init) {
+      try {
+        await plugin.init(context);
+      } catch (err) {
+        throw new PluginInitError(plugin.id, err);
+      }
+    }
+  }
+  return { hookRegistry, endpoints, schema, pluginIds };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HookRegistry,
+  PluginInitError,
+  PluginInvokeError,
+  assertDefined,
+  assertOneOf,
+  mergeSchemas,
+  resolvePlugins
+});
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type {\n  HookContract,\n  HookHandlers,\n  PluginContext,\n  FieldType,\n  PluginFieldDefinition,\n  PluginTableDefinition,\n  PluginSchema,\n  HttpMethod,\n  PluginRequestContext,\n  PluginResponse,\n  PluginEndpointHandler,\n  PluginEndpoint,\n  PluginDefinition,\n} from \"./types.js\";\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/hook-registry.ts","../src/validation.ts","../src/schema.ts","../src/resolve-plugins.ts"],"sourcesContent":["export type {\n  HookContract,\n  HookHandlers,\n  PluginContext,\n  FieldType,\n  PluginFieldDefinition,\n  PluginTableDefinition,\n  PluginSchema,\n  HttpMethod,\n  PluginRequestContext,\n  PluginResponse,\n  PluginEndpointHandler,\n  PluginEndpoint,\n  PluginDefinition,\n} from \"./types.js\";\n\nexport { HookRegistry, PluginInvokeError } from \"./hook-registry.js\";\nexport type { PluginError } from \"./hook-registry.js\";\n\nexport { assertDefined, assertOneOf } from \"./validation.js\";\n\nexport { mergeSchemas } from \"./schema.js\";\nexport type { MergedPluginSchema } from \"./schema.js\";\n\nexport { resolvePlugins, PluginInitError } from \"./resolve-plugins.js\";\nexport type { ResolvedPlugins, ResolvedEndpoint } from \"./resolve-plugins.js\";\n","import type { HookContract, HookHandlers } from \"./types.js\";\n\n/**\n * Error captured when a plugin hook handler fails during `invokeAfter`.\n */\nexport interface PluginError {\n  pluginId: string;\n  hook: string;\n  error: unknown;\n}\n\n/**\n * Error thrown by `invokeBefore` when a plugin hook handler fails.\n * Wraps the original error with plugin and hook context so callers\n * can identify which plugin caused the failure.\n */\nexport class PluginInvokeError extends Error {\n  override readonly name = \"PluginInvokeError\";\n  readonly pluginId: string;\n  readonly hook: string;\n\n  constructor(pluginId: string, hook: string, cause: unknown) {\n    const detail = cause instanceof Error ? cause.message : String(cause);\n    super(`Plugin \"${pluginId}\" failed on hook \"${hook}\": ${detail}`, {\n      cause,\n    });\n    this.pluginId = pluginId;\n    this.hook = hook;\n  }\n}\n\n/**\n * Internal handler entry. The handler is typed as `(payload: never) => …`\n * because any function `(payload: T) => R` is assignable to it (contravariance\n * on `never`). This avoids a type assertion at registration time.\n */\ninterface RegisteredHook {\n  pluginId: string;\n  handler: (payload: never) => void | Promise<void>;\n}\n\n/**\n * Runtime registry that products use to register plugin hooks and invoke them\n * at lifecycle points.\n *\n * Generic over THooks so products get type-safe hook names and payloads.\n */\nexport class HookRegistry<THooks extends HookContract> {\n  private hooks = new Map<string, RegisteredHook[]>();\n  private registeredPlugins = new Set<string>();\n\n  /**\n   * Register all hooks declared by a plugin. Skips entries whose value is not\n   * a function (defensive against partial/optional declarations).\n   *\n   * Throws if a plugin with the same ID has already been registered.\n   */\n  register(pluginId: string, hooks: Partial<HookHandlers<THooks>>): void {\n    if (this.registeredPlugins.has(pluginId)) {\n      throw new Error(`Plugin \"${pluginId}\" is already registered`);\n    }\n    this.registeredPlugins.add(pluginId);\n\n    for (const [key, handler] of Object.entries(hooks)) {\n      if (typeof handler !== \"function\") {\n        continue;\n      }\n\n      let list = this.hooks.get(key);\n      if (list === undefined) {\n        list = [];\n        this.hooks.set(key, list);\n      }\n      list.push({ pluginId, handler });\n    }\n  }\n\n  /**\n   * Sequential, fail-fast invocation — for \"before\" hooks.\n   * Runs handlers in registration order. Aborts on first throw and wraps\n   * the error in a {@link PluginInvokeError} so the caller knows which\n   * plugin failed. Later handlers are **not** called.\n   *\n   * Uses a snapshot of the handler list so that registrations during\n   * async execution do not affect the current invocation.\n   */\n  async invokeBefore<K extends keyof THooks & string>(\n    hook: K,\n    payload: THooks[K],\n  ): Promise<void> {\n    const list = this.hooks.get(hook);\n    if (list === undefined) {\n      return;\n    }\n    const snapshot = [...list];\n    for (const entry of snapshot) {\n      try {\n        await this.callHandler(entry.handler, payload);\n      } catch (error: unknown) {\n        throw new PluginInvokeError(entry.pluginId, hook, error);\n      }\n    }\n  }\n\n  /**\n   * Sequential, collect-errors invocation — for \"after\" hooks.\n   * Runs **all** handlers even when some fail. Failures are wrapped in\n   * {@link PluginError} and returned as an array. Returns an empty array\n   * when all handlers succeed or when no handlers are registered.\n   *\n   * Uses a snapshot of the handler list so that registrations during\n   * async execution do not affect the current invocation.\n   */\n  async invokeAfter<K extends keyof THooks & string>(\n    hook: K,\n    payload: THooks[K],\n  ): Promise<PluginError[]> {\n    const list = this.hooks.get(hook);\n    if (list === undefined) {\n      return [];\n    }\n\n    const errors: PluginError[] = [];\n    const snapshot = [...list];\n    for (const entry of snapshot) {\n      try {\n        await this.callHandler(entry.handler, payload);\n      } catch (error: unknown) {\n        errors.push({\n          pluginId: entry.pluginId,\n          hook,\n          error,\n        });\n      }\n    }\n    return errors;\n  }\n\n  /**\n   * Calls a stored handler with the given payload.\n   *\n   * Handlers are stored as `(payload: never) => …` for variance compatibility\n   * (see {@link RegisteredHook}). At runtime the payload always matches\n   * `THooks[K]` — guaranteed by the generic constraint on {@link register}.\n   * This single assertion is the only place where TypeScript's type system\n   * cannot statically verify the heterogeneous map access.\n   */\n  private callHandler<K extends keyof THooks>(\n    handler: (payload: never) => void | Promise<void>,\n    payload: THooks[K],\n  ): void | Promise<void> {\n    return (handler as (p: THooks[K]) => void | Promise<void>)(payload);\n  }\n}\n","/**\n * Asserts that a value is not `undefined`.\n * Throws with a descriptive error message following the plugin config error pattern.\n */\nexport function assertDefined<T>(\n  value: T | undefined,\n  name: string,\n): asserts value is T {\n  if (value === undefined) {\n    throw new Error(`Plugin config error: \"${name}\" is required`);\n  }\n}\n\n/**\n * Asserts that a value is one of the allowed values.\n * Throws with a descriptive error message listing the allowed options.\n */\nexport function assertOneOf<T extends string | number | boolean>(value: T, allowed: T[], name: string): void {\n  if (!allowed.includes(value)) {\n    const allowedStr = allowed.join(\", \");\n    throw new Error(\n      `Plugin config error: \"${name}\" must be one of: ${allowedStr} (got: ${String(value)})`,\n    );\n  }\n}\n","import type {\n  HookContract,\n  PluginDefinition,\n  PluginFieldDefinition,\n  PluginTableDefinition,\n} from \"./types.js\";\n\n/**\n * Merged schema produced by combining all plugin schema declarations.\n * Unlike per-plugin `PluginSchema` (where fields are optional),\n * the merged result always contains both maps.\n */\nexport interface MergedPluginSchema {\n  tables: Record<string, PluginTableDefinition>;\n  extend: Record<string, Record<string, PluginFieldDefinition>>;\n}\n\n/**\n * Merges schema declarations from all plugins into a single result.\n *\n * Returns empty maps. Full merge logic (conflict detection, ordering)\n * will be added when schema merging is needed.\n */\nexport function mergeSchemas<THooks extends HookContract>(\n  _plugins: PluginDefinition<THooks>[],\n): MergedPluginSchema {\n  return { tables: {}, extend: {} };\n}\n","import { HookRegistry } from \"./hook-registry.js\";\nimport type { MergedPluginSchema } from \"./schema.js\";\nimport { mergeSchemas } from \"./schema.js\";\nimport type {\n  HookContract,\n  PluginContext,\n  PluginDefinition,\n  PluginEndpoint,\n} from \"./types.js\";\n\nexport class PluginInitError extends Error {\n  override readonly name = \"PluginInitError\";\n  readonly pluginId: string;\n\n  constructor(pluginId: string, cause: unknown) {\n    const detail = cause instanceof Error ? cause.message : String(cause);\n    super(`Plugin \"${pluginId}\" failed during init: ${detail}`, { cause });\n    this.pluginId = pluginId;\n  }\n}\n\n/**\n * A collected endpoint annotated with the plugin that contributed it.\n */\nexport interface ResolvedEndpoint extends PluginEndpoint {\n  pluginId: string;\n}\n\n/**\n * Result of resolving a set of plugins. Contains the fully wired\n * hook registry, collected endpoints, merged schema, and plugin IDs.\n */\nexport interface ResolvedPlugins<THooks extends HookContract> {\n  hookRegistry: HookRegistry<THooks>;\n  endpoints: ResolvedEndpoint[];\n  schema: MergedPluginSchema;\n  pluginIds: string[];\n}\n\n/**\n * Lifecycle orchestrator that products call during construction.\n *\n * Steps:\n * 1. **Validate** — duplicate IDs throw immediately\n * 2. **Register hooks** — into a new HookRegistry\n * 3. **Collect endpoints** — flat array from all plugins\n * 4. **Merge schemas** — calls mergeSchemas\n * 5. **Init** — call plugin.init(ctx) sequentially in declaration order\n */\nexport async function resolvePlugins<THooks extends HookContract>(\n  productId: string,\n  plugins: PluginDefinition<THooks>[],\n  config: Record<string, unknown>,\n): Promise<ResolvedPlugins<THooks>> {\n  // 1. Validate — check for empty/whitespace IDs and duplicates\n  const seen = new Set<string>();\n  for (const plugin of plugins) {\n    if (!plugin.id || !plugin.id.trim()) {\n      throw new Error('Plugin config error: \"id\" is required');\n    }\n    if (plugin.id !== plugin.id.trim()) {\n      throw new Error(\n        `Plugin config error: \"id\" must not have leading or trailing whitespace (got: \"${plugin.id}\")`,\n      );\n    }\n    if (seen.has(plugin.id)) {\n      throw new Error(`Duplicate plugin ID: \"${plugin.id}\"`);\n    }\n    seen.add(plugin.id);\n  }\n\n  // 2. Register hooks\n  const hookRegistry = new HookRegistry<THooks>();\n  for (const plugin of plugins) {\n    if (plugin.hooks) {\n      hookRegistry.register(plugin.id, plugin.hooks);\n    }\n  }\n\n  // 3. Collect endpoints (annotated with pluginId)\n  const endpoints: ResolvedEndpoint[] = [];\n  for (const plugin of plugins) {\n    if (plugin.endpoints) {\n      for (const ep of plugin.endpoints) {\n        if (!ep.path || !ep.path.startsWith(\"/\")) {\n          throw new Error(\n            `Plugin \"${plugin.id}\" endpoint path must start with \"/\" (got: \"${ep.path}\")`,\n          );\n        }\n        endpoints.push({ ...ep, pluginId: plugin.id });\n      }\n    }\n  }\n\n  // 4. Merge schemas\n  const schema = mergeSchemas(plugins);\n\n  // 5. Init — sequential in declaration order\n  const pluginIds = plugins.map((p) => p.id);\n  const frozenConfig = Object.freeze({ ...config });\n  const context: PluginContext = {\n    productId,\n    hasPlugin: (id: string) => seen.has(id),\n    config: frozenConfig,\n  };\n\n  for (const plugin of plugins) {\n    if (plugin.init) {\n      try {\n        await plugin.init(context);\n      } catch (err) {\n        throw new PluginInitError(plugin.id, err);\n      }\n    }\n  }\n\n  return { hookRegistry, endpoints, schema, pluginIds };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,2 +1,9 @@
 export type { HookContract, HookHandlers, PluginContext, FieldType, PluginFieldDefinition, PluginTableDefinition, PluginSchema, HttpMethod, PluginRequestContext, PluginResponse, PluginEndpointHandler, PluginEndpoint, PluginDefinition, } from "./types.js";
+export { HookRegistry, PluginInvokeError } from "./hook-registry.js";
+export type { PluginError } from "./hook-registry.js";
+export { assertDefined, assertOneOf } from "./validation.js";
+export { mergeSchemas } from "./schema.js";
+export type { MergedPluginSchema } from "./schema.js";
+export { resolvePlugins, PluginInitError } from "./resolve-plugins.js";
+export type { ResolvedPlugins, ResolvedEndpoint } from "./resolve-plugins.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1 +1,200 @@
+// src/hook-registry.ts
+var PluginInvokeError = class extends Error {
+  name = "PluginInvokeError";
+  pluginId;
+  hook;
+  constructor(pluginId, hook, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Plugin "${pluginId}" failed on hook "${hook}": ${detail}`, {
+      cause
+    });
+    this.pluginId = pluginId;
+    this.hook = hook;
+  }
+};
+var HookRegistry = class {
+  hooks = /* @__PURE__ */ new Map();
+  registeredPlugins = /* @__PURE__ */ new Set();
+  /**
+   * Register all hooks declared by a plugin. Skips entries whose value is not
+   * a function (defensive against partial/optional declarations).
+   *
+   * Throws if a plugin with the same ID has already been registered.
+   */
+  register(pluginId, hooks) {
+    if (this.registeredPlugins.has(pluginId)) {
+      throw new Error(`Plugin "${pluginId}" is already registered`);
+    }
+    this.registeredPlugins.add(pluginId);
+    for (const [key, handler] of Object.entries(hooks)) {
+      if (typeof handler !== "function") {
+        continue;
+      }
+      let list = this.hooks.get(key);
+      if (list === void 0) {
+        list = [];
+        this.hooks.set(key, list);
+      }
+      list.push({ pluginId, handler });
+    }
+  }
+  /**
+   * Sequential, fail-fast invocation — for "before" hooks.
+   * Runs handlers in registration order. Aborts on first throw and wraps
+   * the error in a {@link PluginInvokeError} so the caller knows which
+   * plugin failed. Later handlers are **not** called.
+   *
+   * Uses a snapshot of the handler list so that registrations during
+   * async execution do not affect the current invocation.
+   */
+  async invokeBefore(hook, payload) {
+    const list = this.hooks.get(hook);
+    if (list === void 0) {
+      return;
+    }
+    const snapshot = [...list];
+    for (const entry of snapshot) {
+      try {
+        await this.callHandler(entry.handler, payload);
+      } catch (error) {
+        throw new PluginInvokeError(entry.pluginId, hook, error);
+      }
+    }
+  }
+  /**
+   * Sequential, collect-errors invocation — for "after" hooks.
+   * Runs **all** handlers even when some fail. Failures are wrapped in
+   * {@link PluginError} and returned as an array. Returns an empty array
+   * when all handlers succeed or when no handlers are registered.
+   *
+   * Uses a snapshot of the handler list so that registrations during
+   * async execution do not affect the current invocation.
+   */
+  async invokeAfter(hook, payload) {
+    const list = this.hooks.get(hook);
+    if (list === void 0) {
+      return [];
+    }
+    const errors = [];
+    const snapshot = [...list];
+    for (const entry of snapshot) {
+      try {
+        await this.callHandler(entry.handler, payload);
+      } catch (error) {
+        errors.push({
+          pluginId: entry.pluginId,
+          hook,
+          error
+        });
+      }
+    }
+    return errors;
+  }
+  /**
+   * Calls a stored handler with the given payload.
+   *
+   * Handlers are stored as `(payload: never) => …` for variance compatibility
+   * (see {@link RegisteredHook}). At runtime the payload always matches
+   * `THooks[K]` — guaranteed by the generic constraint on {@link register}.
+   * This single assertion is the only place where TypeScript's type system
+   * cannot statically verify the heterogeneous map access.
+   */
+  callHandler(handler, payload) {
+    return handler(payload);
+  }
+};
+
+// src/validation.ts
+function assertDefined(value, name) {
+  if (value === void 0) {
+    throw new Error(`Plugin config error: "${name}" is required`);
+  }
+}
+function assertOneOf(value, allowed, name) {
+  if (!allowed.includes(value)) {
+    const allowedStr = allowed.join(", ");
+    throw new Error(
+      `Plugin config error: "${name}" must be one of: ${allowedStr} (got: ${String(value)})`
+    );
+  }
+}
+
+// src/schema.ts
+function mergeSchemas(_plugins) {
+  return { tables: {}, extend: {} };
+}
+
+// src/resolve-plugins.ts
+var PluginInitError = class extends Error {
+  name = "PluginInitError";
+  pluginId;
+  constructor(pluginId, cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Plugin "${pluginId}" failed during init: ${detail}`, { cause });
+    this.pluginId = pluginId;
+  }
+};
+async function resolvePlugins(productId, plugins, config) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const plugin of plugins) {
+    if (!plugin.id || !plugin.id.trim()) {
+      throw new Error('Plugin config error: "id" is required');
+    }
+    if (plugin.id !== plugin.id.trim()) {
+      throw new Error(
+        `Plugin config error: "id" must not have leading or trailing whitespace (got: "${plugin.id}")`
+      );
+    }
+    if (seen.has(plugin.id)) {
+      throw new Error(`Duplicate plugin ID: "${plugin.id}"`);
+    }
+    seen.add(plugin.id);
+  }
+  const hookRegistry = new HookRegistry();
+  for (const plugin of plugins) {
+    if (plugin.hooks) {
+      hookRegistry.register(plugin.id, plugin.hooks);
+    }
+  }
+  const endpoints = [];
+  for (const plugin of plugins) {
+    if (plugin.endpoints) {
+      for (const ep of plugin.endpoints) {
+        if (!ep.path || !ep.path.startsWith("/")) {
+          throw new Error(
+            `Plugin "${plugin.id}" endpoint path must start with "/" (got: "${ep.path}")`
+          );
+        }
+        endpoints.push({ ...ep, pluginId: plugin.id });
+      }
+    }
+  }
+  const schema = mergeSchemas(plugins);
+  const pluginIds = plugins.map((p) => p.id);
+  const frozenConfig = Object.freeze({ ...config });
+  const context = {
+    productId,
+    hasPlugin: (id) => seen.has(id),
+    config: frozenConfig
+  };
+  for (const plugin of plugins) {
+    if (plugin.init) {
+      try {
+        await plugin.init(context);
+      } catch (err) {
+        throw new PluginInitError(plugin.id, err);
+      }
+    }
+  }
+  return { hookRegistry, endpoints, schema, pluginIds };
+}
+export {
+  HookRegistry,
+  PluginInitError,
+  PluginInvokeError,
+  assertDefined,
+  assertOneOf,
+  mergeSchemas,
+  resolvePlugins
+};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/hook-registry.ts","../src/validation.ts","../src/schema.ts","../src/resolve-plugins.ts"],"sourcesContent":["import type { HookContract, HookHandlers } from \"./types.js\";\n\n/**\n * Error captured when a plugin hook handler fails during `invokeAfter`.\n */\nexport interface PluginError {\n  pluginId: string;\n  hook: string;\n  error: unknown;\n}\n\n/**\n * Error thrown by `invokeBefore` when a plugin hook handler fails.\n * Wraps the original error with plugin and hook context so callers\n * can identify which plugin caused the failure.\n */\nexport class PluginInvokeError extends Error {\n  override readonly name = \"PluginInvokeError\";\n  readonly pluginId: string;\n  readonly hook: string;\n\n  constructor(pluginId: string, hook: string, cause: unknown) {\n    const detail = cause instanceof Error ? cause.message : String(cause);\n    super(`Plugin \"${pluginId}\" failed on hook \"${hook}\": ${detail}`, {\n      cause,\n    });\n    this.pluginId = pluginId;\n    this.hook = hook;\n  }\n}\n\n/**\n * Internal handler entry. The handler is typed as `(payload: never) => …`\n * because any function `(payload: T) => R` is assignable to it (contravariance\n * on `never`). This avoids a type assertion at registration time.\n */\ninterface RegisteredHook {\n  pluginId: string;\n  handler: (payload: never) => void | Promise<void>;\n}\n\n/**\n * Runtime registry that products use to register plugin hooks and invoke them\n * at lifecycle points.\n *\n * Generic over THooks so products get type-safe hook names and payloads.\n */\nexport class HookRegistry<THooks extends HookContract> {\n  private hooks = new Map<string, RegisteredHook[]>();\n  private registeredPlugins = new Set<string>();\n\n  /**\n   * Register all hooks declared by a plugin. Skips entries whose value is not\n   * a function (defensive against partial/optional declarations).\n   *\n   * Throws if a plugin with the same ID has already been registered.\n   */\n  register(pluginId: string, hooks: Partial<HookHandlers<THooks>>): void {\n    if (this.registeredPlugins.has(pluginId)) {\n      throw new Error(`Plugin \"${pluginId}\" is already registered`);\n    }\n    this.registeredPlugins.add(pluginId);\n\n    for (const [key, handler] of Object.entries(hooks)) {\n      if (typeof handler !== \"function\") {\n        continue;\n      }\n\n      let list = this.hooks.get(key);\n      if (list === undefined) {\n        list = [];\n        this.hooks.set(key, list);\n      }\n      list.push({ pluginId, handler });\n    }\n  }\n\n  /**\n   * Sequential, fail-fast invocation — for \"before\" hooks.\n   * Runs handlers in registration order. Aborts on first throw and wraps\n   * the error in a {@link PluginInvokeError} so the caller knows which\n   * plugin failed. Later handlers are **not** called.\n   *\n   * Uses a snapshot of the handler list so that registrations during\n   * async execution do not affect the current invocation.\n   */\n  async invokeBefore<K extends keyof THooks & string>(\n    hook: K,\n    payload: THooks[K],\n  ): Promise<void> {\n    const list = this.hooks.get(hook);\n    if (list === undefined) {\n      return;\n    }\n    const snapshot = [...list];\n    for (const entry of snapshot) {\n      try {\n        await this.callHandler(entry.handler, payload);\n      } catch (error: unknown) {\n        throw new PluginInvokeError(entry.pluginId, hook, error);\n      }\n    }\n  }\n\n  /**\n   * Sequential, collect-errors invocation — for \"after\" hooks.\n   * Runs **all** handlers even when some fail. Failures are wrapped in\n   * {@link PluginError} and returned as an array. Returns an empty array\n   * when all handlers succeed or when no handlers are registered.\n   *\n   * Uses a snapshot of the handler list so that registrations during\n   * async execution do not affect the current invocation.\n   */\n  async invokeAfter<K extends keyof THooks & string>(\n    hook: K,\n    payload: THooks[K],\n  ): Promise<PluginError[]> {\n    const list = this.hooks.get(hook);\n    if (list === undefined) {\n      return [];\n    }\n\n    const errors: PluginError[] = [];\n    const snapshot = [...list];\n    for (const entry of snapshot) {\n      try {\n        await this.callHandler(entry.handler, payload);\n      } catch (error: unknown) {\n        errors.push({\n          pluginId: entry.pluginId,\n          hook,\n          error,\n        });\n      }\n    }\n    return errors;\n  }\n\n  /**\n   * Calls a stored handler with the given payload.\n   *\n   * Handlers are stored as `(payload: never) => …` for variance compatibility\n   * (see {@link RegisteredHook}). At runtime the payload always matches\n   * `THooks[K]` — guaranteed by the generic constraint on {@link register}.\n   * This single assertion is the only place where TypeScript's type system\n   * cannot statically verify the heterogeneous map access.\n   */\n  private callHandler<K extends keyof THooks>(\n    handler: (payload: never) => void | Promise<void>,\n    payload: THooks[K],\n  ): void | Promise<void> {\n    return (handler as (p: THooks[K]) => void | Promise<void>)(payload);\n  }\n}\n","/**\n * Asserts that a value is not `undefined`.\n * Throws with a descriptive error message following the plugin config error pattern.\n */\nexport function assertDefined<T>(\n  value: T | undefined,\n  name: string,\n): asserts value is T {\n  if (value === undefined) {\n    throw new Error(`Plugin config error: \"${name}\" is required`);\n  }\n}\n\n/**\n * Asserts that a value is one of the allowed values.\n * Throws with a descriptive error message listing the allowed options.\n */\nexport function assertOneOf<T extends string | number | boolean>(value: T, allowed: T[], name: string): void {\n  if (!allowed.includes(value)) {\n    const allowedStr = allowed.join(\", \");\n    throw new Error(\n      `Plugin config error: \"${name}\" must be one of: ${allowedStr} (got: ${String(value)})`,\n    );\n  }\n}\n","import type {\n  HookContract,\n  PluginDefinition,\n  PluginFieldDefinition,\n  PluginTableDefinition,\n} from \"./types.js\";\n\n/**\n * Merged schema produced by combining all plugin schema declarations.\n * Unlike per-plugin `PluginSchema` (where fields are optional),\n * the merged result always contains both maps.\n */\nexport interface MergedPluginSchema {\n  tables: Record<string, PluginTableDefinition>;\n  extend: Record<string, Record<string, PluginFieldDefinition>>;\n}\n\n/**\n * Merges schema declarations from all plugins into a single result.\n *\n * Returns empty maps. Full merge logic (conflict detection, ordering)\n * will be added when schema merging is needed.\n */\nexport function mergeSchemas<THooks extends HookContract>(\n  _plugins: PluginDefinition<THooks>[],\n): MergedPluginSchema {\n  return { tables: {}, extend: {} };\n}\n","import { HookRegistry } from \"./hook-registry.js\";\nimport type { MergedPluginSchema } from \"./schema.js\";\nimport { mergeSchemas } from \"./schema.js\";\nimport type {\n  HookContract,\n  PluginContext,\n  PluginDefinition,\n  PluginEndpoint,\n} from \"./types.js\";\n\nexport class PluginInitError extends Error {\n  override readonly name = \"PluginInitError\";\n  readonly pluginId: string;\n\n  constructor(pluginId: string, cause: unknown) {\n    const detail = cause instanceof Error ? cause.message : String(cause);\n    super(`Plugin \"${pluginId}\" failed during init: ${detail}`, { cause });\n    this.pluginId = pluginId;\n  }\n}\n\n/**\n * A collected endpoint annotated with the plugin that contributed it.\n */\nexport interface ResolvedEndpoint extends PluginEndpoint {\n  pluginId: string;\n}\n\n/**\n * Result of resolving a set of plugins. Contains the fully wired\n * hook registry, collected endpoints, merged schema, and plugin IDs.\n */\nexport interface ResolvedPlugins<THooks extends HookContract> {\n  hookRegistry: HookRegistry<THooks>;\n  endpoints: ResolvedEndpoint[];\n  schema: MergedPluginSchema;\n  pluginIds: string[];\n}\n\n/**\n * Lifecycle orchestrator that products call during construction.\n *\n * Steps:\n * 1. **Validate** — duplicate IDs throw immediately\n * 2. **Register hooks** — into a new HookRegistry\n * 3. **Collect endpoints** — flat array from all plugins\n * 4. **Merge schemas** — calls mergeSchemas\n * 5. **Init** — call plugin.init(ctx) sequentially in declaration order\n */\nexport async function resolvePlugins<THooks extends HookContract>(\n  productId: string,\n  plugins: PluginDefinition<THooks>[],\n  config: Record<string, unknown>,\n): Promise<ResolvedPlugins<THooks>> {\n  // 1. Validate — check for empty/whitespace IDs and duplicates\n  const seen = new Set<string>();\n  for (const plugin of plugins) {\n    if (!plugin.id || !plugin.id.trim()) {\n      throw new Error('Plugin config error: \"id\" is required');\n    }\n    if (plugin.id !== plugin.id.trim()) {\n      throw new Error(\n        `Plugin config error: \"id\" must not have leading or trailing whitespace (got: \"${plugin.id}\")`,\n      );\n    }\n    if (seen.has(plugin.id)) {\n      throw new Error(`Duplicate plugin ID: \"${plugin.id}\"`);\n    }\n    seen.add(plugin.id);\n  }\n\n  // 2. Register hooks\n  const hookRegistry = new HookRegistry<THooks>();\n  for (const plugin of plugins) {\n    if (plugin.hooks) {\n      hookRegistry.register(plugin.id, plugin.hooks);\n    }\n  }\n\n  // 3. Collect endpoints (annotated with pluginId)\n  const endpoints: ResolvedEndpoint[] = [];\n  for (const plugin of plugins) {\n    if (plugin.endpoints) {\n      for (const ep of plugin.endpoints) {\n        if (!ep.path || !ep.path.startsWith(\"/\")) {\n          throw new Error(\n            `Plugin \"${plugin.id}\" endpoint path must start with \"/\" (got: \"${ep.path}\")`,\n          );\n        }\n        endpoints.push({ ...ep, pluginId: plugin.id });\n      }\n    }\n  }\n\n  // 4. Merge schemas\n  const schema = mergeSchemas(plugins);\n\n  // 5. Init — sequential in declaration order\n  const pluginIds = plugins.map((p) => p.id);\n  const frozenConfig = Object.freeze({ ...config });\n  const context: PluginContext = {\n    productId,\n    hasPlugin: (id: string) => seen.has(id),\n    config: frozenConfig,\n  };\n\n  for (const plugin of plugins) {\n    if (plugin.init) {\n      try {\n        await plugin.init(context);\n      } catch (err) {\n        throw new PluginInitError(plugin.id, err);\n      }\n    }\n  }\n\n  return { hookRegistry, endpoints, schema, pluginIds };\n}\n"],"mappings":"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","names":[]}

package/dist/resolve-plugins.d.ts

@@ -0,0 +1,36 @@
+import { HookRegistry } from "./hook-registry.js";
+import type { MergedPluginSchema } from "./schema.js";
+import type { HookContract, PluginDefinition, PluginEndpoint } from "./types.js";
+export declare class PluginInitError extends Error {
+    readonly name = "PluginInitError";
+    readonly pluginId: string;
+    constructor(pluginId: string, cause: unknown);
+}
+/**
+ * A collected endpoint annotated with the plugin that contributed it.
+ */
+export interface ResolvedEndpoint extends PluginEndpoint {
+    pluginId: string;
+}
+/**
+ * Result of resolving a set of plugins. Contains the fully wired
+ * hook registry, collected endpoints, merged schema, and plugin IDs.
+ */
+export interface ResolvedPlugins<THooks extends HookContract> {
+    hookRegistry: HookRegistry<THooks>;
+    endpoints: ResolvedEndpoint[];
+    schema: MergedPluginSchema;
+    pluginIds: string[];
+}
+/**
+ * Lifecycle orchestrator that products call during construction.
+ *
+ * Steps:
+ * 1. **Validate** — duplicate IDs throw immediately
+ * 2. **Register hooks** — into a new HookRegistry
+ * 3. **Collect endpoints** — flat array from all plugins
+ * 4. **Merge schemas** — calls mergeSchemas
+ * 5. **Init** — call plugin.init(ctx) sequentially in declaration order
+ */
+export declare function resolvePlugins<THooks extends HookContract>(productId: string, plugins: PluginDefinition<THooks>[], config: Record<string, unknown>): Promise<ResolvedPlugins<THooks>>;
+//# sourceMappingURL=resolve-plugins.d.ts.map

package/dist/resolve-plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-plugins.d.ts","sourceRoot":"","sources":["../src/resolve-plugins.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,KAAK,EACV,YAAY,EAEZ,gBAAgB,EAChB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAgB,SAAQ,KAAK;IACxC,SAAkB,IAAI,qBAAqB;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAK7C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,MAAM,SAAS,YAAY;IAC1D,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IACnC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,MAAM,SAAS,YAAY,EAC9D,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,EACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAgElC"}

package/dist/schema.d.ts

@@ -0,0 +1,18 @@
+import type { HookContract, PluginDefinition, PluginFieldDefinition, PluginTableDefinition } from "./types.js";
+/**
+ * Merged schema produced by combining all plugin schema declarations.
+ * Unlike per-plugin `PluginSchema` (where fields are optional),
+ * the merged result always contains both maps.
+ */
+export interface MergedPluginSchema {
+    tables: Record<string, PluginTableDefinition>;
+    extend: Record<string, Record<string, PluginFieldDefinition>>;
+}
+/**
+ * Merges schema declarations from all plugins into a single result.
+ *
+ * Returns empty maps. Full merge logic (conflict detection, ordering)
+ * will be added when schema merging is needed.
+ */
+export declare function mergeSchemas<THooks extends HookContract>(_plugins: PluginDefinition<THooks>[]): MergedPluginSchema;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC;CAC/D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,YAAY,EACtD,QAAQ,EAAE,gBAAgB,CAAC,MAAM,CAAC,EAAE,GACnC,kBAAkB,CAEpB"}

package/dist/validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Asserts that a value is not `undefined`.
+ * Throws with a descriptive error message following the plugin config error pattern.
+ */
+export declare function assertDefined<T>(value: T | undefined, name: string): asserts value is T;
+/**
+ * Asserts that a value is one of the allowed values.
+ * Throws with a descriptive error message listing the allowed options.
+ */
+export declare function assertOneOf<T extends string | number | boolean>(value: T, allowed: T[], name: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,GAAG,SAAS,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,IAAI,CAAC,CAIpB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO3G"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usebetterdev/plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "repository": "github:usebetter-dev/usebetter",
   "bugs": "https://github.com/usebetter-dev/usebetter/issues",
   "homepage": "https://github.com/usebetter-dev/usebetter#readme",
@@ -33,7 +33,8 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
+    "build": "tsup && tsc --build tsconfig.build.json --force",
+    "build:types": "tsc --build tsconfig.build.json",
     "lint": "oxlint",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"