@warlock.js/core 5.30.0 → 5.32.0

package/skills/resolve-path/SKILL.md

@@ -12,30 +12,30 @@ Twelve helpers, all anchored at `process.cwd()`, all in `@warlock.js/core`. They
 ```ts
 import { appPath, configPath, uploadsPath, storagePath } from "@warlock.js/core";
 
-appPath("orders/routes.ts");           // → <cwd>/src/app/orders/routes.ts
-configPath("http.ts");                  // → <cwd>/src/config/http.ts
-uploadsPath("avatars/42.png");          // → <cwd>/storage/uploads/avatars/42.png
-storagePath("backups/2026-01.tar.gz");  // → <cwd>/storage/backups/2026-01.tar.gz
+appPath("orders/routes.ts"); // → <cwd>/src/app/orders/routes.ts
+configPath("http.ts"); // → <cwd>/src/config/http.ts
+uploadsPath("avatars/42.png"); // → <cwd>/storage/uploads/avatars/42.png
+storagePath("backups/2026-01.tar.gz"); // → <cwd>/storage/backups/2026-01.tar.gz
 ```
 
 Every helper takes any number of path segments and joins them. No-argument calls return the base directory itself.
 
 ## Full inventory
 
-| Helper             | Resolves to                              | Notes                                                              |
-| ------------------ | ---------------------------------------- | ------------------------------------------------------------------ |
-| `rootPath(...p)`   | `<cwd>/<...p>`                           | Also `Application.rootPath`. Base of every other helper.           |
-| `srcPath(...p)`    | `<cwd>/src/<...p>`                       | Also `Application.srcPath`.                                        |
-| `appPath(p?)`      | `<cwd>/src/app/<p>`                      | Also `Application.appPath`. Module roots live here.                |
-| `configPath(...p)` | `<cwd>/src/config/<...p>`                | `src/config/*.ts` subsystem configs.                               |
-| `publicPath(p?)`   | `<cwd>/public/<p>`                       | Also `Application.publicPath`. Static assets served as-is.         |
-| `storagePath(p?)`  | `<cwd>/storage/<p>`                      | Also `Application.storagePath`. Root for framework-managed files.  |
-| `uploadsPath(p?)`  | `<cwd>/storage/uploads/<p>` *(default)*  | Also `Application.uploadsPath`. Honors `config.uploads.root` override (string or function). |
-| `cachePath(p?)`    | `<cwd>/storage/cache/<p>`                | Persistent cache files.                                            |
-| `logsPath(p?)`     | `<cwd>/storage/logs/<p>`                 | Application logs.                                                  |
-| `tempPath(p?)`     | `<cwd>/storage/tmp/<p>`                  | Throw-away scratch.                                                |
+| Helper              | Resolves to                             | Notes                                                                                                                               |
+| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `rootPath(...p)`    | `<cwd>/<...p>`                          | Also `Application.rootPath`. Base of every other helper.                                                                            |
+| `srcPath(...p)`     | `<cwd>/src/<...p>`                      | Also `Application.srcPath`.                                                                                                         |
+| `appPath(p?)`       | `<cwd>/src/app/<p>`                     | Also `Application.appPath`. Module roots live here.                                                                                 |
+| `configPath(...p)`  | `<cwd>/src/config/<...p>`               | `src/config/*.ts` subsystem configs.                                                                                                |
+| `publicPath(p?)`    | `<cwd>/public/<p>`                      | Also `Application.publicPath`. Static assets served as-is.                                                                          |
+| `storagePath(p?)`   | `<cwd>/storage/<p>`                     | Also `Application.storagePath`. Root for framework-managed files.                                                                   |
+| `uploadsPath(p?)`   | `<cwd>/storage/uploads/<p>` _(default)_ | Also `Application.uploadsPath`. Honors `config.uploads.root` override (string or function).                                         |
+| `cachePath(p?)`     | `<cwd>/storage/cache/<p>`               | Persistent cache files.                                                                                                             |
+| `logsPath(p?)`      | `<cwd>/storage/logs/<p>`                | Application logs.                                                                                                                   |
+| `tempPath(p?)`      | `<cwd>/storage/tmp/<p>`                 | Throw-away scratch.                                                                                                                 |
 | `warlockPath(...p)` | `<cwd>/.warlock/<...p>`                 | Framework internals (manifest, transpile cache, typings). **Never write app files here** — the framework deletes the folder freely. |
