@zerotal/core 1.13.1 → 1.13.3

package/CHANGELOG.md

@@ -8,6 +8,70 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.13.3] — 2026-08-31
+
+### Added
+
+- **`Heartbeat` — which background processes are actually running.** An app could say what
+  it _registered_ and nothing could say whether any of it ever _ran_.
+
+  The failure this exists for was reported from production: an app shipped with no worker
+  process, and every scheduled task silently did not execute for weeks. No hold was
+  released, no reminder was sent, and nothing logged, because from the web process's point
+  of view nothing was wrong. They found it by going looking.
+
+  `@zerotal/core/heartbeat` — `beat()`, `start()`, `lastSeen()`, and `workerLivenessCheck()`
+  for building the doctor check.
+
+  The beat lives in the **cache**, because the reader is a different process from the
+  writer and often a different machine, and the app has already chosen where its shared
+  state goes. `sqlite` (the default) is shared across processes on one box, `redis` across
+  machines, `memory` with nobody — which is why `lastSeen()` returns a distinct
+  `"unknown"` rather than `"never"`. A check that reported a missing worker on every app
+  using the memory driver would be wrong more often than right, and a check that is
+  usually wrong is one people learn to skip.
+
+### Added
+
+- **A site gate — maintenance, and private preview.** From a proposal by the Trekly team,
+  who were running a hand-edited `basic_auth` block in a reverse proxy, deliberately kept
+  out of version control so it could not be deployed and forgotten into a live shop.
+
+  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.
+
+  `zt down`, `zt preview`, `zt up`, `zt gate:status`, and a `Gate` API at
+  `@zerotal/core/gate` so an app can build its own switch. See
+  [the guide](https://zerotal.dev/docs/site-gate).
+
+  The details that are the reason this belongs in the framework rather than in each app:
+
+  - **Maintenance is always `503` with `Retry-After`, and is not configurable.** A
+    maintenance page at `200` tells a search engine the apology is your homepage.
+  - **A preview token is stripped from the URL on first use**, via a redirect to a cookie.
+    Left in the address bar it travels into `Referer`, analytics and screenshots.
+  - **Webhook paths must be declared** in `gate.allow`. A payment provider posting a
+    settlement into a maintenance window otherwise gets a 503, and that is 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 while testing: 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.
+  - **`zt doctor` reports a gate left on**, and a preview whose `until` has passed.
+  - **The state file is gitignored** by the scaffold, which is the whole point.
+
+### Fixed
+
+- **`secureHeaders: false` no longer empties the kernel.** It set the kernel middleware to
+  `[]`, which was the same thing as removing the headers until the gate joined that layer —
+  at which point opting out of security headers would silently have taken the site gate
+  with it. One feature's opt-out disabling another's is the failure the gate is otherwise
+  about.
+
 ## [1.13.0] — 2026-08-31
 
 ### Changed — **BREAKING**

package/api-surface.md

@@ -1448,6 +1448,62 @@ class DoctorCommand = {
   write: (msg: string) => void
 }
 
+class DownCommand = {
+  new (): DownCommand
+  static args: never[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    type: 'number';    description: string;    default: number;} | {    name: string;    type: 'string';    description: string;    default?: never;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
+class GateStatusCommand = {
+  new (): GateStatusCommand
+  static args: never[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    type: 'boolean';    description: string;    default: boolean;}[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class KeyGenerateCommand = {
   new (): KeyGenerateCommand
   static args: never[]
@@ -1896,6 +1952,34 @@ class MakeTestCommand = {
   write: (msg: string) => void
 }
 
+class PreviewCommand = {
+  new (): PreviewCommand
+  static args: never[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    type: 'string';    description: string;}[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class ReloadCommand = {
   new (): ReloadCommand
   static args: never[]
@@ -2123,6 +2207,34 @@ class TestCommand = {
   write: (msg: string) => void
 }
 
+class UpCommand = {
+  new (): UpCommand
+  static args: never[]
+  static commandName: string
+  static description: string
+  static flags: never[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class UpgradeCommand = {
   new (): UpgradeCommand
   static args: ArgDef[]
@@ -2625,6 +2737,59 @@ interface ArtisanResult = {
   output: string
 }
 
+## ./gate  `(./src/gate/index.ts)`
+
+class GateMiddleware = {
+  new (): GateMiddleware
+  static with: <T extends new (...args: any[]) => BaseMiddleware<any>, Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object>(this: T, options: DeepPartial<NoInfer<Opts>>) => new () => InstanceType<T>
+  afterResponse?: (ctx: HttpContext) => Promise<void>
+  handle: (ctx: HttpContext, next: NextFn) => Promise<Response | void>
+  onError?: (ctx: HttpContext, error: Error) => Promise<void>
+}
+
+const Gate = {    maintenance(options?: MaintenanceOptions): Promise<void>;    preview(options: PreviewOptions): Promise<void>;    open(): Promise<void>;    status(): GateStatus;}
+
+const GATE_COOKIE = 'zerotal_preview'
+
+const GATE_FILE = string
+
+const GATE_QUERY = 'preview'
+
+function gateExpired = (state: GateState, now?: Date) => boolean
+
+function readGate = (root?: string) => GateState | null
+
+interface GateState = {
+  by?: string | undefined
+  mode: GateMode
+  retryAfter?: number | undefined
+  since: string
+  tokenHash?: string | undefined
+  until?: string | undefined
+}
+
+interface GateStatus = {
+  by?: string | undefined
+  expired?: boolean | undefined
+  mode: 'open' | GateMode
+  retryAfter?: number | undefined
+  since?: string | undefined
+  until?: string | undefined
+}
+
+interface MaintenanceOptions = {
+  by?: string | undefined
+  retryAfter?: number | undefined
+}
+
+interface PreviewOptions = {
+  by?: string | undefined
+  token: string
+  until?: string | undefined
+}
+
+type GateMode = 'maintenance' | 'preview'
+
 ## ./health  `(./src/health/index.ts)`
 
 const Health = HealthRegistry
@@ -2669,6 +2834,22 @@ type HealthCheckFn = () => Promise<HealthResult | void> | HealthResult | void
 
 type HealthStatus = 'ok' | 'degraded' | 'down'
 
+## ./heartbeat  `(./src/heartbeat/index.ts)`
+
+const Heartbeat = {    beat(name: string, extra?: Omit<Beat, 'at'>): Promise<void>;    start(name: string, extra?: Omit<Beat, 'at'>, everyMs?: number): () => void;    lastSeen(name: string): Promise<BeatLookup>;}
+
+function describeBeat = (lookup: BeatLookup) => string
+
+function workerLivenessCheck = (options: WorkerLivenessOptions) => DoctorCheck
+
+interface Beat = {
+  at: string
+  detail?: string | undefined
+  pid?: number | undefined
+}
+
+type BeatLookup = { status: 'seen'; beat: Beat; ageSeconds: number } | { status: 'never' } | { status: 'unknown'; reason: string }
+
 ## ./helpers  `(./src/helpers/index.ts)`
 
 const Str = {    camelCase(value: string): string;    snakeCase(value: string): string;    slugify(value: string): string;    titleCase(value: string): string;    pascalCase(value: string): string;    capitalize(value: string): string;    lcfirst(value: string): string;    truncate(value: string, maxLength: number, suffix?: string): string;    isAlphanumeric(value: string): boolean;    padLeft(value: string, length: number, char?: string): string;    kebab(value: string): string;    squish(value: string): string;    finish(value: string, cap: string): string;    start(value: string, prefix: string): string;    after(value: string, needle: string): string;    before(value: string, needle: string): string;    afterLast(value: string, needle: string): string;    beforeLast(value: string, needle: string): string;    contains(value: string, substring: string): boolean;    random(length?: number): string;    replaceFirst(value: string, search: string, replace: string): string;    replaceLast(value: string, search: string, replace: string): string;    reverse(value: string): string;    words(value: string, maxWords: number, suffix?: string): string;    macro(name: string, fn: (...args: unknown[]) => unknown): void;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.13.1",
+  "version": "1.13.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -17,6 +17,8 @@
     "./commands": "./src/command/builtin/index.ts",
     "./helpers": "./src/helpers/index.ts",
     "./runtime": "./src/support/runtime.ts",
+    "./gate": "./src/gate/index.ts",
+    "./heartbeat": "./src/heartbeat/index.ts",
     "./shared": "./src/shared/index.ts",
     "./facades": "./src/facade/facades/index.ts",
     "./carbon": "./src/datetime/index.ts",

package/src/application/Application.ts

@@ -32,6 +32,7 @@ import {
   SecureHeadersMiddleware,
   staticSecurityHeaders,
 } from "../middleware/SecureHeadersMiddleware.ts";
+import { GateMiddleware } from "../gate/GateMiddleware.ts";
 import { isAllowedOrigin, allowedOriginsFrom } from "../http/originGuard.ts";
 import { rescueSync } from "../helpers/index.ts";
 import {
@@ -525,7 +526,15 @@ export class Application {
 
     const app = new Application();
     app._env = resolvedEnv;
-    if (options.secureHeaders === false) app._kernelMiddleware = [];
+    // Remove only the headers, not the whole kernel. Emptying it used to be the
+    // same thing; once the gate joined the kernel it stopped being, and
+    // `secureHeaders: false` would have silently taken a site's maintenance mode
+    // with it — an opt-out for one feature disabling an unrelated one.
+    if (options.secureHeaders === false) {
+      app._kernelMiddleware = app._kernelMiddleware.filter(
+        (pipe) => pipe !== SecureHeadersMiddleware,
+      );
+    }
     if (options.providers) for (const provider of options.providers) app._addProvider(provider);
     if (options.config) {
       app._configMap =
@@ -899,7 +908,11 @@ export class Application {
    * documenting it and hoping — shipped every scaffold with no clickjacking protection and
    * no MIME-sniffing protection. Cleared by `Application.create({ secureHeaders: false })`.
    */
-  private _kernelMiddleware: PipeClass[] = [SecureHeadersMiddleware];
+  // GateMiddleware first, and before SecureHeaders: a closed site should answer
+  // from the gate without anything else running, including the session and
+  // anything that reaches the database — which in maintenance mode may be the
+  // thing that is unavailable.
+  private _kernelMiddleware: PipeClass[] = [GateMiddleware, SecureHeadersMiddleware];
 
   /** Resolved middleware pipeline: kernel → provider auto → explicit .use() */
   private get _pipeline(): PipeClass[] {

package/src/command/CommandRunner.ts

@@ -344,6 +344,10 @@ export class CommandRunner {
       ReloadCommand,
       StatusCommand,
       VersionCommand,
+      DownCommand,
+      PreviewCommand,
+      UpCommand,
+      GateStatusCommand,
       MakeControllerCommand,
       MakeMiddlewareCommand,
       MakeCommandCommand,
@@ -386,6 +390,15 @@ export class CommandRunner {
     // "which version is this" must not depend on which environment is asking.
     this.register(VersionCommand);
 
+    // The gate is changed at the moments things are going wrong — before a
+    // migration, during an incident — so these are registered in every
+    // environment and need no application. A maintenance command that only
+    // works when the app boots is one you cannot reach when you need it.
+    this.register(DownCommand);
+    this.register(PreviewCommand);
+    this.register(UpCommand);
+    this.register(GateStatusCommand);
+
     // route:list and doctor are inspection commands — always available regardless of mode.
     this.register(RouteListCommand);
     this.register(DoctorCommand);

package/src/command/builtin/GateCommands.ts

@@ -0,0 +1,171 @@
+import { Command } from "../Command.ts";
+import { Gate } from "../../gate/Gate.ts";
+
+/**
+ * `bun zt down` — take the site down for maintenance.
+ *
+ * Every request is answered `503` with `Retry-After`, 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.
+ *
+ * @example
+ * ```bash
+ * bun zt down --retry=120
+ * bun zt up
+ * ```
+ *
+ * @category Serving
+ */
+export class DownCommand extends Command {
+  static override commandName = "down";
+  static override description = "Take the site down for maintenance (503 + Retry-After)";
+  static override needsApp = false;
+  static override args = [];
+  static override flags = [
+    {
+      name: "retry",
+      type: "number" as const,
+      description: "Seconds to advertise in Retry-After",
+      default: 60,
+    },
+    { name: "by", type: "string" as const, description: "Who is taking it down" },
+  ];
+
+  async run(): Promise<void> {
+    const retryAfter = this.flags["retry"] as number;
+    const by = this.flags["by"] as string | undefined;
+
+    await Gate.maintenance({ retryAfter, ...(by ? { by } : {}) });
+
+    this.info(`Site is down. Answering 503 with Retry-After: ${retryAfter}.`);
+    this.dim("Health checks and static assets stay reachable. `bun zt up` to restore.");
+    this.dim("Webhook paths do NOT — declare them in config/gate.ts `allow` first.");
+  }
+}
+
+/**
+ * `bun zt preview` — put the site behind a private preview.
+ *
+ * The site works normally for anyone holding the token; the public gets a
+ * holding page. Unlike `down`, this is not an outage — invited people can
+ * transact.
+ *
+ * @example
+ * ```bash
+ * bun zt preview                       # generates a token and prints the link
+ * bun zt preview --until=2026-09-30
+ * ```
+ *
+ * @category Serving
+ */
+export class PreviewCommand extends Command {
+  static override commandName = "preview";
+  static override description = "Put the site behind a private preview link";
+  static override needsApp = false;
+  static override args = [];
+  static override flags = [
+    {
+      name: "token",
+      type: "string" as const,
+      description: "Token to use. Generated when omitted; pass a new one to rotate",
+    },
+    {
+      name: "until",
+      type: "string" as const,
+      description: "ISO date the preview lifts, e.g. 2026-09-30",
+    },
+    { name: "by", type: "string" as const, description: "Who is raising it" },
+    { name: "url", type: "string" as const, description: "Base URL to print the link against" },
+  ];
+
+  async run(): Promise<void> {
+    // Generated rather than asked for by default. A token typed by a person is
+    // the one thing standing between the public and an unlaunched site, and
+    // nothing rate-limits guesses at it.
+    const token =
+      (this.flags["token"] as string | undefined) ?? crypto.randomUUID().replace(/-/g, "");
+    const until = this.flags["until"] as string | undefined;
+    const by = this.flags["by"] as string | undefined;
+    const base = (this.flags["url"] as string | undefined) ?? "https://your-site";
+
+    const rotating = Gate.status().mode === "preview";
+    await Gate.preview({ token, ...(until ? { until } : {}), ...(by ? { by } : {}) });
+
+    this.info("Site is in private preview.");
+    this.newLine();
+    this.line(`  ${base}/?preview=${token}`);
+    this.newLine();
+    this.dim("Keep that link — the token is stored as a hash and cannot be read back.");
+    if (rotating) this.warn("Rotated: every previously issued preview cookie has stopped working.");
+    if (until) this.dim(`Lifts itself after ${until}.`);
+  }
+}
+
+/**
+ * `bun zt up` — open the site to the public again.
+ *
+ * @category Serving
+ */
+export class UpCommand extends Command {
+  static override commandName = "up";
+  static override description = "Open the site — clears maintenance or preview";
+  static override needsApp = false;
+  static override args = [];
+  static override flags = [];
+
+  async run(): Promise<void> {
+    const before = Gate.status();
+    await Gate.open();
+
+    if (before.mode === "open") {
+      this.info("Site was already open. Nothing to do.");
+      return;
+    }
+    this.info(`Site is open. Was in ${before.mode} since ${before.since ?? "unknown"}.`);
+  }
+}
+
+/**
+ * `bun zt gate:status` — what the gate is doing.
+ *
+ * @category Diagnostics
+ */
+export class GateStatusCommand extends Command {
+  static override commandName = "gate:status";
+  static override description = "Show whether the site is open, in maintenance, or in preview";
+  static override needsApp = false;
+  static override args = [];
+  static override flags = [
+    { name: "json", type: "boolean" as const, description: "Print as JSON", default: false },
+  ];
+
+  async run(): Promise<void> {
+    const status = Gate.status();
+
+    if (this.flags["json"] === true) {
+      // `write`, not `line`: the other helpers colour, and a colour code is not
+      // JSON.
+      this.write(`${JSON.stringify(status, null, 2)}\n`);
+      return;
+    }
+
+    if (status.mode === "open") {
+      this.info("Site is open.");
+      return;
+    }
+
+    this.table([
+      ["Mode", status.mode],
+      ["Since", status.since ?? "—"],
+      ["Until", status.until ?? "—"],
+      ["By", status.by ?? "—"],
+      ...(status.mode === "maintenance"
+        ? ([["Retry-After", String(status.retryAfter ?? 60)]] as [string, string][])
+        : []),
+    ]);
+
+    if (status.expired) {
+      this.warn("This preview's window has passed — it is no longer gating anything.");
+    }
+  }
+}

package/src/command/builtin/index.ts

@@ -34,6 +34,7 @@ export { KeyGenerateCommand } from "./KeyGenerateCommand.ts";
 export { ReloadCommand } from "./ReloadCommand.ts";
 export { StatusCommand } from "./StatusCommand.ts";
 export { VersionCommand } from "./VersionCommand.ts";
+export { DownCommand, PreviewCommand, UpCommand, GateStatusCommand } from "./GateCommands.ts";
 export { MakeControllerCommand } from "./MakeControllerCommand.ts";
 export { MakeMiddlewareCommand } from "./MakeMiddlewareCommand.ts";
 export { MakeCommandCommand } from "./MakeCommandCommand.ts";

package/src/doctor/AppDoctor.ts

@@ -12,6 +12,7 @@
  * scheduler's static-config check is the model); the built-ins cover core.
  */
 import { readdirSync } from "node:fs";
+import { siteGateCheck } from "../gate/doctor.ts";
 import type { Application } from "../application/Application.ts";
 import { appKeyStrengthWarning } from "../support/appKey.ts";
 import { unroutedRoutesWarning } from "../support/unroutedRoutes.ts";
@@ -409,6 +410,7 @@ const throttleIdentityCheck: DoctorCheck = {
  */
 export const builtinDoctorChecks: DoctorCheck[] = [
   appKeyCheck,
+  siteGateCheck,
   allowedOriginsCheck,
   corsWildcardCheck,
   secureHeadersCheck,