@warlock.js/core 5.34.1 → 5.34.3

package/skills/configure-app/SKILL.md

@@ -421,3 +421,30 @@ export default {
 Keep the domain error class in an app module imported by both the service and
 this config. Return `undefined` for errors you do not recognize; a mapped 5xx
 is opaque unless the mapper explicitly chooses a public message.
+
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
+
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
+
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.

package/skills/generate-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-openapi
-description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `devtools-overview` topic of the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
+description: 'Generate an OpenAPI 3.1 document from the registered routes with `warlock generate.openapi` (default `storage/openapi/openapi.json`), write a Postman collection from it with `warlock generate.postman` (default `storage/postman/collection.json`), and read it live in the dev-only API docs page at `/__warlock/docs`. Documents paths, path/query parameters, request bodies from Seal validation, responses from `handler.responseSchema`, 401/422 and bearer/cookie security from `authMiddleware()`. Triggers: `generate.openapi`, `openApiGeneratorCommand`, `buildOpenApiDocument`, `getDevelopmentOpenApiDocument`, `generate.postman`, `openApiToPostmanCollection`, `getDevelopmentPostmanCollection`, `responseSchema`, `--include-pages`, `/__warlock/docs`; "OpenAPI", "Swagger", "API docs", "import my API into Postman or Insomnia", "document my routes". Skip: declaring response types on a handler — the `create-controller` topic; the devtools dashboard — the `warlock-js-devtools` skill; listing routes — the `warlock-routes` topic.'
 ---
 
 # Warlock — generate an OpenAPI document

package/skills/index.md

@@ -1,5 +1,5 @@
 ---
-description: "The Warlock server framework: HTTP routes, controllers, responses, resources, repositories, CLI, mail, storage, security helpers. Exports `router`, `Request`, `Response`, `RequestHandler`, `useCase`, `RepositoryManager`, `defineResource`, `defineConfig`, `storage`, `sendMail`, `hashPassword`, `command`. Use for: add a route, write a controller, return a JSON response, hide a field from the response, upload a file, send an email, hash a password, add a CLI command, generate an OpenAPI document, type an API response, wire a socket, run or configure the app. Not this package: database models/queries → @warlock.js/cascade; input schemas → @warlock.js/seal; SSR pages → @warlock.js/web."
+description: 'Warlock application runtime: `router`, `Request`, `Response`, `config`, `env`, `sendMail` and `defineConfig`. Use for "add an API route", controllers, middleware, CLI commands, config, uploads, mail, sockets, OpenAPI, testing or upgrades. Not this package → @warlock.js/web for React SSR pages; @warlock.js/cascade for database queries; @warlock.js/seal for standalone schemas; @warlock.js/auth for login.'
 ---
 
 # @warlock.js/core
@@ -14,11 +14,11 @@ Core is the application runtime: it boots the app, auto-loads each module's spec
 4. Return via `response.*` (`send-response.md`) and shape output with a resource (`define-resource.md`); declare `responseSchema` for typed clients and docs (`create-controller.md`, `generate-openapi.md`).
 5. Configure and run (`configure-app.md`, `run-app.md`); check setup with `warlock-doctor.md`, read the app with `warlock-inspect.md` (or serve it to an agent with `warlock-mcp.md`), verify a change with `warlock-check.md`, and a request's runtime behaviour with `warlock-trace.md`.
 
-When the framework is wrong or missing a capability, follow `report-framework-issue.md` to prepare a public report and ask the user before filing.
+When the framework is wrong or missing a capability, follow the `report-framework-issue` topic to prepare a public report and ask the user before filing.
 
 ## Topics by area
 
-- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators
+- **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators, upgrade-from-5-29
 - **HTTP & routing:** register-route, warlock-routes, create-controller, use-middleware, write-middleware, validate-input, use-request-locals, build-restful, wire-socket
 - **Responses & resources:** send-response, define-resource, use-model-transformers, use-localization
 - **Domain layers:** write-use-case, use-repository, write-seeder
@@ -26,7 +26,7 @@ When the framework is wrong or missing a capability, follow `report-framework-is
 - **Agent tooling:** warlock-mcp, warlock-trace, warlock-agents-md, warlock-board
 - **Storage, files & mail:** store-file, upload-file, process-image, send-mail
 - **Security & utilities:** hash-password, encrypt-data, store-secrets, retry-operation, benchmark-code, request-memo, request-tracing
-- **Testing:** test-http, test-service, test-fakes, model-factories
+- **Testing:** test-browser, test-http, test-service, test-fakes, model-factories
 
 ## Conventions and pitfalls
 

package/skills/{report-framework-issue.md → report-framework-issue/SKILL.md}

@@ -1,3 +1,8 @@
+---
+name: report-framework-issue
+description: "Report a confirmed Warlock.js framework bug or missing capability. Read when behavior contradicts the installed docs, a crash appears to originate in @warlock.js packages, or no documented API meets a requirement; covers minimal reproduction, duplicate searches, sanitized warlock issue output and user approval before filing."
+---
+
 # Report a Warlock.js framework issue
 
 Use this topic when behavior contradicts the installed version's docs or skills,

package/skills/send-response/SKILL.md

@@ -481,3 +481,30 @@ export function requireProduct<T>(product: T | null | undefined): T {
   return product;
 }
 ```
+
+## Format every JSON error response
+
+`http.errorMapper` classifies thrown non-`HttpError` errors as `{ status, message?, payload? }`. It does not see existing `HttpError` subclasses, returned validation errors, helper responses, unmatched routes, or global rate-limit failures.
+
+Use `http.errorResponse` when the application needs one JSON error envelope across those paths:
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  errorMapper: () => ({ status: 500 }),
+  errorResponse({ status, requestId }) {
+    return {
+      error: {
+        code: status >= 500 ? "serverError" : `http${status}`,
+        message: status >= 500 ? "Internal server error." : "Request failed.",
+      },
+      requestId,
+    };
+  },
+} satisfies HttpConfigurations;
+```
+
+The synchronous formatter receives `HttpErrorResponseContext`: `{ status: number, body: unknown, requestId: string }`. Narrow `body` before reading fields; it is the parsed, serialized JSON body. Return a JSON-serializable object or `undefined` to keep the original. The formatter changes only the body, preserving the HTTP status and headers except for recalculated content length, a `private, no-store` cache policy, and the correlation header. If it throws or cannot serialize its result, core logs the formatter error and retains the original body.
+
+The hook covers status 400–599 with `application/json` or an `application/*+json` content type, including Fastify parsing errors, unmatched-route 404s, validation 422s, rate-limit 429s, and 500s. Warlock responses use the ID already stamped from `request.id`. Before Warlock creates a Request, the formatter receives Fastify's `request.id` and echoes that same value under `http.requestId.header` (default `X-Request-Id`). Setting `http.requestId.enabled: false` suppresses that header; without a stamped Warlock ID, the formatter falls back to Fastify's request ID even for routed responses. Keep request-ID headers enabled when the body must correlate with Warlock request logs. HTML pages, files, raw text, streams, and errors after headers have been sent are not reformatted. With no formatter configured, existing response shapes are unchanged.

package/skills/test-browser/SKILL.md

@@ -103,6 +103,7 @@ port-file handshake above when the app supports binding `0` itself.
   document. Selector helpers do not enter frames or closed shadow roots.
 
 Use `--browser /path/to/chrome` or `WARLOCK_E2E_BROWSER` if discovery fails.
+Set `browser.startupTimeoutMs` (default 30 seconds) when the browser is slow to start, for example on shared CI runners.
 `browser: { args: ["--no-sandbox"] }` is an explicit option for controlled root
 containers; it is not a default. On Windows, command arrays should invoke JS tools
 through `process.execPath`, avoiding `.cmd` executables that require a shell.

package/skills/upgrade-from-5-29/SKILL.md

@@ -476,6 +476,10 @@ It replaces standard scripts/dependencies, pins TypeScript 7.0.2, updates genera
 editor settings, removes `healthCheckers.eslint` and selects Oxlint. A generated
 `.prettierignore` becomes `.oxfmtignore`; Oxfmt scripts read it explicitly.
 
+Generated migration configs enable `typescript/no-explicit-any`, `curly`, and
+`no-console` as errors, matching new apps. Fix those diagnostics before running
+`npm run lint:check` and `npx warlock check` again.
+
 The `oxc-toolchain` codemod also updates generated VS Code settings and literal
 ESLint/Oxlint health-check switches. Custom editor settings, checker arrays,
 computed options and nonstandard scripts require review. Oxc diagnostics keep

package/skills/warlock-check/SKILL.md

@@ -127,7 +127,7 @@ const types = runTypecheck({ files: ["src/app/posts/services/publish.service.ts"
 
 ## See also
 
-- `report-framework-issue.md` — confirm a framework bug or missing capability, collect `warlock issue` output, and get the user's approval before filing.
+- the `report-framework-issue` topic — confirm a framework bug or missing capability, collect `warlock issue` output, and get the user's approval before filing.
 - The `warlock-doctor` topic — boot-time diagnostics; `doctor --json` uses the same codes and fields.
 - The `warlock-inspect` topic — the app's routes, models and config as JSON.
 - The `warlock-conventions` topic — the rules behind `WL9001`–`WL9012`, with the fix for each.

package/skills/warlock-trace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: warlock-trace
-description: 'Verify runtime behaviour without a browser: `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running `warlock dev` server and prints what devtools recorded for it — middleware chain with timings, validation result and errors, handler time, queries with N+1 flags, logs, cache operations, captured mails, the response and timings — as a versioned report (`schemaVersion: 1`); `traceRequest()` returns the same object. Triggers: `warlock trace`, `traceRequest`, `TraceReport`, `buildTraceReport`, `x-request-id`, `.warlock/dev-server.json`, `WL8008`, `WL8009`, `WL5004`, `--id-header`; "did validation pass for this request", "which queries does this endpoint run", "is there an N+1 on this route", "what middleware runs on this route", "check the endpoint after my change", "request timeline as JSON". Skip: the devtools dashboard in a browser — the `devtools-overview` skill of @warlock.js/devtools; static route facts (guard, rate limit, schemas) — the `warlock-inspect` topic; typecheck/lint/tests — the `warlock-check` topic.'
+description: 'Verify runtime behaviour without a browser: `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running `warlock dev` server and prints what devtools recorded for it — middleware chain with timings, validation result and errors, handler time, queries with N+1 flags, logs, cache operations, captured mails, the response and timings — as a versioned report (`schemaVersion: 1`); `traceRequest()` returns the same object. Triggers: `warlock trace`, `traceRequest`, `TraceReport`, `buildTraceReport`, `x-request-id`, `.warlock/dev-server.json`, `WL8008`, `WL8009`, `WL5004`, `--id-header`; "did validation pass for this request", "which queries does this endpoint run", "is there an N+1 on this route", "what middleware runs on this route", "check the endpoint after my change", "request timeline as JSON". Skip: the devtools dashboard in a browser — the `warlock-js-devtools` skill; static route facts (guard, rate limit, schemas) — the `warlock-inspect` topic; typecheck/lint/tests — the `warlock-check` topic.'
 ---
 
 # Warlock — `warlock trace`
@@ -78,4 +78,4 @@ Devtools is checked before anything is sent. With `--json` a failure prints `{ "
 
 - The `warlock-inspect` topic — the static facts of a route (guard, rate limit, schemas).
 - The `warlock-check` topic — typecheck, lint, tests and conventions in one run.
-- The `devtools-overview` skill of `@warlock.js/devtools` — the dashboard behind the timeline.
+- The `warlock-js-devtools` skill — the dashboard behind the timeline.

package/skills/write-cli-command/SKILL.md

@@ -337,5 +337,5 @@ Set a unique owner and registry per app instance, then import `processes` from
 the generated module and await `processes.spawn({ kind: "worker", command,
 args, labels })`. Consume output and await `handle.exited`. Use handle stops or
 label filters; never stop processes by command or name. `spawnPty()` lazily
-loads separately installed optional peer `node-pty`. The `supervise-processes`
-skill in `@warlock.js/process` contains complete working examples.
+loads separately installed optional peer `node-pty`. The `warlock-js-process`
+skill contains complete working examples.

package/skills/README.md

@@ -1,76 +0,0 @@
-# @warlock.js/core — skills index
-
-Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The `llms.txt` / `llms-full.txt` at the package root are **generated projections** of this folder — run `node scripts/generate-llms.mjs` from the package root after any skill change; never hand-edit them.
-
-## HTTP layer
-
-- `register-route` — register single routes, prefix groups, middleware-guarded blocks, and RESTful resource chains.
-- `build-restful` — generate standard CRUD endpoints via the `router.route(...)` chain or the `Restful` base class.
-- `create-controller` — author HTTP controllers: `RequestHandler` signature, validated input, response helpers, middleware, `responseSchema` response types.
-- `send-response` — `Response` helpers: success/error variants, status helpers, redirects, files, streams, SSE.
-- `validate-input` — author seal schemas, attach them to controllers, infer types, layer DTOs.
-- `use-middleware` — attach built-in HTTP middleware (rateLimit, concurrencyLimit, maxBodySize, …) via the `middleware` namespace.
-- `write-middleware` — author HTTP middleware: the `({ request, response })` signature, short-circuit, request enrichment.
-- `build-url` — HTTP URL helpers (`url`, `publicUrl`, `assetsUrl`, `uploadsUrl`) anchored at `app.baseUrl`.
-- `upload-file` — handle multipart uploads: `request.file()`, `v.file()` validation, `UploadedFile.save()`.
-- `health-checks` — built-in `/health` + `/ready` endpoints, the `health` registry, and graceful request draining.
-
-## Data layer
-
-- `use-repository` — subclass `RepositoryManager`: `source`/`filterBy`/`defaultOptions`, list/find/CRUD, cached/cursor variants, and the `filterBy`-aware aggregates (`sum`/`avg`/`min`/`max`/`groupBy`/`aggregate`).
-- `use-model-transformers` — schema-side helpers: `useHashedPassword()`, `useComputedSlug()`, and friends.
-- `define-resource` — map model fields to wire-shape via `defineResource()` / `Resource` subclasses (output-only); typed output with `ResourceOutput`, `Serialized<T, W>` and `ModelResourceRegistry`.
-- `write-seeder` — author a seed file with `seeder()` — `name`/`dependsOn`/`once`/`order`/`batchSize`, `run({ track, now, batchSize })`, `warlock seed --drop`.
-
-## Files, media, mail
-
-- `store-file` — read/write/delete files via the `storage` singleton (local/S3/R2/DO Spaces), `StorageFile` handles, presigned URLs.
-- `process-image` — transform images with the `Image` class (resize, crop, rotate, format, watermark, …) on a deferred pipeline.
-- `send-mail` — send transactional email: the `Mail` fluent builder, `sendMail()`, React Email, test-mode capture.
-
-## App, config, lifecycle
-
-- `configure-app` — the two config layers (`warlock.config.ts` vs `src/config/*.ts`), `.env` + `env()`.
-- `use-app-context` — read app-wide context via the `Application` static class and the `app` runtime accessor.
-- `add-connector` — extend the lifecycle with a `BaseConnector` subclass (`start`/`shutdown`/`watchedFiles`).
-- `wire-socket` — configure Socket.IO, reach the live server via `getSocketServer()` / `app.socket`.
-- `use-localization` — multi-locale translations: `groupedTranslations`, `t()` (always, never `request.t()`), locale resolution.
-
-## Use-cases & services
-
-- `write-use-case` — author `useCase()` pipelines: guards, schema, before/after, retry, benchmark, broadcast, lifecycle.
-- `create-module` — scaffold a feature module under `src/app/<name>/` via `warlock generate.module` + follow-up generators.
-- `make-endpoint` — `warlock make endpoint <module>/<name>`: one spec-first endpoint (schema → service, resource, controller, route, locale key, OpenAPI response, HTTP test); `--dry-run` / `--json` on every generator.
-
-## CLI & operations
-
-- `warlock-doctor` — `warlock doctor`: read-only diagnostics (routes/config/connectors/optional-peers/health/release-hygiene) with a pass/warn/fail report and non-zero exit on failure.
-- `warlock-inspect` — `warlock inspect [--json] [--section ...]`: the app's routes, models, resources, config keys, events, pages, jobs, schedules and package versions from the booted registries, as a versioned JSON report; `inspectApp()` from `@warlock.js/core/tooling`.
-- `warlock-check` — `warlock check` / `typecheck` / `explain`: one verify command (typecheck, lint, affected tests, conventions) with one JSON object per problem, stable `WL` error codes, and exit 1 for your code vs 2 for this machine.
-- `warlock-mcp` — `warlock mcp [--http] [--allow-writes]` and `warlock dev --mcp`: the app as an MCP server for coding agents — `inspect_*`, `db_schema`, offline `docs_search` over installed skills, `explain`, `check_run`, `test_run`, devtools `requests_recent`, and `generate_make` / `generate_add` that return a diff by default.
-- `warlock-trace` — `warlock trace <method> <url> [--json]`: send one request to the running dev server and print its devtools timeline (middleware, validation, queries with N+1 flags, logs, response, timings).
-- `warlock-agents-md` — `warlock agents-md [--write]`: the app-specific AGENTS.md section between `warlock:generated` markers, refreshed by `warlock dev`.
-- `warlock-board` — `warlock board init|add|status|send|watch`: a git-ignored task board with review states and append-only messages for an implementer and a reviewer agent.
-- `warlock-routes` — `warlock routes`: list the registered HTTP routes as a verb-colored table (method/path/name/action/middleware/source); filter by method/path/name or emit JSON. Read-only, no connectors.
-- `write-cli-command` — author a custom `warlock <cmd>` via the `command()` factory, or inspect built-in `warlock add` feature scaffolding such as the Web starter.
-- `generate-openapi` — `warlock generate.openapi`: an OpenAPI 3.1 document from the routes (validation, `responseSchema`, auth), plus the dev-only API docs page.
-- `run-app` — `warlock dev` / `warlock build` / `warlock start` operational commands.
-- `update-packages` — bump every `@warlock.js/*` dependency with `warlock update`.
-
-## Testing
-
-- `test-http` — integration tests against a real HTTP server (`startHttpTestServer()`, `testGet` / `testPost`).
-- `test-service` — pure unit tests against services/repositories/models/use-cases via `setupTest({ connectors })`.
-- `store-secrets` — app-scoped credentials, lazy keychain/environment/encrypted file storage, memory backends and safe errors.
-- `test-fakes` — mail, queue, cache, storage, clock, ids and secrets fakes, on by default in tests, and their assertions; opting out.
-- `model-factories` — `defineFactory(Model, (seed) => attrs)`: deterministic `make()` / `create(n)` / states.
-
-## Utilities
-
-- `encrypt-data` — reversible AES-256-GCM `encrypt`/`decrypt`, plus one-way `hmacHash` fingerprints.
-- `hash-password` — one-way bcrypt `hashPassword`/`verifyPassword` and the `useHashedPassword()` transformer.
-- `resolve-path` — path helpers anchored at `process.cwd()` (`rootPath`, `srcPath`, `appPath`, …).
-- `benchmark-code` — time a function with `measure(name, fn, options?)` and classify the latency.
-- `retry-operation` — wrap a flaky operation with `retry(fn, options)` (now from `@mongez/reinforcements`).
-- `lower-stage3-decorators` — the `lowerStage3Decorators()` Vite/Vitest plugin for native decorators.
-- `warlock-conventions` — framework-wide invariants: module layout, canonical imports, layered flow, file naming.