@warlock.js/core 4.15.0 → 5.0.0

package/CHANGELOG.md

@@ -6,7 +6,48 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 > ⚠ **Versioning: `@warlock.js/*` does not follow SemVer strictly — breaking changes may ship in a minor.** This is a deliberate decision, not an oversight: the framework is pre-adoption and the cost of a major per behaviour fix currently outweighs the benefit. **Pin an exact version or a tilde range (`~4.13.0`) if you need to opt into changes rather than receive them.** Every breaking change is marked **BREAKING** in its entry and summarised in an *Upgrading* section at the top of the release. **This policy will change once the framework has consumers beyond its author.**
 
-## 4.14.0
+## 5.0.0 - 2026-08-25
+
+### Upgrading
+
+- **BREAKING — `Request` no longer has a `[key: string]: any` index signature.** Attaching arbitrary properties (`request.post = post`) no longer compiles. Migrate per attachment: per-request data written by middleware → `request.locals` (augment `RequestLocals`); per-request memoized computation → `requestMemo(key, fn)`; new typed members → module augmentation of `Request` itself
+- **BREAKING — `fromRequest(key, callback)` is removed.** It cached values as dynamic `Request` properties, which only compiled because of the deleted index signature. `requestMemo(key, fn)` is the drop-in successor: same per-request lifetime, single-flight (concurrent callers share one promise), and it never touches the `Request` object
+- **BREAKING — client-supplied locales are validated against `app.localeCodes`.** A `locale`/`translation-locale-code` header or `locale` query value outside the configured list is treated as absent and falls through to the default locale — it previously won as-is, steering every translated string and every serialized Resource. Apps that declare no `app.localeCodes` keep the pass-through behavior
+- **`request.trans()` / `request.t()` now resolve the locale at call time.** Previously the translator captured the locale once during request construction (before routing), so a locale set later — a path locale, `setLocaleCode()` — changed `request.locale` but not the language of translated strings
+
+### Added
+
+- **`request.requireUser()`** — returns the authenticated user non-optionally, or throws `UnAuthorizedError` when no user is attached. For handlers behind an auth guard, where an absent user is a misconfigured route rather than a normal state; replaces `request.user!` assertions
+
+## 4.16.0 - 2026-08-18
+
+### Security
+
+- **`request.detectIp()` no longer trusts `X-Real-IP` / `X-Forwarded-For` unless `http.trustProxy` is set.** Both headers are client-settable, and `detectIp()` honoured them unconditionally — bypassing the `trustProxy` opt-in the Fastify server itself is configured with. Any client could therefore spoof its IP to everything keyed on `detectIp()`: `ipFilter` allowlists/denylists, the default rate-limit bucket key, and anonymous idempotency scoping. Without the opt-in, `detectIp()` (and its `realIp` alias) now returns `baseRequest.ip` — the socket peer address, which cannot be forged
+
+  ⚠ **If your app runs behind a proxy and relied on `detectIp()` reading the forwarding headers without setting `http.trustProxy`, set `http.trustProxy: true`** (or a Fastify `trustProxy` value matching your edge). With `true` set, behaviour is unchanged: `X-Real-IP` first, then the leftmost `X-Forwarded-For` hop, then the peer address. Only enable `true` when your edge overwrites those headers — it trusts them wholesale
+
+- **`http.trustProxy` now accepts a hop count or a trusted-proxy list, and `detectIp()` honours them.** `true` is the wrong shape for the common topology: an edge that *appends* to `X-Forwarded-For` leaves whatever the client prepended as the leftmost entry, so "trust the leftmost hop" hands the client its own IP back. The config value is passed to Fastify untouched, and `detectIp()` now reads the resolved client off `request.ip` instead of re-parsing the header — so both agree, and every Fastify shape works:
+
+  | `http.trustProxy` | Client IP |
+  | --- | --- |
+  | `false` *(default)* | Socket peer address; forwarding headers ignored |
+  | `true` | Leftmost `X-Forwarded-For` entry (whole chain trusted) |
+  | `2` | Walks past the 2 rightmost hops — for an edge that appends |
+  | `"10.0.0.0/8"`, `"loopback, 10.0.0.0/8"`, `["10.0.0.0/8", "192.168.0.0/16"]` | Walks left while each hop is a listed proxy, stops at the first that isn't |
+  | `(address, hop) => boolean` | Your predicate |
+
+  Prefer the narrowest shape your topology allows: with `true`, any client that can reach the process directly picks its own IP, and an `ipFilter` allowlist in front of it is decorative
+
+  ⚠ **`X-Real-IP` is now honoured only under `trustProxy: true`.** It carries no chain, so there is nothing to check a hop count or proxy list against, and a trusted edge that forwards the client's own `X-Real-IP` verbatim would otherwise let any client escape the bound. Under a bounded `trustProxy` the value comes from the `X-Forwarded-For` chain instead — if your edge sets only `X-Real-IP`, have it set `X-Forwarded-For` as well
+
+### Dependencies
+
+- Bumped `@mongez/*` deps to their 2026-08-17 security release specs: `concat-route` ^1.2.0, `config` ^1.2.1, `dotenv` ^1.3.2, `events` ^2.2.7, `http` ^3.5.0, `localization` ^3.4.7, `reinforcements` ^4.0.1, `supportive-is` ^2.1.4
+- ⚠ **`@mongez/reinforcements` 4.0.1 is a major bump: `Random` is now CSPRNG-backed (WebCrypto) and `Random.seed()` was removed** — seeded/reproducible `Random.string/nanoid/id/token/uuid` calls now throw. Audited `core`'s `Random.string(...)` call sites (`use-case.ts`, `http/request.ts`, `dev-server/files-watcher.ts`, `http/uploaded-file.ts`) and its test suite: none rely on seeding or reproducible output, so no code changes were required
+- `@mongez/encryption` 2.0.1 (async `encrypt`/`decrypt`, throws on failure) does not apply to this package — `core` is not a consumer; `src/encryption/encrypt.ts` uses Node's built-in `crypto` module directly and is unaffected
+
+## 4.14.0 - 2026-08-16
 
 ### ⚠ Upgrading from 4.13.0 — read this first
 
@@ -104,7 +145,7 @@ afterAll(teardownTest);     // ← is new
 
   **The cost is a framework bootstrap per test file — which is exactly what 4.13.0 already paid**, since its module-level flag died with the module registry between files. **Nothing gets slower; an unearned speed-up is simply not being claimed.** A worker-scoped lifetime remains open, and gets taken when the real per-file cost has been measured on a real application and the runner integration is chosen deliberately rather than inherited from whatever the wiring happened to do
 
-## 4.13.0
+## 4.13.0 - 2026-08-12
 
 ### ⚠ Upgrading from 4.12.0 — read this first
 

package/bin/warlock.js

@@ -1,3 +1,156 @@
 #!/usr/bin/env node
 
