@warlock.js/core 5.31.0 → 5.33.0

package/CHANGELOG.md

@@ -6,6 +6,67 @@ 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.**
 
+## 5.33.0 - 2026-10-19
+
+### Added
+
+- `oxc-toolchain`, a 5.33.0 `warlock upgrade` codemod, migrates generated configs, package scripts/dependencies, editor settings and literal dev health switches to Oxlint/Oxfmt. Customized files are retained with file:line review guidance; additions and deletions honor `--dry-run` and `--json`.
+
+### Changed
+
+- **BREAKING** ESLint no longer starts from config detection alone in the dev server or `warlock check`. TypeScript and configured Oxlint remain the default health checkers; `check` defaults to Oxlint.
+
+### Deprecated
+
+- ESLint/Prettier support is removed in 5.34.0. Explicit ESLint opt-ins emit one deprecation warning per process on stderr with migration instructions.
+
+### Upgrading
+
+- Run `npx warlock upgrade --from 5.32 --to 5.33.0` (preview with `--dry-run`), install dependencies and review customized configs. To retain legacy lint checks temporarily, set `devServer.healthCheckers.eslint: true` and select `warlock check --lint eslint`. See the upgrade skill's "5.32 to 5.33" section.
+- `broadcastSocketEvent(event, ...args)` dispatches through the existing socket connector's adapter and returns `false` when no socket server is available. Web page-cache invalidations use this path to notify clients across processes configured with a shared adapter.
+- Add app-scoped `secrets.get/set/remove/has` and `environmentName`, also exported from `@warlock.js/core/secrets`, with lazy optional OS keychain storage, read-only scoped environment lookup, authenticated encrypted owner-only files, typed errors, logger masking and explicit memory backends.
+- Add `secretsFake` to the default test fakes, with isolated memory storage and assertions that never reveal credentials; opt out with `tests.fakes: { secrets: false }`.
+- `warlock ai measure --model <id> [--tools <module>] [--system <file>] [--skills <dir>] [--json]` lazily loads AI and reports per-part input tokens and priced USD. Supports provider-qualified IDs, configured model modules, and JSON output without app bootstrap.
+- Optional `warlock pm2 init` generates `ecosystem.config.cjs` from app/build config with a `<project>-<app>-<env>` name, readiness URL, `wait_ready`, startup timeout and a kill timeout matched to `app.shutdownTimeout`. PM2 stays outside core's dependencies. Fork mode is the default; cluster mode requires a socket adapter and WebSocket-only transports when sockets are configured.
+- `warlock pm2 reload [--id <pm2-id>]` verifies the exact app name, working directory and bundle path before reloading numeric PM2 ids sequentially. Document rolling reload limits, shared-server stops by PM2 id and logger output formatting.
+
+### Changed
+
+- Completed application boot now sends PM2's `"ready"` IPC message without disconnecting its channel; the existing `warlock start` readiness protocol remains supported. Cluster workers skip the exclusive port preflight so they can share their primary's listener during rolling reloads.
+
+### Fixed
+
+- Type the socket connector’s raw HTTP(S) server across asynchronous listener startup; keep native-keyring test doubles declaration-safe and cover the documented `check --lint` option.
+- Socket-only connector boot awaits its listener and rejects bind failures before application readiness can be announced.
+
+### Upgrading
+
+- Rebuild production bundles to include PM2 readiness before using `wait_ready`. Generate with the target `NODE_ENV`, review the ecosystem file, and start the bundle directly under PM2. Cluster sockets require `socket.adapter`, `socket.options.transports: ["websocket"]` and WebSocket-only clients; polling deployments need sticky routing to individual listeners. Fork reloads can interrupt traffic.
+- Add `warlock add process` with exact family dependency, typed supervisor config, application recovery/shutdown hooks, optional devtools registration, next steps and idempotent file generation.
+
+## 5.32.0 - 2026-10-18
+
+### Added
+
+- `warlock issue [--type bug|feature] [--title "..."] [--json]` collects installed environment details and a static config summary without booting the app, then prints a bounded pre-filled framework issue URL; it never submits anything. Add bug/feature issue forms and the `report-framework-issue.md` agent topic with minimal-repro, privacy, duplicate-search and user-consent guidance.
+
+### Security
+
+- Upgrade esbuild to ^0.28.2, past the Windows development-server advisory [GHSA-g7r4-m6w7-qqqr](https://github.com/advisories/GHSA-g7r4-m6w7-qqqr) (patched in 0.28.1).
+
+### Changed
+
+- Clarify the upgrade skill: new scaffolds default to Oxlint/Oxfmt and TypeScript 7.0.2; explicit ESLint mode stays on TypeScript 6.0.3 to satisfy typescript-eslint, with deprecation planned for 5.33 and removal for 5.34.
+
+- Verify generated web stubs with the scaffold’s TypeScript-independent Prettier import sorter, including an explicit no-plugin negative control and decorator parsing; align the contact controller stub’s inline type-specifier order.
+- **BREAKING:** pin `typescript` to 7.0.2, whose `tsc` command uses the native Go compiler. Apps must remove `baseUrl`, rebase `paths`, replace `moduleResolution: "node"` / `"node10"`, and declare ambient Node types explicitly.
+- Preserve incremental CLI checks and changed-file filtering; reuse a native compiler session for per-file development diagnostics and close it on shutdown.
+- Parse imports, configuration, translation keys, model/resource typings, convention checks, page discovery and doctor migrations with OXC instead of the removed JavaScript compiler API.
+
+### Fixed
+
+- Fix source development workers on Node.js 24 failing to load Node builtins through native dependencies, restoring background TypeScript health checks.
+
 ## 5.31.0 - 2026-10-18
 
 ### Security

package/esm/application/app.d.mts

@@ -1,8 +1,8 @@
 import { Router } from "../router/router.mjs";
+import "../router/index.mjs";
 import { DataSource } from "@warlock.js/cascade";
 import { FastifyInstance } from "fastify";
 import { Server } from "socket.io";
-
 //#region ../../packages/core/src/application/app.d.ts
 type RuntimeApplication = {
   socket: Server | undefined;
@@ -10,7 +10,7 @@ type RuntimeApplication = {
   router: Router;
   database: DataSource | undefined;
 };
-declare const app: RuntimeApplication;
+export declare const app: RuntimeApplication;
 //#endregion
-export { app };
+export {};
 //# sourceMappingURL=app.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"app.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/app.ts"],"mappings":";;;;;;KAMK,kBAAA;EACH,MAAA,EAAQ,MAAA;EACR,IAAA,EAAM,eAAA;EACN,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,UAAA;AAAA;AAAA,cAGC,GAAA,EAAK,kBAkCjB"}
+{"version":3,"file":"app.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/app.ts"],"mappings":";;;;;;KAMK;EACH,QAAQ;EACR,MAAM;EACN,QAAQ;EACR,UAAU;;qBAGC,KAAK"}

package/esm/application/application-config-types.d.mts

@@ -1,9 +1,17 @@
 //#region ../../packages/core/src/application/application-config-types.d.ts
-type AppConfigurations = {
+export type AppConfigurations = {
   /**
    * App name
    */
   appName?: string;
+  /**
+   * Overall connector shutdown budget in milliseconds. PM2 config generation
+   * uses the same value for `kill_timeout`. Allow enough time for HTTP draining
+   * and the remaining connectors; tune `http.gracefulShutdown.timeout` below it.
+   *
+   * @default 10000
+   */
+  shutdownTimeout?: number;
   /**
    * Default locale code
    *
@@ -35,5 +43,4 @@ type AppConfigurations = {
   localeCodes?: string[];
 };
 //#endregion
-export { AppConfigurations };
 //# sourceMappingURL=application-config-types.d.mts.map

package/esm/application/application-config-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"application-config-types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/application-config-types.ts"],"mappings":";KAAY,iBAAA;EAAA;;;EAIV,OAAA;EAAA;;;;;EAMA,UAAA;EAuBW;AAAA;;;;EAjBX,OAAA;;;;;;;;;EASA,SAAA;;;;EAIA,QAAA;;;;EAIA,WAAA;AAAA"}
+{"version":3,"file":"application-config-types.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/application-config-types.ts"],"mappings":";YAAY;;;;EAIV;;;;;;;;EAQA;;;;;;EAMA;;;;;;EAMA;;;;;;;;;EASA;;;;EAIA;;;;EAIA"}

package/esm/application/application.d.mts

@@ -1,6 +1,5 @@
 import { Environment, RuntimeStrategy } from "../utils/environment.mjs";
 import { AppRole } from "./roles.mjs";
-
 //#region ../../packages/core/src/application/application.d.ts
 /**
  * Snapshot of the global facts known the moment the application finished
@@ -8,7 +7,7 @@ import { AppRole } from "./roles.mjs";
  * (locales, events, main, routes) are loaded. Passed to every
  * `Application.onceBooted` listener and resolved from `Application.whenBooted`.
  */
-type BootContext = {
+export type BootContext = {
   environment: Environment;
   runtimeStrategy: RuntimeStrategy;
   /**
@@ -22,7 +21,7 @@ type BootContext = {
  * rejection is caught and logged so a single listener can never break boot or
  * the other listeners.
  */
-type BootListener = (context: BootContext) => void | Promise<void>;
+export 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.
@@ -33,14 +32,14 @@ type BootListener = (context: BootContext) => void | Promise<void>;
  * 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>;
+export 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
  * resources cleanly. May be async — its rejection is caught and logged.
  */
-type ShutdownListener = () => void | Promise<void>;
-declare class Application {
+export type ShutdownListener = () => void | Promise<void>;
+export declare class Application {
   /**
    * Project start time regarding the process start time
    */
@@ -294,5 +293,4 @@ declare class Application {
   static get publicPath(): string;
 }
 //#endregion
-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":["../../../../../../../../packages/core/src/application/application.ts"],"mappings":";;;;;;AAkBA;;;;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;EA4OY;;;EAAA,OAvO9B,eAAA,EAAiB,eAAA;EAqVG;;;EAAA,eAhVnB,MAAA;EAkYa;;;EAAA,eA7Xb,WAAA;EAfiB;;;;EAAA,eAqBjB,aAAA;EAAA;;;;;EAAA,eAOA,SAAA;EA8BG;;;;EAAA,eAxBH,cAAA;EAiDD;;;;;;EAAA,eAzCC,UAAA;EA0EqB;;;;EAAA,eApErB,YAAA;EA8JD;;;EAAA,eAzJC,iBAAA;EAuL6B;;;EAAA,WAlL1B,OAAA;EAiOO;;;EAAA,OA1NX,kBAAA,CAAmB,QAAA,EAAU,eAAA;EA2QzB;;;;;EAAA,WAlQA,QAAA;EAuRA;;;;;EAAA,OA9QJ,aAAA,CAAc,IAAA;EA6SV;;;;;;;;;;;;AAsDU;;EAtDV,OA3RJ,UAAA,CAAW,QAAA,EAAU,YAAA;;;;;SAerB,UAAA,IAAc,OAAA,CAAQ,WAAA;;;;;;;;;;;;;;;SAwBtB,UAAA,CAAW,OAAA,EAAS,WAAA;;;;;iBAgCb,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;;;;;;aASA,KAAA,IAAS,WAAA,CAAY,OAAA;;;;;aAQrB,KAAA,IAAS,WAAA;;;;;;;;;SAYb,OAAA,CAAQ,IAAA,EAAM,OAAA;;;;aAOV,QAAA;;;;aAOA,OAAA;;;;aAOA,OAAA;;;;aAOA,WAAA;;;;aAOA,WAAA;;;;aAOA,UAAA;AAAA"}
+{"version":3,"file":"application.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/application.ts"],"mappings":";;;;;;;;;YAkBY;EACV,aAAa;EACb,iBAAiB;;;;;EAKjB;;;;;;;YAQU,gBAAgB,SAAS,uBAAuB;;;;;;;;;;;YAYhD,6BAA6B;;;;;;YAkB7B,gCAAgC;qBAE/B;;;;kBAIY,WAAS;;;;SAKlB,iBAAiB;;;;iBAKhB;;;;iBAKA;;;;;iBAMA;;;;;;iBAOA;;;;;iBAMA;;;;;;;iBAQA;;;;;iBAMA;;;;iBAKA;;;;aAKG;;;;SAOJ,mBAAmB,UAAU;;;;;;aASzB;;;;;;SASJ,cAAc;;;;;;;;;;;;;;;SAkBd,WAAW,UAAU;;;;;SAerB,cAAc,QAAQ;;;;;;;;;;;;;;;SAwBtB,WAAW,SAAS;;;;;iBAgCb;;;;;;;;;;;;;;;;;;;;;;;;SAkCP,eAAe,WAAW;;;;;;;;;;;;;;;;;;SA8BpB,wBAAwB;;;;;;aAgC1B;;;;;;;;;;;;SAeJ,WAAW,UAAU;;;;;;;;;;SAmBf,oBAAoB;;;;;iBAmBnB;;;;aAWH;;;;aAOA,eAAe;;;;SAOnB,eAAe,KAAK;;;;aAOhB;;;;aAOA;;;;aAOA;;;;;;aASA,SAAS,YAAY;;;;;aAQrB,SAAS;;;;;;;;;SAYb,QAAQ,MAAM;;;;aAOV;;;;aAOA;;;;aAOA;;;;aAOA;;;;aAOA;;;;aAOA"}

package/esm/application/application.mjs

@@ -185,7 +185,9 @@ var Application = class {
 		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 });
+			const name = validator.name || "<anonymous>";
+			const cause = error instanceof Error ? error.message : String(error);
+			throw new ErrorWithCause(`Startup validator "${name}" rejected boot: ${cause}. Fix the condition it checks, or remove the validator if it no longer applies — boot cannot proceed while it fails.`, { cause: error });
 		}
 	}
 	/**

package/esm/application/application.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"application.mjs","names":[],"sources":["../../../../../../../../packages/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\";\nimport { getRoles, getSites, hasRole, type AppRole } from \"./roles\";\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      roles: [...this.roles],\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   * The roles this process serves — `WARLOCK_ROLES`, resolved once at\n   * bootstrap. Every role is on when the variable is absent (plain `warlock\n   * start`, `warlock dev`, and tests).\n   */\n  public static get roles(): ReadonlySet<AppRole> {\n    return getRoles();\n  }\n\n  /**\n   * The site keys this process installs pages for — `WARLOCK_SITES`,\n   * resolved once at bootstrap. `undefined` means every site.\n   */\n  public static get sites(): ReadonlySet<string> | undefined {\n    return getSites();\n  }\n\n  /**\n   * Whether this process serves the given role.\n   *\n   * @example\n   * if (Application.hasRole(\"worker\")) {\n   *   scheduler.start();\n   * }\n   */\n  public static hasRole(role: AppRole): boolean {\n    return hasRole(role);\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":["../../../../../../../../packages/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\";\nimport { getRoles, getSites, hasRole, type AppRole } from \"./roles\";\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      roles: [...this.roles],\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   * The roles this process serves — `WARLOCK_ROLES`, resolved once at\n   * bootstrap. Every role is on when the variable is absent (plain `warlock\n   * start`, `warlock dev`, and tests).\n   */\n  public static get roles(): ReadonlySet<AppRole> {\n    return getRoles();\n  }\n\n  /**\n   * The site keys this process installs pages for — `WARLOCK_SITES`,\n   * resolved once at bootstrap. `undefined` means every site.\n   */\n  public static get sites(): ReadonlySet<string> | undefined {\n    return getSites();\n  }\n\n  /**\n   * Whether this process serves the given role.\n   *\n   * @example\n   * if (Application.hasRole(\"worker\")) {\n   *   scheduler.start();\n   * }\n   */\n  public static hasRole(role: AppRole): boolean {\n    return hasRole(role);\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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"}

package/esm/application/boot-signal.d.mts

@@ -1,12 +1,11 @@
 import { Environment, RuntimeStrategy } from "../utils/environment.mjs";
-
 //#region ../../packages/core/src/application/boot-signal.d.ts
 /**
  * The only message type the boot channel carries today. Named rather than
  * inlined because both the sender (`sendBootSignal`) and the receiver
  * (`warlock start`) must agree on the exact literal.
  */
-type BootSignalType = "warlock:ready";
+export type BootSignalType = "warlock:ready";
 /**
  * Schema version of {@link BootSignal}.
  *
@@ -14,7 +13,7 @@ type BootSignalType = "warlock:ready";
  * a shipped wire format without a flag day, and this one has to be able to
  * evolve while older CLIs are still supervising newer bundles.
  */
-declare const BOOT_SIGNAL_VERSION = 1;
+export declare const BOOT_SIGNAL_VERSION = 1;
 /**
  * What a booted child process tells its supervising parent over the IPC
  * channel `warlock start` opens for it.
@@ -23,38 +22,42 @@ declare const BOOT_SIGNAL_VERSION = 1;
  * success banner **only** when this arrives, so anything watching that banner
  * (a CI gate, a process supervisor) transitively depends on it.
  */
-type BootSignal = {
+export type BootSignal = {
   type: BootSignalType;
-  version: number; /** The application process, so a supervisor can address it directly. */
-  pid: number; /** When the boot completed, ISO-8601. */
+  version: number;
+  /** The application process, so a supervisor can address it directly. */
+  pid: number;
+  /** When the boot completed, ISO-8601. */
   at: string;
   environment: Environment;
   runtimeStrategy: RuntimeStrategy;
-  bootDurationMs?: number; /** The bound http port, absent for an app with no http connector. */
-  port?: number; /** The roles this process serves — see `Application.roles`. */
+  bootDurationMs?: number;
+  /** The bound http port, absent for an app with no http connector. */
+  port?: number;
+  /** The roles this process serves — see `Application.roles`. */
   roles: string[];
 };
 /**
  * Environment flag `warlock start` sets on the process it supervises.
  *
  * An IPC channel alone is NOT proof that the parent speaks this protocol —
- * pm2, a vitest worker fork, and any custom supervisor all hand their child a
+ * a vitest worker fork or a custom supervisor may hand their child a
  * channel they use for their own messages. Writing to one of those, and then
  * closing it, corrupts someone else's protocol and can kill the process. The
  * flag is the handshake: only a parent that set it gets signalled.
  */
-declare const BOOT_SIGNAL_ENV_KEY = "WARLOCK_BOOT_SIGNAL";
+export declare const BOOT_SIGNAL_ENV_KEY = "WARLOCK_BOOT_SIGNAL";
 /**
  * Report a completed boot to the parent process, if one is supervising.
  *
- * Two conditions must both hold: the process was spawned with an `ipc` stdio
- * channel (`process.send` exists), and the parent identified itself with
- * {@link BOOT_SIGNAL_ENV_KEY}. A bundle run directly (`node app.mjs`, a Docker
- * `CMD`) or under a foreign supervisor is a no-op, so the signal never changes
- * how a standalone process behaves and never touches a channel we don't own.
+ * The versioned signal requires an IPC channel (`process.send` exists) and
+ * the parent's {@link BOOT_SIGNAL_ENV_KEY} handshake. With IPC and `pm_id`,
+ * PM2 instead receives its documented `"ready"` message and keeps its channel
+ * open for logs and worker coordination.
+ * Standalone bundles and unrecognized supervisors remain silent.
  *
- * The channel is closed as soon as the message is flushed. An open IPC channel
- * holds a `ref` on the child's event loop, which would keep a finished or
+ * The `warlock start` channel is closed as soon as its message is flushed.
+ * An open IPC channel holds a `ref` on the child's event loop, keeping a finished or
  * wedged process alive and indistinguishable from a healthy server — the exact
  * confusion this signal exists to remove. One message, then disconnect.
  *
@@ -62,7 +65,7 @@ declare const BOOT_SIGNAL_ENV_KEY = "WARLOCK_BOOT_SIGNAL";
  * detached or died, and a supervisor going away must never take down a
  * healthy application.
  */
-declare function sendBootSignal(signal: BootSignal): void;
+export declare function sendBootSignal(signal: BootSignal): void;
 /**
  * Narrow an arbitrary IPC payload to a {@link BootSignal}.
  *
@@ -72,7 +75,6 @@ declare function sendBootSignal(signal: BootSignal): void;
  * accepted — readiness is readiness, and refusing it would make an old
  * supervisor report a healthy app as failed.
  */
-declare function isBootSignal(message: unknown): message is BootSignal;
+export declare function isBootSignal(message: unknown): message is BootSignal;
 //#endregion
-export { BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, BootSignal, BootSignalType, isBootSignal, sendBootSignal };
 //# sourceMappingURL=boot-signal.d.mts.map

package/esm/application/boot-signal.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"boot-signal.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/boot-signal.ts"],"mappings":";;;;;AAOA;;;KAAY,cAAA;AAAc;AAS1B;;;;AAAgC;AAUhC;AAnB0B,cASb,mBAAA;;;;;;;;;KAUD,UAAA;EACV,IAAA,EAAM,cAAA;EACN,OAAA,UAKA;EAHA,GAAA,UAIA;EAFA,EAAA;EACA,WAAA,EAAa,WAAA;EACb,eAAA,EAAiB,eAAA;EACjB,cAAA,WAIK;EAFL,IAAA,WAcW;EAZX,KAAA;AAAA;;AAY8B;AAoBhC;;;;AAAiD;AA4BjD;;cAhDa,mBAAA;;;;;;AAgDwD;;;;;;;;;;;;;iBA5BrD,cAAA,CAAe,MAAkB,EAAV,UAAU;;;;;;;;;;iBA4BjC,YAAA,CAAa,OAAA,YAAmB,OAAA,IAAW,UAAU"}
+{"version":3,"file":"boot-signal.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/boot-signal.ts"],"mappings":";;;;;;;YAOY;;;;;;;;qBASC;;;;;;;;;YAUD;EACV,MAAM;EACN;;EAEA;;EAEA;EACA,aAAa;EACb,iBAAiB;EACjB;;EAEA;;EAEA;;;;;;;;;;;qBAYW;;;;;;;;;;;;;;;;;;;wBAoBG,eAAe,QAAQ;;;;;;;;;;wBA2CvB,aAAa,mBAAmB,WAAW"}

package/esm/application/boot-signal.mjs

@@ -11,7 +11,7 @@ const BOOT_SIGNAL_VERSION = 1;
 * Environment flag `warlock start` sets on the process it supervises.
 *
 * An IPC channel alone is NOT proof that the parent speaks this protocol —
-* pm2, a vitest worker fork, and any custom supervisor all hand their child a
+* a vitest worker fork or a custom supervisor may hand their child a
 * channel they use for their own messages. Writing to one of those, and then
 * closing it, corrupts someone else's protocol and can kill the process. The
 * flag is the handshake: only a parent that set it gets signalled.
@@ -20,14 +20,14 @@ const BOOT_SIGNAL_ENV_KEY = "WARLOCK_BOOT_SIGNAL";
 /**
 * Report a completed boot to the parent process, if one is supervising.
 *
-* Two conditions must both hold: the process was spawned with an `ipc` stdio
-* channel (`process.send` exists), and the parent identified itself with
-* {@link BOOT_SIGNAL_ENV_KEY}. A bundle run directly (`node app.mjs`, a Docker
-* `CMD`) or under a foreign supervisor is a no-op, so the signal never changes
-* how a standalone process behaves and never touches a channel we don't own.
+* The versioned signal requires an IPC channel (`process.send` exists) and
+* the parent's {@link BOOT_SIGNAL_ENV_KEY} handshake. With IPC and `pm_id`,
+* PM2 instead receives its documented `"ready"` message and keeps its channel
+* open for logs and worker coordination.
+* Standalone bundles and unrecognized supervisors remain silent.
 *
-* The channel is closed as soon as the message is flushed. An open IPC channel
-* holds a `ref` on the child's event loop, which would keep a finished or
+* The `warlock start` channel is closed as soon as its message is flushed.
+* An open IPC channel holds a `ref` on the child's event loop, keeping a finished or
 * wedged process alive and indistinguishable from a healthy server — the exact
 * confusion this signal exists to remove. One message, then disconnect.
 *
@@ -36,7 +36,13 @@ const BOOT_SIGNAL_ENV_KEY = "WARLOCK_BOOT_SIGNAL";
 * healthy application.
 */
 function sendBootSignal(signal) {
-	if (typeof process.send !== "function" || process.env["WARLOCK_BOOT_SIGNAL"] !== "1") return;
+	if (typeof process.send !== "function") return;
+	if (process.env["WARLOCK_BOOT_SIGNAL"] !== "1") {
+		if (process.env.pm_id !== void 0) try {
+			process.send("ready", void 0, void 0, () => {});
+		} catch {}
+		return;
+	}
 	delete process.env[BOOT_SIGNAL_ENV_KEY];
 	try {
 		process.send(signal, void 0, void 0, () => {

package/esm/application/boot-signal.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"boot-signal.mjs","names":[],"sources":["../../../../../../../../packages/core/src/application/boot-signal.ts"],"sourcesContent":["import type { Environment, RuntimeStrategy } from \"../utils/environment\";\n\n/**\n * The only message type the boot channel carries today. Named rather than\n * inlined because both the sender (`sendBootSignal`) and the receiver\n * (`warlock start`) must agree on the exact literal.\n */\nexport type BootSignalType = \"warlock:ready\";\n\n/**\n * Schema version of {@link BootSignal}.\n *\n * Present from the first release on purpose: a version field cannot be added to\n * a shipped wire format without a flag day, and this one has to be able to\n * evolve while older CLIs are still supervising newer bundles.\n */\nexport const BOOT_SIGNAL_VERSION = 1;\n\n/**\n * What a booted child process tells its supervising parent over the IPC\n * channel `warlock start` opens for it.\n *\n * This is a wire contract, not an internal detail: `warlock start` prints its\n * success banner **only** when this arrives, so anything watching that banner\n * (a CI gate, a process supervisor) transitively depends on it.\n */\nexport type BootSignal = {\n  type: BootSignalType;\n  version: number;\n  /** The application process, so a supervisor can address it directly. */\n  pid: number;\n  /** When the boot completed, ISO-8601. */\n  at: string;\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  bootDurationMs?: number;\n  /** The bound http port, absent for an app with no http connector. */\n  port?: number;\n  /** The roles this process serves — see `Application.roles`. */\n  roles: string[];\n};\n\n/**\n * Environment flag `warlock start` sets on the process it supervises.\n *\n * An IPC channel alone is NOT proof that the parent speaks this protocol —\n * pm2, a vitest worker fork, and any custom supervisor all hand their child a\n * channel they use for their own messages. Writing to one of those, and then\n * closing it, corrupts someone else's protocol and can kill the process. The\n * flag is the handshake: only a parent that set it gets signalled.\n */\nexport const BOOT_SIGNAL_ENV_KEY = \"WARLOCK_BOOT_SIGNAL\";\n\n/**\n * Report a completed boot to the parent process, if one is supervising.\n *\n * Two conditions must both hold: the process was spawned with an `ipc` stdio\n * channel (`process.send` exists), and the parent identified itself with\n * {@link BOOT_SIGNAL_ENV_KEY}. A bundle run directly (`node app.mjs`, a Docker\n * `CMD`) or under a foreign supervisor is a no-op, so the signal never changes\n * how a standalone process behaves and never touches a channel we don't own.\n *\n * The channel is closed as soon as the message is flushed. An open IPC channel\n * holds a `ref` on the child's event loop, which would keep a finished or\n * wedged process alive and indistinguishable from a healthy server — the exact\n * confusion this signal exists to remove. One message, then disconnect.\n *\n * Failure to send is deliberately swallowed: the parent may have already\n * detached or died, and a supervisor going away must never take down a\n * healthy application.\n */\nexport function sendBootSignal(signal: BootSignal): void {\n  if (typeof process.send !== \"function\" || process.env[BOOT_SIGNAL_ENV_KEY] !== \"1\") {\n    return;\n  }\n\n  // Consumed here so it cannot be inherited by anything this app itself spawns\n  // and make a grandchild report readiness on a channel meant for someone else.\n  delete process.env[BOOT_SIGNAL_ENV_KEY];\n\n  try {\n    process.send(signal, undefined, undefined, () => {\n      process.disconnect?.();\n    });\n  } catch {\n    // The channel closed between the check and the write — the app is up\n    // regardless, and there is no longer anyone to tell.\n  }\n}\n\n/**\n * Narrow an arbitrary IPC payload to a {@link BootSignal}.\n *\n * The parent receives whatever the child chooses to send, so the message is\n * untrusted input and is validated before it is allowed to flip the parent's\n * \"the server is up\" state. A *newer* version than this CLI knows is still\n * accepted — readiness is readiness, and refusing it would make an old\n * supervisor report a healthy app as failed.\n */\nexport function isBootSignal(message: unknown): message is BootSignal {\n  if (typeof message !== \"object\" || message === null) {\n    return false;\n  }\n\n  const candidate = message as { type?: unknown; version?: unknown };\n\n  return candidate.type === \"warlock:ready\" && typeof candidate.version === \"number\";\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,sBAAsB;;;;;;;;;;AAmCnC,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;AAoBnC,SAAgB,eAAe,QAA0B;CACvD,IAAI,OAAO,QAAQ,SAAS,cAAc,QAAQ,+BAA6B,KAC7E;CAKF,OAAO,QAAQ,IAAI;CAEnB,IAAI;EACF,QAAQ,KAAK,QAAQ,QAAW,cAAiB;GAC/C,QAAQ,aAAa;EACvB,CAAC;CACH,QAAQ,CAGR;AACF;;;;;;;;;;AAWA,SAAgB,aAAa,SAAyC;CACpE,IAAI,OAAO,YAAY,YAAY,YAAY,MAC7C,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,UAAU,SAAS,mBAAmB,OAAO,UAAU,YAAY;AAC5E"}
+{"version":3,"file":"boot-signal.mjs","names":[],"sources":["../../../../../../../../packages/core/src/application/boot-signal.ts"],"sourcesContent":["import type { Environment, RuntimeStrategy } from \"../utils/environment\";\n\n/**\n * The only message type the boot channel carries today. Named rather than\n * inlined because both the sender (`sendBootSignal`) and the receiver\n * (`warlock start`) must agree on the exact literal.\n */\nexport type BootSignalType = \"warlock:ready\";\n\n/**\n * Schema version of {@link BootSignal}.\n *\n * Present from the first release on purpose: a version field cannot be added to\n * a shipped wire format without a flag day, and this one has to be able to\n * evolve while older CLIs are still supervising newer bundles.\n */\nexport const BOOT_SIGNAL_VERSION = 1;\n\n/**\n * What a booted child process tells its supervising parent over the IPC\n * channel `warlock start` opens for it.\n *\n * This is a wire contract, not an internal detail: `warlock start` prints its\n * success banner **only** when this arrives, so anything watching that banner\n * (a CI gate, a process supervisor) transitively depends on it.\n */\nexport type BootSignal = {\n  type: BootSignalType;\n  version: number;\n  /** The application process, so a supervisor can address it directly. */\n  pid: number;\n  /** When the boot completed, ISO-8601. */\n  at: string;\n  environment: Environment;\n  runtimeStrategy: RuntimeStrategy;\n  bootDurationMs?: number;\n  /** The bound http port, absent for an app with no http connector. */\n  port?: number;\n  /** The roles this process serves — see `Application.roles`. */\n  roles: string[];\n};\n\n/**\n * Environment flag `warlock start` sets on the process it supervises.\n *\n * An IPC channel alone is NOT proof that the parent speaks this protocol —\n * a vitest worker fork or a custom supervisor may hand their child a\n * channel they use for their own messages. Writing to one of those, and then\n * closing it, corrupts someone else's protocol and can kill the process. The\n * flag is the handshake: only a parent that set it gets signalled.\n */\nexport const BOOT_SIGNAL_ENV_KEY = \"WARLOCK_BOOT_SIGNAL\";\n\n/**\n * Report a completed boot to the parent process, if one is supervising.\n *\n * The versioned signal requires an IPC channel (`process.send` exists) and\n * the parent's {@link BOOT_SIGNAL_ENV_KEY} handshake. With IPC and `pm_id`,\n * PM2 instead receives its documented `\"ready\"` message and keeps its channel\n * open for logs and worker coordination.\n * Standalone bundles and unrecognized supervisors remain silent.\n *\n * The `warlock start` channel is closed as soon as its message is flushed.\n * An open IPC channel holds a `ref` on the child's event loop, keeping a finished or\n * wedged process alive and indistinguishable from a healthy server — the exact\n * confusion this signal exists to remove. One message, then disconnect.\n *\n * Failure to send is deliberately swallowed: the parent may have already\n * detached or died, and a supervisor going away must never take down a\n * healthy application.\n */\nexport function sendBootSignal(signal: BootSignal): void {\n  if (typeof process.send !== \"function\") {\n    return;\n  }\n\n  // PM2 injects pm_id (including \"0\") in both fork and cluster mode. Its\n  // ProcessContainer uses this channel for logs too: never disconnect it.\n  // https://github.com/Unitech/pm2/blob/master/lib/ProcessContainer.js\n  // https://pm2.keymetrics.io/docs/usage/signals-clean-restart/\n  if (process.env[BOOT_SIGNAL_ENV_KEY] !== \"1\") {\n    if (process.env.pm_id !== undefined) {\n      try {\n        process.send(\"ready\", undefined, undefined, () => {});\n      } catch {\n        // A detached supervisor must not take down an already booted app.\n      }\n    }\n    return;\n  }\n\n  // Consumed here so it cannot be inherited by anything this app itself spawns\n  // and make a grandchild report readiness on a channel meant for someone else.\n  delete process.env[BOOT_SIGNAL_ENV_KEY];\n\n  try {\n    process.send(signal, undefined, undefined, () => {\n      process.disconnect?.();\n    });\n  } catch {\n    // The channel closed between the check and the write — the app is up\n    // regardless, and there is no longer anyone to tell.\n  }\n}\n\n/**\n * Narrow an arbitrary IPC payload to a {@link BootSignal}.\n *\n * The parent receives whatever the child chooses to send, so the message is\n * untrusted input and is validated before it is allowed to flip the parent's\n * \"the server is up\" state. A *newer* version than this CLI knows is still\n * accepted — readiness is readiness, and refusing it would make an old\n * supervisor report a healthy app as failed.\n */\nexport function isBootSignal(message: unknown): message is BootSignal {\n  if (typeof message !== \"object\" || message === null) {\n    return false;\n  }\n\n  const candidate = message as { type?: unknown; version?: unknown };\n\n  return candidate.type === \"warlock:ready\" && typeof candidate.version === \"number\";\n}\n"],"mappings":";;;;;;;;AAgBA,MAAa,sBAAsB;;;;;;;;;;AAmCnC,MAAa,sBAAsB;;;;;;;;;;;;;;;;;;;AAoBnC,SAAgB,eAAe,QAA0B;CACvD,IAAI,OAAO,QAAQ,SAAS,YAC1B;CAOF,IAAI,QAAQ,+BAA6B,KAAK;EAC5C,IAAI,QAAQ,IAAI,UAAU,QACxB,IAAI;GACF,QAAQ,KAAK,SAAS,QAAW,cAAiB,CAAC,CAAC;EACtD,QAAQ,CAER;EAEF;CACF;CAIA,OAAO,QAAQ,IAAI;CAEnB,IAAI;EACF,QAAQ,KAAK,QAAQ,QAAW,cAAiB;GAC/C,QAAQ,aAAa;EACvB,CAAC;CACH,QAAQ,CAGR;AACF;;;;;;;;;;AAWA,SAAgB,aAAa,SAAyC;CACpE,IAAI,OAAO,YAAY,YAAY,YAAY,MAC7C,OAAO;CAGT,MAAM,YAAY;CAElB,OAAO,UAAU,SAAS,mBAAmB,OAAO,UAAU,YAAY;AAC5E"}

package/esm/application/index.d.mts

@@ -3,4 +3,5 @@ import { APP_ROLES, AppRole, assertSitesRequireWebRole, getRoles, getSites, hasR
 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";
-import { getPublicUrl } from "./public-url.mjs";
+import { getPublicUrl } from "./public-url.mjs";
+export { APP_ROLES, AppConfigurations, AppRole, Application, BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, BootContext, BootListener, BootSignal, BootSignalType, BootValidator, ShutdownListener, app, assertSitesRequireWebRole, getPublicUrl, getRoles, getSites, hasRole, isBootSignal, parseRoles, parseSites, resetRolesCacheForTests, sendBootSignal, servesHttp };

package/esm/application/index.mjs

@@ -4,4 +4,4 @@ import { Application } from "./application.mjs";
 import { app } from "./app.mjs";
 import { getPublicUrl } from "./public-url.mjs";
 
-export {  };
+export { APP_ROLES, Application, BOOT_SIGNAL_ENV_KEY, BOOT_SIGNAL_VERSION, app, assertSitesRequireWebRole, getPublicUrl, getRoles, getSites, hasRole, isBootSignal, parseRoles, parseSites, resetRolesCacheForTests, sendBootSignal, servesHttp };

package/esm/application/public-url.d.mts

@@ -14,7 +14,6 @@
  * value (e.g. the sitemap route, at boot) is responsible for failing loudly
  * itself, naming both `app.publicUrl` and `PUBLIC_APP_URL`.
  */
-declare function getPublicUrl(): string | undefined;
+export declare function getPublicUrl(): string | undefined;
 //#endregion
-export { getPublicUrl };
 //# sourceMappingURL=public-url.d.mts.map

package/esm/application/public-url.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"public-url.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/public-url.ts"],"mappings":";;AAiBA;;;;AAA4B;;;;;;;;;;iBAAZ,YAAA"}
+{"version":3,"file":"public-url.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/public-url.ts"],"mappings":";;;;;;;;;;;;;;;;wBAiBgB"}

package/esm/application/roles.d.mts

@@ -4,12 +4,12 @@
  * `api` and `web` both bind the http port (§`servesHttp`); `worker` never
  * does — it exists to run queue workers, the scheduler and `worker.ts`.
  */
-declare const APP_ROLES: readonly ["api", "web", "worker"];
+export declare const APP_ROLES: readonly ["api", "web", "worker"];
 /**
  * One of {@link APP_ROLES}. What `Application.hasRole` checks and what
  * `warlock start --role` accepts, comma-separated.
  */
-type AppRole = (typeof APP_ROLES)[number];
+export type AppRole = (typeof APP_ROLES)[number];
 /**
  * Parse a `--role` / `WARLOCK_ROLES` value into the set of roles a process
  * should serve.
@@ -20,7 +20,7 @@ type AppRole = (typeof APP_ROLES)[number];
  * an entry that is not one of {@link APP_ROLES}, throws rather than silently
  * falling back to "every role", since that would mask a typo as full traffic.
  */
-declare function parseRoles(value: string | undefined): ReadonlySet<AppRole>;
+export declare function parseRoles(value: string | undefined): ReadonlySet<AppRole>;
 /**
  * Parse a `--sites` / `WARLOCK_SITES` value into the set of site keys a
  * `web` process should install pages for.
@@ -31,34 +31,34 @@ declare function parseRoles(value: string | undefined): ReadonlySet<AppRole>;
  * passed. Cross-checking against the active roles and against `web.sites`
  * config happens where both are known, not here.
  */
-declare function parseSites(value: string | undefined): ReadonlySet<string> | undefined;
+export declare function parseSites(value: string | undefined): ReadonlySet<string> | undefined;
 /**
  * `--sites` only makes sense alongside the `web` role — an `api`- or
  * `worker`-only process never installs pages, so a sites filter on it could
  * never do anything, and staying silent about that would hide a
  * misconfigured deploy.
  */
-declare function assertSitesRequireWebRole(roles: ReadonlySet<AppRole>, sites: ReadonlySet<string> | undefined): void;
+export declare function assertSitesRequireWebRole(roles: ReadonlySet<AppRole>, sites: ReadonlySet<string> | undefined): void;
 /**
  * The roles this process serves. See {@link resolveRoles}.
  */
-declare function getRoles(): ReadonlySet<AppRole>;
+export declare function getRoles(): ReadonlySet<AppRole>;
 /**
  * The sites this process installs pages for, or `undefined` for every site.
  * See {@link resolveSites}.
  */
-declare function getSites(): ReadonlySet<string> | undefined;
+export declare function getSites(): ReadonlySet<string> | undefined;
 /**
  * Whether this process serves the given role.
  */
-declare function hasRole(role: AppRole): boolean;
+export declare function hasRole(role: AppRole): boolean;
 /**
  * Whether this process should bind the http port — true when it serves
  * `api` or `web`, false for a `worker`-only process. Shared by the http
  * connector (skips `listen()`) and the production port preflight (skips the
  * probe), so both agree on the same condition.
  */
-declare function servesHttp(): boolean;
+export declare function servesHttp(): boolean;
 /**
  * Drop the cached roles/sites so the next call to {@link getRoles} /
  * {@link getSites} re-reads `process.env`.
@@ -66,7 +66,6 @@ declare function servesHttp(): boolean;
  * @internal Test-only — production code resolves once per process on
  * purpose (see {@link resolveRoles}).
  */
-declare function resetRolesCacheForTests(): void;
+export declare function resetRolesCacheForTests(): void;
 //#endregion
-export { APP_ROLES, AppRole, assertSitesRequireWebRole, getRoles, getSites, hasRole, parseRoles, parseSites, resetRolesCacheForTests, servesHttp };
 //# sourceMappingURL=roles.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"roles.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/roles.ts"],"mappings":";;AAKA;;;;cAAa,SAAA;AAMb;;;;AAAA,KAAY,OAAA,WAAkB,SAAS;AAcvC;;;;;;;;AAA0E;AAiC1E;AAjCA,iBAAgB,UAAA,CAAW,KAAA,uBAA4B,WAAW,CAAC,OAAA;;;AAiCD;AAuBlE;;;;;;;iBAvBgB,UAAA,CAAW,KAAA,uBAA4B,WAAW;;;;;;;iBAuBlD,yBAAA,CACd,KAAA,EAAO,WAAA,CAAY,OAAA,GACnB,KAAA,EAAO,WAAA;AA0CT;;;AAAA,iBAAgB,QAAA,IAAY,WAAW,CAAC,OAAA;AAAO;AAQ/C;;;AAR+C,iBAQ/B,QAAA,IAAY,WAAW;AAAA;AAOvC;;AAPuC,iBAOvB,OAAA,CAAQ,IAAa,EAAP,OAAO;;AAAA;AAUrC;;;;iBAAgB,UAAA;AAahB;;;;AAAuC;;;AAAvC,iBAAgB,uBAAA"}
+{"version":3,"file":"roles.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/roles.ts"],"mappings":";;;;;;qBAKa;;;;;YAMD,kBAAkB;;;;;;;;;;;wBAcd,WAAW,4BAA4B,YAAY;;;;;;;;;;;wBAiCnD,WAAW,4BAA4B;;;;;;;wBAuBvC,0BACd,OAAO,YAAY,UACnB,OAAO;;;;wBA0CO,YAAY,YAAY;;;;;wBAQxB,YAAY;;;;wBAOZ,QAAQ,MAAM;;;;;;;wBAUd;;;;;;;;wBAaA"}

package/esm/benchmark/benchmark-snapshots.d.mts

@@ -1,7 +1,6 @@
 import { BenchmarkErrorResult, BenchmarkSnapshotsOptions, BenchmarkSuccessResult } from "./types.mjs";
-
 //#region ../../packages/core/src/benchmark/benchmark-snapshots.d.ts
-declare class BenchmarkSnapshots {
+export declare class BenchmarkSnapshots {
   private readonly maxSnapshots;
   private readonly capture;
   private readonly snapshots;
@@ -47,5 +46,4 @@ declare class BenchmarkSnapshots {
   reset(name?: string): void;
 }
 //#endregion
-export { BenchmarkSnapshots };
 //# sourceMappingURL=benchmark-snapshots.d.mts.map

package/esm/benchmark/benchmark-snapshots.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"benchmark-snapshots.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/benchmark/benchmark-snapshots.ts"],"mappings":";;;cAMa,kBAAA;EAAA,iBACM,YAAA;EAAA,iBACA,OAAA;EAAA,iBACA,SAAA;cAKE,OAAA,GAAU,yBAAA;EAAA;;;;;;;;;EActB,MAAA,CAAO,MAAA,EAAQ,sBAAA,YAAkC,oBAAA;EArBvC;;;;;;;;;EAgDV,YAAA,CAAa,IAAA,YAAgB,sBAAA,YAAkC,oBAAA;EAA/D;;;;;;;;EAYA,YAAA,IAAgB,MAAA,UAEpB,sBAAA,YAAkC,oBAAA;EAoBxB;;AAAa;;;;;;;EAAnB,KAAA,CAAM,IAAA;AAAA"}
+{"version":3,"file":"benchmark-snapshots.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/benchmark/benchmark-snapshots.ts"],"mappings":";;qBAMa;mBACM;mBACA;mBACA;EAKjB,YAAmB,UAAU;;;;;;;;;;EActB,OAAO,QAAQ,kCAAkC;;;;;;;;;;EA2BjD,aAAa,gBAAgB,kCAAkC;;;;;;;;;EAY/D,gBAAgB,gBAEpB,kCAAkC;;;;;;;;;;EAoB9B,MAAM"}