@warlock.js/core 5.35.0 → 5.37.0

package/llms-full.txt

@@ -30,7 +30,7 @@ When the framework is wrong or missing a capability, follow the `report-framewor
 - **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
-- **CLI & running the app:** generate-web-ui, run-app, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
+- **CLI & running the app:** generate-web-ui, run-app, deploy-release, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
 - **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
@@ -2487,6 +2487,86 @@ export const CommentResource = defineResource({
 - The `create-controller` topic — calling `new XResource(record).toJSON()` from a controller.
 
 
+## deploy-release  `@warlock.js/core/skills/deploy-release/SKILL.md`
+
+---
+name: deploy-release
+description: 'Deploy a Warlock application with `warlock release` — freeze a clean commit as a candidate, run the gate, prove migrations, stage the build, switch `current` by atomic symlink, verify the health URL and roll back, configured by the `release` section of `warlock.config.ts`. Triggers: `warlock release`, `release candidate`, `release gate`, `release migrations --prove`, `release stage`, `release activate`, `release verify`, `release rollback`, `release prune`, `ReleaseConfig`, `release.restart.command`, `release.verify`, `.warlock/releases`; "deploy my app", "zero-downtime deploy", "roll back a deploy", "atomic release", "release gate", "prove migrations before deploy". Skip: the `/health` and `/ready` endpoints themselves — the `health-checks` topic; generating a PM2 ecosystem file — `warlock pm2` (the `run-app` topic); publishing the framework packages — `releasing-warlock-monorepo`; competing tools Capistrano, Deployer, hand-rolled symlink scripts.'
+---
+
+# Warlock — deploy with `warlock release`
+
+A recorded, step-by-step deploy for one host. Each step is a command; each writes into a per-release `manifest.json` and a shared `release.log`.
+
+```text
+candidate -> gate -> migrations --prove -> stage -> activate -> verify
+                                                        \-> rollback
+```
+
+Warlock never calls PM2, systemd or any process manager. The only restart is the command you set in `release.restart.command`.
+
+## Configure
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  release: {
+    gate: {
+      checks: [
+        { name: "typecheck", command: "npx warlock typecheck" },
+        { name: "test", command: "npx warlock test" },
+        { name: "build", command: "NODE_ENV=production npx warlock build" },
+      ],
+    },
+    restart: { command: "pm2 reload my-app" },
+    verify: { url: "http://127.0.0.1:2030/health" },
+  },
+});
+```
+
+Defaults: `directory` `.warlock`, `distDir` `dist`, gate = typecheck, check, test, build. Add `.warlock` to `.gitignore`.
+
+## Run the steps
+
+```bash
+npx warlock release candidate [--commit <sha>] [--allow-dirty]
+npx warlock release gate
+npx warlock release migrations --prove --target staging
+npx warlock release stage
+npx warlock release activate --preflight
+npx warlock release activate [--dry-run] [--allow-same]
+npx warlock release verify || npx warlock release rollback
+```
+
+Every command takes an optional release id (`release gate 1.4.0-a1b2c3d`); without one it uses the newest candidate, gated or staged release. `--json` prints the result as JSON; a failed step exits 1.
+
+- **candidate** freezes the commit with `git archive` into `.warlock/releases/<version>-<shortsha>/source`. Refuses a dirty tree without `--allow-dirty` and never overwrites a release.
+- **gate** runs the checks in order in the frozen source and stops at the first failure; results go into the manifest.
+- **migrations** without `--prove` only lists the pending set. With `--prove` it snapshots the ledger, tables and indexes, runs the pending migrations, snapshots again and compares with the expected set (`release.migrations.expected`, default the pending set; `expectedTables`). The migrations really run: use `--target` (a `release.migrations.targets` entry whose `env` is applied before the database connects) on a database that is safe to migrate. A failed proof blocks activation.
+- **stage** (needs a passing gate) copies `dist`, `package.json`, the lockfile, `release.include` entries and `release.json` into `staged/`, atomically.
+- **activate** needs staged artefacts, a passed gate (and proof), and a version strictly greater than the active one (semver; `--allow-same` accepts an equal version, a lower one is refused). It switches `current -> releases/<id>` with an atomic rename, keeps the old target as `previous`, then runs the restart command with `WARLOCK_RELEASE_ID`, `WARLOCK_RELEASE_DIR` and `WARLOCK_RELEASE_CURRENT` set. If that command fails, the pointer stays switched and the exit code is 1.
+- **verify** GETs `release.verify.url` with retries and a timeout and checks the status plus the `version` and `commit` fields of the JSON body against the active release (`verify.versionPath`, `commitPath` and `match` adjust that). Serve the `release.json` values from your health endpoint.
+- **rollback** switches `current` back to `previous` (and `previous` to the release just left), reruns the restart command. It does not roll migrations back: a migration may have destroyed data no reverse step restores; use `warlock migrate --rollback` deliberately if needed.
+- **list** and **status** show releases and the active one; **prune --keep <n>** is the only command that deletes releases and always keeps `current` and `previous`.
+
+## Layout
+
+```text
+.warlock/current -> releases/<id>      .warlock/previous -> releases/<id>
+.warlock/release.log
+.warlock/releases/<id>/{manifest.json, source/, staged/}
+```
+
+Run the app from `.warlock/current/staged` so a restart follows the pointer.
+
+## Pitfalls
+
+- Run `activate --dry-run` or `--preflight` first in CI; both change nothing.
+- Without `restart.command` activation only moves the symlink; the running process keeps serving the old code.
+- `verify` fails when the response does not report a version; set `verify.match` to `[]` to check only the status.
+
+
 ## encrypt-data  `@warlock.js/core/skills/encrypt-data/SKILL.md`
 
 ---
