@kubb/core 5.0.0-alpha.54 → 5.0.0-alpha.56

package/dist/{types-CeLqzzAf.d.ts → types-BjL3cJ-T.d.ts}

@@ -307,46 +307,70 @@ type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TEl
  */
 declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
 //#endregion
-//#region src/defineParser.d.ts
-type PrintOptions = {
-  extname?: FileNode['extname'];
-};
-type Parser<TMeta extends object = any> = {
+//#region src/definePlugin.d.ts
+/**
+ * A plugin object produced by `definePlugin`.
+ * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
+ * (matching Astro's integration naming convention).
+ *
+ * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ */
+type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   */
   name: string;
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * Plugins that must be registered before this plugin executes.
+   * An error is thrown at startup when any listed dependency is missing.
+   */
+  dependencies?: Array<string>;
+  /**
+   * Controls the execution order of this plugin relative to others.
    *
-   * @example Handled extensions
-   * `['.ts', '.js']`
+   * - `'pre'`  — runs before all normal plugins.
+   * - `'post'` — runs after all normal plugins.
+   * - `undefined` (default) — runs in declaration order among normal plugins.
+   *
+   * Dependency constraints always take precedence over `enforce`.
    */
-  extNames: Array<FileNode['extname']> | undefined;
+  enforce?: 'pre' | 'post';
   /**
-   * Convert a resolved file to a string.
+   * The options passed by the user when calling the plugin factory.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
+  options?: TFactory['options'];
+  /**
+   * Lifecycle event handlers for this plugin.
+   * Any event from the global `KubbHooks` map can be subscribed to here.
+   */
+  hooks: { [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void> } & {
+    'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
+  };
 };
 /**
- * Defines a parser with type safety.
+ * Creates a plugin factory using the hook-style (`hooks:`) API.
  *
- * Use this function to create parsers that transform generated files to strings
- * based on their extension.
+ * The returned factory is called with optional options and produces a `Plugin`
+ * that coexists with plugins created via the legacy `createPlugin` API in the same
+ * `kubb.config.ts`.
+ *
+ * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
+ * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
  *
  * @example
  * ```ts
- * import { defineParser } from '@kubb/core'
- *
- * export const jsonParser = defineParser({
- *   name: 'json',
- *   extNames: ['.json'],
- *   parse(file) {
- *     const { extractStringsFromNodes } = await import('@kubb/ast')
- *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ * // With PluginFactoryOptions (recommended for real plugins)
+ * export const pluginTs = definePlugin<PluginTs>((options) => ({
+ *   name: 'plugin-ts',
+ *   hooks: {
+ *     'kubb:plugin:setup'(ctx) {
+ *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+ *     },
  *   },
- * })
+ * }))
  * ```
  */
-declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta>;
+declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
 //#endregion
 //#region src/FileManager.d.ts
 /**
@@ -381,7 +405,6 @@ declare class FileManager {
   clear(): void;
   /**
    * All stored files, sorted by path length (shorter paths first).
-   * Barrel/index files (e.g. index.ts) are sorted last within each length bucket.
    */
   get files(): Array<FileNode>;
 }
@@ -730,6 +753,13 @@ interface KubbHooks {
    * The adapter has already parsed the source and `inputNode` is available.
    */
   'kubb:build:start': [ctx: KubbBuildStartContext];
+  /**
+   * Fired after all plugins have run and all per-plugin barrels have been generated,
+   * but BEFORE files are written to disk.
+   * Use this event to inject final files (e.g. a root barrel) that must be persisted
+   * in the same write pass as the plugin output.
+   */
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext];
   /**
    * Fired after all files have been written to disk.
    */
