@zerotal/core 1.4.0 → 1.5.1

package/src/command/builtin/ServeCommand.ts

@@ -1,11 +1,14 @@
-/**
+/**
  * The `serve` command, which starts the HTTP server. Also drives dev mode: the
  * file-watching orchestrator (process 1) and the managed dev worker (process 2).
  */
 import { Command } from "../Command.ts";
-import { DevOrchestrator } from "../../dev/DevOrchestrator.ts";
+import type { FlagDef } from "../Command.ts";
 import { hasDevBuildHooks, runDevBuildHooks } from "../../dev/DevBuildHook.ts";
 import { buildConfiguredAssets, type AssetBuildConfig } from "../../dev/CssPlugins.ts";
+import { bootBuildDecision } from "../../dev/bootBuild.ts";
+import { collectDevProcesses, type ResolvedDevProcess } from "../../dev/DevProcess.ts";
+import { startDevMode, SERVER_PROCESS_NAME } from "../../dev/startDevMode.ts";
 import type { ConfigManager } from "../../config/ConfigManager.ts";
 import type { Application } from "../../application/Application.ts";
 import * as DevWsServer from "../../dev/DevWsServer.ts";
@@ -34,36 +37,36 @@ export class ServeCommand extends Command {
   static description = "Start the HTTP server";
   static needsApp = true;
 
-  static flags = [
+  static flags: FlagDef[] = [
     {
       name: "port",
       short: "p",
-      type: "number" as const,
+      type: "number",
       description: "Port to listen on",
       default: 3000,
     },
     {
       name: "dev",
-      type: "boolean" as const,
+      type: "boolean",
       description: "Start in dev mode with file watching, auto-rebuild, and browser reload",
       default: false,
     },
     {
       name: "force",
-      type: "boolean" as const,
+      type: "boolean",
       description: "If the port is busy, stop the process holding it",
       default: false,
     },
     {
       name: "auto-port",
-      type: "boolean" as const,
+      type: "boolean",
       description: "If the port is busy, start on the next free port",
       default: false,
     },
     // Internal flag — spawned by DevOrchestrator; not shown in help
     {
       name: "dev-worker",
-      type: "boolean" as const,
+      type: "boolean",
       description: "Internal: run as the managed server process under DevOrchestrator",
       default: false,
     },
@@ -72,49 +75,23 @@ export class ServeCommand extends Command {
   async run(): Promise<void> {
     const isDev = this.flags["dev"] as boolean;
     const isWorker = this.flags["dev-worker"] as boolean;
-    const port = await this._resolvePort(this.flags["port"] as number, isWorker);
-    const assets = this._assetsConfig();
 
     // ── DEV ORCHESTRATOR (Process 1) ────────────────────────────────────────
     // Spawns and manages the server child process, watches files, drives builds.
+    //
+    // Handled before the port is resolved, because in dev mode the port is not
+    // always needed: `--list` starts nothing, and `--only=queue` starts no
+    // server. Resolving first turns either into a prompt about killing whatever
+    // holds port 3000 — or a hard failure with no TTY — over a port that was
+    // never going to be bound.
     if (isDev) {
-      this._announce("dev", port);
-
-      // Every view package (Inertia/Flow) that registered a build routine gets
-      // run on each change; otherwise synthesise one from `app.assets` so
-      // configured assets rebuild on change.
-      let buildHook: (() => Promise<{ success: boolean; logs?: unknown[] }>) | undefined =
-        hasDevBuildHooks() ? runDevBuildHooks : undefined;
-      if (!buildHook && assets) {
-        buildHook = (): Promise<{ success: boolean; logs?: unknown[] }> =>
-          buildConfiguredAssets(assets, process.cwd());
-      }
-
-      if (!buildHook) {
-        // No Inertia (or no frontend build configured). Fall back to simple
-        // bun --watch restart so the developer still gets auto-reload.
-        console.warn("  [zerotal:dev] no build hook registered — falling back to bun --watch");
-        const subprocess = Bun.spawn(
-          ["bun", "--watch", Bun.main, "serve", "--port", String(port)],
-          {
-            stdin: "inherit",
-            stdout: "inherit",
-            stderr: "inherit",
-            // The port is already settled here, and each --watch restart races
-            // the socket the previous run is still letting go of. Without this
-            // the child would re-prompt on every save.
-            env: { ...Bun.env, [PORT_RESOLVED_ENV_VAR]: "1" },
-          },
-        );
-        await subprocess.exited;
-        return;
-      }
-
-      const orchestrator = new DevOrchestrator(port, process.cwd(), buildHook);
-      await orchestrator.start();
+      await this._runDevMode();
       return;
     }
 
+    const port = await this._resolvePort(this.flags["port"] as number, isWorker);
+    const assets = this._assetsConfig();
+
     // ── DEV WORKER (Process 2) ──────────────────────────────────────────────
     // Normal server start, but:
     //   1. Registers GET /__dev/events for browser SSE reload.
@@ -122,6 +99,13 @@ export class ServeCommand extends Command {
     if (isWorker) {
       const app = this.app as import("../../application/Application.ts").Application;
 
+      // Refresh types/routes.generated.ts from the routes this boot registered.
+      // The worker is the right place for it: the orchestrator restarts the
+      // worker on every route-file change, so this runs exactly when the route
+      // table can have changed, and it reads a booted router rather than
+      // re-deriving names from filenames.
+      await this._writeRouteTypes();
+
       // Enable the /__dev/ws HMR WebSocket endpoint.
       app.enableDevWs();
 
@@ -147,6 +131,180 @@ export class ServeCommand extends Command {
     await new Promise<never>(() => {});
   }
 
+  // ── Dev mode ───────────────────────────────────────────────────────────────
+
+  /**
+   * Everything `--dev` does, shared verbatim with `bun zt dev`.
+   *
+   * `protected` rather than private because {@link DevCommand} is this command
+   * with a richer flag set — keeping one body is what stops the two from
+   * disagreeing about what dev mode is.
+   */
+  protected async _runDevMode(): Promise<void> {
+    const processes = await this._devProcesses();
+
+    if (this.flags["list"]) {
+      this._listDevProcesses(processes);
+      return;
+    }
+
+    // Item C: the cache is keyed on file mtime and size, which a same-size edit
+    // that preserves mtime slips past. This is the escape hatch for that, and
+    // for the "I don't believe the cache" moment every cache eventually causes.
+    if (this.flags["force-build"]) {
+      (Bun.env as Record<string, string>)["ZT_NO_BUILD_CACHE"] = "1";
+    }
+
+    const wantsServer = processes.some((entry) => entry.name === SERVER_PROCESS_NAME);
+    const assets = this._assetsConfig();
+
+    if (!wantsServer) {
+      // `--only=queue`, say. No port to bind and no assets to build — just the
+      // supervisor and the deck, so a busy port is nobody's problem.
+      await startDevMode({
+        port: 0,
+        cwd: process.cwd(),
+        processes,
+        writer: this._writer,
+        deckMode: this.flags["stream"] ? "stream" : undefined,
+      });
+      return;
+    }
+
+    const port = await this._resolvePort(this.flags["port"] as number, false);
+    this._announce("dev", port);
+
+    // Every view package (Inertia/Flow) that registered a build routine gets
+    // run on each change; otherwise synthesise one from `app.assets` so
+    // configured assets rebuild on change.
+    let buildHook: (() => Promise<{ success: boolean; logs?: unknown[] }>) | undefined =
+      hasDevBuildHooks() ? runDevBuildHooks : undefined;
+    if (!buildHook && assets) {
+      buildHook = (): Promise<{ success: boolean; logs?: unknown[] }> =>
+        buildConfiguredAssets(assets, process.cwd());
+    }
+
+    if (!buildHook) {
+      // No Inertia (or no frontend build configured). Fall back to simple
+      // bun --watch restart so the developer still gets auto-reload.
+      //
+      // Deliberately keeps the terminal to itself: `bun --watch` needs stdin,
+      // and a deck drawn over a process we are not supervising would show tabs
+      // that no key could restart.
+      this.warn("  [zerotal:dev] no build hook registered — falling back to bun --watch");
+      if (processes.some((entry) => entry.name !== SERVER_PROCESS_NAME)) {
+        this.dim("  [zerotal:dev] dev processes are not supervised on this path.");
+      }
+      const subprocess = Bun.spawn(["bun", "--watch", Bun.main, "serve", "--port", String(port)], {
+        stdin: "inherit",
+        stdout: "inherit",
+        stderr: "inherit",
+        // The port is already settled here, and each --watch restart races
+        // the socket the previous run is still letting go of. Without this
+        // the child would re-prompt on every save.
+        env: { ...Bun.env, [PORT_RESOLVED_ENV_VAR]: "1" },
+      });
+      await subprocess.exited;
+      return;
+    }
+
+    await startDevMode({
+      port,
+      cwd: process.cwd(),
+      build: buildHook,
+      processes,
+      writer: this._writer,
+      deckMode: this.flags["stream"] ? "stream" : undefined,
+    });
+  }
+
+  /**
+   * What dev mode should run, after `--only` / `--without`.
+   *
+   * The server is prepended as an ordinary entry so the two filters need no
+   * special case for it — `--only=queue` really does mean "just the queue", and
+   * says so by leaving the server out of the list rather than by ignoring you.
+   */
+  protected async _devProcesses(): Promise<ResolvedDevProcess[]> {
+    const app = this.app as Application;
+    const server: ResolvedDevProcess = {
+      name: SERVER_PROCESS_NAME,
+      label: SERVER_PROCESS_NAME,
+      color: "green",
+      restart: "on-failure",
+      after: "none",
+      registrant: "@zerotal/core",
+    };
+
+    let contributed: ResolvedDevProcess[] = [];
+    try {
+      contributed = await collectDevProcesses(app, this._config());
+    } catch (error) {
+      // A badly-formed definition names its registrant. Reporting and carrying
+      // on beats refusing to start the server over another package's typo.
+      this.error(`  ${error instanceof Error ? error.message : String(error)}`);
+    }
+
+    const only = _names(this.flags["only"]);
+    const without = _names(this.flags["without"]);
+
+    return [server, ...contributed].filter((entry) => {
+      if (only.length > 0 && !only.includes(entry.name)) return false;
+      return !without.includes(entry.name);
+    });
+  }
+
+  /** `--list`: what would run, and who asked for it. */
+  private _listDevProcesses(processes: ResolvedDevProcess[]): void {
+    this.section("Dev processes");
+    if (processes.length === 0) {
+      this.dim("  Nothing to run — every process was filtered out.");
+      return;
+    }
+    for (const entry of processes) {
+      const command = entry.run
+        ? "(in-process)"
+        : (entry.argv?.join(" ") ?? "(managed by the orchestrator)");
+      this.line(`  ${entry.name}`);
+      this.table(
+        [
+          ["command", command],
+          ["registered by", entry.registrant],
+          ["restart", entry.restart],
+          ["after", entry.after],
+        ],
+        4,
+      );
+    }
+  }
+
+  /**
+   * Refresh the generated route-name map from this boot's router.
+   *
+   * Best-effort by design: a read-only project directory (a container mount, a
+   * sandbox) must not take the dev server down over a types file, and the app
+   * still runs perfectly well without it — only the compile-time check is lost.
+   */
+  private async _writeRouteTypes(): Promise<void> {
+    try {
+      const { writeRouteTypes } = await import("../../router/routeTypes.ts");
+      const { Router } = await import("../../router/Router.ts");
+      const result = await writeRouteTypes(Router.namedRoutes);
+      if (result.changed) this.dim(`  [zerotal:dev] wrote ${result.path} (${result.count} routes)`);
+    } catch (error) {
+      this.dim(`  [zerotal:dev] could not write route types: ${error}`);
+    }
+  }
+
+  /** The config manager, or undefined when the app has none bound. */
+  private _config(): { get<T>(key: string, fallback?: T): T | undefined } | undefined {
+    try {
+      return (this.app as Application).container.makeSync("config") as ConfigManager;
+    } catch {
+      return undefined;
+    }
+  }
+
   // ── Private ────────────────────────────────────────────────────────────────
 
   /**
@@ -282,8 +440,29 @@ export class ServeCommand extends Command {
     }
   }
 
+  /** The resolved `app.env`, or undefined when the config store is unavailable. */
+  private _appEnv(): string | undefined {
+    try {
+      const config = (this.app as Application).container.makeSync("config") as ConfigManager;
+      return config.get("app.env") as string | undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
   /** Bundle the configured assets, reporting any build failure (non-fatal — the server still starts). */
   private async _buildAssets(assets: AssetBuildConfig): Promise<void> {
+    // A production deployment that built its assets ahead of time and locked the tree
+    // down is doing the right thing; rebuilding at boot would only fail. See bootBuild.ts.
+    const decision = await bootBuildDecision(
+      [`${process.cwd()}/${assets.outDir}`],
+      (this._appEnv() ?? Bun.env["APP_ENV"]) as string | undefined,
+    );
+    if (!decision.build) {
+      this.info(decision.reason ?? "Skipping the boot-time asset build.");
+      return;
+    }
+
     const entries = Array.isArray(assets.entrypoint)
       ? assets.entrypoint.join(", ")
       : assets.entrypoint;
@@ -314,6 +493,15 @@ export class ServeCommand extends Command {
   }
 }
 
+/** Split a `--only` / `--without` value into names. Absent means "no filter". */
+function _names(flag: unknown): string[] {
+  if (typeof flag !== "string") return [];
+  return flag
+    .split(",")
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
 /** `" by bun.exe (pid 1234)"`, or `""` when the holder could not be identified. */
 function _describe(owner: PortOwner | undefined): string {
   if (!owner) return "";

package/src/command/builtin/index.ts

@@ -25,6 +25,7 @@
  * @packageDocumentation
  */
 export { ServeCommand } from "./ServeCommand.ts";
+export { DevCommand } from "./DevCommand.ts";
 export { ReplCommand } from "./ReplCommand.ts";
 export { StartCommand } from "./StartCommand.ts";
 export { WorkerCommand } from "./WorkerCommand.ts";
@@ -47,7 +48,11 @@ export { MakeResourceCommand } from "./MakeResourceCommand.ts";
 export { MakeTestCommand } from "./MakeTestCommand.ts";
 export { TestCommand } from "./TestCommand.ts";
 export { RouteListCommand } from "./RouteListCommand.ts";
+export { RouteTypesCommand } from "./RouteTypesCommand.ts";
+export { DoctorCommand } from "./DoctorCommand.ts";
+export { DeployCommand, makeDeployCommand } from "./DeployCommand.ts";
 export { MakeProviderCommand } from "./MakeProviderCommand.ts";
 export { CssBuildCommand } from "./CssBuildCommand.ts";
+export { AssetsBuildCommand } from "./AssetsBuildCommand.ts";
 export { LintPackagesCommand } from "./LintPackagesCommand.ts";
 export { MakePackageCommand } from "./MakePackageCommand.ts";

package/src/command/scaffold/zerotal.ts.txt

@@ -4,16 +4,8 @@
 // DO NOT MODIFY THIS FILE.
 // This file is managed by the Zerotal framework.
 //
-// To add custom commands, create classes in app/commands/ and
-// register them in your AppServiceProvider.onBooted():
-//
-//   override async onBooted(): Promise<void> {
-//     if (this.app._env === 'console') {
-//       const runner = this.app.container.makeSync('commands');
-//       const { MyCommand } = await import('../commands/MyCommand.ts');
-//       runner.register(MyCommand);
-//     }
-//   }
+// To add custom commands, create classes in app/commands/ —
+// they are discovered automatically (`bun zerotal.ts make:command MyCommand`).
 //
 // Help:  bun zerotal.ts list
 //        bun zerotal.ts help <command>

package/src/config/AppConfig.ts

@@ -4,7 +4,9 @@
  * defaults, conventions), with sensible defaults applied over caller overrides.
  */
 import { deepMerge } from "../support/deepMerge.ts";
+import { isProdLike } from "../support/env.ts";
 import type { HealthConfigShape } from "../health/Health.ts";
+import type { DevConfigShape } from "../dev/DevProcess.ts";
 
 /** TLS certificate and key paths that enable HTTPS when provided. */
 export interface AppTlsConfig {
@@ -30,6 +32,7 @@ export interface ConventionsConfig {
     jobs: string;
     schedules: string;
     validators: string;
+    commands: string;
   };
 }
 
@@ -45,9 +48,32 @@ export interface AppThrottleConfig {
   windowSeconds: number;
 }
 
-/** App-level security-header defaults (consumed by `SecureHeadersMiddleware`). */
+/**
+ * App-level security-header defaults (consumed by `SecureHeadersMiddleware`).
+ *
+ * The middleware reads this whole block and layers it over its own defaults, so
+ * every one of its options has always worked here — but only `frameOptions` was
+ * declared, which made the rest a type error to write down. `secure` is the one
+ * that matters: HSTS is emitted only when it is true, so an app that could not
+ * name it in config had no supported way to turn HSTS on.
+ */
 export interface AppSecureHeadersConfig {
   frameOptions: "DENY" | "SAMEORIGIN";
+  /**
+   * 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;
+  /** `Strict-Transport-Security` max-age in seconds. Defaults to one year. */
+  hstsMaxAge?: number;
+  /** Include `includeSubDomains` in the HSTS header. Defaults to `true`. */
+  hstsIncludeSubDomains?: boolean;
+  /** Set the HSTS `preload` directive. Only with the domain registered. Defaults to `false`. */
+  hstsPreload?: boolean;
+  /** `Content-Security-Policy` value. Omitted by default. */
+  contentSecurityPolicy?: string;
+  /** `Referrer-Policy` value. Defaults to `strict-origin-when-cross-origin`. */
+  referrerPolicy?: string;
 }
 
 /**
@@ -121,6 +147,7 @@ const DEFAULT_CONVENTION_PATHS: ConventionsConfig["paths"] = {
   jobs: "app/jobs",
   schedules: "app/schedules",
   validators: "app/validators",
+  commands: "app/commands",
 };
 
 // ── Full shape (resolved — what the config store holds after AppConfig()) ────
@@ -180,6 +207,26 @@ export interface AppConfigShape {
    */
   health: boolean | HealthConfigShape;
 
+  // ── Transport origins ─────────────────────────────────────────────────────
+  /**
+   * Origins accepted for credentialed endpoints that bypass the middleware pipeline:
+   * WebSocket upgrades and raw routes, of which Flow's `/__flow/http` action fallback
+   * is one. Compared exactly — no wildcards, no suffix matching.
+   *
+   * The app's own origin is always accepted, but "own" means
+   * `new URL(request.url).origin` — behind a reverse proxy that is the loopback
+   * address it was bound to (`http://127.0.0.1:3000`), never the public URL the
+   * browser truthfully sends. So the origin of {@link AppConfigShape.url} is always
+   * merged into this list: without it a proxied app renders every page correctly and
+   * refuses every browser-initiated action with a 403, which is a far quieter failure
+   * than a 500 and passes any health check that reads a status code.
+   *
+   * Add entries only for a *different* host that legitimately drives this app — an SPA
+   * on `app.example.com` calling `api.example.com`. Unlike every other array in this
+   * config, what you pass is added to the URL's origin rather than replacing it.
+   */
+  allowedOrigins: string[];
+
   // ── Middleware defaults ───────────────────────────────────────────────────
   /** CORS defaults applied by `CorsMiddleware` when registered without explicit options. */
   cors: AppCorsConfig;
@@ -192,11 +239,60 @@ export interface AppConfigShape {
   /** Front-end asset bundling, built on `serve`. Omitted means no asset build. */
   assets?: AppAssetsConfig;
 
+  // ── Dev mode ──────────────────────────────────────────────────────────────
+  /**
+   * Extra processes for `bun zt dev`, and names to drop.
+   *
+   * App entries are registered after every provider's, so reusing a provider's
+   * name replaces it rather than adding a second tab — which is how an app swaps
+   * out, say, the queue worker for its own. `disable` removes by name whoever
+   * registered it.
+   *
+   * @example
+   * ```ts
+   * dev: {
+   *   processes: [{ name: "stripe", command: ["stripe", "listen", "--forward-to", "localhost:3000"] }],
+   *   disable: ["queue"],
+   * }
+   * ```
+   */
+  dev?: DevConfigShape;
+
   // ── Conventions ───────────────────────────────────────────────────────────
   /** Auto-discovery settings (enabled + per-concern paths). */
   conventions: ConventionsConfig;
 }
 
+/**
+ * Reduce a list of URLs or origins to the deduplicated origins an `Origin` header can be
+ * compared against.
+ *
+ * Full URLs are accepted because the two things that feed this list — `app.url` and an
+ * `ALLOWED_ORIGINS` env var someone pasted a browser address into — usually carry a path
+ * or a trailing slash, and `https://app.com/` never equals the `https://app.com` a browser
+ * sends. Entries that do not parse are kept verbatim rather than dropped: an unmatchable
+ * entry is inert, whereas silently discarding one hides the typo that caused it. `bun zt
+ * doctor` reports those.
+ */
+function _normaliseOrigins(entries: string[]): string[] {
+  const out: string[] = [];
+  for (const entry of entries) {
+    if (typeof entry !== "string") continue;
+    const trimmed = entry.trim();
+    if (trimmed === "") continue;
+    let origin: string;
+    try {
+      origin = new URL(trimmed).origin;
+      // `new URL("mailto:a@b").origin` is "null" — parsed, but not an origin.
+      if (origin === "null") origin = trimmed;
+    } catch {
+      origin = trimmed;
+    }
+    if (!out.includes(origin)) out.push(origin);
+  }
+  return out;
+}
+
 // ── AppConfig factory ─────────────────────────────────────────────────────────
 
 /**
@@ -232,6 +328,7 @@ export function AppConfig(options: {
   tls?: AppTlsConfig;
   maxRequestBodySize?: number;
   health?: boolean | HealthConfigShape;
+  allowedOrigins?: string[];
   cors?: Partial<AppCorsConfig>;
   throttle?: Partial<AppThrottleConfig>;
   secureHeaders?: Partial<AppSecureHeadersConfig>;
@@ -242,6 +339,7 @@ export function AppConfig(options: {
     minify?: boolean;
     loader?: Record<string, AssetLoaderKind>;
   };
+  dev?: DevConfigShape;
   conventions?: { enabled?: boolean; paths?: Partial<ConventionsConfig["paths"]> };
 }): AppConfigShape {
   // Resolve env-derived defaults, then deep-merge the caller's overrides so partial nested
@@ -258,6 +356,7 @@ export function AppConfig(options: {
     http3: false,
     maxRequestBodySize: DEFAULT_MAX_REQUEST_BODY_SIZE,
     health: false,
+    allowedOrigins: [],
     cors: DEFAULT_CORS,
     throttle: DEFAULT_THROTTLE,
     secureHeaders: DEFAULT_SECURE_HEADERS,
@@ -265,10 +364,18 @@ export function AppConfig(options: {
   };
   const resolved = deepMerge(defaults, options as Partial<AppConfigShape>);
 
+  // `allowedOrigins` always contains the origin of `url`, and is the one array here that
+  // unions rather than replaces. An app naming a second origin does not mean "and stop
+  // trusting my own public URL", and the cost of getting that wrong is asymmetric: the
+  // app keeps rendering and every action 403s, with nothing in the logs to say why.
+  resolved.allowedOrigins = _normaliseOrigins([resolved.url, ...resolved.allowedOrigins]);
+
   // Normalise the optional `assets` block: fill outDir/prefix/minify defaults
   // only when the app actually declares an asset entrypoint.
   if (options.assets) {
-    const isProduction = resolved.env === "production" || resolved.env === "prod";
+    // `isProdLike`, so `staging` minifies too. This runs at config-load time, where
+    // `resolved.env` is still the deployment name rather than the runtime mode.
+    const isProduction = isProdLike(resolved.env);
     resolved.assets = {
       entrypoint: options.assets.entrypoint,
       outDir: options.assets.outDir ?? "public",

package/src/config/DeployConfig.ts

@@ -0,0 +1,71 @@
+/**
+ * Deploy targets — the environments this app is released to, and the pipeline each
+ * one runs.
+ *
+ * Every target gets its own command: declare `production` and `staging` and you get
+ * `bun zt deploy:production` and `bun zt deploy:staging`. The name is the whole
+ * point of the split — it is checked against the deployment this process was
+ * actually started as, so running the production pipeline against a staging box
+ * stops on the first line rather than migrating the wrong database.
+ *
+ * The file is optional. Without it, `production` and `staging` exist with the
+ * default pipeline, which is what most apps want.
+ *
+ * @example
+ * ```ts
+ * // config/deploy.ts
+ * import { DeployConfig } from "zerotal/config";
+ *
+ * export default DeployConfig({
+ *   targets: {
+ *     production: { url: "https://example.com" },
+ *     staging: { url: "https://staging.example.com" },
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * The release steps, in order. Each names a `zt` command; one that is not
+ * registered is skipped, so an app without Inertia simply has no `inertia:build`.
+ *
+ * Ordered so that everything able to refuse runs before anything that mutates:
+ * the build cannot corrupt a database and the migration cannot half-apply if the
+ * preflight has already stopped the deploy.
+ */
+export const DEFAULT_DEPLOY_STEPS: readonly string[] = ["assets:build", "inertia:build", "migrate"];
+
+/** One environment this app is released to. */
+export interface DeployTarget {
+  /**
+   * The app's public URL in this environment. Used by `--probe` to run a real
+   * WebSocket handshake against the deployed site, the way a browser would.
+   */
+  url?: string;
+  /**
+   * Override the release steps for this target. Defaults to
+   * {@link DEFAULT_DEPLOY_STEPS}. Names a `zt` command per entry.
+   */
+  steps?: readonly string[];
+}
+
+/** The `deploy` config namespace. */
+export interface DeployConfigShape {
+  targets: Record<string, DeployTarget>;
+}
+
+/** The targets assumed when an app ships no `config/deploy.ts`. */
+export const DEFAULT_DEPLOY_TARGETS: Record<string, DeployTarget> = {
+  production: {},
+  staging: {},
+};
+
+/**
+ * Build the `deploy` config block, filling in defaults.
+ *
+ * @param options - The targets this app releases to.
+ */
+export function DeployConfig(options: Partial<DeployConfigShape> = {}): DeployConfigShape {
+  const targets = options.targets ?? DEFAULT_DEPLOY_TARGETS;
+  return { targets };
+}

package/src/config/index.ts

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

package/src/config/registry.ts

@@ -21,6 +21,7 @@ import type { HealthConfigShape } from "../health/Health.ts";
  */
 export interface ConfigRegistry {
   app: AppConfigShape;
+  deploy: import("./DeployConfig.ts").DeployConfigShape;
   health: HealthConfigShape;
   lock: import("../lock/config.ts").LockConfigShape;
   logging: import("../logger/config.ts").LoggingConfigShape;