@zerotal/core 1.11.0 → 1.11.1

package/CHANGELOG.md

@@ -8,6 +8,27 @@ 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

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[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.11.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);

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.

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");
+}