@zerotal/core 1.6.3 → 1.7.2

package/src/dev/DevDeck.ts

@@ -19,10 +19,19 @@
  * ## The terminal must survive us
  *
  * Raw mode plus the alternate screen left on is the classic TUI bug: the shell
- * comes back with no echo, no line editing, and no scrollback. The restore is
+ * comes back with no echo, no line editing, and no shell scrollback. The restore is
  * therefore registered *before* raw mode is entered, and it runs on every exit
  * path there is — `q`, a signal, and an uncaught throw. It is also idempotent,
  * because several of those can happen at once.
+ *
+ * ## Scrolling is ours to do
+ *
+ * The alternate screen has no scrollback of its own, so the terminal's scrollbar
+ * and wheel have nothing to move: from the moment tabs mode starts, every way of
+ * looking at an older line has to come from here. Each card keeps its own buffer
+ * and its own position in it, the wheel arrives as cursor keys, and a card that
+ * has been scrolled up holds its place while the process behind it keeps
+ * printing.
  */
 import type { OutputWriter } from "../command/OutputWriter.ts";
 import type { DevProcessColor } from "./DevProcess.ts";
@@ -184,7 +193,7 @@ export class TabsDeck implements Deck {
   private _restored = false;
   private _stream: StreamDeck | undefined;
 
-  private readonly _onData = (chunk: Buffer | string): void => this._key(chunk.toString());
+  private readonly _onData = (chunk: Buffer | string): void => this._input(chunk.toString());
   private readonly _onResize = (): void => this._paint();
   private readonly _onExit = (): void => this.stop();
 
@@ -207,7 +216,7 @@ export class TabsDeck implements Deck {
     process.on("uncaughtException", this._onExit);
     process.on("unhandledRejection", this._onExit);
 
-    this._write(ALT_SCREEN_ON + CURSOR_HIDE);
+    this._write(ALT_SCREEN_ON + CURSOR_HIDE + ALT_SCROLL_ON);
     this._stdin.setRawMode?.(true);
     this._stdin.resume?.();
     this._stdin.on?.("data", this._onData);
@@ -224,6 +233,7 @@ export class TabsDeck implements Deck {
     const body = stream === "stderr" ? _paint(text, "red") : text;
     card.lines.push(`${stamp}${body}`);
     if (card.lines.length > SCROLLBACK) card.lines.shift();
+    this._anchor(card, body);
 
     // A tab the user is not looking at still buffers; only the visible one costs
     // a repaint. In stream mode every line prints regardless of focus.
@@ -271,26 +281,38 @@ export class TabsDeck implements Deck {
     }
     this._stdin.pause?.();
     if (this._repaintTimer) clearTimeout(this._repaintTimer);
-    this._write(CURSOR_SHOW + ALT_SCREEN_OFF);
+    this._write(ALT_SCROLL_OFF + CURSOR_SHOW + ALT_SCREEN_OFF);
   }
 
   // ── Input ──────────────────────────────────────────────────────────────────
 
-  private _key(sequence: string): void {
-    if (this._searching) {
-      this._searchKey(sequence);
-      return;
-    }
+  /**
+   * One read from stdin, which is not the same thing as one key.
+   *
+   * A wheel tick arrives as the same arrow sequence repeated as many times as
+   * there are lines to scroll, all in a single read, and two fast keystrokes
+   * arrive together — so a chunk is split into keys first and the frame is
+   * painted once at the end rather than once per key.
+   */
+  private _input(chunk: string): void {
+    let dirty = false;
+    for (const key of _keys(chunk)) dirty = this._key(key) || dirty;
+    if (dirty) this._paint();
+  }
+
+  /** Handle one key. Returns whether the frame needs repainting. */
+  private _key(sequence: string): boolean {
+    if (this._searching) return this._searchKey(sequence);
 
     switch (sequence) {
       case "q":
       case "\x03": // Ctrl-C — the deck owns the terminal, so it owns the quit.
         this._options.onQuit();
-        return;
+        return false;
       case "r": {
         const card = this._cards[this._focused];
         if (card) this._options.onRestart(card.status.name);
-        return;
+        return false;
       }
       case "c": {
         const card = this._cards[this._focused];
@@ -306,7 +328,7 @@ export class TabsDeck implements Deck {
         break;
       case "s":
         this._toggleStream();
-        return;
+        return false;
       case "t":
         this._timestamps = !this._timestamps;
         break;
@@ -317,22 +339,39 @@ export class TabsDeck implements Deck {
       case ARROW_LEFT:
         this._focus(this._focused - 1);
         break;
+      // The wheel is these two: in the alternate screen a terminal has no
+      // scrollback to move, so it sends the cursor keys instead (which is what
+      // `ALT_SCROLL_ON` asks for). Ignoring them is what makes the deck look
+      // like a terminal that will not scroll.
+      case ARROW_UP:
+        this._scroll(1);
+        break;
+      case ARROW_DOWN:
+        this._scroll(-1);
+        break;
       case PAGE_UP:
         this._scroll(this._bodyHeight());
         break;
       case PAGE_DOWN:
         this._scroll(-this._bodyHeight());
         break;
+      case HOME:
+        this._scroll(Number.MAX_SAFE_INTEGER);
+        break;
+      case END:
+        this._scroll(-Number.MAX_SAFE_INTEGER);
+        break;
       default: {
         if (sequence >= "1" && sequence <= "9") this._focus(Number(sequence) - 1);
-        else return;
+        else return false;
       }
     }
 
-    this._paint();
+    return true;
   }
 
-  private _searchKey(sequence: string): void {
+  /** Handle one key while the search box has the keyboard. Always repaints. */
+  private _searchKey(sequence: string): boolean {
     if (sequence === "\r" || sequence === "\n" || sequence === "\x1b") {
       // Enter keeps the filter and hands the keyboard back; Escape drops it.
       this._searching = false;
@@ -348,7 +387,7 @@ export class TabsDeck implements Deck {
 
     const card = this._cards[this._focused];
     if (card) card.scroll = 0;
-    this._paint();
+    return true;
   }
 
   private _focus(index: number): void {
@@ -361,11 +400,36 @@ export class TabsDeck implements Deck {
   private _scroll(by: number): void {
     const card = this._cards[this._focused];
     if (!card) return;
-    const total = this._visibleLines(card).length;
-    const max = Math.max(0, total - this._bodyHeight());
+    const max = Math.max(0, this._visibleLines(card).length - this._bodyHeight());
     card.scroll = Math.min(max, Math.max(0, card.scroll + by));
   }
 
+  /**
+   * Hold a scrolled-up view on the lines it was left on.
+   *
+   * `scroll` counts lines up from the newest, so a busy process would otherwise
+   * drag the window down by one line for every line it printed and the text
+   * somebody stopped to read would slide off the top while they read it. A card
+   * pinned to the bottom (`scroll === 0`) is left alone — that one *should*
+   * follow the output.
+   */
+  private _anchor(card: Card, appended: string): void {
+    if (card.scroll === 0) return;
+    // Only the focused card is ever filtered — `_focus()` clears the search —
+    // so only there can an arriving line be invisible and move nothing.
+    const needle = this._cards[this._focused] === card ? this._search.toLowerCase() : "";
+    const visible = !needle || appended.toLowerCase().includes(needle);
+    // Unfiltered, the count is the buffer's own — worth the branch, because this
+    // runs once per line of output and the buffer holds thousands.
+    const total = needle ? this._visibleLines(card).length : card.lines.length;
+    // Clamped even when nothing was added: at the scrollback cap every new line
+    // evicts an old one, and without this the view would walk off the top.
+    card.scroll = Math.min(
+      card.scroll + (visible ? 1 : 0),
+      Math.max(0, total - this._bodyHeight()),
+    );
+  }
+
   /**
    * Hand the terminal back and print plainly from here on.
    *
@@ -384,7 +448,7 @@ export class TabsDeck implements Deck {
       return;
     }
     this._stream = undefined as StreamDeck | undefined;
-    this._write(ALT_SCREEN_ON + CURSOR_HIDE);
+    this._write(ALT_SCREEN_ON + CURSOR_HIDE + ALT_SCROLL_ON);
     this._stdin.setRawMode?.(true);
     this._paint();
   }
@@ -453,7 +517,7 @@ export class TabsDeck implements Deck {
     const scrolled = card && card.scroll > 0 ? `  ↑${card.scroll}` : "";
     const filtered = this._search ? `  /${this._search}` : "";
     const keys =
-      "1-9 tab · ←/→ cycle · r restart · c clear · / search · t time · s stream · q quit";
+      "1-9 tab · ←/→ cycle · ↑/↓ scroll · r restart · c clear · / search · t time · s stream · q quit";
     return _fit(_paint(keys + filtered + scrolled, "dim"), width);
   }
 
@@ -486,10 +550,70 @@ const CURSOR_HOME = "\x1b[H";
 const CLEAR_LINE = "\x1b[K";
 const CLEAR_BELOW = "\x1b[J";
 
+/**
+ * Alternate scroll: ask the terminal to send cursor keys when the wheel turns.
+ *
+ * On the alternate screen there is no scrollback for the wheel to move, so
+ * without this the wheel does nothing at all and the deck reads as frozen.
+ * Most terminals do it by default, some do not, and asking costs one sequence.
+ * Deliberately *not* mouse tracking (`?1000h` and friends), which would hand us
+ * real wheel events at the price of the terminal's own text selection.
+ */
+const ALT_SCROLL_ON = "\x1b[?1007h";
+const ALT_SCROLL_OFF = "\x1b[?1007l";
+
+const ARROW_UP = "\x1b[A";
+const ARROW_DOWN = "\x1b[B";
 const ARROW_LEFT = "\x1b[D";
 const ARROW_RIGHT = "\x1b[C";
 const PAGE_UP = "\x1b[5~";
 const PAGE_DOWN = "\x1b[6~";
+const HOME = "\x1b[H";
+const END = "\x1b[F";
+
+/** A CSI sequence ends at the first byte in this range; everything before is parameters. */
+const _CSI_END = /[@-~]/;
+
+/**
+ * Split one read from stdin into individual key presses.
+ *
+ * SS3 arrows (`ESC O A`, what a terminal in application cursor mode sends) are
+ * rewritten to their CSI spelling so the switch upstairs only has to know one
+ * form of each key, and text is walked by code point so that an emoji typed
+ * into the search box stays one key rather than two broken halves.
+ */
+function _keys(chunk: string): string[] {
+  const out: string[] = [];
+  let at = 0;
+
+  while (at < chunk.length) {
+    if (chunk[at] !== "\x1b") {
+      const point = String.fromCodePoint(chunk.codePointAt(at)!);
+      out.push(point);
+      at += point.length;
+      continue;
+    }
+
+    const next = chunk[at + 1];
+    if (next === "[") {
+      let end = at + 2;
+      while (end < chunk.length && !_CSI_END.test(chunk[end]!)) end++;
+      // A sequence cut off by the end of the read is passed through whole
+      // rather than split into an Escape and some letters, which is what would
+      // type `[` and `A` into the search box.
+      out.push(chunk.slice(at, end + 1));
+      at = end + 1;
+    } else if (next === "O" && at + 2 < chunk.length) {
+      out.push(`\x1b[${chunk[at + 2]}`);
+      at += 3;
+    } else {
+      out.push("\x1b"); // A bare Escape — the key, not the start of anything.
+      at += 1;
+    }
+  }
+
+  return out;
+}
 
 const STATE_GLYPH: Record<DevProcessStatus["state"], string> = {
   starting: "◌",

package/src/dev/DevOrchestrator.ts

@@ -166,7 +166,7 @@ export class DevOrchestrator {
         cwd: this._cwd,
         env: {
           ...Bun.env,
-          APP_ENV: "web",
+          APP_TYPE: "web",
           // Mark the worker as developer-supervised. APP_ENV above is the
           // runtime mode, not a deployment name, so it cannot carry this —
           // without the flag the worker looks production-like to every

package/src/doctor/HeaderProbe.ts

@@ -0,0 +1,164 @@
+/**
+ * Read a deployed app's security headers from the outside, and report the ones
+ * that arrive twice.
+ *
+ * A header the app sets and the proxy also sets is invisible from inside the
+ * process: the app's own view is the value it wrote, and the app is right about
+ * that. Only a request that has been through the proxy sees both. Deploying
+ * zerotal.dev turned up exactly that — `X-Frame-Options: DENY` from the proxy
+ * and `SAMEORIGIN` from the app, on the same response — and browsers do not
+ * agree on which one wins. A security control that applies inconsistently is
+ * worse than one that is simply absent, because it looks configured.
+ *
+ * ## How a duplicate is visible at all
+ *
+ * `fetch` folds repeated headers into one comma-joined value, so
+ * `X-Frame-Options` sent twice reads back as `"DENY, SAMEORIGIN"`. For headers
+ * whose grammar has no comma in it that is unambiguous evidence of a duplicate.
+ * For `Permissions-Policy` and `Referrer-Policy` it is not — a comma is
+ * legitimate syntax there — so those are deliberately not checked. A probe that
+ * cried wolf on a correct `Permissions-Policy` would be switched off within a
+ * week, and then it would not catch the `X-Frame-Options` either.
+ */
+
+/** One header's finding. */
+export interface HeaderProbeResult {
+  /** The URL that was read. */
+  url: string;
+  /** The header, in the casing it is conventionally written. */
+  header: string;
+  /** The distinct values received, in the order sent. */
+  values: string[];
+  /** False when this needs attention. */
+  ok: boolean;
+  /** Whether the duplicated values disagree — the case browsers handle inconsistently. */
+  conflicting: boolean;
+  message: string;
+  fix?: string;
+}
+
+/**
+ * Headers that take exactly one value, so a comma in the received value means
+ * the header was sent more than once.
+ *
+ * `Permissions-Policy`, `Referrer-Policy` and `Accept-CH` are absent on purpose:
+ * each takes a comma-separated list, so duplication is undetectable this way.
+ */
+const SINGLE_VALUE_HEADERS: Record<string, string> = {
+  "x-frame-options": "X-Frame-Options",
+  "x-content-type-options": "X-Content-Type-Options",
+  "strict-transport-security": "Strict-Transport-Security",
+  "cross-origin-opener-policy": "Cross-Origin-Opener-Policy",
+  "cross-origin-resource-policy": "Cross-Origin-Resource-Policy",
+  "cross-origin-embedder-policy": "Cross-Origin-Embedder-Policy",
+  "x-xss-protection": "X-XSS-Protection",
+};
+
+/**
+ * CSP is its own case: a comma separates *whole policies*, and a browser
+ * enforces every one of them — the effective policy is their intersection. Two
+ * policies that were each written to be sufficient usually intersect into
+ * something that blocks the page.
+ */
+const CSP_HEADERS: Record<string, string> = {
+  "content-security-policy": "Content-Security-Policy",
+  "content-security-policy-report-only": "Content-Security-Policy-Report-Only",
+};
+
+/** Split a folded header value into the values that were actually sent. */
+export function splitFolded(value: string): string[] {
+  return value
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+/**
+ * Inspect a set of response headers for duplicates.
+ *
+ * Exported separately from {@link probeHeaders} so the analysis can be tested
+ * without a network round-trip — the fetch is the only part that needs one.
+ */
+export function analyseHeaders(url: string, headers: Headers): HeaderProbeResult[] {
+  const findings: HeaderProbeResult[] = [];
+
+  for (const [key, label] of Object.entries(SINGLE_VALUE_HEADERS)) {
+    const raw = headers.get(key);
+    if (raw === null) continue;
+    const values = splitFolded(raw);
+    if (values.length < 2) continue;
+
+    const distinct = [...new Set(values.map((value) => value.toLowerCase()))];
+    if (distinct.length > 1) {
+      findings.push({
+        url,
+        header: label,
+        values,
+        ok: false,
+        conflicting: true,
+        message:
+          `sent ${values.length} times with different values (${values.join(" / ")}). ` +
+          `Browsers do not agree on which one applies, so this control is enforced ` +
+          `inconsistently across your visitors.`,
+        fix:
+          `Set ${label} in exactly one place — either the app (config/app.ts → ` +
+          `app.secureHeaders) or the proxy — and remove the other.`,
+      });
+      continue;
+    }
+
+    findings.push({
+      url,
+      header: label,
+      values,
+      ok: false,
+      conflicting: false,
+      message:
+        `sent ${values.length} times with the same value (${values[0]}). Harmless today, ` +
+        `and a conflict the moment either side is changed without the other.`,
+      fix: `Remove the duplicate — keep ${label} in one place.`,
+    });
+  }
+
+  for (const [key, label] of Object.entries(CSP_HEADERS)) {
+    const raw = headers.get(key);
+    if (raw === null) continue;
+    // A comma inside a policy is not valid in the directives apps actually use,
+    // so one here means a second policy was appended.
+    const policies = splitFolded(raw);
+    if (policies.length < 2) continue;
+
+    findings.push({
+      url,
+      header: label,
+      values: policies,
+      ok: false,
+      conflicting: true,
+      message:
+        `${policies.length} separate policies were sent. A browser enforces all of them at ` +
+        `once, so the policy in force is their intersection — usually stricter than either ` +
+        `author intended, and a page that breaks for no visible reason.`,
+      fix: `Send one ${label}, from the app or the proxy but not both.`,
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Fetch `url` and report every duplicated security header on the response.
+ *
+ * Returns an empty array when the request fails: an unreachable URL is the
+ * transport probe's finding to make, and reporting it twice would be noise.
+ */
+export async function probeHeaders(url: string): Promise<HeaderProbeResult[]> {
+  let response: Response;
+  try {
+    // `redirect: "manual"` on purpose: a redirect's own headers are what the
+    // proxy adds, and following it would report the destination's instead.
+    response = await fetch(url, { method: "GET", redirect: "manual" });
+  } catch {
+    return [];
+  }
+  return analyseHeaders(url, response.headers);
+}

package/src/events/Emitter.ts

@@ -270,6 +270,30 @@ export class Emitter {
     return (this._listeners.get(eventClass)?.length ?? 0) > 0;
   }
 
+  /**
+   * Every event with a listener, and the listeners it has, by name.
+   *
+   * The wiring between an application's events and what reacts to them is
+   * spread across every provider that calls `listen()`, so "what happens when an
+   * order is placed" is a question you answer by searching. This is that map,
+   * and it is what the inspector's Events tab draws.
+   *
+   * Names rather than classes, because the answer is read by a human or crosses
+   * a wire — and a listener class is not serialisable either way.
+   *
+   * @returns One row per event with at least one listener, sorted by name.
+   * @category Subscription
+   */
+  registrations(): Array<{ event: string; listeners: string[] }> {
+    return [...this._listeners.entries()]
+      .filter(([, listeners]) => listeners.length > 0)
+      .map(([eventClass, listeners]) => ({
+        event: (eventClass as { name?: string }).name ?? String(eventClass),
+        listeners: listeners.map((listener) => listener.name),
+      }))
+      .sort((a, b) => a.event.localeCompare(b.event));
+  }
+
   /**
    * Remove every registered listener.
    * @category Subscription

package/src/events/FrameworkEvents.ts

@@ -133,6 +133,34 @@ export const FrameworkEvents = {
     for (const handlers of _byKind.values()) count += handlers.size;
     return count;
   },
+
+  /**
+   * Which events currently have subscribers, and how many each has.
+   *
+   * The bus is the framework's nervous system and has been invisible: "does
+   * anything actually listen to `ModelChanged`" was a question you answered by
+   * reading every package. Sorted by name so two calls are comparable.
+   *
+   * Class- and kind-keyed subscriptions are merged, because a subscriber that
+   * listened by string and one that imported the class are subscribed to the
+   * same event and a reader does not care which door they came through.
+   *
+   * @returns One row per event with at least one live handler.
+   * @category Subscription
+   */
+  subscriptions(): Array<{ event: string; handlers: number }> {
+    const counts = new Map<string, number>();
+    for (const [ctor, handlers] of _byClass) {
+      if (handlers.size)
+        counts.set(_kindOf(ctor), (counts.get(_kindOf(ctor)) ?? 0) + handlers.size);
+    }
+    for (const [kind, handlers] of _byKind) {
+      if (handlers.size) counts.set(kind, (counts.get(kind) ?? 0) + handlers.size);
+    }
+    return [...counts.entries()]
+      .map(([event, handlers]) => ({ event, handlers }))
+      .sort((a, b) => a.event.localeCompare(b.event));
+  },
 };
 
 // ── Framework event types ─────────────────────────────────────────────────────
@@ -218,6 +246,20 @@ export class RequestFailed {
     readonly durationMs: number,
     readonly error: string,
     readonly status: number,
+    /**
+     * The error's class name, when the failure was an `Error`.
+     *
+     * `message` alone cannot tell a `ValidationError` from a `TypeError`, and
+     * which one it was is usually the first thing you want to know.
+     */
+    readonly type?: string,
+    /**
+     * The raw `Error.stack`, for subscribers that render a trace.
+     *
+     * Carried as the unparsed string: the shape differs between runtimes, and
+     * this event should not be the thing that decides how a frame is spelled.
+     */
+    readonly stack?: string,
   ) {}
 }
 

package/src/helpers/index.ts

@@ -22,7 +22,11 @@
  */
 import { join } from "node:path";
 import { ConfigError } from "../errors/ConfigError.ts";
-import { DEPLOY_ENV_VAR, RUNTIME_MODES as _RUNTIME_MODES } from "../support/env.ts";
+import {
+  DEPLOY_ENV_VAR,
+  RUNTIME_MODES as _RUNTIME_MODES,
+  RUNTIME_MODE_VAR as _RUNTIME_MODE_VAR,
+} from "../support/env.ts";
 
 // ── basePath() ────────────────────────────────────────────────────────────────
 
@@ -46,13 +50,19 @@ export function basePath(...segments: string[]): string {
 // ── setAppEnv() ───────────────────────────────────────────────────────────────
 
 /**
- * Set `APP_ENV` from the CLI command name — call this in `zerotal.ts` BEFORE
- * the dynamic import of `bootstrap/app.ts` so `Application.create()` sees
- * the correct environment.
+ * Set `APP_TYPE` — the runtime mode — from the CLI command name. Call it in
+ * `zerotal.ts` BEFORE the dynamic import of `bootstrap/app.ts`, so
+ * `Application.create()` sees the mode it should boot providers for.
  *
- * If `APP_ENV` is already set (e.g. from `.env` or the shell), this is a no-op.
+ * **`APP_ENV` is not touched.** That variable holds the deployment name the
+ * operator set, and it is what answers "is this production?". The two used to
+ * share one variable and the mode won, so `APP_ENV=production` read back as
+ * `"console"` in every CLI command — see {@link RUNTIME_MODE_VAR}.
  *
- * | Command              | APP_ENV   |
+ * An `APP_TYPE` already in the environment wins over the command, which is how
+ * the dev orchestrator boots a supervised server as `web`.
+ *
+ * | Command              | APP_TYPE  |
  * |----------------------|-----------|
  * | serve / start / s    | web       |
  * | dev / d              | web       |
@@ -71,41 +81,46 @@ export function setAppEnv(command?: string): void {
   const current = Bun.env["APP_ENV"];
   const environment = Bun.env as Record<string, string>;
 
-  // 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}.
+  // `APP_ENV` is left alone. It holds the deployment name the operator set —
+  // `production`, `staging`, `local` — and it is the only place that answers
+  // "is this production?". This function used to overwrite it with the runtime
+  // mode, which is why six gates asking that question of `Bun.env["APP_ENV"]`
+  // read `"web"` and quietly answered no, including the weak-`APP_KEY` refusal
+  // and the ORM's N+1 detector; a preserved copy patched those, and then
+  // `env("APP_ENV")` still returned `"console"` inside a seeder, because the
+  // copy was only ever read through `deployEnv()`.
   //
-  // 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"`.
+  // Two questions, two variables. The mode goes to `APP_TYPE`.
   if (current && !_RUNTIME_MODES.has(current.toLowerCase())) {
+    // Still mirrored, for anything already reading the preserved copy.
     environment[DEPLOY_ENV_VAR] = current;
   }
 
+  // Deliberately no attempt to "migrate" a legacy `APP_ENV=web` into `APP_TYPE`
+  // and put a deployment name back. `RUNTIME_MODES` contains `test` — which
+  // `zt test` sets as a *deployment* name — so the two sets overlap and any
+  // rewrite here would eventually clobber the one thing this change exists to
+  // protect. `runtimeMode()` reads the legacy location instead, where a wrong
+  // guess costs a mode rather than an environment.
+
+  // An explicit `APP_TYPE` wins: it is how the dev orchestrator tells the server
+  // it supervises to boot as `web` regardless of the command that started it.
+  const explicit = environment[_RUNTIME_MODE_VAR];
+  if (explicit && _RUNTIME_MODES.has(explicit.toLowerCase())) return;
+
   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
+    // provider is only asked if `static environments` includes the mode 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";
-    }
+    environment[_RUNTIME_MODE_VAR] = "web";
   } else if (["worker", "queue:work"].includes(normalizedCommand)) {
-    if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
-      environment["APP_ENV"] = "worker";
-    }
-  } else if (!current || !_RUNTIME_MODES.has(current.toLowerCase())) {
-    // Mirror the serve/worker branches: a deployment-env name like "local" or
-    // "production" must not leave the app in web mode for a CLI command.
-    environment["APP_ENV"] = "console";
+    environment[_RUNTIME_MODE_VAR] = "worker";
+  } else {
+    environment[_RUNTIME_MODE_VAR] = "console";
   }
 }
 

package/src/index.ts

@@ -66,6 +66,7 @@ export type {
   FileRoutingEntry,
   FileRoutingConfig,
   AppScopeInstaller,
+  ProviderReport,
 } from "./application/Application.ts";
 export { ExceptionHandler } from "./application/ExceptionHandler.ts";
 
@@ -161,6 +162,7 @@ export {
 export { config } from "./helpers/config.ts";
 export { pluralize, singularize, snakeCase, camelCase, tableNameFor } from "./support/str.ts";
 export { deepMerge } from "./support/deepMerge.ts";
+export type { DeepPartial } from "./support/deepMerge.ts";
 // The type every class-keyed registry uses — a class rather than an instance.
 export type { ClassRef } from "./support/classRef.ts";
 export { safeEqual, sha256Hex, hmacHex } from "./support/crypto.ts";