@warlock.js/core 5.30.0 → 5.32.0

package/skills/send-response/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: send-response
-description: 'Send HTTP responses via @warlock.js/core''s Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `ResourceNotFoundError`, `ForbiddenError`, `request.cookie`, `request.hasCookie`, `CookieJarUnavailableError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — the `create-controller` topic; route registration — the `register-route` topic; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.'
+description: 'Send HTTP responses via @warlock.js/core''s Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `retainEvents`, `retainChunks`, `backpressure`, `@warlock.js/core/errors`, `ResourceNotFoundError`, `ForbiddenError`, `request.cookie`, `request.hasCookie`, `CookieJarUnavailableError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — the `create-controller` topic; route registration — the `register-route` topic; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.'
 ---
 
 # Warlock — send a response
@@ -69,6 +69,23 @@ return response.redirect("/login"); // 302
 return response.redirect("/new-home", 301); // permanent
 ```
 
+A target from the request (`?next=`, `returnTo`) goes through `safeRedirect()`:
+same-origin paths and allow-listed origins pass, anything else (`//evil.com`,
+`javascript:`) becomes the fallback.
+
+```ts
+import { safeRedirect, type RequestHandler } from "@warlock.js/core";
+
+export const afterLoginController: RequestHandler = async ({ request, response }) => {
+  return response.redirect(
+    safeRedirect(request.input("next"), {
+      allowedOrigins: ["https://app.example.com"],
+      fallback: "/dashboard",
+    }),
+  );
+};
+```
+
 ## Files
 
 ```ts
@@ -84,6 +101,27 @@ return response.sendBuffer(buffer, { contentType: "image/png" });
 
 `SendFileOptions` lets you set `cacheTime`, `immutable`, `inline`, `filename` (download attachment name).
 
+Conditional requests are handled for you (RFC 9110): `If-None-Match` compares weakly (`W/"a"` matches `"a"`) and answers 304 on GET/HEAD; `If-Match` compares strongly (a `W/` tag never passes) and answers 412. For your own ETags, use the same helper:
+
+```ts
+import { evaluateConditionalRequest, type RequestHandler } from "@warlock.js/core";
+
+export const showDocumentController: RequestHandler = async ({ request, response }) => {
+  const etag = `"doc-42-v7"`;
+  const outcome = evaluateConditionalRequest({
+    method: request.method,
+    etag,
+    ifMatch: request.header("if-match"),
+    ifNoneMatch: request.header("if-none-match"),
+  });
+
+  if (outcome === "not-modified") return response.setStatusCode(304).send();
+  if (outcome === "precondition-failed") return response.setStatusCode(412).send();
+
+  return response.header("ETag", etag).success({ id: 42 });
+};
+```
+
 `response.xml(string | XMLable, statusCode?)` sends `application/xml` — pass a raw XML string, or anything with a `toXML(): string` method (structural, so core never depends on `@warlock.js/sitemap`). This is for BOUNDED values only: a raw string, or a single `@warlock.js/sitemap` `Sitemap` under the sitemaps.org 50,000-URL / 50MB ceiling. `SitemapIndex` has no `toXML()` — it is the streaming path for larger URL sets and does not fit in one response body. It writes shards plus a master index as FILES via `saveTo`/`publish`, and those files are served directly rather than passed through `xml()`. In Warlock web this is the `web.sitemap` config: `enabled`, `outputDir` (default `storagePath("sitemap")`), and `path` (default `/sitemap.xml`) — the app serves the generated files from `outputDir` at that route, it never builds a `SitemapIndex` response inline.
 
 ## Streams
@@ -115,6 +153,8 @@ import {
   HttpError, // base class — `new HttpError(status, message, payload?)` for arbitrary codes
 } from "@warlock.js/core";
 
+declare const id: string;
+
 throw new ResourceNotFoundError("product.notFound");
 throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
@@ -246,18 +286,42 @@ A route can still override it — call `response.header("Content-Security-Policy
 from a controller or middleware that runs after the funnel, and your value
 wins, same as any other header.
 
+### Header values from user input
+
+`escapeHeaderValue(value)` removes CR/LF and other control characters (tabs
+stay) and replaces non-Latin-1 characters with `?`, so input can neither split
+a header nor make Node throw a 500:
+
+```ts
+import { escapeHeaderValue, type RequestHandler } from "@warlock.js/core";
+
+export const exportController: RequestHandler = async ({ request, response }) => {
+  response.header("X-Export-Name", escapeHeaderValue(request.input("name")));
+  return response.success({ ok: true });
+};
+```
+
+SSE `event`/`id` fields are already single-lined by `response.sse()`
+(`toSingleLineSseField()` is exported for custom writers).
+
 ## Common patterns
 
 ### Localized error
 
 ```ts
-import { t } from "@warlock.js/core";
+import { t, type RequestHandler } from "@warlock.js/core";
 
-if (!result) {
-  return response.unauthorized({ error: t("auth.invalidCredentials") });
-}
+declare function attemptLogin(email: string, password: string): Promise<{ token: string } | null>;
+
+export const loginController: RequestHandler = async ({ request, response }) => {
+  const result = await attemptLogin(request.input("email"), request.input("password"));
+
+  if (!result) {
+    return response.unauthorized({ error: t("auth.invalidCredentials") });
+  }
 
-return response.success(result);
+  return response.success(result);
+};
 ```
 
 ### Created with link header
@@ -273,18 +337,23 @@ return response.successCreate({ product });
 ### Streaming an LLM reply
 
 ```ts
-import { ai } from "@warlock.js/ai";
+import type { AgentContract } from "@warlock.js/ai";
+import { type RequestHandler } from "@warlock.js/core";
 
-const stream = response.stream("text/event-stream");
-const streamedAgent = await myAgent.stream(request.input("message"));
+declare const myAgent: AgentContract; // an ai.agent(...) instance
 
-for await (const event of streamedAgent.events) {
-  if (event.type === "text-delta") {
-    stream.send(`data: ${JSON.stringify({ delta: event.text })}\n\n`);
+export const chatController: RequestHandler = async ({ request, response }) => {
+  const stream = response.stream("text/event-stream");
+  const run = myAgent.stream(request.input("message"));
+
+  for await (const event of run) {
+    if (event.type === "agent.trip.streaming") {
+      stream.send(`data: ${JSON.stringify({ delta: event.delta })}\n\n`);
+    }
   }
-}
 
-stream.end();
+  stream.end();
+};
 ```
 
 (For the agent surface itself, see `@warlock.js/ai/skills/subskills/agent.md`.)
@@ -316,3 +385,99 @@ return response.header("X-Cache", "HIT").replay({
 - The `create-controller` topic — what calls `response.<helper>()` from.
 - The `register-route` topic — wiring the controller to a URL.
 - The `warlock-conventions` topic — when to use HTTP error helpers vs `throw`.
+
+## Stream wire format, headers and synchronous producers
+
+```ts
+const sse = response.sse({
+  headers: { "Cache-Control": "private, no-store" },
+  maxQueuedBytes: 1024 * 1024,
+  onOverflow: "disconnect",
+});
+sse.send(undefined, { status: "ready" }); // no event field: EventSource.onmessage
+sse.enqueue(undefined, "already serialized\nsecond line", undefined, { raw: true });
+```
+
+The positional `send(event, data, id?, options?)` and `write(...)` calls still work.
+An undefined event omits `event:`. Data is JSON by default; `{ raw: true }` requires
+string data and emits one safe `data:` line per input line. Event/id line breaks
+and NUL are removed, so raw data cannot inject event fields.
+
+Both `sse({ headers })` and `stream(contentType, { headers })` apply caller headers
+before flushing. Cache-Control keeps the safe stream default unless explicitly
+set in options.headers; a pre-existing global cache header does not override it.
+Caller protocol headers are filtered case-insensitively before applying overrides.
+Both helpers use chunked HTTP/1.1 framing, set their own content type, and preserve
+Connection: close during graceful drain. Content-Length cannot override framing.
+
+Use synchronous `enqueue()` for event-bus producers. It returns false when closed
+or overflowing. The byte cap includes queued UTF-8 data and Node's unsent buffer.
+It defaults to 1 MiB for enqueue; `onOverflow: "disconnect"` aborts the signal and
+runs disconnect cleanup, while `"drop"` rejects the newest chunk so the producer
+can schedule a resync. Every drop increments controller.dropped, including drops
+from send/write/render/comments. write() still returns false only when ended or
+disconnected; true means ready to continue, so inspect dropped when using drop
+mode. A single event exceeding the byte cap is always rejected (and disconnects
+in the default overflow mode). Choosing maxQueuedBytes also bounds send/write/render and
+SSE comments; using enqueue switches subsequent writes on that controller into
+bounded mode. `drain()` waits for both queues. `end()` stops accepting new output
+and flushes already accepted queued output before ending. Without a byte cap or
+enqueue, send/write retain their existing behavior.
+
+Graceful HTTP/1 drain tracks raw responses, including hijacked replies. Before
+headers flush it adds Connection: close; already-streaming replies finish and
+then have their idle connections reaped. A hand-written hijacked writer that sets
+its own Connection header must preserve close during drain rather than overwrite
+it with keep-alive. Headers already on the wire cannot be changed.
+
+On HTTP/2, SSE and stream helpers omit connection-specific and Transfer-Encoding
+headers. Graceful drain sends GOAWAY and closes sessions once active streams finish;
+HTTP/1.1 keeps its existing Connection: close behavior. HTTP/1.0 uses close-delimited responses without Transfer-Encoding. The shutdown timeout still
+bounds a stream that never finishes.
+
+`http.serverOptions: { http2: true }` uses session draining by default. The
+framework maps idle-connection shutdown to session tracking on HTTP/2, so Fastify
+never receives its unsupported `forceCloseConnections: "idle"` setting.
+
+## Complete backpressure examples
+
+```ts title="src/app/events/controllers/events.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const eventsController: RequestHandler = async ({ response }) => {
+  const sse = response.sse({ retainEvents: 2 });
+  try {
+    for (const count of [1, 2, 3]) {
+      if (sse.signal.aborted || !(await sse.write("tick", { count }))) break;
+    }
+    await sse.drain();
+  } finally {
+    sse.end();
+  }
+};
+
+export const exportController: RequestHandler = async ({ response }) => {
+  const stream = response.stream("text/plain", { retainChunks: 1 });
+  try {
+    for (const line of ["id,name\n", "1,Anvil\n"]) {
+      if (stream.signal.aborted || !(await stream.write(line))) break;
+    }
+    await stream.drain();
+  } finally {
+    stream.end();
+  }
+};
+```
+
+Retention keeps only the requested tail in `response.body` for inspection; it
+is not a buffer to replay the whole stream. Neither controller's `signal`
+aborts on its normal `end()`.
+
+```ts title="src/app/catalog/services/require-product.service.ts"
+import { ResourceNotFoundError } from "@warlock.js/core/errors";
+
+export function requireProduct<T>(product: T | null | undefined): T {
+  if (product == null) throw new ResourceNotFoundError("Product not found");
+  return product;
+}
+```

package/skills/store-file/SKILL.md

@@ -12,11 +12,13 @@ description: 'Read/write/delete files via the `storage` singleton — disks, dri
 ```ts
 import { storage } from "@warlock.js/core";
 
+declare const buffer: Buffer; // file contents
+
 const file = await storage.put(buffer, "uploads/photo.jpg");
 
-console.log(file.url);     // public URL
-console.log(file.name);    // "photo.jpg"
-console.log(file.hash);    // sha256
+console.log(file.url); // public URL
+console.log(file.name); // "photo.jpg"
+console.log(file.hash); // sha256
 ```
 
 That's the entire surface for the common case. `storage.put(...)` writes to the default driver and returns a `StorageFile`.
@@ -78,6 +80,12 @@ The `storage` singleton (and any `storage.use(name)` scoped view) exposes the sa
 ### Writing
 
 ```ts
+import { createReadStream } from "node:fs";
+import { storage, type Request } from "@warlock.js/core";
+
+declare const buffer: Buffer; // file contents
+declare const request: Request; // the current request
+
 // From buffer
 const file = await storage.put(buffer, "uploads/photo.jpg");
 
@@ -88,20 +96,16 @@ await storage.put(buffer, "uploads/photo.jpg", {
 });
 
 // From stream (large files)
-import { createReadStream } from "node:fs";
 await storage.putStream(createReadStream("./video.mp4"), "uploads/video.mp4");
 
 // From a URL (downloads then stores)
 await storage.putFromUrl("https://example.com/image.jpg", "uploads/image.jpg");
 
 // From base64 data URL
-await storage.putFromBase64(
-  "data:image/png;base64,iVBORw0KGgo...",
-  "uploads/photo.png",
-);
+await storage.putFromBase64("data:image/png;base64,iVBORw0KGgo...", "uploads/photo.png");
 
 // From an UploadedFile (multipart upload)
-await storage.put(request.file("image"), "uploads/avatar.jpg");
+await storage.put(request.file("image")!, "uploads/avatar.jpg"); // validate the upload first
 ```
 
 Every `put*` returns a `StorageFile`.
@@ -119,8 +123,8 @@ const json = await storage.getJson("config/settings.json");
 ### Existence + metadata
 
 ```ts
-await storage.exists("uploads/photo.jpg");                  // boolean
-const info = await storage.metadata("uploads/photo.jpg");   // { size, mimeType, lastModified, ... }
+await storage.exists("uploads/photo.jpg"); // boolean
+const info = await storage.metadata("uploads/photo.jpg"); // { size, mimeType, lastModified, ... }
 const bytes = await storage.size("uploads/photo.jpg");
 ```
 
@@ -162,10 +166,26 @@ const files = await storage.list("uploads", { recursive: true, limit: 100 });
 ### URLs
 
 ```ts
-storage.url("uploads/photo.jpg");                        // public URL (sync)
-await storage.temporaryUrl("private/doc.pdf", 3600);     // signed URL, expires in seconds
+storage.url("uploads/photo.jpg"); // public URL (sync)
+await storage.temporaryUrl("private/doc.pdf", 3600); // signed URL, expires in seconds
 ```
 
+## Private-address check without the framework — `@warlock.js/core/net`
+
+`putFromUrl` refuses private, loopback, link-local and cloud-metadata hosts. Its classifier is also a side-effect-free subpath that loads only `node:net`, so workers, CLIs and standalone agent processes can reuse the rules without booting Core:
+
+```ts
+import { isPrivateOrReservedIp } from "@warlock.js/core/net";
+
+const address = "10.0.0.1";
+
+if (isPrivateOrReservedIp(address)) {
+  throw new Error(`Refusing private address ${address}`);
+}
+```
+
+Same function as the root `@warlock.js/core` export.
+
 ## Switching drivers — `storage.use(name)`
 
 For a single call against a non-default driver, scope it:
@@ -183,7 +203,25 @@ console.log(localFile.url);
 
 ## Cached image variants follow their source
 
-On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears the disk's whole derivative cache. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
+On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears that disk's derivative cache — or, when `uploads.images.cacheDirectory` is set (shared by every local disk), every disk's derivatives. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
+
+Give derivatives a dedicated cache folder, even when it sits beneath a storage root. Full and per-file purges delete recognized image, source-manifest and temporary files in the generated shard/source/generation layout; they retain directories, unrelated files and symlinks. Eviction validates the same directory layout; it may remove empty generated generation directories, while user folders and unrelated entries are never touched. Per-file purges and stale-generation pruning also reject symlinked shard/source directories. Pruning removes only recognized files from older generation-shaped folders, retaining current-generation files and unrelated entries. Reserve generated-looking paths for derivatives and reclaim files from older cache layouts manually.
+
+### Bound the cache and render remote disks
+
+Set `uploads.images.maxCacheBytes` (default `512 * 1024 * 1024`) and `maxCacheAge` (seconds, default seven days). Hits older than the age render again. A write schedules a coalesced background check, at most once per minute; hits never walk the cache. The check walks the cache only on the first check after boot, when the byte estimate is over budget, when the oldest retained derivative has expired, or once per `maxCacheAge`. The sweep removes expired derivatives and evicts oldest files to meet the byte budget, retaining the file being returned even when it alone exceeds that budget. It also removes writer temporaries older than an hour (left by a crashed write), and a generation directory left without derivatives loses its `source.json` and then the empty directory once it is older than five minutes, which reclaims old object-storage generations after ETag changes. The byte budget can be exceeded until the next sweep; idle caches are cleaned after the next generated derivative. Use `Number.MAX_SAFE_INTEGER` for a practically unbounded budget. Keep the cache on a local, writable filesystem outside `public/`; it must not equal or contain any configured local storage root, including runtime-registered disks. Generation and purge use the same guard and compare realpaths, including symlinked directories and existing ancestors of paths not yet created. An overlapping setting throws `ImageVariantsConfigError` before cache removal, as does a cache or root that cannot be resolved (`ENOTDIR`, `EACCES`, `ELOOP`; the original error is its `cause`). The guard result is remembered per cache, disk root and configured local roots; a newly registered disk is checked again.
+
+```ts
+import { createUploadedFileController, generateImageVariants, router } from "@warlock.js/core";
+
+router.get("/cloud-images/*", createUploadedFileController({ disk: "r2" }));
+const descriptor = await generateImageVariants("products/photo.jpg", {
+  disk: "r2",
+  urlPrefix: "/cloud-images",
+});
+```
+
+For an object-storage disk, `descriptor.src` is the driver's original URL; variant URLs use `/cloud-images` and its controller accepts variant queries only (an original request there returns 404). Selecting a remote disk explicitly opts that route into cloud serving; the default `uploadedFileController` continues to return 404 when the default disk is cloud. `createUploadedFileController({ remote: true })` opts into the default cloud disk. Protect a remote route before serving private derivatives: an unguarded route exposes every allowed image in that bucket/prefix, including originals otherwise served only through signed URLs. Use signed original URLs separately for private buckets. `resolveImageVariant` also accepts remote disks. Requests read source metadata; an ETag, size and last-modified date select the cached generation without downloading the source on a hit. Without an ETag, bytes are downloaded and hashed. Concurrent loads for the same disk/path/version are shared, bounded by `maxSourceBytes`, and ingest generation downloads once for all variants and formats. The default remote cache is `<app>/storage/.cache/image-variants`. Bucket identity and the effective storage prefix isolate cached sources. After remote deletion or moving, call `purgeImageVariants(path, { disk: "r2" })` yourself; age/size cleanup also reclaims those derivatives.
 
 ## `StorageFile` — the OOP handle
 
@@ -195,33 +233,33 @@ const file = storage.file("uploads/photo.jpg");
 
 ### Sync properties (no I/O)
 
-| Property         | Description                                    |
-| ---------------- | ---------------------------------------------- |
-| `file.path`      | full storage path (`"uploads/photo.jpg"`)      |
-| `file.name`      | basename (`"photo.jpg"`)                       |
-| `file.extension` | lowercased ext, no dot (`"jpg"`)               |
-| `file.directory` | parent directory                               |
-| `file.driver`    | driver name (`"local"` / `"s3"` / …)           |
-| `file.url`       | public URL (uses cached value if present)      |
-| `file.hash`      | sha256, set by `put*` operations               |
-| `file.isDeleted` | `true` after `file.delete()`                   |
+| Property         | Description                               |
+| ---------------- | ----------------------------------------- |
+| `file.path`      | full storage path (`"uploads/photo.jpg"`) |
+| `file.name`      | basename (`"photo.jpg"`)                  |
+| `file.extension` | lowercased ext, no dot (`"jpg"`)          |
+| `file.directory` | parent directory                          |
+| `file.driver`    | driver name (`"local"` / `"s3"` / …)      |
+| `file.url`       | public URL (uses cached value if present) |
+| `file.hash`      | sha256, set by `put*` operations          |
+| `file.isDeleted` | `true` after `file.delete()`              |
 
 ### Async data
 
 ```ts
-await file.data();        // full StorageFileData with size/mimeType/url/hash
+await file.data(); // full StorageFileData with size/mimeType/url/hash
 await file.size();
 await file.mimeType();
 await file.lastModified();
-await file.etag();        // cloud only
+await file.etag(); // cloud only
 ```
 
 ### Operations
 
 ```ts
-await file.copy("backups/photo.jpg");      // → new StorageFile at the copy
-await file.move("archive/photo.jpg");      // → returns this; path is updated in place
-await file.delete();                       // marks isDeleted
+await file.copy("backups/photo.jpg"); // → new StorageFile at the copy
+await file.move("archive/photo.jpg"); // → returns this; path is updated in place
+await file.delete(); // marks isDeleted
 const buffer = await file.contents();
 const stream = await file.stream();
 ```
@@ -279,20 +317,22 @@ await cloud.getRegion();
 Local storage signs URLs with an HMAC token (no presigned URL — there is no S3 here). Validate inbound tokens before serving:
 
 ```ts
-import { storage } from "@warlock.js/core";
+import { storage, type RequestHandler } from "@warlock.js/core";
 
-const result = await storage.validateTemporaryToken(token);
+export const temporaryFileController: RequestHandler = async ({ request, response }) => {
+  const result = await storage.validateTemporaryToken(String(request.input("token")));
 
-if (!result.valid) {
-  return response.forbidden({ error: result.error });
-}
+  if (!result.valid) {
+    return response.forbidden({ error: result.error });
+  }
 
-if (result.absolutePath) {
-  return response.sendFile(result.absolutePath);
-}
+  if (result.absolutePath) {
+    return response.sendFile(result.absolutePath);
+  }
 
-const stream = await result.getStream!();
-stream.pipe(response.raw);
+  const stream = await result.getStream!();
+  stream.pipe(response.raw);
+};
 ```
 
 Cloud drivers always return `{ valid: false }` from `validateTemporaryToken` — they validate via presigned URL on the cloud side.
@@ -319,16 +359,16 @@ await storage.use("tenant-s3").put(buffer, "data.csv");
 
 `storage.on(event, handler)` subscribes to lifecycle hooks. Event types:
 
-| Event          | Fires                              |
-| -------------- | ---------------------------------- |
-| `beforePut`    | before write                       |
-| `afterPut`     | after successful write             |
-| `beforeDelete` | before delete                      |
-| `afterDelete`  | after delete                       |
-| `beforeCopy`   | before copy                        |
-| `afterCopy`    | after copy                         |
-| `beforeMove`   | before move                        |
-| `afterMove`    | after move                         |
+| Event          | Fires                  |
+| -------------- | ---------------------- |
+| `beforePut`    | before write           |
+| `afterPut`     | after successful write |
+| `beforeDelete` | before delete          |
+| `afterDelete`  | after delete           |
+| `beforeCopy`   | before copy            |
+| `afterCopy`    | after copy             |
+| `beforeMove`   | before move            |
+| `afterMove`    | after move             |
 
 ```ts
 storage.on("afterPut", ({ location, file }) => {
@@ -378,10 +418,10 @@ export const uploadAvatarController: GuardedRequestHandler = async ({ request, r
 ### Direct browser upload via presigned URL
 
 ```ts
-const uploadUrl = await storage.use("r2").getPresignedUploadUrl(
-  `uploads/${userId}/${filename}`,
-  { expiresIn: 600, contentType: mimeType },
-);
+const uploadUrl = await storage.use("r2").getPresignedUploadUrl(`uploads/${userId}/${filename}`, {
+  expiresIn: 600,
+  contentType: mimeType,
+});
 
 return response.success({ uploadUrl });
 ```

package/skills/test-fakes/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: test-fakes
+description: 'The test fakes Warlock installs by default in the test environment — `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake` — and their assertions (`assertSent`, `assertPushed`, `assertHas`, `assertExists`, `travel`), plus how to opt out (`tests.fakes`, `setupTest({ fakes })`). Triggers: `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake`, `installTestFakes`, `restoreTestFakes`, `tests.fakes`, `FakeAssertionError`, `clock.now`, `ids.uuid`, `setDispatchInterceptor`; "assert an email was sent", "assert a job was dispatched", "freeze time in a test", "deterministic ids", "tests without Redis", "keep the real cache driver in tests". Typical import `import { mailFake, queueFake } from "@warlock.js/core/tests"`. Skip: HTTP request helpers — the `test-http` topic; fixtures — the `model-factories` topic.'
+---
+
+# Warlock — test fakes
+
+In the test environment six fakes are installed for you: `setupTest()` installs them in every test file once its connectors are up, `startHttpTestServer()` installs them in the shared server, and teardown restores them. Nothing is delivered, pushed to Redis, uploaded to a bucket, and time and ids are deterministic.
+
+| Fake          | Replaces                                                        |
+| ------------- | --------------------------------------------------------------- |
+| `mailFake`    | Mail delivery: `sendMail()` / `Mail` sends are captured         |
+| `queueFake`   | `@warlock.js/queue` dispatch: jobs are recorded, not pushed     |
+| `cacheFake`   | The cache's current driver: a fresh in-memory driver            |
+| `storageFake` | Every storage driver (local, S3, R2, Spaces): a temp directory  |
+| `clockFake`   | `clock` from `@warlock.js/core`: frozen at 2026-01-01T00:00:00Z |
+| `idsFake`     | `ids` from `@warlock.js/core`: numbered UUIDs and tokens        |
+
+## Assert what your code did
+
+```ts
+// with: import { cacheFake, mailFake, queueFake, storageFake } from "@warlock.js/core/tests";
+//       plus your job (buildReport) and service (requestReportService)
+beforeEach(() => {
+  mailFake.clear();
+  queueFake.clear();
+});
+
+it("queues the report, mails the requester and caches the request", async () => {
+  await requestReportService({ reportId: "r-1", email: "ada@example.test" });
+
+  mailFake.assertSent({ to: "ada@example.test", subject: /report requested/i });
+  mailFake.assertSentCount(1);
+  queueFake.assertPushed(buildReport, { reportId: "r-1" });
+  queueFake.assertNotPushed("reports.cleanup");
+  await cacheFake.assertHas("reports.r-1.status");
+  await storageFake.assertMissing("reports/r-1.pdf");
+});
+```
+
+- **mail** — `assertSent(matcher?)` returns the first match; `assertNotSent`, `assertSentCount(n, matcher?)`, `assertNothingSent()`, `sent(matcher?)`, `clear()`. Matcher: a predicate or `{ to, subject, from, contains }` (`to` matches to/cc/bcc, `subject` a string or RegExp, `contains` the HTML or text body).
+- **queue** — `assertPushed(jobOrName, payloadSubset?)`, `assertNotPushed`, `assertPushedCount(n, job?)`, `assertNothingPushed()`, `pushed(job?, matcher?)`. Each record has `id`, `name`, `queue`, `payload`, `options` (`delay`, `priority`, `jobId`) and `pushedAt`. An explicit `jobId` stays idempotent and `job.find(id)` answers from the record. Jobs are not run — call the handler to test it.
+- **cache** — `assertHas(key)`, `assertMissing(key)`, `assertStored(key, value)` (deep equality), `driver()`, `clear()`. TTLs, tags, namespaces and locks are the real memory driver's.
+- **storage** — `assertExists(path, driver?)`, `assertMissing(path, driver?)`, `files(driver?)`, `root()`. Each configured driver name gets a folder under one temp root, shared with the HTTP test server through `WARLOCK_TEST_STORAGE_ROOT`; the process that created it deletes it.
+- A failed assertion throws `FakeAssertionError` listing what was recorded.
+
+## Time and ids
+
+```ts
+import { clock, ids } from "@warlock.js/core";
+import { clockFake, idsFake } from "@warlock.js/core/tests";
+import { expect, it } from "vitest";
+
+it("is deterministic", () => {
+  expect(clock.now().toISOString()).toBe("2026-01-01T00:00:00.000Z");
+
+  clockFake.travel(90_000); // +1m30s
+  clockFake.travelTo("2030-05-05T10:00:00Z");
+
+  expect(ids.uuid()).toBe("00000000-0000-4000-8000-000000000001");
+  expect(ids.uuid()).toBe(idsFake.uuid(2));
+});
+```
+
+Only `clock` and `ids` are faked — `Date`, `setTimeout` and drivers keep real time, so nothing stalls. In app code, read time through `clock.now()` / `clock.timestamp()` and make identifiers with `ids.uuid()` / `ids.token(length)` wherever a test needs to control them; outside tests they are the system clock and `node:crypto`.
+
+## Where a fake records
+
+A fake records in the process that runs the code. A request served by the shared `startHttpTestServer()` runs in Vitest's main process, so its mail is captured there, not in your test. Serve it in the worker with `createTestHttpServer()` (the `test-http` topic) and the worker's fakes see it:
+
+```ts
+import { createTestHttpServer, mailFake } from "@warlock.js/core/tests";
+import { it } from "vitest";
+
+it("mails the requester", async () => {
+  const app = await createTestHttpServer({
+    loadAppModules: true,
+    importModule: (file) => import(file),
+  });
+
+  try {
+    await app.post("/reports", { reportId: "r-1", email: "ada@example.test" });
+    mailFake.assertSent({ to: "ada@example.test" });
+  } finally {
+    await app.close();
+  }
+});
+```
+
+## Opting out
+
+Precedence: the `fakes` option > `tests.fakes` in `src/config/tests.ts` > all on.
+
+```ts title="src/config/tests.ts"
+const testsConfigurations = {
+  fakes: { cache: false }, // keep the configured cache driver; `fakes: false` keeps every real driver
+};
+
+export default testsConfigurations;
+```
+
+```ts title="src/test-setup.ts"
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
+import { afterAll } from "vitest";
+
+await setupTest({ importModule: (file) => import(file), fakes: { storage: false } });
+
+afterAll(teardownTest);
+```
+
+An unknown fake name or a non-boolean value fails setup with the list of known fakes. Without `setupTest()`, call `installTestFakes(selection?)` / `restoreTestFakes()` yourself.
+
+## Gotchas
+
+- **Recorded state lives for the test file.** Call `clear()` in `beforeEach` when tests in one file must not see each other's mails or jobs.
+- **Real deliveries in tests need an opt-out.** A test that relied on a real SMTP sink, a Redis cache shared between the HTTP server and the workers, or a real bucket now gets the fake — set that fake to `false`.
+- **The queue seam is public.** `setDispatchInterceptor({ dispatch, find? })` from `@warlock.js/queue` replaces the broker for every job in the process; `queueFake` is built on it.
+
+## See also
+
+- The `test-service` topic — `setupTest()` and its lifecycle.
+- The `test-http` topic — `createTestHttpServer()` and the HTTP helpers.
+- The `model-factories` topic — deterministic fixtures.