-| `sanitizePath(p)`  | Strips `<>:"/\|?*` from `p`              | Cleans user-supplied filename fragments before joining.            |
+| `sanitizePath(p)`   | Strips `<>:"/\|?*` from `p`             | Cleans user-supplied filename fragments before joining.                                                                             |
 
 ## The aggregate — `paths`
 
@@ -44,15 +44,15 @@ For builders or maintenance scripts that shuttle several locations in close prox
 ```ts
 import { paths } from "@warlock.js/core";
 
-paths.root("dist", "app.js");        // → <cwd>/dist/app.js
-paths.app("orders/routes.ts");        // → <cwd>/src/app/orders/routes.ts
-paths.uploads("avatars/42.png");      // → <cwd>/storage/uploads/avatars/42.png
-paths.config("mail.ts");              // → <cwd>/src/config/mail.ts
-paths.cache("queries.bin");           // → <cwd>/storage/cache/queries.bin
-paths.logs("errors.log");             // → <cwd>/storage/logs/errors.log
-paths.temp("tmp-export.csv");         // → <cwd>/storage/tmp/tmp-export.csv
-paths.warlock("manifest.json");       // → <cwd>/.warlock/manifest.json
-paths.sanitize("../etc/passwd");      // → "..etcpasswd"
+paths.root("dist", "app.js"); // → <cwd>/dist/app.js
+paths.app("orders/routes.ts"); // → <cwd>/src/app/orders/routes.ts
+paths.uploads("avatars/42.png"); // → <cwd>/storage/uploads/avatars/42.png
+paths.config("mail.ts"); // → <cwd>/src/config/mail.ts
+paths.cache("queries.bin"); // → <cwd>/storage/cache/queries.bin
+paths.logs("errors.log"); // → <cwd>/storage/logs/errors.log
+paths.temp("tmp-export.csv"); // → <cwd>/storage/tmp/tmp-export.csv
+paths.warlock("manifest.json"); // → <cwd>/.warlock/manifest.json
+paths.sanitize("../etc/passwd"); // → "..etcpasswd"
 ```
 
 Use the named import (`appPath`, `uploadsPath`, ...) when one helper dominates the file; reach for `paths.*` when you're shuttling multiple paths together.
@@ -65,10 +65,7 @@ Use the named import (`appPath`, `uploadsPath`, ...) when one helper dominates t
 import { appPath } from "@warlock.js/core";
 import { readFile } from "node:fs/promises";
 
-const template = await readFile(
-  appPath("mailers/templates/welcome.html"),
-  "utf-8",
-);
+const template = await readFile(appPath("mailers/templates/welcome.html"), "utf-8");
 ```
 
 ### Locate a config file
@@ -84,13 +81,17 @@ const httpConfigFile = configPath("http.ts");
 ```ts
 import { uploadsPath } from "@warlock.js/core";
 
+declare const userId: string;
+
 const avatar = uploadsPath(`avatars/${userId}/profile.png`);
 ```
 
 ### Sanitize a user-supplied filename before joining
 
 ```ts
-import { sanitizePath, uploadsPath } from "@warlock.js/core";
+import { sanitizePath, uploadsPath, type Request } from "@warlock.js/core";
+
+declare const req: Request; // the current request
 
 const safe = sanitizePath(req.input("filename"));
 const dest = uploadsPath(`exports/${safe}`);
