@warlock.js/core 4.0.174 → 4.1.3

package/skills/send-response/SKILL.md

@@ -0,0 +1,245 @@
+---
+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`; "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 — `@warlock.js/core/create-controller/SKILL.md`; route registration — `@warlock.js/core/register-route/SKILL.md`; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.'
+---
+
+# Warlock — send a response
+
+`Response` is the helper-rich object passed to every controller. Pick the helper that matches the outcome — the helper carries the status code, so you almost never set one by hand.
+
+## The shape
+
+```ts
+import type { RequestHandler, Response } from "@warlock.js/core";
+
+export const myController: RequestHandler = async (request, response: Response) => {
+  // …choose a helper and return it
+  return response.success({ data: "…" });
+};
+```
+
+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          |
+
+```ts
+return response.success({ products: [...] });
+
+return response.successCreate({ product });
+
+return response.noContent();
+```
+
+`response.success()` (no argument) defaults to `{ success: true }` — useful for void operations that still need a body.
+
+## 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  |
+
+```ts
+return response.badRequest({ error: t("validation.invalid") });
+
+return response.unauthorized({ error: t("auth.invalidCredentials") });
+
+return response.forbidden({ error: t("permission.denied") });
+
+return response.notFound({ error: t("product.notFound") });
+
+return response.conflict({ error: t("product.duplicateSku") });
+```
+
+Most error helpers accept an optional payload — if you omit it, they send a default `{ error: "<status name>" }` shape.
+
+## Redirects
+
+```ts
+return response.redirect("/login");                    // 302
+return response.redirect("/new-home", 301);            // permanent
+```
+
+## Files
+
+```ts
+// stream a file from disk
+return response.sendFile("/abs/path/to/file.pdf");
+
+// cache for 1 year (default)
+return response.sendCachedFile("/abs/path/to/asset.css");
+
+// send a buffer with content type
+return response.sendBuffer(buffer, { contentType: "image/png" });
+```
+
+`SendFileOptions` lets you set `cacheTime`, `immutable`, `inline`, `filename` (download attachment name).
+
+## Streams
+
+```ts
+const stream = response.stream("text/plain");
+
+stream.send("first chunk\n");
+stream.send("second chunk\n");
+stream.end();
+```
+
+`response.stream(contentType?)` returns a controller with `.send(chunk)`, `.render(reactNode)`, `.end()`, and an `.ended` getter. Use for large dynamic payloads where buffering would blow memory. Calling `.send()` after `.end()` throws.
+
+## 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:
+
+```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
+} from "@warlock.js/core";
+
+throw new ResourceNotFoundError("product.notFound");
+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.
+
+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
+  return response.success({ product });
+};
+```
+
+See [`create-controller`](../create-controller/SKILL.md) for the "throw from service, return from controller" pattern.
+
+## Server-Sent Events
+
+```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.end();
+```
+
+`response.sse()` returns a controller with `send(event, data, id?)`, `comment(text)`, `end()`, `onDisconnect(handler)`, and an `.ended` getter. The `send` signature is positional — `event` name first, then the `data` payload (JSON-stringified for you), then an optional event `id`. After the client disconnects, `send`/`comment` become silent no-ops and any `onDisconnect` handlers fire — register cleanup there:
+
+```ts
+const sse = response.sse();
+const listener = (chunk: string) => sse.send("chunk", { chunk });
+
+eventBus.on(messageId, listener);
+sse.onDisconnect(() => eventBus.off(messageId, listener));
+```
+
+Browsers consume SSE via `new EventSource(url)`. Cheaper than websockets when you only need server-to-client push.
+
+## Setting headers and cookies
+
+```ts
+response.header("X-Total-Count", "42");
+
+// JSON-wrapped (default) — round-trips with request.cookie("prefs")
+response.cookie("prefs", { theme: "dark" }, { httpOnly: true });
+
+// Plain string — use raw: true for session tokens / opaque IDs that
+// shouldn't be JSON-quoted on the wire
+response.cookie("session_id", "abc.def.ghi", { raw: true, httpOnly: true });
+
+response.clearCookie("session_id");
+```
+
+`response.cookie()` JSON-stringifies the value by default so structured cookies round-trip cleanly with `request.cookie(name)`. Pass `{ raw: true }` to skip the wrapping for plain-string cookies (session tokens, opaque IDs, simple flags). The new `CookieOptions` type extends Fastify's `CookieSerializeOptions` with the `raw` flag.
+
+These mutate the response in place; chain or call before the final `return response.<helper>()`.
+
+## Common patterns
+
+### Localized error
+
+```ts
+import { t } from "@warlock.js/core";
+
+if (!result) {
+  return response.unauthorized({ error: t("auth.invalidCredentials") });
+}
+
+return response.success(result);
+```
+
+### Created with link header
+
+```ts
+const product = await createProductService(request.validated());
+
+response.header("Location", `/products/${product.id}`);
+
+return response.successCreate({ product });
+```
+
+### Streaming an LLM reply
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const stream = response.stream("text/event-stream");
+const streamedAgent = await myAgent.stream(request.input("message"));
+
+for await (const event of streamedAgent.events) {
+  if (event.type === "text-delta") {
+    stream.send(`data: ${JSON.stringify({ delta: event.text })}\n\n`);
+  }
+}
+
+stream.end();
+```
+
+(For the agent surface itself, see `@warlock.js/ai/skills/subskills/agent.md`.)
+
+### Replaying a cached response
+
+For cache-pattern middleware (idempotency, response cache) that needs to send a previously-captured response without re-running the controller:
+
+```ts
+return response.header("X-Cache", "HIT").replay({
+  status: cached.status,
+  body: cached.body,
+  contentType: cached.contentType,
+  headers: cached.extraHeaders,
+});
+```
+
+`replay()` sets the status, content-type, and extra headers, then calls `send(body)` so the full event lifecycle still fires — cross-cutting observers (logger, metrics) stay consistent between fresh and replayed responses. Built-in `middleware.idempotency` and `middleware.cache` use this internally; reach for it when writing your own cache-pattern middleware.
+
+## Gotchas
+
+- **Don't manually set the status code.** Use the matching helper. `response.send(...)` with a hand-rolled status loses error-handler integration.
+- **Don't call multiple helpers.** First helper wins; subsequent calls log a "response already sent" warning.
+- **Cookie options vary by environment.** Set `secure: Application.isProduction` so cookies work in dev (HTTP) and prod (HTTPS) without changing code.
+- **Streaming and SSE consume the response.** No `response.success(...)` afterward — call `stream.end()` / `sse.end()` to finish.
+
+## See also
+
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — what calls `response.<helper>()` from.
+- [`register-route/SKILL.md`](../register-route/SKILL.md) — wiring the controller to a URL.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — when to use HTTP error helpers vs `throw`.

