@zerotal/core 1.8.1 → 1.9.0

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 };
@@ -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/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/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
@@ -129,6 +133,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 +335,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/startZerotal.ts

@@ -7,6 +7,12 @@
 import { CommandRunner } from "./CommandRunner.ts";
 import { configLoader } from "../config/ConfigLoader.ts";
 import { setAppEnv } from "../helpers/index.ts";
+import {
+  runtimeMismatch,
+  runtimeMismatchAllowed,
+  runtimeMismatchMessage,
+} from "../support/runtime.ts";
+import { RuntimeMismatchError } from "../errors/RuntimeMismatchError.ts";
 import type { Application } from "../application/Application.ts";
 
 /** Options for {@link startZerotal}. */
@@ -35,6 +41,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 +64,26 @@ export async function startZerotal(
   await runner.boot();
   await runner.run(process.argv.slice(2));
 }
+
+/**
+ * Refuse to run when the project has two Bun runtimes in it.
+ *
+ * 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 it prevents is a suite
+ * that passes about the wrong binary, and nothing downstream of here can notice
+ * that. A project with no `node_modules/bun` — most of them — never sees this.
+ *
+ * @throws When the running Bun and the installed one disagree, unless
+ *   `ZT_ALLOW_RUNTIME_MISMATCH` is set, which downgrades it to a warning on stderr.
+ * @internal
+ */
+function assertOneRuntime(): void {
+  const mismatch = runtimeMismatch();
+  if (!mismatch) return;
+  const message = runtimeMismatchMessage(mismatch);
+  if (runtimeMismatchAllowed()) {
+    console.warn(`\n⚠  ${message}\n`);
+    return;
+  }
+  throw new RuntimeMismatchError(message, mismatch);
+}

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. */

package/src/config/validation.ts

@@ -29,7 +29,11 @@ export interface ConfigIssue {
   message: string;
 }
 
