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

package/README.md

@@ -86,6 +86,21 @@ console.log(result.artifact.result); // "item1, item2"
 - **Typed contracts** – helper descriptors, execution metadata, and diagnostics surfaces are
   fully typed for TypeScript consumers.
 
+## Official extension incubator
+
+The package owns an `src/extensions/` workspace where internal extensions are designed before
+being promoted to standalone packages. The directory ships a README that documents authoring
+guidelines and an [`official.ts`](./src/extensions/official.ts) catalogue describing the
+blueprints for:
+
+- a live runner extension that streams reporter events to interactive renderers;
+- a deterministic concurrency scheduler;
+- additional integration blueprints for telemetry and runtime adapters.
+
+Consumers can import the catalogue through `@wpkernel/pipeline/extensions` to understand the
+contracts and helper annotations each extension expects while we finalise their
+implementations.
+
 ## Consumers
 
 - `@wpkernel/cli` (code generation pipeline, codemod entry points)

package/dist/createExtension.d.ts

@@ -1,13 +1,14 @@
-import { MaybePromise, PipelineExtension, PipelineExtensionHook } from './types.js';
+import { MaybePromise, PipelineExtension, PipelineExtensionHook, PipelineExtensionHookRegistration, PipelineExtensionLifecycle } from './types.js';
 interface CreatePipelineExtensionBaseOptions {
     readonly key?: string;
 }
 interface CreatePipelineExtensionWithRegister<TPipeline, TContext, TOptions, TArtifact> extends CreatePipelineExtensionBaseOptions {
-    readonly register: (pipeline: TPipeline) => MaybePromise<void | PipelineExtensionHook<TContext, TOptions, TArtifact>>;
+    readonly register: (pipeline: TPipeline) => MaybePromise<void | PipelineExtensionHook<TContext, TOptions, TArtifact> | PipelineExtensionHookRegistration<TContext, TOptions, TArtifact>>;
 }
 interface CreatePipelineExtensionWithSetup<TPipeline, TContext, TOptions, TArtifact> extends CreatePipelineExtensionBaseOptions {
     readonly setup?: (pipeline: TPipeline) => MaybePromise<void>;
-    readonly hook?: PipelineExtensionHook<TContext, TOptions, TArtifact>;
+    readonly hook?: PipelineExtensionHook<TContext, TOptions, TArtifact> | PipelineExtensionHookRegistration<TContext, TOptions, TArtifact>;
+    readonly lifecycle?: PipelineExtensionLifecycle;
 }
 export type CreatePipelineExtensionOptions<TPipeline, TContext, TOptions, TArtifact> = CreatePipelineExtensionWithRegister<TPipeline, TContext, TOptions, TArtifact> | CreatePipelineExtensionWithSetup<TPipeline, TContext, TOptions, TArtifact>;
 /**

package/dist/createExtension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createExtension.d.ts","sourceRoot":"","sources":["../src/createExtension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,YAAY,CAAC;AAEpB,UAAU,kCAAkC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,mCAAmC,CAC5C,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAClB,QAAQ,EAAE,SAAS,KACf,YAAY,CAAC,IAAI,GAAG,qBAAqB,CAC7C,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,CAAC,CAAC;CACH;AAED,UAAU,gCAAgC,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;CACrE;AAED,MAAM,MAAM,8BAA8B,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,IAEP,mCAAmC,CACnC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,GACD,gCAAgC,CAChC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EAET,OAAO,EAAE,8BAA8B,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,GACC,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAsB7D"}
+{"version":3,"file":"createExtension.d.ts","sourceRoot":"","sources":["../src/createExtension.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,iCAAiC,EACjC,0BAA0B,EAC1B,MAAM,YAAY,CAAC;AAEpB,UAAU,kCAAkC;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,mCAAmC,CAC5C,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAClB,QAAQ,EAAE,SAAS,KACf,YAAY,CACd,IAAI,GACJ,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAClE,CAAC;CACF;AAED,UAAU,gCAAgC,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,SAAQ,kCAAkC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,CAAC,EACX,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GACpD,iCAAiC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,0BAA0B,CAAC;CAChD;AAED,MAAM,MAAM,8BAA8B,CACzC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,IAEP,mCAAmC,CACnC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,GACD,gCAAgC,CAChC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACR,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoJG;AACH,wBAAgB,uBAAuB,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EAET,OAAO,EAAE,8BAA8B,CACtC,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,CACT,GACC,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAoD7D"}

package/dist/createExtension.js

@@ -1,23 +1,32 @@
-import { isPromiseLike as u } from "./async-utils.js";
+import { isPromiseLike as f } from "./async-utils.js";
 /**
  * @wpkernel/pipeline
  * @license EUPL-1.2
  */
