@zerotal/core 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -8,6 +8,58 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.1] — 2026-08-31
+
+### Added
+
+- **`zt version`** — which Zerotal, which Bun, which app. The first question anyone
+  asks when filing a bug, and the CLI had no answer: `zt version` was an unknown
+  command, so the version had to be dug out of `package.json` or `node_modules` —
+  both of which report what is _installed_ rather than what is _running_, and those
+  differ for any process that has been up since before an upgrade.
+
+  `--version` and `-v` are answered earlier still, before the runtime check, the
+  config load and the app import, because those are the things someone is asking the
+  version _about_. A version flag that only works when the app already boots answers
+  a question nobody has. Add `--json` for a script.
+
+  Two notes on the output. It is uncoloured, unlike every other `Command` helper,
+  because it gets pasted into bug reports and piped into parsers more than it is read
+  on a terminal. And prefer `zt --version --json` over `zt version --json` in a
+  script: the application's boot log is written to stdout, so the second form emits a
+  log line ahead of the JSON while the first never boots at all.
+
+## [1.11.0] — 2026-08-31
+
+### Fixed
+
+- **A command can fail without throwing.** `CommandRunner` ran an unconditional
+  `process.exit(0)` the moment `run()` returned and never read `process.exitCode` —
+  which is the idiomatic way to fail a Bun/Node CLI without an exception, and what
+  most people reach for. An app's `release:check` printed six blockers, set the code,
+  and exited **0**; their deploy script read success and would have restarted a broken
+  production deployment. `zt deploy` gates on the same value through
+  `callInProcess`, so its own preflight had the hole too. A gate that cannot fail is
+  not a gate, and this one failed _open_.
+
+  `callInProcess` saves and restores the code around each command, because it runs
+  them in-process and the value is global. Note for anyone doing the same:
+  `process.exitCode = undefined` is a **no-op in Bun** — the previous value survives —
+  so clearing it takes `0`.
+
+- **A Bun the project never asked for is a warning, not a refusal.**
+  `bun-plugin-tailwind` declares `bun` as a _required_ peer, so `bun install` fetches
+  the Bun npm package as a second, newer runtime — and the runtime guard refused to
+  boot. An app took two production outages on this: the first crash-looping behind a
+  502, the second because the obvious fix (removing `node_modules/bun` after install)
+  cannot work — that package's postinstall runs _during_ install, so deleting it
+  leaves the tree incomplete.
+
+  Nothing about that is two runtimes in play; nobody executes the stray copy. The
+  guard now asks whether the project _declared_ `bun` in its own dependencies. If it
+  did, the refusal stands. If it did not, it warns and names the likely culprit, the
+  fix that works (`bun install --omit=peer`) and the one that does not.
+
 ## [1.10.0] — 2026-08-30
 
 ### Changed

package/api-surface.md

@@ -2151,6 +2151,34 @@ class UpgradeCommand = {
   write: (msg: string) => void
 }
 
