@zerotal/core 1.3.0 → 1.5.0

package/src/doctor/AppDoctor.ts

@@ -0,0 +1,399 @@
+/**
+ * `zt doctor` — static sanity checks against a booted app.
+ *
+ * Most of the expensive failures in a Zerotal app are silent: a provider that
+ * isn't registered fails by doing nothing, `synchronize` and migrations collide
+ * on the first command a new user types, a routes file 404s because nothing
+ * loads it. Each is statically detectable, and the individual warnings already
+ * exist at various points of the boot sequence — this runs them all in one
+ * place, on demand, with the fix next to each finding.
+ *
+ * Packages contribute their own checks via `app.registerDoctorCheck()` (the
+ * scheduler's static-config check is the model); the built-ins cover core.
+ */
+import { readdirSync } from "node:fs";
+import type { Application } from "../application/Application.ts";
+import { appKeyStrengthWarning } from "../support/appKey.ts";
+import { unroutedRoutesWarning } from "../support/unroutedRoutes.ts";
+import { isWritableDir } from "../dev/bootBuild.ts";
+import { isProdLike } from "../support/env.ts";
+
+/** One finding: ok is silent health, warn is worth reading, fail is broken now. */
+export interface DoctorCheckResult {
+  status: "ok" | "warn" | "fail";
+  message: string;
+  /** The command or edit that resolves it, shown under the finding. */
+  fix?: string;
+}
+
+/** A named check. Contribute app-specific ones via `app.registerDoctorCheck()`. */
+export interface DoctorCheck {
+  /** Stable kebab-case id (e.g. `"app-key"`). */
+  id: string;
+  /** Human label printed next to the finding. */
+  label: string;
+  run(app: Application): DoctorCheckResult | Promise<DoctorCheckResult>;
+}
+
+/** A check paired with what it found. */
+export interface DoctorReportEntry {
+  check: DoctorCheck;
+  result: DoctorCheckResult;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _config(app: Application, key: string): unknown {
+  try {
+    const config = app.container.makeSync("config") as { get(k: string): unknown };
+    return config.get(key);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Non-test source files directly inside `<root>/<dir>`, or [] when absent. */
+function _sourceFiles(root: string, dir: string): string[] {
+  try {
+    return readdirSync(`${root}/${dir}`).filter(
+      (f) => /\.(ts|js)$/.test(f) && !/\.test\.(ts|js)$/.test(f),
+    );
+  } catch {
+    return [];
+  }
+}
+
+const ok = (message: string): DoctorCheckResult => ({ status: "ok", message });
+const warn = (message: string, fix?: string): DoctorCheckResult => ({
+  status: "warn",
+  message,
+  ...(fix !== undefined ? { fix } : {}),
+});
+const fail = (message: string, fix?: string): DoctorCheckResult => ({
+  status: "fail",
+  message,
+  ...(fix !== undefined ? { fix } : {}),
+});
+
+// ── Built-in checks ───────────────────────────────────────────────────────────
+
+const appKeyCheck: DoctorCheck = {
+  id: "app-key",
+  label: "APP_KEY",
+  run() {
+    const key = Bun.env["APP_KEY"];
+    if (!key) {
+      return warn(
+        "APP_KEY is not set. Sessions, signed URLs and encrypted columns all derive from it; " +
+          "a production-like APP_ENV refuses to boot without a strong one.",
+        "bun zt key:generate",
+      );
+    }
+    const weakness = appKeyStrengthWarning(key);
+    return weakness ? fail(weakness, "bun zt key:generate") : ok("set and strong");
+  },
+};
+
+const syncVsMigrationsCheck: DoctorCheck = {
+  id: "synchronize-vs-migrations",
+  label: "Schema source of truth",
+  run(app) {
+    const synchronize = _config(app, "database.synchronize") === true;
+    const migrations = _sourceFiles(process.cwd(), "database/migrations");
+    if (synchronize && migrations.length > 0) {
+      return fail(
+        `database.synchronize is on and ${migrations.length} migration(s) exist. Boot-time ` +
+          `sync creates tables from the models first, so the first \`migrate\` fails with ` +
+          `"table already exists". The schema needs exactly one source of truth.`,
+        "Set synchronize: false in config/database.ts (migrations become the source of truth).",
+      );
+    }
+    if (synchronize) return ok("synchronize (no migrations present)");
+    return ok(migrations.length > 0 ? "migrations" : "no schema management configured");
+  },
+};
+
+/**
+ * The origin guard on pipeline-bypassing endpoints compares the browser's `Origin` against
+ * the app's own — which behind a proxy is the loopback address it bound to. Everything the
+ * app needs to be reachable is therefore in `app.allowedOrigins`, and getting it wrong is
+ * silent: pages render, actions 403.
+ */
+const allowedOriginsCheck: DoctorCheck = {
+  id: "allowed-origins",
+  label: "Transport origins",
+  run(app) {
+    const url = _config(app, "app.url");
+    const origins = _config(app, "app.allowedOrigins");
+    const list = Array.isArray(origins) ? origins.filter((o) => typeof o === "string") : [];
+
+    if (list.length === 0) {
+      return fail(
+        "app.allowedOrigins is empty. Behind a reverse proxy the app's own origin is the " +
+          "loopback address it bound to, so every browser-initiated WebSocket and " +
+          "/__flow/http action will be refused with 403 while pages keep rendering.",
+        "Set url in config/app.ts (AppConfig fills allowedOrigins from it).",
+      );
+    }
+
+    // Unparseable entries can never equal an `Origin` header, so they are inert — but an
+    // inert entry is always a typo, and the typo is usually the one that mattered.
+    const unparseable = list.filter((entry) => {
+      try {
+        return new URL(entry).origin !== entry;
+      } catch {
+        return true;
+      }
+    });
+    if (unparseable.length > 0) {
+      return warn(
+        `app.allowedOrigins contains ${unparseable.map((e) => `"${e}"`).join(", ")}, which ` +
+          `${unparseable.length === 1 ? "is not an origin" : "are not origins"} and can never ` +
+          `match an Origin header. An origin is scheme + host + port, with no path or trailing slash.`,
+        "Correct the entry in config/app.ts, e.g. https://app.example.com",
+      );
+    }
+
+    // A production app still pointing at localhost has a plausible-looking config and an
+    // allowedOrigins list that no real browser will ever match.
+    if (_isProductionEnv(app) && typeof url === "string" && _isLoopback(url)) {
+      return fail(
+        `app.url is ${url} in a production environment, so allowedOrigins is a loopback ` +
+          `address. Browsers send the public origin, which is not in the list — every ` +
+          `credentialed action will be refused.`,
+        "Set APP_URL to the public URL the site is served from.",
+      );
+    }
+
+    return ok(list.join(", "));
+  },
+};
+
+/**
+ * `serve` builds configured assets at boot, so the output directory has to be writable —
+ * or the build has to have happened at deploy time. Either is fine; the failure is the
+ * combination nobody chose deliberately.
+ */
+const bootAssetWriteCheck: DoctorCheck = {
+  id: "boot-asset-writes",
+  label: "Asset output",
+  async run(app) {
+    const assets = _config(app, "app.assets") as { outDir?: string } | undefined;
+    const dirs = [
+      ...(assets?.outDir ? [assets.outDir] : []),
+      // Flow bundles its own CSS/JS into these when the entry points exist.
+      ...(await _existingFlowAssetDirs()),
+    ];
+    if (dirs.length === 0) return ok("no bundled assets configured");
+
+    if (!_isProductionEnv(app)) return ok(`${dirs.join(", ")} (built at boot outside production)`);
+
+    const unwritable: string[] = [];
+    for (const dir of dirs) {
+      if (!(await isWritableDir(`${process.cwd()}/${dir}`))) unwritable.push(dir);
+    }
+    if (unwritable.length === 0) return ok(`${dirs.join(", ")} writable`);
+
+    return ok(
+      `${unwritable.join(", ")} is read-only — the boot-time build is skipped and the ` +
+        `assets shipped with the release are served. Build them at deploy time.`,
+    );
+  },
+};
+
+/** Directories Flow writes bundles into, listed only when the matching entry point exists. */
+async function _existingFlowAssetDirs(): Promise<string[]> {
+  const pairs = [
+    ["resources/css/app.css", "public/css"],
+    ["resources/js/app.js", "public/js"],
+  ] as const;
+  const out: string[] = [];
+  for (const [entry, dir] of pairs) {
+    if (await Bun.file(`${process.cwd()}/${entry}`).exists()) out.push(dir);
+  }
+  return out;
+}
+
+function _isProductionEnv(app: Application): boolean {
+  return isProdLike(String(_config(app, "app.env") ?? ""));
+}
+
+/** Whether a URL points at this machine — i.e. is not something a browser elsewhere can reach. */
+function _isLoopback(url: string): boolean {
+  try {
+    const host = new URL(url).hostname;
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+
+const unroutedRoutesCheck: DoctorCheck = {
+  id: "unrouted-routes",
+  label: "routes/ directory",
+  run(app) {
+    const warning = unroutedRoutesWarning(process.cwd(), app.routedFiles);
+    return warning ? warn(warning) : ok("absent or routed");
+  },
+};
+
+/** A directory-full-of-classes whose consuming provider isn't registered does nothing. */
+function _providerDirCheck(options: {
+  id: string;
+  label: string;
+  dir: (app: Application) => string;
+  binding: string;
+  provider: string;
+}): DoctorCheck {
+  return {
+    id: options.id,
+    label: options.label,
+    run(app) {
+      const dir = options.dir(app);
+      const files = _sourceFiles(process.cwd(), dir);
+      if (files.length === 0) return ok(`no ${dir}/`);
+      if (app.container.bound(options.binding as never)) {
+        return ok(`${files.length} file(s), provider registered`);
+      }
+      return warn(
+        `${dir}/ holds ${files.join(", ")} but ${options.provider} is not registered — ` +
+          `nothing in it will run, and nothing will say so.`,
+        `Add ${options.provider} to bootstrap/providers.ts.`,
+      );
+    },
+  };
+}
+
+function _conventionPath(app: Application, key: string, fallback: string): string {
+  const paths = _config(app, "app.conventions.paths") as Record<string, string> | undefined;
+  return paths?.[key] ?? fallback;
+}
+
+const schedulesProviderCheck = _providerDirCheck({
+  id: "schedules-provider",
+  label: "app/schedules",
+  dir: (app) => _conventionPath(app, "schedules", "app/schedules"),
+  binding: "scheduler",
+  provider: "SchedulerProvider",
+});
+
+const jobsProviderCheck = _providerDirCheck({
+  id: "jobs-provider",
+  label: "app/jobs",
+  dir: (app) => _conventionPath(app, "jobs", "app/jobs"),
+  binding: "queue",
+  provider: "QueueProvider",
+});
+
+const storageProviderCheck: DoctorCheck = {
+  id: "storage-provider",
+  label: "Storage",
+  async run(app) {
+    const hasConfig = await Bun.file(`${process.cwd()}/config/storage.ts`).exists();
+    if (!hasConfig) return ok("no config/storage.ts");
+    if (app.container.bound("storage" as never)) return ok("configured and registered");
+    return warn(
+      "config/storage.ts exists but StorageProvider is not registered — the first " +
+        "Storage.disk(...) call will throw, typically behind auth checks on an upload path.",
+      "Add StorageProvider to bootstrap/providers.ts.",
+    );
+  },
+};
+
+/**
+ * `cors.origin: "*"` tells every site on the internet it may read this app's
+ * responses from a browser. That is the right default for a public read-only API
+ * and wrong for everything else — and it is what every scaffolded app shipped with
+ * until 1.5.0, because the templates set it while the framework's own default was
+ * the safe empty list.
+ *
+ * Only a problem once deployed, so it fails on a production-like deployment and
+ * stays quiet locally, where `*` is what makes a second dev server work.
+ */
+const corsWildcardCheck: DoctorCheck = {
+  id: "cors-wildcard",
+  label: "CORS",
+  run(app) {
+    const origin = _config(app, "app.cors.origin");
+    const wildcard = origin === "*" || (Array.isArray(origin) && origin.some((o) => o === "*"));
+    if (!wildcard) return ok("no wildcard origin.");
+    if (!_isProductionEnv(app)) return ok('origin is "*" — fine outside a deployment.');
+    return fail(
+      'app.cors.origin is "*", so any website can read this app\'s responses from a ' +
+        "visitor's browser.",
+      "Set app.cors.origin to the origins that legitimately call this app, in config/app.ts.",
+    );
+  },
+};
+
+/**
+ * HSTS is emitted only when `app.secureHeaders.secure` is true, which defaults to
+ * false and has never had production auto-detection. A deployment that never set it
+ * serves no `Strict-Transport-Security` at all, so a visitor's first request each
+ * time stays downgradeable to plain HTTP.
+ */
+const secureHeadersCheck: DoctorCheck = {
+  id: "secure-headers",
+  label: "Secure headers",
+  run(app) {
+    const secure = _config(app, "app.secureHeaders.secure") === true;
+    if (secure) return ok("HSTS enabled.");
+    if (!_isProductionEnv(app)) return ok("HSTS off — expected outside a deployment.");
+    return fail(
+      "app.secureHeaders.secure is not true, so no Strict-Transport-Security header is " +
+        "sent and the first request of each visit can be downgraded to HTTP.",
+      "Set app.secureHeaders.secure: true in config/app.ts once the site is served over HTTPS.",
+    );
+  },
+};
+
+/** The core checks every app gets. */
+export const builtinDoctorChecks: DoctorCheck[] = [
+  appKeyCheck,
+  allowedOriginsCheck,
+  corsWildcardCheck,
+  secureHeadersCheck,
+  bootAssetWriteCheck,
+  syncVsMigrationsCheck,
+  unroutedRoutesCheck,
+  schedulesProviderCheck,
+  jobsProviderCheck,
+  storageProviderCheck,
+];
+
+/**
+ * Run the built-in checks plus everything providers contributed. A check that
+ * throws is reported as a failure of that check, never of the doctor.
+ */
+export async function runDoctor(
+  app: Application,
+  extraChecks: DoctorCheck[] = [],
+): Promise<DoctorReportEntry[]> {
+  // Three sources, one list. `registerDoctorCheck()` is imperative and runs in
+  // `onRegister()`; `doctorChecks()` is declarative and is asked of a booted
+  // provider, which is the shape a package author already knows from
+  // `replContext()` and `devProcesses()`. A provider whose method throws
+  // contributes nothing rather than failing the doctor for every other package.
+  const declared: DoctorCheck[] = [];
+  for (const provider of app._activeProviders ?? []) {
+    try {
+      declared.push(...(provider.doctorChecks?.() ?? []));
+    } catch {
+      // Deliberately silent: a broken contribution is not a finding about the
+      // app being checked, and the doctor is what the user ran.
+    }
+  }
+
+  const checks = [...builtinDoctorChecks, ...app.doctorChecks, ...declared, ...extraChecks];
+  const report: DoctorReportEntry[] = [];
+  for (const check of checks) {
+    let result: DoctorCheckResult;
+    try {
+      result = await check.run(app);
+    } catch (err) {
+      result = fail(`check threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    report.push({ check, result });
+  }
+  return report;
+}

package/src/doctor/TransportProbe.ts

@@ -0,0 +1,169 @@
+/**
+ * Probe a deployed app's WebSocket transport the way a browser would.
+ *
+ * Every static check in the doctor runs inside the process, and the expensive production
+ * failures are precisely the ones that cannot be seen from there: a reverse proxy that
+ * gates the transport path, an origin guard comparing against the loopback address the app
+ * bound to, a proxy that never forwards the upgrade. All of them leave the app healthy
+ * from the inside — the HTML renders, the logs are quiet, a status-code health check
+ * passes — while every action in the browser does nothing.
+ *
+ * So this probe goes the long way round: out through the public URL, back through the
+ * proxy. It sends a real handshake with a real `Origin`, and reads the status the server
+ * actually returned.
+ *
+ * ## Why not curl
+ *
+ * You can do this by hand, with one caveat that costs an hour the first time: curl over
+ * TLS negotiates HTTP/2, where `Connection: Upgrade` is meaningless, and the server answers
+ * `404` on a route that is working perfectly. Browsers use HTTP/1.1 for WebSockets, so any
+ * hand-run check needs `--http1.1`:
+ *
+ * ```bash
+ * curl -s -o /dev/null -w '%{http_code}\n' --http1.1 \
+ *      -H 'Origin: https://your.app' -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
+ *      -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
+ *      https://your.app/__flow/ws          # expect 101
+ * ```
+ */
+
+/** The outcome of one handshake attempt. */
+export interface TransportProbeResult {
+  /** The full URL probed. */
+  url: string;
+  /** HTTP status returned to the handshake, or null when the request never completed. */
+  status: number | null;
+  /** Whether the transport is usable from a browser at this origin. */
+  ok: boolean;
+  /** What the status means here, in one line. */
+  message: string;
+  /** The change that fixes it, when the diagnosis implies one. */
+  fix?: string;
+}
+
+/** A WebSocket handshake is an ordinary HTTP request until the server agrees to switch. */
+function _handshakeHeaders(origin: string): Record<string, string> {
+  return {
+    Origin: origin,
+    Connection: "Upgrade",
+    Upgrade: "websocket",
+    "Sec-WebSocket-Version": "13",
+    // Any base64 of 16 bytes. The server echoes a derivation of it; nothing here checks
+    // that, because the status code is the whole signal.
+    "Sec-WebSocket-Key": "dGhlIHNhbXBsZSBub25jZQ==",
+  };
+}
+
+/** Turn a handshake status into a diagnosis. */
+function _diagnose(status: number): Omit<TransportProbeResult, "url" | "status"> {
+  if (status === 101) {
+    return { ok: true, message: "101 Switching Protocols — a browser can open this socket." };
+  }
+  if (status === 401 || status === 407) {
+    return {
+      ok: false,
+      message:
+        `${status} — something in front of the app is asking for credentials. Browsers do ` +
+        `not attach basic-auth credentials to a WebSocket handshake, so any auth gate over ` +
+        `this path blocks the transport outright.`,
+      fix: "Exempt the transport path at the proxy, e.g. Caddy: `@gated not path /__flow/*`.",
+    };
+  }
+  if (status === 403) {
+    return {
+      ok: false,
+      message:
+        "403 — the origin guard refused this Origin. Behind a proxy the app's own origin is " +
+        "the loopback address it bound to, so the public origin has to be configured.",
+      fix: "Set url in config/app.ts to the public URL (AppConfig fills allowedOrigins from it).",
+    };
+  }
+  if (status === 404) {
+    return {
+      ok: false,
+      message:
+        "404 — nothing handled the upgrade. Either the proxy is not forwarding this path, " +
+        "or it terminated the request on a protocol where Upgrade has no meaning.",
+      fix: "Check the proxy forwards this path to the app, and that it speaks HTTP/1.1 upstream.",
+    };
+  }
+  if (status === 426 || status === 400) {
+    return {
+      ok: false,
+      message:
+        `${status} — the upgrade was not negotiated. Usually the request reached the app ` +
+        `over a protocol that cannot upgrade (HTTP/2), rather than a fault in the app.`,
+      fix: "Ensure the proxy connects to the app over HTTP/1.1 and does not buffer the connection.",
+    };
+  }
+  if (status >= 500) {
+    return {
+      ok: false,
+      message: `${status} — the app errored handling the handshake. Check its logs.`,
+    };
+  }
+  return { ok: false, message: `${status} — unexpected; a working transport answers 101.` };
+}
+
+/**
+ * Attempt a WebSocket handshake against `url`, declaring `origin`, and report what came back.
+ *
+ * @param url - The absolute ws/http URL to probe. `http`/`https` are used as-is; the
+ *   handshake is an HTTP request.
+ * @param origin - The `Origin` to send — the public origin a browser would send.
+ * @param timeoutMs - How long to wait before giving up. Default 10s.
+ */
+export async function probeWebSocket(
+  url: string,
+  origin: string,
+  timeoutMs = 10_000,
+): Promise<TransportProbeResult> {
+  try {
+    const response = await fetch(url, {
+      headers: _handshakeHeaders(origin),
+      signal: AbortSignal.timeout(timeoutMs),
+      redirect: "manual",
+    });
+    // A 3xx here is a redirect the browser would follow for a page but not for a socket.
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location") ?? "elsewhere";
+      return {
+        url,
+        status: response.status,
+        ok: false,
+        message: `${response.status} — redirected to ${location}. A WebSocket handshake is not redirected; probe the final URL.`,
+        fix: `Probe ${location} instead, or stop redirecting the transport path.`,
+      };
+    }
+    return { url, status: response.status, ..._diagnose(response.status) };
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return {
+      url,
+      status: null,
+      ok: false,
+      message: `the request never completed: ${reason}`,
+      fix: "Check the host resolves, the TLS certificate is valid, and the port is reachable.",
+    };
+  }
+}
+
+/**
+ * Probe every WebSocket path an app registered, against its public base URL.
+ *
+ * @param baseUrl - The public URL the app is served from, as a browser would reach it.
+ * @param paths - Registered WS paths, from `app.webSocketPaths()`. Catch-all (`"*"`)
+ *   registrations are skipped: there is no single URL that represents them.
+ */
+export async function probeTransport(
+  baseUrl: string,
+  paths: string[],
+): Promise<TransportProbeResult[]> {
+  const base = new URL(baseUrl);
+  const results: TransportProbeResult[] = [];
+  for (const path of paths) {
+    if (path === "*") continue;
+    results.push(await probeWebSocket(new URL(path, base).href, base.origin));
+  }
+  return results;
+}

package/src/events/Emitter.ts

@@ -4,6 +4,7 @@
  * (fire-and-forget), synchronously, or be deferred to a queue.
  */
 import { CallQueuedListener } from "./CallQueuedListener.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 type EventClass<T extends object> = new (...args: unknown[]) => T;
 type ListenerClass<T extends object> = new (...args: unknown[]) => {
@@ -56,7 +57,7 @@ export interface QueuedListener<T = any> {
  * ```
  */
 export class Emitter {
-  private _listeners = new Map<Function, ListenerClass<object>[]>();
+  private _listeners = new Map<ClassRef, ListenerClass<object>[]>();
   private _listenerByName = new Map<string, ListenerClass<object>>();
 
   // Holds the application so the emitter can resolve the queue manager lazily.
@@ -170,7 +171,7 @@ export class Emitter {
     // A snapshot, not the live array: a listener that registers another listener for the
     // same event otherwise extends the array being iterated. One emit ran handle() 100,000
     // times that way.
-    const listenerClasses = [...(this._listeners.get(event.constructor as Function) ?? [])];
+    const listenerClasses = [...(this._listeners.get(event.constructor as ClassRef) ?? [])];
 
     if (listenerClasses.length === 0) return;
 
@@ -229,7 +230,7 @@ export class Emitter {
     // A snapshot, not the live array: a listener that registers another listener for the
     // same event otherwise extends the array being iterated. One emit ran handle() 100,000
     // times that way.
-    const listenerClasses = [...(this._listeners.get(event.constructor as Function) ?? [])];
+    const listenerClasses = [...(this._listeners.get(event.constructor as ClassRef) ?? [])];
 
     for (const ListenerClass of listenerClasses) {
       const listener = new ListenerClass();

package/src/facade/facades/App.ts

@@ -20,6 +20,7 @@ import { currentApp } from "../../application/currentApp.ts";
 import type { Container } from "../../container/Container.ts";
 import type { BindingToken, ContainerBindings, Factory } from "../../container/types.ts";
 import { ContainerLockedError } from "../../errors/ContainerErrors.ts";
+import { isProdLike } from "../../support/env.ts";
 
 /**
  * Return the live container, throwing {@link ContainerLockedError} when the
@@ -64,9 +65,16 @@ export const App = {
     return currentApp().environment;
   },
 
-  /** Whether the configured `app.env` is a production environment. */
+  /**
+   * Whether the configured `app.env` is a production-like environment —
+   * `production`, `prod`, or `staging`.
+   *
+   * `staging` counts. A staging box is a deployed box: it serves real traffic over
+   * a real network with real credentials, and every reason to suppress a stack
+   * trace or a debug surface in production applies to it identically.
+   */
   isProduction(): boolean {
-    return ["production", "prod"].includes(_appEnv());
+    return isProdLike(_appEnv());
   },
 
   /** Whether the configured `app.env` is a local/development environment. */

package/src/helpers/index.ts

@@ -22,6 +22,7 @@
  */
 import { join } from "node:path";
 import { ConfigError } from "../errors/ConfigError.ts";
+import { DEPLOY_ENV_VAR } from "../support/env.ts";
 
 // ── basePath() ────────────────────────────────────────────────────────────────
 
@@ -54,6 +55,7 @@ export function basePath(...segments: string[]): string {
  * | Command              | APP_ENV   |
  * |----------------------|-----------|
  * | serve / start / s    | web       |
+ * | dev / d              | web       |
  * | worker / queue:work  | worker    |
  * | anything else        | console   |
  *
@@ -71,9 +73,29 @@ export function setAppEnv(command?: string): void {
   const current = Bun.env["APP_ENV"];
   const environment = Bun.env as Record<string, string>;
 
-  if (["serve", "start", "s"].includes(normalizedCommand)) {
+  // Preserve the deployment name before it is overwritten. Every branch below
+  // replaces `APP_ENV` with a runtime mode, which is why six different gates that
+  // asked "is this production?" of `Bun.env["APP_ENV"]` were reading `"web"` and
+  // 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.
+  if (current && !_RUNTIME_MODES.has(current.toLowerCase())) {
+    environment[DEPLOY_ENV_VAR] ??= current;
+  }
+
+  if (["serve", "start", "s", "dev", "d"].includes(normalizedCommand)) {
     // Always force web mode for the HTTP server — deployment-env names like
     // "local" or "production" must not leave the app in console mode.
+    //
+    // `dev` belongs here with `serve`, and the reason is not cosmetic. Dev mode's
+    // process 1 boots the app purely to ask its providers what to run, and a
+    // provider is only asked if `static environments` includes the env it booted
+    // under. Falling through to "console" below would silently drop every
+    // web-only provider — no error, no empty tab, just a process that never
+    // appears — and would make `zt dev` and `serve --dev` disagree about what
+    // dev mode consists of.
     if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
       environment["APP_ENV"] = "web";
     }