@zerotal/core 1.15.0 → 1.15.2

package/CHANGELOG.md

@@ -8,6 +8,89 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.2] — 2026-10-23
+
+### Fixed
+
+- **A production build ships React's production build.** `browserEnvDefines()` defined
+  `import.meta.env` but not `process.env.NODE_ENV`, which is the switch React and most of
+  npm read — and Bun.build leaves that expression to whatever the shell has. An app that ran
+  `inertia:build --production` without `NODE_ENV` in its environment shipped React's
+  development build: a 522 KB vendor chunk where 322 KB would do, the DevTools notice in
+  every visitor's console, and full hydration diffs. The define now states it from the same
+  flag. Found on a live consumer app (Trekly).
+
+- **`back()` works behind a proxy that terminates TLS.** `safeRedirectPath` — which
+  `ctx.back()`, `validate()`'s redirect on failure, `FormRequest`, the intended-URL helpers
+  and flow all use — accepted a Referer only from the request's own origin. Behind Caddy or
+  nginx the request reaches the process as `http://…` while every browser sends
+  `https://…`, so every Referer was refused and "back" was always `/`: a form with one
+  mistake in it sent the user to the home page, its errors flashed to a page that never
+  shows them. The configured `app.url`'s origin now counts as the app's own as well; every
+  other site is still refused. Found on a live consumer app (Trekly), which had worked
+  round it in its exception handler.
+
+## [1.15.1] — 2026-09-13
+
+### Added
+
+- **`registerViewFileRouteResolver` is public.** It is what turns on server-rendered
+  file-route pages — a route file's default export rendered to HTML and wrapped in the
+  nearest `_layout` — and it carried an internal marker, so nothing outside the framework
+  could call it. Both features were implemented, tested, and described in `docs/view.md` as
+  automatic, while being unreachable through the public API.
+
+  Promoted rather than removed: the marker was wrong, not the design. It stays opt-in, and
+  the docblock now says why — it claims every `.tsx` route file's default export, which an
+  app using file routes for plain handlers has not asked for, and it turns on a directory
+  walk per scanned route. `docs/view.md` documents the call and the `_layout` convention,
+  including that `_layout` is read by its **default** export where `_middleware` is read by
+  a named one.
+
+### Fixed
+
+- **Four test suites left their fixture trees on disk after every run.** Each builds a
+  temporary package or asset tree and removes it in `afterAll`, and the removal reported
+  success without removing anything: on Bun 1.4.0 under Windows, a recursive `rm()` from
+  `node:fs/promises` resolves and deletes nothing when the path carries a `"./"` prefix,
+  which all four used. Written bare, the same call works.
+
+  Test-only, but it was not harmless. The abandoned trees contain deliberately
+  non-conformant fixture packages, `lint:ci` lints anything under `packages/**`, and the
+  gate is a ratchet against a committed count — so a full test run left the next lint run
+  one or two warnings over baseline, and the regression pointed at whatever change happened
+  to be in the tree. Previously read as fallout from interrupted runs, because an
+  interrupted run skips the hook and produces the same evidence.
+
+- **A `_layout` file that could not apply rendered its pages without one.** The same
+  fail-open the `_middleware` loader had, one function up in the same file, and found by
+  looking for the shape rather than by hitting it: an import error was swallowed together
+  with the not-found case under "component resolution is best-effort". Best-effort is
+  right for _absence_ and wrong for a file that exists and threw — a `_layout.tsx` with a
+  typo rendered every page beneath it without its chrome, with no error and no log, and on
+  a hot-reload without chrome it had a moment earlier.
+
+  Absence stays silent and the walk continues outward, as before. An import error stops
+  the boot with the path and the original error, and a `_layout` that default-exports no
+  component now says so rather than silently handing those pages an outer directory's
+  layout instead.
+
+  Worth noting alongside the `_middleware` fix in 1.15.0: these two sibling conventions
+  disagreed about export shape — `_layout` reads `default` and ignored a named export,
+  `_middleware` read the named export and ignored `default` — and each failed open on the
+  other's spelling. That disagreement is why `export default` was the natural guess in a
+  `_middleware.ts` to begin with.
+
+- **`zt doctor` says when its outside-in probes did not run.** The response-header and
+  WebSocket-transport probes only run with `--url`, and they are the two checks that can
+  see what no in-process check can. Being silent about skipping them meant the people who
+  most needed them were the ones with no way to learn they existed — a team running
+  `doctor` after every deploy for months never saw the duplicate-header check.
+
+  A line, not a new default: auto-probing `app.url` would print "✓ No duplicated security
+  headers" for a site that was merely unreachable, which is the same false confidence the
+  secure-headers check was fixed for in 1.15.0.
+
 ## [1.15.0] — 2026-09-04
 
 ### Changed — **BREAKING**

package/api-surface.md