-/** Context handed to a config validator. */
+/**
+ * Context handed to a config validator.
+ *
+ * @internal
+ */
 export interface ConfigValidationContext {
   /** The namespace being validated (e.g. `"session"`). */
   namespace: string;
@@ -52,7 +56,11 @@ export type ConfigValidator = (
   ctx: ConfigValidationContext,
 ) => ConfigIssue[] | void;
 
-/** A validator paired with the namespace it guards, as held on the application. */
+/**
+ * A validator paired with the namespace it guards, as held on the application.
+ *
+ * @internal
+ */
 export interface RegisteredConfigValidator {
   namespace: string;
   validate: ConfigValidator;

package/src/conventions/ConventionLoader.ts

@@ -12,7 +12,11 @@ import type { Application } from "../application/Application.ts";
 import type { AppEnvironment } from "../provider/ServiceProvider.ts";
 import { frameworkLog } from "../logger/frameworkLog.ts";
 
-/** The context a concern receives while registering discovered modules. */
+/**
+ * The context a concern receives while registering discovered modules.
+ *
+ * @internal
+ */
 export interface ConcernContext {
   app: Application;
   env: AppEnvironment;

package/src/dev/CssPlugins.ts

@@ -40,6 +40,8 @@ function _scanRoots(cwd: string): string[] {
  *
  * Returns an empty array when `bun-plugin-tailwind` is not installed.
  * The caller falls back to a `bunx @tailwindcss/cli` subprocess.
+ *
+ * @internal
  */
 export async function detectCssPlugins(cwd: string): Promise<BunPlugin[]> {
   try {
@@ -60,6 +62,8 @@ export async function detectCssPlugins(cwd: string): Promise<BunPlugin[]> {
  * @param input   Absolute path to the CSS source (e.g. `${cwd}/resources/css/app.css`)
  * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/css`)
  * @param minify  Whether to minify the output (true in production)
+ *
+ * @internal
  */
 export async function buildCssBundle(
   input: string,
@@ -155,6 +159,8 @@ export async function buildCssBundle(
  * @param input   Absolute path to the JS/TS entry (e.g. `${cwd}/resources/js/app.js`)
  * @param outdir  Absolute path to the output directory (e.g. `${cwd}/public/js`)
  * @param minify  Whether to minify the output (true in production)
+ *
+ * @internal
  */
 export async function buildJsBundle(
   input: string,
@@ -193,7 +199,11 @@ function _basename(filePath: string): string {
   return filePath.split("/").at(-1) ?? filePath;
 }
 
-/** The resolved `app.assets` config block (see {@link AppAssetsConfig}). */
+/**
+ * The resolved `app.assets` config block (see {@link AppAssetsConfig}).
+ *
+ * @internal
+ */
 export interface AssetBuildConfig {
   entrypoint: string | string[];
   outDir: string;

package/src/dev/DevBuildHook.ts

@@ -12,7 +12,11 @@
  * server cheerfully reported "rebuilding… ✓ ready" on every change.
  */
 
-/** Outcome of a frontend build: whether it succeeded and any collected logs. */
+/**
+ * Outcome of a frontend build: whether it succeeded and any collected logs.
+ *
+ * @internal
+ */
 export interface BuildResult {
   success: boolean;
   logs?: unknown[];
@@ -25,7 +29,11 @@ export interface BuildResult {
   skipped?: boolean;
 }
 
-/** A frontend build routine that resolves once the build finishes. */
+/**
+ * A frontend build routine that resolves once the build finishes.
+ *
+ * @internal
+ */
 export type BuildHookFn = () => Promise<BuildResult>;
 
 const _hooks = new Map<string, BuildHookFn>();

package/src/dev/DevDeck.ts

@@ -51,6 +51,7 @@ export interface Deck {
   stop(): void;
 }
 
+/** @internal */
 export interface DeckOptions {
   writer: OutputWriter;
   /** Restart the named process — bound to `r`. */
@@ -90,6 +91,8 @@ export interface DeckStdin {
  * read keys from. A process with a TTY on stdout but not stdin (some CI
  * runners, `zt dev < /dev/null`) would render a tab bar nobody could ever
  * switch, so it gets stream instead.
+ *
+ * @internal
  */
 export function createDeck(options: DeckOptions): Deck {
   const stdout = options.stdout ?? process.stdout;
@@ -108,6 +111,8 @@ export function createDeck(options: DeckOptions): Deck {
  * Colour is applied only when stdout is a terminal. Piped to a file this emits
  * nothing but text, which is the point — a log with escape codes in it is a log
  * you have to clean before you can read it.
+ *
+ * @internal
  */
 export class StreamDeck implements Deck {
   private _width = 0;
@@ -181,6 +186,7 @@ interface Card {
   scroll: number;
 }
 
+/** @internal */
 export class TabsDeck implements Deck {
   private readonly _cards: Card[] = [];
   private readonly _index = new Map<string, Card>();

package/src/dev/DevOrchestrator.ts

@@ -14,6 +14,8 @@ import { ZEROTAL_VERSION, installedCoreVersion } from "../support/version.ts";
  * All optional, and all defaulting to the console. Without them the orchestrator
  * behaves exactly as it did before the deck existed — which is what keeps the
  * plain `bun --watch` path and the existing tests honest.
+ *
+ * @internal
  */
 export interface DevOrchestratorHooks {
   /**

package/src/dev/DevProcess.ts

@@ -69,13 +69,21 @@ export interface DevProcessDefinition {
   color?: DevProcessColor;
 }
 
-/** The colours a deck tab can take. Named, not ANSI codes, so the deck owns the rendering. */
+/**
+ * The colours a deck tab can take. Named, not ANSI codes, so the deck owns the rendering.
+ *
+ * @internal
+ */
 export type DevProcessColor = "cyan" | "magenta" | "yellow" | "green" | "blue" | "red";
 
 /** Assigned in order to processes that did not pick a colour. */
 const _PALETTE: DevProcessColor[] = ["cyan", "magenta", "yellow", "green", "blue", "red"];
 
-/** A definition with every default filled in and its argv settled. */
+/**
+ * A definition with every default filled in and its argv settled.
+ *
+ * @internal
+ */
 export interface ResolvedDevProcess {
   name: string;
   label: string;
@@ -95,7 +103,11 @@ export interface ResolvedDevProcess {
   registrant: string;
 }
 
-/** The `app.dev` config block. */
+/**
+ * The `app.dev` config block.
+ *
+ * @internal
+ */
 export interface DevConfigShape {
   /** App-level processes, registered after every provider's. */
   processes?: DevProcessDefinition[];
@@ -123,6 +135,8 @@ interface ConfigReader {
  * @param app     A booted application — providers must have run, since `enabled`
  *                and a `command` thunk are allowed to read config.
  * @param config  The config manager, read for `app.dev`.
+ *
+ * @internal
  */
 export async function collectDevProcesses(
   app: ProviderHost,

package/src/dev/DevReloadMiddleware.ts

@@ -19,7 +19,11 @@ import type { HttpContext } from "../pipeline/HttpContext.ts";
 import { BaseMiddleware } from "../middleware/BaseMiddleware.ts";
 import { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 
-/** Produces an HTML fragment to inject before `</body>` for the given request. */
+/**
+ * Produces an HTML fragment to inject before `</body>` for the given request.
+ *
+ * @internal
+ */
 export type DevHtmlSnippet = (ctx: HttpContext) => string;
 
 interface RegisteredSnippet {
@@ -39,6 +43,8 @@ const _snippets: RegisteredSnippet[] = [];
  * registerDevHtmlSnippet("devtools", (ctx) =>
  *   ctx.url.pathname.startsWith("/__zerotal") ? "" : `<script src="/__zerotal/devtools/client.js"></script>`,
  * );
+ *
+ * @internal
  */
 export function registerDevHtmlSnippet(name: string, fn: DevHtmlSnippet): void {
   if (_snippets.some((s) => s.name === name)) return;

package/src/dev/DevSupervisor.ts

@@ -16,7 +16,11 @@
  */
 import type { ResolvedDevProcess } from "./DevProcess.ts";
 
-/** What the supervisor needs back from whatever it spawned. */
+/**
+ * What the supervisor needs back from whatever it spawned.
+ *
+ * @internal
+ */
 export interface DevChild {
   readonly stdout: ReadableStream<Uint8Array> | null;
   readonly stderr: ReadableStream<Uint8Array> | null;
@@ -24,16 +28,28 @@ export interface DevChild {
   kill(signal?: number | NodeJS.Signals): void;
 }
 
-/** How the supervisor starts a child. Injected so tests need no real processes. */
+/**
+ * How the supervisor starts a child. Injected so tests need no real processes.
+ *
+ * @internal
+ */
 export type DevSpawnFn = (
   argv: string[],
   options: { cwd: string; env: Record<string, string | undefined> },
 ) => DevChild;
 
-/** Where a process is in its life. */
+/**
+ * Where a process is in its life.
+ *
+ * @internal
+ */
 export type DevProcessState = "starting" | "running" | "restarting" | "exited" | "parked";
 
-/** A process as the deck sees it. */
+/**
+ * A process as the deck sees it.
+ *
+ * @internal
+ */
 export interface DevProcessStatus {
   name: string;
   label: string;
@@ -53,6 +69,7 @@ export interface DevSupervisorHooks {
   onState?: (status: DevProcessStatus) => void;
 }
 
+/** @internal */
 export interface DevSupervisorOptions extends DevSupervisorHooks {
   cwd: string;
   env?: Record<string, string | undefined>;
@@ -92,6 +109,7 @@ interface Entry {
   healthyTimer?: ReturnType<typeof setTimeout> | undefined;
 }
 
+/** @internal */
 export class DevSupervisor {
   private readonly _entries = new Map<string, Entry>();
   private readonly _cwd: string;

package/src/dev/bootBuild.ts

@@ -23,7 +23,11 @@
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import { isProdLike } from "../support/env.ts";
 
-/** What to do about a boot-time asset build, and why. */
+/**
+ * What to do about a boot-time asset build, and why.
+ *
+ * @internal
+ */
 export interface BootBuildDecision {
   /** Whether to run the build. */
   build: boolean;
@@ -37,6 +41,8 @@ export interface BootBuildDecision {
  * Tested by writing rather than by reading a permission bit: the thing that makes
  * `public/` unwritable in the failure this guards against is `ProtectSystem=strict`, a
  * mount-level restriction that a mode check does not see.
+ *
+ * @internal
  */
 export async function isWritableDir(dir: string): Promise<boolean> {
   const probe = `${dir}/.zerotal-write-probe-${process.pid}`;
@@ -68,6 +74,8 @@ export async function isWritableDir(dir: string): Promise<boolean> {
  * if (!decision.build) console.info(decision.reason);
  * else await build();
  * ```
+ *
+ * @internal
  */
 export async function bootBuildDecision(
   outDirs: string[],

package/src/dev/reloadClient.ts

@@ -19,6 +19,8 @@
  * Exported as a string because it is injected inline: `DevReloadMiddleware`
  * rewrites HTML responses with it for every view layer, and Inertia bakes it
  * into its cached template so streamed pages need no body rewrite.
+ *
+ * @internal
  */
 export const DEV_RELOAD_CLIENT: string =
   `<script>(function(){` +

package/src/dev/startDevMode.ts

@@ -39,7 +39,11 @@ export interface StartDevModeOptions {
   deckMode?: "tabs" | "stream" | undefined;
 }
 
-/** The server's card. Named so `--only=server` and `--without=server` read naturally. */
+/**
+ * The server's card. Named so `--only=server` and `--without=server` read naturally.
+ *
+ * @internal
+ */
 export const SERVER_PROCESS_NAME = "server";
 
 /**
@@ -47,6 +51,8 @@ export const SERVER_PROCESS_NAME = "server";
  *
  * Never returns: the orchestrator parks on an unresolved promise and the exit
  * happens in its signal handlers, after the deck has restored the terminal.
+ *
+ * @internal
  */
 export async function startDevMode(options: StartDevModeOptions): Promise<void> {
   const supervised = options.processes.filter((entry) => entry.name !== SERVER_PROCESS_NAME);