-import "../esm/cli/start.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const binDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The published package ships compiled ESM next to this file; a source
+ * checkout (this monorepo, or anyone consuming `@warlock.js/core` straight
+ * from git) has only TypeScript. `main` in package.json already points at
+ * `./src/index.ts`, so "consumed as source" is the supported layout — the bin
+ * has to honour it too instead of assuming build output exists.
+ */
+const publishedEntry = path.join(binDir, "..", "esm", "cli", "start.mjs");
+
+if (existsSync(publishedEntry)) {
+  // One `stat` is the entire cost the published path pays. No loader is
+  // registered, nothing is transpiled, esbuild is never even imported.
+  await import(pathToFileURL(publishedEntry).href);
+} else {
+  await bootFromSource();
+}
+
+/**
+ * Register a TypeScript loader, then hand off to the TS CLI entry.
+ *
+ * Why a bootstrap loader at all, when core already owns one under
+ * `src/dev-server/loader/`? Because that loader is itself TypeScript and is
+ * registered by `registerLoader()`, which can only be reached through a TS
+ * import — the chicken-and-egg. It also wants things a bare `warlock --help`
+ * has no business producing: a `.warlock/` directory in the user's cwd, a
+ * bundled hook worker, a transpile cache and a MessageChannel for HMR bumps.
+ *
+ * So this is deliberately the *smaller* half of that machinery, and it reuses
+ * rather than reimplements the part that actually encodes framework
+ * behaviour: resolution. The sequence below is what makes that possible.
+ */
+async function bootFromSource() {
+  const sourceEntry = path.join(binDir, "..", "src", "cli", "start.ts");
+
+  if (!existsSync(sourceEntry)) {
+    console.error(
+      "[warlock] Neither esm/cli/start.mjs nor src/cli/start.ts was found next to " +
+        `${binDir}. The @warlock.js/core installation looks incomplete.`,
+    );
+    process.exit(1);
+  }
+
+  const { registerHooks } = await import("node:module");
+  const { readFileSync } = await import("node:fs");
+  const { transformSync } = await import("esbuild");
+  const { getTsconfig, resolvePathAlias } = await import("get-tsconfig");
+
+  // Same target the dev loader and the production builder pin, so a file
+  // transpiled here lowers TC39 decorators to the same helper output it would
+  // get anywhere else in the toolchain. Drifting from it would make the CLI a
+  // third, subtly different dialect.
+  const TRANSPILE_TARGET = "node22";
+  const TS_FILE = /\.(ts|tsx|mts|cts)$/;
+  const VERSION_QUERY = /\?v=\d+$/;
+
+  // Read from cwd, not from core: `jsx`, `experimentalDecorators` and friends
+  // are the *app's* call, and this is the same source of truth the dev
+  // loader's resolve hook reads.
+  const tsconfig = getTsconfig(process.cwd());
+  const tsconfigRaw = JSON.stringify({
+    compilerOptions: tsconfig?.config?.compilerOptions ?? {},
+  });
+
+  /**
+   * Handover switch. Verified behaviour: in-thread hooks run *before*
+   * `register()` worker hooks and delegate down the chain. So once the dev
+   * server registers its own loader, these hooks would still intercept every
+   * `.ts` first and short-circuit — silently bypassing the dev loader's
+   * transpile cache and, worse, its `?v=N` HMR stamping.
+   *
+   * Setting `active = false` makes both hooks pure pass-throughs, handing the
+   * TypeScript path over intact. `registerLoader()` should flip it just before
+   * it calls `register()`; until it does, these hooks stay in charge, which is
+   * the correct default for every non-dev command.
+   */
+  const bootstrapLoader = { active: true };
+  globalThis.__warlockBootstrapLoader = bootstrapLoader;
+
+  /**
+   * `load` hook. In-thread (`registerHooks`) rather than the worker-thread
+   * `register()`, which is what lets stage 2 below exist at all: a worker hook
+   * could not hand a transpiled function back to this thread.
+   */
+  function load(url, context, nextLoad) {
+    const cleanUrl = url.replace(VERSION_QUERY, "");
+
+    // Not TypeScript → not ours. npm `.js`, `node:`, JSON all fall through.
+    if (!bootstrapLoader.active || !TS_FILE.test(cleanUrl)) return nextLoad(url, context);
+
+    const absolutePath = fileURLToPath(cleanUrl);
+    const { code } = transformSync(readFileSync(absolutePath, "utf8"), {
+      loader: absolutePath.endsWith(".tsx") ? "tsx" : "ts",
+      format: "esm",
+      target: TRANSPILE_TARGET,
+      sourcefile: absolutePath,
+      sourcemap: "inline",
+      tsconfigRaw,
+    });
+
+    return { format: "module", source: code, shortCircuit: true };
+  }
+
+  registerHooks({ load });
+
+  // Stage 2 — the reuse. With `load` live, core's own resolver can be pulled
+  // in as TypeScript. It is imported by exact absolute path on purpose: it is
+  // a leaf module whose only import is `node:url`, so it needs no extension
+  // probing to load, which is precisely the thing we don't have yet.
+  const { ownResolve } = await import(
+    pathToFileURL(
+      path.join(binDir, "..", "src", "dev-server", "loader", "own-resolver.ts"),
+    ).href
+  );
+
+  let pathsMatcher = null;
+  if (tsconfig) {
+    pathsMatcher = specifier => resolvePathAlias(tsconfig, specifier);
+  }
+
+  /**
+   * `resolve` hook — a thin sync wrapper over `ownResolve`, which owns
+   * tsconfig `paths` plus TS extension/index probing. Everything it returns
+   * `null` for (bare npm, `node:`, `file:`) falls through to Node's default,
+   * which keeps `exports`/`node_modules` semantics intact.
+   *
+   * The dev loader's version of this also stamps `?v=N` for HMR. That is
+   * deliberately absent: the CLI process has no watcher, and the dev server
+   * registers its own full loader when it boots.
+   */
+  function resolve(specifier, context, nextResolve) {
+    const owned = bootstrapLoader.active
+      ? ownResolve(specifier, context.parentURL, pathsMatcher, existsSync)
+      : null;
+
+    // Producing the URL ourselves means `nextResolve` was never called, so the
+    // chain has to be short-circuited explicitly or Node raises
+    // ERR_LOADER_CHAIN_INCOMPLETE.
+    return owned ? { url: owned, shortCircuit: true } : nextResolve(specifier, context);
+  }
+
+  registerHooks({ resolve });
+
+  // The transpile above emits inline maps; without this they'd be dead weight
+  // and every CLI stack trace would point at generated line numbers.
+  process.setSourceMapsEnabled(true);
+
+  await import(pathToFileURL(sourceEntry).href);
+}

package/esm/application/application.d.mts

