@zerotal/core 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -8,6 +8,25 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.5.1] — 2026-08-15
+
+### Fixed
+
+- **Every development-only surface switched itself off under `zt serve`.**
+  `devSurfacesEnabled()` asked `Bun.env["APP_ENV"]` whether this was a development
+  environment — but `setAppEnv()` replaces that with the runtime mode before the app is
+  created, so it was asking whether `"web"` is development. The answer is no. An app with
+  `APP_ENV=development` in its `.env` therefore got **production error pages** from a plain
+  `bun zt serve`: no stack trace, no dev overlay.
+
+  It reads `deployEnv()` now, which is where the deployment name survives. Production and
+  staging are unaffected — both still fail closed, and an unset value still fails closed.
+
+  This is the third instance of one mistake. The weak-`APP_KEY` refusal and the ORM's N+1
+  detector had exactly the same bug, both fixed in 1.5.0. Reading `APP_ENV` to decide
+  anything about the _deployment_ is wrong once the app has booted; `deployEnv()` is the
+  answer.
+
 ## [1.5.0] — 2026-08-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/helpers/index.ts

@@ -22,7 +22,7 @@
  */
 import { join } from "node:path";
 import { ConfigError } from "../errors/ConfigError.ts";
-import { DEPLOY_ENV_VAR } from "../support/env.ts";
+import { DEPLOY_ENV_VAR, RUNTIME_MODES as _RUNTIME_MODES } from "../support/env.ts";
 
 // ── basePath() ────────────────────────────────────────────────────────────────
 
@@ -65,9 +65,6 @@ export function basePath(...segments: string[]): string {
  * setAppEnv(process.argv[2]);
  * const { default: app } = await import('./bootstrap/app.ts');
  */
-/** Runtime-mode values that Application understands natively — never remapped. */
-const _RUNTIME_MODES = new Set(["web", "worker", "console", "test", "testing", "repl"]);
-
 export function setAppEnv(command?: string): void {
   const normalizedCommand = (command ?? "").toLowerCase();
   const current = Bun.env["APP_ENV"];
@@ -79,10 +76,11 @@ export function setAppEnv(command?: string): void {
   // quietly answering no — including the weak-`APP_KEY` refusal and the ORM's
   // N+1 detector. `deployEnv()` reads this back; see {@link DEPLOY_ENV_VAR}.
   //
-  // `??=` so the first caller wins: a re-entrant `setAppEnv` (dev mode boots the
-  // app twice) must not stamp the runtime mode over the real deployment name.
+  // The guard is what protects a re-entrant call: `current` is only ever written
+  // when it is a genuine deployment name, so a second `setAppEnv` — which sees the
+  // runtime mode this one just wrote — cannot stamp `"web"` over `"production"`.
   if (current && !_RUNTIME_MODES.has(current.toLowerCase())) {
-    environment[DEPLOY_ENV_VAR] ??= current;
+    environment[DEPLOY_ENV_VAR] = current;
   }
 
   if (["serve", "start", "s", "dev", "d"].includes(normalizedCommand)) {

package/src/support/env.ts

@@ -53,6 +53,22 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  */
 export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
 
+/**
+ * The values of `APP_ENV` that name a runtime *mode* rather than a deployment.
+ * `setAppEnv()` writes these; {@link deployEnv} recognises them to know whether
+ * `APP_ENV` still holds the deployment name.
+ *
+ * @internal
+ */
+export const RUNTIME_MODES: ReadonlySet<string> = new Set([
+  "web",
+  "worker",
+  "console",
+  "test",
+  "testing",
+  "repl",
+]);
+
 /**
  * The deployment name this process was started with — `production`, `staging`,
  * `local`, whatever the operator set — as opposed to the runtime *mode*.
@@ -72,7 +88,16 @@ export const DEPLOY_ENV_VAR = "ZT_APP_ENV";
  * @internal
  */
 export function deployEnv(): string {
-  return Bun.env[DEPLOY_ENV_VAR] ?? Bun.env["APP_ENV"] ?? "";
+  const current = Bun.env["APP_ENV"] ?? "";
+  // If `APP_ENV` still holds a deployment name, it has not been overwritten yet —
+  // or something set it deliberately since — so it is the freshest answer. Only
+  // once it holds a runtime mode is the preserved copy the better one.
+  //
+  // Preferring the preserved copy unconditionally made it sticky for the life of
+  // the process: anything that set `APP_ENV` afterwards was ignored, which is
+  // wrong in itself and which leaked between test files sharing one process.
+  if (current && !RUNTIME_MODES.has(current.toLowerCase())) return current;
+  return Bun.env[DEPLOY_ENV_VAR] ?? current;
 }
 
 /**
@@ -101,7 +126,11 @@ export function deployEnv(): string {
  */
 export function devSurfacesEnabled(): boolean {
   if (Bun.env[DEV_WORKER_ENV_VAR] === "1") return true;
-  return isDevSurfaceAllowed(Bun.env["APP_ENV"] ?? "");
+  // `deployEnv()`, not `Bun.env["APP_ENV"]` — by the time anything asks, `setAppEnv()`
+  // has replaced that with the runtime mode, and `isDevSurfaceAllowed("web")` is false.
+  // An app with `APP_ENV=development` in its `.env` was therefore getting production
+  // error pages from a plain `zt serve`.
+  return isDevSurfaceAllowed(deployEnv());
 }
 
 /**