@warlock.js/core 5.2.3 → 5.3.0

package/esm/validation/validators/file-validator.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"file-validator.mjs","names":[],"sources":["../../../../../../../../core/src/validation/validators/file-validator.ts"],"sourcesContent":["import type { FileSizeOption, JsonSchemaResult, JsonSchemaTarget } from \"@warlock.js/seal\";\nimport {\n  BaseValidator,\n  maxFileSizeRule,\n  maxHeightRule,\n  maxWidthRule,\n  minFileSizeRule,\n  minHeightRule,\n  minWidthRule,\n  resolveFileSize,\n  v,\n} from \"@warlock.js/seal\";\nimport { UploadedFile } from \"../../http\";\nimport { fileExtensionRule, fileRule, fileTypeRule, imageRule } from \"../file\";\n\nexport const uploadedFileMetadataSchema = v.object({\n  location: v.string().oneOf([\"local\", \"cloud\"]),\n  width: v.int().positive(),\n  height: v.int().positive(),\n  size: v.int().positive(),\n  mimeType: v.string(),\n  extension: v.string(),\n  name: v.string(),\n});\n\n/**\n * File validator class\n */\nexport class FileValidator extends BaseValidator {\n  public constructor(errorMessage?: string) {\n    super();\n    this.addMutableRule(fileRule, errorMessage);\n  }\n\n  /**\n   * Check if value is a File type\n   */\n  public matchesType(value: any): boolean {\n    return value instanceof UploadedFile;\n  }\n\n  /** Value must be an image */\n  public image(errorMessage?: string): FileValidator {\n    return this.addRule(imageRule, errorMessage);\n  }\n\n  /** Accept specific file extensions */\n  public accept(extensions: string | string[], errorMessage?: string): FileValidator {\n    return this.addRule(fileExtensionRule, errorMessage, {\n      extensions,\n    });\n  }\n\n  /** Allow specific MIME types */\n  public mimeType(mimeTypes: string | string[], errorMessage?: string): FileValidator {\n    return this.addRule(fileTypeRule, errorMessage, {\n      mimeTypes,\n    });\n  }\n\n  /** Allow only pdf files */\n  public pdf(errorMessage?: string): FileValidator {\n    return this.mimeType(\"application/pdf\", errorMessage);\n  }\n\n  /** Allow only excel files */\n  public excel(errorMessage?: string): FileValidator {\n    return this.mimeType(\n      [\n        \"application/vnd.ms-excel\",\n        \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n      ],\n      errorMessage,\n    );\n  }\n\n  /** Allow only word files */\n  public word(errorMessage?: string): FileValidator {\n    return this.mimeType(\n      [\n        \"application/msword\",\n        \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      ],\n      errorMessage,\n    );\n  }\n\n  /** Minimum file size */\n  public minSize(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.addRule(minFileSizeRule, errorMessage, {\n      minSize: resolveFileSize(size),\n    });\n  }\n\n  /** @alias minSize */\n  public min(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.minSize(size, errorMessage);\n  }\n\n  /** Maximum file size */\n  public maxSize(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.addRule(maxFileSizeRule, errorMessage, {\n      maxSize: resolveFileSize(size),\n    });\n  }\n\n  /** @alias maxSize */\n  public max(size: number, errorMessage?: string): FileValidator {\n    return this.maxSize(size, errorMessage);\n  }\n\n  /** Minimum image width */\n  public minWidth(width: number, errorMessage?: string): FileValidator {\n    return this.addRule(minWidthRule, errorMessage, {\n      minWidth: width,\n    });\n  }\n\n  /** Maximum image width */\n  public maxWidth(width: number, errorMessage?: string): FileValidator {\n    return this.addRule(maxWidthRule, errorMessage, {\n      maxWidth: width,\n    });\n  }\n\n  /** Minimum image height */\n  public minHeight(height: number, errorMessage?: string): FileValidator {\n    return this.addRule(minHeightRule, errorMessage, {\n      minHeight: height,\n    });\n  }\n\n  /** Maximum image height */\n  public maxHeight(height: number, errorMessage?: string): FileValidator {\n    return this.addRule(maxHeightRule, errorMessage, {\n      maxHeight: height,\n    });\n  }\n\n  /**\n   * Save the file and return it as a string\n   */\n  public saveTo(relativeDirectory: string): FileValidator {\n    return this.addTransformer(async (file: UploadedFile) => {\n      const output = await file.save(relativeDirectory);\n\n      return output.path;\n    });\n  }\n\n  /**\n   * @inheritdoc\n   *\n   * File uploads are not natively representable in JSON Schema.\n   * The output varies by target:\n   * - `openapi-3.0`   → `{ type: \"string\", format: \"binary\" }` (standard for multipart/form-data uploads)\n   * - `draft-2020-12` → `{ type: \"string\", contentEncoding: \"binary\" }`\n   * - `draft-07`      → `{}` (no standard binary representation — permissive fallback)\n   *\n   * @example\n   * ```ts\n   * v.file().toJsonSchema(\"openapi-3.0\")\n   * // → { type: \"string\", format: \"binary\" }\n   * ```\n   */\n  public override toJsonSchema(target: JsonSchemaTarget = \"draft-2020-12\"): JsonSchemaResult {\n    if (target === \"openapi-3.0\") {\n      return { type: \"string\", format: \"binary\" };\n    }\n\n    if (target === \"draft-2020-12\") {\n      return { type: \"string\", contentEncoding: \"binary\" };\n    }\n\n    // draft-07: no standard binary representation\n    return {};\n  }\n}\n"],"mappings":";;;;;;;AAeA,MAAa,6BAA6B,EAAE,OAAO;CACjD,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,OAAO,CAAC;CAC7C,OAAO,EAAE,IAAI,EAAE,SAAS;CACxB,QAAQ,EAAE,IAAI,EAAE,SAAS;CACzB,MAAM,EAAE,IAAI,EAAE,SAAS;CACvB,UAAU,EAAE,OAAO;CACnB,WAAW,EAAE,OAAO;CACpB,MAAM,EAAE,OAAO;AACjB,CAAC;;;;AAKD,IAAa,gBAAb,cAAmC,cAAc;CAC/C,AAAO,YAAY,cAAuB;EACxC,MAAM;EACN,KAAK,eAAe,UAAU,YAAY;CAC5C;;;;CAKA,AAAO,YAAY,OAAqB;EACtC,OAAO,iBAAiB;CAC1B;;CAGA,AAAO,MAAM,cAAsC;EACjD,OAAO,KAAK,QAAQ,WAAW,YAAY;CAC7C;;CAGA,AAAO,OAAO,YAA+B,cAAsC;EACjF,OAAO,KAAK,QAAQ,mBAAmB,cAAc,EACnD,WACF,CAAC;CACH;;CAGA,AAAO,SAAS,WAA8B,cAAsC;EAClF,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UACF,CAAC;CACH;;CAGA,AAAO,IAAI,cAAsC;EAC/C,OAAO,KAAK,SAAS,mBAAmB,YAAY;CACtD;;CAGA,AAAO,MAAM,cAAsC;EACjD,OAAO,KAAK,SACV,CACE,4BACA,mEACF,GACA,YACF;CACF;;CAGA,AAAO,KAAK,cAAsC;EAChD,OAAO,KAAK,SACV,CACE,sBACA,yEACF,GACA,YACF;CACF;;CAGA,AAAO,QAAQ,MAA+B,cAAsC;EAClF,OAAO,KAAK,QAAQ,iBAAiB,cAAc,EACjD,SAAS,gBAAgB,IAAI,EAC/B,CAAC;CACH;;CAGA,AAAO,IAAI,MAA+B,cAAsC;EAC9E,OAAO,KAAK,QAAQ,MAAM,YAAY;CACxC;;CAGA,AAAO,QAAQ,MAA+B,cAAsC;EAClF,OAAO,KAAK,QAAQ,iBAAiB,cAAc,EACjD,SAAS,gBAAgB,IAAI,EAC/B,CAAC;CACH;;CAGA,AAAO,IAAI,MAAc,cAAsC;EAC7D,OAAO,KAAK,QAAQ,MAAM,YAAY;CACxC;;CAGA,AAAO,SAAS,OAAe,cAAsC;EACnE,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UAAU,MACZ,CAAC;CACH;;CAGA,AAAO,SAAS,OAAe,cAAsC;EACnE,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UAAU,MACZ,CAAC;CACH;;CAGA,AAAO,UAAU,QAAgB,cAAsC;EACrE,OAAO,KAAK,QAAQ,eAAe,cAAc,EAC/C,WAAW,OACb,CAAC;CACH;;CAGA,AAAO,UAAU,QAAgB,cAAsC;EACrE,OAAO,KAAK,QAAQ,eAAe,cAAc,EAC/C,WAAW,OACb,CAAC;CACH;;;;CAKA,AAAO,OAAO,mBAA0C;EACtD,OAAO,KAAK,eAAe,OAAO,SAAuB;GAGvD,QAAO,MAFc,KAAK,KAAK,iBAAiB,GAElC;EAChB,CAAC;CACH;;;;;;;;;;;;;;;;CAiBA,AAAgB,aAAa,SAA2B,iBAAmC;EACzF,IAAI,WAAW,eACb,OAAO;GAAE,MAAM;GAAU,QAAQ;EAAS;EAG5C,IAAI,WAAW,iBACb,OAAO;GAAE,MAAM;GAAU,iBAAiB;EAAS;EAIrD,OAAO,CAAC;CACV;AACF"}
+{"version":3,"file":"file-validator.mjs","names":[],"sources":["../../../../../../../../core/src/validation/validators/file-validator.ts"],"sourcesContent":["import type { FileSizeOption, JsonSchemaResult, JsonSchemaTarget } from \"@warlock.js/seal\";\nimport {\n  BaseValidator,\n  maxFileSizeRule,\n  maxHeightRule,\n  maxWidthRule,\n  minFileSizeRule,\n  minHeightRule,\n  minWidthRule,\n  resolveFileSize,\n  v,\n} from \"@warlock.js/seal\";\nimport { UploadedFile } from \"../../http\";\nimport { fileExtensionRule, fileRule, fileTypeRule, imageRule } from \"../file\";\n\nexport const uploadedFileMetadataSchema = v.object({\n  location: v.string().oneOf([\"local\", \"cloud\"]),\n  width: v.int().positive(),\n  height: v.int().positive(),\n  size: v.int().positive(),\n  mimeType: v.string(),\n  extension: v.string(),\n  name: v.string(),\n});\n\n/**\n * File validator class\n */\nexport class FileValidator extends BaseValidator {\n  public constructor(errorMessage?: string) {\n    super();\n    this.addMutableRule(fileRule, errorMessage);\n  }\n\n  /**\n   * Check if value is a File type\n   */\n  public matchesType(value: any): boolean {\n    return value instanceof UploadedFile;\n  }\n\n  /** Value must be an image */\n  public image(errorMessage?: string): FileValidator {\n    return this.addRule(imageRule, errorMessage);\n  }\n\n  /** Accept specific file extensions */\n  public accept(extensions: string | string[], errorMessage?: string): FileValidator {\n    return this.addRule(fileExtensionRule, errorMessage, {\n      extensions,\n    });\n  }\n\n  /** Allow specific MIME types */\n  public mimeType(mimeTypes: string | string[], errorMessage?: string): FileValidator {\n    return this.addRule(fileTypeRule, errorMessage, {\n      mimeTypes,\n    });\n  }\n\n  /** Allow only pdf files */\n  public pdf(errorMessage?: string): FileValidator {\n    return this.mimeType(\"application/pdf\", errorMessage);\n  }\n\n  /** Allow only excel files */\n  public excel(errorMessage?: string): FileValidator {\n    return this.mimeType(\n      [\n        \"application/vnd.ms-excel\",\n        \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n      ],\n      errorMessage,\n    );\n  }\n\n  /** Allow only word files */\n  public word(errorMessage?: string): FileValidator {\n    return this.mimeType(\n      [\n        \"application/msword\",\n        \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      ],\n      errorMessage,\n    );\n  }\n\n  /** Minimum file size */\n  public minSize(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.addRule(minFileSizeRule, errorMessage, {\n      minSize: resolveFileSize(size),\n    });\n  }\n\n  /** @alias minSize */\n  public min(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.minSize(size, errorMessage);\n  }\n\n  /** Maximum file size */\n  public maxSize(size: number | FileSizeOption, errorMessage?: string): FileValidator {\n    return this.addRule(maxFileSizeRule, errorMessage, {\n      maxSize: resolveFileSize(size),\n    });\n  }\n\n  /** @alias maxSize */\n  public max(size: number, errorMessage?: string): FileValidator {\n    return this.maxSize(size, errorMessage);\n  }\n\n  /** Minimum image width */\n  public minWidth(width: number, errorMessage?: string): FileValidator {\n    return this.addRule(minWidthRule, errorMessage, {\n      minWidth: width,\n    });\n  }\n\n  /** Maximum image width */\n  public maxWidth(width: number, errorMessage?: string): FileValidator {\n    return this.addRule(maxWidthRule, errorMessage, {\n      maxWidth: width,\n    });\n  }\n\n  /** Minimum image height */\n  public minHeight(height: number, errorMessage?: string): FileValidator {\n    return this.addRule(minHeightRule, errorMessage, {\n      minHeight: height,\n    });\n  }\n\n  /** Maximum image height */\n  public maxHeight(height: number, errorMessage?: string): FileValidator {\n    return this.addRule(maxHeightRule, errorMessage, {\n      maxHeight: height,\n    });\n  }\n\n  /**\n   * Save the file and return it as a string\n   */\n  public saveTo(relativeDirectory: string): FileValidator {\n    return this.addTransformer(async (file: UploadedFile) => {\n      const output = await file.save(relativeDirectory);\n\n      return output.path;\n    });\n  }\n\n  /**\n   * @inheritdoc\n   *\n   * File uploads are not natively representable in JSON Schema.\n   * The output varies by target:\n   * - `openapi-3.0`   → `{ type: \"string\", format: \"binary\" }` (standard for multipart/form-data uploads)\n   * - `draft-2020-12` → `{ type: \"string\", contentEncoding: \"binary\" }`\n   * - `draft-07`      → `{}` (no standard binary representation — permissive fallback)\n   *\n   * @example\n   * ```ts\n   * v.file().toJsonSchema(\"openapi-3.0\")\n   * // → { type: \"string\", format: \"binary\" }\n   * ```\n   */\n  public override toJsonSchema(target: JsonSchemaTarget = \"draft-2020-12\"): JsonSchemaResult {\n    if (target === \"openapi-3.0\") {\n      return { type: \"string\", format: \"binary\" };\n    }\n\n    if (target === \"draft-2020-12\") {\n      return { type: \"string\", contentEncoding: \"binary\" };\n    }\n\n    // draft-07: no standard binary representation\n    return {};\n  }\n}\n"],"mappings":";;;;;;;AAeA,MAAa,6BAA6B,EAAE,OAAO;CACjD,UAAU,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,SAAS,OAAO,CAAC;CAC7C,OAAO,EAAE,IAAI,CAAC,CAAC,SAAS;CACxB,QAAQ,EAAE,IAAI,CAAC,CAAC,SAAS;CACzB,MAAM,EAAE,IAAI,CAAC,CAAC,SAAS;CACvB,UAAU,EAAE,OAAO;CACnB,WAAW,EAAE,OAAO;CACpB,MAAM,EAAE,OAAO;AACjB,CAAC;;;;AAKD,IAAa,gBAAb,cAAmC,cAAc;CAC/C,AAAO,YAAY,cAAuB;EACxC,MAAM;EACN,KAAK,eAAe,UAAU,YAAY;CAC5C;;;;CAKA,AAAO,YAAY,OAAqB;EACtC,OAAO,iBAAiB;CAC1B;;CAGA,AAAO,MAAM,cAAsC;EACjD,OAAO,KAAK,QAAQ,WAAW,YAAY;CAC7C;;CAGA,AAAO,OAAO,YAA+B,cAAsC;EACjF,OAAO,KAAK,QAAQ,mBAAmB,cAAc,EACnD,WACF,CAAC;CACH;;CAGA,AAAO,SAAS,WAA8B,cAAsC;EAClF,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UACF,CAAC;CACH;;CAGA,AAAO,IAAI,cAAsC;EAC/C,OAAO,KAAK,SAAS,mBAAmB,YAAY;CACtD;;CAGA,AAAO,MAAM,cAAsC;EACjD,OAAO,KAAK,SACV,CACE,4BACA,mEACF,GACA,YACF;CACF;;CAGA,AAAO,KAAK,cAAsC;EAChD,OAAO,KAAK,SACV,CACE,sBACA,yEACF,GACA,YACF;CACF;;CAGA,AAAO,QAAQ,MAA+B,cAAsC;EAClF,OAAO,KAAK,QAAQ,iBAAiB,cAAc,EACjD,SAAS,gBAAgB,IAAI,EAC/B,CAAC;CACH;;CAGA,AAAO,IAAI,MAA+B,cAAsC;EAC9E,OAAO,KAAK,QAAQ,MAAM,YAAY;CACxC;;CAGA,AAAO,QAAQ,MAA+B,cAAsC;EAClF,OAAO,KAAK,QAAQ,iBAAiB,cAAc,EACjD,SAAS,gBAAgB,IAAI,EAC/B,CAAC;CACH;;CAGA,AAAO,IAAI,MAAc,cAAsC;EAC7D,OAAO,KAAK,QAAQ,MAAM,YAAY;CACxC;;CAGA,AAAO,SAAS,OAAe,cAAsC;EACnE,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UAAU,MACZ,CAAC;CACH;;CAGA,AAAO,SAAS,OAAe,cAAsC;EACnE,OAAO,KAAK,QAAQ,cAAc,cAAc,EAC9C,UAAU,MACZ,CAAC;CACH;;CAGA,AAAO,UAAU,QAAgB,cAAsC;EACrE,OAAO,KAAK,QAAQ,eAAe,cAAc,EAC/C,WAAW,OACb,CAAC;CACH;;CAGA,AAAO,UAAU,QAAgB,cAAsC;EACrE,OAAO,KAAK,QAAQ,eAAe,cAAc,EAC/C,WAAW,OACb,CAAC;CACH;;;;CAKA,AAAO,OAAO,mBAA0C;EACtD,OAAO,KAAK,eAAe,OAAO,SAAuB;GAGvD,QAAO,MAFc,KAAK,KAAK,iBAAiB,EAEnC,CAAC;EAChB,CAAC;CACH;;;;;;;;;;;;;;;;CAiBA,AAAgB,aAAa,SAA2B,iBAAmC;EACzF,IAAI,WAAW,eACb,OAAO;GAAE,MAAM;GAAU,QAAQ;EAAS;EAG5C,IAAI,WAAW,iBACb,OAAO;GAAE,MAAM;GAAU,iBAAiB;EAAS;EAIrD,OAAO,CAAC;CACV;AACF"}

