@warlock.js/core 4.11.0 → 4.13.0

package/llms.txt

@@ -17,7 +17,7 @@
 - [encrypt-data](@warlock.js/core/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 — `@warlock.js/core/hash-password/SKILL.md`; config wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs Node `crypto` direct, `crypto-js`, `libsodium-wrappers`.
 - [hash-password](@warlock.js/core/hash-password/SKILL.md): One-way bcrypt password hashing — `hashPassword` / `verifyPassword`, plus the declarative `useHashedPassword()` schema transformer that auto-hashes a model's password field on save. Salt rounds come from `src/config/encryption.ts`. Triggers: `hashPassword`, `verifyPassword`, `useHashedPassword`, `password.salt`, `bcryptjs`; "hash a user password", "verify login credentials", "auto-hash on save", "rotate a password"; typical import `import { hashPassword, verifyPassword } from "@warlock.js/core"`. Skip: reversible secrets — `@warlock.js/core/encrypt-data/SKILL.md`; the other transformers — `@warlock.js/core/use-model-transformers/SKILL.md`; config wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `bcrypt` native, `argon2`, `scrypt`.
 - [health-checks](@warlock.js/core/health-checks/SKILL.md): Built-in liveness (`/health`) and readiness (`/ready`) endpoints plus graceful HTTP request draining for zero-downtime deploys — the `health` registry (`health.addCheck`/`removeCheck`), the `http.health.*` and `http.gracefulShutdown.*` config, and how readiness ties into `Application.isShuttingDown`. Triggers: `health`, `health.addCheck`, `health.removeCheck`, `HealthCheck`, `/health`, `/ready`, `http.health`, `http.gracefulShutdown`, `forceCloseConnections`, "liveness probe", "readiness probe", "graceful shutdown", "drain in-flight requests", "zero-downtime deploy", "kubernetes health check", "503 until ready"; typical import `import { health } from "@warlock.js/core"`. Skip: the `Application.onShutdown` / `onceBooted` lifecycle hooks — `@warlock.js/core/use-app-context/SKILL.md`; maintenance-mode 503s — `@warlock.js/core/use-middleware/SKILL.md`; connector lifecycle — `@warlock.js/core/add-connector/SKILL.md`; competing libs `@fastify/under-pressure`, `terminus`, hand-rolled `/health` controllers.
-- [lower-stage3-decorators](@warlock.js/core/lower-stage3-decorators/SKILL.md): Vite/Vitest plugin `lowerStage3Decorators()` that lowers TC39 Stage-3 (native) decorators with esbuild before oxc / the SSR rewrite mangles them — so `@RegisterModel`-decorated Cascade models load under Vitest 4 / Vite 8. Triggers: `lowerStage3Decorators`, "SyntaxError: Invalid or unexpected token" on a decorated class, "@(0, __vite_ssr_import__.X)()", "decorator crashes vitest", "models won't load in tests", "Vite 8 oxc decorators"; typical import `import { lowerStage3Decorators } from "@warlock.js/core"` in `vite.config.ts` / `vitest.config.ts`. Skip: writing the tests themselves — `@warlock.js/core/test-service/SKILL.md` / `@warlock.js/core/test-http/SKILL.md`; runtime migrations — `@warlock.js/cascade/write-migration/SKILL.md`.
+- [lower-stage3-decorators](@warlock.js/core/lower-stage3-decorators/SKILL.md): Vite/Vitest plugin `lowerStage3Decorators()` that lowers TC39 Stage-3 (native) decorators with esbuild before oxc / the SSR rewrite mangles them — so `@RegisterModel`-decorated Cascade models load under Vitest 4 / Vite 8. Triggers: `lowerStage3Decorators`, "SyntaxError: Invalid or unexpected token" on a decorated class, "@(0, __vite_ssr_import__.X)()", "decorator crashes vitest", "models won't load in tests", "Vite 8 oxc decorators"; typical import `import { lowerStage3Decorators } from "@warlock.js/core/vite"` in `vite.config.ts` / `vitest.config.ts`. Skip: writing the tests themselves — `@warlock.js/core/test-service/SKILL.md` / `@warlock.js/core/test-http/SKILL.md`; runtime migrations — `@warlock.js/cascade/write-migration/SKILL.md`.
 - [process-image](@warlock.js/core/process-image/SKILL.md): Transform images with the `Image` class — resize, crop, rotate, format, quality, watermark, blur, etc. — using a deferred pipeline that runs only at `save()` / `toBuffer()` / `toBase64()` / `toDataUrl()` time. Requires sharp via `warlock add image`. Triggers: `Image`, `Image.fromFile`, `Image.fromBuffer`, `Image.fromUrl`, `.resize`, `.crop`, `.watermark`, `.toBuffer`, `.toDataUrl`, `.apply`; "resize an image", "generate a thumbnail", "watermark a product photo", "build an image pipeline"; typical import `import { Image } from "@warlock.js/core"`. Skip: multipart upload entry — `@warlock.js/core/upload-file/SKILL.md`; storage persistence — `@warlock.js/core/store-file/SKILL.md`; competing libs `sharp` direct, `jimp`, `imagemagick`, `gm`.
 - [register-route](@warlock.js/core/register-route/SKILL.md): Register HTTP routes via @warlock.js/core's router — single routes, prefix groups, middleware-guarded blocks, and RESTful resource chains. Routes always live in `src/app/<module>/routes.ts`. Triggers: `router.get`, `router.post`, `router.prefix`, `router.group`, `router.route`, `guarded`; "add a route", "wire a controller to a URL", "group routes by prefix", "register a RESTful resource"; typical import `import { router } from "@warlock.js/core"`. Skip: handler shape — `@warlock.js/core/create-controller/SKILL.md`; CRUD chain details — `@warlock.js/core/build-restful/SKILL.md`; middleware authoring — `@warlock.js/core/write-middleware/SKILL.md`; competing libs `express`, `fastify`, `koa`, `@nestjs/common`.
 - [resolve-path](@warlock.js/core/resolve-path/SKILL.md): Path helpers anchored at `process.cwd()` — `rootPath`, `srcPath`, `appPath`, `configPath`, `publicPath`, `storagePath`, `uploadsPath`, `cachePath`, `logsPath`, `tempPath`, `warlockPath`, `sanitizePath`. Optional `uploads.root` config overrides the uploads anchor. Triggers: `appPath`, `configPath`, `uploadsPath`, `storagePath`, `publicPath`, `cachePath`, `logsPath`, `tempPath`, `sanitizePath`, `paths`; "resolve a path inside src/app", "absolute upload destination", "sanitize a user filename", "ship uploads to a mounted volume"; typical import `import { appPath, uploadsPath } from "@warlock.js/core"`. Skip: HTTP URL helpers — `@warlock.js/core/build-url/SKILL.md`; app metadata — `@warlock.js/core/use-app-context/SKILL.md`; storage abstraction — `@warlock.js/core/store-file/SKILL.md`; competing patterns: `path.join(process.cwd(), ...)`, hand-rolled directory constants.
@@ -26,8 +26,8 @@
 - [send-mail](@warlock.js/core/send-mail/SKILL.md): Send transactional email — `Mail` fluent builder, `sendMail()` direct call, React Email components. Test mode auto-captures into an in-memory mailbox; dev mode logs. Triggers: `Mail.to`, `sendMail`, `setMailMode`, `mailEvents`, `assertMailSent`, `getTestMailbox`, `wasMailSentTo`, `closeAllMailers`; "send a transactional email", "build a React Email template", "configure SMTP or SES", "assert an email was sent in tests"; typical import `import { Mail, sendMail } from "@warlock.js/core"`. Skip: per-config wiring — `@warlock.js/core/configure-app/SKILL.md`; layered service patterns — `@warlock.js/core/warlock-conventions/SKILL.md`; competing libs `nodemailer` direct, `@sendgrid/mail`, `resend`, `mailgun.js`.
 - [send-response](@warlock.js/core/send-response/SKILL.md): Send HTTP responses via @warlock.js/core's Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `ResourceNotFoundError`, `ForbiddenError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — `@warlock.js/core/create-controller/SKILL.md`; route registration — `@warlock.js/core/register-route/SKILL.md`; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.
 - [store-file](@warlock.js/core/store-file/SKILL.md): Read/write/delete files via the `storage` singleton — disks, drivers (local/S3/R2/DO Spaces), `storage.use(name)`, `StorageFile` handles, presigned URLs. Triggers: `storage.put`, `storage.get`, `storage.use`, `StorageFile`, `storageConfigurations`, `getPresignedUrl`, `getPresignedUploadUrl`; "save an uploaded file", "switch between local and S3", "generate a presigned URL", "read file metadata"; typical import `import { storage } from "@warlock.js/core"`. Skip: multipart parsing + image chain — `@warlock.js/core/upload-file/SKILL.md`; image transforms — `@warlock.js/core/process-image/SKILL.md`; storage config shape — `@warlock.js/core/configure-app/SKILL.md`; competing libs `@aws-sdk/client-s3`, `multer`, `formidable`.
-- [test-http](@warlock.js/core/test-http/SKILL.md): 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`.
-- [test-service](@warlock.js/core/test-service/SKILL.md): Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.
+- [test-http](@warlock.js/core/test-http/SKILL.md): 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/tests"`. 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`.
+- [test-service](@warlock.js/core/test-service/SKILL.md): Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.
 - [update-packages](@warlock.js/core/update-packages/SKILL.md): Keep a project current with `warlock update` — bump every `@warlock.js/*` dependency in package.json to its latest published version (range operator preserved), then run the lockfile-detected package manager install. Also covers the `warlock dev` update notice, its `u` update-and-restart keyboard shortcut, and the `devServer.checkForUpdates` toggle. Triggers: `warlock update`, `--no-install`, `--dry-run`, `--check`, `checkForUpdates`, `fetchLatestVersion`, `isNewerVersion`; "update warlock packages", "upgrade the framework", "is there a new warlock version", "update notice in the dev server", "press u to update", "dev server keyboard shortcut", "update check offline", "bump @warlock.js/* to latest"; typical CLI `warlock update`. Skip: dev/build/start runtime — `@warlock.js/core/run-app/SKILL.md`; writing a custom command — `@warlock.js/core/write-cli-command/SKILL.md`; installing a NEW feature package (auth, mail, storage) — that is `warlock add`; releasing/publishing the framework — workspace release tooling, not this command.
 - [upload-file](@warlock.js/core/upload-file/SKILL.md): Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.
 - [use-app-context](@warlock.js/core/use-app-context/SKILL.md): Read app-wide context — the `Application` static class (env, version, uptime, runtime strategy, boot lifecycle) plus the `app` runtime accessor (live Fastify, socket.io, router, database via the DI container). Triggers: `Application.isProduction`, `Application.environment`, `Application.runtimeStrategy`, `Application.uptime`, `Application.version`, `Application.onceBooted`, `Application.whenBooted`, `Application.isBooted`, `Application.onShutdown`, `Application.isShuttingDown`, `app.http`, `app.socket`, `app.database`, `app.router`; "branch on environment", "reach the live Fastify instance", "framework version in health endpoint", "dev vs production runtime check", "run code once the app is fully booted", "after all connectors started", "app booted hook", "run cleanup before shutdown", "graceful shutdown hook"; typical import `import { Application, app } from "@warlock.js/core"`. Skip: path helpers — `@warlock.js/core/resolve-path/SKILL.md`; connector start order — `@warlock.js/core/add-connector/SKILL.md`; competing patterns: bare `process.env.NODE_ENV`, ad-hoc Fastify imports.

package/package.json

@@ -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.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",
+    "@warlock.js/auth": "4.13.0",
+    "@warlock.js/cache": "4.13.0",
+    "@warlock.js/cascade": "4.13.0",
+    "@warlock.js/context": "4.13.0",
+    "@warlock.js/logger": "4.13.0",
+    "@warlock.js/seal": "4.13.0",
+    "@warlock.js/fs": "4.13.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.11.0",
-    "@warlock.js/ai": "4.11.0",
-    "@warlock.js/access": "4.11.0",
-    "@warlock.js/notifications": "4.11.0"
+    "@warlock.js/herald": "4.13.0",
+    "@warlock.js/ai": "4.13.0",
+    "@warlock.js/access": "4.13.0",
+    "@warlock.js/notifications": "4.13.0"
   },
   "bin": {
     "warlock": "bin/warlock.js"
   },
-  "version": "4.11.0",
+  "version": "4.13.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",
@@ -94,6 +94,18 @@
         "default": "./esm/cli/start.mjs"
       }
     },
+    "./tests": {
+      "import": {
+        "types": "./esm/tests/index.d.mts",
+        "default": "./esm/tests/index.mjs"
+      }
+    },
+    "./vite": {
+      "import": {
+        "types": "./esm/vite/index.d.mts",
+        "default": "./esm/vite/index.mjs"
+      }
+    },
     "./dev-server/health-checker/workers/eslint-health.worker": {
       "import": {
         "types": "./esm/dev-server/health-checker/workers/eslint-health.worker.d.mts",

package/skills/lower-stage3-decorators/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lower-stage3-decorators
-description: 'Vite/Vitest plugin `lowerStage3Decorators()` that lowers TC39 Stage-3 (native) decorators with esbuild before oxc / the SSR rewrite mangles them — so `@RegisterModel`-decorated Cascade models load under Vitest 4 / Vite 8. Triggers: `lowerStage3Decorators`, "SyntaxError: Invalid or unexpected token" on a decorated class, "@(0, __vite_ssr_import__.X)()", "decorator crashes vitest", "models won''t load in tests", "Vite 8 oxc decorators"; typical import `import { lowerStage3Decorators } from "@warlock.js/core"` in `vite.config.ts` / `vitest.config.ts`. Skip: writing the tests themselves — `@warlock.js/core/test-service/SKILL.md` / `@warlock.js/core/test-http/SKILL.md`; runtime migrations — `@warlock.js/cascade/write-migration/SKILL.md`.'
+description: 'Vite/Vitest plugin `lowerStage3Decorators()` that lowers TC39 Stage-3 (native) decorators with esbuild before oxc / the SSR rewrite mangles them — so `@RegisterModel`-decorated Cascade models load under Vitest 4 / Vite 8. Triggers: `lowerStage3Decorators`, "SyntaxError: Invalid or unexpected token" on a decorated class, "@(0, __vite_ssr_import__.X)()", "decorator crashes vitest", "models won''t load in tests", "Vite 8 oxc decorators"; typical import `import { lowerStage3Decorators } from "@warlock.js/core/vite"` in `vite.config.ts` / `vitest.config.ts`. Skip: writing the tests themselves — `@warlock.js/core/test-service/SKILL.md` / `@warlock.js/core/test-http/SKILL.md`; runtime migrations — `@warlock.js/cascade/write-migration/SKILL.md`.'
 ---
 
 # Lower Stage-3 decorators for Vite/Vitest
@@ -15,12 +15,14 @@ The cause is two transforms that don't understand each other. Vite 8 transpiles
 
 `lowerStage3Decorators()` fixes it by getting **esbuild** to lower the decorators *first*.
 
+⚠ **Changed in 4.13.0 — the import is a subpath now.** The plugin used to be re-exported from the package root; it is not any more, because that put the Vite integration into every application's production module graph. `import { lowerStage3Decorators } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/vite` to the specifier and nothing else changes.**
+
 ## Use it
 
 Drop it **first** in your `plugins` array:
 
 ```ts title="vite.config.ts"
-import { lowerStage3Decorators } from "@warlock.js/core";
+import { lowerStage3Decorators } from "@warlock.js/core/vite";
 import mongezVite from "@mongez/vite";
 import { defineConfig } from "vitest/config";
 

package/skills/process-image/SKILL.md

@@ -22,7 +22,9 @@ await new Image("./photo.jpg")
   .save("./output.webp");
 ```
 
-That's the full contract. The chain doesn't touch sharp until the output method fires.
+That's the full contract. The chain doesn't run sharp until the output method fires; the
+constructor resolves the sharp module itself, so a missing sharp throws there rather than at the
+final await.
 
 ## Installation
 

package/skills/run-app/SKILL.md

@@ -165,6 +165,8 @@ export default defineConfig({
     outFile: "app.js",            // default — bundle filename
     minify: true,                 // default — esbuild minify
     sourcemap: true,              // default — true | false | "inline" | "linked"
+    singleBundle: false,          // default — one runnable file, deps inlined
+    esmShim: true,                // default — require/__filename/__dirname for bundled CJS
   },
 });
 ```
@@ -176,6 +178,10 @@ Defaults are sensible for the typical "Node service" deployment. Knobs to actual
 - **`minify: false`** — flip to debug a production-only bug. Larger bundle, readable stack traces.
 - **`sourcemap: "inline"`** — embed the source map in the bundle. Useful when your error reporter only captures the bundle and can't fetch a `.map` sidecar.
 - **`sourcemap: false`** — skip source maps entirely. Smaller artifact, but stack traces in production logs lose their file:line precision (and `warlock start` will not enable `--enable-source-maps` since there's nothing to map).
+- **`singleBundle: true`** — inline dependencies so `node dist/app.js` runs with no `node_modules` and no launcher. Sets `packages: "bundle"` + `splitting: false` as **defaults you can override**. ⚠ Native `.node` addons are still emitted alongside — "single bundle" is one JS file *plus* any native addons. Do NOT reach for it as the default: keeping deps external is right when you deploy the folder.
+- **`esmShim: false`** — only if you are certain nothing in the graph is CommonJS. Leave it on.
+
+⚠ **The trap this replaced.** Setting `packages: "bundle"` by hand used to produce a clean build whose process died on start with `Error: Dynamic require of "node:assert" is not supported`. The output is ESM; bundled CJS deps call `require(...)` and read `__dirname`, and neither exists in an ES module, so the bundler substitutes a throwing stub. **A green `warlock build` was not evidence the bundle ran.** `esmShim` now injects `createRequire(import.meta.url)` and friends automatically for any ESM build, so both `singleBundle` and a hand-written `packages: "bundle"` work. An existing hand-written `banner` is preserved — the shim is prepended, not substituted.
 
 ### What it preloads
 

package/skills/test-http/SKILL.md

@@ -1,19 +1,21 @@
 ---
 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`, `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`.'
+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/tests"`. 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
 
 Some tests need the full stack: route matching, middleware chain, validation, controller, response serialization. For those, you boot the real HTTP server once per test run and make real `fetch` calls against it.
 
-`startHttpTestServer()` is the bootstrap. `testGet` / `testPost` / `expectJson` are the call helpers. Both ship in `@warlock.js/core`.
+`startHttpTestServer()` is the bootstrap. `testGet` / `testPost` / `expectJson` are the call helpers. Both ship in `@warlock.js/core/tests`.
+
+⚠ **Changed in 4.13.0 — the import is a subpath now.** These helpers used to be re-exported from the package root; they are not any more, because that put the test helpers into every application's production module graph. `import { testGet } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
 ```ts title="src/app/users/tests/users.controller.test.ts"
 import { describe, expect, it } from "vitest";
-import { expectJson, testGet, testPost } from "@warlock.js/core";
+import { expectJson, testGet, testPost } from "@warlock.js/core/tests";
 
 describe("Users API", () => {
   it("GET /users returns the list", async () => {
@@ -39,7 +41,7 @@ No `beforeAll`, no manual server start — the project's `src/test-global-setup.
 ## The bootstrap — `startHttpTestServer` / `stopHttpTestServer`
 
 ```ts
-import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core";
+import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
 ```
 
 `startHttpTestServer()` boots a **minimal but real** HTTP server:
@@ -80,6 +82,23 @@ 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.
 
+### Port `0` is refused
+
+`port: 0` — "let the OS pick one" — is not supported, and says so rather than half-working:
+
+```
+startHttpTestServer() cannot run on port 0. Pass an explicit port — e.g.
+startHttpTestServer({ port: 3999 }) — or set `http.port` in your config. Test workers
+are separate processes that resolve the server's URL from the port published at
+startup, and an OS-assigned port is not knowable to them.
+```
+
+The reason is the worker handoff described above: the port the OS assigns is never recorded anywhere the workers can read, so `getTestServerUrl()` would resolve `0` and send every request to `http://host:0`.
+
+### If startup fails, nothing is left behind
+
+`startHttpTestServer()` owns the connectors it starts. A failure part-way through — a bad config, a connector that won't boot — tears down whatever came up, withdraws the published port, and **rethrows the original error**; a failure during that cleanup is logged but never replaces the cause. `stopHttpTestServer()` withdraws the port and resets its state even when the shutdown itself throws, and still surfaces that failure.
+
 ## Project wiring — `src/test-global-setup.ts` + `vite.config.ts`
 
 ```ts title="src/test-global-setup.ts"
@@ -87,7 +106,7 @@ This runs whether or not you passed a port, so a collision never reaches you as
  * Global Test Setup
  * Runs ONCE in the main process before all test workers start.
  */
-import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core";
+import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
 
 export async function setup() {
   await startHttpTestServer();
@@ -99,7 +118,7 @@ export async function teardown() {
 ```
 
 ```ts title="vite.config.ts"
-import { lowerStage3Decorators } from "@warlock.js/core";
+import { lowerStage3Decorators } from "@warlock.js/core/vite";
 import mongezVite from "@mongez/vite";
 import { defineConfig } from "vitest/config";
 
@@ -124,7 +143,7 @@ Everything is built on native `fetch` — no extra dependency, no special wire f
 ### URL resolution
 
 ```ts
-import { getTestServerUrl } from "@warlock.js/core";
+import { getTestServerUrl } from "@warlock.js/core/tests";
 
 const url = getTestServerUrl();  // → "http://localhost:2031" (defaults)
 ```
@@ -141,7 +160,7 @@ import {
   testPut,
   testPatch,
   testDelete,
-} from "@warlock.js/core";
+} from "@warlock.js/core/tests";
 
 await testGet("/products");
 await testGet("/products?published=true", { headers: { "X-Tenant": "abc" } });
@@ -158,7 +177,7 @@ All accept a relative path (leading `/` optional) and a standard `RequestInit`.
 ### Parsing + asserting — `expectJson<T>`
 
 ```ts
-import { expectJson, parseJsonResponse } from "@warlock.js/core";
+import { expectJson, parseJsonResponse } from "@warlock.js/core/tests";
 
 // Parse-only
 const body = await parseJsonResponse<MyShape>(response);
@@ -177,7 +196,7 @@ const body = await expectJson<MyShape>(response, 404);     // expects 404 (testi
 
 ```ts
 import { describe, expect, it } from "vitest";
-import { expectJson, testGet, testPost } from "@warlock.js/core";
+import { expectJson, testGet, testPost } from "@warlock.js/core/tests";
 
 describe("Products API — happy path", () => {
   it("creates and reads back a product", async () => {

package/skills/test-service/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-service
-description: 'Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.'
+description: 'Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.'
 ---
 
 # Warlock — test a service
@@ -9,6 +9,8 @@ For unit tests, you import the thing under test and call it directly. No HTTP, n
 
 `setupTest()` is the one-call bootstrap that gives each worker that environment.
 
+⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+
 ## The shape
 
 ```ts title="src/app/users/tests/register-user.service.test.ts"
@@ -37,7 +39,7 @@ No `beforeAll(setupTest)` in this file — the project's `src/test-setup.ts` (re
 ## `setupTest({ connectors })` — the worker bootstrap
 
 ```ts
-import { setupTest } from "@warlock.js/core";
+import { setupTest } from "@warlock.js/core/tests";
 
 await setupTest({ connectors: true });
 ```
@@ -85,13 +87,13 @@ The `warlock add test` feature creates both files. The standard wiring:
  * Per-Worker Test Setup
  * Runs in EACH Vitest worker thread before tests execute.
  */
-import { setupTest } from "@warlock.js/core";
+import { setupTest } from "@warlock.js/core/tests";
 
 await setupTest({ connectors: true });
 ```
 
 ```ts title="vite.config.ts"
-import { lowerStage3Decorators } from "@warlock.js/core";
+import { lowerStage3Decorators } from "@warlock.js/core/vite";
 import mongezVite from "@mongez/vite";
 import { defineConfig } from "vitest/config";
 
@@ -210,11 +212,11 @@ Vitest runs tests in a single worker file sequentially, so an `afterEach` trunca
 
 ```ts title="src/app/utils/tests/slugify.test.ts"
 import { beforeAll, describe, expect, it } from "vitest";
-import { setupTest } from "@warlock.js/core";
+import { setupTest } from "@warlock.js/core/tests";
 import { slugify } from "../utils/slugify";
 
 beforeAll(async () => {
-  await setupTest({ connectors: false });  // override the project default
+  await setupTest({ connectors: false });  // starts no connectors at all
 });
 
 describe("slugify", () => {
@@ -224,7 +226,9 @@ describe("slugify", () => {
 });
 ```
 
-`setupTest` is idempotent per worker (`isSetupComplete` flag) — calling it again with different options after `src/test-setup.ts` already ran is a no-op. To genuinely skip connectors, either set `tests.connectors: false` in config (project-wide) or rely on the default in `src/test-setup.ts` being what you want most of the time.
+`setupTest` is idempotent per worker (`isSetupComplete` flag) — calling it again with different options after `src/test-setup.ts` already ran is a no-op. **That includes a `connectors: false` call: if `src/test-setup.ts` already ran `setupTest()` in this worker, the example above changes nothing.** To genuinely skip connectors, either set `tests.connectors: false` in config (project-wide) or rely on the default in `src/test-setup.ts` being what you want most of the time.
+
+⚠ **Config beats the parameter.** If `tests.connectors` is set at all, `setupTest({ connectors })` cannot override it — the config value wins. That is the current contract, not an accident; a per-call override is under discussion for a later release.
 
 ## Gotchas
 
@@ -232,7 +236,7 @@ describe("slugify", () => {
 - **Per-worker connections are separate from the HTTP server's connections.** A row inserted by a service-level test is on the worker's connection; the HTTP test server has its own. They don't see each other unless they're both pointing at the same physical DB and the inserting test has already committed.
 - **`NODE_ENV` is set to `"test"`** by `setupTest`. Code that branches on `Application.isProduction` / `Application.isDevelopment` sees `false` for both. If your tests need production-like config (cookies, CORS), set those values in `src/config/*.ts` explicitly under the test branch — don't rely on the env flag.
 - **No HTTP from this layer.** `setupTest({ connectors: true })` never starts the HTTP connector by design. Don't try to `request.app.http` your way to a fetch test — use the `test-http` skill instead.
-- **Don't import `vitest-setup` from `@warlock.js/core/src/...`.** The public surface is `import { setupTest } from "@warlock.js/core"`. Reaching into source paths breaks when the package layout shifts.
+- **Don't import `vitest-setup` from `@warlock.js/core/src/...`.** The public surface is `import { setupTest } from "@warlock.js/core/tests"`. Reaching into source paths breaks when the package layout shifts.
 - **Test files need the `.test.ts` suffix.** `include: ["src/app/**/*.test.ts"]` is what vitest scans. A file named `service.tests.ts` (plural) silently doesn't run.
 
 ## See also

package/skills/use-middleware/SKILL.md

@@ -81,6 +81,8 @@ Server errors (5xx) are not cached — clients can retry past a 5xx. 4xx respons
 
 `http.bodyLimit` in config is read by Fastify at server-start and applies to every body. `middleware.maxBodySize()` is a per-route middleware on top — it checks `Content-Length` after route match and rejects with 413 before body parsing runs. Use both: global as a safety net, per-route for tight caps on small-payload endpoints.
 
+⚠ **Since 4.13.0, configuring nothing gives you Fastify's own 1 MB limit.** Earlier versions defaulted to 200 GB, which **replaced** Fastify's protection rather than adding to it — so an app that set nothing had effectively no cap. **Set `bodyLimit` explicitly if you need more than 1 MB.**
+
 ```ts
 // src/config/http.ts
 export default { bodyLimit: 10 * 1024 * 1024 }; // 10MB globally
@@ -111,7 +113,9 @@ export default {
 
 ## `ipFilter` — fail-closed
 
-`deny` wins over `allow`. If the IP can't be read (empty / unparseable), the request is rejected with 403. Reads via `request.detectIp()` which honors `X-Real-IP` and `X-Forwarded-For` (Fastify starts with `trustProxy: true`).
+`deny` wins over `allow`. If the IP can't be read (empty / unparseable), the request is rejected with 403. Reads via `request.detectIp()`.
+
+⚠ **Since 4.13.0 `http.trustProxy` defaults to `false`**, so `request.detectIp()` returns the socket address and **`X-Real-IP` / `X-Forwarded-For` are ignored unless you opt in.** Set `trustProxy: true` **only when you are genuinely behind a proxy that overwrites those headers** — before 4.13.0 the default was `true`, which meant any client could set its own forwarding header and be believed.
 
 ```ts
 import { middleware } from "@warlock.js/core";

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

@@ -156,12 +156,30 @@ The framework ships a fixed set of commands you call but don't author. Knowing t
 
 | Command  | Flags / args                                    | Preloads                       |
 | -------- | ----------------------------------------------- | ------------------------------ |
-| `warlock migrate` | `--list` (just list pending), `--fresh` / `-f` (drop tables first) | database, logger          |
+| `warlock migrate` | `--list` / `-l` (executed **and** pending), `--pending` (pending only, sets an exit code), `--fresh` / `-f` (drop tables first) | database, logger          |
 | `warlock seed` | `--name <pattern>` (run seeds matching the pattern) | full bootstrap (env, configs, app modules) |
 | `warlock create-database <name>` | bare positional `<name>`        | database                       |
 | `warlock drop.tables` | `--force, -f` (skip confirmation prompt) | database, logger          |
 | `warlock db.indexes` | builds DB indexes for every registered model    | database                  |
 
+**Asking what will run next.** `warlock migrate --list` prints executed migrations and then the pending ones **in execution order**. Do not derive the pending set by differencing `--all` against `--list`: `--all` globs `src/app` only, while `--list` reads the migrations table, which also holds migrations that packages register through `database.migrations` (`@warlock.js/auth` contributes two). The difference under-counts pending, in the direction that says "safe to proceed".
+
+`--list` is a report and always exits `0`. `--pending` is a gate, and its exit code is its whole API:
+
+| Exit | Meaning |
+| ---- | ------- |
+| `0`  | computed, nothing pending |
+| `1`  | computed, N pending |
+| `2`  | **could not be computed** |
+
+```bash
+warlock migrate --pending && ./deploy.sh
+```
+
+`2` is separate from `1` on purpose — a script must be able to tell a backlog from an unknown, because one means *run them* and the other means *stop*. When the migration files cannot be loaded, both commands print `Pending: unavailable — <reason>` beneath a complete executed listing rather than reporting `0`.
+
+**If you are writing a command that reports on pending migrations:** register migrations first. `listPendingMigrations()` filters the runner's registry, so a caller that has not loaded anything gets `[]` — which reads as "nothing pending" and is not the same claim.
+
 ### Scaffolding
 
 The `generate.*` family covers every module piece:

package/esm/cli/cli-command.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-command.d.mts","names":[],"sources":["../../../../../../../core/src/cli/cli-command.ts"],"mappings":";;;cAUa,UAAA;EAqDF,IAAA;EArDE;;;EAIJ,aAAA,GAAgB,gBAAA;EAKA;;;EAAhB,aAAA,GAAgB,gBAAA;EAyDD;;;;EAnDf,gBAAA,GAAmB,gBAAA;EAuHuC;;;EAlH1D,cAAA,GAAiB,iBAAA;EAoNA;;;EA/MjB,kBAAA;EAuNqC;;;EAlNrC,cAAA,EAAgB,wBAAA;EArBhB;;;;;EA4BA,mBAAA;EAZA;;;EAiBA,YAAA;EAAA;;;EAKA,YAAA;EAOL;;;cADO,IAAA,UACP,WAAA;EAoBK;;;EARA,MAAA,CAAO,MAAA,EAAQ,gBAAA;EAyBf;;;EAjBA,WAAA,CAAY,WAAA;EAyBL;;;EAjBP,UAAA,CAAW,YAAA;EAkCX;;;;EAzBA,KAAA,CAAM,KAAA;EA0CN;;;EAlCA,MAAA,CAAO,MAAA,EAAQ,gBAAA;EAmCR;;;;EA1BP,SAAA,CAAU,MAAA,EAAQ,gBAAA;EAwDf;;;EAhDH,OAAA,CAAQ,OAAA,EAAS,gBAAA;EA8FhB;;;EArFD,aAAA,CAAc,YAAA;EAmHR;;;EA3GN,MAAA,CAAO,MAAA,EAAQ,gBAAA;EACf,MAAA,CAAO,IAAA,UAAc,WAAA,WAAsB,OAAA,GAAU,IAAA,CAAK,gBAAA;EA0GrB;AAS9C;;;;;;;;EAT8C,UA5ElC,WAAA,CAAY,MAAA,EAAQ,gBAAA,GAAmB,wBAAA;;;;;;;;;UA8CzC,iBAAA;;;;EAsBD,OAAA,CAAQ,OAAA,EAAS,iBAAA;;;;EAQX,OAAA,CAAQ,IAAA,EAAM,iBAAA,GAAiB,OAAA;AAAA;AAAA,iBAS9B,OAAA,CAAQ,OAAA,EAAS,iBAAA,GAAiB,UAAA"}

package/esm/cli/cli-command.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli-command.mjs","names":[],"sources":["../../../../../../../core/src/cli/cli-command.ts"],"sourcesContent":["import type {\n  CLICommandAction,\n  CLICommandOption,\n  CLICommandOptions,\n  CLICommandPreload,\n  CLICommandSource,\n  CommandActionData,\n  ResolvedCLICommandOption,\n} from \"./types\";\n\nexport class CLICommand {\n  /**\n   * Command source\n   */\n  public commandSource?: CLICommandSource;\n\n  /**\n   * Command action\n   */\n  public commandAction?: CLICommandAction;\n\n  /**\n   * Command pre action\n   * This will be executed before loading preloaders\n   */\n  public commandPreAction?: CLICommandAction;\n\n  /**\n   *    Command preload\n   */\n  public commandPreload?: CLICommandPreload;\n\n  /**\n   * Command description\n   */\n  public commandDescription?: string;\n\n  /**\n   * Command options\n   */\n  public commandOptions: ResolvedCLICommandOption[] = [];\n\n  /**\n   * Command relative path\n   * Available only for project commands\n   * Auto injected by the framework itself\n   */\n  public commandRelativePath?: string;\n\n  /**\n   * Determine if the command is persistent\n   */\n  public isPersistent: boolean = false;\n\n  /**\n   * Command alias (short name)\n   */\n  public commandAlias?: string;\n\n  /**\n   * Constructor\n   */\n  public constructor(\n    public name: string,\n    description?: string,\n  ) {\n    if (description) {\n      this.commandDescription = description;\n    }\n\n    return this;\n  }\n\n  /**\n   * Add command source\n   */\n  public source(source: CLICommandSource): this {\n    this.commandSource = source;\n    return this;\n  }\n\n  /**\n   * Set command description\n   */\n  public description(description: string): this {\n    this.commandDescription = description;\n    return this;\n  }\n\n  /**\n   * Determine if the command is persistent\n   */\n  public persistent(isPersistent = true): this {\n    this.isPersistent = isPersistent;\n    return this;\n  }\n\n  /**\n   * Set command alias (short name)\n   * @example .alias(\"m\") for \"migrate\"\n   */\n  public alias(alias: string): this {\n    this.commandAlias = alias;\n    return this;\n  }\n\n  /**\n   * Command action\n   */\n  public action(action: CLICommandAction): this {\n    this.commandAction = action;\n    return this;\n  }\n\n  /**\n   * Command pre action\n   * This will be executed before loading preloaders\n   */\n  public preAction(action: CLICommandAction): this {\n    this.commandPreAction = action;\n    return this;\n  }\n\n  /**\n   * Add command options\n   */\n  public options(options: CLICommandOption[]): this {\n    options.map((option) => this.option(option));\n\n    return this;\n  }\n\n  /**\n   * Add command relative path\n   */\n  public $relativePath(relativePath: string) {\n    this.commandRelativePath = relativePath;\n    return this;\n  }\n\n  /**\n   * Add command option\n   */\n  public option(option: CLICommandOption): this;\n  public option(name: string, description?: string, options?: Omit<CLICommandOption, \"name\">): this;\n  public option(\n    ...args: [CLICommandOption] | [string, string?, Omit<CLICommandOption, \"name\">?]\n  ): this {\n    let option: CLICommandOption;\n    if (args.length === 1) {\n      option = args[0] as CLICommandOption;\n    } else {\n      option = {\n        text: args[0],\n        description: args[1],\n        ...args[2],\n        name: \"\",\n      };\n    }\n\n    this.commandOptions.push(this.parseOption(option));\n\n    return this;\n  }\n\n  /**\n   * Parse option name and alias if exists\n   *\n   * Supports formats:\n   * - \"--port, -p\" → name: \"port\", alias: \"p\"\n   * - \"-p, --port\" → name: \"port\", alias: \"p\"\n   * - \"--port\" → name: \"port\", alias: undefined\n   * - \"-p\" → name: \"p\", alias: undefined\n   */\n  protected parseOption(option: CLICommandOption): ResolvedCLICommandOption {\n    const text = option.text.trim();\n\n    // Split by comma to check for alias\n    const parts = text.split(\",\").map((part) => part.trim());\n\n    let name = \"\";\n    let alias = \"\";\n\n    if (parts.length === 1) {\n      // Single option: \"--port\" or \"-p\"\n      name = this.extractOptionName(parts[0]);\n    } else if (parts.length === 2) {\n      // Two options: \"--port, -p\" or \"-p, --port\"\n      const first = parts[0];\n      const second = parts[1];\n\n      // Determine which is the long form (name) and which is short (alias)\n      if (first.startsWith(\"--\")) {\n        name = this.extractOptionName(first);\n        alias = this.extractOptionName(second);\n      } else {\n        name = this.extractOptionName(second);\n        alias = this.extractOptionName(first);\n      }\n    }\n\n    if (alias === \"h\" || name === \"help\") {\n      throw new Error(\"Help option is not allowed, it's reserved for displaying command help\");\n    }\n\n    return {\n      ...option,\n      name,\n      alias,\n    };\n  }\n\n  /**\n   * Extract option name from text (removes -- or -)\n   *\n   * @example\n   * extractOptionName(\"--port\") → \"port\"\n   * extractOptionName(\"-p\") → \"p\"\n   * extractOptionName(\"--port=3000\") → \"port\"\n   */\n  private extractOptionName(text: string): string {\n    // Remove leading dashes\n    let name = text.replace(/^-+/, \"\");\n\n    // Remove value assignment if exists (e.g., \"--port=3000\" → \"port\")\n    const equalIndex = name.indexOf(\"=\");\n    if (equalIndex !== -1) {\n      name = name.slice(0, equalIndex);\n    }\n\n    // Remove angle brackets if exists (e.g., \"--port <number>\" → \"port\")\n    const spaceIndex = name.indexOf(\" \");\n    if (spaceIndex !== -1) {\n      name = name.slice(0, spaceIndex);\n    }\n\n    return name.trim();\n  }\n\n  /**\n   * Command preload\n   */\n  public preload(options: CLICommandPreload) {\n    this.commandPreload = options;\n    return this;\n  }\n\n  /**\n   * Execute the command\n   */\n  public async execute(data: CommandActionData) {\n    if (!this.commandAction) {\n      throw new Error(`Command \"${this.name}\" has no action defined`);\n    }\n\n    await this.commandAction(data);\n  }\n}\n\nexport function command(options: CLICommandOptions) {\n  const commandInstnace = new CLICommand(options.name, options.description);\n\n  if (options.preload) {\n    commandInstnace.preload(options.preload);\n  }\n\n  if (options.persistent) {\n    commandInstnace.persistent(options.persistent);\n  }\n\n  if (options.alias) {\n    commandInstnace.alias(options.alias);\n  }\n\n  commandInstnace.action(options.action);\n\n  if (options.options) {\n    commandInstnace.options(options.options);\n  }\n\n  if (options.preAction) {\n    commandInstnace.preAction(options.preAction);\n  }\n\n  return commandInstnace;\n}\n"],"mappings":";AAUA,IAAa,aAAb,MAAwB;;;;CAoDtB,AAAO,YACL,AAAO,MACP,aACA;EAFO;wBAvB2C,CAAC;sBAYtB;EAc7B,IAAI,aACF,KAAK,qBAAqB;EAG5B,OAAO;CACT;;;;CAKA,AAAO,OAAO,QAAgC;EAC5C,KAAK,gBAAgB;EACrB,OAAO;CACT;;;;CAKA,AAAO,YAAY,aAA2B;EAC5C,KAAK,qBAAqB;EAC1B,OAAO;CACT;;;;CAKA,AAAO,WAAW,eAAe,MAAY;EAC3C,KAAK,eAAe;EACpB,OAAO;CACT;;;;;CAMA,AAAO,MAAM,OAAqB;EAChC,KAAK,eAAe;EACpB,OAAO;CACT;;;;CAKA,AAAO,OAAO,QAAgC;EAC5C,KAAK,gBAAgB;EACrB,OAAO;CACT;;;;;CAMA,AAAO,UAAU,QAAgC;EAC/C,KAAK,mBAAmB;EACxB,OAAO;CACT;;;;CAKA,AAAO,QAAQ,SAAmC;EAChD,QAAQ,KAAK,WAAW,KAAK,OAAO,MAAM,CAAC;EAE3C,OAAO;CACT;;;;CAKA,AAAO,cAAc,cAAsB;EACzC,KAAK,sBAAsB;EAC3B,OAAO;CACT;CAOA,AAAO,OACL,GAAG,MACG;EACN,IAAI;EACJ,IAAI,KAAK,WAAW,GAClB,SAAS,KAAK;OAEd,SAAS;GACP,MAAM,KAAK;GACX,aAAa,KAAK;GAClB,GAAG,KAAK;GACR,MAAM;EACR;EAGF,KAAK,eAAe,KAAK,KAAK,YAAY,MAAM,CAAC;EAEjD,OAAO;CACT;;;;;;;;;;CAWA,AAAU,YAAY,QAAoD;EAIxE,MAAM,QAHO,OAAO,KAAK,KAGR,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS,KAAK,KAAK,CAAC;EAEvD,IAAI,OAAO;EACX,IAAI,QAAQ;EAEZ,IAAI,MAAM,WAAW,GAEnB,OAAO,KAAK,kBAAkB,MAAM,EAAE;OACjC,IAAI,MAAM,WAAW,GAAG;GAE7B,MAAM,QAAQ,MAAM;GACpB,MAAM,SAAS,MAAM;GAGrB,IAAI,MAAM,WAAW,IAAI,GAAG;IAC1B,OAAO,KAAK,kBAAkB,KAAK;IACnC,QAAQ,KAAK,kBAAkB,MAAM;GACvC,OAAO;IACL,OAAO,KAAK,kBAAkB,MAAM;IACpC,QAAQ,KAAK,kBAAkB,KAAK;GACtC;EACF;EAEA,IAAI,UAAU,OAAO,SAAS,QAC5B,MAAM,IAAI,MAAM,uEAAuE;EAGzF,OAAO;GACL,GAAG;GACH;GACA;EACF;CACF;;;;;;;;;CAUA,AAAQ,kBAAkB,MAAsB;EAE9C,IAAI,OAAO,KAAK,QAAQ,OAAO,EAAE;EAGjC,MAAM,aAAa,KAAK,QAAQ,GAAG;EACnC,IAAI,eAAe,IACjB,OAAO,KAAK,MAAM,GAAG,UAAU;EAIjC,MAAM,aAAa,KAAK,QAAQ,GAAG;EACnC,IAAI,eAAe,IACjB,OAAO,KAAK,MAAM,GAAG,UAAU;EAGjC,OAAO,KAAK,KAAK;CACnB;;;;CAKA,AAAO,QAAQ,SAA4B;EACzC,KAAK,iBAAiB;EACtB,OAAO;CACT;;;;CAKA,MAAa,QAAQ,MAAyB;EAC5C,IAAI,CAAC,KAAK,eACR,MAAM,IAAI,MAAM,YAAY,KAAK,KAAK,wBAAwB;EAGhE,MAAM,KAAK,cAAc,IAAI;CAC/B;AACF;AAEA,SAAgB,QAAQ,SAA4B;CAClD,MAAM,kBAAkB,IAAI,WAAW,QAAQ,MAAM,QAAQ,WAAW;CAExE,IAAI,QAAQ,SACV,gBAAgB,QAAQ,QAAQ,OAAO;CAGzC,IAAI,QAAQ,YACV,gBAAgB,WAAW,QAAQ,UAAU;CAG/C,IAAI,QAAQ,OACV,gBAAgB,MAAM,QAAQ,KAAK;CAGrC,gBAAgB,OAAO,QAAQ,MAAM;CAErC,IAAI,QAAQ,SACV,gBAAgB,QAAQ,QAAQ,OAAO;CAGzC,IAAI,QAAQ,WACV,gBAAgB,UAAU,QAAQ,SAAS;CAG7C,OAAO;AACT"}

package/esm/cli/types.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/cli/types.ts"],"mappings":";;;;;AAgB4B;AAY5B;;;;KAZY,gBAAA;;;;AAwBK;AAsBjB;;;;;;KAlCY,iBAAA;EAuDV;;;;EAlDA,IAAA;EAiFA;;;AAA0B;AAgB5B;EA1FE,OAAA,EAAS,MAAM;AAAA;;;;;;;;;;AAiIP;AAGV;;;;;;;;;KA9GY,iBAAA;EAuHA;;;;;EAjHV,MAAA;EAiHiE;;AAAO;EA5GxE,QAAA;EAkI2B;;;EA7H3B,aAAA;EAsKQ;;;EAjKR,eAAA,GAAkB,eAAA;EA6HlB;;;EAxHA,WAAA;EAyIU;;;;;;;;;EA9HV,GAAA;;;;;EAMA,SAAA;;;;;;;;EASA,UAAA,GAAa,aAAa;AAAA;;;;;;;;;;;;;;KAgBhB,gBAAA;;;;;EAKV,IAAA;;;;;EAMA,IAAA;;;;;EAMA,KAAA;;;;EAKA,WAAA;;;;;EAMA,IAAA;;;;EAKA,YAAA;;;;;EAMA,QAAA;AAAA;AAAA,KAGU,wBAAA,GAA2B,IAAI,CAAC,gBAAA;EAC1C,IAAA;EACA,KAAA;AAAA;;;;;KAOU,gBAAA,IAAoB,IAAA,EAAM,iBAAA,YAA6B,OAAO;;;;;;;;;;;;;;;;;;;;;KAsB9D,iBAAA;;;;;EAKV,IAAA;;;;;EAMA,KAAA;;;;EAKA,WAAA;;;;;EAMA,OAAA,GAAU,iBAAA;;;;;;EAOV,UAAA;;;;;EAMA,SAAA,GAAY,gBAAA;;;;;EAMZ,MAAA,EAAQ,gBAAA;;;;;EAMR,OAAA,GAAU,gBAAA;AAAA"}

package/esm/dev-server/files-orchestrator.d.mts

@@ -1,89 +0,0 @@
-import { DependencyGraph } from "./dependency-graph.mjs";
-import { SpecialFilesCollector } from "./special-files-collector.mjs";
-import { FileOperations } from "./file-operations.mjs";
-import { FileManager } from "./file-manager.mjs";
-import { FilesWatcher } from "./files-watcher.mjs";
-import { FileHealthCheckerContract } from "./health-checker/file-health-checker.contract.mjs";
-import { FilesHealthcareManager } from "./health-checker/files-healthcare.manager.mjs";
-import { ModuleLoader } from "./module-loader.mjs";
-
-//#region ../core/src/dev-server/files-orchestrator.d.ts
-/**
- * Register a cleanup callback that fires before the current module is
- * unloaded by HMR. Stack-inspects the caller so user code doesn't need to
- * thread the FileManager through.
- */
-declare function onCleanup(callback: () => any): void;
-/**
- * Top-level coordinator for the dev server's file system.
- *
- * Owns: file discovery, the dependency graph, the manifest, the special-files
- * index, the file watcher, and the lifecycle of the ESM loader hook (which
- * provides cache-busting via `?v=N` version tokens).
- */
-declare class FilesOrchestrator {
-  readonly filesWatcher: FilesWatcher;
-  readonly files: Map<string, FileManager>;
-  private readonly manifest;
-  private readonly dependencyGraph;
-  private readonly healthCheckerManager;
-  readonly specialFilesCollector: SpecialFilesCollector;
-  readonly moduleLoader: ModuleLoader;
-  readonly fileOperations: FileOperations;
-  private readonly eventHandler;
-  /** Main-thread end of the MessageChannel to the loader hook worker. */
-  private loaderPort;
-  /** Resolve callbacks for pending `flushVersionBumps()` calls. */
-  private readonly pendingFlushes;
-  isInitialized: boolean;
-  constructor();
-  add(relativePath: string): Promise<FileManager>;
-  load<T>(relativePath: string, type?: string): Promise<T | undefined>;
-  getDependencyGraph(): DependencyGraph;
-  getInvalidationChain(file: string): string[];
-  getFiles(): Map<string, FileManager>;
-  getHealthCheckerManager(): FilesHealthcareManager;
-  /**
-   * Initialise managers and register the ESM loader hook. Must be called
-   * before any user `src/` module is dynamically imported.
-   */
-  init(): Promise<void>;
-  /**
-   * Tell the hook worker a file changed. The next `import()` of it will get
-   * a fresh `?v=N` URL → Node cache miss → fresh content.
-   */
-  bumpVersion(absolutePath: string): void;
-  /**
-   * Wait until the hook worker has processed every pending bump.
-   *
-   * `postMessage` is async — without this, a follow-up `import()` may
-   * resolve before the worker increments the counter and Node will return
-   * the cached old module.
-   */
-  flushVersionBumps(): Promise<void>;
-  /**
-   * Discover files on disk, reconcile against the manifest, build the dep
-   * graph, and persist the new manifest. Idempotent.
-   */
-  initializeAll(): Promise<void>;
-  checkHealth(files: {
-    added: string[];
-    changed: string[];
-    deleted: string[];
-  }): Promise<void>;
-  startCheckingHealth(healthCheckers?: FileHealthCheckerContract[]): Promise<void>;
-  /**
-   * Glob the src directory, returning relative paths.
-   */
-  getAllFilesFromFilesystem(): Promise<string[]>;
-  /**
-   * Process every file from scratch — used when no manifest exists.
-   */
-  private processFiles;
-  private reconcileFiles;
-  watchFiles(): Promise<void>;
-}
-declare const filesOrchestrator: FilesOrchestrator;
-//#endregion
-export { FilesOrchestrator, filesOrchestrator, onCleanup };
-//# sourceMappingURL=files-orchestrator.d.mts.map

package/esm/dev-server/files-orchestrator.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"files-orchestrator.d.mts","names":[],"sources":["../../../../../../../core/src/dev-server/files-orchestrator.ts"],"mappings":";;;;;;;;;;;;AA8BA;;;iBAAgB,SAAA,CAAU,QAAmB;AAAA;AAuB7C;;;;;;AAvB6C,cAuBhC,iBAAA;EAAA,SACK,YAAA,EAAY,YAAA;EAAA,SACZ,KAAA,EAAK,GAAA,SAAA,WAAA;EAAA,iBACJ,QAAA;EAAA,iBACA,eAAA;EAAA,iBACA,oBAAA;EAAA,SACD,qBAAA,EAAqB,qBAAA;EAAA,SACrB,YAAA,EAAY,YAAA;EAAA,SACZ,cAAA,EAAgB,cAAA;EAAA,iBACf,YAAA;EA+CiB;EAAA,QA5C1B,UAAA;EA4FoB;EAAA,iBAzFX,cAAA;EAEV,aAAA;;EAkBM,GAAA,CAAI,YAAA,WAAuB,OAAA,CAAQ,WAAA;EAInC,IAAA,IAAQ,YAAA,UAAsB,IAAA,YAAc,OAAA,CAAA,CAAA;EAKlD,kBAAA,IAAsB,eAAA;EAItB,oBAAA,CAAqB,IAAA;EAIrB,QAAA,IAAY,GAAA,SAAY,WAAA;EAIxB,uBAAA,IAA2B,sBAAA;EAvDN;;;;EA+Df,IAAA,IAAI,OAAA;EA5DA;;;;EAyFV,WAAA,CAAY,YAAA;EAtFS;;;;;;;EAiGrB,iBAAA,IAAqB,OAAA;EArEf;;;;EAkFA,aAAA,IAAa,OAAA;EAkBb,WAAA,CAAY,KAAA;IAAS,KAAA;IAAiB,OAAA;IAAmB,OAAA;EAAA,IAAmB,OAAA;EAc5E,mBAAA,CAAoB,cAAA,GAAiB,yBAAA,KAA8B,OAAA;EAzGnD;;;EAmHhB,yBAAA,IAA6B,OAAA;EA3GvB;;;EAAA,QAmHL,YAAA;EAAA,QAcA,cAAA;EAgCD,UAAA,IAAU,OAAA;AAAA;AAAA,cAuBZ,iBAAA,EAAiB,iBAA0B"}

package/esm/dev-server/files-watcher.d.mts

@@ -1,69 +0,0 @@
-//#region ../core/src/dev-server/files-watcher.d.ts
-type FileWatcherEvent = "change" | "delete" | "add" | "error" | "addDir" | "unlinkDir";
-type FileChangeCallback = (filePath: string) => void;
-type FileDeleteCallback = (filePath: string) => void;
-type FileAddCallback = (filePath: string) => void;
-type FileErrorCallback = (filePath: string, error: Error) => void;
-type FileAddDirCallback = (filePath: string) => void;
-type FileUnlinkDirCallback = (filePath: string) => void;
-type OnFileEventCallback = FileChangeCallback | FileDeleteCallback | FileAddCallback | FileErrorCallback | FileAddDirCallback | FileUnlinkDirCallback;
-/**
- * Watch configuration options
- */
-type WatchConfig = {
-  /**
-   * Glob patterns to include
-   */
-  include?: string[];
-  /**
-   * Glob patterns to exclude
-   */
-  exclude?: string[];
-};
-declare class FilesWatcher {
-  /**
-   * File watcher id
-   */
-  private id;
-  /**
-   * Watch for files changes
-   * @param config Optional watch configuration
-   */
-  watch(config?: WatchConfig): Promise<void>;
-  /**
-   * Trigger event immediately (no debouncing here)
-   * Debouncing is handled at the orchestrator level for batch processing
-   */
-  private triggerEvent;
-  /**
-   * On file change event
-   */
-  onFileChange(callback: FileChangeCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file delete event
-   */
-  onFileDelete(callback: FileDeleteCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file add event
-   */
-  onFileAdd(callback: FileAddCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file error event
-   */
-  onFileError(callback: FileErrorCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file add dir event
-   */
-  onDirectoryAdd(callback: FileAddDirCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file unlink dir event
-   */
-  onDirectoryRemove(callback: FileUnlinkDirCallback): import("@mongez/events").EventSubscription;
-  /**
-   * On file event
-   */
-  on(event: FileWatcherEvent, callback: OnFileEventCallback): import("@mongez/events").EventSubscription;
-}
-//#endregion
-export { FilesWatcher };
-//# sourceMappingURL=files-watcher.d.mts.map

package/esm/dev-server/files-watcher.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"files-watcher.d.mts","names":[],"sources":["../../../../../../../core/src/dev-server/files-watcher.ts"],"mappings":";KAOK,gBAAA;AAAA,KAEA,kBAAA,IAAsB,QAAgB;AAAA,KACtC,kBAAA,IAAsB,QAAgB;AAAA,KACtC,eAAA,IAAmB,QAAgB;AAAA,KACnC,iBAAA,IAAqB,QAAA,UAAkB,KAAA,EAAO,KAAK;AAAA,KACnD,kBAAA,IAAsB,QAAgB;AAAA,KACtC,qBAAA,IAAyB,QAAgB;AAAA,KACzC,mBAAA,GACD,kBAAA,GACA,kBAAA,GACA,eAAA,GACA,iBAAA,GACA,kBAAA,GACA,qBAAA;;;AAZuC;KAiB/B,WAAA;EAhBW;;;EAoBrB,OAAA;EAnBG;;;EAuBH,OAAO;AAAA;AAAA,cAsBI,YAAA;EA5CS;;;EAAA,QAgDZ,EAAA;EAhDyC;;;AAAK;EAsDzC,KAAA,CAAM,MAAA,GAAS,WAAA,GAAW,OAAA;EArDlB;;;AAAoB;EAApB,QA8Gb,YAAA;EA7GgB;;;EAoHjB,YAAA,CAAa,QAAA,EAAU,kBAAA,4BAAkB,iBAAA;EAnH7C;;;EA0HI,YAAA,CAAa,QAAA,EAAU,kBAAA,4BAAkB,iBAAA;EAxH9C;;;EA+HK,SAAA,CAAU,QAAA,EAAU,eAAA,4BAAe,iBAAA;EA3HxC;;;EAkIK,WAAA,CAAY,QAAA,EAAU,iBAAA,4BAAiB,iBAAA;EAtI5C;;;EA6IK,cAAA,CAAe,QAAA,EAAU,kBAAA,4BAAkB,iBAAA;EAzIhD;;AAAqB;EAgJhB,iBAAA,CAAkB,QAAA,EAAU,qBAAA,4BAAqB,iBAAA;EA3InC;;;EAkJd,EAAA,CAAG,KAAA,EAAO,gBAAA,EAAkB,QAAA,EAAU,mBAAA,4BAAmB,iBAAA;AAAA"}