@akanjs/devkit 3.0.0-beta.24 → 3.0.0-beta.26

package/incrementalBuilder/buildBatchRunner.test.ts

@@ -31,4 +31,35 @@ describe("BuildBatchRunner", () => {
 
     expect(result.errors.base).toContain('"./not-there" (apps/demo/page/_index.tsx:1:22)');
   }, 30_000);
+
+  test("a worker that dies mid-batch keeps what each need reported, and fails only the needs it never reached", async () => {
+    const { root } = track(await createTempApp("demo"));
+    const appDir = path.join(root, "apps/demo");
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `const { generation } = JSON.parse(process.argv[2]);
+const status = (phase, message) =>
+  process.send({ type: "build-status", data: { generation, phase, ok: !message, files: [], message } });
+status("ssr");
+status("css", "css broke");
+setTimeout(() => process.exit(1), 50);
+`,
+    );
+    const result = await new BuildBatchRunner({ workspaceRoot: root, cwd: appDir }).run({
+      appName: "demo",
+      workspaceRoot: root,
+      repoName: "repo",
+      generation: 7,
+      needs: ["ssr", "css", "pages"],
+      changedFiles: [],
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.join(appDir, ".akan/artifact"),
+    });
+    expect(result).toMatchObject({ crashed: true, crashedNeeds: ["pages"] });
+    expect(result.errors.ssr).toBeUndefined();
+    expect(result.errors.css).toBe("css broke");
+    expect(result.errors.pages).toContain("exited with code 1");
+  }, 30_000);
 });

package/incrementalBuilder/buildBatchRunner.ts

@@ -3,7 +3,8 @@ import { Logger } from "akanjs/common";
 import type { BuilderMessage } from "akanjs/server";
 import type { BuildBatchMessage, BuildBatchRequest, BuildBatchResult } from "./buildBatchProtocol";
 
