@zerotal/core 1.7.4 → 1.8.0

package/src/command/builtin/UpgradeCommand.ts

@@ -0,0 +1,148 @@
+import { Command } from "../Command.ts";
+import { CODEMODS } from "../../upgrade/codemods/index.ts";
+import { planUpgrade, applyPlan } from "../../upgrade/runner.ts";
+import { compareVersions } from "../../upgrade/types.ts";
+
+/**
+ * `bun zt upgrade` — carry an app across a version boundary.
+ *
+ * Every breaking change the framework wants to make waits in the 2.0 ledger, and
+ * the rule attached to that ledger is that anything which *can* have a codemod
+ * has one before 2.0 ships. This is the runner those codemods plug into; without
+ * it the ledger is a list of things nobody can afford to pay.
+ *
+ * ## Dry by default
+ *
+ * It prints the plan and writes nothing unless asked. That is the opposite of
+ * most tools and deliberate: this rewrites source across a whole project, and
+ * the first run should be something a person can read and disagree with. `--write`
+ * is one word, and by the time somebody types it they have seen the diff summary.
+ *
+ * ## The report is the product
+ *
+ * Anyone can rewrite `BaseModel` to `Model` with `sed`. What makes an upgrade
+ * tool worth running is the part that says "these eleven places I did not touch,
+ * and here is why" — a codemod that silently walks past what it does not
+ * understand is worse than none, because the changes it *did* make imply the job
+ * is finished.
+ *
+ * @category Maintenance
+ */
+export class UpgradeCommand extends Command {
+  static commandName = "upgrade";
+  static description = "Apply the codemods for a version upgrade";
+  static needsApp = false;
+
+  static flags = [
+    {
+      name: "from",
+      type: "string" as const,
+      description: "Version being upgraded from (defaults to the installed zerotal version)",
+      default: "",
+    },
+    {
+      name: "to",
+      type: "string" as const,
+      description: "Version being upgraded to",
+      default: "",
+    },
+    {
+      name: "write",
+      short: "w",
+      type: "boolean" as const,
+      description: "Apply the changes. Without this, the plan is printed and nothing is written",
+      default: false,
+    },
+    {
+      name: "path",
+      short: "p",
+      type: "string" as const,
+      description: "Directory to upgrade",
+      default: ".",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const root = (this.flags["path"] as string) || ".";
+    const write = this.flags["write"] as boolean;
+
+    const from = ((this.flags["from"] as string) || (await this.installedVersion(root))).trim();
+    const to = (this.flags["to"] as string).trim();
+
+    if (!/^\d+\.\d+\.\d+$/.test(from)) {
+      this.error(
+        `Cannot tell which version this app is on. Pass --from <version>, or run this in a ` +
+          `project whose package.json depends on zerotal.`,
+      );
+      return;
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(to)) {
+      this.error("Pass the version you are upgrading to: --to <version>");
+      return;
+    }
+    if (compareVersions(to, from) <= 0) {
+      this.error(`--to (${to}) must be newer than --from (${from}).`);
+      return;
+    }
+
+    const plan = await planUpgrade(root, CODEMODS, from, to);
+
+    this.info(`Upgrade ${from} → ${to}`);
+    this.dim(`  scanned ${plan.scanned} file(s) under ${root}`);
+
+    if (plan.codemods.length === 0) {
+      this.info("No codemods apply to this version range. Nothing to do.");
+      return;
+    }
+
+    this.line("");
+    this.line("Codemods:");
+    for (const codemod of plan.codemods) {
+      const ledger = codemod.ledger ? ` (ledger #${codemod.ledger})` : "";
+      this.dim(`  ${codemod.version}  ${codemod.name}${ledger} — ${codemod.description}`);
+    }
+
+    this.line("");
+    if (plan.changes.size === 0) {
+      this.info("No files need changing.");
+    } else {
+      this.line(`${plan.changes.size} file(s) to change:`);
+      for (const change of plan.changes.values()) this.dim(`  ${change.file} — ${change.summary}`);
+    }
+
+    // Last and loudest: the part a person has to act on.
+    if (plan.manual.length > 0) {
+      this.line("");
+      this.warn(`${plan.manual.length} place(s) need a decision this cannot make for you:`);
+      for (const item of plan.manual.slice(0, 20)) {
+        this.dim(`  ${item.file}:${item.line}  ${item.text}`);
+        this.dim(`    ${item.reason}`);
+      }
+      if (plan.manual.length > 20) this.dim(`  … and ${plan.manual.length - 20} more`);
+    }
+
+    this.line("");
+    if (!write) {
+      this.info("Dry run — nothing written. Re-run with --write to apply.");
+      return;
+    }
+
+    const written = await applyPlan(root, plan);
+    this.info(`Wrote ${written} file(s).`);
+    this.dim("  Run your tests, then run this again — a second run should report no changes.");
+  }
+
+  /** The `zerotal` version this project depends on, if it says. */
+  private async installedVersion(root: string): Promise<string> {
+    try {
+      const pkg = (await Bun.file(`${root}/package.json`).json()) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      const spec = pkg.dependencies?.["zerotal"] ?? pkg.devDependencies?.["zerotal"] ?? "";
+      return /(\d+\.\d+\.\d+)/.exec(spec)?.[1] ?? "";
+    } catch {
+      return "";
+    }
+  }
+}

package/src/command/builtin/index.ts

@@ -50,6 +50,7 @@ export { TestCommand } from "./TestCommand.ts";
 export { RouteListCommand } from "./RouteListCommand.ts";
 export { RouteTypesCommand } from "./RouteTypesCommand.ts";
 export { DoctorCommand } from "./DoctorCommand.ts";
+export { UpgradeCommand } from "./UpgradeCommand.ts";
 export { DeployCommand, makeDeployCommand } from "./DeployCommand.ts";
 export { MakeProviderCommand } from "./MakeProviderCommand.ts";
 export { CssBuildCommand } from "./CssBuildCommand.ts";

package/src/dev/BuildOutput.ts

@@ -16,6 +16,16 @@ const CHUNK_NAME = /^chunk-[a-z0-9]+\.js(\.map)?$/i;
 /** Where the per-directory record of "what the last build wrote" is kept. */
 const MANIFEST_DIR = ".zerotal/build";
 
+/** What `Bun.build()` reports for one emitted file. */
+interface BuildArtifact {
+  path: string;
+  /** `"entry-point"` on the files the build was asked for; absent on older shapes. */
+  kind?: string;
+}
+
+/** One directory's record: which build wrote which files. */
+type Manifest = Record<string, string[]>;
+
 /**
  * Delete what an earlier build wrote to `outdir` and this one did not.
  *
@@ -40,40 +50,44 @@ const MANIFEST_DIR = ".zerotal/build";
  */
 export async function pruneBuildOutput(
   outdir: string,
-  outputs: readonly { path: string }[],
+  outputs: readonly BuildArtifact[],
 ): Promise<string[]> {
   const root = resolve(outdir);
   const current = new Set(outputs.map((output) => _relative(root, output.path)));
 
-  const previous = await _readManifest(root);
-  const stale = new Set<string>();
+  // Whose output this is. Nothing stops two builds sharing a directory —
+  // `inertia:build` and `assets:build` both default near `public/`, and the
+  // default release pipeline runs them one after the other — and with a single
+  // list per directory each one read the *other's* files as its own previous
+  // build and deleted them. The release ended with whichever ran last, and no
+  // error anywhere: `assets:build` removed the Inertia entry point, then
+  // `inertia:build` removed the other bundle.
+  const key = _buildKey(root, outputs);
+  const manifest = await _readManifest(root);
+  const mine = new Set(manifest[key] ?? []);
+  const theirs = new Set(
+    Object.entries(manifest)
+      .filter(([owner]) => owner !== key)
+      .flatMap(([, files]) => files),
+  );
 
-  for (const path of previous) {
+  const stale = new Set<string>();
+  for (const path of mine) {
     if (!current.has(path)) stale.add(path);
   }
 
   // Chunks are swept by name as well as by manifest, so a directory that has
   // been accumulating them since before any manifest existed still gets cleaned
-  // on the next build.
+  // on the next build. Only the unclaimed ones: a chunk another build has
+  // recorded is that build's to remove.
   for (const path of await _listEntries(root)) {
-    if (current.has(path)) continue;
+    if (current.has(path) || theirs.has(path)) continue;
     if (CHUNK_NAME.test(path.split("/").at(-1) ?? "")) stale.add(path);
   }
 
-  const removed: string[] = [];
-  for (const path of stale) {
-    try {
-      await unlink(join(root, path));
-      removed.push(path);
-    } catch {
-      // Already gone, or held open by another process — either way the next
-      // build tries again, and a file we could not delete is not worth failing
-      // an otherwise good build over.
-    }
-  }
-
-  await _writeManifest(root, [...current].sort());
-  return removed.sort();
+  const removed = await _unlinkAll(root, stale);
+  await _writeManifest(root, { ...manifest, [key]: [...current].sort() });
+  return removed;
 }
 
 // ── Private ──────────────────────────────────────────────────────────────────
@@ -95,28 +109,75 @@ function _manifestPath(root: string): string {
   return join(process.cwd(), MANIFEST_DIR, `${slug}-${hash}.json`);
 }
 
-/** What the previous build recorded, or nothing on a first run. */
-async function _readManifest(root: string): Promise<string[]> {
+/**
+ * Which build these outputs belong to, named by its entry points.
+ *
+ * Stable across rebuilds of the same build — the entry keeps its name while the
+ * chunks around it are rehashed — and different between two builds sharing a
+ * directory, which is the whole point of having it.
+ */
+function _buildKey(root: string, outputs: readonly BuildArtifact[]): string {
+  const entries = outputs
+    .filter((output) => output.kind === "entry-point")
+    .map((output) => _relative(root, output.path))
+    .sort();
+  // No entry point reported: an older Bun, or a build of nothing. One shared key
+  // is what this did before, and is no worse than it was.
+  return entries.join("|") || "default";
+}
+
+/** What previous builds recorded, or nothing on a first run. */
+async function _readManifest(root: string): Promise<Manifest> {
   try {
     const contents = (await Bun.file(_manifestPath(root)).json()) as unknown;
-    if (!Array.isArray(contents)) return [];
-    return contents.filter((entry): entry is string => typeof entry === "string");
+
+    // Written before this file recorded ownership: one flat list, which belonged
+    // to whichever build ran last. Kept under a key no build claims, so those
+    // files stay eligible for the build that recognises them and are never
+    // treated as another build's property.
+    if (Array.isArray(contents)) {
+      return { default: contents.filter((entry): entry is string => typeof entry === "string") };
+    }
+    if (!contents || typeof contents !== "object") return {};
+
+    const manifest: Manifest = {};
+    for (const [key, files] of Object.entries(contents as Record<string, unknown>)) {
+      if (!Array.isArray(files)) continue;
+      manifest[key] = files.filter((entry): entry is string => typeof entry === "string");
+    }
+    return manifest;
   } catch {
-    return [];
+    return {};
   }
 }
 
-async function _writeManifest(root: string, files: string[]): Promise<void> {
+async function _writeManifest(root: string, manifest: Manifest): Promise<void> {
   const path = _manifestPath(root);
   try {
     await mkdir(join(process.cwd(), MANIFEST_DIR), { recursive: true });
-    await writeFile(path, JSON.stringify(files, null, 2));
+    await writeFile(path, JSON.stringify(manifest, null, 2));
   } catch {
     // A manifest that cannot be written costs precision on the next prune, not
     // correctness: chunks are still swept by name.
   }
 }
 
+/** Delete each path, reporting what actually went. */
+async function _unlinkAll(root: string, paths: Iterable<string>): Promise<string[]> {
+  const removed: string[] = [];
+  for (const path of paths) {
+    try {
+      await unlink(join(root, path));
+      removed.push(path);
+    } catch {
+      // Already gone, or held open by another process — either way the next
+      // build tries again, and a file we could not delete is not worth failing
+      // an otherwise good build over.
+    }
+  }
+  return removed.sort();
+}
+
 /**
  * Every entry under `root`, relative and slash-normalised. Empty if unreadable
  * (a first build has nothing to clean, and neither does a missing directory).
@@ -129,3 +190,64 @@ async function _listEntries(root: string): Promise<string[]> {
     return [];
   }
 }
+
+/**
+ * Remove everything in `outdir` that this build did not write.
+ *
+ * The difference from {@link pruneBuildOutput} is what it trusts. Pruning
+ * removes only what it recognises: a file the manifest recorded, or one named
+ * the way `Bun.build()` names a code-split chunk. That covers what this
+ * framework's own builds emit, with or without a manifest — the name rule alone
+ * holds a directory steady across releases on a machine that has never seen it
+ * before. What it cannot recognise is output some other naming produced: an app
+ * that sets its own `naming`, or writes a second bundle into the same directory
+ * by other means.
+ *
+ * This needs no recognition — whatever is not in `outputs` goes. It refuses the
+ * two directories where that is certainly wrong: the project root, and `public/`,
+ * which holds the app's images and favicon beside its bundles. Point it at a
+ * dedicated directory, or prune instead.
+ *
+ * Neither of these helps a directory nothing runs in. A release unpacked over the
+ * top of the previous one — `tar -xzf`, `rsync` without `--delete` — merges into
+ * it, and no build happens on that machine to clean anything: the old bundles
+ * stay, publicly fetchable at their content-hashed URLs. That one is fixed by
+ * replacing the directory on release, not here.
+ *
+ * @param outdir  Absolute path the build wrote to.
+ * @param outputs The build's artifacts (`Bun.build()`'s `outputs`).
+ * @returns Paths removed, relative to `outdir`.
+ * @throws When `outdir` is the project root or its `public/` directory.
+ *
+ * @internal
+ */
+export async function cleanBuildOutput(
+  outdir: string,
+  outputs: readonly BuildArtifact[],
+): Promise<string[]> {
+  const root = resolve(outdir);
+  const cwd = resolve(process.cwd());
+
+  if (root === cwd || root === join(cwd, "public")) {
+    throw new Error(
+      `Refusing to clean ${_relative(cwd, root) || "."} — it holds more than this build's output, ` +
+        `and everything not rebuilt would be deleted. Point the build at a directory of its own ` +
+        `(public/assets, say), or drop --clean and let the prune handle chunks.`,
+    );
+  }
+
+  const current = new Set(outputs.map((output) => _relative(root, output.path)));
+
+  // Directories are left behind: emptied they cost nothing, and removing them
+  // races a concurrent read.
+  const doomed = (await _listEntries(root)).filter((path) => !current.has(path));
+  const removed = await _unlinkAll(root, doomed);
+
+  // This directory now holds one build's output and nothing else, so the record
+  // says exactly that — including dropping any other build that used to claim
+  // files here, whose files this has just deleted. Sharing a directory with
+  // `--clean` is the one thing it does not support, and the record should not
+  // pretend otherwise.
+  await _writeManifest(root, { [_buildKey(root, outputs)]: [...current].sort() });
+  return removed;
+}

package/src/dev/CssPlugins.ts

@@ -4,7 +4,7 @@
  * back to the Tailwind CLI when the plugin is absent).
  */
 import type { BunPlugin } from "bun";
-import { pruneBuildOutput } from "./BuildOutput.ts";
+import { pruneBuildOutput, cleanBuildOutput } from "./BuildOutput.ts";
 import { BuildCache } from "./BuildCache.ts";
 
 /** Outcome of one bundling helper. `skipped` means the cache answered. */
@@ -201,6 +201,12 @@ export interface AssetBuildConfig {
   minify: boolean;
   /** Per-extension loader overrides (e.g. `{ ".woff2": "file" }`). See AppAssetsConfig. */
   loader?: Record<string, string>;
+  /**
+   * Delete everything in `outDir` this build did not write, rather than only what
+   * the last build on this machine recorded. See {@link cleanBuildOutput} — it
+   * refuses a directory that holds more than build output.
+   */
+  clean?: boolean;
 }
 
 /**
@@ -271,7 +277,8 @@ export async function buildConfiguredAssets(
     // previous build — which is why the cache check returns early above rather
     // than falling through to here.
     if (result.success) {
-      await pruneBuildOutput(outdir, result.outputs);
+      if (assets.clean) await cleanBuildOutput(outdir, result.outputs);
+      else await pruneBuildOutput(outdir, result.outputs);
       await cache.record(result.outputs, { scanRoots: _scanRoots(cwd) });
     }
     return { success: result.success, logs: result.logs as unknown[] };

package/src/dev/DevDeck.ts

@@ -217,21 +217,47 @@ export class TabsDeck implements Deck {
     process.on("unhandledRejection", this._onExit);
 
     this._write(ALT_SCREEN_ON + CURSOR_HIDE + ALT_SCROLL_ON);
-    this._stdin.setRawMode?.(true);
-    this._stdin.resume?.();
-    this._stdin.on?.("data", this._onData);
-    this._stdout.on?.("resize", this._onResize);
 
+    try {
+      this._stdin.setRawMode?.(true);
+      this._stdin.resume?.();
+      this._stdin.on?.("data", this._onData);
+    } catch (error) {
+      // Someone else still owns stdin — a prompt earlier in the same command that
+      // never let go, most likely. Tabs with no keys is a deck nobody can drive,
+      // but that is no reason to take the dev server down with it, which is
+      // exactly what throwing from here used to do.
+      this._degrade(statuses, error);
+      return;
+    }
+
+    this._stdout.on?.("resize", this._onResize);
     this._paint();
   }
 
+  /**
+   * Give up the tabs and stream instead, for a terminal that cannot be taken
+   * over. Losing the keyboard costs tab switching, restart and `q`; Ctrl-C still
+   * works, because that one is the shell's.
+   */
+  private _degrade(statuses: DevProcessStatus[], error: unknown): void {
+    this.stop();
+    this._restored = false; // stop() still has to run on quit.
+    this._streaming = true;
+    this._stream = new StreamDeck(this._options.writer, Boolean(this._stdout.isTTY));
+    this._stream.start(statuses);
+    this._stream.notice(
+      `keyboard controls unavailable (${error instanceof Error ? error.message : String(error)}) — streaming instead`,
+    );
+  }
+
   line(name: string, text: string, stream: "stdout" | "stderr"): void {
     const card = this._index.get(name);
     if (!card) return;
 
     const stamp = _clock();
     const body = stream === "stderr" ? _paint(text, "red") : text;
-    card.lines.push(`${stamp}${body}`);
+    card.lines.push(`${stamp}\0${body}`);
     if (card.lines.length > SCROLLBACK) card.lines.shift();
     this._anchor(card, body);
 
@@ -256,7 +282,7 @@ export class TabsDeck implements Deck {
     }
     const card = this._cards[this._focused];
     if (!card) return;
-    card.lines.push(`${_clock()}${_paint(text, "yellow")}`);
+    card.lines.push(`${_clock()}\0${_paint(text, "yellow")}`);
     this._schedulePaint();
   }
 
@@ -526,7 +552,7 @@ export class TabsDeck implements Deck {
     const needle = this._search.toLowerCase();
     const out: string[] = [];
     for (const entry of card.lines) {
-      const split = entry.indexOf("");
+      const split = entry.indexOf("\0");
       const stamp = entry.slice(0, split);
       const body = entry.slice(split + 1);
       if (needle && !body.toLowerCase().includes(needle)) continue;

package/src/dev/index.ts

@@ -33,7 +33,7 @@ export { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
 export { browserEnvDefines } from "./buildEnv.ts";
 export { detectCssPlugins, buildCssBundle, buildJsBundle } from "./CssPlugins.ts";
 export type { AssetBuildConfig } from "./CssPlugins.ts";
-export { pruneBuildOutput } from "./BuildOutput.ts";
+export { pruneBuildOutput, cleanBuildOutput } from "./BuildOutput.ts";
 // Lets `serve` and any view provider agree on whether to build at boot, so a hardened
 // production unit with a read-only output directory logs a line instead of restart-looping.
 export { bootBuildDecision, isWritableDir } from "./bootBuild.ts";

package/src/dev/startDevMode.ts

@@ -114,23 +114,40 @@ export async function startDevMode(options: StartDevModeOptions): Promise<void>
     },
   });
 
-  // Cards exist before anything can write to them, so early output has a tab to
-  // land in rather than being dropped for want of one.
-  deck.start([...(wantsServer ? [serverStatus] : []), ...supervised.map(_toStatus)]);
+  try {
+    // Cards exist before anything can write to them, so early output has a tab to
+    // land in rather than being dropped for want of one.
+    deck.start([...(wantsServer ? [serverStatus] : []), ...supervised.map(_toStatus)]);
 
-  // Started before the server rather than after it: these declared they do not
-  // depend on it, and making them wait for a build they have nothing to do with
-  // is dead time on every boot.
-  supervisor.start(supervised.filter((entry) => entry.after === "none"));
+    // Started before the server rather than after it: these declared they do not
+    // depend on it, and making them wait for a build they have nothing to do with
+    // is dead time on every boot.
+    supervisor.start(supervised.filter((entry) => entry.after === "none"));
 
-  if (!wantsServer) {
-    // `--only=queue`, say — supervised and drawn, with no server underneath.
-    // Still parks forever: quitting goes through the deck like everywhere else.
-    await new Promise<never>(() => {});
-    return;
-  }
+    if (!wantsServer) {
+      // `--only=queue`, say — supervised and drawn, with no server underneath.
+      // Still parks forever: quitting goes through the deck like everywhere else.
+      await new Promise<never>(() => {});
+      return;
+    }
 
-  await orchestrator.start();
+    await orchestrator.start();
+  } catch (error) {
+    // Give the terminal back *before* saying what went wrong.
+    //
+    // The deck draws in the alternate screen buffer, and leaving it restores the
+    // shell's screen — discarding everything written while it was up. So a dev
+    // run that failed printed its reason into a buffer that was then thrown
+    // away, and the developer was left with the startup banner and
+    // `error: script "zt" exited with code 1`. Nothing about the failure
+    // survived, on the one path where knowing the reason matters most.
+    //
+    // Reported here rather than left to the caller for the same reason: by the
+    // time an error reaches the command runner the deck may or may not have been
+    // stopped, and "may or may not" decides whether the message is visible.
+    deck.stop();
+    throw error;
+  }
 }
 
 /** The card a process starts life with, before the supervisor has run it. */

package/src/doctor/AppDoctor.ts

@@ -100,13 +100,31 @@ const syncVsMigrationsCheck: DoctorCheck = {
   run(app) {
     const synchronize = _config(app, "database.synchronize") === true;
     const migrations = _sourceFiles(process.cwd(), "database/migrations");
+
+    // Both present is only *fatal* in production, where `deploy:<env>` runs
+    // `migrate` and boot-time sync would have created the tables first.
+    //
+    // Outside production it is a documented arrangement rather than a mistake:
+    // sync builds the schema from the models so a fresh clone runs without a
+    // migration step, and `synchronize` is written as an expression that is false
+    // in production. This app is one of them. Failing that configuration is how a
+    // check stops being trusted — and this is the check the roadmap wants trusted
+    // enough to gate a deploy, which it cannot be while it cries wolf locally.
     if (synchronize && migrations.length > 0) {
-      return fail(
+      const detail =
         `database.synchronize is on and ${migrations.length} migration(s) exist. Boot-time ` +
-          `sync creates tables from the models first, so the first \`migrate\` fails with ` +
-          `"table already exists". The schema needs exactly one source of truth.`,
-        "Set synchronize: false in config/database.ts (migrations become the source of truth).",
-      );
+        `sync creates tables from the models, so \`migrate\` then fails with ` +
+        `"table already exists".`;
+      return _isProductionEnv(app)
+        ? fail(
+            `${detail} In production the deploy runs \`migrate\`, so this will break the release.`,
+            "Set synchronize: false in config/database.ts (migrations become the source of truth).",
+          )
+        : warn(
+            `${detail} Fine if sync is deliberately for local only and off in production — ` +
+              `just do not run \`migrate\` against this database.`,
+            "If you meant migrations to own the schema everywhere, set synchronize: false.",
+          );
     }
     if (synchronize) return ok("synchronize (no migrations present)");
     return ok(migrations.length > 0 ? "migrations" : "no schema management configured");

package/src/events/FrameworkEvents.ts

@@ -35,7 +35,8 @@ function _kindOf(ctor: EventCtor): string {
  *
  * @example
  * ```ts
- * import { FrameworkEvents, QueryExecuted } from "@zerotal/core";
+ * import { FrameworkEvents } from "@zerotal/core";
+ * import { QueryExecuted } from "@zerotal/orm";
  *
  * // In a provider's onBooting(): watch every SQL query.
  * const off = FrameworkEvents.on(QueryExecuted, (e) => {

package/src/helpers/response.ts

@@ -137,6 +137,14 @@ export class RedirectBuilder {
    * Redirect to the URL stored in session under `intended_url` (set by RequireAuth when
    * intercepting an unauthenticated request), then clear it. Falls back to `fallback` when
    * none is stored, or when the stored URL is cross-origin (open-redirect guard).
+   *
+   * **Single use.** Reading it spends it, so a second call in the same sign-in gets
+   * `fallback` — which is right (a stale destination should not hijack a later
+   * navigation) and surprising when the *first* redirect did not take effect. If a
+   * form is resubmitted because its redirect went unnoticed, the retry lands on
+   * `fallback`, and a customer who was part-way through something arrives somewhere
+   * they did not ask for with their selection gone. Nothing here can tell the two
+   * cases apart; read the value before authenticating if the flow needs it twice.
    */
   intended(fallback = "/", status: 301 | 302 | 303 | 307 | 308 = 302): ResponseBuilder {
     const session = (