@forinda/kickjs-cli 5.0.2 → 5.2.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v5.0.2
+ * @forinda/kickjs-cli v5.2.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,4161 +8,7 @@
  *
  * @license MIT
  */
-import { createRequire } from "node:module";
-import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import * as clack from "@clack/prompts";
-import pc from "picocolors";
-import pkg from "pluralize";
-import { execSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-/** Extensions prettier can format. Anything else is written verbatim. */
-const FORMATTABLE = new Set([
-	".ts",
-	".tsx",
-	".js",
-	".jsx",
-	".mjs",
-	".cjs",
-	".json",
-	".md"
-]);
-/**
-* Write a file, creating parent directories if needed.
-*
-* After write, runs prettier against the file when:
-*   - format-on-write is enabled (default)
-*   - the extension is in {@link FORMATTABLE}
-*   - prettier resolves from the user's project (or our own cwd)
-*
-* Failures (missing prettier, unparseable source, prettier crash) are
-* swallowed silently — formatting is a polish step, not a correctness
-* gate. The pre-existing pre-commit hook still catches anything we
-* couldn't format.
-*
-* Skips writing entirely in dry run mode.
-*/
-async function writeFileSafe(filePath, content) {
-	await mkdir(dirname(filePath), { recursive: true });
-	await writeFile(filePath, content, "utf-8");
-	if (FORMATTABLE.has(extname(filePath))) await formatFile(filePath, content).catch(() => {});
-}
-let _prettier = void 0;
-/** Resolve prettier from the user's project; cache the result (or null) for the process. */
-function resolvePrettier(cwd) {
-	if (_prettier !== void 0) return _prettier;
-	try {
-		_prettier = createRequire(join(cwd, "package.json"))("prettier");
-	} catch {
-		_prettier = null;
-	}
-	return _prettier;
-}
-async function formatFile(filePath, content) {
-	const prettier = resolvePrettier(process.cwd());
-	if (!prettier) return;
-	if ((await prettier.getFileInfo(filePath, { resolveConfig: true })).ignored) return;
-	const config = await prettier.resolveConfig(filePath) ?? {};
-	const formatted = await prettier.format(content, {
-		...config,
-		filepath: filePath
-	});
-	if (formatted === content) return;
-	await writeFile(filePath, formatted, "utf-8");
-}
-/** Check if a file exists */
-async function fileExists(filePath) {
-	try {
-		await access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-pc.green, pc.cyan, pc.yellow, pc.magenta, pc.red;
-pc.green("✓"), pc.red("✖"), pc.yellow("⚠"), pc.blue("ℹ");
-/** Handle cancellation — print message and exit */
-function handleCancel(value) {
-	if (clack.isCancel(value)) {
-		clack.cancel("Operation cancelled.");
-		process.exit(0);
-	}
-}
-/** Yes/no confirmation prompt */
-async function confirm(opts) {
-	const value = await clack.confirm(opts);
-	handleCancel(value);
-	return value;
-}
-/** Log utilities for styled messages inside clack flow */
-const log = clack.log;
-//#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.
-* Uses the `pluralize` npm package for correct English pluralization
-* including irregulars (person → people, status → statuses, child → children).
-*/
-function pluralize(name) {
-	return pkg.plural(name);
-}
-/**
-* Pluralize a PascalCase name for class identifiers.
-* Used for `List${pluralPascal}UseCase` to avoid `ListUserssUseCase`.
-*/
-function pluralizePascal(name) {
-	return pkg.plural(name);
-}
-//#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>('app/${kebab}/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, packages = []) {
-	switch (template) {
-		case "cqrs": {
-			const cqrsImports = [];
-			const cqrsAdapters = [];
-			if (packages.includes("devtools")) {
-				cqrsImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				cqrsAdapters.push(`    DevToolsAdapter(),`);
-			}
-			if (packages.includes("swagger")) {
-				cqrsImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				cqrsAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
-			}
-			return `import 'reflect-metadata'
-// Side-effect import — registers the extended env schema with kickjs
-// **before** any controller / service / @Value gets resolved. Without
-// this line ConfigService.get('YOUR_KEY') returns undefined because the
-// cached schema would still be the base shape. See guide/configuration.
-import './config'
-import { bootstrap } from '@forinda/kickjs'
-// import { WsAdapter } from '@forinda/kickjs-ws'
-// import { QueueAdapter, BullMQProvider } from '@forinda/kickjs-queue'
-${cqrsImports.length ? cqrsImports.join("\n") + "\n" : ""}import { modules } from './modules'
-
-// Export the app for the Vite plugin (dev mode)
-export const app = await bootstrap({
-  modules,${cqrsImports.length ? `\n  adapters: [\n${cqrsAdapters.join("\n")}\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],` : `\n  adapters: [\n    // Uncomment for WebSocket support:\n    // WsAdapter(),\n    // Uncomment when Redis is available:\n    // QueueAdapter({\n    //   provider: new BullMQProvider({ host: 'localhost', port: 6379 }),\n    // }),\n  ],`}
-})
-`;
-		}
-		case "minimal": {
-			const imports = [];
-			const adapters = [];
-			if (packages.includes("swagger")) {
-				imports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				adapters.push(`    SwaggerAdapter({ info: { title: '${name}', version: '${version}' } }),`);
-			}
-			if (packages.includes("devtools")) {
-				imports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				adapters.push(`    DevToolsAdapter(),`);
-			}
-			return `import 'reflect-metadata'
-// Side-effect import — registers the extended env schema with kickjs
-// **before** any controller / service / @Value gets resolved. Without
-// this line ConfigService.get('YOUR_KEY') returns undefined because the
-// cached schema would still be the base shape. See guide/configuration.
-import './config'
-import { bootstrap } from '@forinda/kickjs'
-${imports.length ? imports.join("\n") + "\n" : ""}import { modules } from './modules'
-
-// Export the app for the Vite plugin (dev mode)
-export const app = await bootstrap({ modules${adapters.length ? `,\n  adapters: [\n${adapters.join("\n")}\n  ]` : ""} })
-`;
-		}
-		default: {
-			const restImports = [];
-			const restAdapters = [];
-			if (packages.includes("devtools")) {
-				restImports.push(`import { DevToolsAdapter } from '@forinda/kickjs-devtools'`);
-				restAdapters.push(`    DevToolsAdapter(),`);
-			}
-			if (packages.includes("swagger")) {
-				restImports.push(`import { SwaggerAdapter } from '@forinda/kickjs-swagger'`);
-				restAdapters.push(`    SwaggerAdapter({\n      info: { title: '${name}', version: '${version}' },\n    }),`);
-			}
-			return `import 'reflect-metadata'
-// Side-effect import — registers the extended env schema with kickjs
-// **before** any controller / service / @Value gets resolved. Without
-// this line ConfigService.get('YOUR_KEY') returns undefined because the
-// cached schema would still be the base shape. See guide/configuration.
-import './config'
-import express from 'express'
-import {
-  bootstrap,
-  requestId,
-  requestLogger,
-  helmet,
-  cors,
-} from '@forinda/kickjs'
-${restImports.length ? restImports.join("\n") + "\n" : ""}import { modules } from './modules'
-
-// Export the app for the Vite plugin (dev mode)
-export const app = await bootstrap({
-  modules,${restAdapters.length ? `\n  adapters: [\n${restAdapters.join("\n")}\n  ],` : ""}
-  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/config/index.ts` — the project's typed env schema.
-*
-* Default-exports a `defineEnv(...)` schema so `kick typegen` can
-* infer it into the global `KickEnv` registry, and *also* calls
-* `loadEnv(envSchema)` as a module-load side effect so `ConfigService`
-* and `@Value()` see the extended shape from the very first DI
-* resolution. The companion `src/index.ts` template adds
-* `import './config'` immediately after `reflect-metadata` so the
-* registration runs before `bootstrap()` constructs anything.
-*
-* 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, loadEnv } 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(),
- */
-const envSchema = defineEnv((base) =>
-  base.extend({
-    // DATABASE_URL: z.string().url(),
-  }),
-)
-
-/**
- * IMPORTANT — side effect: register the schema with kickjs's env cache
- * **at module-load time**. \`ConfigService\` and \`@Value()\` both consume
- * this cache, and they will fall back to the base schema (or undefined)
- * if no extended schema has been registered before they're resolved.
- *
- * As long as \`src/index.ts\` imports this file (\`import './env'\`) at the
- * top — before \`bootstrap()\` runs — every controller and service in the
- * app sees the typed extended values.
- */
-export const env = loadEnv(envSchema)
-
-export default envSchema
-`;
-}
-/** 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", packageManager = "pnpm") {
-	return `import { defineConfig } from '@forinda/kickjs-cli'
-
-export default defineConfig({
-  pattern: '${template}',
-  // Pinned so \`kick add\` and other dep-installing commands always use the
-  // project's intended package manager, regardless of which lockfile exists.
-  packageManager: '${packageManager}',
-  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: 'ci:check',
-      description: 'Run typecheck + format check',
-      steps: ['npx tsc --noEmit', 'npx prettier --check src/'],
-      aliases: ['verify'],
-    },
-  ],
-})
-`;
-}
-//#endregion
-//#region src/generators/patterns/minimal.ts
-async function generateMinimalFiles(ctx) {
-	const { pascal, kebab, plural, write } = ctx;
-	await write(`${kebab}.module.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(`${kebab}.module.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(`${kebab}.module.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(`${kebab}.module.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
-/**
-* Generate a module — structure depends on the project pattern.
-*
-* Patterns:
-*   rest         — flat folder: controller + service + DTOs + repo
-*   ddd          — nested DDD: presentation/ application/ domain/ infrastructure/
-*   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)) {
-			if (!await confirm({
-				message: `File exists: ${pc.dim(relativePath)}. Overwrite?`,
-				initialValue: false
-			})) {
-				log.warn(`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, kebab);
-	return files;
-}
-/** Add the new module to src/modules/index.ts */
-async function autoRegisterModule(modulesDir, pascal, plural, kebab) {
-	const indexPath = join(modulesDir, "index.ts");
-	const exists = await fileExists(indexPath);
-	const importPath = `./${plural}/${kebab}.module`;
-	if (!exists) {
-		await writeFileSafe(indexPath, `import type { AppModuleClass } from '@forinda/kickjs'
-import { ${pascal}Module } from '${importPath}'
-
-export const modules: AppModuleClass[] = [${pascal}Module]
-`);
-		return;
-	}
-	let content = await readFile(indexPath, "utf-8");
-	const importLine = `import { ${pascal}Module } from '${importPath}'`;
-	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
-/**
-* Scaffold a `defineAdapter()` factory under `src/adapters/<name>.adapter.ts`.
-*
-* v4 dropped the `class implements AppAdapter` pattern in favour of the
-* `defineAdapter()` factory (architecture.md §21.3.4). The generated
-* template uses the new factory shape so adopters get a working
-* adapter with all four lifecycle hooks (beforeMount, beforeStart,
-* afterStart, shutdown), a typed config object with defaults, and the
-* factory's call / `.scoped()` / `.async()` surfaces — without
-* writing a single class.
-*/
-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 {
-  defineAdapter,
-  type AdapterContext,
-  type AdapterMiddleware,
-  type ContributorRegistrations,
-  type Constructor,
-} from '@forinda/kickjs'
-
-/**
- * Configuration for the ${pascal} adapter.
- *
- * Adapters typically take a small config object so callers can tune
- * behaviour at bootstrap time. Keep the shape narrow — anything
- * derived from the environment should be read inside the build
- * function via getEnv(), not forced onto the caller.
- */
-export interface ${pascal}AdapterConfig {
-  // Add your adapter configuration here, e.g.:
-  // enabled?: boolean
-  // apiKey?: string
-}
-
-/**
- * ${pascal} adapter — built via \`defineAdapter()\` so callers get the
- * factory's call / \`.scoped()\` / \`.async()\` surfaces for free.
- *
- * Hooks into the Application lifecycle to add middleware, routes,
- * Context Contributors, or external service connections.
- *
- * Every lifecycle hook below is OPTIONAL. The scaffold emits all of
- * them so adopters can browse what's available and delete what they
- * don't need — \`build()\` returning \`{}\` is also valid for an adapter
- * that only contributes config defaults.
- *
- * @example
- * \`\`\`ts
- * import { bootstrap } from '@forinda/kickjs'
- * import { ${pascal}Adapter } from './adapters/${kebab}.adapter'
- *
- * bootstrap({
- *   modules,
- *   adapters: [${pascal}Adapter({ /* config overrides *\\/ })],
- * })
- * \`\`\`
- */
-export const ${pascal}Adapter = defineAdapter<${pascal}AdapterConfig>({
-  name: '${pascal}Adapter',
-  defaults: {
-    // Default config values go here. The adopter's overrides shallow-merge
-    // on top of these before \`build()\` runs.
-  },
-  build: (_config, { name: _name }) => {
-    // Closures inside \`build()\` are how each adapter instance owns its
-    // own state (database client, Map, timer handle, …). The same
-    // \`_config\` is visible to every hook below.
-
-    return {
-      /**
-       * Express middleware entries the Application mounts at named phases.
-       *
-       * \`phase\` controls where each handler sits in the pipeline:
-       *   'beforeGlobal' | 'afterGlobal' | 'beforeRoutes' | 'afterRoutes'.
-       *
-       * \`path\` (optional) scopes the entry to a path prefix.
-       *
-       * Delete this hook entirely if you don't add middleware.
-       */
-      middleware(): AdapterMiddleware[] {
-        return [
-          // Example: add a custom header to all responses
-          // {
-          //   phase: 'beforeGlobal',
-          //   handler: (_req, res, next) => {
-          //     res.setHeader('X-${pascal}', 'true')
-          //     next()
-          //   },
-          // },
-          // Example: scope a rate limiter to one path prefix
-          // {
-          //   phase: 'beforeRoutes',
-          //   path: '/api/v1/auth',
-          //   handler: rateLimit({ max: 10 }),
-          // },
-        ]
-      },
-
-      /**
-       * Runs BEFORE global middleware. Mount routes that should bypass the
-       * middleware stack — health checks, docs UI, static assets, OAuth
-       * callbacks. Anything you want reachable even if a global middleware
-       * later in the chain rejects requests.
-       *
-       * Delete this hook if you have no early routes.
-       */
-      beforeMount(_ctx: AdapterContext): void {
-        // Example:
-        // _ctx.app.get('/${kebab}/status', (_req, res) => res.json({ status: 'ok' }))
-      },
-
-      /**
-       * Fires once per controller class as the router mounts. Use this to
-       * collect route metadata for OpenAPI specs, dependency graphs, route
-       * inventories, devtools dashboards.
-       *
-       * Delete this hook unless your adapter introspects the route registry.
-       */
-      onRouteMount(_controllerClass: Constructor, _mountPath: string): void {
-        // Example (Swagger-style): collect routes for the spec.
-        // openApiSpec.addController(_controllerClass, _mountPath)
-      },
-
-      /**
-       * Runs AFTER modules + routes are wired, BEFORE the server starts.
-       * Right place for late-stage DI registrations or final config validation.
-       *
-       * Delete this hook if there's nothing to wire post-modules.
-       */
-      beforeStart(_ctx: AdapterContext): void {
-        // Example: _ctx.container.registerInstance(MY_TOKEN, new MyService(_config))
-      },
-
-      /**
-       * Runs AFTER the HTTP server is listening. The raw \`http.Server\` is
-       * available on \`ctx.server\` — attach upgrade handlers (Socket.IO,
-       * gRPC, GraphQL subscriptions), warm caches, log a banner.
-       *
-       * Delete this hook if you don't need the running server reference.
-       */
-      afterStart(_ctx: AdapterContext): void {
-        // Example: const io = new Server(_ctx.server)
-      },
-
-      /**
-       * Returns Context Contributors to merge into every route's pipeline
-       * at the \`'adapter'\` precedence level. Per-route handlers can
-       * override the value at the method / class / module level.
-       *
-       * Delete this hook unless your adapter ships typed per-request values
-       * (auth user, tenant, locale, feature flags, geo, etc).
-       */
-      contributors(): ContributorRegistrations {
-        return [
-          // Example:
-          // import { defineHttpContextDecorator } from '@forinda/kickjs'
-          // declare module '@forinda/kickjs' { interface ContextMeta { ${kebab}: { id: string } } }
-          // const Load${pascal} = defineHttpContextDecorator({
-          //   key: '${kebab}',
-          //   resolve: (ctx) => ({ id: ctx.req.headers['x-${kebab}-id'] as string }),
-          // })
-          // return [Load${pascal}.registration]
-        ]
-      },
-
-      /**
-       * Runs on graceful shutdown (SIGINT/SIGTERM). Clean up long-lived
-       * resources the adapter owns: close connections, flush buffers,
-       * cancel timers. The framework runs every adapter's \`shutdown\`
-       * concurrently via \`Promise.allSettled\` — one failure won't block
-       * sibling adapters.
-       *
-       * Delete this hook if your adapter holds no resources.
-       */
-      async shutdown(): Promise<void> {
-        // Example: await this.pool.end()
-        // Example: clearInterval(this.heartbeatTimer)
-      },
-    }
-  },
-})
-`);
-	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", shouldPluralize = true } = options;
-	if (outDir) return resolve(outDir);
-	if (moduleName) {
-		const folderMap = pattern === "ddd" ? DDD_FOLDER_MAP : pattern === "cqrs" ? CQRS_FOLDER_MAP : FLAT_FOLDER_MAP;
-		const kebab = toKebabCase(moduleName);
-		const folder = shouldPluralize ? pluralize(kebab) : kebab;
-		const subfolder = folderMap[type] ?? "";
-		const base = join(modulesDir, folder);
-		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,
-		shouldPluralize: options.pluralize ?? true
-	});
-	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,
-		shouldPluralize: options.pluralize ?? true
-	});
-	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,
-		shouldPluralize: options.pluralize ?? true
-	});
-	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,
-		shouldPluralize: options.pluralize ?? true
-	});
-	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,
-		shouldPluralize: options.pluralize ?? true
-	});
-	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
-/** Map of optional package names to their npm package identifiers */
-const PACKAGE_DEPS = {
-	auth: "@forinda/kickjs-auth",
-	swagger: "@forinda/kickjs-swagger",
-	ws: "@forinda/kickjs-ws",
-	queue: "@forinda/kickjs-queue",
-	devtools: "@forinda/kickjs-devtools"
-};
-/** Generate package.json with template-aware dependencies */
-function generatePackageJson(name, template, kickjsVersion, packages = []) {
-	const baseDeps = {
-		"@forinda/kickjs": kickjsVersion,
-		dotenv: "^17.3.1",
-		express: "^5.1.0",
-		"reflect-metadata": "^0.2.2",
-		zod: "^4.3.6",
-		pino: "^10.3.1",
-		"pino-pretty": "^13.1.3"
-	};
-	for (const pkg of packages) {
-		const dep = PACKAGE_DEPS[pkg];
-		if (dep && !baseDeps[dep]) baseDeps[dep] = 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: "^6.0.3",
-			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, envWatchPlugin } from '@forinda/kickjs-vite'
-
-export default defineConfig({
-  oxc: false,
-  plugins: [
-    swc.vite(),
-    kickjsVitePlugin({ entry: 'src/index.ts' }),
-    // Watches .env files and triggers a full reload on change so the
-    // dev server picks up env tweaks without a manual restart.
-    envWatchPlugin(),
-  ],
-  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",
-		ddd: "Domain-Driven Design",
-		cqrs: "CQRS + Event-Driven",
-		minimal: "Minimal"
-	};
-	const packages = ["@forinda/kickjs", "@forinda/kickjs-vite"];
-	if (template !== "minimal") packages.push("@forinda/kickjs-swagger", "@forinda/kickjs-devtools");
-	if (template === "cqrs") packages.push("@forinda/kickjs-queue", "@forinda/kickjs-ws");
-	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 --list        # Show all available packages
-\`\`\`
-
-For email, scheduled tasks, multi-tenancy, OpenTelemetry, GraphQL, and notifications use the BYO recipes in the [KickJS guides](https://forinda.github.io/kick-js/guide/) — they wire the upstream library through \`defineAdapter()\` / \`definePlugin()\` directly, so you keep control of the integration.
-
-## 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.
-*
-* v4 update: this file is intentionally thin. AGENTS.md is the
-* canonical, multi-agent project reference (Claude / Copilot /
-* Codex / Gemini / etc.) — duplicating it here meant two files
-* drifting out of sync after every framework change. The generated
-* CLAUDE.md now redirects there + adds Claude-specific affordances
-* only.
-*/
-function generateClaude(name, _template, pm) {
-	return `# CLAUDE.md — ${name}
-
-**Read \`./AGENTS.md\` first.** It is the canonical, multi-agent
-reference for this project (Claude, Copilot, Codex, Gemini, etc.) —
-project conventions, structure, decorator patterns, env wiring, CLI
-generators, every gotcha.
-
-**Then read \`./kickjs-skills.md\`.** That file is the task-oriented
-skill index — short, rigid recipes keyed to triggers ("add-module",
-"write-controller-test", "bootstrap-export", "deny-list", …). Use it
-as the playbook when executing common KickJS workflows.
-
-This file is a thin Claude-specific layer on top of those two; when
-they disagree on anything substantive, treat \`AGENTS.md\` as
-authoritative and flag the discrepancy.
-
-## Why two files
-
-\`AGENTS.md\` is what every agent reads. \`CLAUDE.md\` is what
-Claude Code automatically loads as project context on each
-conversation. Keeping CLAUDE.md slim avoids two files drifting; the
-redirect above ensures Claude pulls the canonical content without
-us copy-pasting.
-
-## Claude-specific notes
-
-- **Slash commands** — \`/help\` for Claude Code commands; \`/init\`
-  to refresh project memory if AGENTS.md changes substantially.
-- **Feedback** — file issues at <https://github.com/anthropics/claude-code/issues>.
-- **Persistent memory** — Claude maintains user/feedback/project/
-  reference memories under \`.claude/memory/\`. If you ask for
-  something that contradicts a remembered preference, Claude flags
-  it before acting; corrections update memory automatically.
-- **Long-running tasks** — \`/loop\` and \`/schedule\` for recurring
-  or background work. Useful for "wait for the deploy then open a
-  cleanup PR" or "every Monday triage the issue board" patterns.
-
-## Quick reference (full version in AGENTS.md)
-
-\`\`\`bash
-${pm} install            # Install dependencies
-kick dev                 # Dev server with HMR + typegen
-kick build && kick start # Production
-${pm} run test           # Vitest
-${pm} run typecheck      # tsc --noEmit
-${pm} run format         # Prettier
-\`\`\`
-
-## v4 framework reminders
-
-When generating or modifying code in this project, stay aligned with the v4 conventions documented in \`AGENTS.md\`:
-
-- **Adapters**: \`defineAdapter()\` factory — never \`class implements AppAdapter\`.
-- **Plugins**: \`definePlugin()\` factory — never plain function returning \`KickPlugin\`.
-- **DI tokens**: slash-delimited \`<scope>/<area>/<key>\` (e.g. \`'app/users/repository'\`). First-party uses the reserved \`'kick/'\` prefix; this project owns its own scope.
-- **Decorators**: \`@Controller()\` (no path arg — mount prefix comes from \`routes().path\`).
-- **Module entry file** MUST be named \`<name>.module.ts\` and live under \`src/modules/<name>/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed \`projects.ts\` silently degrades every save into a full restart.
-- **Env**: schema lives in \`src/config/index.ts\`; \`import './config'\` MUST be the first import in \`src/index.ts\` (side-effect registers the schema before any \`@Value\` resolves).
-- **Assets**: drop new template files into \`src/templates/<namespace>/\`; the dev watcher auto-rebuilds the \`KickAssets\` augmentation + \`assets.x.y()\` re-walks on next call. No restart, no manual build.
-- **Context Contributors** (\`defineContextDecorator\`) over \`@Middleware()\` for ctx-population work.
-- **Repos under tests**: \`Container.create()\` for isolation — never \`new Container()\` or \`getInstance().reset()\`.
-- **Bootstrap export**: \`src/index.ts\` must end with \`export const app = await bootstrap({ ... })\`. The Vite plugin and \`createTestApp\` import the named \`app\`; without the export, HMR silently degrades to full restarts.
-- **Thin entry file**: aggregate \`modules\`, \`middleware\`, \`plugins\`, \`adapters\` in their own folders (\`src/modules/index.ts\`, \`src/middleware/index.ts\`, …) and pass them by name to \`bootstrap()\` — never inline the lists in \`src/index.ts\`.
-- **Refresh these files**: \`kick g agents -f\` regenerates \`AGENTS.md\` + \`CLAUDE.md\` from the latest CLI templates. Hand-edited content is overwritten — keep customisation in \`AGENTS.local.md\`.
-
-For everything else (controllers, services, modules, RequestContext API, generators, CLI commands, package additions, env wiring, troubleshooting) → \`AGENTS.md\`.
-`;
-}
-/** Generate AGENTS.md with AI agent guide */
-function generateAgents(name, template, pm) {
-	return `# AGENTS.md — AI Agent Guide for ${name}
-
-This guide is the **canonical, multi-agent reference** for this KickJS
-application — Claude, Copilot, Codex, Gemini, etc. all read it first.
-Per-agent files (\`CLAUDE.md\`, \`GEMINI.md\`, etc.) are thin layers that
-add tool-specific affordances on top.
-
-## Before You Start
-
-1. Run \`${pm} install\` to install dependencies
-2. Run \`kick dev\` to verify the app starts
-3. Read the [KickJS documentation](https://forinda.github.io/kick-js/) for framework details
-
-## v4 Conventions (don't skip)
-
-KickJS v4 made a handful of structural changes from v3. Internalise these
-before generating or modifying code — they are the source of most agent
-mistakes:
-
-- **Adapters** — \`defineAdapter()\` factory. Never write \`class Foo implements AppAdapter\`.
-
-  \`\`\`ts
-  export const MyAdapter = defineAdapter<MyOptions>({
-    name: 'MyAdapter',
-    defaults: { ... },
-    build: (config) => ({
-      beforeMount({ app }) { /* ... */ },
-      afterStart({ server }) { /* ... */ },
-    }),
-  })
-  \`\`\`
-
-- **Plugins** — \`definePlugin()\` factory. Same shape, never plain function returning \`KickPlugin\`.
-
-- **DI tokens** — slash-delimited \`<scope>/<area>/<key>\`, lower-case, no \`:\` separators:
-
-  \`\`\`ts
-  const USERS_REPO = createToken<UsersRepo>('app/users/repository')
-  const DB         = createToken<Database>('app/db/connection')
-  \`\`\`
-
-  The \`kick/\` prefix is reserved for first-party packages; this project
-  owns its own scope (\`app/\`, your domain name, etc.).
-
-- **\`@Controller()\`** takes **no path argument**. Mount prefix comes from
-  the module's \`routes()\` return value, not the decorator. \`@Controller('/users')\`
-  is a v3 leftover; the linter and codegen reject it.
-
-- **Env wiring** — \`src/config/index.ts\` calls \`loadEnv(envSchema)\` as a
-  side effect. \`src/index.ts\` MUST have \`import './config'\` as its **first**
-  import (before \`bootstrap()\`). Without it, \`ConfigService.get('YOUR_KEY')\`
-  returns \`undefined\` and \`@Value()\` only works via raw \`process.env\` fallback
-  (Zod coercion + defaults silently skipped).
-
-- **Module entry files MUST be named \`<name>.module.ts\`** — see the Vite
-  HMR contract at the top of "Module Pattern" below. The CLI enforces this;
-  hand-rolled files must too.
-
-- **Assets** — drop new template files into \`src/templates/<namespace>/\`
-  (or wherever \`kick.config.ts\` points). The dev watcher auto-rebuilds the
-  \`KickAssets\` augmentation; \`assets.x.y()\` re-walks on next call. No restart,
-  no manual build step.
-
-- **Context over \`@Middleware()\`** — when a middleware's only job is to
-  populate \`ctx.set('key', value)\`, use \`defineHttpContextDecorator()\`
-  (HTTP) or \`defineContextDecorator()\` (transport-agnostic) instead.
-  Typed via \`ContextMeta\`, ordered via \`dependsOn\`, validated at boot.
-  Reserve \`@Middleware()\` for response short-circuit / stream mutation /
-  pre-route-matching work.
-
-  Two ground rules around the data flow — both stem from the fact that
-  every per-request stage gets its OWN \`RequestContext\` instance, all
-  reading/writing the SAME \`AsyncLocalStorage\`-backed Map:
-  - **\`resolve\` and \`onError\` must RETURN the value.** The runner
-    writes it via \`ctx.set(reg.key, value)\` on your behalf. Direct
-    property assignment (\`ctx.tenant = …\`) sticks to the contributor
-    instance only — the handler instance never sees it.
-  - **Read across instances via \`ctx.set\` / \`ctx.get\`** (or
-    \`getRequestValue(key)\` from a service that has no \`ctx\` reference
-    — typed via \`MetaValue<K>\`). \`ctx.req\` works because the underlying
-    Express request is shared; bespoke property assignments don't.
-
-- **Test isolation** — default to \`Container.create()\` for fresh DI state.
-  Never \`new Container()\` and never \`getInstance().reset()\` — both leak
-  registrations between tests.
-
-  \`\`\`ts
-  const container = Container.create()
-  // ... register test-scoped providers, run, discard
-  \`\`\`
-
-- **Bootstrap export** — \`src/index.ts\` MUST end with
-  \`export const app = await bootstrap({ ... })\`. The Vite plugin imports
-  the named \`app\` symbol to drive HMR module swaps; testing helpers
-  (\`createTestApp\`) and the OpenAPI introspector also rely on it. Drop
-  the \`export\` and \`kick dev\` will silently fall back to a full restart
-  on every save while \`createTestApp\` complains about a missing handle.
-
-- **Keep \`src/index.ts\` thin** — collect plugins, modules, middleware, and
-  adapters in dedicated folders and re-export aggregated arrays. Do **not**
-  inline registration in the entry file:
-
-  \`\`\`ts
-  // src/modules/index.ts
-  export const modules: AppModuleClass[] = [HelloModule, UsersModule, ...]
-
-  // src/middleware/index.ts
-  export const middleware = [helmet(), cors(), requestId(), ...]
-
-  // src/plugins/index.ts
-  export const plugins = [MetricsPlugin(), AuditPlugin()]
-
-  // src/adapters/index.ts
-  export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
-  \`\`\`
-
-  \`\`\`ts
-  // src/index.ts — stays small; one import per category
-  import 'reflect-metadata'
-  import './config'
-  import { bootstrap } from '@forinda/kickjs'
-  import { modules } from './modules'
-  import { middleware } from './middleware'
-  import { plugins } from './plugins'
-  import { adapters } from './adapters'
-
-  export const app = await bootstrap({ modules, middleware, plugins, adapters })
-  \`\`\`
-
-  This keeps the entry file diff-friendly, scales to dozens of modules
-  without git churn, and lets each domain own its own registration list.
-  The generators (\`kick g module\`, \`kick g middleware\`, \`kick g plugin\`,
-  \`kick g adapter\`) follow this layout — manual additions should too.
-
-Everything else (controllers, services, modules, RequestContext API, generators,
-package additions, env access patterns, troubleshooting) is detailed below.
-
-## 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>/\` |
-| **Module entry file** | \`src/modules/<name>/<name>.module.ts\` (filename suffix is required — see Vite HMR contract below) |
-| Env values | \`.env\` |
-| Env schema (Zod) | \`src/config/index.ts\` |
-| 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()})
-
-> **Vite HMR auto-discovery contract:** module files **must** be named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and live under \`src/modules/\`. The Vite plugin scans for \`*.module.[tj]sx?\` to drive graceful HMR rebuilds; renaming a file to \`projects.ts\` (no \`.module\`) silently breaks HMR — saves trigger a full restart instead of a swap. The CLI generator (\`kick g module <name>\`) follows the convention; manual files must too.
-
-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 (implements AppModule)
-\`\`\`
-` : 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 (implements AppModule)
-\`\`\`
-` : 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 (implements AppModule)
-\`\`\`
-` : `\`\`\`
-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()\` decorator
-- [ ] Add route handlers with \`@Get()\`, \`@Post()\`, etc.
-- [ ] Create module file implementing \`AppModule\` with \`routes()\` returning \`{ path, router: buildRoutes(Controller), controller }\`
-- [ ] Register module in \`src/modules/index.ts\` (\`AppModuleClass[]\` array)
-- [ ] Test with \`kick dev\`
-
-### Manual Service
-
-- [ ] Create \`src/modules/<name>/<name>.service.ts\`
-- [ ] Add \`@Service()\` decorator
-- [ ] Inject dependencies with \`@Autowired()\`
-- [ ] Inject via \`@Autowired()\` where needed
-- [ ] 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:optional age:number
-\`\`\`
-
-Append \`:optional\` for optional fields (shell-safe, no quoting needed).
-Quoted \`?\` syntax also works: \`"email:string?"\` or \`"email?:string"\`.
-
-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: [
-    AuthAdapter({
-      strategies: [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: [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', () => {
-  it('should return users', async () => {
-    // Container.create() — isolated DI state per test, never new Container()
-    // and never getInstance().reset() (both leak registrations between tests).
-    const container = Container.create()
-    const app = await createTestApp([UserModule], { container })
-    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
-
-Schema is declared in \`src/config/index.ts\` (extends the base
-\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` shape via \`defineEnv\`) and registered
-with kickjs at module load. \`src/index.ts\` imports it via
-\`import './config'\` **before** \`bootstrap()\` so the cache is populated
-in time for DI. Add new keys to the schema, drop their values into
-\`.env\`, and they're typed everywhere.
-
-Access patterns:
-
-1. **@Value() decorator** (recommended for known-at-construction keys):
-\`\`\`ts
-@Value('DATABASE_URL')
-private dbUrl!: string
-\`\`\`
-
-2. **ConfigService** (recommended for dynamic / method-scoped access):
-\`\`\`ts
-@Autowired()
-private config!: ConfigService
-
-const port = this.config.get('PORT')  // typed: number
-\`\`\`
-
-3. **Standalone utilities** (no DI — works in scripts, CLI, plain files):
-\`\`\`ts
-import { loadEnv, getEnv, reloadEnv, resetEnvCache } from '@forinda/kickjs/config'
-
-const env = loadEnv(schema)         // Parse + validate all vars
-const port = getEnv('PORT')         // Single value lookup
-reloadEnv()                         // Re-read .env from disk
-resetEnvCache()                     // Full reset (for tests)
-\`\`\`
-
-4. **Direct \`process.env\`** — avoid in app code; bypasses Zod
-   coercion and the typed \`KickEnv\` registry.
-
-> **Pitfall**: never delete \`import './config'\` from \`src/index.ts\`.
-> If the schema is not registered before DI runs, \`config.get()\`
-> returns \`undefined\` for user keys (the base shape only) and
-> \`@Value()\` only works because of its raw \`process.env\` fallback —
-> Zod coercion + schema defaults are silently skipped.
-
-## Standalone Utilities (No DI Required)
-
-These work anywhere — scripts, plain files, outside \`@Service\`/\`@Controller\`:
-
-| Utility | Import | Example |
-|---------|--------|---------|
-| \`Logger.for(name)\` | \`@forinda/kickjs\` | \`const log = Logger.for('MyScript')\` |
-| \`createLogger(name)\` | \`@forinda/kickjs\` | \`const log = createLogger('Worker')\` |
-| \`createToken<T>(name)\` | \`@forinda/kickjs\` | \`const TOKEN = createToken<string>('app/db/url')\` |
-| \`ref(value)\` | \`@forinda/kickjs\` | \`const count = ref(0)\` |
-| \`computed(fn)\` | \`@forinda/kickjs\` | \`const doubled = computed(() => count.value * 2)\` |
-| \`watch(source, cb)\` | \`@forinda/kickjs\` | \`watch(() => count.value, (v) => log(v))\` |
-| \`reactive(obj)\` | \`@forinda/kickjs\` | \`const state = reactive({ count: 0 })\` |
-| \`HttpException\` | \`@forinda/kickjs\` | \`throw new HttpException(404, 'Not found')\` |
-| \`HttpStatus\` | \`@forinda/kickjs\` | \`HttpStatus.NOT_FOUND // 404\` |
-
-## Key Decorators
-
-### HTTP Routes
-| Decorator | Purpose |
-|-----------|---------|
-| \`@Controller()\` | 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 |
-|-----------|---------|
-| \`AppModule\` interface | Define feature module (implements \`routes()\`) |
-| \`@Service()\` | Register singleton service |
-| \`@Repository()\` | Register repository |
-| \`@Autowired()\` | Property injection |
-| \`@Inject('token')\` | Token-based injection |
-| \`@Value('VAR')\` | Inject env variable |
-
-### Context Decorators
-
-Typed, ordered way to populate \`ctx.set/get\` keys before the handler runs.
-Use this **instead of \`@Middleware()\`** when the middleware's only output
-is a value other code reads off \`ctx\`.
-
-| Concept | Where it lives |
-|---------|----------------|
-| \`defineContextDecorator({ key, deps, dependsOn, optional, onError, resolve })\` | \`@forinda/kickjs\` |
-| Method/class decorator | \`@LoadX\` on a controller method/class |
-| Module hook | \`AppModule.contributors?(): ContributorRegistration[]\` |
-| Adapter hook | \`AppAdapter.contributors?(): ContributorRegistration[]\` |
-| Global registration | \`bootstrap({ contributors: [LoadX.registration] })\` |
-| Type augmentation | \`declare module '@forinda/kickjs' { interface ContextMeta { ... } }\` |
-
-Precedence high → low: **method > class > module > adapter > global**.
-Cycles and missing \`dependsOn\` keys throw at \`app.setup()\` (boot fails
-fast). The \`onError\` hook is async-permitted.
-
-Full guide: <https://forinda.github.io/kick-js/guide/context-decorators>.
-
-${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** — Sharing the global container between tests. Default to \`Container.create()\` per test (or per \`beforeEach\`) instead of \`new Container()\` / \`getInstance().reset()\`
-4. **Routes not found** — Check controller path and module registration
-5. **HMR not working** — Two checks: (a) \`vite.config.ts\` has \`hmr: true\`; (b) module file is named \`<name>.module.ts\` (or \`.tsx\`/\`.js\`/\`.jsx\`) and lives under \`src/modules/\`. The Vite plugin auto-discovers \`*.module.[tj]sx?\` for graceful HMR — a misnamed module file (e.g., \`projects.ts\`) silently degrades to a full restart on every save.
-6. **Decorators not working** — Check \`tsconfig.json\` has \`experimentalDecorators: true\`
-7. **\`config.get('YOUR_KEY')\` returns \`undefined\`** — \`src/index.ts\` is missing \`import './config'\`. That side-effect import registers the env schema with kickjs (\`loadEnv(envSchema)\` runs at module load). Without it, \`ConfigService\` falls back to the base schema (\`PORT\`/\`NODE_ENV\`/\`LOG_LEVEL\` only) and every user-defined key reads as \`undefined\`. \`@Value()\` may *appear* to work because of a raw \`process.env\` fallback, but Zod coercion and schema defaults are silently skipped — investigate \`src/index.ts\` and \`src/config/index.ts\` first.
-8. **Used \`@Middleware()\` to compute a value for \`ctx\`** — prefer \`defineContextDecorator()\` (see Context Decorators above). It's typed via \`ContextMeta\`, supports \`dependsOn\` for ordering, and validates the pipeline at boot. \`@Middleware()\` is for response short-circuiting, stream mutation, and pre-route-matching work.
-9. **Context contributor's \`dependsOn\` key not produced anywhere** — boot throws \`MissingContributorError\` naming the dependent and the route. Either remove the dep or register a contributor that produces the key (at any precedence level: method/class/module/adapter/global).
-10. **\`bootstrap()\` not exported** — \`src/index.ts\` calls \`await bootstrap({ ... })\` but discards the return value (no \`export const app = ...\`). Vite HMR can't locate the running instance, so module saves degrade to full restarts; \`createTestApp\`/\`@forinda/kickjs-testing\` consumers can't import the handle either. Always: \`export const app = await bootstrap({ ... })\`.
-11. **Refresh AGENTS.md / CLAUDE.md after a framework upgrade** — these files are scaffolded by the CLI and don't auto-update. Run \`kick g agents -f\` (or \`kick g agent-docs -f\`) to regenerate from the latest CLI templates after \`kick add\` / version bumps. Hand-edited sections will be overwritten — keep customisation in a separate file like \`AGENTS.local.md\`.
-
-## 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)
-`;
-}
-/**
-* Generate `kickjs-skills.md` — task-oriented "skill" recipes for AI
-* agents (Claude superpowers, Copilot, etc.). Where AGENTS.md is the
-* narrative reference, this file lists short, rigid workflows the agent
-* should follow when it sees the corresponding trigger.
-*/
-function generateKickJsSkills(name, _template, pm) {
-	return `# kickjs-skills.md — Task Skills for AI Agents (${name})
-
-This file is the agent-facing **skills index** for KickJS work in this
-repo. Each block below is a short, rigid workflow keyed to a specific
-trigger ("user wants to add a module", "tests are leaking state", etc.).
-
-- Reference docs (narrative, exhaustive) → \`AGENTS.md\`.
-- Tool-specific notes → \`CLAUDE.md\`, \`GEMINI.md\`, etc.
-- **This file** → step-by-step recipes the agent should *execute*.
-
-Re-run \`kick g agents -f --only skills\` after framework upgrades to refresh.
-
----
-
-## Skill: add-module
-
-\`\`\`yaml
-name: kickjs-add-module
-description: Use when the user asks to add a new feature module (controller + service + repo + DTOs).
-\`\`\`
-
-**Trigger phrases**: "add a users module", "scaffold tasks", "new feature for X".
-
-**Steps**:
-1. Run \`kick g module <name>\` (use plural form if the project pluralizes — check \`kick.config.ts\`).
-2. Verify the new folder under \`src/modules/<name>/\` contains \`<name>.module.ts\` (filename suffix is mandatory for HMR).
-3. Confirm the module appears in \`src/modules/index.ts\` exports — generator does this automatically; verify if you bypassed it.
-4. Open \`<name>.dto.ts\` and tighten the Zod schemas to real fields (the generator emits placeholders).
-5. Run \`${pm} run typecheck\` and \`${pm} run test\` before claiming done.
-
-**Red flags** (stop and ask):
-- File created as \`<name>.ts\` instead of \`<name>.module.ts\` — Vite won't HMR it.
-- Module not registered in \`src/modules/index.ts\`.
-- \`@Controller('/path')\` with a path argument — that's a v3 pattern; remove it (mount comes from \`routes().path\`).
-
----
-
-## Skill: add-adapter
-
-\`\`\`yaml
-name: kickjs-add-adapter
-description: Use when wiring a new lifecycle integration (Swagger, DevTools, Auth, custom).
-\`\`\`
-
-**Steps**:
-1. \`kick g adapter <name>\` to scaffold the boilerplate, OR install via \`kick add <package>\` for first-party adapters.
-2. The generated file uses \`defineAdapter()\` — never \`class implements AppAdapter\`.
-3. Add the adapter instance to \`src/adapters/index.ts\` (don't inline in \`src/index.ts\`).
-4. If the adapter contributes to \`ctx.set/get\`, prefer \`AppAdapter.contributors?()\` over a wrapping middleware.
-5. Verify with \`kick dev\` that the adapter's lifecycle logs fire.
-
-**Red flags**:
-- Inlining the adapter list directly in \`src/index.ts\` (entry file should stay thin).
-- Returning a plain object instead of going through \`defineAdapter()\` — type inference for \`config\` will be wrong.
-
----
-
-## Skill: write-controller-test
-
-\`\`\`yaml
-name: kickjs-write-controller-test
-description: Use when adding a Vitest test that exercises an HTTP route or DI graph.
-\`\`\`
-
-**Template** (copy/paste, adjust):
-
-\`\`\`ts
-import { describe, it, expect } from 'vitest'
-import { Container } from '@forinda/kickjs'
-import { createTestApp } from '@forinda/kickjs-testing'
-
-describe('UserController', () => {
-  it('returns users', async () => {
-    const container = Container.create()           // isolated DI per test
-    const app = await createTestApp([UserModule], { container })
-    const res = await app.get('/users')
-    expect(res.status).toBe(200)
-  })
-})
-\`\`\`
-
-**Red flags**:
-- \`new Container()\` — wrong; use \`Container.create()\`.
-- \`Container.getInstance().reset()\` — wrong; same fix.
-- Sharing a container across \`it()\` blocks — leaks registrations.
-
----
-
-## Skill: env-wiring-check
-
-\`\`\`yaml
-name: kickjs-env-wiring-check
-description: Use when ConfigService.get('SOME_KEY') returns undefined or @Value silently falls back to process.env.
-\`\`\`
-
-**Diagnosis**:
-1. Open \`src/index.ts\`. The **first non-\`reflect-metadata\`** import MUST be \`import './config'\`.
-2. Open \`src/config/index.ts\`. It MUST call \`loadEnv(envSchema)\` as a top-level side effect.
-3. The new key MUST be declared in the Zod schema there. \`@Value('NEW_KEY')\` won't work without a schema entry (it'll fall back to raw \`process.env\` and skip Zod coercion silently).
-
-**Fix**: add the key to the schema; ensure both side-effect imports above are present.
-
----
-
-## Skill: bootstrap-export
-
-\`\`\`yaml
-name: kickjs-bootstrap-export
-description: Use when HMR is silently doing full restarts on every save, or createTestApp can't find the app handle.
-\`\`\`
-
-**Check** \`src/index.ts\`'s last line:
-
-\`\`\`ts
-// CORRECT
-export const app = await bootstrap({ ... })
-
-// WRONG (HMR degrades to full restart, createTestApp loses the handle)
-await bootstrap({ ... })
-\`\`\`
-
-The Vite plugin imports the named \`app\` symbol; testing helpers do too.
-
----
-
-## Skill: thin-entry-file
-
-\`\`\`yaml
-name: kickjs-thin-entry-file
-description: Use when src/index.ts is accumulating module/middleware/plugin/adapter literals.
-\`\`\`
-
-**Refactor target**:
-
-\`\`\`ts
-// src/modules/index.ts
-export const modules: AppModuleClass[] = [HelloModule, UsersModule, ...]
-
-// src/middleware/index.ts
-export const middleware = [helmet(), cors(), requestId(), ...]
-
-// src/plugins/index.ts
-export const plugins = [MetricsPlugin(), ...]
-
-// src/adapters/index.ts
-export const adapters = [SwaggerAdapter({ ... }), DevToolsAdapter()]
-
-// src/index.ts — stays small
-import 'reflect-metadata'
-import './config'
-import { bootstrap } from '@forinda/kickjs'
-import { modules } from './modules'
-import { middleware } from './middleware'
-import { plugins } from './plugins'
-import { adapters } from './adapters'
-export const app = await bootstrap({ modules, middleware, plugins, adapters })
-\`\`\`
-
-**Red flags**: any \`new SomeAdapter()\` or \`SomePlugin()\` literal inside \`bootstrap({ ... })\` instead of imported from a category folder.
-
----
-
-## Skill: context-contributor
-
-\`\`\`yaml
-name: kickjs-context-contributor
-description: Use when a middleware's only job is to set ctx values consumed elsewhere — replace with defineHttpContextDecorator (HTTP) or defineContextDecorator (transport-agnostic).
-\`\`\`
-
-**Pattern** (HTTP — most common):
-
-\`\`\`ts
-import { defineHttpContextDecorator, type RequestContext } from '@forinda/kickjs'
-
-const LoadTenant = defineHttpContextDecorator({
-  key: 'tenant',
-  deps: { repo: TENANT_REPO },
-  resolve: (ctx, { repo }) => repo.findById(ctx.req.headers['x-tenant-id'] as string),
-})
-
-const LoadProject = defineHttpContextDecorator({
-  key: 'project',
-  dependsOn: ['tenant'],
-  resolve: (ctx) => projectsRepo.find(ctx.get('tenant')!.id, ctx.params.id),
-})
-
-@LoadTenant
-@LoadProject
-@Get('/projects/:id')
-getProject(ctx: RequestContext) { ctx.json(ctx.get('project')) }
-\`\`\`
-
-Use \`defineContextDecorator\` (no Http prefix) when authoring a contributor that must run across HTTP, WebSocket, queue, and cron transports — \`Ctx\` defaults to the smaller \`ExecutionContext\` surface (\`get\` / \`set\` / \`requestId\` only, no \`req\`).
-
-Precedence high → low: **method > class > module > adapter > global**.
-Cycles or unmet \`dependsOn\` keys throw \`MissingContributorError\` at boot.
-
-**Critical rules — all stem from the same shared-via-ALS instance model**:
-- Every per-request stage (middleware → contributors → handler) gets its OWN \`RequestContext\` instance, but they all read/write the SAME \`AsyncLocalStorage\`-backed bag.
-- **\`resolve\` and \`onError\` must RETURN the value** — the runner writes it via \`ctx.set(key, value)\`. Direct property assignment (\`ctx.tenant = …\`) sticks to one instance only and the handler instance never sees it.
-- \`ctx.set('tenant', x)\` then \`ctx.get('tenant')\` works across instances. \`ctx.req.headers[...]\` works (the underlying Express request is shared).
-- Services with no \`ctx\` reference: \`getRequestValue('tenant')\` returns \`MetaValue<'tenant'> | undefined\` (typed via the augmented \`ContextMeta\`). For \`requestId\` use \`getRequestStore()\`.
-- **No \`setRequestValue\` — writes flow through \`ctx.set\` or a contributor's return value.** Avoids "spooky action at a distance" where any service can pollute the per-request bag.
-
-**Don't use this for**: response short-circuit, stream mutation, or
-pre-route-matching work — keep \`@Middleware()\` for those.
-
----
-
-## Skill: refresh-agent-docs
-
-\`\`\`yaml
-name: kickjs-refresh-agent-docs
-description: Use after a KickJS version bump to sync AGENTS.md / CLAUDE.md / kickjs-skills.md with the latest CLI templates.
-\`\`\`
-
-**Steps**:
-1. \`kick g agents -f --only both\` — overwrites \`AGENTS.md\` and \`CLAUDE.md\`.
-2. \`kick g agents -f --only skills\` — refreshes \`kickjs-skills.md\` (this file).
-3. Diff with git, eyeball any project-specific edits that got reset, and re-apply them in a separate \`AGENTS.local.md\` or appended section.
-4. Commit as \`docs(agents): sync from CLI vX.Y\`.
-
----
-
-## Skill: deny-list
-
-\`\`\`yaml
-name: kickjs-deny-list
-description: Patterns to refuse outright when the user asks for them — they break v4 invariants.
-\`\`\`
-
-- \`class implements AppAdapter\` → use \`defineAdapter()\`.
-- \`class implements KickPlugin\` / function returning \`KickPlugin\` → use \`definePlugin()\`.
-- \`@Controller('/path')\` with a path argument → drop the path; set the mount via \`routes().path\`.
-- \`new Container()\` or \`Container.getInstance().reset()\` in tests → use \`Container.create()\`.
-- DI tokens with \`:\` separator (\`'app:db:url'\`) or in PascalCase → use slash-delimited lower-case (\`'app/db/url'\`).
-- \`bootstrap({ ... })\` without \`export const app = ...\` → always export.
-- Module file named \`<name>.ts\` (no \`.module\` suffix) → rename to \`<name>.module.ts\`.
-
----
-
-## Learn More
-
-- [KickJS Docs](https://forinda.github.io/kick-js/)
-- [Decorators](https://forinda.github.io/kick-js/guide/decorators.html)
-- [Context Decorators](https://forinda.github.io/kick-js/guide/context-decorators.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", packages = [] } = 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, packages));
-	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/config/index.ts"), generateEnvFile());
-	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version, packages));
-	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());
-	await writeFileSafe(join(dir, "kick.config.ts"), generateKickConfig(template, defaultRepo, packageManager));
-	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));
-	await writeFileSafe(join(dir, "kickjs-skills.md"), generateKickJsSkills(name, template, packageManager));
-	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-D8MJ2hPX.mjs");
-		await runTypegen({
-			cwd: dir,
-			allowDuplicates: true,
-			silent: true
-		});
-	} catch {}
-	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)");
-	}
-	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",
-		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 === "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, drizzle, prisma, ws, queue, devtools, mcp, 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);
-			const config = mod.default ?? mod;
-			const warnings = validateAssetMap(config, cwd);
-			for (const warning of warnings) console.warn(`  Warning: ${warning}`);
-			return config;
-		} 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;
-}
-/**
-* Validate `assetMap` entries on a loaded config. Returns a list of
-* human-readable warnings; the caller decides how to surface them
-* (typically `console.warn`). Never throws — `kick g` and other
-* unrelated commands should keep working even when the assetMap is
-* misconfigured.
-*
-* Checks:
-*
-* - Each entry's `src` is a non-empty string.
-* - The `src` directory exists on disk (otherwise the typegen + build
-*   steps will fail later with cryptic errors).
-* - `dest` doesn't escape the project root (defensive — a `dest:
-*   '../../etc'` typo could write files outside the workspace).
-* - The namespace key is a non-empty string and doesn't include a
-*   `/` (would conflict with the `<namespace>/<key>` manifest format).
-*/
-function validateAssetMap(config, cwd) {
-	const warnings = [];
-	if (!config?.assetMap) return warnings;
-	const root = resolve(cwd);
-	for (const [namespace, entry] of Object.entries(config.assetMap)) {
-		if (!namespace || namespace.includes("/")) {
-			warnings.push(`assetMap key '${namespace}' is invalid — must be a non-empty string without '/'`);
-			continue;
-		}
-		if (typeof entry?.src !== "string" || entry.src.length === 0) {
-			warnings.push(`assetMap.${namespace} is missing a non-empty 'src' field`);
-			continue;
-		}
-		if (!existsSync(resolve(cwd, entry.src))) warnings.push(`assetMap.${namespace}.src ('${entry.src}') does not exist — typegen + build will fail`);
-		if (entry.dest) {
-			if (escapesRoot(resolve(cwd, entry.dest), root)) warnings.push(`assetMap.${namespace}.dest ('${entry.dest}') resolves outside the project root — refusing to copy`);
-		}
-	}
-	return warnings;
-}
-/**
-* Returns true when `path` (absolute) resolves outside of `root`
-* (also absolute). Uses `path.relative` for accuracy:
-*
-* - The result is empty when paths are identical (inside).
-* - It starts with `..` when the path traverses outside the root.
-* - It's absolute (Windows: cross-drive) when there's no relative
-*   path between them.
-*
-* Avoids the prefix-match pitfalls of `startsWith` (e.g. `/app`
-* matching `/app2/...`, or case-mismatches on macOS / Windows).
-*/
-function escapesRoot(path, root) {
-	const rel = relative(root, path);
-	return rel === "" ? false : rel.startsWith("..") || isAbsolute(rel);
-}
-//#endregion
-//#region src/generator-extension/define.ts
-/**
-* Identity factory — returns the spec verbatim. Exists for type
-* inference and forward-compatibility (future fields can be added with
-* defaults).
-*
-* @example
-* ```ts
-* import { defineGenerator } from '@forinda/kickjs-cli'
-*
-* export default [
-*   defineGenerator({
-*     name: 'command',
-*     description: 'Generate a CQRS command + handler',
-*     files: (ctx) => [
-*       {
-*         path: `src/modules/${ctx.kebab}/commands/${ctx.kebab}.command.ts`,
-*         content: `// command for ${ctx.pascal}`,
-*       },
-*     ],
-*   }),
-* ]
-* ```
-*/
-function defineGenerator(spec) {
-	return spec;
-}
-//#endregion
-//#region src/generator-extension/context.ts
-/** Convert any string to snake_case (`UserPost` / `user-post` → `user_post`). */
-function toSnakeCase(name) {
-	return toKebabCase(name).replace(/-/g, "_");
-}
-/**
-* Build a {@link GeneratorContext} from the raw name + invocation
-* arguments. Centralises the case-transformation logic so every plugin
-* generator sees the same shape regardless of how the name was typed
-* on the command line (`Post` vs `post` vs `user_post`).
-*/
-function buildGeneratorContext(input) {
-	const cwd = input.cwd ?? process.cwd();
-	const usePlural = input.pluralize ?? true;
-	const pascal = toPascalCase(input.name);
-	const camel = toCamelCase(input.name);
-	const kebab = toKebabCase(input.name);
-	const snake = toSnakeCase(input.name);
-	const ctx = {
-		name: input.name,
-		pascal,
-		camel,
-		kebab,
-		snake,
-		modulesDir: input.modulesDir ?? "src/modules",
-		cwd,
-		args: input.args ?? [],
-		flags: input.flags ?? {}
-	};
-	if (usePlural) {
-		const pluralKebab = pluralize(kebab);
-		ctx.pluralKebab = pluralKebab;
-		ctx.pluralPascal = toPascalCase(pluralKebab);
-		ctx.pluralCamel = toCamelCase(pluralKebab);
-	}
-	return ctx;
-}
-//#endregion
-export { buildGeneratorContext, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };
-
-//# sourceMappingURL=index.mjs.map
+import { _ as pluralize, a as initProject, b as toKebabCase, d as generateService, f as generateGuard, h as generateModule, i as defineGenerator, l as generateDto, m as generateAdapter, p as generateMiddleware, r as buildGeneratorContext, u as generateController, x as toPascalCase, y as toCamelCase } from "./generator-extension-DRNQpoZP.mjs";
+import { i as loadKickConfig, r as defineConfig } from "./config-DDrgs-I3.mjs";
+import { n as defineCliPlugin, t as KickPluginConflictError } from "./types-CGB8BiQh.mjs";
+export { KickPluginConflictError, buildGeneratorContext, defineCliPlugin, defineConfig, defineGenerator, generateAdapter, generateController, generateDto, generateGuard, generateMiddleware, generateModule, generateService, initProject, loadKickConfig, pluralize, toCamelCase, toKebabCase, toPascalCase };