@@ -776,75 +806,155 @@ declare global {
      * ```
      */
     interface PluginRegistry {}
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
   }
 }
 //#endregion
-//#region src/definePlugin.d.ts
+//#region src/defineMiddleware.d.ts
 /**
- * A plugin object produced by `definePlugin`.
- * Instead of flat lifecycle methods, it groups all handlers under a `hooks:` property
- * (matching Astro's integration naming convention).
+ * A middleware observes and post-processes the build output produced by plugins.
+ * It attaches listeners to the shared `hooks` emitter before the plugin execution loop
+ * begins and reacts to lifecycle events (e.g. `kubb:plugin:end`, `kubb:build:end`) to
+ * inject barrel files or perform other cross-cutting concerns.
  *
- * @template TFactory - The plugin's `PluginFactoryOptions` type.
+ * Middleware listeners are always registered **after** all plugin listeners, because
+ * `createKubb` installs middleware only after the `PluginDriver` has registered every
+ * plugin's hooks.  This means middleware hooks for any event always fire last.
+ *
+ * @example
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
+ * export const myMiddleware = defineMiddleware({
+ *   name: 'my-middleware',
+ *   install(hooks) {
+ *     hooks.on('kubb:build:end', ({ files }) => {
+ *       console.log(`Build complete with ${files.length} files`)
+ *     })
+ *   },
+ * })
+ * ```
  */
-type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+type Middleware = {
   /**
-   * Unique name for the plugin, following the same naming convention as `createPlugin`.
+   * Unique identifier for this middleware.
    */
   name: string;
   /**
-   * Plugins that must be registered before this plugin executes.
-   * An error is thrown at startup when any listed dependency is missing.
+   * Called during `createKubb` after `setup()` but before the plugin
+   * execution loop starts. Attach listeners to `hooks` here.
    */
-  dependencies?: Array<string>;
+  install(hooks: AsyncEventEmitter<KubbHooks>): void;
+};
+/**
+ * Identity factory for middleware.
+ * Returns the middleware object unchanged but provides a typed entry-point
+ * to define middleware with proper inference.
+ *
+ * @example
+ * ```ts
+ * export const myMiddleware = defineMiddleware({
+ *   name: 'my-middleware',
+ *   install(hooks) {
+ *     hooks.on('kubb:build:end', ({ files }) => {
+ *       console.log(`Build complete with ${files.length} files`)
+ *     })
+ *   },
+ * })
+ * ```
+ */
+declare function defineMiddleware(middleware: Middleware): Middleware;
+//#endregion
+//#region src/defineParser.d.ts
+type PrintOptions = {
+  extname?: FileNode['extname'];
+};
+type Parser<TMeta extends object = any> = {
+  name: string;
   /**
-   * The options passed by the user when calling the plugin factory.
+   * File extensions this parser handles.
+   * Use `undefined` to create a catch-all fallback parser.
+   *
+   * @example Handled extensions
+   * `['.ts', '.js']`
    */
-  options?: TFactory['options'];
+  extNames: Array<FileNode['extname']> | undefined;
   /**
-   * Lifecycle event handlers for this plugin.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
+   * Convert a resolved file to a string.
    */
-  hooks: { [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void> } & {
-    'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>;
-  };
+  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string;
 };
 /**
- * Creates a plugin factory using the hook-style (`hooks:`) API.
- *
- * The returned factory is called with optional options and produces a `Plugin`
- * that coexists with plugins created via the legacy `createPlugin` API in the same
- * `kubb.config.ts`.
+ * Defines a parser with type safety.
  *
- * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
- * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+ * Use this function to create parsers that transform generated files to strings
+ * based on their extension.
  *
  * @example
  * ```ts
- * // With PluginFactoryOptions (recommended for real plugins)
- * export const pluginTs = definePlugin<PluginTs>((options) => ({
- *   name: 'plugin-ts',
- *   hooks: {
- *     'kubb:plugin:setup'(ctx) {
- *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
- *     },
+ * import { defineParser } from '@kubb/core'
+ *
+ * export const jsonParser = defineParser({
+ *   name: 'json',
+ *   extNames: ['.json'],
+ *   parse(file) {
+ *     const { extractStringsFromNodes } = await import('@kubb/ast')
+ *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
  *   },
- * }))
+ * })
  * ```
  */
-declare function definePlugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>(factory: (options: TFactory['options']) => Plugin<TFactory>): (options?: TFactory['options']) => Plugin<TFactory>;
+declare function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta>;
 //#endregion
-//#region src/utils/getBarrelFiles.d.ts
+//#region src/types.d.ts
 /**
- * Minimal file metadata attached to every generated file for barrel-file bookkeeping.
+ * Safely extracts the type of key `K` from `T`, returning `{}` when `K` is not a key of `T`.
+ * Used to implement optional interface augmentation for `Kubb.ConfigOptionsRegistry` and
+ * `Kubb.PluginOptionsRegistry` so that middleware and plugin packages can extend core types
+ * without requiring modifications to core.
  *
  * @internal
  */
-type FileMetaBase = {
-  pluginName?: string;
-};
-//#endregion
-//#region src/types.d.ts
+type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {};
 type InputPath = {
   /**
    * Specify your Swagger/OpenAPI file, either as an absolute path or a path relative to the root.
@@ -936,13 +1046,6 @@ type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
     path: string;
   }) => Array<ImportNode>;
 };
-/**
- * Controls how `index.ts` barrel files are generated.
- * - `'all'` — exports every generated symbol from every file.
- * - `'named'` — exports only explicitly named exports.
- * - `'propagate'` — propagates re-exports from nested barrel files upward.
- */
-type BarrelType = 'all' | 'named' | 'propagate';
 type DevtoolsOptions = {
   /**
    * Open the AST inspector view (`/ast`) in Kubb Studio.
@@ -1058,11 +1161,6 @@ type Config<TInput = Input> = {
      * @default { '.ts': '.ts'}
      */
     extension?: Record<FileNode['extname'], FileNode['extname'] | ''>;
-    /**
-     * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
-     * @default 'named'
-     */
-    barrelType?: 'all' | 'named' | false;
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -1078,7 +1176,7 @@ type Config<TInput = Input> = {
      * @default false
      */
     override?: boolean;
-  };
+  } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
   /**
    * An array of Kubb plugins used for code generation.
    * Each plugin may declare additional configurable options.
@@ -1086,6 +1184,22 @@ type Config<TInput = Input> = {
    * Use `dependencies` on the plugin to declare execution order.
    */
   plugins: Array<Plugin>;
+  /**
+   * Middleware instances that observe and post-process the build output.
+   * Each middleware receives the `hooks` emitter and attaches its own listeners.
+   * Middleware listeners are always registered after all plugin listeners,
+   * so middleware hooks fire last for any given event.
+   *
+   * @example
+   * ```ts
+   * import { middlewareBarrel } from '@kubb/middleware-barrel'
+   * export default defineConfig({
+   *   middleware: [middlewareBarrel],
+   *   plugins: [pluginTs(), pluginZod()],
+   * })
+   * ```
+   */
+  middleware?: Array<Middleware>;
   /**
    * Project-wide renderer factory. All plugins and generators that do not declare their own
    * `renderer` ultimately fall back to this value.
@@ -1360,11 +1474,6 @@ type Output<_TOptions = unknown> = {
    * Path to the output folder or file that will contain generated code.
    */
   path: string;
-  /**
-   * Define what needs to be exported, here you can also disable the export of barrel files
-   * @default 'named'
-   */
-  barrelType?: BarrelType | false;
   /**
    * Text or function appended at the start of every generated file.
    * When a function, receives the current `InputNode` and must return a string.
@@ -1380,7 +1489,7 @@ type Output<_TOptions = unknown> = {
    * @default false
    */
   override?: boolean;
-};
+} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>;
 type Group = {
   /**
    * Determines how files are grouped into subdirectories.
@@ -1481,6 +1590,37 @@ type KubbBuildStartContext = {
    */
   getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined;
   getPlugin(name: string): Plugin | undefined;
+  /**
+   * Returns all files currently in the file manager.
+   * Call this lazily (e.g. inside a `kubb:plugin:end` listener) to see files added by plugins
+   * that have already run.
+   */
+  readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Upsert one or more files into the file manager.
+   * Files with the same path are merged; new files are appended.
+   * Safe to call at any point during the plugin lifecycle, including inside `kubb:plugin:end`.
+   */
+  upsertFile: (...files: Array<FileNode>) => void;
+};
+/**
+ * Context passed to `kubb:plugins:end` handlers.
+ * Fires after all plugins have run and per-plugin barrels have been written,
+ * but BEFORE files are written to disk.
+ * Middleware that needs to inject final files (e.g. a root barrel) should use this event.
+ */
+type KubbPluginsEndContext = {
+  config: Config;
+  /**
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins and per-plugin barrel middleware.
+   */
+  readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Upsert one or more files into the file manager.
+   * Files added here will be included in the write pass that follows.
+   */
+  upsertFile: (...files: Array<FileNode>) => void;
 };
 /**
  * Context passed to a hook-style plugin's `kubb:build:end` handler.
@@ -1757,5 +1897,5 @@ type CLIOptions = {
  */
 type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>);
 //#endregion
