@warlock.js/core 5.30.0 → 5.31.0

package/skills/model-factories/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: model-factories
+description: 'Deterministic model factories for tests and seeders — `defineFactory(Model, (seed) => attributes)` with `make()`, `makeMany(n)`, `create()`, `create(n)`, `createMany(n)`, named states via `.state()` / `.with()`, and a faker-free seed (`seed.text`, `seed.email`, `seed.uuid`, `seed.date`, `seed.number`, `seed.pick`). Triggers: `defineFactory`, `Factory`, `FactorySeed`, `resetFactorySequences`, `userFactory`; "test fixtures", "create test users", "factory states", "deterministic test data", "build a request body for a test". Typical import `import { defineFactory } from "@warlock.js/core/tests"`. Skip: seeding a real database for development — the `write-seeder` topic; fakes — the `test-fakes` topic.'
+---
+
+# Warlock — model factories
+
+A factory turns a sequence number into attributes. The n-th record a factory builds is the same on every run — no faker, no randomness — so snapshots and assertions stay stable.
+
+## Define one per model
+
+```ts title="src/app/users/tests/user.factory.ts"
+import { Model } from "@warlock.js/cascade";
+import { defineFactory } from "@warlock.js/core/tests";
+
+// Your model; in an app this is `import { User } from "app/users/models/user"`.
+type UserSchema = { name: string; email: string; password: string; emailVerifiedAt?: Date };
+
+export class User extends Model<UserSchema> {
+  public static table = "users";
+}
+
+export const userFactory = defineFactory(User, (seed) => ({
+  name: seed.text("User"), // "User 1", "User 2", ...
+  email: seed.email(), // "user1@example.test", ...
+  password: "test-password",
+}))
+  .state("unverified", () => ({ emailVerifiedAt: undefined }))
+  .state("named", (seed) => ({ name: `Named ${seed.sequence}` }));
+```
+
+Attributes are typed by the model's schema (`Partial` of it, as `Model.create()` takes). Keep factories next to the module's tests.
+
+## Use it
+
+```ts
+// with: import { expectJson, testPost } from "@warlock.js/core/tests";
+//       import { userFactory } from "./user.factory";
+it("registers a user from a factory-built body", async () => {
+  const body = userFactory.make({ email: "ada@example.test" }); // attributes only, no database
+
+  const response = await testPost("/auth/register", body);
+
+  expect((await expectJson<{ user: { email: string } }>(response, 201)).user.email).toBe(
+    "ada@example.test",
+  );
+});
+
+it("lists users", async () => {
+  await userFactory.create(3); // three saved users, in order
+  await userFactory.with("unverified", "named").create();
+});
+```
+
+| Call                        | Returns            | Database |
+| --------------------------- | ------------------ | -------- |
+| `make(overrides?)`          | attributes         | no       |
+| `makeMany(n, overrides?)`   | attributes[]       | no       |
+| `create(overrides?)`        | `Promise<Model>`   | yes      |
+| `create(n, overrides?)`     | `Promise<Model[]>` | yes      |
+| `createMany(n, overrides?)` | `Promise<Model[]>` | yes      |
+| `with(...states)`           | a derived factory  | —        |
+| `state(name, fn)`           | the same factory   | —        |
+| `resetSequence()`           | —                  | —        |
+
+`create()` goes through the model's own `create()`, so casts, defaults, hooks and events run exactly as in the app. Overrides are a partial or a function of the seed: `make((seed) => ({ name: `Custom ${seed.sequence}` }))`. States apply in order on top of the definition, then the overrides. A derived factory shares the base sequence.
+
+## The seed
+
+| Member               | Value                                                  |
+| -------------------- | ------------------------------------------------------ |
+| `sequence`           | 1 for the first record the factory builds, then 2, ... |
+| `index`              | position within the current `makeMany` / `createMany`  |
+| `text(prefix?)`      | `"<prefix> <sequence>"`                                |
+| `email(prefix?)`     | `"<prefix><sequence>@example.test"` (default `user`)   |
+| `uuid()`             | `00000000-0000-4000-8000-<sequence, 12 digits>`        |
+| `date(offsetDays?)`  | 2026-01-01T00:00:00Z plus `offsetDays` days            |
+| `number(min?, max?)` | an integer in `[min, max]`, cycling with the sequence  |
+| `pick(values)`       | one of `values`, cycling with the sequence             |
+
+`resetFactorySequences()` restarts every factory — call it in `beforeEach` when a test asserts exact values.
+
+## Gotchas
+
+- **Unique columns.** `seed.email()` is unique per factory sequence, not across test files; a database shared between files needs cleanup or `resetFactorySequences()` plus truncation, otherwise a second file collides on `user1@example.test`.
+- **`make()` never touches the database.** It returns attributes, not a model instance — use it for request bodies and pure-logic tests.
+- **An unknown state throws** and lists the defined ones.
+
+## See also
+
+- The `test-fakes` topic — fakes for mail, queue, cache, storage, clock and ids.
+- The `write-seeder` topic — seeding a development database.

