@wpkernel/pipeline 0.12.1-beta.0 → 0.12.1-beta.3

package/dist/internal/extension-coordinator.js

@@ -0,0 +1,55 @@
+import { commitExtensionResults as m, rollbackExtensionResults as d, runExtensionHooks as f, createRollbackErrorMetadata as s } from "../extensions.js";
+import { maybeThen as i } from "../async-utils.js";
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function R(n) {
+  return {
+    runLifecycle: (t, { hooks: o, hookOptions: r }) => {
+      const c = o.filter(
+        (e) => e.lifecycle === t
+      ), a = f(
+        o,
+        t,
+        r,
+        ({ error: e, extensionKeys: l, hookSequence: u }) => n({
+          error: e,
+          extensionKeys: l,
+          hookSequence: u,
+          errorMetadata: s(e),
+          hookOptions: r
+        })
+      );
+      return i(
+        a,
+        (e) => ({
+          artifact: e.artifact,
+          results: e.results,
+          hooks: c
+        })
+      );
+    },
+    createRollbackHandler: (t) => (o) => i(
+      d(
+        t.results,
+        t.hooks,
+        ({ error: r, extensionKeys: c, hookSequence: a }) => n({
+          error: r,
+          extensionKeys: c,
+          hookSequence: a,
+          errorMetadata: s(r),
+          hookOptions: void 0
+        })
+      ),
+      () => {
+        throw o;
+      }
+    ),
+    commit: (t) => m(t.results),
+    handleRollbackError: n
+  };
+}
+export {
+  R as initExtensionCoordinator
+};

package/dist/internal/extension-coordinator.types.d.ts

@@ -0,0 +1,42 @@
+import { MaybePromise, PipelineExtensionHookOptions, PipelineExtensionRollbackErrorMetadata } from '../types';
+import { ExtensionHookEntry, ExtensionHookExecution, RollbackErrorArgs } from '../extensions';
+/**
+ * Represents the state returned after executing a specific extension lifecycle.
+ *
+ * @category Pipeline
+ * @internal
+ */
+export interface ExtensionLifecycleState<TContext, TOptions, TArtifact> {
+    readonly artifact: TArtifact;
+    readonly results: ExtensionHookExecution<TContext, TOptions, TArtifact>[];
+    readonly hooks: readonly ExtensionHookEntry<TContext, TOptions, TArtifact>[];
+}
+/**
+ * Handles extension execution, rollback, and commit using the primitives exposed by the
+ * `extensions` module. Delegating this coordination to a dedicated utility keeps the pipeline
+ * runner focused on dependency graph orchestration and helper execution.
+ *
+ * @category Pipeline
+ * @internal
+ */
+/**
+ * Payload supplied to rollback error handlers when an extension lifecycle fails.
+ *
+ * @category Pipeline
+ * @internal
+ */
+export interface ExtensionRollbackEvent<TContext, TOptions, TArtifact> extends RollbackErrorArgs {
+    readonly errorMetadata: PipelineExtensionRollbackErrorMetadata;
+    readonly hookOptions?: PipelineExtensionHookOptions<TContext, TOptions, TArtifact>;
+}
+export interface ExtensionCoordinator<TContext, TOptions, TArtifact> {
+    readonly runLifecycle: (lifecycle: ExtensionHookEntry<TContext, TOptions, TArtifact>['lifecycle'], options: {
+        readonly hooks: readonly ExtensionHookEntry<TContext, TOptions, TArtifact>[];
+        readonly hookOptions: PipelineExtensionHookOptions<TContext, TOptions, TArtifact>;
+    }) => MaybePromise<ExtensionLifecycleState<TContext, TOptions, TArtifact>>;
+    readonly createRollbackHandler: <TResult>(state: ExtensionLifecycleState<TContext, TOptions, TArtifact>) => (error: unknown) => MaybePromise<TResult>;
+    readonly commit: (state: ExtensionLifecycleState<TContext, TOptions, TArtifact>) => MaybePromise<void>;
+    readonly handleRollbackError: (args: ExtensionRollbackEvent<TContext, TOptions, TArtifact>) => void;
+}
+export type { ExtensionHookEntry, ExtensionHookExecution, RollbackErrorArgs };
+//# sourceMappingURL=extension-coordinator.types.d.ts.map

