@zerotal/core 1.8.1 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -16,6 +16,8 @@
     "./logger": "./src/logger/index.ts",
     "./commands": "./src/command/builtin/index.ts",
     "./helpers": "./src/helpers/index.ts",
+    "./runtime": "./src/support/runtime.ts",
+    "./shared": "./src/shared/index.ts",
     "./facades": "./src/facade/facades/index.ts",
     "./carbon": "./src/datetime/index.ts",
     "./http": "./src/http/index.ts",

package/src/application/Application.ts

@@ -96,6 +96,8 @@ async function _discoverConfig(dir: string): Promise<Record<string, Record<strin
  *   "web" → prefix: "",     middleware: ["web"]
  *   "api" → prefix: "/api", middleware: ["api"]
  * Custom keys must declare both `prefix` and `middleware` explicitly.
+ *
+ * @internal
  */
 export type RoutingEntry = string | { file: string; prefix?: string; middleware?: MiddlewareInput };
 
@@ -105,6 +107,8 @@ export type RoutingConfig = Record<string, RoutingEntry>;
 /**
  * A single entry in a `fileBasedRouting()` config map.
  * Same semantics as `RoutingEntry` but points to a directory instead of a file.
+ *
+ * @internal
  */
 export type FileRoutingEntry =
   string | { dir: string; prefix?: string; middleware?: MiddlewareInput };
