@wpkernel/pipeline 0.12.1-beta.0

package/dist/dependency-graph.d.ts

@@ -0,0 +1,80 @@
+import { HelperDescriptor, HelperKind } from './types';
+/**
+ * A registered helper with its unique identifier and registration index.
+ *
+ * @internal
+ */
+export interface RegisteredHelper<THelper> {
+    readonly helper: THelper;
+    readonly id: string;
+    readonly index: number;
+}
+/**
+ * Describes a helper that depends on a missing helper key.
+ *
+ * @internal
+ */
+export interface MissingDependencyIssue<THelper> {
+    readonly dependant: RegisteredHelper<THelper>;
+    readonly dependencyKey: string;
+}
+/**
+ * Options for dependency graph creation.
+ *
+ * @internal
+ */
+export interface CreateDependencyGraphOptions<THelper> {
+    readonly onMissingDependency?: (issue: MissingDependencyIssue<THelper>) => void;
+    readonly onUnresolvedHelpers?: (options: {
+        readonly unresolved: RegisteredHelper<THelper>[];
+    }) => void;
+}
+/**
+ * Creates a unique identifier for a registered helper.
+ *
+ * Format: `{kind}:{key}#{index}`
+ *
+ * @param helper      - The helper descriptor
+ * @param helper.kind
+ * @param index       - The registration index
+ * @param helper.key
+ * @returns A unique string identifier
+ *
+ * @internal
+ */
+export declare function createHelperId(helper: {
+    kind: HelperKind;
+    key: string;
+}, index: number): string;
+/**
+ * Comparator for sorting helpers by priority, key, then registration index.
+ *
+ * Higher priority comes first. If equal, sorts by key alphabetically.
+ * If still equal, sorts by registration index.
+ *
+ * @param a  - First helper entry
+ * @param b  - Second helper entry
+ * @returns Negative if a < b, positive if a > b, zero if equal
+ *
+ * @internal
+ */
+export declare function compareHelpers<THelper extends HelperDescriptor>(a: RegisteredHelper<THelper>, b: RegisteredHelper<THelper>): number;
+/**
+ * Creates a dependency graph and returns the topological order.
+ *
+ * Validates that all dependencies exist and that there are no circular dependencies.
+ * Throws `WPKernelError` if validation fails.
+ *
+ * @param  entries     - All registered helpers with their IDs
+ * @param  options     - Optional callbacks for diagnostic reporting
+ * @param  createError - Error factory function
+ * @returns Ordered helpers and the adjacency list
+ * @throws {Error} If dependencies are missing or unresolved
+ *
+ * @internal
+ */
+export declare function createDependencyGraph<THelper extends HelperDescriptor>(entries: RegisteredHelper<THelper>[], options: CreateDependencyGraphOptions<THelper> | undefined, createError: (code: string, message: string) => Error): {
+    order: RegisteredHelper<THelper>[];
+    adjacency: Map<string, Set<string>>;
+};
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAaD;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC9C,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B,CAAC,OAAO;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAC9B,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,KAClC,IAAI,CAAC;IACV,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QACxC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;KACjD,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EACzC,KAAK,EAAE,MAAM,GACX,MAAM,CAER;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,SAAS,gBAAgB,EAC9D,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAC5B,CAAC,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAC1B,MAAM,CAUR;AA2KD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,gBAAgB,EACrE,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,OAAO,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAAG,SAAS,EAC1D,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,GACnD;IACF,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;CACpC,CA4CA"}

package/dist/dependency-graph.js

@@ -0,0 +1,105 @@
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function k(n, e) {
+  return `${n.kind}:${n.key}#${e}`;
+}
+function f(n, e) {
+  return n.helper.priority !== e.helper.priority ? e.helper.priority - n.helper.priority : n.helper.key !== e.helper.key ? n.helper.key.localeCompare(e.helper.key) : n.index - e.index;
+}
+function y(n) {
+  const e = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+  for (const t of n)
+    e.set(t.id, /* @__PURE__ */ new Set()), o.set(t.id, 0), r.set(t.id, t);
+  return { adjacency: e, indegree: o, entryById: r };
+}
+function a(n, e) {
+  const o = [];
+  for (const r of n)
+    for (const t of r.helper.dependsOn)
+      h(
+        n,
+        e,
+        t,
+        r.id
+      ) || o.push({
+        dependant: r,
+        dependencyKey: t
+      });
+  return o;
+}
+function h(n, e, o, r) {
+  const t = n.filter(
+    ({ helper: c }) => c.key === o
+  );
+  if (t.length === 0)
+    return !1;
+  for (const c of t) {
+    const d = e.adjacency.get(c.id);
+    if (!d)
+      continue;
+    d.add(r);
+    const i = e.indegree.get(r) ?? 0;
+    e.indegree.set(r, i + 1);
+  }
+  return !0;
+}
+function g(n, e) {
+  const o = n.filter(
+    (i) => (e.indegree.get(i.id) ?? 0) === 0
+  );
+  o.sort(f);
+  const r = [], t = new Map(e.indegree), c = /* @__PURE__ */ new Set();
+  for (; o.length > 0; ) {
+    const i = o.shift();
+    if (!i)
+      break;
+    r.push(i), c.add(i.id);
+    const u = e.adjacency.get(i.id);
+    if (u)
+      for (const s of u) {
+        const p = (t.get(s) ?? 0) - 1;
+        if (t.set(s, p), p !== 0)
+          continue;
+        const l = e.entryById.get(s);
+        l && (o.push(l), o.sort(f));
+      }
+  }
+  const d = n.filter((i) => !c.has(i.id));
+  return { ordered: r, unresolved: d };
+}
+function w(n, e, o) {
+  const r = y(n), t = a(n, r);
+  if (t.length > 0) {
+    for (const s of t)
+      e?.onMissingDependency?.(s);
+    const i = /* @__PURE__ */ new Map();
+    for (const s of t) {
+      const p = s.dependant.helper.key, l = i.get(p) ?? [];
+      l.push(s.dependencyKey), i.set(p, l);
+    }
+    const u = Array.from(i.entries()).map(
+      ([s, p]) => `"${s}" → [${p.map((l) => `"${l}"`).join(", ")}]`
+    ).join(", ");
+    throw o(
+      "ValidationError",
+      `Helpers depend on unknown helpers: ${u}.`
+    );
+  }
+  const { ordered: c, unresolved: d } = g(n, r);
+  if (d.length > 0) {
+    e?.onUnresolvedHelpers?.({ unresolved: d });
+    const i = d.map((u) => u.helper.key);
+    throw o(
+      "ValidationError",
+      `Detected unresolved pipeline helpers: ${i.join(", ")}.`
+    );
+  }
+  return { order: c, adjacency: r.adjacency };
+}
+export {
+  f as compareHelpers,
+  w as createDependencyGraph,
+  k as createHelperId
+};

package/dist/error-factory.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Factory function for creating errors.
+ * Allows the pipeline to be framework-agnostic.
+ *
+ * @param code    - Error code (e.g., 'ValidationError', 'RuntimeError')
+ * @param message - Error message
+ * @returns An Error instance
+ *
+ * @example
+ * ```typescript
+ * const createError = (code: string, message: string) =>
+ *   new MyCustomError(code, { message });
+ * ```
+ */
+export type ErrorFactory = (code: string, message: string) => Error;
+/**
+ * Default error factory that creates standard Error instances with code property.
+ *
+ * @param code    - Error code
+ * @param message - Error message
+ * @returns A standard Error with code property and prefixed message
+ */
+export declare function createDefaultError(code: string, message: string): Error;
+/**
+ * Creates an error factory that wraps a custom error class.
+ *
+ * @param ErrorClass - Custom error class constructor
+ * @param create
+ * @returns An error factory function
+ *
+ * @example
+ * ```typescript
+ * class WPKernelError extends Error {
+ *   constructor(code: string, options: { message: string }) {
+ *     super(options.message);
+ *     this.name = code;
+ *   }
+ * }
+ *
+ * const createError = createErrorFactory(
+ *   (code, message) => new WPKernelError(code, { message })
+ * );
+ * ```
+ */
+export declare function createErrorFactory(create: (code: string, message: string) => Error): ErrorFactory;
+//# sourceMappingURL=error-factory.d.ts.map

