@warlock.js/core 4.0.174 → 4.1.2

package/skills/write-middleware/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: write-middleware
+description: 'Author HTTP middleware for @warlock.js/core — the `(request, response)` signature, short-circuit by returning a response, enrich the request with extra fields, register per-route, per-group, or app-wide. Triggers: `Middleware`, `MiddlewareResponse`, `router.group`, `guarded`, `request.detectIp`, `authMiddleware`; "write a custom middleware", "short-circuit a request", "enrich the request with extra fields", "per-route vs per-group middleware"; typical import `import type { Middleware } from "@warlock.js/core"`. Skip: built-in middleware catalog — `@warlock.js/core/use-middleware/SKILL.md`; route attachment — `@warlock.js/core/register-route/SKILL.md`; response helpers — `@warlock.js/core/send-response/SKILL.md`; competing patterns: `express` `(req, res, next)` middleware, Fastify `preHandler` hooks.'
+---
+
+# Warlock — write a middleware
+
+Middleware is a plain function that runs before the controller. Two outcomes: return nothing (or `undefined`) and the request continues; return a `Response` and the request is short-circuited there. No `next()` callback — the framework chains them automatically.
+
+## The shape
+
+```ts title="src/app/<module>/utils/<name>.middleware.ts"
+import type { Middleware } from "@warlock.js/core";
+
+export const requireApiKey: Middleware = (request, response) => {
+  const key = request.header("X-API-Key");
+
+  if (!key || key !== process.env.API_KEY) {
+    return response.unauthorized({ error: "invalid api key" });
+  }
+
+  // return nothing → request continues to next middleware / controller
+};
+```
+
+That's the contract: `(request: Request, response: Response) => Response | undefined | void`. Async is fine — return a `Promise<Response | undefined | void>`.
+
+The real type, from `@warlock.js/core/src/router/types.ts`:
+
+```ts
+export type Middleware<MiddlewareRequest extends Request = Request> = {
+  (request: MiddlewareRequest, response: Response): MiddlewareResponse;
+};
+
+export type MiddlewareResponse = ReturnedResponse | undefined | void;
+```
+
+## Short-circuit vs continue
+
+The pattern is "return a response to stop, return nothing to continue":
+
+```ts
+import type { Middleware } from "@warlock.js/core";
+
+export const requireFeatureFlag: Middleware = async (request, response) => {
+  const flag = await loadFeatureFlag(request.input("organization_id"));
+
+  if (!flag.enabled) {
+    return response.forbidden({ error: "feature.disabled" });
+  }
+
+  // implicit `return undefined` → continue
+};
+```
+
+If you short-circuit, the controller never runs. The response helper you pick (`forbidden`, `unauthorized`, `badRequest`, etc.) sets the status — see [`send-response`](../send-response/SKILL.md).
+
+## Enriching the request
+
+You can attach arbitrary fields to `request` from a middleware, and they survive into the controller. The cleanest pattern is to extend `Request` via module augmentation in a `.d.ts` and assign in the middleware:
+
+```ts title="src/app/feature-flags/middleware/load-feature-flag.middleware.ts"
+import type { Middleware } from "@warlock.js/core";
+import type { FeatureFlag } from "../models/feature-flag";
+
+declare module "@warlock.js/core" {
+  interface Request {
+    featureFlag?: FeatureFlag;
+  }
+}
+
+export const loadFeatureFlag: Middleware = async (request) => {
+  request.featureFlag = await FeatureFlag.findBy("organization_id", request.user.organizationId);
+};
+```
+
+After this middleware runs, `request.featureFlag` is typed inside any downstream middleware or controller. The same pattern is how `@warlock.js/auth`'s `authMiddleware` attaches `request.user` and `request.decodedAccessToken`.
+
+## Registration — three scopes
+
+### Per-route
+
+Pass middleware in the third arg's `middleware` array:
+
+```ts
+import { router } from "@warlock.js/core";
+
+router.post("/sync", syncController, {
+  middleware: [requireApiKey],
+});
+```
+
+### Per-group (preferred for modules)
+
+`router.group(options, callback)` applies middleware to every route registered inside the callback:
+
+```ts
+import { router } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+router.group(
+  {
+    prefix: "/admin",
+    middleware: [authMiddleware("admin")],
+  },
+  () => {
+    router.get("/dashboard", dashboardController);
+    router.delete("/users/:id", removeUserController);
+  },
+);
+```
+
+Group middleware runs **before** per-route middleware. Stack multiple middlewares — they run in array order:
+
+```ts
+import { middleware } from "@warlock.js/core";
+import { authMiddleware } from "@warlock.js/auth";
+
+router.group(
+  { middleware: [middleware.rateLimit({ max: 60, duration: 60_000 }), authMiddleware("user")] },
+  () => {
+    // rate-limit first, then auth, then controller
+  },
+);
+```
+
+`all` runs on every route; `only` / `except` scope by route path or named-route. Prefer per-group for anything domain-specific — app-wide is for true cross-cutting concerns (request logging, CORS, rate limit defaults).
+
+## The `guarded()` helper
+
+Most modules wrap a `router.group({ middleware: [authMiddleware("user")] }, …)` call in a project-level helper:
+
+```ts title="src/app/shared/utils/router.ts"
+import { authMiddleware } from "@warlock.js/auth";
+import { router } from "@warlock.js/core";
+
+export function guarded(callback: () => void) {
+  router.group({ middleware: [authMiddleware("user")] }, callback);
+}
+
+export function guardedAdmin(callback: () => void) {
+  router.group({ prefix: "/admin", middleware: [authMiddleware()] }, callback);
+}
+
+export function publicRoutes(callback: () => void) {
+  router.group({ prefix: "/" }, callback);
+}
+```
+
+Then every module's `routes.ts` reads cleanly:
+
+```ts
+import { guarded } from "app/shared/utils/router";
+
+guarded(() => {
+  router.post("/products", createProductController);
+});
+```
+
+`authMiddleware(allowedUserType?)` accepts a user-type string or array. Without an arg it just verifies the token is present; with `"user"` / `"admin"` it also checks the decoded `userType` matches.
+
+## Common patterns
+
+### Combining auth with a custom check
+
+```ts
+import { authMiddleware } from "@warlock.js/auth";
+import { router } from "@warlock.js/core";
+import { requireFeatureFlag } from "./middleware/require-feature-flag";
+
+router.group(
+  {
+    prefix: "/beta",
+    middleware: [authMiddleware("user"), requireFeatureFlag],
+  },
+  () => {
+    router.get("/canary", canaryController);
+  },
+);
+```
+
+### Conditional pass-through
+
+```ts
+import type { Middleware } from "@warlock.js/core";
+
+export const optionalAuth: Middleware = async (request, response) => {
+  if (!request.authorizationValue) {
+    return; // anonymous — let it through
+  }
+
+  // token present → enforce it
+  return authMiddleware("user")(request, response);
+};
+```
+
+## Using built-in middleware
+
+`@warlock.js/core` ships seven built-in middlewares (rate limit, concurrency cap, body cap, idempotency, maintenance, IP filter, response cache) under the `middleware` namespace from `@warlock.js/core`. They cover the patterns most apps need — see [`use-middleware`](../use-middleware/SKILL.md) for the catalog, per-primitive deep-dives, error semantics, and gotchas specific to using them.
+
+`X-Request-Id` correlation is wired automatically (inherit + echo on every response) — the same skill covers that too. It's not a middleware; nothing to register.
+
+## Gotchas
+
+- **Don't `throw` for HTTP-shaped failures.** Throwing escalates to the framework's error handler and you lose the specific status. Use `return response.<helper>(...)`.
+- **Group middleware runs before per-route middleware**, in array order. The full chain is `app.all → group → per-route → controller`. Mind the order if you stack auth + rate-limit + audit.
+- **Middleware can be async.** Returning `Promise<undefined>` continues the chain. Returning `Promise<Response>` short-circuits. The framework awaits the result.
+- **Don't mutate `request.payload` directly.** Use `request.setValidatedData(...)` or attach a new named field (`request.featureFlag = ...`). The internals expect `payload.all` shapes to come from the validator pipeline.
+- **`Middleware` is generic over the request type.** For middleware that assumes a validated schema, narrow it: `const m: Middleware<CreateProductRequest> = (request) => { ... }`. But most middlewares run before validation, so the default `Middleware` is right.
+- **No `next()` parameter.** Express-style `next()` doesn't apply here. The framework chains based on return value.
+- **`request.baseRequest` / `response.baseResponse` are escape hatches, not API.** They expose the underlying Fastify primitives for cases the framework hasn't covered yet (streaming was the historical precedent). Prefer framework helpers first — `response.send()`, `response.header()`, `response.replay()`, `request.input()`, `request.detectIp()`, etc. If you find yourself reaching for `baseResponse` or `baseRequest` for non-streaming work, that's a missing helper — file an issue. The cache and idempotency middlewares both shipped with a quietly-broken FastifyReply-return bug because they bypassed the helper layer; the framework now guards `Response.send()` against double-send, but the right answer is "use the helper."
+- **Behind any proxy, use `request.detectIp()` not `request.ip`.** `request.ip` is the immediate peer (likely your load balancer); `request.detectIp()` honors `X-Real-IP` / `X-Forwarded-For`. Either way, only trust the result as far as you trust the upstream chain — those headers are client-settable; verify the request came through your trusted edge before treating the value as authoritative.
+
+## See also
+
+- [`use-middleware/SKILL.md`](../use-middleware/SKILL.md) — the built-in middleware catalog (`rateLimit`, `idempotency`, `maxBodySize`, etc.) + request-id correlation.
+- [`register-route/SKILL.md`](../register-route/SKILL.md) — where middleware attaches: `router.group` and route-options.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — how the controller picks up `request.user`, `request.validated()`, etc., set by upstream middleware.
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — the response helpers used to short-circuit.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — the `guarded()` / `guardedAdmin()` / `publicRoutes()` convention.

