@zerotal/arch 1.15.0 → 1.15.2

package/docs/changelog.md

@@ -27,6 +27,136 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
 
+## 1.15.2 — 2026-10-23
+
+A patch, and if you run Bun 1.4.4 or later it is the one to take: that Bun stopped accepting the
+way the ORM hands it SQL, so most of what the ORM sent to the database failed. Three smaller
+faults ride with it, found running a live app on Zerotal, each of which that app had been
+working round in its own code.
+
+Nothing here breaks. Safe to take directly.
+
+### Fixed
+
+- **The ORM runs on Bun 1.4.4** (`@zerotal/orm`, with `@zerotal/notifications` and
+  `@zerotal/testing`). Bun's `sql` function refuses a template object whose `raw` property
+  is enumerable — "so it is not a template object" — and the ORM built every statement it
+  assembled from a string that way: the string form of `DB.raw()`, the query builder,
+  schema and migration DDL, the `SAVEPOINT` a nested transaction issues, the validator's
+  `unique` and `exists` rules. 1.4.4 is the first Bun known to refuse it, and on that version
+  and later none of those statements ran. They now come from one helper that builds the
+  object the way the language does. An app on Bun 1.4.2 or earlier was never affected, and
+  nothing about its behaviour changes.
+
+- **A production build ships React's production build** (`@zerotal/core`). The browser
+  build's defines stated `import.meta.env` but not `process.env.NODE_ENV`, which is the
+  switch React and most of npm read — and the bundler left that expression to whatever the
+  shell happened to have. 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 `NODE_ENV` from the same flag, so the build no longer depends on the
+  shell it ran in.
+
+- **`back()` works behind a proxy that terminates TLS** (`@zerotal/core`). A redirect back
+  to the previous page accepted a `Referer` only from the request's own origin. Behind a
+  reverse proxy the request reaches the app as `http://…` while every browser sends
+  `https://…`, so every `Referer` was refused and "back" was always `/`. That is not only
+  `ctx.back()`: `validate()`'s redirect on failure, `FormRequest`, the intended-URL helpers
+  and Flow all use the same check, so a form with one mistake in it sent the user to the
+  home page with its errors flashed to a page that never shows them. The origin of the
+  configured `app.url` now counts as the app's own as well. Every other site is still
+  refused, and with no `app.url` set the behaviour is exactly what it was.
+
+- **`SmtpDriver` transfer-encodes text and HTML parts** (`@zerotal/notifications`). Both
+  went on the wire raw, with no `Content-Transfer-Encoding`. A body line over the 998-octet
+  limit of RFC 5322 was cut by a relay wherever the limit fell — a single-line HTML email
+  reached a customer reading "sup pliers" — and a non-ASCII body was sent as undeclared
+  8-bit on a connection that never negotiates `8BITMIME`. A part that is plain ASCII with
+  lines of 78 characters or fewer is still sent as written, now declared `7bit`; anything
+  else is quoted-printable, which keeps ASCII readable where base64 would not. A test that
+  asserts on the raw bytes the driver sent will see the new header, and for a long or
+  non-ASCII body, encoded text to decode before comparing.
+
+### Changed
+
+- **Three runtime dependencies move to newer minimums.** `alpinejs` and its seven plugins
+  (`@zerotal/flow`) are now `^3.17.4`, `@simplewebauthn/server` (`@zerotal/auth`) is now
+  `^13.3.3`, and `tailwind-merge` (`@zerotal/flow-ui`) is now `^3.7.0`. Each stays within
+  the major it was already on, and nothing in Zerotal's own API moves. The rest of the
+  weekly dependency update is development tooling and does not reach an installed app.
+
+## 1.15.1 — 2026-09-13
+
+A patch, and its headline is an ORM bug as old as the option it breaks: a model keyed on
+anything but `id` could not be updated, deleted or reloaded, and said nothing about it.
+
+Nothing here breaks. Safe to take directly.
+
+### Added
+
+- **`registerViewFileRouteResolver` is public** (`@zerotal/core`). 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`. Both halves were implemented, tested, and described in
+  [View](/docs/view) as automatic, while the call that enables them carried an internal
+  marker and could not be reached from an app. It stays opt-in, because it claims every
+  `.tsx` route file's default export; the docs now say so and document the `_layout`
+  convention beside it.
+
+### Fixed
+
+- **A model with a primary key other than `id` could not be updated, deleted or reloaded**
+  (`@zerotal/orm`). `static primaryKey = "uuid"` configured the column name everywhere the
+  key was written into SQL, while the value bound against it came from `this.id` — a
+  property such a model never has. So every statement went out as `WHERE uuid = NULL`:
+  `save()` on a loaded instance and `delete()` each matched zero rows and returned as
+  though they had written, `refresh()` and `fresh()` raised `ModelNotFoundError` for a row
+  sitting in the table, and `increment()`, `loadCount()` and the relation aggregates
+  no-opped or reported zero.
+
+  The insert was worse than silent. It wrote the row, then read it back by
+  `last_insert_rowid()`, which answers with a rowid no `TEXT` key ever equals — so the
+  instance came back with no timestamps and not marked as resident, and the next `save()`
+  on it was a second INSERT and a duplicate-key error rather than an UPDATE.
+
+  Every one of those paths now reads the key by its declared name. A write against an
+  instance whose key is genuinely absent, such as a row hydrated by `select("title")`,
+  raises `E_NO_PRIMARY_KEY` instead of binding NULL and looking like a success.
+  [The ORM guide](/docs/orm) now has a section on keying a model on something other than
+  `id`, including the part that bit: `localKey` on a relation defaults to `"id"`, so a
+  named key has to be named there too.
+
+- **A primary key the app mints was stripped from the INSERT** (`@zerotal/orm`). `id` was
+  treated as database-generated unconditionally, so a table whose key is a `TEXT id` the
+  application supplies took the value off the instance, dropped it from the statement, and
+  stored NULL — while the in-memory model went on holding the value it thought it had
+  written. The key is now omitted only when it has no value, which is what leaves
+  AUTOINCREMENT to the database.
+
+- **A `_layout` file that could not apply rendered its pages without one**
+  (`@zerotal/core`). The same fail-open the `_middleware` loader had in
+  [1.15.0](#1150--2026-09-04), one function up in the same file: an import error was
+  swallowed together with the not-found case. A `_layout.tsx` with a typo rendered every
+  page beneath it stripped of its chrome, with no error and no log. Absence stays silent;
+  a file that exists and threw now stops the boot with its path and the original error.
+
+- **A test file that booted the app with a `setup` callback left every later file without a
+  database** (`@zerotal/testing`). `createTestApp(bootstrap, setup)` opts out of sharing,
+  which was implemented as opting out of the cache — so nothing knew that app was in use,
+  its `close()` ran the full provider teardown, and `DatabaseProvider.onStopping` cleared
+  the process-global connection resolver for everyone after it. Suites that had done
+  nothing wrong failed with `No database connection. Is DatabaseProvider registered?`. It
+  read as a CI-only flake for months, because whether it bites depends on test-file order.
+
+- **`zt doctor` says when its outside-in probes did not run** (`@zerotal/core`). The
+  response-header and WebSocket-transport checks need `--url`, and they are the two that
+  see what no in-process check can. Skipping them silently meant the people who most needed
+  them had no way to learn they existed.
+
+Three more are internal, and in the notes for each package: a MySQL adapter that offers
+connection reservation may still refuse it, a dialect-coverage test left the ORM in MySQL
+mode for the rest of the process, and four test suites left their fixture trees on disk
+because a recursive `rm()` of a `"./"`-prefixed path silently deletes nothing on Windows.
+
 ## 1.15.0 — 2026-09-04
 
 A working developer building a training-provider platform on 1.14.3 sent eight findings

package/docs/contributing.md

@@ -114,6 +114,41 @@ bun test src/db/QueryBuilder.test.ts   # a single file
 5. **Update the docs.** If you change or add public API, update the relevant page
    under `docs/` (and the nav in `apps/docs/app/routes/_layout.ts` if you add a page).
 
+### Tests restore anything process-global
+
+Bun runs a package's test files in **one process**, and the preload is evaluated
+once per worker, not once per file. So a global a test writes is still there for
+every file that runs after it: `Bun.env` keys, `globalThis.fetch` or
+`globalThis.document`, and framework module state set through the `_set*` helpers.
+
+Put it back. `beforeEach` captures, `afterEach` restores — and restore in a
+`finally` or an `afterEach`, never at the end of the test body, or a failing
+assertion skips the restore and takes the rest of the suite with it.
+
+```ts fragment
+let saved: string | undefined;
+beforeEach(() => {
+  saved = Bun.env["APP_ENV"];
+  Bun.env["APP_ENV"] = "production";
+});
+afterEach(() => {
+  if (saved === undefined) delete Bun.env["APP_ENV"];
+  else Bun.env["APP_ENV"] = saved;
+});
+```
+
+This is worth its own rule because **the damage never lands where the mistake is**.
+The file that fails is whichever ran next, and which file that is depends on
+directory order — alphabetical on Windows, arbitrary readdir order on Linux. So a
+leak passes locally for months and reddens CI on an unrelated commit. Five of
+these were found in one week, each written by someone who had tested their own
+file in isolation and seen it pass.
+
+If a CI-only failure lands in a package your change did not touch, suspect a
+leaked global before suspecting your diff. To reproduce the order locally, rename
+the file you think runs second so it sorts last — passing paths to `bun test`
+explicitly does not work, because Bun re-sorts them.
+
 ## Documentation changes
 
 The docs are markdown files in `docs/`, served by the docs app in `apps/docs`. A page's

package/docs/middleware.md

@@ -185,13 +185,17 @@ Middleware stacks from outer directories are prepended automatically —
 you get `root/_middleware → admin/_middleware → route handler` in one pipeline.
 
 > **It is `export const middleware`, an array — not `export default`.** Route
-> files in the same directory default-export their handler, so `export default
-[AdminMiddleware]` is the natural guess and it is the wrong one. The app refuses
-> to boot and tells you which file, rather than serving the subtree unguarded and
-> looking exactly like a guarded one. The same applies to a `_middleware.ts` that
+> files in the same directory default-export their handler, so a default export is
+> the natural guess here and it is the wrong one. The app refuses to boot and tells
+> you which file, rather than serving the subtree unguarded and looking exactly
+> like a guarded one. The same applies to a `_middleware.ts` that
 > fails to import: a typo or a bad import path is a boot error, not a subtree that
 > quietly loses its guard. A directory with no `_middleware` file at all is the
 > convention working, and stays silent.
+>
+> Note the asymmetry with its sibling: a `_layout` file is read by its **default**
+> export, a `_middleware` file by a **named** one. Both now refuse to boot on the
+> other's spelling rather than applying nothing.
 
 ## Global middleware
 

package/docs/orm/index.md

@@ -171,6 +171,45 @@ export class LedgerEntry extends Model {
 > `forceDelete()`, `trashed()`, and the `withTrashed()` / `onlyTrashed()` scopes. See
 > [Lifecycle & Events](/docs/orm/lifecycle).
 
+#### A primary key that isn't `id`
+
+Name the key column and every read and write keys on it — `find()`, `save()`, `delete()`,
+`refresh()`, `increment()`, relation counts. Declare it like any other column and set the
+value yourself, because a `TEXT` key has no auto-increment to fall back on:
+
+```typescript fragment
+@(table("documents").primaryKey("uuid"))
+export class Document extends Model {
+  @column("string") uuid!: string;
+  @column("string") title!: string;
+
+  // `localKey` defaults to "id" on every relation, so a named key has to be named here too
+  @hasMany(() => Revision, { foreignKey: "documentUuid", localKey: "uuid" })
+  revisions!: HasMany<Revision>;
+}
+
+const doc = new Document();
+doc.uuid = crypto.randomUUID(); // nothing fills this in for you
+doc.title = "Roadmap";
+await doc.save();
+
+doc.createdAt; // the insert writes your key, then reads the row back by it
+```
+
+Three consequences worth holding onto:
+
+- **Set the key before the first `save()`.** With no value to write, the insert hands the
+  column to the database, which for a `TEXT` key means whatever its schema says — a `NOT
+NULL` violation, or a silent `NULL`.
+- **`localKey` on every relation.** It defaults to `"id"`, so a relation left at the
+  default reads a property the model does not have and quietly matches nothing.
+- **A string key wants its own name.** `Model` types the inherited `id` as a `number`, so
+  `primaryKey("uuid")` (or `"ticket_ref"`, or whatever it is) type-checks where a `TEXT`
+  column called `id` does not.
+
+Keep the key out of `fillable` unless request data really is allowed to choose it —
+[mass assignment](#mass-assignment) is what decides that, the same as any other column.
+
 ### @column decorator
 
 Declare typed columns. Accepts a shorthand cast string or a full options object:

package/docs/upgrade.md

@@ -371,6 +371,12 @@ routes, so a guard never drops mid-session.
 
 ### Also worth knowing (not breaking)
 
+- **A save or delete on a model with no primary-key value now raises an error** (1.15.1).
+  It used to bind NULL, match no row, and resolve as though it had written. The one way to
+  reach it is a partially hydrated instance — `Post.query().select("title").get()`, then
+  `save()` on a result — and in that state the write was already being thrown away. What
+  changes is that you hear about it: `E_NO_PRIMARY_KEY`, naming the model and the key.
+  Select the key column alongside whatever else you need, and the write works as intended.
 - **`bun zt route:types` regenerates the Inertia page registry too.** Adding a page and
   getting `TS2345: … not assignable to parameter of type 'PageName'` is now fixed by the
   command whose name says it generates types. `--check` gates on both files.

package/docs/view.md

@@ -272,9 +272,27 @@ Router.view("/terms", TermsPage)
 
 ## File-based pages
 
-Under [file-based routing](/docs/routing), a page file's **default export**
-becomes a `GET` route automatically. The page is a function of `(http, params)`
-and may be async:
+Server-rendered file-route pages are **opt-in**. Register the resolver before
+your routes are scanned — in `bootstrap/app.ts`, or a provider's `onRegister()`:
+
+```ts
+// bootstrap/app.ts
+import { registerViewFileRouteResolver } from "@zerotal/core/view";
+
+registerViewFileRouteResolver();
+```
+
+That is what makes the two conventions below work: a page's default export is
+rendered to HTML rather than treated as a plain handler, and `_layout` files are
+discovered. Without it neither applies — the default export is registered as an
+ordinary file handler and `_layout` discovery is switched off.
+
+It is opt-in because it claims every `.tsx` route file's default export, which an
+app using file routes for plain handlers has not asked for, and because `_layout`
+discovery walks the directory tree for every scanned route.
+
+With it registered, a page file's **default export** becomes a `GET` route. The
+page is a function of `(http, params)` and may be async:
 
 ```tsx fragment
 // app/views/posts/[slug].tsx  →  GET /posts/:slug