package/dist/error-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-factory.d.ts","sourceRoot":"","sources":["../src/error-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC;AAEpE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAIvE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,GAC9C,YAAY,CAEd"}

package/dist/error-factory.js

@@ -0,0 +1,15 @@
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function o(r, t) {
+  const e = new Error(`[${r}] ${t}`);
+  return e.code = r, e;
+}
+function n(r) {
+  return r;
+}
+export {
+  o as createDefaultError,
+  n as createErrorFactory
+};

package/dist/executor.d.ts

@@ -0,0 +1,24 @@
+import { Helper, HelperApplyOptions, HelperKind, MaybePromise, PipelineReporter } from './types';
+import { RegisteredHelper } from './dependency-graph';
+/**
+ * Executes an ordered list of helpers sequentially with middleware-style `next()` support.
+ *
+ * Each helper can optionally call `next()` to explicitly control when the next helper runs.
+ * If a helper doesn't call `next()`, execution continues automatically after the helper completes
+ * (for async helpers, after the promise resolves).
+ *
+ * This enables middleware patterns where helpers can:
+ * - Pre-process before calling next()
+ * - Post-process after next() returns
+ * - Control timing of downstream execution via explicit next() calls
+ *
+ * @param ordered    - Topologically sorted helpers to execute
+ * @param makeArgs   - Factory function to create arguments for each helper
+ * @param invoke     - Function that invokes a helper with its arguments and next callback
+ * @param recordStep - Callback invoked when a helper starts executing (for diagnostics)
+ * @returns Set of visited helper IDs
+ *
+ * @internal
+ */
+export declare function executeHelpers<TContext, TInput, TOutput, TReporter extends PipelineReporter, TKind extends HelperKind, THelper extends Helper<TContext, TInput, TOutput, TReporter, TKind>, TArgs extends HelperApplyOptions<TContext, TInput, TOutput, TReporter>>(ordered: RegisteredHelper<THelper>[], makeArgs: (entry: RegisteredHelper<THelper>) => TArgs, invoke: (helper: THelper, args: TArgs, next: () => MaybePromise<void>) => MaybePromise<void>, recordStep: (entry: RegisteredHelper<THelper>) => void): MaybePromise<Set<string>>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,MAAM,EACN,kBAAkB,EAClB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,SAAS,gBAAgB,EAClC,KAAK,SAAS,UAAU,EACxB,OAAO,SAAS,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,EACnE,KAAK,SAAS,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAEtE,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,KAAK,EACrD,MAAM,EAAE,CACP,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,KAAK,EACX,IAAI,EAAE,MAAM,YAAY,CAAC,IAAI,CAAC,KAC1B,YAAY,CAAC,IAAI,CAAC,EACvB,UAAU,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,CAAC,KAAK,IAAI,GACpD,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CA0E3B"}

package/dist/executor.js

@@ -0,0 +1,40 @@
+import { isPromiseLike as u } from "./async-utils.js";
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function g(s, a, v, h) {
+  const o = /* @__PURE__ */ new Set();
+  function m(t) {
+    const e = r(t);
+    return u(e) ? Promise.resolve(e).then(() => {
+    }) : Promise.resolve();
+  }
+  function r(t) {
+    if (t >= s.length)
+      return;
+    const e = s[t];
+    if (!e || o.has(e.id))
+      return r(t + 1);
+    o.add(e.id), h(e);
+    let i = !1, n;
+    const p = a(e), P = () => {
+      if (i)
+        return n;
+      i = !0;
+      const l = r(t + 1);
+      return n = l, l;
+    }, f = v(e.helper, p, P);
+    return u(f) ? Promise.resolve(f).then(() => {
+      if (!i)
+        return m(t + 1);
+      if (u(n))
+        return n;
+    }) : i ? n : r(t + 1);
+  }
+  const c = r(0);
+  return u(c) ? c.then(() => o) : o;
+}
+export {
+  g as executeHelpers
+};

package/dist/extensions.d.ts