@@ -178,9 +182,9 @@ type PipeClass = new (...args: any[]) => Pipe<HttpContext>;
 
 /** Options form for `Application.create({ ... })`. */
 export interface CreateOptions {
-  providers?: ProviderClass[];
-  env?: Environment;
-  config?: ConfigLoader | ConfigMap;
+  providers?: ProviderClass[] | undefined;
+  env?: Environment | undefined;
+  config?: ConfigLoader | ConfigMap | undefined;
   /**
    * Drop {@link SecureHeadersMiddleware} from the front of the pipeline.
    *
@@ -190,7 +194,7 @@ export interface CreateOptions {
    * `config('app.secureHeaders')`; turn it off only when a proxy in front of the app is
    * already emitting the same headers.
    */
-  secureHeaders?: false;
+  secureHeaders?: false | undefined;
 }
 
 function _normaliseEnv(raw: string): Environment {
@@ -271,6 +275,8 @@ export interface WebSocketHandlers {
 /**
  * Installs application-scoped state and returns a teardown function that
  * restores the previous state when the application is reset.
+ *
+ * @internal
  */
 export type AppScopeInstaller = () => () => void;
 

package/src/application/currentApp.ts

@@ -51,7 +51,11 @@ export function currentApp(): Application {
   return app;
 }
 
-/** The current application, or `undefined` when none is available. Safe off-app (CLI bootstrap, tests). */
+/**
+ * The current application, or `undefined` when none is available. Safe off-app (CLI bootstrap, tests).
+ *
+ * @internal
+ */
 export function tryCurrentApp(): Application | undefined {
   return _scope.getStore() ?? _default;
 }
@@ -67,6 +71,8 @@ export function tryCurrentApp(): Application | undefined {
  * // Run a migration against a second app's config without disturbing the default.
  * await withApp(secondApp, () => secondApp.container.make("db"));
  * ```
+ *
+ * @internal
  */
 export function withApp<T>(app: Application, fn: () => T): T {
   return _scope.run(app, fn);

package/src/build/codemod.ts

@@ -40,7 +40,7 @@ export interface RegisterProviderOptions {
   /** Import specifier, e.g. '../app/providers/FooProvider.ts' or '@zerotal/foo'. */
   importPath: string;
   /** Bootstrap file. Default: 'bootstrap/providers.ts'. */
-  bootstrapPath?: string;
+  bootstrapPath?: string | undefined;
 }
 
 /**

package/src/command/CommandRunner.ts

@@ -363,6 +363,7 @@ export class CommandRunner {
       MakeProviderCommand,
       CssBuildCommand,
       AssetsBuildCommand,
+      AssetsPruneCommand,
       LintPackagesCommand,
       MakePackageCommand,
     } = await import("./builtin/index.ts");
@@ -414,6 +415,7 @@ export class CommandRunner {
         TestCommand,
         CssBuildCommand,
         AssetsBuildCommand,
+        AssetsPruneCommand,
         LintPackagesCommand,
         MakePackageCommand,
       ]);

package/src/command/OutputWriter.ts

@@ -13,7 +13,11 @@ export interface OutputWriter {
   writeError(message: string): void;
 }
 
-/** Default writer — output goes to the terminal */
+/**
+ * Default writer — output goes to the terminal
+ *
+ * @internal
+ */
 export class TerminalWriter implements OutputWriter {
   // Explicit constructor so JSC's function-coverage counter attributes
   // the new TerminalWriter() call to this entry.

package/src/command/builtin/AssetsPruneCommand.ts

@@ -0,0 +1,138 @@
+import { readdir, unlink } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { Command } from "../Command.ts";
+import type { Application } from "../../application/Application.ts";
+import type { ConfigManager } from "../../config/ConfigManager.ts";
+import { _recordedBuildOutput } from "../../dev/BuildOutput.ts";
+import type { AssetBuildConfig } from "../../dev/CssPlugins.ts";
+
+/** Bundler-generated code-split chunk, e.g. `chunk-2502z4dn.js` (+ `.map`). */
+const CHUNK_NAME = /^chunk-[a-z0-9]+\.js(\.map)?$/i;
+
+/**
+ * `bun zt assets:prune` — remove the chunks a previous release left behind.
+ *
+ * `assets:build --clean` cleans the directory it *builds into*, which is the build
+ * machine. It does nothing for the common release shape: build here, tar the output,
+ * extract it over `public/` there. Extracting a tarball merges — nothing removes a
+ * file the new release does not contain — so every deploy adds another set of
+ * content-hashed chunks to a directory that only ever grows. One app reached 225
+ * chunk files on disk for the 49 its entry point references.
+ *
+ * Nothing breaks while that happens, which is why it runs for months unnoticed. The
+ * accumulation even *masks* a stale-cache bug, because the pruned chunk an old
+ * browser asks for is usually still lying there. But it grows without bound on a box
+ * with a disk quota, and a release process that cannot say which files belong to the
+ * current release is one that cannot clean up after itself.
+ *
+ * This is that answer. `assets:build` records what it wrote; ship `.zerotal/` with
+ * the release and this removes what the record does not claim.
+ *
+ * ## What it will and will not delete
+ *
+ * Only two things qualify: a file an *earlier* recorded build wrote that the current
+ * one did not, and a file named the way the bundler names a code-split chunk.
+ * Everything else is left alone, because an output directory is usually `public/`,
+ * where a blanket sweep takes the app's images and favicon with it.
+ *
+ * @example
+ * ```bash
+ * # on the server, after extracting the release and before the restart
+ * bun zt assets:prune --dry-run   # list what would go
+ * bun zt assets:prune
+ * ```
+ *
+ * @category Build & assets
+ */
+export class AssetsPruneCommand extends Command {
+  static override commandName = "assets:prune";
+  static override description = "Remove asset files left behind by an earlier release";
+  static override needsApp = true;
+
+  static override flags = [
+    {
+      name: "dir",
+      type: "string" as const,
+      description: "Output directory to prune (defaults to the configured `app.assets.outDir`)",
+    },
+    {
+      name: "dry-run",
+      type: "boolean" as const,
+      description: "List what would be removed, and remove none of it",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const cwd = process.cwd();
+    const dir = (this.flags["dir"] as string | undefined) ?? this._configuredOutDir();
+    if (!dir) {
+      this.warn(
+        "No output directory to prune. Pass --dir, or configure app.assets.outDir in config/app.ts.",
+      );
+      return;
+    }
+
+    const root = resolve(cwd, dir);
+    const recorded = new Set(await _recordedBuildOutput(root, cwd));
+    if (recorded.size === 0) {
+      // Without a record, "what belongs to this release" has no answer, and the
+      // by-name sweep alone would be guessing about a directory it does not own.
+      this.warn(
+        `No build record for ${dir}. Run \`zt assets:build\` (and ship .zerotal/ with the ` +
+          `release) so a prune knows which files are the current one's.`,
+      );
+      return;
+    }
+
+    const stale: string[] = [];
+    for (const entry of await _listEntries(root)) {
+      if (recorded.has(entry)) continue;
+      if (!CHUNK_NAME.test(entry.split("/").at(-1) ?? "")) continue;
+      stale.push(entry);
+    }
+
+    if (stale.length === 0) {
+      this.info(`${dir}: nothing to prune — ${recorded.size} file(s) all accounted for.`);
+      return;
+    }
+
+    if (this.flags["dry-run"] === true) {
+      this.info(`${dir}: ${stale.length} file(s) would be removed:`);
+      for (const path of stale.sort()) this.line(`  ${path}`);
+      return;
+    }
+
+    let removed = 0;
+    for (const path of stale) {
+      try {
+        await unlink(join(root, path));
+        removed++;
+      } catch {
+        // Already gone, or held open. The next prune tries again, and a file we
+        // could not delete is not worth failing a release over.
+      }
+    }
+    this.info(`${dir}: removed ${removed} stale file(s), kept ${recorded.size}.`);
+  }
+
+  /** The configured asset output directory, or undefined when the app declares none. */
+  private _configuredOutDir(): string | undefined {
+    try {
+      const config = (this.app as Application).container.makeSync("config") as ConfigManager;
+      return (config.get("app.assets") as AssetBuildConfig | undefined)?.outDir;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+/** Every entry under `root`, relative and slash-normalised. Empty when unreadable. */
+async function _listEntries(root: string): Promise<string[]> {
+  try {
+    const entries = await readdir(root, { recursive: true });
+    return entries.map((entry) => relative(".", entry).split("\\").join("/"));
+  } catch {
+    return [];
+  }
+}

package/src/command/builtin/DeployCommand.ts

@@ -26,7 +26,11 @@ import { runDoctor } from "../../doctor/AppDoctor.ts";
 import { probeTransport } from "../../doctor/TransportProbe.ts";
 import { runConfigValidators } from "../../config/validation.ts";
 import { deployEnv } from "../../support/env.ts";
-import { DEFAULT_DEPLOY_STEPS, type DeployTarget } from "../../config/DeployConfig.ts";
+import {
+  CONVENTIONAL_PREFLIGHT_COMMAND,
+  DEFAULT_DEPLOY_STEPS,
+  type DeployTarget,
+} from "../../config/DeployConfig.ts";
 
 /**
  * The pipeline. Subclassed per target by {@link makeDeployCommand}, which is what
@@ -47,6 +51,12 @@ export abstract class DeployCommand extends Command {
       description: "Print the steps that would run, and run none of them",
       default: false,
     },
+    {
+      name: "check",
+      type: "boolean" as const,
+      description: "Run the preflight gate and stop — build nothing, migrate nothing",
+      default: false,
+    },
     {
       name: "skip-migrations",
       type: "boolean" as const,
@@ -73,6 +83,19 @@ export abstract class DeployCommand extends Command {
     const steps = this._steps(app, target);
     if (dryRun) return this._printPlan(app, target, steps);
 
+    // `--check` is the gate on its own, for the moment in a release script where the
+    // new code is on disk and the service has not restarted yet. Everything that can
+    // refuse has already run by the end of preflight and none of it mutates, so
+    // stopping here is a complete answer: exit 0 and restart, exit 1 and keep serving
+    // the previous release. A workspace that has lost its banking details or had its
+    // mail driver knocked back to `log` never goes live broken.
+    if (this.flags["check"] === true) {
+      await this._preflight(app, target);
+      this.newLine();
+      this.info(`${target} passed preflight. Nothing was built, migrated or restarted.`);
+      return;
+    }
+
     await this._preflight(app, target);
     await this._runSteps(app, steps);
     await this._verify(app);
@@ -129,6 +152,70 @@ export abstract class DeployCommand extends Command {
     this.line(`✓ config is valid for a ${target} deployment`);
 
     await this._doctor(app, "preflight");
+    await this._appPreflight(app, target);
+  }
+
+  /**
+   * Run the app's own preflight commands — the refusals the framework is not in a
+   * position to make.
+   *
+   * Last inside preflight, so the framework's cheap structural checks have already
+   * spoken; still before every step, so nothing has been built or migrated when one
+   * of these says no.
+   */
+  private async _appPreflight(app: Application, target: string): Promise<void> {
+    const commands = this._preflightCommands(app, target);
+    if (commands.length === 0) return;
+
+    const runner = app.container.makeSync("commands") as CommandRunner;
+    for (const name of commands) {
+      const { code, output } = await runner.callInProcess([name]);
+      if (output.trim()) this.line(output.trimEnd());
+      if (code !== 0) {
+        throw new Error(
+          `${name} refused this release. Nothing has been built or migrated — ` +
+            `fix what it reported and deploy again.`,
+        );
+      }
+      this.line(`✓ ${name} passed`);
+    }
+  }
+
+  /**
+   * The preflight commands for this target: what `config/deploy.ts` declares, or
+   * the conventional `release:check` when the app registers one.
+   *
+   * A declared name that is not registered is an error rather than a skip. That is
+   * the opposite of how `steps` treats an absent command, and deliberately so: a
+   * missing `inertia:build` means the app has no Inertia, while a missing gate
+   * means the gate is not running, which is exactly the state this feature exists
+   * to make impossible.
+   */
+  private _preflightCommands(app: Application, target: string): string[] {
+    let runner: CommandRunner | undefined;
+    try {
+      runner = app.container.makeSync("commands") as CommandRunner | undefined;
+    } catch {
+      runner = undefined;
+    }
+    // Same reasoning as `_steps`: with no registry to ask, nothing can be
+    // confirmed present. Returning nothing is the honest answer, and a declared
+    // preflight will be checked again by `_appPreflight` when it goes to run one.
+    if (!runner?.has) return [];
+
+    const declared = this._target(app, target)?.preflight;
+    if (declared === undefined) {
+      return runner.has(CONVENTIONAL_PREFLIGHT_COMMAND) ? [CONVENTIONAL_PREFLIGHT_COMMAND] : [];
+    }
+
+    const missing = declared.filter((name) => !runner.has(name));
+    if (missing.length > 0) {
+      throw new Error(
+        `config/deploy.ts declares preflight command(s) that are not registered: ` +
+          `${missing.join(", ")}. A gate that silently does not run is worse than no gate.`,
+      );
+    }
+    return [...declared];
   }
 
   // ── Phase 2 — build and migrate ─────────────────────────────────────────────
@@ -267,6 +354,9 @@ export abstract class DeployCommand extends Command {
       `APP_ENV       ${actual || "(unset)"}${actual === target ? "" : `  ✗ expected ${target}`}`,
     );
     this.line(`preflight     config validators, then ${"doctor"} checks`);
+    for (const name of this._preflightCommands(app, target)) {
+      this.line(`preflight     ${name}`);
+    }
     for (const name of steps) {
       const skipped = name === "migrate" && this.flags["skip-migrations"] === true;
       this.line(`step          ${name}${skipped ? "  (skipped: --skip-migrations)" : ""}`);

package/src/command/builtin/TestCommand.ts

@@ -1,4 +1,5 @@
 import { Command } from "../Command.ts";
+import { bunBinary } from "../../support/runtime.ts";
 
 /**
  * `bun zt test [pattern] [flags]` — runs the test suite in the test environment.
@@ -121,10 +122,16 @@ export class TestCommand extends Command {
     const timeout = (this.flags["timeout"] as number | undefined) || TestCommand.DEFAULT_TIMEOUT_MS;
     bunArguments.push(`--timeout=${timeout}`);
 
-    this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}`);
+    this.dim(`APP_ENV=test  ZT_DB_URL=${dbUrl}  bun ${Bun.version}`);
     this.dim(`bun ${bunArguments.join(" ")}\n`);
 
-    const subprocess = Bun.spawn(["bun", ...bunArguments], {
+    // `bunBinary()`, not `"bun"`. The child of a command whose entire job is to run
+    // this app's tests must be the runtime this app is served by, and `"bun"` is
+    // resolved against PATH — so `node_modules/.bin/bun zt test` used to satisfy every
+    // check in the parent process and then hand the suite to whatever the shell had.
+    // The parent already refuses to boot on a runtime mismatch; spawning its own
+    // binary is what extends that guarantee to the process the assertions run in.
+    const subprocess = Bun.spawn([bunBinary(), ...bunArguments], {
       stdout: "inherit",
       stderr: "inherit",
       env: {

package/src/command/builtin/index.ts

@@ -55,5 +55,6 @@ export { DeployCommand, makeDeployCommand } from "./DeployCommand.ts";
 export { MakeProviderCommand } from "./MakeProviderCommand.ts";
 export { CssBuildCommand } from "./CssBuildCommand.ts";
 export { AssetsBuildCommand } from "./AssetsBuildCommand.ts";
+export { AssetsPruneCommand } from "./AssetsPruneCommand.ts";
 export { LintPackagesCommand } from "./LintPackagesCommand.ts";
 export { MakePackageCommand } from "./MakePackageCommand.ts";

package/src/command/startZerotal.ts

@@ -7,12 +7,21 @@
 import { CommandRunner } from "./CommandRunner.ts";
 import { configLoader } from "../config/ConfigLoader.ts";
 import { setAppEnv } from "../helpers/index.ts";
+import {
+  runtimeBelowFloor,
+  runtimeBelowFloorMessage,
+  runtimeMismatch,
+  runtimeMismatchAllowed,
+  runtimeMismatchMessage,
+} from "../support/runtime.ts";
+import type { RuntimeMismatch } from "../support/runtime.ts";
+import { RuntimeMismatchError } from "../errors/RuntimeMismatchError.ts";
 import type { Application } from "../application/Application.ts";
 
 /** Options for {@link startZerotal}. */
 export interface StartZerotalOptions {
   /** Directory to load config from, resolved against the cwd. Default: `./config`. */
-  configDir?: string;
+  configDir?: string | undefined;
 }
 
 /**
@@ -35,6 +44,11 @@ export async function startZerotal(
   loadApp: () => Promise<{ default: Application }>,
   options: StartZerotalOptions = {},
 ): Promise<void> {
+  // Before anything else, because everything after this is an assertion about a
+  // runtime — and if there are two of them, which one made the assertion is the
+  // first thing worth knowing.
+  assertOneRuntime();
+
   // Load + validate config synchronously — safe before the app boots.
   const config = configLoader(options.configDir ?? "./config");
   config.validate();
@@ -53,3 +67,50 @@ export async function startZerotal(
   await runner.boot();
   await runner.run(process.argv.slice(2));
 }
+
+/**
+ * Refuse to run on a Bun the project does not agree with.
+ *
+ * Two disagreements, both about the same thing — which binary the assertions
+ * downstream of here are assertions *about*:
+ *
+ * - The runtime is below the `engines.bun` the project declares. Every generated
+ *   app writes that floor and nothing had ever enforced it.
+ * - The project installs a different Bun in `node_modules` than the one running.
+ *   Most projects do not install Bun as a package, so most never see this one.
+ *
+ * At the top of the entry point rather than in a check somebody remembers to run,
+ * because the value is in it being unmissable: the failure both prevent is a suite
+ * that passes about the wrong binary, and nothing downstream of here can notice that.
+ *
+ * @throws When either check fails, unless `ZT_ALLOW_RUNTIME_MISMATCH` is set, which
+ *   downgrades it to a warning on stderr.
+ * @internal
+ */
+function assertOneRuntime(): void {
+  const floor = runtimeBelowFloor();
+  if (floor) {
+    _refuse(runtimeBelowFloorMessage(floor), {
+      running: floor.running,
+      installed: floor.required,
+      manifest: floor.manifest,
+    });
+  }
+
+  const mismatch = runtimeMismatch();
+  if (mismatch) _refuse(runtimeMismatchMessage(mismatch), mismatch);
+}
+
+/**
+ * Stop, or warn and continue when the escape hatch is set.
+ *
+ * @param message - The full explanation, already formatted.
+ * @param mismatch - The two versions, carried on the error for a harness to read.
+ */
+function _refuse(message: string, mismatch: RuntimeMismatch): void {
+  if (runtimeMismatchAllowed()) {
+    console.warn(`\n⚠  ${message}\n`);
+    return;
+  }
+  throw new RuntimeMismatchError(message, mismatch);
+}

package/src/config/AppConfig.ts

@@ -63,17 +63,17 @@ export interface AppSecureHeadersConfig {
    * Enable HSTS (and the `Secure` flag on the XSRF-TOKEN cookie). Defaults to
    * `false` — turn it on for any deployment served over HTTPS.
    */
-  secure?: boolean;
+  secure?: boolean | undefined;
   /** `Strict-Transport-Security` max-age in seconds. Defaults to one year. */
-  hstsMaxAge?: number;
+  hstsMaxAge?: number | undefined;
   /** Include `includeSubDomains` in the HSTS header. Defaults to `true`. */
-  hstsIncludeSubDomains?: boolean;
+  hstsIncludeSubDomains?: boolean | undefined;
   /** Set the HSTS `preload` directive. Only with the domain registered. Defaults to `false`. */
-  hstsPreload?: boolean;
+  hstsPreload?: boolean | undefined;
   /** `Content-Security-Policy` value. Omitted by default. */
-  contentSecurityPolicy?: string;
+  contentSecurityPolicy?: string | undefined;
   /** `Referrer-Policy` value. Defaults to `strict-origin-when-cross-origin`. */
-  referrerPolicy?: string;
+  referrerPolicy?: string | undefined;
 }
 
 /**
@@ -106,7 +106,7 @@ export interface AppAssetsConfig {
    * // config/app.ts
    * assets: { entrypoint: 'resources/css/app.css', loader: { '.woff2': 'file', '.woff': 'file' } }
    */
-  loader?: Record<string, AssetLoaderKind>;
+  loader?: Record<string, AssetLoaderKind> | undefined;
 }
 
 /**
@@ -176,7 +176,7 @@ export interface AppConfigShape {
   /** Enable HTTP/3 over QUIC. Requires a valid tls config. Default: false */
   http3: boolean;
   /** TLS certificate + key for HTTPS. Enables HTTPS when set. */
-  tls?: AppTlsConfig;
+  tls?: AppTlsConfig | undefined;
   /**
    * Largest request body the server will accept, in bytes. Default: 8 MiB.
    *
@@ -237,7 +237,7 @@ export interface AppConfigShape {
 
   // ── Assets ────────────────────────────────────────────────────────────────
   /** Front-end asset bundling, built on `serve`. Omitted means no asset build. */
-  assets?: AppAssetsConfig;
+  assets?: AppAssetsConfig | undefined;
 
   // ── Dev mode ──────────────────────────────────────────────────────────────
   /**
@@ -256,7 +256,7 @@ export interface AppConfigShape {
    * }
    * ```
    */
-  dev?: DevConfigShape;
+  dev?: DevConfigShape | undefined;
 
   // ── Conventions ───────────────────────────────────────────────────────────
   /** Auto-discovery settings (enabled + per-concern paths). */

package/src/config/ConfigLoader.ts

@@ -9,7 +9,11 @@ import { frameworkLog } from "../logger/frameworkLog.ts";
 
 const requireModule = createRequire(import.meta.url);
 
-/** Namespace → config object map (filename without extension is the namespace). */
+/**
+ * Namespace → config object map (filename without extension is the namespace).
+ *
+ * @internal
+ */
 export type ConfigMap = Record<string, Record<string, unknown>>;
 type Validator = (value: Record<string, unknown>) => void;
 

package/src/config/DeployConfig.ts

@@ -35,6 +35,19 @@
  */
 export const DEFAULT_DEPLOY_STEPS: readonly string[] = ["assets:build", "inertia:build", "migrate"];
 
+/**
+ * The command a deploy runs before anything else, when the app defines one.
+ *
+ * A convention rather than a required declaration, because the alternative is the
+ * failure this exists to prevent: an app writes a preflight command, forgets to
+ * wire it into the pipeline, and every refusal that command knows how to make sits
+ * behind something nobody is obliged to run. **A gate nothing calls is a comment.**
+ *
+ * Register a command by this name and the pipeline finds it. Declare `preflight`
+ * on a target to run something else, or to run more than one.
+ */
+export const CONVENTIONAL_PREFLIGHT_COMMAND = "release:check";
+
 /** One environment this app is released to. */
 export interface DeployTarget {
   /**
@@ -47,6 +60,26 @@ export interface DeployTarget {
    * {@link DEFAULT_DEPLOY_STEPS}. Names a `zt` command per entry.
    */
   steps?: readonly string[];
+  /**
+   * App-owned commands that run in the preflight phase — after the framework's
+   * own config validators and `doctor`, and before any step that mutates
+   * anything. A non-zero exit refuses the release.
+   *
+   * This is the slot for the checks only the app can make. The framework can tell
+   * you the `APP_KEY` is the one from `.env.example`; it cannot tell you this
+   * workspace has no cancellation policy, or that the owner account is still on
+   * the password the installer issued it. Those refusals are yours, and until
+   * there was somewhere to put them they lived in a command nobody ran.
+   *
+   * Defaults to {@link CONVENTIONAL_PREFLIGHT_COMMAND} when that command is
+   * registered, and to nothing when it is not.
+   *
+   * @example
+   * ```ts
+   * production: { preflight: ["release:check", "assets:verify"] }
+   * ```
+   */
+  preflight?: readonly string[];
 }
 
 /** The `deploy` config namespace. */

package/src/config/index.ts

@@ -36,7 +36,12 @@ export type {
   AppAssetsConfig,
   AssetLoaderKind,
 } from "./AppConfig.ts";
-export { DeployConfig, DEFAULT_DEPLOY_STEPS, DEFAULT_DEPLOY_TARGETS } from "./DeployConfig.ts";
+export {
+  DeployConfig,
+  DEFAULT_DEPLOY_STEPS,
+  DEFAULT_DEPLOY_TARGETS,
+  CONVENTIONAL_PREFLIGHT_COMMAND,
+} from "./DeployConfig.ts";
 export type { DeployConfigShape, DeployTarget } from "./DeployConfig.ts";
 export type { ConfigRegistry, ConfigPath, ConfigValue } from "./registry.ts";
 export { ConfigValidationError } from "./validation.ts";

package/src/config/registry.ts

@@ -53,7 +53,11 @@ type ValueAt<T, P extends string> = P extends `${infer Head}.${infer Rest}`
     ? T[P]
     : unknown;
 
-/** Every valid dot-path string across the registered config namespaces. */
+/**
+ * Every valid dot-path string across the registered config namespaces.
+ *
+ * @internal
+ */
 export type ConfigPath = Leaves<ConfigRegistry>;
 
 /** The value type stored at a given config dot-path. */