@vercube/core 0.0.48 → 1.0.0-beta.1

package/dist/index.d.mts

@@ -1,27 +1,250 @@
 import { Container } from "@vercube/di";
 import { FastResponse, ServerPlugin } from "srvx";
-import { LoggerTypes } from "@vercube/logger";
+import { LoggerTypes, RequestLogger } from "@vercube/logger";
+import { BaseEvlogOptions } from "@vercube/logger/toolkit";
 import { DotenvOptions } from "c12";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region src/Services/Plugins/BasePlugin.d.ts
+//#region src/Services/Middleware/BaseMiddleware.d.ts
 /**
- * Represents a Plugin.
+ * BaseMiddleware class that serves as a base for all middleware implementations.
  */
-declare class BasePlugin<T = unknown> {
+declare class BaseMiddleware<T = any, U = any> {
   /**
-   * The name of the plugin.
+   * Middleware function that processes the HTTP event.
+   * This method should be overridden by subclasses to implement specific middleware logic.
+   * WARNING: This method cannot return a value, it will be ignored.
+   * Middleware can only modify the event object or throw an HttpError like BadRequestError, ForbiddenError, etc.
+   *
+   * @param {Request} request - The HTTP Request to process
+   * @param {T[]} args - Additional arguments for the middleware.
+   * @returns {void | Promise<void>} - A void or a promise that resolves when the processing is complete.
    */
-  name: string;
+  onRequest?(request: Request, response: Response, args: MiddlewareOptions<T>): MaybePromise<void | Response>;
   /**
-   * Uses the plugin with the given app.
-   * @param {App} app - The application instance.
-   * @returns {void | Promise<void>} - A void or a promise that resolves to void.
+   * Middleware function that processes the response.
+   * This method should be overridden by subclasses to implement specific middleware logic.
+   * WARNING: This method cannot return a value, it will be ignored.
+   * Middleware can only modify the event object or throw an HttpError like BadRequestError, ForbiddenError, etc.
+   *
+   * @param {Request} request - The HTTP Request to process
+   * @param {Response} response - The HTTP Response to process
+   * @returns {void | Promise<void>} - A void or a promise that resolves when the processing is complete.
    */
-  use(app: App, options?: T): void | Promise<void>;
+  onResponse?(request: Request, response: Response, payload: U): MaybePromise<void | Response>;
+}
+//#endregion
+//#region src/Types/RouterTypes.d.ts
+declare namespace RouterTypes {
+  interface Route {
+    path: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'CONNECT' | 'TRACE';
+    handler: RouterHandler;
+  }
+  interface RouteFind {
+    path: string;
+    method: string;
+  }
+  interface MiddlewareDefinition {
+    middleware: BaseMiddleware<unknown, unknown>;
+    target: string;
+    priority?: number;
+    args?: unknown;
+  }
+  interface RouterHandler {
+    instance: any;
+    propertyName: string;
+    args: MetadataTypes.Arg[];
+    middlewares: {
+      beforeMiddlewares: MiddlewareDefinition[];
+      afterMiddlewares: MiddlewareDefinition[];
+    };
+    actions: MetadataTypes.Action[];
+  }
+  interface RouteMatched<T = unknown> {
+    data: T;
+    params?: Record<string, string>;
+  }
+  type RouterEvent = RouterTypes.RouteMatched<RouterTypes.RouterHandler> & {
+    request: Request;
+    response: Response;
+  };
+}
+//#endregion
+//#region src/Types/ValidationTypes.d.ts
+declare namespace ValidationTypes {
+  type Schema = StandardSchemaV1;
+  type Result<T = any> = StandardSchemaV1.Result<T>;
+  type Input<T extends Schema = Schema> = StandardSchemaV1.InferInput<T>;
+}
+//#endregion
+//#region src/Types/MetadataTypes.d.ts
+declare namespace MetadataTypes {
+  interface Metadata {
+    __metadata: Ctx;
+  }
+  interface Ctx {
+    __controller: {
+      path: string;
+    };
+    __middlewares: Middleware[];
+    __methods: Record<string, Method>;
+    __meta?: Record<string, unknown>;
+  }
+  interface Method {
+    req: Request | null;
+    res: Response | null;
+    url: string | null;
+    method: string | null;
+    args: Arg[];
+    actions: Action[];
+    meta: Record<string, unknown>;
+  }
+  interface ResolvedData {
+    req: Request | null;
+    res: Response | null;
+    url: string | null;
+    args: Arg[];
+    actions: Action[];
+    middlewares: Middleware[];
+  }
+  interface Arg {
+    idx: number;
+    type: string;
+    data?: Record<string, any>;
+    resolver?: (event: RouterTypes.RouterEvent) => Promise<unknown>;
+    resolved?: unknown;
+    validate?: boolean;
+    validationSchema?: ValidationTypes.Schema;
+  }
+  interface Action {
+    handler: (req: Request, res: Response) => void | Response | ResponseInit;
+  }
+  interface Middleware<T = unknown, U = unknown> {
+    target: string;
+    priority?: number;
+    middleware: typeof BaseMiddleware<T, U>;
+    args?: unknown;
+  }
+  interface ResolveUrlParams {
+    instance: any;
+    path: string;
+    propertyName: string;
+  }
 }
 //#endregion
-//#region ../../node_modules/.pnpm/rolldown@1.0.2/node_modules/rolldown/dist/shared/logging-BSNejiLS.d.mts
+//#region src/Types/CommonTypes.d.ts
+type MaybePromise<T> = T | Promise<T>;
+interface MiddlewareOptions<T = any> {
+  middlewareArgs?: T;
+  methodArgs?: MetadataTypes.Arg[];
+}
+type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
+type RequestHandler = (request: Request) => Promise<Response>;
+//#endregion
+//#region src/Types/Plugin.d.ts
+/**
+ * Context passed to `BasePlugin.setupCLI` and object-style plugins' `cli` hook when the CLI loads config.
+ */
+interface VercubePluginCliContext {
+  /** Current working directory used to resolve the config file. */
+  cwd: string;
+  /**
+   * Citty subcommand when known (for example `dev`, `build`).
+   */
+  command?: string;
+  /** Merged configuration after the `config` plugin phase. */
+  config: ConfigTypes.Config;
+  /** Appends decorated command class constructors to the merged `config.cli.commands` list. */
+  register: (...commands: (new () => unknown)[]) => void;
+}
+/**
+ * Context passed to `BasePlugin.hooks` and object-style plugins' `hooks` hook in the `vercube dev` parent process only.
+ *
+ * `hooks` is typed as `unknown` so devkit's `Hookable<DevKitTypes.Hooks>` assigns without pulling `@vercube/devkit` into core.
+ */
+interface VercubePluginHooksContext {
+  /** Merged configuration for the dev session. */
+  config: ConfigTypes.Config;
+  /** Devkit hookable instance (`bundler-watch:*`, `dev:reload`, and related events). */
+  hooks: unknown;
+}
+/**
+ * Environment passed to plugin `config` and `setup` hooks during config loading and app bootstrap.
+ */
+interface VercubePluginEnv {
+  /** Working directory for config resolution and path-relative behavior. */
+  cwd: string;
+  /** Active CLI subcommand when hooks run in a CLI context. */
+  command?: string;
+  /** True when configuration is loaded for a development session. */
+  dev?: boolean;
+  /** True when configuration is loaded for production. */
+  production?: boolean;
+}
+/**
+ * Object-style plugin with optional lifecycle hooks (config merge, runtime setup, CLI registration, dev hooks).
+ */
+interface VercubePlugin {
+  /** Display name for logging and debugging. */
+  name?: string;
+  /**
+   * When the `config` hook runs relative to other plugins.
+   * `pre` runs first, `post` runs last; default runs in user order between them.
+   */
+  enforce?: 'pre' | 'post';
+  /**
+   * Merge partial configuration into the resolved config; returned values override previous layers.
+   */
+  config?: (config: ConfigTypes.Config, env: VercubePluginEnv) => MaybePromise<void | DeepPartial<ConfigTypes.Config>>;
+  /** Worker process: DI bindings, services, controllers. */
+  setup?: (app: App, env: VercubePluginEnv) => MaybePromise<void>;
+  /** Register CLI command classes (citty / `@vercube/cli`). */
+  cli?: (ctx: VercubePluginCliContext) => MaybePromise<void>;
+  /**
+   * Parent process only when running `vercube dev`: subscribe to `ctx.hooks` for bundler and reload events.
+   */
+  hooks?: (ctx: VercubePluginHooksContext) => MaybePromise<void>;
+}
+/**
+ * Resolves `TOptions` from a class that extends `BasePlugin<TOptions>`.
+ *
+ * @typeParam TClass - Constructor type whose instance extends `BasePlugin`.
+ */
+type InferPluginOptions<TClass extends new (...args: any[]) => BasePlugin<any>> = TClass extends (new (...args: any[]) => BasePlugin<infer O>) ? O : never;
+/**
+ * Class-only plugin entry as a tuple, checked with `satisfies` against `BasePlugin` options (no runtime helper).
+ *
+ * @typeParam TClass - `BasePlugin` subclass constructor.
+ */
+type PluginWithOptions<TClass extends new (...args: any[]) => BasePlugin<any>> = readonly [TClass] | readonly [TClass, InferPluginOptions<TClass>];
+/**
+ * Raw values allowed in `defineConfig({ plugins: [...] })` before `normalizeVercubePluginInputs`.
+ *
+ * Includes resolved plugin objects, promises, factories, bare `BasePlugin` classes, and `[Class, options?]` tuples.
+ */
+type VercubePluginInput = VercubePlugin | MaybePromise<VercubePlugin> | (() => MaybePromise<VercubePlugin>) | (new (...args: unknown[]) => BasePlugin) | [new (...args: unknown[]) => BasePlugin, unknown?];
+/**
+ * Convenience aliases for config-time plugin typing (`defineConfig`, tooling).
+ */
+declare namespace PluginTypes {
+  /**
+   * Any `BasePlugin` subclass constructor.
+   */
+  type PluginClass = new (...args: any[]) => BasePlugin;
+  /**
+   * Class entry as a bare constructor or `[Class, options]` before normalization.
+   */
+  type PluginDef = PluginClass | [PluginClass, unknown];
+  /**
+   * Same union as `VercubePluginInput`: all shapes allowed in `plugins` before resolution.
+   */
+  type PluginEntry = VercubePluginInput;
+  /** Alias for `VercubePluginCliContext`. */
+  type CliContext = VercubePluginCliContext;
+}
+//#endregion
+//#region ../../node_modules/.pnpm/rolldown@1.1.1/node_modules/rolldown/dist/shared/logging-BSNejiLS.d.mts
 //#region src/log/logging.d.ts
 /** @inline */
 type LogLevel = "info" | "debug" | "warn";
@@ -71,7 +294,7 @@ interface RolldownError extends RolldownLog {
 }
 type LogOrStringHandler = (level: LogLevelWithError, log: RolldownLogWithString) => void; //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/@oxc-project+types@0.132.0/node_modules/@oxc-project/types/types.d.ts
+//#region ../../node_modules/.pnpm/@oxc-project+types@0.135.0/node_modules/@oxc-project/types/types.d.ts
 // Auto-generated code, DO NOT EDIT DIRECTLY!
 // To edit this generated file you have to edit `tasks/ast_tools/src/generators/typescript.rs`.
 interface Program extends Span {
@@ -1370,7 +1593,7 @@ type UnaryOperator = "+" | "-" | "!" | "~" | "typeof" | "void" | "delete";
 type UpdateOperator = "++" | "--";
 type Node = Program | IdentifierName | IdentifierReference | BindingIdentifier | LabelIdentifier | ThisExpression | ArrayExpression | ObjectExpression | ObjectProperty | TemplateLiteral | TaggedTemplateExpression | TemplateElement | ComputedMemberExpression | StaticMemberExpression | PrivateFieldExpression | CallExpression | NewExpression | MetaProperty | SpreadElement | UpdateExpression | UnaryExpression | BinaryExpression | PrivateInExpression | LogicalExpression | ConditionalExpression | AssignmentExpression | ArrayAssignmentTarget | ObjectAssignmentTarget | AssignmentTargetRest | AssignmentTargetWithDefault | AssignmentTargetPropertyIdentifier | AssignmentTargetPropertyProperty | SequenceExpression | Super | AwaitExpression | ChainExpression | ParenthesizedExpression | Directive | Hashbang | BlockStatement | VariableDeclaration | VariableDeclarator | EmptyStatement | ExpressionStatement | IfStatement | DoWhileStatement | WhileStatement | ForStatement | ForInStatement | ForOfStatement | ContinueStatement | BreakStatement | ReturnStatement | WithStatement | SwitchStatement | SwitchCase | LabeledStatement | ThrowStatement | TryStatement | CatchClause | DebuggerStatement | AssignmentPattern | ObjectPattern | BindingProperty | ArrayPattern | BindingRestElement | Function$1 | FunctionBody | ArrowFunctionExpression | YieldExpression | Class | ClassBody | MethodDefinition | PropertyDefinition | PrivateIdentifier | StaticBlock | AccessorProperty | ImportExpression | ImportDeclaration | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ImportAttribute | ExportNamedDeclaration | ExportDefaultDeclaration | ExportAllDeclaration | ExportSpecifier | V8IntrinsicExpression | BooleanLiteral | NullLiteral | NumericLiteral | StringLiteral | BigIntLiteral | RegExpLiteral | JSXElement | JSXOpeningElement | JSXClosingElement | JSXFragment | JSXOpeningFragment | JSXClosingFragment | JSXNamespacedName | JSXMemberExpression | JSXExpressionContainer | JSXEmptyExpression | JSXAttribute | JSXSpreadAttribute | JSXIdentifier | JSXSpreadChild | JSXText | TSThisParameter | TSEnumDeclaration | TSEnumBody | TSEnumMember | TSTypeAnnotation | TSLiteralType | TSConditionalType | TSUnionType | TSIntersectionType | TSParenthesizedType | TSTypeOperator | TSArrayType | TSIndexedAccessType | TSTupleType | TSNamedTupleMember | TSOptionalType | TSRestType | TSAnyKeyword | TSStringKeyword | TSBooleanKeyword | TSNumberKeyword | TSNeverKeyword | TSIntrinsicKeyword | TSUnknownKeyword | TSNullKeyword | TSUndefinedKeyword | TSVoidKeyword | TSSymbolKeyword | TSThisType | TSObjectKeyword | TSBigIntKeyword | TSTypeReference | TSQualifiedName | TSTypeParameterInstantiation | TSTypeParameter | TSTypeParameterDeclaration | TSTypeAliasDeclaration | TSClassImplements | TSInterfaceDeclaration | TSInterfaceBody | TSPropertySignature | TSIndexSignature | TSCallSignatureDeclaration | TSMethodSignature | TSConstructSignatureDeclaration | TSIndexSignatureName | TSInterfaceHeritage | TSTypePredicate | TSModuleDeclaration | TSGlobalDeclaration | TSModuleBlock | TSTypeLiteral | TSInferType | TSTypeQuery | TSImportType | TSImportTypeQualifiedName | TSFunctionType | TSConstructorType | TSMappedType | TSTemplateLiteralType | TSAsExpression | TSSatisfiesExpression | TSTypeAssertion | TSImportEqualsDeclaration | TSExternalModuleReference | TSNonNullExpression | Decorator | TSExportAssignment | TSNamespaceExportDeclaration | TSInstantiationExpression | JSDocNullableType | JSDocNonNullableType | JSDocUnknownType | ParamPattern;
 //#endregion
-//#region ../../node_modules/.pnpm/rolldown@1.0.2/node_modules/rolldown/dist/shared/binding-DktDDYoY.d.mts
+//#region ../../node_modules/.pnpm/rolldown@1.1.1/node_modules/rolldown/dist/shared/binding-DgGsNpT9.d.mts
 interface CodegenOptions {
   /**
    * Remove whitespace.
@@ -1378,6 +1601,20 @@ interface CodegenOptions {
    * @default true
    */
   removeWhitespace?: boolean;
+  /**
+   * How to handle legal comments (comments containing `@license`, `@preserve`, or starting with `//!`/`/*!`).
+   *
+   * * `"none"` - Do not preserve any legal comments.
+   * * `"inline"` - Preserve all legal comments inline.
+   * * `"eof"` - Move all legal comments to the end of the file.
+   * * `"external"` - Extract legal comments without linking.
+   * * `{ linked: "path/to/legal.txt" }` - Extract legal comments and add a link comment to the given path.
+   *
+   * @default "none" (when minifying)
+   */
+  legalComments?: 'none' | 'inline' | 'eof' | 'external' | {
+    linked: string;
+  };
 }
 interface CompressOptions {
   /**
@@ -1392,7 +1629,7 @@ interface CompressOptions {
    *
    * @default 'esnext'
    *
-   * @see [esbuild#target](https://esbuild.github.io/api/#target)
+   * @see [oxc#target](https://oxc.rs/docs/guide/usage/transformer/lowering#target)
    */
   target?: string | Array<string>;
   /**
@@ -1659,6 +1896,18 @@ interface DecoratorOptions {
    * @default false
    */
   emitDecoratorMetadata?: boolean;
+  /**
+   * Aligns nullable-union `design:type` emission with `--strictNullChecks`.
+   *
+   * When `true` (default), `T | null` and `T | undefined` emit `Object`, matching tsc strict.
+   * When `false`, `null` and `undefined` are elided from the union so the underlying
+   * primitive constructor is emitted, matching tsc with `--strictNullChecks=false`
+   * and `babel-plugin-transform-typescript-metadata`.
+   *
+   * @see https://www.typescriptlang.org/tsconfig/#strictNullChecks
+   * @default true
+   */
+  strictNullChecks?: boolean;
 }
 type HelperMode =
 /**
@@ -1792,6 +2041,94 @@ interface PluginsOptions {
   styledComponents?: StyledComponentsOptions;
   taggedTemplateEscape?: boolean;
 }
+/** Dynamic gating for {@link ReactCompilerOptions#dynamicGating}. */
+interface ReactCompilerDynamicGating {
+  /** Module the gating import comes from. */
+  source: string;
+}
+/** Static gating for {@link ReactCompilerOptions#gating}. */
+interface ReactCompilerGating {
+  /** Module the gating import comes from. */
+  source: string;
+  /** Imported specifier used as the gate. */
+  importSpecifierName: string;
+}
+/**
+ * Options for the experimental [React Compiler](https://github.com/facebook/react/pull/36173).
+ *
+ * Mirrors the compiler's `PluginOptions`. The deep `environment` configuration
+ * (inference / validation flags) is not surfaced here.
+ *
+ * @see {@link TransformOptions#reactCompiler}
+ */
+interface ReactCompilerOptions {
+  /**
+   * Which functions to compile.
+   *
+   * @default 'infer'
+   */
+  compilationMode?: 'infer' | 'syntax' | 'annotation' | 'all';
+  /**
+   * What to do when a function cannot be compiled.
+   *
+   * @default 'none'
+   */
+  panicThreshold?: 'none' | 'critical_errors' | 'all_errors';
+  /**
+   * React runtime version target. `17` and `18` require the
+   * `react-compiler-runtime` package; `19` ships the runtime in `react`.
+   *
+   * @default '19'
+   */
+  target?: '17' | '18' | '19';
+  /**
+   * Analyze and report diagnostics only; emit no transformed code.
+   *
+   * @default false
+   */
+  noEmit?: boolean;
+  /**
+   * Compiler output mode.
+   *
+   * @default undefined
+   */
+  outputMode?: 'client' | 'ssr' | 'lint';
+  /**
+   * Compile even functions marked with the `"use no memo"` / `"use no forget"`
+   * opt-out directives.
+   *
+   * @default false
+   */
+  ignoreUseNoForget?: boolean;
+  /**
+   * Treat Flow suppression comments as opt-outs.
+   *
+   * @default true
+   */
+  flowSuppressions?: boolean;
+  /**
+   * Enable `react-native-reanimated` support.
+   *
+   * @default false
+   */
+  enableReanimated?: boolean;
+  /**
+   * Development mode (extra validation / instrumentation).
+   *
+   * @default false
+   */
+  isDev?: boolean;
+  /** Source file name, used for the fast-refresh hash and in diagnostics. */
+  filename?: string;
+  /** ESLint rules whose suppressions opt a function out of compilation. */
+  eslintSuppressionRules?: Array<string>;
+  /** Extra directives that opt a function out of compilation. */
+  customOptOutDirectives?: Array<string>;
+  /** Also emit a gated (feature-flagged) version of each compiled function. */
+  gating?: ReactCompilerGating;
+  /** Dynamically-gated compilation. */
+  dynamicGating?: ReactCompilerDynamicGating;
+}
 interface ReactRefreshOptions {
   /**
    * Specify the identifier of the refresh registration variable.
@@ -1951,6 +2288,14 @@ interface TransformOptions$1 {
   inject?: Record<string, string | [string, string]>;
   /** Decorator plugin */
   decorator?: DecoratorOptions;
+  /**
+   * Enable the experimental [React Compiler](https://github.com/facebook/react/pull/36173).
+   *
+   * `true` enables it with default options; an object enables it with the
+   * given options; `false` or omitted disables it. When enabled, the compiler
+   * runs as the first transform and memoizes React components and hooks.
+   */
+  reactCompiler?: boolean | ReactCompilerOptions;
   /**
    * Third-party plugins to use.
    * @see {@link https://oxc.rs/docs/guide/usage/transformer/plugins}
@@ -2286,7 +2631,8 @@ interface ViteImportGlobMeta {
   isSubImportsPattern?: boolean;
 } //#endregion
 //#endregion
-//#region ../../node_modules/.pnpm/@rolldown+pluginutils@1.0.0/node_modules/@rolldown/pluginutils/dist/filter/composable-filters.d.ts
+//#region ../../node_modules/.pnpm/@rolldown+pluginutils@1.0.1/node_modules/@rolldown/pluginutils/dist/filter/index.d.mts
+//#region src/filter/composable-filters.d.ts
 type StringOrRegExp$1 = string | RegExp;
 type PluginModuleType = 'js' | 'jsx' | 'ts' | 'tsx' | 'json' | 'text' | 'base64' | 'dataurl' | 'binary' | 'empty' | (string & {});
 type FilterExpression = And | Or | Not | Id | ImporterId | ModuleType$1 | Code | Query;
@@ -2348,7 +2694,7 @@ declare class Exclude$1 {
   constructor(expr: FilterExpression);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/rolldown@1.0.2/node_modules/rolldown/dist/shared/define-config-Bo24xyUK.d.mts
+//#region ../../node_modules/.pnpm/rolldown@1.1.1/node_modules/rolldown/dist/shared/define-config-ChOOV2QZ.d.mts
 //#region src/types/misc.d.ts
 /** @inline */
 type SourcemapPathTransformOption = (relativeSourcePath: string, sourcemapPath: string) => string;
@@ -3476,6 +3822,20 @@ type CodeSplittingGroup = {
   */
   entriesAwareMergeThreshold?: number;
   /**
+  * Whether to include captured modules' dependencies.
+  *
+  * Enabling this option reduces the chance of generating circular chunks.
+  *
+  * If you want to disable this behavior, it's recommended to both set
+  * - {@linkcode InputOptions.preserveEntrySignatures | preserveEntrySignatures}: `false | 'allow-extension'`
+  * - {@linkcode OutputOptions.strictExecutionOrder | strictExecutionOrder}: `true`
+  *
+  * to avoid generating invalid chunks.
+  *
+  * @default true
+  */
+  includeDependenciesRecursively?: boolean;
+  /**
   * Filter modules by tags. Only modules that have **all** specified tags
   * are captured by this group. Combines with `test` and other filters —
   * a module must match all criteria.
@@ -3501,15 +3861,7 @@ type CodeSplittingGroup = {
 */
 type CodeSplittingOptions = {
   /**
-  * By default, each group will also include captured modules' dependencies. This reduces the chance of generating circular chunks.
-  *
-  * If you want to disable this behavior, it's recommended to both set
-  * - {@linkcode InputOptions.preserveEntrySignatures | preserveEntrySignatures}: `false | 'allow-extension'`
-  * - {@linkcode OutputOptions.strictExecutionOrder | strictExecutionOrder}: `true`
-  *
-  * to avoid generating invalid chunks.
-  *
-  * @default true
+  * Global fallback of {@linkcode CodeSplittingGroup.includeDependenciesRecursively | group.includeDependenciesRecursively}, if it's not specified in the group.
   */
   includeDependenciesRecursively?: boolean;
   /**
@@ -3723,9 +4075,16 @@ interface ChecksOptions {
   * Such modules can significantly slow down module resolution. Consider using
   * [`@rolldown/plugin-transform-imports`](https://github.com/rolldown/plugins/tree/main/packages/transform-imports)
   * to rewrite barrel imports at the source level so the barrel file is never loaded.
+  *
+  * See [Large barrel modules](https://rolldown.rs/in-depth/lazy-barrel-optimization#large-barrel-modules) for more details.
   * @default true
   * */
   largeBarrelModules?: boolean;
+  /**
+  * Whether to emit warnings when a plugin transforms code without generating a sourcemap.
+  * @default true
+  * */
+  sourcemapBroken?: boolean;
 } //#endregion
 //#region src/options/transform-options.d.ts
 interface TransformOptions extends Omit<TransformOptions$1, "sourceType" | "lang" | "cwd" | "sourcemap" | "define" | "inject" | "jsx"> {
@@ -5769,8 +6128,11 @@ interface InputOptions {
     * Lazy barrel optimization avoids compiling unused re-export modules in side-effect-free barrel modules,
     * significantly improving build performance for large codebases with many barrel modules.
     *
+    * This option is planned to be removed in the future. If you need to opt out, please open an issue
+    * describing your use case so we can address it before the option is gone.
+    *
     * @see {@link https://rolldown.rs/in-depth/lazy-barrel-optimization | Lazy Barrel Documentation}
-    * @default false
+    * @default true
     */
     lazyBarrel?: boolean;
   };
@@ -6004,6 +6366,13 @@ declare namespace ConfigTypes {
      * The logging level for the application.
      */
     logLevel?: LoggerTypes.Level;
+    /**
+     * Enables the evlog request middleware, which emits one structured
+     * wide event per request (method, path, status, duration).
+     *
+     * @default true
+     */
+    requestLogging?: boolean;
     /**
      * Server configuration options.
      */
@@ -6021,6 +6390,22 @@ declare namespace ConfigTypes {
      * This property is only used when using vercube cli.
      */
     build?: BuildOptions;
+    /**
+     * CLI configuration options.
+     * This property is only used when using vercube cli.
+     */
+    cli?: {
+      /**
+       * List of command classes to register in the CLI.
+       * Each class must be decorated with @Command.
+       */
+      commands?: (new () => unknown)[];
+    };
+    /**
+     * Framework plugins (config, runtime, CLI, dev `hooks`).
+     * @see {@link https://vercube.dev/docs/advanced/custom-plugin} - Plugins documentation
+     */
+    plugins?: VercubePluginInput[];
     /**
      * Additional configuration for c12.
      */
@@ -6033,6 +6418,56 @@ declare namespace ConfigTypes {
   }
 }
 //#endregion
+//#region src/Services/Plugins/BasePlugin.d.ts
+/**
+ * Base class for class-based plugins registered via `defineConfig({ plugins })` or `app.addPlugin()`.
+ *
+ * @typeParam T - Options type passed into `configure`, `setup` / `use`, and `hooks` when provided.
+ */
+declare class BasePlugin<T = unknown> {
+  /** Stable identifier used by the plugin registry and logging. */
+  name: string;
+  /**
+   * Legacy runtime attach when the plugin is not registered with a `setup` implementation.
+   *
+   * @param app - Running application instance.
+   * @param options - Optional plugin options from registration or config tuple.
+   * @returns Void or a promise that settles when attachment is done.
+   */
+  use(app: App, options?: T): void | Promise<void>;
+  /**
+   * Merges partial config during the plugin `config` phase (config file and CLI load).
+   *
+   * @param config - Current merged configuration.
+   * @param options - Optional options from `[Class, options]` or adapter.
+   * @returns Partial config to merge, or void.
+   */
+  configure?(config: ConfigTypes.Config, options?: T): MaybePromise<void | DeepPartial<ConfigTypes.Config>>;
+  /**
+   * Worker runtime setup when listed in config `plugins`. If defined, runs instead of {@link use}.
+   *
+   * @param app - Running application instance.
+   * @param options - Optional plugin options.
+   * @returns Void or a promise that settles when setup is done.
+   */
+  setup?(app: App, options?: T): MaybePromise<void>;
+  /**
+   * Registers CLI commands when config is loaded (citty / `@vercube/cli`).
+   *
+   * @param ctx - CLI context with `register` and merged `config`.
+   * @returns Void or a promise that settles when registration is done.
+   */
+  setupCLI?(ctx: VercubePluginCliContext): MaybePromise<void>;
+  /**
+   * Dev parent process only (`vercube dev`): subscribe to bundler and reload hooks.
+   *
+   * @param ctx - Merged config and devkit `hooks` instance.
+   * @param options - Optional plugin options from the class adapter.
+   * @returns Void or a promise that settles when subscriptions are registered.
+   */
+  hooks?(ctx: VercubePluginHooksContext, options?: T): MaybePromise<void>;
+}
+//#endregion
 //#region src/Common/App.d.ts
 /**
  * Represents the main application class.
@@ -6096,150 +6531,13 @@ declare class App {
    */
   fetch(request: Request): Promise<Response>;
   /**
-   * Resolves and initializes the plugins for the application.
+   * Initializes registry plugins, then runs `setup` on each normalized config plugin in order.
    *
-   * @private
+   * @returns Resolves when all plugin `setup` hooks have been awaited.
    */
   private resolvePlugins;
 }
 //#endregion
-//#region src/Services/Middleware/BaseMiddleware.d.ts
-/**
- * BaseMiddleware class that serves as a base for all middleware implementations.
- */
-declare class BaseMiddleware<T = any, U = any> {
-  /**
-   * Middleware function that processes the HTTP event.
-   * This method should be overridden by subclasses to implement specific middleware logic.
-   * WARNING: This method cannot return a value, it will be ignored.
-   * Middleware can only modify the event object or throw an HttpError like BadRequestError, ForbiddenError, etc.
-   *
-   * @param {Request} request - The HTTP Request to process
-   * @param {T[]} args - Additional arguments for the middleware.
-   * @returns {void | Promise<void>} - A void or a promise that resolves when the processing is complete.
-   */
-  onRequest?(request: Request, response: Response, args: MiddlewareOptions<T>): MaybePromise<void | Response>;
-  /**
-   * Middleware function that processes the response.
-   * This method should be overridden by subclasses to implement specific middleware logic.
-   * WARNING: This method cannot return a value, it will be ignored.
-   * Middleware can only modify the event object or throw an HttpError like BadRequestError, ForbiddenError, etc.
-   *
-   * @param {Request} request - The HTTP Request to process
-   * @param {Response} response - The HTTP Response to process
-   * @returns {void | Promise<void>} - A void or a promise that resolves when the processing is complete.
-   */
-  onResponse?(request: Request, response: Response, payload: U): MaybePromise<void | Response>;
-}
-//#endregion
-//#region src/Types/RouterTypes.d.ts
-declare namespace RouterTypes {
-  interface Route {
-    path: string;
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD' | 'CONNECT' | 'TRACE';
-    handler: RouterHandler;
-  }
-  interface RouteFind {
-    path: string;
-    method: string;
-  }
-  interface MiddlewareDefinition {
-    middleware: BaseMiddleware<unknown, unknown>;
-    target: string;
-    priority?: number;
-    args?: unknown;
-  }
-  interface RouterHandler {
-    instance: any;
-    propertyName: string;
-    args: MetadataTypes.Arg[];
-    middlewares: {
-      beforeMiddlewares: MiddlewareDefinition[];
-      afterMiddlewares: MiddlewareDefinition[];
-    };
-    actions: MetadataTypes.Action[];
-  }
-  interface RouteMatched<T = unknown> {
-    data: T;
-    params?: Record<string, string>;
-  }
-  type RouterEvent = RouterTypes.RouteMatched<RouterTypes.RouterHandler> & {
-    request: Request;
-    response: Response;
-  };
-}
-//#endregion
-//#region src/Types/ValidationTypes.d.ts
-declare namespace ValidationTypes {
-  type Schema = StandardSchemaV1;
-  type Result<T = any> = StandardSchemaV1.Result<T>;
-  type Input<T extends Schema = Schema> = StandardSchemaV1.InferInput<T>;
-}
-//#endregion
-//#region src/Types/MetadataTypes.d.ts
-declare namespace MetadataTypes {
-  interface Metadata {
-    __metadata: Ctx;
-  }
-  interface Ctx {
-    __controller: {
-      path: string;
-    };
-    __middlewares: Middleware[];
-    __methods: Record<string, Method>;
-    __meta?: Record<string, unknown>;
-  }
-  interface Method {
-    req: Request | null;
-    res: Response | null;
-    url: string | null;
-    method: string | null;
-    args: Arg[];
-    actions: Action[];
-    meta: Record<string, unknown>;
-  }
-  interface ResolvedData {
-    req: Request | null;
-    res: Response | null;
-    url: string | null;
-    args: Arg[];
-    actions: Action[];
-    middlewares: Middleware[];
-  }
-  interface Arg {
-    idx: number;
-    type: string;
-    data?: Record<string, any>;
-    resolver?: (event: RouterTypes.RouterEvent) => Promise<unknown>;
-    resolved?: unknown;
-    validate?: boolean;
-    validationSchema?: ValidationTypes.Schema;
-  }
-  interface Action {
-    handler: (req: Request, res: Response) => void | Response | ResponseInit;
-  }
-  interface Middleware<T = unknown, U = unknown> {
-    target: string;
-    priority?: number;
-    middleware: typeof BaseMiddleware<T, U>;
-    args?: unknown;
-  }
-  interface ResolveUrlParams {
-    instance: any;
-    path: string;
-    propertyName: string;
-  }
-}
-//#endregion
-//#region src/Types/CommonTypes.d.ts
-type MaybePromise<T> = T | Promise<T>;
-interface MiddlewareOptions<T = any> {
-  middlewareArgs?: T;
-  methodArgs?: MetadataTypes.Arg[];
-}
-type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P] };
-type RequestHandler = (request: Request) => Promise<Response>;
-//#endregion
 //#region src/Common/CreateApp.d.ts
 interface CreateAppOptions {
   cfg?: ConfigTypes.Config;
@@ -6264,12 +6562,22 @@ declare function createApp({
 declare function defineConfig<T = Record<string, unknown>>(config: ConfigTypes.Config<T>): ConfigTypes.Config<T>;
 //#endregion
 //#region src/Config/Loader.d.ts
+interface LoadVercubeConfigOptions {
+  /** Directory containing `vercube.config` (defaults to `process.cwd()`). */
+  cwd?: string;
+  /** Custom ESM importer (for example CLI `jiti`) when loading the config module. */
+  import?: (id: string) => Promise<unknown>;
+  /** Active CLI subcommand name, forwarded to `VercubePluginEnv.command` for plugins. */
+  command?: string;
+}
 /**
- * Loads the configuration object for the application
- * @param {ConfigTypes.Config} overrides - The configuration object to load
- * @returns {ConfigTypes.Config} The loaded configuration object
+ * Loads and merges `vercube` config from disk, applies defaults, runs env setup, then the plugin `config` and `cli` pipeline.
+ *
+ * @param overrides - Values merged on top of file-based config (wins over file).
+ * @param options - `cwd`, optional `import`, and `command` for plugin context.
+ * @returns Fully merged config with normalized `plugins` and aggregated `cli.commands`.
  */
-declare function loadVercubeConfig(overrides?: ConfigTypes.Config): Promise<ConfigTypes.Config>;
+declare function loadVercubeConfig(overrides?: ConfigTypes.Config, options?: LoadVercubeConfigOptions): Promise<ConfigTypes.Config>;
 //#endregion
 //#region src/Decorators/Http/Body.d.ts
 interface BodyDecoratorOptions {
@@ -6715,6 +7023,61 @@ declare class HooksService {
   private objectToClass;
 }
 //#endregion
+//#region src/Plugins/VercubePlugin.d.ts
+/**
+ * Returns the same plugin object; narrows the type for object literals.
+ *
+ * @param plugin - Plugin definition with optional hooks.
+ * @returns The input plugin unchanged.
+ */
+declare function defineVercubePlugin(plugin: VercubePlugin): VercubePlugin;
+/**
+ * Builds a `[PluginClass, options]` tuple with options typed from the class `BasePlugin` generic.
+ *
+ * @param PluginClass - Constructor extending `BasePlugin<TOptions>`.
+ * @param options - Options object matching `TOptions` for that class.
+ * @returns Tuple consumed by the config `plugins` pipeline.
+ */
+declare function withPluginOptions<TClass extends new (...args: any[]) => BasePlugin<any>>(PluginClass: TClass, options: NoInfer<InferPluginOptions<TClass>>): [TClass, InferPluginOptions<TClass>];
+/**
+ * @param value - Any value to test.
+ * @returns True if `value` is a constructor whose prototype extends `BasePlugin`.
+ */
+declare function isBasePluginClass(value: unknown): value is new (...args: unknown[]) => BasePlugin;
+/**
+ * Adapts a `BasePlugin` subclass into a `VercubePlugin` for `defineConfig({ plugins })`.
+ *
+ * @param PluginClass - Plugin class constructor.
+ * @param options - Optional value passed into `configure`, `setup` / `use`, and `hooks`.
+ * @param displayName - Optional name; defaults to `PluginClass.name`.
+ * @returns Object implementing `VercubePlugin` that delegates to the class.
+ */
+declare function vercubePluginFromClass<T>(PluginClass: (new (...args: unknown[]) => BasePlugin<T>) & typeof BasePlugin<T>, options?: T, displayName?: string): VercubePlugin;
+/**
+ * Resolves async plugin factories and normalizes class entries into `VercubePlugin` objects.
+ *
+ * @param inputs - Raw `plugins` array from config, or undefined.
+ * @returns Resolved plugins in source order (before `enforce` sorting elsewhere).
+ * @throws {Error} If an array entry is neither `[Class]`, `[Class, options]`, nor a valid plugin shape.
+ */
+declare function normalizeVercubePluginInputs(inputs: readonly VercubePluginInput[] | undefined): Promise<VercubePlugin[]>;
+/**
+ * Runs each plugin's `config` hook (merge order), normalizes `plugins` to resolved objects, runs `cli` hooks, and merges registered commands into `config.cli.commands`.
+ *
+ * @param config - Full Vercube config (may contain raw plugin inputs).
+ * @param env - Working directory and CLI context flags.
+ * @returns Config with `plugins` normalized and CLI commands aggregated.
+ */
+declare function applyVercubePluginHooks(config: ConfigTypes.Config, env: VercubePluginEnv): Promise<ConfigTypes.Config>;
+/**
+ * Invokes `hooks` on each resolved plugin (dev parent process only).
+ *
+ * @param plugins - Normalized plugins from config (after `applyVercubePluginHooks`).
+ * @param ctx - Hooks context from devkit (`config`, `hooks`).
+ * @returns Resolves when every plugin `hooks` call completes.
+ */
+declare function invokeVercubePluginDevHooks(plugins: VercubePlugin[] | undefined, ctx: VercubePluginHooksContext): Promise<void>;
+//#endregion
 //#region src/Services/Middleware/GlobalMiddlewareRegistry.d.ts
 interface GlobalMiddlewareParams<T> extends Omit<MetadataTypes.Middleware<T>, 'middleware'> {}
 /**
@@ -6742,6 +7105,53 @@ declare class GlobalMiddlewareRegistry {
   registerGlobalMiddleware<T = unknown, U = unknown>(middleware: typeof BaseMiddleware<T, U>, opts?: GlobalMiddlewareParams<T>): void;
 }
 //#endregion
+//#region src/Middleware/EvlogMiddleware.d.ts
+/**
+ * Key under which the request-scoped evlog logger is stored in {@link RequestContext}.
+ */
+declare const EVLOG_REQUEST_LOGGER_KEY = "evlog:requestLogger";
+/**
+ * Key under which the evlog `finish` callback is stored in {@link RequestContext}.
+ */
+declare const EVLOG_FINISH_KEY = "evlog:finish";
+/**
+ * Global middleware that emits one structured wide event per request using
+ * evlog (https://evlog.dev).
+ *
+ * On each request it creates a request-scoped logger via evlog's toolkit and
+ * stores it in {@link RequestContext} (so handlers can enrich the event), then
+ * emits the accumulated wide event - including method, path, status and
+ * duration - when the response is produced.
+ *
+ * Registered automatically by the framework; disable via `requestLogging: false`
+ * in the application config.
+ */
+declare class EvlogMiddleware extends BaseMiddleware<BaseEvlogOptions> {
+  /**
+   * Request context used to carry the request-scoped logger across the lifecycle.
+   */
+  private gRequestContext;
+  /**
+   * Creates a request-scoped evlog logger and stores it in the request context.
+   *
+   * @param request - The incoming HTTP request
+   * @param _response - The current response (unused)
+   * @param args - Middleware options (evlog include/exclude/drain/enrich/keep)
+   */
+  onRequest(request: Request, _response: Response, args: MiddlewareOptions<BaseEvlogOptions>): void;
+  /**
+   * Emits the request wide event with the final response status.
+   *
+   * @param _request - The HTTP request (unused)
+   * @param response - The final HTTP response
+   */
+  onResponse(_request: Request, response: Response): Promise<void>;
+}
+/**
+ * Request-scoped wide-event logger type, re-exported for handler ergonomics.
+ */
+type EvlogRequestLogger = RequestLogger;
+//#endregion
 //#region src/Services/HttpServer/HttpServer.d.ts
 /**
  * HTTP server implementation for handling incoming web requests
@@ -7624,4 +8034,4 @@ declare function sanitizeObject(obj: Record<string, unknown>): Record<string, un
  */
 declare function safeAssign(target: any, source: Record<string, unknown>): void;
 //#endregion
-export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, ConfigTypes, Connect, Controller, CreateAppOptions, DANGEROUS_PROPERTIES, DeepPartial, Delete, ErrorHandlerProvider, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers, HooksService, HooksTypes, HttpError, HttpServer, HttpStatusCode, InternalServerError, Listen, MaybePromise, MetadataResolver, MetadataTypes, MethodNotAllowedError, Middleware$1 as Middleware, MiddlewareOptions, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, Post, Put, QueryParam, QueryParams, Redirect, Request$1 as Request, RequestContext, RequestHandler, Response$1 as Response, Router, RouterTypes, RuntimeConfig$1 as RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, ValidationTypes, createApp, createMetadataCtx, createMetadataMethod, defineConfig, initializeMetadata, initializeMetadataMethod, isSafeProperty, loadVercubeConfig, safeAssign, safeJsonParse, sanitizeObject, secureReviver };
+export { App, BadRequestError, BaseMiddleware, BasePlugin, Body, ConfigTypes, Connect, Controller, CreateAppOptions, DANGEROUS_PROPERTIES, DeepPartial, Delete, EVLOG_FINISH_KEY, EVLOG_REQUEST_LOGGER_KEY, ErrorHandlerProvider, EvlogMiddleware, EvlogRequestLogger, FastResponse, ForbiddenError, Get, GlobalMiddlewareRegistry, HTTPStatus, Head, Header, Headers, HooksService, HooksTypes, HttpError, HttpServer, HttpStatusCode, InferPluginOptions, InternalServerError, Listen, type LoadVercubeConfigOptions, MaybePromise, MetadataResolver, MetadataTypes, MethodNotAllowedError, Middleware$1 as Middleware, MiddlewareOptions, MultipartFormData, NotAcceptableError, NotFoundError, Options, Param, Patch, PluginTypes, PluginWithOptions, Post, Put, QueryParam, QueryParams, Redirect, Request$1 as Request, RequestContext, RequestHandler, Response$1 as Response, Router, RouterTypes, RuntimeConfig$1 as RuntimeConfig, SetHeader, StandardSchemaValidationProvider, Status, Trace, UnauthorizedError, ValidationProvider, ValidationTypes, VercubePlugin, VercubePluginCliContext, VercubePluginEnv, VercubePluginHooksContext, VercubePluginInput, applyVercubePluginHooks, createApp, createMetadataCtx, createMetadataMethod, defineConfig, defineVercubePlugin, initializeMetadata, initializeMetadataMethod, invokeVercubePluginDevHooks, isBasePluginClass, isSafeProperty, loadVercubeConfig, normalizeVercubePluginInputs, safeAssign, safeJsonParse, sanitizeObject, secureReviver, vercubePluginFromClass, withPluginOptions };