package/skills/store-file/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: store-file
+description: 'Read/write/delete files via the `storage` singleton — disks, drivers (local/S3/R2/DO Spaces), `storage.use(name)`, `StorageFile` handles, presigned URLs. Triggers: `storage.put`, `storage.get`, `storage.use`, `StorageFile`, `storageConfigurations`, `getPresignedUrl`, `getPresignedUploadUrl`; "save an uploaded file", "switch between local and S3", "generate a presigned URL", "read file metadata"; typical import `import { storage } from "@warlock.js/core"`. Skip: multipart parsing + image chain — `@warlock.js/core/upload-file/SKILL.md`; image transforms — `@warlock.js/core/process-image/SKILL.md`; storage config shape — `@warlock.js/core/configure-app/SKILL.md`; competing libs `@aws-sdk/client-s3`, `multer`, `formidable`.'
+---
+
+# Warlock — store a file
+
+`storage` is a singleton manager that wraps one or more drivers. Each driver lives behind a name (`"local"`, `"s3"`, `"r2"`, `"spaces"`). Calls go to the active driver by default; `storage.use("name")` returns a scoped view. Every write returns a `StorageFile` — a thin OOP wrapper with rich properties (`name`, `url`, `hash`, `size`) and chainable methods (`copy`, `move`, `delete`).
+
+## The shape
+
+```ts
+import { storage } from "@warlock.js/core";
+
+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
+```
+
+That's the entire surface for the common case. `storage.put(...)` writes to the default driver and returns a `StorageFile`.
+
+## Configuration
+
+`src/config/storage.ts` declares the disks. Each entry under `drivers` uses one of four built-in driver factories:
+
+```ts title="src/config/storage.ts"
+import {
+  env,
+  type StorageConfigurations,
+  storageConfigurations,
+  storagePath,
+} from "@warlock.js/core";
+
+const storageOptions: StorageConfigurations = {
+  default: "local",
+  drivers: {
+    local: storageConfigurations.local({
+      root: storagePath(),
+      urlPrefix: "/uploads",
+    }),
+    aws: storageConfigurations.aws({
+      accessKeyId: env("AWS_ACCESS_KEY_ID"),
+      secretAccessKey: env("AWS_SECRET_ACCESS_KEY"),
+      region: env("AWS_REGION"),
+      bucket: env("AWS_S3_BUCKET"),
+      urlPrefix: "/uploads",
+    }),
+    r2: storageConfigurations.r2({
+      bucket: env("R2_BUCKET"),
+      endpoint: env("R2_ENDPOINT"),
+      accessKeyId: env("R2_ACCESS_KEY_ID"),
+      secretAccessKey: env("R2_SECRET_ACCESS_KEY"),
+      accountId: env("R2_ACCOUNT_ID"),
+      region: env("R2_REGION", "auto"),
+      publicDomain: env("R2_BASE_URL"),
+    }),
+    spaces: storageConfigurations.spaces({
+      accessKeyId: env("DO_KEY"),
+      secretAccessKey: env("DO_SECRET"),
+      region: env("DO_REGION"),
+      bucket: env("DO_BUCKET"),
+      endpoint: env("DO_ENDPOINT"),
+    }),
+  },
+};
+
+export default storageOptions;
+```
+
+`default` names the disk used when callers don't specify one. The factories (`storageConfigurations.local|aws|r2|spaces`) just stamp the `driver` field on the options object — pass whatever the driver supports.
+
+## File operations
+
+The `storage` singleton (and any `storage.use(name)` scoped view) exposes the same operations:
+
+### Writing
+
+```ts
+// From buffer
+const file = await storage.put(buffer, "uploads/photo.jpg");
+
+// With explicit metadata
+await storage.put(buffer, "uploads/photo.jpg", {
+  mimeType: "image/jpeg",
+  cacheControl: "max-age=31536000",
+});
+
+// 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",
+);
+
+// From an UploadedFile (multipart upload)
+await storage.put(request.file("image"), "uploads/avatar.jpg");
+```
+
+Every `put*` returns a `StorageFile`.
+
+### Reading
+
+```ts
+const buffer = await storage.get("uploads/photo.jpg");
+const stream = await storage.getStream("uploads/video.mp4");
+const json = await storage.getJson("config/settings.json");
+```
+
+`get()` loads the whole file into memory. Use `getStream()` for anything > a few MB.
+
+### Existence + metadata
+
+```ts
+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");
+```
+
+### Delete / copy / move
+
+```ts
+await storage.delete("uploads/photo.jpg");
+await storage.deleteMany(["a.txt", "b.txt", "c.txt"]);
+await storage.copy("uploads/photo.jpg", "backups/photo.jpg");
+await storage.move("uploads/temp.jpg", "uploads/photo.jpg");
+```
+
+Directory operations:
+
+```ts
+await storage.copyDirectory("uploads/temp", "uploads/final");
+await storage.moveDirectory("uploads/temp", "uploads/final");
+await storage.emptyDirectory("uploads/temp");
+await storage.deleteDirectory("uploads/temp");
+```
+
+### Listing
+
+```ts
+const files = await storage.list("uploads", { recursive: true, limit: 100 });
+// → StorageFileInfo[]
+```
+
+### URLs
+
+```ts
+storage.url("uploads/photo.jpg");                        // public URL (sync)
+await storage.temporaryUrl("private/doc.pdf", 3600);     // signed URL, expires in seconds
+```
+
+## Switching drivers — `storage.use(name)`
+
+For a single call against a non-default driver, scope it:
+
+```ts
+const r2File = await storage.use("r2").put(buffer, "exports/data.csv");
+const localFile = await storage.use("local").put(buffer, "tmp/preview.jpg");
+
+// Both return StorageFile with identical API
+console.log(r2File.url);
+console.log(localFile.url);
+```
+
+`storage.use(name)` returns a `ScopedStorage` with the same surface as `storage`. To change the default permanently, call `storage.setDefault(name)` — but you almost always want per-call scoping for clarity.
+
+## `StorageFile` — the OOP handle
+
+Every `put*`/`copy`/`move` returns a `StorageFile`. You can also build one for an existing path:
+
+```ts
+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()`                   |
+
+### Async data
+
+```ts
+await file.data();        // full StorageFileData with size/mimeType/url/hash
+await file.size();
+await file.mimeType();
+await file.lastModified();
+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
+const buffer = await file.contents();
+const stream = await file.stream();
+```
+
+`file.copy(dest)` returns a fresh `StorageFile` for the copy. `file.move(dest)` (and `file.rename(name)`) mutate the receiver — they rewrite `this._path`, refresh the cached data, and return the same instance. The handle stays valid at its new location.
+
+## Cloud-only operations
+
+Some methods only work against cloud drivers (`s3`, `r2`, `spaces`). Calling them on `local` throws.
+
+### Presigned URLs (direct upload/download)
+
+```ts
+const downloadUrl = await storage.getPresignedUrl("private/doc.pdf", {
+  expiresIn: 3600, // seconds
+});
+
+const uploadUrl = await storage.getPresignedUploadUrl("uploads/file.pdf", {
+  expiresIn: 3600,
+  contentType: "application/pdf",
+});
+
+// Client can PUT directly to uploadUrl, bypassing your server
+```
+
+For these you usually scope to a specific cloud disk:
+
+```ts
+const url = await storage.use("r2").getPresignedUrl(path, { expiresIn: 600 });
+```
+
+### Visibility + storage class
+
+```ts
+await storage.setVisibility("uploads/photo.jpg", "public");
+await storage.setVisibility("private/doc.pdf", "private");
+const v = await storage.getVisibility("uploads/photo.jpg");
+
+await storage.setStorageClass("archive/old.zip", "GLACIER");
+```
+
+### Cloud driver helper
+
+For cloud-only chains, get the typed cloud interface:
+
+```ts
+const cloud = storage.useCloud("s3");
+await cloud.getPresignedUrl("private/doc.pdf");
+await cloud.getBucket();
+await cloud.getRegion();
+```
+
+## Temporary URLs on the local driver
+
+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";
+
+const result = await storage.validateTemporaryToken(token);
+
+if (!result.valid) {
+  return response.forbidden({ error: result.error });
+}
+
+if (result.absolutePath) {
+  return response.sendFile(result.absolutePath);
+}
+
+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.
+
+## Runtime driver registration
+
+For multi-tenancy or runtime config, register a driver after boot:
+
+```ts
+storage.register("tenant-s3", {
+  driver: "s3",
+  bucket: tenant.bucket,
+  region: tenant.region,
+  accessKeyId: tenant.key,
+  secretAccessKey: tenant.secret,
+});
+
+await storage.use("tenant-s3").put(buffer, "data.csv");
+```
+
+`storage.register(name, config)` clears any cached instance for that name, so the next access rebuilds with the new config.
+
+## Events
+
+`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                         |
+
+```ts
+storage.on("afterPut", ({ location, file }) => {
+  console.log(`uploaded ${file?.size} bytes to ${location}`);
+});
+
+storage.on("afterDelete", ({ location }) => {
+  analytics.track("file_deleted", { path: location });
+});
+```
+
+## Common patterns
+
+### Switching disk per env
+
+```ts title="src/config/storage.ts"
+const storageOptions: StorageConfigurations = {
+  default: env("STORAGE_DRIVER", "local"),
+  drivers: {
+    local: storageConfigurations.local({ root: storagePath(), urlPrefix: "/uploads" }),
+    r2: storageConfigurations.r2({ ... }),
+  },
+};
+```
+
+Set `STORAGE_DRIVER=r2` in production, leave unset in dev — same code uses local files in dev and R2 in prod.
+
+### Uploading a request file
+
+```ts
+import type { RequestHandler, Response } from "@warlock.js/core";
+import { storage } from "@warlock.js/core";
+
+export const uploadAvatarController: RequestHandler = async (request, response: Response) => {
+  const upload = request.file("avatar");
+  const file = await storage.put(upload, `avatars/${request.user.id}/${upload.fileName}`);
+
+  return response.successCreate({ url: file.url, hash: file.hash });
+};
+```
+
+### Direct browser upload via presigned URL
+
+```ts
+const uploadUrl = await storage.use("r2").getPresignedUploadUrl(
+  `uploads/${userId}/${filename}`,
+  { expiresIn: 600, contentType: mimeType },
+);
+
+return response.success({ uploadUrl });
+```
+
+Client `PUT`s the bytes straight to R2 — your server never sees them.
+
+## Gotchas
+
+- **`storage` is the lowercase singleton.** Don't `new Storage()` — there's no point, and configuration won't reach it.
+- **`storage.path(location)` only works on the local driver.** Calls on cloud drivers throw. Check the driver if you don't control it.
+- **`StorageFile.move()` mutates the receiver and returns it.** After `await file.move(dest)`, `file.path` now points at `dest` — the same instance stays live (unlike the manager's `storage.move(from, to)`, which returns a fresh `StorageFile`). `file.copy(dest)`, by contrast, leaves the receiver untouched and returns a new handle.
+- **Local URLs are relative (`/uploads/...`).** Prefix with `baseUrl` from `config.get("app").baseUrl` if you need absolute. Cloud drivers return absolute URLs.
+- **Presigned uploads enforce content-type at the cloud side.** Mismatched `contentType` between the presigned URL and the actual upload returns 403 from the cloud — match exactly.
+- **Driver name keys are case-sensitive** — `"r2"`, not `"R2"`. Match what's in `src/config/storage.ts`.
+
+## See also
+
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/storage.ts` shape and `env()` patterns.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — module layout for upload flows (`src/app/uploads/`).
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — `response.sendFile(absPath)` for serving local files.