@warlock.js/core 5.31.0 → 5.33.0

package/package.json

@@ -25,17 +25,17 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^3.0.0",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.31.0",
-    "@warlock.js/cascade": "5.31.0",
-    "@warlock.js/context": "5.31.0",
-    "@warlock.js/fs": "5.31.0",
-    "@warlock.js/logger": "5.31.0",
-    "@warlock.js/seal": "5.31.0",
+    "@warlock.js/cache": "5.33.0",
+    "@warlock.js/cascade": "5.33.0",
+    "@warlock.js/context": "5.33.0",
+    "@warlock.js/fs": "5.33.0",
+    "@warlock.js/logger": "5.33.0",
+    "@warlock.js/seal": "5.33.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
-    "esbuild": "^0.27.2",
+    "esbuild": "^0.28.2",
     "eslint": "^9.18.0",
     "fast-glob": "^3.3.3",
     "fastify": "^5.12.5",
@@ -43,22 +43,25 @@
     "get-tsconfig": "^5.0.0-beta.5",
     "glob": "^13.0.6",
     "import-meta-resolve": "^4.2.0",
+    "jsonc-parser": "3.3.1",
     "mime": "^4.1.0",
+    "oxc-parser": "0.154.0",
     "pluralize-esm": "^9.0.5",
-    "typescript": "^5.7.3"
+    "typescript": "7.0.2"
   },
   "peerDependencies": {
+    "@napi-rs/keyring": "^2.1.1",
     "@aws-sdk/client-s3": "^3.955.0",
     "@aws-sdk/client-sesv2": "^3.1025.0",
     "@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.31.0",
-    "@warlock.js/ai": "5.31.0",
-    "@warlock.js/ai-tools": "5.31.0",
-    "@warlock.js/devtools": "5.31.0",
-    "@warlock.js/herald": "5.31.0",
-    "@warlock.js/notifications": "5.31.0",
+    "@warlock.js/access": "5.33.0",
+    "@warlock.js/ai": "5.33.0",
+    "@warlock.js/ai-tools": "5.33.0",
+    "@warlock.js/devtools": "5.33.0",
+    "@warlock.js/herald": "5.33.0",
+    "@warlock.js/notifications": "5.33.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -67,6 +70,9 @@
     "ts-morph": ">=27.0.0"
   },
   "peerDependenciesMeta": {
+    "@napi-rs/keyring": {
+      "optional": true
+    },
     "sharp": {
       "optional": true
     },
@@ -140,7 +146,7 @@
   "engines": {
     "node": ">=22.15"
   },
-  "version": "5.31.0",
+  "version": "5.33.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",
@@ -182,6 +188,12 @@
         "default": "./esm/net/index.mjs"
       }
     },
