@zerotal/core 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -8,7 +8,51 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
-## [1.6.1] — 2026-08-15
+## [1.6.3] — 2026-08-15
+
+### Added
+
+- **`serve --dev` says when the framework on disk is no longer the framework running.** A
+  running dev server holds the code it imported at boot: `bun add zerotal@latest` in another
+  terminal rewrites `node_modules` and nothing else, and a save restarts only the _worker_,
+  which re-executes your app against that same in-memory framework. So an upgrade taken
+  mid-session appears to do nothing — the fix is installed, the symptom persists, and the
+  reasonable conclusion is that the fix does not work.
+
+  The supervisor now compares the version it booted with against the one installed, on each
+  restart, and says which is which:
+
+  ```text
+  [zerotal:dev] ⚠  framework upgraded on disk: running v1.6.2, installed v1.6.3
+  [zerotal:dev]    restart the dev server to pick it up (a save will not).
+  ```
+
+  Once per version, so a long session is not nagged, and silent where there is nothing to read
+  — a workspace checkout or a hoisted layout is not a finding.
+
+- **The dev banner carries the version** — `Zerotal v1.6.3 › dev`. There was previously
+  nothing on screen naming the framework a running server was actually executing.
+
+## [1.6.2] — 2026-08-15
+
+### Fixed
+
+- **`serve --dev` killed its worker outright on Windows instead of stopping it.** A restart
+  sent `SIGTERM`, but Windows has no POSIX signals: there that call is `TerminateProcess`, so
+  the worker died mid-instruction. No provider ran `onStopping`, no open response was
+  finished, no database handle was closed — on every save, since that is how the dev server
+  reloads. The visible symptom was a console full of `ERR_INCOMPLETE_CHUNKED_ENCODING` from
+  the devtools event stream, which is just what a chunked response looks like when the
+  process writing it stops existing.
+
+  The supervisor now **asks** over an IPC channel and kills only if the request goes
+  unanswered within a second. POSIX behaviour is unchanged in substance — the worker runs the
+  same `stop()` either way — and Windows gets the orderly shutdown it never had. Verified
+  across a real hot restart: before, an open stream ended in a connection reset with the
+  worker never draining; after, the stream ends cleanly and the worker logs its stop.
+
+  A supervisor that cannot open a channel falls straight through to the signal path, so
+  nothing waits out the grace period for a chance it never had.
 
 ### Added
 

package/package.json

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

package/src/application/Application.ts

@@ -9,6 +9,7 @@ import { ServiceProvider } from "../provider/ServiceProvider.ts";
 import type { AuthenticatedUser } from "../auth/AuthenticatedUser.ts";
 import * as DevWsServer from "../dev/DevWsServer.ts";
 import { DevReloadMiddleware, setDevReloadClientActive } from "../dev/DevReloadMiddleware.ts";
+import { onGracefulStopRequest } from "../dev/devShutdown.ts";
 import type { HttpContext } from "../pipeline/HttpContext.ts";
 import { Pipeline } from "../pipeline/Pipeline.ts";
 import { ExceptionHandler } from "./ExceptionHandler.ts";
@@ -1520,6 +1521,11 @@ export class Application {
       process.on(signal, () => void this.stop());
     }
 
+    // Windows cannot deliver either of those to a child, so `serve --dev` asks
+    // over IPC instead and this is the ear for it. Silent anywhere there is no
+    // supervisor on the other end.
+    onGracefulStopRequest(() => void this.stop());
+
     process.on("SIGUSR2", () => void this._reloadRoutes());
   }
 

package/src/command/builtin/ServeCommand.ts

@@ -24,6 +24,7 @@ import {
   type PortOwner,
 } from "../../support/port.ts";
 import { localNetworkAddress } from "../../support/network.ts";
