@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -1,4 +1,8 @@
 import { afterEach, describe, expect, mock, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
 import { IncrementalBuilderHost } from "./incrementalBuilder.host";
 
@@ -26,18 +30,25 @@ const mockSpawns = (): SpawnRecord[] => {
   return spawns;
 };
 
+const createHost = (onMessage: (message: unknown) => void = () => undefined) =>
+  new IncrementalBuilderHost({ app: { cwdPath: "/tmp/app" } as never, entry: "/tmp/builder.ts", env: {}, onMessage });
+
+const startRecordingHost = () => {
+  const spawns = mockSpawns();
+  const messages: unknown[] = [];
+  const host = createHost((message) => messages.push(message));
+  host.start();
+  spawns[0]?.options.ipc?.({ type: "builder-ready" });
+  return { spawns, messages, host };
+};
+
 describe("IncrementalBuilderHost", () => {
   test("restarts after a ready builder exits", async () => {
     const spawns = mockSpawns();
 
     const onReady = mock();
     const onRestartReady = mock();
-    const host = new IncrementalBuilderHost({
-      app: { cwdPath: "/tmp/app" } as never,
-      entry: "/tmp/builder.ts",
-      env: {},
-      onMessage: () => undefined,
-    });
+    const host = createHost();
 
     host.start({ onReady, onRestartReady });
     spawns[0]?.options.ipc?.({ type: "builder-ready" });
@@ -60,12 +71,7 @@ describe("IncrementalBuilderHost", () => {
   test("recycles a ready builder gracefully and replaces it immediately", async () => {
     const spawns = mockSpawns();
     const onRestartReady = mock();
-    const host = new IncrementalBuilderHost({
-      app: { cwdPath: "/tmp/app" } as never,
-      entry: "/tmp/builder.ts",
-      env: {},
-      onMessage: () => undefined,
-    });
+    const host = createHost();
 
     host.start({ onRestartReady });
     spawns[0]?.options.ipc?.({ type: "builder-ready" });
@@ -73,18 +79,14 @@ describe("IncrementalBuilderHost", () => {
 
     const reason = "rss=1300MiB>=1200MiB after 3 build(s)";
     expect(host.recycle(reason)).toBe(true);
-    // Graceful: the builder is asked to drain, not killed, so a rebuild in flight still completes.
     expect(spawns[0]?.proc.send).toHaveBeenCalledWith({ type: "builder-shutdown", reason });
     expect(spawns[0]?.proc.kill).not.toHaveBeenCalled();
     expect(host.recycle("second request")).toBe(false);
 
-    // The drain refuses everything that arrives during it, so a request sent here is a request the
-    // developer gets an error page for. Reporting the state is what lets the host hold it instead.
     expect(host.status).toBe("recycling");
     expect(host.send({ type: "build-route", id: 9, routeId: "z", seeds: [], knownEntries: [] })).toBe(false);
     expect(spawns[0]?.proc.send).toHaveBeenCalledTimes(1);
 
-    // A planned exit skips the crash backoff — the dev server has no file watcher until it is back.
     spawns[0]?.options.onExit?.();
     expect(spawns).toHaveLength(2);
     expect(spawns[1]?.options.env?.AKAN_BUILDER_ANNOUNCE_BOOT).toBe("1");
@@ -103,17 +105,7 @@ describe("IncrementalBuilderHost", () => {
   });
 
   test("fails the requests a departing builder never answered", async () => {
-    const spawns = mockSpawns();
-    const messages: unknown[] = [];
-    const host = new IncrementalBuilderHost({
-      app: { cwdPath: "/tmp/app" } as never,
-      entry: "/tmp/builder.ts",
-      env: {},
-      onMessage: (message) => messages.push(message),
-    });
-
-    host.start();
-    spawns[0]?.options.ipc?.({ type: "builder-ready" });
+    const { spawns, messages, host } = startRecordingHost();
     expect(host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] })).toBe(true);
     expect(host.send({ type: "build-csr", id: 2, reason: "device webview" })).toBe(true);
     // Answered before the exit, so this one must not be failed again afterwards.
@@ -124,8 +116,6 @@ describe("IncrementalBuilderHost", () => {
     host.recycle("rss=1300MiB>=1200MiB after 3 build(s)");
     spawns[0]?.options.onExit?.();
 
-    // Nothing else answers these: the builder only refuses requests that arrive after it starts shutting
-    // down, and a kill or a truncated write sends nothing at all.
     expect(messages).toEqual([
       {
         type: "build-route-res",
@@ -152,17 +142,7 @@ describe("IncrementalBuilderHost", () => {
   });
 
   test("names a crash rather than a recycle, and answers on stop too", async () => {
-    const spawns = mockSpawns();
-    const messages: unknown[] = [];
-    const host = new IncrementalBuilderHost({
-      app: { cwdPath: "/tmp/app" } as never,
-      entry: "/tmp/builder.ts",
-      env: {},
-      onMessage: (message) => messages.push(message),
-    });
-
-    host.start();
-    spawns[0]?.options.ipc?.({ type: "builder-ready" });
+    const { spawns, messages, host } = startRecordingHost();
     host.send({ type: "build-route", id: 1, routeId: "a", seeds: [], knownEntries: [] });
     messages.length = 0;
     spawns[0]?.options.onExit?.();
@@ -175,8 +155,6 @@ describe("IncrementalBuilderHost", () => {
       },
     ]);
 
-    // `stop()` clears the process before its exit callback runs, so the callback bails on its identity
-    // check and cannot be the only place this happens.
     await wait(1_050);
     spawns[1]?.options.ipc?.({ type: "builder-ready" });
     messages.length = 0;
@@ -189,12 +167,7 @@ describe("IncrementalBuilderHost", () => {
 
   test("only recycles a builder that is ready", () => {
     const spawns = mockSpawns();
-    const host = new IncrementalBuilderHost({
-      app: { cwdPath: "/tmp/app" } as never,
-      entry: "/tmp/builder.ts",
-      env: {},
-      onMessage: () => undefined,
-    });
+    const host = createHost();
 
     host.start();
     expect(host.recycle("while still booting")).toBe(false);
@@ -203,6 +176,36 @@ describe("IncrementalBuilderHost", () => {
     host.stop();
     expect(host.recycle("after stop")).toBe(false);
   });
+
+  test("a patcher a crash turned off stays off in the host that replaces this one", async () => {
+    const cwdPath = await mkdtemp(path.join(os.tmpdir(), "akan-builder-patcher-"));
+    try {
+      const spawns = mockSpawns();
+      const app = { cwdPath } as never;
+      const host = new IncrementalBuilderHost({ app, entry: "/tmp/builder.ts", env: {}, onMessage: () => undefined });
+      host.start();
+      spawns[0]?.options.ipc?.({ type: "builder-ready" });
+      const marker = path.join(cwdPath, ".akan/artifact", SSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER);
+      await Bun.write(marker, "");
+      spawns[0]?.options.onExit?.();
+      await wait(1_050);
+      expect(spawns[1]?.options.env?.AKAN_DEV_CSR_PATCHER).toBe("off");
+      expect(host.patcherOff).toBe(true);
+      host.stop();
+      const next = new IncrementalBuilderHost({
+        app,
+        entry: "/tmp/builder.ts",
+        env: {},
+        onMessage: () => undefined,
+        patcherOff: host.patcherOff,
+      });
+      next.start();
+      expect(spawns[2]?.options.env?.AKAN_DEV_CSR_PATCHER).toBe("off");
+      next.stop();
+    } finally {
+      await rm(cwdPath, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("IncrementalBuilderHost.maxRssBytes", () => {
@@ -222,23 +225,17 @@ describe("IncrementalBuilderHost.maxRssBytes", () => {
     }
   };
 
-  /**
-   * Only where nothing else supplies a limit, which is not true in a container: a cgroup `memory.max`
-   * makes `resolveMaxRssBytes` derive from that instead. Measured under `docker --memory=7g`, this
-   * returned 2.45GiB rather than the fallback — the assertion was about the runner, not the code.
-   */
+  // Skipped under a cgroup `memory.max`, which `resolveMaxRssBytes` derives the ceiling from instead.
   test.skipIf(MemoryLimit.readCgroupBytes() !== null)("defaults to a dev ceiling well above a fresh boot", () => {
     withEnv(
       { AKAN_BUILDER_MAX_RSS_MB: undefined, AKAN_BUILDER_MAX_RSS: undefined, AKAN_MEMORY_LIMIT: undefined },
       () => {
-        expect(IncrementalBuilderHost.maxRssBytes()).toBe(1_200 * 1024 * 1024);
+        expect(IncrementalBuilderHost.maxRssBytes()).toBe(2_048 * 1024 * 1024);
       },
     );
   });
 
   test("derives the ceiling from the sandbox's own limit, wherever it runs", () => {
-    // The property the fallback test cannot assert in a container, stated so it holds on every runner:
-    // the builder gets 35% of whatever the sandbox is allowed.
     withEnv(
       {
         AKAN_BUILDER_MAX_RSS_MB: undefined,

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -1,6 +1,8 @@
+import fs from "node:fs";
 import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
+import { CSR_DEV_DIRNAME, CSR_DEV_PATCHING_MARKER, SSR_DEV_DIRNAME } from "akanjs/server/hmr/csrDevManifest";
 import { MemoryLimit } from "akanjs/server/memoryLimit";
 import type { App } from "../commandDecorators";
 
@@ -11,15 +13,13 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "invalidate",
   "css-updated",
   "pages-updated",
+  "csr-updated",
+  "ssr-updated",
   "build-status",
   "builder-metrics",
+  "boot-armed",
 ]);
-/**
- * Where a dev child process writes. `"pipe"` is not only about keeping a TUI's frame clean: a Bun child
- * that inherits the controlling terminal snapshots its termios at spawn and writes that snapshot back
- * when it exits, so a builder spawned while something holds the terminal raw turns it raw again on the
- * first recycle. See the XXX comment on `Spinner.oraOptions`.
- */
+/** Prefer `"pipe"` under a TUI: a Bun child that inherits the terminal restores its spawn-time termios on exit. */
 export type DevStdioMode = "inherit" | "pipe";
 
 interface IncrementalBuilderHostOptions {
@@ -28,49 +28,32 @@ interface IncrementalBuilderHostOptions {
   env: Record<string, string>;
   stdio?: DevStdioMode;
   onMessage: (message: BuilderMessage) => void;
-  /**
-   * Required when `stdio` is `"pipe"`: an undrained pipe fills and blocks the builder's next write.
-   * Text arrives as decoded chunks, not lines — a consumer that needs lines splits them itself.
-   */
+  /** Required with `stdio: "pipe"` (an undrained pipe blocks the builder); receives decoded chunks, not lines. */
   onOutput?: (kind: "stdout" | "stderr", text: string) => void;
+  /** Carried over from the host this one replaces: a patcher a crash turned off stays off. */
+  patcherOff?: boolean;
 }
 
-/**
- * `recycling` is the drain: the builder is still alive and still holds the work it accepted, but it
- * refuses anything new. Saying so here is what lets the host hold those requests for the replacement
- * instead of handing the developer the refusal.
- */
+/** `recycling`: the builder finishes accepted work but refuses new requests; hold them for the replacement. */
 export type IncrementalBuilderStatus = "starting" | "ready" | "recycling" | "restarting" | "stopped";
 
 interface IncrementalBuilderStartOptions {
   onExit?: () => void;
   onReady?: () => void;
   onRestartReady?: () => void;
-  /**
-   * The builder is gone and a replacement is on its way. Distinct from `onExit`, which reports the
-   * builder giving up: this one says the dev server is temporarily without a watcher.
-   */
+  /** The builder is gone and a replacement is coming (unwatched until then); `onExit` means it gave up. */
   onAway?: () => void;
-  /**
-   * Ask the builder to re-announce the artifact it boots with. Needed whenever a *previous* builder's
-   * artifact may still be live in a running backend — after an rss recycle, and after an idle wake.
-   */
+  /** Re-announce the boot artifact, for when a previous builder's artifact may still be live in the backend. */
   announceBootState?: boolean;
 }
 
 export class IncrementalBuilderHost {
   static readonly #restartBaseDelayMs = 1_000;
   static readonly #restartMaxDelayMs = 30_000;
-  /**
-   * A builder that has stopped answering has to be replaced anyway; killing it after this long turns
-   * a wedged drain into an ordinary restart instead of leaving the recycle stuck forever.
-   */
   static readonly #recycleDrainTimeoutMs = 30_000;
-  /**
-   * Dev has no memory limit to derive a fraction from, so this is what bounds the builder there. Well
-   * above a fresh boot (~300-600MB depending on app size) with room for one full rebuild on top.
-   */
-  static readonly #devMaxRssBytes = 1_200 * 1024 * 1024;
+  // apps/akan's builder peaks near 950MB holding the SSR registry's patcher through a route build, and arming CSR adds
+  // a second patcher: this recycles only a builder grown well past both.
+  static readonly #devMaxRssBytes = 2_048 * 1024 * 1024;
   logger = new Logger("IncrementalBuilderHost");
   entry: string;
   env: Record<string, string>;
@@ -86,35 +69,36 @@ export class IncrementalBuilderHost {
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
+  #patcherOff: boolean = false;
   #manualStop = false;
-  /**
-   * Requests handed to the running builder that it has not answered yet, keyed by the backend's
-   * correlation id.
-   *
-   * Nothing else answers a request whose builder exits while holding it: the builder only refuses
-   * requests that arrive *after* it starts shutting down, a kill or crash sends nothing at all, and even
-   * a clean drain races its own `process.exit`. The builder exits routinely — it is recycled whenever its
-   * RSS passes the ceiling — so a page request that happened to be mid route-build left the backend's
-   * promise pending and the browser tab spinning with no error and nothing to retry.
-   */
+  // Nothing else answers a request whose builder exits holding it: a crash or kill sends nothing, and a drain races
+  // its own exit, so an unanswered page request would spin forever.
   readonly #inFlight = new Map<number, "build-route" | "build-csr">();
   #startOptions: IncrementalBuilderStartOptions = {};
-  constructor({ app, entry, env, stdio = "inherit", onMessage, onOutput }: IncrementalBuilderHostOptions) {
+  constructor({
+    app,
+    entry,
+    env,
+    stdio = "inherit",
+    onMessage,
+    onOutput,
+    patcherOff = false,
+  }: IncrementalBuilderHostOptions) {
     this.app = app;
     this.entry = entry;
     this.env = env;
     this.#stdio = stdio;
     this.#onMessage = onMessage;
     this.#onOutput = onOutput ?? null;
+    this.#patcherOff = patcherOff;
   }
   get status() {
     return this.#status;
   }
-  /**
-   * The running builder's pid, so the host can read its RSS from the OS between builds. The builder
-   * only reports its own metrics at work-completion points, which is the *peak*; on a platform that
-   * returns bundler arenas to the OS while idle, that sample goes stale within seconds.
-   */
+  get patcherOff(): boolean {
+    return this.#patcherOff;
+  }
+  /** For reading RSS between builds: the builder's own metrics sample the post-work peak, stale once arenas return. */
   get pid(): number | null {
     return this.#proc?.pid ?? null;
   }
@@ -129,14 +113,18 @@ export class IncrementalBuilderHost {
   #spawn(isRestart: boolean) {
     this.#status = isRestart ? "restarting" : "starting";
     this.ready = false;
-    // A fresh builder rebuilds every artifact while the running backend still holds the previous one;
-    // the flag is what tells it to re-announce what it booted with.
     const afterRecycle = this.#spawnAfterRecycle;
     this.#spawnAfterRecycle = false;
+    this.#checkPatchingMarker(isRestart && !afterRecycle);
     let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
     proc = Bun.spawn(["bun", this.entry], {
       cwd: this.app.cwdPath,
-      env: { ...this.env, AKAN_WATCH: "1", ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}) },
+      env: {
+        ...this.env,
+        AKAN_WATCH: "1",
+        ...(afterRecycle ? { AKAN_BUILDER_ANNOUNCE_BOOT: "1" } : {}),
+        ...(this.#patcherOff ? { AKAN_DEV_CSR_PATCHER: "off" } : {}),
+      },
       stdio: ["ignore", this.#stdio, this.#stdio],
       ipc: (msg: BuilderMessage) => {
         if (this.#proc !== proc) return;
@@ -170,11 +158,9 @@ export class IncrementalBuilderHost {
           this.#startOptions.onExit?.();
           return;
         }
-        // Said once for both branches below, because both leave the tree unwatched until a replacement
-        // has primed its own index — and an edit that lands in that window is reported by nobody.
+        // Both branches below leave the tree unwatched until the replacement primes its index.
         this.#startOptions.onAway?.();
-        // A recycle is a planned exit, so it neither counts as a failed attempt nor waits out the
-        // crash backoff — the dev server is without a watcher until the replacement is up.
+        // A planned exit: no failed attempt, no crash backoff.
         if (wasRecycle) {
           this.logger.verbose("builder exited for a recycle; spawning its replacement now");
           this.#spawnAfterRecycle = true;
@@ -192,6 +178,23 @@ export class IncrementalBuilderHost {
     }
     this.logger.verbose(`builder spawned pid=${proc.pid} entry=${this.entry}${isRestart ? " restart=1" : ""}`);
   }
+  //? The resident builder patches the dev CSR bundle in its own process, so a bundler crash there takes the file watcher
+  //? with it. A builder that died holding the marker hands every later CSR save to build workers for this session;
+  //? a marker any other exit left behind (Ctrl-C mid-patch) is cleared so it cannot turn the patcher off next session.
+  #checkPatchingMarker(afterCrash: boolean): void {
+    const markers = [CSR_DEV_DIRNAME, SSR_DEV_DIRNAME]
+      .map((dirName) => path.join(this.app.cwdPath, ".akan/artifact", dirName, CSR_DEV_PATCHING_MARKER))
+      .filter((marker) => fs.existsSync(marker));
+    if (markers.length === 0) return;
+    if (afterCrash && !this.#patcherOff) {
+      this.#patcherOff = true;
+      this.logger.warn(
+        "the builder died while patching a dev module registry; registry saves go to a build worker until the next config or metadata restart (AKAN_DEV_CSR_PATCHER=off)",
+      );
+    }
+    for (const marker of markers) fs.rmSync(marker, { force: true });
+  }
+
   async #drain(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
     if (!stream) return;
     const decoder = new TextDecoder();
@@ -220,20 +223,14 @@ export class IncrementalBuilderHost {
       this.#spawn(true);
     }, delay);
   }
-  /**
-   * Ask the builder to drain its queues and exit so the OS reclaims the bundler arenas `Bun.build`
-   * never gives back; `onExit` then spawns the replacement. Graceful rather than `kill()` so a rebuild
-   * in flight is never truncated, with a watchdog for a builder that stops answering.
-   */
+  /** Drain-and-exit rather than `kill()`, so no rebuild is truncated; false when the request was not sent. */
   recycle(reason: string): boolean {
     if (!this.#proc || this.#status !== "ready" || this.#recycleRequested) return false;
     const proc = this.#proc;
     if (!this.send({ type: "builder-shutdown", reason })) return false;
     this.#recycleRequested = true;
-    // From here the builder answers nothing new — it refuses every request that arrives during the
-    // drain. Leaving the status at `ready` is what used to let those requests through to be refused,
-    // one at a time, into the dev error page a recycle is supposed to be invisible to. `ready` the
-    // field is deliberately untouched: `onExit` reads it to tell a planned exit from a boot failure.
+    // Not `ready`: the draining builder refuses new requests. The `ready` field stays, since `onExit` reads it to tell
+    // a planned exit from a boot failure.
     this.#status = "recycling";
     this.logger.debug(`recycling builder pid=${proc.pid} (${reason})`);
     this.#recycleTimer = setTimeout(() => {
@@ -252,11 +249,7 @@ export class IncrementalBuilderHost {
     clearTimeout(this.#recycleTimer);
     this.#recycleTimer = null;
   }
-  /**
-   * RSS at which the builder is recycled: an explicit override, else a share of the container's limit
-   * (the builder is one of several dev processes), else the dev default. Set
-   * `AKAN_BUILDER_MAX_RSS_MB=0` to leave it unbounded.
-   */
+  /** RSS that triggers a recycle; `null` (`AKAN_BUILDER_MAX_RSS_MB=0`) means unbounded. */
   static maxRssBytes(): number | null {
     if (process.env.AKAN_BUILDER_MAX_RSS_MB === "0") return null;
     return MemoryLimit.resolveMaxRssBytes({
@@ -268,8 +261,7 @@ export class IncrementalBuilderHost {
   }
   send(message: BuilderMessage): boolean {
     if (!this.#proc || this.#status !== "ready") {
-      // A builder on its way back is routine and the host holds what it refuses here, so only the
-      // states nothing is recovering from are worth a warning.
+      // Recycling/restarting is routine (the caller holds the message), so only unrecoverable states warn.
       if (this.#status === "recycling" || this.#status === "restarting")
         this.logger.verbose(`incrementalBuilderHost is ${this.#status}; ${message.type} is for the replacement`);
       else this.logger.warn(`incrementalBuilderHost is ${this.#status}; cannot send ${message.type}`);
@@ -286,19 +278,13 @@ export class IncrementalBuilderHost {
       return false;
     }
   }
-  /**
-   * Answer every request the departing builder still owed, as if it had failed them itself. `onExit`
-   * cannot do this alone: `stop()` clears `#proc` first, so the exit callback bails on its identity check.
-   */
+  // Called from `stop()` too: it clears `#proc` first, so `onExit` bails on its identity check.
   #failInFlight(reason: string): void {
     if (!this.#inFlight.size) return;
     const lost = [...this.#inFlight];
     this.#inFlight.clear();
     this.logger.warn(`failing ${lost.length} unanswered builder request(s): ${reason}`);
-    for (const [id, type] of lost) {
-      if (type === "build-route") this.#onMessage({ type: "build-route-res", id, ok: false, error: reason });
-      else this.#onMessage({ type: "build-csr-res", id, ok: false, error: reason });
-    }
+    for (const [id, type] of lost) this.#onMessage({ type: `${type}-res`, id, ok: false, error: reason });
   }
   stop() {
     this.#manualStop = true;
@@ -320,7 +306,8 @@ export class IncrementalBuilderHost {
     {
       stdio = "inherit",
       onOutput,
-    }: { stdio?: DevStdioMode; onOutput?: (kind: "stdout" | "stderr", text: string) => void } = {},
+      patcherOff = false,
+    }: Pick<IncrementalBuilderHostOptions, "stdio" | "onOutput" | "patcherOff"> = {},
   ) {
     const candidates = [
       path.join(app.workspace.workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts"),
@@ -333,7 +320,7 @@ export class IncrementalBuilderHost {
     ];
     for (const c of candidates)
       if (await Bun.file(c).exists())
-        return new IncrementalBuilderHost({ app, entry: c, env, stdio, onMessage, onOutput });
+        return new IncrementalBuilderHost({ app, entry: c, env, stdio, onMessage, onOutput, patcherOff });
     throw new Error(`[cli] frontend builder entry not found; looked in: ${candidates.join(", ")}`);
   }
 }