@zerotal/core 1.7.5 → 1.8.0

package/CHANGELOG.md

@@ -8,6 +8,49 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.8.0] — 2026-08-24
+
+### Added
+
+- **`zt upgrade`** — the codemod runner. Dry by default: it rewrites source across a whole
+  project, so the first run is something you read and disagree with before `--write` applies
+  it. Nothing is written until the whole plan is known, so a run that fails halfway leaves no
+  half-upgraded tree. The first codemod covers the deprecated aliases — `BaseModel` → `Model`,
+  `routes:types` → `route:types`, `serve --dev` → `dev` — renaming the class only in a heritage
+  clause and fixing the import to match. What it _could not_ do is reported last and loudest,
+  with file, line and reason: a codemod that walks past what it does not understand implies the
+  job is finished when it is not.
+
+- **`--clean` on `assets:build` and `inertia:build`.** Pruning is conservative by default —
+  chunk-shaped filenames plus what the last build on this machine recorded in `.zerotal/` —
+  which cannot recognise output some other naming produced. `--clean` needs no record: the
+  output directory belongs to the build. It refuses `public/` and the project root, where
+  deleting what was not rebuilt takes the app's images and favicon with it.
+
+### Fixed
+
+- **Answering the busy-port prompt killed `serve --dev`.** The banner printed, then
+  `exited with code 1`, with nothing on screen saying why. Reading a prompt locks Bun's stdin
+  stream and the lock is held for the life of the command, so the dev deck's
+  `process.stdin.resume()` threw `ReadableStream is locked` — and it threw inside the alternate
+  screen buffer, so restoring the terminal erased the error on the way out. The prompt hands
+  stdin back where it took it; a deck that still cannot have it degrades to streaming instead
+  of dying, and a dev-mode failure stops the deck before it reports.
+
+- **Two builds sharing an output directory deleted each other's files.** Nothing forbids
+  `inertia:build` and `assets:build` writing to the same place and the defaults invite it, but
+  the prune record was one flat list per directory — so each build read the other's files as
+  its own previous output and removed them. The release ended up with whichever ran last, and
+  neither reported a problem: the build that lost still said "Build complete", and the page it
+  served then 404'd its own script. The record is keyed by entry point now, so a file another
+  build claimed is not this one's to remove. Unclaimed chunks are still swept.
+
+- **`zt doctor` failed a schema configuration that works.** Sync on plus migrations present
+  read as "the schema needs exactly one source of truth" — but sync building the schema from
+  the models for a fresh clone, with `synchronize` false in production where the deploy runs
+  `migrate`, is a documented arrangement in which the two never apply in the same environment.
+  It fails in production, where the deploy really does run both, and warns elsewhere.
+
 ## [1.7.3] — 2026-08-20
 
 ### Fixed

package/api-surface.md

@@ -2248,6 +2248,34 @@ class TestCommand = {
   write: (msg: string) => void
 }
 
