@forinda/kickjs-cli 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -28,6 +28,50 @@ interface CustomRepoType {
 }
 /** Repository type — built-in string or custom object */
 type RepoTypeConfig = BuiltinRepoType$1 | CustomRepoType;
+/**
+ * Supported schema validators for `kick typegen` body/query/params
+ * type extraction. Only `'zod'` ships built-in for now; other libraries
+ * (Joi, Yup, JSON Schema) will be added later as the adapter system
+ * grows. Set to `false` (or omit) to disable schema-driven body typing
+ * entirely (the route entries will keep `body: unknown`).
+ */
+type SchemaValidator = 'zod' | false;
+/** Typegen settings — controls .kickjs/types/* generation */
+interface TypegenConfig {
+  /**
+   * Source directory to scan for controllers and decorators.
+   * Defaults to `'src'`.
+   */
+  srcDir?: string;
+  /**
+   * Output directory for generated `.d.ts` files.
+   * Defaults to `'.kickjs/types'`.
+   */
+  outDir?: string;
+  /**
+   * Schema validator used to derive `body` types from route metadata.
+   *
+   * - `'zod'` — emit `z.infer<typeof <importedSchema>>` for any schema
+   *   referenced as a named identifier in `@Get/@Post/...({ body, query, params })`.
+   * - `false` — disable schema-driven body typing.
+   *
+   * Future: `'joi' | 'yup' | 'json-schema'` plus a `{ name; module }`
+   * escape hatch for custom adapters.
+   *
+   * @default 'zod'
+   */
+  schemaValidator?: SchemaValidator;
+  /**
+   * Path to the project's env schema file (relative to project root).
+   * Must default-export a `defineEnv(...)` schema for typegen to emit
+   * the typed `KickEnv` global registry.
+   *
+   * Set to `false` to disable env typing entirely.
+   *
+   * @default 'src/env.ts'
+   */
+  envFile?: string | false;
+}
 /** Module generation settings — controls how `kick g module` produces code */
 interface ModuleConfig {
   /** Where modules live (default: 'src/modules') */
@@ -113,6 +157,18 @@ interface KickConfig {
     src: string;
     dest?: string;
   }>;
+  /**
+   * Typegen settings — controls `.kickjs/types/*` generation including
+   * the schema validator used for body type extraction.
+   *
+   * @example
+   * ```ts
+   * typegen: {
+   *   schemaValidator: 'zod',
+   * }
+   * ```
+   */
+  typegen?: TypegenConfig;
   /** Custom commands that extend the CLI */
   commands?: KickCommandDefinition[];
   /** Code style overrides (auto-detected from prettier when possible) */

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/utils/naming.ts"],"mappings":";;;UAIiB,qBAAA;EAAqB;EAEpC,IAAA;EAFoC;EAIpC,WAAA;EAAA;;;;;AAeF;;;EANE,KAAA;EAMwB;EAJxB,OAAA;AAAA;;KAIU,cAAA;;KAGA,iBAAA;;UAKK,cAAA;EACf,IAAA;AAAA;;KAIU,cAAA,GAAiB,iBAAA,GAAkB,cAAA;;UAG9B,YAAA;EAAA;EAEf,GAAA;;;;;;;;;;;AAoCF;;;EAtBE,IAAA,GAAO,cAAA;EA2CG;EAzCV,SAAA;EAiEW;;;;;EA3DX,SAAA;EAmCA;;;;;;;;;EAzBA,gBAAA;AAAA;;UAIe,UAAA;EAiDf;;;;;;;AASF;EAjDE,OAAA,GAAU,cAAA;;;;;;;;AA8EZ;;;;EAlEE,OAAA,GAAU,YAAA;EAkEuC;EA9DjD,UAAA;EA8DmE;EA5DnE,WAAA,GAAc,cAAA;;EAEd,SAAA;;EAEA,SAAA;EC9FyB;;;;AAC3B;;;;;AAOC;;;;EDoGC,QAAA,GAAW,KAAA;IAAiB,GAAA;IAAa,IAAA;EAAA;EC7FzC;ED+FA,QAAA,GAAW,qBAAA;EC9FX;EDgGA,KAAA;IACE,UAAA;IACA,MAAA;IACA,aAAA;IACA,MAAA;EAAA;AAAA;;iBAKY,YAAA,CAAa,MAAA,EAAQ,UAAA,GAAa,UAAA;;iBA6B5B,cAAA,CAAe,GAAA,WAAc,OAAA,CAAQ,UAAA;;;KCtJ/C,eAAA;AAAA,KACA,QAAA,GAAW,eAAA;AAAA,UASb,qBAAA;EACR,IAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;EACA,IAAA,GAAO,QAAA;EACP,OAAA;EACA,KAAA;EACA,OAAA,GAAU,cAAA;EACV,MAAA;EDVwB;ECYxB,SAAA;EDTyB;ECWzB,gBAAA;AAAA;;ADNF;;;;;AAKA;;;;iBCyBsB,cAAA,CAAe,OAAA,EAAS,qBAAA,GAAwB,OAAA;;;UCzD5D,sBAAA;EACR,IAAA;EACA,MAAA;AAAA;AAAA,iBAGoB,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCH9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,oBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,OAAA;;;UCR1D,sBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCR9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,kBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;KCiB3D,eAAA;AAAA,UAEK,kBAAA;EACR,IAAA;EACA,SAAA;EACA,cAAA;EACA,OAAA;EACA,WAAA;EACA,QAAA,GAAW,eAAA;EACX,WAAA;AAAA;;iBAIoB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;;iBC3ChD,YAAA,CAAa,IAAA;;iBAOb,WAAA,CAAY,IAAA;;iBAMZ,WAAA,CAAY,IAAA;;;;;iBAWZ,SAAA,CAAU,IAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/generators/module.ts","../src/generators/adapter.ts","../src/generators/middleware.ts","../src/generators/guard.ts","../src/generators/service.ts","../src/generators/controller.ts","../src/generators/dto.ts","../src/generators/project.ts","../src/utils/naming.ts"],"mappings":";;;UAIiB,qBAAA;EAAqB;EAEpC,IAAA;EAFoC;EAIpC,WAAA;EAAA;;;;;AAeF;;;EANE,KAAA;EAMwB;EAJxB,OAAA;AAAA;;KAIU,cAAA;;KAGA,iBAAA;;UAKK,cAAA;EACf,IAAA;AAAA;;KAIU,cAAA,GAAiB,iBAAA,GAAkB,cAAA;;;AAS/C;;;;;KAAY,eAAA;;UAGK,aAAA;EAuBkB;;;;EAlBjC,MAAA;EA4BA;;;AAIF;EA3BE,MAAA;;;;;;;;;;;AAiEF;;EApDE,eAAA,GAAkB,eAAA;EA6DR;;;;;;;;;EAnDV,OAAA;AAAA;;UAIe,YAAA;EAiEf;EA/DA,GAAA;EAiEA;;;;;;;;;;;;;EAnDA,IAAA,GAAO,cAAA;EAuFL;EArFF,SAAA;EAqFQ;AAKV;;;;EApFE,SAAA;EAoF2B;;;;AA6B7B;;;;;EAvGE,gBAAA;AAAA;;UAIe,UAAA;;;;AC7GjB;;;;;EDsHE,OAAA,GAAU,cAAA;ECrHQ;;;;AAOnB;;;;;;;ED0HC,OAAA,GAAU,YAAA;ECnHV;EDuHA,UAAA;ECtHA;EDwHA,WAAA,GAAc,cAAA;ECtHd;EDwHA,SAAA;ECvHA;EDyHA,SAAA;ECrHA;;;AAwBF;;;;;;;;;;ED2GE,QAAA,GAAW,KAAA;IAAiB,GAAA;IAAa,IAAA;EAAA;;;;AE/J3C;;;;;;;;EF2KE,OAAA,GAAU,aAAA;;EAEV,QAAA,GAAW,qBAAA;;EAEX,KAAA;IACE,UAAA;IACA,MAAA;IACA,aAAA;IACA,MAAA;EAAA;AAAA;;iBAKY,YAAA,CAAa,MAAA,EAAQ,UAAA,GAAa,UAAA;;iBA6B5B,cAAA,CAAe,GAAA,WAAc,OAAA,CAAQ,UAAA;;;KChN/C,eAAA;AAAA,KACA,QAAA,GAAW,eAAA;AAAA,UASb,qBAAA;EACR,IAAA;EACA,UAAA;EACA,QAAA;EACA,OAAA;EACA,IAAA,GAAO,QAAA;EACP,OAAA;EACA,KAAA;EACA,OAAA,GAAU,cAAA;EACV,MAAA;EDVwB;ECYxB,SAAA;EDTyB;ECWzB,gBAAA;AAAA;;ADNF;;;;;AAKA;;;;iBCyBsB,cAAA,CAAe,OAAA,EAAS,qBAAA,GAAwB,OAAA;;;UCzD5D,sBAAA;EACR,IAAA;EACA,MAAA;AAAA;AAAA,iBAGoB,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCH9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,oBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,OAAA;;;UCR1D,sBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,eAAA,CAAgB,OAAA,EAAS,sBAAA,GAAyB,OAAA;;;UCR9D,yBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,kBAAA,CAAmB,OAAA,EAAS,yBAAA,GAA4B,OAAA;;;UCRpE,kBAAA;EACR,IAAA;EACA,MAAA;EACA,UAAA;EACA,UAAA;EACA,OAAA,GAAU,cAAA;AAAA;AAAA,iBAGU,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;KCkB3D,eAAA;AAAA,UAEK,kBAAA;EACR,IAAA;EACA,SAAA;EACA,cAAA;EACA,OAAA;EACA,WAAA;EACA,QAAA,GAAW,eAAA;EACX,WAAA;AAAA;;iBAIoB,WAAA,CAAY,OAAA,EAAS,kBAAA,GAAqB,OAAA;;;;iBC5ChD,YAAA,CAAa,IAAA;;iBAOb,WAAA,CAAY,IAAA;;iBAMZ,WAAA,CAAY,IAAA;;;;;iBAWZ,SAAA,CAAU,IAAA"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v2.1.0
+ * @forinda/kickjs-cli v2.2.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -219,8 +219,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'
@@ -231,18 +230,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,
@@ -251,7 +255,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)
@@ -259,21 +263,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()
   }
