@zerotal/arch 1.13.2 → 1.13.3

package/docs/changelog.md

@@ -27,6 +27,87 @@ 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.13.3 — 2026-08-31
+
+Two things an app cannot see about itself, from two field reports. Both are the same
+shape as most of this month's work: state that is real, consequential, and invisible from
+inside the process that would want to know it.
+
+### Added
+
+- **A site gate — maintenance, and private preview.**
+  [Guide](/docs/site-gate) · `zt down` · `zt preview` · `zt up` · `zt gate:status`
+
+  Proposed by a team running a hand-edited `basic_auth` block in their reverse proxy,
+  deliberately kept out of version control so it could not be deployed and forgotten into
+  a live shop. That precaution is the feature request: the gate belongs where the app can
+  reason about it.
+
+  Two states that look alike and are not. **Maintenance** means the site is down —
+  everyone refused, staff included, because the usual reason a site is down is that its
+  database is being changed underneath it. **Private preview** means the site is up and
+  working, for the people invited to it, for weeks.
+
+  The details that make it framework work rather than app work:
+
+  - **Maintenance is always `503` with `Retry-After`, and is not configurable.** A
+    maintenance page served at `200` tells a search engine the apology is your homepage,
+    and it will index it as such.
+  - **A preview token is stripped from the URL on first use**, by redirecting to a
+    cookie. Left in the address bar it travels into `Referer` on every outbound link,
+    into analytics, and into screenshots.
+  - **Webhook paths must be declared** in `gate.allow`. A payment provider posting a
+    settlement into a maintenance window otherwise gets a 503 — a retry, a dropped
+    callback, or a payment your books never learn about.
+  - **The state is a file, and the token is stored hashed.** A flag in the database is
+    unreadable exactly when the database is what you are working on; a token in a file
+    is a credential in something every backup copies.
+  - **It covers `Router.raw()` routes.** Found by running it: this framework's own docs
+    site serves every `/docs/*` page from a raw route, so an early build gated the front
+    page — which is what a person checks — and left all the content public.
+  - **The state file is gitignored** by the scaffold, which is the entire point.
+
+- **Worker liveness — `zt doctor` can tell whether anything is running your background
+  work.** [Schedules](/docs/scheduler#is-anything-actually-running-them) ·
+  [Queue](/docs/queue#is-a-worker-running)
+
+  An app could say what it _registered_ and nothing could say whether any of it ever
+  _ran_. The reported failure: a team shipped to production with no worker process, and
+  every scheduled task silently did not execute for weeks. No hold was released, no
+  reminder was sent, nothing logged — from the web process's point of view nothing was
+  wrong, and they found it by going looking.
+
+  ```
+  ✖ Scheduler — 3 schedule(s) registered, and no worker has ever checked in.
+    Nothing is running them.
+      fix: Start the worker process: `bun zt worker`.
+  ```
+
+  The beat lives in the **cache**, because the process reading `doctor` is not the process
+  running the work and often not the same machine — and your cache driver already decides
+  what shared state can see. On `memory`, which is private to each process, the check
+  **says it cannot tell** rather than reporting a missing worker: a check that cried wolf
+  on every app using that driver is one people would learn to skip, and then it would not
+  be there for the case it exists for.
+
+  `@zerotal/core/heartbeat` exposes the primitive if you want the same signal on an ops
+  page.
+
+### Fixed
+
+- **`secureHeaders: false` no longer empties the kernel middleware.** It set the layer to
+  `[]`, which was the same thing as removing the headers right up until the site gate
+  joined it — at which point opting out of security headers would silently have taken the
+  gate with it. One feature's opt-out disabling another's is precisely what the gate is
+  otherwise about.
+
+### Documented
+
+- **Minting `APP_KEY` without the code.** `key:generate` is part of the application, so it
+  exists only once a release is installed — awkward when preparing `.env` first, since
+  `migrate` wants the file and the file wants a key. `openssl rand -base64 32` produces
+  exactly what `key:generate` writes; the [deployment guide](/docs/deployment) now says so.
+
 ## 1.13.2 — 2026-08-31
 
 From a production field report at 1.12.0 — an Inertia + React app on SQLite, 117 routes,

package/docs/deployment.md

@@ -213,6 +213,19 @@ DATABASE_URL=postgres://user:pass@db-host:5432/app
 and a `base64:`-prefixed one are accepted. Generate it **on the server** — a key carried
 from a laptop is a key that has been in a shell history and a scrollback buffer.
 
+**On a first deploy you do not have to wait for the code.** `key:generate` is part of the
+application, so it only exists once the release is installed — which is awkward if you are
+preparing `.env` before that, since `migrate` wants the file and the file wants a key.
+There is nothing framework-specific about the value:
+
+```bash fragment
+openssl rand -base64 32
+```
+
+That is exactly what `key:generate` produces — 32 random bytes, base64 — so a key minted
+this way is indistinguishable from one it wrote. Use whichever fits the order you deploy
+in.
+
 `APP_ENV` accepts deployment names like `production` and `staging`; they all normalize to
 the `web` runtime mode — they describe _where_ the app runs, not _how_. See
 [Configuration](/docs/config-system).

package/docs/index.md

@@ -40,7 +40,7 @@ cd my-app && bun dev
 | See what's running in production   | [Logger](/docs/logger) · [Monitor](/docs/monitor) · [Telemetry](/docs/telemetry) · [Health](/docs/health)                                         |
 | Debug what it just did             | [DevTools](/docs/devtools) · [Errors](/docs/errors)                                                                                               |
 | Work with a coding agent           | [Agent Surface](/docs/arch)                                                                                                                       |
-| Ship it                            | [Deployment](/docs/deployment) · [Commands](/docs/commands)                                                                                       |
+| Ship it                            | [Deployment](/docs/deployment) · [Site gate](/docs/site-gate) · [Commands](/docs/commands)                                                        |
 
 ## Choosing a frontend
 

package/docs/queue.md

@@ -353,6 +353,24 @@ needed, so chaining works with any driver.
 
 ## Processing jobs
 
+### Is a worker running?
+
+Jobs waiting with nothing to run them is the same failure as an unrun schedule, one layer
+over: the queue fills, nothing errors, and you find out when a customer asks where their
+email went.
+
+`zt doctor` reports it, keyed on the **pending depth** rather than on whether any job
+class exists — an app with an empty queue and no worker may be perfectly fine:
+
+```
+✖ Queue worker — 4102 job(s) waiting, and no worker has ever checked in.
+    fix: Start the worker process: `bun zt worker`.
+```
+
+The same shared-cache caveat applies as for [schedules](/docs/scheduler#is-anything-actually-running-them):
+the beat lives in the cache, so a `memory` driver means the check stands aside rather
+than guessing.
+
 ### Dedicated worker process
 
 The standard way to process jobs in production is a long-running worker process:

package/docs/scheduler.md

@@ -301,6 +301,69 @@ Scheduled tasks (2)
   Next run     2026-06-22T06:00:00.000Z
 ```
 
+## Is anything actually running them?
+
+Schedules register in the `worker` and `console` environments, not in `web`. That is the
+right design — HTTP instances should not run cron — and it means **a second process is
+required.** The framework starts happily without one.
+
+An app shipped to production with no worker, and every scheduled task silently did not
+execute for weeks. No hold was released, no reminder was sent, nothing logged, because
+from the web process's point of view nothing was wrong. They found it by going looking.
+
+`zt doctor` now looks for you:
+
+```
+✖ Scheduler — 3 schedule(s) registered, and no worker has ever checked in. Nothing is
+  running them. This is silent by nature — the web process has no way to notice, and
+  the work simply does not happen.
+    fix: Start the worker process: `bun zt worker`. It is a second process; the web
+         server does not run this.
+```
+
+The worker records a check-in every minute while it runs. A check-in older than fifteen
+minutes is a warning rather than a failure, because a worker mid-restart is not a
+missing worker.
+
+### It needs a shared cache to mean anything
+
+The beat is written to the cache, because the process reading `doctor` is not the
+process running the schedules — and often not the same machine. Your cache driver
+decides what that can see:
+
+| Driver             | Sees a worker on…                       |
+| ------------------ | --------------------------------------- |
+| `sqlite` (default) | another process on the same box         |
+| `redis`            | another machine                         |
+| `memory`           | nothing — it is private to each process |
+
+On `memory` the check **stands aside and says so** rather than reporting a missing
+worker. A check that cried wolf on every app using the memory driver is one people would
+learn to skip, and then it would not be there for the case it exists for.
+
+### Reading it yourself
+
+The primitive is `@zerotal/core/heartbeat`, if you want the same signal on an ops page:
+
+```ts
+import { Heartbeat } from "@zerotal/core/heartbeat";
+
+const seen = await Heartbeat.lastSeen("scheduler");
+// { status: "seen", ageSeconds, beat } | { status: "never" } | { status: "unknown", reason }
+```
+
+| Name                  | Description                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `Heartbeat`           | `beat()` records a check-in, `start()` beats on an interval and returns a stopper, `lastSeen()` reads one. |
+| `Beat`                | What a check-in records — `at`, `pid`, `detail`.                                                           |
+| `BeatLookup`          | The three answers: `seen`, `never`, and `unknown` with a reason.                                           |
+| `workerLivenessCheck` | Builds the doctor check above for a worker kind.                                                           |
+| `describeBeat`        | Renders a `BeatLookup` as the prose used in the report.                                                    |
+
+`unknown` is a distinct answer from `never` on purpose, and every consumer has to keep
+them apart: one means nothing is running, the other means this process cannot see whether
+anything is.
+
 ## Run history
 
 Every completed execution — success or failure — is recorded to a capped JSONL

package/docs/site-gate.md

@@ -0,0 +1,179 @@
+---
+title: Site gate
+description: Maintenance mode and private preview — take a site down correctly, or open it only to the people you invite.
+---
+
+# Site gate
+
+Two states a site can be in that are not "serving the public", and they are not the
+same thing.
+
+**Maintenance** — the site is _down_. Nobody may use it, staff included, because the
+usual reason a site is down is that its database is being changed underneath it, and
+letting one person in is letting them into that. Minutes, not weeks. Every request is
+answered `503` with `Retry-After`.
+
+**Private preview** — the site is _up and working perfectly_, for the people invited to
+it. Not down, not broken, not public yet. Weeks. An invited visitor gets the real site
+at `200` and can transact on it; the public gets a holding page.
+
+Building one and calling it both is the usual mistake, and it is why a pre-launch site
+ends up behind a `503` that search engines take seriously.
+
+## Turning it on
+
+```bash
+bun zt down --retry=120          # maintenance
+bun zt preview                   # private preview; prints the link
+bun zt preview --until=2026-09-30
+bun zt up                        # open again
+bun zt gate:status               # what is it doing
+```
+
+`zt preview` generates the token when you do not pass one, because a token typed by a
+person is the only thing between the public and an unlaunched site and nothing
+rate-limits guesses at it. **Keep the link it prints** — only a hash is stored, so the
+token cannot be read back.
+
+These four commands need no application and are registered in every environment. A
+maintenance command that only works when the app boots is one you cannot reach at the
+moment you need it.
+
+## From your own console
+
+The framework's job is the primitive; the button is yours.
+
+```ts
+import { Gate } from "@zerotal/core/gate";
+
+await Gate.preview({ token, until: "2026-09-30", by: user.name });
+await Gate.maintenance({ retryAfter: 120, by: user.name });
+await Gate.open();
+
+Gate.status(); // { mode, since, until, by, expired } — never the token
+```
+
+## Getting in
+
+**A secret link.** `https://example.com/?preview=<token>`. The gate recognises the
+token, sets a signed `HttpOnly` `SameSite=Lax` cookie, and **redirects to the same URL
+with the parameter removed.**
+
+That redirect is not tidiness. A token left in the address bar travels into `Referer`
+on every outbound link, into analytics, into screenshots, and into the message where
+somebody shares "the page I was looking at". Stripping it on first use leaves the
+secret in a cookie and nowhere else.
+
+**A signed-in staff account.** A request whose authenticated user has any role other
+than `customer` is admitted without a token, so an app that already has staff accounts
+does not need a second secret for the same people.
+
+The cookie lasts seven days. A preview cookie with no lifetime means an ex-tester keeps
+access to a site that has since gone live with real customer data.
+
+**Rotating revokes.** `zt preview --token=<new>` invalidates every cookie issued under
+the previous token, because the way a preview leaks is a tester forwarding the link to
+somebody who has left.
+
+## What stays reachable
+
+These are open whatever the gate is doing:
+
+| Path                                           | Why                                                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `/__zerotal/*`                                 | The health endpoint. Otherwise the uptime monitor pages the on-call about a planned window, and a deploy gate that polls health fails its own release. |
+| `/css/*`, `/js/*`, `/assets/*`, `/favicon.ico` | A maintenance page that 503s its own stylesheet is an unstyled apology.                                                                                |
+
+**Your webhooks are not on that list, and this is the one that costs money.**
+
+A payment provider posting a settlement into a maintenance window gets a `503`, and
+depending on the provider that is a retry, a dropped callback, or a payment your books
+never learn about. Nothing can infer which of your routes a third party calls, so it
+has to be declared:
+
+```ts
+// config/gate.ts
+export default {
+  allow: ["/webhooks/", "/api/callbacks/"],
+};
+```
+
+## What the public gets during a preview
+
+`200` with a holding page by default, which is right for a pre-launch site collecting
+an email address. Set `publicResponse: "notFound"` when the site's existence is itself
+not public:
+
+```ts
+// config/gate.ts
+export default { publicResponse: "notFound" };
+```
+
+Both are legitimate and the framework does not pick. **Maintenance is always `503`** and
+is not configurable, because that one is not a preference: a maintenance page served at
+`200` tells a search engine that "we will be back shortly" is the content of your
+homepage, and it will index it as such. Sites have lost their rankings to a two-hour
+window served at the wrong status code.
+
+## Where the state lives
+
+`storage/framework/gate.json`, not the database.
+
+A flag in the database is unreadable exactly when the database is the thing you are
+working on, so a maintenance mode kept there works only on the days you did not need
+it. The file is also why the gate survives a restart — an in-memory flag would be
+lifted by the very deploy it was supposed to run behind.
+
+The preview token is stored as a **hash**. The file sits on disk, readable by anything
+on the box and copied by every backup, and putting a live credential in it would be the
+same mistake as an `.env.example` carrying a working key.
+
+A file the gate cannot parse reads as **open**, deliberately. Failing closed would take
+a site down because a JSON file lost a brace, and "the site is up" is the safer error
+for a mechanism whose whole purpose is to be turned off again.
+
+## It covers raw routes too
+
+`Router.raw()` bypasses the middleware pipeline by design — that is what it is for. It
+does **not** bypass the gate.
+
+A gate that covered only the pipeline would be the worst kind, because it gates the
+homepage and therefore looks like it works. This framework's own documentation site
+serves every `/docs/*` page from a raw route: with an early build of the gate on, the
+front page said "coming soon" and every page of content stayed public.
+
+Raw routes get no staff bypass, since no session has been resolved by then — the token
+cookie is the only way through.
+
+## `zt doctor` reports it
+
+A gate is the most reversible thing in the framework and the easiest to forget, because
+when it is working nothing complains: the people who would notice are the ones being
+kept out, and they have no way to tell you.
+
+- **Maintenance in production** is reported as a failure. It is an outage.
+- **A preview in production** is a warning naming who set it and when, since a
+  pre-launch gate is usually deliberate.
+- **A preview whose `until` has passed** is its own warning: the file says the site is
+  gated and it is not, so what a reader believes and what visitors get have come apart.
+
+## Reference
+
+| Name                 | Description                                                                  |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `Gate`               | Read and write the gate: `maintenance()`, `preview()`, `open()`, `status()`. |
+| `GateStatus`         | What `Gate.status()` returns. Never includes the token.                      |
+| `MaintenanceOptions` | `retryAfter`, `by`.                                                          |
+| `PreviewOptions`     | `token`, `until`, `by`.                                                      |
+| `GateMiddleware`     | The kernel middleware that answers for a closed site.                        |
+| `GateState`          | The shape written to `storage/framework/gate.json`.                          |
+| `GateMode`           | `"maintenance"                                                               | "preview"`. |
+| `readGate`           | Read the state file, or `null` when the site is open.                        |
+| `gateExpired`        | Whether a preview's `until` has passed.                                      |
+| `GATE_FILE`          | Path of the state file, relative to the project root.                        |
+| `GATE_COOKIE`        | Name of the cookie the gate issues.                                          |
+| `GATE_QUERY`         | The query parameter that carries a token — `preview`.                        |
+| `bun zt down`        | `DownCommand` — maintenance on.                                              |
+| `bun zt preview`     | `PreviewCommand` — private preview on, prints the link.                      |
+| `bun zt up`          | `UpCommand` — open the site.                                                 |
+| `bun zt gate:status` | `GateStatusCommand` — what the gate is doing.                                |

package/package.json

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