@@ -3783,6 +3783,8 @@ function Fragment = ({ children }: {    children?: unknown;}) => SafeHtml
 
 function Raw = ({ html }: {    html: string;}) => SafeHtml
 
+function registerViewFileRouteResolver = () => void
+
 function safe = (html: string) => SafeHtml
 
 type Children = unknown

package/package.json

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

package/src/command/builtin/DoctorCommand.ts

@@ -39,6 +39,7 @@ export class DoctorCommand extends Command {
 
     const probeFailures = await this._probeTransport(app);
     const headerFindings = await this._probeHeaders();
+    this._noteSkippedProbes();
 
     const warns = report.filter((e) => e.result.status === "warn").length + headerFindings.warnings;
     const fails =
@@ -104,6 +105,30 @@ export class DoctorCommand extends Command {
    * are a warning, because they are a conflict waiting for someone to edit one
    * side.
    */
+  /**
+   * Say that the outside-in probes did not run, when they did not.
+   *
+   * They are the two checks that can see what no in-process check can — a header the
+   * proxy also sets, a WebSocket the proxy drops — and they are behind a flag, so the
+   * people who most need them are the ones who do not know the flag exists. A team
+   * running `doctor` after every deploy for months never saw the duplicate-header
+   * check and had no way to find out it was there.
+   *
+   * A line, not a default. Auto-probing `app.url` would print "✓ No duplicated
+   * security headers" for a site that was simply unreachable, which is a worse
+   * failure than the silence: it is the same false confidence the secure-headers
+   * check was fixed for.
+   */
+  private _noteSkippedProbes(): void {
+    if (this.flags["url"]) return;
+    this.newLine();
+    this.dim(
+      "Not checked: response headers and WebSocket transport, which are only visible " +
+        "from outside.\n    Add --url https://your-site to read the deployed app through " +
+        "its proxy.",
+    );
+  }
+
   private async _probeHeaders(): Promise<{ failures: number; warnings: number }> {
     const url = this.flags["url"] as string | undefined;
     if (!url) return { failures: 0, warnings: 0 };

package/src/dev/buildEnv.ts

@@ -37,5 +37,13 @@ export function browserEnvDefines(isProduction: boolean): Record<string, string>
       PROD: isProduction,
       MODE: isProduction ? "production" : "development",
     }),
+    // The other half of the convention, and the one that costs the most to miss.
+    // React and most of npm choose their production build with
+    // `process.env.NODE_ENV === "production"`, and Bun.build leaves the expression
+    // to the environment it runs in. A deploy that ran `inertia:build --production`
+    // without NODE_ENV set shipped React's development build — a 522 KB vendor
+    // chunk where 322 KB would do, the DevTools notice in every visitor's console,
+    // and full hydration diffs to anyone who looked. Stated here, the flag decides.
+    "process.env.NODE_ENV": JSON.stringify(isProduction ? "production" : "development"),
   };
 }

package/src/pipeline/HttpContext.ts

@@ -14,6 +14,7 @@ import {
   DEFAULT_MD_OPTIONS,
   type BunMarkdownOptions,
 } from "../helpers/markdown.ts";
+import { config } from "../helpers/config.ts";
 import type { SessionContract, TransactionContext } from "../contracts/index.ts";
 import type { ContextRegistry, ContextKey } from "./ContextRegistry.ts";
 
@@ -868,14 +869,24 @@ const _prototypeMethods: ReadonlyArray<[string, (...args: unknown[]) => unknown]
 })();
 
 /**
- * Return `url` only when it belongs to the same `origin`, otherwise `undefined`.
+ * Return `url` only when it belongs to the app, otherwise `undefined`.
  * Guards `ctx.back()` and similar helpers against open-redirect attacks by
  * rejecting absent, malformed, or cross-origin URLs.
  *
+ * "Belongs to the app" is the request's own `origin` **or the configured
+ * `app.url`'s**. The second matters behind a reverse proxy that terminates TLS:
+ * the request reaches the process as `http://…`, while every browser sends its
+ * `Referer` as `https://…`, so a same-origin check alone refused every one of
+ * them and `back()` — and `validate()`'s redirect on failure — fell back to "/"
+ * on every request in production. A form with one mistake in it sent the user
+ * to the home page, its errors flashed to a page that never shows them. The
+ * configured URL is the app's own address by definition, so accepting it opens
+ * nothing to anyone else.
+ *
  * @param url - Candidate redirect target (e.g. a `Referer` header value).
  * @param origin - The current request origin to match against.
- * @returns The same-origin `url`, or `undefined` when it is absent, unparseable,
- * or points to a different origin.
+ * @returns The `url`, or `undefined` when it is absent, unparseable, or points
+ * anywhere but this app.
  *
  * @internal
  */
