@zerotal/core 1.4.0 → 1.5.1

package/src/support/env.ts

@@ -13,8 +13,12 @@
  * suppressed. Accepts `"production"`, `"prod"`, and `"staging"`,
  * case-insensitively.
  *
+ * Pass {@link deployEnv}, not `Bun.env["APP_ENV"]` — after `setAppEnv()` the latter
+ * holds a runtime mode, and `isProdLike("web")` is `false` for every deployment.
+ *
+ * @internal
  * @example
- * if (!isProdLike(Bun.env["APP_ENV"] ?? "")) return renderDevErrorPage(error);
+ * if (!isProdLike(deployEnv())) return renderDevErrorPage(error);
  */
 export function isProdLike(env: string): boolean {
   const normalized = env.trim().toLowerCase();
@@ -43,6 +47,59 @@ export function isDevSurfaceAllowed(env: string): boolean {
  */
 export const DEV_WORKER_ENV_VAR = "ZT_DEV";
 
+/**
+ * Where `setAppEnv()` parks the deployment name before overwriting `APP_ENV`.
+ * @internal
+ */
+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*.
+ *
+ * `APP_ENV` carries both meanings, and the second one destroys the first:
+ * `setAppEnv()` overwrites it with `web` / `console` / `worker` before the app
+ * boots, so a gate that asks `isProdLike(Bun.env["APP_ENV"])` after startup is
+ * asking whether `"web"` is production and always getting no. That was not
+ * theoretical — it silently disabled the weak-`APP_KEY` refusal and left the
+ * ORM's N+1 detector wrapping every query in production.
+ *
+ * `setAppEnv()` now preserves the original value, and this reads it back. Prefer
+ * it to `Bun.env["APP_ENV"]` for **any** production decision. Config is an
+ * equally correct source where it is available (`config("app.env")`), but this
+ * works before config is loaded and in processes that have none.
+ *
+ * @internal
+ */
+export function deployEnv(): string {
+  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;
+}
+
 /**
  * Whether *this process* may expose dev-only surfaces — the stack-trace error
  * page, the trace inspector, an open monitor panel.
@@ -56,7 +113,9 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  *     construction. This is the case that carries dev mode, because `APP_ENV`
  *     cannot: `setAppEnv()` overwrites it with a *runtime mode* (`web`,
  *     `worker`, `console`) before the app boots, so by the time any gate reads
- *     it, whatever deployment name the developer configured is gone.
+ *     `APP_ENV` it holds the mode rather than the deployment name. (The name
+ *     itself is not lost — `setAppEnv()` parks it, and {@link deployEnv} reads
+ *     it back. What is lost is the ability to learn it from `APP_ENV`.)
  *
  *   - `APP_ENV` still names an explicitly non-production environment. This
  *     covers processes started outside the CLI — the test harness, and any
@@ -67,5 +126,42 @@ export const DEV_WORKER_ENV_VAR = "ZT_DEV";
  */
 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());
+}
+
+/**
+ * Whether a `DevOrchestrator` owns asset builds for this process.
+ *
+ * View providers build their bundles once at boot so assets are ready before
+ * the first request. Under `serve --dev` that is redundant three times over:
+ * the orchestrator process boots the app (registering hooks, and building), then
+ * runs the hooks itself, then spawns a worker that boots the app and builds
+ * again. Every backend save paid for two of those.
+ *
+ * Both processes are recognised, for different reasons:
+ *
+ *   - The supervised worker carries {@link DEV_WORKER_ENV_VAR}. The orchestrator
+ *     has already built and pruned before spawning it, so its assets are on disk
+ *     before it binds a port.
+ *   - The orchestrator itself is recognised from `argv`, not an environment
+ *     variable, because providers boot *before* `ServeCommand.run()` gets to set
+ *     one — the flag would always arrive too late to be read.
+ *
+ * Anything else — a plain `serve`, a queue worker, a test — is unsupervised and
+ * still builds at boot.
+ *
+ * @param env  Environment to read; defaults to the process environment.
+ * @param argv Command line to read; defaults to the process command line.
+ * @internal
+ */
+export function isDevOrchestrated(
+  env: Record<string, string | undefined> = Bun.env,
+  argv: readonly string[] = Bun.argv,
+): boolean {
+  if (env[DEV_WORKER_ENV_VAR] === "1") return true;
+  return argv.includes("serve") && argv.includes("--dev");
 }

package/src/support/unroutedRoutes.ts

@@ -0,0 +1,37 @@
+/**
+ * Unrouted `routes/` directory check.
+ *
+ * A conventional `routes/index.ts` full of `Router.get(...)` calls does nothing
+ * until a `routing()` group imports it — the file typechecks, the calls would
+ * execute cleanly, and every path in it 404s in a way that is indistinguishable
+ * from a typo'd URL. The scaffold wires only `fileBasedRouting()`, so "I made a
+ * routes file" and "it needs registering" are otherwise never connected.
+ */
+import { readdirSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+/**
+ * A warning message when `<root>/routes` holds route files that no `routing()`
+ * group loads, or `null` when the directory is absent, empty, or covered.
+ */
+export function unroutedRoutesWarning(root: string, routedFiles: string[]): string | null {
+  const dir = resolve(root, "routes");
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => /\.(ts|js)$/.test(f) && !/\.test\.(ts|js)$/.test(f));
+  } catch {
+    return null; // no routes/ directory — nothing to warn about
+  }
+  if (files.length === 0) return null;
+  const insideDir = (file: string) => {
+    const normalized = resolve(file);
+    return normalized === dir || normalized.startsWith(dir + sep);
+  };
+  if (routedFiles.some(insideDir)) return null;
+  const suggestion = files.includes("index.ts") ? "index.ts" : files[0];
+  return (
+    `routes/ contains ${files.join(", ")} but no routing() group loads it — ` +
+    `every route in it will 404. Add .routing("./routes/${suggestion}") to your ` +
+    `Application, or remove the directory.`
+  );
+}