@forinda/kickjs-cli 8.10.2 → 8.12.0

package/dist/{doctor-DGWvBOvj.mjs → doctor-rEbeoAoO.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v8.10.2
+ * @forinda/kickjs-cli v8.12.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,7 +8,7 @@
  *
  * @license MIT
  */
-import{i as e,o as t,t as n}from"./package-manager-DBmD5nSr.mjs";import{a as r,n as i,r as a,t as o,u as s}from"./prompts-D4nwf5mP.mjs";import{s as c}from"./config-CsOfUFfq.mjs";import{c as l,i as u}from"./project-C98JovY4.mjs";import{t as d}from"./project-root-DlgCWwc_.mjs";import{createRequire as f}from"node:module";import p,{dirname as m,join as h,relative as g,resolve as _}from"node:path";import{existsSync as v,readFileSync as y,readdirSync as b,statSync as x}from"node:fs";import{readFile as S,writeFile as C}from"node:fs/promises";import w from"pluralize";import{pathToFileURL as ee}from"node:url";import{defineGenerator as te}from"@forinda/kickjs-cli-kit";function T(e){return e.replace(/[-_\s]+(.)?/g,(e,t)=>t?t.toUpperCase():``).replace(/^(.)/,e=>e.toUpperCase())}function E(e){let t=T(e);return t.charAt(0).toLowerCase()+t.slice(1)}function D(e){return e.replace(/([a-z])([A-Z])/g,`$1-$2`).replace(/[\s_]+/g,`-`).toLowerCase()}function O(e){return w.plural(e)}function k(e){return w.plural(e)}function A(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}const ne={inmemory:`in-memory`,drizzle:`Drizzle`,prisma:`Prisma`};function re(e){return e.charAt(0).toUpperCase()+e.slice(1).replace(/-([a-z])/g,(e,t)=>t.toUpperCase())}function ie(e){return ne[e]??re(e)}function ae(e){return`create${e}Repository`}function j(e){return e??`define`}function M(e){let{pascal:t,kebab:n,plural:r=``,repo:i,style:a}=e,o=ae(t),s=j(a),c=`/**
+import{i as e,o as t,t as n}from"./package-manager-DvXi-NGm.mjs";import{a as r,n as i,r as a,t as o,u as s}from"./prompts-DJBDNwHt.mjs";import{s as c}from"./config-DbnBakh8.mjs";import{c as l,i as u}from"./project-BN1DnrN3.mjs";import{t as d}from"./project-root-FMt83NHV.mjs";import{createRequire as f}from"node:module";import p,{dirname as m,join as h,relative as g,resolve as _}from"node:path";import{existsSync as v,readFileSync as y,readdirSync as b,statSync as x}from"node:fs";import{readFile as S}from"node:fs/promises";import C from"pluralize";import{pathToFileURL as w}from"node:url";import{defineGenerator as ee}from"@forinda/kickjs-cli-kit";C.addUncountableRule(`auth`);function T(e){return e.replace(/[-_\s]+(.)?/g,(e,t)=>t?t.toUpperCase():``).replace(/^(.)/,e=>e.toUpperCase())}function E(e){let t=T(e);return t.charAt(0).toLowerCase()+t.slice(1)}function D(e){return e.replace(/([a-z])([A-Z])/g,`$1-$2`).replace(/[\s_]+/g,`-`).toLowerCase()}function O(e){return C.plural(e)}function k(e){return C.plural(e)}function A(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}const te={inmemory:`in-memory`,drizzle:`Drizzle`,prisma:`Prisma`};function ne(e){return e.charAt(0).toUpperCase()+e.slice(1).replace(/-([a-z])/g,(e,t)=>t.toUpperCase())}function re(e){return te[e]??ne(e)}function ie(e){return`create${e}Repository`}function j(e){return e??`define`}function M(e){let{pascal:t,kebab:n,plural:r=``,repo:i,style:a}=e,o=e.routePath??r,s=ie(t),c=j(a),l=`/**
  * ${t} Module
  *
  * REST module with a flat folder structure.
@@ -21,10 +21,10 @@ import{i as e,o as t,t as n}from"./package-manager-DBmD5nSr.mjs";import{a as r,n
  *   dtos/                   — Request/response schemas
  *
  * The repository is backed by an in-memory Map so this module works as
- * generated. Swap in ${i===`inmemory`?`a database`:ie(i)} by replacing the factory body in
+ * generated. Swap in ${i===`inmemory`?`a database`:re(i)} by replacing the factory body in
  * ${n}.repository.ts — the contract is whatever that factory returns, so
  * nothing else has to change.
- */`,l=`import { ${t.toUpperCase()}_REPOSITORY, ${o} } from './${n}.repository'
+ */`,u=`import { ${t.toUpperCase()}_REPOSITORY, ${s} } from './${n}.repository'
 import { ${t}Controller } from './${n}.controller'
 
 // Eagerly load every module file so decorators (@Controller / @Service /
@@ -33,7 +33,7 @@ import { ${t}Controller } from './${n}.controller'
 // to emit, so a hand-written \`*.usecase.ts\` or \`*.policy.ts\` silently never
 // registered and failed later as \`No provider for X\` (#609). Recursive (./**/)
 // so nesting keeps working.
-import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./**/*.d.ts'], { eager: true })`,u=`    /**
+import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./**/*.d.ts'], { eager: true })`,d=`    /**
      * Declare HTTP routes for this module. Return value shape:
      *
      *   - \`path\`        — URL prefix for this route set.
@@ -44,49 +44,49 @@ import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./**/*.d.ts'], { eager: true
      * surfaces, side-by-side v1 + v2 controllers, etc:
      *
      *   return [
-     *     { path: '/${r}', version: 1, controller: ${t}V1Controller },
-     *     { path: '/${r}', version: 2, controller: ${t}V2Controller },
+     *     { path: '/${o}', version: 1, controller: ${t}V1Controller },
+     *     { path: '/${o}', version: 2, controller: ${t}V2Controller },
      *   ]
-     */`;return s===`class`?`${c}
+     */`;return c===`class`?`${l}
 import { Container, type AppModule, type ModuleRoutes } from '@forinda/kickjs'
-${l}
+${u}
 
 export class ${t}Module implements AppModule {
   register(container: Container): void {
-    container.registerFactory(${t.toUpperCase()}_REPOSITORY, () => ${o}())
+    container.registerFactory(${t.toUpperCase()}_REPOSITORY, () => ${s}())
   }
 
-${u.replace(/^ {4}/gm,`  `).replace(/^ {6}/gm,`    `)}
+${d.replace(/^ {4}/gm,`  `).replace(/^ {6}/gm,`    `)}
   routes(): ModuleRoutes {
     return {
-      path: '/${r}',
+      path: '/${o}',
       controller: ${t}Controller,
     }
   }
 }
-`:`${c}
+`:`${l}
 import { defineModule } from '@forinda/kickjs'
-${l}
+${u}
 
 export const ${t}Module = defineModule({
   name: '${t}Module',
   build: () => ({
     register(container) {
       container.registerFactory(${t.toUpperCase()}_REPOSITORY, () =>
-        ${o}(),
+        ${s}(),
       )
     },
 
-${u}
+${d}
     routes() {
       return {
-        path: '/${r}',
+        path: '/${o}',
         controller: ${t}Controller,
       }
     },
   }),
 })
-`}function oe(e){let{pascal:t,kebab:n,plural:r=``,style:i}=e,a=j(i),o=`    /**
+`}function ae(e){let{pascal:t,kebab:n,plural:r=``,style:i}=e,a=e.routePath??r,o=j(i),s=`    /**
      * Declare HTTP routes. Return value shape:
      *
      *   - \`path\`        — URL prefix for this route set.
@@ -96,17 +96,17 @@ ${u}
      * Return an array to mount multiple route sets:
      *
      *   return [
-     *     { path: '/${r}', version: 1, controller: ${t}V1Controller },
-     *     { path: '/${r}', version: 2, controller: ${t}V2Controller },
+     *     { path: '/${a}', version: 1, controller: ${t}V1Controller },
+     *     { path: '/${a}', version: 2, controller: ${t}V2Controller },
      *   ]
-     */`;return a===`class`?`import { type AppModule, type ModuleRoutes } from '@forinda/kickjs'
+     */`;return o===`class`?`import { type AppModule, type ModuleRoutes } from '@forinda/kickjs'
 import { ${t}Controller } from './${n}.controller'
 
 export class ${t}Module implements AppModule {
-${o.replace(/^ {4}/gm,`  `).replace(/^ {6}/gm,`    `)}
+${s.replace(/^ {4}/gm,`  `).replace(/^ {6}/gm,`    `)}
   routes(): ModuleRoutes {
     return {
-      path: '/${r}',
+      path: '/${a}',
       controller: ${t}Controller,
     }
   }
@@ -117,10 +117,10 @@ import { ${t}Controller } from './${n}.controller'
 export const ${t}Module = defineModule({
   name: '${t}Module',
   build: () => ({
-${o}
+${s}
     routes() {
       return {
-        path: '/${r}',
+        path: '/${a}',
         controller: ${t}Controller,
       }
     },
@@ -131,7 +131,7 @@ ${o}
   Controller,
   Get,
   Post,
-  Put,
+  Patch,
   Delete,
   Autowired,
   ApiQueryParams,
@@ -157,10 +157,18 @@ import { ${t.toUpperCase()}_QUERY_CONFIG } from './${n}.constants'
 // \`ctx.problem.*\` for error branches — those send immediately and return
 // nothing, so they stay out of the success type.
 
+// Require a signed-in user for these routes: https://kickjs.app/guide/authentication
 @Controller()
 export class ${t}Controller {
   @Autowired() private readonly ${a}Service!: ${t}Service
 
+  // Offset pages (?page=&limit=). For keyset pages (?cursor=&limit=) — stable
+  // under concurrent inserts, no deep OFFSET scans — swap the body for:
+  //   return ctx.paginateCursor(
+  //     (q) => this.${a}Service.findAfter({ ...q, limit: q.limit + 1 }),
+  //     ${t.toUpperCase()}_QUERY_CONFIG,
+  //   )
+  // https://kickjs.app/guide/query-parsing#cursor-pagination
   @Get('/')
 ${i}  @ApiQueryParams(${t.toUpperCase()}_QUERY_CONFIG)
   async list(ctx: Ctx<KickRoutes.${t}Controller['list']>) {
@@ -184,10 +192,14 @@ ${i}  async getById(ctx: Ctx<KickRoutes.${t}Controller['getById']>) {
 
   @Post('/', { body: create${t}Schema, name: 'Create${t}' })
 ${i}  async create(ctx: Ctx<KickRoutes.${t}Controller['create']>) {
-    return reply.created(await this.${a}Service.create(ctx.body))
+    const created = await this.${a}Service.create(ctx.body)
+    // 201 + Location: where the new ${n} lives, built from the getById route.
+    return reply.created(created, {
+      location: ctx.urlFor('${t}Controller.getById', { id: created.id }),
+    })
   }
 
-  @Put('/:id', { body: update${t}Schema, name: 'Update${t}' })
+  @Patch('/:id', { body: update${t}Schema, name: 'Update${t}' })
 ${i}  async update(ctx: Ctx<KickRoutes.${t}Controller['update']>) {
     return this.${a}Service.update(ctx.params.id, ctx.body)
   }
@@ -201,7 +213,7 @@ ${i}  async remove(ctx: Ctx<KickRoutes.${t}Controller['remove']>) {
 `}const P={zod:{import:`import { z } from 'zod'`,required:`z.string().min(1, { error: 'Name is required' }).max(200)`,optional:`z.string().min(1).max(200).optional()`,infer:e=>`z.infer<typeof ${e}>`,hint:[` *   z.string(), z.number(), z.boolean(), z.enum([...]),`,` *   z.array(), z.object(), .optional(), .default(), .transform()`].join(`
 `)},valibot:{import:`import * as v from 'valibot'`,required:`v.pipe(v.string(), v.minLength(1, 'Name is required'), v.maxLength(200))`,optional:`v.optional(v.pipe(v.string(), v.minLength(1), v.maxLength(200)))`,infer:e=>`v.InferOutput<typeof ${e}>`,hint:[` *   v.string(), v.number(), v.boolean(), v.picklist([...]),`,` *   v.array(), v.object(), v.optional(), and v.pipe(...) to chain checks`].join(`
 `)},yup:{import:`import * as yup from 'yup'`,required:`yup.string().required('Name is required').min(1).max(200)`,optional:`yup.string().min(1).max(200).optional()`,infer:e=>`yup.InferType<typeof ${e}>`,hint:[` *   yup.string(), yup.number(), yup.boolean(), .oneOf([...]),`,` *   yup.array(), yup.object(), .required(), .optional(), .default()`].join(`
-`)}};function F(e,t){return`${e===`zod`?`z.object`:e===`valibot`?`v.object`:`yup.object`}({\n  ${t},\n})`}function se(e){let{pascal:t}=e,n=e.schemaLib??`zod`,r=P[n],i=`create${t}Schema`,a=n===`zod`?`Zod`:n===`valibot`?`Valibot`:`Yup`;return`${r.import}
+`)}};function F(e,t){return`${e===`zod`?`z.object`:e===`valibot`?`v.object`:`yup.object`}({\n  ${t},\n})`}function oe(e){let{pascal:t}=e,n=e.schemaLib??`zod`,r=P[n],i=`create${t}Schema`,a=n===`zod`?`Zod`:n===`valibot`?`Valibot`:`Yup`;return`${r.import}
 
 /**
  * Create ${t} DTO — ${a} schema for validating POST request bodies.
@@ -214,12 +226,12 @@ ${r.hint}
 export const ${i} = ${F(n,`name: ${r.required}`)}
 
 export type Create${t}DTO = ${r.infer(i)}
-`}function ce(e){let{pascal:t}=e,n=e.schemaLib??`zod`,r=P[n],i=`update${t}Schema`;return`${r.import}
+`}function se(e){let{pascal:t}=e,n=e.schemaLib??`zod`,r=P[n],i=`update${t}Schema`;return`${r.import}
 
 export const ${i} = ${F(n,`name: ${r.optional}`)}
 
 export type Update${t}DTO = ${r.infer(i)}
-`}function le(e){let{pascal:t}=e;return`export interface ${t}ResponseDTO {
+`}function ce(e){let{pascal:t}=e;return`export interface ${t}ResponseDTO {
   id: string
   name: string
   createdAt: string
@@ -227,6 +239,22 @@ export type Update${t}DTO = ${r.infer(i)}
 }
 `}function I(e){let{pascal:t,kebab:n,repoType:r,dtoPrefix:i=`./dtos`,tokenScope:a=`app`}=e,o=r&&r!==`inmemory`?r:``,s=`create${t}Repository`,c=`  const store = new Map<string, ${t}ResponseDTO>()
 
+  /**
+   * Filtered, searched and sorted. \`byId\` breaks sort-key ties by id — what a
+   * cursor needs; without it ties (and an unsorted list) keep insertion order.
+   */
+  function select(parsed: Omit<ParsedQuery, 'pagination'>, byId = false): ${t}ResponseDTO[] {
+    // The parser already limited fields to ${t.toUpperCase()}_QUERY_CONFIG.
+    const q = parsed.search.toLowerCase()
+    return [...store.values()]
+      .filter(
+        (row) =>
+          parsed.filters.every((f) => matches(field(row, f.field), f)) &&
+          (!q || SEARCHABLE.some((name) => String(field(row, name) ?? '').toLowerCase().includes(q))),
+      )
+      .sort((a, b) => order(a, b, parsed.sort, byId))
+  }
+
   return {
     async findById(id: string): Promise<${t}ResponseDTO | null> {
       return store.get(id) ?? null
@@ -239,9 +267,28 @@ export type Update${t}DTO = ${r.infer(i)}
     async findPaginated(
       parsed: ParsedQuery,
     ): Promise<{ data: ${t}ResponseDTO[]; total: number }> {
-      const all = [...store.values()]
+      const rows = select(parsed)
       const { offset, limit } = parsed.pagination
-      return { data: all.slice(offset, offset + limit), total: all.length }
+      return { data: rows.slice(offset, offset + limit), total: rows.length }
+    },
+
+    /**
+     * Keyset page for \`ctx.paginateCursor\`: the rows strictly after
+     * \`cursor\` in sort order (id breaks ties), at most \`limit\` of them —
+     * the caller asks for one more than it shows, to learn whether a next
+     * page exists. A database does the same with
+     * \`WHERE (sortField, id) > (cursor.sortField, cursor.id)\`.
+     */
+    async findAfter(
+      query: Omit<ParsedQuery, 'pagination'> & {
+        cursor: Readonly<Record<string, unknown>> | null
+        limit: number
+      },
+    ): Promise<${t}ResponseDTO[]> {
+      const { cursor, limit, sort } = query
+      const rows = select(query, true)
+      const after = cursor ? rows.filter((row) => order(row, cursor, sort, true) > 0) : rows
+      return after.slice(0, limit)
     },
 
     async create(dto: Create${t}DTO): Promise<${t}ResponseDTO> {
@@ -277,11 +324,71 @@ export type Update${t}DTO = ${r.infer(i)}
  */
 import { randomUUID } from 'node:crypto'
 import { createToken, HttpException } from '@forinda/kickjs'
-import type { ParsedQuery } from '@forinda/kickjs'
+import type { FilterItem, ParsedQuery, SortItem } from '@forinda/kickjs'
+import { ${t.toUpperCase()}_QUERY_CONFIG } from './${n}.constants'
 import type { ${t}ResponseDTO } from '${i}/${n}-response.dto'
 import type { Create${t}DTO } from '${i}/create-${n}.dto'
 import type { Update${t}DTO } from '${i}/update-${n}.dto'
 
+const SEARCHABLE = (${t.toUpperCase()}_QUERY_CONFIG.searchable ?? []) as string[]
+
+function field(row: object, name: string): unknown {
+  return (row as Record<string, unknown>)[name]
+}
+
+/**
+ * A stored number compares by value (the query's value is text); everything
+ * else, ISO dates included, as text — so a string field keeps '001' ≠ '1'.
+ */
+function compare(stored: unknown, other: unknown): number {
+  if (typeof stored === 'number') return stored - Number(other)
+  return String(stored ?? '').localeCompare(String(other ?? ''))
+}
+
+/**
+ * Sort order of two rows (or a row and a cursor position): each sort field in
+ * turn, then — with \`byId\` — id, in the direction of the last sort field.
+ */
+function order(a: object, b: object, sort: readonly SortItem[], byId: boolean): number {
+  for (const { field: name, direction } of sort) {
+    const result = compare(field(a, name), field(b, name))
+    if (result) return direction === 'desc' ? -result : result
+  }
+  if (!byId) return 0
+  const result = compare(field(a, 'id'), field(b, 'id'))
+  return sort.at(-1)?.direction === 'desc' ? -result : result
+}
+
+/** One \`?filter=field:op:value\` — \`in\` and \`between\` take comma-separated values. */
+function matches(value: unknown, { operator, value: raw }: FilterItem): boolean {
+  const text = String(value ?? '').toLowerCase()
+  const list = raw.split(',')
+  switch (operator) {
+    case 'eq':
+      return compare(value, raw) === 0
+    case 'neq':
+      return compare(value, raw) !== 0
+    case 'gt':
+      return compare(value, raw) > 0
+    case 'gte':
+      return compare(value, raw) >= 0
+    case 'lt':
+      return compare(value, raw) < 0
+    case 'lte':
+      return compare(value, raw) <= 0
+    case 'between':
+      return compare(value, list[0]) >= 0 && compare(value, list[1]) <= 0
+    case 'in':
+      return list.some((v) => compare(value, v) === 0)
+    case 'contains':
+      return text.includes(raw.toLowerCase())
+    case 'starts':
+      return text.startsWith(raw.toLowerCase())
+    case 'ends':
+      return text.endsWith(raw.toLowerCase())
+  }
+}
+
 export function ${s}() {
 ${c}
 }
@@ -300,7 +407,7 @@ export type ${t}Repository = ReturnType<typeof ${s}>
  * adopters must NOT use the reserved \`'kick/'\` namespace.
  */
 export const ${t.toUpperCase()}_REPOSITORY = createToken<${t}Repository>('${a}/${t}/repository')
-`}function ue(e){let{pascal:t,kebab:n,plural:r=``,style:i=`define`,testHarness:a=!1}=e,o=i===`define`?`${t}Module()`:`${t}Module`;return`${a?`import { describe, it, expect, beforeEach } from 'vitest'
+`}function le(e){let{pascal:t,kebab:n,plural:r=``,style:i=`define`,testHarness:a=!1,testImport:o=`vitest`}=e,s=e.routePath??r,c=i===`define`?`${t}Module()`:`${t}Module`;return`${a?`import { describe, it, expect, beforeEach } from '${o}'
 import request from 'supertest'
 import { Container } from '@forinda/kickjs'
 import { createTestApp } from '@forinda/kickjs-testing'
@@ -316,11 +423,11 @@ import { ${t}Module } from '../${n}.module'
  * pass the same values in \`boot()\` below and update this to match, so the test
  * exercises the paths production actually serves:
  *
- *   defaultVersion: false  →  '/api/${r}'
- *   apiPrefix: '/v1'       →  '/v1/v1/${r}'
+ *   defaultVersion: false  →  '/api/${s}'
+ *   apiPrefix: '/v1'       →  '/v1/v1/${s}'
  */
-const BASE = '/api/v1/${r}'
-`:`import { describe, it, beforeEach } from 'vitest'
+const BASE = '/api/v1/${s}'
+`:`import { describe, it, beforeEach } from '${o}'
 import { Container } from '@forinda/kickjs'
 
 // Install \`@forinda/kickjs-testing\` and \`supertest\` to boot this module in a
@@ -342,7 +449,7 @@ ${a?`  /**
    */
   async function boot() {
     const { app, container } = await createTestApp({
-      modules: [${o}],
+      modules: [${c}],
       // Mirror your bootstrap() here if it overrides either, and update BASE:
       // apiPrefix: '/api',
       // defaultVersion: 1,
@@ -350,7 +457,7 @@ ${a?`  /**
     return { app, container, agent: request(app.handle.bind(app)) }
   }
 
-  describe('GET /${r}', () => {
+  describe('GET /${s}', () => {
     it('returns an empty page before anything is created', async () => {
       const { agent } = await boot()
       const res = await agent.get(BASE)
@@ -359,8 +466,18 @@ ${a?`  /**
       expect(res.body).toMatchObject({ data: [], meta: { page: 1 } })
     })
 
+    it('filters and sorts through the query string', async () => {
+      const { agent } = await boot()
+      for (const name of ['Alpha', 'Beta', 'Gamma']) await agent.post(BASE).send({ name })
+      const res = await agent.get(\`\${BASE}?filter=name:neq:Beta&sort=name:desc\`)
+
+      expect(res.status).toBe(200)
+      expect(res.body.data.map((row: { name: string }) => row.name)).toEqual(['Gamma', 'Alpha'])
+      expect(res.body.meta.total).toBe(2)
+    })
+
     it.todo('returns created ${r}, paginated')
-  })`:`  describe('GET /${r}', () => {
+  })`:`  describe('GET /${s}', () => {
     // Boot the module with createTestApp and assert { data, meta }.
     it.todo('returns an empty page before anything is created')
     it.todo('returns created ${r}, paginated')
@@ -370,38 +487,45 @@ ${a?`  /**
   // reporter lists it as outstanding instead of counting it as a pass. Replace
   // the todo with a real test as you implement each endpoint.
 
-  describe('POST /${r}', () => {
-    // Post a valid body, assert 201 and the created ${n} in the response.
-    it.todo('creates a ${n}')
+  describe('POST /${s}', () => {
+${a?`    it('creates a ${n} and points Location at it', async () => {
+      const { agent } = await boot()
+      const res = await agent.post(BASE).send({ name: 'Test ${t}' })
+
+      expect(res.status).toBe(201)
+      expect(res.body).toMatchObject({ name: 'Test ${t}' })
+      expect(res.headers.location).toBe(\`\${BASE}/\${res.body.id}\`)
+    })`:`    // Post a valid body, assert 201, the created ${n}, and its Location header.
+    it.todo('creates a ${n}')`}
     // Post an invalid body, assert 422 and the validation detail.
     it.todo('rejects an invalid body')
   })
 
-  describe('GET /${r}/:id', () => {
+  describe('GET /${s}/:id', () => {
     // Create one, fetch it by id, assert the payload matches.
     it.todo('returns a ${n} by id')
     // Fetch an id that does not exist, assert 404.
     it.todo('returns 404 for an unknown id')
   })
 
-  describe('PUT /${r}/:id', () => {
+  describe('PATCH /${s}/:id', () => {
     // Create, update, assert the change is reflected on a subsequent read.
     it.todo('updates an existing ${n}')
   })
 
-  describe('DELETE /${r}/:id', () => {
+  describe('DELETE /${s}/:id', () => {
     // Create, delete, assert a subsequent read is 404.
     it.todo('deletes a ${n}')
   })
 })
-`}function de(e){let{pascal:t,kebab:n,plural:r=``,repoPrefix:i=`../${n}.repository`}=e,a=`create${t}Repository`;return`import { describe, it, expect, beforeEach } from 'vitest'
-import { ${a}, type ${t}Repository } from '${i}'
+`}function ue(e){let{pascal:t,kebab:n,plural:r=``,repoPrefix:i=`../${n}.repository`,testImport:a=`vitest`}=e,o=`create${t}Repository`;return`import { describe, it, expect, beforeEach } from '${a}'
+import { ${o}, type ${t}Repository } from '${i}'
 
 describe('${t} repository', () => {
   let repo: ${t}Repository
 
   beforeEach(() => {
-    repo = ${a}()
+    repo = ${o}()
   })
 
   it('should create and retrieve a ${n}', async () => {
@@ -443,6 +567,83 @@ describe('${t} repository', () => {
     expect(result.total).toBe(3)
   })
 
+  it('should filter, search and sort before paginating', async () => {
+    await repo.create({ name: 'Banana' })
+    await repo.create({ name: 'apple' })
+    await repo.create({ name: 'Cherry' })
+    const pagination = { page: 1, limit: 10, offset: 0 }
+
+    const sorted = await repo.findPaginated({
+      filters: [],
+      sort: [{ field: 'name', direction: 'desc' }],
+      search: '',
+      pagination,
+    })
+    expect(sorted.data.map((row) => row.name)).toEqual(['Cherry', 'Banana', 'apple'])
+
+    const filtered = await repo.findPaginated({
+      filters: [{ field: 'name', operator: 'neq', value: 'apple' }],
+      sort: [],
+      search: '',
+      pagination: { page: 1, limit: 1, offset: 0 },
+    })
+    expect(filtered.data).toHaveLength(1)
+    expect(filtered.total).toBe(2)
+
+    const searched = await repo.findPaginated({ filters: [], sort: [], search: 'AN', pagination })
+    expect(searched.data.map((row) => row.name)).toEqual(['Banana'])
+  })
+
+  it('compares a text field as text, not as a number', async () => {
+    await repo.create({ name: '001' })
+    await repo.create({ name: '10' })
+    await repo.create({ name: '9' })
+    const pagination = { page: 1, limit: 10, offset: 0 }
+
+    const exact = await repo.findPaginated({
+      filters: [{ field: 'name', operator: 'eq', value: '1' }],
+      sort: [],
+      search: '',
+      pagination,
+    })
+    expect(exact.total).toBe(0)
+
+    const sorted = await repo.findPaginated({
+      filters: [],
+      sort: [{ field: 'name', direction: 'asc' }],
+      search: '',
+      pagination,
+    })
+    expect(sorted.data.map((row) => row.name)).toEqual(['001', '10', '9'])
+  })
+
+  it('pages through rows with findAfter, stable when sort keys tie', async () => {
+    // Three rows share 'a', so a page boundary falls inside the tie: only the
+    // id tie-breaker keeps the third 'a' from being skipped or repeated.
+    for (const name of ['b', 'a', 'b', 'a', 'a']) await repo.create({ name })
+    const query = { filters: [], sort: [{ field: 'name', direction: 'asc' as const }], search: '' }
+    const limit = 2
+
+    const pages: string[][] = []
+    const ids: string[] = []
+    let cursor: Record<string, unknown> | null = null
+    let hasNext = true
+    while (hasNext) {
+      // Ask for one more than a page, as ctx.paginateCursor's fetcher does.
+      const rows = await repo.findAfter({ ...query, cursor, limit: limit + 1 })
+      hasNext = rows.length > limit
+      const page = rows.slice(0, limit)
+      pages.push(page.map((row) => row.name))
+      ids.push(...page.map((row) => row.id))
+      const last = page.at(-1)
+      cursor = last ? { name: last.name, id: last.id } : null
+    }
+
+    expect(pages.map((page) => page.length)).toEqual([2, 2, 1])
+    expect(pages.flat()).toEqual(['a', 'a', 'a', 'b', 'b'])
+    expect(new Set(ids).size).toBe(5)
+  })
+
   it('should update a ${n}', async () => {
     const created = await repo.create({ name: 'Original' })
     const updated = await repo.update(created.id, { name: 'Updated' })
@@ -456,7 +657,7 @@ describe('${t} repository', () => {
     expect(found).toBeNull()
   })
 })
-`}function L(e){let{pascal:t,kebab:n}=e;return`import { Service, Inject, HttpException } from '@forinda/kickjs'
+`}function L(e){let{pascal:t,kebab:n}=e;return`import { Service, Inject } from '@forinda/kickjs'
 import type { ParsedQuery } from '@forinda/kickjs'
 import { ${t.toUpperCase()}_REPOSITORY, type ${t}Repository } from './${n}.repository'
 import type { ${t}ResponseDTO } from './dtos/${n}-response.dto'
@@ -481,6 +682,10 @@ export class ${t}Service {
     return this.repo.findPaginated(parsed)
   }
 
+  async findAfter(query: Parameters<${t}Repository['findAfter']>[0]) {
+    return this.repo.findAfter(query)
+  }
+
   async create(dto: Create${t}DTO): Promise<${t}ResponseDTO> {
     return this.repo.create(dto)
   }
@@ -493,14 +698,14 @@ export class ${t}Service {
     await this.repo.delete(id)
   }
 }
-`}function R(e){let{pascal:t}=e;return`import type { QueryFieldConfig } from '@forinda/kickjs'
+`}const de=/* @__PURE__ */ new Set([`string`,`text`,`email`,`url`]),fe=/* @__PURE__ */ new Set([`json`]);function R(e){let{pascal:t,fields:n=[{name:`name`,type:`string`}]}=e,r=n.filter(e=>!fe.has(e.type)).map(e=>e.name),i=n.filter(e=>de.has(e.type)).map(e=>e.name),a=e=>`[${e.map(e=>`'${e}'`).join(`, `)}]`;return`import type { QueryFieldConfig } from '@forinda/kickjs'
 
 export const ${t.toUpperCase()}_QUERY_CONFIG: QueryFieldConfig = {
-  filterable: ['name'],
-  sortable: ['name', 'createdAt'],
-  searchable: ['name'],
+  filterable: ${a(r)},
+  sortable: ${a([...r.filter(e=>e!==`createdAt`),`createdAt`])},
+  searchable: ${a(i)},
 }
-`}async function fe(e){let{pascal:t,kebab:n,plural:r,style:i,write:a}=e;await a(`${n}.module.ts`,oe({pascal:t,kebab:n,plural:r,style:i})),await a(`${n}.controller.ts`,`import { Controller, Get, Post, Put, Delete, reply, type Ctx } from '@forinda/kickjs'
+`}async function pe(e){let{pascal:t,kebab:n,plural:r,routePath:i,style:a,write:o}=e;await o(`${n}.module.ts`,ae({pascal:t,kebab:n,plural:r,routePath:i,style:a})),await o(`${n}.controller.ts`,`import { Controller, Get, Post, Patch, Delete, reply, type Ctx } from '@forinda/kickjs'
 
 // \`Ctx<KickRoutes.${t}Controller['<method>']>\` is generated by
 // \`kick typegen\` (auto-run on \`kick dev\`).
@@ -513,6 +718,7 @@ export const ${t.toUpperCase()}_QUERY_CONFIG: QueryFieldConfig = {
 // "Minimal" is about the file count, not the route surface — you get the whole
 // CRUD shape here in one file.
 
+// Require a signed-in user for these routes: https://kickjs.app/guide/authentication
 @Controller()
 export class ${t}Controller {
   @Get('/')
@@ -530,7 +736,7 @@ export class ${t}Controller {
     return reply.created({ data: ctx.body })
   }
 
-  @Put('/:id')
+  @Patch('/:id')
   async update(ctx: Ctx<KickRoutes.${t}Controller['update']>) {
     return { id: ctx.params.id, data: ctx.body }
   }
@@ -540,7 +746,7 @@ export class ${t}Controller {
     return reply.noContent()
   }
 }
-`)}async function pe(e){let{pascal:t,kebab:n,plural:r,pluralPascal:i,repo:a,noTests:o,tokenScope:s,style:c,testHarness:l,write:u}=e,d=e.swagger??!1,f=e.schemaLib??`zod`;await u(`${n}.module.ts`,M({pascal:t,kebab:n,plural:r,repo:a,style:c})),await u(`${n}.constants.ts`,R({pascal:t,kebab:n})),await u(`${n}.controller.ts`,N({pascal:t,kebab:n,plural:r,pluralPascal:i,swagger:d})),await u(`${n}.service.ts`,L({pascal:t,kebab:n})),await u(`dtos/create-${n}.dto.ts`,se({pascal:t,kebab:n,schemaLib:f})),await u(`dtos/update-${n}.dto.ts`,ce({pascal:t,kebab:n,schemaLib:f})),await u(`dtos/${n}-response.dto.ts`,le({pascal:t,kebab:n})),await u(`${n}.repository.ts`,I({pascal:t,kebab:n,repoType:a,dtoPrefix:`./dtos`,tokenScope:s})),o||(await u(`__tests__/${n}.controller.test.ts`,ue({pascal:t,kebab:n,plural:r,style:c,testHarness:l})),await u(`__tests__/${n}.repository.test.ts`,de({pascal:t,kebab:n,plural:r,repoPrefix:`../${n}.repository`})))}function me(e){return e?typeof e==`string`?e:e.name:`inmemory`}async function he(n){let{name:r,modulesDir:i,noEntity:c,noTests:l,repo:u=`inmemory`,force:d,dryRun:f}=n,p=n.pluralize!==!1,m=n.pattern??`rest`;n.minimal&&(m=`minimal`);let g=D(r),_=T(r),v=p?O(g):g,y=p?k(_):_,b=h(i,v),x=[],S=d??!1,C={kebab:g,pascal:_,plural:v,pluralPascal:y,moduleDir:b,repo:u,noEntity:c??!1,noTests:l??!1,tokenScope:n.tokenScope??`app`,swagger:n.swagger??!1,schemaLib:n.schemaLib??`zod`,testHarness:n.testHarness??!1,style:n.style??`define`,write:async(n,r)=>{let i=h(b,n);f?x.push(i):!S&&await e(i)&&!await o({message:`File exists: ${s.dim(n)}. Overwrite?`,initialValue:!1})?a.warn(`Skipped: ${n}`):(await t(i,r),x.push(i))},files:x};switch(m){case`minimal`:await fe(C);break;default:await pe(C)}return f||await z(i,_,v,g,C.style),x}async function z(n,r,i,a,o=`define`){let s=h(n,`index.ts`),c=await e(s),l=`./${i}/${a}.module`,u=o===`class`?`${r}Module`:`${r}Module()`;if(!c){let e=o===`class`?`import type { AppModuleEntry } from '@forinda/kickjs'
+`)}async function me(e){let{pascal:t,kebab:n,plural:r,pluralPascal:i,routePath:a,repo:o,noTests:s,tokenScope:c,style:l,testHarness:u,testImport:d,write:f}=e,p=e.swagger??!1,m=e.schemaLib??`zod`;await f(`${n}.module.ts`,M({pascal:t,kebab:n,plural:r,routePath:a,repo:o,style:l})),await f(`${n}.constants.ts`,R({pascal:t,kebab:n})),await f(`${n}.controller.ts`,N({pascal:t,kebab:n,plural:r,pluralPascal:i,swagger:p})),await f(`${n}.service.ts`,L({pascal:t,kebab:n})),await f(`dtos/create-${n}.dto.ts`,oe({pascal:t,kebab:n,schemaLib:m})),await f(`dtos/update-${n}.dto.ts`,se({pascal:t,kebab:n,schemaLib:m})),await f(`dtos/${n}-response.dto.ts`,ce({pascal:t,kebab:n})),await f(`${n}.repository.ts`,I({pascal:t,kebab:n,repoType:o,dtoPrefix:`./dtos`,tokenScope:c})),s||(await f(`__tests__/${n}.controller.test.ts`,le({pascal:t,kebab:n,plural:r,routePath:a,style:l,testHarness:u,testImport:d})),await f(`__tests__/${n}.repository.test.ts`,ue({pascal:t,kebab:n,plural:r,repoPrefix:`../${n}.repository`,testImport:d})))}function he(e){return e?typeof e==`string`?e:e.name:`inmemory`}async function ge(n){let{name:r,modulesDir:i,noEntity:c,noTests:l,repo:u=`inmemory`,force:d,dryRun:f}=n,p=n.pluralize===!0,m=n.pattern??`rest`;n.minimal&&(m=`minimal`);let g=D(r),_=T(r),v=p?O(g):g,y=p?k(_):_,b=n.pluralizeRoutes===!1?g:O(g),x=h(i,v),S=[],C=d??!1,w={kebab:g,pascal:_,plural:v,pluralPascal:y,routePath:b,moduleDir:x,repo:u,noEntity:c??!1,noTests:l??!1,tokenScope:n.tokenScope??`app`,swagger:n.swagger??!1,schemaLib:n.schemaLib??`zod`,testHarness:n.testHarness??!1,testImport:n.testImport,style:n.style??`define`,write:async(n,r)=>{let i=h(x,n);f?S.push(i):!C&&await e(i)&&!await o({message:`File exists: ${s.dim(n)}. Overwrite?`,initialValue:!1})?a.warn(`Skipped: ${n}`):(await t(i,r),S.push(i))},files:S};switch(m){case`minimal`:await pe(w);break;default:await me(w)}return f||await z(i,_,v,g,w.style),S}async function z(n,r,i,a,o=`define`){let s=h(n,`index.ts`),c=await e(s),l=`./${i}/${a}.module`,u=o===`class`?`${r}Module`:`${r}Module()`;if(!c){let e=o===`class`?`import type { AppModuleEntry } from '@forinda/kickjs'
 import { ${r}Module } from '${l}'
 
 export const modules: AppModuleEntry[] = [${u}]
@@ -551,8 +757,8 @@ export const modules = defineModules().mount(${u})
 `;await t(s,e);return}let d=await S(s,`utf-8`),f=`import { ${r}Module } from '${l}'`,p=A(l);if(!RegExp(`^import\\s*\\{[^}]*\\b${A(r)}Module\\b[^}]*\\}\\s*from\\s*['"]${p}['"]`,`m`).test(d)){let e=d.lastIndexOf(`import `);if(e!==-1){let t=d.indexOf(`
 `,e);d=d.slice(0,t+1)+f+`
 `+d.slice(t+1)}else d=f+`
-`+d}let m=V(d);if(m){let e=d.slice(m.rhsStart,m.rhsEnd+1);RegExp(`\\b${A(r)}Module\\b`).test(e)||(d=B(d,u))}else d=B(d,u);await C(s,d,`utf-8`)}function B(e,t){let n=V(e);if(!n)return e;if(n.shape===`array`){let r=e.slice(n.rhsStart+1,n.rhsEnd),i=r.trim(),a;if(!i)a=`[${t}]`;else{let e=i.endsWith(`,`)?``:`,`;a=`[${r.trimEnd()}${e} ${t}]`}return e.slice(0,n.rhsStart)+a+e.slice(n.rhsEnd+1)}return`${e.slice(0,n.chainEnd)}\n  .mount(${t})${e.slice(n.chainEnd)}`}function V(e){let t=/export\s+const\s+modules\b[^=]*=/.exec(e);if(!t)return null;let n=t.index+t[0].length;for(;n<e.length&&/\s/.test(e[n]??``);)n++;if(e[n]===`[`){let t=_e(e,n);return t===-1?null:{shape:`array`,rhsStart:n,rhsEnd:t}}if(e.slice(n,n+13)===`defineModules`){let t=ge(e,n);return t===-1?null:{shape:`chain`,rhsStart:n,rhsEnd:t-1,chainEnd:t}}return null}function ge(e,t=0){let n=/defineModules\s*\(/g;n.lastIndex=t;let r=n.exec(e);if(!r)return-1;let i=r.index+r[0].length-1;if(e[i]!==`(`||(i=U(e,i),i===-1))return-1;for(i++;;){let t=i;for(;t<e.length&&/\s/.test(e[t]??``);)t++;if(e[t]!==`.`||e.slice(t,t+6)!==`.mount`)break;for(t+=6;t<e.length&&/\s/.test(e[t]??``);)t++;if(e[t]!==`(`)break;let n=U(e,t);if(n===-1)break;i=n+1}return i}function H(e,t){let n=e.slice(t,t+2);if(n===`//`){for(t+=2;t<e.length&&e[t]!==`
-`;)t++;return t}if(n===`/*`){for(t+=2;t+1<e.length&&(e[t]!==`*`||e[t+1]!==`/`);)t++;return t+2}return t}function _e(e,t){if(e[t]!==`[`)return-1;let n=1,r=t+1;for(;r<e.length;){let t=e.slice(r,r+2);if(t===`//`||t===`/*`){r=H(e,r);continue}let i=e[r]??``;if(i===`'`||i===`"`||i==="`"){let t=i;for(r++;r<e.length&&e[r]!==t;)e[r]===`\\`&&r++,r++;r<e.length&&r++}else{if(i===`[`)n++;else if(i===`]`&&(n--,n===0))return r;r++}}return-1}function U(e,t){if(e[t]!==`(`)return-1;let n=1,r=t+1;for(;r<e.length;){let t=e.slice(r,r+2);if(t===`//`||t===`/*`){r=H(e,r);continue}let i=e[r]??``;if(i===`'`||i===`"`||i==="`"){let t=i;for(r++;r<e.length&&e[r]!==t;)e[r]===`\\`&&r++,r++;r<e.length&&r++}else{if(i===`(`)n++;else if(i===`)`&&(n--,n===0))return r;r++}}return-1}function W(e,t,n,r){return`/**
+`+d}let m=V(d);if(m){let e=d.slice(m.rhsStart,m.rhsEnd+1);RegExp(`\\b${A(r)}Module\\b`).test(e)||(d=B(d,u))}else d=B(d,u);await t(s,d)}function B(e,t){let n=V(e);if(!n)return e;if(n.shape===`array`){let r=e.slice(n.rhsStart+1,n.rhsEnd),i=r.trim(),a;if(!i)a=`[${t}]`;else{let e=i.endsWith(`,`)?``:`,`;a=`[${r.trimEnd()}${e} ${t}]`}return e.slice(0,n.rhsStart)+a+e.slice(n.rhsEnd+1)}return`${e.slice(0,n.chainEnd)}\n  .mount(${t})${e.slice(n.chainEnd)}`}function V(e){let t=/export\s+const\s+modules\b[^=]*=/.exec(e);if(!t)return null;let n=t.index+t[0].length;for(;n<e.length&&/\s/.test(e[n]??``);)n++;if(e[n]===`[`){let t=ve(e,n);return t===-1?null:{shape:`array`,rhsStart:n,rhsEnd:t}}if(e.slice(n,n+13)===`defineModules`){let t=_e(e,n);return t===-1?null:{shape:`chain`,rhsStart:n,rhsEnd:t-1,chainEnd:t}}return null}function _e(e,t=0){let n=/defineModules\s*\(/g;n.lastIndex=t;let r=n.exec(e);if(!r)return-1;let i=r.index+r[0].length-1;if(e[i]!==`(`||(i=U(e,i),i===-1))return-1;for(i++;;){let t=i;for(;t<e.length&&/\s/.test(e[t]??``);)t++;if(e[t]!==`.`||e.slice(t,t+6)!==`.mount`)break;for(t+=6;t<e.length&&/\s/.test(e[t]??``);)t++;if(e[t]!==`(`)break;let n=U(e,t);if(n===-1)break;i=n+1}return i}function H(e,t){let n=e.slice(t,t+2);if(n===`//`){for(t+=2;t<e.length&&e[t]!==`
+`;)t++;return t}if(n===`/*`){for(t+=2;t+1<e.length&&(e[t]!==`*`||e[t+1]!==`/`);)t++;return t+2}return t}function ve(e,t){if(e[t]!==`[`)return-1;let n=1,r=t+1;for(;r<e.length;){let t=e.slice(r,r+2);if(t===`//`||t===`/*`){r=H(e,r);continue}let i=e[r]??``;if(i===`'`||i===`"`||i==="`"){let t=i;for(r++;r<e.length&&e[r]!==t;)e[r]===`\\`&&r++,r++;r<e.length&&r++}else{if(i===`[`)n++;else if(i===`]`&&(n--,n===0))return r;r++}}return-1}function U(e,t){if(e[t]!==`(`)return-1;let n=1,r=t+1;for(;r<e.length;){let t=e.slice(r,r+2);if(t===`//`||t===`/*`){r=H(e,r);continue}let i=e[r]??``;if(i===`'`||i===`"`||i==="`"){let t=i;for(r++;r<e.length&&e[r]!==t;)e[r]===`\\`&&r++,r++;r<e.length&&r++}else{if(i===`(`)n++;else if(i===`)`&&(n--,n===0))return r;r++}}return-1}function W(e,t,n,r){return`/**
  * Snapshot for the DevTools topology view (\`/_debug\`).
  *
  * Must be CHEAP — the topology endpoint polls on a short interval, so
@@ -592,7 +798,7 @@ export const modules = defineModules().mount(${u})
 //   ]
 // },`.split(`
 `).map(e=>r+e).join(`
-`)}async function ve(e){let{name:n,outDir:r}=e,i=D(n),a=T(n),o=[],s=h(r,`${i}.adapter.ts`);return await t(s,`import {
+`)}async function ye(e){let{name:n,outDir:r}=e,i=D(n),a=T(n),o=[],s=h(r,`${i}.adapter.ts`);return await t(s,`import {
   defineAdapter,
   type AdapterContext,
   type AdapterMiddleware,
@@ -801,8 +1007,8 @@ ${W(i,a,`adapter`,`      `)}
     }
   },
 })
-`),o.push(s),o}const ye={controller:``,service:``,dto:`dtos`,guard:`guards`,middleware:`middleware`,contributor:`contributors`};function G(e){let{type:t,outDir:n,moduleName:r,modulesDir:i=`src/modules`,defaultDir:a,shouldPluralize:o=!0}=e;if(n)return _(n);if(r){let e=ye,n=D(r),a=o?O(n):n,s=e[t]??``,c=h(i,a);return _(s?h(c,s):c)}return _(a)}async function be(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=e.runtime===`express`,s=e.runtime?`this project runs on ${e.runtime} and has no
-  // \`express\``:"this project declares no `runtime` in kick.config.ts, so it\n  // may have no `express`",c=G({type:`middleware`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/middleware`,pattern:a,shouldPluralize:e.pluralize??!0}),l=D(n),u=E(n),d=[],f=h(c,`${l}.middleware.ts`);return await t(f,`${o?`import type { Request, Response, NextFunction } from 'express'`:`import type { IncomingMessage, ServerResponse } from 'node:http'`}
+`),o.push(s),o}const be={controller:``,service:``,dto:`dtos`,guard:`guards`,middleware:`middleware`,contributor:`contributors`};function G(e){let{type:t,outDir:n,moduleName:r,modulesDir:i=`src/modules`,defaultDir:a,shouldPluralize:o=!1}=e;if(n)return _(n);if(r){let e=be,n=D(r),a=o?O(n):n,s=e[t]??``,c=h(i,a);return _(s?h(c,s):c)}return _(a)}async function xe(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=e.runtime===`express`,s=e.runtime?`this project runs on ${e.runtime} and has no
+  // \`express\``:"this project declares no `runtime` in kick.config.ts, so it\n  // may have no `express`",c=G({type:`middleware`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/middleware`,pattern:a,shouldPluralize:e.pluralize??!1}),l=D(n),u=E(n),d=[],f=h(c,`${l}.middleware.ts`);return await t(f,`${o?`import type { Request, Response, NextFunction } from 'express'`:`import type { IncomingMessage, ServerResponse } from 'node:http'`}
 
 export interface ${T(n)}Options {
   // Add configuration options here. The factory below closes over the
@@ -861,7 +1067,7 @@ ${o?"  // Typed from `express` because that is this project's runtime\n  // (`ru
     next()
   }
 }
-`),d.push(f),d}async function xe(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`guard`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/guards`,pattern:a,shouldPluralize:e.pluralize??!0}),s=D(n),c=E(n),l=T(n),u=[],d=h(o,`${s}.guard.ts`);return await t(d,`import { Container, HttpException } from '@forinda/kickjs'
+`),d.push(f),d}async function Se(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`guard`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/guards`,pattern:a,shouldPluralize:e.pluralize??!1}),s=D(n),c=E(n),l=T(n),u=[],d=h(o,`${s}.guard.ts`);return await t(d,`import { Container, HttpException } from '@forinda/kickjs'
 import type { RequestContext } from '@forinda/kickjs'
 
 /**
@@ -901,7 +1107,7 @@ export async function ${c}Guard(ctx: RequestContext, next: () => void): Promise<
     ctx.problem.unauthorized({ detail: 'Invalid or expired token' })
   }
 }
-`),u.push(d),u}async function Se(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`service`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/services`,pattern:a,shouldPluralize:e.pluralize??!0}),s=D(n),c=T(n),l=[],u=h(o,`${s}.service.ts`);return await t(u,`import { Service } from '@forinda/kickjs'
+`),u.push(d),u}async function Ce(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`service`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/services`,pattern:a,shouldPluralize:e.pluralize??!1}),s=D(n),c=T(n),l=[],u=h(o,`${s}.service.ts`);return await t(u,`import { Service } from '@forinda/kickjs'
 
 @Service()
 export class ${c}Service {
@@ -910,7 +1116,7 @@ export class ${c}Service {
   //   @Inject(MY_REPO) private readonly repo: IMyRepository,
   // ) {}
 }
-`),l.push(u),l}async function Ce(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`controller`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/controllers`,pattern:a,shouldPluralize:e.pluralize??!0}),s=D(n),c=T(n),l=[],u=h(o,`${s}.controller.ts`);return await t(u,`import { Controller, Get, Post, Put, Delete, reply, type Ctx } from '@forinda/kickjs'
+`),l.push(u),l}async function we(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`controller`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/controllers`,pattern:a,shouldPluralize:e.pluralize??!1}),s=D(n),c=T(n),l=[],u=h(o,`${s}.controller.ts`);return await t(u,`import { Controller, Get, Post, Patch, Delete, reply, type Ctx } from '@forinda/kickjs'
 
 // \`Ctx<KickRoutes.${c}Controller['<method>']>\` is generated by
 // \`kick typegen\` (auto-run on \`kick dev\`). After the first run, your IDE
@@ -923,6 +1129,7 @@ export class ${c}Service {
 //
 // The bodies below are placeholders: wire them to a service or repository.
 
+// Require a signed-in user for these routes: https://kickjs.app/guide/authentication
 @Controller()
 export class ${c}Controller {
   // @Autowired() private readonly myService!: MyService
@@ -942,7 +1149,7 @@ export class ${c}Controller {
     return reply.created({ data: ctx.body })
   }
 
-  @Put('/:id')
+  @Patch('/:id')
   async update(ctx: Ctx<KickRoutes.${c}Controller['update']>) {
     return { id: ctx.params.id, data: ctx.body }
   }
@@ -952,21 +1159,21 @@ export class ${c}Controller {
     return reply.noContent()
   }
 }
-`),l.push(u),l}async function we(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`dto`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/dtos`,pattern:a,shouldPluralize:e.pluralize??!0}),s=D(n),c=T(n),l=E(n),u=e.schemaLib??`zod`,d=P[u],f=[],p=h(o,`${s}.dto.ts`);return await t(p,`${d.import}
+`),l.push(u),l}async function Te(e){let{name:n,moduleName:r,modulesDir:i,pattern:a}=e,o=G({type:`dto`,outDir:e.outDir,moduleName:r,modulesDir:i,defaultDir:`src/dtos`,pattern:a,shouldPluralize:e.pluralize??!1}),s=D(n),c=T(n),l=E(n),u=e.schemaLib??`zod`,d=P[u],f=[],p=h(o,`${s}.dto.ts`);return await t(p,`${d.import}
 
 export const ${l}Schema = ${F(u,`// Define your schema fields here\n  name: ${d.required}`)}
 
 export type ${c}DTO = ${d.infer(`${l}Schema`)}
-`),f.push(p),f}function Te(){let e=(process.env.LOG_LEVEL??process.env.KICKJS_LOG_LEVEL??``).toLowerCase();return e===`debug`||e===`trace`}var Ee=class extends Error{drifted;constructor(e){let t=e.map(e=>`    ${e.id} → ${e.outFile}`).join(`
-`);super(`kick typegen --check: ${e.length} generated file(s) are out of date:\n${t}\n  Run \`kick typegen\` and commit the result.`),this.name=`TypegenDriftError`,this.drifted=e}};function De(e){return e}function Oe(e){let t=/* @__PURE__ */ new Map;return{report(n,r){let i=r instanceof Error?r.message:String(r);t.get(n)!==i&&(t.set(n,i),e(`  kick typegen: ${n} pass failed (${i}) — types in .kickjs/types may be stale`))},clear(e){t.delete(e)}}}const ke=`__kickjs_typegen_owner`;function Ae(e){let{cwd:t,config:n}=e,r=e.debounceMs??100,i=e.pipeline??{runTypegen:async e=>(await import(`./typegen-DSaawXaQ.mjs`).then(e=>e.n)).runTypegen(e),runAllPluginTypegens:async e=>(await import(`./run-plugins-Dx-QENlm.mjs`).then(e=>e.n)).runAllPluginTypegens(e),writeTypegenArtifacts:async(e,t,n)=>(await import(`./typegen-DSaawXaQ.mjs`).then(e=>e.n)).writeTypegenArtifacts(e,t,n),buildAssets:async(e,t)=>(await import(`./build-BuBCsnzr.mjs`).then(e=>e.n)).buildAssets(e,t)},a=n?.typegen?.schemaValidator??`zod`,o=n?.typegen?.envFile,s=p.resolve(t,n?.typegen?.outDir??`.kickjs/types`),c=n?.assetMap?Object.values(n.assetMap).map(e=>e?.src).filter(e=>typeof e==`string`&&e.length>0).map(e=>p.resolve(t,e)):[],l=!!n?.assetMap&&Object.keys(n.assetMap).length>0,u=e=>e.replaceAll(`\\`,`/`),d=c.map(u),f=e=>{let t=u(e);return d.some(e=>t===e||t.startsWith(`${e}/`))},m=Oe(e.emitWarning),h=null,g=!1,_=/* @__PURE__ */ new Set,v=/* @__PURE__ */ new Set,y=!1,b=!1;function x(r,c){i.runTypegen({cwd:t,silent:!0,allowDuplicates:!0,schemaValidator:a,envFile:o,srcDir:n?.typegen?.srcDir,outDir:n?.typegen?.outDir,assetMap:n?.assetMap,changedFiles:r,runPlugins:!1}).then(()=>m.clear(`scan`)).catch(e=>m.report(`scan`,e)),i.runAllPluginTypegens({cwd:t,config:n,silent:!0,changedFiles:r,watch:!0}).then(e=>i.writeTypegenArtifacts(s,e,!0)).then(()=>m.clear(`plugins`)).catch(e=>m.report(`plugins`,e)).finally(()=>e.onPassComplete?.()),c&&n&&i.buildAssets(n,{cwd:t,silent:!0}).catch(()=>{})}function S(){let e=y?void 0:{changed:[..._],removed:[...v]},t=b;_.clear(),v.clear(),y=!1,b=!1,x(e,t)}return{assetSrcRoots:c,handleWatchEvent(e,t){if(!g&&!u(t).includes(`/.kickjs/`)){if(e===`unlinkDir`)y=!0,l&&(b=!0);else{if(t.endsWith(`.d.ts`))return;let n=/\.(ts|tsx|mts|cts)$/.test(t),r=f(t);if(!n&&!r)return;r&&l&&(b=!0),n&&(e===`unlink`?(v.add(t),_.delete(t)):(_.add(t),v.delete(t)))}h&&clearTimeout(h),h=setTimeout(S,r)}},runOnce(){g||x(void 0,l)},dispose(){g=!0,h&&clearTimeout(h),h=null}}}function je(e){return D(e).replace(/-/g,`_`)}function K(e){let t=e.cwd??process.cwd(),n=e.projectRoot??d(t),r=e.pluralize??!0,i=T(e.name),a=E(e.name),o=D(e.name),s=je(e.name),c={name:e.name,pascal:i,camel:a,kebab:o,snake:s,modulesDir:e.modulesDir??`src/modules`,cwd:t,projectRoot:n,args:e.args??[],flags:e.flags??{}};if(r){let e=O(o);c.pluralKebab=e,c.pluralPascal=T(e),c.pluralCamel=E(e)}return c}function Me(e,t){return _(e.cwd,t)}async function Ne(e){return import(ee(e).href)}const q=/* @__PURE__ */ new Map;async function J(e){let t=q.get(e);if(t)return t;let n=Pe(e);return q.set(e,n),n}async function Pe(e){let t=_(e,`package.json`);if(!v(t))return{generators:[],loaded:[],failed:[]};let n=Fe(JSON.parse(await S(t,`utf-8`))),r=f(_(e,`package.json`)),i=[],a=[],o=[];for(let e of n){let t;try{t=r.resolve(`${e}/package.json`)}catch{continue}let n;try{n=JSON.parse(await S(t,`utf-8`))}catch(t){o.push({source:e,reason:`failed to parse package.json: ${t}`});continue}if(!n.kickjs?.generators)continue;let s=n.kickjs.generators,c=_(m(t),s);if(!v(c)){o.push({source:e,reason:`kickjs.generators points to missing file: ${s}`});continue}let l;try{l=await Ne(c)}catch(t){o.push({source:e,reason:`failed to import manifest: ${t}`});continue}let u=l.default;if(!Array.isArray(u))o.push({source:e,reason:`manifest's default export is not an array of GeneratorSpec`});else{for(let t of u)Ie(t)?i.push({source:e,spec:t}):o.push({source:e,reason:`manifest entry is not a valid GeneratorSpec (missing name/files)`});a.push(e)}}return{generators:i,loaded:a,failed:o}}function Fe(e){let t=/* @__PURE__ */ new Set;for(let n of[e.dependencies,e.devDependencies,e.peerDependencies])if(n)for(let e of Object.keys(n))t.add(e);return Array.from(t)}function Ie(e){if(!e||typeof e!=`object`)return!1;let t=e;return typeof t.name==`string`&&typeof t.files==`function`}async function Le(e,t=[]){let n=e.cwd??process.cwd(),r=t.find(t=>t.spec.name===e.generatorName);if(r)return Y(r.spec,r.source,e,n);let i=ze(await J(n),e.generatorName);return i?Y(i.spec,i.source,e,n):null}async function Re(e,t=[]){let n=await J(e),r=new Set(t.map(e=>e.spec.name)),i=n.generators.filter(e=>!r.has(e.spec.name));return{generators:[...t,...i],loaded:n.loaded,failed:n.failed}}function ze(e,t){return e.generators.find(e=>e.spec.name===t)}async function Y(e,n,r,i){let a=K({name:r.itemName,args:r.args,flags:r.flags,modulesDir:r.modulesDir,pluralize:r.pluralize,cwd:i,projectRoot:r.projectRoot}),o=await e.files(a),s=[];for(let e of o){let n=Me(a,e.path);await t(n,e.content),s.push(n)}return{files:s,source:n}}function Be(e){return e}function Ve(e){return e}function He(e){try{return JSON.parse(y(e,`utf-8`))}catch{return null}}function X(e){try{return y(e,`utf-8`)}catch{return null}}function Ue(e){let t=e.replace(/\/\*[\s\S]*?\*\//g,``).replace(/(^|[^:"'\\])\/\/.*$/gm,`$1`).replace(/,(\s*[}\]])/g,`$1`);try{return JSON.parse(t)}catch{return null}}function We(e){let t=h(e,`tsconfig.json`);if(v(t))return Z(t,/* @__PURE__ */ new Set)}function Z(e,t){if(t.has(e)||t.size>=16)return null;t.add(e);let n=X(e);if(n===null)return null;let r=Ue(n);if(typeof r!=`object`||!r)return null;let i=Array.isArray(r.extends)?r.extends:typeof r.extends==`string`?[r.extends]:[],a={};for(let n of i){if(typeof n!=`string`)continue;let r=Ge(m(e),n);if(!r)continue;let i=Z(r,t);i&&Object.assign(a,i.compilerOptions)}return r.compilerOptions={...a,...r.compilerOptions},r}function Ge(e,t){if(t.startsWith(`.`)||t.startsWith(`/`))return Q(_(e,t));let n=e;for(;;){let e=Q(h(n,`node_modules`,t));if(e)return e;let r=m(n);if(r===n)break;n=r}return null}function Q(e){if(v(e)){try{if(x(e).isDirectory()){let t=h(e,`tsconfig.json`);return v(t)?t:null}}catch{return null}return e}let t=`${e}.json`;return v(t)?t:null}function Ke(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function qe(){let e=process.version,t=Number.parseInt(e.replace(/^v/,``).split(`.`)[0],10);return Number.isNaN(t)||t<20?{name:`Node version`,status:`fail`,message:e,fix:`KickJS requires Node 20 or newer.
-Install a supported version via nvm / fnm / volta.`}:{name:`Node version`,status:`pass`,message:e}}function Je(e){if(!e.pkg)return{name:`@forinda/kickjs installed`,status:`warn`,message:`no package.json`};let t={...e.pkg.dependencies,...e.pkg.peerDependencies};return t[`@forinda/kickjs`]?{name:`@forinda/kickjs installed`,status:`pass`,message:t[`@forinda/kickjs`]}:{name:`@forinda/kickjs installed`,status:`fail`,fix:"This directory does not look like a KickJS project — `@forinda/kickjs` is not in your package.json. Run `kick doctor` from the project root, or scaffold a fresh project with `kick new <name>`."}}function Ye(e){if(!e.pkg)return null;let t={...e.pkg.dependencies,...e.pkg.peerDependencies};return t[`@forinda/kickjs`]&&!t.express?{name:`express installed`,status:`fail`,fix:`\`@forinda/kickjs\` declares \`express\` as a required peer dependency, but your package.json does not include it. Install: ${n(e.cwd)} add express`}:t.express?{name:`express installed`,status:`pass`,message:t.express}:null}const Xe={express:[],fastify:[`fastify`,`@fastify/middie`],h3:[`h3`]};function Ze(e){if(!e.pkg||e.runtime===`express`)return null;let t={...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies},r=Xe[e.runtime].filter(e=>!t[e]),i=`runtime engine (${e.runtime})`;return r.length>0?{name:i,status:`fail`,fix:`Resolved runtime '${e.runtime}' is missing engine peer(s): ${r.join(`, `)}.\nInstall: ${n(e.cwd)} add ${r.join(` `)}`}:e.runtime===`h3`&&Qe(e.cwd,t.h3)===1?{name:i,status:`fail`,message:`h3 v1`,fix:`This version of @forinda/kickjs runs on h3 v2 only. Upgrade: ${n(e.cwd)} add h3@^2 — no code change for apps that only use KickJS APIs.`}:{name:i,status:`pass`}}function Qe(e,t){let n=t;for(let t=_(e);;t=m(t)){try{n=JSON.parse(y(h(t,`node_modules`,`h3`,`package.json`),`utf8`)).version;break}catch{}if(m(t)===t)break}let r=/(\d+)/.exec(n)?.[1];return r===void 0?void 0:Number(r)}function $e(e){if(!e.pkg||!et(e.cwd))return null;let t=u[e.runtime],r=`upload driver (${e.runtime})`;return t.prod?{...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies}[t.prod]?{name:r,status:`pass`,message:t.prod}:{name:r,status:`fail`,fix:`This project uses file uploads on the '${e.runtime}' runtime, which needs '${t.prod}'.\nInstall it: kick add upload (or ${n(e.cwd)} add ${t.prod})`}:{name:r,status:`pass`,message:`native multipart`}}const $=2e3;function et(e){let t=h(e,`src`);if(!v(t))return!1;let n=/@FileUpload\b|\bupload\.(single|array|none)\s*\(/,r=[t],i=0;for(;r.length>0&&i<$;){let e=r.pop(),t;try{t=b(e,{withFileTypes:!0})}catch{continue}for(let a of t){if(i>=$)break;let t=h(e,a.name);if(a.isDirectory())a.name!==`node_modules`&&r.push(t);else if(/\.(ts|tsx|mts|cts)$/.test(a.name)&&(i++,n.test(X(t)??``)))return!0}}return!1}function tt(e){if(!e.pkg)return{name:`reflect-metadata installed`,status:`warn`,message:`no package.json`};let t={...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies};return t[`reflect-metadata`]?{name:`reflect-metadata installed`,status:`pass`,message:t[`reflect-metadata`]}:{name:`reflect-metadata installed`,status:`fail`,fix:`KickJS decorators require the reflect-metadata polyfill.\nInstall it: ${n(e.cwd)} add reflect-metadata\nThen import it at the top of src/index.ts:\n\n  import 'reflect-metadata'\n  // ... rest of bootstrap`}}function nt(e){if(e.tsconfig===void 0)return[{name:`tsconfig.json present`,status:`fail`,fix:"Create a tsconfig.json with `experimentalDecorators: true` and `emitDecoratorMetadata: true`. `kick new` scaffolds one automatically."}];if(e.tsconfig===null)return[{name:`tsconfig.json readable`,status:`warn`,message:`could not parse tsconfig.json (or a config it extends)`,fix:"Check tsconfig.json for a syntax error, and that every path in its `extends` chain resolves. Decorator options could not be verified."}];let t=e.tsconfig.compilerOptions??{},n=[];return n.push(t.experimentalDecorators===!0?{name:`tsconfig: experimentalDecorators`,status:`pass`}:{name:`tsconfig: experimentalDecorators`,status:`fail`,fix:'Add `"experimentalDecorators": true` to compilerOptions in tsconfig.json. Without it, @Service / @Controller / @Get etc. don\'t register any metadata at compile time.'}),n.push(t.emitDecoratorMetadata===!0?{name:`tsconfig: emitDecoratorMetadata`,status:`pass`}:{name:`tsconfig: emitDecoratorMetadata`,status:`fail`,fix:'Add `"emitDecoratorMetadata": true` to compilerOptions in tsconfig.json. The DI container uses this metadata for constructor-parameter injection.'}),n}function rt(e){let t=[`src/env.ts`,`src/env/index.ts`,`src/config/env.ts`,`src/config/index.ts`].map(t=>h(e.cwd,t)).filter(e=>v(e)).filter(e=>/\bloadEnv\s*\(/.test(X(e)??``));if(t.length===0)return null;let n=[`src/index.ts`,`src/main.ts`].map(t=>h(e.cwd,t)).find(e=>v(e));if(!n)return{name:`env wiring`,status:`warn`,message:`env-init file exists but no src/index.ts or src/main.ts found`};let r=X(n)??``,i=m(n),a=[];for(let e of t){let t=g(i,e).replace(/\\/g,`/`).replace(/\.ts$/,``),n=t.startsWith(`.`)?t:`./`+t,r=n.replace(/\/index$/,``);a.push(n,r);let o=e.replace(/\\/g,`/`).match(/\/src\/(.+?)(?:\.ts)?$/);if(o){let e=`@/`+o[1],t=e.replace(/\/index$/,``);a.push(e,t)}}let o=-1;for(let e of new Set(a)){let t=RegExp(`^import\\s+(?:.*?from\\s+)?['"]${Ke(e)}['"]`,`m`),n=r.match(t);n&&n.index!==void 0&&(o===-1||n.index<o)&&(o=n.index)}let s=r.search(/\bbootstrap\s*\(/),c=t.map(t=>g(e.cwd,t).replace(/\\/g,`/`)).join(`, `);return o===-1?{name:`env wiring`,status:`fail`,message:c,fix:`An env-init file (${c}) calls \`loadEnv(...)\` but \`${g(e.cwd,n).replace(/\\/g,`/`)}\` doesn't import it.\nWithout this, ConfigService.get('X') returns undefined while @Value('X') works via process.env fallback — a half-broken config you won't notice until something is missing.\n\nFix: add a side-effect import at the top of ${g(e.cwd,n).replace(/\\/g,`/`)} (above bootstrap()), pointing at one of the detected files. For example:\n\n  import './env'\n  // or\n  import './config'\n  // or, with the @/ alias:\n  import '@/config/env'`}:s!==-1&&o>s?{name:`env wiring`,status:`warn`,message:`env-init imported AFTER bootstrap() — should be before`,fix:`Move the env import above the bootstrap() call so the schema runs before any service reads from ConfigService.`}:{name:`env wiring`,status:`pass`}}function it(e,t=at){let n=0,r=0,i=[e];for(;i.length>0&&r<t;){let e=i.pop(),a;try{a=b(e,{withFileTypes:!0})}catch{continue}for(let o of a){if(r>=t)break;r++;let a=h(e,o.name);if(o.isDirectory())i.push(a);else try{let e=x(a).mtimeMs;e>n&&(n=e)}catch{}}}return n}const at=2e3;function ot(e){let t=h(e.cwd,`.kickjs`,`types`);if(!v(t))return null;let n=it(t);if(n===0)return null;let r=Date.now()-n,i=Math.floor(r/6e4);return i>60?{name:`typegen freshness`,status:`warn`,message:`last updated ${i} minutes ago`,fix:"Re-run `kick typegen` (or `kick dev`, which runs it on every reload) so generated types match the current code."}:{name:`typegen freshness`,status:`pass`,message:i===0?`just now`:`${i}m ago`}}const st=[`vitest.config.ts`,`vitest.config.js`,`vitest.config.mts`,`vite.config.ts`,`jest.config.ts`,`jest.config.js`],ct=[`.env.test`,`.env.test.local`],lt=[`.env`,`.env.local`];function ut(e){let t=e.pkg?.scripts;if(t&&typeof t==`object`)for(let[e,n]of Object.entries(t)){if(!e.startsWith(`test`)||typeof n!=`string`)continue;let t=/KICKJS_ENV_FILE=(\S+)/.exec(n);if(t?.[1])return t[1]}return process.env.KICKJS_ENV_FILE??null}function dt(e){if(!st.some(t=>v(h(e.cwd,t))))return null;let t=lt.filter(t=>v(h(e.cwd,t)));if(t.length===0)return null;let n=ct.filter(t=>v(h(e.cwd,t)));if(n.length>0){let t=ut(e);return t&&t!==`off`&&t!==`none`?{name:`test env isolation`,status:`warn`,message:`${n.join(`, `)} present, but KICKJS_ENV_FILE=${t} overrides it`,fix:`KICKJS_ENV_FILE is checked before test-mode isolation, so ${n[0]} is\nignored and "${t}" is read instead. Drop the override to use the\ntest files, or set KICKJS_ENV_FILE=off if env comes from the runner.`}:{name:`test env isolation`,status:`pass`,message:`${n.join(`, `)} present`}}return{name:`test env isolation`,status:`warn`,message:`${t.join(`, `)} present, no .env.test`,fix:`Under NODE_ENV=test (or vitest's VITEST) KickJS reads .env.test / .env.test.local
+`),f.push(p),f}function Ee(){let e=(process.env.LOG_LEVEL??process.env.KICKJS_LOG_LEVEL??``).toLowerCase();return e===`debug`||e===`trace`}var De=class extends Error{drifted;constructor(e){let t=e.map(e=>`    ${e.id} → ${e.outFile}`).join(`
+`);super(`kick typegen --check: ${e.length} generated file(s) are out of date:\n${t}\n  Run \`kick typegen\` and commit the result.`),this.name=`TypegenDriftError`,this.drifted=e}};function Oe(e){return e}function ke(e){let t=/* @__PURE__ */ new Map;return{report(n,r){let i=r instanceof Error?r.message:String(r);t.get(n)!==i&&(t.set(n,i),e(`  kick typegen: ${n} pass failed (${i}) — types in .kickjs/types may be stale`))},clear(e){t.delete(e)}}}const Ae=`__kickjs_typegen_owner`;function je(e){let{cwd:t,config:n}=e,r=e.debounceMs??100,i=e.pipeline??{runTypegen:async e=>(await import(`./typegen-AGdhxyRc.mjs`).then(e=>e.n)).runTypegen(e),runAllPluginTypegens:async e=>(await import(`./run-plugins-9tjbMqS6.mjs`).then(e=>e.n)).runAllPluginTypegens(e),writeTypegenArtifacts:async(e,t,n)=>(await import(`./typegen-AGdhxyRc.mjs`).then(e=>e.n)).writeTypegenArtifacts(e,t,n),buildAssets:async(e,t)=>(await import(`./build-DQnV0GCD.mjs`).then(e=>e.n)).buildAssets(e,t)},a=n?.typegen?.schemaValidator??`zod`,o=n?.typegen?.envFile,s=p.resolve(t,n?.typegen?.outDir??`.kickjs/types`),c=n?.assetMap?Object.values(n.assetMap).map(e=>e?.src).filter(e=>typeof e==`string`&&e.length>0).map(e=>p.resolve(t,e)):[],l=!!n?.assetMap&&Object.keys(n.assetMap).length>0,u=e=>e.replaceAll(`\\`,`/`),d=c.map(u),f=e=>{let t=u(e);return d.some(e=>t===e||t.startsWith(`${e}/`))},m=ke(e.emitWarning),h=null,g=!1,_=/* @__PURE__ */ new Set,v=/* @__PURE__ */ new Set,y=!1,b=!1;function x(r,c){i.runTypegen({cwd:t,silent:!0,allowDuplicates:!0,schemaValidator:a,envFile:o,srcDir:n?.typegen?.srcDir,outDir:n?.typegen?.outDir,assetMap:n?.assetMap,changedFiles:r,runPlugins:!1}).then(()=>m.clear(`scan`)).catch(e=>m.report(`scan`,e)),i.runAllPluginTypegens({cwd:t,config:n,silent:!0,changedFiles:r,watch:!0}).then(e=>i.writeTypegenArtifacts(s,e,!0)).then(()=>m.clear(`plugins`)).catch(e=>m.report(`plugins`,e)).finally(()=>e.onPassComplete?.()),c&&n&&i.buildAssets(n,{cwd:t,silent:!0}).catch(()=>{})}function S(){let e=y?void 0:{changed:[..._],removed:[...v]},t=b;_.clear(),v.clear(),y=!1,b=!1,x(e,t)}return{assetSrcRoots:c,handleWatchEvent(e,t){if(!g&&!u(t).includes(`/.kickjs/`)){if(e===`unlinkDir`)y=!0,l&&(b=!0);else{if(t.endsWith(`.d.ts`))return;let n=/\.(ts|tsx|mts|cts)$/.test(t),r=f(t);if(!n&&!r)return;r&&l&&(b=!0),n&&(e===`unlink`?(v.add(t),_.delete(t)):(_.add(t),v.delete(t)))}h&&clearTimeout(h),h=setTimeout(S,r)}},runOnce(){g||x(void 0,l)},dispose(){g=!0,h&&clearTimeout(h),h=null}}}function Me(e){return D(e).replace(/-/g,`_`)}function K(e){let t=e.cwd??process.cwd(),n=e.projectRoot??d(t),r=e.pluralize??!1,i=T(e.name),a=E(e.name),o=D(e.name),s=Me(e.name),c={name:e.name,pascal:i,camel:a,kebab:o,snake:s,modulesDir:e.modulesDir??`src/modules`,cwd:t,projectRoot:n,args:e.args??[],flags:e.flags??{}};if(r){let e=O(o);c.pluralKebab=e,c.pluralPascal=T(e),c.pluralCamel=E(e)}return c}function Ne(e,t){return _(e.cwd,t)}async function Pe(e){return import(w(e).href)}const q=/* @__PURE__ */ new Map;async function J(e){let t=q.get(e);if(t)return t;let n=Fe(e);return q.set(e,n),n}async function Fe(e){let t=_(e,`package.json`);if(!v(t))return{generators:[],loaded:[],failed:[]};let n=Ie(JSON.parse(await S(t,`utf-8`))),r=f(_(e,`package.json`)),i=[],a=[],o=[];for(let e of n){let t;try{t=r.resolve(`${e}/package.json`)}catch{continue}let n;try{n=JSON.parse(await S(t,`utf-8`))}catch(t){o.push({source:e,reason:`failed to parse package.json: ${t}`});continue}if(!n.kickjs?.generators)continue;let s=n.kickjs.generators,c=_(m(t),s);if(!v(c)){o.push({source:e,reason:`kickjs.generators points to missing file: ${s}`});continue}let l;try{l=await Pe(c)}catch(t){o.push({source:e,reason:`failed to import manifest: ${t}`});continue}let u=l.default;if(!Array.isArray(u))o.push({source:e,reason:`manifest's default export is not an array of GeneratorSpec`});else{for(let t of u)Le(t)?i.push({source:e,spec:t}):o.push({source:e,reason:`manifest entry is not a valid GeneratorSpec (missing name/files)`});a.push(e)}}return{generators:i,loaded:a,failed:o}}function Ie(e){let t=/* @__PURE__ */ new Set;for(let n of[e.dependencies,e.devDependencies,e.peerDependencies])if(n)for(let e of Object.keys(n))t.add(e);return Array.from(t)}function Le(e){if(!e||typeof e!=`object`)return!1;let t=e;return typeof t.name==`string`&&typeof t.files==`function`}async function Re(e,t=[]){let n=e.cwd??process.cwd(),r=t.find(t=>t.spec.name===e.generatorName);if(r)return Y(r.spec,r.source,e,n);let i=Be(await J(n),e.generatorName);return i?Y(i.spec,i.source,e,n):null}async function ze(e,t=[]){let n=await J(e),r=new Set(t.map(e=>e.spec.name)),i=n.generators.filter(e=>!r.has(e.spec.name));return{generators:[...t,...i],loaded:n.loaded,failed:n.failed}}function Be(e,t){return e.generators.find(e=>e.spec.name===t)}async function Y(e,n,r,i){let a=K({name:r.itemName,args:r.args,flags:r.flags,modulesDir:r.modulesDir,pluralize:r.pluralize,cwd:i,projectRoot:r.projectRoot}),o=await e.files(a),s=[];for(let e of o){let n=Ne(a,e.path);await t(n,e.content),s.push(n)}return{files:s,source:n}}function Ve(e){return e}function He(e){return e}function Ue(e){try{return JSON.parse(y(e,`utf-8`))}catch{return null}}function X(e){try{return y(e,`utf-8`)}catch{return null}}function We(e){let t=e.replace(/\/\*[\s\S]*?\*\//g,``).replace(/(^|[^:"'\\])\/\/.*$/gm,`$1`).replace(/,(\s*[}\]])/g,`$1`);try{return JSON.parse(t)}catch{return null}}function Ge(e){let t=h(e,`tsconfig.json`);if(v(t))return Z(t,/* @__PURE__ */ new Set)}function Z(e,t){if(t.has(e)||t.size>=16)return null;t.add(e);let n=X(e);if(n===null)return null;let r=We(n);if(typeof r!=`object`||!r)return null;let i=Array.isArray(r.extends)?r.extends:typeof r.extends==`string`?[r.extends]:[],a={};for(let n of i){if(typeof n!=`string`)continue;let r=Ke(m(e),n);if(!r)continue;let i=Z(r,t);i&&Object.assign(a,i.compilerOptions)}return r.compilerOptions={...a,...r.compilerOptions},r}function Ke(e,t){if(t.startsWith(`.`)||t.startsWith(`/`))return Q(_(e,t));let n=e;for(;;){let e=Q(h(n,`node_modules`,t));if(e)return e;let r=m(n);if(r===n)break;n=r}return null}function Q(e){if(v(e)){try{if(x(e).isDirectory()){let t=h(e,`tsconfig.json`);return v(t)?t:null}}catch{return null}return e}let t=`${e}.json`;return v(t)?t:null}function qe(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function Je(){let e=process.version,t=Number.parseInt(e.replace(/^v/,``).split(`.`)[0],10);return Number.isNaN(t)||t<20?{name:`Node version`,status:`fail`,message:e,fix:`KickJS requires Node 20 or newer.
+Install a supported version via nvm / fnm / volta.`}:{name:`Node version`,status:`pass`,message:e}}function Ye(e){if(!e.pkg)return{name:`@forinda/kickjs installed`,status:`warn`,message:`no package.json`};let t={...e.pkg.dependencies,...e.pkg.peerDependencies};return t[`@forinda/kickjs`]?{name:`@forinda/kickjs installed`,status:`pass`,message:t[`@forinda/kickjs`]}:{name:`@forinda/kickjs installed`,status:`fail`,fix:"This directory does not look like a KickJS project — `@forinda/kickjs` is not in your package.json. Run `kick doctor` from the project root, or scaffold a fresh project with `kick new <name>`."}}function Xe(e){if(!e.pkg)return null;let t={...e.pkg.dependencies,...e.pkg.peerDependencies};return t[`@forinda/kickjs`]&&!t.express?{name:`express installed`,status:`fail`,fix:`\`@forinda/kickjs\` declares \`express\` as a required peer dependency, but your package.json does not include it. Install: ${n(e.cwd)} add express`}:t.express?{name:`express installed`,status:`pass`,message:t.express}:null}const Ze={express:[],fastify:[`fastify`,`@fastify/middie`],h3:[`h3`]};function Qe(e){if(!e.pkg||e.runtime===`express`)return null;let t={...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies},r=Ze[e.runtime].filter(e=>!t[e]),i=`runtime engine (${e.runtime})`;return r.length>0?{name:i,status:`fail`,fix:`Resolved runtime '${e.runtime}' is missing engine peer(s): ${r.join(`, `)}.\nInstall: ${n(e.cwd)} add ${r.join(` `)}`}:e.runtime===`h3`&&$e(e.cwd,t.h3)===1?{name:i,status:`fail`,message:`h3 v1`,fix:`This version of @forinda/kickjs runs on h3 v2 only. Upgrade: ${n(e.cwd)} add h3@^2 — no code change for apps that only use KickJS APIs.`}:{name:i,status:`pass`}}function $e(e,t){let n=t;for(let t=_(e);;t=m(t)){try{n=JSON.parse(y(h(t,`node_modules`,`h3`,`package.json`),`utf8`)).version;break}catch{}if(m(t)===t)break}let r=/(\d+)/.exec(n)?.[1];return r===void 0?void 0:Number(r)}function et(e){if(!e.pkg||!tt(e.cwd))return null;let t=u[e.runtime],r=`upload driver (${e.runtime})`;return t.prod?{...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies}[t.prod]?{name:r,status:`pass`,message:t.prod}:{name:r,status:`fail`,fix:`This project uses file uploads on the '${e.runtime}' runtime, which needs '${t.prod}'.\nInstall it: kick add upload (or ${n(e.cwd)} add ${t.prod})`}:{name:r,status:`pass`,message:`native multipart`}}const $=2e3;function tt(e){let t=h(e,`src`);if(!v(t))return!1;let n=/@FileUpload\b|\bupload\.(single|array|none)\s*\(/,r=[t],i=0;for(;r.length>0&&i<$;){let e=r.pop(),t;try{t=b(e,{withFileTypes:!0})}catch{continue}for(let a of t){if(i>=$)break;let t=h(e,a.name);if(a.isDirectory())a.name!==`node_modules`&&r.push(t);else if(/\.(ts|tsx|mts|cts)$/.test(a.name)&&(i++,n.test(X(t)??``)))return!0}}return!1}function nt(e){if(!e.pkg)return{name:`reflect-metadata installed`,status:`warn`,message:`no package.json`};let t={...e.pkg.dependencies,...e.pkg.peerDependencies,...e.pkg.devDependencies};return t[`reflect-metadata`]?{name:`reflect-metadata installed`,status:`pass`,message:t[`reflect-metadata`]}:{name:`reflect-metadata installed`,status:`fail`,fix:`KickJS decorators require the reflect-metadata polyfill.\nInstall it: ${n(e.cwd)} add reflect-metadata\nThen import it at the top of src/index.ts:\n\n  import 'reflect-metadata'\n  // ... rest of bootstrap`}}function rt(e){if(e.tsconfig===void 0)return[{name:`tsconfig.json present`,status:`fail`,fix:"Create a tsconfig.json with `experimentalDecorators: true` and `emitDecoratorMetadata: true`. `kick new` scaffolds one automatically."}];if(e.tsconfig===null)return[{name:`tsconfig.json readable`,status:`warn`,message:`could not parse tsconfig.json (or a config it extends)`,fix:"Check tsconfig.json for a syntax error, and that every path in its `extends` chain resolves. Decorator options could not be verified."}];let t=e.tsconfig.compilerOptions??{},n=[];return n.push(t.experimentalDecorators===!0?{name:`tsconfig: experimentalDecorators`,status:`pass`}:{name:`tsconfig: experimentalDecorators`,status:`fail`,fix:'Add `"experimentalDecorators": true` to compilerOptions in tsconfig.json. Without it, @Service / @Controller / @Get etc. don\'t register any metadata at compile time.'}),n.push(t.emitDecoratorMetadata===!0?{name:`tsconfig: emitDecoratorMetadata`,status:`pass`}:{name:`tsconfig: emitDecoratorMetadata`,status:`fail`,fix:'Add `"emitDecoratorMetadata": true` to compilerOptions in tsconfig.json. The DI container uses this metadata for constructor-parameter injection.'}),n}function it(e){let t=[`src/env.ts`,`src/env/index.ts`,`src/config/env.ts`,`src/config/index.ts`].map(t=>h(e.cwd,t)).filter(e=>v(e)).filter(e=>/\bloadEnv\s*\(/.test(X(e)??``));if(t.length===0)return null;let n=[`src/index.ts`,`src/main.ts`].map(t=>h(e.cwd,t)).find(e=>v(e));if(!n)return{name:`env wiring`,status:`warn`,message:`env-init file exists but no src/index.ts or src/main.ts found`};let r=X(n)??``,i=m(n),a=[];for(let e of t){let t=g(i,e).replace(/\\/g,`/`).replace(/\.ts$/,``),n=t.startsWith(`.`)?t:`./`+t,r=n.replace(/\/index$/,``);a.push(n,r);let o=e.replace(/\\/g,`/`).match(/\/src\/(.+?)(?:\.ts)?$/);if(o){let e=`@/`+o[1],t=e.replace(/\/index$/,``);a.push(e,t)}}let o=-1;for(let e of new Set(a)){let t=RegExp(`^import\\s+(?:.*?from\\s+)?['"]${qe(e)}['"]`,`m`),n=r.match(t);n&&n.index!==void 0&&(o===-1||n.index<o)&&(o=n.index)}let s=r.search(/\bbootstrap\s*\(/),c=t.map(t=>g(e.cwd,t).replace(/\\/g,`/`)).join(`, `);return o===-1?{name:`env wiring`,status:`fail`,message:c,fix:`An env-init file (${c}) calls \`loadEnv(...)\` but \`${g(e.cwd,n).replace(/\\/g,`/`)}\` doesn't import it.\nWithout this, ConfigService.get('X') returns undefined while @Value('X') works via process.env fallback — a half-broken config you won't notice until something is missing.\n\nFix: add a side-effect import at the top of ${g(e.cwd,n).replace(/\\/g,`/`)} (above bootstrap()), pointing at one of the detected files. For example:\n\n  import './env'\n  // or\n  import './config'\n  // or, with the @/ alias:\n  import '@/config/env'`}:s!==-1&&o>s?{name:`env wiring`,status:`warn`,message:`env-init imported AFTER bootstrap() — should be before`,fix:`Move the env import above the bootstrap() call so the schema runs before any service reads from ConfigService.`}:{name:`env wiring`,status:`pass`}}function at(e,t=ot){let n=0,r=0,i=[e];for(;i.length>0&&r<t;){let e=i.pop(),a;try{a=b(e,{withFileTypes:!0})}catch{continue}for(let o of a){if(r>=t)break;r++;let a=h(e,o.name);if(o.isDirectory())i.push(a);else try{let e=x(a).mtimeMs;e>n&&(n=e)}catch{}}}return n}const ot=2e3;function st(e){let t=h(e.cwd,`.kickjs`,`types`);if(!v(t))return null;let n=at(t);if(n===0)return null;let r=Date.now()-n,i=Math.floor(r/6e4);return i>60?{name:`typegen freshness`,status:`warn`,message:`last updated ${i} minutes ago`,fix:"Re-run `kick typegen` (or `kick dev`, which runs it on every reload) so generated types match the current code."}:{name:`typegen freshness`,status:`pass`,message:i===0?`just now`:`${i}m ago`}}const ct=[`vitest.config.ts`,`vitest.config.js`,`vitest.config.mts`,`vite.config.ts`,`jest.config.ts`,`jest.config.js`],lt=[`.env.test`,`.env.test.local`],ut=[`.env`,`.env.local`];function dt(e){let t=e.pkg?.scripts;if(t&&typeof t==`object`)for(let[e,n]of Object.entries(t)){if(!e.startsWith(`test`)||typeof n!=`string`)continue;let t=/KICKJS_ENV_FILE=(\S+)/.exec(n);if(t?.[1])return t[1]}return process.env.KICKJS_ENV_FILE??null}function ft(e){if(!ct.some(t=>v(h(e.cwd,t))))return null;let t=ut.filter(t=>v(h(e.cwd,t)));if(t.length===0)return null;let n=lt.filter(t=>v(h(e.cwd,t)));if(n.length>0){let t=dt(e);return t&&t!==`off`&&t!==`none`?{name:`test env isolation`,status:`warn`,message:`${n.join(`, `)} present, but KICKJS_ENV_FILE=${t} overrides it`,fix:`KICKJS_ENV_FILE is checked before test-mode isolation, so ${n[0]} is\nignored and "${t}" is read instead. Drop the override to use the\ntest files, or set KICKJS_ENV_FILE=off if env comes from the runner.`}:{name:`test env isolation`,status:`pass`,message:`${n.join(`, `)} present`}}return{name:`test env isolation`,status:`warn`,message:`${t.join(`, `)} present, no .env.test`,fix:`Under NODE_ENV=test (or vitest's VITEST) KickJS reads .env.test / .env.test.local
 INSTEAD of ${t.join(` and `)} — no layering, no fallback. Without one of\nthose files, every var your test config does not pin resolves from your
 development env — including DATABASE_URL and any third-party credentials.
 
 Create .env.test (cp .env.test.example .env.test, if the project has one)
 holding the whole environment the suite should run against
 (a var you leave out is then missing, not inherited), or set KICKJS_ENV_FILE=off
-and supply env from the test runner.`}}const ft=[()=>qe(),Je,Ye,Ze,$e,tt,nt,rt,dt,ot];async function pt(e,t={}){let n={cwd:e,pkg:He(h(e,`package.json`)),tsconfig:We(e),runtime:t.runtime??`express`},r=[...ft,...t.extraChecks??[]],i=[];for(let e of r){let t;try{t=await e(n)}catch(t){i.push({name:e.name||`doctor check`,status:`fail`,message:t instanceof Error?t.message:String(t)});continue}t!=null&&(Array.isArray(t)?i.push(...t):i.push(t))}return i}function mt(e){switch(e){case`pass`:return s.green(`✔`);case`warn`:return s.yellow(`⚠`);case`fail`:return s.red(`✖`)}}function ht(e){let t=mt(e.status),n=e.message?`  ${s.dim(`(${e.message})`)}`:``;return`${t}  ${e.name}${n}`}function gt(e){return e.split(`
+and supply env from the test runner.`}}const pt=[()=>Je(),Ye,Xe,Qe,et,nt,rt,it,ft,st];async function mt(e,t={}){let n={cwd:e,pkg:Ue(h(e,`package.json`)),tsconfig:Ge(e),runtime:t.runtime??`express`},r=[...pt,...t.extraChecks??[]],i=[];for(let e of r){let t;try{t=await e(n)}catch(t){i.push({name:e.name||`doctor check`,status:`fail`,message:t instanceof Error?t.message:String(t)});continue}t!=null&&(Array.isArray(t)?i.push(...t):i.push(t))}return i}function ht(e){switch(e){case`pass`:return s.green(`✔`);case`warn`:return s.yellow(`⚠`);case`fail`:return s.red(`✖`)}}function gt(e){let t=ht(e.status),n=e.message?`  ${s.dim(`(${e.message})`)}`:``;return`${t}  ${e.name}${n}`}function _t(e){return e.split(`
 `).map(e=>`   ${s.dim(`→`)} ${e}`).join(`
-`)}function _t(e){return e?.doctor?.checks??[]}function vt(e){e.command(`doctor`).description(`Pre-flight checks for your KickJS project (dev environment health)`).action(async()=>{let e=process.cwd(),t=_t(await c(e)),n=await l(e);i(`KickJS Doctor`);let o=await pt(e,{extraChecks:t,runtime:n});for(let e of o)a.message(ht(e)),e.fix&&e.status!==`pass`&&a.message(gt(e.fix));let u=o.filter(e=>e.status===`pass`).length,d=o.filter(e=>e.status===`warn`).length,f=o.filter(e=>e.status===`fail`).length,p=[s.green(`${u} passed`),d>0?s.yellow(`${d} warning${d===1?``:`s`}`):`${d} warnings`,f>0?s.red(`${f} error${f===1?``:`s`}`):`${f} errors`].join(`, `);f>0?(r(`${p} — fix the errors above before running the app`),process.exit(1)):r(d>0?`${p} — review the warnings`:s.green(`${p} — your environment looks good`))})}export{A,he as C,I as D,L as E,T as F,k as M,E as N,N as O,D as P,V as S,R as T,be as _,Le as a,W as b,ke as c,De as d,Te as f,xe as g,Se as h,Re as i,O as j,M as k,Ae as l,Ce as m,Be as n,K as o,we as p,vt as r,te as s,Ve as t,Ee as u,G as v,me as w,z as x,ve as y};
-//# sourceMappingURL=doctor-DGWvBOvj.mjs.map
+`)}function vt(e){return e?.doctor?.checks??[]}function yt(e){e.command(`doctor`).description(`Pre-flight checks for your KickJS project (dev environment health)`).action(async()=>{let e=process.cwd(),t=vt(await c(e)),n=await l(e);i(`KickJS Doctor`);let o=await mt(e,{extraChecks:t,runtime:n});for(let e of o)a.message(gt(e)),e.fix&&e.status!==`pass`&&a.message(_t(e.fix));let u=o.filter(e=>e.status===`pass`).length,d=o.filter(e=>e.status===`warn`).length,f=o.filter(e=>e.status===`fail`).length,p=[s.green(`${u} passed`),d>0?s.yellow(`${d} warning${d===1?``:`s`}`):`${d} warnings`,f>0?s.red(`${f} error${f===1?``:`s`}`):`${f} errors`].join(`, `);f>0?(r(`${p} — fix the errors above before running the app`),process.exit(1)):r(d>0?`${p} — review the warnings`:s.green(`${p} — your environment looks good`))})}export{A,ge as C,I as D,L as E,T as F,k as M,E as N,N as O,D as P,V as S,R as T,xe as _,Re as a,W as b,Ae as c,Oe as d,Ee as f,Se as g,Ce as h,ze as i,O as j,M as k,je as l,we as m,Ve as n,K as o,Te as p,yt as r,ee as s,He as t,De as u,G as v,he as w,z as x,ye as y};
+//# sourceMappingURL=doctor-rEbeoAoO.mjs.map