package/dist/internal/extension-coordinator.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-coordinator.types.d.ts","sourceRoot":"","sources":["../../src/internal/extension-coordinator.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,YAAY,EACZ,4BAA4B,EAC5B,sCAAsC,EACtC,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACX,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS;IACrE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,CAC1C,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,EAAE,CAAC;CACJ;AAED;;;;;;;GAOG;AACH;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CACpE,SAAQ,iBAAiB;IACzB,QAAQ,CAAC,aAAa,EAAE,sCAAsC,CAAC;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,4BAA4B,CAClD,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,CAAC;CACF;AAED,MAAM,WAAW,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS;IAClE,QAAQ,CAAC,YAAY,EAAE,CACtB,SAAS,EAAE,kBAAkB,CAC5B,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,CAAC,WAAW,CAAC,EACd,OAAO,EAAE;QACR,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,CAC1C,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,EAAE,CAAC;QACJ,QAAQ,CAAC,WAAW,EAAE,4BAA4B,CACjD,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,CAAC;KACF,KACG,YAAY,CAAC,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,qBAAqB,EAAE,CAAC,OAAO,EACvC,KAAK,EAAE,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KACzD,CAAC,KAAK,EAAE,OAAO,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,CAChB,KAAK,EAAE,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KACzD,YAAY,CAAC,IAAI,CAAC,CAAC;IACxB,QAAQ,CAAC,mBAAmB,EAAE,CAC7B,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KACvD,IAAI,CAAC;CACV;AAED,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/internal/helper-execution.d.ts

@@ -0,0 +1,32 @@
+import { RegisteredHelper } from '../dependency-graph';
+import { ErrorFactory } from '../error-factory';
+import { HelperDescriptor, HelperExecutionSnapshot, HelperKind } from '../types';
+/**
+ * Creates a snapshot summarising helper execution for a specific stage.
+ *
+ * @param    entries
+ * @param    visited
+ * @param    kind
+ * @example
+ * ```ts
+ * const snapshot = buildExecutionSnapshot(fragmentEntries, visited, 'fragment');
+ * console.log(snapshot.executed.length);
+ * ```
+ *
+ * @category Pipeline
+ * @internal
+ */
+export declare function buildExecutionSnapshot<THelper extends HelperDescriptor<TKind>, TKind extends HelperKind>(entries: RegisteredHelper<THelper>[], visited: Set<string>, kind: TKind): HelperExecutionSnapshot<TKind>;
+/**
+ * Throws when required helpers in a stage were never executed.
+ *
+ * @param    entries
+ * @param    snapshot
+ * @param    kind
+ * @param    describeHelper
+ * @param    createError
+ * @category Pipeline
+ * @internal
+ */
+export declare function assertAllHelpersExecuted<THelper extends HelperDescriptor<TKind>, TKind extends HelperKind>(entries: RegisteredHelper<THelper>[], snapshot: HelperExecutionSnapshot<TKind>, kind: TKind, describeHelper: (kind: HelperKind, helper: HelperDescriptor) => string, createError: ErrorFactory): void;
+//# sourceMappingURL=helper-execution.d.ts.map

package/dist/internal/helper-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper-execution.d.ts","sourceRoot":"","sources":["../../src/internal/helper-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EACX,gBAAgB,EAChB,uBAAuB,EACvB,UAAU,EACV,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,SAAS,gBAAgB,CAAC,KAAK,CAAC,EACvC,KAAK,SAAS,UAAU,EAExB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,IAAI,EAAE,KAAK,GACT,uBAAuB,CAAC,KAAK,CAAC,CAsBhC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACvC,OAAO,SAAS,gBAAgB,CAAC,KAAK,CAAC,EACvC,KAAK,SAAS,UAAU,EAExB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,QAAQ,EAAE,uBAAuB,CAAC,KAAK,CAAC,EACxC,IAAI,EAAE,KAAK,EACX,cAAc,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,KAAK,MAAM,EACtE,WAAW,EAAE,YAAY,GACvB,IAAI,CAuBN"}

package/dist/internal/helper-execution.js