@@ -0,0 +1,83 @@
+import { MaybePromise, PipelineExtensionHook, PipelineExtensionHookOptions, PipelineExtensionHookResult, PipelineExtensionRollbackErrorMetadata } from './types';
+/**
+ * An extension hook entry with its unique key.
+ *
+ * @internal
+ */
+export interface ExtensionHookEntry<TContext, TOptions, TArtifact> {
+    readonly key: string;
+    readonly hook: PipelineExtensionHook<TContext, TOptions, TArtifact>;
+}
+/**
+ * The result of executing an extension hook.
+ *
+ * @internal
+ */
+export interface ExtensionHookExecution<TContext, TOptions, TArtifact> {
+    readonly hook: ExtensionHookEntry<TContext, TOptions, TArtifact>;
+    readonly result: PipelineExtensionHookResult<TArtifact>;
+}
+/**
+ * Arguments passed to the rollback error handler.
+ *
+ * @internal
+ */
+export interface RollbackErrorArgs {
+    readonly error: unknown;
+    readonly extensionKeys: readonly string[];
+    readonly hookSequence: readonly string[];
+}
+/**
+ * Converts an error into a serializable metadata object.
+ *
+ * Extracts `name`, `message`, `stack`, and `cause` from Error instances.
+ * Falls back to a plain message string for non-Error values.
+ *
+ * @param error - The error to convert
+ * @returns Serializable error metadata
+ *
+ * @internal
+ */
+export declare function createRollbackErrorMetadata(error: unknown): PipelineExtensionRollbackErrorMetadata;
+/**
+ * Runs extension hooks sequentially and accumulates their results.
+ *
+ * Each hook can optionally transform the artifact and return commit/rollback functions.
+ * If any hook throws, automatically rolls back all previously executed hooks in reverse order.
+ *
+ * @param hooks           - The extension hooks to run
+ * @param options         - Context, options, and initial artifact
+ * @param onRollbackError - Callback invoked if a rollback itself fails
+ * @returns The final artifact and all hook execution results
+ *
+ * @internal
+ */
+export declare function runExtensionHooks<TContext, TOptions, TArtifact>(hooks: readonly ExtensionHookEntry<TContext, TOptions, TArtifact>[], options: PipelineExtensionHookOptions<TContext, TOptions, TArtifact>, onRollbackError: (args: RollbackErrorArgs) => void): MaybePromise<{
+    artifact: TArtifact;
+    results: ExtensionHookExecution<TContext, TOptions, TArtifact>[];
+}>;
+/**
+ * Commits all extension hook results by invoking their commit functions.
+ *
+ * Processes commits sequentially in the order hooks were executed.
+ *
+ * @param results - The hook execution results
+ * @returns A promise if any commit is async, otherwise `void`
+ *
+ * @internal
+ */
+export declare function commitExtensionResults<TContext, TOptions, TArtifact>(results: readonly ExtensionHookExecution<TContext, TOptions, TArtifact>[]): MaybePromise<void>;
+/**
+ * Rolls back extension hook results by invoking their rollback functions in reverse order.
+ *
+ * If a rollback itself fails, calls `onRollbackError` but continues rolling back remaining hooks.
+ *
+ * @param results         - The hook execution results to roll back
+ * @param hooks           - The original hook entries (for error context)
+ * @param onRollbackError - Callback invoked if a rollback fails
+ * @returns A promise if any rollback is async, otherwise `void`
+ *
+ * @internal
+ */
+export declare function rollbackExtensionResults<TContext, TOptions, TArtifact>(results: readonly ExtensionHookExecution<TContext, TOptions, TArtifact>[], hooks: readonly ExtensionHookEntry<TContext, TOptions, TArtifact>[], onRollbackError: (args: RollbackErrorArgs) => void): MaybePromise<void>;
+//# sourceMappingURL=extensions.d.ts.map

package/dist/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../src/extensions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,YAAY,EACZ,qBAAqB,EACrB,4BAA4B,EAC5B,2BAA2B,EAC3B,sCAAsC,EACtC,MAAM,SAAS,CAAC;AAQjB;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS;IACpE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAC1C,KAAK,EAAE,OAAO,GACZ,sCAAsC,CAoBxC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAC9D,KAAK,EAAE,SAAS,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACnE,OAAO,EAAE,4BAA4B,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EACpE,eAAe,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAChD,YAAY,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;CACjE,CAAC,CAuDD;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EACnE,OAAO,EAAE,SAAS,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GACvE,YAAY,CAAC,IAAI,CAAC,CAcpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EACrE,OAAO,EAAE,SAAS,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACzE,KAAK,EAAE,SAAS,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACnE,eAAe,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAChD,YAAY,CAAC,IAAI,CAAC,CA2BpB"}