@@ -115,7 +116,7 @@ const manifest = warlockPath("manifest.json");
 ```ts title="src/config/uploads.ts"
 export default {
   uploads: {
-    root: "/mnt/uploads",                   // static
+    root: "/mnt/uploads", // static
     // root: (rel) => `/mnt/uploads/${rel}`, // dynamic
   },
 };
@@ -137,18 +138,18 @@ The override is applied **inside** `uploadsPath()`. So `Application.uploadsPath`
 
 ## When to use which
 
-| Goal                                       | Helper            |
-| ------------------------------------------ | ----------------- |
-| File inside a module (controllers/services) | `appPath`        |
-| Top-level subsystem config                 | `configPath`      |
-| Static asset served as-is over HTTP        | `publicPath`      |
-| User-uploaded file (avatar, document)      | `uploadsPath`     |
-| Persistent cache for an expensive op       | `cachePath`       |
-| Application log line                       | `logsPath`        |
-| Short-lived scratch (cleaned aggressively) | `tempPath`        |
-| Bundled artifact (build outputs)           | `rootPath("dist", ...)` |
-| Reading a TS source from disk              | `srcPath` / `appPath` |
-| Framework internals (manifest, transpile)  | `warlockPath` *(read-only)* |
+| Goal                                        | Helper                      |
+| ------------------------------------------- | --------------------------- |
+| File inside a module (controllers/services) | `appPath`                   |
+| Top-level subsystem config                  | `configPath`                |
+| Static asset served as-is over HTTP         | `publicPath`                |
+| User-uploaded file (avatar, document)       | `uploadsPath`               |
+| Persistent cache for an expensive op        | `cachePath`                 |
+| Application log line                        | `logsPath`                  |
+| Short-lived scratch (cleaned aggressively)  | `tempPath`                  |
+| Bundled artifact (build outputs)            | `rootPath("dist", ...)`     |
+| Reading a TS source from disk               | `srcPath` / `appPath`       |
+| Framework internals (manifest, transpile)   | `warlockPath` _(read-only)_ |
 
 If you find yourself reaching for `path.join(process.cwd(), ...)` — that's a sign you want one of these helpers instead.
 

package/skills/retry-operation/SKILL.md

@@ -12,22 +12,25 @@ description: 'Wrap a flaky operation with `retry(fn, options)` — now provided
 ```ts
 import { retry } from "@mongez/reinforcements";
 
+declare function fetchUser(id: string): Promise<{ id: string }>; // any flaky async call
+declare const id: string;
+
 const user = await retry(() => fetchUser(id), {
-  attempts: 4,            // TOTAL tries (initial + retries) — default 3
-  delay: 200,             // base ms between attempts
+  attempts: 4, // TOTAL tries (initial + retries) — default 3
+  delay: 200, // base ms between attempts
   backoff: "exponential", // 200, 400, 800 ms
 });
 ```
 
 ## What changed from the old core `retry`
 
-| Old (`@warlock.js/core`)       | New (`@mongez/reinforcements`)                            |
-| ------------------------------ | -------------------------------------------------------- |
-| `count` = **extra** attempts   | `attempts` = **total** attempts (`count + 1`)            |
-| fixed `delay` only             | `delay` + `backoff` (`"linear" \| "exponential" \| fn`)  |
-| —                              | `maxDelay`, `jitter` (`"full" \| "equal"`), `signal`     |
-| `shouldRetry(error, attempt)`  | `shouldRetry(error, attempt)` (kept) + `onError` observe |
-| —                              | `retryable(fn, options)` to pre-bind a reusable wrapper  |
+| Old (`@warlock.js/core`)      | New (`@mongez/reinforcements`)                           |
+| ----------------------------- | -------------------------------------------------------- |
+| `count` = **extra** attempts  | `attempts` = **total** attempts (`count + 1`)            |
+| fixed `delay` only            | `delay` + `backoff` (`"linear" \| "exponential" \| fn`)  |
+| —                             | `maxDelay`, `jitter` (`"full" \| "equal"`), `signal`     |
+| `shouldRetry(error, attempt)` | `shouldRetry(error, attempt)` (kept) + `onError` observe |
+| —                             | `retryable(fn, options)` to pre-bind a reusable wrapper  |
 
 Migration: `count: 3` → `attempts: 4`.
 
@@ -56,8 +59,8 @@ await retry(() => fetch(url), {
   attempts: 6,
   delay: 100,
   backoff: "exponential",
-  maxDelay: 2_000,   // never wait more than 2s as backoff grows
-  jitter: "full",    // randomise each delay to avoid thundering herd
+  maxDelay: 2_000, // never wait more than 2s as backoff grows
+  jitter: "full", // randomise each delay to avoid thundering herd
 });
 ```
 