@@ -0,0 +1,37 @@
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function c(o, n, l) {
+  const s = [], t = [], i = [];
+  for (const r of o) {
+    const e = r.helper.key;
+    s.push(e), n.has(r.id) ? t.push(e) : i.push(e);
+  }
+  return {
+    kind: l,
+    registered: s,
+    executed: t,
+    missing: i
+  };
+}
+function u(o, n, l, s, t) {
+  if (n.missing.length === 0)
+    return;
+  const i = o.filter(
+    (e) => n.missing.includes(e.helper.key) && !e.helper.optional
+  );
+  if (i.length === 0)
+    return;
+  const r = i.map(
+    (e) => s(l, e.helper)
+  );
+  throw t(
+    "ValidationError",
+    `Pipeline finalisation aborted because ${r.join(", ")} did not execute.`
+  );
+}
+export {
+  u as assertAllHelpersExecuted,
+  c as buildExecutionSnapshot
+};

package/dist/internal/pipeline-runner.d.ts

@@ -0,0 +1,18 @@
+import { Helper, HelperKind, PipelineReporter, PipelineDiagnostic } from '../types';
+import { PipelineRunner, PipelineRunnerDependencies } from './pipeline-runner.types';
+/**
+ * Creates the orchestrator responsible for executing pipeline runs.
+ *
+ * The runner wires together dependency graph resolution, helper execution, and the official
+ * extension framework via the {@link initExtensionCoordinator}. By extracting this logic, the
+ * public {@link createPipeline} entry point remains focused on registration while the runner keeps
+ * lifecycle sequencing isolated and testable.
+ *
+ * @param    dependencies
+ * @category Pipeline
+ * @internal
+ */
+export declare function initPipelineRunner<TRunOptions, TBuildOptions, TContext extends {
+    reporter: TReporter;
+}, TReporter extends PipelineReporter, TDraft, TArtifact, TDiagnostic extends PipelineDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind extends HelperKind, TBuilderKind extends HelperKind, TFragmentHelper extends Helper<TContext, TFragmentInput, TFragmentOutput, TReporter, TFragmentKind>, TBuilderHelper extends Helper<TContext, TBuilderInput, TBuilderOutput, TReporter, TBuilderKind>>(dependencies: PipelineRunnerDependencies<TRunOptions, TBuildOptions, TContext, TReporter, TDraft, TArtifact, TDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>): PipelineRunner<TRunOptions, TBuildOptions, TContext, TReporter, TDraft, TArtifact, TDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>;
+//# sourceMappingURL=pipeline-runner.d.ts.map

package/dist/internal/pipeline-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-runner.d.ts","sourceRoot":"","sources":["../../src/internal/pipeline-runner.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAGX,MAAM,EACN,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAMlB,MAAM,UAAU,CAAC;AAMlB,OAAO,KAAK,EAEX,cAAc,EACd,0BAA0B,EAC1B,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,WAAW,EACX,aAAa,EACb,QAAQ,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACxC,SAAS,SAAS,gBAAgB,EAClC,MAAM,EACN,SAAS,EACT,WAAW,SAAS,kBAAkB,EACtC,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,SAAS,UAAU,EAChC,YAAY,SAAS,UAAU,EAC/B,eAAe,SAAS,MAAM,CAC7B,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,EACD,cAAc,SAAS,MAAM,CAC5B,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,EAED,YAAY,EAAE,0BAA0B,CACvC,WAAW,EACX,aAAa,EACb,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,GACC,cAAc,CAChB,WAAW,EACX,aAAa,EACb,QAAQ,EACR,SAAS,EACT,MAAM,EACN,SAAS,EACT,WAAW,EACX,UAAU,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,CA8ZA"}

package/dist/internal/pipeline-runner.js