package/esm/vite/lower-stage3-decorators.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"lower-stage3-decorators.d.mts","names":[],"sources":["../../../../../../../core/src/vite/lower-stage3-decorators.ts"],"mappings":";;AASA;;;;;;UAAiB,uBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,CAAU,IAAA,UAAc,EAAA,WAAa,OAAO;IAAG,IAAA;IAAc,GAAA;EAAA;AAAA;AAoC/D;;;;AAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAhE,iBAAgB,qBAAA,CAAA,GAAyB,uBAAuB"}
+{"version":3,"file":"lower-stage3-decorators.d.mts","names":[],"sources":["../../../../../../../core/src/vite/lower-stage3-decorators.ts"],"mappings":";;AASA;;;;;;UAAiB,uBAAA;EACf,IAAA;EACA,OAAA;EACA,SAAA,CAAU,IAAA,UAAc,EAAA,WAAa,OAAO;IAAG,IAAA;IAAc,GAAA;EAAA;AAAA;AAoC/D;;;;AAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAhE,iBAAgB,qBAAA,IAAyB,uBAAuB"}

package/esm/warlock-config/warlock-config.manager.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"warlock-config.manager.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/warlock-config.manager.ts"],"mappings":";;;;;AAeA;;;;AAAwD;AAaxD;iBAbgB,yBAAA,CAA0B,KAAc;;;;;;;cAa3C,oBAAA;EAyHR;;;EAAA,QArHK,MAAA;EAyIS;;;EAAA,QApIT,OAAA;EAqIL;;;;;EA9HU,IAAA,CAAA,GAAQ,OAAA,CAAQ,aAAA;EAPrB;;;;;;EAAA,QAgCM,MAAA;EA6EH;;;;;;;;EAAA,QAtCG,cAAA;EA2DR;;;;;;;;;;;EArBC,GAAA,mBAAsB,aAAA,CAAA,CAC3B,GAAA,EAAK,GAAA,EACL,YAAA,GAAe,aAAA,CAAc,GAAA,IAC5B,aAAA,CAAc,GAAA;EAsCV;;;;;AAWuB;AAoBhC;;;;EAnDQ,OAAA,mBAA0B,aAAA,CAAA,CAC9B,GAAA,EAAK,GAAA,EACL,YAAA,GAAe,aAAA,CAAc,GAAA,IAC5B,OAAA,CAAQ,aAAA,CAAc,GAAA;;;;MAQd,QAAA,CAAA;;;;;;EASJ,MAAA,CAAA,GAAU,aAAA;;;;EAWJ,MAAA,CAAA,GAAU,OAAA;AAAA;;;;;;;;;;;;;;cAoBZ,oBAAA,EAAoB,oBAA6B"}
+{"version":3,"file":"warlock-config.manager.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/warlock-config.manager.ts"],"mappings":";;;;;AAeA;;;;AAAwD;AAaxD;iBAbgB,yBAAA,CAA0B,KAAc;;;;;;;cAa3C,oBAAA;EAyHR;;;EAAA,QArHK,MAAA;EAyIS;;;EAAA,QApIT,OAAA;EAqIL;;;;;EA9HU,IAAA,IAAQ,OAAA,CAAQ,aAAA;EAPrB;;;;;;EAAA,QAgCM,MAAA;EA6EH;;;;;;;;EAAA,QAtCG,cAAA;EA2DR;;;;;;;;;;;EArBC,GAAA,mBAAsB,aAAA,EAC3B,GAAA,EAAK,GAAA,EACL,YAAA,GAAe,aAAA,CAAc,GAAA,IAC5B,aAAA,CAAc,GAAA;EAsCV;;;;;AAWuB;AAoBhC;;;;EAnDQ,OAAA,mBAA0B,aAAA,EAC9B,GAAA,EAAK,GAAA,EACL,YAAA,GAAe,aAAA,CAAc,GAAA,IAC5B,OAAA,CAAQ,aAAA,CAAc,GAAA;;;;MAQd,QAAA;;;;;;EASJ,MAAA,IAAU,aAAA;;;;EAWJ,MAAA,IAAU,OAAA;AAAA;;;;;;;;;;;;;;cAoBZ,oBAAA,EAAoB,oBAA6B"}