package/dist/extensions.js

@@ -0,0 +1,88 @@
+import { maybeTry as m, maybeThen as l, processSequentially as f, isPromiseLike as k } from "./async-utils.js";
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function p(t) {
+  if (t instanceof Error) {
+    const { name: o, message: r, stack: e } = t, n = t.cause;
+    return {
+      name: o,
+      message: r,
+      stack: e,
+      cause: n
+    };
+  }
+  return typeof t == "string" ? {
+    message: t
+  } : {};
+}
+function v(t, o, r) {
+  let e = o.artifact;
+  const n = [], u = m(
+    () => f(t, (s) => {
+      const i = s.hook({
+        context: o.context,
+        options: o.options,
+        artifact: e
+      });
+      if (k(i))
+        return Promise.resolve(i).then((a) => {
+          a && (a.artifact !== void 0 && (e = a.artifact), n.push({
+            hook: s,
+            result: a
+          }));
+        });
+      if (i)
+        return i.artifact !== void 0 && (e = i.artifact), void n.push({
+          hook: s,
+          result: i
+        });
+    }),
+    (s) => l(
+      h(n, t, r),
+      () => {
+        throw s;
+      }
+    )
+  );
+  return l(u, () => ({ artifact: e, results: n }));
+}
+function x(t) {
+  return f(t, (o) => {
+    const r = o.result.commit;
+    if (!r)
+      return;
+    const e = r();
+    if (k(e))
+      return e.then(() => {
+      });
+  });
+}
+function h(t, o, r) {
+  const e = o.map((c) => c.key), n = e;
+  return f(
+    [...t].reverse(),
+    (c) => {
+      const u = c.result.rollback;
+      if (u)
+        return m(
+          () => u(),
+          (s) => {
+            r({
+              error: s,
+              extensionKeys: e,
+              hookSequence: n
+            });
+          }
+        );
+    },
+    "forward"
+  );
+}
+export {
+  x as commitExtensionResults,
+  p as createRollbackErrorMetadata,
+  h as rollbackExtensionResults,
+  v as runExtensionHooks
+};

package/dist/helper.d.ts

