@warlock.js/core 4.0.174 → 4.1.3

package/skills/register-route/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: register-route
+description: 'Register HTTP routes via @warlock.js/core''s router — single routes, prefix groups, middleware-guarded blocks, and RESTful resource chains. Routes always live in `src/app/<module>/routes.ts`. Triggers: `router.get`, `router.post`, `router.prefix`, `router.group`, `router.route`, `guarded`; "add a route", "wire a controller to a URL", "group routes by prefix", "register a RESTful resource"; typical import `import { router } from "@warlock.js/core"`. Skip: handler shape — `@warlock.js/core/create-controller/SKILL.md`; CRUD chain details — `@warlock.js/core/build-restful/SKILL.md`; middleware authoring — `@warlock.js/core/write-middleware/SKILL.md`; competing libs `express`, `fastify`, `koa`, `@nestjs/common`.'
+---
+
+# Warlock — register a route
+
+How to declare HTTP routes in a Warlock module. The framework auto-loads `routes.ts` from every module on boot — never `import` it.
+
+## The shape
+
+```ts title="src/app/<module>/routes.ts"
+import { router } from "@warlock.js/core";
+import { listProductsController } from "./controllers/list-products.controller";
+
+router.get("/products", listProductsController);
+```
+
+That's the entire contract for a simple route. `router` is a singleton; method calls register routes synchronously. The handler is a plain function (controllers are typed as `RequestHandler` — see [create-controller](../create-controller/SKILL.md)).
+
+## HTTP verbs
+
+```ts
+router.get(path, handler);
+router.post(path, handler);
+router.put(path, handler);
+router.patch(path, handler);
+router.delete(path, handler);
+```
+
+`path` can be a string or a string array (multiple paths, one handler). Path params use `:name`: `router.get("/products/:id", getProductController)`.
+
+## Prefix groups
+
+A whole module typically prefixes its URLs with `/<module-name>`. Use `router.prefix(...)`:
+
+```ts
+router.prefix("/products", () => {
+  router.get("/", listProductsController);
+  router.get("/:id", getProductController);
+  router.post("/", createProductController);
+});
+```
+
+Nested `prefix` calls compose: `router.prefix("/api", () => router.prefix("/v1", () => router.get("/health", ...)))` registers `/api/v1/health`.
+
+## Route groups with middleware
+
+For routes that share both a prefix and middleware, use `router.group(...)`:
+
+```ts
+import { authMiddleware } from "@warlock.js/auth";
+
+router.group(
+  {
+    prefix: "/admin",
+    middleware: [authMiddleware("admin")],
+  },
+  () => {
+    router.get("/dashboard", dashboardController);
+    router.delete("/users/:id", removeUserController);
+  },
+);
+```
+
+`group` options:
+
+- `prefix` — prepended to every route inside
+- `middleware` — array of middleware applied to every route inside
+- `name` — route-name prefix (used for URL generation)
+
+## Auth-guarded shortcut
+
+Projects with `@warlock.js/auth` usually define a `guarded(...)` helper in `src/app/shared/utils/router.ts` that wraps `router.group({ middleware: [authMiddleware("user")] }, …)`:
+
+```ts
+import { guarded } from "app/shared/utils/router";
+
+router.prefix("/products", () => {
+  router.get("/", listProductsController);             // public
+  guarded(() => {
+    router.post("/", createProductController);          // requires logged-in user
+    router.delete("/:id", removeProductController);
+  });
+});
+```
+
+If `guarded` doesn't exist in your project yet, see the shared utility convention in [warlock-conventions](../warlock-conventions/SKILL.md).
+
+## RESTful resource chain
+
+For a standard CRUD resource, `router.route(path)` returns a builder with five named slots:
+
+```ts
+router.route("/products")
+  .list(listProductsController)        // GET    /products
+  .show(getProductController)          // GET    /products/:id
+  .create(createProductController)     // POST   /products
+  .update(updateProductController)     // PUT    /products/:id
+  .destroy(removeProductController);   // DELETE /products/:id
+```
+
+Each method returns the builder so you can chain. Methods you don't call don't register. Pair with `guarded`/`group` the same way as plain routes.
+
+## Common patterns
+
+### A typical module's `routes.ts`
+
+```ts
+import { router } from "@warlock.js/core";
+import { guarded } from "app/shared/utils/router";
+import { createProductController } from "./controllers/create-product.controller";
+import { getProductController } from "./controllers/get-product.controller";
+import { listProductsController } from "./controllers/list-products.controller";
+import { removeProductController } from "./controllers/remove-product.controller";
+import { updateProductController } from "./controllers/update-product.controller";
+
+guarded(() => {
+  router
+    .route("/products")
+    .list(listProductsController)
+    .show(getProductController)
+    .create(createProductController)
+    .update(updateProductController)
+    .destroy(removeProductController);
+});
+```
+
+### Public + guarded mix
+
+```ts
+router.prefix("/auth", () => {
+  router.post("/login", loginController);
+  router.post("/register", registerController);
+  guarded(() => {
+    router.post("/logout", logoutController);
+    router.get("/me", meController);
+  });
+});
+```
+
+### Multiple paths on one handler
+
+```ts
+router.get(["/health", "/healthz"], healthController);
+```
+
+## Gotchas
+
+- **Never import `routes.ts`.** The framework auto-loads it. Importing causes a double-registration error.
+- **Route order matters for static-vs-param overlap.** `router.get("/products/featured", ...)` must register before `router.get("/products/:id", ...)` if you want `featured` to be a static match, not `:id = "featured"`. Easier: use distinct paths.
+- **`group` middleware runs in array order** before the controller; if you stack `[rateLimitMiddleware, authMiddleware]`, rate-limiting runs first.
+- **Don't put logic in `routes.ts`.** It's a registration file. If you want conditional registration (env-flagged endpoints), do it via the controller's logic, not by branching at registration time — branching breaks the dev-server's HMR diff.
+
+## See also
+
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — the handler shape, validation, request/response surface.
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — picking the right `response.<helper>()`.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — module layout, the `guarded` convention, path aliases.