@@ -0,0 +1,261 @@
+import { maybeThen as x, maybeTry as F } from "../async-utils.js";
+import { createDependencyGraph as U } from "../dependency-graph.js";
+import { executeHelpers as C } from "../executor.js";
+import { buildExecutionSnapshot as v, assertAllHelpersExecuted as A } from "./helper-execution.js";
+import { initExtensionCoordinator as B } from "./extension-coordinator.js";
+/**
+ * @wpkernel/pipeline
+ * @license EUPL-1.2
+ */
+function j(r) {
+  return {
+    prepareContext: (s) => {
+      const a = r.options.createBuildOptions(s), n = r.options.createContext(s);
+      r.diagnosticManager.setReporter(n.reporter);
+      const l = r.options.createFragmentState({
+        options: s,
+        context: n,
+        buildOptions: a
+      }), m = U(
+        r.fragmentEntries,
+        {
+          onMissingDependency: ({ dependant: t, dependencyKey: e }) => {
+            const o = t.helper;
+            r.diagnosticManager.flagMissingDependency(
+              o,
+              e,
+              r.fragmentKind
+            ), r.diagnosticManager.flagUnusedHelper(
+              o,
+              r.fragmentKind,
+              `could not execute because dependency "${e}" was not found`,
+              o.dependsOn
+            );
+          },
+          onUnresolvedHelpers: ({ unresolved: t }) => {
+            for (const e of t) {
+              const o = e.helper;
+              r.diagnosticManager.flagUnusedHelper(
+                o,
+                r.fragmentKind,
+                "could not execute because its dependencies never resolved",
+                o.dependsOn
+              );
+            }
+          }
+        },
+        r.createError
+      ).order, c = [], b = (t) => {
+        const e = t.helper;
+        c.push({
+          id: t.id,
+          index: c.length,
+          key: e.key,
+          kind: e.kind,
+          mode: e.mode,
+          priority: e.priority,
+          dependsOn: e.dependsOn,
+          origin: e.origin
+        });
+      }, p = {
+        onMissingDependency: ({ dependant: t, dependencyKey: e }) => {
+          const o = t.helper;
+          r.diagnosticManager.flagMissingDependency(
+            o,
+            e,
+            r.builderKind
+          ), r.diagnosticManager.flagUnusedHelper(
+            o,
+            r.builderKind,
+            `could not execute because dependency "${e}" was not found`,
+            o.dependsOn
+          );
+        },
+        onUnresolvedHelpers: ({ unresolved: t }) => {
+          for (const e of t) {
+            const o = e.helper;
+            r.diagnosticManager.flagUnusedHelper(
+              o,
+              r.builderKind,
+              "could not execute because its dependencies never resolved",
+              o.dependsOn
+            );
+          }
+        }
+      }, E = r.options.createExtensionHookOptions ?? ((t) => ({
+        context: t.context,
+        options: t.options,
+        artifact: t.artifact,
+        lifecycle: t.lifecycle
+      })), y = (t, e) => E({
+        context: n,
+        options: s,
+        buildOptions: a,
+        artifact: t,
+        lifecycle: e
+      }), M = r.options.onExtensionRollbackError ?? ((t) => {
+        const { reporter: e } = t.context, o = e.warn;
+        typeof o == "function" && o.call(e, "Pipeline extension rollback failed.", {
+          error: t.error,
+          errorName: t.errorMetadata.name,
+          errorMessage: t.errorMetadata.message,
+          errorStack: t.errorMetadata.stack,
+          errorCause: t.errorMetadata.cause,
+          extensions: t.extensionKeys,
+          hookKeys: t.hookSequence
+        });
+      });
+      return {
+        runOptions: s,
+        buildOptions: a,
+        context: n,
+        draft: l,
+        fragmentOrder: m,
+        steps: c,
+        pushStep: b,
+        builderGraphOptions: p,
+        buildHookOptions: y,
+        handleRollbackError: M
+      };
+    },
+    executeRun: (s) => {
+      const {
+        runOptions: a,
+        buildOptions: n,
+        context: l,
+        draft: m,
+        fragmentOrder: c,
+        steps: b,
+        pushStep: p,
+        builderGraphOptions: E,
+        buildHookOptions: y,
+        handleRollbackError: M
+      } = s;
+      let t = v(
+        r.builderEntries,
+        /* @__PURE__ */ new Set(),
+        r.builderKind
+      );
+      const e = C(
+        c,
+        (o) => r.options.createFragmentArgs({
+          helper: o.helper,
+          options: a,
+          context: l,
+          buildOptions: n,
+          draft: m
+        }),
+        (o, g, u) => o.apply(g, u),
+        (o) => p(o)
+      );
+      return x(e, (o) => {
+        r.diagnosticManager.reviewUnusedHelpers(
+          r.fragmentEntries,
+          o,
+          r.fragmentKind
+        );
+        const g = v(
+          r.fragmentEntries,
+          o,
+          r.fragmentKind
+        );
+        A(
+          r.fragmentEntries,
+          g,
+          r.fragmentKind,
+          r.diagnosticManager.describeHelper,
+          r.createError
+        );
+        let u = r.options.finalizeFragmentState({
+          draft: m,
+          options: a,
+          context: l,
+          buildOptions: n,
+          helpers: { fragments: g }
+        });
+        const D = U(
+          r.builderEntries,
+          E,
+          r.createError
+        ).order, H = B(
+          ({ error: f, extensionKeys: h, hookSequence: R, errorMetadata: K }) => M({
+            error: f,
+            extensionKeys: h,
+            hookSequence: R,
+            errorMetadata: K,
+            context: l
+          })
+        ), w = "after-fragments", O = H.runLifecycle(
+          w,
+          {
+            hooks: r.extensionHooks,
+            hookOptions: y(u, w)
+          }
+        );
+        return x(O, (f) => {
+          u = f.artifact;
+          const h = () => H.createRollbackHandler(
+            f
+          ), R = h(), K = (i) => {
+            r.diagnosticManager.reviewUnusedHelpers(
+              r.builderEntries,
+              i,
+              r.builderKind
+            );
+            const d = v(
+              r.builderEntries,
+              i,
+              r.builderKind
+            );
+            A(
+              r.builderEntries,
+              d,
+              r.builderKind,
+              r.diagnosticManager.describeHelper,
+              r.createError
+            ), t = d;
+            const k = () => r.resolveRunResult({
+              artifact: u,
+              diagnostics: [
+                ...r.diagnosticManager.readDiagnostics()
+              ],
+              steps: b,
+              context: l,
+              buildOptions: n,
+              options: a,
+              helpers: {
+                fragments: g,
+                builders: t
+              }
+            }), S = h();
+            return x(
+              F(
+                () => H.commit(f),
+                S
+              ),
+              k
+            );
+          };
+          return F(() => x(
+            C(
+              D,
+              (i) => r.options.createBuilderArgs({
+                helper: i.helper,
+                options: a,
+                context: l,
+                buildOptions: n,
+                artifact: u
+              }),
+              (i, d, k) => i.apply(d, k),
+              (i) => p(i)
+            ),
+            K
+          ), R);
+        });
+      });
+    }
+  };
+}
+export {
+  j as initPipelineRunner
+};