package/skills/process-image/SKILL.md

@@ -37,16 +37,16 @@ Adds `sharp` to your dependencies. Skip it and the first `new Image(...)` throws
 ## Constructors
 
 ```ts
-new Image("./avatar.jpg")            // path
-new Image(buffer)                     // Buffer
-new Image(uint8Array)                 // Uint8Array
-new Image(arrayBuffer)                // ArrayBuffer
-new Image(existingSharpInstance)      // wrap a sharp.Sharp you already built
+new Image("./avatar.jpg"); // path
+new Image(buffer); // Buffer
+new Image(uint8Array); // Uint8Array
+new Image(arrayBuffer); // ArrayBuffer
+new Image(existingSharpInstance); // wrap a sharp.Sharp you already built
 
 // Or via static factories:
 Image.fromFile("./avatar.jpg");
 Image.fromBuffer(buffer);
-await Image.fromUrl("https://example.com/photo.jpg");   // @mongez/http under the hood
+await Image.fromUrl("https://example.com/photo.jpg"); // @mongez/http under the hood
 ```
 
 `Image.fromUrl(...)` is the only async factory — it fetches the URL via `@mongez/http` (`responseType: "arrayBuffer"`), then wraps the bytes. The rest are synchronous.
@@ -55,25 +55,25 @@ await Image.fromUrl("https://example.com/photo.jpg");   // @mongez/http under th
 
 Every method returns `this` so calls chain. Transforms are descriptors; nothing runs until the output method.
 