@@ -4014,6 +4094,31 @@ router.get("/webhooks/status", webhookStatusController, { rateLimit: false });
 - The `send-response` topic — picking the right `response.<helper>()`.
 - The `warlock-conventions` topic — module layout, the `guarded` convention, path aliases.
 
+## A named route the browser must never call — `clientVisible: false`
+
+A named API route is embedded in a page's browser route table only when that page's client code reaches its name. Mark an endpoint that browser code must never reach with `clientVisible: false`:
+
+```ts
+router.post("/internal/reindex", reindexController, {
+  name: "internal.reindex",
+  clientVisible: false,
+});
+```
+
+It is then never embedded in a page, and `warlock check` reports a browser reference to its name as `WL9020` (an error). The server still authorizes the call as for any route.
+
+### Offer a route to some sites only — `sites`
+
+In a multi-site app a route answers on every host, and a page of any site may embed it in its browser table. Declare the sites that may embed it on the route or on a group; a route's own `sites` replaces its group's, and a route with none is shared:
+
+```ts
+router.group({ prefix: "/api/admin", sites: ["admin"] }, () => {
+  router.post("/users", createUser, { name: "admin.users.create" });
+});
+```
+
+This limits the browser table only; keep the route's guard. A guard in the route's middleware chain (group middleware included) also keeps it out of a guest's table, and a custom guard must say so with `markAuthGuard(fn)` unless its name contains `auth` or `guard`. `warlock inspect`, `warlock agents-md` and `WL9006` read the same chain, so a guard declared once on a group guards every route inside it.
+
 
 ## report-framework-issue  `@warlock.js/core/skills/report-framework-issue/SKILL.md`
 
@@ -8505,7 +8610,7 @@ and has no Warlock setup or HTTP global setup. `integration` discovers
 It uses the framework setup, HTTP global setup and a generated `src/test-runner.ts`.
 Keep pure service specs beside their source and mock repositories at the boundary.
 Existing config files are preserved; copy the projects layout into them manually.
-Vitest 4.1.10 or newer is required for the generated runner.
+Vitest 5 or newer is required for the generated runner (Vitest 5 removed `vitest/runners`; the runner extends `TestRunner` from `vitest`).
 
 For a unit spec that needs configuration values, use:
 
@@ -8553,20 +8658,20 @@ Run with `npx vitest run --project integration`. Worker lifetime refuses watch,
 threads, isolated module graphs, or a missing runner with a message explaining
 the required settings. Keep `afterAll(teardownTest)` in the setup file: in worker
 mode it marks the end of the file; Vitest's awaited worker cleanup closes the
