@zerotal/arch 1.11.0 → 1.11.1

package/docs/changelog.md

@@ -27,6 +27,79 @@ 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.11.1 — 2026-08-31
+
+Two things the framework could not do, both reported by teams who had already
+worked around them.
+
+A patch, not a minor: nothing here breaks. Under
+[the versioning scheme](/docs/upgrade#versioning) a minor is reserved for a
+breaking change and a patch carries everything else, features included — so this
+is safe to take from any 1.11.x.
+
+### Added
+
+- **`zt version`** — which Zerotal, which Bun, which app.
+
+  ```
+  Zerotal  1.11.1
+  Bun      1.3.14
+  App      my-app 0.1.0
+  ```
+
+  It was an unknown command, so the version had to be dug out of `package.json` or
+  `node_modules` — both of which report what is _installed_ rather than what is
+  _running_, and those differ for any process that has been up since before an
+  upgrade. It reports the running one.
+
+  `--version` and `-v` answer earlier still, ahead of the runtime check, the config
+  load and the app import, because those are the things someone is asking the version
+  _about_: a config that no longer validates and an app that will not boot are the two
+  moments the question stops being idle. A version flag that only works when
+  everything else already works answers a question nobody has.
+
+  Add `--json` for a script, and prefer `zt --version --json` over
+  `zt version --json` there — the application's boot log is written to stdout, so the
+  second form puts a log line ahead of the JSON while the first never boots at all.
+  The output carries no colour, unlike every other command's, because it gets pasted
+  into bug reports and piped into parsers more than it is read on a terminal.
+
+- **`MailMessage.header()` and `MailPayload.headers`** — set a header the mail driver
+  does not build itself.
+
+  ```ts
+  new MailMessage()
+    .subject("Your weekly digest")
+    .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>`)
+    .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+  ```
+
+  `MailPayload` had `to`, `from`, `subject`, `text`, `html`, `cc`, `bcc`, `replyTo`
+  and `attachments`, and no way to add anything else — so a team that wanted
+  `List-Unsubscribe` had to patch a vendored copy of the package, and shipped a footer
+  link instead.
+
+  Those are not substitutes for one another. Gmail and Yahoo draw their native
+  unsubscribe control from the header, and a recipient who cannot find a control marks
+  the message as spam instead — a judgement that attaches to the sending domain and
+  degrades delivery of everything else it sends, including the mail people asked for.
+  Send `List-Unsubscribe-Post` alongside it: alone, the first leaves a link to follow,
+  and only the pair produces the one-click control both providers now expect.
+
+  Wired through all three drivers. SMTP writes them into the message, Resend sends
+  them as the API's `headers` object, and the log driver prints them — that last one
+  deliberately, because the reason to set a header is that a mail client does
+  something with it, and the log driver is where that gets checked before anything is
+  sent for real.
+
+  Names the drivers build themselves are refused rather than sent twice: a second
+  `Subject` is an ambiguous message, not an override, and which copy a client believes
+  is its own business. The list is exported as `RESERVED_MAIL_HEADERS`, with
+  `resolveHeaders()` beside it for anyone writing a custom transport. CR and LF in a
+  value are folded to a space — left raw they end the header and let the remainder be
+  read as further headers, which is how a `Bcc` arrives courtesy of whoever supplied a
+  tracking ID.
+
 ## 1.11.0 — 2026-08-30
 
 Two production reports, from teams taking apps live on 1.9.0 — one shipping a

package/docs/commands.md

@@ -310,6 +310,7 @@ Packages register their own — see
 
 | Command                | Description                                            |
 | ---------------------- | ------------------------------------------------------ |
+| `bun zt version`       | Show the Zerotal, Bun and app versions                 |
 | `bun zt route:list`    | List all registered routes with methods and middleware |
 | `bun zt route:types`   | Write `types/routes.generated.ts` (`--check` in CI)    |
 | `bun zt doctor`        | Check the app for silent misconfigurations             |
@@ -317,6 +318,36 @@ Packages register their own — see
 | `bun zt lint:packages` | Check every workspace package against convention rules |
 | `bun zt upgrade`       | Apply the codemods for a version upgrade               |
 
+#### Which version am I on?
+
+`bun zt version` prints the framework, the runtime and the app:
+
+```
+Zerotal  1.11.0
+Bun      1.3.14
+App      my-app 0.1.0
+```
+
+It reports the version that is **running**, which is not always the version that is
+installed — a long-running server holds the code it booted with, so an upgrade lands
+on disk without reaching it.
+
+`--version` and `-v` answer the same question without booting the application:
+
+```bash
+bun zt --version
+bun zt --version --json     # for a script
+```
+
+Prefer the flag form in scripts, for two reasons. It still answers when the app does
+not boot — a config that no longer validates is exactly when you want to know which
+version you are on. And it is the form whose output can be piped: the application's
+boot log is written to stdout, so `bun zt version --json` carries a log line ahead of
+the JSON, while `bun zt --version --json` never boots and emits nothing else.
+
+If `node_modules` contains a second Bun, the report names it. Nothing executes that
+copy — it arrives as a peer dependency — but it is the one an install would use.
+
 ### Upgrading between versions
 
 `bun zt upgrade --to <version>` applies the codemods a version gap calls for —

package/docs/notifications.md

@@ -390,6 +390,47 @@ async toMail(_n: Notifiable): Promise<MailMessage> {
 }
 ```
 
+#### Custom headers, and the unsubscribe button
+
+`header(name, value)` sets a header the driver does not build itself. The one this
+exists for is `List-Unsubscribe`:
+
+```ts fragment
+// in a Notification
+toMail(n: Notifiable): MailMessage {
+  return new MailMessage()
+    .subject("Your weekly digest")
+    .line("Here is what happened this week.")
+    .header("List-Unsubscribe", `<https://app.test/unsubscribe/${n.unsubscribeToken}>`)
+    .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+}
+```
+
+Gmail and Yahoo draw their native unsubscribe control — the one beside the sender's
+name, not the one in your footer — from that header, and there is no other way to ask
+for it. Send both headers, not just the first: alone, `List-Unsubscribe` leaves the
+recipient a link to follow, and only the pair produces a control that resolves in one
+press. The URL must accept a `POST` with no body and unsubscribe on the spot, with no
+confirmation page.
+
+It is worth more than the footer link it duplicates. A recipient who cannot find the
+control marks the message as spam instead, and that judgement attaches to the sending
+domain and affects delivery of everything else it sends — including the mail people do
+want. The two paths out of a mailing list are not equivalent for the sender.
+
+Header names the drivers build themselves are refused rather than sent twice, because
+a second `Subject` is an ambiguous message rather than an override. Those names are
+`RESERVED_MAIL_HEADERS`, and the error names the `MailMessage` method to use instead
+where there is one. The check runs when you set the header, so the throw carries the
+stack of the code that wrote it rather than of a queue worker three hops away — and
+again in the driver, since a `MailPayload` can be built without ever passing through
+`MailMessage`.
+
+Values are folded to a single line: a CR or LF in a header value ends the header and
+lets the rest be read as further headers, which is how a `Bcc` gets added by someone
+who was only supposed to be supplying a tracking ID. Writing a custom transport?
+Call `resolveHeaders()` on the payload's headers and it does both checks for you.
+
 ### database
 
 Implement `toDatabase(notifiable)` returning a plain object. The notification is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.11.0"
+    "@zerotal/core": "1.11.1"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.11.0"
+    "@zerotal/orm": "1.11.1"
   },
   "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": [