-function c(e) {
-  if ("register" in e)
+function l(r) {
+  if ("register" in r)
     return {
-      key: e.key,
-      register: e.register
+      key: r.key,
+      register: r.register
     };
-  const { key: i, setup: n, hook: t } = e;
+  const { key: o, setup: u, hook: e, lifecycle: t } = r;
   return {
-    key: i,
-    register(s) {
-      const r = n?.(s);
-      return r && u(r) ? r.then(() => t) : t;
+    key: o,
+    register(c) {
+      const n = () => {
+        if (e)
+          return typeof e == "function" ? t ? {
+            lifecycle: t,
+            hook: e
+          } : e : {
+            lifecycle: e.lifecycle ?? t,
+            hook: e.hook
+          };
+      }, i = u?.(c);
+      return i && f(i) ? i.then(n) : n();
     }
   };
 }
 export {
-  c as createPipelineExtension
+  l as createPipelineExtension
 };

package/dist/createPipeline.d.ts

@@ -1,203 +1,43 @@
 import { CreatePipelineOptions, Helper, HelperKind, Pipeline, PipelineDiagnostic, PipelineReporter, PipelineRunState } from './types';
 /**
- * Creates a pipeline orchestrator-the execution engine that powers WPKernel's entire code generation infrastructure.
+ * Creates a pipeline orchestrator-the execution engine that powers WPKernel's code generation stack.
  *
- * ## Why Pipelines Matter
- *
- * The pipeline system is the **single most critical component** of the framework:
- *
- * - **CLI package**: Every generator (`wpk generate resource`, `wpk generate action`, etc.) runs on pipeline
- * - **PHP Driver**: All PHP AST transformations flow through pipeline helpers
- * - **Core package**: Resource definitions, action middleware, and capability proxies leverage pipeline
- * - **Future-proof**: Designed to extract into standalone `@wpkernel/pipeline` package
- *
- * Pipelines provide:
- * 1. **Dependency resolution**: Topologically sorts helpers based on `dependsOn` declarations
- * 2. **Priority ordering**: Executes helpers in deterministic order via priority values
- * 3. **Error recovery**: Automatic rollback on failure via commit/rollback protocol
- * 4. **Diagnostics**: Built-in error tracking with reporter integration
- * 5. **Extensibility**: Plugin-style extensions via hooks (pre-run, post-build, etc.)
- *
- * ## Architecture
- *
- * A pipeline consists of three phases:
- *
- * ### 1. Registration Phase
- * ```
- * pipeline.registerFragment(helper1)
- * pipeline.registerBuilder(helper2)
- * ```
- * Helpers are collected but not executed. Dependency graph is constructed.
- *
- * ### 2. Execution Phase
- * ```
- * const result = await pipeline.run(options)
- * ```
- * - Validates dependency graph (detects missing deps, cycles)
- * - Sorts helpers topologically
- * - Runs fragment helpers to transform AST
- * - Runs builder helpers to produce artifacts
- * - Commits successful results
- *
- * ### 3. Rollback Phase (on error)
- * ```
- * // Automatic on failure
- * ```
- * - Walks back through executed helpers in reverse order
- * - Invokes rollback functions to undo side effects
- * - Aggregates diagnostics for debugging
- *
- * ## Extension System
- *
- * Pipelines support hooks that intercept execution at key points:
- *
- * - `pre-run`: Before any helpers execute (validation, setup)
- * - `post-fragment`: After fragment helpers complete (AST inspection)
- * - `post-builder`: After builder helpers complete (artifact transformation)
- * - `pre-commit`: Before committing results (final validation)
- *
- * Extensions enable:
- * - Custom validation logic
- * - Third-party integrations (ESLint, Prettier, type checkers)
- * - Conditional execution (feature flags, environment checks)
- * - Artifact post-processing (minification, bundling)
- *
- * ## Type Safety
- *
- * The pipeline is fully generic across 16 type parameters, enabling:
- * - Type-safe context sharing between helpers
- * - Strongly-typed input/output contracts
- * - Custom reporter integration (LogLayer, console, etc.)
- * - Flexible artifact types (strings, AST nodes, binary data)
- *
- * ## Performance
- *
- * - **Lazy execution**: Helpers only run when `pipeline.run()` is called
- * - **Incremental registration**: Add helpers at any time before execution
- * - **Async support**: Mix sync and async helpers seamlessly
- * - **Memory efficiency**: Helpers are immutable descriptors (no closures)
- *
- * @param    options
- * @category Pipeline
- *
- * @example Basic pipeline setup
- * ```typescript
- * import { createPipeline, createHelper } from '@wpkernel/core/pipeline';
- * import { createReporter } from '@wpkernel/core';
- *
- * interface MyContext {
- *   reporter: ReturnType<typeof createReporter>;
- *   namespace: string;
- * }
+ * The pipeline coordinates helper registration, dependency resolution, execution, diagnostics, and
+ * extension hooks. Refer to the package README for a full walkthrough and advanced usage examples.
  *
+ * @example
+ * ```ts
  * const pipeline = createPipeline({
  *   fragmentKind: 'fragment',
  *   builderKind: 'builder',
- *
- *   createContext: (reporter) => ({
- *     reporter,
- *     namespace: 'MyPlugin',
+ *   createContext: () => ({ reporter }),
+ *   createFragmentState: () => ({}),
+ *   finalizeFragmentState: ({ draft }) => draft,
+ *   createRunResult: ({ artifact, diagnostics }) => ({ artifact, diagnostics }),
+ *   createBuildOptions: () => ({}),
+ *   createFragmentArgs: ({ helper, draft, context }) => ({
+ *     helper,
+ *     context,
+ *     options: {},
+ *     buildOptions: {},
+ *     draft,
  *   }),
- *
- *   buildFragment: (ctx, opts) => {
- *     // Transform AST node
- *     const fragment = opts.input;
- *     fragment.namespace = ctx.namespace;
- *     return { fragment };
- *   },
- *
- *   buildArtifact: (ctx, opts) => {
- *     // Generate final PHP code
- *     const code = opts.draft.toString();
- *     return { artifact: code };
- *   },
- * });
- *
- * // Register helpers
- * pipeline.registerFragment(addPHPTagHelper);
- * pipeline.registerFragment(addNamespaceHelper);
- * pipeline.registerBuilder(writeFileHelper);
- *
- * // Execute
- * const result = await pipeline.run({ input: myAST });
- * console.log(result.artifact); // Generated PHP code
- * ```
- *
- * @example Pipeline with extensions
- * ```typescript
- * const pipeline = createPipeline({
- *   // ... base config ...
- *
- *   extensions: [
- *     {
- *       key: 'eslint-validation',
- *       hooks: {
- *         'post-builder': async ({ artifact, context }) => {
- *           const lintResult = await eslint.lintText(artifact);
- *           if (lintResult.errorCount > 0) {
- *             throw new Error('Linting failed');
- *           }
- *           return { artifact };
- *         },
- *       },
- *     },
- *   ],
- * });
- * ```
- *
- * @example Error handling with rollback
- * ```typescript
- * const result = await pipeline.run({ input: myAST });
- *
- * if (!result.success) {
- *   console.error('Pipeline failed:', result.diagnostics);
- *   // Rollback already executed automatically
- *   // Files restored, temp resources cleaned up
- * } else {
- *   console.log('Success:', result.artifact);
- *   // All commit functions executed
- * }
- * ```
- *
- * @example Real-world CLI usage
- * ```typescript
- * // This is how `wpk generate resource` works internally:
- *
- * const resourcePipeline = createPipeline({
- *   fragmentKind: 'fragment',
- *   builderKind: 'builder',
- *   createContext: (reporter) => ({
- *     reporter,
- *     config: loadKernelConfig(),
+ *   createBuilderArgs: ({ helper, artifact, context }) => ({
+ *     helper,
+ *     context,
+ *     options: {},
+ *     buildOptions: {},
+ *     artifact,
  *   }),
- *   buildFragment: (ctx, opts) => {
- *     // Build PHP AST for resource class
- *     return buildResourceClass(opts.input, ctx.config);
- *   },
- *   buildArtifact: async (ctx, opts) => {
- *     // Convert AST to PHP code
- *     const code = await printPhpAst(opts.draft);
- *     return { artifact: code };
- *   },
  * });
  *
- * // Register standard helpers
- * resourcePipeline.registerFragment(phpOpeningTagHelper);
- * resourcePipeline.registerFragment(namespaceHelper);
- * resourcePipeline.registerFragment(useStatementsHelper);
- * resourcePipeline.registerFragment(classDefinitionHelper);
- * resourcePipeline.registerBuilder(writeFileHelper);
- * resourcePipeline.registerBuilder(formatCodeHelper);
- *
- * // User can inject custom helpers via config
- * const userHelpers = loadUserHelpers();
- * userHelpers.forEach(h => resourcePipeline.registerFragment(h));
- *
- * // Execute generation
- * const result = await resourcePipeline.run({
- *   input: { name: 'Post', endpoint: '/posts' }
- * });
+ * pipeline.ir.use(createHelper({...}));
+ * pipeline.extensions.use(createPipelineExtension({ key: 'acme.audit' }));
+ * const result = await pipeline.run({});
+ * console.log(result.diagnostics.length);
  * ```
+ *
+ * @category Pipeline
  */
 export declare function createPipeline<TRunOptions, TBuildOptions, TContext extends {
     reporter: TReporter;

package/dist/createPipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createPipeline.d.ts","sourceRoot":"","sources":["../src/createPipeline.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACX,qBAAqB,EACrB,MAAM,EAEN,UAAU,EAGV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAMhB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuMG;AACH,wBAAgB,cAAc,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACxC,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,MAAM,GAAG,OAAO,EAChB,SAAS,GAAG,OAAO,EACnB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,UAAU,GAAG,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,EACrD,cAAc,GAAG,OAAO,EACxB,eAAe,GAAG,OAAO,EACzB,aAAa,GAAG,OAAO,EACvB,cAAc,GAAG,OAAO,EACxB,aAAa,SAAS,UAAU,GAAG,UAAU,EAC7C,YAAY,SAAS,UAAU,GAAG,SAAS,EAC3C,eAAe,SAAS,MAAM,CAC7B,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,GAAG,MAAM,CACT,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,GAAG,MAAM,CACT,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,EAED,OAAO,EAAE,qBAAqB,CAC7B,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,QAAQ,CACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,CAywBA"}
+{"version":3,"file":"createPipeline.d.ts","sourceRoot":"","sources":["../src/createPipeline.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACX,qBAAqB,EACrB,MAAM,EAEN,UAAU,EAEV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAEhB,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,wBAAgB,cAAc,CAC7B,WAAW,EACX,aAAa,EACb,QAAQ,SAAS;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,EACxC,SAAS,SAAS,gBAAgB,GAAG,gBAAgB,EACrD,MAAM,GAAG,OAAO,EAChB,SAAS,GAAG,OAAO,EACnB,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,UAAU,GAAG,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,EACrD,cAAc,GAAG,OAAO,EACxB,eAAe,GAAG,OAAO,EACzB,aAAa,GAAG,OAAO,EACvB,cAAc,GAAG,OAAO,EACxB,aAAa,SAAS,UAAU,GAAG,UAAU,EAC7C,YAAY,SAAS,UAAU,GAAG,SAAS,EAC3C,eAAe,SAAS,MAAM,CAC7B,QAAQ,EACR,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,CACb,GAAG,MAAM,CACT,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,GAAG,MAAM,CACT,QAAQ,EACR,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,CACZ,EAED,OAAO,EAAE,qBAAqB,CAC7B,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,QAAQ,CACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,WAAW,EACX,aAAa,EACb,YAAY,EACZ,eAAe,EACf,cAAc,CACd,CAwNA"}