-runtime once. The runner uses `VitestTestRunner.onCleanupWorkerContext`, verified
-in Vitest 4.1.10's `runners.d.ts`, runner implementation and worker cleanup source.
+runtime once. The runner uses `TestRunner.onCleanupWorkerContext`, verified
+in Vitest 5.0.3's `TestRunner` declaration, runner implementation and worker cleanup source.
 For an existing project, generate this runner without overwriting your config:
 
 ```ts title="src/test-runner.ts"
 import { configureTestWorker } from "@warlock.js/core/tests";
-import { VitestTestRunner } from "vitest/runners";
+import { TestRunner } from "vitest";
 
-export default class WarlockTestRunner extends VitestTestRunner {
-  public constructor(config: ConstructorParameters<typeof VitestTestRunner>[0]) {
+export default class WarlockTestRunner extends TestRunner {
+  public constructor(config: ConstructorParameters<typeof TestRunner>[0]) {
     super(config);
     configureTestWorker(
       { pool: this.pool, watch: config.watch, isolate: config.isolate },
-      (cleanup) => this.onCleanupWorkerContext(cleanup),
+      (cleanup) => this.onCleanupWorkerContext?.(cleanup),
     );
   }
 }
@@ -8585,7 +8690,7 @@ This trades module isolation for startup cost: application singletons, config
 mutations, mocks and module side effects can survive between files. Reset your
 own state in `resetBetweenFiles`, restore mocks, and keep connector selection
 consistent. Give each worker a distinct database/schema using
-`process.env.VITEST_POOL_ID` when preparing test connections. Never drop a shared
+`process.env.VITEST_POOL_ID` (1-based since Vitest 5) when preparing test connections. Never drop a shared
 database from this hook while other workers are using it. The framework does not
 create a memory replica set or a cross-worker lock; those belong to the application's
 global setup. A shared HTTP server and a single replica set can contend on I/O,
@@ -9360,6 +9465,97 @@ one `#vessel` around `{children}`. Client navigation still swaps layout/page
 children while preserving the document root. Remove temporary explicit form IDs
 only when the application does not otherwise depend on those names.
 
+## 5.35 to 5.36 per-page API routes
+
+A page document now carries only the named API routes its client code can reach. Before 5.36 every page carried every named route, so a browser call to a name the build cannot see worked on every page by accident. Check each `apiHref()` and `useSubmitForm({ route })` call:
+
+- A name written as a string literal, a constant or a template with a static prefix is found automatically.
+- A name computed at run time, or taken from a module the build cannot follow, now throws on the page that calls it. Declare the names in that page's setup file, for example `export const config = { apiRoutes: ["orders.*"] };`, a layout or root `config` covers every page that renders it. Or call the endpoint with an explicit `path` and `method`.
+- `npx warlock check` reports the call sites that need a declaration as `WL9019`.
+
+Routes registered with `clientVisible: false` are never embedded, and a browser call to one is an error (`WL9020`). Keep endpoints the browser must not reach on that option. Authorization is unchanged: the server still decides each request.
+
+To measure a page's inline payload, set `build.budgets.payload` (default `64kb`). An over-budget route logs one line per process and never fails a request.
+
+## 5.35 to 5.36 translation payloads
+
+A page's hydration payload now carries only the translations its client code
+can reach, in route-dictionary (`locales.json`) and global-registry (`extend()`)
+apps alike. The groups every page uses (default `app` and `common`) arrive once
+per locale in a hashed, cached file that the page preloads. Nothing in a page's
+render changes: server output is the full dictionary, as before.
+
+Run `warlock build`, then `warlock check`. A `WL9104` warning marks a page that
+renders a translation key computed at runtime. Declare the keys it renders in
+the page's setup file, for example
+`export const config = { translations: ["statuses.*", "members.title"] }`, so the
+page ships only what it uses.
+
+In development, a warning names a key the page reads but its payload lacks, and
+resolves it from the full table so the page keeps working. In production the
+key renders as its own text and the miss is reported once through
+`onClientError` with `kind: "translations"`. Declare the key, or set
+`build: { translations: { prune: false } }` in the web connector options while migrating to
+restore the previous per-page payload.
+
+Global-registry apps are covered too. Their shared table is served at
+`/__warlock/translations/<locale>.<hash>.json`, which is cached immutable in
+production. A direct `trans()` call from `@mongez/localization` is not checked
+for a pruning miss; the calls through `useTrans()` are.
+
+## 5.35 to 5.36 Vite 8 and Vitest 5
+
+`@warlock.js/web` requires Vite 8 (`^8.0.0`) and `@vitejs/plugin-react` 6, and the
+test kit requires Vitest 5. Vite 8 bundles with Rolldown and transforms
+TypeScript with Oxc. Vite 7 is not supported; plugin-react 6 needs Vite 8, so the
+family moves together. Vite 8 needs Node.js 20.19 or 22.12 and newer, Vitest 5
+needs 22.12 or newer; Warlock already requires 22.15.
+
+```bash
+npx warlock upgrade --from 5.35 --to 5.36.0 --dry-run
+npx warlock upgrade --from 5.35 --to 5.36.0
+npm install
+npx warlock check
+```
+
+The `vite-8-vitest-5` codemod:
+
+- raises `vite` (8.3.3), `vitest` and `@vitest/*` (5.0.3) and `@vitejs/plugin-react`
+  (6.1.2) in `dependencies`, `devDependencies`, `overrides` and `resolutions`,
+  keeping `^`, `~` or exact style;
+- rewrites a generated `src/test-runner.ts` from `VitestTestRunner` in
+  `vitest/runners` to `TestRunner` from `vitest`, and calls
+  `this.onCleanupWorkerContext?.(cleanup)` (the hook is absent in vm pools);
+- lists, without editing, imports of the removed `vitest/coverage`,
+  `vitest/reporters`, `vitest/environments`, `vitest/snapshot`, `vitest/suite`,
+  `vitest/mocker` and `vitest/internal/module-runner` entry points, other names
+  imported from `vitest/runners`, a top-level `esbuild` option in a Vite or
+  Vitest config, and object-form `output.manualChunks`.
+
+Do these by hand when the codemod lists them:
+
+- Move a config's `esbuild: { jsx: "automatic" }` to
+  `oxc: { jsx: { runtime: "automatic" } }`. `esbuild.target` is not converted, and
+  Oxc does not lower native decorators: keep `lowerStage3Decorators()` from
+  `@warlock.js/core/vite` first in `plugins` for decorated modules, as in the
+  generated test config.
+- Replace object `manualChunks` with
+  `build.rolldownOptions.output.codeSplitting.groups`; `build.rollupOptions` still
+  works but is deprecated in favour of `build.rolldownOptions`.
+- A custom bundler `external` list that names Node builtins is still refused by the
+  client build.
+
+Vitest 5 changes defaults that can alter a green suite: `clearMocks` is true,
+`json` and `junit` reporters write to `.vitest/` instead of stdout, `-t` joins a
+test's names with `>`, `VITEST_POOL_ID` and `VITEST_WORKER_ID` start at 1, nested
+`vi.mock`/`vi.hoisted` calls throw, and an unawaited `resolves` or `rejects`
+assertion fails the test. Vitest also no longer searches parent directories for a
+config file; run it from the package that owns the config. Official guides:
+https://vite.dev/guide/migration and https://vitest.dev/guide/migration.
+
+A project that uses `@warlock.js/ai`'s custom matchers needs Vitest 5 for their
+TypeScript types.
+
 
 ## upload-file  `@warlock.js/core/skills/upload-file/SKILL.md`
 