package/esm/warlock-config/warlock-config.manager.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"warlock-config.manager.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/warlock-config.manager.ts"],"sourcesContent":["import { fileExistsAsync } from \"@warlock.js/fs\";\r\nimport { get } from \"@mongez/reinforcements\";\r\nimport { readFile, unlink, writeFile } from \"node:fs/promises\";\r\nimport { pathToFileURL } from \"url\";\r\nimport { rootPath } from \"../utils\";\r\nimport { type WarlockConfig } from \"./types\";\r\n\r\n/**\r\n * True when `error` is Node's \"this runtime can't import a `.ts` file\" error.\r\n *\r\n * Node only executes TypeScript natively from v22.18 / v23.6 onward (earlier\r\n * 22.x needs `--experimental-strip-types`). On older runtimes a bare\r\n * `import(\"warlock.config.ts\")` throws `ERR_UNKNOWN_FILE_EXTENSION` — which is\r\n * the signal to fall back to transpiling the config ourselves.\r\n */\r\nexport function isUnknownTsExtensionError(error: unknown): boolean {\r\n  return (\r\n    (error as { code?: string })?.code === \"ERR_UNKNOWN_FILE_EXTENSION\" ||\r\n    /Unknown file extension \"\\.tsx?\"/.test(String((error as Error)?.message))\r\n  );\r\n}\r\n\r\n/**\r\n * Warlock Config Manager\r\n *\r\n * Manages lazy loading of the pre-compiled warlock.config.js file\r\n * from the .warlock/cache directory.\r\n */\r\nexport class WarlockConfigManager {\r\n  /**\r\n   * Cached config instance\r\n   */\r\n  private config?: WarlockConfig;\r\n\r\n  /**\r\n   * Loading promise to prevent duplicate loads\r\n   */\r\n  private loading?: Promise<WarlockConfig | undefined>;\r\n\r\n  /**\r\n   * Load warlock.config.js (cached after first load)\r\n   *\r\n   * @returns The resolved Warlock configuration\r\n   */\r\n  public async load(): Promise<WarlockConfig | undefined> {\r\n    // Already loaded\r\n    if (this.config) {\r\n      return this.config;\r\n    }\r\n\r\n    // Currently loading (prevent duplicate loads)\r\n    if (this.loading) {\r\n      return this.loading;\r\n    }\r\n\r\n    // Start loading\r\n    this.loading = this.doLoad();\r\n    this.config = await this.loading;\r\n    this.loading = undefined;\r\n\r\n    return this.config;\r\n  }\r\n\r\n  /**\r\n   * Internal load implementation\r\n   *\r\n   * The ESM loader hook transpiles `warlock.config.ts` on import — no\r\n   * separate compile-to-disk step is needed.\r\n   */\r\n  private async doLoad(): Promise<WarlockConfig | undefined> {\r\n    const configPath = rootPath(\"warlock.config.ts\");\r\n\r\n    if (!(await fileExistsAsync(configPath))) {\r\n      // Written straight to the console, NOT through `@warlock.js/logger`.\r\n      // This runs during CLI bootstrap, before `LoggerConnector.start()` has\r\n      // configured a single channel, so a logger call here reaches nobody in\r\n      // any application — the warning would be silently dropped exactly when\r\n      // the user most needs it.\r\n      console.warn(\"warlock.config.ts is missing — run `warlock init` to create it\");\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const configModule = await import(pathToFileURL(configPath).href);\r\n      return configModule.default;\r\n    } catch (error) {\r\n      // `dev` registers a TS loader hook, and Node ≥ 22.18 / 23.6 strips types\r\n      // natively — in both cases the direct import above works. But `build` /\r\n      // `start` register no hook, so on an older Node the import throws\r\n      // ERR_UNKNOWN_FILE_EXTENSION. Transpile the config with esbuild ourselves\r\n      // so config loading is Node-version-independent rather than relying on an\r\n      // experimental runtime feature.\r\n      if (isUnknownTsExtensionError(error)) {\r\n        return await this.loadViaEsbuild(configPath);\r\n      }\r\n\r\n      throw new Error(`Failed to load warlock.config.ts: ${error}`);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Fallback config loader for runtimes without native TypeScript support.\r\n   *\r\n   * Transpiles `warlock.config.ts` with esbuild (already a core dependency),\r\n   * writes the result as a sibling `.mjs` — so the config's own imports (bare\r\n   * `@warlock.js/*` and any relative paths) resolve exactly as they would from\r\n   * the original location — imports it, then removes the temp file.\r\n   */\r\n  private async loadViaEsbuild(configPath: string): Promise<WarlockConfig | undefined> {\r\n    const { transformSync } = await import(\"esbuild\");\r\n    const source = await readFile(configPath, \"utf8\");\r\n\r\n    const { code } = transformSync(source, {\r\n      loader: \"ts\",\r\n      format: \"esm\",\r\n      target: `node${process.versions.node.split(\".\")[0]}`,\r\n      sourcefile: configPath,\r\n    });\r\n\r\n    // Unique sibling name so concurrent processes never clobber each other.\r\n    const compiledPath = configPath.replace(\r\n      /warlock\\.config\\.ts$/,\r\n      `.warlock.config.${process.pid}.mjs`,\r\n    );\r\n\r\n    await writeFile(compiledPath, code, \"utf8\");\r\n\r\n    try {\r\n      const configModule = await import(pathToFileURL(compiledPath).href);\r\n      return configModule.default;\r\n    } finally {\r\n      await unlink(compiledPath).catch(() => {});\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get config value by key (dot notation supported)\r\n   *\r\n   * @example\r\n   * config.get(\"server.port\") // Returns 3000\r\n   * config.get(\"cli.commands\") // Returns array of commands\r\n   *\r\n   * @param key - Config key (supports dot notation), autocompletes for first level only\r\n   * @returns The config value\r\n   * @throws Error if config is not loaded\r\n   */\r\n  public get<Key extends keyof WarlockConfig>(\r\n    key: Key,\r\n    defaultValue?: WarlockConfig[Key],\r\n  ): WarlockConfig[Key] {\r\n    if (!this.config) {\r\n      throw new Error(\"WarlockConfig not loaded. Call load() first or use lazyGet().\");\r\n    }\r\n\r\n    return get(this.config, key as string, defaultValue);\r\n  }\r\n\r\n  /**\r\n   * Lazy get - loads config if not already loaded\r\n   *\r\n   * @example\r\n   * const port = await config.lazyGet(\"server\");\r\n   *\r\n   * @param key - Config key (supports dot notation), autocompletes for first level only\r\n   * @param defaultValue - Default value if config key is undefined\r\n   * @returns The config value\r\n   */\r\n  async lazyGet<Key extends keyof WarlockConfig>(\r\n    key: Key,\r\n    defaultValue?: WarlockConfig[Key],\r\n  ): Promise<WarlockConfig[Key]> {\r\n    await this.load();\r\n    return this.get(key, defaultValue);\r\n  }\r\n\r\n  /**\r\n   * Check if config is loaded\r\n   */\r\n  public get isLoaded(): boolean {\r\n    return this.config !== undefined;\r\n  }\r\n\r\n  /**\r\n   * Get the entire config object\r\n   *\r\n   * @throws Error if config is not loaded\r\n   */\r\n  public getAll(): WarlockConfig {\r\n    if (!this.config) {\r\n      throw new Error(\"WarlockConfig not loaded. Call load() first or use lazyGet().\");\r\n    }\r\n\r\n    return this.config;\r\n  }\r\n\r\n  /**\r\n   * Reload config (useful for HMR/development)\r\n   */\r\n  public async reload(): Promise<void> {\r\n    this.config = undefined;\r\n    this.loading = undefined;\r\n    await this.load();\r\n  }\r\n}\r\n\r\n/**\r\n * Exported singleton instance\r\n *\r\n * @example\r\n * import { warlockConfig } from \"@warlock.js/core\";\r\n *\r\n * // Lazy load and get value\r\n * const port = await warlockConfig.lazyGet(\"server.port\");\r\n *\r\n * // Or load first, then get\r\n * await warlockConfig.load();\r\n * const commands = warlockConfig.get(\"cli.commands\");\r\n */\r\nexport const warlockConfigManager = new WarlockConfigManager();\r\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,SAAgB,0BAA0B,OAAyB;CACjE,OACG,OAA6B,SAAS,gCACvC,kCAAkC,KAAK,OAAQ,OAAiB,OAAO,CAAC;AAE5E;;;;;;;AAQA,IAAa,uBAAb,MAAkC;;;;;;CAgBhC,MAAa,OAA2C;EAEtD,IAAI,KAAK,QACP,OAAO,KAAK;EAId,IAAI,KAAK,SACP,OAAO,KAAK;EAId,KAAK,UAAU,KAAK,OAAO;EAC3B,KAAK,SAAS,MAAM,KAAK;EACzB,KAAK,UAAU;EAEf,OAAO,KAAK;CACd;;;;;;;CAQA,MAAc,SAA6C;EACzD,MAAM,aAAa,SAAS,mBAAmB;EAE/C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;GAMxC,QAAQ,KAAK,gEAAgE;GAC7E;EACF;EAEA,IAAI;GAEF,QAAO,MADoB,OAAO,cAAc,UAAU,EAAE,OACxC;EACtB,SAAS,OAAO;GAOd,IAAI,0BAA0B,KAAK,GACjC,OAAO,MAAM,KAAK,eAAe,UAAU;GAG7C,MAAM,IAAI,MAAM,qCAAqC,OAAO;EAC9D;CACF;;;;;;;;;CAUA,MAAc,eAAe,YAAwD;EACnF,MAAM,EAAE,kBAAkB,MAAM,OAAO;EAGvC,MAAM,EAAE,SAAS,cAAc,MAFV,SAAS,YAAY,MAAM,GAET;GACrC,QAAQ;GACR,QAAQ;GACR,QAAQ,OAAO,QAAQ,SAAS,KAAK,MAAM,GAAG,EAAE;GAChD,YAAY;EACd,CAAC;EAGD,MAAM,eAAe,WAAW,QAC9B,wBACA,mBAAmB,QAAQ,IAAI,KACjC;EAEA,MAAM,UAAU,cAAc,MAAM,MAAM;EAE1C,IAAI;GAEF,QAAO,MADoB,OAAO,cAAc,YAAY,EAAE,OAC1C;EACtB,UAAU;GACR,MAAM,OAAO,YAAY,EAAE,YAAY,CAAC,CAAC;EAC3C;CACF;;;;;;;;;;;;CAaA,AAAO,IACL,KACA,cACoB;EACpB,IAAI,CAAC,KAAK,QACR,MAAM,IAAI,MAAM,+DAA+D;EAGjF,OAAO,IAAI,KAAK,QAAQ,KAAe,YAAY;CACrD;;;;;;;;;;;CAYA,MAAM,QACJ,KACA,cAC6B;EAC7B,MAAM,KAAK,KAAK;EAChB,OAAO,KAAK,IAAI,KAAK,YAAY;CACnC;;;;CAKA,IAAW,WAAoB;EAC7B,OAAO,KAAK,WAAW;CACzB;;;;;;CAOA,AAAO,SAAwB;EAC7B,IAAI,CAAC,KAAK,QACR,MAAM,IAAI,MAAM,+DAA+D;EAGjF,OAAO,KAAK;CACd;;;;CAKA,MAAa,SAAwB;EACnC,KAAK,SAAS;EACd,KAAK,UAAU;EACf,MAAM,KAAK,KAAK;CAClB;AACF;;;;;;;;;;;;;;AAeA,MAAa,uBAAuB,IAAI,qBAAqB"}
+{"version":3,"file":"warlock-config.manager.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/warlock-config.manager.ts"],"sourcesContent":["import { fileExistsAsync } from \"@warlock.js/fs\";\r\nimport { get } from \"@mongez/reinforcements\";\r\nimport { readFile, unlink, writeFile } from \"node:fs/promises\";\r\nimport { pathToFileURL } from \"url\";\r\nimport { rootPath } from \"../utils\";\r\nimport { type WarlockConfig } from \"./types\";\r\n\r\n/**\r\n * True when `error` is Node's \"this runtime can't import a `.ts` file\" error.\r\n *\r\n * Node only executes TypeScript natively from v22.18 / v23.6 onward (earlier\r\n * 22.x needs `--experimental-strip-types`). On older runtimes a bare\r\n * `import(\"warlock.config.ts\")` throws `ERR_UNKNOWN_FILE_EXTENSION` — which is\r\n * the signal to fall back to transpiling the config ourselves.\r\n */\r\nexport function isUnknownTsExtensionError(error: unknown): boolean {\r\n  return (\r\n    (error as { code?: string })?.code === \"ERR_UNKNOWN_FILE_EXTENSION\" ||\r\n    /Unknown file extension \"\\.tsx?\"/.test(String((error as Error)?.message))\r\n  );\r\n}\r\n\r\n/**\r\n * Warlock Config Manager\r\n *\r\n * Manages lazy loading of the pre-compiled warlock.config.js file\r\n * from the .warlock/cache directory.\r\n */\r\nexport class WarlockConfigManager {\r\n  /**\r\n   * Cached config instance\r\n   */\r\n  private config?: WarlockConfig;\r\n\r\n  /**\r\n   * Loading promise to prevent duplicate loads\r\n   */\r\n  private loading?: Promise<WarlockConfig | undefined>;\r\n\r\n  /**\r\n   * Load warlock.config.js (cached after first load)\r\n   *\r\n   * @returns The resolved Warlock configuration\r\n   */\r\n  public async load(): Promise<WarlockConfig | undefined> {\r\n    // Already loaded\r\n    if (this.config) {\r\n      return this.config;\r\n    }\r\n\r\n    // Currently loading (prevent duplicate loads)\r\n    if (this.loading) {\r\n      return this.loading;\r\n    }\r\n\r\n    // Start loading\r\n    this.loading = this.doLoad();\r\n    this.config = await this.loading;\r\n    this.loading = undefined;\r\n\r\n    return this.config;\r\n  }\r\n\r\n  /**\r\n   * Internal load implementation\r\n   *\r\n   * The ESM loader hook transpiles `warlock.config.ts` on import — no\r\n   * separate compile-to-disk step is needed.\r\n   */\r\n  private async doLoad(): Promise<WarlockConfig | undefined> {\r\n    const configPath = rootPath(\"warlock.config.ts\");\r\n\r\n    if (!(await fileExistsAsync(configPath))) {\r\n      // Written straight to the console, NOT through `@warlock.js/logger`.\r\n      // This runs during CLI bootstrap, before `LoggerConnector.start()` has\r\n      // configured a single channel, so a logger call here reaches nobody in\r\n      // any application — the warning would be silently dropped exactly when\r\n      // the user most needs it.\r\n      console.warn(\"warlock.config.ts is missing — run `warlock init` to create it\");\r\n      return;\r\n    }\r\n\r\n    try {\r\n      const configModule = await import(pathToFileURL(configPath).href);\r\n      return configModule.default;\r\n    } catch (error) {\r\n      // `dev` registers a TS loader hook, and Node ≥ 22.18 / 23.6 strips types\r\n      // natively — in both cases the direct import above works. But `build` /\r\n      // `start` register no hook, so on an older Node the import throws\r\n      // ERR_UNKNOWN_FILE_EXTENSION. Transpile the config with esbuild ourselves\r\n      // so config loading is Node-version-independent rather than relying on an\r\n      // experimental runtime feature.\r\n      if (isUnknownTsExtensionError(error)) {\r\n        return await this.loadViaEsbuild(configPath);\r\n      }\r\n\r\n      throw new Error(`Failed to load warlock.config.ts: ${error}`);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Fallback config loader for runtimes without native TypeScript support.\r\n   *\r\n   * Transpiles `warlock.config.ts` with esbuild (already a core dependency),\r\n   * writes the result as a sibling `.mjs` — so the config's own imports (bare\r\n   * `@warlock.js/*` and any relative paths) resolve exactly as they would from\r\n   * the original location — imports it, then removes the temp file.\r\n   */\r\n  private async loadViaEsbuild(configPath: string): Promise<WarlockConfig | undefined> {\r\n    const { transformSync } = await import(\"esbuild\");\r\n    const source = await readFile(configPath, \"utf8\");\r\n\r\n    const { code } = transformSync(source, {\r\n      loader: \"ts\",\r\n      format: \"esm\",\r\n      target: `node${process.versions.node.split(\".\")[0]}`,\r\n      sourcefile: configPath,\r\n    });\r\n\r\n    // Unique sibling name so concurrent processes never clobber each other.\r\n    const compiledPath = configPath.replace(\r\n      /warlock\\.config\\.ts$/,\r\n      `.warlock.config.${process.pid}.mjs`,\r\n    );\r\n\r\n    await writeFile(compiledPath, code, \"utf8\");\r\n\r\n    try {\r\n      const configModule = await import(pathToFileURL(compiledPath).href);\r\n      return configModule.default;\r\n    } finally {\r\n      await unlink(compiledPath).catch(() => {});\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get config value by key (dot notation supported)\r\n   *\r\n   * @example\r\n   * config.get(\"server.port\") // Returns 3000\r\n   * config.get(\"cli.commands\") // Returns array of commands\r\n   *\r\n   * @param key - Config key (supports dot notation), autocompletes for first level only\r\n   * @returns The config value\r\n   * @throws Error if config is not loaded\r\n   */\r\n  public get<Key extends keyof WarlockConfig>(\r\n    key: Key,\r\n    defaultValue?: WarlockConfig[Key],\r\n  ): WarlockConfig[Key] {\r\n    if (!this.config) {\r\n      throw new Error(\"WarlockConfig not loaded. Call load() first or use lazyGet().\");\r\n    }\r\n\r\n    return get(this.config, key as string, defaultValue);\r\n  }\r\n\r\n  /**\r\n   * Lazy get - loads config if not already loaded\r\n   *\r\n   * @example\r\n   * const port = await config.lazyGet(\"server\");\r\n   *\r\n   * @param key - Config key (supports dot notation), autocompletes for first level only\r\n   * @param defaultValue - Default value if config key is undefined\r\n   * @returns The config value\r\n   */\r\n  async lazyGet<Key extends keyof WarlockConfig>(\r\n    key: Key,\r\n    defaultValue?: WarlockConfig[Key],\r\n  ): Promise<WarlockConfig[Key]> {\r\n    await this.load();\r\n    return this.get(key, defaultValue);\r\n  }\r\n\r\n  /**\r\n   * Check if config is loaded\r\n   */\r\n  public get isLoaded(): boolean {\r\n    return this.config !== undefined;\r\n  }\r\n\r\n  /**\r\n   * Get the entire config object\r\n   *\r\n   * @throws Error if config is not loaded\r\n   */\r\n  public getAll(): WarlockConfig {\r\n    if (!this.config) {\r\n      throw new Error(\"WarlockConfig not loaded. Call load() first or use lazyGet().\");\r\n    }\r\n\r\n    return this.config;\r\n  }\r\n\r\n  /**\r\n   * Reload config (useful for HMR/development)\r\n   */\r\n  public async reload(): Promise<void> {\r\n    this.config = undefined;\r\n    this.loading = undefined;\r\n    await this.load();\r\n  }\r\n}\r\n\r\n/**\r\n * Exported singleton instance\r\n *\r\n * @example\r\n * import { warlockConfig } from \"@warlock.js/core\";\r\n *\r\n * // Lazy load and get value\r\n * const port = await warlockConfig.lazyGet(\"server.port\");\r\n *\r\n * // Or load first, then get\r\n * await warlockConfig.load();\r\n * const commands = warlockConfig.get(\"cli.commands\");\r\n */\r\nexport const warlockConfigManager = new WarlockConfigManager();\r\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,SAAgB,0BAA0B,OAAyB;CACjE,OACG,OAA6B,SAAS,gCACvC,kCAAkC,KAAK,OAAQ,OAAiB,OAAO,CAAC;AAE5E;;;;;;;AAQA,IAAa,uBAAb,MAAkC;;;;;;CAgBhC,MAAa,OAA2C;EAEtD,IAAI,KAAK,QACP,OAAO,KAAK;EAId,IAAI,KAAK,SACP,OAAO,KAAK;EAId,KAAK,UAAU,KAAK,OAAO;EAC3B,KAAK,SAAS,MAAM,KAAK;EACzB,KAAK,UAAU;EAEf,OAAO,KAAK;CACd;;;;;;;CAQA,MAAc,SAA6C;EACzD,MAAM,aAAa,SAAS,mBAAmB;EAE/C,IAAI,CAAE,MAAM,gBAAgB,UAAU,GAAI;GAMxC,QAAQ,KAAK,gEAAgE;GAC7E;EACF;EAEA,IAAI;GAEF,QAAO,MADoB,OAAO,cAAc,UAAU,CAAC,CAAC,MACzC,CAAC;EACtB,SAAS,OAAO;GAOd,IAAI,0BAA0B,KAAK,GACjC,OAAO,MAAM,KAAK,eAAe,UAAU;GAG7C,MAAM,IAAI,MAAM,qCAAqC,OAAO;EAC9D;CACF;;;;;;;;;CAUA,MAAc,eAAe,YAAwD;EACnF,MAAM,EAAE,kBAAkB,MAAM,OAAO;EAGvC,MAAM,EAAE,SAAS,cAAc,MAFV,SAAS,YAAY,MAAM,GAET;GACrC,QAAQ;GACR,QAAQ;GACR,QAAQ,OAAO,QAAQ,SAAS,KAAK,MAAM,GAAG,CAAC,CAAC;GAChD,YAAY;EACd,CAAC;EAGD,MAAM,eAAe,WAAW,QAC9B,wBACA,mBAAmB,QAAQ,IAAI,KACjC;EAEA,MAAM,UAAU,cAAc,MAAM,MAAM;EAE1C,IAAI;GAEF,QAAO,MADoB,OAAO,cAAc,YAAY,CAAC,CAAC,MAC3C,CAAC;EACtB,UAAU;GACR,MAAM,OAAO,YAAY,CAAC,CAAC,YAAY,CAAC,CAAC;EAC3C;CACF;;;;;;;;;;;;CAaA,AAAO,IACL,KACA,cACoB;EACpB,IAAI,CAAC,KAAK,QACR,MAAM,IAAI,MAAM,+DAA+D;EAGjF,OAAO,IAAI,KAAK,QAAQ,KAAe,YAAY;CACrD;;;;;;;;;;;CAYA,MAAM,QACJ,KACA,cAC6B;EAC7B,MAAM,KAAK,KAAK;EAChB,OAAO,KAAK,IAAI,KAAK,YAAY;CACnC;;;;CAKA,IAAW,WAAoB;EAC7B,OAAO,KAAK,WAAW;CACzB;;;;;;CAOA,AAAO,SAAwB;EAC7B,IAAI,CAAC,KAAK,QACR,MAAM,IAAI,MAAM,+DAA+D;EAGjF,OAAO,KAAK;CACd;;;;CAKA,MAAa,SAAwB;EACnC,KAAK,SAAS;EACd,KAAK,UAAU;EACf,MAAM,KAAK,KAAK;CAClB;AACF;;;;;;;;;;;;;;AAeA,MAAa,uBAAuB,IAAI,qBAAqB"}