@@ -306,6 +324,41 @@ import { definePage } from "zerotal/view";
 export default definePage((http, params) => `<h1>Hello ${params.name}</h1>`);
 ```
 
+### Directory layouts — `_layout.tsx`
+
+With the resolver registered, a `_layout.tsx` beside your pages wraps every page
+in that directory and below. The nearest one wins, so a section can override the
+root:
+
+```tsx fragment
+// app/views/_layout.tsx  →  wraps every page under app/views
+export default (http: HttpContext, { children }: { children?: unknown }) => (
+  <html>
+    <body>
+      <nav>…</nav>
+      {children}
+    </body>
+  </html>
+);
+```
+
+```
+app/views/
+  _layout.tsx          ← wraps everything below
+  index.tsx
+  admin/
+    _layout.tsx        ← wraps only the admin pages
+    users.tsx
+```
+
+It is read by its **default export** — the opposite of `_middleware.ts`, which is
+read by a named `middleware` export. Both refuse to boot on the other's spelling
+rather than silently applying nothing, so a mistake here is a startup error
+naming the file, not a page that quietly renders without its chrome.
+
+A page can opt out with `export const layout = null`, or override with
+`export { SomeLayout as layout }`.
+
 ## Embedding raw HTML
 
 When you have pre-rendered markup (e.g. from a Markdown renderer) use `safe()` or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.15.0"
+    "@zerotal/core": "1.15.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.15.0"
+    "@zerotal/orm": "1.15.2"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [