@warlock.js/core 4.10.0 → 4.11.0

package/package.json

@@ -28,7 +28,7 @@
     "@mongez/concat-route": "^1.1.4",
     "@mongez/config": "^1.1.4",
     "@mongez/copper": "^2.1.2",
-    "@mongez/dotenv": "^1.2.4",
+    "@mongez/dotenv": "^1.3.1",
     "@mongez/events": "^2.2.6",
     "@mongez/http": "^3.3.8",
     "@mongez/localization": "^3.4.6",
@@ -36,13 +36,13 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.3",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/auth": "4.10.0",
-    "@warlock.js/cache": "4.10.0",
-    "@warlock.js/cascade": "4.10.0",
-    "@warlock.js/context": "4.10.0",
-    "@warlock.js/logger": "4.10.0",
-    "@warlock.js/seal": "4.10.0",
-    "@warlock.js/fs": "4.10.0",
+    "@warlock.js/auth": "4.11.0",
+    "@warlock.js/cache": "4.11.0",
+    "@warlock.js/cascade": "4.11.0",
+    "@warlock.js/context": "4.11.0",
+    "@warlock.js/logger": "4.11.0",
+    "@warlock.js/seal": "4.11.0",
+    "@warlock.js/fs": "4.11.0",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
@@ -68,15 +68,15 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/herald": "4.10.0",
-    "@warlock.js/ai": "4.10.0",
-    "@warlock.js/access": "4.10.0",
-    "@warlock.js/notifications": "4.10.0"
+    "@warlock.js/herald": "4.11.0",
+    "@warlock.js/ai": "4.11.0",
+    "@warlock.js/access": "4.11.0",
+    "@warlock.js/notifications": "4.11.0"
   },
   "bin": {
     "warlock": "bin/warlock.js"
   },
-  "version": "4.10.0",
+  "version": "4.11.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/run-app/SKILL.md

@@ -219,6 +219,57 @@ Just `warlockConfig: true` — same as `build`. The actual app bootstrap happens
 
 Means `docker stop` / `kubectl delete pod` works as expected: SIGTERM reaches the bundle, your graceful-shutdown hooks fire, then the parent exits.
 
+### pnpm needs esbuild's install script allowed
+
+pnpm 10+ will not run a dependency's install script unless the app names it. esbuild's script links its platform-native binary, and `warlock build` shells out to that binary — so the app installs cleanly and then cannot build:
+
+```
+[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.27.7
+```
+
+Fix it once in the app's `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  esbuild: true
+```
+
+Note pnpm reads this from `pnpm-workspace.yaml`, **not** from `package.json`'s `pnpm` field — pnpm 11 warns that the field is ignored and then carries on, so settings left there fail silently.
+
+Nothing else is needed for pnpm. Warlock never requires an app to declare a package it does not import: generated code is checked at build time against the app's own `dependencies`, so `warlock build` failing over an unfamiliar package name is a framework bug, not a missing dependency.
+
+### Output streams — what a supervisor may trust
+
+**A success line on stdout means the app is serving requests.** That is a contract, not a convention, and you can build a CI gate or a health probe on it.
+
+| Stream     | Carries                                                        |
+| ---------- | -------------------------------------------------------------- |
+| **stdout** | the started banner, and start failures. Nothing else.           |
+| **stderr** | progress (`🚀 Starting production server...`), diagnostics, the application's own logs |
+
+The started banner prints **only** when the running application reports a completed boot — not when the command starts, not when the child is spawned. A child that dies before reporting is a failed start: the failure is written to **both** streams (stderr for humans and log collectors, stdout so a supervisor greping for the banner finds a failure rather than silence), and `warlock start` exits non-zero **even when the child itself exited `0`**.
+
+```bash
+# a CI gate can be this blunt, and it is now correct
+yarn warlock start | grep -q "production server started"
+```
+
+### How readiness is reported
+
+`warlock start` spawns the bundle with an IPC channel and sets `WARLOCK_BOOT_SIGNAL=1` on it. `Application.markBooted()` — which the production entry calls after the late-phase connectors (http, socket) are up — sends one versioned message and closes the channel:
+
+```ts
+{ type: "warlock:ready", version: 1, pid, at, environment, runtimeStrategy, bootDurationMs?, port? }
+```
+
+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.
+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.
+
 ## Picking which mode you're in
 
 `Application.environment` and `Application.runtimeStrategy` are separate axes:
@@ -286,6 +337,18 @@ export default defineConfig({
 
 CI sets `BUILD_OUT=build/<sha>` per pipeline. `warlock start` reads the same config and finds the bundle without any hardcoded paths.
 
+**This recipe only started working in 4.11.0.** Before that, `warlock.config.ts` was evaluated *before* any `.env` file was read, so every `env()` call in it returned its default — silently, under every command. If you copied this recipe earlier and concluded that `BUILD_OUT` was ignored, it was.
+
+**Which file the value comes from is decided by `NODE_ENV`, and no Warlock command sets it.** `env()` reads `.env.<NODE_ENV>` when that file exists and falls back to plain `.env`. So:
+
+```bash
+warlock build                       # NODE_ENV unset → reads .env
+NODE_ENV=production warlock build   # → reads .env.production
+NODE_ENV=staging warlock build      # → reads .env.staging
+```
+
+That is deliberate: `build` and `start` do **not** force `production`. Forcing it would silently change which file an existing `NODE_ENV=staging` pipeline reads, and would have the framework overriding an operator's explicit choice at the moment of deployment. Set `NODE_ENV` in your Dockerfile, CI job, or process manager — the same place you already set it for `Application.environment`.
+
 ### Skip type-gen on machines without write access
 
 ```bash