+    "./secrets": {
+      "import": {
+        "types": "./esm/secrets/index.d.mts",
+        "default": "./esm/secrets/index.mjs"
+      }
+    },
     "./tooling": {
       "import": {
         "types": "./esm/tooling/index.d.mts",

package/skills/README.md

@@ -61,7 +61,8 @@ Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The
 
 - `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 })`.
-- `test-fakes` — mail, queue, cache, storage, clock and ids fakes, on by default in tests, and their assertions; opting out.
+- `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

package/skills/create-module/SKILL.md

@@ -188,3 +188,10 @@ await warmupProductCache();
 - The `validate-input` topic — wiring `schema/*.schema.ts` to controllers.
 - The `write-seeder` topic — populating the generated `seeds/` folder.
 - The `use-localization` topic — populating the generated `utils/locales.ts`.
+
+## Verify generated imports
+
+Generated web starter files match the scaffold’s Prettier configuration, using
+`@ianvs/prettier-plugin-sort-imports` with Babel independently of TypeScript 7.
+After editing generated code, run `npm run format` and `npm run lint:check`.
+Formatting retains unused imports; the linter reports them.

package/skills/index.md

@@ -14,6 +14,8 @@ 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.
+
 ## Topics by area
 
 - **Foundations:** warlock-conventions, create-module, make-endpoint, configure-app, use-app-context, resolve-path, build-url, update-packages, lower-stage3-decorators
@@ -23,7 +25,7 @@ Core is the application runtime: it boots the app, auto-loads each module's spec
 - **CLI & running the app:** run-app, 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, retry-operation, benchmark-code, request-memo, request-tracing
+- **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
 
 ## Conventions and pitfalls

package/skills/report-framework-issue.md

@@ -0,0 +1,154 @@
+# Report a Warlock.js framework issue
+
+Use this topic when behavior contradicts the installed version's docs or skills,
+a crash originates inside `@warlock.js/*`, or a needed framework capability is
+missing. Framework reports belong at <https://github.com/warlockjs/framework>.
+
+## Confirm and search first
+
+1. Reduce the problem to a minimal reproduction in a clean, generic app. Isolate
+   application logic, third-party packages and configuration mistakes; a stack
+   frame in the framework alone does not prove a framework bug.
+2. Read the **installed version's** package `CHANGELOG.md` and skills. Confirm
+   that the documented API exists in that version and check whether a later
+   release already addresses it. For a feature, describe the missing capability
+   and why the documented APIs or an app-level workaround are insufficient.
+3. Run `warlock doctor --json` (see `warlock-doctor.md`). Fix app/environment
+   findings first. If boot fails, retain only the sanitized failure; `warlock
+   issue` itself does not boot the app.
+4. Search existing reports, including closed issues, using distinctive public
+   terms. If a matching issue exists, show its link and help draft a useful
+   follow-up instead of opening a duplicate. Ask before posting that follow-up.
+
+```bash
+gh issue list -R warlockjs/framework --state all --search "public error or capability"
+```
+
+Without GitHub CLI, use
+<https://github.com/warlockjs/framework/issues?q=is%3Aissue> and enter those terms.
+
+## Collect and protect
+
+```bash
+warlock issue --type bug --title "Public description of the failure"
+warlock issue --type feature --title "Public description of the capability" --json
+```
+
+Collect affected package names and **installed versions**, Node and package
+manager versions, OS/architecture, TypeScript version, the reviewed `warlock
+issue` environment output, a minimal reproduction with exact steps, expected
+versus actual behavior, and relevant sanitized logs / `warlock doctor --json`
+output. If a tool cannot run or there are no relevant logs, explain why.
+
+**Never paste secrets, tokens, `.env` contents, customer data, proprietary code or
+private app names** into titles, bodies, logs, screenshots, repro repositories,
+search queries or URLs. Replace the original app with a minimal generic repro.
+Review even generated environment output and stack traces; remove local paths,
+hostnames and identifying details. The command reads installed package metadata
+and a static config summary; it never reads `.env` or executes the app/config.
+Do not attach the app's full config or diagnostic report without sanitizing it.
+
+## Draft and get consent
+
+Choose one template below, replace every prompt with concrete evidence, and
+write the sanitized body to a local UTF-8 file such as `framework-issue.md`.
+**Always show the complete drafted title and body to the user and explicitly ask
+before filing.** Generating a draft or URL is not consent to publish. If the user
+requests edits, show the revised draft and obtain approval for that version.
+
+### Bug body
+
+```markdown
+### Summary
+
+Public description of the framework failure and affected packages.
+
+### Environment / warlock issue output
+
+Reviewed environment output: installed @warlock.js package versions, Node,
+package manager + version, OS/arch, TypeScript, static config summary.
+
+### Minimal reproduction
+
+Public minimal code or repro link, setup commands and exact steps.
+
+### Expected behavior
+
+What should happen, with the installed version's docs/skills reference.
+
+### Actual / current behavior
+
+What happens instead, including the error and impact.
+
+### Sanitized logs / doctor output
+
+Relevant logs and warlock doctor --json, or why unavailable / not applicable.
+
+### Checks
+
+- [ ] Searched existing issues and checked installed-version CHANGELOG and skills.
+- [ ] Removed secrets, tokens, .env, customer data, proprietary code and private app names.
+- [ ] User reviewed this complete draft and approved filing.
+```
+
+### Feature request body
+
+```markdown
+### Problem / use case
+
+Public description of the missing framework capability and affected packages.
+
+### Environment / warlock issue output
+
+Reviewed environment output: installed @warlock.js package versions, Node,
+package manager + version, OS/arch, TypeScript, static config summary.
+
+### Minimal reproduction
+
+Minimal public example of the capability that cannot currently be expressed.
+
+### Proposed behavior
+
+Desired API/behavior, with an example and why it belongs in the framework.
+
+### Actual / current behavior
+
+Current limitation and relevant installed-version docs/skills.
+
+### Alternatives considered
+
+Existing APIs, app-level workarounds and their limitations.
+
+### Sanitized logs / doctor output
+
+Relevant logs and warlock doctor --json, or why unavailable / not applicable.
+
+### Checks
+
+- [ ] Searched existing issues and checked installed-version CHANGELOG and skills.
+- [ ] Removed secrets, tokens, .env, customer data, proprietary code and private app names.
+- [ ] User reviewed this complete draft and approved filing.
+```
+
+Only check a box after completing that step, including obtaining consent.
+
+## File the approved draft
+
+Check `gh --version` and `gh auth status --hostname github.com`. If GitHub CLI is
+available and authenticated, **after approval** run:
+
+```bash
+gh issue create -R warlockjs/framework --title "Approved public title" --body-file framework-issue.md
+```
+
+Return the created issue's link. If GitHub CLI is unavailable or unauthenticated,
+give the user the pre-filled new-issue URL printed by `warlock issue` together
+with the approved body. The URL selects `bug.yml` or `feature.yml` and prefills
+the environment field; the user must complete the remaining form fields. URLs
+are capped at 7,500 characters and may include a truncation note: restore the
+remaining reviewed output manually. Never claim the issue was filed from merely
+printing or opening a URL. `warlock issue` never sends anything itself.
+
+GitHub CLI flags: [list](https://cli.github.com/manual/gh_issue_list),
+[create](https://cli.github.com/manual/gh_issue_create),
+[authentication](https://cli.github.com/manual/gh_auth_status).

package/skills/run-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-app
-description: 'Three operational commands — `warlock dev` (HMR + type-gen + health checks), `warlock build` (esbuild bundle), `warlock start` (spawn the production bundle). All flags, all `warlock.config.ts` knobs that shape them. Triggers: `warlock dev`, `warlock build`, `warlock start`, `devServer`, `--fresh`, `--skip-typings`, `--skip-health`, `outdir`, `outFile`, `sourcemap`, `PortInUseError`, `assertPortIsAvailable`, `EADDRINUSE`, `EsbuildBinaryMissingError`, `detectJavaScriptRuntime`, `assertNodeOnlyCommand`, Bun, Deno, `bun dist/app.js`, `deno run -A`; "start the dev server", "build for production", "run the bundle", "skip type generation", "tune watch globs", "dev server keyboard shortcuts", "press r to restart", "press q to quit", "restart the dev server", "port already in use", "run on Bun", "run on Deno", "supported runtimes"; typical config `warlock.config.ts > devServer / build`. Skip: writing a custom CLI — the `write-cli-command` topic; config shape — the `configure-app` topic; competing tooling `nodemon`, `tsx`, `ts-node-dev`, `esbuild` direct.'
+description: 'Operational commands — `warlock dev` (HMR + type-gen + health checks), `warlock build` (esbuild bundle), `warlock start` (spawn the production bundle), `warlock pm2 init` / `reload` (optional deployment tooling). All flags, all `warlock.config.ts` knobs that shape them. Triggers: `warlock pm2`, `ecosystem.config.cjs`, `wait_ready`, `kill_timeout`, `app.shutdownTimeout`, `warlock dev`, `warlock build`, `warlock start`, `devServer`, `--fresh`, `--skip-typings`, `--skip-health`, `outdir`, `outFile`, `sourcemap`, `PortInUseError`, `assertPortIsAvailable`, `EADDRINUSE`, `EsbuildBinaryMissingError`, `detectJavaScriptRuntime`, `assertNodeOnlyCommand`, Bun, Deno, `bun dist/app.js`, `deno run -A`; "start the dev server", "build for production", "run the bundle", "skip type generation", "tune watch globs", "dev server keyboard shortcuts", "press r to restart", "press q to quit", "restart the dev server", "port already in use", "run on Bun", "run on Deno", "supported runtimes"; typical config `warlock.config.ts > devServer / build`. Skip: writing a custom CLI — the `write-cli-command` topic; config shape — the `configure-app` topic; competing tooling `nodemon`, `tsx`, `ts-node-dev`, `esbuild` direct.'
 ---
 
 # Warlock — run the app
@@ -150,13 +150,13 @@ export default defineConfig({
 
 - **`watch.include` / `watch.exclude`** — globs piped into the file watcher. Override when you have non-`.ts(x)` files driving reloads (e.g. SQL fixtures), or to exclude a generated folder.
 - **`generateTypings`** — turn off if you're committing generated typings and don't want them rewritten on every boot. The `--skip-typings` flag is the per-run version.
-- **`healthCheckers`** — built-in switches (`{ typescript?, eslint?, oxlint? }`), custom file health checker contracts, or `false` to disable. The `--skip-health` flag disables all checkers for that run. TypeScript runs by default. ESLint uses core's dependency and requires only an app-root flat config; Oxlint requires its package installed in the app plus a config. Both run when configured.
+- **`healthCheckers`** — built-in switches (`{ typescript?, eslint?, oxlint? }`), custom file health checker contracts, or `false` to disable. The `--skip-health` flag disables all checkers for that run. TypeScript runs by default. ESLint uses core's dependency and requires only an app-root flat config; Oxlint requires its package installed in the app plus a config. ESLint is disabled by default; explicitly set `eslint: true` to retain it until removal in 5.34.0. Enabling it prints one deprecation warning and the Oxc migration command.
 - **`transpileCacheDebug`** — diagnostic only. Names `.warlock/transpile/*.js` files `<slug>.<hash>.js` and appends `// @source <path>` markers so you can eyeball which cache entry came from which source. Leave off in normal use.
 - **`checkForUpdates`** — on `warlock dev` start, check npm for a newer `@warlock.js/core` and print a one-line notice if one exists. Best-effort and non-blocking; auto-skipped in CI and non-TTY shells. In an interactive terminal the notice arms a **`u` shortcut** that updates every `@warlock.js/*` package, installs, and restarts the server; elsewhere it prints `npx warlock update` instead. The registry answer is cached for 24h in `.warlock/update-check.json`, so a day of restarts costs one lookup. See the `update-packages` topic.
 - **`restartOnConfigChange`** — restart the dev server when `warlock.config.ts` or any `.env*` changes (default `true`). Set `false` to get a warning instead and restart by hand. Neither file can be hot-reloaded, so without a restart the running services keep the old values.
 - **`timings`** — print a one-line, per-phase breakdown next to the `hmr update` line on every hot reload: `watcher`, `debounce`, `graph`, `reimport`, `connectors`. `watcher` is the raw-fs-notification-to-stabilised-event gap (chokidar's `awaitWriteFinish` window); `debounce` is the handler's own adaptive wait; the rest are self-explanatory. Opt-in, off by default — a disabled flag costs one boolean check per reload, since the watcher-settle bookkeeping only runs when this is on. Use it to see which phase a slow reload is actually spending time in.
 
-### Optional Oxlint file checks
+### Default Oxlint file checks
 
 Install `oxlint` in the app (`npm install --save-dev oxlint`) and add `.oxlintrc.json` at the app root:
 
@@ -178,7 +178,7 @@ export default defineConfig({
 });
 ```
 
-Omit the switches to run TypeScript and every installed/configured linter; `true` still requires the linter's config, and Oxlint also requires its app-installed package. Set `oxlint: false` to disable only Oxlint while leaving other defaults intact. A custom checker array replaces the built-in list. Config discovery also accepts `.oxlintrc.jsonc`, `oxlint.config.ts` and `oxlint.config.mts`; use JSON/JSONC on Node 22.15 because current Oxlint TypeScript configs need Node 22.18 or newer.
+Omit the switches to run TypeScript and installed/configured Oxlint; ESLint is off by default and requires `eslint: true`; `true` still requires the linter's config, and Oxlint also requires its app-installed package. Set `oxlint: false` to disable only Oxlint while leaving other defaults intact. A custom checker array replaces the built-in list. Config discovery also accepts `.oxlintrc.jsonc`, `oxlint.config.ts` and `oxlint.config.mts`; use JSON/JSONC on Node 22.15 because current Oxlint TypeScript configs need Node 22.18 or newer.
 
 ## `warlock build` — production bundle
 
@@ -412,11 +412,120 @@ Configured http.port "03999" normalised to 3999.
 Three consequences worth knowing:
 
 1. **A queue worker with no http connector still reports.** Readiness hangs on a completed boot, not on a bound port. `port` is simply absent.
-2. **Running the bundle any other way changes nothing.** `node dist/app.js`, a Docker `CMD`, or pm2 — the signal is a strict no-op without both the IPC channel and the handshake flag, so Warlock never writes into a channel that belongs to another supervisor.
+2. **PM2 receives its own readiness message (5.33.0+).** With an IPC channel and PM2's `pm_id` present, core sends `"ready"` after completed boot and leaves the channel open. Plain Node/Docker launches without IPC remain silent. `warlock start` takes priority when its handshake is present.
 3. **A bundle built before 4.11.0 has no signal.** It starts and runs normally, and after ten seconds prints a note on **stderr only** telling you to re-run `warlock build`. An absent signal is never an error, never fails the run, and never kills a slow boot.
 
 If you need the same fact inside the app, use `Application.onceBooted()` / `Application.whenBooted()` — the signal and your listeners fire from the same latch.
 
+## `warlock pm2 init` / `reload` — optional production supervision
+
+PM2 is operator tooling, never a core dependency. Install it separately and
+put `pm2` on `PATH`. Generate from the app root with the target environment:
+
+```bash
+NODE_ENV=production npx warlock build
+NODE_ENV=production npx warlock pm2 init
+# package.json name=store, app.appName=api → store-api-production
+pm2 start ecosystem.config.cjs --only store-api-production
+
+# Deploy a fresh successful build, then reload only this app:
+NODE_ENV=production npx warlock pm2 reload
+NODE_ENV=production npx warlock pm2 reload --id 7
+```
+
+`init` reads app/http/socket config and resolved build paths without starting
+connectors, bootstrap or prestart. It creates `ecosystem.config.cjs` exclusively;
+an existing file is an error. It works without PM2 installed or a prior build.
+The file runs the built entry directly, with an absolute `cwd`, Node interpreter
+and source maps matching `build.sourcemap`.
+
+The identity is `<project>-<app>-<NODE_ENV>`; project defaults to `package.json`
+name (`@team/store` → `team-store`), app to `app.appName` or `app`, environment
+to `NODE_ENV` or `development`. Use `--project store --app api` to override the
+components, and repeat those overrides on reload. Components accept letters,
+digits, `_` and `-`, starting with a letter/digit. Choose a combination unique
+within the daemon; no patterns or broad selectors are supported.
+
+```bash
+NODE_ENV=production npx warlock pm2 init --project store --app api \
+  --cluster --instances 2 --listen-timeout 60000
+NODE_ENV=production npx warlock pm2 reload --project store --app api
+```
+
+Defaults: `exec_mode: "fork"`, `instances: 1`, `wait_ready: true`,
+`listen_timeout: 30000`. `--cluster` opts into two workers by default;
+`--instances` accepts a positive integer or `max`, only with `--cluster`.
+Fork reload falls back to restart and may interrupt traffic. PM2 cluster reload
+can replace workers while others serve, but a boot/readiness timeout can still
+cause downtime. Keep both the PM2 daemon and app on Node 22.15+; cluster uses
+the daemon's runtime.
+
+`kill_timeout` equals the existing overall connector budget,
+`app.shutdownTimeout` (default 10000ms), now typed on `AppConfigurations`:
+
+```ts
+import type { AppConfigurations } from "@warlock.js/core";
+
+export default {
+  appName: "api",
+  shutdownTimeout: 20000,
+} satisfies AppConfigurations;
+```
+
+Keep `http.gracefulShutdown.timeout` lower (e.g. 10000ms), with room for other
+connectors, hooks and log flushes. PM2's kill timer covers the whole exit;
+core's connector timer starts after app hooks and finishes before log flushing.
+The generated comment and CLI output show the configured readiness URL (or an
+unavailable notice for no HTTP, disabled health or ephemeral ports). PM2 itself
+does not poll it. Use an external deployment probe.
+
+Core emits `process.send("ready")` once at completed boot when PM2's `pm_id`
+and IPC are present, after HTTP and the connectors have started. It never
+disconnects PM2's channel. Socket-only apps also await the listener and reject
+bind failures before completing boot. Rebuild with core 5.33+ before using `wait_ready`.
+`listen_timeout` limits waiting for readiness; `kill_timeout` limits shutdown
+before PM2's forced kill. Core handles PM2's default `SIGINT` gracefully.
+
+With sockets enabled, cluster generation/reload refuse a missing
+`socket.adapter` factory and require `socket.options.transports: ["websocket"]`
+with WebSocket-only clients. The adapter handles broadcasts; polling still
+needs sticky routing to each worker, which this generator does not install.
+For polling, use individual fork listeners behind a sticky proxy or a custom
+cluster primary. See the `wire-socket` topic. Avoid duplicating worker jobs
+and in-memory sessions across HTTP workers.
+
+`reload` requires a successful build marker, reads `pm2 jlist`, verifies **all**
+exact-name matches against the app's absolute cwd and entry, then calls
+`pm2 reload <numeric-id>` sequentially. `--id` narrows to one verified worker.
+Foreign cwd/script, invalid selectors, offline cluster workers or cluster
+workers without `wait_ready` are refused before reload. Reload uses settings
+already registered in PM2; regenerate/reapply the ecosystem when they change.
+
+On shared servers, inspect the current PM2 id and path before stopping:
+
+```bash
+pm2 list
+pm2 show 7
+pm2 stop 7
+```
+
+Repeat for each intended worker id. Never stop by pattern or broad name, and
+avoid daemon-wide operations. PM2 ids are not OS PIDs and can change after an
+app is deleted/recreated.
+
+To put logger entries in PM2's captured stdout, configure
+`src/config/log.ts` with `production: { channels: [new ConsoleLog()] }`
+(`ConsoleLog` comes from `@warlock.js/logger`). Keep `time: false` and omit
+`log_date_format` to preserve the logger's timestamp/module/action format.
+Generated `merge_logs: false` keeps worker logs separate. PM2 JSON output wraps
+captured text; it does not recover logger fields. Use `JSONFileLog` with a
+distinct per-worker storage path for structured persistent entries.
+
+Official references: [PM2 readiness/shutdown](https://pm2.keymetrics.io/docs/usage/signals-clean-restart/),
+[cluster reload](https://pm2.keymetrics.io/docs/usage/cluster-mode/),
+[Socket.IO multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/).
+Full docs: `docs/src/content/docs/v/latest/core/cli/pm2.mdx`.
+
 ## Runtimes — Node, Bun, Deno
 
 | Command              | Node.js 22.15+     | Bun 1.4.3                     | Deno 2.9.7                    |
@@ -599,8 +708,9 @@ diagnostics keep their specific message. Command failure messages contain a
 bounded status/output summary, without the batch command line. Shutdown gives
 workers up to 500 ms to exit and reap owned CLI children before forcing termination.
 
-Source TypeScript health workers use the framework's JavaScript/tsx bootstrap on
-Node.js 22.15; published JavaScript workers start directly. Framework regression
-tests cover that bootstrap and a built `.mjs` worker with no inherited loader
-hooks. Both paths check configured declaration roots, source updates and deleted
-declarations under the supported minimum runtime.
+Source TypeScript health workers use the framework's JavaScript bootstrap to
+register tsx inside each worker on Node.js 22.15 and Node.js 24. Registration
+remains active for later TypeScript imports and lets native dependencies load
+Node builtins through `createRequire`. Published JavaScript workers start
+directly. Regression tests cover both paths without inherited loader hooks,
+including configured declaration roots, source updates and deleted declarations.

package/skills/store-secrets/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: store-secrets
+description: "Store app credentials with secrets.get/set/remove/has and environmentName; lazy optional OS keychain, read-only scoped environment variables, encrypted file fallback, typed SecretStoreError and memory-backed secretsFake. Use for provider keys and OAuth credentials the app must read back. Skip user passwords (hash-password) and encrypted database columns (encrypt-data)."
+---
+
+# Application secret store
+
+Use core's facade; there is no separate package or preparation step:
+
+```ts
+import { secrets, SecretStoreError } from "@warlock.js/core";
+// The same API is available from "@warlock.js/core/secrets".
+
+await secrets.set("vendor-token", "provider-credential");
+const token = await secrets.get("vendor-token"); // string | undefined
+const exists = await secrets.has("vendor-token"); // boolean; true for ""
+const removed = await secrets.remove("vendor-token"); // boolean
+const variable = secrets.environmentName("vendor-token"); // variable name, not value
+
+try {
+  await secrets.remove("vendor-token");
+} catch (error) {
+  if (error instanceof SecretStoreError && error.code === "READ_ONLY") {
+    // Change the deployment environment instead.
+  } else {
+    throw error;
+  }
+}
+```
+
+Names are case-sensitive, nonempty strings of at most 256 UTF-16 code units. Values are strings, including empty strings. Every operation is async, except `environmentName()`.
+
+## Configuration and backend decisions
+
+- Default namespace: app name plus the SHA-256 hash of the absolute project root. For changing release directories, configure a stable unique namespace including the deployment environment.
+- Reads: OS keychain → exact scoped environment variable → encrypted file.
+- Optional peer: `npm install @napi-rs/keyring`. Core lazily uses its 2.1.1 `AsyncEntry` API. Linux requires `secret-service` for persistence; it does not use the memory-only keyutils fallback. Sources: [official README](https://github.com/Brooooooklyn/keyring-node#readme), [published declarations](https://www.npmjs.com/package/@napi-rs/keyring?activeTab=code), verified 2026-10-19.
+- One initial read-only probe selects the keychain for that store lifetime. Missing peer/initially unavailable service falls back automatically. A later keychain failure throws `UNAVAILABLE`; do not silently change backends mid-operation. Keep backend availability consistent between deployments; independent backend writes are not reconciled automatically.
+- Environment names are `WARLOCK_SECRET_<namespace UTF-8 uppercase hex>_<name UTF-8 uppercase hex>`; use `environmentName()` to avoid guessing. No unscoped environment fallback. Both mutation methods throw `READ_ONLY` if that variable is present, including `""` and shadowed environment values.
+- File fallback derives a per-namespace HKDF-SHA256 key from `encryption.key` (64 hex characters, conventionally `APP_ENCRYPTION_KEY`) and uses AES-256-GCM with name/namespace authenticated data. It never stores an unencrypted value/key file. Core's global `encrypt()` helper cannot accept a derived key, so the backend uses Node crypto without changing global config. Consult `encrypt-data` for app key provisioning.
+- Default files: `storage/secrets/<namespace hash>/<name hash>.secret`. Directories `0700`, files `0600`, owner checks, no symlinks/hardlinks, synced temporary writes and rename. Parent directories must be trusted. Same-key concurrent writes use last completed rename.
+- File fallback fails closed on Windows because Node modes cannot enforce owner-only ACLs; use keychain/environment. See [Node file modes](https://nodejs.org/docs/latest-v22.x/api/fs.html#file-modes).
+- Keychain writes clear an old file copy; removal clears both writable layers. Retry errors after fixing the backend; a multi-layer operation may partially complete.
+
+```ts title="src/config/secrets.ts"
+import type { SecretsConfigurations } from "@warlock.js/core";
+
+export default {
+  namespace: "sample-app-production",
+  // directory: "/srv/sample-app/private-secrets",
+} satisfies SecretsConfigurations;
+```
+
+Never change namespace or encryption key without a migration. Keep file storage outside publicly served paths, and secure the app key separately from encrypted backups.
+
+## Isolated tests and explicit stores
+
+`setupTest()` and the HTTP test harness install `secretsFake` by default. `NODE_ENV=test` alone does not install it. Opt out with `tests.fakes: { secrets: false }` only for real-backend tests. Memory is per process; HTTP server and test worker do not share it.
+
+```ts
+import { secrets } from "@warlock.js/core";
+import { secretsFake } from "@warlock.js/core/tests";
+
+secretsFake.install(); // only needed without the standard test harness
+try {
+  secretsFake.clear();
+  await secrets.set("vendor-token", "test-credential");
+  await secretsFake.assertHas("vendor-token");
+  await secretsFake.assertStored("vendor-token", "test-credential");
+  await secrets.remove("vendor-token");
+  await secretsFake.assertMissing("vendor-token");
+  const installed = secretsFake.isInstalled();
+} finally {
+  secretsFake.restore();
+}
+```
+
+For standalone unit tests or distinct app instances:
+
+```ts
+import { MemorySecretBackend, SecretStore } from "@warlock.js/core/secrets";
+import type { SecretBackend, SecretStoreOptions } from "@warlock.js/core/secrets";
+
+const backend: SecretBackend = new MemorySecretBackend();
+const options: SecretStoreOptions = { namespace: "test-app", backend };
+const store = new SecretStore(options);
+await store.set("vendor-token", "test-credential");
+await store.get("vendor-token");
+await store.has("vendor-token");
+await store.remove("vendor-token");
+
+const memory = new MemorySecretBackend();
+memory.clear();
+```
+
+Options also allow a `directory` and `encryptionKey` (string or lazy callback); the default key reads `encryption.key` lazily. A custom `SecretBackend` implements async namespace-aware `get`, `set`, and `remove`. Explicit backends bypass keychain, environment and files; the test fake only swaps the shared facade.
+
+## Error and logging contract
+
+`SecretStoreError.code` is `INVALID_NAME`, `INVALID_VALUE`, `INVALID_NAMESPACE`, `READ_ONLY`, `KEY_REQUIRED`, `UNAVAILABLE`, `UNSAFE_FILE` or `CORRUPT_FILE`. Errors never include names, values, paths or vendor causes. `KEY_REQUIRED` means provision/fix the app encryption key; `CORRUPT_FILE` means wrong key, invalid format or failed authentication. Never replace an unreadable store with an empty one.
+
+The store never logs credentials. It registers encountered names and literal values with `@warlock.js/logger` for process-lifetime masking, including old/removed/failed-write values, interpolated messages, Error text/causes, and channel error reports. Keys and exact values stay protected even with permissive custom censors. Registration retains values in memory. It cannot mask direct console/third-party logging, earlier logs, transformed/encoded values, or credentials never encountered by the store. Keep secrets out of logs even with masking enabled. Fake assertion errors do not print values.

package/skills/test-fakes/SKILL.md

@@ -1,20 +1,21 @@
 ---
 name: test-fakes
-description: 'The test fakes Warlock installs by default in the test environment — `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake` — and their assertions (`assertSent`, `assertPushed`, `assertHas`, `assertExists`, `travel`), plus how to opt out (`tests.fakes`, `setupTest({ fakes })`). Triggers: `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake`, `installTestFakes`, `restoreTestFakes`, `tests.fakes`, `FakeAssertionError`, `clock.now`, `ids.uuid`, `setDispatchInterceptor`; "assert an email was sent", "assert a job was dispatched", "freeze time in a test", "deterministic ids", "tests without Redis", "keep the real cache driver in tests". Typical import `import { mailFake, queueFake } from "@warlock.js/core/tests"`. Skip: HTTP request helpers — the `test-http` topic; fixtures — the `model-factories` topic.'
+description: 'The test fakes Warlock installs by default in the test environment — `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake`, `secretsFake` — and their assertions (`assertSent`, `assertPushed`, `assertHas`, `assertExists`, `travel`), plus how to opt out (`tests.fakes`, `setupTest({ fakes })`). Triggers: `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake`, `secretsFake`, `installTestFakes`, `restoreTestFakes`, `tests.fakes`, `FakeAssertionError`, `clock.now`, `ids.uuid`, `setDispatchInterceptor`; "assert an email was sent", "assert a job was dispatched", "freeze time in a test", "deterministic ids", "tests without Redis", "keep the real cache driver in tests". Typical import `import { mailFake, queueFake } from "@warlock.js/core/tests"`. Skip: HTTP request helpers — the `test-http` topic; fixtures — the `model-factories` topic.'
 ---
 
 # Warlock — test fakes
 
-In the test environment six fakes are installed for you: `setupTest()` installs them in every test file once its connectors are up, `startHttpTestServer()` installs them in the shared server, and teardown restores them. Nothing is delivered, pushed to Redis, uploaded to a bucket, and time and ids are deterministic.
+In the test environment seven fakes are installed for you: `setupTest()` installs them in every test file once its connectors are up, `startHttpTestServer()` installs them in the shared server, and teardown restores them. Nothing is delivered, pushed to Redis, uploaded to a bucket, and time and ids are deterministic.
 
-| Fake          | Replaces                                                        |
-| ------------- | --------------------------------------------------------------- |
-| `mailFake`    | Mail delivery: `sendMail()` / `Mail` sends are captured         |
-| `queueFake`   | `@warlock.js/queue` dispatch: jobs are recorded, not pushed     |
-| `cacheFake`   | The cache's current driver: a fresh in-memory driver            |
-| `storageFake` | Every storage driver (local, S3, R2, Spaces): a temp directory  |
-| `clockFake`   | `clock` from `@warlock.js/core`: frozen at 2026-01-01T00:00:00Z |
-| `idsFake`     | `ids` from `@warlock.js/core`: numbered UUIDs and tokens        |
+| Fake          | Replaces                                                              |
+| ------------- | --------------------------------------------------------------------- |
+| `mailFake`    | Mail delivery: `sendMail()` / `Mail` sends are captured               |
+| `queueFake`   | `@warlock.js/queue` dispatch: jobs are recorded, not pushed           |
+| `cacheFake`   | The cache's current driver: a fresh in-memory driver                  |
+| `storageFake` | Every storage driver (local, S3, R2, Spaces): a temp directory        |
+| `clockFake`   | `clock` from `@warlock.js/core`: frozen at 2026-01-01T00:00:00Z       |
+| `idsFake`     | `ids` from `@warlock.js/core`: numbered UUIDs and tokens              |
+| `secretsFake` | The `secrets` facade: namespace-aware memory, no OS/environment/files |
 
 ## Assert what your code did
 
@@ -42,7 +43,8 @@ it("queues the report, mails the requester and caches the request", async () =>
 - **queue** — `assertPushed(jobOrName, payloadSubset?)`, `assertNotPushed`, `assertPushedCount(n, job?)`, `assertNothingPushed()`, `pushed(job?, matcher?)`. Each record has `id`, `name`, `queue`, `payload`, `options` (`delay`, `priority`, `jobId`) and `pushedAt`. An explicit `jobId` stays idempotent and `job.find(id)` answers from the record. Jobs are not run — call the handler to test it.
 - **cache** — `assertHas(key)`, `assertMissing(key)`, `assertStored(key, value)` (deep equality), `driver()`, `clear()`. TTLs, tags, namespaces and locks are the real memory driver's.
 - **storage** — `assertExists(path, driver?)`, `assertMissing(path, driver?)`, `files(driver?)`, `root()`. Each configured driver name gets a folder under one temp root, shared with the HTTP test server through `WARLOCK_TEST_STORAGE_ROOT`; the process that created it deletes it.
-- A failed assertion throws `FakeAssertionError` listing what was recorded.
+- **secrets** — async `assertHas(name)`, `assertMissing(name)`, `assertStored(name, value)`, plus `clear()` and `isInstalled()`. Assertion errors never reveal values. See `store-secrets` for examples and explicit memory stores.
+- A failed assertion throws `FakeAssertionError`; secret assertions omit values. Other fakes list what was recorded.
 
 ## Time and ids