-| Method                                       | Effect                                                                       |
-| -------------------------------------------- | ---------------------------------------------------------------------------- |
-| `.resize({ width?, height?, fit?, ... })`    | sharp resize — accepts the full `sharp.ResizeOptions` shape                  |
-| `.crop({ left, top, width, height })`        | extract a region                                                             |
-| `.rotate(deg)`                               | clockwise rotation                                                           |
-| `.flip()`                                    | mirror vertically (top↔bottom)                                               |
-| `.flop()`                                    | mirror horizontally (left↔right)                                             |
-| `.blur(sigma)`                               | gaussian blur (sigma is required, must be ≥ 0.3 — throws otherwise)          |
-| `.sharpen(options?)`                         | sharp's sharpen                                                              |
-| `.grayscale()` / `.blackAndWhite()`          | grayscale (aliases)                                                          |
-| `.tint(color)`                               | color tint                                                                   |
-| `.negate(options?)`                          | invert colors                                                                |
-| `.opacity(value)`                            | 0–100, applied via composite                                                 |
-| `.trim(options?)`                            | trim borders                                                                 |
-| `.watermark(image, options?)`                | overlay one watermark — two positional args (`image` accepts the same inputs as the constructor, plus another `Image`; `options` is `sharp.OverlayOptions`) |
-| `.watermarks([{ image, options }, ...])`     | overlay many — one `WatermarkConfig` object (`{ image, options }`) per entry  |
-| `.format(format)`                            | output format — `"jpeg"`, `"png"`, `"webp"`, `"avif"`, `"tiff"`, `"heif"`, ... |
-| `.quality(1–100)`                            | lossy formats only (`jpeg` / `webp` / `avif` / `tiff` / `heif`); ignored otherwise |
-| `.apply(options)`                            | apply many transforms in one call, in a fixed canonical order                |
+| Method                                    | Effect                                                                                                                                                      |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.resize({ width?, height?, fit?, ... })` | sharp resize — accepts the full `sharp.ResizeOptions` shape                                                                                                 |
+| `.crop({ left, top, width, height })`     | extract a region                                                                                                                                            |
+| `.rotate(deg)`                            | clockwise rotation                                                                                                                                          |
+| `.flip()`                                 | mirror vertically (top↔bottom)                                                                                                                              |
+| `.flop()`                                 | mirror horizontally (left↔right)                                                                                                                            |
+| `.blur(sigma)`                            | gaussian blur (sigma is required, must be ≥ 0.3 — throws otherwise)                                                                                         |
+| `.sharpen(options?)`                      | sharp's sharpen                                                                                                                                             |
+| `.grayscale()` / `.blackAndWhite()`       | grayscale (aliases)                                                                                                                                         |
+| `.tint(color)`                            | color tint                                                                                                                                                  |
+| `.negate(options?)`                       | invert colors                                                                                                                                               |
+| `.opacity(value)`                         | 0–100, applied via composite                                                                                                                                |
+| `.trim(options?)`                         | trim borders                                                                                                                                                |
+| `.watermark(image, options?)`             | overlay one watermark — two positional args (`image` accepts the same inputs as the constructor, plus another `Image`; `options` is `sharp.OverlayOptions`) |
+| `.watermarks([{ image, options }, ...])`  | overlay many — one `WatermarkConfig` object (`{ image, options }`) per entry                                                                                |
+| `.format(format)`                         | output format — `"jpeg"`, `"png"`, `"webp"`, `"avif"`, `"tiff"`, `"heif"`, ...                                                                              |
+| `.quality(1–100)`                         | lossy formats only (`jpeg` / `webp` / `avif` / `tiff` / `heif`); ignored otherwise                                                                          |
+| `.apply(options)`                         | apply many transforms in one call, in a fixed canonical order                                                                                               |
 
 `apply(options)` accepts an `ImageTransformOptions` object — every transform above as a key. Useful when transforms come from config or a request payload.
 
@@ -82,10 +82,10 @@ Every method returns `this` so calls chain. Transforms are descriptors; nothing
 Each of these fires the pipeline exactly once and returns the result. Subsequent calls run the pipeline again (operations aren't memoised).
 
 ```ts
-await image.save("./output.webp");          // write to disk; returns the absolute path
-const buffer = await image.toBuffer();      // → Buffer
-const base64 = await image.toBase64();      // → "iVBORw0KGgo..."
-const dataUrl = await image.toDataUrl();    // → "data:image/webp;base64,..."
+await image.save("./output.webp"); // write to disk; returns the absolute path
+const buffer = await image.toBuffer(); // → Buffer
+const base64 = await image.toBase64(); // → "iVBORw0KGgo..."
+const dataUrl = await image.toDataUrl(); // → "data:image/webp;base64,..."
 ```
 
 ## Common patterns
@@ -93,7 +93,9 @@ const dataUrl = await image.toDataUrl();    // → "data:image/webp;base64,..."
 ### Resize an uploaded avatar to two sizes
 
 ```ts
-import { Image } from "@warlock.js/core";
+import { Image, type UploadedFile } from "@warlock.js/core";
+
+declare const uploadedAvatar: UploadedFile; // e.g. request.validated().avatar
 
 const buffer = await uploadedAvatar.buffer();
 

package/skills/register-route/SKILL.md