-export { Plugin as $, KubbPluginSetupContext as A, Override as B, KubbGenerationStartContext as C, KubbInfoContext as D, KubbHookStartContext as E, Logger as F, ResolveOptionsContext as G, PossibleConfig as H, LoggerContext as I, ResolverFileParams as J, Resolver as K, LoggerOptions as L, KubbSuccessContext as M, KubbVersionNewContext as N, KubbLifecycleStartContext as O, KubbWarnContext as P, FileMetaBase as Q, NormalizedPlugin as R, KubbGenerationEndContext as S, KubbHookEndContext as T, ResolveBannerContext as U, PluginFactoryOptions as V, ResolveNameParams as W, UserConfig as X, ResolverPathParams as Y, UserLogger as Z, KubbDebugContext as _, AsyncEventEmitter as _t, CLIOptions as a, PluginDriver as at, KubbFilesProcessingEndContext as b, Exclude$1 as c, defineParser as ct, Include as d, Storage as dt, definePlugin as et, InputData as f, createStorage as ft, KubbConfigEndContext as g, logLevel as gt, KubbBuildStartContext as h, createRenderer as ht, BarrelType as i, createKubb as it, KubbPluginStartContext as j, KubbPluginEndContext as k, GeneratorContext as l, Generator as lt, KubbBuildEndContext as m, RendererFactory as mt, AdapterFactoryOptions as n, KubbHooks as nt, Config as o, FileManager as ot, InputPath as p, Renderer as pt, ResolverContext as q, AdapterSource as r, BuildOutput as rt, DevtoolsOptions as s, Parser as st, Adapter as t, Kubb$1 as tt, Group as u, defineGenerator as ut, KubbErrorContext as v, KubbGenerationSummaryContext as w, KubbFilesProcessingStartContext as x, KubbFileProcessingUpdateContext as y, Output as z };
-//# sourceMappingURL=types-CeLqzzAf.d.ts.map
+export { defineParser as $, KubbPluginStartContext as A, Override as B, KubbGenerationSummaryContext as C, KubbLifecycleStartContext as D, KubbInfoContext as E, Logger as F, ResolveOptionsContext as G, PossibleConfig as H, LoggerContext as I, ResolverFileParams as J, Resolver as K, LoggerOptions as L, KubbSuccessContext as M, KubbVersionNewContext as N, KubbPluginEndContext as O, KubbWarnContext as P, Parser as Q, NormalizedPlugin as R, KubbGenerationStartContext as S, KubbHookStartContext as T, ResolveBannerContext as U, PluginFactoryOptions as V, ResolveNameParams as W, UserConfig as X, ResolverPathParams as Y, UserLogger as Z, KubbErrorContext as _, logLevel as _t, Config as a, createKubb as at, KubbFilesProcessingStartContext as b, GeneratorContext as c, Plugin as ct, InputData as d, defineGenerator as dt, Middleware as et, InputPath as f, Storage as ft, KubbDebugContext as g, createRenderer as gt, KubbConfigEndContext as h, RendererFactory as ht, CLIOptions as i, BuildOutput as it, KubbPluginsEndContext as j, KubbPluginSetupContext as k, Group as l, definePlugin as lt, KubbBuildStartContext as m, Renderer as mt, AdapterFactoryOptions as n, Kubb$1 as nt, DevtoolsOptions as o, PluginDriver as ot, KubbBuildEndContext as p, createStorage as pt, ResolverContext as q, AdapterSource as r, KubbHooks as rt, Exclude$1 as s, FileManager as st, Adapter as t, defineMiddleware as tt, Include as u, Generator as ut, KubbFileProcessingUpdateContext as v, AsyncEventEmitter as vt, KubbHookEndContext as w, KubbGenerationEndContext as x, KubbFilesProcessingEndContext as y, Output as z };
+//# sourceMappingURL=types-BjL3cJ-T.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.54",
+  "version": "5.0.0-alpha.56",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "ast",
@@ -65,15 +65,15 @@
   "dependencies": {
     "fflate": "^0.8.2",
     "tinyexec": "^1.1.1",
-    "@kubb/ast": "5.0.0-alpha.54"
+    "@kubb/ast": "5.0.0-alpha.56"
   },
   "devDependencies": {
     "p-limit": "^7.3.0",
     "@internals/utils": "0.0.0",
-    "@kubb/renderer-jsx": "5.0.0-alpha.54"
+    "@kubb/renderer-jsx": "5.0.0-alpha.56"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-alpha.54"
+    "@kubb/renderer-jsx": "5.0.0-alpha.56"
   },
   "size-limit": [
     {

package/src/FileManager.ts

@@ -1,7 +1,5 @@
-import { trimExtName } from '@internals/utils'
 import type { FileNode } from '@kubb/ast'
 import { createFile } from '@kubb/ast'
-import { BARREL_BASENAME } from './constants.ts'
 
 function mergeFile<TMeta extends object = object>(a: FileNode<TMeta>, b: FileNode<TMeta>): FileNode<TMeta> {
   return {
@@ -95,39 +93,23 @@ export class FileManager {
 
   /**
    * All stored files, sorted by path length (shorter paths first).
-   * Barrel/index files (e.g. index.ts) are sorted last within each length bucket.
    */
   get files(): Array<FileNode> {
     if (this.#filesCache) {
       return this.#filesCache
     }
 
-    // Precompute the barrel-file flag per key so the comparator avoids repeated string work.
-    const keys = [...this.#cache.keys()]
-    const meta = new Map<string, { length: number; isIndex: boolean }>()
-    for (const key of keys) {
-      meta.set(key, {
-        length: key.length,
-        isIndex: trimExtName(key).endsWith(BARREL_BASENAME),
-      })
-    }
-    keys.sort((a, b) => {
-      const ma = meta.get(a)!
-      const mb = meta.get(b)!
-      if (ma.length !== mb.length) return ma.length - mb.length
-      if (ma.isIndex !== mb.isIndex) return ma.isIndex ? 1 : -1
+    this.#filesCache = [...this.#cache.values()].sort((a, b) => {
+      const lenDiff = a.path.length - b.path.length
+      if (lenDiff !== 0) return lenDiff
+      // Within the same length bucket, index.ts barrel files go last so other
+      // files are always processed before their barrel file.
+      const aIsIndex = a.path.endsWith('/index.ts') || a.path === 'index.ts'
+      const bIsIndex = b.path.endsWith('/index.ts') || b.path === 'index.ts'
+      if (aIsIndex && !bIsIndex) return 1
+      if (!aIsIndex && bIsIndex) return -1
       return 0
     })
-
-    const files: Array<FileNode> = []
-    for (const key of keys) {
-      const file = this.#cache.get(key)
-      if (file) {
-        files.push(file)
-      }
-    }
-
-    this.#filesCache = files
-    return files
+    return this.#filesCache
   }
 }

package/src/Kubb.ts

@@ -23,6 +23,7 @@ import type {
   KubbPluginEndContext,
   KubbPluginSetupContext,
   KubbPluginStartContext,
+  KubbPluginsEndContext,
   KubbSuccessContext,
   KubbVersionNewContext,
   KubbWarnContext,
@@ -225,6 +226,13 @@ export interface KubbHooks {
    * The adapter has already parsed the source and `inputNode` is available.
    */
   'kubb:build:start': [ctx: KubbBuildStartContext]
+  /**
+   * Fired after all plugins have run and all per-plugin barrels have been generated,
+   * but BEFORE files are written to disk.
+   * Use this event to inject final files (e.g. a root barrel) that must be persisted
+   * in the same write pass as the plugin output.
+   */
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext]
   /**
    * Fired after all files have been written to disk.
    */
@@ -273,5 +281,47 @@ declare global {
      * ```
      */
     interface PluginRegistry {}
+
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrelType?: import('./types.ts').BarrelType | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
   }
 }

package/src/PluginDriver.ts

@@ -28,6 +28,10 @@ type Options = {
   hooks: AsyncEventEmitter<KubbHooks>
 }
 
+function enforceOrder(enforce: 'pre' | 'post' | undefined): number {
+  return enforce === 'pre' ? -1 : enforce === 'post' ? 1 : 0
+}
+
 export class PluginDriver {
   readonly config: Config
   readonly options: Options
@@ -88,7 +92,8 @@ export class PluginDriver {
       .sort((a, b) => {
         if (b.dependencies?.includes(a.name)) return -1
         if (a.dependencies?.includes(b.name)) return 1
-        return 0
+        // enforce: 'pre' plugins run first, 'post' plugins run last
+        return enforceOrder(a.enforce) - enforceOrder(b.enforce)
       })
       .forEach((plugin) => {
         this.plugins.set(plugin.name, plugin)
@@ -107,6 +112,7 @@ export class PluginDriver {
     const normalizedPlugin = {
       name: hookPlugin.name,
       dependencies: hookPlugin.dependencies,
+      enforce: hookPlugin.enforce,
       options: { output: { path: '.' }, exclude: [], override: [] },
     } as unknown as NormalizedPlugin
 

package/src/constants.ts

@@ -15,19 +15,6 @@ export const DEFAULT_CONCURRENCY = 15
  */
 export const PARALLEL_CONCURRENCY_LIMIT = 100
 
-/**
- * Basename (without extension) of generated barrel files.
- *
- * Used to detect whether a path already points at a barrel so the generator
- * avoids re-creating one on top of it.
- */
-export const BARREL_BASENAME = 'index' as const
-
-/**
- * File name used for generated barrel (index) files.
- */
-export const BARREL_FILENAME = `${BARREL_BASENAME}.ts` as const
-
 /**
  * Default banner style written at the top of every generated file.
  */