stratal 0.0.13 → 0.0.14

package/dist/i18n.module-C9wQr_2k.mjs

@@ -0,0 +1,1792 @@
+import { S as ApplicationError, b as ERROR_CODES, o as I18N_TOKENS, s as Scope, v as ROUTER_TOKENS, y as getHttpStatus } from "./errors-BRJgVd5-.mjs";
+import { a as __decorate, d as Transient, g as DI_TOKENS, m as getMethodInjections, o as __decorateParam, s as __decorateMetadata } from "./logger-Bg-CuidS.mjs";
+import { r as Module } from "./module-Dvzm4dhS.mjs";
+import { i as getControllerRoute, r as getControllerOptions, t as MiddlewareConfigurationService } from "./middleware-B3tx1u1K.mjs";
+import { a as ROUTER_CONTEXT_KEYS, c as VERSION_NEUTRAL, i as METHOD_STATUS_CODES, n as DEFAULT_CONTENT_TYPE, o as ROUTE_METADATA_KEYS, r as HTTP_METHODS, s as SECURITY_SCHEMES, t as RouterContext } from "./router-context-DlTxpJUG.mjs";
+import { i as z, o as backendErrorMap, r as validation_exports, s as runWithErrorMapContext, t as OpenAPIHono } from "./validation-DA5nptIp.mjs";
+import { t as en_exports } from "./en-C9U5-ETs.mjs";
+import { i as getMethodGuards, r as getControllerGuards, t as GuardExecutionService } from "./guards-B5o618bL.mjs";
+import { c as getWsOnMessageMethod, d as isGateway, o as getWsOnCloseMethod, s as getWsOnErrorMethod, t as GatewayContext } from "./gateway-context-D7TFPLi5.mjs";
+import { inject } from "tsyringe";
+import { compile, createCoreContext, registerMessageCompiler, translate } from "@intlify/core-base";
+import { swaggerUI } from "@hono/swagger-ui";
+//#region src/i18n/middleware/i18n-context.middleware.ts
+/**
+* I18n Context Middleware
+*
+* Sets up AsyncLocalStorage context for Zod i18n validation.
+* Must run after LocaleExtractionMiddleware sets the locale.
+*/
+let I18nContextMiddleware = class I18nContextMiddleware {
+	constructor(i18n) {
+		this.i18n = i18n;
+	}
+	async handle(ctx, next) {
+		await runWithErrorMapContext({
+			t: (key, params) => this.i18n.t(key, params),
+			locale: ctx.getLocale()
+		}, () => next());
+	}
+};
+I18nContextMiddleware = __decorate([
+	Transient(),
+	__decorateParam(0, inject(I18N_TOKENS.I18nService)),
+	__decorateMetadata("design:paramtypes", [Object])
+], I18nContextMiddleware);
+//#endregion
+//#region src/i18n/middleware/locale-extraction.middleware.ts
+/**
+* Locale Extraction Middleware
+*
+* Extracts locale from X-Locale header and sets it on RouterContext.
+* Validates against available locales from MessageLoaderService.
+*/
+let LocaleExtractionMiddleware = class LocaleExtractionMiddleware {
+	constructor(loader) {
+		this.loader = loader;
+	}
+	async handle(ctx, next) {
+		const locale = this.extractLocale(ctx);
+		ctx.setLocale(locale);
+		await next();
+	}
+	/**
+	* Extract and validate locale from X-Locale header
+	*/
+	extractLocale(ctx) {
+		const requestedLocale = ctx.header("x-locale")?.toLowerCase();
+		if (requestedLocale && this.loader.isLocaleSupported(requestedLocale)) return requestedLocale;
+		return this.loader.getDefaultLocale();
+	}
+};
+LocaleExtractionMiddleware = __decorate([
+	Transient(),
+	__decorateParam(0, inject(I18N_TOKENS.MessageLoader)),
+	__decorateMetadata("design:paramtypes", [Object])
+], LocaleExtractionMiddleware);
+//#endregion
+//#region src/openapi/openapi.tokens.ts
+/**
+* OpenAPI Module DI Tokens
+*/
+const OPENAPI_TOKENS = {
+	Options: Symbol.for("stratal:openapi:options"),
+	ConfigService: Symbol.for("stratal:openapi:config:service"),
+	OpenAPIService: Symbol.for("stratal:openapi:service")
+};
+//#endregion
+//#region src/openapi/services/openapi-config.service.ts
+let OpenAPIConfigService = class OpenAPIConfigService {
+	overrides = [];
+	constructor(baseOptions) {
+		this.baseOptions = baseOptions;
+	}
+	/**
+	* Add configuration override for this request
+	* Overrides are merged in the order they are added
+	*/
+	override(config) {
+		this.overrides.push(config);
+	}
+	/**
+	* Get effective configuration (base merged with all overrides)
+	*/
+	getEffectiveConfig() {
+		let effective = {
+			jsonPath: this.baseOptions?.jsonPath ?? "/api/openapi.json",
+			ui: this.baseOptions?.ui,
+			info: {
+				title: this.baseOptions?.info?.title ?? "API",
+				version: this.baseOptions?.info?.version ?? "1.0.0",
+				description: this.baseOptions?.info?.description
+			},
+			securitySchemes: this.baseOptions?.securitySchemes
+		};
+		for (const override of this.overrides) effective = this.mergeConfig(effective, override);
+		return effective;
+	}
+	/**
+	* Merge override into effective config
+	* Info is shallow-merged, routeFilter is replaced
+	*/
+	mergeConfig(base, override) {
+		return {
+			...base,
+			info: {
+				...base.info,
+				...override.info && {
+					title: override.info.title ?? base.info.title,
+					version: override.info.version ?? base.info.version,
+					description: override.info.description ?? base.info.description
+				}
+			},
+			routeFilter: override.routeFilter ?? base.routeFilter
+		};
+	}
+};
+OpenAPIConfigService = __decorate([
+	Transient(OPENAPI_TOKENS.ConfigService),
+	__decorateParam(0, inject(OPENAPI_TOKENS.Options, { isOptional: true })),
+	__decorateMetadata("design:paramtypes", [Object])
+], OpenAPIConfigService);
+//#endregion
+//#region src/i18n/messages/index.ts
+/**
+* Core Messages
+*
+* Messages used by packages/modules infrastructure.
+* These are automatically merged with application-specific messages.
+*/
+/**
+* All locale messages
+* Explicitly import and export (no filesystem scanning - Cloudflare Workers compatible)
+*/
+const messages = { en: en_exports };
+/**
+* Get messages for all locales
+*/
+function getMessages() {
+	return messages;
+}
+/**
+* Get available locales
+*/
+function getLocales() {
+	return Object.keys(messages);
+}
+//#endregion
+//#region src/i18n/setup.ts
+/**
+* I18n Setup - Message Compiler Registration
+*
+* Registers a JIT (Just-In-Time) message compiler for @intlify/core-base
+* that works in Cloudflare Workers edge runtime.
+*
+* This must be called ONCE at application startup, before any I18nService instances are created.
+*/
+let isRegistered = false;
+/**
+* Setup JIT message compiler for i18n
+*
+* Registers a message compiler that uses JIT compilation mode.
+* In @intlify/core-base v10+, JIT mode is enabled by default, which generates
+* AST (Abstract Syntax Tree) instead of JavaScript code, making it compatible
+* with CSP-restricted environments like Cloudflare Workers.
+*
+* **IMPORTANT:** Call this function once at application startup before creating
+* any I18nService instances. Safe to call multiple times (only registers once).
+*
+* @example
+* ```typescript
+* // In application entry point (before app.initialize())
+* setupI18nCompiler()
+* ```
+*/
+function setupI18nCompiler() {
+	if (isRegistered) return;
+	registerMessageCompiler(compile);
+	isRegistered = true;
+	console.log("[i18n] JIT message compiler registered successfully");
+}
+//#endregion
+//#region src/i18n/i18n.options.ts
+/**
+* Resolve I18n options with defaults
+*/
+function resolveI18nOptions(options) {
+	return {
+		defaultLocale: options?.defaultLocale ?? "en",
+		fallbackLocale: options?.fallbackLocale ?? "en",
+		locales: options?.locales ?? ["en"],
+		messages: options?.messages ?? {}
+	};
+}
+//#endregion
+//#region src/i18n/errors/locale-not-supported.error.ts
+/**
+* Locale Not Supported Error
+* Thrown when an unsupported locale is requested
+*
+* HTTP Status: 500 Internal Server Error
+* Error Code: 9301
+*/
+var LocaleNotSupportedError = class extends ApplicationError {
+	constructor(locale, supportedLocales) {
+		super("errors.localeNotSupported", ERROR_CODES.I18N.LOCALE_NOT_SUPPORTED, {
+			locale,
+			supportedLocales: supportedLocales.join(", ")
+		});
+	}
+};
+//#endregion
+//#region src/i18n/errors/translation-missing.error.ts
+/**
+* Translation Missing Error
+* Thrown when a translation key is missing from all locales
+*
+* HTTP Status: 500 Internal Server Error
+* Error Code: 9300
+*/
+var TranslationMissingError = class extends ApplicationError {
+	constructor(key, locale) {
+		super("errors.translationMissing", ERROR_CODES.I18N.TRANSLATION_MISSING, {
+			key,
+			locale
+		});
+	}
+};
+//#endregion
+//#region src/router/decorators/http-method.decorator.ts
+/**
+* Creates an HTTP method decorator factory for the given HTTP method.
+*
+* The returned decorator stores {@link HttpRouteMetadata} on the method and
+* tracks the method name under {@link ROUTE_METADATA_KEYS.HTTP_DECORATED_METHODS}
+* on the controller prototype so they can be discovered at registration time.
+*/
+function createHttpMethodDecorator(method) {
+	return function(path, config) {
+		return function(target, propertyKey, descriptor) {
+			const metadata = {
+				method,
+				path,
+				config: config ?? { response: z.any() }
+			};
+			Reflect.defineMetadata(ROUTE_METADATA_KEYS.HTTP_ROUTE_CONFIG, metadata, target, propertyKey);
+			const existing = Reflect.getOwnMetadata(ROUTE_METADATA_KEYS.HTTP_DECORATED_METHODS, target) ?? [];
+			existing.push(propertyKey);
+			Reflect.defineMetadata(ROUTE_METADATA_KEYS.HTTP_DECORATED_METHODS, existing, target);
+			return descriptor;
+		};
+	};
+}
+/**
+* Registers a GET route on the controller method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration (response schema, body, params, etc.)
+*
+* @example
+* ```typescript
+* @Controller('/api/v1/users')
+* class UsersController {
+*   @Get('/', { response: z.array(userSchema), summary: 'List users' })
+*   async list(ctx: RouterContext) { ... }
+*
+*   @Get('/:id', { params: z.object({ id: z.string().uuid() }), response: userSchema })
+*   async getUser(ctx: RouterContext) { ... }
+* }
+* ```
+*/
+const Get = createHttpMethodDecorator("get");
+/**
+* Registers a POST route on the controller method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration (response schema, body, params, etc.)
+*
+* @example
+* ```typescript
+* @Controller('/api/v1/users')
+* class UsersController {
+*   @Post('/', { body: createUserSchema, response: userSchema, statusCode: 201 })
+*   async createUser(ctx: RouterContext) { ... }
+* }
+* ```
+*/
+const Post = createHttpMethodDecorator("post");
+/**
+* Registers a PUT route on the controller method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration
+*/
+const Put = createHttpMethodDecorator("put");
+/**
+* Registers a PATCH route on the controller method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration
+*/
+const Patch = createHttpMethodDecorator("patch");
+/**
+* Registers a DELETE route on the controller method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration
+*/
+const Delete = createHttpMethodDecorator("delete");
+/**
+* Registers an ALL (any HTTP method) route on the controller method.
+* Routes using @All are automatically hidden from OpenAPI documentation
+* since OpenAPI does not support a catch-all HTTP method.
+*
+* @param path - Route path relative to the controller base path
+* @param config - Optional route configuration
+*/
+const All = createHttpMethodDecorator("all");
+/**
+* Get the HTTP route metadata from a controller method decorated with
+* @Get, @Post, @Put, @Patch, @Delete, or @All.
+*
+* @param target - Controller prototype
+* @param methodName - Name of the method
+* @returns HTTP route metadata or undefined if not decorated
+*/
+function getHttpRouteMetadata(target, methodName) {
+	return Reflect.getMetadata(ROUTE_METADATA_KEYS.HTTP_ROUTE_CONFIG, target, methodName);
+}
+/**
+* Get all methods decorated with HTTP method decorators from a controller class.
+*
+* @param ControllerClass - Controller class
+* @returns Array of method names that have HTTP route metadata
+*/
+function getHttpDecoratedMethods(ControllerClass) {
+	const prototype = ControllerClass.prototype;
+	return Reflect.getOwnMetadata(ROUTE_METADATA_KEYS.HTTP_DECORATED_METHODS, prototype) ?? [];
+}
+//#endregion
+//#region src/router/decorators/route.decorator.ts
+/**
+* Decorator to add OpenAPI metadata to a controller method using convention-based routing.
+*
+* **Cannot be mixed with HTTP method decorators** (`@Get`, `@Post`, `@Put`, `@Patch`,
+* `@Delete`, `@All`) in the same controller. Use one pattern or the other.
+*
+* Stores route configuration (schemas, response, tags, security) in metadata.
+* HTTP method, path, and success status code are auto-derived from the method name:
+* - index() → GET /base-path → 200
+* - show() → GET /base-path/:id → 200
+* - create() → POST /base-path → 201
+* - update() → PUT /base-path/:id → 200
+* - patch() → PATCH /base-path/:id → 200
+* - destroy() → DELETE /base-path/:id → 200
+*
+* @param config - Route configuration (schemas, response, tags, security)
+*
+* @example
+* ```typescript
+* @Controller('/api/v1/notes', {
+*   tags: ['Notes'],
+*   security: ['bearerAuth']
+* })
+* export class NotesController implements Controller {
+*   @Route({
+*     body: createNoteSchema,
+*     response: noteSchema, // 201 auto-derived from 'create' method
+*     tags: ['Mutations'],
+*     description: 'Create a new note'
+*   })
+*   async create(ctx: RouterContext): Promise<Response> {
+*     // POST /api/v1/notes (auto-derived from method name)
+*     // Body schema: createNoteSchema (auto-validated)
+*     // Response: 201 → noteSchema (status auto-derived)
+*     // Tags: ['Notes', 'Mutations'] (merged with controller)
+*     // Security: ['bearerAuth'] (inherited from controller)
+*     const body = ctx.body()
+*     const note = await this.notesService.create(body)
+*     return ctx.json(note, 201)
+*   }
+*
+*   @Route({
+*     query: paginationSchema,
+*     response: z.array(noteSchema) // 200 auto-derived from 'index' method
+*   })
+*   async index(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes (auto-derived)
+*     // Query params auto-validated
+*     const notes = await this.notesService.list()
+*     return ctx.json(notes)
+*   }
+*
+*   @Route({
+*     params: z.object({ id: z.string().uuid() }),
+*     response: {
+*       schema: noteSchema,
+*       description: 'Note details'
+*     },
+*     security: [] // Override to make public
+*   })
+*   async show(ctx: RouterContext): Promise<Response> {
+*     // GET /api/v1/notes/:id (auto-derived)
+*     // URL params auto-validated
+*     // Response: 200 → noteSchema (status auto-derived)
+*     // Security: [] (public route, override controller security)
+*     const id = ctx.param('id')
+*     const note = await this.notesService.findById(id)
+*     return ctx.json(note)
+*   }
+* }
+* ```
+*/
+function Route(config) {
+	return function(target, propertyKey, descriptor) {
+		Reflect.defineMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, config, target, propertyKey);
+		return descriptor;
+	};
+}
+/**
+* Get the route configuration from a controller method
+*
+* @param target - Controller instance or prototype
+* @param methodName - Name of the method
+* @returns Route configuration or undefined if not decorated
+*/
+function getRouteConfig(target, methodName) {
+	return Reflect.getMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, target, methodName);
+}
+/**
+* Get all methods with @Route() decorator from a controller
+*
+* @param ControllerClass - Controller class
+* @returns Array of method names that have route config
+*/
+function getDecoratedMethods(ControllerClass) {
+	const prototype = ControllerClass.prototype;
+	return Object.getOwnPropertyNames(prototype).filter((name) => name !== "constructor" && typeof prototype[name] === "function").filter((methodName) => Reflect.hasMetadata(ROUTE_METADATA_KEYS.ROUTE_CONFIG, prototype, methodName));
+}
+//#endregion
+//#region src/openapi/services/openapi.service.ts
+let OpenAPIService = class OpenAPIService {
+	routeInfoMap = /* @__PURE__ */ new Map();
+	constructor(configService) {
+		this.configService = configService;
+	}
+	/**
+	* Setup OpenAPI documentation endpoints
+	*/
+	setupEndpoints(app, controllers) {
+		this.buildRouteInfoMap(controllers);
+		const config = this.configService.getEffectiveConfig();
+		app.get(config.jsonPath, (c) => {
+			const requestContainer = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER);
+			const i18n = requestContainer.resolve(I18N_TOKENS.I18nService);
+			const effectiveConfig = requestContainer.resolve(OPENAPI_TOKENS.ConfigService).getEffectiveConfig();
+			const url = new URL(c.req.raw.url);
+			const fullSpec = app.getOpenAPIDocument({
+				openapi: "3.0.0",
+				info: {
+					version: effectiveConfig.info.version,
+					title: effectiveConfig.info.title,
+					description: effectiveConfig.info.description
+				},
+				servers: [{
+					url: `${url.protocol}//${url.host}`,
+					description: i18n.t("common.api.serverDescription")
+				}]
+			});
+			fullSpec.components ??= {};
+			fullSpec.components.securitySchemes = this.getSecuritySchemeDefinitions(i18n);
+			fullSpec.paths = this.filterRoutes(fullSpec.paths, effectiveConfig);
+			if (fullSpec.components.schemas) fullSpec.components.schemas = this.filterSchemas(fullSpec);
+			return c.json(fullSpec);
+		});
+		if (config.ui !== false) {
+			const uiPath = config.ui?.path ?? "/api/docs";
+			const uiRenderer = config.ui?.renderer;
+			app.get(uiPath, (c, next) => {
+				const effectiveConfig = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER).resolve(OPENAPI_TOKENS.ConfigService).getEffectiveConfig();
+				const uiContext = {
+					specUrl: effectiveConfig.jsonPath,
+					title: effectiveConfig.info.title
+				};
+				if (uiRenderer) return uiRenderer(uiContext)(c, next);
+				return swaggerUI({ url: uiContext.specUrl })(c, next);
+			});
+		}
+	}
+	/**
+	* Get localized security scheme definitions
+	*/
+	getSecuritySchemeDefinitions(i18n) {
+		return {
+			[SECURITY_SCHEMES.BEARER_AUTH]: {
+				type: "http",
+				scheme: "bearer",
+				bearerFormat: "JWT",
+				description: i18n.t("common.api.security.bearerAuth")
+			},
+			[SECURITY_SCHEMES.API_KEY]: {
+				type: "apiKey",
+				in: "header",
+				name: "X-API-Key",
+				description: i18n.t("common.api.security.apiKey")
+			},
+			[SECURITY_SCHEMES.SESSION_COOKIE]: {
+				type: "apiKey",
+				in: "cookie",
+				name: "session",
+				description: i18n.t("common.api.security.sessionCookie")
+			}
+		};
+	}
+	/**
+	* Build route info map from controllers
+	* Maps route prefixes to their hideFromDocs flag
+	*/
+	buildRouteInfoMap(controllers) {
+		for (const ControllerClass of controllers) {
+			const route = getControllerRoute(ControllerClass);
+			const options = getControllerOptions(ControllerClass);
+			if (route) this.routeInfoMap.set(route, { hideFromDocs: options?.hideFromDocs ?? false });
+		}
+	}
+	/**
+	* Filter OpenAPI paths based on hideFromDocs and custom routeFilter
+	*/
+	filterRoutes(paths, config) {
+		const filteredPaths = {};
+		for (const [path, pathItem] of Object.entries(paths)) {
+			if (this.getRouteInfo(path).hideFromDocs) continue;
+			if (config.routeFilter) {
+				if (!config.routeFilter(path, pathItem)) continue;
+			}
+			filteredPaths[path] = pathItem;
+		}
+		return filteredPaths;
+	}
+	/**
+	* Get route info by matching path against controller routes
+	*/
+	getRouteInfo(path) {
+		for (const [route, info] of this.routeInfoMap.entries()) if (path === route || path.startsWith(`${route}/`)) return info;
+		return { hideFromDocs: false };
+	}
+	/**
+	* Filter unreferenced schemas from OpenAPI spec
+	*/
+	filterSchemas(spec) {
+		const referencedSchemas = /* @__PURE__ */ new Set();
+		this.collectSchemaRefs(spec.paths, referencedSchemas);
+		const filteredSchemas = {};
+		const components = spec.components;
+		if (components?.schemas) {
+			for (const [schemaName, schemaValue] of Object.entries(components.schemas)) if (referencedSchemas.has(schemaName)) {
+				filteredSchemas[schemaName] = schemaValue;
+				this.collectSchemaRefs(schemaValue, referencedSchemas);
+			}
+			for (const [schemaName, schemaValue] of Object.entries(components.schemas)) if (referencedSchemas.has(schemaName) && !filteredSchemas[schemaName]) filteredSchemas[schemaName] = schemaValue;
+		}
+		return filteredSchemas;
+	}
+	/**
+	* Recursively collect all schema references from an object
+	*/
+	collectSchemaRefs(obj, refs) {
+		if (!obj || typeof obj !== "object") return;
+		const record = obj;
+		if (record.$ref && typeof record.$ref === "string") {
+			const match = /^#\/components\/schemas\/(.+)$/.exec(record.$ref);
+			if (match) refs.add(match[1]);
+		}
+		if (Array.isArray(obj)) for (const item of obj) this.collectSchemaRefs(item, refs);
+		else for (const value of Object.values(record)) this.collectSchemaRefs(value, refs);
+	}
+};
+OpenAPIService = __decorate([
+	Transient(OPENAPI_TOKENS.OpenAPIService),
+	__decorateParam(0, inject(OPENAPI_TOKENS.ConfigService)),
+	__decorateMetadata("design:paramtypes", [Object])
+], OpenAPIService);
+//#endregion
+//#region src/openapi/openapi.module.ts
+/**
+* OpenAPI Module
+*
+* Provides configurable OpenAPI documentation endpoints with runtime override support.
+*
+* Features:
+* - Configurable paths for /openapi.json and /docs
+* - Runtime config overrides via middleware
+* - i18n support for titles and descriptions
+* - Route filtering via hideFromDocs and custom routeFilter
+*
+* @example Basic usage
+* ```typescript
+* @Module({
+*   imports: [
+*     OpenAPIModule.forRoot({
+*       info: { title: 'My API', version: '1.0.0' }
+*     })
+*   ]
+* })
+* export class AppModule {}
+* ```
+*
+* @example With runtime override in middleware
+* ```typescript
+* // In RouteAccessMiddleware
+* constructor(
+*   @inject(OPENAPI_TOKENS.ConfigService) private openAPIConfig: IOpenAPIConfigService
+* ) {}
+*
+* async handle(ctx, next) {
+*   this.openAPIConfig.override({
+*     info: { title: 'Custom API' },
+*     routeFilter: (path) => this.shouldInclude(path)
+*   })
+*   await next()
+* }
+* ```
+*/
+var _OpenAPIModule;
+/** Default options when none provided */
+const DEFAULT_OPTIONS = {
+	jsonPath: "/api/openapi.json",
+	info: {
+		title: "API",
+		version: "1.0.0"
+	}
+};
+let OpenAPIModule = _OpenAPIModule = class OpenAPIModule {
+	/**
+	* Configure OpenAPI module with static options
+	*
+	* @param options - OpenAPI configuration (paths, info, security schemes)
+	* @returns DynamicModule with options provider
+	*/
+	static forRoot(options = {}) {
+		const mergedOptions = {
+			...DEFAULT_OPTIONS,
+			...options,
+			info: {
+				...DEFAULT_OPTIONS.info,
+				...options.info,
+				title: options.info?.title ?? DEFAULT_OPTIONS.info?.title ?? "API",
+				version: options.info?.version ?? DEFAULT_OPTIONS.info?.version ?? "1.0.0"
+			}
+		};
+		return {
+			module: _OpenAPIModule,
+			providers: [{
+				provide: OPENAPI_TOKENS.Options,
+				useValue: mergedOptions
+			}]
+		};
+	}
+	static forRootAsync(options) {
+		return {
+			module: _OpenAPIModule,
+			providers: [{
+				provide: OPENAPI_TOKENS.Options,
+				useFactory: options.useFactory,
+				inject: options.inject
+			}]
+		};
+	}
+};
+OpenAPIModule = _OpenAPIModule = __decorate([Module({ providers: [{
+	provide: OPENAPI_TOKENS.ConfigService,
+	useClass: OpenAPIConfigService,
+	scope: Scope.Request
+}, {
+	provide: OPENAPI_TOKENS.OpenAPIService,
+	useClass: OpenAPIService
+}] })], OpenAPIModule);
+//#endregion
+//#region src/router/errors/controller-method-not-found.error.ts
+/**
+* ControllerMethodNotFoundError
+*
+* Thrown when a controller method is registered but doesn't exist on the controller instance.
+* This typically indicates a mismatch between route registration and controller implementation.
+*/
+var ControllerMethodNotFoundError = class extends ApplicationError {
+	constructor(methodName, controllerName) {
+		super("errors.controllerMethodNotFound", ERROR_CODES.ROUTER.CONTROLLER_METHOD_NOT_FOUND, {
+			methodName,
+			controllerName
+		});
+	}
+};
+//#endregion
+//#region src/router/errors/hono-app-already-configured.error.ts
+/**
+* Error thrown when HonoApp.configure() is called more than once.
+*
+* HonoApp can only be configured a single time during application bootstrap.
+*/
+var HonoAppAlreadyConfiguredError = class extends ApplicationError {
+	constructor() {
+		super("errors.honoAppAlreadyConfigured", ERROR_CODES.SYSTEM.CONFIGURATION_ERROR);
+	}
+};
+//#endregion
+//#region src/router/errors/controller-registration.error.ts
+/**
+* Error thrown when a controller fails to register
+*
+* This typically happens when:
+* - Controller is missing the `@Controller` decorator
+* - Controller route metadata is not set
+* - Controller class name is invalid
+*
+* Error Code: 9005
+*/
+var ControllerRegistrationError = class extends ApplicationError {
+	constructor(controllerName, reason) {
+		super("errors.controllerRegistration", ERROR_CODES.ROUTER.CONTROLLER_REGISTRATION_ERROR, {
+			controllerName,
+			reason
+		});
+	}
+};
+//#endregion
+//#region src/router/errors/openapi-route-registration.error.ts
+/**
+* OpenAPIRouteRegistrationError
+*
+* Thrown when an OpenAPI route fails to register properly
+* This indicates a configuration issue with route decorators or metadata
+* Uses i18n key for localized error messages
+*
+* @example
+* ```typescript
+* throw new OpenAPIRouteRegistrationError('/api/v1/users', 'Missing response schema')
+* ```
+*/
+var OpenAPIRouteRegistrationError = class extends ApplicationError {
+	constructor(path, reason) {
+		super("errors.openapiRouteRegistration", ERROR_CODES.ROUTER.OPENAPI_ROUTE_REGISTRATION, {
+			path,
+			reason
+		});
+	}
+};
+//#endregion
+//#region src/router/errors/openapi-validation.error.ts
+/**
+* OpenAPIValidationError
+*
+* Thrown when OpenAPI request/response validation fails
+* Uses i18n key for localized error messages
+*
+* HTTP Status: 400 Bad Request
+* Error Code: 1004
+*
+* @example
+* ```typescript
+* throw new OpenAPIValidationError('Request body missing required field: email')
+* ```
+*/
+var OpenAPIValidationError = class extends ApplicationError {
+	constructor(details) {
+		super("errors.openapiValidation", ERROR_CODES.VALIDATION.REQUEST_VALIDATION, { details });
+	}
+};
+//#endregion
+//#region src/router/errors/route-not-found.error.ts
+/**
+* Error thrown when a requested route is not found
+*
+* HTTP Status: 404 Not Found
+* Error Code: 4004
+*/
+var RouteNotFoundError = class extends ApplicationError {
+	constructor(path, method) {
+		super("errors.routeNotFound", ERROR_CODES.RESOURCE.ROUTE_NOT_FOUND, {
+			path,
+			method
+		});
+	}
+};
+//#endregion
+//#region src/router/errors/schema-validation.error.ts
+/**
+* SchemaValidationError
+*
+* Thrown when Zod schema validation fails
+*/
+var SchemaValidationError = class extends ApplicationError {
+	constructor(zodError) {
+		const issues = zodError.issues.map((err) => ({
+			path: err.path.join("."),
+			message: err.message,
+			code: err.code
+		}));
+		super("errors.schemaValidation", ERROR_CODES.VALIDATION.SCHEMA_VALIDATION, { issues });
+	}
+};
+//#endregion
+//#region src/router/middleware/logger.middleware.ts
+/**
+* Create a Hono middleware that logs HTTP requests using our Logger service
+*
+* Logs request method, path, status code, and duration in milliseconds.
+* Format: [HTTP] METHOD /path -> STATUS (duration ms)
+*
+* @param logger - Logger service instance
+* @returns Hono middleware handler
+*
+* @example
+* ```typescript
+* const logger = container.resolve<LoggerService>(LOGGER_TOKENS.LoggerService)
+* app.use('*', createLoggerMiddleware(logger))
+* ```
+*/
+function createLoggerMiddleware(logger) {
+	return async (c, next) => {
+		const start = Date.now();
+		const method = c.req.method;
+		const path = c.req.path;
+		await next();
+		const duration = Date.now() - start;
+		const status = c.res.status;
+		logger.info(`[HTTP] ${method} ${path} -> ${status}`, {
+			method,
+			path,
+			status,
+			duration
+		});
+	};
+}
+//#endregion
+//#region src/router/schemas/common.schemas.ts
+/**
+* Common OpenAPI Schemas
+*
+* Reusable schema definitions for common API patterns:
+* - Error responses
+* - Pagination
+* - Common parameters
+*/
+/**
+* Generic error response schema
+* Used for all error responses (4xx, 5xx)
+* Matches ApplicationError.toErrorResponse() structure
+*/
+const errorResponseSchema = z.object({
+	code: z.number().int().describe("Application error code"),
+	message: z.string().describe("Human-readable error message"),
+	timestamp: z.string().datetime().describe("ISO timestamp when error occurred"),
+	metadata: z.record(z.string(), z.unknown()).optional().describe("Additional error context"),
+	stack: z.string().optional().describe("Stack trace (development only)")
+}).openapi("ErrorResponse");
+/**
+* Validation error response schema
+* Used for 400 Bad Request with validation failures
+* Matches ApplicationError.toErrorResponse() structure with validation-specific metadata
+*/
+const validationErrorResponseSchema = z.object({
+	code: z.number().int().describe("Application error code"),
+	message: z.string().describe("Human-readable error message"),
+	timestamp: z.string().datetime().describe("ISO timestamp when error occurred"),
+	metadata: z.object({ issues: z.array(z.object({
+		path: z.string().describe("Field path that failed validation"),
+		message: z.string().describe("Validation failure message"),
+		code: z.string().describe("Zod validation error code")
+	})) }).describe("Validation error details"),
+	stack: z.string().optional().describe("Stack trace (development only)")
+}).openapi("ValidationErrorResponse");
+/**
+* Pagination query parameters schema
+* Used for list endpoints
+*/
+const paginationQuerySchema = z.object({
+	page: z.coerce.number().int().positive().default(1).describe("Page number (1-indexed)"),
+	limit: z.coerce.number().int().positive().max(100).default(20).describe("Items per page (max 100)")
+}).openapi("PaginationQuery");
+/**
+* Paginated response wrapper schema
+* Generic wrapper for paginated list responses
+*/
+const paginatedResponseSchema = (itemSchema) => z.object({
+	data: z.array(itemSchema).describe("Array of items for current page"),
+	pagination: z.object({
+		page: z.number().int().positive().describe("Current page number"),
+		limit: z.number().int().positive().describe("Items per page"),
+		total: z.number().int().nonnegative().describe("Total number of items"),
+		totalPages: z.number().int().nonnegative().describe("Total number of pages")
+	})
+});
+/**
+* UUID parameter schema
+* Used for :id parameters in RESTful routes
+*/
+const uuidParamSchema = z.object({ id: z.string().uuid().describe("Resource UUID") }).openapi("UUIDParam");
+/**
+* Success message response schema
+* Used for operations that don't return data (e.g., DELETE)
+*/
+const successMessageSchema = z.object({
+	message: z.string().describe("Success message"),
+	data: z.record(z.string(), z.unknown()).optional().describe("Optional additional data")
+}).openapi("SuccessMessage");
+/**
+* Common HTTP status error schemas
+* Pre-configured for standard error responses
+*/
+const commonErrorSchemas = {
+	400: {
+		schema: validationErrorResponseSchema,
+		description: "Validation error"
+	},
+	401: {
+		schema: errorResponseSchema,
+		description: "Unauthorized"
+	},
+	403: {
+		schema: errorResponseSchema,
+		description: "Forbidden"
+	},
+	404: {
+		schema: errorResponseSchema,
+		description: "Not found"
+	},
+	409: {
+		schema: errorResponseSchema,
+		description: "Conflict"
+	},
+	500: {
+		schema: errorResponseSchema,
+		description: "Internal server error"
+	}
+};
+//#endregion
+//#region src/router/services/route-registration.service.ts
+const invokeHandler = (instance, method, ...args) => {
+	try {
+		return Promise.resolve(instance[method](...args));
+	} catch (err) {
+		return Promise.reject(err);
+	}
+};
+/**
+* Route registration service
+* Manages controller and route registration with OpenAPI support
+*
+* Responsibilities:
+* - Register RESTful controllers with OpenAPI metadata
+* - Auto-derive HTTP methods/paths from controller method names
+* - Build OpenAPI route configurations with guard execution
+* - Validate all controllers have access decorators (strict mode)
+* - Create controller handlers with DI resolution
+*/
+var RouteRegistrationService = class {
+	controllerClasses = /* @__PURE__ */ new Map();
+	constructor(logger, versioningOptions = null) {
+		this.logger = logger;
+		this.versioningOptions = versioningOptions;
+	}
+	/**
+	* Configure router with controllers
+	*
+	* @param app - OpenAPIHono application instance
+	* @param controllers - Array of controller classes from modules
+	*/
+	async configure(app, controllers) {
+		this.logger.info("Registering controllers", { controllerCount: controllers.length });
+		const sortedControllers = [...controllers].sort((a, b) => {
+			const aHasHandle = "handle" in a.prototype;
+			const bHasHandle = "handle" in b.prototype;
+			if (aHasHandle && !bHasHandle) return 1;
+			if (!aHasHandle && bHasHandle) return -1;
+			return 0;
+		});
+		const gateways = [];
+		const regulars = [];
+		for (const c of sortedControllers) if (isGateway(c)) gateways.push(c);
+		else regulars.push(c);
+		for (const GatewayClass of gateways) await this.registerGateway(app, GatewayClass);
+		for (const ControllerClass of regulars) this.registerController(app, ControllerClass);
+		this.logger.info("Controller registration complete");
+	}
+	/**
+	* Register a WebSocket gateway
+	* Applies versioning and guards, then registers an upgradeWebSocket handler
+	*/
+	async registerGateway(app, GatewayClass) {
+		const route = getControllerRoute(GatewayClass);
+		if (!route) throw new ControllerRegistrationError(GatewayClass.name, "Missing @Gateway decorator or route metadata");
+		const controllerOpts = getControllerOptions(GatewayClass);
+		const paths = this.versioningOptions ? this.resolveVersionedPaths(route, controllerOpts) : [route];
+		for (const fullPath of paths) await this.registerGatewayRoute(app, GatewayClass, fullPath);
+	}
+	/**
+	* Register a single WebSocket gateway route
+	*/
+	async registerGatewayRoute(app, GatewayClass, fullPath) {
+		const controllerGuards = getControllerGuards(GatewayClass)?.guards ?? [];
+		const { upgradeWebSocket } = await import("hono/cloudflare-workers");
+		const onMsgMethod = getWsOnMessageMethod(GatewayClass);
+		const onCloseMethod = getWsOnCloseMethod(GatewayClass);
+		const onErrMethod = getWsOnErrorMethod(GatewayClass);
+		const wsHandler = upgradeWebSocket((c) => {
+			const gateway = new RouterContext(c).getContainer().resolve(GatewayClass);
+			const events = {};
+			const bindWsHandler = (method, onCatch) => {
+				return (evt, ws) => {
+					const ctx = new GatewayContext(c, ws);
+					c.executionCtx.waitUntil(invokeHandler(gateway, method, evt, ctx).catch((err) => {
+						this.logger.error(`WebSocket ${method} handler error`, {
+							gateway: GatewayClass.name,
+							error: err instanceof Error ? err.message : String(err)
+						});
+						onCatch?.(err, ws);
+					}));
+				};
+			};
+			if (onMsgMethod) events.onMessage = bindWsHandler(onMsgMethod, (_err, ws) => ws.close(1011, "Internal Error"));
+			if (onCloseMethod) events.onClose = bindWsHandler(onCloseMethod);
+			if (onErrMethod) events.onError = bindWsHandler(onErrMethod);
+			return events;
+		});
+		this.logger.info("Registering WebSocket gateway", {
+			gateway: GatewayClass.name,
+			path: fullPath
+		});
+		const handlers = [];
+		if (controllerGuards.length > 0) {
+			this.logger.info("Gateway guards", {
+				gateway: GatewayClass.name,
+				path: fullPath,
+				guardCount: controllerGuards.length
+			});
+			handlers.push(this.createGuardMiddleware(controllerGuards));
+		}
+		handlers.push(wsHandler);
+		app.get(fullPath, ...handlers);
+	}
+	/**
+	* Register a single controller with all its routes
+	* Validates that controller has access decorator (strict mode)
+	*/
+	registerController(app, ControllerClass) {
+		const route = getControllerRoute(ControllerClass);
+		if (!route) throw new ControllerRegistrationError(ControllerClass.name, "Missing @Controller decorator or route metadata");
+		const className = ControllerClass.name;
+		this.controllerClasses.set(className, ControllerClass);
+		const prototype = ControllerClass.prototype;
+		const controllerOpts = getControllerOptions(ControllerClass);
+		if (prototype.handle) {
+			if (!this.versioningOptions) this.registerWildcardRoute(app, ControllerClass, route);
+			else for (const versionedRoute of this.resolveVersionedPaths(route, controllerOpts)) this.registerWildcardRoute(app, ControllerClass, versionedRoute);
+			return;
+		}
+		const decoratedMethods = getDecoratedMethods(ControllerClass);
+		const httpDecoratedMethods = getHttpDecoratedMethods(ControllerClass);
+		if (decoratedMethods.length > 0 && httpDecoratedMethods.length > 0) throw new ControllerRegistrationError(ControllerClass.name, "Cannot mix @Route() with HTTP method decorators (@Get, @Post, etc.) in the same controller. Use one pattern or the other.");
+		if (!this.versioningOptions) {
+			this.dispatchRoutes(app, ControllerClass, route, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype);
+			return;
+		}
+		for (const versionedRoute of this.resolveVersionedPaths(route, controllerOpts)) this.dispatchRoutes(app, ControllerClass, versionedRoute, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype);
+	}
+	/**
+	* Dispatch route registration based on decorator type
+	*/
+	dispatchRoutes(app, ControllerClass, path, decoratedMethods, httpDecoratedMethods, controllerOpts, prototype) {
+		if (httpDecoratedMethods.length > 0) this.registerHttpRoutes(app, ControllerClass, path, httpDecoratedMethods, controllerOpts);
+		else if (decoratedMethods.length > 0) this.registerOpenAPIRoutes(app, ControllerClass, path, decoratedMethods, controllerOpts);
+		else this.registerRESTfulRoutes(app, ControllerClass, path, prototype);
+	}
+	/**
+	* Resolve versioned paths for a controller based on versioning configuration.
+	*
+	* @param basePath - The base path from @Controller decorator
+	* @param controllerOpts - Controller options (may contain version)
+	* @returns Array of resolved paths (with version prefix if applicable)
+	*/
+	resolveVersionedPaths(basePath, controllerOpts) {
+		if (!this.versioningOptions) return [basePath];
+		const version = controllerOpts?.version;
+		if (version === VERSION_NEUTRAL) return [basePath];
+		const prefix = this.versioningOptions.prefix ?? "v";
+		if (version !== void 0) return (Array.isArray(version) ? version : [version]).map((v) => `/${prefix}${v}${basePath}`);
+		if (this.versioningOptions.defaultVersion !== void 0) return (Array.isArray(this.versioningOptions.defaultVersion) ? this.versioningOptions.defaultVersion : [this.versioningOptions.defaultVersion]).map((v) => `/${prefix}${v}${basePath}`);
+		return [basePath];
+	}
+	/**
+	* Create a guard execution middleware
+	*
+	* This middleware executes all guards for a route before the handler.
+	* Guards are executed in order; all must pass for the request to proceed.
+	*
+	* @param guards - Array of guards to execute
+	* @returns Hono middleware function
+	*/
+	createGuardMiddleware(guards) {
+		const guardService = new GuardExecutionService(this.logger);
+		return async (c, next) => {
+			const ctx = new RouterContext(c);
+			const container = ctx.getContainer();
+			await guardService.executeGuards(guards, ctx, container);
+			await next();
+		};
+	}
+	/**
+	* Register wildcard route for non-RESTful controllers
+	*/
+	registerWildcardRoute(app, ControllerClass, route) {
+		this.logger.info(`Registering wildcard route`, {
+			controller: ControllerClass.name,
+			route: `${route}/:path{.+}`,
+			method: "ALL"
+		});
+		const handler = this.createControllerHandler(ControllerClass, "handle");
+		app.all(route, handler);
+		app.all(`${route}/:path{.+}`, handler);
+	}
+	/**
+	* Register OpenAPI routes with metadata
+	*/
+	registerOpenAPIRoutes(app, ControllerClass, route, decoratedMethods, controllerOpts) {
+		const className = ControllerClass.name;
+		const prototype = ControllerClass.prototype;
+		const controllerHidden = controllerOpts?.hideFromDocs ?? false;
+		const controllerGuards = getControllerGuards(ControllerClass)?.guards ?? [];
+		for (const methodName of decoratedMethods) {
+			const routeConfig = getRouteConfig(prototype, methodName);
+			if (!routeConfig) continue;
+			const derived = this.deriveHttpMethodAndPath(methodName, route);
+			if (!derived) {
+				this.logger.warn(`Cannot derive HTTP method/path for ${className}.${methodName}`);
+				continue;
+			}
+			if (routeConfig.hideFromDocs ?? controllerHidden) {
+				this.logger.info(`Registering hidden route (no OpenAPI)`, {
+					controller: className,
+					method: derived.method.toUpperCase(),
+					path: derived.path,
+					methodName
+				});
+				this.registerRouteWithoutOpenAPI(app, ControllerClass, methodName, derived);
+				continue;
+			}
+			const methodGuards = getMethodGuards(prototype, methodName)?.guards ?? [];
+			const allGuards = [...controllerGuards, ...methodGuards];
+			if (allGuards.length > 0) this.logger.info(`Route guards`, {
+				controller: className,
+				method: derived.method.toUpperCase(),
+				path: derived.path,
+				methodName,
+				guardCount: allGuards.length
+			});
+			const metadata = this.mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName);
+			const openApiRoute = this.buildOpenAPIRoute(derived.method, derived.path, routeConfig, metadata, allGuards, methodName);
+			this.logger.info(`Registering OpenAPI route`, {
+				controller: className,
+				method: derived.method.toUpperCase(),
+				path: derived.path,
+				methodName,
+				tags: metadata.tags
+			});
+			app.openapi(openApiRoute, async (c) => {
+				const ctx = new RouterContext(c);
+				const requestContainer = ctx.getContainer();
+				const controller = requestContainer.resolve(ControllerClass);
+				const method = controller[methodName];
+				if (typeof method === "function") {
+					const injectedArgs = this.resolveMethodInjections(prototype, methodName, requestContainer);
+					return await method.call(controller, ctx, ...injectedArgs);
+				}
+				throw new ControllerMethodNotFoundError(methodName, className);
+			});
+		}
+	}
+	/**
+	* Register routes using HTTP method decorators (@Get, @Post, etc.)
+	* These use explicit method + path instead of convention-based derivation
+	*/
+	registerHttpRoutes(app, ControllerClass, basePath, httpDecoratedMethods, controllerOpts) {
+		const className = ControllerClass.name;
+		const prototype = ControllerClass.prototype;
+		const controllerHidden = controllerOpts?.hideFromDocs ?? false;
+		const controllerGuards = getControllerGuards(ControllerClass)?.guards ?? [];
+		for (const methodName of httpDecoratedMethods) {
+			const httpMeta = getHttpRouteMetadata(prototype, methodName);
+			if (!httpMeta) continue;
+			const fullPath = this.joinPaths(basePath, httpMeta.path);
+			const routeConfig = httpMeta.config;
+			const hideFromDocs = routeConfig.hideFromDocs ?? controllerHidden;
+			if (httpMeta.method === "all" || hideFromDocs) {
+				this.logger.info(`Registering route (no OpenAPI)`, {
+					controller: className,
+					method: httpMeta.method.toUpperCase(),
+					path: fullPath,
+					methodName
+				});
+				this.registerRouteWithoutOpenAPI(app, ControllerClass, methodName, {
+					method: httpMeta.method,
+					path: fullPath
+				});
+				continue;
+			}
+			const methodGuards = getMethodGuards(prototype, methodName)?.guards ?? [];
+			const allGuards = [...controllerGuards, ...methodGuards];
+			if (allGuards.length > 0) this.logger.info(`Route guards`, {
+				controller: className,
+				method: httpMeta.method.toUpperCase(),
+				path: fullPath,
+				methodName,
+				guardCount: allGuards.length
+			});
+			const metadata = this.mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName);
+			const statusCode = routeConfig.statusCode ?? 200;
+			const openApiRoute = this.buildOpenAPIRoute(httpMeta.method, fullPath, routeConfig, metadata, allGuards, void 0, statusCode);
+			this.logger.info(`Registering OpenAPI route`, {
+				controller: className,
+				method: httpMeta.method.toUpperCase(),
+				path: fullPath,
+				methodName,
+				tags: metadata.tags
+			});
+			app.openapi(openApiRoute, async (c) => {
+				const ctx = new RouterContext(c);
+				const requestContainer = ctx.getContainer();
+				const controller = requestContainer.resolve(ControllerClass);
+				const method = controller[methodName];
+				if (typeof method === "function") {
+					const injectedArgs = this.resolveMethodInjections(prototype, methodName, requestContainer);
+					return await method.call(controller, ctx, ...injectedArgs);
+				}
+				throw new ControllerMethodNotFoundError(methodName, className);
+			});
+		}
+	}
+	/**
+	* Join a base path and a route path, normalizing slashes
+	*/
+	joinPaths(basePath, routePath) {
+		if (routePath === "/") return basePath;
+		return basePath + routePath;
+	}
+	/**
+	* Register route without OpenAPI metadata (for hidden routes)
+	* Route is functional but won't appear in documentation
+	*/
+	registerRouteWithoutOpenAPI(app, ControllerClass, methodName, derived) {
+		const prototype = ControllerClass.prototype;
+		const handler = async (c) => {
+			const ctx = new RouterContext(c);
+			const requestContainer = ctx.getContainer();
+			const controller = requestContainer.resolve(ControllerClass);
+			const method = controller[methodName];
+			if (typeof method === "function") {
+				const injectedArgs = this.resolveMethodInjections(prototype, methodName, requestContainer);
+				return await method.call(controller, ctx, ...injectedArgs);
+			}
+			throw new ControllerMethodNotFoundError(methodName, ControllerClass.name);
+		};
+		switch (derived.method) {
+			case "get":
+				app.get(derived.path, handler);
+				break;
+			case "post":
+				app.post(derived.path, handler);
+				break;
+			case "put":
+				app.put(derived.path, handler);
+				break;
+			case "patch":
+				app.patch(derived.path, handler);
+				break;
+			case "delete":
+				app.delete(derived.path, handler);
+				break;
+			case "all":
+				app.all(derived.path, handler);
+				break;
+			default:
+				app.all(derived.path, handler);
+				break;
+		}
+	}
+	/**
+	* Register traditional RESTful routes without OpenAPI
+	*/
+	registerRESTfulRoutes(app, ControllerClass, route, prototype) {
+		if (prototype.index) app.get(route, this.createControllerHandler(ControllerClass, "index"));
+		if (prototype.show) app.get(`${route}/:id`, this.createControllerHandler(ControllerClass, "show"));
+		if (prototype.create) app.post(route, this.createControllerHandler(ControllerClass, "create"));
+		if (prototype.update) app.put(`${route}/:id`, this.createControllerHandler(ControllerClass, "update"));
+		if (prototype.patch) app.patch(`${route}/:id`, this.createControllerHandler(ControllerClass, "patch"));
+		if (prototype.destroy) app.delete(`${route}/:id`, this.createControllerHandler(ControllerClass, "destroy"));
+	}
+	/**
+	* Auto-derive HTTP method and path from controller method name
+	* Uses HTTP_METHODS constant for RESTful convention mapping
+	*/
+	deriveHttpMethodAndPath(methodName, basePath) {
+		if (!(methodName in HTTP_METHODS)) return null;
+		const mapping = HTTP_METHODS[methodName];
+		return {
+			method: mapping.method,
+			path: basePath + mapping.path
+		};
+	}
+	/**
+	* Merge controller-level and route-level metadata
+	* Tags are merged (appended), security is merged (union)
+	* Guards automatically add sessionCookie security if present
+	*/
+	mergeMetadata(controllerOpts, routeConfig, ControllerClass, methodName) {
+		const tags = [...controllerOpts?.tags ?? [], ...routeConfig.tags ?? []];
+		const prototype = ControllerClass.prototype;
+		const hasMethodGuards = (getMethodGuards(prototype, methodName)?.guards.length ?? 0) > 0;
+		const hasControllerGuards = (getControllerGuards(ControllerClass)?.guards.length ?? 0) > 0;
+		const requiresAuth = hasMethodGuards || hasControllerGuards;
+		let security = [];
+		if (routeConfig.security !== void 0) security = [...controllerOpts?.security ?? [], ...routeConfig.security];
+		else if (controllerOpts?.security) security = controllerOpts.security;
+		if (requiresAuth && !security.includes(SECURITY_SCHEMES.SESSION_COOKIE)) security.push(SECURITY_SCHEMES.SESSION_COOKIE);
+		return {
+			tags,
+			security: security.length > 0 ? security.map((scheme) => ({ [scheme]: [] })) : []
+		};
+	}
+	/**
+	* Build OpenAPI route configuration from metadata
+	* Creates a route definition compatible with @hono/zod-openapi
+	* Includes guard execution for proper access control
+	*
+	* Execution order: Global middlewares → Guards → Handler
+	*/
+	buildOpenAPIRoute(method, path, routeConfig, metadata, guards, methodName, statusCodeOverride) {
+		try {
+			const route = {
+				method,
+				path,
+				request: {},
+				responses: {}
+			};
+			if (guards.length > 0) route.middleware = [this.createGuardMiddleware(guards)];
+			if (routeConfig.body) {
+				const bodySchema = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.schema : routeConfig.body;
+				const bodyContentType = this.isRouteBodyObject(routeConfig.body) ? routeConfig.body.contentType ?? "application/json" : DEFAULT_CONTENT_TYPE;
+				route.request = {
+					...route.request,
+					body: { content: { [bodyContentType]: { schema: bodySchema } } }
+				};
+			}
+			if (routeConfig.query) route.request = {
+				...route.request,
+				query: routeConfig.query
+			};
+			if (routeConfig.params) route.request = {
+				...route.request,
+				params: routeConfig.params
+			};
+			const successStatus = statusCodeOverride ?? (methodName && METHOD_STATUS_CODES[methodName]) ?? 200;
+			const responses = {};
+			const responseDef = routeConfig.response;
+			if (responseDef) if (typeof responseDef === "object" && "schema" in responseDef) responses[successStatus] = {
+				content: { [responseDef.contentType ?? "application/json"]: { schema: responseDef.schema } },
+				description: responseDef.description ?? `Response ${successStatus}`
+			};
+			else responses[successStatus] = {
+				content: { [DEFAULT_CONTENT_TYPE]: { schema: responseDef } },
+				description: `Response ${successStatus}`
+			};
+			for (const [statusStr, schema] of Object.entries(commonErrorSchemas)) {
+				const status = parseInt(statusStr);
+				responses[status] ??= schema;
+			}
+			route.responses = responses;
+			if (metadata.tags.length > 0) route.tags = metadata.tags;
+			if (metadata.security.length > 0) route.security = metadata.security;
+			if (routeConfig.description) route.description = routeConfig.description;
+			if (routeConfig.summary) route.summary = routeConfig.summary;
+			return (0, validation_exports.createRoute)(route);
+		} catch (error) {
+			throw new OpenAPIRouteRegistrationError(path, error instanceof Error ? error.message : String(error));
+		}
+	}
+	/**
+	* Check if a body definition is a RouteBodyObject (has schema key) vs bare ZodType
+	*/
+	isRouteBodyObject(body) {
+		return typeof body === "object" && "schema" in body;
+	}
+	/**
+	* Resolve method parameter injections from the container
+	*
+	* @param prototype - Controller prototype
+	* @param methodName - Method name to get injections for
+	* @param container - Request-scoped container
+	* @returns Array of resolved dependencies in parameter order
+	*/
+	resolveMethodInjections(prototype, methodName, container) {
+		const injections = getMethodInjections(prototype, methodName);
+		if (!injections.length) return [];
+		return injections.map((inj) => container.resolve(inj.token));
+	}
+	/**
+	* Create controller handler that resolves controller from request-scoped container
+	* This ensures each request gets a fresh controller with request-scoped context
+	*/
+	createControllerHandler(ControllerClass, methodName) {
+		return async (c) => {
+			this.logger.info("Handler invoked", {
+				path: c.req.path,
+				method: c.req.method,
+				controller: ControllerClass.name,
+				methodName
+			});
+			try {
+				const ctx = new RouterContext(c);
+				const requestContainer = ctx.getContainer();
+				const controller = requestContainer.resolve(ControllerClass);
+				const method = controller[methodName];
+				if (typeof method === "function") {
+					const injectedArgs = this.resolveMethodInjections(ControllerClass.prototype, methodName, requestContainer);
+					return await method.apply(controller, [ctx, ...injectedArgs]);
+				}
+				throw new ControllerMethodNotFoundError(methodName, ControllerClass.name);
+			} catch (error) {
+				this.logger.error("Error in controller handler", {
+					controller: ControllerClass.name,
+					methodName,
+					error: error instanceof Error ? error.message : String(error),
+					stack: error instanceof Error ? error.stack : void 0
+				});
+				throw error;
+			}
+		};
+	}
+};
+//#endregion
+//#region src/router/hono-app.ts
+const isMiddlewareClass = (arg) => typeof arg === "function" && arg.prototype && "handle" in arg.prototype;
+/**
+* HonoApp — extends OpenAPIHono with Stratal-specific setup
+*
+* Absorbs all Hono-related setup from the former RouterService and RequestScopeService:
+* - Request scope middleware (child container per request)
+* - Global middleware (CORS, logging, error handling)
+* - defaultHook for validation errors
+* - `use()` overload for Stratal middleware classes
+* - `configure()` for module middleware, OpenAPI, routes, and 404
+*/
+var HonoApp = class extends OpenAPIHono {
+	configured = false;
+	_container;
+	_logger;
+	/**
+	* Reference to the original Hono `use` implementation.
+	* Captured in constructor after super() sets it as an instance property.
+	* Used by private methods to register middleware without going through the override.
+	*/
+	nativeUse;
+	constructor(container, logger) {
+		super({ defaultHook: (result, c) => {
+			if (!result.success) {
+				const errorHandler = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER).resolve(DI_TOKENS.ErrorHandler);
+				const validationError = new SchemaValidationError(result.error);
+				const errorResponse = errorHandler.handle(validationError);
+				return c.json(errorResponse, getHttpStatus(errorResponse.code));
+			}
+		} });
+		this._container = container;
+		this._logger = logger;
+		this.nativeUse = this.use;
+		this.use = ((...args) => {
+			if (isMiddlewareClass(args[0])) {
+				this.applyMiddlewareClasses("*", args);
+				return this;
+			}
+			if (typeof args[0] === "string" && args.length > 1 && isMiddlewareClass(args[1])) {
+				this.applyMiddlewareClasses(args[0], args.slice(1));
+				return this;
+			}
+			return this.nativeUse(...args);
+		});
+		this.setupRequestScope();
+		this.setupGlobalMiddleware();
+	}
+	/**
+	* Configure module middleware, OpenAPI endpoints, controller routes, and 404 handler.
+	* Called once by Application.initialize().
+	*/
+	async configure(middlewareConfigs, controllers, versioningOptions) {
+		if (this.configured) throw new HonoAppAlreadyConfiguredError();
+		new MiddlewareConfigurationService(this._logger, versioningOptions ?? null).applyMiddlewares(this, middlewareConfigs, controllers, this._container);
+		this._container.resolve(OPENAPI_TOKENS.OpenAPIService).setupEndpoints(this, controllers);
+		await new RouteRegistrationService(this._logger, versioningOptions ?? null).configure(this, controllers);
+		this.notFound((c) => {
+			throw new RouteNotFoundError(c.req.path, c.req.method);
+		});
+		this.configured = true;
+	}
+	setupRequestScope() {
+		this.nativeUse("*", async (c, next) => {
+			const routerContext = new RouterContext(c);
+			const requestContainer = this._container.createRequestScope(routerContext);
+			c.set(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER, requestContainer);
+			try {
+				await next();
+			} finally {
+				await requestContainer.dispose();
+			}
+		});
+	}
+	setupGlobalMiddleware() {
+		this.nativeUse("*", createLoggerMiddleware(this._logger));
+		this.onError((err, c) => {
+			const errorResponse = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER).resolve(DI_TOKENS.ErrorHandler).handle(err);
+			return c.json(errorResponse, getHttpStatus(errorResponse.code));
+		});
+	}
+	applyMiddlewareClasses(path, classes) {
+		this.nativeUse(path, async (c, next) => {
+			const requestContainer = c.get(ROUTER_CONTEXT_KEYS.REQUEST_CONTAINER);
+			const ctx = new RouterContext(c);
+			let current = next;
+			for (let i = classes.length - 1; i >= 0; i--) {
+				const prevNext = current;
+				const middleware = requestContainer.resolve(classes[i]);
+				current = () => middleware.handle(ctx, prevNext);
+			}
+			await current();
+		});
+		return this;
+	}
+};
+//#endregion
+//#region src/i18n/services/i18n.service.ts
+/**
+* I18n Service
+*
+* Request-scoped service for translations.
+* Injects RouterContext to access request-specific locale.
+* Uses pre-built CoreContext from MessageLoaderService (singleton) for zero-cost lookups.
+*/
+var _ref;
+let I18nService = class I18nService {
+	constructor(loader, routerContext) {
+		this.loader = loader;
+		this.routerContext = routerContext;
+	}
+	/**
+	* Translate a message key
+	*
+	* @param key - Message key (e.g., 'common.actions.save')
+	* @param params - Optional parameters for interpolation
+	* @returns Translated string
+	*/
+	t(key, params) {
+		const context = this.loader.getCoreContext(this.getLocale());
+		const result = params !== void 0 ? translate(context, key, params) : translate(context, key);
+		return typeof result === "string" ? result : key;
+	}
+	/**
+	* Get current locale
+	*
+	* @returns Current locale code from RouterContext or default locale
+	*/
+	getLocale() {
+		return this.routerContext?.getLocale() ?? "en";
+	}
+};
+I18nService = __decorate([
+	Transient(I18N_TOKENS.I18nService),
+	__decorateParam(0, inject(I18N_TOKENS.MessageLoader)),
+	__decorateParam(1, inject(ROUTER_TOKENS.RouterContext, { isOptional: true })),
+	__decorateMetadata("design:paramtypes", [Object, typeof (_ref = typeof RouterContext !== "undefined" && RouterContext) === "function" ? _ref : Object])
+], I18nService);
+//#endregion
+//#region src/i18n/services/message-loader.service.ts
+let MessageLoaderService = class MessageLoaderService {
+	cache;
+	contextCache;
+	locales;
+	defaultLocale;
+	constructor(options) {
+		this.options = options;
+		this.defaultLocale = this.options?.defaultLocale ?? "en";
+		this.cache = /* @__PURE__ */ new Map();
+		this.contextCache = /* @__PURE__ */ new Map();
+		const coreMessages = getMessages();
+		const coreLocales = getLocales();
+		const appMessages = this.options?.messages ?? {};
+		const appLocales = Object.keys(appMessages);
+		const allLocales = [...new Set([...coreLocales, ...appLocales])];
+		this.locales = allLocales;
+		for (const locale of allLocales) {
+			const coreLocaleMessages = coreMessages[locale] ?? {};
+			const appLocaleMessages = appMessages[locale] ?? {};
+			const merged = this.deepMerge(coreLocaleMessages, appLocaleMessages);
+			this.cache.set(locale, merged);
+		}
+	}
+	/**
+	* Get CoreContext for a locale (lazily built and cached on first access)
+	* Falls back to default locale if locale not found
+	*
+	* @param locale - Locale code
+	* @returns Cached CoreContext ready for translation
+	*/
+	getCoreContext(locale) {
+		const cached = this.contextCache.get(locale);
+		if (cached) return cached;
+		const effectiveLocale = this.cache.has(locale) ? locale : this.defaultLocale;
+		const cachedEffective = this.contextCache.get(effectiveLocale);
+		if (cachedEffective) return cachedEffective;
+		const messages = this.cache.get(effectiveLocale) ?? {};
+		const flattened = this.flattenMessages(messages);
+		const ctx = createCoreContext({
+			locale: effectiveLocale,
+			messages: { [effectiveLocale]: flattened },
+			missingWarn: false,
+			fallbackWarn: false
+		});
+		this.contextCache.set(effectiveLocale, ctx);
+		return ctx;
+	}
+	/**
+	* Get messages for a specific locale
+	* Falls back to default locale if locale not found
+	*
+	* @param locale - Locale code
+	* @returns Message object for the locale
+	*/
+	getMessages(locale) {
+		const msgs = this.cache.get(locale);
+		if (!msgs) return this.cache.get(this.defaultLocale) ?? {};
+		return msgs;
+	}
+	/**
+	* Get list of available locale codes
+	*
+	* @returns Array of locale codes
+	*/
+	getAvailableLocales() {
+		return this.locales;
+	}
+	/**
+	* Check if a locale is supported
+	*
+	* @param locale - Locale code to check
+	* @returns true if locale is supported
+	*/
+	isLocaleSupported(locale) {
+		return this.cache.has(locale);
+	}
+	/**
+	* Get default locale
+	*
+	* @returns Default locale code
+	*/
+	getDefaultLocale() {
+		return this.defaultLocale;
+	}
+	/**
+	* Flatten nested messages to dot-notation
+	*
+	* Converts { auth: { login: { title: 'Sign In' } } }
+	* to { 'auth.login.title': 'Sign In' }
+	*/
+	flattenMessages(messages, prefix = "") {
+		const result = {};
+		for (const key of Object.keys(messages)) {
+			const value = messages[key];
+			const newKey = prefix ? `${prefix}.${key}` : key;
+			if (typeof value === "object" && value !== null && !Array.isArray(value)) Object.assign(result, this.flattenMessages(value, newKey));
+			else result[newKey] = String(value);
+		}
+		return result;
+	}
+	/**
+	* Deep merge two objects
+	* App messages override core messages at leaf level
+	*/
+	deepMerge(target, source) {
+		const result = { ...target };
+		for (const key of Object.keys(source)) {
+			const targetValue = target[key];
+			const sourceValue = source[key];
+			if (typeof targetValue === "object" && targetValue !== null && !Array.isArray(targetValue) && typeof sourceValue === "object" && sourceValue !== null && !Array.isArray(sourceValue)) result[key] = this.deepMerge(targetValue, sourceValue);
+			else result[key] = sourceValue;
+		}
+		return result;
+	}
+};
+MessageLoaderService = __decorate([
+	Transient(I18N_TOKENS.MessageLoader),
+	__decorateParam(0, inject(I18N_TOKENS.Options, { isOptional: true })),
+	__decorateMetadata("design:paramtypes", [Object])
+], MessageLoaderService);
+//#endregion
+//#region src/i18n/i18n.module.ts
+/**
+* I18n Module
+*
+* Core infrastructure module for internationalization.
+* Provides message translation and locale handling.
+*
+* @example Default usage (system messages only)
+* ```typescript
+* // In Application.ts - I18nModule is already included in core modules
+* // Works with system messages and 'en' default locale
+* ```
+*
+* @example With app-specific configuration
+* ```typescript
+* // In apps/backend/src/app.module.ts
+* import { i18nConfig } from './i18n'
+*
+* @Module({
+*   imports: [I18nModule.forRoot(i18nConfig)],
+* })
+* export class AppModule {}
+* ```
+*/
+var _I18nModule;
+setupI18nCompiler();
+z.config({ customError: backendErrorMap });
+let I18nModule = _I18nModule = class I18nModule {
+	/**
+	* Configure I18n with app-specific options
+	*
+	* Use this method in AppModule to provide custom locale configuration
+	* and app-specific messages that merge with system messages.
+	*
+	* @param options - I18n configuration options
+	* @returns Dynamic module with options provider
+	*
+	* @example
+	* ```typescript
+	* // apps/backend/src/i18n/index.ts
+	* export const i18nConfig: I18nModuleOptions = {
+	*   defaultLocale: 'en',
+	*   fallbackLocale: 'en',
+	*   locales: ['en', 'fr'],
+	*   messages: appMessages
+	* }
+	*
+	* // apps/backend/src/app.module.ts
+	* @Module({
+	*   imports: [I18nModule.forRoot(i18nConfig)],
+	* })
+	* export class AppModule {}
+	* ```
+	*/
+	static forRoot(options = {}) {
+		return {
+			module: _I18nModule,
+			providers: [{
+				provide: I18N_TOKENS.Options,
+				useValue: options
+			}]
+		};
+	}
+	/**
+	* Configure middleware for locale extraction and i18n context
+	*/
+	configure(consumer) {
+		consumer.apply(LocaleExtractionMiddleware, I18nContextMiddleware).forRoutes("*");
+	}
+};
+I18nModule = _I18nModule = __decorate([Module({ providers: [{
+	provide: I18N_TOKENS.MessageLoader,
+	useClass: MessageLoaderService,
+	scope: Scope.Singleton
+}, {
+	provide: I18N_TOKENS.I18nService,
+	useClass: I18nService
+}] })], I18nModule);
+//#endregion
+export { LocaleNotSupportedError as A, Get as C, getHttpDecoratedMethods as D, Put as E, messages as F, OpenAPIConfigService as I, OPENAPI_TOKENS as L, setupI18nCompiler as M, getLocales as N, getHttpRouteMetadata as O, getMessages as P, LocaleExtractionMiddleware as R, Delete as S, Post as T, OpenAPIService as _, errorResponseSchema as a, getRouteConfig as b, successMessageSchema as c, RouteNotFoundError as d, OpenAPIValidationError as f, OpenAPIModule as g, HonoAppAlreadyConfiguredError as h, commonErrorSchemas as i, resolveI18nOptions as j, TranslationMissingError as k, uuidParamSchema as l, ControllerRegistrationError as m, HonoApp as n, paginatedResponseSchema as o, OpenAPIRouteRegistrationError as p, RouteRegistrationService as r, paginationQuerySchema as s, I18nModule as t, validationErrorResponseSchema as u, Route as v, Patch as w, All as x, getDecoratedMethods as y, I18nContextMiddleware as z };
+
+//# sourceMappingURL=i18n.module-C9wQr_2k.mjs.map