@@ -10347,6 +10543,10 @@ workers, and registered module cleanup hooks, including after partial startup.
 A Node loader registration is process-scoped; its message channel is closed at
 teardown. Module-owned timers/listeners must register their cleanup hooks.
 
+## Translation keys in pages (5.36)
+
+`warlock check` reports `WL9104` when a page renders a translation key computed at runtime (`trans(key)` with no static prefix, or a translator passed on as a value). Such a page ships every translation group. Declare its keys in the page's setup file, `export const config = { translations: ["statuses.*", "members.title"] }`, to ship only what it uses. The `web` skill `localize-pages` covers the browser side.
+
 
 ## use-middleware  `@warlock.js/core/skills/use-middleware/SKILL.md`
 
@@ -12214,14 +12414,17 @@ and work through the manual-review list. Use `--lint=oxc` for new apps.
 The following codes default to **warnings**, so upgrading does not fail existing projects.
 They parse real TypeScript/JSX syntax with the same oxc-parser adapter as the existing conventions.
 
-| Code     | Convention                                                                   | Remedy                                                                                                                                                             |
-| -------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `WL9013` | A component file exceeds 150 lines                                           | Split components and extract hooks; configure `componentLineLimit`.                                                                                                |
-| `WL9014` | More than one component in a file                                            | Move each component into its own TSX file.                                                                                                                         |
-| `WL9015` | State/effects or event-handler functions inside a component                  | Move `useState`, `useReducer`, `useEffect`, `useLayoutEffect` and handlers into `use-*.ts` hooks.                                                                  |
-| `WL9016` | Native select, checkbox, radio, date, time or datetime-local input           | Use the design-system control. Native controls are allowed in `src/web/design-system/**`.                                                                          |
-| `WL9017` | DOM input/textarea/select native validation                                  | Use shared schema validation instead of `required`, `pattern`, `min`, `max`, `minLength`, `maxLength` or input `type="email"`. Custom component props are allowed. |
-| `WL9018` | Exported `RequestHandler` in `src/app/**/controllers` lacks `responseSchema` | Assign `handler.responseSchema` to document each response status.                                                                                                  |
+| Code     | Convention                                                                       | Remedy                                                                                                                                                             |
+| -------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `WL9013` | A component file exceeds 150 lines                                               | Split components and extract hooks; configure `componentLineLimit`.                                                                                                |
+| `WL9014` | More than one component in a file                                                | Move each component into its own TSX file.                                                                                                                         |
+| `WL9015` | State/effects or event-handler functions inside a component                      | Move `useState`, `useReducer`, `useEffect`, `useLayoutEffect` and handlers into `use-*.ts` hooks.                                                                  |
+| `WL9016` | Native select, checkbox, radio, date, time or datetime-local input               | Use the design-system control. Native controls are allowed in `src/web/design-system/**`.                                                                          |
+| `WL9017` | DOM input/textarea/select native validation                                      | Use shared schema validation instead of `required`, `pattern`, `min`, `max`, `minLength`, `maxLength` or input `type="email"`. Custom component props are allowed. |
+| `WL9018` | Exported `RequestHandler` in `src/app/**/controllers` lacks `responseSchema`     | Assign `handler.responseSchema` to document each response status.                                                                                                  |
+| `WL9019` | Browser route call (`apiHref`, `useSubmitForm({ route })`) takes a run-time name | Pass a string literal or a template with a static prefix, or declare the names with `config.apiRoutes` in a page setup file.                                       |
+| `WL9020` | Browser code names a route registered with `clientVisible: false` (error)        | Call the endpoint from the server, or remove `clientVisible: false` from the route.                                                                                |
+| `WL9104` | Translation key computed at runtime in `src/web` (the page ships every group)    | Declare the keys with `config.translations` in the page's setup file, for example `["statuses.*"]`.                                                                |
 
 Web rules apply to `src/web/**/*.tsx`. Components are top-level JSX-returning functions
 with a capitalized name (or an anonymous default export). Hook files and ordinary helpers
