@zerotal/core 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -8,6 +8,357 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Added
+
+- **`bun zt deploy:<env>` — a release that refuses to finish when something is wrong.**
+  The pieces already existed: `zt doctor` finds silent misconfigurations, config
+  validators refuse an insecure production boot, `assets:build` builds a release,
+  `migrate` applies the schema. What was missing was an order, and the order is the
+  value: **everything that can refuse runs before anything that mutates.** A bad
+  origin list stops the deploy while the old release is still serving, instead of
+  after the migration has run and the new process is live and inert.
+
+  Four phases — preflight (this really is that environment; every config validator
+  re-run with production semantics; `doctor`), build, migrate, verify. It exits
+  non-zero and **does not restart your service**: systemd or your container runtime
+  owns process lifecycle, and this gives it a gate to restart behind.
+
+  Every environment gets its own command. `production` and `staging` exist without
+  configuration; `config/deploy.ts` declares more, each with an optional public URL
+  and its own step list. The target name is checked against the deployment the
+  process was actually started as, so `deploy:production` on a staging box stops on
+  the first line rather than migrating the wrong database.
+
+  `--dry-run` prints the plan, `--skip-migrations` releases without touching the
+  schema, `--probe` runs a real WebSocket handshake against the deployed site.
+
+- **Two new `doctor` checks, for the two settings nothing was watching.**
+  `app.cors.origin: "*"` lets any website read this app's responses out of a
+  visitor's browser — and it was what every scaffolded app shipped with, because the
+  templates set it while the framework's own default was the safe empty list.
+  `app.secureHeaders.secure` gates HSTS, defaults to false, and had no production
+  detection anywhere, so a deployment that never set it sent no
+  `Strict-Transport-Security` at all. Both fail on a production-like deployment and
+  stay quiet locally.
+
+### Fixed
+
+- **A weak `APP_KEY` never actually refused a production boot.** The check asked
+  `isProdLike(Bun.env["APP_ENV"])` — but `setAppEnv()` overwrites that variable with
+  the runtime mode (`web`/`console`/`worker`) before the app is created, so the
+  answer was always "no" and the refusal this code exists for had never once fired.
+
+  `APP_ENV` carries two meanings and the second destroys the first. `setAppEnv()`
+  now preserves the deployment name, and `deployEnv()` reads it back. Prefer it to
+  `Bun.env["APP_ENV"]` for any production decision.
+
+- **`staging` was production for some purposes and not others.** `isProdLike`
+  accepted it — so config validation refused an insecure staging boot — while
+  `App.isProduction()`, the doctor, the boot-build policy and the asset-minify
+  default all excluded it. A staging box therefore got production-grade config
+  refusal alongside unminified assets and a boot-time asset build, which is the one
+  environment where the read-only restart loop was still reachable. All of them now
+  agree.
+
+- **`app.secureHeaders` could not be configured beyond `frameOptions`.** The
+  middleware reads the whole block and layers it over its defaults, so every option
+  had always worked — but only `frameOptions` was declared on the type, which made
+  the rest a type error to write down. `secure` is the one that mattered: HSTS is
+  emitted only when it is true, so an app had no supported way to turn HSTS on.
+
+- **`assets:build` and `doctor` killed the process instead of failing.** Both called
+  `process.exit(1)` directly, so composing either through `callInProcess` ended the
+  caller — and in the doctor's case its buffered report was never flushed, so the
+  failure arrived with nothing explaining it. Both throw now; the CLI exit code is
+  unchanged.
+
+- **The development error page can now say what to do, not just what broke.**
+  `no such table: assets` is exact about the failure and useless about the cause:
+  every frame in its stack is inside the SQL driver, because that is where the
+  error surfaced rather than where it came from.
+
+  `registerErrorDiagnoser()` lets the package that owns an error class contribute
+  a diagnosis — a title, a paragraph, supporting specifics, and optionally a
+  button — rendered above the stack. `@zerotal/orm` registers the first one; see
+  its changelog. Diagnosers run in order, the first match wins, and one that
+  throws is skipped rather than replacing a real stack trace with a stack trace
+  about the diagnoser.
+
+  A diagnosis with an `action` changes server state from a page rendered by a
+  GET, so the type carries the values and the _endpoint_ owns the safety. That is
+  stated on the type, because the alternative is each implementor rediscovering
+  it.
+
+- **Typed route names — `bun zt route:types`.** The command boots the app, reads the
+  routes it registered, and writes `types/routes.generated.ts`: a name → URL pattern map
+  plus a one-line `RouteRegistry` augmentation. With it, `route("psots.show")` and
+  `route("posts.show", {})` are compile errors, and the second one names the `slug` it
+  wants. Params are derived from the pattern, so adding a segment changes one string and
+  every call site updates with it.
+
+  It boots rather than scanning `routes/` because a route name comes from three places
+  and only one is a file path — the file-router's convention, a route file's
+  `export const meta = { GET: { name } }`, and programmatic registrations, including a
+  package provider's. A scanner sees the first and quietly misses the other two, and a
+  second implementation of the naming rules is a second implementation to disagree with
+  the first.
+
+  Freshness has three parts, because a generated file that is only right after someone
+  remembers to run a command is wrong in every fresh checkout: `zt dev` rewrites it on
+  every restart, the file is committed so editors and CI need no boot, and
+  `route:types --check` fails when the tree has drifted from it. Until the file exists,
+  the registry is empty and `route()` behaves exactly as before.
+
+- **`route.dynamic(name, params?, query?)`** — the escape hatch for a route name that is
+  only known at runtime (read from config, chosen by a package). Deliberately a separate
+  function rather than a `string` overload on `route()`: an overload that accepts every
+  string is matched by every string, which would have made the checked signature
+  decorative. Typed names also flow through `redirect().to()`, `redirectTo()`,
+  `Url.route()` and `Uri.route()`.
+
+- **`app.allowedOrigins` is declared config, and defaults to the origin of `app.url`.**
+  WebSocket upgrades and raw routes bypass the middleware pipeline, so each carries its
+  own `Origin` check against the app's own origin — which behind a reverse proxy is the
+  loopback address it bound to, never the public URL a browser sends. The runtime already
+  read `allowedOrigins`, but `AppConfigShape` did not declare it, so the only way to set
+  it was to spread it onto the exported config and the type system said nothing. Unset, a
+  proxied app renders every page correctly and refuses every credentialed action with a
+  403 — quieter than a 500, invisible in the logs, and passing any health check that reads
+  a status code.
+
+  It is now a first-class field, filled from `url`, and unions rather than replaces: an
+  app naming a second origin does not mean "and stop trusting my own public URL".
+
+- **`bun zt doctor --url=…` probes the deployed transport from the outside.** Every other
+  check runs inside the process, and the expensive proxy failures are exactly the ones
+  that cannot be seen from there. This sends a real handshake with a real `Origin` through
+  the real proxy and reads the status: `101` is healthy, `403` is the origin guard, `401`
+  is an auth gate over the transport (browsers do not send basic-auth credentials on a
+  handshake), `404` is usually a proxy not forwarding the path.
+
+  Two static checks come with it: **Transport origins** (empty list, an entry that is not
+  an origin, or a production app still pointing at localhost) and **Asset output**.
+
+- **`bun zt assets:build`** — build every bundle the app declares as a release step:
+  `app.assets` entrypoints plus Flow's conventional `resources/css/app.css` and
+  `resources/js/app.js`. `css:build` only ever covered the first half of that.
+
+- **`Application.declareWebSocketPath()` / `webSocketPaths()`.** Handlers are only wired in
+  the web runtime, so a CLI process could not name the app's own transport — which is what
+  `doctor --url` needs. Providers declare the path in `onRegister()`, which runs in every
+  mode.
+
+- **`RequestContext.remember(key, factory)`** — run something at most once per request.
+  The N+1 detector says a query ran too many times; when the answer is the same every
+  time, the fix is to ask once, and every app that hits it rebuilds this by hand. Two
+  behaviours are the whole point and are the ones a hand-rolled version gets wrong: the
+  **promise** is cached rather than the resolved value (cache after the `await` and a
+  `Promise.all` of ten readers all miss), and a **rejected promise is evicted** (leave
+  it in and one transient failure poisons every later read in the same request).
+  Outside a request it is a pass-through — a queue worker has no request to scope to.
+  `RequestContext.forget(key)` drops a value when a write invalidates an earlier read.
+
+- **Refreshable locks — a lock can now be held across work longer than its TTL.** Sizing
+  a TTL was a trade with no good answer: too short and the lock evaporates mid-job, too
+  long and a crashed holder blocks the key for however long you guessed. The number was
+  being asked two different questions at once.
+
+  `refresh: true` separates them. The lock is extended in the background for as long as
+  the callback runs, so the TTL only has to answer "how long after a crash before someone
+  else may take over" — a decision rather than a guess:
+
+  ```ts
+  await Lock.block(
+    "report:monthly",
+    60,
+    async (lock, signal) => {
+      await buildReport({ signal }); // may take an hour; 60 is fine
+    },
+    { refresh: true },
+  );
+  ```
+
+  Refreshes run every `refreshEvery` seconds, defaulting to a third of the TTL so one
+  missed beat is survivable. `ManagedLock.refresh()` exposes the same thing by hand for
+  flows that span steps, alongside `expiresAt` — a client-side estimate, for deciding
+  when to refresh next rather than for deciding whether you still hold the lock.
+
+  **A lock that is lost anyway is not papered over.** The callback's `AbortSignal` is
+  aborted and `LockLostError` is thrown, because work that continues after losing
+  exclusivity is exactly the situation the lock existed to prevent. The signal is a
+  request, not a guarantee — work that ignores it runs on — so a job that can do damage
+  after losing the lock has to check it between steps.
+
+  `extend` is **optional** on the `LockDriver` contract, so a driver written against 1.x
+  still compiles; refreshing falls back to `acquire(key, owner, ttl)`, which is an
+  owner-guarded refresh on all three built-ins. Both callback arguments are additive —
+  every existing zero-argument call site is untouched.
+
+  The refresh timer is `unref()`d and cleared in `finally` on all three exits (success,
+  throw, and lock lost). An un-unref'd interval in a lock helper is the reason a process
+  stops exiting, and nothing about that symptom points back here.
+
+- **`bun zt dev` — the server and every companion process in one terminal.** An app with
+  a queue needed two terminals and the discipline to restart the right one by hand. Worse,
+  the gap was not closeable from a package: every library with a companion process — a
+  worker, a listener, a watcher — had the same problem and no way to help, because the dev
+  runner only knew about the server.
+
+  A provider now declares one the way it declares `replContext()`:
+
+  ```ts
+  override devProcesses(): DevProcessDefinition[] {
+    return [{ name: "queue", command: "queue:work", enabled: () => this._hasQueue() }];
+  }
+  ```
+
+  and it appears as its own tab, individually restartable with `r`. `QueueProvider` ships
+  the first one; it stays off screen under the `sync` driver and when an in-process worker
+  pool is already draining the queue, because a tab with nothing to do is worse than no
+  tab. Apps get the last word through `app.dev.processes` and `app.dev.disable` — reusing
+  a name replaces the process rather than adding a second one.
+
+  **A dying process never takes the server with it.** It restarts on its own, three times
+  with backoff, and then parks that one tab with instructions rather than tearing dev mode
+  down. This is deliberately the opposite of the asset build hook, where a failure aborts
+  the reload — different lifetimes, different failure rules.
+
+  `--only` / `--without` / `--list` / `--stream` / `--force-build` mirror `artisan dev`,
+  so there is nothing to translate coming from another framework. `--list` names the provider behind
+  every entry, which is the question you actually have when an unfamiliar tab appears.
+  `serve --dev` is unchanged in spelling and gains all of it — `dev` is that command with
+  a richer flag set, not a second implementation of it.
+
+- **The Deck — a tabbed dev UI with no new dependency.** `@zerotal/core` carries exactly
+  one external runtime dependency, and a terminal multiplexer off npm would be the second,
+  in the package everything else depends on, to draw a box. Bun ships every primitive it
+  needs: `Bun.stringWidth` measures what the terminal will actually show, `Bun.sliceAnsi`
+  cuts a styled line without severing an escape sequence, and raw stdin gives us keys.
+
+  Scrollback belongs to the deck rather than the terminal — 5,000 lines per process —
+  which is what makes per-tab history and `/` search possible at all. `1`–`9` and the
+  arrows select, `r` restarts, `c` clears, `t` toggles timestamps, `q` quits.
+
+  **Stream mode is the base case, not a fallback.** Interleaved `[label] line` output with
+  no escape codes whatsoever, chosen automatically whenever stdout is not a TTY, and what
+  you want in a log file or CI. The tab UI is a layer on top of it. Either way the terminal
+  is restored on every exit path there is — `q`, a signal, and an uncaught throw — because
+  raw mode plus the alternate screen left on makes a shell unusable, and that is the
+  classic way a TUI ruins someone's afternoon.
+
+- **`doctorChecks()` on `ServiceProvider`.** The declarative counterpart to
+  `app.registerDoctorCheck()`: same checks, same report, but asked of the provider rather
+  than pushed from inside `onRegister()`, so a package's checks sit next to its other
+  contributions and read without tracing a registration call. A provider whose method
+  throws contributes nothing rather than failing the doctor for every other package.
+
+- **Dev asset builds are skipped when nothing changed.** `serve --dev` rebuilt every bundle
+  on every boot and every backend save, including when the project had not been touched.
+  A build now records what it consumed and produced, and is skipped when none of it moved.
+  The input set comes from two places, because one is not enough: the module graph, read
+  back from the external sourcemaps the dev build already emits (lazily-imported chunks
+  included), and — for stylesheets — a stat sweep of `app/`, `resources/`, `routes/` and
+  `config/`, since Tailwind discovers utility classes by reading templates that appear in
+  no sourcemap. Measured on a small app: a Tailwind CSS build of ~740 ms becomes ~1 ms.
+  Every uncertainty resolves to _build_: a corrupt cache, an unreadable input, a deleted
+  output, a changed config, or a different Bun version all rebuild. Minified (production)
+  builds never consult it, and `ZT_NO_BUILD_CACHE=1` disables it everywhere.
+
+- **`app/commands/` is auto-discovered.** `make:command` generates into the conventional
+  directory, but the runner never read it — a generated command answered
+  `Unknown command` until it was hand-registered in a provider, and nothing said so. The
+  runner now discovers the directory in console/worker/test environments (after the
+  built-ins, so an app command wins a name collision), the path is overridable via
+  `app.conventions.paths.commands`, and `make:command` prints the run invocation. The
+  scaffolded `zt.ts` comment describing the manual registration dance is gone.
+- **`bun zt doctor`.** One command that runs every static sanity check against the booted
+  app and prints each finding with its fix: APP_KEY strength, `database.synchronize`
+  colliding with migration files, a `routes/` directory no `routing()` group loads, and
+  class directories (`app/schedules`, `app/jobs`, `config/storage.ts`) whose consuming
+  provider isn't registered — the family of failures that otherwise fail by doing
+  nothing. Packages contribute their own checks via `app.registerDoctorCheck()` in
+  `onRegister()`; the scheduler's static-config check is the first. Exits 1 when any
+  check fails outright.
+- **Boot warns about an unrouted `routes/` directory.** A conventional `routes/index.ts`
+  full of `Router.get(...)` calls registers nothing until `.routing()` loads it, so every
+  path in it 404s in a way indistinguishable from a typo'd URL. The web boot now names
+  the files and the one-line fix. (`Application.routedFiles` is new, so the check — and
+  anything else — can see what the routing groups actually load.)
+
+### Changed — BREAKING
+
+- **`route()` takes query values as a third argument: `route(name, params, query)`.**
+  Previously any param that matched no `:segment` was appended to the query string, which
+  meant a typo'd param name silently produced a URL that was wrong rather than an error —
+  `route("posts.show", { slugg })` shipped `/posts/:slug?slugg=…`. Params are now exact:
+  an unknown key throws, naming the key and pointing at the third argument.
+
+  ```ts
+  route("search", { q: "zerotal", page: 2 }); // before
+  route("search", {}, { q: "zerotal", page: 2 }); // now
+  ```
+
+  Query values may be arrays (`{ tag: ["a", "b"] }` → `?tag=a&tag=b`), and `null` /
+  `undefined` entries are dropped rather than serialised as `"null"`. The same applies to
+  `redirect().to()` / `redirectTo()`, which take params only — build the URL with
+  `route()` when you need a query string.
+
+  This was a decision between typing the existing behaviour and fixing it. Typing it
+  would have made a footgun look safe, which is worse than leaving it alone.
+
+- **A catch-all route's value is passed under the `"*"` key.** `[...slug]` compiles to `*`
+  in the URL pattern — the segment name is gone by the time routing sees it — and
+  `route()` previously left the `*` in the URL untouched, producing a literal
+  `/docs/*`. It now substitutes, from either a path or an array of segments:
+  `route("docs.show", { "*": "guides/intro" })`, `route("docs.show", { "*": ["guides", "intro"] })`.
+
+### Changed
+
+- **`serve` no longer rebuilds assets at boot in production when the output directory is
+  read-only.** Rebuilding on start is right in development and load-bearing for the wrong
+  reason in production: it makes the server process require write access to its own output
+  tree, so a properly hardened unit (`ProtectSystem=strict` with a tight `ReadWritePaths`)
+  fails at startup with `Read-only file system: writing chunk "./app.css"` and
+  restart-loops — with the logs blaming the filesystem rather than the boot-time build that
+  made it a problem.
+
+  A read-only output directory is now read as what it is: a deployment that built its
+  assets ahead of time and locked the tree down. It serves what it shipped and logs one
+  line. Everywhere else, and anywhere the directory is writable, behaviour is unchanged.
+
+- **`SessionContract.get` and `pull` take an optional `<T>`.** The contract's own
+  docblock said higher-level surfaces layer a generic on top, but `ctx.session` _is_
+  typed as the contract — so `ctx.session.get<number>(k)` was a compile error while
+  `ctx.flashed<T>(k)` on the same object was not. `<T>` defaults to `unknown`, so the
+  read-then-narrow form is unchanged.
+
+### Fixed
+
+- **The memory lock driver refreshes on re-acquire.** `ManagedLock.acquire()` documents
+  that re-acquiring while this instance already holds the key refreshes it. Redis honoured
+  that with `EXPIRE` and SQLite with an `UPDATE`; the memory driver returned `true` for the
+  same owner and never touched `expiresAt` — so the driver every app gets by default was
+  the only one of the three that quietly refused. A caller re-acquiring to stay alive was
+  told it had worked and then lost the lock on the original schedule.
+
+- **`setAppEnv("dev")` resolves to `web`, not `console`.** Dev mode's process 1 boots the
+  app purely to ask its providers what to run, and a provider is only asked if its
+  `static environments` includes the environment it booted under. Falling through to
+  `console` would have silently dropped every web-only provider — no error, no empty tab,
+  just a process that never appears — and would have left `zt dev` and `serve --dev`
+  disagreeing about what dev mode consists of.
+
+- **A Flow app built its bundles three times on every `serve --dev`.** `APP_ENV` defaults to
+  `"web"`, so the orchestrator process passed the view provider's web-runtime check and ran
+  its "build once at startup" pass; the orchestrator then ran the same build hook itself;
+  then it spawned a worker that booted the app and built a third time. Every backend save
+  paid for two of them. View providers now skip their boot-time build when a
+  `DevOrchestrator` owns builds — detected from `argv` for the orchestrator, since providers
+  boot before `ServeCommand` can set an environment variable, and from `ZT_DEV` for the
+  worker it supervises. A plain `serve` still builds at boot.
+
 ## [1.1.0] — 2026-08-08
 
 ### Fixed