@@ -74,6 +77,9 @@ controller.abort(); // rejects promptly with signal.reason
 ```ts
 import { retryable } from "@mongez/reinforcements";
 
+declare function getUser(id: string): Promise<{ id: string }>; // any flaky async call
+declare const id: string;
+
 const fetchUser = retryable(getUser, { attempts: 4, backoff: "exponential" });
 await fetchUser(id);
 ```
@@ -86,6 +92,9 @@ await fetchUser(id);
 import { measure } from "@warlock.js/core";
 import { retry } from "@mongez/reinforcements";
 
+declare const bus: { publish(event: unknown): Promise<void> }; // your event bus
+declare const event: { type: string };
+
 const result = await measure("publish-event", () =>
   retry(() => bus.publish(event), { attempts: 4, delay: 200 }),
 ); // result.latency includes all retries

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`; "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"; 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: '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.'
 ---
 
 # Warlock — run the app
@@ -40,14 +40,14 @@ When a flag is **not** passed, the corresponding `warlock.config.ts > devServer.
 
 Once the server is ready, `warlock dev` listens for single keypresses:
 
-| Key      | Does                                                                                                                                                                    |
-| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `r`      | Restart the server on a fresh process.                                                                                                                                  |
-| `c`      | Clear the console.                                                                                                                                                      |
-| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                                                                                                                |
-| `h`      | Print the shortcuts that are armed right now.                                                                                                                           |
+| Key      | Does                                                                                                                                      |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `r`      | Restart the server on a fresh process.                                                                                                    |
+| `c`      | Clear the console.                                                                                                                        |
+| `q`      | Graceful shutdown, exit `0` — the same path as `Ctrl+C`.                                                                                  |
+| `h`      | Print the shortcuts that are armed right now.                                                                                             |
 | `u`      | **Only while an update notice is showing** — update every `@warlock.js/*` package, install, and restart. See the `update-packages` topic. |
-| `Ctrl+C` | Graceful shutdown, unchanged.                                                                                                                                           |
+| `Ctrl+C` | Graceful shutdown, unchanged.                                                                                                             |
 
 A "restart" is a fresh process (`r` and `u` both use it) — see [The supervisor](#the-supervisor) below for how that works.
 
@@ -123,7 +123,7 @@ preload: {
 
 HTTP + Socket connectors are **Late** phase — they boot later in the dev-server startup sequence, after app modules load. That ordering is what guarantees `app.http` / `app.socket` are live by the time your `main.ts` runs.
 
-**Runs on any Node version.** `warlock.config.ts` is loaded by transpiling it with esbuild when the runtime can't import `.ts` natively (Node < 22.18 / < 23.6) — so `build`/`start` work on older production Node without `--experimental-strip-types` or a newer Node.
+**Requires Node 22.15 or newer.** The CLI checks the runtime before loading either the published entry or the source loader and exits with a clear message on older versions. `warlock.config.ts` is transpiled with esbuild when the supported runtime cannot import `.ts` natively (Node < 22.18 / < 23.6); no `--experimental-strip-types` flag is needed.
 
 **Boot failures are fatal and loud.** Anything that throws during preload — a bad import in a `src/config/*.ts` file, a removed package export, a connector that fails to start — stops `dev`/`start` immediately with the error message and the offending file/line, then exits `1`. A common cause is upgrading `@warlock.js/*` and hitting a removed export (e.g. a config file that pulls in a model importing a symbol the new version no longer exports). If `warlock dev` ever just freezes right after the banner with no message, treat it as a bug and report it — preload errors are meant to print, never hang.
 
@@ -138,24 +138,48 @@ export default defineConfig({
       include: ["**/*.{ts,tsx}"],
       exclude: ["**/node_modules/**", "**/dist/**", "**/.warlock/**", "**/.git/**"],
     },
-    generateTypings: true,             // background type generation
-    checkForUpdates: true,             // notify on a newer @warlock.js/core at dev start
-    restartOnConfigChange: true,       // restart when warlock.config.ts / .env* changes
-    healthCheckers: [...] /* or false */,
-    transpileCacheDebug: false,        // name cache files <slug>.<hash>.js w/ // @source markers
-    timings: false,                    // print a per-phase reload timing breakdown
+    generateTypings: true, // background type generation
+    checkForUpdates: true, // notify on a newer @warlock.js/core at dev start
+    restartOnConfigChange: true, // restart when warlock.config.ts / .env* changes
+    healthCheckers: { typescript: true }, // built-in switches, custom checkers, or false
+    transpileCacheDebug: false, // name cache files <slug>.<hash>.js w/ // @source markers
+    timings: false, // print a per-phase reload timing breakdown
   },
 });
 ```
 
 - **`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`** — custom file health checker contracts (or `false` to disable). The `--skip-health` 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.
 - **`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