package/skills/test-http/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-http
-description: 'Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.'
+description: 'Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `startHttpTestServer({ port })`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`, `PortInUseError`, `assertPortIsAvailable`, `isPortAvailable`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape", "test server port already in use", "EADDRINUSE while running tests", "run tests while the dev server is up"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.'
 ---
 
 # Warlock — HTTP integration tests
@@ -56,6 +56,30 @@ Unlike the dev server, it doesn't watch files, doesn't do HMR, doesn't run healt
 
 Both are idempotent. A second `start` returns early; `stop` on a non-running server logs and returns.
 
+### Choosing the port — `startHttpTestServer({ port })`
+
+```ts
+await startHttpTestServer({ port: 3999 });
+```
+
+The explicit port wins over `http.port` — including over `HTTP_PORT` in `.env`. Use it to run a suite while the dev server holds the configured port, or to run two suites side by side.
+
+**Nothing else can move the server.** `startHttpTestServer()` bootstraps the app itself, and that bootstrap re-reads `.env` (dotenv overrides by default), so any value you set before calling it is gone before the port is read. Assigning `process.env.HTTP_PORT` does not work either: `env()` reads dotenv's own store and never falls back to `process.env`. The option is applied after the bootstrap, immediately before the connector binds — that is why it is the only channel that survives.
+
+The request helpers follow with no extra wiring: the bound port is published as `WARLOCK_TEST_SERVER_PORT`, which the workers inherit, and `getTestServerUrl()` prefers it over their own `.env`-resolved `http.port`. `stopHttpTestServer()` withdraws it.
+
+### The port is preflighted
+
+Before binding, the test server checks the resolved port is free and fails with an instruction if it isn't:
+
+```
+Port 2031 is already in use on localhost. Stop the dev server (or whatever else is
+listening on port 2031) and run again, or start on a free port — e.g.
+startHttpTestServer({ port: 2032 }).
+```
+
+This runs whether or not you passed a port, so a collision never reaches you as a bare `EADDRINUSE` from inside Fastify. The failure is a `PortInUseError` carrying `port` and `host`. The same check is available on its own — `assertPortIsAvailable(port, host)` throws it, `isPortAvailable(port, host)` returns a boolean.
+
 ## Project wiring — `src/test-global-setup.ts` + `vite.config.ts`
 
 ```ts title="src/test-global-setup.ts"
@@ -105,7 +129,7 @@ import { getTestServerUrl } from "@warlock.js/core";
 const url = getTestServerUrl();  // → "http://localhost:2031" (defaults)
 ```
 
-Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config. If you change the HTTP config, helpers follow automatically.
+Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config — unless `startHttpTestServer` published a port, which wins, since a worker's own config never sees the `{ port }` option passed in `globalSetup`. If you change the HTTP config, helpers follow automatically.
 
 ### Verb helpers
 
@@ -274,7 +298,7 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 ## Gotchas
 
 - **`globalSetup` must export `setup` and `teardown`.** Vitest reads them by name. A typo in the export gets you a confusing "server not running" error on the first `testGet` call.
-- **Port conflicts.** If `http.port` matches your running dev server, `startHttpTestServer()` fails to bind. Either stop the dev server or set a test-only port: `http: { port: 3999 }` in a test-config branch.
+- **Port conflicts.** If `http.port` matches your running dev server, the preflight fails with a `PortInUseError` naming the port. Either stop the dev server or pass a free one: `startHttpTestServer({ port: 3999 })`.
 - **Auth tokens need a real user.** Generating a JWT with a non-existent `user_id` works — but the auth middleware's user-loading step will reject the request with 401 because it can't find the user in the DB.
 - **`expectJson` parses the body once.** If you call it twice on the same response, the second call gets an already-consumed stream error. Capture the result.
 - **The HTTP server's connection is NOT torn down between test files.** Data persists across files within a single `vitest` run. Either truncate in `afterEach` / `afterAll`, or design your tests to be order-independent.