@@ -90,9 +90,9 @@ Projects with `@warlock.js/auth` usually define a `guarded(...)` helper in `src/
 import { guarded } from "app/shared/utils/router";
 
 router.prefix("/products", () => {
-  router.get("/", listProductsController);             // public
+  router.get("/", listProductsController); // public
   guarded(() => {
-    router.post("/", createProductController);          // requires logged-in user
+    router.post("/", createProductController); // requires logged-in user
     router.delete("/:id", removeProductController);
   });
 });
@@ -100,17 +100,27 @@ router.prefix("/products", () => {
 
 If `guarded` doesn't exist in your project yet, see the shared utility convention in the `warlock-conventions` topic.
 
+### A mutating route with no guard — say so with `public: true`
+
+```ts
+// src/app/contact/routes.ts
+router.post("/api/contact", contactController, { public: true });
+```
+
+`public: true` changes nothing at runtime; it records that the missing guard is deliberate, so reviewers, `warlock check` and route tooling can tell a decision from an omission. `warlock make endpoint --public` writes it (the `make-endpoint` topic).
+
 ## RESTful resource chain
 
 For a standard CRUD resource, `router.route(path)` returns a builder with five named slots:
 
 ```ts
-router.route("/products")
-  .list(listProductsController)        // GET    /products
-  .show(getProductController)          // GET    /products/:id
-  .create(createProductController)     // POST   /products
-  .update(updateProductController)     // PUT    /products/:id
-  .destroy(removeProductController);   // DELETE /products/:id
+router
+  .route("/products")
+  .list(listProductsController) // GET    /products
+  .show(getProductController) // GET    /products/:id
+  .create(createProductController) // POST   /products
+  .update(updateProductController) // PUT    /products/:id
+  .destroy(removeProductController); // DELETE /products/:id
 ```
 
 Each method returns the builder so you can chain. Methods you don't call don't register. Pair with `guarded`/`group` the same way as plain routes.
@@ -143,8 +153,8 @@ guarded(() => {
 
 ```ts
 router.prefix("/auth", () => {
-  router.post("/login", loginController);
-  router.post("/register", registerController);
+  router.post("/login", loginController, { public: true });
+  router.post("/register", registerController, { public: true });
   guarded(() => {
     router.post("/logout", logoutController);
     router.get("/me", meController);
@@ -152,6 +162,41 @@ router.prefix("/auth", () => {
 });
 ```
 
+### Mutating routes: guard them or say `public: true`
+
+Every POST/PUT/PATCH/DELETE route either runs auth middleware (on the route, its
+builder, or an enclosing group such as `guarded()`) or is marked `public: true`.
+`warlock dev` warns once per route about mutating routes with neither, and
+`warlock check` reports the same from source as `WL9006` before the app runs.
+The check reads source, not runtime markers: a guard counts when its name
+contains `auth` or `guard`, or when it is a constant initialised with
+`markAuthGuard()` in the same file. A differently-named guard imported from
+another file needs a `// warlock-check-ignore WL9006` comment on its route.
+
+```ts
+import { markAuthGuard, router, type Middleware, type RequestHandler } from "@warlock.js/core";
+
+const stripeWebhookController: RequestHandler = async ({ response }) =>
+  response.success({ received: true });
+const importController: RequestHandler = async ({ response }) => response.success({ queued: true });
+
+// Open on purpose: a webhook signed by the provider.
+router.group({ prefix: "/webhooks", public: true }, () => {
+  router.post("/stripe", stripeWebhookController);
+});
+
+// A hand-written guard whose name has no "auth"/"guard" in it.
+const requireApiKey: Middleware = markAuthGuard(async ({ request, response }) => {
+  if (request.headers["x-api-key"] !== process.env.API_KEY) return response.unauthorized();
+});
+
+router.post("/imports", importController, { middleware: [requireApiKey] });
+```
+
+`public` changes nothing at runtime. `authMiddleware()` marks itself (its
+`{ optional: true }` form does not count). Silence the warning app-wide with
+`http.warnUnguardedRoutes: false`; page routes are never reported.
+
 ### Multiple paths on one handler
 
 ```ts
@@ -168,6 +213,60 @@ router.post("/accounts/credentials", accountsController.store, {
 
 Request log entries otherwise include the body as received (before validation), so rejected fields would be logged too.
 
+## Static directories and public files
+
+```ts
+router.directory({ root: Application.publicPath, prefix: "/assets/" });
+```
+
+Static routes are queued at scan time after HTTP plugin hooks. `@fastify/static` itself loads only on
+the first static file request, even with an existing public folder; concurrent
+first requests share initialization. The upstream sender retains ranges, caching,
+listings, precompressed files, `allowedPath` and `setHeaders` behavior. The
+`setHeaders` callback receives the real Fastify reply.
+
+`wildcard: false` still enumerates exact file routes at boot, so files added later
+follow the application's ordinary fallback until restart. The directory globber
+loads at boot only for this option; the upstream sender enumerates those roots
+again on the first request, which can be noticeable for large directories. The public folder uses
+`storage.publicRoot` (default `public/`) and `storage.publicPrefix` (default
+`/public/`); `false` disables it and missing folders add no routes. Its
+`reply.sendFile`/`reply.download` decorators are lazy too. `router.directory`
+keeps `decorateReply: false` for additional mounts. Initialization failures reach
+the application's normal error handler.
+
+Global rate limits apply to application routes and web page routes in
+production and development. Defaults are 60 requests/minute per IP in one shared
+bucket across routes and pages. Behind a reverse proxy, configure trusted
+`http.trustProxy` addresses or a suitable `http.rateLimit.keyGenerator`, and
+review `max` before upgrading. `http.rateLimit.global: false` disables blanket
+quotas while retaining explicit route limits. Built-in health/readiness probes
+are exempt unless `http.health.rateLimit: true` opts them into the global policy.
+
+Static files are exempt from the global limiter by default: the public folder,
+every `router.directory()` mount and `router.file()` / `cachedFile()` / `files()` /
+`cachedFiles()` routes (and the web build's assets). `http.rateLimit.staticFiles:
+true` counts them all; a mount can decide for itself:
+
+```ts
+import { rootPath, router } from "@warlock.js/core";
+
+router.directory({ root: rootPath("storage/exports"), prefix: "/exports/" }, { rateLimit: true });
+router.directory(
+  { root: rootPath("storage/reports"), prefix: "/reports/" },
+  { rateLimit: { max: 20, timeWindow: 60_000 } },
+);
+router.file("/price-list.pdf", rootPath("storage/price-list.pdf"), 300, { rateLimit: true });
+```
+
+Exempt one application route with `rateLimit: false` (or
+`serverOptions: { config: { rateLimit: false } }`); development's wildcard
+dispatcher honours both exactly as production does:
+
+```ts
+router.get("/webhooks/status", webhookStatusController, { rateLimit: false });
+```
+
 ## Gotchas
 
 - **Never import `routes.ts`.** The framework auto-loads it. Importing causes a double-registration error.

package/skills/request-memo/SKILL.md

@@ -12,7 +12,7 @@ description: 'Memoize async work for one HTTP request with `requestMemo<T>(key,
 From `core/src/http/context/request-memo.ts`:
 
 ```ts
-export function requestMemo<T>(key: string, fn: () => Promise<T>): Promise<T>
+export function requestMemo<T>(key: string, fn: () => Promise<T>): Promise<T>;
 ```
 
 Import it from the package root:

package/skills/request-tracing/SKILL.md

@@ -181,11 +181,12 @@ own extra guard — the check is already there.
 
 ```ts
 // src/config/http.ts
+import { env, type HttpConfigurations } from "@warlock.js/core";
 import { log } from "@warlock.js/logger";
 
 const SLOW_MS = 200;
 
-export default {
+const httpConfig: HttpConfigurations = {
   tracing: {
     enabled: env("TRACING_ENABLED") === "true",
     hooks: [
@@ -206,6 +207,8 @@ export default {
     ],
   },
 };
+
+export default httpConfig;
 ```
 
 ## Gotchas

package/skills/resolve-path/SKILL.md

@@ -12,30 +12,30 @@ Twelve helpers, all anchored at `process.cwd()`, all in `@warlock.js/core`. They
 ```ts
 import { appPath, configPath, uploadsPath, storagePath } from "@warlock.js/core";
 
-appPath("orders/routes.ts");           // → <cwd>/src/app/orders/routes.ts
-configPath("http.ts");                  // → <cwd>/src/config/http.ts
-uploadsPath("avatars/42.png");          // → <cwd>/storage/uploads/avatars/42.png
-storagePath("backups/2026-01.tar.gz");  // → <cwd>/storage/backups/2026-01.tar.gz
+appPath("orders/routes.ts"); // → <cwd>/src/app/orders/routes.ts
+configPath("http.ts"); // → <cwd>/src/config/http.ts
+uploadsPath("avatars/42.png"); // → <cwd>/storage/uploads/avatars/42.png
+storagePath("backups/2026-01.tar.gz"); // → <cwd>/storage/backups/2026-01.tar.gz
 ```
 
 Every helper takes any number of path segments and joins them. No-argument calls return the base directory itself.
 
 ## Full inventory
 
-| Helper             | Resolves to                              | Notes                                                              |
-| ------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
-| `rootPath(...p)`   | `<cwd>/<...p>`                           | Also `Application.rootPath`. Base of every other helper.           |
-| `srcPath(...p)`    | `<cwd>/src/<...p>`                       | Also `Application.srcPath`.                                        |
-| `appPath(p?)`      | `<cwd>/src/app/<p>`                      | Also `Application.appPath`. Module roots live here.                |
-| `configPath(...p)` | `<cwd>/src/config/<...p>`                | `src/config/*.ts` subsystem configs.                               |
-| `publicPath(p?)`   | `<cwd>/public/<p>`                       | Also `Application.publicPath`. Static assets served as-is.         |
-| `storagePath(p?)`  | `<cwd>/storage/<p>`                      | Also `Application.storagePath`. Root for framework-managed files.  |
-| `uploadsPath(p?)`  | `<cwd>/storage/uploads/<p>` *(default)*  | Also `Application.uploadsPath`. Honors `config.uploads.root` override (string or function). |
-| `cachePath(p?)`    | `<cwd>/storage/cache/<p>`                | Persistent cache files.                                            |
-| `logsPath(p?)`     | `<cwd>/storage/logs/<p>`                 | Application logs.                                                  |
-| `tempPath(p?)`     | `<cwd>/storage/tmp/<p>`                  | Throw-away scratch.                                                |
+| Helper              | Resolves to                             | Notes                                                                                                                               |
+| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `rootPath(...p)`    | `<cwd>/<...p>`                          | Also `Application.rootPath`. Base of every other helper.                                                                            |
+| `srcPath(...p)`     | `<cwd>/src/<...p>`                      | Also `Application.srcPath`.                                                                                                         |
+| `appPath(p?)`       | `<cwd>/src/app/<p>`                     | Also `Application.appPath`. Module roots live here.                                                                                 |
+| `configPath(...p)`  | `<cwd>/src/config/<...p>`               | `src/config/*.ts` subsystem configs.                                                                                                |
+| `publicPath(p?)`    | `<cwd>/public/<p>`                      | Also `Application.publicPath`. Static assets served as-is.                                                                          |
+| `storagePath(p?)`   | `<cwd>/storage/<p>`                     | Also `Application.storagePath`. Root for framework-managed files.                                                                   |
+| `uploadsPath(p?)`   | `<cwd>/storage/uploads/<p>` _(default)_ | Also `Application.uploadsPath`. Honors `config.uploads.root` override (string or function).                                         |
+| `cachePath(p?)`     | `<cwd>/storage/cache/<p>`               | Persistent cache files.                                                                                                             |
+| `logsPath(p?)`      | `<cwd>/storage/logs/<p>`                | Application logs.                                                                                                                   |
+| `tempPath(p?)`      | `<cwd>/storage/tmp/<p>`                 | Throw-away scratch.                                                                                                                 |
 | `warlockPath(...p)` | `<cwd>/.warlock/<...p>`                 | Framework internals (manifest, transpile cache, typings). **Never write app files here** — the framework deletes the folder freely. |
-| `sanitizePath(p)`  | Strips `<>:"/\|?*` from `p`              | Cleans user-supplied filename fragments before joining.            |
+| `sanitizePath(p)`   | Strips `<>:"/\|?*` from `p`             | Cleans user-supplied filename fragments before joining.                                                                             |
 
 ## The aggregate — `paths`
 
@@ -44,15 +44,15 @@ For builders or maintenance scripts that shuttle several locations in close prox
 ```ts
 import { paths } from "@warlock.js/core";
 
-paths.root("dist", "app.js");        // → <cwd>/dist/app.js
-paths.app("orders/routes.ts");        // → <cwd>/src/app/orders/routes.ts
-paths.uploads("avatars/42.png");      // → <cwd>/storage/uploads/avatars/42.png
-paths.config("mail.ts");              // → <cwd>/src/config/mail.ts
-paths.cache("queries.bin");           // → <cwd>/storage/cache/queries.bin
-paths.logs("errors.log");             // → <cwd>/storage/logs/errors.log
-paths.temp("tmp-export.csv");         // → <cwd>/storage/tmp/tmp-export.csv
-paths.warlock("manifest.json");       // → <cwd>/.warlock/manifest.json
-paths.sanitize("../etc/passwd");      // → "..etcpasswd"
+paths.root("dist", "app.js"); // → <cwd>/dist/app.js
+paths.app("orders/routes.ts"); // → <cwd>/src/app/orders/routes.ts
+paths.uploads("avatars/42.png"); // → <cwd>/storage/uploads/avatars/42.png
+paths.config("mail.ts"); // → <cwd>/src/config/mail.ts
+paths.cache("queries.bin"); // → <cwd>/storage/cache/queries.bin
+paths.logs("errors.log"); // → <cwd>/storage/logs/errors.log
+paths.temp("tmp-export.csv"); // → <cwd>/storage/tmp/tmp-export.csv
+paths.warlock("manifest.json"); // → <cwd>/.warlock/manifest.json
+paths.sanitize("../etc/passwd"); // → "..etcpasswd"
 ```
 
 Use the named import (`appPath`, `uploadsPath`, ...) when one helper dominates the file; reach for `paths.*` when you're shuttling multiple paths together.
@@ -65,10 +65,7 @@ Use the named import (`appPath`, `uploadsPath`, ...) when one helper dominates t
 import { appPath } from "@warlock.js/core";
 import { readFile } from "node:fs/promises";
 
-const template = await readFile(
-  appPath("mailers/templates/welcome.html"),
-  "utf-8",
-);
+const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-8");
 ```
 
 ### Locate a config file
@@ -84,13 +81,17 @@ const httpConfigFile = configPath("http.ts");
 ```ts
 import { uploadsPath } from "@warlock.js/core";
 
+declare const userId: string;
+
 const avatar = uploadsPath(`avatars/${userId}/profile.png`);
 ```
 
 ### Sanitize a user-supplied filename before joining
 
 ```ts
-import { sanitizePath, uploadsPath } from "@warlock.js/core";
+import { sanitizePath, uploadsPath, type Request } from "@warlock.js/core";
+
+declare const req: Request; // the current request
 
 const safe = sanitizePath(req.input("filename"));
 const dest = uploadsPath(`exports/${safe}`);
@@ -115,7 +116,7 @@ const manifest = warlockPath("manifest.json");
 ```ts title="src/config/uploads.ts"
 export default {
   uploads: {
-    root: "/mnt/uploads",                   // static
+    root: "/mnt/uploads", // static
     // root: (rel) => `/mnt/uploads/${rel}`, // dynamic
   },
 };
@@ -137,18 +138,18 @@ The override is applied **inside** `uploadsPath()`. So `Application.uploadsPath`
 
 ## When to use which
 
-| Goal                                       | Helper            |
-| ------------------------------------------ | ----------------- |
-| File inside a module (controllers/services) | `appPath`        |
-| Top-level subsystem config                 | `configPath`      |
-| Static asset served as-is over HTTP        | `publicPath`      |
-| User-uploaded file (avatar, document)      | `uploadsPath`     |
-| Persistent cache for an expensive op       | `cachePath`       |
-| Application log line                       | `logsPath`        |
-| Short-lived scratch (cleaned aggressively) | `tempPath`        |
-| Bundled artifact (build outputs)           | `rootPath("dist", ...)` |
-| Reading a TS source from disk              | `srcPath` / `appPath` |
-| Framework internals (manifest, transpile)  | `warlockPath` *(read-only)* |
+| Goal                                        | Helper                      |
+| ------------------------------------------- | --------------------------- |
+| File inside a module (controllers/services) | `appPath`                   |
+| Top-level subsystem config                  | `configPath`                |
+| Static asset served as-is over HTTP         | `publicPath`                |
+| User-uploaded file (avatar, document)       | `uploadsPath`               |
+| Persistent cache for an expensive op        | `cachePath`                 |
+| Application log line                        | `logsPath`                  |
+| Short-lived scratch (cleaned aggressively)  | `tempPath`                  |
+| Bundled artifact (build outputs)            | `rootPath("dist", ...)`     |
+| Reading a TS source from disk               | `srcPath` / `appPath`       |
+| Framework internals (manifest, transpile)   | `warlockPath` _(read-only)_ |
 
 If you find yourself reaching for `path.join(process.cwd(), ...)` — that's a sign you want one of these helpers instead.
 

package/skills/retry-operation/SKILL.md

@@ -12,22 +12,25 @@ description: 'Wrap a flaky operation with `retry(fn, options)` — now provided
 ```ts
 import { retry } from "@mongez/reinforcements";
 
+declare function fetchUser(id: string): Promise<{ id: string }>; // any flaky async call
+declare const id: string;
+
 const user = await retry(() => fetchUser(id), {
-  attempts: 4,            // TOTAL tries (initial + retries) — default 3
-  delay: 200,             // base ms between attempts
+  attempts: 4, // TOTAL tries (initial + retries) — default 3
+  delay: 200, // base ms between attempts
   backoff: "exponential", // 200, 400, 800 ms
 });
 ```
 
 ## What changed from the old core `retry`
 
-| Old (`@warlock.js/core`)       | New (`@mongez/reinforcements`)                            |
-| ------------------------------ | -------------------------------------------------------- |
-| `count` = **extra** attempts   | `attempts` = **total** attempts (`count + 1`)            |
-| fixed `delay` only             | `delay` + `backoff` (`"linear" \| "exponential" \| fn`)  |
-| —                              | `maxDelay`, `jitter` (`"full" \| "equal"`), `signal`     |
-| `shouldRetry(error, attempt)`  | `shouldRetry(error, attempt)` (kept) + `onError` observe |
-| —                              | `retryable(fn, options)` to pre-bind a reusable wrapper  |
+| Old (`@warlock.js/core`)      | New (`@mongez/reinforcements`)                           |
+| ----------------------------- | -------------------------------------------------------- |
+| `count` = **extra** attempts  | `attempts` = **total** attempts (`count + 1`)            |
+| fixed `delay` only            | `delay` + `backoff` (`"linear" \| "exponential" \| fn`)  |
+| —                             | `maxDelay`, `jitter` (`"full" \| "equal"`), `signal`     |
+| `shouldRetry(error, attempt)` | `shouldRetry(error, attempt)` (kept) + `onError` observe |
+| —                             | `retryable(fn, options)` to pre-bind a reusable wrapper  |
 
 Migration: `count: 3` → `attempts: 4`.
 
@@ -56,8 +59,8 @@ await retry(() => fetch(url), {
   attempts: 6,
   delay: 100,
   backoff: "exponential",
-  maxDelay: 2_000,   // never wait more than 2s as backoff grows
-  jitter: "full",    // randomise each delay to avoid thundering herd
+  maxDelay: 2_000, // never wait more than 2s as backoff grows
+  jitter: "full", // randomise each delay to avoid thundering herd
 });
 ```
 
@@ -74,6 +77,9 @@ controller.abort(); // rejects promptly with signal.reason
 ```ts
 import { retryable } from "@mongez/reinforcements";
 
+declare function getUser(id: string): Promise<{ id: string }>; // any flaky async call
+declare const id: string;
+
 const fetchUser = retryable(getUser, { attempts: 4, backoff: "exponential" });
 await fetchUser(id);
 ```
@@ -86,6 +92,9 @@ await fetchUser(id);
 import { measure } from "@warlock.js/core";
 import { retry } from "@mongez/reinforcements";
 
+declare const bus: { publish(event: unknown): Promise<void> }; // your event bus
+declare const event: { type: string };
+
 const result = await measure("publish-event", () =>
   retry(() => bus.publish(event), { attempts: 4, delay: 200 }),
 ); // result.latency includes all retries