@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/incrementalBuilder/incrementalBuilder.host.test.ts

@@ -26,18 +26,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 +67,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 +75,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 +101,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 +112,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 +138,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 +151,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 +163,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);
@@ -222,11 +191,7 @@ 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 },
@@ -237,8 +202,6 @@ describe("IncrementalBuilderHost.maxRssBytes", () => {
   });
 
   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

@@ -14,12 +14,7 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "build-status",
   "builder-metrics",
 ]);
-/**
- * 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,48 +23,28 @@ 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;
 }
 
-/**
- * `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.
-   */
+  // A fresh boot is ~300-600MB; this leaves room for one full rebuild on top.
   static readonly #devMaxRssBytes = 1_200 * 1024 * 1024;
   logger = new Logger("IncrementalBuilderHost");
   entry: string;
@@ -87,16 +62,8 @@ export class IncrementalBuilderHost {
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: 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) {
@@ -110,11 +77,7 @@ export class IncrementalBuilderHost {
   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.
-   */
+  /** 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,8 +92,6 @@ 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;
     let proc!: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe">;
@@ -170,11 +131,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;
@@ -220,20 +179,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 +205,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 +217,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 +234,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;

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import type { BuilderMessage, BuilderReq } from "akanjs/server";
+import { createTempApp, tempRoots, writeText } from "../testHelpers";
+
+const track = tempRoots();
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const until = async (proc: Bun.Subprocess, what: string, condition: () => boolean) => {
+  const deadline = Date.now() + 20_000;
+  while (!condition()) {
+    if (proc.exitCode !== null || Date.now() > deadline) throw new Error(`the builder never sent ${what}`);
+    await wait(20);
+  }
+};
+
+describe("incremental builder process", () => {
+  test("says why and where a route's client bundle failed, in its answer, its build status and its log", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    // The batch runner looks under the workspace root first: a stand-in for the boot build, which needs a whole app.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+process.send({ type: "build-batch-result", data: { generation, errors: {}, artifact: {}, optimizedFonts: { css: "", files: [] } } });
+`,
+    );
+    const page = path.join(appDir, "page/_index.tsx");
+    await writeText(page, 'import { Broken } from "../ui/Broken";\nexport default Broken;\n');
+    await writeText(
+      path.join(appDir, "ui/Broken.tsx"),
+      '"use client";\nimport { gone } from "./not-there";\nexport const Broken = () => gone;\n',
+    );
+
+    const messages: BuilderMessage[] = [];
+    const proc = Bun.spawn(["bun", path.join(import.meta.dir, "incrementalBuilder.proc.ts")], {
+      cwd: appDir,
+      env: {
+        ...process.env,
+        AKAN_WORKSPACE_ROOT: root,
+        AKAN_PUBLIC_APP_NAME: "demo",
+        AKAN_PUBLIC_REPO_NAME: "repo",
+        AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_WATCH: "0",
+      },
+      stdio: ["ignore", "ignore", "pipe"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    try {
+      await until(proc, "builder-ready", () => messages.some((message) => message.type === "builder-ready"));
+      proc.send({
+        type: "build-route",
+        id: 1,
+        routeId: "page:/",
+        seeds: [page],
+        knownEntries: [],
+        generation: 3,
+      } satisfies BuilderReq);
+      await until(proc, "build-route-res", () => messages.some((message) => message.type === "build-route-res"));
+    } finally {
+      proc.kill();
+    }
+    const log = await new Response(proc.stderr).text();
+
+    const reason = '"./not-there" (apps/demo/ui/Broken.tsx:2:22)';
+    expect(messages.find((message) => message.type === "build-route-res")).toMatchObject({
+      id: 1,
+      ok: false,
+      error: expect.stringContaining(reason),
+    });
+    expect(messages.find((message) => message.type === "build-status")).toMatchObject({
+      data: { generation: 3, phase: "route", ok: false, message: expect.stringContaining(reason) },
+    });
+    expect(log).toContain(reason);
+  }, 30_000);
+});