package/dist/internal/pipeline-runner.types.d.ts

@@ -0,0 +1,79 @@
+import { CreateDependencyGraphOptions, RegisteredHelper } from '../dependency-graph';
+import { ErrorFactory } from '../error-factory';
+import { CreatePipelineOptions, Helper, HelperApplyOptions, HelperKind, MaybePromise, PipelineDiagnostic, PipelineExecutionMetadata, PipelineExtensionHookOptions, PipelineExtensionLifecycle, PipelineExtensionRollbackErrorMetadata, PipelineReporter, PipelineStep } from '../types';
+import { DiagnosticManager } from './diagnostic-manager.types';
+import { ExtensionHookEntry } from '../extensions';
+/**
+ * Mutable state captured while preparing a pipeline run. This mirrors the context consumed by
+ * {@link executeHelpers} and downstream extension orchestration.
+ *
+ * @category Pipeline
+ * @internal
+ */
+export interface PipelineRunContext<TRunOptions, TBuildOptions, TContext, TDraft, TArtifact, TFragmentHelper, TBuilderHelper> {
+    readonly runOptions: TRunOptions;
+    readonly buildOptions: TBuildOptions;
+    readonly context: TContext;
+    readonly draft: TDraft;
+    readonly fragmentOrder: RegisteredHelper<TFragmentHelper>[];
+    readonly steps: PipelineStep[];
+    readonly pushStep: (entry: RegisteredHelper<unknown>) => void;
+    readonly builderGraphOptions: CreateDependencyGraphOptions<TBuilderHelper>;
+    readonly buildHookOptions: (artifact: TArtifact, lifecycle: PipelineExtensionLifecycle) => PipelineExtensionHookOptions<TContext, TRunOptions, TArtifact>;
+    readonly handleRollbackError: (options: {
+        readonly error: unknown;
+        readonly extensionKeys: readonly string[];
+        readonly hookSequence: readonly string[];
+        readonly errorMetadata: PipelineExtensionRollbackErrorMetadata;
+        readonly context: TContext;
+    }) => void;
+}
+/**
+ * Dependency bundle consumed by {@link initPipelineRunner}. Splitting the type into a dedicated
+ * module improves cognitive load in the implementation file and keeps the generics re-usable for
+ * test doubles.
+ *
+ * @category Pipeline
+ * @internal
+ */
+export interface PipelineRunnerDependencies<TRunOptions, TBuildOptions, TContext extends {
+    reporter: TReporter;
+}, TReporter extends PipelineReporter, TDraft, TArtifact, TDiagnostic extends PipelineDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind extends HelperKind, TBuilderKind extends HelperKind, TFragmentHelper extends Helper<TContext, TFragmentInput, TFragmentOutput, TReporter, TFragmentKind>, TBuilderHelper extends Helper<TContext, TBuilderInput, TBuilderOutput, TReporter, TBuilderKind>> {
+    readonly options: CreatePipelineOptions<TRunOptions, TBuildOptions, TContext, TReporter, TDraft, TArtifact, TDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>;
+    readonly fragmentEntries: RegisteredHelper<TFragmentHelper>[];
+    readonly builderEntries: RegisteredHelper<TBuilderHelper>[];
+    readonly fragmentKind: TFragmentKind;
+    readonly builderKind: TBuilderKind;
+    readonly diagnosticManager: DiagnosticManager<TRunOptions, TBuildOptions, TContext, TReporter, TDraft, TArtifact, TDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind, TBuilderKind, TFragmentHelper, TBuilderHelper>;
+    readonly createError: ErrorFactory;
+    readonly resolveRunResult: (state: {
+        readonly artifact: TArtifact;
+        readonly diagnostics: readonly TDiagnostic[];
+        readonly steps: readonly PipelineStep[];
+        readonly context: TContext;
+        readonly buildOptions: TBuildOptions;
+        readonly options: TRunOptions;
+        readonly helpers: PipelineExecutionMetadata<TFragmentKind, TBuilderKind>;
+    }) => TRunResult;
+    readonly extensionHooks: ExtensionHookEntry<TContext, TRunOptions, TArtifact>[];
+}
+/**
+ * Public surface returned by {@link initPipelineRunner}. Downstream consumers receive a helper to
+ * prepare the context (building dependency graphs, instantiating drafts) and an executor that runs
+ * the prepared context through fragments, extensions, and builders.
+ *
+ * @category Pipeline
+ * @internal
+ */
+export interface PipelineRunner<TRunOptions, TBuildOptions, TContext extends {
+    reporter: TReporter;
+}, TReporter extends PipelineReporter, TDraft, TArtifact, TDiagnostic extends PipelineDiagnostic, TRunResult, TFragmentInput, TFragmentOutput, TBuilderInput, TBuilderOutput, TFragmentKind extends HelperKind, TBuilderKind extends HelperKind, TFragmentHelper extends Helper<TContext, TFragmentInput, TFragmentOutput, TReporter, TFragmentKind>, TBuilderHelper extends Helper<TContext, TBuilderInput, TBuilderOutput, TReporter, TBuilderKind>> {
+    readonly prepareContext: (runOptions: TRunOptions) => PipelineRunContext<TRunOptions, TBuildOptions, TContext, TDraft, TArtifact, TFragmentHelper, TBuilderHelper>;
+    readonly executeRun: (context: PipelineRunContext<TRunOptions, TBuildOptions, TContext, TDraft, TArtifact, TFragmentHelper, TBuilderHelper>) => MaybePromise<TRunResult>;
+    readonly __types?: {
+        diagnostic: TDiagnostic;
+        helperArgs: HelperApplyOptions<unknown, unknown, unknown>;
+    };
+}
+export type { ExtensionHookEntry };
+//# sourceMappingURL=pipeline-runner.types.d.ts.map