package/llms-full.txt

@@ -1222,7 +1222,7 @@ A controller is a thin function: pull inputs from `request`, call work, return t
 ```ts title="src/app/<module>/controllers/<action>.controller.ts"
 import { type RequestHandler } from "@warlock.js/core";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   return response.success({ products: [] });
 };
 ```
@@ -1277,10 +1277,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -1306,10 +1306,10 @@ Routes behind `authMiddleware` need `request.user` typed. Project conventions ad
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   // request.user is typed
   const product = await createProductService(request.validated());
   return response.successCreate({ product });
@@ -1356,7 +1356,7 @@ If your controller is over ~30 lines, the work probably belongs in a service.
 import { type RequestHandler } from "@warlock.js/core";
 import { listProductsService } from "../services/list-products.service";
 
-export const listProductsController: RequestHandler = async (request, response) => {
+export const listProductsController: RequestHandler = async ({ request, response }) => {
   const { data: products, pagination } = await listProductsService({
     ...request.all(),
     organization_id: request.user.organizationId,
@@ -1373,10 +1373,10 @@ import { type Request, type RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -1410,7 +1410,7 @@ export async function getProductService(id: string) {
 import type { RequestHandler } from "@warlock.js/core";
 import { getProductService } from "../services/get-product.service";
 
-export const getProductController: RequestHandler = async (request, response) => {
+export const getProductController: RequestHandler = async ({ request, response }) => {
   const product = await getProductService(request.input("id"));
 
   return response.success({ product });
@@ -4133,9 +4133,9 @@ description: 'Send HTTP responses via @warlock.js/core''s Response helpers — s
 ## The shape
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import type { RequestHandler } from "@warlock.js/core";
 
-export const myController: RequestHandler = async (request, response: Response) => {
+export const myController: RequestHandler = async ({ request, response }) => {
   // …choose a helper and return it
   return response.success({ data: "…" });
 };
@@ -4145,11 +4145,11 @@ Always `return response.<helper>(...)`. The return value drives Fastify's send.
 
 ## Success helpers
 
-| Method                              | Status | When                                      |
-| ----------------------------------- | ------ | ----------------------------------------- |
-| `response.success(data?)`           | 200    | normal read / update                      |
-| `response.successCreate(data)`      | 201    | resource created (POST)                   |
-| `response.noContent()`              | 204    | delete succeeded, no body needed          |
+| Method                         | Status | When                             |
+| ------------------------------ | ------ | -------------------------------- |
+| `response.success(data?)`      | 200    | normal read / update             |
+| `response.successCreate(data)` | 201    | resource created (POST)          |
+| `response.noContent()`         | 204    | delete succeeded, no body needed |
 
 ```ts
 return response.success({ products: [...] });
@@ -4163,13 +4163,13 @@ return response.noContent();
 
 ## Client-error helpers
 
-| Method                                              | Status | When                                  |
-| --------------------------------------------------- | ------ | ------------------------------------- |
-| `response.badRequest(data)`                         | 400    | malformed or invalid input            |
-| `response.unauthorized(data?)`                      | 401    | missing/invalid auth token            |
-| `response.forbidden(data?)`                         | 403    | authenticated but not allowed         |
-| `response.notFound(data?)`                          | 404    | record missing                        |
-| `response.conflict(data?)`                          | 409    | uniqueness violation, state conflict  |
+| Method                         | Status | When                                 |
+| ------------------------------ | ------ | ------------------------------------ |
+| `response.badRequest(data)`    | 400    | malformed or invalid input           |
+| `response.unauthorized(data?)` | 401    | missing/invalid auth token           |
+| `response.forbidden(data?)`    | 403    | authenticated but not allowed        |
+| `response.notFound(data?)`     | 404    | record missing                       |
+| `response.conflict(data?)`     | 409    | uniqueness violation, state conflict |
 
 ```ts
 return response.badRequest({ error: t("validation.invalid") });
@@ -4188,8 +4188,8 @@ Most error helpers accept an optional payload — if you omit it, they send a de
 ## Redirects
 
 ```ts
-return response.redirect("/login");                    // 302
-return response.redirect("/new-home", 301);            // permanent
+return response.redirect("/login"); // 302
+return response.redirect("/new-home", 301); // permanent
 ```
 
 ## Files
@@ -4221,19 +4221,19 @@ stream.end();
 
 ## Throwing HTTP errors
 
-Most of the time, controllers don't need to *choose* an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
+Most of the time, controllers don't need to _choose_ an error helper — they throw from the service layer instead. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. The error classes mirror the helpers above:
 
 ```ts
 import {
-  ResourceNotFoundError,   // 404
-  UnAuthorizedError,        // 401
-  ForbiddenError,           // 403
-  BadRequestError,          // 400
-  ConflictError,            // 409
-  NotAcceptableError,       // 406
-  NotAllowedError,          // 405
-  ServerError,              // 500
-  HttpError,                // base class — `new HttpError(status, message, payload?)` for arbitrary codes
+  ResourceNotFoundError, // 404
+  UnAuthorizedError, // 401
+  ForbiddenError, // 403
+  BadRequestError, // 400
+  ConflictError, // 409
+  NotAcceptableError, // 406
+  NotAllowedError, // 405
+  ServerError, // 500
+  HttpError, // base class — `new HttpError(status, message, payload?)` for arbitrary codes
 } from "@warlock.js/core";
 
 throw new ResourceNotFoundError("product.notFound");
@@ -4241,13 +4241,27 @@ throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
 ```
 
-Each class takes `(message, payload?)`. The payload merges into the response body alongside `error`. In development mode, the stack trace is included too.
+Each class takes `(message, payload?)`. The framework keeps the optional
+detail nested under `payload`:
+
+```json
+{
+  "error": "Product not found",
+  "payload": { "id": 42 }
+}
+```
+
+Every unhandled error response also carries
+`Cache-Control: private, no-store`, regardless of status. The floor is
+applied once at the shared error funnel, so API-route errors cannot be stored
+and replayed across users. In development mode, the stack trace is included
+too.
 
 Pick the class, throw from the service or use-case, and forget about response shaping at the call site. The controller stays focused on the success path:
 
 ```ts
-export const getProductController: RequestHandler = async (request, response) => {
-  const product = await getProductService(request.input("id"));   // throws ResourceNotFoundError on miss
+export const getProductController: RequestHandler = async ({ request, response }) => {
+  const product = await getProductService(request.input("id")); // throws ResourceNotFoundError on miss
   return response.success({ product });
 };
 ```
@@ -4259,9 +4273,9 @@ See [`create-controller`](../create-controller/SKILL.md) for the "throw from ser
 ```ts
 const sse = response.sse();
 
-sse.send("tick", { count: 1 });             // event name, data, optional id
-sse.send("tick", { count: 2 }, "msg-2");    // third arg is the SSE event id
-sse.comment("keep-alive");                  // invisible to the client, prevents timeout
+sse.send("tick", { count: 1 }); // event name, data, optional id
+sse.send("tick", { count: 2 }, "msg-2"); // third arg is the SSE event id
+sse.comment("keep-alive"); // invisible to the client, prevents timeout
 sse.end();
 ```
 
@@ -4301,11 +4315,11 @@ response.clearCookie("session_id");
 
 Every response cookie gets `httpOnly: true`, `sameSite: "lax"`, and `secure: true` outside development, unless you override them:
 
-| Flag | Default | Why it's the default |
-|---|---|---|
-| `httpOnly` | `true` | without it, any injected script can read the cookie |
-| `sameSite` | `"lax"` | without it, the cookie rides along on cross-site requests |
-| `secure` | `true`, except in development | without it, the cookie travels in cleartext |
+| Flag       | Default                       | Why it's the default                                      |
+| ---------- | ----------------------------- | --------------------------------------------------------- |
+| `httpOnly` | `true`                        | without it, any injected script can read the cookie       |
+| `sameSite` | `"lax"`                       | without it, the cookie rides along on cross-site requests |
+| `secure`   | `true`, except in development | without it, the cookie travels in cleartext               |
 
 `secure` is relaxed in development only — browsers drop a `Secure` cookie over plain http, which would silently break every local login. It stays on in test and staging.
 
@@ -4736,12 +4750,17 @@ Set `STORAGE_DRIVER=r2` in production, leave unset in dev — same code uses loc
 ### Uploading a request file
 
 ```ts
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { storage } from "@warlock.js/core";
 
-export const uploadAvatarController: RequestHandler = async (request, response: Response) => {
+export const uploadAvatarController: GuardedRequestHandler = async ({ request, response }) => {
   const upload = request.file("avatar");
-  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.fileName}`);
+
+  if (!upload) {
+    return response.badRequest({ error: "missing file" });
+  }
+
+  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.name}`);
 
   return response.successCreate({ url: file.url, hash: file.hash });
 };
@@ -5656,8 +5675,8 @@ Multipart uploads come in as `UploadedFile` instances. The class wraps Fastify's
 
 ## The shape
 
-```ts title="src/app/uploads/schema/index.ts"
-import { v } from "@warlock.js/seal";
+```ts title="src/app/uploads/schema/upload-avatar.schema.ts"
+import { v, type Infer } from "@warlock.js/seal";
 
 export const uploadAvatarSchema = v.object({
   avatar: v
@@ -5666,16 +5685,18 @@ export const uploadAvatarSchema = v.object({
     .maxSize({ unit: "MB", size: 5 })
     .mimeType(["image/jpeg", "image/png", "image/webp"]),
 });
+
+export type UploadAvatarSchema = Infer<typeof uploadAvatarSchema>;
 ```
 
 ```ts title="src/app/uploads/controllers/upload-avatar.controller.ts"
-import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type UploadAvatarSchema, uploadAvatarSchema } from "../schema/upload-avatar.schema";
 
-export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async (
+export const uploadAvatarController: GuardedRequestHandler<UploadAvatarSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const { avatar } = request.validated();
 
   const file = await avatar
@@ -5701,7 +5722,7 @@ Inside a controller:
 ```ts
 import type { RequestHandler, UploadedFile } from "@warlock.js/core";
 
-export const uploadController: RequestHandler = async (request, response) => {
+export const uploadController: RequestHandler = async ({ request, response }) => {
   // option A — direct from request, no validation
   const file: UploadedFile | undefined = request.file("avatar");
 
@@ -5883,7 +5904,7 @@ export const uploadFilesSchema = v.object({
 ```ts title="src/app/uploads/controllers/create-upload.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const createUploadController: RequestHandler = async (request, response) => {
+export const createUploadController: RequestHandler = async ({ request, response }) => {
   const { files } = request.validated();
 
   const saved = await Promise.all(
@@ -6180,9 +6201,9 @@ const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-
 ### Health endpoint
 
 ```ts title="src/app/system/controllers/health.controller.ts"
-import { Application, type RequestHandler, type Response } from "@warlock.js/core";
+import { Application, type RequestHandler } from "@warlock.js/core";
 
-export const healthController: RequestHandler = async (_request, response: Response) => {
+export const healthController: RequestHandler = async ({ response }) => {
   return response.success({
     status: "ok",
     environment: Application.environment,
@@ -6481,10 +6502,14 @@ The error's message is locale-aware — the `inject-request-context` middleware
 ### Translated response message in a controller
 
 ```ts
-export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { type CreateProductSchema } from "../schema/create-product.schema";
+import { createProductService } from "../services/create-product.service";
+
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
   return response.success({
     message: request.t("products.created"),
@@ -7301,10 +7326,10 @@ export async function listFaqsService(filters: FaqListOptions) {
 ```
 
 ```ts title="src/app/faqs/controllers/list-faqs.controller.ts"
-import type { RequestHandler, Response } from "@warlock.js/core";
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { listFaqsService } from "../services/list-faqs.service";
 
-export const listFaqsController: RequestHandler = async (request, response: Response) => {
+export const listFaqsController: GuardedRequestHandler = async ({ request, response }) => {
   const { data, pagination } = await listFaqsService({
     ...request.all(),
     organization_id: request.user.organizationId,
@@ -7489,7 +7514,7 @@ public locals: RequestLocals = {};
 ```ts title="src/app/observability/middleware/request-timing.middleware.ts"
 import type { Middleware } from "@warlock.js/core";
 
-export const requestTimingMiddleware: Middleware = request => {
+export const requestTimingMiddleware: Middleware = (request) => {
   request.startedAt = Date.now();
 };
 ```
@@ -7497,7 +7522,7 @@ export const requestTimingMiddleware: Middleware = request => {
 ```ts title="src/app/observability/controllers/timing.controller.ts"
 import type { RequestHandler } from "@warlock.js/core";
 
-export const timingController: RequestHandler = async (request, response) => {
+export const timingController: RequestHandler = async ({ request, response }) => {
   return response.success({ elapsedMs: Date.now() - request.startedAt });
 };
 ```
@@ -7582,7 +7607,7 @@ Feature-local files such as `src/app/organizations/request-locals.d.ts` are equa
 
 Two rules the scaffold's own comments spell out, and both bite silently:
 
-- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an *ambient* module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
+- **Keep the trailing `export {}`.** `declare module "x"` inside a file with no top-level import or export declares an _ambient_ module, which REPLACES `@warlock.js/core`'s real typings instead of merging into them — every framework export vanishes. The `export {}` is what makes the file a module and the block an augmentation. It is not an unused statement to clean up.
 - **Keep them `interface`, not `type`.** This project otherwise prefers `type`; these are the named exception, because declaration merging is interface-only. `type RequestUser = { ... }` is a duplicate-identifier error, not an augmentation.
 
 On a project scaffolded before 5.1 there is no `src/typings.d.ts`, and `tsconfig.json` carries `"typeRoots": ["./src/typings.d.ts"]` — wrong twice, since `typeRoots` takes directories of `@types` packages rather than files, and that file did not exist. Drop the `typeRoots` entry, create the file, and list it under `include`.
@@ -7656,10 +7681,10 @@ import type { Request, RequestHandler } from "@warlock.js/core";
 import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
 
-export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async ({
   request,
   response,
-) => {
+}) => {
   const product = await createProductService(request.validated());
 
   return response.successCreate({ product });
@@ -7969,11 +7994,11 @@ This skill is the foundation. Every other warlock skill (`register-route`, `crea
    ```
 
    ```ts title="src/app/<module>/controllers/create-<thing>.controller.ts"
-   import { type GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+   import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
    import { type CreateThingSchema, createThingSchema } from "../schema/create-thing.schema";
    import { createThingService } from "../services/create-thing.service";
 
-   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async (request, response) => {
+   export const createThingController: GuardedRequestHandler<CreateThingSchema> = async ({ request, response }) => {
      const thing = await createThingService(request.validated());
      return response.success({ thing });
    };
@@ -8459,10 +8484,10 @@ export async function notifyUserService(user: User, payload: unknown) {
 Then from a controller:
 
 ```ts
-import type { GuardedRequestHandler } from "app/auth/types/guarded-request.type";
+import type { GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { notifyUserService } from "../services/notify-user.service";
 
-export const sendNotificationController: GuardedRequestHandler = async (request, response) => {
+export const sendNotificationController: GuardedRequestHandler = async ({ request, response }) => {
   await notifyUserService(request.user, request.input("payload"));
   return response.success({ delivered: true });
 };
@@ -8624,7 +8649,7 @@ CLI commands, scheduled jobs, queue workers — anything running outside an HTTP
 
 ---
 name: write-cli-command
-description: 'Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.'
+description: 'Author a custom `warlock <my-cmd>` command via the `command()` factory — name, description, action, options, preload, then register in `warlock.config.ts > cli.commands` or drop in `src/app/<module>/commands/`. Also covers built-in `warlock add` feature scaffolding, including the Web starter and `index.register.ts`. Triggers: `command`, `CLICommand`, `CLICommandPreload`, `CLICommandOption`, `preload`, `preAction`, `persistent`, `colors`, `warlock add`, `index.register.ts`; "write a custom warlock command", "one-off maintenance task", "ship a CLI from a package", "framework built-in commands"; typical import `import { command } from "@warlock.js/core"`. Skip: framework dev/build/start — `@warlock.js/core/run-app/SKILL.md`; warlock.config.ts wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `commander`, `yargs`, `oclif`.'
 ---
 
 # Warlock — write a CLI command
@@ -8829,6 +8854,7 @@ warlock generate                         (alias: g)      — interactive picker
 | Feature       | Installs                                                                                            |
 | ------------- | --------------------------------------------------------------------------------------------------- |
 | `react-email` | `react-email` + `@react-email/components` + `@react-email/render` + `@react-email/tailwind`; drops a `welcome-email.tsx` sample; patches `tsconfig.json` |
+| `web`         | Warlock Web + React stack; scaffolds the application page, localization, contact endpoint, and Web configuration                         |
 | `react`       | `react` + `react-dom` + types                                                                       |
 | `image`       | `sharp` (for the `Image` class)                                                                     |
 | `mail`        | `nodemailer` + types                                                                                |
@@ -8846,6 +8872,8 @@ warlock generate                         (alias: g)      — interactive picker
 
 Run `warlock add --list` to see what's currently registered. Pass `--packageManager <yarn\|pnpm\|npm>` to override auto-detection (defaults to whichever lockfile is present).
 
+The Web starter keeps the page's universal non-component setup in `src/web/index.register.ts`, while `src/web/index.page.tsx` re-exports `register`. Warlock still discovers and runs the hook from the page namespace in both SSR and the browser, but editing the page component remains inside React's Fast Refresh boundary. Do not move the `register()` declaration inline beside the component: React Refresh treats that non-component export as incompatible and reloads the page, losing component state.
+
 ### Misc
 
 | Command  | Purpose                                                     |
@@ -8935,7 +8963,7 @@ export default command({
 
 ---
 name: write-middleware
-description: 'Author HTTP middleware for @warlock.js/core — the `(request, response)` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.'
+description: 'Author HTTP middleware for @warlock.js/core — the `({ request, response })` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.'
 ---
 
 # Warlock — write a middleware
@@ -8947,7 +8975,7 @@ Middleware is a plain function that runs before the controller. Two outcomes: re
 ```ts title="src/app/<module>/utils/<name>.middleware.ts"
 import type { Middleware } from "@warlock.js/core";
 
-export const requireApiKey: Middleware = (request, response) => {
+export const requireApiKey: Middleware = ({ request, response }) => {
   const key = request.header("X-API-Key");
 
   if (!key || key !== process.env.API_KEY) {
@@ -8958,16 +8986,14 @@ export const requireApiKey: Middleware = (request, response) => {
 };
 ```
 
-That's the contract: `(request: Request, response: Response) => Response | undefined | void`. Async is fine — return a `Promise<Response | undefined | void>`.
+That's the contract: `(context: HttpContext<Request>) => Response | undefined | void`, where `context` is `{ request, response }`. Async is fine — return a `Promise<Response | undefined | void>`.
 
 The real type, from `@warlock.js/core/src/router/types.ts`:
 
 ```ts
 export type Middleware<MiddlewareRequest extends Request = Request> = {
-  (request: MiddlewareRequest, response: Response): MiddlewareResponse;
+  (context: HttpContext<MiddlewareRequest>): MiddlewareResponse;
 };
-
-export type MiddlewareResponse = ReturnedResponse | undefined | void;
 ```
 
 ## Short-circuit vs continue
@@ -8977,7 +9003,7 @@ The pattern is "return a response to stop, return nothing to continue":
 ```ts
 import type { Middleware } from "@warlock.js/core";
 
-export const requireFeatureFlag: Middleware = async (request, response) => {
+export const requireFeatureFlag: Middleware = async ({ request, response }) => {
   const flag = await loadFeatureFlag(request.input("organization_id"));
 
   if (!flag.enabled) {
@@ -8995,8 +9021,8 @@ If you short-circuit, the controller never runs. The response helper you pick (`
 You can attach arbitrary fields to `request` from a middleware, and they survive into the controller. The cleanest pattern is to extend `Request` via module augmentation in a `.d.ts` and assign in the middleware:
 
 ```ts title="src/app/feature-flags/middleware/load-feature-flag.middleware.ts"
-import type { Middleware } from "@warlock.js/core";
-import type { FeatureFlag } from "../models/feature-flag";
+import type { Middleware, Request, RequestUser } from "@warlock.js/core";
+import { FeatureFlag } from "../models/feature-flag";
 
 declare module "@warlock.js/core" {
   interface Request {
@@ -9004,7 +9030,7 @@ declare module "@warlock.js/core" {
   }
 }
 
-export const loadFeatureFlag: Middleware = async (request) => {
+export const loadFeatureFlag: Middleware<Request & { user: RequestUser }> = async ({ request }) => {
   request.featureFlag = await FeatureFlag.findBy("organization_id", request.user.organizationId);
 };
 ```
@@ -9074,7 +9100,7 @@ export function guarded(callback: () => void) {
 }
 
 export function guardedAdmin(callback: () => void) {
-  router.group({ prefix: "/admin", middleware: [authMiddleware()] }, callback);
+  router.group({ prefix: "/admin", middleware: [authMiddleware("admin")] }, callback);
 }
 
 export function publicRoutes(callback: () => void) {
@@ -9092,7 +9118,7 @@ guarded(() => {
 });
 ```
 
-`authMiddleware(allowedUserType?)` accepts a user-type string or array. Without an arg it just verifies the token is present; with `"user"` / `"admin"` it also checks the decoded `userType` matches.
+`authMiddleware(allowedUserType, tokenFrom?)` requires a user-type string or array — `[]` accepts any authenticated user without checking `userType`; `"user"` / `"admin"` also checks the decoded `userType` matches.
 
 ## Common patterns
 
@@ -9119,13 +9145,13 @@ router.group(
 ```ts
 import type { Middleware } from "@warlock.js/core";
 
-export const optionalAuth: Middleware = async (request, response) => {
+export const optionalAuth: Middleware = async ({ request, response }) => {
   if (!request.authorizationValue) {
     return; // anonymous — let it through
   }
 
   // token present → enforce it
-  return authMiddleware("user")(request, response);
+  return authMiddleware("user")({ request, response });
 };
 ```
 
@@ -9141,7 +9167,7 @@ export const optionalAuth: Middleware = async (request, response) => {
 - **Group middleware runs before per-route middleware**, in array order. The full chain is `app.all → group → per-route → controller`. Mind the order if you stack auth + rate-limit + audit.
 - **Middleware can be async.** Returning `Promise<undefined>` continues the chain. Returning `Promise<Response>` short-circuits. The framework awaits the result.
 - **Don't mutate `request.payload` directly.** Use `request.setValidatedData(...)` or attach a new named field (`request.featureFlag = ...`). The internals expect `payload.all` shapes to come from the validator pipeline.
-- **`Middleware` is generic over the request type.** For middleware that assumes a validated schema, narrow it: `const m: Middleware<CreateProductRequest> = (request) => { ... }`. But most middlewares run before validation, so the default `Middleware` is right.
+- **`Middleware` is generic over the request type.** For middleware that assumes a validated schema, narrow it: `const m: Middleware<CreateProductRequest> = ({ request }) => { ... }`. But most middlewares run before validation, so the default `Middleware` is right.
 - **No `next()` parameter.** Express-style `next()` doesn't apply here. The framework chains based on return value.
 - **`request.baseRequest` / `response.baseResponse` are escape hatches, not API.** They expose the underlying Fastify primitives for cases the framework hasn't covered yet (streaming was the historical precedent). Prefer framework helpers first — `response.send()`, `response.header()`, `response.replay()`, `request.input()`, `request.detectIp()`, etc. If you find yourself reaching for `baseResponse` or `baseRequest` for non-streaming work, that's a missing helper — file an issue. The cache and idempotency middlewares both shipped with a quietly-broken FastifyReply-return bug because they bypassed the helper layer; the framework now guards `Response.send()` against double-send, but the right answer is "use the helper."
 - **Behind any proxy, use `request.detectIp()` not `request.ip`.** `request.ip` is the immediate peer (likely your load balancer); `request.detectIp()` honors `X-Real-IP` / `X-Forwarded-For`. Either way, only trust the result as far as you trust the upstream chain — those headers are client-settable; verify the request came through your trusted edge before treating the value as authoritative.