@warlock.js/core 4.0.174 → 4.1.2

package/skills/build-url/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: build-url
+description: 'HTTP URL helpers — `url`, `publicUrl`, `assetsUrl`, `uploadsUrl`, anchored at `app.baseUrl`. Use to render `src` / `href` / API URLs in resources and responses. `setBaseUrl` is wired by the HTTP connector from `config.get("app.baseUrl")`. Triggers: `url`, `publicUrl`, `assetsUrl`, `uploadsUrl`, `setBaseUrl`, `BASE_URL`; "render an avatar src URL", "absolute download link", "embed asset URL in email", "URL helpers vs path helpers"; typical import `import { url, publicUrl, uploadsUrl } from "@warlock.js/core"`. Skip: filesystem paths — `@warlock.js/core/resolve-path/SKILL.md`; signed CDN URLs — `@warlock.js/core/store-file/SKILL.md`; resource output — `@warlock.js/core/define-resource/SKILL.md`; competing patterns: hand-rolled `${baseUrl}/...` template strings.'
+---
+
+# Warlock — build a URL
+
+Path helpers ([`resolve-path/SKILL.md`](../resolve-path/SKILL.md)) give you absolute filesystem paths. URL helpers give you absolute HTTP URLs. Different jobs, often confused.
+
+Use URL helpers whenever you need to render a string that goes into a browser, an HTTP client, or an email — `<img src=...>`, `<a href=...>`, an API response that includes a download link, a webhook payload.
+
+## The shape
+
+```ts
+import { url, publicUrl, assetsUrl, uploadsUrl } from "@warlock.js/core";
+
+url();                       // → "http://localhost:3000"
+url("/health");              // → "http://localhost:3000/health"
+
+publicUrl("favicon.ico");    // → "http://localhost:3000/public/favicon.ico"
+assetsUrl("logo.png");       // → "http://localhost:3000/public/assets/logo.png"
+uploadsUrl("avatars/42.png"); // → "http://localhost:3000/uploads/avatars/42.png"
+```
+
+Every helper resolves against the **base URL** the HTTP connector set at boot.
+
+## Setting the base URL
+
+`setBaseUrl(url)` is wired automatically — the HTTP connector reads `app.baseUrl` from config and sets it during boot:
+
+```ts title="src/config/app.ts"
+import type { AppConfigurations } from "@warlock.js/core";
+import { env } from "@warlock.js/core";
+
+const appConfigurations: AppConfigurations = {
+  appName: env("APP_NAME", "Mongez"),
+  baseUrl: env("BASE_URL", "http://localhost:3000"),
+  // ...
+};
+
+export default appConfigurations;
+```
+
+The env var `BASE_URL` controls the deployed base. In production, set it to `https://api.example.com` (or whatever the deployed host is). In dev, `http://localhost:3000` is the default.
+
+You can also call `setBaseUrl` manually if you need to override at runtime — but in normal app code, the HTTP connector handles this; you don't touch it.
+
+```ts
+import { setBaseUrl } from "@warlock.js/core";
+
+setBaseUrl("https://cdn.example.com");
+// → every subsequent url() / publicUrl() / assetsUrl() / uploadsUrl() uses this
+```
+
+## Full inventory
+
+| Helper                | Resolves to                              | Use for                                     |
+| --------------------- | ---------------------------------------- | ------------------------------------------- |
+| `url(path?)`          | `<baseUrl>/<path>`                       | Arbitrary absolute URL on the same host.    |
+| `publicUrl(path?)`    | `<baseUrl>/public/<path>`                | Files served out of the `public/` folder.   |
+| `assetsUrl(path?)`    | `<baseUrl>/public/assets/<path>`         | Assets inside `public/assets/`.             |
+| `uploadsUrl(path?)`   | `<baseUrl>/uploads/<path>`               | User-uploaded files served over HTTP.       |
+| `setBaseUrl(url)`     | (sets the anchor for all of the above)   | Override at runtime — rarely needed.        |
+
+`assetsUrl` is just `publicUrl` with `assets/` prepended — they share the same `/public/` mount point.
+
+`url(path)` is the escape hatch — it composes the base URL with any path you give it, no convention enforced. Use it for one-off URLs that don't fit `public` / `uploads`.
+
+## URL helpers vs. path helpers
+
+The most common confusion. They look related but resolve completely differently:
+
+| Goal                                          | Helper            | Returns                                     |
+| --------------------------------------------- | ----------------- | ------------------------------------------- |
+| **Read** a file from the filesystem           | `uploadsPath(...)` | `<cwd>/storage/uploads/<path>` (filesystem) |
+| **Render** an `<img src>` for the same file   | `uploadsUrl(...)`  | `<baseUrl>/uploads/<path>` (HTTP URL)       |
+| **Write** to public folder                    | `publicPath(...)`  | `<cwd>/public/<path>` (filesystem)          |
+| **Embed** an asset URL in a response          | `publicUrl(...)`   | `<baseUrl>/public/<path>` (HTTP URL)        |
+
+Pick by the consumer:
+
+- **Filesystem read/write code** (services that read templates, scripts that copy files) → path helpers.
+- **API responses, HTML, emails** (anything the browser or an HTTP client sees) → URL helpers.
+
+## Patterns
+
+### Render an avatar URL in a resource
+
+```ts title="src/app/users/resources/user.resource.ts"
+import { defineResource, uploadsUrl } from "@warlock.js/core";
+
+export const UserResource = defineResource({
+  schema: {
+    id: "string",
+    email: "string",
+    // `uploadsUrl` cast joins the stored path with the base URL automatically
+    avatarUrl: ["avatar_path", "uploadsUrl"],
+  },
+});
+```
+
+The stored value (`avatars/42.png`) is the filesystem-relative key — relative to `storage/uploads/`. The `uploadsUrl` cast renders the full URL by joining it with the base URL. For conditional logic (e.g. fall back to `null` when there's no avatar), use a resolver function instead:
+
+```ts
+export const UserResource = defineResource({
+  schema: {
+    id: "string",
+    email: "string",
+    avatarUrl: function (_value, resource) {
+      const path = resource.get("avatar_path"); // e.g. "avatars/42.png"
+
+      return path ? uploadsUrl(path) : null;
+    },
+  },
+});
+```
+
+### Asset URL in an HTML email
+
+```tsx title="src/app/users/emails/welcome.email.tsx"
+import { assetsUrl } from "@warlock.js/core";
+import { Body, Container, Html, Img } from "@react-email/components";
+
+export function WelcomeEmail() {
+  return (
+    <Html>
+      <Body>
+        <Container>
+          <Img src={assetsUrl("logo.png")} alt="Logo" />
+          <h1>Welcome!</h1>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+```
+
+Email clients can't reach `localhost` — make sure `BASE_URL` is the public host before sending production mail. Otherwise the `src` resolves to `http://localhost:3000/...` and recipients see broken images.
+
+### Absolute API URL in a webhook payload
+
+```ts
+await sendWebhook({
+  url: vendor.callback_url,
+  payload: {
+    order_id: order.id,
+    receipt_url: url(`/orders/${order.id}/receipt`),  // → "https://api.example.com/orders/42/receipt"
+  },
+});
+```
+
+The receiver needs the full URL — they'll never see your `Host` header to deduce the rest.
+
+### Override per-request for a multi-tenant CDN
+
+```ts
+// Inside a request handler that needs a tenant-specific URL prefix
+const tenantCdn = `https://${tenant.slug}.cdn.example.com`;
+const fullUrl = `${tenantCdn}/uploads/${path}`;
+```
+
+Don't call `setBaseUrl` per request — it's process-global and races every other request. Build the URL manually with template strings instead.
+
+## Gotchas
+
+- **`setBaseUrl` is process-global.** Calling it inside a request handler changes the URL for **every** in-flight request. The HTTP connector sets it once on boot — leave it alone in app code.
+- **No host detection from the request.** These helpers don't read `request.host` / `X-Forwarded-Host`. They use the configured `app.baseUrl` only. If your app sits behind a reverse proxy and you need the actual host the user typed, read it from the request directly.
+- **Trailing slashes are stripped from the base, leading slashes from the path.** `url("/foo")` and `url("foo")` both return `<base>/foo`. Don't bother double-checking the slash.
+- **`uploadsUrl` doesn't know about `uploads.root` overrides.** Even if your filesystem is mounted at `/mnt/uploads`, the URL stays `<baseUrl>/uploads/<path>` — that's the HTTP route the framework serves uploads from. The two are decoupled by design.
+- **`publicUrl` vs `assetsUrl`.** `publicUrl("logo.png")` resolves to `/public/logo.png`; `assetsUrl("logo.png")` to `/public/assets/logo.png`. Convention is: framework assets go in `public/assets/`, ad-hoc files (favicon.ico, robots.txt) at `public/` root.
+- **The `baseUrl` config is read once at HTTP-connector boot.** Changing the config after boot doesn't update the cached value — either restart, or call `setBaseUrl` manually (with the global-state caveat above).
+- **Email + localhost = broken links.** Always use a public host in `BASE_URL` for environments that send mail. Production should never have `localhost` in there.
+
+## See also
+
+- [`resolve-path/SKILL.md`](../resolve-path/SKILL.md) — filesystem path helpers (`uploadsPath`, `publicPath`, ...). Use for read/write; use the URL helpers for rendering.
+- [`store-file/SKILL.md`](../store-file/SKILL.md) — the `storage.url(path)` driver method, which can produce signed CDN URLs for non-local drivers (S3 etc.). Use that over `uploadsUrl` when you're on a remote driver.
+- [`upload-file/SKILL.md`](../upload-file/SKILL.md) — the `UploadedFile` lifecycle; where the path that feeds `uploadsUrl` comes from.
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — the `url` / `uploadsUrl` / `storageUrl` casts (and resolver functions) are the right place to call URL helpers.
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/app.ts` and the `baseUrl` env wiring.

package/skills/configure-app/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: configure-app
+description: 'Configure a Warlock app — the two layers (`warlock.config.ts` for framework-level wiring, `src/config/*.ts` for subsystems), `.env` + `env()`, and the `config()` getter for runtime reads. Triggers: `defineConfig`, `config.get`, `config.key`, `env`, `ConfigRegistry`, `HttpConfigurations`, `AppConfigurations`; "add a new config file", "warlock.config.ts vs src/config", "read env values", "runtime config lookup"; typical import `import { defineConfig, config, env } from "@warlock.js/core"`. Skip: cache driver registration — `@warlock.js/cache/cache-basics/SKILL.md`; mail config — `@warlock.js/core/send-mail/SKILL.md`; storage config — `@warlock.js/core/store-file/SKILL.md`; competing libs `dotenv` direct, `convict`, `node-config`.'
+---
+
+# Warlock — configure the app
+
+Two config layers, one source of env, one read API. Get those four mental model bits straight and the rest is filing.
+
+## The shape
+
+**Layer 1 — framework wiring.** One file at the project root: `warlock.config.ts`. Exports a `defineConfig({...})` call. Governs the bootstrap/server/build/devServer/cli/database hooks.
+
+**Layer 2 — subsystem config.** One file per subsystem in `src/config/<name>.ts`. Each file `export default` a typed config object. Auto-loaded; registered under the file's basename (`http.ts` → `config.get("http")`).
+
+```ts title="warlock.config.ts"
+import { authMigrations, registerAuthCleanupCommand } from "@warlock.js/auth";
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: {
+    healthCheckers: false,
+    generateTypings: false,
+  },
+  cli: {
+    commands: [registerAuthCleanupCommand()],
+  },
+  build: {
+    minify: true,
+  },
+  database: {
+    migrations: authMigrations,
+  },
+});
+```
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+import { Application, env } from "@warlock.js/core";
+
+const httpConfigurations: HttpConfigurations = {
+  port: env("HTTP_PORT", 3000),
+  host: env("HTTP_HOST", "localhost"),
+  log: true,
+  fileUploadLimit: 12 * 1024 * 1024 * 1024,
+  rateLimit: {
+    max: 260,
+    duration: 60 * 1000,
+  },
+  cors: {
+    origin: "*",
+    methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+  },
+  cookies: {
+    secret: env("COOKIE_SECRET", "super-secret-key-change-me"),
+    options: {
+      httpOnly: true,
+      secure: Application.isProduction,
+      path: "/",
+    },
+  },
+};
+
+export default httpConfigurations;
+```
+
+## Which layer holds what
+
+| Setting                                                | Layer                          |
+| ------------------------------------------------------ | ------------------------------ |
+| Build/bundler options (minify, sourcemap, outFile)     | `warlock.config.ts > build`    |
+| Dev server (HMR scope, health checkers, typings)       | `warlock.config.ts > devServer`|
+| Package migrations (external `@warlock.js/*` packages) | `warlock.config.ts > database` |
+| CLI commands (registered via `warlock <cmd>`)          | `warlock.config.ts > cli`      |
+| HTTP server tuning per env (port, host, retry)         | `warlock.config.ts > server`   |
+| HTTP runtime (CORS, cookies, rate limits, upload size) | `src/config/http.ts`           |
+| App identity (name, baseUrl, timezone, locales)        | `src/config/app.ts`            |
+| Subsystem configs (auth, mail, storage, cache, ai, …)  | `src/config/<name>.ts`         |
+
+Heuristic: if the setting changes how the framework **boots, builds, or scaffolds**, it goes in `warlock.config.ts`. If it changes how a **subsystem behaves at runtime**, it goes in `src/config/`.
+
+## `.env` and `env()`
+
+`env(key, default?)` reads from `process.env` and **auto-coerces** known shapes:
+
+- `"true"` / `"false"` → `boolean`
+- Numeric strings → `number`
+- Falls back to the `default` argument when unset
+
+```ts
+import { env } from "@warlock.js/core";
+
+env("HTTP_PORT", 3000);             // number
+env("CACHE_LOGGING", false);        // boolean
+env("BASE_URL", "http://localhost:3000"); // string
+env("REDIS_URL");                   // undefined if unset
+```
+
+`env` is re-exported from `@warlock.js/core` (sourced from `@mongez/dotenv`). Use this — not `process.env.X` — so callers consistently get coerced values.
+
+`.env.local` overrides `.env`. Project ships a `.env.example` listing the keys.
+
+## Reading config at runtime — `config()`
+
+`config` has two methods. Both accept a default:
+
+```ts
+import { config } from "@warlock.js/core";
+
+// Whole group — typed by ConfigRegistry augmentation
+const http = config.get("http");
+const httpPort = http.port;
+
+// Dot-notation key
+const port = config.key<number>("http.port", 3000);
+const baseUrl = config.key("app.baseUrl");
+```
+
+Use `config.get("name")` when you need the whole subsystem object; `config.key("a.b.c")` for a single value.
+
+The `ConfigRegistry` interface is augmented by generated typings — once you add `src/config/foo.ts` and rerun typings, `config.get("foo")` autocompletes. Until then, pass an explicit generic.
+
+## Anatomy of a `src/config/<name>.ts`
+
+1. Import the typed shape (`HttpConfigurations`, `AppConfigurations`, `CacheConfigurations<DriverNames>`, `MailConfigurations`, `StorageConfigurations`, …) from `@warlock.js/core` (or `@warlock.js/cache` for cache).
+2. Build the object, typed as that shape — TS will surface missing keys.
+3. Pull values from `env(...)` where they belong in `.env`. Hard-code immutable choices.
+4. `export default` the object.
+
+That's the contract. Filename → config key. No registration, no manifest, no side effects.
+
+## Special handlers
+
+Some subsystems need to do extra work when their config loads (e.g. set the active locale, register a driver). Those have a special handler attached internally — for the most part you don't see them. The takeaway: changing a config file at dev time fires the handler again automatically.
+
+## Multi-file or conditional config
+
+A config file is just a TS module. Branch on `env(...)` if production should differ from development:
+
+```ts title="src/config/storage.ts"
+import {
+  env,
+  type StorageConfigurations,
+  storageConfigurations,
+  storagePath,
+} from "@warlock.js/core";
+
+const storageOptions: StorageConfigurations = {
+  default: env("STORAGE_DRIVER", "local"),
+  drivers: {
+    local: storageConfigurations.local({
+      root: storagePath(),
+      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"),
+    }),
+  },
+};
+
+export default storageOptions;
+```
+
+Same shape — TS validates the union; runtime picks the `default` key.
+
+## Per-env knobs
+
+For one-off switches gated on environment, the canonical pattern is `Application.isProduction` (also `isDevelopment`, `isTest`):
+
+```ts
+import { Application } from "@warlock.js/core";
+
+const config = {
+  cookies: {
+    secure: Application.isProduction,
+  },
+};
+```
+
+Avoid scattering `process.env.NODE_ENV === "production"` checks — they don't get the same default-handling.
+
+## Common patterns
+
+### Adding a new subsystem
+
+1. Create `src/config/<name>.ts` exporting a default object.
+2. (Optional) Augment `ConfigRegistry` in a `.d.ts` if you want `config.get("<name>")` to autocomplete.
+3. Read it where needed: `config.get("<name>")` or `config.key("<name>.field")`.
+
+That's the whole flow. No barrel, no register call.
+
+### Per-tenant config
+
+For multi-tenancy, don't put per-tenant values in `src/config/`. Resolve at runtime from the tenant context and pass into the subsystem's per-call options (e.g. `Mail.config(tenant.mailSettings)`).
+
+### Package config
+
+Internal `@warlock.js/*` packages read from `config.get("<name>")` the same way app code does. When wiring a package config (e.g. `src/config/cache.ts`), the package surface (`cache.init()`) reads the registered values on boot.
+
+## Gotchas
+
+- **One `default` export per config file.** Anything else won't be picked up. A named export is invisible to the loader.
+- **`env(key)` returns the env value coerced, not the literal string.** `env("HTTP_LOG")` returns `true`/`false`, not `"true"`. Type the default to match.
+- **Don't mutate `config` at runtime.** It's read-only by convention. For dynamic overrides, fold into the call-site options (e.g. `cache.set(key, val, { driver: "redis" })`).
+- **`Application.isProduction` is preferred over `process.env.NODE_ENV` checks** in config files — same source, but it survives `setEnvironment(...)` and reads consistently.
+- **`warlock.config.ts` is the boot config; `src/config/` is the runtime config.** Putting runtime tuning into `warlock.config.ts` doesn't crash but won't be visible via `config.get(...)`.
+
+## See also
+
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — module layout, canonical imports, framework-wide invariants.
+- [`@warlock.js/cache/pick-cache-driver/SKILL.md`](../../../cache/skills/pick-cache-driver/SKILL.md) — picking and registering a cache driver in `src/config/cache.ts`.
+- [`send-mail/SKILL.md`](../send-mail/SKILL.md) — the `src/config/mail.ts` shape.
+- [`store-file/SKILL.md`](../store-file/SKILL.md) — the `src/config/storage.ts` shape.

package/skills/create-controller/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: create-controller
+description: 'Author HTTP controllers in @warlock.js/core — RequestHandler signature, validated input via seal schemas, response helpers, attaching metadata. Controllers are thin functions; business logic moves to services or use-cases. Triggers: `RequestHandler`, `Request<TSchema>`, `GuardedRequestHandler`, `request.validated`, `request.input`, `controller.validation`, `response.success`, `response.successCreate`; "write a controller", "attach a schema to a handler", "thin controller pattern", "guarded request type"; typical import `import { type RequestHandler } from "@warlock.js/core"`. Skip: response helper menu — `@warlock.js/core/send-response/SKILL.md`; schema authoring — `@warlock.js/core/validate-input/SKILL.md`; URL wiring — `@warlock.js/core/register-route/SKILL.md`; competing patterns: `express` middleware functions, `@nestjs/common` `@Controller`/`@Get` decorators.'
+---
+
+# Warlock — create a controller
+
+A controller is a thin function: pull inputs from `request`, call work, return through a `response.<helper>()`. No classes. No decorators. No DI.
+
+## The shape
+
+```ts title="src/app/<module>/controllers/<action>.controller.ts"
+import { type RequestHandler } from "@warlock.js/core";
+
+export const listProductsController: RequestHandler = async (request, response) => {
+  return response.success({ products: [] });
+};
+```
+
+That's the full contract. The `RequestHandler` annotation carries both parameter types — `request` and `response` infer automatically; you never annotate them by hand.
+
+## File location and naming
+
+- One controller per file.
+- File: `src/app/<module>/controllers/<action>.controller.ts`.
+- Export name matches the action in camelCase + `Controller` suffix: `listProductsController`, `createProductController`, `getProductController`.
+
+Scaffold with: `yarn warlock generate.controller <module>/<action>` (add `--with-validation` to get the schema generated alongside).
+
+## Reading input
+
+| Method                            | Returns                                          | Use when                                            |
+| --------------------------------- | ------------------------------------------------ | --------------------------------------------------- |
+| `request.input("key", default?)`  | one field                                        | reading a single param/body field by name           |
+| `request.all()`                   | full input object                                | passing the whole input straight to a service       |
+| `request.validated()`             | schema-typed object (only after schema attached) | controllers with a schema — preferred over `.all()` |
+| `request.user`                    | authenticated user                               | guarded routes (see "Typing a guarded handler")     |
+| `request.file("key")`             | `UploadedFile`                                   | multipart uploads                                   |
+| `request.header("X-Foo")`         | header value                                     | reading request metadata                            |
+| `request.ip`, `request.userAgent` | strings                                          | logging, device info                                |
+
+Prefer `request.validated()` once a schema is attached — it's typed.
+
+## Returning output
+
+Pick the helper that matches the outcome. Full surface in [send-response](../send-response/SKILL.md). Quick map:
+
+| Helper                             | Status | Use when                      |
+| ---------------------------------- | ------ | ----------------------------- |
+| `response.success(data)`           | 200    | normal read                   |
+| `response.successCreate(data)`     | 201    | resource created              |
+| `response.noContent()`             | 204    | delete succeeded              |
+| `response.badRequest({ error })`   | 400    | invalid input                 |
+| `response.unauthorized({ error })` | 401    | missing/invalid token         |
+| `response.forbidden({ error })`    | 403    | authenticated but not allowed |
+| `response.notFound({ error })`     | 404    | record missing                |
+| `response.conflict({ error })`     | 409    | uniqueness / state            |
+
+Always `return response.<helper>(...)` — the return value is the request's response.
+
+## Attaching a validation schema
+
+The schema is a property on the handler function, not a decorator. The handler's type generic carries the schema shape so `request.validated()` is typed end-to-end:
+
+```ts title="src/app/products/controllers/create-product.controller.ts"
+import { type Request, type RequestHandler } from "@warlock.js/core";
+import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
+import { createProductService } from "../services/create-product.service";
+
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+  request,
+  response,
+) => {
+  const product = await createProductService(request.validated());
+
+  return response.successCreate({ product });
+};
+
+createProductController.validation = {
+  schema: createProductSchema,
+};
+```
+
+Two pieces:
+
+1. **`RequestHandler<Request<TSchema>>`** as the controller's annotation — types `request.validated()` and keeps `request`/`response` inferred. No separate `*.request.ts` alias file is needed; the schema's exported `TSchema` type is the single source of truth.
+2. **`controller.validation = { schema }`** at module top level so the framework knows to validate before calling the handler.
+
+If validation fails, the framework returns a 400 with an `errors` payload and your handler never runs.
+
+### Typing a guarded handler
+
+Routes behind `authMiddleware` need `request.user` typed. Project conventions add a `GuardedRequest<TSchema>` (adding `user: User`) and a paired `GuardedRequestHandler<TSchema>` alias in `app/auth/requests/guarded.request`:
+
+```ts
+import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
+import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
+
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+  request,
+  response,
+) => {
+  // request.user is typed
+  const product = await createProductService(request.validated());
+  return response.successCreate({ product });
+};
+
+createProductController.validation = { schema: createProductSchema };
+```
+
+Use `RequestHandler<Request<TSchema>>` for public routes, `GuardedRequestHandler<TSchema>` for guarded ones. The `generate.controller`/`generate.module` scaffolds emit `GuardedRequestHandler` by default, since generated routes are wired behind `guarded(...)` — swap to `RequestHandler` when the endpoint is public.
+
+## Optional metadata
+
+```ts
+createProductController.description = "Create a new product (admin only)";
+```
+
+Used by OpenAPI/Swagger generation (planned per `domains/core/backlog.md`) and surfaces in dev-server logs.
+
+## What belongs in a controller (and what doesn't)
+
+**Belongs:**
+
+- Input pulling (`request.validated()` / `request.input(...)`)
+- Calling exactly one service or use-case
+- Returning the success path via `response.<helper>()`
+
+Errors? Throw from the service. The framework catches every `HttpError` subclass and produces the matching response — controllers stay branch-free. See the next section.
+
+**Doesn't belong:**
+
+- Database queries (push to a repository, called by a service)
+- Transactions (use-cases own them)
+- External API calls (services)
+- Cross-cutting orchestration of multiple services (use a `useCase()` — see `write-use-case` skill in Slice 2)
+- Logging beyond what the framework does automatically
+
+If your controller is over ~30 lines, the work probably belongs in a service.
+
+## Common patterns
+
+### Read
+
+```ts
+import { type RequestHandler } from "@warlock.js/core";
+import { listProductsService } from "../services/list-products.service";
+
+export const listProductsController: RequestHandler = async (request, response) => {
+  const { data: products, pagination } = await listProductsService({
+    ...request.all(),
+    organization_id: request.user.organizationId,
+  });
+
+  return response.success({ products, pagination });
+};
+```
+
+### Create
+
+```ts
+import { type Request, type RequestHandler } from "@warlock.js/core";
+import { type CreateProductSchema, createProductSchema } from "../schema/create-product.schema";
+import { createProductService } from "../services/create-product.service";
+
+export const createProductController: RequestHandler<Request<CreateProductSchema>> = async (
+  request,
+  response,
+) => {
+  const product = await createProductService(request.validated());
+
+  return response.successCreate({ product });
+};
+
+createProductController.validation = {
+  schema: createProductSchema,
+};
+```
+
+### Service throws — controller stays branch-free
+
+For HTTP-shaped errors (`404` not found, `403` forbidden, `400` bad request, `409` conflict, `500` server error), **throw from the service**. The request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the matching response. Controllers stay focused on the success path:
+
+```ts title="src/app/products/services/get-product.service.ts"
+import { ResourceNotFoundError } from "@warlock.js/core";
+import { productsRepository } from "../repositories/products.repository";
+
+export async function getProductService(id: string) {
+  const product = await productsRepository.find(id);
+
+  if (!product) {
+    throw new ResourceNotFoundError("product.notFound");
+  }
+
+  return product;
+}
+```
+
+```ts title="src/app/products/controllers/get-product.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+import { getProductService } from "../services/get-product.service";
+
+export const getProductController: RequestHandler = async (request, response) => {
+  const product = await getProductService(request.input("id"));
+
+  return response.success({ product });
+};
+```
+
+No `if (!product)` branch in the controller. The error class carries the HTTP semantic (`404` for `ResourceNotFoundError`, `403` for `ForbiddenError`, `400` for `BadRequestError`, `409` for `ConflictError`, `500` for `ServerError`). Full list in [`send-response`](../send-response/SKILL.md#throwing-http-errors). `product.notFound` is a translation key — see localization conventions in your project's `utils/locales.ts`.
+
+## Gotchas
+
+- **DO throw HTTP-shaped errors from services.** `ResourceNotFoundError`, `ForbiddenError`, `BadRequestError`, etc. — the framework's request middleware (`http/middleware/inject-request-context.ts`) catches every `HttpError` subclass and produces the right response. Controllers stay clean of branching; only catch when you genuinely need to recover and continue.
+- **Don't read `request.body` directly.** Use `request.all()` / `request.validated()` — they handle multipart, JSON, and form bodies uniformly.
+- **Don't annotate `request`/`response` by hand.** They flow from the `RequestHandler<...>` generic. Adding `request: SomeRequest` separately re-introduces a contravariance error and defeats the inference.
+- **Don't keep a `*.request.ts` alias file.** The schema's exported `TSchema` type plus `RequestHandler<Request<TSchema>>` (or `GuardedRequestHandler<TSchema>`) is the single source of truth. Separate request alias files drift from the schema and add an indirection that pays no rent.
+
+## See also
+
+- [`register-route/SKILL.md`](../register-route/SKILL.md) — wiring a controller to a URL.
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — full Response helper surface.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — controller-service-repository layering.