-// No pool on purpose: one worker at a time, exiting after its batch, returns the arenas `Bun.build` never frees.
+// No pool on purpose: a worker exiting after its batch returns the arenas `Bun.build` never frees. The callers order
+// their own work (the slow lane, the css queue, the SSR registry's boot build beside them), so a few can overlap.
 // A worker that dies without reporting must not take the watcher down; its needs come back as errors.
 export class BuildBatchRunner {
   #logger = new Logger("BuildBatchRunner");
@@ -38,8 +39,10 @@ export class BuildBatchRunner {
     const started = Date.now();
     const entry = await this.#resolveEntry();
     let result: BuildBatchResult | null = null;
+    const reported = new Map<string, string | undefined>();
+    const payload = request.trace ? { ...request, trace: { ...request.trace, spawnAt: Date.now() } } : request;
     // argv rather than IPC, so the worker starts on its first tick instead of waiting for a handshake.
-    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(payload)], {
       cwd: this.#cwd,
       env: process.env,
       stdio: ["ignore", "inherit", "inherit"],
@@ -47,7 +50,10 @@ export class BuildBatchRunner {
       ipc: (message: BuildBatchMessage | BuilderMessage) => {
         if (!message || typeof message !== "object") return;
         if (message.type === "build-batch-result") result = message.data;
-        else onMessage(message);
+        else {
+          if (message.type === "build-status") reported.set(message.data.phase, message.data.message);
+          onMessage(message);
+        }
       },
     });
     const exitCode = await proc.exited;
@@ -64,10 +70,13 @@ export class BuildBatchRunner {
         }`
       : `build worker exited with code ${exitCode} before reporting a result`;
     this.#logger.error(`[build-batch] generation=${request.generation} ${message}`);
-    return {
-      generation: request.generation,
-      errors: Object.fromEntries(request.needs.map((need) => [need, message])),
-      crashed: true,
-    };
+    //? A need that reported before the crash keeps what it reported: a worker killed during pages built ssr and css.
+    const crashedNeeds = request.needs.filter((need) => !reported.has(need));
+    const failed = request.needs.flatMap((need) => {
+      if (!reported.has(need)) return [[need, message] as const];
+      const error = reported.get(need);
+      return error ? [[need, error] as const] : [];
+    });
+    return { generation: request.generation, errors: Object.fromEntries(failed), crashed: true, crashedNeeds };
   }
 }

package/incrementalBuilder/builderWorkQueue.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { type BatchJob, BuilderWorkQueue } from "./builderWorkQueue";
+
+const gate = () => {
+  const { promise: opened, resolve: open } = Promise.withResolvers<void>();
+  return { open, opened };
+};
+
+describe("BuilderWorkQueue", () => {
+  test("runs jobs one at a time, in the order they were queued", async () => {
+    const order: string[] = [];
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const first = gate();
+    const a = queue.enqueue("a", async () => {
+      await first.opened;
+      order.push("a");
+    });
+    const b = queue.enqueue("b", async () => {
+      order.push("b");
+      return 2;
+    });
+    expect(queue.size).toBe(2);
+    first.open();
+    await a;
+    expect(await b).toBe(2);
+    expect(order).toEqual(["a", "b"]);
+    expect(queue.size).toBe(0);
+  });
+
+  test("folds a batch queued behind another batch into it, for the newest generation", async () => {
+    const ran: BatchJob[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        ran.push(batch);
+        if (ran.length === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages", "css"], changedFiles: ["a.tsx"] });
+    const second = queue.enqueueBatch({
+      generation: 2,
+      needs: ["pages", "css"],
+      changedFiles: ["b.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+    const third = queue.enqueueBatch({ generation: 3, needs: ["csr", "pages"], changedFiles: ["a.tsx", "c.tsx"] });
+    expect(second).toBe(third);
+    running.open();
+    await Promise.all([first, second, third]);
+    expect(ran).toHaveLength(2);
+    expect(ran[1]).toEqual({
+      generation: 3,
+      needs: ["pages", "css", "csr"],
+      changedFiles: ["b.tsx", "a.tsx", "c.tsx"],
+      discovery: { files: ["b.tsx"], refresh: false, generation: 2 },
+    });
+  });
+
+  test("keeps a batch queued after a task behind that task", async () => {
+    const order: string[] = [];
+    const running = gate();
+    const queue = new BuilderWorkQueue({
+      runBatch: async (batch) => {
+        order.push(`batch:${batch.generation}`);
+        if (batch.generation === 1) await running.opened;
+      },
+    });
+    const first = queue.enqueueBatch({ generation: 1, needs: ["pages"], changedFiles: [] });
+    const route = queue.enqueue("route", async () => {
+      order.push("route");
+    });
+    const second = queue.enqueueBatch({ generation: 2, needs: ["pages"], changedFiles: [] });
+    running.open();
+    await Promise.all([first, route, second]);
+    expect(order).toEqual(["batch:1", "route", "batch:2"]);
+  });
+
+  test("drains jobs queued while it waits, and survives a job that throws", async () => {
+    const queue = new BuilderWorkQueue({ runBatch: async () => undefined });
+    const failing = queue.enqueue("fails", async () => {
+      throw new Error("boom");
+    });
+    let late = false;
+    void queue.enqueue("queues-more", async () => {
+      void queue.enqueue("late", async () => {
+        late = true;
+      });
+    });
+    await expect(failing).rejects.toThrow("boom");
+    await queue.drain();
+    expect(late).toBe(true);
+    expect(queue.size).toBe(0);
+  });
+});

package/incrementalBuilder/builderWorkQueue.ts

@@ -0,0 +1,126 @@
+import type { HmrTrace } from "akanjs/server";
+import type { BuildBatchNeed } from "./buildBatchProtocol";
+
+export interface DiscoveryJob {
+  files: string[];
+  refresh: boolean;
+  /** The newest batch these files came from: a route build that starts after has taken it in. */
+  generation: number;
+}
+
+export interface BatchJob {
+  generation: number;
+  needs: BuildBatchNeed[];
+  changedFiles: string[];
+  trace?: HmrTrace;
+  /** Code files whose client-entry discovery goes stale before this batch builds; `refresh` rebuilds it whole. */
+  discovery?: DiscoveryJob;
+}
+
+interface QueuedJob {
+  label: string;
+  batch: BatchJob | null;
+  run: () => Promise<void>;
+  settle: PromiseWithResolvers<void>;
+}
+
+export interface BuilderWorkQueueOptions {
+  runBatch: (batch: BatchJob) => Promise<void>;
+  onSettled?: (label: string, ms: number) => void;
+}
+
+//* The builder's slow lane: build-worker batches, route builds and full CSR builds run here one at a time, so a save's
+//* CSR patch never waits behind them. A batch queued behind another batch folds into it: a burst of saves builds pages
+//* and css once for the newest generation instead of once per save.
+export class BuilderWorkQueue {
+  readonly #runBatch: BuilderWorkQueueOptions["runBatch"];
+  readonly #onSettled: BuilderWorkQueueOptions["onSettled"];
+  readonly #pending: QueuedJob[] = [];
+  #running: QueuedJob | null = null;
+  #idle: Promise<void> = Promise.resolve();
+  #wakeIdle: (() => void) | null = null;
+
+  constructor({ runBatch, onSettled }: BuilderWorkQueueOptions) {
+    this.#runBatch = runBatch;
+    this.#onSettled = onSettled;
+  }
+
+  /** Jobs waiting or running. */
+  get size(): number {
+    return this.#pending.length + (this.#running ? 1 : 0);
+  }
+
+  enqueueBatch(batch: BatchJob): Promise<void> {
+    const tail = this.#pending.at(-1);
+    if (tail?.batch) {
+      tail.batch = BuilderWorkQueue.merge(tail.batch, batch);
+      return tail.settle.promise;
+    }
+    const job = this.#job("batch", batch, async () => undefined);
+    job.run = async () => await this.#runBatch(job.batch ?? batch);
+    return this.#push(job);
+  }
+
+  enqueue<T>(label: string, run: () => Promise<T>): Promise<T> {
+    let result: T | undefined;
+    const job = this.#job(label, null, async () => {
+      result = await run();
+    });
+    return this.#push(job).then(() => result as T);
+  }
+
+  /** Resolves once nothing is waiting or running, including jobs queued while it waits. */
+  async drain(): Promise<void> {
+    while (this.size > 0) await this.#idle;
+  }
+
+  static merge(into: BatchJob, next: BatchJob): BatchJob {
+    const discovery =
+      into.discovery || next.discovery
+        ? {
+            files: [...new Set([...(into.discovery?.files ?? []), ...(next.discovery?.files ?? [])])],
+            refresh: !!into.discovery?.refresh || !!next.discovery?.refresh,
+            generation: Math.max(into.discovery?.generation ?? 0, next.discovery?.generation ?? 0),
+          }
+        : undefined;
+    return {
+      generation: Math.max(into.generation, next.generation),
+      needs: [...new Set([...into.needs, ...next.needs])],
+      changedFiles: [...new Set([...into.changedFiles, ...next.changedFiles])],
+      trace: next.trace ?? into.trace,
+      ...(discovery ? { discovery } : {}),
+    };
+  }
+
+  #job(label: string, batch: BatchJob | null, run: () => Promise<void>): QueuedJob {
+    return { label, batch, run, settle: Promise.withResolvers<void>() };
+  }
+
+  #push(job: QueuedJob): Promise<void> {
+    if (this.size === 0)
+      this.#idle = new Promise<void>((resolve) => {
+        this.#wakeIdle = resolve;
+      });
+    this.#pending.push(job);
+    if (!this.#running) void this.#pump();
+    return job.settle.promise;
+  }
+
+  async #pump(): Promise<void> {
+    for (let job = this.#pending.shift(); job; job = this.#pending.shift()) {
+      this.#running = job;
+      const started = Date.now();
+      try {
+        await job.run();
+        job.settle.resolve();
+      } catch (error) {
+        job.settle.reject(error);
+      } finally {
+        this.#running = null;
+        this.#onSettled?.(job.label, Date.now() - started);
+      }
+    }
+    this.#wakeIdle?.();
+    this.#wakeIdle = null;
+  }
+}

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";
 
@@ -172,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", () => {
@@ -196,7 +230,7 @@ describe("IncrementalBuilderHost.maxRssBytes", () => {
     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);
       },
     );
   });

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";
 
@@ -12,8 +14,10 @@ const builderMsgTypeSet = new Set<BuilderMessage["type"]>([
   "css-updated",
   "pages-updated",
   "csr-updated",
+  "ssr-updated",
   "build-status",
   "builder-metrics",
+  "boot-armed",
 ]);
 /** Prefer `"pipe"` under a TUI: a Bun child that inherits the terminal restores its spawn-time termios on exit. */
 export type DevStdioMode = "inherit" | "pipe";
@@ -26,6 +30,8 @@ interface IncrementalBuilderHostOptions {
   onMessage: (message: BuilderMessage) => void;
   /** 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`: the builder finishes accepted work but refuses new requests; hold them for the replacement. */
@@ -45,8 +51,9 @@ export class IncrementalBuilderHost {
   static readonly #restartBaseDelayMs = 1_000;
   static readonly #restartMaxDelayMs = 30_000;
   static readonly #recycleDrainTimeoutMs = 30_000;
-  // A fresh boot is ~300-600MB; this leaves 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>;
@@ -62,22 +69,35 @@ export class IncrementalBuilderHost {
   #recycleTimer: ReturnType<typeof setTimeout> | null = null;
   #recycleRequested: boolean = false;
   #spawnAfterRecycle: boolean = false;
+  #patcherOff: boolean = false;
   #manualStop = false;
   // 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;
   }
+  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;
@@ -95,10 +115,16 @@ export class IncrementalBuilderHost {
     this.ready = false;
     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;
@@ -152,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();
@@ -263,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"),
@@ -276,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(", ")}`);
   }
 }