package/dist/internal/pipeline-runner.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-runner.types.d.ts","sourceRoot":"","sources":["../../src/internal/pipeline-runner.types.ts"],"names":[],"mappings":"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"}

package/dist/registration.d.ts

@@ -1,4 +1,4 @@
-import { Helper, HelperKind, PipelineExtensionHook, PipelineReporter } from './types';
+import { Helper, HelperKind, PipelineExtensionHook, PipelineExtensionLifecycle, PipelineReporter } from './types';
 import { RegisteredHelper } from './dependency-graph';
 import { ExtensionHookEntry } from './extensions';
 import { ErrorFactory } from './error-factory';
@@ -22,11 +22,12 @@ export declare function registerHelper<TContext, TInput, TOutput, TReporter exte
  * @param key            - Optional unique key for the hook
  * @param hook           - The extension hook function
  * @param extensionHooks - The array of registered extension hooks
+ * @param lifecycle
  * @returns The resolved key used for registration
  *
  * @internal
  */
-export declare function registerExtensionHook<TContext, TOptions, TArtifact>(key: string | undefined, hook: PipelineExtensionHook<TContext, TOptions, TArtifact>, extensionHooks: ExtensionHookEntry<TContext, TOptions, TArtifact>[]): string;
+export declare function registerExtensionHook<TContext, TOptions, TArtifact>(key: string | undefined, hook: PipelineExtensionHook<TContext, TOptions, TArtifact>, extensionHooks: ExtensionHookEntry<TContext, TOptions, TArtifact>[], lifecycle?: PipelineExtensionLifecycle): string;
 /**
  * Handles the result of an extension's register() method.
  *

package/dist/registration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,MAAM,EACN,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,SAAS,gBAAgB,EAClC,KAAK,SAAS,UAAU,EACxB,OAAO,SAAS,MAAM,CACrB,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,EACT,KAAK,CACL,GAAG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,EAEvD,MAAM,EAAE,OAAO,EACf,YAAY,EAAE,UAAU,EACxB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,EACzE,WAAW,EAAE,YAAY,GACvB,IAAI,CA6BN;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAClE,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAC1D,cAAc,EAAE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GACjE,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAC1E,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GACjE,OAAO,CAWT"}
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,MAAM,EACN,UAAU,EACV,qBAAqB,EAErB,0BAA0B,EAC1B,gBAAgB,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,SAAS,gBAAgB,EAClC,KAAK,SAAS,UAAU,EACxB,OAAO,SAAS,MAAM,CACrB,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,EACT,KAAK,CACL,GAAG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,EAEvD,MAAM,EAAE,OAAO,EACf,YAAY,EAAE,UAAU,EACxB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,EAAE,EACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,EACzE,WAAW,EAAE,YAAY,GACvB,IAAI,CA6BN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAClE,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,IAAI,EAAE,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAC1D,cAAc,EAAE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EACnE,SAAS,GAAE,0BAA8C,GACvD,MAAM,CASR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAC1E,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GACjE,OAAO,CAqCT"}

package/dist/registration.js

@@ -1,50 +1,61 @@
-import { createHelperId as u } from "./dependency-graph.js";
+import { createHelperId as a } from "./dependency-graph.js";
 /**
  * @wpkernel/pipeline
  * @license EUPL-1.2
  */
