@zerotal/core 1.14.2 → 1.15.0

package/CHANGELOG.md

@@ -8,6 +8,85 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.0] — 2026-09-04
+
+### Changed — **BREAKING**
+
+- **BREAKING: a `_middleware.ts` that cannot apply now stops the boot.** Two ways one could
+  fail were silent, and both left the routes it was written to guard live and unguarded.
+  An app where either was happening will now refuse to boot until the file is fixed —
+  which is the point: it was not guarding anything before, and nothing said so. A directory
+  with no `_middleware` file is unchanged and stays silent. See the
+  [Upgrade Guide](/docs/upgrade#114-to-115).
+
+### Fixed
+
+- **A `_middleware.ts` that default-exported its list left the subtree unguarded.** The
+  loader read only `export const middleware`, so `export default [EmployerMiddleware]` was
+  ignored — no warning, no boot error, nothing in `route:list`. The app started, the routes
+  answered, and the directory the file was written to protect served to anyone. `export
+default` is the natural guess: every route file in the same directory default-exports its
+  handler.
+
+  The file now has to export a `middleware` array, and boot fails naming the file and the
+  fix when it does not. Nothing rejected here has ever applied, so no working app changes.
+
+- **An import error in a `_middleware.ts` was swallowed with the missing-file case.** Both
+  shared one `catch`, so a typo, a bad import path, a circular import or a `SyntaxError` all
+  read as "this directory has no middleware" and the routes beneath went on serving — on a
+  hot-reload, a guard that had been there a second earlier.
+
+  Absence and failure are now separate: no file is silent, as the convention intends, and a
+  file that threw stops the boot with the original error and its path. Under `zt dev` the
+  reload aborts and the previously compiled routes keep serving, so the guard never drops.
+
+- **`zt doctor`'s secure-headers check failed on any app behind a reverse proxy.** It read
+  `app.secureHeaders.secure` and inferred the response from it, so a deployment where Caddy
+  or nginx terminates TLS and sets HSTS — the most common production topology for a Bun app
+  — was reported as downgradeable while `curl -I` showed the header present. A check that is
+  wrong on the ordinary case is one people learn to skip.
+
+  It now makes one request to `app.url` on a deployment and reports what came back. When it
+  cannot reach the site, it warns with what it actually knows — the app does not send HSTS,
+  confirm the proxy does — instead of asserting a header is missing. Unreachable is no
+  longer reported as absent.
+
+### Added
+
+- **`zt route:types` regenerates every type file the app generates from its file tree**, not
+  only `types/routes.generated.ts`. `@zerotal/inertia` registers its page registry through
+  the new `registerTypeGenerator`, so adding a page and running the command whose name says
+  it generates types now does. Previously it regenerated the routes half, `Inertia.render`
+  still failed with `TS2345: … not assignable to 'PageName'`, and the error reads as a typo
+  in the page name rather than a registry that has not been rebuilt. `--check` gates on all
+  of them.
+
+- **`zt test` no longer inherits `.env`'s mail, queue, session and cache drivers.** Bun loads
+  `.env` into every process, so a developer with `MAIL_DRIVER=smtp` pointed at a local
+  Postfix got a suite where every path that sends mail opened a real SMTP connection — one
+  test going from milliseconds to a five-second timeout, failing only when run with its
+  siblings, and invisible to anyone without a mail server configured.
+
+  These four now get their in-process defaults (`log`, `sync`, `cookie`, `memory`), which is
+  what the app's own config already defaults to. A value set in the shell still wins, so
+  `MAIL_DRIVER=smtp bun zt test` works; `.env.test` is read and merged last; `--keep-env`
+  turns the whole thing off. The command prints what it changed.
+
+## [1.14.3] — 2026-09-01
+
+### Fixed
+
+- **`zt upgrade` never offered the 1.13.0 migrations.** `deprecated-aliases` bundled two
+  retirements that shipped in 1.13.0 — `serve --dev` and `routes:types` — with the
+  `BaseModel` rename that has not shipped and is scheduled for 2.0. A codemod carries one
+  version, so it took the later one, and `zt upgrade --to 1.13.0` selected nothing at all.
+  The migration for the release that broke `serve --dev` was unreachable by every app
+  crossing it.
+
+  Split into `deprecated-aliases` at 1.13.0 and `base-model-rename` at 2.0.0. An app moving
+  to any 1.13+ release now gets the command rewrites, and one crossing to 2.0 no longer has
+  `BaseModel` renamed as a side effect of a command alias.
+
 ## [1.14.2] — 2026-09-01
 
 ### Fixed

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class AppBooted = {

package/package.json

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

package/src/command/TypeGenerators.ts

@@ -0,0 +1,87 @@
+/**
+ * The registry of generated-type files that `bun zt route:types` refreshes.
+ *
+ * Route names are not the only thing a Zerotal app generates from its own
+ * filesystem — `@zerotal/inertia` emits a page registry that gives
+ * `Inertia.render(name, props)` its typed page names. Both answer the same
+ * question ("what does the tree contain, as types?"), both go stale the moment
+ * a file is added, and `route:types` is the command whose name says it fixes
+ * that. It used to fix only half of it: adding a page and running `route:types`
+ * left the page registry stale, and the resulting error —
+ *
+ *   TS2345: Argument of type '"ops/orders"' is not assignable to 'PageName'
+ *
+ * — reads as "you typed the name wrong" rather than "nothing has regenerated
+ * the registry since you added the file", which sends you looking at the name.
+ *
+ * A view package registers its routine here from provider boot, so
+ * `@zerotal/core` never imports `@zerotal/inertia` (which would be circular).
+ * This mirrors `registerDevBuildHook` in `../dev/DevBuildHook.ts`, for the same
+ * reason and with the same shape.
+ */
+
+/**
+ * What one generator wrote, for the command's summary output.
+ *
+ * @internal Part of the {@link registerTypeGenerator} contract, like
+ * {@link TypeGeneratorFn} — framework-package plumbing, not app-facing API.
+ */
+export interface TypeGeneratorResult {
+  /** The file written, relative to the project root. */
+  file: string;
+  /** What it contains, phrased for a summary line (e.g. `12 pages`). */
+  summary: string;
+  /**
+   * Whether the file on disk differed from what the routine produced. Drives
+   * `route:types --check`, and lets the command say "Unchanged" rather than
+   * claiming a write it did not need to make.
+   */
+  changed: boolean;
+}
+
+/**
+ * A generated-types routine. `check` asks it to compare against disk and report,
+ * without writing — the CI gate that keeps a committed generated file honest.
+ *
+ * @internal
+ */
+export type TypeGeneratorFn = (options: { check: boolean }) => Promise<TypeGeneratorResult>;
+
+const _generators = new Map<string, TypeGeneratorFn>();
+
+/**
+ * @internal Exported for view packages to wire their codegen into `route:types`.
+ *
+ * Register a generated-types routine under a package name. Registering the same
+ * name twice replaces the earlier routine, so a provider may safely register on
+ * every boot.
+ */
+export function registerTypeGenerator(name: string, fn: TypeGeneratorFn): void {
+  _generators.set(name, fn);
+}
+
+/** @internal Forget every registered routine (tests only). */
+export function _resetTypeGenerators(): void {
+  _generators.clear();
+}
+
+/**
+ * @internal Run every registered routine, in registration order.
+ *
+ * One routine throwing does not stop the others — a broken page registry should
+ * not cost you your route types — but the error is returned rather than
+ * swallowed, so the command can report it and exit non-zero.
+ */
+export async function _runTypeGenerators(options: {
+  check: boolean;
+}): Promise<{ name: string; result?: TypeGeneratorResult; error?: unknown }[]> {
+  const outcomes: { name: string; result?: TypeGeneratorResult; error?: unknown }[] = [];
+  for (const [name, fn] of _generators) {
+    try {
+      outcomes.push({ name, result: await fn(options) });
+    } catch (error) {
+      outcomes.push({ name, error });
+    }
+  }
+  return outcomes;
+}

package/src/command/builtin/RouteTypesCommand.ts

@@ -2,25 +2,34 @@ import { Command } from "../Command.ts";
 import type { FlagDef } from "../Command.ts";
 import { Router } from "../../router/Router.ts";
 import { writeRouteTypes, ROUTE_TYPES_FILE } from "../../router/routeTypes.ts";
+import { _runTypeGenerators } from "../TypeGenerators.ts";
 
 /**
- * `bun zt route:types` — write `types/routes.generated.ts`, the name → pattern
- * map that makes `route()` type-checked.
+ * `bun zt route:types` — refresh every type file the app generates from its own
+ * filesystem: `types/routes.generated.ts`, the name → pattern map that makes
+ * `route()` type-checked, plus whatever the installed view packages register
+ * (`@zerotal/inertia` adds its page registry, which types `Inertia.render`).
+ *
+ * It generates more than routes because a developer who adds a page and gets a
+ * type error about its name reaches for the command whose name says it
+ * generates types — and used to get the same error back, having regenerated the
+ * wrong half. Both files answer "what does the tree contain, as types?", and
+ * both go stale on the same edits.
  *
  * Boots the application (`needsApp`) and reads `Router.namedRoutes`, so routes
  * a provider registers programmatically and names set via a route file's
  * `export const meta` are included — not just what the file-router's naming
  * convention would produce.
  *
- * Commit the generated file: editors and CI need it without booting the app.
- * `zt dev` refreshes it on every restart, and `--check` fails when the file on
- * disk no longer matches the routes, which is the CI gate that keeps it honest.
+ * Commit the generated files: editors and CI need them without booting the app.
+ * `zt dev` refreshes them on every restart, and `--check` fails when a file on
+ * disk no longer matches, which is the CI gate that keeps them honest.
  *
  * @category Diagnostics
  */
 export class RouteTypesCommand extends Command {
   static commandName = "route:types";
-  static description = "Generate types/routes.generated.ts for typed route() names";
+  static description = "Generate the app's type files (routes, and any view package's registry)";
   static needsApp = true;
   static args = [];
   static flags: FlagDef[] = [
@@ -35,23 +44,51 @@ export class RouteTypesCommand extends Command {
   async run(): Promise<void> {
     const check = this.flags["check"] as boolean;
 
-    const result = await writeRouteTypes(Router.namedRoutes, { check });
+    const routes = await writeRouteTypes(Router.namedRoutes, { check });
+
+    // The routes file, then whatever the installed view packages register — the
+    // Inertia page registry, today. Collected into one list so the command reports
+    // every generated file the same way, and so a failure in one does not cost
+    // you the other: half-regenerated types are how this got confusing to begin with.
+    const files: { file: string; summary: string; changed: boolean }[] = [
+      {
+        file: ROUTE_TYPES_FILE,
+        summary: `${routes.count} named routes`,
+        changed: routes.changed,
+      },
+    ];
+    let failed = false;
+
+    for (const { name, result, error } of await _runTypeGenerators({ check })) {
+      if (error) {
+        failed = true;
+        this.error(`${name}: ${error instanceof Error ? error.message : String(error)}`);
+        continue;
+      }
+      if (result) files.push(result);
+    }
 
     if (check) {
-      if (result.changed) {
-        this.error(`${result.path} is out of date. Run: bun zt route:types`);
-        throw new Error("Route types are out of date.");
+      const stale = files.filter((f) => f.changed);
+      for (const f of files) {
+        if (f.changed) this.error(`${f.file} is out of date. Run: bun zt route:types`);
+        else this.info(`${f.file} is up to date (${f.summary}).`);
+      }
+      if (stale.length > 0) {
+        throw new Error(`Generated types are out of date: ${stale.map((f) => f.file).join(", ")}`);
       }
-      this.info(`${result.path} is up to date (${result.count} named routes).`);
+      if (failed) throw new Error("A type generator failed.");
       return;
     }
 
-    if (result.count === 0) {
+    if (routes.count === 0) {
       this.warn("No named routes found — the generated map is empty.");
     }
 
-    this.info(
-      `${result.changed ? "Wrote" : "Unchanged"}: ${ROUTE_TYPES_FILE} (${result.count} named routes)`,
-    );
+    for (const f of files) {
+      this.info(`${f.changed ? "Wrote" : "Unchanged"}: ${f.file} (${f.summary})`);
+    }
+
+    if (failed) throw new Error("A type generator failed.");
   }
 }

package/src/command/builtin/TestCommand.ts

@@ -1,5 +1,6 @@
 import { Command } from "../Command.ts";
 import { bunBinary } from "../../support/runtime.ts";
+import { testEnvOverrides } from "../testEnv.ts";
 
 /**
  * `bun zt test [pattern] [flags]` — runs the test suite in the test environment.
@@ -11,6 +12,9 @@ import { bunBinary } from "../../support/runtime.ts";
  *    withDatabase() and DB.table() work without manual beforeAll boilerplate.
  *  - If @zerotal/testing is not installed the preload is silently skipped —
  *    tests that use createTestApp() still work without it.
+ *  - Resets the driver keys `.env` would otherwise lend the suite (mail, queue,
+ *    session, cache) to their in-process defaults, and loads `.env.test` when
+ *    the app has one. See `../testEnv.ts` for why, and `--keep-env` to opt out.
  *
  * All positional args and recognised flags are forwarded to bun test.
  *
@@ -72,6 +76,12 @@ export class TestCommand extends Command {
       description: "Run database/migrations against the test database before the suite",
       default: false,
     },
+    {
+      name: "keep-env",
+      type: "boolean" as const,
+      description: "Inherit .env's mail/queue/session/cache drivers instead of resetting them",
+      default: false,
+    },
   ];
 
   async run(): Promise<void> {
@@ -122,7 +132,18 @@ export class TestCommand extends Command {
     const timeout = (this.flags["timeout"] as number | undefined) || TestCommand.DEFAULT_TIMEOUT_MS;
     bunArguments.push(`--timeout=${timeout}`);
 
+    // `.env` is written for `zt dev`; a test run should decide for itself which
+    // outbound services it reaches. Reported rather than applied silently — a
+    // suite that behaves differently from the same code under `zt dev` has to
+    // say so, or the next person debugs the difference instead of reading it.
+    const { overrides, neutralised } = this.flags["keep-env"]
+      ? { overrides: {}, neutralised: [] as string[] }
+      : await testEnvOverrides(process.cwd(), Bun.env as Record<string, string | undefined>);
+
     this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}  bun ${Bun.version}`);
+    if (neutralised.length > 0) {
+      this.dim(`Reset for tests: ${neutralised.join("  ")}  (keep .env's with --keep-env)`);
+    }
     this.dim(`bun ${bunArguments.join(" ")}\n`);
 
     // `bunBinary()`, not `"bun"`. The child of a command whose entire job is to run
@@ -136,6 +157,7 @@ export class TestCommand extends Command {
       stderr: "inherit",
       env: {
         ...Bun.env,
+        ...overrides,
         APP_ENV: "test",
         ZT_DB_URL: dbUrl,
       } as Record<string, string | undefined>,

package/src/command/builtin/index.ts

@@ -60,3 +60,10 @@ export { AssetsBuildCommand } from "./AssetsBuildCommand.ts";
 export { AssetsPruneCommand } from "./AssetsPruneCommand.ts";
 export { LintPackagesCommand } from "./LintPackagesCommand.ts";
 export { MakePackageCommand } from "./MakePackageCommand.ts";
+
+// Extension point rather than a command: lets a view package add its own
+// generated-types file to `zt route:types`, so one command refreshes every type
+// file an app generates from its file tree. `@zerotal/inertia` registers its page
+// registry here. See ../TypeGenerators.ts.
+export { registerTypeGenerator } from "../TypeGenerators.ts";
+export type { TypeGeneratorFn, TypeGeneratorResult } from "../TypeGenerators.ts";

package/src/command/testEnv.ts

@@ -0,0 +1,140 @@
+/**
+ * The environment `bun zt test` hands its child, and the one thing it takes away.
+ *
+ * Bun loads `.env` into every process it starts, so a test run inherits the
+ * developer's whole local setup — including the driver keys that decide whether
+ * a code path talks to something real. A developer with `MAIL_DRIVER=smtp`
+ * pointed at a local Postfix gets a suite where every path that sends mail opens
+ * an SMTP connection: one confirmed payment that issues an invitation goes from
+ * milliseconds to a five-second timeout, and fails only when run with its
+ * siblings. A developer with no mail server configured never sees it, which
+ * makes it precisely the kind of failure that lands on one person and looks
+ * like flakiness to everyone else.
+ *
+ * So the drivers below are reset for the test child. Not because `.env` is
+ * wrong — it is right for `zt dev`, which is what it was written for — but
+ * because "which outbound service does this reach" is a question a test run
+ * should answer for itself. The app's own config already defaults to the same
+ * safe values; it is only `.env` that overrides them.
+ *
+ * Two things still win over this:
+ *  - a value set in the shell (`MAIL_DRIVER=smtp bun zt test`), which is
+ *    someone deliberately testing that path;
+ *  - a value in `.env.test`, which is the same intent written down. Bun only
+ *    loads that file when `NODE_ENV=test`, so it is read here explicitly rather
+ *    than left as a file the docs mention and nothing loads.
+ */
+
+/**
+ * Driver keys reset for a test run, and what they are reset to. Each default is
+ * the in-process option: no socket, no external service, no shared state between
+ * runs — and each is already the app config's own default.
+ */
+export const TEST_SAFE_DRIVERS: Readonly<Record<string, string>> = {
+  /** Writes the message to the log instead of opening an SMTP connection. */
+  MAIL_DRIVER: "log",
+  /** Runs a dispatched job inline, so a test sees its effects without a worker. */
+  QUEUE_DRIVER: "sync",
+  /** Keeps the session in the cookie rather than reaching for Redis. */
+  SESSION_DRIVER: "cookie",
+  /** In-process cache, so one test file cannot see another's entries. */
+  CACHE_DRIVER: "memory",
+};
+
+/**
+ * Parse a dotenv file into a map. Deliberately small: this is used to find out
+ * *which keys a file mentions*, not to load anything — Bun has already loaded
+ * `.env` by the time this runs, and re-implementing its full semantics here
+ * would only produce a second, disagreeing answer.
+ *
+ * @param text - Raw file contents.
+ * @returns Key → value, with surrounding quotes stripped.
+ */
+export function parseDotenv(text: string): Map<string, string> {
+  const entries = new Map<string, string>();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+
+    const key = line
+      .slice(0, eq)
+      .trim()
+      .replace(/^export\s+/, "");
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+
+    let value = line.slice(eq + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
+      value = value.slice(1, -1);
+    } else {
+      // Unquoted values run to a trailing comment, matching dotenv.
+      value = value.replace(/\s+#.*$/, "");
+    }
+    entries.set(key, value);
+  }
+  return entries;
+}
+
+/** Read and parse a dotenv file, or an empty map when it does not exist. */
+async function _read(path: string): Promise<Map<string, string>> {
+  const text = await Bun.file(path)
+    .text()
+    .catch(() => null);
+  return text === null ? new Map() : parseDotenv(text);
+}
+
+/**
+ * Work out what to change about the child process's environment.
+ *
+ * @param cwd - Project root holding the dotenv files.
+ * @param env - The parent's environment, as the child would otherwise inherit it.
+ * @returns Keys to override, and the subset of those that were neutralised drivers (for reporting).
+ */
+export async function testEnvOverrides(
+  cwd: string,
+  env: Record<string, string | undefined>,
+): Promise<{ overrides: Record<string, string>; neutralised: string[] }> {
+  const [dotenv, dotenvLocal, dotenvTest] = await Promise.all([
+    _read(`${cwd}/.env`),
+    _read(`${cwd}/.env.local`),
+    _read(`${cwd}/.env.test`),
+  ]);
+
+  const overrides: Record<string, string> = {};
+  const neutralised: string[] = [];
+
+  for (const [key, safe] of Object.entries(TEST_SAFE_DRIVERS)) {
+    const current = env[key];
+
+    // Unset means the app config's default applies, which is already the safe
+    // one — setting it anyway would only paper over a config the app changed
+    // on purpose.
+    if (current === undefined) continue;
+
+    // Already safe: nothing to say, and nothing to report.
+    if (current === safe) continue;
+
+    // Set in the shell rather than in a file — someone testing this path on
+    // purpose. Inferred by comparing against what the files declare, which is
+    // the only handle available: Bun merges dotenv into the environment before
+    // any of this runs, and does not record where a value came from.
+    const fromFile = dotenv.get(key) === current || dotenvLocal.get(key) === current;
+    if (!fromFile) continue;
+
+    overrides[key] = safe;
+    neutralised.push(`${key}=${safe}`);
+  }
+
+  // `.env.test` last: it is the app saying what a test run should use, which
+  // outranks both the inherited value and the default chosen here.
+  for (const [key, value] of dotenvTest) {
+    overrides[key] = value;
+    const index = neutralised.findIndex((entry) => entry.startsWith(`${key}=`));
+    if (index !== -1) neutralised.splice(index, 1);
+  }
+
+  return { overrides, neutralised };
+}

package/src/doctor/AppDoctor.ts

@@ -351,22 +351,88 @@ const corsWildcardCheck: DoctorCheck = {
  * 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.
+ *
+ * The header is the only thing that settles this, and the header is not always the
+ * app's to send. Reading `app.secureHeaders.secure` and inferring the response from
+ * it failed on the most ordinary production topology there is: a reverse proxy
+ * terminating TLS and setting HSTS itself. The app's config is then correctly
+ * false, the header is correctly present, and the check said the site could be
+ * downgraded — a wrong answer on a check that is otherwise reliable enough to be
+ * read, which is how a check becomes the line people learn to skip.
+ *
+ * So it probes when it can (`--url`, or `app.url` on a deployment: the response is
+ * the only thing that answers the question) and, when it cannot, says what it
+ * actually knows — the app does not send HSTS — rather than what it was guessing.
  */
 const secureHeadersCheck: DoctorCheck = {
   id: "secure-headers",
   label: "Secure headers",
-  run(app) {
+  async 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.",
+
+    // One request to the public URL, which is the only view that includes the
+    // proxy. A loopback `app.url` on a deployment is its own finding, already
+    // reported by the transport-origins check.
+    const url = _config(app, "app.url");
+    if (typeof url === "string" && url !== "" && !_isLoopback(url)) {
+      const observed = await _observedHsts(url);
+      if (observed === true) {
+        return ok(`HSTS served by the proxy (${url}) — the app does not set it.`);
+      }
+      if (observed === false) {
+        return fail(
+          `No Strict-Transport-Security on ${url}: neither the app nor anything in ` +
+            `front of it sends it, so the first request of each visit can be downgraded ` +
+            `to HTTP.`,
+          "Set app.secureHeaders.secure: true in config/app.ts, or add the header at the proxy.",
+        );
+      }
+      // Unreachable: the deployment may not be up yet, or `doctor` may be running
+      // somewhere that cannot see the public URL. That is not evidence either way.
+    }
+
+    return warn(
+      "app.secureHeaders.secure is not true, so the app does not send " +
+        "Strict-Transport-Security. If a reverse proxy terminates TLS it may be sending " +
+        "it — confirm there; if nothing does, the first request of each visit can be " +
+        "downgraded to HTTP.",
+      `Check with: curl -sI ${typeof url === "string" && url !== "" ? url : "https://your-site"} | grep -i strict-transport-security\n` +
+        "    Then either set app.secureHeaders.secure: true in config/app.ts, or leave it " +
+        "to the proxy — but not both, which sends the header twice.",
     );
   },
 };
 
+/**
+ * Whether the deployed site answers with `Strict-Transport-Security`.
+ *
+ * `null` when the request could not be made at all, which is different from "no
+ * header" and must not be reported as one.
+ */
+async function _observedHsts(url: string): Promise<boolean | null> {
+  try {
+    const response = await fetch(url, {
+      method: "HEAD",
+      // `redirect: "manual"`: the redirect's own response is the one the proxy wrote,
+      // and following it would report the destination's headers instead.
+      redirect: "manual",
+      // `doctor` is what people run immediately after a deploy, so it may not hang on
+      // an unreachable host — a diagnostic that stops responding is worse than one
+      // that says it could not tell. A timeout lands in the `catch` as `null`, which
+      // is already "no evidence either way" rather than "no header".
+      signal: AbortSignal.timeout(_PROBE_TIMEOUT_MS),
+    });
+    return response.headers.get("strict-transport-security") !== null;
+  } catch {
+    return null;
+  }
+}
+
+/** How long the HSTS probe waits before reporting that it could not tell. */
+const _PROBE_TIMEOUT_MS = 5_000;
+
 /**
  * A rate limiter behind a proxy that was never told about the proxy keys every
  * visitor to the same bucket, because the socket address is the proxy's. It then

package/src/index.ts

@@ -245,6 +245,9 @@ export type {
 } from "./router/Route.ts";
 export { scanFileRoutes, registerFileRouteResolver } from "./router/FileRouter.ts";
 export type { FileRouteResolver, FileRouteContext } from "./router/FileRouter.ts";
+// `registerTypeGenerator` — the hook that lets a view package add its own
+// generated-types file to `zt route:types` — lives on `@zerotal/core/commands`,
+// not here: it is command plumbing, and this barrel is the frozen lean kernel.
 export type {
   FileHandler,
   RouteModule,

package/src/router/FileRouter.ts

@@ -312,25 +312,73 @@ async function _collectMiddleware(
     // sibling routes stayed live and unguarded, with no error and no log. A convention
     // that fails open is worse than one that does not exist.
     const middlewarePath = await _findMiddlewareFile(baseDir, dir);
+    // No file is the convention working — most directories have none. Everything past
+    // this point is a file somebody wrote in order to guard a subtree, so every way it
+    // can fail to apply is loud. These two cases used to share one `catch`, which made
+    // "there is no middleware here" and "the middleware is broken" indistinguishable.
+    if (!middlewarePath) continue;
+
+    // Convert to a file:// URL so dynamic import works on Windows (raw
+    // absolute paths with backslashes are not valid import specifiers).
+    // Append ?t=<reloadId> to bust the module cache on hot-reload.
+    const href = pathToFileURL(middlewarePath).href;
+    const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
+
+    let loadedModule: MiddlewareModule & { default?: unknown };
     try {
-      if (middlewarePath) {
-        // Convert to a file:// URL so dynamic import works on Windows (raw
-        // absolute paths with backslashes are not valid import specifiers).
-        // Append ?t=<reloadId> to bust the module cache on hot-reload.
-        const href = pathToFileURL(middlewarePath).href;
-        const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
-        const loadedModule = (await import(importUrl)) as MiddlewareModule;
-        if (Array.isArray(loadedModule.middleware)) {
-          result.push(...loadedModule.middleware);
-        }
-      }
-    } catch {
-      // The file is missing or failed to import — skip it.
+      loadedModule = (await import(importUrl)) as MiddlewareModule & { default?: unknown };
+    } catch (error) {
+      // A typo, a bad import path, a circular import, a SyntaxError — swallowing any of
+      // these left the subtree beneath serving normally with its guard silently gone,
+      // and on a hot-reload, gone a second after it was there. Boot stops instead.
+      throw new Error(
+        `[Zerotal] Failed to import ${middlewarePath}: ` +
+          `${error instanceof Error ? error.message : String(error)}\n` +
+          `Routes under this directory would serve unguarded, so boot stops here. ` +
+          `Fix the file, or delete it if the subtree needs no middleware.`,
+        { cause: error },
+      );
+    }
+
+    if (Array.isArray(loadedModule.middleware)) {
+      result.push(...loadedModule.middleware);
+      continue;
     }
+
+    // The file loaded and exports nothing the loader can apply — the same fail-open in
+    // a different disguise. `export default` is the common one: every route file in the
+    // same directory default-exports its handler, so it is the natural guess, and it
+    // used to leave the subtree open while looking exactly like a guarded one. Throwing
+    // cannot break a working app, because no shape rejected here has ever applied.
+    throw new Error(_middlewareExportError(middlewarePath, loadedModule));
   }
   return result;
 }
 
+/**
+ * The boot error for a `_middleware` file that exports nothing the loader can apply,
+ * naming the specific mistake so the message carries its own fix.
+ */
+function _middlewareExportError(
+  path: string,
+  loadedModule: MiddlewareModule & { default?: unknown },
+): string {
+  const fix = "  export const middleware = [YourMiddleware];";
+  const head = `[Zerotal] ${path} does not export a \`middleware\` array, so it guards nothing.`;
+
+  if (loadedModule.default !== undefined) {
+    return (
+      `${head}\n` +
+      `It has a \`default\` export, which this file does not use — route files ` +
+      `default-export their handler, but a _middleware file is read by name:\n${fix}`
+    );
+  }
+  if (loadedModule.middleware !== undefined) {
+    return `${head}\n\`middleware\` must be an array, even for a single entry:\n${fix}`;
+  }
+  return `${head}\nAdd the export, or delete the file if the subtree needs no middleware:\n${fix}`;
+}
+
 /**
  * Combine the stacked `_middleware.ts` chain (`base`) with a route file's own
  * `export const middleware` for a specific verb. Array form applies to every method;

package/src/upgrade/codemods/deprecated-aliases.ts

@@ -1,24 +1,19 @@
 /**
  * Ledger #4 — retire the deprecated aliases.
  *
- * Three pairs, each a live alias somebody depends on, which is exactly why they
- * could not be dropped in a minor:
+ * Two codemods, not one, because they retire at different times and a codemod
+ * carries a single version:
  *
- * - `BaseModel` → `Model`. The same class object under its original name.
- * - `routes:types` → `route:types`. Registered as an alias in `CommandRunner`.
- * - `serve --dev` → `dev`. The flag still works; `dev` is the command it became.
+ * - {@link deprecatedAliases} at **1.13.0** — `routes:types` → `route:types` and
+ *   `serve --dev` → `dev`. Both shipped; both fail loudly now.
+ * - {@link baseModelRename} at **2.0.0** — `BaseModel` → `Model`. Not shipped;
+ *   sized on 1 Sep 2026 at 617 api-surface references and moved to 2.0.
  *
- * ## What this deliberately does not do
- *
- * **It does not touch `BaseModel` in a type position.** `Model` and `BaseModel`
- * are the same runtime class, so a value-position rename is cosmetic and safe.
- * In a generic bound — `<T extends BaseModel>` — the name may be load-bearing
- * for a reader even though it resolves identically, and in framework source it
- * genuinely is. Those are reported for a person instead.
- *
- * That asymmetry is the whole reason this is a codemod rather than a
- * find-and-replace: the mixin-composition script learned it the hard way in
- * 1.3.0, where a blind rename broke import specifiers it had not considered.
+ * They were one codemod, which forced one version, which took the later of the
+ * two — so `zt upgrade --to 1.13.0` selected nothing and offered no help
+ * migrating the very release that retired `serve --dev`, while an app crossing to
+ * 2.0 would have had its `BaseModel` renamed as a side effect of a command alias.
+ * A codemod nobody's upgrade reaches is a codemod that does not exist.
  */
 import type { Change, Codemod, CodemodResult, Manual, SourceFile } from "../types.ts";
 
@@ -52,10 +47,53 @@ const COMMAND_ALIASES: { find: RegExp; replace: string; label: string }[] = [
   },
 ];
 
+/** The command aliases retired in 1.13.0. Both fail loudly rather than drifting. */
 export const deprecatedAliases: Codemod = {
-  version: "2.0.0",
+  version: "1.13.0",
   name: "deprecated-aliases",
-  description: "Retire BaseModel, routes:types and serve --dev in favour of their real names",
+  description: "Retire routes:types and serve --dev in favour of their real names",
+  ledger: 4,
+
+  run(files: SourceFile[]): CodemodResult {
+    const changes: Change[] = [];
+
+    for (const { file, contents } of files) {
+      let next = contents;
+      const notes: string[] = [];
+
+      for (const { find, replace, label } of COMMAND_ALIASES) {
+        const hits = next.match(find)?.length ?? 0;
+        if (hits === 0) continue;
+        next = next.replace(find, replace);
+        notes.push(`${hits} × ${label}`);
+      }
+
+      if (next !== contents) changes.push({ file, summary: notes.join(", "), contents: next });
+    }
+
+    return { changes, manual: [] };
+  },
+};
+
+/**
+ * `BaseModel` → `Model`, which has **not shipped** and is scheduled for 2.0.
+ *
+ * ## What this deliberately does not do
+ *
+ * **It does not touch `BaseModel` in a type position.** `Model` and `BaseModel`
+ * are the same runtime class, so a value-position rename is cosmetic and safe.
+ * In a generic bound — `<T extends BaseModel>` — the name may be load-bearing
+ * for a reader even though it resolves identically, and in framework source it
+ * genuinely is. Those are reported for a person instead.
+ *
+ * That asymmetry is the whole reason this is a codemod rather than a
+ * find-and-replace: the mixin-composition script learned it the hard way in
+ * 1.3.0, where a blind rename broke import specifiers it had not considered.
+ */
+export const baseModelRename: Codemod = {
+  version: "2.0.0",
+  name: "base-model-rename",
+  description: "Rename BaseModel to Model at every declaration site",
   ledger: 4,
 
   run(files: SourceFile[]): CodemodResult {
@@ -88,13 +126,6 @@ export const deprecatedAliases: Codemod = {
         notes.push("import specifier updated");
       }
 
-      for (const { find, replace, label } of COMMAND_ALIASES) {
-        const hits = next.match(find)?.length ?? 0;
-        if (hits === 0) continue;
-        next = next.replace(find, replace);
-        notes.push(`${hits} × ${label}`);
-      }
-
       // Type positions are a handover, not a rewrite.
       contents.split("\n").forEach((line, i) => {
         if (!BASE_MODEL_TYPE.test(line)) return;

package/src/upgrade/codemods/index.ts

@@ -8,9 +8,9 @@
  * that rule fails is by everyone assuming there is time.
  */
 import type { Codemod } from "../types.ts";
-import { deprecatedAliases } from "./deprecated-aliases.ts";
+import { deprecatedAliases, baseModelRename } from "./deprecated-aliases.ts";
 import { clientTaggedTemplate } from "./client-tagged-template.ts";
 
-export const CODEMODS: Codemod[] = [clientTaggedTemplate, deprecatedAliases];
+export const CODEMODS: Codemod[] = [clientTaggedTemplate, deprecatedAliases, baseModelRename];
 
-export { deprecatedAliases, clientTaggedTemplate };
+export { deprecatedAliases, baseModelRename, clientTaggedTemplate };