package/package.json

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

package/src/application/Application.ts

@@ -38,13 +38,16 @@ import { NotFoundError } from "../errors/HttpError.ts";
 import type { ContainerBindings } from "../container/types.ts";
 import { dispatchRequest } from "../router/RouteHandler.ts";
 import type { ProviderHooks } from "../router/RouteHandler.ts";
-import { isProdLike } from "../support/env.ts";
+import { isProdLike, deployEnv } from "../support/env.ts";
 import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { runBootDoctor } from "./BootDoctor.ts";
 import { runConfigValidators } from "../config/validation.ts";
 import { pathToFileURL } from "node:url";
-import { currentApp, defaultApp, setDefaultApp } from "./currentApp.ts";
+import { unroutedRoutesWarning } from "../support/unroutedRoutes.ts";
+import type { DoctorCheck } from "../doctor/AppDoctor.ts";
+import { defaultApp, setDefaultApp } from "./currentApp.ts";
 import type { ConfigValidator, RegisteredConfigValidator } from "../config/validation.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 // ── Convention config discovery ───────────────────────────────────────────────
 
@@ -323,6 +326,9 @@ export class Application {
    * a `path` is a catch-all. Each connection is tagged with `_wsPath` on upgrade and dispatched
    * to the matching registration.
    */
+  /** Transport paths declared by providers in any runtime. See `declareWebSocketPath`. */
+  private _declaredWsPaths = new Set<string>();
+
   private _wsRegistrations: Array<{
     path?: string | undefined;
     handlers: WebSocketHandlers;
@@ -331,16 +337,29 @@ export class Application {
   /** Set by ServeCommand --dev-worker to enable the /__dev/ws HMR endpoint. */
   private _devWsEnabled = false;
   /** Tracks provider-auto-registered middleware to prevent double-registration. */
-  private readonly _autoMiddlewareSet = new Set<Function>();
+  private readonly _autoMiddlewareSet = new Set<ClassRef>();
   private _providerHooks: ProviderHooks | undefined = undefined;
   /** @internal The auth user-resolver registered via {@link withUserResolver}; called by AuthMiddleware. */
   _userResolver: ((id: number) => Promise<AuthenticatedUser | null>) | undefined = undefined;
   /** Convention descriptors contributed by providers (models, observers, policies, …). */
   private _concerns: ConcernDescriptor[] = [];
-  /** Namespace validators contributed by providers; run once at boot (see {@link registerConfigValidator}). */
-  private _configValidators: RegisteredConfigValidator[] = [];
+  /**
+   * Namespace validators contributed by providers; run once at boot (see
+   * {@link registerConfigValidator}).
+   *
+   * Readable, not private, so `zt deploy:<env>` can re-run them against the target
+   * environment before a release. Boot already ran them — but on a machine that is
+   * not the deployment, where `isProduction` was false and every finding was a
+   * warning. Re-running them with production semantics is how a deploy reports the
+   * problems that would otherwise refuse the boot after the cutover.
+   *
+   * @internal
+   */
+  readonly _configValidators: RegisteredConfigValidator[] = [];
   /** Bootstrap container-registration callbacks queued via `bind()`; run during boot(). */
   private _bindCallbacks: Array<(container: Container) => void> = [];
+  /** Doctor checks contributed by providers (see {@link registerDoctorCheck}). */
+  private _doctorChecks: DoctorCheck[] = [];
 
   private constructor() {}
 
@@ -355,6 +374,30 @@ export class Application {
     return this;
   }
 
+  /**
+   * Contribute a check to `zt doctor`. Providers call this in `onRegister()`;
+   * the doctor runs the built-in checks plus everything contributed here.
+   *
+   * @category Providers
+   */
+  registerDoctorCheck(check: DoctorCheck): this {
+    this._doctorChecks.push(check);
+    return this;
+  }
+
+  /** The provider-contributed doctor checks (read by `runDoctor`). */
+  get doctorChecks(): readonly DoctorCheck[] {
+    return this._doctorChecks;
+  }
+
+  /**
+   * The files loaded by `routing()` groups — what actually serves explicit routes.
+   * Read by the unrouted-`routes/` boot warning and the doctor.
+   */
+  get routedFiles(): string[] {
+    return this._routeGroups.map((g) => g.file);
+  }
+
   /**
    * Attach a validator to a config namespace. Providers call this in
    * `onRegister()`; the boot sequence runs every validator once — after
@@ -719,7 +762,7 @@ export class Application {
     const hasSubclass = this._middleware.some(
       (registered) =>
         registered !== middlewareClass &&
-        registered.prototype instanceof (middlewareClass as Function),
+        registered.prototype instanceof (middlewareClass as ClassRef),
     );
     if (hasSubclass) return;
     this._autoMiddlewareSet.add(middlewareClass);
@@ -854,6 +897,38 @@ export class Application {
     return this;
   }
 
+  /**
+   * Declare a WebSocket path this app serves, without wiring any handlers for it.
+   *
+   * Handlers are only registered in the web runtime, so a CLI process — which is what
+   * `bun zt doctor` is — has no idea the app has a transport at all. Providers call this
+   * from `onRegister()`, which runs in every mode, so the paths are knowable from the
+   * console even though nothing is listening there.
+   *
+   * @category Server
+   */
+  declareWebSocketPath(path: string): this {
+    this._declaredWsPaths.add(path);
+    return this;
+  }
+
+  /**
+   * Every WebSocket path this app serves: those declared via
+   * {@link Application.declareWebSocketPath} plus those actually registered. A catch-all
+   * registration (no path) is reported as `"*"`.
+   *
+   * Exposed for tooling that has to reach the transport from outside the process — `bun zt
+   * doctor --url=…` probes each of these through the real proxy, because a handshake a
+   * browser cannot complete is invisible from in here.
+   *
+   * @category Server
+   */
+  webSocketPaths(): string[] {
+    return [
+      ...new Set([...this._declaredWsPaths, ...this._wsRegistrations.map((r) => r.path ?? "*")]),
+    ];
+  }
+
   /** Find the WS registration handling a connection's path (exact match, else a catch-all). */
   private _wsRegFor(wsPath: unknown): (typeof this._wsRegistrations)[number] | undefined {
     return (
@@ -1016,15 +1091,25 @@ export class Application {
       await this._loadFileRoutes();
     }
 
+    // A routes/ directory nobody routed is a silent 404 for every path in it — the file
+    // imports cleanly and registers nothing, which looks identical to a typo'd URL.
+    this._warnUnroutedRoutesDir(process.cwd());
+
     // Convention phase — worker jobs/schedules + public static files.
     await this._bootConventions();
 
     // Fail loud on a weak APP_KEY: in a production-like deployment a short key is
     // a refuse-to-boot error; elsewhere (bar the test harness) it's a warning.
+    //
+    // `deployEnv()`, not `Bun.env["APP_ENV"]`. `setAppEnv()` overwrites that
+    // variable with the runtime mode (`web`/`console`/`worker`) before the app is
+    // created, so this read was always `"web"` under the CLI — meaning a weak key
+    // in production only ever warned, and the refusal this block exists for had
+    // never once fired.
     if (this._env !== "test") {
       const _keyWarning = appKeyStrengthWarning(Bun.env["APP_KEY"]);
       if (_keyWarning) {
-        if (isProdLike(Bun.env["APP_ENV"] ?? "")) throw new Error(_keyWarning);
+        if (isProdLike(deployEnv())) throw new Error(_keyWarning);
         console.warn(_keyWarning);
       }
     }
@@ -1045,6 +1130,20 @@ export class Application {
     }
   }
 
+  /**
+   * Warn when `routes/` exists on disk but no `routing()` group points inside it.
+   * Web only: workers and the console don't answer HTTP, and the test harness
+   * routinely boots apps with no routes at all.
+   */
+  private _warnUnroutedRoutesDir(root: string): void {
+    if (this._env !== "web") return;
+    const warning = unroutedRoutesWarning(
+      root,
+      this._routeGroups.map((g) => g.file),
+    );
+    if (warning) frameworkLog("app").warn(warning);
+  }
+
   private async _loadFileRoutes(): Promise<void> {
     for (const { dir, prefix, middleware } of this._fileRouteGroups) {
       await Router.groupAsync({ prefix, middleware }, () => scanFileRoutes(dir).then(() => {}));
@@ -1537,7 +1636,6 @@ export class Application {
     const appVersion =
       configManager?.get<string>("app.version", Bun.env["APP_VERSION"] ?? Bun.version) ??
       Bun.version;
-    const app = this;
 
     // Built-in runtime probe — memory, Bun version, in-flight request count.
     Health.register("runtime", () => ({
@@ -1546,7 +1644,7 @@ export class Application {
         memory: process.memoryUsage(),
         bun: Bun.version,
         pendingRequests:
-          (app._static as { pendingRequests?: number } | undefined)?.pendingRequests ?? 0,
+          (this._static as { pendingRequests?: number } | undefined)?.pendingRequests ?? 0,
       },
     }));