+class VersionCommand = {
+  new (): VersionCommand
+  static args: never[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    type: 'boolean';    description: string;    default: boolean;}[]
+  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[]
@@ -3207,6 +3235,8 @@ function bunBinary = () => string
 
 function declaredBunFloor = (cwd: string) => {    range: string;    manifest: string;} | null
 
+function declaresBunDependency = (cwd: string) => boolean
+
 function installedBunVersion = (cwd: string) => {    version: string;    manifest: string;} | null
 
 function runtimeBelowFloor = (cwd?: string) => RuntimeFloor | null
@@ -3226,6 +3256,7 @@ interface RuntimeFloor = {
 }
 
 interface RuntimeMismatch = {
+  chosen?: boolean | undefined
   installed: string
   manifest: string
   running: string

package/package.json

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

package/src/command/CommandRunner.ts

@@ -343,6 +343,7 @@ export class CommandRunner {
       KeyGenerateCommand,
       ReloadCommand,
       StatusCommand,
+      VersionCommand,
       MakeControllerCommand,
       MakeMiddlewareCommand,
       MakeCommandCommand,
@@ -381,6 +382,10 @@ export class CommandRunner {
     this.register(ReloadCommand);
     this.register(StatusCommand);
 
+    // Always registered, and deliberately not gated on the boot mode: the answer to
+    // "which version is this" must not depend on which environment is asking.
+    this.register(VersionCommand);
+
     // route:list and doctor are inspection commands — always available regardless of mode.
     this.register(RouteListCommand);
     this.register(DoctorCommand);
@@ -533,8 +538,21 @@ export class CommandRunner {
     const startedAt = performance.now();
     try {
       await instance.run();
-      FrameworkEvents.emit(new CommandRan(name, performance.now() - startedAt, 0, true));
-      process.exit(0);
+
+      // Honour `process.exitCode` if the command set one.
+      //
+      // This used to be an unconditional `process.exit(0)`, so a command could
+      // only fail by throwing — and `process.exitCode = 1` is the idiomatic way
+      // to fail a Bun/Node CLI without an exception, which is what most people
+      // reach for. It was silently discarded. An app wrote a `release:check`
+      // gate that printed six blockers, set the code, and exited 0; the deploy
+      // script's `if ! …` read success and would have restarted a broken
+      // production deployment. A gate that cannot fail is not a gate, and that
+      // one failed *open*, which is the worst direction available.
+      const code = process.exitCode ?? 0;
+      const ok = Number(code) === 0;
+      FrameworkEvents.emit(new CommandRan(name, performance.now() - startedAt, Number(code), ok));
+      process.exit(Number(code));
     } catch (error) {
       FrameworkEvents.emit(
         new CommandRan(name, performance.now() - startedAt, 1, false, (error as Error).message),
@@ -594,16 +612,32 @@ export class CommandRunner {
 
     const name = (Cmd as { commandName?: string }).commandName ?? commandName;
     const startedAt = performance.now();
+    // `process.exitCode` is process-global, and this runs the command *in this
+    // process* — so it has to be cleared before and restored after, or a command
+    // that sets it poisons the runner and everything called after it. Reading it
+    // at all is the point: `zt deploy` gates on these return codes, and a
+    // `release:check` that printed its blockers and set the code used to come back
+    // as success. The gate failed open, which is the one direction a gate must not.
+    //
+    // `0`, not `undefined`, for both the clear and the restore: in Bun,
+    // `process.exitCode = undefined` is a no-op that leaves the previous value in
+    // place, so clearing with it does nothing and one blocked command marks every
+    // command after it as failed.
+    const outerExitCode = process.exitCode ?? 0;
+    process.exitCode = 0;
     try {
       await instance.run();
-      FrameworkEvents.emit(new CommandRan(name, performance.now() - startedAt, 0, true));
-      return { code: 0, output: writer.flush() };
+      const code = Number(process.exitCode ?? 0);
+      FrameworkEvents.emit(new CommandRan(name, performance.now() - startedAt, code, code === 0));
+      return { code, output: writer.flush() };
     } catch (error) {
       FrameworkEvents.emit(
         new CommandRan(name, performance.now() - startedAt, 1, false, (error as Error).message),
       );
       const errorLine = `\x1b[31m✖ ${(error as Error).message}\x1b[0m\n`;
       return { code: 1, output: writer.flush() + errorLine };
+    } finally {
+      process.exitCode = outerExitCode;
     }
   }
 

package/src/command/builtin/VersionCommand.ts

@@ -0,0 +1,53 @@
+import { Command } from "../Command.ts";
+import { _formatVersion, _versionInfo } from "../versionInfo.ts";
+
+/**
+ * `bun zt version` — which Zerotal, which Bun, which app.
+ *
+ * The first question anyone asks when filing a bug or reading a field report,
+ * and until now the CLI had no answer: `zt version` was an unknown command, so
+ * the version had to be dug out of `package.json` or `node_modules`, which
+ * reports what is *installed* rather than what is *running* — not the same thing
+ * for a process that has been up since before an upgrade.
+ *
+ * Registered in every environment and needs no application, so it still answers
+ * when the app does not boot. `--version` and `-v` are intercepted even earlier,
+ * in `startZerotal`, before config is loaded — see there for why.
+ *
+ * @example
+ * ```bash
+ * bun zt version
+ * bun zt version --json    # for a script
+ * ```
+ *
+ * @category Diagnostics
+ */
+export class VersionCommand extends Command {
+  static commandName = "version";
+  static description = "Show the Zerotal, Bun and app versions";
+  static needsApp = false;
+  static args = [];
+  static flags = [
+    {
+      name: "json",
+      type: "boolean" as const,
+      description: "Print as JSON",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const info = _versionInfo();
+
+    // `write`, not `line`: every other output helper on Command wraps its argument
+    // in an ANSI colour, and `zt version --json | jq` chokes on an escape code.
+    // The plain report goes the same way, for the same reason it is formatted
+    // plainly — it gets pasted into bug reports.
+    if (this.flags["json"] === true) {
+      this.write(`${JSON.stringify(info, null, 2)}\n`);
+      return;
+    }
+
+    this.write(`${_formatVersion(info)}\n`);
+  }
+}

package/src/command/builtin/index.ts

@@ -33,6 +33,7 @@ export { CompileCommand } from "./CompileCommand.ts";
 export { KeyGenerateCommand } from "./KeyGenerateCommand.ts";
 export { ReloadCommand } from "./ReloadCommand.ts";
 export { StatusCommand } from "./StatusCommand.ts";
+export { VersionCommand } from "./VersionCommand.ts";
 export { MakeControllerCommand } from "./MakeControllerCommand.ts";
 export { MakeMiddlewareCommand } from "./MakeMiddlewareCommand.ts";
 export { MakeCommandCommand } from "./MakeCommandCommand.ts";

package/src/command/startZerotal.ts

@@ -17,6 +17,7 @@ import {
 import type { RuntimeMismatch } from "../support/runtime.ts";
 import { RuntimeMismatchError } from "../errors/RuntimeMismatchError.ts";
 import type { Application } from "../application/Application.ts";
+import { _formatVersion, _versionInfo } from "./versionInfo.ts";
 
 /** Options for {@link startZerotal}. */
 export interface StartZerotalOptions {
@@ -44,6 +45,29 @@ export async function startZerotal(
   loadApp: () => Promise<{ default: Application }>,
   options: StartZerotalOptions = {},
 ): Promise<void> {
+  // Answer `--version` before anything else can fail to.
+  //
+  // Ahead of the runtime assertion, the config load and the app import, because
+  // those are exactly the things someone is asking the version *about*: a config
+  // that no longer validates and an app that will not boot are the two moments
+  // when "which version am I on" stops being idle curiosity. A version flag that
+  // only works when everything else already works answers a question nobody has.
+  //
+  // It reports a second runtime as a line of output rather than throwing about
+  // one, which is strictly more informative than the refusal it skips.
+  // `--json` is honoured here and not only on the command, because this is the
+  // path that produces clean output: the app's boot log goes to stdout, so
+  // `zt version --json` — which dispatches normally, and therefore boots — cannot
+  // be piped into a parser. This form never boots, so it can.
+  const first = process.argv[2] ?? "";
+  if (first === "--version" || first === "-v") {
+    const info = _versionInfo();
+    console.log(
+      process.argv.includes("--json") ? JSON.stringify(info, null, 2) : _formatVersion(info),
+    );
+    return;
+  }
+
   // 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.
@@ -98,7 +122,23 @@ function assertOneRuntime(): void {
   }
 
   const mismatch = runtimeMismatch();
-  if (mismatch) _refuse(runtimeMismatchMessage(mismatch), mismatch);
+  if (!mismatch) return;
+
+  // A runtime the project never asked for is a warning, not a refusal. It arrives
+  // as a transitive peer — `bun-plugin-tailwind` declares `bun` as a required peer
+  // and Bun auto-installs it — and nothing executes the stray copy, so "two
+  // runtimes in play" is not what is happening. Refusing over it crash-looped an
+  // app behind a 502 twice, and the remedies the refusal prints are the wrong ones
+  // for this cause. Loud, because the version skew is still real if anything ever
+  // *does* run it.
+  if (mismatch.chosen === false) {
+    console.warn(`
+⚠  ${runtimeMismatchMessage(mismatch)}
+`);
+    return;
+  }
+
+  _refuse(runtimeMismatchMessage(mismatch), mismatch);
 }
 
 /**

package/src/command/versionInfo.ts

@@ -0,0 +1,89 @@
+/**
+ * What `bun zt version` reports, and the formatting of it.
+ *
+ * Split out of the command because the same answer has to be available from two
+ * places: the registered {@link VersionCommand}, and the early intercept in
+ * `startZerotal` that answers `--version` before config is loaded or the app is
+ * imported. Those two must not drift — a version command that reports one thing
+ * when the app boots and another when it does not is worse than either.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { ZEROTAL_VERSION } from "../support/version.ts";
+import { runtimeMismatch } from "../support/runtime.ts";
+
+/** Everything `zt version` knows. Fields are `null` when there is nothing to read. */
+export interface _VersionInfo {
+  /** Version of the running framework, e.g. `1.11.0`. */
+  zerotal: string;
+  /** Version of the Bun executing this process. */
+  bun: string;
+  /** The app's own name and version from its `package.json`, when it has one. */
+  app: { name: string; version: string } | null;
+  /**
+   * A second Bun installed under `node_modules`, when one is there.
+   *
+   * Usually arrives as a transitive peer nothing executes, so it is reported
+   * rather than complained about — but it is the recurring cause of "which Bun
+   * actually ran this", and `version` is where someone goes to ask.
+   */
+  otherBun: string | null;
+}
+
+/**
+ * Collect the versions worth reporting.
+ *
+ * @param cwd - Project root to read the app manifest and `node_modules` from.
+ * @internal
+ */
+export function _versionInfo(cwd: string = process.cwd()): _VersionInfo {
+  return {
+    zerotal: ZEROTAL_VERSION,
+    bun: Bun.version,
+    app: _appManifest(cwd),
+    otherBun: runtimeMismatch(cwd)?.installed ?? null,
+  };
+}
+
+/** The app's own name and version, or `null` when the manifest is missing or unreadable. */
+function _appManifest(cwd: string): { name: string; version: string } | null {
+  try {
+    const raw = readFileSync(`${cwd}/package.json`, "utf8");
+    const { name, version } = JSON.parse(raw) as { name?: string; version?: string };
+    if (name === undefined && version === undefined) return null;
+    return { name: name ?? "(unnamed)", version: version ?? "(no version)" };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render {@link _VersionInfo} as the lines `zt version` prints.
+ *
+ * Plain text with no colour, because this output gets piped into scripts and
+ * pasted into bug reports more often than it gets read on a terminal.
+ *
+ * @internal
+ */
+export function _formatVersion(info: _VersionInfo): string {
+  const rows: [string, string][] = [
+    ["Zerotal", info.zerotal],
+    ["Bun", info.bun],
+  ];
+  if (info.app) rows.push(["App", `${info.app.name} ${info.app.version}`]);
+
+  const width = Math.max(...rows.map(([label]) => label.length));
+  const lines = rows.map(([label, value]) => `${label.padEnd(width)}  ${value}`);
+
+  if (info.otherBun !== null && info.otherBun !== info.bun) {
+    lines.push(
+      "",
+      `node_modules also contains bun ${info.otherBun}, which is not the one running.`,
+      `Nothing executes it — it arrives as a peer dependency — but that is the copy`,
+      `an install would use if anything ever did.`,
+    );
+  }
+
+  return lines.join("\n");
+}

package/src/support/runtime.ts

@@ -35,6 +35,12 @@ export interface RuntimeMismatch {
   installed: string;
   /** Absolute path of the manifest `installed` was read from. */
   manifest: string;
+  /**
+   * Whether the project *asked* for a `bun` package — named it in its own
+   * dependencies — or merely acquired one as a transitive peer. A mismatch the
+   * project chose is a refusal; one it did not is a warning.
+   */
+  chosen?: boolean | undefined;
 }
 
 /**
@@ -83,7 +89,54 @@ export function runtimeMismatch(cwd: string = process.cwd()): RuntimeMismatch |
   const installed = installedBunVersion(cwd);
   if (!installed) return null;
   if (installed.version === running) return null;
-  return { running, installed: installed.version, manifest: installed.manifest };
+  return {
+    running,
+    installed: installed.version,
+    manifest: installed.manifest,
+    chosen: declaresBunDependency(cwd),
+  };
+}
+
+/**
+ * Whether the project asked for a `bun` package, or merely ended up with one.
+ *
+ * This is the difference between two runtimes and one runtime plus a stray npm
+ * package, and it decides whether the mismatch is a refusal or a warning.
+ *
+ * It matters because the common way to acquire a `node_modules/bun` is not to want
+ * one. `bun-plugin-tailwind@0.1.2` — which the scaffold itself installs — declares
+ * `"peerDependencies": { "bun": ">=1.0.0" }` with no `peerDependenciesMeta` marking
+ * it optional, so `bun install` auto-installs the Bun *npm package* as a second
+ * runtime, newer than the one executing. An app hit exactly that and took two
+ * production outages: the first when the refusal crash-looped behind a 502, the
+ * second when the obvious fix (`rm -rf node_modules/bun` after install) could not
+ * work, because that package's postinstall runs *during* install and its removal
+ * leaves the tree incomplete.
+ *
+ * Nothing about that situation is a project running two runtimes. Nobody executes
+ * the stray copy; it is a directory. Refusing to boot over it is the guard being
+ * confidently wrong, and the remedies it prints — `bun update bun`, or run
+ * everything through `node_modules/.bin/bun` — are both wrong answers to it.
+ *
+ * @param cwd - Project root to look under.
+ * @returns `true` when a manifest up the tree names `bun` in its own dependencies.
+ */
+export function declaresBunDependency(cwd: string): boolean {
+  let dir = cwd;
+  for (;;) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      if (manifest.dependencies?.["bun"] ?? manifest.devDependencies?.["bun"]) return true;
+    } catch {
+      // No manifest here, or unreadable — keep climbing.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
 }
 
 /**
@@ -93,12 +146,34 @@ export function runtimeMismatch(cwd: string = process.cwd()): RuntimeMismatch |
  * @param mismatch - The disagreement to describe.
  */
 export function runtimeMismatchMessage(mismatch: RuntimeMismatch): string {
-  return (
+  const head =
     `Two Bun runtimes are in play. This process is Bun ${mismatch.running}, but the ` +
     `project installs Bun ${mismatch.installed} (${mismatch.manifest}).\n\n` +
     `  Whichever one is not running this command is still running something else — ` +
     `the server, the suite, a deploy step — and a test that passes under one is not ` +
-    `evidence about the other.\n\n` +
+    `evidence about the other.\n\n`;
+
+  // Nothing named `bun`, so it arrived as a transitive peer. Naming the usual
+  // culprit is most of the fix, because the remedies below are the opposite of the
+  // ones for a runtime somebody chose — and following those instead cost an app two
+  // production outages.
+  if (mismatch.chosen === false) {
+    return (
+      head +
+      `  Nothing in this project depends on "bun", so it arrived as a transitive peer —\n` +
+      `  usually bun-plugin-tailwind, which declares "bun" as a required peer dependency\n` +
+      `  and has Bun auto-install it as a second runtime.\n\n` +
+      `  Fix it by not installing it:\n` +
+      `    bun install --omit=peer   # skips every peer; safe when yours are direct deps\n\n` +
+      `  Do NOT remove node_modules/bun after installing. That package's postinstall runs\n` +
+      `  *during* install, so deleting it afterwards leaves the tree incomplete and the\n` +
+      `  next install fails — which is its own outage.\n\n` +
+      `  To boot anyway, set ${RUNTIME_MISMATCH_ESCAPE}=1 — it downgrades this to a warning.`
+    );
+  }
+
+  return (
+    head +
     `  Fix it by picking one:\n` +
     `    bun update bun          # move the installed one to match your shell\n` +
     `    node_modules/.bin/bun   # or run everything through the installed one\n\n` +