@@ -282,24 +286,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,
@@ -308,7 +316,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)
@@ -316,21 +324,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()
   }
@@ -511,6 +519,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'
@@ -525,7 +534,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) {
@@ -1053,8 +1068,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'
@@ -1065,18 +1079,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,
@@ -1085,7 +1104,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)
@@ -1093,21 +1112,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()
   }
@@ -1606,6 +1625,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'
@@ -1624,20 +1678,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())
   }
 }
@@ -1649,6 +1708,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',
@@ -1675,6 +1741,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',
@@ -1710,13 +1783,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' })
   }
 }
@@ -2442,20 +2517,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 })
   }
 }
@@ -2563,7 +2642,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'
 
@@ -2613,10 +2692,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 */
@@ -2654,6 +2736,7 @@ dist/
 coverage/
 .DS_Store
 *.tsbuildinfo
+.kickjs/
 `;
 }
 /** Generate .gitattributes for consistent line endings */
@@ -2841,20 +2924,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 })
   }
@@ -2897,7 +2982,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)
@@ -3404,6 +3490,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());
@@ -3448,6 +3535,14 @@ async function initProject(options) {
 			console.log(`\n  Warning: ${packageManager} install failed. Run it manually.`);
 		}
 	}
+	try {
+		const { runTypegen } = await import("./typegen-DCnJdqP1.mjs");
+		await runTypegen({
+			cwd: dir,
+			allowDuplicates: true,
+			silent: true
+		});
+	} catch {}
 	console.log("\n  Project scaffolded successfully!");
 	console.log();
 	const needsCd = dir !== process.cwd();