+import { ZEROTAL_VERSION } from "../../support/version.ts";
 import { createInterface } from "node:readline";
 
 /**
@@ -319,7 +320,11 @@ export class ServeCommand extends Command {
     const network = localNetworkAddress();
 
     this.newLine();
-    this.line(`  Zerotal  ›  ${mode}`);
+    // The version is here because a running server holds the framework it booted
+    // with: an upgrade installed in another terminal is invisible until a full
+    // restart, and without this line there is nothing on screen to tell you which
+    // one you are looking at.
+    this.line(`  Zerotal v${ZEROTAL_VERSION}  ›  ${mode}`);
     this.newLine();
     this._route("Local", `http://localhost:${port}`);
     this._route(

package/src/dev/DevOrchestrator.ts

@@ -5,6 +5,8 @@
 import { watch } from "node:fs";
 import type { BuildHookFn } from "./DevBuildHook.ts";
 import { DEV_WORKER_ENV_VAR } from "../support/env.ts";
+import { requestGracefulStop } from "./devShutdown.ts";
+import { ZEROTAL_VERSION, installedCoreVersion } from "../support/version.ts";
 
 /**
  * How the orchestrator reports to whatever is presenting dev mode.
@@ -80,6 +82,8 @@ export class DevOrchestrator {
    * queues a single follow-up instead of running in parallel.
    */
   private _restartInFlight: Promise<void> | null = null;