package/skills/write-seeder/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: write-seeder
+description: 'Author a seed file under `src/app/<module>/seeds/<name>.ts` using the `seeder()` factory — `name`, `dependsOn`, `once`, `order`, `batchSize`, `run()`. Auto-discovered by `warlock seed`; tracked in a `seeds` table. Triggers: `seeder`, `Seeder`, `SeedResult`, `SeedersManager`, `warlock seed`, `--fresh`, `--list`, `--path`; "seed default roles", "one-time data migration", "auto-discovered seeds", "order seeds by dependency"; typical import `import { seeder } from "@warlock.js/core"`. Skip: module folder layout — `@warlock.js/core/create-module/SKILL.md`; repository CRUD — `@warlock.js/core/use-repository/SKILL.md`; CLI flags — `@warlock.js/core/write-cli-command/SKILL.md`; competing patterns: hand-rolled `node scripts/seed.js`, `typeorm-seeding`.'
+---
+
+# Warlock — write a seeder
+
+Seeds are how you push initial data into the database — default roles, currencies, lookup tables, sample records for staging. They sit beside the module they belong to (`src/app/<module>/seeds/<name>.ts`), get auto-discovered by `warlock seed`, and the framework tracks which seeds have run so `once: true` ones don't re-run on a clean DB after the first time.
+
+## The shape
+
+```ts title="src/app/roles/seeds/default-roles.seed.ts"
+import { seeder } from "@warlock.js/core";
+import { Role } from "../models/role";
+
+export default seeder({
+  name: "default-roles",
+  description: "Insert admin / member / viewer roles",
+  once: true,
+  order: 1,
+  async run() {
+    let recordsCreated = 0;
+
+    for (const slug of ["admin", "member", "viewer"]) {
+      const existing = await Role.first({ slug });
+      if (existing) continue;
+
+      await Role.create({ slug, name: slug.toUpperCase() });
+      recordsCreated++;
+    }
+
+    return { recordsCreated };
+  },
+});
+```
+
+Run them:
+
+```bash
+yarn warlock seed                            # discover + run all
+yarn warlock seed --list                     # show registry, don't run
+yarn warlock seed --path=src/app/roles/seeds/default-roles.seed.ts  # one file
+yarn warlock seed --fresh                    # truncate every table first, then run all
+```
+
+`--fresh` truncates **every** table in the DB (`datasource.driver.truncateTable(table, { cascade: true })`), including the `seeds` tracking table. After `--fresh`, `once: true` seeds will run again.
+
+## The `Seeder` type
+
+```ts
+type Seeder = {
+  name: string;                                // required, used as the registry key
+  enabled?: boolean;                            // default true — set false to skip
+  description?: string;                         // shown in --list output
+  dependsOn?: string[];                         // names of seeds that must run first
+  once?: boolean;                               // skip if a row exists in the `seeds` table
+  order?: number;                               // sort key — lower runs first
+  batchSize?: number;                           // documented; not enforced by the manager
+  run(): Promise<SeedResult | void>;            // your work
+};
+
+type SeedResult = {
+  recordsCreated: number;                       // tracked in the seeds table
+};
+```
+
+Returning a `SeedResult` is optional — the manager uses `recordsCreated` only to populate metadata in the `seeds` table. If you don't return anything, the seed still counts as run (the row is inserted with `recordsCreated: 0`).
+
+## Auto-discovery
+
+`warlock seed` walks `src/app/*/seeds/*.ts` and imports each file via the framework's module loader. Each file must **default-export** a `Seeder`:
+
+```
+src/app/
+├── roles/
+│   └── seeds/
+│       ├── default-roles.seed.ts
+│       └── role-permissions.seed.ts
+└── currencies/
+    └── seeds/
+        └── default-currencies.seed.ts
+```
+
+A seed file that doesn't export a default `Seeder` throws at discovery time:
+> `Seeder file <relative> does not export a default seeder.`
+
+Filename convention is `<name>.seed.ts` but the loader doesn't enforce it — any `.ts` inside a `seeds/` folder is picked up. Sticking to the suffix keeps things grep-able.
+
+## Tracking — the `seeds` table
+
+The first `warlock seed` run creates a `seeds` table via `SeedsTableMigration`. Every successful seed run stores a row:
+
+| Column                  | Meaning                                    |
+| ----------------------- | ------------------------------------------ |
+| `name`                  | Seeder's `name` (the lookup key)           |
+| `createdAt`             | Wall time of the first run                 |
+| `firstRunAt`            | Same as `createdAt`                        |
+| `lastRunAt`             | Updated on every subsequent successful run |
+| `runCount`              | Increments by 1 per run                    |
+| `totalRecordsCreated`   | Sum of `recordsCreated` across all runs    |
+| `lastRunRecordsCreated` | Last run's `recordsCreated`                |
+
+Skip-on-`once`:
+
+- Before each seed runs, the manager looks up `name` in the `seeds` table.
+- If a row exists **and** `once: true`, the seed is skipped with `⏭️  Skipping <name> (already executed)`.
+- If `once` is unset / `false`, the seed always runs (but still appends a row, incrementing `runCount`).
+
+Use `once: true` for irreversible "starter" data (the framework's default `roles`, fixed enum tables) and leave it off for repeatable seeds (dev fixtures you re-run after rolling the DB).
+
+## Ordering
+
+```ts
+seeder({
+  name: "user-roles",
+  order: 10,
+  // ...
+});
+
+seeder({
+  name: "default-admin-user",
+  order: 20,         // runs AFTER user-roles (which created the roles it references)
+  // ...
+});
+```
+
+The manager sorts by `order` ascending — lower runs first. Seeds without an `order` get sorted to the end (`Number.MAX_SAFE_INTEGER`).
+
+`dependsOn: ["user-roles"]` is on the `Seeder` type but **not yet resolved** by the manager (there's an explicit `TODO: Handle dependsOn resolution` in the source — topological sort isn't implemented). For now, rely on `order` to express dependencies. The `dependsOn` field stays available for forward-compat.
+
+## Transactions
+
+By default, each seed runs inside a transaction:
+
+```ts
+const result = withTransaction
+  ? await transaction(async () => seeder.run())
+  : await seeder.run();
+```
+
+If your `run()` throws, the transaction rolls back. The CLI takes `--transaction` to flip this — pass `--transaction=false` for large seeds where you want each insert committed individually (avoid the rollback-on-failure cost; accept partial state on error).
+
+Within a single seed, multiple model `create()` / `insert()` calls share the same transaction — partial-on-error doesn't apply unless you opt out.
+
+## Patterns
+
+### Idempotent seed (safe to re-run without `once`)
+
+```ts title="src/app/currencies/seeds/default-currencies.seed.ts"
+import { seeder } from "@warlock.js/core";
+import { Currency } from "../models/currency";
+
+export default seeder({
+  name: "default-currencies",
+  description: "USD / EUR / SAR / EGP currencies",
+  order: 5,
+  async run() {
+    const seeds = [
+      { code: "USD", name: "US Dollar", decimals: 2 },
+      { code: "EUR", name: "Euro", decimals: 2 },
+      { code: "SAR", name: "Saudi Riyal", decimals: 2 },
+      { code: "EGP", name: "Egyptian Pound", decimals: 2 },
+    ];
+
+    let recordsCreated = 0;
+    for (const data of seeds) {
+      const existing = await Currency.first({ code: data.code });
+      if (existing) continue;
+      await Currency.create(data);
+      recordsCreated++;
+    }
+
+    return { recordsCreated };
+  },
+});
+```
+
+`first` + `continue` keeps the seed safe to run twice — the second run does nothing.
+
+### Run-once admin user (depends on roles)
+
+```ts title="src/app/users/seeds/default-admin.seed.ts"
+import { seeder } from "@warlock.js/core";
+import { Role } from "../../roles/models/role";
+import { User } from "../models/user";
+
+export default seeder({
+  name: "default-admin",
+  description: "Insert the seed admin user",
+  once: true,                   // never re-run
+  order: 20,                    // after roles (order: 10)
+  async run() {
+    const adminRole = await Role.first({ slug: "admin" });
+    if (!adminRole) throw new Error("admin role missing — run user-roles seed first");
+
+    await User.create({
+      email: "admin@example.com",
+      password: "change-me-immediately",
+      role_id: adminRole.id,
+    });
+
+    return { recordsCreated: 1 };
+  },
+});
+```
+
+Combining `once: true` + `order` is the canonical "starter data" pattern.
+
+### Bulk dev fixtures (no `once`, large batch)
+
+```ts title="src/app/products/seeds/dev-products.seed.ts"
+import { seeder } from "@warlock.js/core";
+import { Product } from "../models/product";
+
+export default seeder({
+  name: "dev-products",
+  description: "100 sample products for dev",
+  enabled: process.env.NODE_ENV === "development",
+  order: 100,
+  async run() {
+    let recordsCreated = 0;
+    for (let i = 0; i < 100; i++) {
+      await Product.create({
+        name: `Sample ${i}`,
+        price: Math.random() * 100,
+      });
+      recordsCreated++;
+    }
+    return { recordsCreated };
+  },
+});
+```
+
+`enabled: false` (or env-gated like above) keeps the seed off in production runs while leaving the file in the repo.
+
+### Wire seeds explicitly (alternative to auto-discovery)
+
+If you need to bypass auto-discovery — e.g. a shared-seeds package — register via `SeedersManager` directly:
+
+```ts
+import { SeedersManager } from "@warlock.js/core";
+import { defaultRoles } from "./seeds/default-roles.seed";
+import { defaultCurrencies } from "./seeds/default-currencies.seed";
+
+const manager = new SeedersManager();
+manager.register(defaultRoles, defaultCurrencies);
+await manager.run();
+```
+
+Most projects don't need this — auto-discovery handles the common case.
+
+## CLI flags
+
+```
+warlock seed                  # run all auto-discovered seeds
+warlock seed --list           # show registry (name, order, enabled), don't run
+warlock seed --path=<file>    # run one file by absolute or relative path
+warlock seed --fresh          # truncate every table first, then run all
+warlock seed --transaction    # (default true) — pass --transaction=false to skip wrapping
+```
+
+`--fresh` is **destructive** — it truncates all tables, including the `seeds` tracking table. Treat it as "reset the dev DB," not "run pending seeds."
+
+## Gotchas
+
+- **The seed file must default-export.** A named export gets the discovery error at boot. Wrap with `export default seeder({...})`.
+- **`once: true` only works if the seed run succeeds.** A throw rolls back the transaction including the `seeds` table insert — the next run will retry.
+- **`dependsOn` is documented but not enforced yet.** Use `order` until topological sort lands (`TODO` in source).
+- **`batchSize` is documented on the type but unused by the manager.** It's a forward-compat field. If you need batch inserts, batch inside `run()` directly.
+- **`--fresh` truncates `cascade: true`.** Foreign-key chains delete with their parents. If you have data outside the seeded scope that you want to keep, do NOT run `--fresh`.
+- **Seeds aren't migrations.** Schema changes go in `migrations/`. Seeds populate data into a schema that already exists. Mixing the two (creating a table in a seed) confuses the lifecycle.
+- **`enabled: false` skips the seed but it's still in the registry.** `warlock seed --list` shows it as disabled. Re-enable by flipping the flag, not by deleting the file.
+
+## See also
+
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `seeds/` folder layout in a module, `generate.module` scaffolding.
+- [`use-repository/SKILL.md`](../use-repository/SKILL.md) — the model `create` / `first` calls used inside seeds.
+- [`write-cli-command/SKILL.md`](../write-cli-command/SKILL.md) — the `warlock seed` CLI flags and full preload shape.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `seeds/` is the canonical folder name (singular `seed/` is incorrect).