@@ -0,0 +1,134 @@
+import { CreateHelperOptions, Helper, HelperKind, PipelineReporter } from './types';
+/**
+ * Creates a pipeline helper-the fundamental building block of WPKernel's code generation system.
+ *
+ * ## Overview
+ *
+ * Helpers are composable, dependency-aware transformation units that power the entire framework:
+ * - **CLI package**: Generates PHP resources, actions, blocks, and bindings via helper chains
+ * - **PHP Driver**: Transforms PHP AST nodes through fragment helpers
+ * - **Core**: Orchestrates resource definitions and action middleware
+ *
+ * Each helper is a pure, immutable descriptor that declares:
+ * - **What it does**: Fragment transformations or artifact building
+ * - **When it runs**: Priority ordering and dependency relationships
+ * - **How it integrates**: Mode (extend/replace/before/after) and rollback behavior
+ *
+ * ## Key Concepts
+ *
+ * ### Helper Kinds
+ * - `fragment`: Modifies AST nodes in-place (e.g., add PHP opening tag, inject imports)
+ * - `builder`: Produces final artifacts from fragments (e.g., write files, format code)
+ *
+ * ### Execution Modes
+ * - `extend` (default): Add to existing transformations; multiple helpers with same key can coexist
+ * - `override`: Only one override helper per key is allowed; prevents duplicate override registrations
+ *
+ * Note: Mode primarily affects registration validation. For execution ordering, use `priority` and `dependsOn`.
+ *
+ * ### Dependency Resolution
+ * The pipeline automatically:
+ * - Topologically sorts helpers based on `dependsOn` declarations
+ * - Validates dependency chains and reports missing/circular dependencies
+ * - Ensures helpers run in correct order regardless of registration sequence
+ *
+ * ## Architecture
+ *
+ * Helpers form directed acyclic graphs (DAGs) where each node represents a transformation
+ * and edges represent dependencies. The pipeline executes helpers in topological order,
+ * ensuring all dependencies complete before dependent helpers run.
+ *
+ * This design enables:
+ * - **Composability**: Combine helpers from different packages without conflicts
+ * - **Extensibility**: Third-party helpers integrate seamlessly via dependency declarations
+ * - **Reliability**: Rollback support ensures atomic operations across helper chains
+ * - **Observability**: Built-in diagnostics and reporter integration for debugging
+ *
+ * @param    options
+ * @category Pipeline
+ *
+ * @example Basic fragment helper
+ * ```typescript
+ * import { createHelper } from '@wpkernel/pipeline';
+ *
+ * // Add PHP opening tag to generated files
+ * const addPHPTag = createHelper({
+ *   key: 'add-php-opening-tag',
+ *   kind: 'fragment',
+ *   mode: 'extend',
+ *   priority: 100, // Run early in pipeline
+ *   origin: 'wp-kernel-core',
+ *   apply: ({ fragment }) => {
+ *     fragment.children.unshift({
+ *       kind: 'text',
+ *       text: '<?php\n',
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @example Helper with dependencies
+ * ```typescript
+ * // This helper depends on namespace detection running first
+ * const addNamespaceDeclaration = createHelper({
+ *   key: 'add-namespace',
+ *   kind: 'fragment',
+ *   dependsOn: ['detect-namespace'], // Won't run until this completes
+ *   apply: ({ fragment, context }) => {
+ *     const ns = context.detectedNamespace;
+ *     fragment.children.push({
+ *       kind: 'namespace',
+ *       name: ns,
+ *     });
+ *   },
+ * });
+ * ```
+ *
+ * @example Builder helper with rollback
+ * ```typescript
+ * import { createPipelineCommit, createPipelineRollback } from '@wpkernel/pipeline';
+ *
+ * const writeFileHelper = createHelper({
+ *   key: 'write-file',
+ *   kind: 'builder',
+ *   apply: ({ draft, context }) => {
+ *     const path = context.outputPath;
+ *     const backup = readFileSync(path, 'utf-8'); // Capture current state
+ *
+ *     writeFileSync(path, draft);
+ *
+ *     return {
+ *       commit: createPipelineCommit(
+ *         () => context.reporter.info(`Wrote ${path}`)
+ *       ),
+ *       rollback: createPipelineRollback(
+ *         () => writeFileSync(path, backup), // Restore on error
+ *         () => context.reporter.warn(`Rolled back ${path}`)
+ *       ),
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Async helper with error handling
+ * ```typescript
+ * const formatCodeHelper = createHelper({
+ *   key: 'format-code',
+ *   kind: 'builder',
+ *   dependsOn: ['write-file'],
+ *   apply: async ({ artifact, context }) => {
+ *     try {
+ *       const formatted = await prettier.format(artifact, {
+ *         parser: 'php',
+ *       });
+ *       return { artifact: formatted };
+ *     } catch (error) {
+ *       context.reporter.error('Formatting failed', { error });
+ *       throw error;
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export declare function createHelper<TContext, TInput, TOutput, TReporter extends PipelineReporter = PipelineReporter, TKind extends HelperKind = HelperKind>(options: CreateHelperOptions<TContext, TInput, TOutput, TReporter, TKind>): Helper<TContext, TInput, TOutput, TReporter, TKind>;
+//# sourceMappingURL=helper.d.ts.map

package/dist/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,mBAAmB,EACnB,MAAM,EACN,UAAU,EAEV,gBAAgB,EAChB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AACH,wBAAgB,YAAY,CAC3B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,KAAK,SAAS,UAAU,GAAG,UAAU,EAErC,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,GACvE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CA8BrD"}

package/dist/helper.js

@@ -0,0 +1,29 @@
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function a(e) {
+  const {
+    key: r,
+    kind: n,
+    mode: t = "extend",
+    priority: p = 0,
+    dependsOn: o = [],
+    origin: d,
+    apply: i
+  } = e;
+  return Object.freeze({
+    key: r,
+    kind: n,
+    mode: t,
+    priority: p,
+    dependsOn: Array.from(o),
+    origin: d,
+    apply(c, s) {
+      return i(c, s);
+    }
+  });
+}
+export {
+  a as createHelper
+};