+  /** The installed version already warned about, so one upgrade warns once. */
+  private _warnedVersion: string | null = null;
   private _restartQueued = false;
 
   /**
@@ -156,6 +160,9 @@ export class DevOrchestrator {
         stdin: "pipe",
         stdout: routed ? "pipe" : "inherit",
         stderr: routed ? "pipe" : "inherit",
+        // Opens the channel `_stopChild` asks over. Nothing is sent the other
+        // way, but Bun only gives the parent a `send` when a handler is present.
+        ipc: () => {},
         cwd: this._cwd,
         env: {
           ...Bun.env,
@@ -278,17 +285,48 @@ export class DevOrchestrator {
     // browser refetches the updated CSS.
     await this._runBuild();
 
+    this._warnIfFrameworkUpgradedUnderneath();
+
     // Stop before spawning, always: the old server owns the port until it exits.
     await this._stopChild();
     await this._spawnServerWithRetry();
   }
 
+  /**
+   * Say so when the framework on disk is no longer the framework running.
+   *
+   * A `bun add zerotal@latest` in another terminal changes `node_modules` and
+   * nothing else: this process holds the code it imported at boot, and a restart
+   * only re-executes the *app* against that same in-memory framework. So the
+   * upgrade appears to have no effect — the fix is installed, the symptom
+   * persists, and the obvious conclusion is that the fix does not work.
+   *
+   * Checked on restart rather than at boot, because that is when it can have
+   * become true, and warned once per version so a long session is not nagged.
+   */
+  private _warnIfFrameworkUpgradedUnderneath(): void {
+    const onDisk = installedCoreVersion(this._cwd);
+    if (onDisk === null || onDisk === ZEROTAL_VERSION || onDisk === this._warnedVersion) return;
+
+    this._warnedVersion = onDisk;
+    this._say(
+      `  [zerotal:dev] ⚠  framework upgraded on disk: running v${ZEROTAL_VERSION}, installed v${onDisk}`,
+      "warn",
+    );
+    this._say("  [zerotal:dev]    restart the dev server to pick it up (a save will not).", "warn");
+  }
+
   /** Stop the running server and wait for it to actually exit, releasing the port. */
   private async _stopChild(): Promise<void> {
     const child = this._child;
     this._child = null;
     if (!child) return;
 
+    // Ask first. On Windows a signal cannot reach the worker at all — it is
+    // terminated where it stands, with open responses left half-written — and
+    // asking is the only way it ever drains its providers. See devShutdown.ts.
+    if (await requestGracefulStop(child)) return;
+
     child.kill("SIGTERM");
     const forceKill = setTimeout(() => child.kill("SIGKILL"), 1_500);
     try {

package/src/dev/devShutdown.ts

@@ -0,0 +1,89 @@
+/**
+ * Asking a dev worker to stop, on a platform where a signal cannot.
+ *
+ * Windows has no POSIX signals. `child.kill("SIGTERM")` there is
+ * `TerminateProcess`: the worker dies mid-instruction, so no provider drains, no
+ * open response is finished, and no database handle is closed — on every save,
+ * because that is how `serve --dev` restarts. The visible symptom is a browser
+ * console full of `ERR_INCOMPLETE_CHUNKED_ENCODING` from the devtools event
+ * stream, which is simply what a chunked response looks like when the process
+ * writing it stops existing.
+ *
+ * The supervisor therefore asks over the IPC channel first and kills only when
+ * the request goes unanswered. POSIX behaviour is unchanged in substance — the
+ * worker runs the same {@link Application.stop} either way — and Windows gains
+ * the orderly shutdown it never had.
+ *
+ * @module
+ */
+
+/** The message a supervisor sends to ask a worker to shut itself down. */
+export const DEV_SHUTDOWN_MESSAGE = "zerotal:dev:shutdown";
+
+/** How long a supervisor waits for the worker to go on its own, in ms. */
+export const DEV_SHUTDOWN_GRACE_MS = 1_000;
+
+/** The part of a spawned child this module needs. */
+export interface StoppableChild {
+  send?: (message: unknown) => void;
+  exited: Promise<number>;
+}
+
+/**
+ * Ask a child to shut itself down, and wait for it to actually go.
+ *
+ * @param child - The spawned worker. Must have been spawned with an `ipc`
+ *   handler, or there is no channel to ask over and this returns `false`.
+ * @param graceMs - How long to wait before giving up on the request.
+ * @returns `true` if the child exited on its own, `false` if the caller still
+ *   has to kill it. Never throws: a dead channel is a `false`, not an error,
+ *   because the caller's next move is the same either way.
+ *
+ * @example
+ * if (!(await requestGracefulStop(child))) child.kill("SIGTERM");
+ */
+export async function requestGracefulStop(
+  child: StoppableChild,
+  graceMs: number = DEV_SHUTDOWN_GRACE_MS,
+): Promise<boolean> {
+  if (typeof child.send !== "function") return false;
+
+  try {
+    child.send(DEV_SHUTDOWN_MESSAGE);
+  } catch {
+    // The channel is already gone, which means so is the chance of a polite
+    // exit. The caller kills.
+    return false;
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const outcome = await Promise.race([
+      child.exited.then(() => "exited" as const),
+      new Promise<"timeout">((resolve) => {
+        timer = setTimeout(() => resolve("timeout"), graceMs);
+      }),
+    ]);
+    return outcome === "exited";
+  } catch {
+    // `exited` rejecting means the child is gone by some other route.
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Run `stop` when a supervisor asks this process to shut down.
+ *
+ * Installed by {@link Application} alongside its signal handlers. Harmless in a
+ * process with no IPC channel — the message never arrives — so it needs no
+ * environment check to stay out of production's way.
+ *
+ * @param stop - What to run. Called at most once per request.
+ */
+export function onGracefulStopRequest(stop: () => void): void {
+  process.on("message", (message: unknown) => {
+    if (message === DEV_SHUTDOWN_MESSAGE) stop();
+  });
+}

package/src/support/version.ts

@@ -0,0 +1,39 @@
+/**
+ * The framework version this build of `@zerotal/core` is.
+ *
+ * Read from the manifest rather than written down, for the reason `@zerotal/monitor`
+ * already learned: a hardcoded version is correct until the next release, and three
+ * separate literals across the monorepo once claimed a version that had never been
+ * published. The monorepo releases in lockstep, so this package's manifest carries
+ * the framework version, and it ships inside the tarball.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+
+const pkg: { version: string } = JSON.parse(
+  readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+) as { version: string };
+
+/** Full version of the running framework, e.g. `1.6.2`. */
+export const ZEROTAL_VERSION: string = pkg.version;
+
+/**
+ * The version of `@zerotal/core` currently installed in a project, which is not
+ * necessarily {@link ZEROTAL_VERSION} — a long-running process holds the code it
+ * booted with, so an upgrade lands on disk without reaching it.
+ *
+ * @param cwd - Project root to look under.
+ * @returns The installed version, or `null` when there is nothing to read — a
+ *   workspace checkout, a hoisted layout, a partial install. Absence is not a
+ *   finding, so callers stay quiet on `null` rather than guessing.
+ */
+export function installedCoreVersion(cwd: string): string | null {
+  try {
+    const raw = readFileSync(`${cwd}/node_modules/@zerotal/core/package.json`, "utf8");
+    const { version } = JSON.parse(raw) as { version?: string };
+    return version ?? null;
+  } catch {
+    return null;
+  }
+}