@@ -22,6 +22,17 @@ type BootContext = {
  * the other listeners.
  */
 type BootListener = (context: BootContext) => void | Promise<void>;
+/**
+ * A callback registered through `Application.onValidateBoot`. May be async —
+ * unlike {@link BootListener}, its rejection is NOT caught: it aborts boot.
+ *
+ * Use this for configuration that makes the application WRONG rather than
+ * degraded when missing (a signing secret, a required integration key) — the
+ * kind of check that must fail closed. Use `onceBooted` for everything else;
+ * that contract stays fire-and-forget on purpose (it is the right behaviour
+ * for plugins reacting to boot, not for gating it).
+ */
+type BootValidator = () => void | Promise<void>;
 /**
  * A callback registered through `Application.onShutdown`. Runs once, while the
  * connectors (db, cache, http) are still up, so it can release app-owned
@@ -50,6 +61,17 @@ declare class Application {
    * `markBooted`.
    */
   private static bootListeners;
+  /**
+   * Whether `runStartupValidators` has already run. Flipped once, so a
+   * validator registered afterwards is refused instead of silently skipped
+   * or run too late to matter.
+   */
+  private static validated;
+  /**
+   * Startup validators queued before `runStartupValidators` ran, drained in
+   * registration order.
+   */
+  private static bootValidators;
   /**
    * The http port this process actually bound, once it has. Reported in the
    * readiness signal so a supervisor knows where to send its health check
@@ -126,6 +148,48 @@ declare class Application {
    * the remaining listeners are affected.
    */
   private static runBootListener;
+  /**
+   * Register a startup validator — distinct from {@link onceBooted}. A
+   * rejecting validator aborts boot instead of being caught and logged, so
+   * this is where configuration that must fail closed belongs (a signing
+   * secret, a required integration key), not `onceBooted`.
+   *
+   * Must be registered before the framework calls `runStartupValidators` —
+   * typically at module scope in `src/app/main.ts`, the same place a
+   * `BootListener` would be registered. Registering one after validation has
+   * already run throws: by then a rejection could no longer stop the app
+   * from serving, so running it late would silently defeat the guarantee
+   * this hook exists to give.
+   *
+   * @example
+   * Application.onValidateBoot(() => {
+   *   if (!env("JWT_SECRET")) {
+   *     throw new Error(
+   *       "JWT_SECRET is not set. Sessions cannot be signed without it. " +
+   *         "Generate one with `yarn jwt` and put it in .env.",
+   *     );
+   *   }
+   * });
+   */
+  static onValidateBoot(validator: BootValidator): void;
+  /**
+   * Run every registered startup validator, in registration order, and abort
+   * on the first rejection. Idempotent — a second call is a no-op.
+   *
+   * Distinct from `runBootListener`: a listener's failure is isolated so it
+   * can never break boot; a validator's failure IS the boot failing — that is
+   * the entire point of registering one instead of the other. The thrown
+   * error names the failing validator and the original cause, so whatever
+   * catches it (the dev server's boot try/catch, the production entry's
+   * top-level await) reports which check failed and why, not a bare
+   * rejection.
+   *
+   * @internal Framework entry points call this once app code (main.ts et al)
+   * has loaded and BEFORE late-phase connectors (http, socket) start, so a
+   * failing validator runs before anything can bind a port or accept a
+   * request. Application code must not call this directly.
+   */
+  static runStartupValidators(): Promise<void>;
   /**
    * Whether the application has begun shutting down. Once true, readiness
    * checks report not-ready so a load balancer drains this instance before the
@@ -209,5 +273,5 @@ declare class Application {
   static get publicPath(): string;
 }
 //#endregion
-export { Application, BootContext, BootListener, ShutdownListener };
+export { Application, BootContext, BootListener, BootValidator, ShutdownListener };
 //# sourceMappingURL=application.d.mts.map

package/esm/application/application.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.mts","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"mappings":";;;;;AAiBA;;;;KAAY,WAAA;EACV,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAe;EAAf;;;AAKH;EAAd,cAAA;AAAA;;;;;;KAQU,YAAA,IAAgB,OAAA,EAAS,WAAA,YAAuB,OAAO;AAAA;AAOnE;;;;AAPmE,KAOvD,gBAAA,gBAAgC,OAAO;AAAA,cAEtC,WAAA;EAAW;;;EAAA,gBAIC,SAAA,EAAS,IAAA;EAoDW;;;EAAA,OA/C7B,eAAA,EAAiB,eAAA;EA0HG;;;EAAA,eArHnB,MAAA;EAkPmB;;;EAAA,eA7OnB,WAAA;EAfiB;;;;EAAA,eAqBjB,aAAA;EAAA;;;;;;EAAA,eAQA,UAAA;EAuBkB;;;;EAAA,eAjBlB,YAAA;EAqDoB;;;EAAA,eAhDpB,iBAAA;EA+DqB;;;EAAA,WA1DlB,OAAA;EAiHG;;;EAAA,OA1GP,kBAAA,CAAmB,QAAA,EAAU,eAAA;EAyIlB;;;;;EAAA,WAhIP,QAAA;EAwLe;;;;;EAAA,OA/KnB,aAAA,CAAc,IAAA;EA2MV;;;;;;;;AA0CU;;;;;;EA1CV,OAzLJ,UAAA,CAAW,QAAA,EAAU,YAAA;;;;;SAerB,UAAA,IAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;SAwBtB,UAAA,CAAW,OAAA,EAAS,WAAA;;;;;iBA+Bb,eAAA;;;;;;aAgBH,cAAA;;;;;;;;;;;;SAeJ,UAAA,CAAW,QAAA,EAAU,gBAAA;;;;;;;;;;SAmBf,gBAAA,IAAoB,OAAA;;;;;iBAmBnB,mBAAA;;;;aAWH,MAAA;;;;aAOA,WAAA,IAAe,WAAA;;;;SAOnB,cAAA,CAAe,GAAA,EAAK,WAAA;;;;aAOhB,YAAA;;;;aAOA,aAAA;;;;aAOA,MAAA;;;;aAOA,QAAA;;;;aAOA,OAAA;;;;aAOA,OAAA;;;;aAOA,WAAA;;;;aAOA,WAAA;;;;aAOA,UAAA;AAAA"}
+{"version":3,"file":"application.d.mts","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"mappings":";;;;;AAiBA;;;;KAAY,WAAA;EACV,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAe;EAAf;;;AAKH;EAAd,cAAA;AAAA;;;;;;KAQU,YAAA,IAAgB,OAAA,EAAS,WAAA,YAAuB,OAAO;AAAA;AAYnE;;;;AAAgD;AAkBhD;;;;AA9BmE,KAYvD,aAAA,gBAA6B,OAAO;AAoBhD;;;;;AAAA,KAFY,gBAAA,gBAAgC,OAAO;AAAA,cAEtC,WAAA;EAwHyB;;;EAAA,gBApHb,SAAA,EAAS,IAAA;EA2OY;;;EAAA,OAtO9B,eAAA,EAAiB,eAAA;EAoVG;;;EAAA,eA/UnB,MAAA;EAViB;;;EAAA,eAejB,WAAA;EAAA;;;;EAAA,eAMA,aAAA;EA2BA;;;;;EAAA,eApBA,SAAA;EA8CG;;;;EAAA,eAxCH,cAAA;EAmEU;;;;;;EAAA,eA3DV,UAAA;EAiIM;;;;EAAA,eA3HN,YAAA;EA2L6B;;;EAAA,eAtL7B,iBAAA;EAqOU;;;EAAA,WAhOP,OAAA;EAiRA;;;EAAA,OA1QJ,kBAAA,CAAmB,QAAA,EAAU,eAAA;EAwRT;;;;;EAAA,WA/QhB,QAAA;EAkTA;;;;;EAAA,OAzSJ,aAAA,CAAc,IAAA;EAqUA;;;;;;;;;;;;;;EAAA,OAnTd,UAAA,CAAW,QAAA,EAAU,YAAA;;;;;SAerB,UAAA,IAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;SAwBtB,UAAA,CAAW,OAAA,EAAS,WAAA;;;;;iBA+Bb,eAAA;;;;;;;;;;;;;;;;;;;;;;;;SAkCP,cAAA,CAAe,SAAA,EAAW,aAAA;;;;;;;;;;;;;;;;;;SA8BpB,oBAAA,IAAwB,OAAA;;;;;;aAgC1B,cAAA;;;;;;;;;;;;SAeJ,UAAA,CAAW,QAAA,EAAU,gBAAA;;;;;;;;;;SAmBf,gBAAA,IAAoB,OAAA;;;;;iBAmBnB,mBAAA;;;;aAWH,MAAA;;;;aAOA,WAAA,IAAe,WAAA;;;;SAOnB,cAAA,CAAe,GAAA,EAAK,WAAA;;;;aAOhB,YAAA;;;;aAOA,aAAA;;;;aAOA,MAAA;;;;aAOA,QAAA;;;;aAOA,OAAA;;;;aAOA,OAAA;;;;aAOA,WAAA;;;;aAOA,WAAA;;;;aAOA,UAAA;AAAA"}

package/esm/application/application.mjs

@@ -5,6 +5,7 @@ import { getFrameworkVersion } from "../utils/framework-vesion.mjs";
 import { log } from "@warlock.js/logger";
 
 //#region ../core/src/application/application.ts
+const ErrorWithCause = Error;
 var Application = class {
 	static {
 		this.startedAt = /* @__PURE__ */ new Date(Date.now() - process.uptime() * 1e3);
@@ -15,6 +16,12 @@ var Application = class {
 	static {
 		this.bootListeners = [];
 	}
+	static {
+		this.validated = false;
+	}
+	static {
+		this.bootValidators = [];
+	}
 	static {
 		this.shuttingDown = false;
 	}
@@ -125,6 +132,61 @@ var Application = class {
 		}
 	}
 	/**
+	* Register a startup validator — distinct from {@link onceBooted}. A
+	* rejecting validator aborts boot instead of being caught and logged, so
+	* this is where configuration that must fail closed belongs (a signing
+	* secret, a required integration key), not `onceBooted`.
+	*
+	* Must be registered before the framework calls `runStartupValidators` —
+	* typically at module scope in `src/app/main.ts`, the same place a
+	* `BootListener` would be registered. Registering one after validation has
+	* already run throws: by then a rejection could no longer stop the app
+	* from serving, so running it late would silently defeat the guarantee
+	* this hook exists to give.
+	*
+	* @example
+	* Application.onValidateBoot(() => {
+	*   if (!env("JWT_SECRET")) {
+	*     throw new Error(
+	*       "JWT_SECRET is not set. Sessions cannot be signed without it. " +
+	*         "Generate one with `yarn jwt` and put it in .env.",
+	*     );
+	*   }
+	* });
+	*/
+	static onValidateBoot(validator) {
+		if (this.validated) throw new Error("Application.onValidateBoot(): startup validators already ran — this validator was registered too late to block boot. Register it before the framework calls Application.runStartupValidators(), typically at module scope in `src/app/main.ts`.");
+		this.bootValidators.push(validator);
+	}
+	/**
+	* Run every registered startup validator, in registration order, and abort
+	* on the first rejection. Idempotent — a second call is a no-op.
+	*
+	* Distinct from `runBootListener`: a listener's failure is isolated so it
+	* can never break boot; a validator's failure IS the boot failing — that is
+	* the entire point of registering one instead of the other. The thrown
+	* error names the failing validator and the original cause, so whatever
+	* catches it (the dev server's boot try/catch, the production entry's
+	* top-level await) reports which check failed and why, not a bare
+	* rejection.
+	*
+	* @internal Framework entry points call this once app code (main.ts et al)
+	* has loaded and BEFORE late-phase connectors (http, socket) start, so a
+	* failing validator runs before anything can bind a port or accept a
+	* request. Application code must not call this directly.
+	*/
+	static async runStartupValidators() {
+		if (this.validated) return;
+		this.validated = true;
+		const validators = this.bootValidators;
+		this.bootValidators = [];
+		for (const validator of validators) try {
+			await validator();
+		} catch (error) {
+			throw new ErrorWithCause(`Startup validator "${validator.name || "<anonymous>"}" rejected boot: ${error instanceof Error ? error.message : String(error)}. Fix the condition it checks, or remove the validator if it no longer applies — boot cannot proceed while it fails.`, { cause: error });
+		}
+	}
+	/**
 	* Whether the application has begun shutting down. Once true, readiness
 	* checks report not-ready so a load balancer drains this instance before the
 	* HTTP server stops accepting requests.

package/esm/application/application.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"application.mjs","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { BOOT_SIGNAL_VERSION, sendBootSignal } from \"./boot-signal\";\nimport {\n  environment,\n  setEnvironment,\n  type Environment,\n  type RuntimeStrategy,\n} from \"../utils/environment\";\nimport { getFrameworkVersion } from \"../utils/framework-vesion\";\nimport { appPath, publicPath, rootPath, srcPath, storagePath, uploadsPath } from \"../utils/paths\";\n\n/**\n * Snapshot of the global facts known the moment the application finished\n * booting: every connector (early + late) is active and all app files\n * (locales, events, main, routes) are loaded. Passed to every\n * `Application.onceBooted` listener and resolved from `Application.whenBooted`.\n */\nexport type BootContext = {\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  /**\n   * Wall-clock milliseconds the boot took. The dev server measures it; the\n   * production entry omits it.\n   */\n  bootDurationMs?: number;\n};\n\n/**\n * A callback registered through `Application.onceBooted`. May be async — its\n * rejection is caught and logged so a single listener can never break boot or\n * the other listeners.\n */\nexport type BootListener = (context: BootContext) => void | Promise<void>;\n\n/**\n * A callback registered through `Application.onShutdown`. Runs once, while the\n * connectors (db, cache, http) are still up, so it can release app-owned\n * resources cleanly. May be async — its rejection is caught and logged.\n */\nexport type ShutdownListener = () => void | Promise<void>;\n\nexport class Application {\n  /**\n   * Project start time regarding the process start time\n   */\n  public static readonly startedAt = new Date(Date.now() - process.uptime() * 1000);\n\n  /**\n   * Runtime strategy\n   */\n  public static runtimeStrategy: RuntimeStrategy;\n\n  /**\n   * Whether the application has finished booting. Flipped once by `markBooted`.\n   */\n  private static booted = false;\n\n  /**\n   * The boot context, set once booted so it can be replayed to late subscribers.\n   */\n  private static bootContext: BootContext | undefined;\n\n  /**\n   * Listeners queued before boot completed, drained in registration order by\n   * `markBooted`.\n   */\n  private static bootListeners: BootListener[] = [];\n\n  /**\n   * The http port this process actually bound, once it has. Reported in the\n   * readiness signal so a supervisor knows where to send its health check\n   * instead of re-deriving it from config it may not be able to read.\n   * Undefined for an app with no http connector — a queue worker still boots.\n   */\n  private static servedPort: number | undefined;\n\n  /**\n   * Whether the application has begun (or finished) shutting down. Flipped once\n   * by `runShutdownHooks`.\n   */\n  private static shuttingDown = false;\n\n  /**\n   * Teardown callbacks, run once when shutdown begins.\n   */\n  private static shutdownListeners: ShutdownListener[] = [];\n\n  /**\n   * Get framework version\n   */\n  public static get version() {\n    return getFrameworkVersion();\n  }\n\n  /**\n   * Set the runtime strategy\n   */\n  public static setRuntimeStrategy(strategy: RuntimeStrategy) {\n    this.runtimeStrategy = strategy;\n  }\n\n  /**\n   * Whether the application has finished booting — every connector in both\n   * the early and late phases is active and all app files (locales, events,\n   * main, routes) have been loaded.\n   */\n  public static get isBooted(): boolean {\n    return this.booted;\n  }\n\n  /**\n   * Record the http port this process bound.\n   *\n   * @internal The http connector calls this after a successful `listen`.\n   */\n  public static setServedPort(port: number): void {\n    this.servedPort = port;\n  }\n\n  /**\n   * Run a callback once the application is fully booted.\n   *\n   * App files (`main` / `events` / `routes` / locales) are imported BEFORE the\n   * late-phase connectors (http, socket) start, so a listener registered at\n   * import time waits for the whole sequence to finish before it runs. If the\n   * application is already booted, the callback runs on the next microtask —\n   * so a late subscriber never silently misses the event.\n   *\n   * @example\n   * Application.onceBooted(({ environment }) => {\n   *   log.info(\"app\", \"booted\", `ready in ${environment}`);\n   * });\n   */\n  public static onceBooted(listener: BootListener): void {\n    if (this.booted && this.bootContext) {\n      const context = this.bootContext;\n      void this.runBootListener(listener, context);\n\n      return;\n    }\n\n    this.bootListeners.push(listener);\n  }\n\n  /**\n   * Promise form of {@link onceBooted} — resolves with the boot context once\n   * the application is booted, or immediately if it already is.\n   */\n  public static whenBooted(): Promise<BootContext> {\n    if (this.booted && this.bootContext) {\n      return Promise.resolve(this.bootContext);\n    }\n\n    return new Promise<BootContext>((resolve) => {\n      this.onceBooted((context) => resolve(context));\n    });\n  }\n\n  /**\n   * Flip the boot latch and drain every queued listener. The dev server and\n   * the production entry call this once, right after the late phase starts. It\n   * is idempotent — a second call is a no-op, so a double-invoke can never\n   * double-fire listeners.\n   *\n   * Also reports readiness to a supervising parent process — this is the one\n   * moment in the lifecycle where \"the application is serving\" is true, so it\n   * is the only honest source for `warlock start`'s success banner. Sent before\n   * the listeners run: a slow or hanging `onceBooted` listener must not delay\n   * the parent's view of a server that is already accepting requests.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static markBooted(context: BootContext): void {\n    if (this.booted) {\n      return;\n    }\n\n    this.booted = true;\n    this.bootContext = context;\n\n    sendBootSignal({\n      type: \"warlock:ready\",\n      version: BOOT_SIGNAL_VERSION,\n      pid: process.pid,\n      at: new Date().toISOString(),\n      environment: context.environment,\n      runtimeStrategy: context.runtimeStrategy,\n      bootDurationMs: context.bootDurationMs,\n      port: this.servedPort,\n    });\n\n    const listeners = this.bootListeners;\n    this.bootListeners = [];\n\n    for (const listener of listeners) {\n      void this.runBootListener(listener, context);\n    }\n  }\n\n  /**\n   * Invoke a single boot listener, isolating its failure so neither boot nor\n   * the remaining listeners are affected.\n   */\n  private static async runBootListener(\n    listener: BootListener,\n    context: BootContext,\n  ): Promise<void> {\n    try {\n      await listener(context);\n    } catch (error) {\n      log.error(\"application\", \"booted-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Whether the application has begun shutting down. Once true, readiness\n   * checks report not-ready so a load balancer drains this instance before the\n   * HTTP server stops accepting requests.\n   */\n  public static get isShuttingDown(): boolean {\n    return this.shuttingDown;\n  }\n\n  /**\n   * Register a teardown callback, run once when the application shuts down —\n   * before the connectors (db, cache, http) are torn down, so it can still use\n   * them. The natural place to close an app-owned resource opened in\n   * `onceBooted`. If shutdown has already begun, the callback runs immediately.\n   *\n   * @example\n   * Application.onShutdown(async () => {\n   *   await myQueueConsumer.stop();\n   * });\n   */\n  public static onShutdown(listener: ShutdownListener): void {\n    if (this.shuttingDown) {\n      void this.runShutdownListener(listener);\n\n      return;\n    }\n\n    this.shutdownListeners.push(listener);\n  }\n\n  /**\n   * Flip the shutdown latch and run every teardown callback. The connectors\n   * manager calls this at the start of shutdown — before any connector is torn\n   * down. Idempotent and error-isolated: each callback is awaited, a thrown one\n   * is logged and does not stop the rest. Listeners run LIFO (reverse of\n   * registration), mirroring resource-unwind order.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static async runShutdownHooks(): Promise<void> {\n    if (this.shuttingDown) {\n      return;\n    }\n\n    this.shuttingDown = true;\n\n    const listeners = this.shutdownListeners.reverse();\n    this.shutdownListeners = [];\n\n    for (const listener of listeners) {\n      await this.runShutdownListener(listener);\n    }\n  }\n\n  /**\n   * Invoke a single teardown callback, isolating its failure so the rest still\n   * run and shutdown is never blocked by one bad hook.\n   */\n  private static async runShutdownListener(listener: ShutdownListener): Promise<void> {\n    try {\n      await listener();\n    } catch (error) {\n      log.error(\"application\", \"shutdown-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Get project uptime in milliseconds\n   */\n  public static get uptime(): number {\n    return process.uptime() * 1000;\n  }\n\n  /**\n   * Get the current environment\n   */\n  public static get environment(): Environment {\n    return environment();\n  }\n\n  /**\n   * Set the current environment\n   */\n  public static setEnvironment(env: Environment) {\n    setEnvironment(env);\n  }\n\n  /**\n   * Check if the application is running in production environment\n   */\n  public static get isProduction(): boolean {\n    return this.environment === \"production\";\n  }\n\n  /**\n   * Check if the application is running in development environment\n   */\n  public static get isDevelopment(): boolean {\n    return this.environment === \"development\";\n  }\n\n  /**\n   * Check if the application is running in test environment\n   */\n  public static get isTest(): boolean {\n    return this.environment === \"test\";\n  }\n\n  /**\n   * Get the root path\n   */\n  public static get rootPath(): string {\n    return rootPath();\n  }\n\n  /**\n   * Get the src path\n   */\n  public static get srcPath(): string {\n    return srcPath();\n  }\n\n  /**\n   * Get the app path\n   */\n  public static get appPath(): string {\n    return appPath();\n  }\n\n  /**\n   * Get the storage path\n   */\n  public static get storagePath(): string {\n    return storagePath();\n  }\n\n  /**\n   * Get the uploads path\n   */\n  public static get uploadsPath(): string {\n    return uploadsPath();\n  }\n\n  /**\n   * Get the public path\n   */\n  public static get publicPath(): string {\n    return publicPath();\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"application.mjs","names":[],"sources":["../../../../../../../core/src/application/application.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { BOOT_SIGNAL_VERSION, sendBootSignal } from \"./boot-signal\";\nimport {\n  environment,\n  setEnvironment,\n  type Environment,\n  type RuntimeStrategy,\n} from \"../utils/environment\";\nimport { getFrameworkVersion } from \"../utils/framework-vesion\";\nimport { appPath, publicPath, rootPath, srcPath, storagePath, uploadsPath } from \"../utils/paths\";\n\n/**\n * Snapshot of the global facts known the moment the application finished\n * booting: every connector (early + late) is active and all app files\n * (locales, events, main, routes) are loaded. Passed to every\n * `Application.onceBooted` listener and resolved from `Application.whenBooted`.\n */\nexport type BootContext = {\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  /**\n   * Wall-clock milliseconds the boot took. The dev server measures it; the\n   * production entry omits it.\n   */\n  bootDurationMs?: number;\n};\n\n/**\n * A callback registered through `Application.onceBooted`. May be async — its\n * rejection is caught and logged so a single listener can never break boot or\n * the other listeners.\n */\nexport type BootListener = (context: BootContext) => void | Promise<void>;\n\n/**\n * A callback registered through `Application.onValidateBoot`. May be async —\n * unlike {@link BootListener}, its rejection is NOT caught: it aborts boot.\n *\n * Use this for configuration that makes the application WRONG rather than\n * degraded when missing (a signing secret, a required integration key) — the\n * kind of check that must fail closed. Use `onceBooted` for everything else;\n * that contract stays fire-and-forget on purpose (it is the right behaviour\n * for plugins reacting to boot, not for gating it).\n */\nexport type BootValidator = () => void | Promise<void>;\n\n/**\n * `new Error(message, { cause })` is ES2022, and this package still compiles\n * against the ES2020 lib, where `Error` is typed as taking a message only.\n * Node has supported the option since v16, so this is the type layer\n * catching up with the runtime, not a change in what the code does. Same\n * workaround as `image.ts` (see #16).\n */\ntype ErrorWithCauseConstructor = new (message: string, options: { cause: unknown }) => Error;\n\nconst ErrorWithCause = Error as ErrorWithCauseConstructor;\n\n/**\n * A callback registered through `Application.onShutdown`. Runs once, while the\n * connectors (db, cache, http) are still up, so it can release app-owned\n * resources cleanly. May be async — its rejection is caught and logged.\n */\nexport type ShutdownListener = () => void | Promise<void>;\n\nexport class Application {\n  /**\n   * Project start time regarding the process start time\n   */\n  public static readonly startedAt = new Date(Date.now() - process.uptime() * 1000);\n\n  /**\n   * Runtime strategy\n   */\n  public static runtimeStrategy: RuntimeStrategy;\n\n  /**\n   * Whether the application has finished booting. Flipped once by `markBooted`.\n   */\n  private static booted = false;\n\n  /**\n   * The boot context, set once booted so it can be replayed to late subscribers.\n   */\n  private static bootContext: BootContext | undefined;\n\n  /**\n   * Listeners queued before boot completed, drained in registration order by\n   * `markBooted`.\n   */\n  private static bootListeners: BootListener[] = [];\n\n  /**\n   * Whether `runStartupValidators` has already run. Flipped once, so a\n   * validator registered afterwards is refused instead of silently skipped\n   * or run too late to matter.\n   */\n  private static validated = false;\n\n  /**\n   * Startup validators queued before `runStartupValidators` ran, drained in\n   * registration order.\n   */\n  private static bootValidators: BootValidator[] = [];\n\n  /**\n   * The http port this process actually bound, once it has. Reported in the\n   * readiness signal so a supervisor knows where to send its health check\n   * instead of re-deriving it from config it may not be able to read.\n   * Undefined for an app with no http connector — a queue worker still boots.\n   */\n  private static servedPort: number | undefined;\n\n  /**\n   * Whether the application has begun (or finished) shutting down. Flipped once\n   * by `runShutdownHooks`.\n   */\n  private static shuttingDown = false;\n\n  /**\n   * Teardown callbacks, run once when shutdown begins.\n   */\n  private static shutdownListeners: ShutdownListener[] = [];\n\n  /**\n   * Get framework version\n   */\n  public static get version() {\n    return getFrameworkVersion();\n  }\n\n  /**\n   * Set the runtime strategy\n   */\n  public static setRuntimeStrategy(strategy: RuntimeStrategy) {\n    this.runtimeStrategy = strategy;\n  }\n\n  /**\n   * Whether the application has finished booting — every connector in both\n   * the early and late phases is active and all app files (locales, events,\n   * main, routes) have been loaded.\n   */\n  public static get isBooted(): boolean {\n    return this.booted;\n  }\n\n  /**\n   * Record the http port this process bound.\n   *\n   * @internal The http connector calls this after a successful `listen`.\n   */\n  public static setServedPort(port: number): void {\n    this.servedPort = port;\n  }\n\n  /**\n   * Run a callback once the application is fully booted.\n   *\n   * App files (`main` / `events` / `routes` / locales) are imported BEFORE the\n   * late-phase connectors (http, socket) start, so a listener registered at\n   * import time waits for the whole sequence to finish before it runs. If the\n   * application is already booted, the callback runs on the next microtask —\n   * so a late subscriber never silently misses the event.\n   *\n   * @example\n   * Application.onceBooted(({ environment }) => {\n   *   log.info(\"app\", \"booted\", `ready in ${environment}`);\n   * });\n   */\n  public static onceBooted(listener: BootListener): void {\n    if (this.booted && this.bootContext) {\n      const context = this.bootContext;\n      void this.runBootListener(listener, context);\n\n      return;\n    }\n\n    this.bootListeners.push(listener);\n  }\n\n  /**\n   * Promise form of {@link onceBooted} — resolves with the boot context once\n   * the application is booted, or immediately if it already is.\n   */\n  public static whenBooted(): Promise<BootContext> {\n    if (this.booted && this.bootContext) {\n      return Promise.resolve(this.bootContext);\n    }\n\n    return new Promise<BootContext>((resolve) => {\n      this.onceBooted((context) => resolve(context));\n    });\n  }\n\n  /**\n   * Flip the boot latch and drain every queued listener. The dev server and\n   * the production entry call this once, right after the late phase starts. It\n   * is idempotent — a second call is a no-op, so a double-invoke can never\n   * double-fire listeners.\n   *\n   * Also reports readiness to a supervising parent process — this is the one\n   * moment in the lifecycle where \"the application is serving\" is true, so it\n   * is the only honest source for `warlock start`'s success banner. Sent before\n   * the listeners run: a slow or hanging `onceBooted` listener must not delay\n   * the parent's view of a server that is already accepting requests.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static markBooted(context: BootContext): void {\n    if (this.booted) {\n      return;\n    }\n\n    this.booted = true;\n    this.bootContext = context;\n\n    sendBootSignal({\n      type: \"warlock:ready\",\n      version: BOOT_SIGNAL_VERSION,\n      pid: process.pid,\n      at: new Date().toISOString(),\n      environment: context.environment,\n      runtimeStrategy: context.runtimeStrategy,\n      bootDurationMs: context.bootDurationMs,\n      port: this.servedPort,\n    });\n\n    const listeners = this.bootListeners;\n    this.bootListeners = [];\n\n    for (const listener of listeners) {\n      void this.runBootListener(listener, context);\n    }\n  }\n\n  /**\n   * Invoke a single boot listener, isolating its failure so neither boot nor\n   * the remaining listeners are affected.\n   */\n  private static async runBootListener(\n    listener: BootListener,\n    context: BootContext,\n  ): Promise<void> {\n    try {\n      await listener(context);\n    } catch (error) {\n      log.error(\"application\", \"booted-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Register a startup validator — distinct from {@link onceBooted}. A\n   * rejecting validator aborts boot instead of being caught and logged, so\n   * this is where configuration that must fail closed belongs (a signing\n   * secret, a required integration key), not `onceBooted`.\n   *\n   * Must be registered before the framework calls `runStartupValidators` —\n   * typically at module scope in `src/app/main.ts`, the same place a\n   * `BootListener` would be registered. Registering one after validation has\n   * already run throws: by then a rejection could no longer stop the app\n   * from serving, so running it late would silently defeat the guarantee\n   * this hook exists to give.\n   *\n   * @example\n   * Application.onValidateBoot(() => {\n   *   if (!env(\"JWT_SECRET\")) {\n   *     throw new Error(\n   *       \"JWT_SECRET is not set. Sessions cannot be signed without it. \" +\n   *         \"Generate one with `yarn jwt` and put it in .env.\",\n   *     );\n   *   }\n   * });\n   */\n  public static onValidateBoot(validator: BootValidator): void {\n    if (this.validated) {\n      throw new Error(\n        \"Application.onValidateBoot(): startup validators already ran — \" +\n          \"this validator was registered too late to block boot. Register it \" +\n          \"before the framework calls Application.runStartupValidators(), \" +\n          \"typically at module scope in `src/app/main.ts`.\",\n      );\n    }\n\n    this.bootValidators.push(validator);\n  }\n\n  /**\n   * Run every registered startup validator, in registration order, and abort\n   * on the first rejection. Idempotent — a second call is a no-op.\n   *\n   * Distinct from `runBootListener`: a listener's failure is isolated so it\n   * can never break boot; a validator's failure IS the boot failing — that is\n   * the entire point of registering one instead of the other. The thrown\n   * error names the failing validator and the original cause, so whatever\n   * catches it (the dev server's boot try/catch, the production entry's\n   * top-level await) reports which check failed and why, not a bare\n   * rejection.\n   *\n   * @internal Framework entry points call this once app code (main.ts et al)\n   * has loaded and BEFORE late-phase connectors (http, socket) start, so a\n   * failing validator runs before anything can bind a port or accept a\n   * request. Application code must not call this directly.\n   */\n  public static async runStartupValidators(): Promise<void> {\n    if (this.validated) {\n      return;\n    }\n\n    this.validated = true;\n\n    const validators = this.bootValidators;\n    this.bootValidators = [];\n\n    for (const validator of validators) {\n      try {\n        await validator();\n      } catch (error) {\n        const name = validator.name || \"<anonymous>\";\n        const cause = error instanceof Error ? error.message : String(error);\n\n        throw new ErrorWithCause(\n          `Startup validator \"${name}\" rejected boot: ${cause}. ` +\n            `Fix the condition it checks, or remove the validator if it no ` +\n            `longer applies — boot cannot proceed while it fails.`,\n          { cause: error },\n        );\n      }\n    }\n  }\n\n  /**\n   * Whether the application has begun shutting down. Once true, readiness\n   * checks report not-ready so a load balancer drains this instance before the\n   * HTTP server stops accepting requests.\n   */\n  public static get isShuttingDown(): boolean {\n    return this.shuttingDown;\n  }\n\n  /**\n   * Register a teardown callback, run once when the application shuts down —\n   * before the connectors (db, cache, http) are torn down, so it can still use\n   * them. The natural place to close an app-owned resource opened in\n   * `onceBooted`. If shutdown has already begun, the callback runs immediately.\n   *\n   * @example\n   * Application.onShutdown(async () => {\n   *   await myQueueConsumer.stop();\n   * });\n   */\n  public static onShutdown(listener: ShutdownListener): void {\n    if (this.shuttingDown) {\n      void this.runShutdownListener(listener);\n\n      return;\n    }\n\n    this.shutdownListeners.push(listener);\n  }\n\n  /**\n   * Flip the shutdown latch and run every teardown callback. The connectors\n   * manager calls this at the start of shutdown — before any connector is torn\n   * down. Idempotent and error-isolated: each callback is awaited, a thrown one\n   * is logged and does not stop the rest. Listeners run LIFO (reverse of\n   * registration), mirroring resource-unwind order.\n   *\n   * @internal Framework entry points call this; application code must not.\n   */\n  public static async runShutdownHooks(): Promise<void> {\n    if (this.shuttingDown) {\n      return;\n    }\n\n    this.shuttingDown = true;\n\n    const listeners = this.shutdownListeners.reverse();\n    this.shutdownListeners = [];\n\n    for (const listener of listeners) {\n      await this.runShutdownListener(listener);\n    }\n  }\n\n  /**\n   * Invoke a single teardown callback, isolating its failure so the rest still\n   * run and shutdown is never blocked by one bad hook.\n   */\n  private static async runShutdownListener(listener: ShutdownListener): Promise<void> {\n    try {\n      await listener();\n    } catch (error) {\n      log.error(\"application\", \"shutdown-listener\", error as Error);\n    }\n  }\n\n  /**\n   * Get project uptime in milliseconds\n   */\n  public static get uptime(): number {\n    return process.uptime() * 1000;\n  }\n\n  /**\n   * Get the current environment\n   */\n  public static get environment(): Environment {\n    return environment();\n  }\n\n  /**\n   * Set the current environment\n   */\n  public static setEnvironment(env: Environment) {\n    setEnvironment(env);\n  }\n\n  /**\n   * Check if the application is running in production environment\n   */\n  public static get isProduction(): boolean {\n    return this.environment === \"production\";\n  }\n\n  /**\n   * Check if the application is running in development environment\n   */\n  public static get isDevelopment(): boolean {\n    return this.environment === \"development\";\n  }\n\n  /**\n   * Check if the application is running in test environment\n   */\n  public static get isTest(): boolean {\n    return this.environment === \"test\";\n  }\n\n  /**\n   * Get the root path\n   */\n  public static get rootPath(): string {\n    return rootPath();\n  }\n\n  /**\n   * Get the src path\n   */\n  public static get srcPath(): string {\n    return srcPath();\n  }\n\n  /**\n   * Get the app path\n   */\n  public static get appPath(): string {\n    return appPath();\n  }\n\n  /**\n   * Get the storage path\n   */\n  public static get storagePath(): string {\n    return storagePath();\n  }\n\n  /**\n   * Get the uploads path\n   */\n  public static get uploadsPath(): string {\n    return uploadsPath();\n  }\n\n  /**\n   * Get the public path\n   */\n  public static get publicPath(): string {\n    return publicPath();\n  }\n}\n"],"mappings":";;;;;;;AAuDA,MAAM,iBAAiB;AASvB,IAAa,cAAb,MAAyB;;mCAIY,IAAI,KAAK,KAAK,IAAI,IAAI,QAAQ,OAAO,IAAI,GAAI;;;gBAUxD;;;uBAWuB,CAAC;;;mBAOrB;;;wBAMsB,CAAC;;;sBAcpB;;;2BAKyB,CAAC;;;;;CAKxD,WAAkB,UAAU;EAC1B,OAAO,oBAAoB;CAC7B;;;;CAKA,OAAc,mBAAmB,UAA2B;EAC1D,KAAK,kBAAkB;CACzB;;;;;;CAOA,WAAkB,WAAoB;EACpC,OAAO,KAAK;CACd;;;;;;CAOA,OAAc,cAAc,MAAoB;EAC9C,KAAK,aAAa;CACpB;;;;;;;;;;;;;;;CAgBA,OAAc,WAAW,UAA8B;EACrD,IAAI,KAAK,UAAU,KAAK,aAAa;GACnC,MAAM,UAAU,KAAK;GACrB,AAAK,KAAK,gBAAgB,UAAU,OAAO;GAE3C;EACF;EAEA,KAAK,cAAc,KAAK,QAAQ;CAClC;;;;;CAMA,OAAc,aAAmC;EAC/C,IAAI,KAAK,UAAU,KAAK,aACtB,OAAO,QAAQ,QAAQ,KAAK,WAAW;EAGzC,OAAO,IAAI,SAAsB,YAAY;GAC3C,KAAK,YAAY,YAAY,QAAQ,OAAO,CAAC;EAC/C,CAAC;CACH;;;;;;;;;;;;;;;CAgBA,OAAc,WAAW,SAA4B;EACnD,IAAI,KAAK,QACP;EAGF,KAAK,SAAS;EACd,KAAK,cAAc;EAEnB,eAAe;GACb,MAAM;GACN;GACA,KAAK,QAAQ;GACb,qBAAI,IAAI,KAAK,EAAC,CAAC,YAAY;GAC3B,aAAa,QAAQ;GACrB,iBAAiB,QAAQ;GACzB,gBAAgB,QAAQ;GACxB,MAAM,KAAK;EACb,CAAC;EAED,MAAM,YAAY,KAAK;EACvB,KAAK,gBAAgB,CAAC;EAEtB,KAAK,MAAM,YAAY,WACrB,AAAK,KAAK,gBAAgB,UAAU,OAAO;CAE/C;;;;;CAMA,aAAqB,gBACnB,UACA,SACe;EACf,IAAI;GACF,MAAM,SAAS,OAAO;EACxB,SAAS,OAAO;GACd,IAAI,MAAM,eAAe,mBAAmB,KAAc;EAC5D;CACF;;;;;;;;;;;;;;;;;;;;;;;;CAyBA,OAAc,eAAe,WAAgC;EAC3D,IAAI,KAAK,WACP,MAAM,IAAI,MACR,iPAIF;EAGF,KAAK,eAAe,KAAK,SAAS;CACpC;;;;;;;;;;;;;;;;;;CAmBA,aAAoB,uBAAsC;EACxD,IAAI,KAAK,WACP;EAGF,KAAK,YAAY;EAEjB,MAAM,aAAa,KAAK;EACxB,KAAK,iBAAiB,CAAC;EAEvB,KAAK,MAAM,aAAa,YACtB,IAAI;GACF,MAAM,UAAU;EAClB,SAAS,OAAO;GAId,MAAM,IAAI,eACR,sBAJW,UAAU,QAAQ,cAIF,mBAHf,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAGb,uHAGpD,EAAE,OAAO,MAAM,CACjB;EACF;CAEJ;;;;;;CAOA,WAAkB,iBAA0B;EAC1C,OAAO,KAAK;CACd;;;;;;;;;;;;CAaA,OAAc,WAAW,UAAkC;EACzD,IAAI,KAAK,cAAc;GACrB,AAAK,KAAK,oBAAoB,QAAQ;GAEtC;EACF;EAEA,KAAK,kBAAkB,KAAK,QAAQ;CACtC;;;;;;;;;;CAWA,aAAoB,mBAAkC;EACpD,IAAI,KAAK,cACP;EAGF,KAAK,eAAe;EAEpB,MAAM,YAAY,KAAK,kBAAkB,QAAQ;EACjD,KAAK,oBAAoB,CAAC;EAE1B,KAAK,MAAM,YAAY,WACrB,MAAM,KAAK,oBAAoB,QAAQ;CAE3C;;;;;CAMA,aAAqB,oBAAoB,UAA2C;EAClF,IAAI;GACF,MAAM,SAAS;EACjB,SAAS,OAAO;GACd,IAAI,MAAM,eAAe,qBAAqB,KAAc;EAC9D;CACF;;;;CAKA,WAAkB,SAAiB;EACjC,OAAO,QAAQ,OAAO,IAAI;CAC5B;;;;CAKA,WAAkB,cAA2B;EAC3C,OAAO,YAAY;CACrB;;;;CAKA,OAAc,eAAe,KAAkB;EAC7C,eAAe,GAAG;CACpB;;;;CAKA,WAAkB,eAAwB;EACxC,OAAO,KAAK,gBAAgB;CAC9B;;;;CAKA,WAAkB,gBAAyB;EACzC,OAAO,KAAK,gBAAgB;CAC9B;;;;CAKA,WAAkB,SAAkB;EAClC,OAAO,KAAK,gBAAgB;CAC9B;;;;CAKA,WAAkB,WAAmB;EACnC,OAAO,SAAS;CAClB;;;;CAKA,WAAkB,UAAkB;EAClC,OAAO,QAAQ;CACjB;;;;CAKA,WAAkB,UAAkB;EAClC,OAAO,QAAQ;CACjB;;;;CAKA,WAAkB,cAAsB;EACtC,OAAO,YAAY;CACrB;;;;CAKA,WAAkB,cAAsB;EACtC,OAAO,YAAY;CACrB;;;;CAKA,WAAkB,aAAqB;EACrC,OAAO,WAAW;CACpB;AACF"}

package/esm/application/index.d.mts

@@ -1,4 +1,4 @@
 import { app } from "./app.mjs";
-import { Application, BootContext, BootListener, ShutdownListener } from "./application.mjs";
+import { Application, BootContext, BootListener, BootValidator, ShutdownListener } from "./application.mjs";
 import { BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, BootSignal, BootSignalType, isBootSignal, sendBootSignal } from "./boot-signal.mjs";
 import { AppConfigurations } from "./application-config-types.mjs";

package/esm/cli/cli-commands.manager.mjs

@@ -7,6 +7,7 @@ import { bootstrap } from "../bootstrap.mjs";
 import { ConnectorLifecyclePhase } from "../connectors/types.mjs";
 import { connectorsManager } from "../connectors/connectors-manager.mjs";
 import { warlockConfigManager } from "../warlock-config/warlock-config.manager.mjs";
+import { registerConfiguredConnectors } from "../connectors/register-configured-connectors.mjs";
 import { filesOrchestrator } from "../dev-server/files-orchestrator.mjs";
 import { loadConfigFiles } from "../config/load-config-files.mjs";
 import { manifestManager } from "../manifest/manifest-manager.mjs";
@@ -19,11 +20,38 @@ import { colors } from "@mongez/copper";
 import { fileExistsAsync } from "@warlock.js/fs";
 
 //#region ../core/src/cli/cli-commands.manager.ts
+/**
+* Best-effort budget (ms) for draining stdout/stderr before a forced exit.
+* Bounded so a stuck stream can never hang the CLI.
+*/
+const EXIT_FLUSH_BUDGET = 500;
+/**
+* Exit with `code` once stdout/stderr have drained.
+*
+* `process.exit()` truncates writes still queued on a non-TTY stdout — a pipe,
+* a CI log — which is how the *reason* for a failure gets lost even when the
+* exit code is right. `exitCode` is set up front so that a natural exit (should
+* the drain outlive the process's remaining work) is non-zero too.
+*/
+function exitAfterFlush(code) {
+	process.exitCode = code;
+	const timer = setTimeout(() => process.exit(code), EXIT_FLUSH_BUDGET);
+	timer.unref?.();
+	let pending = 2;
+	const drained = () => {
+		if (--pending > 0) return;
+		clearTimeout(timer);
+		process.exit(code);
+	};
+	process.stdout.write("", drained);
+	process.stderr.write("", drained);
+}
 var CLICommandsManager = class {
 	constructor() {
 		this.commands = [];
 		this.commandsMap = /* @__PURE__ */ new Map();
 		this.aliasMap = /* @__PURE__ */ new Map();
+		this.fatalAsyncErrorReported = false;
 	}
 	/**
 	* Register the given commands
@@ -117,10 +145,10 @@ var CLICommandsManager = class {
 			process.exit(0);
 		}
 		const resolved = this.resolveCommandArgs(command);
-		await this.execute(command, {
+		if (await this.execute(command, {
 			options: resolved.options,
 			args: resolved.args
-		});
+		}) === "succeeded") exitAfterFlush(0);
 	}
 	/**
 	* Re-parse argv against the resolved command's declared options.
@@ -256,7 +284,10 @@ var CLICommandsManager = class {
 		return result;
 	}
 	/**
-	* Execute the given command
+	* Execute the given command and report how it ended.
+	*
+	* Returning the verdict — rather than exiting on success from in here — is
+	* what makes the awaited result trustworthy: see {@link CommandRunVerdict}.
 	*/
 	async execute(command, data) {
 		const startTime = Date.now();
@@ -274,24 +305,40 @@ var CLICommandsManager = class {
 			displayBootError(command.name, error);
 			process.exit(1);
 		}
+		this.captureFatalAsyncErrors(command);
 		try {
 			await command.execute(data);
-			if (!command.isPersistent) {
-				displayCommandSuccess(command.name, Date.now() - startTime);
-				process.exit(0);
-			}
+			if (command.isPersistent) return "running";
+			await new Promise((resolve) => setImmediate(resolve));
+			if (this.fatalAsyncErrorReported) return "failed";
+			displayCommandSuccess(command.name, Date.now() - startTime);
+			return "succeeded";
 		} catch (error) {
 			displayCommandError(command.name, error);
 			if (!command.isPersistent) process.exit(1);
+			return "failed";
 		}
 	}
+	captureFatalAsyncErrors(command) {
+		const onFatalAsyncError = (reason) => {
+			const error = reason instanceof Error ? reason : new Error(String(reason));
+			this.fatalAsyncErrorReported = true;
+			displayCommandError(command.name, error);
+			if (!command.isPersistent) exitAfterFlush(1);
+		};
+		process.on("unhandledRejection", onFatalAsyncError);
+		process.on("uncaughtException", onFatalAsyncError);
+	}
 	/**
 	* Load preloaders
 	*/
 	async loadPreloaders(command) {
 		const preloaders = command.commandPreload || {};
 		if (preloaders.runtimeStrategy) Application.setRuntimeStrategy(preloaders.runtimeStrategy);
-		if (preloaders.environemnt) Application.setEnvironment(preloaders.environemnt);
+		if (preloaders.environment) {
+			Application.setEnvironment(preloaders.environment);
+			if (process.env.NODE_ENV !== preloaders.environment) throw new Error(`Command "${command.name}" set NODE_ENV to "${preloaders.environment}", but it read back as "${process.env.NODE_ENV}". The environment did not take, and every decision made downstream of it — env file selection, bundler dep optimisation — would be wrong.`);
+		}
 		await loadEnvironmentFiles();
 		await warlockConfigManager.load();
 		if (preloaders.config || preloaders.bootstrap || preloaders.prestart) await filesOrchestrator.init();
@@ -303,8 +350,11 @@ var CLICommandsManager = class {
 		if (preloaders.prestart) {
 			if (await fileExistsAsync(appPath("prestart.ts"))) await filesOrchestrator.load("src/app/prestart.ts");
 		}
-		if (preloaders.connectors) if (preloaders.connectors === true) await connectorsManager.startPhase("early");
-		else await connectorsManager.start(preloaders.connectors);
+		if (preloaders.connectors) {
+			registerConfiguredConnectors();
+			if (preloaders.connectors === true) await connectorsManager.startPhase("early");
+			else await connectorsManager.start(preloaders.connectors);
+		}
 	}
 };