+
+Install `oxlint` in the app (`npm install --save-dev oxlint`) and add `.oxlintrc.json` at the app root:
+
+```json
+{
+  "rules": { "no-debugger": "error", "no-unused-vars": "warn" }
+}
+```
+
+`warlock dev` then checks changed JavaScript/TypeScript files in an isolated worker and reports rule ids, line/column spans, errors and warnings. It reads saved files from disk, honors the app's Oxlint ignore/config rules, and uses the app-resolved CLI package. A missing package or config skips the checker. Large file lists run in sequential batches of at most 500 files within platform command-line limits, using paths relative to the app; a batch whose report overflows the 8 MiB buffer is split and retried, and a single path the OS refuses as too long is reported as an unchecked warning instead of failing the scan. Tool/config errors include the CLI output and are reported without stopping the dev server. On worker shutdown CLI children get SIGTERM, then SIGKILL after 250 ms; the interrupted check is cancelled quietly ("the development server is shutting down") rather than reported as a timeout.
+
+```ts
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: {
+    healthCheckers: { typescript: true, eslint: false, oxlint: true },
+  },
+});
+```
+
+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.
+
 ## `warlock build` — production bundle
 
 esbuild bundle of the app down to a single JS file in `dist/`. No flags — every setting comes from `warlock.config.ts > build`.
@@ -163,6 +187,8 @@ esbuild bundle of the app down to a single JS file in `dist/`. No flags — ever
 ### `build.*` config knobs
 
 ```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
 export default defineConfig({
   build: {
     outdir: "dist", // default — relative or absolute
@@ -305,10 +331,10 @@ pnpm 10+ will not run a dependency's install script unless the app names it. esb
 
 Where the approval goes depends on the pnpm version (measured with real installs):
 
-| pnpm             | Approve esbuild in                                                           |
-| ---------------- | ---------------------------------------------------------------------------- |
-| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                    |
-| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`              |
+| pnpm             | Approve esbuild in                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------ |
+| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                                        |
+| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`                                  |
 | 7 – 9, 10.0–10.4 | `package.json`: `"pnpm": { "onlyBuiltDependencies": ["esbuild"] }`, and no `pnpm-workspace.yaml` |
 
 ```yaml
@@ -391,6 +417,50 @@ Three consequences worth knowing:
 
 If you need the same fact inside the app, use `Application.onceBooted()` / `Application.whenBooted()` — the signal and your listeners fire from the same latch.
 
