@forinda/kickjs-cli 2.1.0 → 2.2.1

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.1.0
+ * @forinda/kickjs-cli v2.2.1
  *
  * Copyright (c) Felix Orinda
  *
@@ -10,12 +10,24 @@
  */
 import { Command } from "commander";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
 import { execSync, fork } from "node:child_process";
-import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { arch, platform, release } from "node:os";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
 //#region src/utils/fs.ts
 let _dryRun = false;
 /** Enable/disable dry run mode globally for all writeFileSafe calls */
@@ -108,7 +120,7 @@ function generatePackageJson(name, template, kickjsVersion) {
 */
 function generateViteConfig() {
 	return `import { defineConfig } from 'vite'
-import { resolve } from 'path'
+import { resolve } from 'node:path'
 import swc from 'unplugin-swc'
 import { kickjsVitePlugin } from '@forinda/kickjs-vite'
 
@@ -158,10 +170,13 @@ function generateTsConfig() {
 			experimentalDecorators: true,
 			emitDecoratorMetadata: true,
 			outDir: "dist",
-			rootDir: "src",
 			paths: { "@/*": ["./src/*"] }
 		},
-		include: ["src"]
+		include: [
+			"src",
+			".kickjs/types/**/*.d.ts",
+			".kickjs/types/**/*.ts"
+		]
 	}, null, 2);
 }
 /** Generate .prettierrc with project formatting rules */
@@ -199,6 +214,7 @@ dist/
 coverage/
 .DS_Store
 *.tsbuildinfo
+.kickjs/
 `;
 }
 /** Generate .gitattributes for consistent line endings */
@@ -359,6 +375,41 @@ import { HelloModule } from './hello/hello.module'
 export const modules: AppModuleClass[] = [HelloModule]
 `;
 }
+/**
+* Generate `src/env.ts` — the project's typed env schema.
+*
+* Default-exports a `defineEnv(...)` schema so `kick typegen` can
+* infer it into the global `KickEnv` registry. After typegen runs:
+*
+*   @Value('DATABASE_URL') private url!: Env<'DATABASE_URL'>
+*   process.env.DATABASE_URL  // typed as string
+*
+* Both autocomplete and type-check at compile time.
+*/
+function generateEnvFile() {
+	return `import { defineEnv } from '@forinda/kickjs-config'
+import { z } from 'zod'
+
+/**
+ * Project environment schema.
+ *
+ * Extend the base schema with your application's variables. The
+ * default export is the contract \`kick typegen\` reads to populate
+ * the global \`KickEnv\` registry — that's what makes \`@Value('FOO')\`
+ * autocomplete and \`process.env.FOO\` typed.
+ *
+ * @example
+ *   DATABASE_URL: z.string().url(),
+ *   JWT_SECRET: z.string().min(32),
+ *   REDIS_URL: z.string().url().optional(),
+ */
+export default defineEnv((base) =>
+  base.extend({
+    // DATABASE_URL: z.string().url(),
+  }),
+)
+`;
+}
 /** Generate src/modules/hello/hello.service.ts */
 function generateHelloService() {
 	return `import { Service } from '@forinda/kickjs'
@@ -377,20 +428,25 @@ export class HelloService {
 }
 /** Generate src/modules/hello/hello.controller.ts */
 function generateHelloController() {
-	return `import { Controller, Get, Autowired, type RequestContext } from '@forinda/kickjs'
+	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 helloService!: HelloService
+  @Autowired() private readonly helloService!: HelloService
 
   @Get('/')
-  index(ctx: RequestContext) {
+  index(ctx: Ctx<KickRoutes.HelloController['index']>) {
     ctx.json(this.helloService.greet('World'))
   }
 
   @Get('/health')
-  health(ctx: RequestContext) {
+  health(ctx: Ctx<KickRoutes.HelloController['health']>) {
     ctx.json(this.helloService.healthCheck())
   }
 }
@@ -402,6 +458,13 @@ function generateHelloModule() {
 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',
@@ -428,6 +491,13 @@ export default defineConfig({
     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',
@@ -590,20 +660,22 @@ ${template === "graphql" ? "├── resolvers/         # GraphQL resolvers\n"
 
 ### Controllers
 
-Use decorators to define routes:
+Use decorators to define routes. Annotate \`ctx\` with \`Ctx<KickRoutes.X['method']>\`
+to get fully-typed \`ctx.params\`, \`ctx.body\`, and \`ctx.query\` from the
+generated \`KickRoutes\` namespace (refreshed on \`kick dev\` and \`kick typegen\`).
 
 \`\`\`ts
-import { Controller, Get, Post, RequestContext } from '@forinda/kickjs'
+import { Controller, Get, Post, type Ctx } from '@forinda/kickjs'
 
 @Controller('/users')
 export class UserController {
   @Get('/')
-  async findAll(ctx: RequestContext) {
+  async findAll(ctx: Ctx<KickRoutes.UserController['findAll']>) {
     return ctx.json({ users: [] })
   }
 
   @Post('/')
-  async create(ctx: RequestContext) {
+  async create(ctx: Ctx<KickRoutes.UserController['create']>) {
     const data = ctx.body
     return ctx.created({ user: data })
   }
@@ -646,7 +718,8 @@ export class UserModule {}
 
 ### RequestContext
 
-Every controller method receives \`ctx: RequestContext\`:
+Every controller method receives a \`ctx\` (alias \`Ctx<TRoute>\` or the
+loose \`RequestContext\`):
 
 \`\`\`ts
 ctx.body           // Request body (parsed JSON)
@@ -1153,6 +1226,7 @@ async function initProject(options) {
 	await writeFileSafe(join(dir, ".gitattributes"), generateGitAttributes());
 	await writeFileSafe(join(dir, ".env"), generateEnv());
 	await writeFileSafe(join(dir, ".env.example"), generateEnvExample());
+	await writeFileSafe(join(dir, "src/env.ts"), generateEnvFile());
 	await writeFileSafe(join(dir, "src/index.ts"), generateEntryFile(name, template, cliPkg.version));
 	await writeFileSafe(join(dir, "src/modules/index.ts"), generateModulesIndex());
 	await writeFileSafe(join(dir, "src/modules/hello/hello.service.ts"), generateHelloService());
@@ -1197,6 +1271,14 @@ async function initProject(options) {
 			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
 		}
 	}
+	try {
+		const { runTypegen } = await Promise.resolve().then(() => typegen_exports);
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
 	console.log("\n  Project scaffolded successfully!");
 	console.log();
 	const needsCd = dir !== process.cwd();
@@ -1542,8 +1624,7 @@ export class ${pascal}Module implements AppModule {
 /** 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 } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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'
@@ -1554,18 +1635,23 @@ 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 create${pascal}UseCase!: Create${pascal}UseCase
-  @Autowired() private get${pascal}UseCase!: Get${pascal}UseCase
-  @Autowired() private list${pluralPascal}UseCase!: List${pluralPascal}UseCase
-  @Autowired() private update${pascal}UseCase!: Update${pascal}UseCase
-  @Autowired() private delete${pascal}UseCase!: Delete${pascal}UseCase
+  @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: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     return ctx.paginate(
       (parsed) => this.list${pluralPascal}UseCase.execute(parsed),
       ${pascal.toUpperCase()}_QUERY_CONFIG,
@@ -1574,7 +1660,7 @@ export class ${pascal}Controller {
 
   @Get('/:id')
   @ApiTags('${pascal}')
-  async getById(ctx: RequestContext) {
+  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)
@@ -1582,21 +1668,21 @@ export class ${pascal}Controller {
 
   @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
   @ApiTags('${pascal}')
-  async create(ctx: RequestContext) {
+  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: RequestContext) {
+  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: RequestContext) {
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
     await this.delete${pascal}UseCase.execute(ctx.params.id)
     ctx.noContent()
   }
@@ -1605,24 +1691,28 @@ export class ${pascal}Controller {
 }
 /** REST controller — injects service directly, flat import paths */
 function generateRestController(ctx) {
-	const { pascal, kebab, plural = "", pluralPascal = "" } = ctx;
+	const { pascal, kebab } = ctx;
 	const camel = pascal.charAt(0).toLowerCase() + pascal.slice(1);
-	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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 ${camel}Service!: ${pascal}Service
+  @Autowired() private readonly ${camel}Service!: ${pascal}Service
 
   @Get('/')
   @ApiTags('${pascal}')
   @ApiQueryParams(${pascal.toUpperCase()}_QUERY_CONFIG)
-  async list(ctx: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     return ctx.paginate(
       (parsed) => this.${camel}Service.findPaginated(parsed),
       ${pascal.toUpperCase()}_QUERY_CONFIG,
@@ -1631,7 +1721,7 @@ export class ${pascal}Controller {
 
   @Get('/:id')
   @ApiTags('${pascal}')
-  async getById(ctx: RequestContext) {
+  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)
@@ -1639,21 +1729,21 @@ export class ${pascal}Controller {
 
   @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
   @ApiTags('${pascal}')
-  async create(ctx: RequestContext) {
+  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: RequestContext) {
+  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: RequestContext) {
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
     await this.${camel}Service.delete(ctx.params.id)
     ctx.noContent()
   }
@@ -1834,6 +1924,7 @@ function generateRepositoryInterface(ctx) {
  *
  * 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'
@@ -1848,7 +1939,13 @@ export interface I${pascal}Repository {
   delete(id: string): Promise<void>
 }
 
-export const ${pascal.toUpperCase()}_REPOSITORY = Symbol('I${pascal}Repository')
+/**
+ * Collision-safe DI token bound to \`I${pascal}Repository\`.
+ * \`container.resolve(${pascal.toUpperCase()}_REPOSITORY)\` and
+ * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
+ * interface — no manual generic, no \`any\` cast.
+ */
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${pascal}/Repository')
 `;
 }
 function generateInMemoryRepository(ctx) {
@@ -2376,8 +2473,7 @@ export class ${pascal}Module implements AppModule {
 /** 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 } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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'
@@ -2388,18 +2484,23 @@ 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 create${pascal}Command!: Create${pascal}Command
-  @Autowired() private update${pascal}Command!: Update${pascal}Command
-  @Autowired() private delete${pascal}Command!: Delete${pascal}Command
-  @Autowired() private get${pascal}Query!: Get${pascal}Query
-  @Autowired() private list${pluralPascal}Query!: List${pluralPascal}Query
+  @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: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     return ctx.paginate(
       (parsed) => this.list${pluralPascal}Query.execute(parsed),
       ${pascal.toUpperCase()}_QUERY_CONFIG,
@@ -2408,7 +2509,7 @@ export class ${pascal}Controller {
 
   @Get('/:id')
   @ApiTags('${pascal}')
-  async getById(ctx: RequestContext) {
+  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)
@@ -2416,21 +2517,21 @@ export class ${pascal}Controller {
 
   @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
   @ApiTags('${pascal}')
-  async create(ctx: RequestContext) {
+  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: RequestContext) {
+  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: RequestContext) {
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
     await this.delete${pascal}Command.execute(ctx.params.id)
     ctx.noContent()
   }
@@ -2829,13 +2930,15 @@ async function generateMinimalFiles(ctx) {
 		kebab,
 		plural
 	}));
-	await write(`${kebab}.controller.ts`, `import { Controller, Get } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     ctx.json({ message: '${pascal} list' })
   }
 }
@@ -3567,20 +3670,24 @@ async function generateController(options) {
 	const pascal = toPascalCase(name);
 	const files = [];
 	const filePath = join(outDir, `${kebab}.controller.ts`);
-	await writeFileSafe(filePath, `import { Controller, Get, Post, Autowired } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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 myService!: MyService
+  // @Autowired() private readonly myService!: MyService
 
   @Get('/')
-  async list(ctx: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     ctx.json({ message: '${pascal} list' })
   }
 
   @Post('/')
-  async create(ctx: RequestContext) {
+  async create(ctx: Ctx<KickRoutes.${pascal}Controller['create']>) {
     ctx.created({ message: '${pascal} created', data: ctx.body })
   }
 }
@@ -3913,7 +4020,7 @@ async function generateScaffold(options) {
 		await writeFileSafe(fullPath, content);
 		files.push(fullPath);
 	};
-	await write("index.ts", genModuleIndex(pascal, kebab, plural, repo));
+	await write("index.ts", genModuleIndex(pascal, kebab, plural));
 	await write("constants.ts", genConstants(pascal, fields));
 	await write(`presentation/${kebab}.controller.ts`, genController(pascal, kebab, plural, pluralPascal));
 	await write(`application/dtos/create-${kebab}.dto.ts`, genCreateDTO(pascal, fields));
@@ -4100,30 +4207,44 @@ export class ${pascal}Id {
 }
 `;
 }
-function genModuleIndex(pascal, kebab, plural, repo) {
-	return `import type { AppModule, AppModuleClass } from '@forinda/kickjs'
+function genModuleIndex(pascal, kebab, plural) {
+	return `import { type AppModule, type ModuleRoutes, Container, buildRoutes } from '@forinda/kickjs'
 import { ${pascal}Controller } from './presentation/${kebab}.controller'
-import { ${pascal}DomainService } from './domain/services/${kebab}-domain.service'
 import { ${pascal.toUpperCase()}_REPOSITORY } from './domain/repositories/${kebab}.repository'
 import { InMemory${pascal}Repository } from './infrastructure/repositories/in-memory-${kebab}.repository'
 
+// Eagerly load decorated classes so @Service()/@Repository() decorators
+// register in the DI container before the application bootstraps.
+import.meta.glob(
+  ['./domain/services/**/*.ts', './application/use-cases/**/*.ts', '!./**/*.test.ts'],
+  { eager: true },
+)
+
 export class ${pascal}Module implements AppModule {
-  register(container: any): void {
+  /**
+   * Bind the repository token to its concrete implementation.
+   * Decorator-managed classes (@Service, @Controller, @Repository) are
+   * registered automatically — only token-to-impl bindings need to live here.
+   */
+  register(container: Container): void {
     container.registerFactory(
       ${pascal.toUpperCase()}_REPOSITORY,
       () => container.resolve(InMemory${pascal}Repository),
     )
   }
 
-  routes() {
-    return { prefix: '/${plural}', controllers: [${pascal}Controller] }
+  routes(): ModuleRoutes {
+    return {
+      path: '/${plural}',
+      router: buildRoutes(${pascal}Controller),
+      controller: ${pascal}Controller,
+    }
   }
 }
 `;
 }
 function genController(pascal, kebab, plural, pluralPascal) {
-	return `import { Controller, Get, Post, Put, Delete, Autowired, ApiQueryParams } from '@forinda/kickjs'
-import type { RequestContext } from '@forinda/kickjs'
+	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'
@@ -4134,18 +4255,23 @@ 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 create${pascal}UseCase!: Create${pascal}UseCase
-  @Autowired() private get${pascal}UseCase!: Get${pascal}UseCase
-  @Autowired() private list${pluralPascal}UseCase!: List${pluralPascal}UseCase
-  @Autowired() private update${pascal}UseCase!: Update${pascal}UseCase
-  @Autowired() private delete${pascal}UseCase!: Delete${pascal}UseCase
+  @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: RequestContext) {
+  async list(ctx: Ctx<KickRoutes.${pascal}Controller['list']>) {
     return ctx.paginate(
       (parsed) => this.list${pluralPascal}UseCase.execute(parsed),
       ${pascal.toUpperCase()}_QUERY_CONFIG,
@@ -4154,7 +4280,7 @@ export class ${pascal}Controller {
 
   @Get('/:id')
   @ApiTags('${pascal}')
-  async getById(ctx: RequestContext) {
+  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)
@@ -4162,21 +4288,21 @@ export class ${pascal}Controller {
 
   @Post('/', { body: create${pascal}Schema, name: 'Create${pascal}' })
   @ApiTags('${pascal}')
-  async create(ctx: RequestContext) {
+  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: RequestContext) {
+  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: RequestContext) {
+  async remove(ctx: Ctx<KickRoutes.${pascal}Controller['remove']>) {
     await this.delete${pascal}UseCase.execute(ctx.params.id)
     ctx.noContent()
   }
@@ -4184,7 +4310,8 @@ export class ${pascal}Controller {
 `;
 }
 function genRepositoryInterface(pascal, kebab) {
-	return `import type { ${pascal}ResponseDTO } from '../../application/dtos/${kebab}-response.dto'
+	return `import { createToken } from '@forinda/kickjs'
+import type { ${pascal}ResponseDTO } from '../../application/dtos/${kebab}-response.dto'
 import type { Create${pascal}DTO } from '../../application/dtos/create-${kebab}.dto'
 import type { Update${pascal}DTO } from '../../application/dtos/update-${kebab}.dto'
 import type { ParsedQuery } from '@forinda/kickjs'
@@ -4198,7 +4325,13 @@ export interface I${pascal}Repository {
   delete(id: string): Promise<void>
 }
 
-export const ${pascal.toUpperCase()}_REPOSITORY = Symbol('I${pascal}Repository')
+/**
+ * Collision-safe DI token bound to \`I${pascal}Repository\`.
+ * \`container.resolve(${pascal.toUpperCase()}_REPOSITORY)\` and
+ * \`@Inject(${pascal.toUpperCase()}_REPOSITORY)\` both return the typed
+ * interface — no manual generic, no \`any\` cast.
+ */
+export const ${pascal.toUpperCase()}_REPOSITORY = createToken<I${pascal}Repository>('${pascal}/Repository')
 `;
 }
 function genDomainService(pascal, kebab) {
@@ -4400,6 +4533,949 @@ async function loadKickConfig(cwd) {
 	return null;
 }
 //#endregion
+//#region src/typegen/scanner.ts
+/** Decorators that mark a class as DI-managed */
+const DECORATOR_NAMES = [
+	"Service",
+	"Controller",
+	"Repository",
+	"Injectable",
+	"Component",
+	"Module"
+];
+const DEFAULT_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".mts",
+	".cts"
+];
+const DEFAULT_EXCLUDES = [
+	"node_modules",
+	".kickjs",
+	"dist",
+	"build",
+	".test.",
+	".spec.",
+	".d.ts"
+];
+/**
+* Match a class-level decorator immediately followed by an exported
+* class declaration. Captures decorator name and class name.
+*/
+const DECORATED_CLASS_REGEX = new RegExp(String.raw`@(${DECORATOR_NAMES.join("|")})\s*\([^)]*\)` + String.raw`(?:\s*@[A-Z]\w*(?:\s*\([^)]*\))?)*` + String.raw`\s*export\s+(default\s+)?(?:abstract\s+)?class\s+(\w+)`, "g");
+/**
+* Match a `createToken<T>('name')` call with optional `export const X =`
+* or `const X =` prefix. Tolerates whitespace and the type parameter
+* being absent (`createToken('name')`).
+*/
+const CREATE_TOKEN_REGEX = /(?:export\s+)?const\s+(\w+)\s*(?::\s*[^=]+)?=\s*createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/**
+* Match a bare `createToken<T>('name')` call (no const assignment) so
+* we still pick up dynamically-used tokens.
+*/
+const BARE_CREATE_TOKEN_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/** Match `@Inject('literal')` — only literals; computed args are skipped */
+const INJECT_LITERAL_REGEX = /@Inject\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+/**
+* Match a route decorator immediately followed by a method declaration.
+* Captures the HTTP verb, path literal (or empty), and method name.
+*
+* Tolerates:
+* - Optional second arg to the route decorator (`@Get('/path', { ... })`)
+* - Stacked decorators between the route and the method (`@Get('/') @Use(...)`)
+* - Path-less decorators (`@Get()` → defaults to `/`)
+* - `async` modifier on the method
+*
+* Run within a class body slice (see extractRoutesFromSource) so the
+* captured method name is unambiguously a method on that class.
+*/
+const ROUTE_METHOD_REGEX = new RegExp(String.raw`@(${[
+	"Get",
+	"Post",
+	"Put",
+	"Delete",
+	"Patch"
+].join("|")})\s*\(` + String.raw`(?:\s*['"\`]([^'"\`]*)['"\`])?[^)]*\)` + String.raw`(?:\s*@[A-Z]\w*(?:\s*\([^)]*\))?)*` + String.raw`\s*(?:public\s+|private\s+|protected\s+)?(?:async\s+)?` + String.raw`([a-zA-Z_]\w*)\s*\(`, "g");
+/** Extract `:placeholder` segments from an Express route path */
+function extractPathParams(path) {
+	return (path.match(/:([a-zA-Z_]\w*)/g) ?? []).map((m) => m.slice(1));
+}
+/**
+* Given the matched text of a route decorator + method declaration, return
+* the substring inside the route decorator's argument list (between the
+* outermost `(` and `)`). Returns `null` if no parens are found.
+*
+* Example input:
+*   `@Post('/', { body: createTaskSchema, name: 'CreateTask' }) async create(`
+* Returns:
+*   `'/', { body: createTaskSchema, name: 'CreateTask' }`
+*/
+function extractRouteOptionsArg(matchedText) {
+	const open = matchedText.indexOf("(");
+	if (open < 0) return null;
+	let depth = 1;
+	for (let i = open + 1; i < matchedText.length; i++) {
+		const ch = matchedText[i];
+		if (ch === "(") depth++;
+		else if (ch === ")") {
+			depth--;
+			if (depth === 0) return matchedText.slice(open + 1, i);
+		}
+	}
+	return null;
+}
+/**
+* Extract a bare identifier value from a single field in an object literal
+* embedded in a string. Returns `null` if the field is missing or its value
+* isn't a bare identifier (e.g. an inline object, function call, etc.).
+*
+* Example: `extractObjectFieldIdentifier("'/' , { body: createTaskSchema }", 'body')`
+* returns `'createTaskSchema'`.
+*/
+function extractObjectFieldIdentifier(text, field) {
+	const m = new RegExp(String.raw`\b${field}\s*:\s*([A-Za-z_$][\w$]*)`, "g").exec(text);
+	if (!m) return null;
+	return m[1];
+}
+/**
+* Resolve a bare identifier to its module source by inspecting the file's
+* top-level imports and same-file `const` declarations.
+*
+* - `import { X } from './path'` → returns `'./path'`
+* - `import X from './path'` (default import) → returns `'./path'`
+* - `import * as X from './path'` → returns `'./path'`
+* - `const X = z.object(...)` (same file) → returns `null` (caller emits a self-import)
+*
+* Returns `null` when the identifier cannot be resolved.
+*/
+function resolveImportSource(source, identifier) {
+	const named = new RegExp(String.raw`import\s*(?:type\s+)?\{[^}]*\b${identifier}\b[^}]*\}\s*from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (named) return named[1];
+	const def = new RegExp(String.raw`import\s+(?:type\s+)?${identifier}\s+from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (def) return def[1];
+	const ns = new RegExp(String.raw`import\s*\*\s*as\s+${identifier}\s+from\s*['"\`]([^'"\`]+)['"\`]`).exec(source);
+	if (ns) return ns[1];
+	if (new RegExp(String.raw`(?:^|\n)\s*(?:export\s+)?const\s+${identifier}\b`).test(source)) return "";
+	return null;
+}
+/**
+* Extract whitelist arrays from an `@ApiQueryParams(...)` decorator
+* within `decoratorBlock`. Handles two forms:
+*
+* - Inline literal: `@ApiQueryParams({ filterable: ['a', 'b'], ... })`
+* - Const reference: `@ApiQueryParams(SOME_CONFIG)` — looks up
+*   `const SOME_CONFIG = { ... }` in the same file (`fullSource`).
+*
+* Returns `null` if no `@ApiQueryParams` is present. Returns
+* `{ filterable: [], sortable: [], searchable: [] }` if the decorator
+* is present but no fields could be statically extracted (opaque
+* imports, column-object configs, function calls, etc.).
+*/
+function extractApiQueryParams(decoratorBlock, fullSource) {
+	const apiMatch = /@ApiQueryParams\s*\(\s*([\s\S]*?)\s*\)\s*$/.exec(decoratorBlock);
+	if (!apiMatch) {
+		const loose = /@ApiQueryParams\s*\(([\s\S]*?)\)/.exec(decoratorBlock);
+		if (!loose) return null;
+		return parseApiQueryParamsArg(loose[1].trim(), fullSource);
+	}
+	return parseApiQueryParamsArg(apiMatch[1].trim(), fullSource);
+}
+function parseApiQueryParamsArg(arg, fullSource) {
+	if (arg.startsWith("{")) return parseInlineConfigLiteral(arg);
+	const idMatch = /^([A-Za-z_]\w*)/.exec(arg);
+	if (idMatch) {
+		const ident = idMatch[1];
+		const constMatch = new RegExp(String.raw`const\s+${ident}\s*(?::\s*[^=]+)?=\s*(\{[\s\S]*?\n\})`, "m").exec(fullSource);
+		if (constMatch) return parseInlineConfigLiteral(constMatch[1]);
+	}
+	return {
+		filterable: [],
+		sortable: [],
+		searchable: []
+	};
+}
+/** Extract a string array literal for one config key from an inline object literal */
+function extractStringArray(literal, key) {
+	const m = new RegExp(String.raw`${key}\s*:\s*\[([\s\S]*?)\]`).exec(literal);
+	if (!m) return [];
+	return Array.from(m[1].matchAll(/['"`]([^'"`]+)['"`]/g)).map((x) => x[1]);
+}
+/** Parse an inline `{ filterable: [...], sortable: [...], searchable: [...] }` literal */
+function parseInlineConfigLiteral(literal) {
+	return {
+		filterable: extractStringArray(literal, "filterable"),
+		sortable: extractStringArray(literal, "sortable"),
+		searchable: extractStringArray(literal, "searchable")
+	};
+}
+/** Recursively walk a directory and yield matching file paths */
+async function walk(dir, opts) {
+	const exts = opts.extensions ?? DEFAULT_EXTENSIONS;
+	const excludes = opts.exclude ?? DEFAULT_EXCLUDES;
+	const out = [];
+	let entries;
+	try {
+		entries = await readdir(dir, {
+			withFileTypes: true,
+			encoding: "utf-8"
+		});
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		const rel = relative(opts.cwd, full);
+		if (excludes.some((ex) => rel.includes(ex))) continue;
+		if (entry.isDirectory()) out.push(...await walk(full, opts));
+		else if (entry.isFile()) {
+			if (exts.some((ext) => entry.name.endsWith(ext))) out.push(full);
+		}
+	}
+	return out;
+}
+/** Compute the forward-slash relative path used in scanner output */
+function toRelative(filePath, cwd) {
+	return relative(cwd, filePath).split(sep).join("/");
+}
+/** Extract decorated classes from a single source file */
+function extractClassesFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	DECORATED_CLASS_REGEX.lastIndex = 0;
+	let match;
+	while ((match = DECORATED_CLASS_REGEX.exec(source)) !== null) {
+		const [, decorator, defaultMarker, className] = match;
+		out.push({
+			className,
+			decorator,
+			filePath,
+			relativePath: relPath,
+			isDefault: Boolean(defaultMarker)
+		});
+	}
+	return out;
+}
+/** Extract `createToken('name')` definitions from a single source file */
+function extractTokensFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	CREATE_TOKEN_REGEX.lastIndex = 0;
+	let match;
+	while ((match = CREATE_TOKEN_REGEX.exec(source)) !== null) {
+		const [full, variable, name] = match;
+		seen.add(full);
+		out.push({
+			name,
+			variable,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	BARE_CREATE_TOKEN_REGEX.lastIndex = 0;
+	while ((match = BARE_CREATE_TOKEN_REGEX.exec(source)) !== null) {
+		if (seen.has(match[0])) continue;
+		out.push({
+			name: match[1],
+			variable: null,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Extract route handlers from a source file.
+*
+* For each decorated class in `classesInFile`, slices the source from
+* the class declaration to the next class (or EOF) and runs the route
+* decorator regex within that slice. The result is a list of routes
+* tagged with their owning controller.
+*
+* Heuristic note: this assumes classes are not nested. KickJS controllers
+* are top-level by convention so this holds in practice.
+*/
+function extractRoutesFromSource(source, filePath, cwd, classesInFile) {
+	const out = [];
+	if (classesInFile.length === 0) return out;
+	const relPath = toRelative(filePath, cwd);
+	const positions = [];
+	for (const cls of classesInFile) {
+		const m = new RegExp(String.raw`class\s+${cls.className}\b`).exec(source);
+		if (m?.index !== void 0) positions.push({
+			cls,
+			start: m.index
+		});
+	}
+	positions.sort((a, b) => a.start - b.start);
+	for (let i = 0; i < positions.length; i++) {
+		const { cls, start } = positions[i];
+		const end = i + 1 < positions.length ? positions[i + 1].start : source.length;
+		const block = source.slice(start, end);
+		ROUTE_METHOD_REGEX.lastIndex = 0;
+		let match;
+		while ((match = ROUTE_METHOD_REGEX.exec(block)) !== null) {
+			const [matchedText, verb, pathLiteral, methodName] = match;
+			const path = pathLiteral && pathLiteral.length > 0 ? pathLiteral : "/";
+			const apiQp = extractApiQueryParams(matchedText, source);
+			const routeArgs = extractRouteOptionsArg(matchedText);
+			const bodyId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "body") : null;
+			const queryId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "query") : null;
+			const paramsId = routeArgs ? extractObjectFieldIdentifier(routeArgs, "params") : null;
+			out.push({
+				controller: cls.className,
+				method: methodName,
+				httpMethod: verb.toUpperCase(),
+				path,
+				pathParams: extractPathParams(path),
+				queryFilterable: apiQp?.filterable ?? null,
+				querySortable: apiQp?.sortable ?? null,
+				querySearchable: apiQp?.searchable ?? null,
+				bodySchema: bodyId ? {
+					identifier: bodyId,
+					source: resolveImportSource(source, bodyId)
+				} : null,
+				querySchema: queryId ? {
+					identifier: queryId,
+					source: resolveImportSource(source, queryId)
+				} : null,
+				paramsSchema: paramsId ? {
+					identifier: paramsId,
+					source: resolveImportSource(source, paramsId)
+				} : null,
+				filePath,
+				relativePath: relPath
+			});
+		}
+	}
+	return out;
+}
+/** Extract `@Inject('literal')` calls from a single source file */
+function extractInjectsFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	INJECT_LITERAL_REGEX.lastIndex = 0;
+	let match;
+	while ((match = INJECT_LITERAL_REGEX.exec(source)) !== null) out.push({
+		name: match[1],
+		filePath,
+		relativePath: relPath
+	});
+	return out;
+}
+/**
+* Look for an env schema file at `<cwd>/<envFile>`. Returns a
+* `DiscoveredEnv` if the file exists and contains both a
+* `defineEnv(...)` call and a default export — the two markers we
+* need before it's safe to emit `import type schema from '...'` in
+* the generator.
+*
+* Returns `null` for any other state (file missing, no defineEnv, no
+* default export) so the generator skips env typing silently. Users
+* who want env typing must opt in by writing `src/env.ts` to the
+* documented shape.
+*/
+async function detectEnvFile(cwd, envFile) {
+	const abs = resolve(cwd, envFile);
+	let source;
+	try {
+		source = await readFile(abs, "utf-8");
+	} catch {
+		return null;
+	}
+	if (!/\bdefineEnv\s*\(/.test(source)) return null;
+	if (!/export\s+default\b/.test(source)) return null;
+	return {
+		filePath: abs,
+		relativePath: toRelative(abs, cwd)
+	};
+}
+/** Detect duplicate class names across files */
+function findCollisions(classes) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const cls of classes) {
+		const arr = groups.get(cls.className) ?? [];
+		arr.push(cls);
+		groups.set(cls.className, arr);
+	}
+	const collisions = [];
+	for (const [className, group] of groups) if (new Set(group.map((c) => c.filePath)).size > 1) collisions.push({
+		className,
+		classes: group
+	});
+	collisions.sort((a, b) => a.className.localeCompare(b.className));
+	return collisions;
+}
+/**
+* Scan a project for decorated classes, createToken definitions, and
+* `@Inject` literal usages.
+*/
+async function scanProject(opts) {
+	const files = await walk(resolve(opts.root), opts);
+	const classes = [];
+	const routes = [];
+	const tokens = [];
+	const injects = [];
+	const sources = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		let source;
+		try {
+			source = await readFile(file, "utf-8");
+		} catch {
+			continue;
+		}
+		sources.set(file, source);
+		classes.push(...extractClassesFromSource(source, file, opts.cwd));
+		tokens.push(...extractTokensFromSource(source, file, opts.cwd));
+		injects.push(...extractInjectsFromSource(source, file, opts.cwd));
+	}
+	for (const [file, source] of sources) {
+		const classesInFile = classes.filter((c) => c.filePath === file);
+		routes.push(...extractRoutesFromSource(source, file, opts.cwd, classesInFile));
+	}
+	classes.sort((a, b) => {
+		if (a.className !== b.className) return a.className.localeCompare(b.className);
+		return a.relativePath.localeCompare(b.relativePath);
+	});
+	tokens.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	injects.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	routes.sort((a, b) => a.controller.localeCompare(b.controller) || a.method.localeCompare(b.method));
+	return {
+		classes,
+		routes,
+		tokens,
+		injects,
+		collisions: findCollisions(classes),
+		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts")
+	};
+}
+//#endregion
+//#region src/typegen/generator.ts
+/**
+* Generates `.d.ts` files inside `.kickjs/types/` from the discovered
+* decorated classes and DI tokens. Pattern modeled on React Router's
+* `.react-router/types/` directory.
+*
+* Outputs:
+* - `.kickjs/types/registry.d.ts` — module augmentation for `KickJsRegistry`
+*    that gives `container.resolve('UserService')` the right return type.
+* - `.kickjs/types/services.d.ts` — string-literal union of all known
+*   service-style tokens for tooling autocomplete.
+* - `.kickjs/types/modules.d.ts` — string-literal union of discovered
+*   module class names.
+* - `.kickjs/types/index.d.ts` — re-exports the above (single import target).
+* - `.kickjs/.gitignore` — gitignores the whole folder so generated files
+*   never get committed.
+*
+* ## Collision behaviour
+*
+* If `findCollisions()` returns any duplicate class names:
+* - **Default (`allowDuplicates: false`)** — `generateTypes` throws a
+*   `TokenCollisionError` with a clear message listing every conflicting
+*   file. The caller (CLI) prints it and exits non-zero. Nothing is
+*   written to disk.
+* - **`allowDuplicates: true`** — colliding classes are auto-namespaced
+*   by their relative file path so the registry keys become e.g.
+*   `'modules/users/UserService'` instead of `'UserService'`. Non-colliding
+*   classes still get bare `'ClassName'` keys (smart default).
+*
+* @module @forinda/kickjs-cli/typegen/generator
+*/
+/** Header written to every generated file */
+const HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+/** Decorators whose classes participate in the DI registry augmentation */
+const REGISTRY_DECORATORS = new Set([
+	"Service",
+	"Repository",
+	"Injectable",
+	"Component"
+]);
+/** Thrown by `generateTypes` when collisions are found and not allowed */
+var TokenCollisionError = class extends Error {
+	collisions;
+	constructor(collisions) {
+		super(formatCollisionMessage(collisions));
+		this.name = "TokenCollisionError";
+		this.collisions = collisions;
+	}
+};
+/** Build a human-readable message describing every collision */
+function formatCollisionMessage(collisions) {
+	const lines = ["kick typegen: token collision detected"];
+	for (const c of collisions) {
+		lines.push("");
+		lines.push(`  ${c.classes.length} classes named '${c.className}':`);
+		for (const cls of c.classes) lines.push(`    - ${cls.relativePath}`);
+	}
+	lines.push("");
+	lines.push("Resolutions:");
+	lines.push("  (a) Rename one of the classes");
+	lines.push("  (b) Use createToken<T>('namespaced/Name') and import the token explicitly — see @forinda/kickjs");
+	lines.push("  (c) Pass --allow-duplicates to namespace the registry keys automatically");
+	lines.push("      (e.g. 'modules/users/UserService' instead of 'UserService')");
+	return lines.join("\n");
+}
+/** Compute the module specifier (without extension) used inside `import('...')` */
+function importSpecifierFor(targetFile, fromFile) {
+	let rel = relative(dirname(fromFile), targetFile).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return rel;
+}
+/**
+* Build the namespaced registry key for a colliding class.
+* Strips the `src/` prefix and the file extension, then appends the
+* class name. Example: `src/modules/users/user.service.ts` + `UserService`
+* → `modules/users/UserService`.
+*/
+function namespacedKeyFor(cls) {
+	const parts = cls.relativePath.replace(/^src\//, "").replace(/\.(ts|tsx|mts|cts)$/i, "").split("/");
+	parts.pop();
+	const ns = parts.join("/");
+	return ns ? `${ns}/${cls.className}` : cls.className;
+}
+/**
+* Render the `KickJsRegistry` module augmentation. Each entry maps a
+* string token to the imported class type.
+*
+* Default-exported classes are imported as `import('...').default`.
+*
+* `collidingNames` lists class names that should be auto-namespaced;
+* everything else gets a bare key.
+*/
+function renderRegistry(classes, outFile, collidingNames) {
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const c of classes) {
+		if (!REGISTRY_DECORATORS.has(c.decorator)) continue;
+		const key = collidingNames.has(c.className) ? namespacedKeyFor(c) : c.className;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const spec = importSpecifierFor(c.filePath, outFile);
+		const ref = c.isDefault ? `import('${spec}').default` : `import('${spec}').${c.className}`;
+		entries.push(`    '${key}': ${ref}`);
+	}
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  interface KickJsRegistry {
+${entries.length ? entries.join("\n") : "    // (no services discovered yet — run `kick g service <name>` to add one)"}
+  }
+}
+
+export {}
+`;
+}
+/** Render a string-literal union type containing the given names */
+function renderUnion(typeName, names, emptyComment) {
+	if (names.length === 0) return `${HEADER}
+// ${emptyComment}
+export type ${typeName} = never
+`;
+	return `${HEADER}
+export type ${typeName} =
+${[...new Set(names)].sort().map((n) => `  | '${n}'`).join("\n")}
+`;
+}
+/** Render the barrel index that re-exports the union types */
+function renderIndex(includeEnv) {
+	return `${HEADER}
+export type { ServiceToken } from './services'
+export type { ModuleToken } from './modules'
+
+// The registry, routes, and env augmentations are loaded as side-effects —
+// importing this file (or having it on tsconfig include) is enough for
+// \`container.resolve()\`, \`Ctx<KickRoutes.UserController['getUser']>\`,
+// and \`@Value('PORT')\` to resolve.
+import './registry'
+import './routes'
+${includeEnv ? "import './env'\n" : ""}`;
+}
+/**
+* Render the `query` field's TypeScript type for a single route.
+*
+* - When `@ApiQueryParams` is absent (`queryFilterable === null`), emits
+*   `unknown` so the user gets nothing extra.
+* - When the decorator is present, emits an object literal whose keys
+*   are the standard query string keys (`filter`, `sort`, `q`, `page`,
+*   `limit`). `sort` is narrowed to a string-literal union of allowed
+*   field names with optional `-` direction prefix.
+*/
+function renderQueryShape(m) {
+	if (m.queryFilterable === null) return "unknown";
+	const sortable = m.querySortable ?? [];
+	return `{ filter?: string | string[]; sort?: ${sortable.length > 0 ? sortable.flatMap((f) => [`'${f}'`, `'-${f}'`]).join(" | ") : "string"}; q?: string; page?: string; limit?: string }`;
+}
+/** Render JSDoc lines summarising the @ApiQueryParams whitelist */
+function renderQueryDocLines(m) {
+	const lines = [];
+	if (m.queryFilterable && m.queryFilterable.length > 0) lines.push(`Filterable: ${m.queryFilterable.join(", ")}`);
+	if (m.querySortable && m.querySortable.length > 0) lines.push(`Sortable: ${m.querySortable.join(", ")}`);
+	if (m.querySearchable && m.querySearchable.length > 0) lines.push(`Searchable: ${m.querySearchable.join(", ")}`);
+	return lines;
+}
+/**
+* Plan a schema import for hoisting at the top of `routes.ts`. Returns
+* the alias the in-namespace code should use, or `null` if the schema
+* cannot be referenced (no validator configured, or source unresolvable).
+*
+* Aliases are unique per (alias-counter) so two schemas named
+* `createTaskSchema` from different modules don't collide.
+*/
+function planSchemaImport(schema, routeFilePath, routesOutFile, schemaValidator, imports) {
+	if (!schema || schemaValidator !== "zod") return null;
+	if (schema.source === null) return null;
+	const specifier = resolveSchemaImportSpecifier(schema.source, routeFilePath, routesOutFile);
+	if (specifier === "unknown") return null;
+	const key = `${specifier}::${schema.identifier}`;
+	let alias = imports.get(key)?.specifier;
+	if (!alias) {
+		alias = `_S${imports.size}`;
+		imports.set(key, {
+			identifier: schema.identifier,
+			specifier: alias
+		});
+	} else alias = imports.get(key).specifier;
+	return alias;
+}
+/** Build the `import type { ... } from '...'` lines for hoisted schema imports */
+function renderSchemaImports(imports) {
+	if (imports.size === 0) return "";
+	const lines = [];
+	for (const [key, value] of imports) {
+		const [path] = key.split("::");
+		lines.push(`import type { ${value.identifier} as ${value.specifier} } from '${path}'`);
+	}
+	return lines.join("\n") + "\n";
+}
+/**
+* Compute the import specifier the generated `routes.d.ts` should use to
+* reach a schema declared either in the controller file (empty string)
+* or imported from elsewhere (relative path or bare module name).
+*
+* - Bare module names (`zod`, `@scope/pkg`) are returned as-is.
+* - Relative paths (`./users.dto`, `../shared/schema`) are resolved
+*   against the controller's file path, then re-relativised against the
+*   directory containing `routes.d.ts`.
+* - Empty string (same-file schema) becomes a relative path from the
+*   `routes.d.ts` directory back to the controller file.
+*/
+function resolveSchemaImportSpecifier(source, routeFilePath, routesOutFile) {
+	if (source === null) return "unknown";
+	const routesDir = dirname(routesOutFile);
+	if (source === "") {
+		let rel = relative(routesDir, routeFilePath).split(sep).join("/");
+		rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+		if (!rel.startsWith(".")) rel = "./" + rel;
+		return rel;
+	}
+	if (!source.startsWith(".") && !source.startsWith("/")) return source;
+	let rel = relative(routesDir, resolve(dirname(routeFilePath), source)).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return rel;
+}
+/**
+* Render the `KickEnv` + `NodeJS.ProcessEnv` augmentation file from a
+* detected env schema. Mirrors the routes.ts pattern: emits as a `.ts`
+* file (not `.d.ts`) so the top-level `import type schema from '...'`
+* actually resolves under `moduleResolution: 'bundler'`.
+*
+* Returns `null` when no env file was discovered, so the caller can
+* skip writing the file altogether (rather than emitting an empty
+* augmentation that would shadow `KickEnv` to a useless `{}`).
+*/
+function renderEnv(env, envOutFile) {
+	if (!env) return null;
+	let rel = relative(dirname(envOutFile), env.filePath).split(sep).join("/");
+	rel = rel.replace(/\.(ts|tsx|mts|cts)$/i, "");
+	if (!rel.startsWith(".")) rel = "./" + rel;
+	return `${HEADER}
+// Importing the schema as a type lets us infer its shape without
+// pulling in any runtime code. \`Awaited<>\` strips an accidental
+// Promise wrap on dynamic-imported defaults.
+import type _envSchema from '${rel}'
+
+// Local type alias — interfaces can only \`extend\` an identifier,
+// not an inline import expression, so we resolve the schema's
+// inferred shape into a named type first.
+type _KickEnvShape = import('zod').infer<typeof _envSchema>
+
+declare global {
+  /**
+   * Typed environment registry. Augmented from \`${env.relativePath}\`
+   * so \`@Value('PORT')\`, \`Env<'PORT'>\`, and \`process.env.PORT\` are
+   * all type-safe and autocomplete.
+   */
+  interface KickEnv extends _KickEnvShape {}
+
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace NodeJS {
+    /**
+     * Narrow \`process.env\` so known keys exist as \`string\` (the raw
+     * pre-Zod-coercion form). \`@Value\` and the \`ConfigService\` apply
+     * the schema's transforms internally; access \`process.env\` directly
+     * only when you need the raw string. Unknown keys still resolve to
+     * \`string | undefined\` via the base @types/node declaration.
+     */
+    interface ProcessEnv extends Record<keyof KickEnv, string> {}
+  }
+}
+
+export {}
+`;
+}
+/**
+* Render the `KickRoutes` global namespace augmentation. Each interface
+* inside corresponds to a controller class; each property is a single
+* route method on that controller, conforming to `RouteShape`.
+*
+* Fills `params` from URL patterns, `query` from `@ApiQueryParams`, and
+* `body`/`query`/`params` (when schema-validated) from the configured
+* schema validator. `response` is emitted as `unknown`.
+*/
+function renderRoutes(routes, routesOutFile, schemaValidator) {
+	if (routes.length === 0) return `${HEADER}
+// (no routes discovered yet — annotate a controller method with
+//  @Get/@Post/@Put/@Delete/@Patch and re-run \`kick typegen\`)
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace KickRoutes {}
+}
+
+export {}
+`;
+	const byController = /* @__PURE__ */ new Map();
+	for (const r of routes) {
+		const arr = byController.get(r.controller) ?? [];
+		arr.push(r);
+		byController.set(r.controller, arr);
+	}
+	const schemaImports = /* @__PURE__ */ new Map();
+	const renderField = (schema, routeFilePath) => {
+		const alias = planSchemaImport(schema, routeFilePath, routesOutFile, schemaValidator, schemaImports);
+		return alias ? `import('zod').infer<typeof ${alias}>` : null;
+	};
+	const interfaces = [];
+	for (const [controller, methods] of byController) {
+		const lines = [`    interface ${controller} {`];
+		for (const m of methods) {
+			const urlParamsType = m.pathParams.length > 0 ? `{ ${m.pathParams.map((p) => `${p}: string`).join("; ")} }` : "{}";
+			const bodySchemaType = renderField(m.bodySchema, m.filePath);
+			const querySchemaType = renderField(m.querySchema, m.filePath);
+			const paramsType = renderField(m.paramsSchema, m.filePath) ?? urlParamsType;
+			const bodyType = bodySchemaType ?? "unknown";
+			const queryType = querySchemaType ?? renderQueryShape(m);
+			const docLines = renderQueryDocLines(m);
+			lines.push(`      /**`, `       * ${m.httpMethod} ${m.path}`, ...docLines.map((d) => `       * ${d}`), `       */`, `      ${m.method}: {`, `        params: ${paramsType}`, `        body: ${bodyType}`, `        query: ${queryType}`, `        response: unknown`, `      }`);
+		}
+		lines.push("    }");
+		interfaces.push(lines.join("\n"));
+	}
+	return `${HEADER}${renderSchemaImports(schemaImports)}
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace KickRoutes {
+${interfaces.join("\n")}
+  }
+}
+
+export {}
+`;
+}
+/** Write all generated `.d.ts` files to `outDir` */
+async function generateTypes(opts) {
+	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, outDir, allowDuplicates = false, schemaValidator = false } = opts;
+	if (collisions.length > 0 && !allowDuplicates) throw new TokenCollisionError(collisions);
+	await mkdir(outDir, { recursive: true });
+	const registryFile = join(outDir, "registry.d.ts");
+	const servicesFile = join(outDir, "services.d.ts");
+	const modulesFile = join(outDir, "modules.d.ts");
+	const routesFile = join(outDir, "routes.ts");
+	const envFile = join(outDir, "env.ts");
+	const indexFile = join(outDir, "index.d.ts");
+	const collidingNames = new Set(collisions.map((c) => c.className));
+	const registryContent = renderRegistry(classes, registryFile, collidingNames);
+	const classTokens = classes.filter((c) => REGISTRY_DECORATORS.has(c.decorator)).map((c) => collidingNames.has(c.className) ? namespacedKeyFor(c) : c.className);
+	const tokenLiterals = tokens.map((t) => t.name);
+	const injectLiterals = injects.map((i) => i.name);
+	const allServices = [
+		...classTokens,
+		...tokenLiterals,
+		...injectLiterals
+	];
+	const modules = classes.filter((c) => c.decorator === "Module").map((c) => c.className);
+	const servicesContent = renderUnion("ServiceToken", allServices, "(no tokens discovered — declare with createToken<T>() or `kick g service <name>`)");
+	const modulesContent = renderUnion("ModuleToken", modules, "(no @Module classes discovered — `kick g module <name>` to add one)");
+	const routesContent = renderRoutes(routes, routesFile, schemaValidator);
+	const envContent = renderEnv(env, envFile);
+	const indexContent = renderIndex(envContent !== null);
+	await writeFile(registryFile, registryContent, "utf-8");
+	await writeFile(servicesFile, servicesContent, "utf-8");
+	await writeFile(modulesFile, modulesContent, "utf-8");
+	await writeFile(routesFile, routesContent, "utf-8");
+	await writeFile(indexFile, indexContent, "utf-8");
+	const written = [
+		registryFile,
+		servicesFile,
+		modulesFile,
+		routesFile,
+		indexFile
+	];
+	if (envContent) {
+		await writeFile(envFile, envContent, "utf-8");
+		written.push(envFile);
+	}
+	await writeFile(join(dirname(outDir), ".gitignore"), "# Auto-generated by kick typegen\n*\n", "utf-8");
+	return {
+		registryEntries: classTokens.length,
+		serviceTokens: new Set(allServices).size,
+		moduleTokens: modules.length,
+		routeEntries: routes.length,
+		envWritten: envContent !== null,
+		written,
+		resolvedCollisions: collisions.length
+	};
+}
+//#endregion
+//#region src/typegen/index.ts
+/**
+* Public entry point for the KickJS typegen module.
+*
+* Used by:
+* - `kick typegen` (one-shot or watch mode)
+* - `kick dev` (auto-runs once before Vite starts; refreshes when files change)
+*
+* @module @forinda/kickjs-cli/typegen
+*/
+var typegen_exports = /* @__PURE__ */ __exportAll({
+	runTypegen: () => runTypegen,
+	watchTypegen: () => watchTypegen
+});
+/** Resolve options to absolute paths */
+function resolveOptions(opts) {
+	const cwd = opts.cwd ?? process.cwd();
+	return {
+		cwd,
+		srcDir: resolve(cwd, opts.srcDir ?? "src"),
+		outDir: resolve(cwd, opts.outDir ?? ".kickjs/types"),
+		silent: opts.silent ?? false,
+		allowDuplicates: opts.allowDuplicates ?? false,
+		schemaValidator: opts.schemaValidator ?? false,
+		envFile: opts.envFile ?? "src/env.ts"
+	};
+}
+/**
+* Run a single typegen pass: scan source files, generate `.d.ts` files.
+*
+* Returns the discovered scan result alongside the generation result so
+* callers (`kick dev`, devtools) can log them or feed them to other tools.
+*
+* Throws `TokenCollisionError` if duplicate class names are found and
+* `allowDuplicates` is false.
+*/
+async function runTypegen(opts = {}) {
+	const { cwd, srcDir, outDir, silent, allowDuplicates, schemaValidator, envFile } = resolveOptions(opts);
+	const start = Date.now();
+	const scan = await scanProject({
+		root: srcDir,
+		cwd,
+		envFile: envFile === false ? void 0 : envFile
+	});
+	const result = await generateTypes({
+		classes: scan.classes,
+		routes: scan.routes,
+		tokens: scan.tokens,
+		injects: scan.injects,
+		collisions: scan.collisions,
+		env: envFile === false ? null : scan.env,
+		outDir,
+		allowDuplicates,
+		schemaValidator
+	});
+	const elapsed = Date.now() - start;
+	if (!silent) {
+		const where = outDir.replace(cwd + "/", "");
+		const collisionNote = result.resolvedCollisions > 0 ? `, ${result.resolvedCollisions} collisions namespaced` : "";
+		const envNote = result.envWritten ? ", env typed" : "";
+		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+	}
+	return {
+		scan,
+		result
+	};
+}
+/**
+* Watch mode for `kick typegen --watch`.
+*
+* Uses Node's built-in `fs.watch` (recursive, available on Linux 22+ and
+* macOS 19+). Falls back gracefully if recursive watch is not supported.
+*
+* Debounces re-runs by 100ms so a bulk file change (e.g. `kick g module`
+* creating 5 files at once) emits one regen, not five.
+*
+* In watch mode collisions are reported but never thrown — the watcher
+* keeps running so the user can fix the rename and the next scan
+* recovers automatically.
+*
+* Returns a `stop()` function that closes the watcher.
+*/
+async function watchTypegen(opts = {}) {
+	const resolved = resolveOptions(opts);
+	const { srcDir, silent } = resolved;
+	const runOpts = {
+		...resolved,
+		allowDuplicates: true
+	};
+	await safeRun(runOpts, silent);
+	const { watch } = await import("node:fs");
+	let timer = null;
+	const trigger = (filename) => {
+		if (!filename) return;
+		if (!/\.(ts|tsx|mts|cts)$/.test(filename)) return;
+		if (filename.includes(".kickjs")) return;
+		if (filename.endsWith(".d.ts")) return;
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			safeRun(runOpts, silent);
+		}, 100);
+	};
+	let watcher;
+	try {
+		watcher = watch(srcDir, { recursive: true }, (_event, filename) => {
+			trigger(filename);
+		});
+	} catch (err) {
+		if (!silent) console.warn(`  kick typegen: watch mode unavailable (${err?.message ?? err}). Falling back to polling.`);
+		const interval = setInterval(() => {
+			safeRun({
+				...runOpts,
+				silent: true
+			}, true);
+		}, 2e3);
+		return () => clearInterval(interval);
+	}
+	return () => {
+		if (timer) clearTimeout(timer);
+		watcher.close();
+	};
+}
+/** Run typegen swallowing errors so the watcher loop never dies */
+async function safeRun(opts, silent) {
+	try {
+		await runTypegen(opts);
+	} catch (err) {
+		if (silent) return;
+		if (err instanceof TokenCollisionError) console.error("\n" + err.message + "\n");
+		else {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(`  kick typegen failed: ${msg}`);
+		}
+	}
+}
+//#endregion
 //#region src/commands/generate.ts
 /** Check if --dry-run was passed on the parent generate command */
 function isDryRun(cmd) {
@@ -4412,6 +5488,29 @@ function printGenerated(files, dryRun = false) {
 	if (dryRun) console.log("\n  (dry run — no files were written)");
 	console.log();
 }
+/**
+* Refresh `.kickjs/types/*` after a generator that emitted controllers,
+* so the new `Ctx<KickRoutes.X['method']>` references resolve in the
+* user's editor without waiting for `kick dev`.
+*
+* Loads `kick.config.ts` for `typegen.schemaValidator`. Failures are
+* non-fatal — typegen problems should never block code generation.
+*/
+async function runPostTypegen(dryRun) {
+	if (dryRun) return;
+	try {
+		const cfg = await loadKickConfig(process.cwd());
+		await runTypegen({
+			cwd: process.cwd(),
+			allowDuplicates: true,
+			silent: true,
+			schemaValidator: cfg?.typegen?.schemaValidator ?? "zod",
+			envFile: cfg?.typegen?.envFile,
+			srcDir: cfg?.typegen?.srcDir,
+			outDir: cfg?.typegen?.outDir
+		});
+	} catch {}
+}
 const GENERATORS = [
 	{
 		name: "module <name>",
@@ -4500,6 +5599,7 @@ function registerGenerateCommand(program) {
 			allFiles.push(...files);
 		}
 		printGenerated(allFiles, dryRun);
+		await runPostTypegen(dryRun);
 	});
 	gen.command("adapter <name>").description("Generate an AppAdapter with lifecycle hooks and middleware support").option("-o, --out <dir>", "Output directory", "src/adapters").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
@@ -4560,6 +5660,7 @@ function registerGenerateCommand(program) {
 			modulesDir,
 			pattern: config?.pattern
 		}), dryRun);
+		await runPostTypegen(dryRun);
 	});
 	gen.command("dto <name>").description("Generate a Zod DTO schema\n  Use -m to scope it to a module: kick g dto create-user -m users").option("-o, --out <dir>", "Output directory (overrides --module)").option("-m, --module <module>", "Place inside a module folder").action(async (name, opts, cmd) => {
 		const dryRun = isDryRun(cmd);
@@ -4623,6 +5724,7 @@ function registerGenerateCommand(program) {
 		console.log(`\n  Scaffolded ${name} with ${fields.length} field(s):`);
 		for (const f of fields) console.log(`    ${f.name}: ${f.type}${f.optional ? " (optional)" : ""}`);
 		printGenerated(files, dryRun);
+		await runPostTypegen(dryRun);
 	});
 	gen.command("config").description("Generate a kick.config.ts at the project root").option("--modules-dir <dir>", "Modules directory path", "src/modules").option("--repo <type>", "Default repository type: inmemory | drizzle | prisma", "inmemory").option("-f, --force", "Overwrite existing kick.config.ts without prompting").action(async (opts, cmd) => {
 		const dryRun = isDryRun(cmd);
@@ -4661,16 +5763,54 @@ function runShellCommand(command, cwd) {
 */
 async function startDevServer(_entry, port) {
 	if (port) process.env.PORT = port;
+	const cwd = process.cwd();
+	const devConfig = await loadKickConfig(cwd);
+	const schemaValidator = devConfig?.typegen?.schemaValidator ?? "zod";
+	const envFile = devConfig?.typegen?.envFile;
+	try {
+		await runTypegen({
+			cwd,
+			allowDuplicates: true,
+			schemaValidator,
+			envFile,
+			srcDir: devConfig?.typegen?.srcDir,
+			outDir: devConfig?.typegen?.outDir
+		});
+	} catch (err) {
+		console.warn(`  kick typegen: skipped (${err?.message ?? err})`);
+	}
 	const { createRequire } = await import("node:module");
 	const { createServer } = await import(createRequire(resolve("package.json")).resolve("vite"));
 	const server = await createServer({
 		configFile: resolve("vite.config.ts"),
 		server: { port: port ? parseInt(port, 10) : void 0 }
 	});
+	let typegenTimer = null;
+	const scheduleTypegen = (file) => {
+		if (!/\.(ts|tsx|mts|cts)$/.test(file)) return;
+		if (file.includes(".kickjs")) return;
+		if (file.endsWith(".d.ts")) return;
+		if (typegenTimer) clearTimeout(typegenTimer);
+		typegenTimer = setTimeout(() => {
+			runTypegen({
+				cwd,
+				silent: true,
+				allowDuplicates: true,
+				schemaValidator,
+				envFile,
+				srcDir: devConfig?.typegen?.srcDir,
+				outDir: devConfig?.typegen?.outDir
+			}).catch(() => {});
+		}, 100);
+	};
+	server.watcher.on("add", scheduleTypegen);
+	server.watcher.on("unlink", scheduleTypegen);
+	server.watcher.on("change", scheduleTypegen);
 	await server.listen();
 	server.printUrls();
 	console.log(`\n  KickJS dev server running (Vite + @forinda/kickjs-vite)\n`);
 	const shutdown = async () => {
+		if (typegenTimer) clearTimeout(typegenTimer);
 		await server.close();
 		process.exit(0);
 	};
@@ -5323,6 +6463,64 @@ function registerRemoveCommand(program) {
 	});
 }
 //#endregion
+//#region src/commands/typegen.ts
+/**
+* Parse the `--schema-validator` CLI flag. Returns `undefined` if the
+* flag was not passed (so the config default applies), `'zod'` if a
+* supported value was passed, or `false` if explicitly disabled.
+*/
+function parseSchemaValidatorFlag(value) {
+	if (value === void 0) return void 0;
+	if (value === "false" || value === "off" || value === "none") return false;
+	if (value === "zod") return "zod";
+	console.warn(`  kick typegen: unknown --schema-validator '${value}' (only 'zod' and 'false' are supported). Falling back to project config.`);
+}
+/**
+* Parse the `--env-file` CLI flag. Returns `undefined` to fall through
+* to the config default, `false` when the user disables env typing
+* with `--env-file false`, or the literal path string otherwise.
+*/
+function parseEnvFileFlag(value) {
+	if (value === void 0) return void 0;
+	if (value === "false" || value === "off" || value === "none") return false;
+	return value;
+}
+function registerTypegenCommand(program) {
+	program.command("typegen").description("Generate type-safe DI registry and module types into .kickjs/types/").option("-w, --watch", "Watch source files and regenerate on change").option("-s, --src <dir>", "Source directory to scan", "src").option("-o, --out <dir>", "Output directory", ".kickjs/types").option("--silent", "Suppress output").option("--allow-duplicates", "Auto-namespace duplicate class names instead of failing (use with caution)").option("--schema-validator <name>", "Schema validator for body/query/params typing (currently 'zod' or 'false')").option("--env-file <path>", "Path to env schema file for KickEnv typing (default 'src/env.ts'; pass 'false' to disable)").action(async (opts) => {
+		const cwd = process.cwd();
+		const config = await loadKickConfig(cwd);
+		const schemaValidator = parseSchemaValidatorFlag(opts.schemaValidator) ?? config?.typegen?.schemaValidator ?? "zod";
+		const envFile = parseEnvFileFlag(opts.envFile) ?? config?.typegen?.envFile;
+		const baseOpts = {
+			cwd,
+			srcDir: opts.src ?? config?.typegen?.srcDir,
+			outDir: opts.out ?? config?.typegen?.outDir,
+			silent: opts.silent,
+			allowDuplicates: opts.allowDuplicates,
+			schemaValidator,
+			envFile
+		};
+		try {
+			if (opts.watch) {
+				const stop = await watchTypegen(baseOpts);
+				if (!opts.silent) console.log("  kick typegen: watching for changes (Ctrl-C to exit)");
+				const shutdown = () => {
+					stop();
+					process.exit(0);
+				};
+				process.on("SIGINT", shutdown);
+				process.on("SIGTERM", shutdown);
+				await new Promise(() => {});
+			} else await runTypegen(baseOpts);
+		} catch (err) {
+			if (err instanceof TokenCollisionError) console.error("\n" + err.message + "\n");
+			else if (err instanceof Error) console.error(`\n  kick typegen failed: ${err.message}`);
+			else console.error(`\n  kick typegen failed: ${JSON.stringify(err)}`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
 //#region src/cli.ts
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -5339,6 +6537,7 @@ async function main() {
 	registerListCommand(program);
 	registerTinkerCommand(program);
 	registerRemoveCommand(program);
+	registerTypegenCommand(program);
 	registerCustomCommands(program, config);
 	program.showHelpAfterError();
 	await program.parseAsync(process.argv);