@@ -885,7 +896,20 @@ export function safeRedirectPath(
 ): string | undefined {
   if (!url) return undefined;
   try {
-    return new URL(url).origin === origin ? url : undefined;
+    const target = new URL(url).origin;
+    if (target === origin) return url;
+    return target === configuredOrigin() ? url : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The configured `app.url`'s origin, or `undefined` off-app or when it is unset or malformed. */
+function configuredOrigin(): string | undefined {
+  const base = config.safe("app.url", "") as string;
+  if (!base) return undefined;
+  try {
+    return new URL(base).origin;
   } catch {
     return undefined;
   }

package/src/router/FileRouter.ts

@@ -414,18 +414,44 @@ async function _collectLayout(
       const layoutPath = dir
         ? join(baseDir, dir, `_layout${extension}`)
         : join(baseDir, `_layout${extension}`);
+      // No file at this spelling is the ordinary case — most directories have no
+      // layout, and the walk continues outward to find the nearest one that does.
+      if (!(await Bun.file(layoutPath).exists())) continue;
+
+      const href = pathToFileURL(layoutPath).href;
+      const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
+
+      let loadedModule: { default?: unknown };
       try {
-        if (await Bun.file(layoutPath).exists()) {
-          const href = pathToFileURL(layoutPath).href;
-          const importUrl = reloadId ? `${href}?t=${reloadId}` : href;
-          const loadedModule = (await import(importUrl)) as { default?: unknown };
-          if (typeof loadedModule.default === "function") {
-            return loadedModule.default as ViewComponent;
-          }
-        }
-      } catch {
-        // A page module that fails to import is skipped — component resolution is best-effort.
+        loadedModule = (await import(importUrl)) as { default?: unknown };
+      } catch (error) {
+        // This was swallowed with the not-found case, under "component resolution is
+        // best-effort". Best-effort is right for *absence*; it is not right for a file
+        // that exists and threw. A `_layout.tsx` with a typo in it rendered every page
+        // beneath without its chrome — no error, no log, and on a hot-reload a layout
+        // that was there a moment ago. Same failure the `_middleware` loader had, one
+        // function up, minus the part where the missing thing was a guard.
+        throw new Error(
+          `[Zerotal] Failed to import ${layoutPath}: ` +
+            `${error instanceof Error ? error.message : String(error)}\n` +
+            `Pages under this directory would render without their layout, so boot ` +
+            `stops here. Fix the file, or delete it if the directory needs no layout.`,
+          { cause: error },
+        );
       }
+
+      if (typeof loadedModule.default === "function") {
+        return loadedModule.default as ViewComponent;
+      }
+
+      // The file exists and exports no component. Continuing the walk would silently
+      // hand these pages an outer directory's layout instead — plausible-looking output
+      // that is not what the file says should happen.
+      throw new Error(
+        `[Zerotal] ${layoutPath} does not default-export a component, so it lays out ` +
+          `nothing.\nA layout file is read by its default export:\n` +
+          `  export default (ctx, { children }) => \`<main>\${children}</main>\`;`,
+      );
     }
   }
   return undefined;

package/src/view/FileRouteResolver.ts

@@ -19,12 +19,36 @@ function isClass(fn: Function): boolean {
 }
 
 /**
- * Opt into rendering `.tsx`/`.jsx` file-route pages: a route file's default
- * export that is a view component (or any function tagged via the view marker)
- * is rendered to HTML, wrapped in the nearest `_layout`, and registered as a GET
- * route. Call from a provider's `onRegister()` before file routes are scanned.
+ * Opt into server-rendered file-route pages.
  *
- * @internal
+ * With this registered, a route file whose default export is a view component
+ * (or any function tagged by {@link definePage}) is rendered to HTML, wrapped in
+ * the nearest `_layout`, and registered as a `GET` route. Without it, neither
+ * happens: the default export is registered as an ordinary file handler and the
+ * `_layout` convention is switched off entirely.
+ *
+ * Call it before file routes are scanned — a provider's `onRegister()`, or
+ * `bootstrap/app.ts` before `fileBasedRouting()`:
+ *
+ * ```ts
+ * // bootstrap/app.ts
+ * import { registerViewFileRouteResolver } from "@zerotal/core/view";
+ *
+ * registerViewFileRouteResolver();
+ *
+ * export default Application.create({ providers }).fileBasedRouting({
+ *   web: basePath("app/views"),
+ * });
+ * ```
+ *
+ * **Why it is opt-in rather than on by default.** It claims every `.tsx` route
+ * file's default export, which an app using file routes for plain handlers has
+ * not asked for — and it turns on `_layout` discovery, which walks the directory
+ * tree on every scanned route. An app that wants JSX pages says so.
+ *
+ * It carried an internal marker until 1.15, which made both features unreachable
+ * through the public API while the documentation described them as automatic.
+ * The marker was wrong, not the design.
  */
 export function registerViewFileRouteResolver(): void {
   enableFileRouteLayouts();