@zerotal/core 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -8,6 +8,38 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [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
+
+- **`import.meta.env` is defined for bundled browser builds.** `DEV`, `PROD` and `MODE`,
+  set from whether the build is a production one. It is a Vite convention rather than a web
+  standard — `import.meta.env` is undefined in a browser module — but enough of the npm
+  ecosystem branches on it that a bundler leaving it alone ships code reading a property off
+  `undefined`. Bun leaves it alone, so Zerotal defines it.
+
+  `BASE_URL` and `SSR` are deliberately omitted: Zerotal has its own answers for both, and a
+  wrong value is worse than an absent one for a package that feature-detects.
+
 ## [1.6.0] — 2026-08-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/core",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "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/dev/DevOrchestrator.ts

@@ -5,6 +5,7 @@
 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";
 
 /**
  * How the orchestrator reports to whatever is presenting dev mode.
@@ -156,6 +157,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,
@@ -289,6 +293,11 @@ export class DevOrchestrator {
     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/buildEnv.ts

@@ -0,0 +1,41 @@
+/**
+ * The `import.meta.env` members a bundled browser build is expected to carry.
+ *
+ * These are a Vite convention, not a web standard — `import.meta.env` is
+ * undefined in a browser module — but enough of the npm ecosystem branches on
+ * them that a bundler which leaves them alone ships code that reads a property
+ * off `undefined`. Bun's bundler leaves them alone, so we define them.
+ *
+ * The case that found this: the Inertia DevTools browser extension relies on
+ * client-side hooks that `createInertiaApp()` enables from its `dev` option,
+ * and that option's default is literally `import.meta.env.DEV`. Under Bun that
+ * expression survived into the bundle, so the panel reported the app was "not
+ * running in dev mode" and told the developer to start a Vite server they do
+ * not have — advice that cannot be followed in a Zerotal app.
+ *
+ * Only the three members whose meaning is unambiguous are defined. `BASE_URL`
+ * and `SSR` are deliberately omitted: Zerotal has its own answers for both
+ * (`app.assets.prefix`, and SSR being a server concern), and a wrong value is
+ * worse than an absent one for a package that feature-detects.
+ *
+ * @param isProduction Whether this build is for a deployment.
+ * @internal
+ */
+export function browserEnvDefines(isProduction: boolean): Record<string, string> {
+  return {
+    // The WHOLE object, not `import.meta.env.DEV` member by member. Adapters write
+    // `import.meta.env?.DEV` — optional-chained, which is why an unbundled
+    // `import.meta.env` yields `false` instead of throwing — and a define keyed on
+    // `import.meta.env.DEV` does not match `import.meta.env?.DEV`, so the member
+    // form silently changes nothing. Replacing the object satisfies both spellings.
+    //
+    // Members this does not name resolve to `undefined` rather than throwing, which
+    // is the right answer for a bundler that is not Vite: code that feature-detects
+    // `import.meta.env.SSR` or a `VITE_*` variable gets a clean miss.
+    "import.meta.env": JSON.stringify({
+      DEV: !isProduction,
+      PROD: isProduction,
+      MODE: isProduction ? "production" : "development",
+    }),
+  };
+}

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/dev/index.ts

@@ -30,6 +30,7 @@ export type { BuildHookFn, BuildResult } from "./DevBuildHook.ts";
 export { DevReloadMiddleware, registerDevHtmlSnippet } from "./DevReloadMiddleware.ts";
 export type { DevHtmlSnippet } from "./DevReloadMiddleware.ts";
 export { DEV_RELOAD_CLIENT } from "./reloadClient.ts";
+export { browserEnvDefines } from "./buildEnv.ts";
 export { detectCssPlugins, buildCssBundle, buildJsBundle } from "./CssPlugins.ts";
 export type { AssetBuildConfig } from "./CssPlugins.ts";
 export { pruneBuildOutput } from "./BuildOutput.ts";