package/skills/resolve-path/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: resolve-path
+description: 'Path helpers anchored at `process.cwd()` — `rootPath`, `srcPath`, `appPath`, `configPath`, `publicPath`, `storagePath`, `uploadsPath`, `cachePath`, `logsPath`, `tempPath`, `warlockPath`, `sanitizePath`. Optional `uploads.root` config overrides the uploads anchor. Triggers: `appPath`, `configPath`, `uploadsPath`, `storagePath`, `publicPath`, `cachePath`, `logsPath`, `tempPath`, `sanitizePath`, `paths`; "resolve a path inside src/app", "absolute upload destination", "sanitize a user filename", "ship uploads to a mounted volume"; typical import `import { appPath, uploadsPath } from "@warlock.js/core"`. Skip: HTTP URL helpers — `@warlock.js/core/build-url/SKILL.md`; app metadata — `@warlock.js/core/use-app-context/SKILL.md`; storage abstraction — `@warlock.js/core/store-file/SKILL.md`; competing patterns: `path.join(process.cwd(), ...)`, hand-rolled directory constants.'
+---
+
+# Warlock — resolve a path
+
+Twelve helpers, all anchored at `process.cwd()`, all in `@warlock.js/core`. They exist so you don't re-parse `process.cwd()` in every call site or hand-roll `path.join` for the same five locations.
+
+## The shape
+
+```ts
+import { appPath, configPath, uploadsPath, storagePath } from "@warlock.js/core";
+
+appPath("orders/routes.ts");           // → <cwd>/src/app/orders/routes.ts
+configPath("http.ts");                  // → <cwd>/src/config/http.ts
+uploadsPath("avatars/42.png");          // → <cwd>/storage/uploads/avatars/42.png
+storagePath("backups/2026-01.tar.gz");  // → <cwd>/storage/backups/2026-01.tar.gz
+```
+
+Every helper takes any number of path segments and joins them. No-argument calls return the base directory itself.
+
+## Full inventory
+
+| Helper             | Resolves to                              | Notes                                                              |
+| ------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
+| `rootPath(...p)`   | `<cwd>/<...p>`                           | Also `Application.rootPath`. Base of every other helper.           |
+| `srcPath(...p)`    | `<cwd>/src/<...p>`                       | Also `Application.srcPath`.                                        |
+| `appPath(p?)`      | `<cwd>/src/app/<p>`                      | Also `Application.appPath`. Module roots live here.                |
+| `configPath(...p)` | `<cwd>/src/config/<...p>`                | `src/config/*.ts` subsystem configs.                               |
+| `publicPath(p?)`   | `<cwd>/public/<p>`                       | Also `Application.publicPath`. Static assets served as-is.         |
+| `storagePath(p?)`  | `<cwd>/storage/<p>`                      | Also `Application.storagePath`. Root for framework-managed files.  |
+| `uploadsPath(p?)`  | `<cwd>/storage/uploads/<p>` *(default)*  | Also `Application.uploadsPath`. Honors `config.uploads.root` override (string or function). |
+| `cachePath(p?)`    | `<cwd>/storage/cache/<p>`                | Persistent cache files.                                            |
+| `logsPath(p?)`     | `<cwd>/storage/logs/<p>`                 | Application logs.                                                  |
+| `tempPath(p?)`     | `<cwd>/storage/tmp/<p>`                  | Throw-away scratch.                                                |
+| `warlockPath(...p)` | `<cwd>/.warlock/<...p>`                 | Framework internals (manifest, transpile cache, typings). **Never write app files here** — the framework deletes the folder freely. |
+| `sanitizePath(p)`  | Strips `<>:"/\|?*` from `p`              | Cleans user-supplied filename fragments before joining.            |
+
+## The aggregate — `paths`
+
+For builders or maintenance scripts that shuttle several locations in close proximity, use the `paths` object — a short-alias view over every helper:
+
+```ts
+import { paths } from "@warlock.js/core";
+
+paths.root("dist", "app.js");        // → <cwd>/dist/app.js
+paths.app("orders/routes.ts");        // → <cwd>/src/app/orders/routes.ts
+paths.uploads("avatars/42.png");      // → <cwd>/storage/uploads/avatars/42.png
+paths.config("mail.ts");              // → <cwd>/src/config/mail.ts
+paths.cache("queries.bin");           // → <cwd>/storage/cache/queries.bin
+paths.logs("errors.log");             // → <cwd>/storage/logs/errors.log
+paths.temp("tmp-export.csv");         // → <cwd>/storage/tmp/tmp-export.csv
+paths.warlock("manifest.json");       // → <cwd>/.warlock/manifest.json
+paths.sanitize("../etc/passwd");      // → "..etcpasswd"
+```
+
+Use the named import (`appPath`, `uploadsPath`, ...) when one helper dominates the file; reach for `paths.*` when you're shuttling multiple paths together.
+
+## Patterns
+
+### Read a file inside a module
+
+```ts
+import { appPath } from "@warlock.js/core";
+import { readFile } from "node:fs/promises";
+
+const template = await readFile(
+  appPath("mailers/templates/welcome.html"),
+  "utf-8",
+);
+```
+
+### Locate a config file
+
+```ts
+import { configPath } from "@warlock.js/core";
+
+const httpConfigFile = configPath("http.ts");
+```
+
+### Compute an absolute upload destination
+
+```ts
+import { uploadsPath } from "@warlock.js/core";
+
+const avatar = uploadsPath(`avatars/${userId}/profile.png`);
+```
+
+### Sanitize a user-supplied filename before joining
+
+```ts
+import { sanitizePath, uploadsPath } from "@warlock.js/core";
+
+const safe = sanitizePath(req.input("filename"));
+const dest = uploadsPath(`exports/${safe}`);
+```
+
+`sanitizePath` strips characters that are illegal in filenames on Windows (`<>:"/\|?*`) and that enable path traversal. **Always** sanitize before joining user input into an `uploadsPath` / `tempPath` / any persistence helper.
+
+### Read framework metadata (rare)
+
+```ts
+import { warlockPath } from "@warlock.js/core";
+
+const manifest = warlockPath("manifest.json");
+```
+
+`.warlock/` is the framework's scratch space — manifests, transpile cache, generated typings. Reading is occasionally useful for diagnostics. **Writing** is a defect; the framework deletes the folder whenever it feels like it.
+
+## Overriding the uploads root
+
+`uploadsPath` is the only helper with a config override. Set `uploads.root` in `src/config/uploads.ts` to a string (static directory) or a function `(relativePath) => string` (dynamic per-call). Useful when you've moved user uploads onto a mounted volume:
+
+```ts title="src/config/uploads.ts"
+export default {
+  uploads: {
+    root: "/mnt/uploads",                   // static
+    // root: (rel) => `/mnt/uploads/${rel}`, // dynamic
+  },
+};
+```
+
+After this, `uploadsPath("avatars/42.png")` resolves to `/mnt/uploads/avatars/42.png`. Other helpers continue resolving against `process.cwd()`.
+
+When to reach for the function form:
+
+- Per-tenant uploads (`(rel) => /mnt/${tenant.id}/${rel}`).
+- Per-environment routing (production → S3-mounted volume, dev → local).
+- Date-based shards (`(rel) => /mnt/uploads/${YYYY-MM}/${rel}`).
+
+When to keep it as a static string: everything else. The function form is per-call overhead.
+
+### What "override" means
+
+The override is applied **inside** `uploadsPath()`. So `Application.uploadsPath` (the no-arg getter on the `Application` class) also respects it. Other helpers — `storagePath`, `cachePath`, `logsPath`, `tempPath` — continue resolving against `<cwd>/storage`, even though they're conceptually "under" the same root. If you want all of those redirected too, your deployment should mount the whole `storage/` folder, not just `storage/uploads`.
+
+## When to use which
+
+| Goal                                       | Helper            |
+| ------------------------------------------ | ----------------- |
+| File inside a module (controllers/services) | `appPath`        |
+| Top-level subsystem config                 | `configPath`      |
+| Static asset served as-is over HTTP        | `publicPath`      |
+| User-uploaded file (avatar, document)      | `uploadsPath`     |
+| Persistent cache for an expensive op       | `cachePath`       |
+| Application log line                       | `logsPath`        |
+| Short-lived scratch (cleaned aggressively) | `tempPath`        |
+| Bundled artifact (build outputs)           | `rootPath("dist", ...)` |
+| Reading a TS source from disk              | `srcPath` / `appPath` |
+| Framework internals (manifest, transpile)  | `warlockPath` *(read-only)* |
+
+If you find yourself reaching for `path.join(process.cwd(), ...)` — that's a sign you want one of these helpers instead.
+
+## Gotchas
+
+- **Paths depend on `process.cwd()`.** If something `process.chdir()`s, the paths shift. Warlock never does this; if you do, you've broken every path lookup.
+- **`warlockPath` is read-only from app code.** The framework deletes `.warlock/` on dev restart, build clean, etc. Anything you write there is collateral damage on the next run.
+- **`sanitizePath` strips, doesn't reject.** It replaces illegal characters with empty string — `../foo/bar` becomes `..foobar`, not an error. If you want a hard refusal on traversal attempts, validate upstream first (e.g. seal schema rule).
+- **`storagePath` vs `uploadsPath`.** Storage is the framework-managed root (logs, cache, temp, uploads sit under it). Uploads is the user-content subfolder. Don't write app logs into `uploadsPath` or user files into `logsPath`.
+- **`uploads.root` override is read at call time.** Changing config mid-process is honored on the next `uploadsPath()` call. Useful in tests; don't rely on it in request handlers.
+- **No helper covers `node_modules`.** If you need an `node_modules/<pkg>` path, use `rootPath("node_modules", "<pkg>")` — there's no `vendorPath`.
+
+## See also
+
+- [`build-url/SKILL.md`](../build-url/SKILL.md) — HTTP URL helpers (`url`, `uploadsUrl`, `publicUrl`, `assetsUrl`) — companion for rendering URLs (not filesystem paths).
+- [`use-app-context/SKILL.md`](../use-app-context/SKILL.md) — `Application` static (env, runtime strategy, version, uptime) + `app` runtime accessor (Fastify, socket.io, router, database).
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/uploads.ts` for the `root` override.
+- [`store-file/SKILL.md`](../store-file/SKILL.md) — the storage abstraction (most uploads code goes through `storage.put(...)`, not raw paths).
+- [`upload-file/SKILL.md`](../upload-file/SKILL.md) — the `UploadedFile` shape that pairs with `uploadsPath`.

package/skills/retry-operation/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: retry-operation
+description: 'Wrap a flaky operation with `retry(fn, options)` — now provided by `@mongez/reinforcements` (not `@warlock.js/core`). `attempts` total tries, `delay` + `backoff` (linear/exponential/fn), `maxDelay`, `jitter`, `shouldRetry` to bail on permanent errors, `signal` to cancel, plus `retryable()` to pre-bind options. Triggers: `retry`, `retryable`, `RetryOptions`, `attempts`, `backoff`, `jitter`, `maxDelay`, `shouldRetry`, `signal`; "retry a flaky API call", "handle transient errors", "exponential backoff with jitter", "wrap an external request"; typical import `import { retry } from "@mongez/reinforcements"`. Skip: timing the retried op — `@warlock.js/core/benchmark-code/SKILL.md`; use-case-level `retry` option — `@warlock.js/core/write-use-case/SKILL.md`; competing libs `p-retry`, `async-retry`, `cockatiel`.'
+---
+
+# Warlock — retry an operation
+
+> **Moved.** The retry primitive now lives in **`@mongez/reinforcements`**, not
+> `@warlock.js/core`. The old `import { retry } from "@warlock.js/core"` no longer
+> exists. Full reference: [`mongez-reinforcements-async`](mongez-reinforcements-async).
+
+```ts
+import { retry } from "@mongez/reinforcements";
+
+const user = await retry(() => fetchUser(id), {
+  attempts: 4,            // TOTAL tries (initial + retries) — default 3
+  delay: 200,             // base ms between attempts
+  backoff: "exponential", // 200, 400, 800 ms
+});
+```
+
+## What changed from the old core `retry`
+
+| Old (`@warlock.js/core`)       | New (`@mongez/reinforcements`)                            |
+| ------------------------------ | -------------------------------------------------------- |
+| `count` = **extra** attempts   | `attempts` = **total** attempts (`count + 1`)            |
+| fixed `delay` only             | `delay` + `backoff` (`"linear" \| "exponential" \| fn`)  |
+| —                              | `maxDelay`, `jitter` (`"full" \| "equal"`), `signal`     |
+| `shouldRetry(error, attempt)`  | `shouldRetry(error, attempt)` (kept) + `onError` observe |
+| —                              | `retryable(fn, options)` to pre-bind a reusable wrapper  |
+
+Migration: `count: 3` → `attempts: 4`.
+
+## Bail out on permanent errors
+
+Observe with `onError`, decide with `shouldRetry` (called in that order). Return `false` to stop immediately and re-throw:
+
+```ts
+await retry(() => stripe.charges.create(payload), {
+  attempts: 4,
+  delay: 500,
+  shouldRetry: (error) => error instanceof NetworkError || error instanceof TimeoutError,
+});
+```
+
+## What's safe to retry
+
+- **Idempotent reads** (GET, SELECT, cache lookups) — always safe.
+- **Idempotent writes** with server-side dedup (Stripe `Idempotency-Key`, conditional writes, PUT to a known id) — safe.
+- **Non-idempotent writes** (a POST that charges a card, sends an email) — dangerous. Gate with `shouldRetry` so only transient infra errors retry.
+
+## Backoff + jitter + cap
+
+```ts
+await retry(() => fetch(url), {
+  attempts: 6,
+  delay: 100,
+  backoff: "exponential",
+  maxDelay: 2_000,   // never wait more than 2s as backoff grows
+  jitter: "full",    // randomise each delay to avoid thundering herd
+});
+```
+
+## Cancel a long loop
+
+```ts
+const controller = new AbortController();
+const promise = retry(poll, { attempts: 10, delay: 1_000, signal: controller.signal });
+controller.abort(); // rejects promptly with signal.reason
+```
+
+## Pre-bind with `retryable`
+
+```ts
+import { retryable } from "@mongez/reinforcements";
+
+const fetchUser = retryable(getUser, { attempts: 4, backoff: "exponential" });
+await fetchUser(id);
+```
+
+## Composing with `measure()`
+
+`measure()` (from `@warlock.js/core`) returns a result object and doesn't throw on `fn` failure — so put `measure` **inside** `retry` (per-attempt timing) and re-throw, or **outside** for total wall-clock:
+
+```ts
+import { measure } from "@warlock.js/core";
+import { retry } from "@mongez/reinforcements";
+
+const result = await measure("publish-event", () =>
+  retry(() => bus.publish(event), { attempts: 4, delay: 200 }),
+); // result.latency includes all retries
+```
+
+## Use-case integration
+
+`useCase()` accepts a `retry` option (the same `RetryOptions`) that wraps the **handler** — see [`@warlock.js/core/write-use-case/SKILL.md`](@warlock.js/core/write-use-case/SKILL.md). Reach for that when "retry" means "re-run the handler"; reach for raw `retry()` when only one step inside is flaky.
+
+## Gotchas
+
+- **`attempts` is the TOTAL, not extra.** `attempts: 3` = 3 calls. (The old core `count: 3` meant 4 calls.)
+- **`shouldRetry` decides, `onError` observes.** `onError` can't stop the loop; only `shouldRetry` returning `false` does.
+- **Don't retry inside a DB transaction.** Most drivers invalidate the transaction on error — retry the whole transaction, not the inner statement.
+- **`exponential` + many `attempts` without `maxDelay`** can produce very long waits. Set `maxDelay`.
+
+## See also
+
+- [`mongez-reinforcements-async`](mongez-reinforcements-async) — full `retry` / `retryable` reference.
+- [`@warlock.js/core/benchmark-code/SKILL.md`](@warlock.js/core/benchmark-code/SKILL.md) — timing retried operations.
+- [`@warlock.js/core/write-use-case/SKILL.md`](@warlock.js/core/write-use-case/SKILL.md) — the use-case `retry` option.