-function k(e, t, i, o, f, r) {
-  if (e.kind !== t)
-    throw r(
+function p(e, i, o, t, r, d) {
+  if (e.kind !== i)
+    throw d(
       "ValidationError",
-      `Attempted to register helper "${e.key}" as ${o} but received kind "${e.kind}".`
+      `Attempted to register helper "${e.key}" as ${t} but received kind "${e.kind}".`
     );
   if (e.mode === "override") {
-    const s = i.find(
+    const c = o.find(
       (n) => n.helper.key === e.key && n.helper.mode === "override"
     );
-    if (s) {
+    if (c) {
       const n = `Multiple overrides registered for helper "${e.key}".`;
-      throw f(e, s.helper, n), r("ValidationError", n);
+      throw r(e, c.helper, n), d("ValidationError", n);
     }
   }
-  const d = i.length;
-  i.push({
+  const f = o.length;
+  o.push({
     helper: e,
-    id: u(e, d),
-    index: d
+    id: a(e, f),
+    index: f
   });
 }
-function c(e, t, i) {
-  const o = e ?? `pipeline.extension#${i.length + 1}`;
-  return i.push({
-    key: o,
-    hook: t
-  }), o;
+function g(e, i, o, t = "after-fragments") {
+  const r = e ?? `pipeline.extension#${o.length + 1}`;
+  return o.push({
+    key: r,
+    lifecycle: t,
+    hook: i
+  }), r;
 }
-function p(e, t, i) {
-  if (typeof t == "function") {
-    c(
+function s(e, i, o) {
+  if (typeof i == "function") {
+    g(
       e,
-      t,
-      i
+      i,
+      o
     );
     return;
   }
-  return t;
+  if (i && typeof i == "object" && "hook" in i && typeof i.hook == "function") {
+    const t = i;
+    g(
+      e,
+      t.hook,
+      o,
+      t.lifecycle
+    );
+    return;
+  }
+  return i;
 }
 export {
-  p as handleExtensionRegisterResult,
-  c as registerExtensionHook,
-  k as registerHelper
+  s as handleExtensionRegisterResult,
+  g as registerExtensionHook,
+  p as registerHelper
 };