+## Runtimes — Node, Bun, Deno
+
+| Command              | Node.js 22.15+     | Bun 1.4.3                     | Deno 2.9.7                    |
+| -------------------- | ------------------ | ----------------------------- | ----------------------------- |
+| `warlock dev`        | supported          | refused (exit 1, clear error) | refused (exit 1, clear error) |
+| `warlock build`      | supported          | runs with a notice — use Node | runs with a notice — use Node |
+| `warlock start`      | supported          | supported                     | supported                     |
+| built entry directly | `node dist/app.js` | `bun dist/app.js`             | `deno run -A dist/app.js`     |
+
+Build on Node, then start the same `dist/` (plus `node_modules` and `.env`) on any of the three:
+
+```bash
+npx warlock build                                                          # Node
+NODE_ENV=production bun dist/app.js                                        # Bun, direct
+NODE_ENV=production bun node_modules/@warlock.js/core/bin/warlock.js start # Bun, via the CLI (--role works)
+NODE_ENV=production deno run -A dist/app.js                                # Deno, direct
+NODE_ENV=production deno run -A node_modules/@warlock.js/core/bin/warlock.js start
+```
+
+- `warlock start` spawns the server with the runtime the CLI runs on (`process.execPath`), so the server runs on Bun/Deno whenever the CLI does. `bun --bun run start` works; plain `bun run start` runs the CLI on Node.
+- Deno needs no npm-compat flag — it reads `node_modules` through the app's `package.json`. `-A` is what CI verifies.
+- Pages render on Bun and Deno: both resolve `react-dom/server` to a build without `renderToPipeableStream`, so `@warlock.js/web` loads `react-dom/server.node` in that case (no change on Node).
+- The versions above are pinned in `.github/workflows/runtimes.yml`; `packages/core/tests/acceptance/run-runtime-acceptance.mjs --runtimes=node,bun,deno` repeats the CI check locally.
+
+A custom Node-only command can reuse the same guard:
+
+```ts title="src/app/tools/commands/profile.command.ts"
+import { assertNodeOnlyCommand, command, detectJavaScriptRuntime } from "@warlock.js/core";
+
+export const profileCommand = command({
+  name: "profile",
+  description: "Capture a CPU profile (uses node:inspector)",
+  preAction: () => {
+    // Prints "warlock profile runs on Node.js only — this process is Bun 1.4.3." and exits 1 on Bun/Deno.
+    assertNodeOnlyCommand("profile");
+  },
+  action: () => {
+    const runtime = detectJavaScriptRuntime(); // { type: "node", version: "22.15.0" }
+
+    console.log(`profiling on ${runtime.type} ${runtime.version}`);
+  },
+});
+```
+
 ## Picking which mode you're in
 
 `Application.environment` and `Application.runtimeStrategy` are separate axes:
@@ -424,14 +494,14 @@ Now `npm run dev` / `npm run build` / `npm run start`. Standard Node hosting pro
 ### Production Dockerfile
 
 ```dockerfile
-FROM node:20-alpine AS build
+FROM node:22.15-alpine AS build
 WORKDIR /app
 COPY package.json package-lock.json ./
 RUN npm ci
 COPY . .
 RUN npx warlock build
 
-FROM node:20-alpine
+FROM node:22.15-alpine
 WORKDIR /app
 COPY --from=build /app/dist ./dist
 COPY --from=build /app/node_modules ./node_modules
@@ -479,6 +549,8 @@ npx warlock dev --skip-typings
 Or persist it:
 
 ```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
 export default defineConfig({
   devServer: {
     generateTypings: false,
@@ -510,6 +582,7 @@ NODE_OPTIONS=--max-old-space-size=4096 npx warlock start
 - **`outdir` is the directory, `outFile` is the filename within it.** A common mistake is putting the full path in one and leaving the other default — you end up with `<full-path>/app.js` or `dist/<full-path>`. They concatenate.
 - **`sourcemap: false` cascades to `start`.** Stack traces lose `.ts` precision. Keep sourcemaps on unless artifact size is a hard constraint.
 - **`NODE_ENV` is not set by these commands.** The deployment env (your Dockerfile, CI, hosting provider) sets it. Forget it on a production server and `Application.isProduction` returns `false`, which flips cookie security, CORS, logging — silently. Always set `NODE_ENV=production` in production deployments.
+- **`warlock dev` is Node only.** On Bun or Deno it exits 1 before doing anything; develop on Node and run only the production build on Bun/Deno.
 - **`prestart` runs once on dev boot, not on reload.** If you're seeding test data in `src/app/prestart.ts`, it fires on `warlock dev` startup only. HMR reloads don't re-run it.
 
 ## See also
@@ -520,3 +593,15 @@ NODE_OPTIONS=--max-old-space-size=4096 npx warlock start
 - The `add-connector` topic — Early vs Late connector phases (why HTTP/socket boot late in dev).
 - The `update-packages` topic — `warlock update` + the dev-server update notice (`devServer.checkForUpdates`).
 - The `warlock-routes` topic — `warlock routes` / `warlock routes:diff`, the latter comparing live page routes against the manifest `warlock build` writes.
+
+Oxlint config failures preserve both warning and error output; structured
+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 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.