@forinda/kickjs-cli 2.0.1 → 2.2.0

package/dist/index.mjs

@@ -0,0 +1,3627 @@
+/**
+ * @forinda/kickjs-cli v2.2.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** Write a file, creating parent directories if needed. Skips writing in dry run mode. */
+async function writeFileSafe(filePath, content) {
+	await mkdir(dirname(filePath), { recursive: true });
+	await writeFile(filePath, content, "utf-8");
+}
+/** Check if a file exists */
+async function fileExists(filePath) {
+	try {
+		await access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/utils/naming.ts
+/** Convert a name to PascalCase */
+function toPascalCase(name) {
+	return name.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^(.)/, (c) => c.toUpperCase());
+}
+/** Convert a name to camelCase */
+function toCamelCase(name) {
+	const pascal = toPascalCase(name);
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+/** Convert a name to kebab-case */
+function toKebabCase(name) {
+	return name.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+/**
+* Pluralize a kebab-case name for directory/file names.
+* If already plural (ends in 's'), returns as-is.
+*/
+function pluralize(name) {
+	if (name.endsWith("s")) return name;
+	if (name.endsWith("x") || name.endsWith("z")) return name + "es";
+	if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
+	if (name.endsWith("y") && !/[aeiou]y$/.test(name)) return name.slice(0, -1) + "ies";
+	return name + "s";
+}
+/**
+* Pluralize a PascalCase name for class identifiers.
+* If already plural (ends in 's'), returns as-is.
+* Used for `List${pluralPascal}UseCase` to avoid `ListUserssUseCase`.
+*/
+function pluralizePascal(name) {
+	if (name.endsWith("s")) return name;
+	if (name.endsWith("x") || name.endsWith("z")) return name + "es";
+	if (name.endsWith("sh") || name.endsWith("ch")) return name + "es";
+	if (name.endsWith("y") && !/[aeiou]y$/i.test(name)) return name.slice(0, -1) + "ies";
+	return name + "s";
+}
+//#endregion
+//#region src/generators/templates/module-index.ts
+const repoLabelMap = {
+	inmemory: "in-memory",
+	drizzle: "Drizzle",
+	prisma: "Prisma"
+};
+function toPascalRepoType(repo) {
+	return repo.charAt(0).toUpperCase() + repo.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function toKebabRepoType(repo) {
+	return repo.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+function repoLabel(repo) {
+	return repoLabelMap[repo] ?? toPascalRepoType(repo);
+}
+function repoMaps(pascal, kebab, repo) {
+	const repoClassMap = {
+		inmemory: `InMemory${pascal}Repository`,
+		drizzle: `Drizzle${pascal}Repository`,
+		prisma: `Prisma${pascal}Repository`
+	};
+	const repoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	return {
+		repoClass: repoClassMap[repo] ?? `${toPascalRepoType(repo)}${pascal}Repository`,
+		repoFile: repoFileMap[repo] ?? `${toKebabRepoType(repo)}-${kebab}`
+	};
+}
+/** DDD module index — nested folders, use-cases, domain services */
+function generateModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const { repoClass, repoFile } = repoMaps(pascal, kebab, repo);
+	return `/**
+ * ${pascal} Module
+ *
+ * Self-contained feature module following Domain-Driven Design (DDD).
+ * Registers dependencies in the DI container and declares HTTP routes.
+ *
+ * Structure:
+ *   presentation/    — HTTP controllers (entry points)
+ *   application/     — Use cases (orchestration) and DTOs (validation)
+ *   domain/          — Entities, value objects, repository interfaces, domain services
+ *   infrastructure/  — Repository implementations (currently ${repoLabel(repo)})
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './domain/repositories/${kebab}.repository'
+import { ${repoClass} } from './infrastructure/repositories/${repoFile}.repository'
+import { ${pascal}Controller } from './presentation/${kebab}.controller'
+
+// Eagerly load decorated classes so @Service()/@Repository() decorators register in the DI container
+import.meta.glob(
+  ['./domain/services/**/*.ts', './application/use-cases/**/*.ts', '!./**/*.test.ts'],
+  { eager: true },
+)
+
+export class ${pascal}Module implements AppModule {
+  /**
+   * Register module dependencies in the DI container.
+   * Bind repository interface tokens to their implementations here.
+   * Currently wired to ${repoLabel(repo)}. To swap implementations, change the factory target.
+   */
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  /**
+   * Declare HTTP routes for this module.
+   * The path is prefixed with the global apiPrefix and version (e.g. /api/v1/${plural}).
+   * Passing 'controller' enables automatic OpenAPI spec generation via SwaggerAdapter.
+   */
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** REST module index — flat folder, service + controller, no use-cases */
+function generateRestModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const { repoClass, repoFile } = repoMaps(pascal, kebab, repo);
+	return `/**
+ * ${pascal} Module
+ *
+ * REST module with a flat folder structure.
+ * Controller delegates to service, service wraps the repository.
+ *
+ * Structure:
+ *   ${kebab}.controller.ts  — HTTP routes (CRUD)
+ *   ${kebab}.service.ts     — Business logic
+ *   ${kebab}.repository.ts  — Repository interface
+ *   ${repoFile}.repository.ts — Repository implementation
+ *   dtos/                   — Request/response schemas
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './${kebab}.repository'
+import { ${repoClass} } from './${repoFile}.repository'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+// Eagerly load decorated classes so @Service()/@Repository() decorators register in the DI container
+import.meta.glob(['./**/*.service.ts', './**/*.repository.ts', '!./**/*.test.ts'], { eager: true })
+
+export class ${pascal}Module implements AppModule {
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** Minimal module index — just controller, no service/repo */
+function generateMinimalModuleIndex(ctx) {
+	const { pascal, kebab, plural = "" } = ctx;
+	return `import { type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+export class ${pascal}Module implements AppModule {
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/controller.ts
+/** DDD controller — injects use-cases, nested import paths */
+function generateController$1(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { Create${pascal}UseCase } from '../application/use-cases/create-${kebab}.use-case'
+import { Get${pascal}UseCase } from '../application/use-cases/get-${kebab}.use-case'
+import { List${pluralPascal}UseCase } from '../application/use-cases/list-${plural}.use-case'
+import { Update${pascal}UseCase } from '../application/use-cases/update-${kebab}.use-case'
+import { Delete${pascal}UseCase } from '../application/use-cases/delete-${kebab}.use-case'
+import { create${pascal}Schema } from '../application/dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from '../application/dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from '../constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly create${pascal}UseCase!: Create${pascal}UseCase
+  @Autowired() private readonly get${pascal}UseCase!: Get${pascal}UseCase
+  @Autowired() private readonly list${pluralPascal}UseCase!: List${pluralPascal}UseCase
+  @Autowired() private readonly update${pascal}UseCase!: Update${pascal}UseCase
+  @Autowired() private readonly delete${pascal}UseCase!: Delete${pascal}UseCase
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.list${pluralPascal}UseCase.execute(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.get${pascal}UseCase.execute(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.create${pascal}UseCase.execute(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.update${pascal}UseCase.execute(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.delete${pascal}UseCase.execute(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+/** REST controller — injects service directly, flat import paths */
+function generateRestController(ctx) {
+	const { pascal, kebab } = ctx;
+	const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { ${pascal}Service } from './${kebab}.service'
+import { create${pascal}Schema } from './dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from './dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from './${kebab}.constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly ${camel}Service!: ${pascal}Service
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.${camel}Service.findPaginated(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.${camel}Service.findById(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.${camel}Service.create(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.${camel}Service.update(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.${camel}Service.delete(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/constants.ts
+function generateConstants(ctx) {
+	const { pascal } = ctx;
+	return `import type { QueryParamsConfig } from '@forinda/kickjs'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: QueryParamsConfig = {
+  filterable: ['name'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name'],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/dtos.ts
+function generateCreateDTO(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import { z } from 'zod'
+
+/**
+ * Create ${pascal} DTO — Zod schema for validating POST request bodies.
+ * This schema is passed to @Post('/', { body: create${pascal}Schema }) for automatic validation.
+ * It also generates OpenAPI request body docs when SwaggerAdapter is used.
+ *
+ * Add more fields as needed. Supported Zod types:
+ *   z.string(), z.number(), z.boolean(), z.enum([...]),
+ *   z.array(), z.object(), .optional(), .default(), .transform()
+ */
+export const create${pascal}Schema = z.object({
+  name: z.string().min(1, 'Name is required').max(200),
+})
+
+export type Create${pascal}DTO = z.infer<typeof create${pascal}Schema>
+`;
+}
+function generateUpdateDTO(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import { z } from 'zod'
+
+export const update${pascal}Schema = z.object({
+  name: z.string().min(1).max(200).optional(),
+})
+
+export type Update${pascal}DTO = z.infer<typeof update${pascal}Schema>
+`;
+}
+function generateResponseDTO(ctx) {
+	const { pascal, kebab } = ctx;
+	return `export interface ${pascal}ResponseDTO {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/use-cases.ts
+function generateUseCases(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return [
+		{
+			file: `create-${kebab}.use-case.ts`,
+			content: `/**
+ * Create ${pascal} Use Case
+ *
+ * Application layer — orchestrates a single business operation.
+ * Use cases are thin: validate input (via DTO), call domain/repo, return response.
+ * Keep business rules in the domain service, not here.
+ */
+import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Create${pascal}DTO } from '../dtos/create-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Create${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.create(dto)
+  }
+}
+`
+		},
+		{
+			file: `get-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Get${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+}
+`
+		},
+		{
+			file: `list-${plural}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+@Service()
+export class List${pluralPascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+}
+`
+		},
+		{
+			file: `update-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+import type { Update${pascal}DTO } from '../dtos/update-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Update${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.update(id, dto)
+  }
+}
+`
+		},
+		{
+			file: `delete-${kebab}.use-case.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../../domain/repositories/${kebab}.repository'
+
+@Service()
+export class Delete${pascal}UseCase {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<void> {
+    await this.repo.delete(id)
+  }
+}
+`
+		}
+	];
+}
+//#endregion
+//#region src/generators/templates/repository.ts
+function generateRepositoryInterface(ctx) {
+	const { pascal, kebab, dtoPrefix = "../../application/dtos" } = ctx;
+	return `/**
+ * ${pascal} Repository Interface
+ *
+ * Defines the contract for data access.
+ * The interface declares what operations are available;
+ * implementations (in-memory, Drizzle, Prisma) fulfill the contract.
+ *
+ * To swap implementations, change the factory in the module's register() method.
+ */
+import { createToken } from '@forinda/kickjs'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+export interface I${pascal}Repository {
+  findById(id: string): Promise<${pascal}ResponseDTO | null>
+  findAll(): Promise<${pascal}ResponseDTO[]>
+  findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }>
+  create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO>
+  update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO>
+  delete(id: string): Promise<void>
+}
+
+/**
+ * Collision-safe DI token bound to \`I${pascal}Repository\`.
+ * \`container.resolve(${pascal.toUpperCase()}_REPOSITORY)\` and
+ * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
+ * interface — no manual generic, no \`any\` cast.
+ */
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${pascal}/Repository')
+`;
+}
+function generateInMemoryRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	return `/**
+ * In-Memory ${pascal} Repository
+ *
+ * Implements the repository interface using a Map.
+ * Useful for prototyping and testing. Replace with a database implementation
+ * (Drizzle, Prisma, etc.) for production use.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { randomUUID } from 'node:crypto'
+import { Repository, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class InMemory${pascal}Repository implements I${pascal}Repository {
+  private store = new Map<string, ${pascal}ResponseDTO>()
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.store.get(id) ?? null
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return Array.from(this.store.values())
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    const all = Array.from(this.store.values())
+    const data = all.slice(parsed.pagination.offset, parsed.pagination.offset + parsed.pagination.limit)
+    return { data, total: all.length }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const now = new Date().toISOString()
+    const entity: ${pascal}ResponseDTO = {
+      id: randomUUID(),
+      name: dto.name,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.store.set(entity.id, entity)
+    return entity
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const existing = this.store.get(id)
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    const updated = { ...existing, ...dto, updatedAt: new Date().toISOString() }
+    this.store.set(id, updated)
+    return updated
+  }
+
+  async delete(id: string): Promise<void> {
+    if (!this.store.has(id)) throw HttpException.notFound('${pascal} not found')
+    this.store.delete(id)
+  }
+}
+`;
+}
+function generateCustomRepository(ctx) {
+	const { pascal, kebab, repoType = "", repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	const repoTypePascal = repoType.charAt(0).toUpperCase() + repoType.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+	return `/**
+ * ${repoTypePascal} ${pascal} Repository
+ *
+ * Stub implementation for a custom '${repoType}' repository.
+ * Implements the repository interface using an in-memory Map as a placeholder.
+ *
+ * TODO: Replace the in-memory Map with your ${repoType} data-access logic.
+ * See I${pascal}Repository for the interface contract.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { randomUUID } from 'node:crypto'
+import { Repository, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class ${repoTypePascal}${pascal}Repository implements I${pascal}Repository {
+  // TODO: Replace with your ${repoType} client/connection
+  private store = new Map<string, ${pascal}ResponseDTO>()
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    // TODO: Implement with ${repoType}
+    return this.store.get(id) ?? null
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    // TODO: Implement with ${repoType}
+    return Array.from(this.store.values())
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    // TODO: Implement with ${repoType}
+    const all = Array.from(this.store.values())
+    const data = all.slice(parsed.pagination.offset, parsed.pagination.offset + parsed.pagination.limit)
+    return { data, total: all.length }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with ${repoType}
+    const now = new Date().toISOString()
+    const entity: ${pascal}ResponseDTO = {
+      id: randomUUID(),
+      name: dto.name,
+      createdAt: now,
+      updatedAt: now,
+    }
+    this.store.set(entity.id, entity)
+    return entity
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with ${repoType}
+    const existing = this.store.get(id)
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    const updated = { ...existing, ...dto, updatedAt: new Date().toISOString() }
+    this.store.set(id, updated)
+    return updated
+  }
+
+  async delete(id: string): Promise<void> {
+    // TODO: Implement with ${repoType}
+    if (!this.store.has(id)) throw HttpException.notFound('${pascal} not found')
+    this.store.delete(id)
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/domain.ts
+function generateDomainService(ctx) {
+	const { pascal, kebab } = ctx;
+	return `/**
+ * ${pascal} Domain Service
+ *
+ * Domain layer — contains business rules that don't belong to a single entity.
+ * Use this for cross-entity logic, validation rules, and domain invariants.
+ * Keep it free of HTTP/framework concerns.
+ */
+import { Service, Inject, HttpException } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../repositories/${kebab}.repository'
+
+@Service()
+export class ${pascal}DomainService {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async ensureExists(id: string): Promise<void> {
+    const entity = await this.repo.findById(id)
+    if (!entity) {
+      throw HttpException.notFound('${pascal} not found')
+    }
+  }
+}
+`;
+}
+function generateEntity(ctx) {
+	const { pascal, kebab } = ctx;
+	return `/**
+ * ${pascal} Entity
+ *
+ * Domain layer — the core business object.
+ * Uses a private constructor with static factory methods (create, reconstitute)
+ * to enforce invariants. Properties are accessed via getters to maintain encapsulation.
+ *
+ * Patterns used:
+ *   - Private constructor: prevents direct instantiation
+ *   - create(): factory for new entities (generates ID, sets timestamps)
+ *   - reconstitute(): factory for rebuilding from persistence (no side effects)
+ *   - changeName(): mutation method that enforces business rules
+ */
+import { ${pascal}Id } from '../value-objects/${kebab}-id.vo'
+
+interface ${pascal}Props {
+  id: ${pascal}Id
+  name: string
+  createdAt: Date
+  updatedAt: Date
+}
+
+export class ${pascal} {
+  private constructor(private props: ${pascal}Props) {}
+
+  static create(params: { name: string }): ${pascal} {
+    const now = new Date()
+    return new ${pascal}({
+      id: ${pascal}Id.create(),
+      name: params.name,
+      createdAt: now,
+      updatedAt: now,
+    })
+  }
+
+  static reconstitute(props: ${pascal}Props): ${pascal} {
+    return new ${pascal}(props)
+  }
+
+  get id(): ${pascal}Id {
+    return this.props.id
+  }
+  get name(): string {
+    return this.props.name
+  }
+  get createdAt(): Date {
+    return this.props.createdAt
+  }
+  get updatedAt(): Date {
+    return this.props.updatedAt
+  }
+
+  changeName(name: string): void {
+    if (!name || name.trim().length === 0) {
+      throw new Error('Name cannot be empty')
+    }
+    this.props.name = name.trim()
+    this.props.updatedAt = new Date()
+  }
+
+  toJSON() {
+    return {
+      id: this.props.id.toString(),
+      name: this.props.name,
+      createdAt: this.props.createdAt.toISOString(),
+      updatedAt: this.props.updatedAt.toISOString(),
+    }
+  }
+}
+`;
+}
+function generateValueObject(ctx) {
+	const { pascal, kebab } = ctx;
+	return `/**
+ * ${pascal} ID Value Object
+ *
+ * Domain layer — wraps a primitive ID with type safety and validation.
+ * Value objects are immutable and compared by value, not reference.
+ *
+ *   ${pascal}Id.create()    — generate a new UUID
+ *   ${pascal}Id.from(id)    — wrap an existing ID string (validates non-empty)
+ *   id.equals(other)  — compare two IDs by value
+ */
+import { randomUUID } from 'node:crypto'
+
+export class ${pascal}Id {
+  private constructor(private readonly value: string) {}
+
+  static create(): ${pascal}Id {
+    return new ${pascal}Id(randomUUID())
+  }
+
+  static from(id: string): ${pascal}Id {
+    if (!id || id.trim().length === 0) {
+      throw new Error('${pascal}Id cannot be empty')
+    }
+    return new ${pascal}Id(id)
+  }
+
+  toString(): string {
+    return this.value
+  }
+
+  equals(other: ${pascal}Id): boolean {
+    return this.value === other.value
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/tests.ts
+function generateControllerTest(ctx) {
+	const { pascal, kebab, plural = "" } = ctx;
+	return `import { describe, it, expect, beforeEach } from 'vitest'
+import { Container } from '@forinda/kickjs'
+
+describe('${pascal}Controller', () => {
+  beforeEach(() => {
+    Container.reset()
+  })
+
+  it('should be defined', () => {
+    expect(true).toBe(true)
+  })
+
+  describe('POST /${plural}', () => {
+    it('should create a new ${kebab}', async () => {
+      // TODO: Set up test module, call create endpoint, assert 201
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('GET /${plural}', () => {
+    it('should return paginated ${plural}', async () => {
+      // TODO: Set up test module, call list endpoint, assert { data, meta }
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('GET /${plural}/:id', () => {
+    it('should return a ${kebab} by id', async () => {
+      // TODO: Create a ${kebab}, then fetch by id, assert match
+      expect(true).toBe(true)
+    })
+
+    it('should return 404 for non-existent ${kebab}', async () => {
+      // TODO: Fetch non-existent id, assert 404
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('PUT /${plural}/:id', () => {
+    it('should update an existing ${kebab}', async () => {
+      // TODO: Create, update, assert changes
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('DELETE /${plural}/:id', () => {
+    it('should delete a ${kebab}', async () => {
+      // TODO: Create, delete, assert gone
+      expect(true).toBe(true)
+    })
+  })
+})
+`;
+}
+function generateRepositoryTest(ctx) {
+	const { pascal, kebab, plural = "", repoPrefix = `../infrastructure/repositories/in-memory-${kebab}.repository` } = ctx;
+	return `import { describe, it, expect, beforeEach } from 'vitest'
+import { InMemory${pascal}Repository } from '${repoPrefix}'
+
+describe('InMemory${pascal}Repository', () => {
+  let repo: InMemory${pascal}Repository
+
+  beforeEach(() => {
+    repo = new InMemory${pascal}Repository()
+  })
+
+  it('should create and retrieve a ${kebab}', async () => {
+    const created = await repo.create({ name: 'Test ${pascal}' })
+    expect(created).toBeDefined()
+    expect(created.name).toBe('Test ${pascal}')
+    expect(created.id).toBeDefined()
+
+    const found = await repo.findById(created.id)
+    expect(found).toEqual(created)
+  })
+
+  it('should return null for non-existent id', async () => {
+    const found = await repo.findById('non-existent')
+    expect(found).toBeNull()
+  })
+
+  it('should list all ${plural}', async () => {
+    await repo.create({ name: '${pascal} 1' })
+    await repo.create({ name: '${pascal} 2' })
+
+    const all = await repo.findAll()
+    expect(all).toHaveLength(2)
+  })
+
+  it('should return paginated results', async () => {
+    await repo.create({ name: '${pascal} 1' })
+    await repo.create({ name: '${pascal} 2' })
+    await repo.create({ name: '${pascal} 3' })
+
+    const result = await repo.findPaginated({
+      filters: [],
+      sort: [],
+      search: '',
+      pagination: { page: 1, limit: 2, offset: 0 },
+    })
+
+    expect(result.data).toHaveLength(2)
+    expect(result.total).toBe(3)
+  })
+
+  it('should update a ${kebab}', async () => {
+    const created = await repo.create({ name: 'Original' })
+    const updated = await repo.update(created.id, { name: 'Updated' })
+    expect(updated.name).toBe('Updated')
+  })
+
+  it('should delete a ${kebab}', async () => {
+    const created = await repo.create({ name: 'To Delete' })
+    await repo.delete(created.id)
+    const found = await repo.findById(created.id)
+    expect(found).toBeNull()
+  })
+})
+`;
+}
+//#endregion
+//#region src/generators/templates/rest-service.ts
+/** REST service — wraps repository with CRUD methods, replaces use-cases for flat pattern */
+function generateRestService(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import { Service, Inject, HttpException } from '@forinda/kickjs'
+import type { ParsedQuery } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from './${kebab}.repository'
+import type { ${pascal}ResponseDTO } from './dtos/${kebab}-response.dto'
+import type { Create${pascal}DTO } from './dtos/create-${kebab}.dto'
+import type { Update${pascal}DTO } from './dtos/update-${kebab}.dto'
+
+@Service()
+export class ${pascal}Service {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return this.repo.findAll()
+  }
+
+  async findPaginated(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.create(dto)
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.repo.update(id, dto)
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.repo.delete(id)
+  }
+}
+`;
+}
+/** REST constants — query config for flat pattern */
+function generateRestConstants(ctx) {
+	const { pascal } = ctx;
+	return `import type { QueryFieldConfig } from '@forinda/kickjs'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: QueryFieldConfig = {
+  filterable: ['name'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name'],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/cqrs.ts
+/** CQRS module index — commands, queries, events, WebSocket + queue integration */
+function generateCqrsModuleIndex(ctx) {
+	const { pascal, kebab, plural = "", repo } = ctx;
+	const repoClassMap = {
+		inmemory: `InMemory${pascal}Repository`,
+		drizzle: `Drizzle${pascal}Repository`,
+		prisma: `Prisma${pascal}Repository`
+	};
+	const repoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const repoClass = repoClassMap[repo] ?? repoClassMap.inmemory;
+	const repoFile = repoFileMap[repo] ?? repoFileMap.inmemory;
+	return `/**
+ * ${pascal} Module — CQRS Pattern
+ *
+ * Separates read (queries) and write (commands) operations.
+ * Events are emitted after state changes and can be handled via
+ * WebSocket broadcasts, queue jobs, or ETL pipelines.
+ *
+ * Structure:
+ *   commands/       — Write operations (create, update, delete)
+ *   queries/        — Read operations (get, list)
+ *   events/         — Domain events + handlers (WS broadcast, queue dispatch)
+ *   dtos/           — Request/response schemas
+ */
+import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+import { buildRoutes } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY } from './${kebab}.repository'
+import { ${repoClass} } from './${repoFile}.repository'
+import { ${pascal}Controller } from './${kebab}.controller'
+
+// Eagerly load decorated classes
+import.meta.glob(
+  [
+    './commands/**/*.ts',
+    './queries/**/*.ts',
+    './events/**/*.ts',
+    '!./**/*.test.ts',
+  ],
+  { eager: true },
+)
+
+export class ${pascal}Module implements AppModule {
+  register(container: Container): void {
+    container.registerFactory(${pascal.toUpperCase()}_REPOSITORY, () =>
+      container.resolve(${repoClass}),
+    )
+  }
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
+  }
+}
+`;
+}
+/** CQRS controller — dispatches to command/query handlers */
+function generateCqrsController(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams, type Ctx } from '@forinda/kickjs'
+import { ApiTags } from '@forinda/kickjs-swagger'
+import { Create${pascal}Command } from './commands/create-${kebab}.command'
+import { Update${pascal}Command } from './commands/update-${kebab}.command'
+import { Delete${pascal}Command } from './commands/delete-${kebab}.command'
+import { Get${pascal}Query } from './queries/get-${kebab}.query'
+import { List${pluralPascal}Query } from './queries/list-${plural}.query'
+import { create${pascal}Schema } from './dtos/create-${kebab}.dto'
+import { update${pascal}Schema } from './dtos/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from './${kebab}.constants'
+
+// Each handler annotates its \`ctx\` with \`Ctx<KickRoutes.${pascal}Controller['<method>']>\`
+// so \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` are typed end-to-end.
+// The \`KickRoutes\` namespace is generated by \`kick typegen\` (auto-run on
+// \`kick dev\`) — see https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class ${pascal}Controller {
+  @Autowired() private readonly create${pascal}Command!: Create${pascal}Command
+  @Autowired() private readonly update${pascal}Command!: Update${pascal}Command
+  @Autowired() private readonly delete${pascal}Command!: Delete${pascal}Command
+  @Autowired() private readonly get${pascal}Query!: Get${pascal}Query
+  @Autowired() private readonly list${pluralPascal}Query!: List${pluralPascal}Query
+
+  @Get('/')
+  @ApiTags('${pascal}')
+  @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    return ctx.paginate(
+      (parsed) => this.list${pluralPascal}Query.execute(parsed),
+      ${pascal.toUpperCase()}_QUERY_CONFIG,
+    )
+  }
+
+  @Get('/:id')
+  @ApiTags('${pascal}')
+  async getById(ctx: Ctx<KickRoutes.${pascal}Controller['getById']>) {
+    const result = await this.get${pascal}Query.execute(ctx.params.id)
+    if (!result) return ctx.notFound('${pascal} not found')
+    ctx.json(result)
+  }
+
+  @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
+  @ApiTags('${pascal}')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    const result = await this.create${pascal}Command.execute(ctx.body)
+    ctx.created(result)
+  }
+
+  @Put('/:id', { body: update${pascal}Schema, name: 'Update${pascal}' })
+  @ApiTags('${pascal}')
+  async update(ctx: Ctx<KickRoutes.${pascal}Controller['update']>) {
+    const result = await this.update${pascal}Command.execute(ctx.params.id, ctx.body)
+    ctx.json(result)
+  }
+
+  @Delete('/:id')
+  @ApiTags('${pascal}')
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
+    await this.delete${pascal}Command.execute(ctx.params.id)
+    ctx.noContent()
+  }
+}
+`;
+}
+/** CQRS commands — write operations that emit events */
+function generateCqrsCommands(ctx) {
+	const { pascal, kebab } = ctx;
+	return [
+		{
+			file: `create-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { Create${pascal}DTO } from '../dtos/create-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Create${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const result = await this.repo.create(dto)
+    this.events.emit('${kebab}.created', result)
+    return result
+  }
+}
+`
+		},
+		{
+			file: `update-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { Update${pascal}DTO } from '../dtos/update-${kebab}.dto'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Update${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const result = await this.repo.update(id, dto)
+    this.events.emit('${kebab}.updated', result)
+    return result
+  }
+}
+`
+		},
+		{
+			file: `delete-${kebab}.command.ts`,
+			content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import { ${pascal}Events } from '../events/${kebab}.events'
+
+@Service()
+export class Delete${pascal}Command {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+    @Inject(${pascal}Events) private readonly events: ${pascal}Events,
+  ) {}
+
+  async execute(id: string): Promise<void> {
+    await this.repo.delete(id)
+    this.events.emit('${kebab}.deleted', { id })
+  }
+}
+`
+		}
+	];
+}
+/** CQRS queries — read operations */
+function generateCqrsQueries(ctx) {
+	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	return [{
+		file: `get-${kebab}.query.ts`,
+		content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+@Service()
+export class Get${pascal}Query {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.repo.findById(id)
+  }
+}
+`
+	}, {
+		file: `list-${plural}.query.ts`,
+		content: `import { Service, Inject } from '@forinda/kickjs'
+import { ${pascal.toUpperCase()}_REPOSITORY, type I${pascal}Repository } from '../${kebab}.repository'
+import type { ParsedQuery } from '@forinda/kickjs'
+
+@Service()
+export class List${pluralPascal}Query {
+  constructor(
+    @Inject(${pascal.toUpperCase()}_REPOSITORY) private readonly repo: I${pascal}Repository,
+  ) {}
+
+  async execute(parsed: ParsedQuery) {
+    return this.repo.findPaginated(parsed)
+  }
+}
+`
+	}];
+}
+/** CQRS events — domain event emitter + handler with WS/queue integration */
+function generateCqrsEvents(ctx) {
+	const { pascal, kebab } = ctx;
+	return [{
+		file: `${kebab}.events.ts`,
+		content: `import { Service } from '@forinda/kickjs'
+import { EventEmitter } from 'node:events'
+import type { ${pascal}ResponseDTO } from '../dtos/${kebab}-response.dto'
+
+/**
+ * ${pascal} domain event types.
+ *
+ * These events are emitted by commands after state changes.
+ * Subscribe to them in event handlers for side effects:
+ *   - WebSocket broadcasts (real-time UI updates)
+ *   - Queue jobs (async processing, ETL pipelines)
+ *   - Audit logging
+ *   - Cache invalidation
+ */
+export interface ${pascal}EventMap {
+  '${kebab}.created': ${pascal}ResponseDTO
+  '${kebab}.updated': ${pascal}ResponseDTO
+  '${kebab}.deleted': { id: string }
+}
+
+@Service()
+export class ${pascal}Events {
+  private emitter = new EventEmitter()
+
+  emit<K extends keyof ${pascal}EventMap>(event: K, data: ${pascal}EventMap[K]): void {
+    this.emitter.emit(event, data)
+  }
+
+  on<K extends keyof ${pascal}EventMap>(event: K, handler: (data: ${pascal}EventMap[K]) => void): void {
+    this.emitter.on(event, handler)
+  }
+
+  off<K extends keyof ${pascal}EventMap>(event: K, handler: (data: ${pascal}EventMap[K]) => void): void {
+    this.emitter.off(event, handler)
+  }
+}
+`
+	}, {
+		file: `on-${kebab}-change.handler.ts`,
+		content: `import { Service, Autowired } from '@forinda/kickjs'
+import { ${pascal}Events } from './${kebab}.events'
+
+/**
+ * ${pascal} Change Event Handler
+ *
+ * Reacts to domain events emitted by commands.
+ * Wire up side effects here:
+ *
+ * 1. WebSocket broadcast — notify connected clients in real-time
+ *    import { WsGateway } from '@forinda/kickjs-ws'
+ *    this.ws.broadcast('${kebab}-channel', { event, data })
+ *
+ * 2. Queue dispatch — offload heavy processing to background workers
+ *    import { QueueService } from '@forinda/kickjs-queue'
+ *    this.queue.add('${kebab}-etl', { action: event, payload: data })
+ *
+ * 3. ETL pipeline — transform and load data to external systems
+ *    await this.etlPipeline.process(data)
+ */
+@Service()
+export class On${pascal}ChangeHandler {
+  @Autowired() private events!: ${pascal}Events
+
+  // Uncomment to inject WebSocket and Queue services:
+  // @Autowired() private ws!: WsGateway
+  // @Autowired() private queue!: QueueService
+
+  onInit(): void {
+    this.events.on('${kebab}.created', (data) => {
+      console.log('[${pascal}] Created:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.created', data })
+      // TODO: Dispatch to queue for async processing / ETL
+      // this.queue.add('${kebab}-etl', { action: 'create', payload: data })
+    })
+
+    this.events.on('${kebab}.updated', (data) => {
+      console.log('[${pascal}] Updated:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.updated', data })
+    })
+
+    this.events.on('${kebab}.deleted', (data) => {
+      console.log('[${pascal}] Deleted:', data.id)
+      // TODO: Broadcast via WebSocket
+      // this.ws.broadcast('${kebab}-channel', { event: '${kebab}.deleted', data })
+    })
+  }
+}
+`
+	}];
+}
+//#endregion
+//#region src/generators/templates/drizzle/index.ts
+function generateDrizzleRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	return `/**
+ * Drizzle ${pascal} Repository
+ *
+ * Implements the repository interface using Drizzle ORM.
+ * Uses buildFromColumns() with Column objects for type-safe query building.
+ *
+ * TODO: Update the schema import to match your Drizzle schema file.
+ * TODO: Replace DRIZZLE_DB injection token with your actual database token.
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { eq, ne, gt, gte, lt, lte, ilike, inArray, between, and, or, asc, desc, count, sql } from 'drizzle-orm'
+import { Repository, HttpException, Inject } from '@forinda/kickjs'
+import { DRIZZLE_DB, DrizzleQueryAdapter } from '@forinda/kickjs-drizzle'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+import { ${pascal.toUpperCase()}_QUERY_CONFIG } from '../../constants'
+
+// TODO: Import your Drizzle schema table — e.g.:
+// import { ${kebab}s } from '@/db/schema'
+
+const queryAdapter = new DrizzleQueryAdapter({
+  eq, ne, gt, gte, lt, lte, ilike, inArray, between, and, or, asc, desc,
+})
+
+@Repository()
+export class Drizzle${pascal}Repository implements I${pascal}Repository {
+  constructor(@Inject(DRIZZLE_DB) private db: any) {}
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    // TODO: Implement with Drizzle
+    // const row = this.db.select().from(${kebab}s).where(eq(${kebab}s.id, id)).get()
+    // return row ?? null
+    throw new Error('Drizzle ${pascal} repository not yet implemented — update schema imports and queries')
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    // TODO: Implement with Drizzle
+    // return this.db.select().from(${kebab}s).all()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    // TODO: Use buildFromColumns() with your query config for type-safe filtering
+    // const query = queryAdapter.buildFromColumns(parsed, ${pascal.toUpperCase()}_QUERY_CONFIG)
+    //
+    // const data = this.db
+    //   .select().from(${kebab}s).$dynamic()
+    //   .where(query.where).orderBy(...query.orderBy)
+    //   .limit(query.limit).offset(query.offset).all()
+    //
+    // const totalResult = this.db
+    //   .select({ count: count() }).from(${kebab}s)
+    //   .$dynamic().where(query.where).get()
+    //
+    // return { data, total: totalResult?.count ?? 0 }
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with Drizzle
+    // return this.db.insert(${kebab}s).values(dto).returning().get()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    // TODO: Implement with Drizzle
+    // const row = this.db.update(${kebab}s).set(dto).where(eq(${kebab}s.id, id)).returning().get()
+    // if (!row) throw HttpException.notFound('${pascal} not found')
+    // return row
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+
+  async delete(id: string): Promise<void> {
+    // TODO: Implement with Drizzle
+    // this.db.delete(${kebab}s).where(eq(${kebab}s.id, id)).run()
+    throw new Error('Drizzle ${pascal} repository not yet implemented')
+  }
+}
+`;
+}
+function generateDrizzleConstants(ctx) {
+	const { pascal, kebab } = ctx;
+	return `import type { DrizzleQueryParamsConfig } from '@forinda/kickjs-drizzle'
+// TODO: Import your schema table and reference actual columns for type safety
+// import { ${kebab}s } from '@/db/schema'
+
+export const ${pascal.toUpperCase()}_QUERY_CONFIG: DrizzleQueryParamsConfig = {
+  columns: {
+    // Replace with actual Drizzle Column references for type-safe filtering:
+    // name: ${kebab}s.name,
+    // status: ${kebab}s.status,
+  },
+  sortable: {
+    // name: ${kebab}s.name,
+    // createdAt: ${kebab}s.createdAt,
+  },
+  searchColumns: [
+    // ${kebab}s.name,
+  ],
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/prisma/index.ts
+function generatePrismaRepository(ctx) {
+	const { pascal, kebab, repoPrefix = "../../domain/repositories", dtoPrefix = "../../application/dtos" } = ctx;
+	const camel = kebab.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+	return `/**
+ * Prisma ${pascal} Repository
+ *
+ * Implements the repository interface using Prisma Client.
+ * Requires a PrismaClient instance injected via the DI container.
+ *
+ * Ensure your Prisma schema has a '${pascal}' model defined.
+ *
+ * For full Prisma field-level type safety, replace PrismaModelDelegate with your PrismaClient:
+ *   @Inject(PRISMA_CLIENT) private prisma!: PrismaClient
+ *
+ * @Repository() registers this class in the DI container as a singleton.
+ */
+import { Repository, HttpException, Inject } from '@forinda/kickjs'
+import { PRISMA_CLIENT, type PrismaModelDelegate } from '@forinda/kickjs-prisma'
+import type { ParsedQuery } from '@forinda/kickjs'
+import type { I${pascal}Repository } from '${repoPrefix}/${kebab}.repository'
+import type { ${pascal}ResponseDTO } from '${dtoPrefix}/${kebab}-response.dto'
+import type { Create${pascal}DTO } from '${dtoPrefix}/create-${kebab}.dto'
+import type { Update${pascal}DTO } from '${dtoPrefix}/update-${kebab}.dto'
+
+@Repository()
+export class Prisma${pascal}Repository implements I${pascal}Repository {
+  @Inject(PRISMA_CLIENT) private prisma!: { ${camel}: PrismaModelDelegate }
+
+  async findById(id: string): Promise<${pascal}ResponseDTO | null> {
+    return this.prisma.${camel}.findUnique({ where: { id } }) as Promise<${pascal}ResponseDTO | null>
+  }
+
+  async findAll(): Promise<${pascal}ResponseDTO[]> {
+    return this.prisma.${camel}.findMany() as Promise<${pascal}ResponseDTO[]>
+  }
+
+  async findPaginated(parsed: ParsedQuery): Promise<{ data: ${pascal}ResponseDTO[]; total: number }> {
+    const [data, total] = await Promise.all([
+      this.prisma.${camel}.findMany({
+        skip: parsed.pagination.offset,
+        take: parsed.pagination.limit,
+      }) as Promise<${pascal}ResponseDTO[]>,
+      this.prisma.${camel}.count(),
+    ])
+    return { data, total }
+  }
+
+  async create(dto: Create${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    return this.prisma.${camel}.create({ data: dto as Record<string, unknown> }) as Promise<${pascal}ResponseDTO>
+  }
+
+  async update(id: string, dto: Update${pascal}DTO): Promise<${pascal}ResponseDTO> {
+    const existing = await this.prisma.${camel}.findUnique({ where: { id } })
+    if (!existing) throw HttpException.notFound('${pascal} not found')
+    return this.prisma.${camel}.update({ where: { id }, data: dto as Record<string, unknown> }) as Promise<${pascal}ResponseDTO>
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.${camel}.deleteMany({ where: { id } })
+  }
+}
+`;
+}
+//#endregion
+//#region src/generators/templates/project-app.ts
+/**
+* Generate src/index.ts entry file with template-specific bootstrap.
+*
+* All templates export the app for the Vite plugin (dev mode).
+* In production, bootstrap() auto-starts the HTTP server when
+* `globalThis.__kickjs_httpServer` is not set.
+*/
+function generateEntryFile(name, template, version) {
+	switch (template) {
+		case "graphql": return `import 'reflect-metadata'
+import { bootstrap } from '@forinda/kickjs'
+import { DevToolsAdapter } from '@forinda/kickjs-devtools'
+import { GraphQLAdapter } from '@forinda/kickjs-graphql'
+import { modules } from './modules'
+
+// Import your resolvers here
+// import { UserResolver } from './resolvers/user.resolver'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({
+  modules,
+  adapters: [
+    new DevToolsAdapter(),
+    new GraphQLAdapter({
+      resolvers: [/* UserResolver */],
+      // Add custom type definitions here:
+      // typeDefs: userTypeDefs,
+    }),
+  ],
+})
+`;
+		case "cqrs": return `import 'reflect-metadata'
+import { bootstrap } from '@forinda/kickjs'
+import { DevToolsAdapter } from '@forinda/kickjs-devtools'
+import { SwaggerAdapter } from '@forinda/kickjs-swagger'
+import { OtelAdapter } from '@forinda/kickjs-otel'
+// import { WsAdapter } from '@forinda/kickjs-ws'
+// import { QueueAdapter, BullMQProvider } from '@forinda/kickjs-queue'
+import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({
+  modules,
+  adapters: [
+    new OtelAdapter({ serviceName: '${name}' }),
+    new DevToolsAdapter(),
+    new SwaggerAdapter({
+      info: { title: '${name}', version: '${version}' },
+    }),
+    // Uncomment for WebSocket support:
+    // new WsAdapter(),
+    // Uncomment when Redis is available:
+    // new QueueAdapter({
+    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),
+    // }),
+  ],
+})
+`;
+		case "minimal": return `import 'reflect-metadata'
+import { bootstrap } from '@forinda/kickjs'
+import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({ modules })
+`;
+		default: return `import 'reflect-metadata'
+import express from 'express'
+import {
+  bootstrap,
+  requestId,
+  requestLogger,
+  helmet,
+  cors,
+} from '@forinda/kickjs'
+import { DevToolsAdapter } from '@forinda/kickjs-devtools'
+import { SwaggerAdapter } from '@forinda/kickjs-swagger'
+import { modules } from './modules'
+
+// Export the app for the Vite plugin (dev mode)
+export const app = await bootstrap({
+  modules,
+  adapters: [
+    new DevToolsAdapter(),
+    new SwaggerAdapter({
+      info: { title: '${name}', version: '${version}' },
+    }),
+  ],
+  middleware: [
+    helmet(),
+    cors({ origin: '*' }),
+    requestId(),
+    requestLogger(),
+    express.json(),
+  ],
+})
+`;
+	}
+}
+/** Generate src/modules/index.ts module registry */
+function generateModulesIndex() {
+	return `import type { AppModuleClass } from '@forinda/kickjs'
+import { HelloModule } from './hello/hello.module'
+
+// Remove HelloModule and run: kick g module <name>
+export const modules: AppModuleClass[] = [HelloModule]
+`;
+}
+/**
+* Generate `src/env.ts` — the project's typed env schema.
+*
+* Default-exports a `defineEnv(...)` schema so `kick typegen` can
+* infer it into the global `KickEnv` registry. After typegen runs:
+*
+*   @Value('DATABASE_URL') private url!: Env<'DATABASE_URL'>
+*   process.env.DATABASE_URL  // typed as string
+*
+* Both autocomplete and type-check at compile time.
+*/
+function generateEnvFile() {
+	return `import { defineEnv } from '@forinda/kickjs-config'
+import { z } from 'zod'
+
+/**
+ * Project environment schema.
+ *
+ * Extend the base schema with your application's variables. The
+ * default export is the contract \`kick typegen\` reads to populate
+ * the global \`KickEnv\` registry — that's what makes \`@Value('FOO')\`
+ * autocomplete and \`process.env.FOO\` typed.
+ *
+ * @example
+ *   DATABASE_URL: z.string().url(),
+ *   JWT_SECRET: z.string().min(32),
+ *   REDIS_URL: z.string().url().optional(),
+ */
+export default defineEnv((base) =>
+  base.extend({
+    // DATABASE_URL: z.string().url(),
+  }),
+)
+`;
+}
+/** Generate src/modules/hello/hello.service.ts */
+function generateHelloService() {
+	return `import { Service } from '@forinda/kickjs'
+
+@Service()
+export class HelloService {
+  greet(name: string) {
+    return { message: \`Hello \${name} from KickJS!\`, timestamp: new Date().toISOString() }
+  }
+
+  healthCheck() {
+    return { status: 'ok', uptime: process.uptime() }
+  }
+}
+`;
+}
+/** Generate src/modules/hello/hello.controller.ts */
+function generateHelloController() {
+	return `import { Controller, Get, Autowired, type Ctx } from '@forinda/kickjs'
+import { HelloService } from './hello.service'
+
+// \`Ctx<KickRoutes.HelloController['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`). The first run after a fresh
+// scaffold creates \`.kickjs/types/routes.ts\` so this file typechecks.
+// See https://forinda.github.io/kick-js/guide/typegen.
+
+@Controller()
+export class HelloController {
+  @Autowired() private readonly helloService!: HelloService
+
+  @Get('/')
+  index(ctx: Ctx<KickRoutes.HelloController['index']>) {
+    ctx.json(this.helloService.greet('World'))
+  }
+
+  @Get('/health')
+  health(ctx: Ctx<KickRoutes.HelloController['health']>) {
+    ctx.json(this.helloService.healthCheck())
+  }
+}
+`;
+}
+/** Generate src/modules/hello/hello.module.ts */
+function generateHelloModule() {
+	return `import { type AppModule, type ModuleRoutes, buildRoutes } from '@forinda/kickjs'
+import { HelloController } from './hello.controller'
+
+export class HelloModule implements AppModule {
+  // \`register(container)\` is optional — only implement it when you need
+  // to bind a token to a concrete implementation, e.g.
+  //   register(container) {
+  //     container.registerFactory(USER_REPOSITORY, () => container.resolve(InMemoryUserRepository))
+  //   }
+  // The HelloService uses @Service() so the decorator handles registration.
+
+  routes(): ModuleRoutes {
+    return {
+      path: '/hello',
+      router: buildRoutes(HelloController),
+      controller: HelloController,
+    }
+  }
+}
+`;
+}
+/** Generate kick.config.ts CLI configuration */
+function generateKickConfig(template, defaultRepo = "inmemory") {
+	return `import { defineConfig } from '@forinda/kickjs-cli'
+
+export default defineConfig({
+  pattern: '${template}',
+  modules: {
+    dir: 'src/modules',
+    repo: ${[
+		"drizzle",
+		"inmemory",
+		"prisma"
+	].includes(defaultRepo) ? `'${defaultRepo}'` : `{ name: '${defaultRepo}' }`},
+    pluralize: true,
+  },
+
+  // \`kick typegen\` populates \`.kickjs/types/\` so \`Ctx<KickRoutes.X['method']>\`
+  // resolves to fully-typed params/body/query. Auto-runs on \`kick dev\`.
+  // Set \`schemaValidator: false\` to skip schema-driven body typing entirely.
+  typegen: {
+    schemaValidator: 'zod',
+  },
+
+  commands: [
+    {
+      name: 'test',
+      description: 'Run tests with Vitest',
+      steps: 'npx vitest run',
+    },
+    {
+      name: 'format',
+      description: 'Format code with Prettier',
+      steps: 'npx prettier --write src/',
+    },
+    {
+      name: 'format:check',
+      description: 'Check formatting without writing',
+      steps: 'npx prettier --check src/',
+    },
+    {
+      name: 'check',
+      description: 'Run typecheck + format check',
+      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
+      aliases: ['verify', 'ci'],
+    },
+  ],
+})
+`;
+}
+//#endregion
+//#region src/generators/patterns/minimal.ts
+async function generateMinimalFiles(ctx) {
+	const { pascal, kebab, plural, write } = ctx;
+	await write("index.ts", generateMinimalModuleIndex({
+		pascal,
+		kebab,
+		plural
+	}));
+	await write(`${kebab}.controller.ts`, `import { Controller, Get, type Ctx } from '@forinda/kickjs'
+
+// \`Ctx<KickRoutes.${pascal}Controller['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`).
+
+@Controller()
+export class ${pascal}Controller {
+  @Get('/')
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    ctx.json({ message: '${pascal} list' })
+  }
+}
+`);
+}
+//#endregion
+//#region src/generators/patterns/rest.ts
+async function generateRestFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noTests, prismaClientPath, write } = ctx;
+	await write("index.ts", generateRestModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write(`${kebab}.constants.ts`, generateRestConstants({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.controller.ts`, generateRestController({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`${kebab}.service.ts`, generateRestService({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab,
+		dtoPrefix: "./dtos"
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos",
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo,
+		repoPrefix: ".",
+		dtoPrefix: "./dtos"
+	}));
+	await write(`${repoFile}.repository.ts`, repoGenerator());
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural,
+			repoPrefix: `../${builtinRepoFileMap.inmemory ?? `in-memory-${kebab}`}.repository`
+		}));
+	}
+}
+//#endregion
+//#region src/generators/patterns/cqrs.ts
+async function generateCqrsFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noTests, prismaClientPath, write } = ctx;
+	await write("index.ts", generateCqrsModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write(`${kebab}.constants.ts`, generateRestConstants({
+		pascal,
+		kebab
+	}));
+	await write(`${kebab}.controller.ts`, generateCqrsController({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	const commands = generateCqrsCommands({
+		pascal,
+		kebab
+	});
+	for (const cmd of commands) await write(`commands/${cmd.file}`, cmd.content);
+	const queries = generateCqrsQueries({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	});
+	for (const q of queries) await write(`queries/${q.file}`, q.content);
+	const events = generateCqrsEvents({
+		pascal,
+		kebab
+	});
+	for (const e of events) await write(`events/${e.file}`, e.content);
+	await write(`${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab,
+		dtoPrefix: "./dtos"
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos",
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo,
+		repoPrefix: ".",
+		dtoPrefix: "./dtos"
+	}));
+	await write(`${repoFile}.repository.ts`, repoGenerator());
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab,
+			repoPrefix: ".",
+			dtoPrefix: "./dtos"
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural,
+			repoPrefix: `../${builtinRepoFileMap.inmemory ?? `in-memory-${kebab}`}.repository`
+		}));
+	}
+}
+//#endregion
+//#region src/generators/patterns/ddd.ts
+async function generateDddFiles(ctx) {
+	const { pascal, kebab, plural, pluralPascal, repo, noEntity, noTests, prismaClientPath, write } = ctx;
+	await write("index.ts", generateModuleIndex({
+		pascal,
+		kebab,
+		plural,
+		repo
+	}));
+	await write("constants.ts", repo === "drizzle" ? generateDrizzleConstants({
+		pascal,
+		kebab
+	}) : generateConstants({
+		pascal,
+		kebab
+	}));
+	await write(`presentation/${kebab}.controller.ts`, generateController$1({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	}));
+	await write(`application/dtos/create-${kebab}.dto.ts`, generateCreateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`application/dtos/update-${kebab}.dto.ts`, generateUpdateDTO({
+		pascal,
+		kebab
+	}));
+	await write(`application/dtos/${kebab}-response.dto.ts`, generateResponseDTO({
+		pascal,
+		kebab
+	}));
+	const useCases = generateUseCases({
+		pascal,
+		kebab,
+		plural,
+		pluralPascal
+	});
+	for (const uc of useCases) await write(`application/use-cases/${uc.file}`, uc.content);
+	await write(`domain/repositories/${kebab}.repository.ts`, generateRepositoryInterface({
+		pascal,
+		kebab
+	}));
+	await write(`domain/services/${kebab}-domain.service.ts`, generateDomainService({
+		pascal,
+		kebab
+	}));
+	const builtinRepoFileMap = {
+		inmemory: `in-memory-${kebab}`,
+		drizzle: `drizzle-${kebab}`,
+		prisma: `prisma-${kebab}`
+	};
+	const builtinRepoGeneratorMap = {
+		inmemory: () => generateInMemoryRepository({
+			pascal,
+			kebab
+		}),
+		drizzle: () => generateDrizzleRepository({
+			pascal,
+			kebab
+		}),
+		prisma: () => generatePrismaRepository({
+			pascal,
+			kebab,
+			prismaClientPath
+		})
+	};
+	const repoFile = builtinRepoFileMap[repo] ?? `${toKebabCase(repo)}-${kebab}`;
+	const repoGenerator = builtinRepoGeneratorMap[repo] ?? (() => generateCustomRepository({
+		pascal,
+		kebab,
+		repoType: repo
+	}));
+	await write(`infrastructure/repositories/${repoFile}.repository.ts`, repoGenerator());
+	if (!noEntity) {
+		await write(`domain/entities/${kebab}.entity.ts`, generateEntity({
+			pascal,
+			kebab
+		}));
+		await write(`domain/value-objects/${kebab}-id.vo.ts`, generateValueObject({
+			pascal,
+			kebab
+		}));
+	}
+	if (!noTests) {
+		if (repo !== "inmemory") await write(`infrastructure/repositories/in-memory-${kebab}.repository.ts`, generateInMemoryRepository({
+			pascal,
+			kebab
+		}));
+		await write(`__tests__/${kebab}.controller.test.ts`, generateControllerTest({
+			pascal,
+			kebab,
+			plural
+		}));
+		await write(`__tests__/${kebab}.repository.test.ts`, generateRepositoryTest({
+			pascal,
+			kebab,
+			plural
+		}));
+	}
+}
+//#endregion
+//#region src/generators/module.ts
+/** Prompt the user for a single-line answer via stdin */
+function promptUser(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim().toLowerCase());
+		});
+	});
+}
+/**
+* Generate a module — structure depends on the project pattern.
+*
+* Patterns:
+*   rest         — flat folder: controller + service + DTOs + repo
+*   ddd          — nested DDD: presentation/ application/ domain/ infrastructure/
+*   graphql      — flat folder: resolver + service + DTOs + repo (future)
+*   cqrs         — commands, queries, events with WS/queue integration
+*   minimal      — just controller + module index
+*/
+async function generateModule(options) {
+	const { name, modulesDir, noEntity, noTests, repo = "inmemory", force, dryRun } = options;
+	const shouldPluralize = options.pluralize !== false;
+	let pattern = options.pattern ?? "ddd";
+	if (options.minimal) pattern = "minimal";
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const plural = shouldPluralize ? pluralize(kebab) : kebab;
+	const pluralPascal = shouldPluralize ? pluralizePascal(pascal) : pascal;
+	const moduleDir = join(modulesDir, plural);
+	const files = [];
+	let overwriteAll = force ?? false;
+	const write = async (relativePath, content) => {
+		const fullPath = join(moduleDir, relativePath);
+		if (dryRun) {
+			files.push(fullPath);
+			return;
+		}
+		if (!overwriteAll && await fileExists(fullPath)) {
+			const answer = await promptUser(`  File already exists: ${relativePath}\n  Overwrite? (y/n/a = yes/no/all) `);
+			if (answer === "a") overwriteAll = true;
+			else if (answer !== "y") {
+				console.log(`  Skipped: ${relativePath}`);
+				return;
+			}
+		}
+		await writeFileSafe(fullPath, content);
+		files.push(fullPath);
+	};
+	const ctx = {
+		kebab,
+		pascal,
+		plural,
+		pluralPascal,
+		moduleDir,
+		repo,
+		noEntity: noEntity ?? false,
+		noTests: noTests ?? false,
+		prismaClientPath: options.prismaClientPath ?? "@prisma/client",
+		write,
+		files
+	};
+	switch (pattern) {
+		case "minimal":
+			await generateMinimalFiles(ctx);
+			break;
+		case "rest":
+			await generateRestFiles(ctx);
+			break;
+		case "cqrs":
+			await generateCqrsFiles(ctx);
+			break;
+		default:
+			await generateDddFiles(ctx);
+			break;
+	}
+	if (!dryRun) await autoRegisterModule(modulesDir, pascal, plural);
+	return files;
+}
+/** Add the new module to src/modules/index.ts */
+async function autoRegisterModule(modulesDir, pascal, plural) {
+	const indexPath = join(modulesDir, "index.ts");
+	if (!await fileExists(indexPath)) {
+		await writeFileSafe(indexPath, `import type { AppModuleClass } from '@forinda/kickjs'
+import { ${pascal}Module } from './${plural}'
+
+export const modules: AppModuleClass[] = [${pascal}Module]
+`);
+		return;
+	}
+	let content = await readFile(indexPath, "utf-8");
+	const importLine = `import { ${pascal}Module } from './${plural}'`;
+	if (!content.includes(`${pascal}Module`)) {
+		const lastImportIdx = content.lastIndexOf("import ");
+		if (lastImportIdx !== -1) {
+			const lineEnd = content.indexOf("\n", lastImportIdx);
+			content = content.slice(0, lineEnd + 1) + importLine + "\n" + content.slice(lineEnd + 1);
+		} else content = importLine + "\n" + content;
+		content = content.replace(/(=\s*\[)([\s\S]*?)(])/, (_match, open, existing, close) => {
+			const trimmed = existing.trim();
+			if (!trimmed) return `${open}${pascal}Module${close}`;
+			const needsComma = trimmed.endsWith(",") ? "" : ",";
+			return `${open}${existing.trimEnd()}${needsComma} ${pascal}Module${close}`;
+		});
+	}
+	await writeFile(indexPath, content, "utf-8");
+}
+//#endregion
+//#region src/generators/adapter.ts
+async function generateAdapter(options) {
+	const { name, outDir } = options;
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.adapter.ts`);
+	await writeFileSafe(filePath, `import type { AppAdapter, AdapterContext, AdapterMiddleware } from '@forinda/kickjs'
+
+export interface ${pascal}AdapterOptions {
+  // Add your adapter configuration here
+}
+
+/**
+ * ${pascal} adapter.
+ *
+ * Hooks into the Application lifecycle to add middleware, routes,
+ * or external service connections.
+ *
+ * Usage:
+ *   bootstrap({
+ *     adapters: [new ${pascal}Adapter({ ... })],
+ *   })
+ */
+export class ${pascal}Adapter implements AppAdapter {
+  name = '${pascal}Adapter'
+
+  constructor(private options: ${pascal}AdapterOptions = {}) {}
+
+  /**
+   * Return middleware entries that the Application will mount.
+   * Use \`phase\` to control where in the pipeline they run:
+   *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'
+   */
+  middleware(): AdapterMiddleware[] {
+    return [
+      // Example: add a custom header to all responses
+      // {
+      //   phase: 'beforeGlobal',
+      //   handler: (_req: any, res: any, next: any) => {
+      //     res.setHeader('X-${pascal}', 'true')
+      //     next()
+      //   },
+      // },
+      // Example: scope middleware to a specific path
+      // {
+      //   phase: 'beforeRoutes',
+      //   path: '/api/v1/admin',
+      //   handler: myAdminMiddleware(),
+      // },
+    ]
+  }
+
+  /**
+   * Called before global middleware.
+   * Use this to mount routes that bypass the middleware stack
+   * (health checks, docs UI, static assets).
+   */
+  beforeMount({ app }: AdapterContext): void {
+    // Example: mount a status route
+    // app.get('/${kebab}/status', (_req, res) => {
+    //   res.json({ status: 'ok' })
+    // })
+  }
+
+  /**
+   * Called after modules and routes are registered, before the server starts.
+   * Use this for late-stage DI registrations or config validation.
+   */
+  beforeStart({ container }: AdapterContext): void {
+    // Example: register a service in the DI container
+    // container.registerInstance(MY_TOKEN, new MyService(this.options))
+  }
+
+  /**
+   * Called after the HTTP server is listening.
+   * Use this to attach to the raw http.Server (Socket.IO, gRPC, etc).
+   */
+  afterStart({ server, container }: AdapterContext): void {
+    // Example: attach Socket.IO
+    // const io = new Server(server)
+    // container.registerInstance(SOCKET_IO, io)
+  }
+
+  /**
+   * Called on graceful shutdown. Clean up connections.
+   */
+  async shutdown(): Promise<void> {
+    // Example: close a connection pool
+    // await this.pool.end()
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/utils/resolve-out-dir.ts
+/**
+* DDD folder mapping — nested layered architecture.
+*/
+const DDD_FOLDER_MAP = {
+	controller: "presentation",
+	service: "domain/services",
+	dto: "application/dtos",
+	guard: "presentation/guards",
+	middleware: "middleware"
+};
+/**
+* Flat folder mapping — REST/GraphQL/minimal patterns.
+* Files live at the module root or in minimal subdirectories.
+*/
+const FLAT_FOLDER_MAP = {
+	controller: "",
+	service: "",
+	dto: "dtos",
+	guard: "guards",
+	middleware: "middleware"
+};
+/**
+* CQRS folder mapping — commands, queries, events.
+*/
+const CQRS_FOLDER_MAP = {
+	controller: "",
+	service: "",
+	dto: "dtos",
+	guard: "guards",
+	middleware: "middleware",
+	command: "commands",
+	query: "queries",
+	event: "events"
+};
+/**
+* Resolve the output directory for a generator artifact.
+*
+* Priority:
+*   1. Explicit --out flag (always wins)
+*   2. --module flag → maps into module's folder (DDD or flat based on pattern)
+*   3. Standalone default directory
+*/
+function resolveOutDir(options) {
+	const { type, outDir, moduleName, modulesDir = "src/modules", defaultDir, pattern = "ddd" } = options;
+	if (outDir) return resolve(outDir);
+	if (moduleName) {
+		const folderMap = pattern === "ddd" ? DDD_FOLDER_MAP : pattern === "cqrs" ? CQRS_FOLDER_MAP : FLAT_FOLDER_MAP;
+		const plural = pluralize(toKebabCase(moduleName));
+		const subfolder = folderMap[type] ?? "";
+		const base = join(modulesDir, plural);
+		return resolve(subfolder ? join(base, subfolder) : base);
+	}
+	return resolve(defaultDir);
+}
+//#endregion
+//#region src/generators/middleware.ts
+async function generateMiddleware(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "middleware",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/middleware",
+		pattern
+	});
+	const kebab = toKebabCase(name);
+	const camel = toCamelCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.middleware.ts`);
+	await writeFileSafe(filePath, `import type { Request, Response, NextFunction } from 'express'
+
+export interface ${toPascalCase(name)}Options {
+  // Add configuration options here
+}
+
+/**
+ * ${toPascalCase(name)} middleware.
+ *
+ * Usage in bootstrap:
+ *   middleware: [${camel}()]
+ *
+ * Usage with adapter:
+ *   middleware() { return [{ handler: ${camel}(), phase: 'afterGlobal' }] }
+ *
+ * Usage with @Middleware decorator:
+ *   @Middleware(${camel}())
+ */
+export function ${camel}(options: ${toPascalCase(name)}Options = {}) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // Implement your middleware logic here
+    next()
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/guard.ts
+async function generateGuard(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "guard",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/guards",
+		pattern
+	});
+	const kebab = toKebabCase(name);
+	const camel = toCamelCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.guard.ts`);
+	await writeFileSafe(filePath, `import { Container, HttpException } from '@forinda/kickjs'
+import type { RequestContext } from '@forinda/kickjs'
+
+/**
+ * ${pascal} guard.
+ *
+ * Guards protect routes by checking conditions before the handler runs.
+ * Return early with an error response to block access.
+ *
+ * Usage:
+ *   @Middleware(${camel}Guard)
+ *   @Get('/protected')
+ *   async handler(ctx: RequestContext) { ... }
+ */
+export async function ${camel}Guard(ctx: RequestContext, next: () => void): Promise<void> {
+  // Example: check for an authorization header
+  const header = ctx.headers.authorization
+  if (!header?.startsWith('Bearer ')) {
+    ctx.res.status(401).json({ message: 'Missing or invalid authorization header' })
+    return
+  }
+
+  const token = header.slice(7)
+
+  try {
+    // Verify the token using a service from the DI container
+    // const container = Container.getInstance()
+    // const authService = container.resolve(AuthService)
+    // const payload = authService.verifyToken(token)
+    // ctx.set('auth', payload)
+
+    next()
+  } catch {
+    ctx.res.status(401).json({ message: 'Invalid or expired token' })
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/service.ts
+async function generateService(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "service",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/services",
+		pattern
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.service.ts`);
+	await writeFileSafe(filePath, `import { Service } from '@forinda/kickjs'
+
+@Service()
+export class ${pascal}Service {
+  // Inject dependencies via constructor
+  // constructor(
+  //   @Inject(MY_REPO) private readonly repo: IMyRepository,
+  // ) {}
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/controller.ts
+async function generateController(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "controller",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/controllers",
+		pattern
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.controller.ts`);
+	await writeFileSafe(filePath, `import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
+
+// \`Ctx<KickRoutes.${pascal}Controller['<method>']>\` is generated by
+// \`kick typegen\` (auto-run on \`kick dev\`). After the first run, your IDE
+// will autocomplete \`ctx.params\`, \`ctx.body\`, and \`ctx.query\`.
+// See https://forinda.github.io/kick-js/guide/typegen for details.
+
+@Controller()
+export class ${pascal}Controller {
+  // @Autowired() private readonly myService!: MyService
+
+  @Get('/')
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
+    ctx.json({ message: '${pascal} list' })
+  }
+
+  @Post('/')
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
+    ctx.created({ message: '${pascal} created', data: ctx.body })
+  }
+}
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/dto.ts
+async function generateDto(options) {
+	const { name, moduleName, modulesDir, pattern } = options;
+	const outDir = resolveOutDir({
+		type: "dto",
+		outDir: options.outDir,
+		moduleName,
+		modulesDir,
+		defaultDir: "src/dtos",
+		pattern
+	});
+	const kebab = toKebabCase(name);
+	const pascal = toPascalCase(name);
+	const camel = toCamelCase(name);
+	const files = [];
+	const filePath = join(outDir, `${kebab}.dto.ts`);
+	await writeFileSafe(filePath, `import { z } from 'zod'
+
+export const ${camel}Schema = z.object({
+  // Define your schema fields here
+  name: z.string().min(1).max(200),
+})
+
+export type ${pascal}DTO = z.infer<typeof ${camel}Schema>
+`);
+	files.push(filePath);
+	return files;
+}
+//#endregion
+//#region src/generators/templates/project-config.ts
+/** Generate package.json with template-aware dependencies */
+function generatePackageJson(name, template, kickjsVersion) {
+	const baseDeps = {
+		"@forinda/kickjs": kickjsVersion,
+		"@forinda/kickjs-config": kickjsVersion,
+		express: "^5.1.0",
+		"reflect-metadata": "^0.2.2",
+		zod: "^4.3.6",
+		pino: "^10.3.1",
+		"pino-pretty": "^13.1.3"
+	};
+	if (template !== "minimal") {
+		baseDeps["@forinda/kickjs-swagger"] = kickjsVersion;
+		baseDeps["@forinda/kickjs-devtools"] = kickjsVersion;
+	}
+	if (template === "graphql") {
+		baseDeps["@forinda/kickjs-graphql"] = kickjsVersion;
+		baseDeps["graphql"] = "^16.11.0";
+	}
+	if (template === "cqrs") {
+		baseDeps["@forinda/kickjs-queue"] = kickjsVersion;
+		baseDeps["@forinda/kickjs-ws"] = kickjsVersion;
+		baseDeps["@forinda/kickjs-otel"] = kickjsVersion;
+	}
+	if (template === "ddd") baseDeps["@forinda/kickjs-swagger"] = kickjsVersion;
+	return JSON.stringify({
+		name,
+		version: kickjsVersion.replace("^", ""),
+		type: "module",
+		scripts: {
+			dev: "vite",
+			"dev:debug": "kick dev:debug",
+			build: "kick build",
+			start: "kick start",
+			test: "vitest run",
+			"test:watch": "vitest",
+			typecheck: "tsc --noEmit",
+			typegen: "kick typegen",
+			lint: "eslint src/",
+			format: "prettier --write src/"
+		},
+		dependencies: baseDeps,
+		devDependencies: {
+			"@forinda/kickjs-cli": kickjsVersion,
+			"@forinda/kickjs-vite": kickjsVersion,
+			"@swc/core": "^1.15.21",
+			"@types/express": "^5.0.6",
+			"@types/node": "^25.0.0",
+			"unplugin-swc": "^1.5.9",
+			vite: "^8.0.3",
+			vitest: "^4.1.2",
+			typescript: "^5.9.2",
+			prettier: "^3.8.1"
+		}
+	}, null, 2);
+}
+/**
+* Generate vite.config.ts with the KickJS Vite plugin.
+*
+* The plugin handles:
+* - SSR environment setup for backend Node.js code
+* - Virtual module generation (virtual:kickjs/app)
+* - Module auto-discovery (scans *.module.ts files)
+* - HMR with selective container invalidation
+* - Express mounting via configureServer() post-hook
+* - httpServer piping to adapters (WsAdapter, Socket.IO, etc.)
+*/
+function generateViteConfig() {
+	return `import { defineConfig } from 'vite'
+import { resolve } from 'node:path'
+import swc from 'unplugin-swc'
+import { kickjsVitePlugin } from '@forinda/kickjs-vite'
+
+export default defineConfig({
+  oxc: false,
+  plugins: [
+    swc.vite(),
+    kickjsVitePlugin({ entry: 'src/index.ts' }),
+  ],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, 'src'),
+    },
+  },
+  ssr: {
+    // Don't bundle pino — its worker-thread transport needs Node.js resolution
+    // to find pino-pretty at runtime for colored log output
+    external: ['pino', 'pino-pretty'],
+  },
+  build: {
+    target: 'node20',
+    ssr: true,
+    outDir: 'dist',
+    sourcemap: true,
+    rollupOptions: {
+      input: resolve(__dirname, 'src/index.ts'),
+      output: { format: 'esm' },
+    },
+  },
+})
+`;
+}
+/** Generate tsconfig.json with decorator support */
+function generateTsConfig() {
+	return JSON.stringify({
+		compilerOptions: {
+			target: "ES2022",
+			module: "ESNext",
+			moduleResolution: "bundler",
+			lib: ["ES2022"],
+			types: ["node", "vite/client"],
+			strict: true,
+			esModuleInterop: true,
+			skipLibCheck: true,
+			sourceMap: true,
+			declaration: true,
+			experimentalDecorators: true,
+			emitDecoratorMetadata: true,
+			outDir: "dist",
+			paths: { "@/*": ["./src/*"] }
+		},
+		include: [
+			"src",
+			".kickjs/types/**/*.d.ts",
+			".kickjs/types/**/*.ts"
+		]
+	}, null, 2);
+}
+/** Generate .prettierrc with project formatting rules */
+function generatePrettierConfig() {
+	return JSON.stringify({
+		semi: false,
+		singleQuote: true,
+		trailingComma: "all",
+		printWidth: 100,
+		tabWidth: 2
+	}, null, 2);
+}
+/** Generate .editorconfig for consistent editor settings */
+function generateEditorConfig() {
+	return `# https://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+`;
+}
+/** Generate .gitignore with common Node.js patterns */
+function generateGitIgnore() {
+	return `node_modules/
+dist/
+.env
+coverage/
+.DS_Store
+*.tsbuildinfo
+.kickjs/
+`;
+}
+/** Generate .gitattributes for consistent line endings */
+function generateGitAttributes() {
+	return `# Auto-detect text files and normalise line endings to LF
+* text=auto eol=lf
+
+# Explicitly mark generated / binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+
+# Lock files — treat as generated
+pnpm-lock.yaml -diff linguist-generated
+yarn.lock -diff linguist-generated
+package-lock.json -diff linguist-generated
+`;
+}
+/** Generate .env file with default environment variables */
+function generateEnv() {
+	return `PORT=3000
+NODE_ENV=development
+`;
+}
+/** Generate .env.example file as a template */
+function generateEnvExample() {
+	return `PORT=3000
+NODE_ENV=development
+`;
+}
+/** Generate vitest.config.ts for test configuration */
+function generateVitestConfig() {
+	return `import { defineConfig } from 'vitest/config'
+import swc from 'unplugin-swc'
+
+export default defineConfig({
+  plugins: [swc.vite()],
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})
+`;
+}
+//#endregion
+//#region src/generators/templates/project-docs.ts
+/** Generate README.md with project documentation */
+function generateReadme(name, template, pm) {
+	const templateLabels = {
+		rest: "REST API",
+		graphql: "GraphQL API",
+		ddd: "Domain-Driven Design",
+		cqrs: "CQRS + Event-Driven",
+		minimal: "Minimal"
+	};
+	const packages = [
+		"@forinda/kickjs",
+		"@forinda/kickjs-vite",
+		"@forinda/kickjs-config"
+	];
+	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
+	if (template === "graphql") packages.push("@forinda/kickjs-graphql");
+	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws", "@forinda/kickjs-otel");
+	return `# ${name}
+
+A **${templateLabels[template] ?? "REST API"}** built with [KickJS](https://forinda.github.io/kick-js/) — a decorator-driven Node.js framework on Express 5 and TypeScript.
+
+## Getting Started
+
+\`\`\`bash
+${pm} install
+kick dev
+\`\`\`
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| \`kick dev\` | Start dev server with Vite HMR |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`${pm} run test\` | Run tests with Vitest |
+| \`kick g module <name>\` | Generate a DDD module |
+| \`kick g scaffold <name> <fields...>\` | Generate CRUD from field definitions |
+| \`kick add <package>\` | Add a KickJS package |
+
+## Project Structure
+
+\`\`\`
+src/
+├── index.ts           # Application entry point
+├── modules/           # Feature modules (controllers, services, repos)
+│   └── index.ts       # Module registry
+└── ...
+\`\`\`
+
+## Packages
+
+${packages.map((p) => `- \`${p}\``).join("\n")}
+
+## Adding Features
+
+\`\`\`bash
+kick add auth          # Authentication (JWT, API key, OAuth)
+kick add swagger       # OpenAPI documentation
+kick add ws            # WebSocket support
+kick add queue         # Background job processing
+kick add mailer        # Email sending
+kick add cron          # Scheduled tasks
+kick add --list        # Show all available packages
+\`\`\`
+
+## Environment Variables
+
+Copy \`.env.example\` to \`.env\` and configure:
+
+| Variable | Default | Description |
+|---|---|---|
+| \`PORT\` | \`3000\` | Server port |
+| \`NODE_ENV\` | \`development\` | Environment |
+
+## Learn More
+
+- [KickJS Documentation](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+`;
+}
+/** Generate CLAUDE.md with AI development guide */
+function generateClaude(name, template, pm) {
+	return `# CLAUDE.md — ${name} Development Guide
+
+## Project Overview
+
+This is a **${{
+		rest: "REST API",
+		graphql: "GraphQL API",
+		ddd: "Domain-Driven Design",
+		cqrs: "CQRS + Event-Driven",
+		minimal: "Minimal Express"
+	}[template] ?? "REST API"}** application built with [KickJS](https://forinda.github.io/kick-js/) — a decorator-driven Node.js framework on Express 5 and TypeScript.
+
+## Quick Commands
+
+\`\`\`bash
+${pm} install           # Install dependencies
+kick dev                # Start dev server with HMR
+kick build              # Production build via Vite
+kick start              # Run production build
+${pm} run test          # Run tests with Vitest
+${pm} run typecheck     # TypeScript type checking
+${pm} run format        # Format code with Prettier
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+src/
+├── index.ts           # Application bootstrap
+├── modules/           # Feature modules (DDD/CQRS pattern)
+│   └── index.ts       # Module registry
+${template === "graphql" ? "├── resolvers/         # GraphQL resolvers\n" : ""}└── ...
+\`\`\`
+
+## Package Manager
+
+- Always use **${pm}** for this project
+- Run \`${pm} install\` to sync dependencies
+- Never mix package managers (npm/yarn/pnpm)
+
+## Code Style
+
+- **Prettier** — no semicolons, single quotes, trailing commas, 100 char width
+- **TypeScript strict mode** — all types required
+- Format before committing: \`${pm} run format\`
+- Type check with: \`${pm} run typecheck\`
+
+## Key Patterns
+
+### Controllers
+
+Use decorators to define routes. Annotate \`ctx\` with \`Ctx<KickRoutes.X['method']>\`
+to get fully-typed \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` from the
+generated \`KickRoutes\` namespace (refreshed on \`kick dev\` and \`kick typegen\`).
+
+\`\`\`ts
+import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
+
+@Controller('/users')
+export class UserController {
+  @Get('/')
+  async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
+    return ctx.json({ users: [] })
+  }
+
+  @Post('/')
+  async create(ctx: Ctx<KickRoutes.UserController['create']>) {
+    const data = ctx.body
+    return ctx.created({ user: data })
+  }
+}
+\`\`\`
+
+### Services
+
+Inject dependencies with \`@Service()\` and \`@Autowired()\`:
+
+\`\`\`ts
+import { Service, Autowired } from '@forinda/kickjs'
+
+@Service()
+export class UserService {
+  @Autowired()
+  private userRepository!: UserRepository
+
+  async findAll() {
+    return this.userRepository.findAll()
+  }
+}
+\`\`\`
+
+### Modules
+
+Register controllers and providers in modules:
+
+\`\`\`ts
+import { Module } from '@forinda/kickjs'
+import { UserController } from './user.controller'
+import { UserService } from './user.service'
+
+@Module({
+  controllers: [UserController],
+  providers: [UserService],
+})
+export class UserModule {}
+\`\`\`
+
+### RequestContext
+
+Every controller method receives a \`ctx\` (alias \`Ctx<TRoute>\` or the
+loose \`RequestContext\`):
+
+\`\`\`ts
+ctx.body           // Request body (parsed JSON)
+ctx.params         // Route params
+ctx.query          // Query string
+ctx.headers        // Request headers
+ctx.requestId      // Auto-generated request ID
+ctx.session        // Session data (if session middleware enabled)
+ctx.file           // Uploaded file (single)
+ctx.files          // Uploaded files (multiple)
+
+// Pagination helpers
+ctx.qs(config)           // Parse query with filters/sort/pagination
+ctx.paginate(handler)     // Auto-paginated response
+
+// Response helpers
+ctx.json(data)            // 200 OK with JSON
+ctx.created(data)         // 201 Created
+ctx.noContent()           // 204 No Content
+ctx.notFound()            // 404 Not Found
+ctx.badRequest(msg)       // 400 Bad Request
+\`\`\`
+
+## CLI Generators
+
+Generate code with the \`kick\` CLI:
+
+\`\`\`bash
+kick g module <name>              # Full module (controller, service, DTOs, repo)
+kick g scaffold <name> <fields>   # CRUD module from field definitions
+kick g controller <name>          # Standalone controller
+kick g service <name>             # Service class
+kick g middleware <name>          # Express middleware
+kick g guard <name>               # Route guard (auth, roles)
+kick g adapter <name>             # AppAdapter with lifecycle hooks
+kick g dto <name>                 # Zod DTO schema
+${template === "graphql" ? "kick g resolver <name>           # GraphQL resolver\n" : ""}${template === "cqrs" ? "kick g job <name>                # Queue job processor\n" : ""}\`\`\`
+
+## Adding Packages
+
+\`\`\`bash
+kick add auth          # JWT, API key, OAuth strategies
+kick add swagger       # OpenAPI docs from decorators
+kick add ws            # WebSocket support
+kick add queue         # Background jobs (BullMQ/RabbitMQ/Kafka)
+kick add mailer        # Email (SMTP, Resend, SES)
+kick add cron          # Scheduled tasks
+kick add prisma        # Prisma ORM adapter
+kick add drizzle       # Drizzle ORM adapter
+kick add otel          # OpenTelemetry tracing
+kick add --list        # Show all available packages
+\`\`\`
+
+## Environment Configuration
+
+Edit \`.env\` for environment variables. Access them with \`@Value()\` decorator:
+
+\`\`\`ts
+import { Value } from '@forinda/kickjs-config'
+
+@Service()
+export class ApiService {
+  @Value('API_KEY')
+  private apiKey!: string
+
+  @Value('PORT', 3000)  // With default
+  private port!: number
+}
+\`\`\`
+
+Or use \`ConfigService\`:
+
+\`\`\`ts
+import { ConfigService } from '@forinda/kickjs-config'
+
+@Service()
+export class AppService {
+  @Autowired()
+  private config!: ConfigService
+
+  getPort() {
+    return this.config.get('PORT', 3000)
+  }
+}
+\`\`\`
+
+## Testing
+
+Tests live in \`src/**/*.test.ts\`:
+
+\`\`\`ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Container } from '@forinda/kickjs'
+import { createTestApp } from '@forinda/kickjs-testing'
+
+describe('UserController', () => {
+  beforeEach(() => Container.reset())
+
+  it('should return users', async () => {
+    const app = await createTestApp([UserModule])
+    const res = await app.get('/users')
+    expect(res.status).toBe(200)
+  })
+})
+\`\`\`
+
+Run tests:
+- \`${pm} run test\` — run all tests
+- \`${pm} run test:watch\` — watch mode
+
+## Decorators Reference
+
+### Route Decorators
+- \`@Controller('/path')\` — define controller prefix
+- \`@Get('/'), @Post('/'), @Put('/'), @Delete('/'), @Patch('/')\` — HTTP methods
+- \`@Middleware(fn)\` — attach middleware
+- \`@Public()\` — skip authentication (requires @forinda/kickjs-auth)
+- \`@Roles('admin', 'user')\` — role-based access control
+
+### DI Decorators
+- \`@Module({ controllers, providers, imports })\` — define module
+- \`@Service()\` — singleton service (DI-registered)
+- \`@Repository()\` — repository (semantic alias for @Service)
+- \`@Autowired()\` — property injection
+- \`@Inject('token')\` — token-based injection
+- \`@Value('ENV_VAR')\` — inject config value
+
+${template === "cqrs" ? `### CQRS/Event Decorators
+- \`@Job('job-name')\` — queue job handler
+- \`@Process('queue-name')\` — queue processor
+- \`@Cron('0 * * * *')\` — cron schedule
+- \`@WsController('/path')\` — WebSocket controller
+- \`@Subscribe('event')\` — WebSocket event handler
+
+` : ""}${template === "graphql" ? `### GraphQL Decorators
+- \`@Resolver()\` — GraphQL resolver
+- \`@Query()\` — GraphQL query
+- \`@Mutation()\` — GraphQL mutation
+- \`@Arg('name')\` — resolver argument
+
+` : ""}## Common Pitfalls
+
+1. **Decorators fire at import time** — make sure to import module classes in \`src/modules/index.ts\`
+2. **Tests need \`Container.reset()\`** — call in \`beforeEach\` to isolate DI state
+3. **Always use \`ctx.body\`** — never \`req.body\` directly
+4. **DI requires \`reflect-metadata\`** — already imported in \`src/index.ts\`
+5. **Vite HMR requires proper cleanup** — adapters should implement \`shutdown()\`
+
+## Learn More
+
+- [KickJS Documentation](https://forinda.github.io/kick-js/)
+- [API Reference](https://forinda.github.io/kick-js/api/)
+- [CLI Commands](https://forinda.github.io/kick-js/guide/cli-commands.html)
+- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
+`;
+}
+/** Generate AGENTS.md with AI agent guide */
+function generateAgents(name, template, pm) {
+	return `# AGENTS.md — AI Agent Guide for ${name}
+
+This guide helps AI agents (Claude, Copilot, etc.) work effectively on this KickJS application.
+
+## Before You Start
+
+1. Read \`CLAUDE.md\` for project conventions and commands
+2. Run \`${pm} install\` to install dependencies
+3. Run \`kick dev\` to verify the app starts
+4. Read the [KickJS documentation](https://forinda.github.io/kick-js/) for framework details
+
+## Where to Find Things
+
+### Application Structure
+
+| What | Where |
+|------|-------|
+| Entry point | \`src/index.ts\` |
+| Module registry | \`src/modules/index.ts\` |
+| Feature modules | \`src/modules/<module-name>/\` |
+${template === "graphql" ? "| GraphQL resolvers | `src/resolvers/` |\n" : ""}| Environment config | \`.env\` |
+| TypeScript config | \`tsconfig.json\` |
+| Vite config (HMR) | \`vite.config.ts\` |
+| Vitest config | \`vitest.config.ts\` |
+| Prettier config | \`.prettierrc\` |
+| CLI config | \`kick.config.ts\` |
+
+### Module Pattern (${template.toUpperCase()})
+
+Each module in \`src/modules/<name>/\` typically contains:
+
+${template === "ddd" ? `\`\`\`
+<name>/
+├── <name>.controller.ts     # HTTP routes (@Controller)
+├── <name>.service.ts        # Business logic (@Service)
+├── <name>.repository.ts     # Data access (@Repository)
+├── <name>.dto.ts            # Request/response schemas (Zod)
+├── <name>.entity.ts         # Domain entity (optional)
+└── <name>.module.ts         # Module definition (@Module)
+\`\`\`
+` : template === "cqrs" ? `\`\`\`
+<name>/
+├── commands/                # Write operations
+│   ├── create-<name>.command.ts
+│   └── create-<name>.handler.ts
+├── queries/                 # Read operations
+│   ├── get-<name>.query.ts
+│   └── get-<name>.handler.ts
+├── events/                  # Domain events
+│   └── <name>-created.event.ts
+├── <name>.controller.ts     # HTTP routes
+├── <name>.repository.ts     # Data access
+└── <name>.module.ts         # Module definition
+\`\`\`
+` : template === "graphql" ? `\`\`\`
+resolvers/
+├── <name>.resolver.ts       # @Resolver, @Query, @Mutation
+├── <name>.types.ts          # GraphQL type definitions
+└── <name>.service.ts        # Business logic
+\`\`\`
+` : template === "rest" ? `\`\`\`
+<name>/
+├── <name>.controller.ts     # HTTP routes (@Controller)
+├── <name>.service.ts        # Business logic (@Service)
+├── <name>.dto.ts            # Request/response schemas (Zod)
+└── <name>.module.ts         # Module definition (@Module)
+\`\`\`
+` : `\`\`\`
+src/
+├── index.ts                 # Add routes here
+└── ...                      # Custom structure
+\`\`\`
+`}
+
+## Checklist: Adding a Feature
+
+### New Module (Recommended)
+
+Use the CLI generator for consistency:
+
+\`\`\`bash
+kick g module <name>              # Generate full module
+# or
+kick g scaffold <name> <fields>   # Generate CRUD from fields
+\`\`\`
+
+Then:
+- [ ] Review generated files in \`src/modules/<name>/\`
+- [ ] Verify module is registered in \`src/modules/index.ts\`
+- [ ] Update DTOs in \`<name>.dto.ts\` if needed
+- [ ] Implement business logic in \`<name>.service.ts\`
+- [ ] Run \`kick dev\` to test with HMR
+- [ ] Write tests in \`<name>.test.ts\`
+
+### Manual Controller
+
+If not using generators:
+
+- [ ] Create \`src/modules/<name>/<name>.controller.ts\`
+- [ ] Add \`@Controller('/path')\` decorator
+- [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
+- [ ] Create module file with \`@Module({ controllers: [NameController] })\`
+- [ ] Register module in \`src/modules/index.ts\`
+- [ ] Test with \`kick dev\`
+
+### Manual Service
+
+- [ ] Create \`src/modules/<name>/<name>.service.ts\`
+- [ ] Add \`@Service()\` decorator
+- [ ] Inject dependencies with \`@Autowired()\`
+- [ ] Register in module \`providers\` array
+- [ ] Write unit tests
+
+### New Middleware
+
+- [ ] Create \`src/middleware/<name>.middleware.ts\`
+- [ ] Export middleware function (Express format)
+- [ ] Register in \`src/index.ts\` or attach to routes with \`@Middleware()\`
+- [ ] Test with sample requests
+
+### Adding a Package
+
+Use \`kick add\` to install KickJS packages with correct peer dependencies:
+
+- [ ] Run \`kick add <package>\` (e.g., \`kick add auth\`)
+- [ ] Follow package-specific setup in terminal output
+- [ ] Update \`src/index.ts\` to register adapter (if needed)
+- [ ] Configure environment variables in \`.env\`
+- [ ] Test integration with \`kick dev\`
+
+## Common Tasks
+
+### Generate CRUD Module
+
+\`\`\`bash
+kick g scaffold user name:string email:string age:number
+\`\`\`
+
+This creates a full CRUD module with:
+- Controller with GET, POST, PUT, DELETE routes
+- Service with business logic
+- Repository with data access
+- DTOs with Zod validation
+
+### Add Authentication
+
+\`\`\`bash
+kick add auth
+\`\`\`
+
+Then configure in \`src/index.ts\`:
+
+\`\`\`ts
+import { AuthAdapter, JwtStrategy } from '@forinda/kickjs-auth'
+
+bootstrap({
+  modules,
+  adapters: [
+    new AuthAdapter({
+      strategies: [new JwtStrategy({ secret: process.env.JWT_SECRET! })],
+    }),
+  ],
+})
+\`\`\`
+
+### Add Database (Prisma)
+
+\`\`\`bash
+kick add prisma
+${pm} install prisma @prisma/client
+npx prisma init
+# Edit prisma/schema.prisma
+npx prisma migrate dev --name init
+kick g module user --repo prisma
+\`\`\`
+
+### Add WebSocket Support
+
+\`\`\`bash
+kick add ws
+\`\`\`
+
+Then add adapter in \`src/index.ts\`:
+
+\`\`\`ts
+import { WsAdapter } from '@forinda/kickjs-ws'
+
+bootstrap({
+  modules,
+  adapters: [new WsAdapter()],
+})
+\`\`\`
+
+Create WebSocket controller:
+
+\`\`\`bash
+kick g controller chat --ws
+\`\`\`
+
+## Testing Guidelines
+
+All tests use Vitest:
+
+\`\`\`ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { Container } from '@forinda/kickjs'
+import { createTestApp } from '@forinda/kickjs-testing'
+
+describe('UserController', () => {
+  beforeEach(() => {
+    Container.reset()  // Important: isolate DI state
+  })
+
+  it('should return users', async () => {
+    const app = await createTestApp([UserModule])
+    const res = await app.get('/users')
+    
+    expect(res.status).toBe(200)
+    expect(res.body).toHaveProperty('users')
+  })
+})
+\`\`\`
+
+Run tests:
+- \`${pm} run test\` — run all tests once
+- \`${pm} run test:watch\` — watch mode
+- Individual file: \`${pm} run test src/modules/user/user.test.ts\`
+
+## Environment Variables
+
+Managed via \`.env\` file. Access with:
+
+1. **@Value() decorator** (recommended):
+\`\`\`ts
+@Value('DATABASE_URL')
+private dbUrl!: string
+\`\`\`
+
+2. **ConfigService** (for dynamic access):
+\`\`\`ts
+@Autowired()
+private config!: ConfigService
+
+const port = this.config.get('PORT', 3000)
+\`\`\`
+
+3. **Direct access** (avoid in app code):
+\`\`\`ts
+process.env.PORT
+\`\`\`
+
+## Key Decorators
+
+### HTTP Routes
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Controller('/path')\` | Define route prefix |
+| \`@Get('/'), @Post('/')\` | HTTP method handlers |
+| \`@Middleware(fn)\` | Attach middleware |
+| \`@Public()\` | Skip auth (requires auth adapter) |
+| \`@Roles('admin')\` | Role-based access |
+
+### Dependency Injection
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Module({})\` | Define feature module |
+| \`@Service()\` | Register singleton service |
+| \`@Repository()\` | Register repository |
+| \`@Autowired()\` | Property injection |
+| \`@Inject('token')\` | Token-based injection |
+| \`@Value('VAR')\` | Inject env variable |
+
+${template === "graphql" ? `### GraphQL
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Resolver()\` | GraphQL resolver class |
+| \`@Query()\` | Query handler |
+| \`@Mutation()\` | Mutation handler |
+| \`@Arg('name')\` | Resolver argument |
+
+` : ""}${template === "cqrs" ? `### Background Jobs
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Job('name')\` | Queue job handler |
+| \`@Process('queue')\` | Queue processor |
+| \`@Cron('0 * * * *')\` | Cron schedule |
+| \`@WsController()\` | WebSocket controller |
+
+` : ""}## Common Pitfalls
+
+1. **Forgot to register module** — Add to \`src/modules/index.ts\` exports array
+2. **DI not working** — Ensure \`reflect-metadata\` is imported in \`src/index.ts\`
+3. **Tests failing randomly** — Missing \`Container.reset()\` in \`beforeEach\`
+4. **Routes not found** — Check controller path and module registration
+5. **HMR not working** — Verify \`vite.config.ts\` has \`hmr: true\`
+6. **Decorators not working** — Check \`tsconfig.json\` has \`experimentalDecorators: true\`
+
+## CLI Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| \`kick dev\` | Dev server with HMR |
+| \`kick dev:debug\` | Dev server with debugger |
+| \`kick build\` | Production build |
+| \`kick start\` | Run production build |
+| \`kick g module <names...>\` | Generate one or more modules |
+| \`kick g scaffold <name> <fields>\` | Generate CRUD |
+| \`kick g controller <name>\` | Generate controller |
+| \`kick g service <name>\` | Generate service |
+| \`kick g middleware <name>\` | Generate middleware |
+| \`kick add <package>\` | Add KickJS package |
+| \`kick add --list\` | List available packages |
+| \`kick rm module <names...>\` | Remove one or more modules |
+
+> **Note:** When using \`kick new\` in scripts or CI, pass \`-t\` (or \`--template\`) and \`-r\` (or \`--repo\`) flags to bypass interactive prompts:
+> \`\`\`bash
+> kick new my-api -t ddd -r prisma --pm ${pm} --no-git --no-install -f
+> \`\`\`
+
+## Learn More
+
+- [KickJS Docs](https://forinda.github.io/kick-js/)
+- [CLI Reference](https://forinda.github.io/kick-js/api/cli.html)
+- [Decorators Guide](https://forinda.github.io/kick-js/guide/decorators.html)
+- [DI System](https://forinda.github.io/kick-js/guide/dependency-injection.html)
+- [Testing](https://forinda.github.io/kick-js/api/testing.html)
+`;
+}
+//#endregion
+//#region src/generators/project.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const KICKJS_VERSION = `^${cliPkg.version}`;
+/** Scaffold a new KickJS project */
+async function initProject(options) {
+	const { name, directory, packageManager = "pnpm", template = "rest", defaultRepo = "inmemory" } = options;
+	const dir = directory;
+	const log = (msg) => console.log(`  ${msg}`);
+	console.log(`\n  Creating KickJS project: ${name}\n`);
+	await writeFileSafe(join(dir, "package.json"), generatePackageJson(name, template, KICKJS_VERSION));
+	await writeFileSafe(join(dir, "vite.config.ts"), generateViteConfig());
+	await writeFileSafe(join(dir, "tsconfig.json"), generateTsConfig());
+	await writeFileSafe(join(dir, ".prettierrc"), generatePrettierConfig());
+	await writeFileSafe(join(dir, ".editorconfig"), generateEditorConfig());
+	await writeFileSafe(join(dir, ".gitignore"), generateGitIgnore());
+	await writeFileSafe(join(dir, ".gitattributes"), generateGitAttributes());
+	await writeFileSafe(join(dir, ".env"), generateEnv());
+	await writeFileSafe(join(dir, ".env.example"), generateEnvExample());
+	await writeFileSafe(join(dir, "src/env.ts"), generateEnvFile());
+	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version));
+	await writeFileSafe(join(dir, "src/modules/index.ts"), generateModulesIndex());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.controller.ts"), generateHelloController());
+	await writeFileSafe(join(dir, "src/modules/hello/hello.module.ts"), generateHelloModule());
+	if (template === "graphql") await writeFileSafe(join(dir, "src/resolvers/.gitkeep"), "");
+	await writeFileSafe(join(dir, "kick.config.ts"), generateKickConfig(template, defaultRepo));
+	await writeFileSafe(join(dir, "vitest.config.ts"), generateVitestConfig());
+	await writeFileSafe(join(dir, "README.md"), generateReadme(name, template, packageManager));
+	await writeFileSafe(join(dir, "CLAUDE.md"), generateClaude(name, template, packageManager));
+	await writeFileSafe(join(dir, "AGENTS.md"), generateAgents(name, template, packageManager));
+	if (options.initGit) try {
+		execSync("git init", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git branch -M main", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git add -A", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		execSync("git commit -m \"chore: initial commit from kick new\"", {
+			cwd: dir,
+			stdio: "pipe"
+		});
+		log("Git repository initialized");
+	} catch {
+		log("Warning: git init failed (git may not be installed)");
+	}
+	if (options.installDeps) {
+		console.log(`\n  Installing dependencies with ${packageManager}...\n`);
+		try {
+			execSync(`${packageManager} install`, {
+				cwd: dir,
+				stdio: "inherit"
+			});
+			console.log("\n  Dependencies installed successfully!");
+		} catch {
+			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
+		}
+	}
+	try {
+		const { runTypegen } = await import("./typegen-DCnJdqP1.mjs");
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
+	console.log("\n  Project scaffolded successfully!");
+	console.log();
+	const needsCd = dir !== process.cwd();
+	log("Next steps:");
+	if (needsCd) log(`  cd ${name}`);
+	if (!options.installDeps) log(`  ${packageManager} install`);
+	const genHint = {
+		rest: "kick g module user",
+		graphql: "kick g resolver user",
+		ddd: "kick g module user --repo drizzle",
+		cqrs: "kick g module user --pattern cqrs",
+		minimal: "# add your routes to src/index.ts"
+	};
+	log(`  ${genHint[template] ?? genHint.rest}`);
+	log("  kick dev");
+	log("");
+	log("Commands:");
+	log("  kick dev                  Start dev server with Vite HMR");
+	log("  kick build                Production build via Vite");
+	log("  kick start                Run production build");
+	log("");
+	log("Generators:");
+	log("  kick g module <name>      Full DDD module (controller, DTOs, use-cases, repo)");
+	log("  kick g scaffold <n> <f..> CRUD module from field definitions");
+	log("  kick g controller <name>  Standalone controller");
+	log("  kick g service <name>     @Service() class");
+	log("  kick g middleware <name>   Express middleware");
+	log("  kick g guard <name>       Route guard (auth, roles, etc.)");
+	log("  kick g adapter <name>     AppAdapter with lifecycle hooks");
+	log("  kick g dto <name>         Zod DTO schema");
+	if (template === "graphql") log("  kick g resolver <name>    GraphQL resolver");
+	if (template === "cqrs") log("  kick g job <name>         Queue job processor");
+	log("  kick g config             Generate kick.config.ts");
+	log("");
+	log("Add packages:");
+	log("  kick add <pkg>            Install a KickJS package + peers");
+	log("  kick add --list           Show all available packages");
+	log("");
+	log("Available: auth, swagger, graphql, drizzle, prisma, ws,");
+	log("           cron, queue, mailer, otel, multi-tenant, notifications, testing");
+	log("");
+}
+//#endregion
+//#region src/config.ts
+/** Helper to define a type-safe kick.config.ts */
+function defineConfig(config) {
+	return config;
+}
+const CONFIG_FILES = [
+	"kick.config.ts",
+	"kick.config.js",
+	"kick.config.mjs",
+	"kick.config.json"
+];
+/** Load kick.config.* from the project root */
+async function loadKickConfig(cwd) {
+	for (const filename of CONFIG_FILES) {
+		const filepath = join(cwd, filename);
+		try {
+			await access(filepath);
+		} catch {
+			continue;
+		}
+		if (filename.endsWith(".json")) {
+			const content = await readFile(filepath, "utf-8");
+			return JSON.parse(content);
+		}
+		try {
+			const { pathToFileURL } = await import("node:url");
+			const mod = await import(pathToFileURL(filepath).href);
+			return mod.default ?? mod;
+		} catch (err) {
+			if (filename.endsWith(".ts")) console.warn(`Warning: Failed to load ${filename}. TypeScript config files require a runtime loader (e.g. tsx, ts-node) or use kick.config.js/.mjs instead.`);
+			continue;
+		}
+	}
+	return null;
+}
+//#endregion
+export { defineConfig, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
+
+//# sourceMappingURL=index.mjs.map