@zerotal/core 1.14.0 → 1.14.1

package/CHANGELOG.md

@@ -8,6 +8,24 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.14.1] — 2026-09-01
+
+### Fixed
+
+- **A command that declares `needsApp = false` no longer boots the application.**
+  `CommandRunner.boot()` booted unconditionally, so `zt version`, `key:generate`, every
+  `make:*` scaffolder and the gate commands all paid for providers, a database connection
+  and a schedule registry they never touch — and could not run at all when booting was the
+  thing that was broken. A CLI you cannot reach when the app is down is missing exactly
+  when it is wanted.
+
+  Config is still bound, via the new `Application.bindConfig()`: `needsApp = false` is a
+  claim about the _application_, not about configuration, and every scaffolder reads config
+  for its output paths.
+
+  This also makes `zt version --json` pipeable, which previously needed the `--version`
+  form to avoid the boot log on stdout.
+
 ## [1.13.4] — 2026-09-01
 
 ### Fixed

package/api-surface.md

@@ -23,6 +23,7 @@ class Application = {
   _userResolver: ((id: number) => Promise<AuthenticatedUser | null>) | undefined
   adoptAsCurrent: () => Application
   bind: (callback: (container: Container) => void) => Application
+  bindConfig: () => Promise<void>
   boot: () => Promise<void>
   bootAsWorker: () => Promise<void>
   bootDurationMs: number | undefined
@@ -179,7 +180,7 @@ class CommandRan = {
 
 class CommandRunner = {
   new (_app: Application): CommandRunner
-  boot: () => Promise<void>
+  boot: (commandName?: string) => Promise<void>
   callInProcess: (argv: string[], parameters?: Record<string, string | boolean | number>) => Promise<{    code: number;    output: string;}>
   command: (definition: CommandDefinition, aliases?: string[]) => CommandClass
   discover: (dir: string) => Promise<string[]>

package/package.json

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

package/src/application/Application.ts

@@ -1157,23 +1157,7 @@ export class Application {
     this.container._app = this;
 
     // Auto-discover config when useConfig() was not called explicitly.
-    // Scans <cwd>/config/*.ts and loads each file's default export.
-    // Gracefully skips missing or unreadable files.
-    if (this._configMap === undefined) {
-      this._configMap = await _discoverConfig(process.cwd());
-    }
-
-    // Built-in core singletons (overridable by providers via last-write-wins)
-    this.container.singleton("config", () => new ConfigManager());
-    this.container.singleton("events", () => new Emitter(this.container));
-
-    if (this._configMap !== undefined) {
-      const configManager = new ConfigManager();
-      for (const [key, value] of Object.entries(this._configMap)) {
-        configManager.load(key, value);
-      }
-      this.container.value("config", configManager);
-    }
+    await this.bindConfig();
 
     // Auto-discover app/providers/* BEFORE the register phase so they run the full lifecycle.
     await this._discoverProviders(process.cwd());
@@ -1727,6 +1711,39 @@ export class Application {
     process.on("SIGUSR2", () => void this._reloadRoutes());
   }
 
+  /**
+   * Make `config` and `events` resolvable without booting the application.
+   *
+   * Split out of {@link boot} so a command that declares `needsApp = false` can
+   * read configuration without paying for providers, a database connection and a
+   * schedule registry it does not use. Every `make:*` scaffolder reads config for
+   * its output paths, so "does not need the app" and "does not need config" are
+   * different statements and only the first one is true of them.
+   *
+   * Idempotent: `boot()` calls it too, and calling it twice binds the same values.
+   *
+   * @category Configuration
+   */
+  async bindConfig(): Promise<void> {
+    // Scans <cwd>/config/*.ts and loads each file's default export.
+    // Gracefully skips missing or unreadable files.
+    if (this._configMap === undefined) {
+      this._configMap = await _discoverConfig(process.cwd());
+    }
+
+    // Built-in core singletons (overridable by providers via last-write-wins)
+    this.container.singleton("config", () => new ConfigManager());
+    this.container.singleton("events", () => new Emitter(this.container));
+
+    if (this._configMap !== undefined) {
+      const configManager = new ConfigManager();
+      for (const [key, value] of Object.entries(this._configMap)) {
+        configManager.load(key, value);
+      }
+      this.container.value("config", configManager);
+    }
+  }
+
   /**
    * Boot the application in the `worker` environment and block for queue/worker use.
    *

package/src/command/CommandRunner.ts

@@ -330,9 +330,16 @@ export class CommandRunner {
    * is dynamically imported. Application.create() reads it, so _env is already
    * correct by the time boot() runs — no argv inspection needed here.
    */
-  async boot(): Promise<void> {
+  async boot(commandName?: string): Promise<void> {
     this._app.container.value("commands", this);
-    await this._app.boot();
+
+    // Config first, and separately from the application.
+    //
+    // `needsApp = false` is a claim about the *application* — providers, the
+    // database, the schedule registry — not about configuration. Every `make:*`
+    // scaffolder reads config for its output paths, so binding it here is what
+    // makes skipping the boot below safe rather than merely fast.
+    await this._app.bindConfig();
 
     const {
       ServeCommand,
@@ -409,6 +416,17 @@ export class CommandRunner {
     // The `routes:types` alias was retired in 1.13.0; `zt upgrade` rewrites it.
     this.register(RouteTypesCommand);
 
+    // Boot the application only when the command actually needs one.
+    //
+    // This used to be unconditional, so `zt version`, `zt key:generate`, every
+    // `make:*` scaffolder and the gate commands all paid for providers, a database
+    // connection and a schedule registry they never touch — and, worse, could not
+    // run at all when booting was the thing that was broken. A CLI you cannot reach
+    // when the app is down is missing exactly when it is wanted.
+    //
+    // Resolved against the built-ins registered above. A name that is not among
+    // them may still be an app command from `app/commands/`, which is discovered
+    // below and needs the boot — so an unknown name boots rather than assuming.
     // Non-web commands (console, worker, test).
     if (this._app._env !== "web") {
       this.register(ReplCommand);
@@ -439,7 +457,20 @@ export class CommandRunner {
         LintPackagesCommand,
         MakePackageCommand,
       ]);
+    }
+
+    // Everything above is a pure `register()` call, so it happens before the
+    // decision — which is what lets a scaffolder skip the boot too. Deciding
+    // earlier would leave `make:*` unregistered and unrecognised, and an
+    // unrecognised name boots.
+    const requested = commandName ? this._resolveStatic(commandName) : undefined;
+    const skipBoot = requested !== undefined && requested.needsApp === false;
+
+    if (skipBoot) return;
+
+    await this._app.boot();
 
+    if (this._app._env !== "web") {
       // One `deploy:<target>` per environment this app releases to. Console-only,
       // like the other release commands — a running web server has no business
       // migrating a database.
@@ -497,6 +528,23 @@ export class CommandRunner {
   // ── Private resolution ────────────────────────────────────────────────────
 
   /** Resolve a command name to its class — handles both eager and lazy entries. */
+  /**
+   * Look a command up without resolving a lazy thunk.
+   *
+   * Used to decide whether to boot the application, which has to happen *before*
+   * anything is awaited that might need one. A thunk is `undefined` here rather
+   * than imported, so a lazily-registered command boots — the safe answer, since
+   * the only cost of booting unnecessarily is the cost this change avoids, while
+   * the cost of not booting when needed is a broken command.
+   *
+   * @internal
+   */
+  private _resolveStatic(name: string): CommandClass | undefined {
+    const entry = this._registry.get(name);
+    if (typeof entry === "function" && "commandName" in entry) return entry as CommandClass;
+    return undefined;
+  }
+
   private async _resolve(name: string): Promise<CommandClass | undefined> {
     const entry = this._registry.get(name);
     if (!entry) return undefined;

package/src/command/startZerotal.ts

@@ -88,7 +88,7 @@ export async function startZerotal(
   app.useConfig(config.all());
 
   const runner = new CommandRunner(app);
-  await runner.boot();
+  await runner.boot(command);
   await runner.run(process.argv.slice(2));
 }