@@ -12471,7 +12674,7 @@ router.post("/posts", createPostController, { middleware: [authMiddleware("user"
 router.post("/contact", contactController, { public: true });
 ```
 
-A route inside `guarded(() => …)` or `router.group({ middleware: [authMiddleware()] }, …)` is guarded. A middleware counts as a guard when its name contains `auth` or `guard`, or when it is a constant initialised with `markAuthGuard()` in the same file. `warlock dev` warns about the same routes at runtime.
+A route inside `guarded(() => …)` or `router.group({ middleware: [authMiddleware()] }, …)` is guarded. A middleware counts as a guard when its name contains `auth` or `guard`, or when it is a constant initialised with `markAuthGuard()` in the same file, or a local factory that returns `markAuthGuard(fn)` and is called in the `middleware` list. `warlock dev` warns about the same routes at runtime.
 
 ### `WL9007` — safe redirects
 

package/llms.txt

@@ -16,6 +16,7 @@
 - [create-controller](@warlock.js/core/skills/create-controller/SKILL.md): 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.signal`, `request.input`, `controller.validation`, `controller.responseSchema`, `response.success`, `response.successCreate`; "write a controller", "attach a schema to a handler", "thin controller pattern", "guarded request type", "type the API response"; typical import `import { type RequestHandler } from "@warlock.js/core"`. Skip: response helper menu — the `send-response` topic; schema authoring — the `validate-input` topic; URL wiring — the `register-route` topic; competing patterns: `express` middleware functions, `@nestjs/common` `@Controller`/`@Get` decorators.
 - [create-module](@warlock.js/core/skills/create-module/SKILL.md): Scaffold a new feature module under `src/app/<name>/` via `warlock generate.module` and the follow-up generators for controllers, models, repositories, resources, and validation schemas. Triggers: `warlock generate.module`, `generate.controller`, `generate.service`, `generate.model`, `generate.repository`, `generate.resource`, `generate.migration`, `--minimal`, `gen.m`; "scaffold a new module", "create CRUD bootstrap", "add a controller to a module", "generate a model"; typical CLI `npx warlock generate.module <name>`. Skip: framework-wide layout rules — the `warlock-conventions` topic; routes file shape — the `register-route` topic; controller shape — the `create-controller` topic; competing tooling: `@nestjs/cli`, `hygen`, hand-rolled folder layouts.
 - [define-resource](@warlock.js/core/skills/define-resource/SKILL.md): Map model fields to wire-shape via `defineResource()` or `Resource` subclasses. Output-only — never put business logic, hydration, or reconciliation in a resource. Also covers the typed output: `ResourceOutput<typeof R>`, `defineResource<Out>()`, `Serialized<T, W>` and `ModelResourceRegistry`. Triggers: `defineResource`, `Resource`, `RegisterResource`, `toJSON`, `ResourceOutput`, `Serialized`, `ModelResourceRegistry`, `"self"`, `"localized"`, `"uploadsUrl"`; "shape an API response", "type a resource's output", "what does the client receive", "nest related resources", "rename a field on output", "self-referential tree resource"; typical import `import { defineResource } from "@warlock.js/core"`. Skip: localized columns — the `use-localization` topic; URL casting — the `build-url` topic; controller side — the `create-controller` topic; competing libs `@nestjs/swagger` `@ApiProperty`, `class-transformer`, hand-rolled DTO mappers.
+- [deploy-release](@warlock.js/core/skills/deploy-release/SKILL.md): Deploy a Warlock application with `warlock release` — freeze a clean commit as a candidate, run the gate, prove migrations, stage the build, switch `current` by atomic symlink, verify the health URL and roll back, configured by the `release` section of `warlock.config.ts`. Triggers: `warlock release`, `release candidate`, `release gate`, `release migrations --prove`, `release stage`, `release activate`, `release verify`, `release rollback`, `release prune`, `ReleaseConfig`, `release.restart.command`, `release.verify`, `.warlock/releases`; "deploy my app", "zero-downtime deploy", "roll back a deploy", "atomic release", "release gate", "prove migrations before deploy". Skip: the `/health` and `/ready` endpoints themselves — the `health-checks` topic; generating a PM2 ecosystem file — `warlock pm2` (the `run-app` topic); publishing the framework packages — `releasing-warlock-monorepo`; competing tools Capistrano, Deployer, hand-rolled symlink scripts.
 - [encrypt-data](@warlock.js/core/skills/encrypt-data/SKILL.md): Reversible AES-256-GCM `encrypt` / `decrypt` for secrets you need to read back; one-way HMAC-SHA256 `hmacHash` for deterministic fingerprints (lookup/dedup of encrypted columns). Keys come from `src/config/encryption.ts`. Triggers: `encrypt`, `decrypt`, `hmacHash`, `EncryptionConfigurations`, `APP_ENCRYPTION_KEY`, `APP_HMAC_KEY`; "store an API key reversibly", "fingerprint an encrypted column for lookup", "AES-256-GCM secret", "HMAC-SHA256 dedup key"; typical import `import { encrypt, decrypt, hmacHash } from "@warlock.js/core"`. Skip: password hashing — the `hash-password` topic; config wiring — the `configure-app` topic; competing libs Node `crypto` direct, `crypto-js`, `libsodium-wrappers`.
 - [generate-openapi](@warlock.js/core/skills/generate-openapi/SKILL.md): 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.
 - [generate-web-ui](@warlock.js/core/skills/generate-web-ui/SKILL.md): Generate web pages, schema-backed forms and CRUD UI with warlock generate page, form and crud-ui. Includes setup companions, design-system controls, useSubmitForm, optional guarded endpoints and module CRUD prerequisites.

package/package.json

@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^3.0.0",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.35.0",
-    "@warlock.js/cascade": "5.35.0",
-    "@warlock.js/context": "5.35.0",
-    "@warlock.js/fs": "5.35.0",
-    "@warlock.js/logger": "5.35.0",
-    "@warlock.js/seal": "5.35.0",
+    "@warlock.js/cache": "5.37.0",
+    "@warlock.js/cascade": "5.37.0",
+    "@warlock.js/context": "5.37.0",
+    "@warlock.js/fs": "5.37.0",
+    "@warlock.js/logger": "5.37.0",
+    "@warlock.js/seal": "5.37.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -56,12 +56,12 @@
     "@aws-sdk/lib-storage": "^3.955.0",
     "@aws-sdk/s3-request-presigner": "^3.955.0",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/access": "5.35.0",
-    "@warlock.js/ai": "5.35.0",
-    "@warlock.js/ai-tools": "5.35.0",
-    "@warlock.js/devtools": "5.35.0",
-    "@warlock.js/herald": "5.35.0",
-    "@warlock.js/notifications": "5.35.0",
+    "@warlock.js/access": "5.37.0",
+    "@warlock.js/ai": "5.37.0",
+    "@warlock.js/ai-tools": "5.37.0",
+    "@warlock.js/devtools": "5.37.0",
+    "@warlock.js/herald": "5.37.0",
+    "@warlock.js/notifications": "5.37.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -146,7 +146,7 @@
   "engines": {
     "node": ">=22.15"
   },
-  "version": "5.35.0",
+  "version": "5.37.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/deploy-release/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: deploy-release
+description: 'Deploy a Warlock application with `warlock release` — freeze a clean commit as a candidate, run the gate, prove migrations, stage the build, switch `current` by atomic symlink, verify the health URL and roll back, configured by the `release` section of `warlock.config.ts`. Triggers: `warlock release`, `release candidate`, `release gate`, `release migrations --prove`, `release stage`, `release activate`, `release verify`, `release rollback`, `release prune`, `ReleaseConfig`, `release.restart.command`, `release.verify`, `.warlock/releases`; "deploy my app", "zero-downtime deploy", "roll back a deploy", "atomic release", "release gate", "prove migrations before deploy". Skip: the `/health` and `/ready` endpoints themselves — the `health-checks` topic; generating a PM2 ecosystem file — `warlock pm2` (the `run-app` topic); publishing the framework packages — `releasing-warlock-monorepo`; competing tools Capistrano, Deployer, hand-rolled symlink scripts.'
+---
+
+# Warlock — deploy with `warlock release`
+
+A recorded, step-by-step deploy for one host. Each step is a command; each writes into a per-release `manifest.json` and a shared `release.log`.
+
+```text
+candidate -> gate -> migrations --prove -> stage -> activate -> verify
+                                                        \-> rollback
+```
+
+Warlock never calls PM2, systemd or any process manager. The only restart is the command you set in `release.restart.command`.
+
+## Configure
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  release: {
+    gate: {
+      checks: [
+        { name: "typecheck", command: "npx warlock typecheck" },
+        { name: "test", command: "npx warlock test" },
+        { name: "build", command: "NODE_ENV=production npx warlock build" },
+      ],
+    },
+    restart: { command: "pm2 reload my-app" },
+    verify: { url: "http://127.0.0.1:2030/health" },
+  },
+});
+```
+
+Defaults: `directory` `.warlock`, `distDir` `dist`, gate = typecheck, check, test, build. Add `.warlock` to `.gitignore`.
+
+## Run the steps
+
+```bash
+npx warlock release candidate [--commit <sha>] [--allow-dirty]
+npx warlock release gate
+npx warlock release migrations --prove --target staging
+npx warlock release stage
+npx warlock release activate --preflight
+npx warlock release activate [--dry-run] [--allow-same]
+npx warlock release verify || npx warlock release rollback
+```
+
+Every command takes an optional release id (`release gate 1.4.0-a1b2c3d`); without one it uses the newest candidate, gated or staged release. `--json` prints the result as JSON; a failed step exits 1.
+
+- **candidate** freezes the commit with `git archive` into `.warlock/releases/<version>-<shortsha>/source`. Refuses a dirty tree without `--allow-dirty` and never overwrites a release.
+- **gate** runs the checks in order in the frozen source and stops at the first failure; results go into the manifest.
+- **migrations** without `--prove` only lists the pending set. With `--prove` it snapshots the ledger, tables and indexes, runs the pending migrations, snapshots again and compares with the expected set (`release.migrations.expected`, default the pending set; `expectedTables`). The migrations really run: use `--target` (a `release.migrations.targets` entry whose `env` is applied before the database connects) on a database that is safe to migrate. A failed proof blocks activation.
+- **stage** (needs a passing gate) copies `dist`, `package.json`, the lockfile, `release.include` entries and `release.json` into `staged/`, atomically.
+- **activate** needs staged artefacts, a passed gate (and proof), and a version strictly greater than the active one (semver; `--allow-same` accepts an equal version, a lower one is refused). It switches `current -> releases/<id>` with an atomic rename, keeps the old target as `previous`, then runs the restart command with `WARLOCK_RELEASE_ID`, `WARLOCK_RELEASE_DIR` and `WARLOCK_RELEASE_CURRENT` set. If that command fails, the pointer stays switched and the exit code is 1.
+- **verify** GETs `release.verify.url` with retries and a timeout and checks the status plus the `version` and `commit` fields of the JSON body against the active release (`verify.versionPath`, `commitPath` and `match` adjust that). Serve the `release.json` values from your health endpoint.
+- **rollback** switches `current` back to `previous` (and `previous` to the release just left), reruns the restart command. It does not roll migrations back: a migration may have destroyed data no reverse step restores; use `warlock migrate --rollback` deliberately if needed.
+- **list** and **status** show releases and the active one; **prune --keep <n>** is the only command that deletes releases and always keeps `current` and `previous`.
+
+## Layout
+
+```text
+.warlock/current -> releases/<id>      .warlock/previous -> releases/<id>
+.warlock/release.log
+.warlock/releases/<id>/{manifest.json, source/, staged/}
+```
+
+Run the app from `.warlock/current/staged` so a restart follows the pointer.
+
+## Pitfalls
+
+- Run `activate --dry-run` or `--preflight` first in CI; both change nothing.
+- Without `restart.command` activation only moves the symlink; the running process keeps serving the old code.
+- `verify` fails when the response does not report a version; set `verify.match` to `[]` to check only the status.

package/skills/index.md

@@ -22,7 +22,7 @@ When the framework is wrong or missing a capability, follow the `report-framewor
 - **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
-- **CLI & running the app:** generate-web-ui, run-app, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
+- **CLI & running the app:** generate-web-ui, run-app, deploy-release, write-cli-command, add-connector, health-checks, warlock-doctor, warlock-inspect, warlock-check, generate-openapi
 - **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

package/skills/register-route/SKILL.md

@@ -279,3 +279,28 @@ router.get("/webhooks/status", webhookStatusController, { rateLimit: false });
 - The `create-controller` topic — the handler shape, validation, request/response surface.
 - The `send-response` topic — picking the right `response.<helper>()`.
 - The `warlock-conventions` topic — module layout, the `guarded` convention, path aliases.
+
+## A named route the browser must never call — `clientVisible: false`
+
+A named API route is embedded in a page's browser route table only when that page's client code reaches its name. Mark an endpoint that browser code must never reach with `clientVisible: false`:
+
+```ts
+router.post("/internal/reindex", reindexController, {
+  name: "internal.reindex",
+  clientVisible: false,
+});
+```
+
+It is then never embedded in a page, and `warlock check` reports a browser reference to its name as `WL9020` (an error). The server still authorizes the call as for any route.
+
+### Offer a route to some sites only — `sites`
+
+In a multi-site app a route answers on every host, and a page of any site may embed it in its browser table. Declare the sites that may embed it on the route or on a group; a route's own `sites` replaces its group's, and a route with none is shared:
+
+```ts
+router.group({ prefix: "/api/admin", sites: ["admin"] }, () => {
+  router.post("/users", createUser, { name: "admin.users.create" });
+});
+```
+
+This limits the browser table only; keep the route's guard. A guard in the route's middleware chain (group middleware included) also keeps it out of a guest's table, and a custom guard must say so with `markAuthGuard(fn)` unless its name contains `auth` or `guard`. `warlock inspect`, `warlock agents-md` and `WL9006` read the same chain, so a guard declared once on a group guards every route inside it.

package/skills/test-service/SKILL.md

@@ -454,7 +454,7 @@ and has no Warlock setup or HTTP global setup. `integration` discovers
 It uses the framework setup, HTTP global setup and a generated `src/test-runner.ts`.
 Keep pure service specs beside their source and mock repositories at the boundary.
 Existing config files are preserved; copy the projects layout into them manually.
-Vitest 4.1.10 or newer is required for the generated runner.
+Vitest 5 or newer is required for the generated runner (Vitest 5 removed `vitest/runners`; the runner extends `TestRunner` from `vitest`).
 
 For a unit spec that needs configuration values, use:
 
@@ -502,20 +502,20 @@ Run with `npx vitest run --project integration`. Worker lifetime refuses watch,
 threads, isolated module graphs, or a missing runner with a message explaining
 the required settings. Keep `afterAll(teardownTest)` in the setup file: in worker
 mode it marks the end of the file; Vitest's awaited worker cleanup closes the
-runtime once. The runner uses `VitestTestRunner.onCleanupWorkerContext`, verified
-in Vitest 4.1.10's `runners.d.ts`, runner implementation and worker cleanup source.
+runtime once. The runner uses `TestRunner.onCleanupWorkerContext`, verified
+in Vitest 5.0.3's `TestRunner` declaration, runner implementation and worker cleanup source.
 For an existing project, generate this runner without overwriting your config:
 
 ```ts title="src/test-runner.ts"
 import { configureTestWorker } from "@warlock.js/core/tests";
-import { VitestTestRunner } from "vitest/runners";
+import { TestRunner } from "vitest";
 
-export default class WarlockTestRunner extends VitestTestRunner {
-  public constructor(config: ConstructorParameters<typeof VitestTestRunner>[0]) {
+export default class WarlockTestRunner extends TestRunner {
+  public constructor(config: ConstructorParameters<typeof TestRunner>[0]) {
     super(config);
     configureTestWorker(
       { pool: this.pool, watch: config.watch, isolate: config.isolate },
-      (cleanup) => this.onCleanupWorkerContext(cleanup),
+      (cleanup) => this.onCleanupWorkerContext?.(cleanup),
     );
   }
 }
@@ -534,7 +534,7 @@ This trades module isolation for startup cost: application singletons, config
 mutations, mocks and module side effects can survive between files. Reset your
 own state in `resetBetweenFiles`, restore mocks, and keep connector selection
 consistent. Give each worker a distinct database/schema using
-`process.env.VITEST_POOL_ID` when preparing test connections. Never drop a shared
+`process.env.VITEST_POOL_ID` (1-based since Vitest 5) when preparing test connections. Never drop a shared
 database from this hook while other workers are using it. The framework does not
 create a memory replica set or a cross-worker lock; those belong to the application's
 global setup. A shared HTTP server and a single replica set can contend on I/O,