@zerotal/core 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,37 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [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

@@ -3207,6 +3207,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 +3228,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.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,

package/src/command/CommandRunner.ts

@@ -533,8 +533,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 +607,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/startZerotal.ts

@@ -98,7 +98,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/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` +