+class UpgradeCommand = {
+  new (): UpgradeCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: ({    name: string;    type: 'string';    description: string;    default: string;    short?: never;} | {    name: string;    short: string;    type: 'boolean';    description: string;    default: boolean;} | {    name: string;    short: string;    type: 'string';    description: string;    default: string;})[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}
+
 class WorkerCommand = {
   new (): WorkerCommand
   static aliases: string[]
@@ -2487,6 +2515,7 @@ function registerDevHtmlSnippet = (name: string, fn: DevHtmlSnippet) => void
 function startDevMode = (options: StartDevModeOptions) => Promise<void>
 
 interface AssetBuildConfig = {
+  clean?: boolean
   entrypoint: string | string[]
   loader?: Record<string, string>
   minify: boolean

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/command/Command.ts

@@ -188,10 +188,11 @@ export abstract class Command {
     try {
       tty.setRawMode!(true);
       const characters: string[] = [];
-      const stdinIterator = this._stdinIter();
+      const reader = this._reader();
+      if (!reader) return "";
       const decoder = new TextDecoder();
       outer: while (true) {
-        const { value, done } = await stdinIterator.next();
+        const { value, done } = await reader.read();
         if (done) break;
         for (const character of decoder.decode(value)) {
           if (character === "\r" || character === "\n") break outer;
@@ -219,11 +220,18 @@ export abstract class Command {
       return line.replace(/\r$/, "");
     }
 
-    const stdinIterator = this._stdinIter();
+    const reader = this._reader();
+    if (!reader) {
+      // stdin belongs to something else now; answer from the buffer or not at all.
+      const rest = this._lineBuf;
+      this._lineBuf = "";
+      return rest.replace(/\r$/, "");
+    }
+
     const decoder = new TextDecoder();
 
     while (true) {
-      const { value, done } = await stdinIterator.next();
+      const { value, done } = await reader.read();
       if (done) break;
       this._lineBuf += decoder.decode(value);
       const newlineIndex = this._lineBuf.indexOf("\n");
@@ -239,16 +247,47 @@ export abstract class Command {
     return remaining.replace(/\r$/, "");
   }
 
-  // Shared stdin async iterator — one per Command instance so consecutive prompts
-  // don't each open a competing stream on the same stdin fd.
+  // One reader for the whole command: a second `Bun.stdin.stream()` over the same
+  // fd never yields, so consecutive prompts have to share the first one.
   private _lineBuf = "";
-  private _stdinIterator: AsyncIterator<Uint8Array> | undefined;
-  private _stdinIter(): AsyncIterator<Uint8Array> {
-    if (!this._stdinIterator) {
-      this._stdinIterator = (Bun.stdin.stream() as unknown as AsyncIterable<Uint8Array>)[
-        Symbol.asyncIterator
-      ]();
+  private _stdinReader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  private _stdinHandedOver = false;
+
+  private _reader(): ReadableStreamDefaultReader<Uint8Array> | undefined {
+    if (this._stdinHandedOver) return undefined;
+    this._stdinReader ??= (Bun.stdin.stream() as ReadableStream<Uint8Array>).getReader();
+    return this._stdinReader;
+  }
+
+  /**
+   * Give stdin back, for a command that prompts and then hands the terminal to
+   * something else.
+   *
+   * Reading locks the stdin stream, and the lock is held for the life of the
+   * command so a second prompt can still read. Anything that takes stdin over
+   * afterwards — `process.stdin.resume()`, a raw-mode key listener, the dev deck
+   * — then throws `ReadableStream is locked`. That is how answering the busy-port
+   * menu used to kill `zt dev` on the spot: the deck died taking the terminal
+   * over, and because it dies inside the alternate screen buffer, the restore
+   * erased the reason on its way out.
+   *
+   * Released rather than cancelled. Cancelling closes the underlying stdin, and
+   * the next owner would take over a terminal that never delivers a keystroke —
+   * a dev deck whose tab keys and `q` silently do nothing.
+   *
+   * One-way: a prompt after this returns whatever is still buffered, because a
+   * fresh reader on Bun's stdin hangs rather than fails, and a hang is the worse
+   * of the two.
+   */
+  protected releaseStdin(): void {
+    this._stdinHandedOver = true;
+    const reader = this._stdinReader;
+    this._stdinReader = undefined;
+    try {
+      reader?.releaseLock();
+    } catch {
+      // Only throws with a read still in flight — nobody is mid-keystroke here,
+      // and the caller is taking the terminal over either way.
     }
-    return this._stdinIterator;
   }
 }

package/src/command/CommandRunner.ts

@@ -359,6 +359,7 @@ export class CommandRunner {
       RouteListCommand,
       RouteTypesCommand,
       DoctorCommand,
+      UpgradeCommand,
       MakeProviderCommand,
       CssBuildCommand,
       AssetsBuildCommand,
@@ -390,6 +391,9 @@ export class CommandRunner {
     // Non-web commands (console, worker, test).
     if (this._app._env !== "web") {
       this.register(ReplCommand);
+      // Rewrites source across the project, so it belongs nowhere near a running
+      // web process — same reasoning as the release commands below.
+      this.register(UpgradeCommand);
       this.register(CompileCommand, ["build"]);
       this.registerAll([
         WorkerCommand,

package/src/command/builtin/AssetsBuildCommand.ts

@@ -34,11 +34,23 @@ export class AssetsBuildCommand extends Command {
       description: "Minify the output",
       default: true,
     },
+    {
+      name: "clean",
+      short: "c",
+      type: "boolean" as const,
+      description:
+        "Delete everything in the output directory this build did not write. " +
+        "Refused when that directory holds more than build output",
+      default: false,
+    },
   ];
 
   async run(): Promise<void> {
     const cwd = process.cwd();
     const minify = this.flags["minify"] as boolean;
+    // Off by default: the prune below is safe anywhere, and this is not — it is
+    // for a directory the build owns, which is a claim only the app can make.
+    const clean = this.flags["clean"] as boolean;
     let built = 0;
     let failed = 0;
 
@@ -48,7 +60,7 @@ export class AssetsBuildCommand extends Command {
         ? assets.entrypoint.join(", ")
         : assets.entrypoint;
       this.info(`Building assets: ${entries} → ${assets.outDir}/`);
-      const result = await buildConfiguredAssets({ ...assets, minify }, cwd);
+      const result = await buildConfiguredAssets({ ...assets, minify, clean }, cwd);
       if (result.success) built++;
       else {
         failed++;

package/src/command/builtin/ServeCommand.ts

@@ -372,7 +372,14 @@ export class ServeCommand extends Command {
       );
     }
 
-    return this._askAboutPort(requested, owner, held);
+    try {
+      return await this._askAboutPort(requested, owner, held);
+    } finally {
+      // Handed back here, where it was taken. What runs next on this path — the
+      // dev deck, or a `bun --watch` child with inherited stdio — takes the
+      // terminal over, and cannot while the menu still holds the read lock.
+      this.releaseStdin();
+    }
   }
 
   /**

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/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 = (

package/src/upgrade/codemods/deprecated-aliases.ts

@@ -0,0 +1,111 @@
+/**
+ * Ledger #4 — retire the deprecated aliases.
+ *
+ * Three pairs, each a live alias somebody depends on, which is exactly why they
+ * could not be dropped in a minor:
+ *
+ * - `BaseModel` → `Model`. The same class object under its original name.
+ * - `routes:types` → `route:types`. Registered as an alias in `CommandRunner`.
+ * - `serve --dev` → `dev`. The flag still works; `dev` is the command it became.
+ *
+ * ## What this deliberately does not do
+ *
+ * **It does not touch `BaseModel` in a type position.** `Model` and `BaseModel`
+ * are the same runtime class, so a value-position rename is cosmetic and safe.
+ * In a generic bound — `<T extends BaseModel>` — the name may be load-bearing
+ * for a reader even though it resolves identically, and in framework source it
+ * genuinely is. Those are reported for a person instead.
+ *
+ * That asymmetry is the whole reason this is a codemod rather than a
+ * find-and-replace: the mixin-composition script learned it the hard way in
+ * 1.3.0, where a blind rename broke import specifiers it had not considered.
+ */
+import type { Change, Codemod, CodemodResult, Manual, SourceFile } from "../types.ts";
+
+/**
+ * `BaseModel` in a class heritage clause — the one place renaming is safe.
+ *
+ * Anchored on `class Name extends`, not on `extends` alone. A generic bound
+ * writes `<T extends BaseModel>` with the same keyword, and matching that was a
+ * real bug the tests caught: it rewrote precisely the type positions this file
+ * says it will not touch.
+ */
+const BASE_MODEL_VALUE = /\bclass\s+(\w+)(\s*<[^>]*>)?\s+extends\s+BaseModel\b/g;
+
+/** `BaseModel` inside a generic bound or a type annotation. Reported, not rewritten. */
+const BASE_MODEL_TYPE = /<[^>]*\bextends\s+BaseModel\b[^>]*>|:\s*BaseModel\b/;
+
+/** The import specifier, which has to follow the rename or the file stops compiling. */
+const BASE_MODEL_IMPORT = /(\bimport\s*\{[^}]*?)\bBaseModel\b([^}]*?\}\s*from\s*["'][^"']*["'])/g;
+
+const COMMAND_ALIASES: { find: RegExp; replace: string; label: string }[] = [
+  { find: /\broutes:types\b/g, replace: "route:types", label: "`routes:types` → `route:types`" },
+  {
+    find: /\b(zt|zerotal)\s+serve\s+--dev\b/g,
+    replace: "$1 dev",
+    label: "`serve --dev` → `dev`",
+  },
+];
+
+export const deprecatedAliases: Codemod = {
+  version: "2.0.0",
+  name: "deprecated-aliases",
+  description: "Retire BaseModel, routes:types and serve --dev in favour of their real names",
+  ledger: 4,
+
+  run(files: SourceFile[]): CodemodResult {
+    const changes: Change[] = [];
+    const manual: Manual[] = [];
+
+    for (const { file, contents } of files) {
+      let next = contents;
+      const notes: string[] = [];
+
+      // Value positions first, then the import that has to agree with them.
+      const valueHits = next.match(BASE_MODEL_VALUE)?.length ?? 0;
+      if (valueHits > 0) {
+        next = next.replace(
+          BASE_MODEL_VALUE,
+          (_match, name: string, generics = "") => `class ${name}${generics} extends Model`,
+        );
+        notes.push(`${valueHits} × \`extends BaseModel\` → \`extends Model\``);
+      }
+
+      if (valueHits > 0 && BASE_MODEL_IMPORT.test(next)) {
+        BASE_MODEL_IMPORT.lastIndex = 0;
+        // `Model` may already be imported alongside it; collapsing to a single
+        // `Model` in that case would produce a duplicate specifier.
+        next = next.replace(BASE_MODEL_IMPORT, (whole, before: string, after: string) =>
+          /\bModel\b\s*[,}]/.test(before + after)
+            ? whole.replace(/\bBaseModel\b\s*,\s*/, "").replace(/,\s*\bBaseModel\b/, "")
+            : `${before}Model${after}`,
+        );
+        notes.push("import specifier updated");
+      }
+
+      for (const { find, replace, label } of COMMAND_ALIASES) {
+        const hits = next.match(find)?.length ?? 0;
+        if (hits === 0) continue;
+        next = next.replace(find, replace);
+        notes.push(`${hits} × ${label}`);
+      }
+
+      // Type positions are a handover, not a rewrite.
+      contents.split("\n").forEach((line, i) => {
+        if (!BASE_MODEL_TYPE.test(line)) return;
+        manual.push({
+          file,
+          line: i + 1,
+          text: line.trim(),
+          reason:
+            "`BaseModel` in a type position. It resolves to the same class as `Model`, so this " +
+            "compiles either way — renaming it is a readability call, not a correctness one.",
+        });
+      });
+
+      if (next !== contents) changes.push({ file, summary: notes.join(", "), contents: next });
+    }
+
+    return { changes, manual };
+  },
+};

package/src/upgrade/codemods/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Every codemod, in one list.
+ *
+ * The runner orders by version, so the order here is only what a reader sees.
+ * A codemod belongs here the moment its ledger entry is decided, even if the
+ * release that needs it is some way off — the roadmap's rule is that every
+ * ledger entry which *can* have a codemod has one before 2.0 ships, and the way
+ * that rule fails is by everyone assuming there is time.
+ */
+import type { Codemod } from "../types.ts";
+import { deprecatedAliases } from "./deprecated-aliases.ts";
+
+export const CODEMODS: Codemod[] = [deprecatedAliases];
+
+export { deprecatedAliases };

package/src/upgrade/runner.ts

@@ -0,0 +1,148 @@
+/**
+ * The upgrade runner: read the tree once, apply the codemods a version gap
+ * calls for, and report before writing anything.
+ *
+ * `scripts/codemod-mixin-composition.ts` proved the shape on a real 1.3.0 break
+ * — walk the tree, rewrite call sites, fix the imports a find-and-replace would
+ * have broken, offer `--dry`. This generalises that one-off into something a
+ * release can hand to users, which is what `zt upgrade` has to be if the 2.0
+ * ledger is ever going to be payable.
+ *
+ * Three properties it keeps:
+ *
+ * **Nothing is written until the whole plan is known.** Codemods return the new
+ * contents rather than writing, so a run that fails halfway leaves no
+ * half-upgraded tree, and `--dry` is the same code path as the real thing rather
+ * than a separate one that can drift from it.
+ *
+ * **Running twice is safe.** Every codemod is expected to be idempotent, and the
+ * second run is the test: it should report no changes. That matters because the
+ * first thing anyone does after an upgrade that printed warnings is run it again.
+ *
+ * **What it could not do is the headline.** See `Manual` in `./types.ts`.
+ */
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, extname, relative } from "node:path";
+import type { Change, Codemod, Manual, SourceFile } from "./types.ts";
+import { compareVersions } from "./types.ts";
+
+/** Never walked. Build output and dependencies are not the app's source. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".next",
+  ".zerotal",
+  ".release-tarballs",
+]);
+
+const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".md", ".mdx"];
+
+export interface UpgradePlan {
+  /** Codemods selected for this version gap, in the order they will run. */
+  codemods: Codemod[];
+  /** Every rewrite, keyed by file — later codemods see earlier ones' output. */
+  changes: Map<string, Change>;
+  manual: Manual[];
+  /** Files read, for the "scanned N files" line. */
+  scanned: number;
+}
+
+/** Every source file under `root`, relative-pathed and forward-slashed. */
+export async function collectFiles(root: string, extensions: string[]): Promise<SourceFile[]> {
+  const wanted = new Set(extensions);
+  const out: SourceFile[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // unreadable directory is not a reason to abandon an upgrade
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(full);
+        continue;
+      }
+      if (!wanted.has(extname(entry.name))) continue;
+      out.push({
+        file: relative(root, full).replace(/\\/g, "/"),
+        contents: await readFile(full, "utf8"),
+      });
+    }
+  }
+
+  await walk(root);
+  return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+
+/**
+ * The codemods that apply to a move from `from` to `to`.
+ *
+ * Exclusive of `from`, inclusive of `to`: an app already on 1.8.0 has paid
+ * 1.8.0's codemods, and an app moving *to* 2.0.0 owes 2.0.0's.
+ */
+export function selectCodemods(all: Codemod[], from: string, to: string): Codemod[] {
+  return all
+    .filter((c) => compareVersions(c.version, from) > 0 && compareVersions(c.version, to) <= 0)
+    .sort((a, b) => compareVersions(a.version, b.version) || a.name.localeCompare(b.name));
+}
+
+/**
+ * Build the plan without touching disk.
+ *
+ * Codemods run in sequence over the *accumulated* contents, so a later one sees
+ * what an earlier one produced. Two codemods rewriting the same line is a real
+ * possibility across a version range, and the alternative — each reading the
+ * original — silently drops one of them.
+ */
+export async function planUpgrade(
+  root: string,
+  codemods: Codemod[],
+  from: string,
+  to: string,
+): Promise<UpgradePlan> {
+  const selected = selectCodemods(codemods, from, to);
+  const extensions = [...new Set(selected.flatMap((c) => c.extensions ?? DEFAULT_EXTENSIONS))];
+  const files = await collectFiles(root, extensions.length ? extensions : DEFAULT_EXTENSIONS);
+
+  const current = new Map(files.map((f) => [f.file, f.contents]));
+  const changes = new Map<string, Change>();
+  const manual: Manual[] = [];
+
+  for (const codemod of selected) {
+    const wanted = new Set(codemod.extensions ?? DEFAULT_EXTENSIONS);
+    const input: SourceFile[] = [...current]
+      .filter(([file]) => wanted.has(extname(file)))
+      .map(([file, contents]) => ({ file, contents }));
+
+    const result = codemod.run(input);
+    for (const change of result.changes) {
+      current.set(change.file, change.contents);
+      const existing = changes.get(change.file);
+      changes.set(change.file, {
+        file: change.file,
+        // One line per file in the report, so a file touched by two codemods
+        // reads as one entry naming both rather than appearing twice.
+        summary: existing ? `${existing.summary}; ${change.summary}` : change.summary,
+        contents: change.contents,
+      });
+    }
+    manual.push(...result.manual);
+  }
+
+  return { codemods: selected, changes, manual, scanned: files.length };
+}
+
+/** Write the plan. Separate from building it, so `--dry` shares every other step. */
+export async function applyPlan(root: string, plan: UpgradePlan): Promise<number> {
+  for (const change of plan.changes.values()) {
+    await writeFile(join(root, change.file), change.contents, "utf8");
+  }
+  return plan.changes.size;
+}

package/src/upgrade/types.ts

@@ -0,0 +1,78 @@
+/**
+ * What an upgrade codemod is, and what it has to report.
+ *
+ * The shape is built around one belief: **the interesting output of an upgrade
+ * tool is what it could not do.** A codemod that rewrites nine call sites and
+ * silently walks past a tenth it did not understand is worse than one that
+ * rewrites nothing, because the nine give the impression the job is finished.
+ * So a codemod returns two lists, and the runner prints the second one louder.
+ */
+
+/** A file the codemod would rewrite, or did. */
+export interface Change {
+  /** Repo-relative path, forward slashes. */
+  file: string;
+  /** What changed, in a line a person can scan — "3 × `BaseModel` → `Model`". */
+  summary: string;
+  /** The rewritten contents. Held rather than written, so `--dry` costs nothing extra. */
+  contents: string;
+}
+
+/**
+ * Something the codemod recognised and deliberately did not touch.
+ *
+ * Not an error — a handover. Each one is a place the author has to look, with
+ * enough detail to find it and a reason that explains why a machine should not
+ * decide.
+ */
+export interface Manual {
+  file: string;
+  /** 1-based, so it can be clicked. */
+  line: number;
+  /** The line as it stands. */
+  text: string;
+  /** Why this one is a person's call. */
+  reason: string;
+}
+
+export interface CodemodResult {
+  changes: Change[];
+  manual: Manual[];
+}
+
+/** One file handed to a codemod. */
+export interface SourceFile {
+  file: string;
+  contents: string;
+}
+
+export interface Codemod {
+  /**
+   * The release that makes this necessary.
+   *
+   * Codemods run in version order, and only those between the app's current
+   * version and the target. A codemod for 2.0.0 does not run on an app moving
+   * from 1.6 to 1.7.
+   */
+  version: string;
+  /** Stable identifier, for `--only` and for reporting. */
+  name: string;
+  /** One line, shown in the plan before anything is written. */
+  description: string;
+  /** The ledger entry this pays, if it pays one. */
+  ledger?: number;
+  /** Files this wants to see. Keeps a codemod from scanning what it cannot use. */
+  extensions?: string[];
+  run(files: SourceFile[]): CodemodResult;
+}
+
+/** Compare two `x.y.z` strings numerically. */
+export function compareVersions(a: string, b: string): number {
+  const left = a.split(".").map(Number);
+  const right = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}