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

package/frontendBuild/ssrDevBundler.ts

@@ -8,7 +8,7 @@ import { bundleDefine } from "./bundleDefine";
 import type { ClientEntryDiscovery } from "./clientBuildTypes";
 import { GraphClientEntryDiscovery } from "./clientEntryDiscovery";
 import { CsrDevPaths } from "./csrDevPaths";
-import type { CsrDevContext, CsrDevGraph } from "./csrDevTypes";
+import type { CsrDevContext } from "./csrDevTypes";
 import { DevRegistryBundler } from "./devRegistryBundler";
 import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
 
@@ -79,12 +79,6 @@ export class SsrDevBundler extends DevRegistryBundler {
     return this.#discovery;
   }
 
-  override async wantedRoots(files: string[], graph: CsrDevGraph): Promise<Set<string>> {
-    const entries = new Set(await this.clientEntries());
-    const reached = await super.wantedRoots(files, graph);
-    return new Set(files.filter((file) => reached.has(file) || entries.has(CsrDevPaths.realpath(file))));
-  }
-
   protected async rootFiles(entryFiles: string[]): Promise<string[]> {
     return [...entryFiles, ...(await this.clientEntries())];
   }

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", () => {

package/incrementalBuilder/incrementalBuilder.host.ts

@@ -30,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. */
@@ -73,17 +75,29 @@ export class IncrementalBuilderHost {
   // 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;
@@ -292,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"),
@@ -305,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(", ")}`);
   }
 }

package/incrementalBuilder/incrementalBuilder.proc.test.ts

@@ -77,7 +77,7 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
       error: expect.stringContaining(reason),
     });
     expect(messages.find((message) => message.type === "build-status")).toMatchObject({
-      data: { generation: 6, phase: "route", ok: false, message: expect.stringContaining(reason) },
+      data: { generation: 6, phase: "route", ok: false, message: expect.stringContaining(reason), scope: "page:/" },
     });
     expect(log).toContain(reason);
   }, 30_000);
@@ -148,6 +148,67 @@ process.send({ type: "build-batch-result", data: { generation, errors: {}, artif
     }
   }, 60_000);
 
+  test("a route build's check whose own worker is killed is tried again after the crash window", async () => {
+    const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));
+    const appDir = path.join(root, "apps/demo");
+    const runs = path.join(root, "ssr-runs.log");
+    // The boot build succeeds, the route check's worker is killed, and the retry after the window succeeds.
+    await writeText(
+      path.join(root, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+      `import fs from "node:fs";
+const { generation, needs } = JSON.parse(process.argv[2]);
+if (needs.includes("ssr")) {
+  fs.appendFileSync(${JSON.stringify(runs)}, Date.now() + "\\n");
+  if (fs.readFileSync(${JSON.stringify(runs)}, "utf8").trim().split("\\n").length === 2) process.exit(1);
+}
+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 { Card } from "../ui/Card";\nexport default Card;\n');
+    await writeText(path.join(appDir, "ui/Card.tsx"), '"use client";\nexport const Card = () => null;\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", "ignore"],
+      serialization: "advanced",
+      ipc: (message: BuilderMessage) => {
+        messages.push(message);
+      },
+    });
+    const ssrRuns = async () =>
+      (await Bun.file(runs).exists()) ? (await Bun.file(runs).text()).trim().split("\n").map(Number) : [];
+    try {
+      await until(proc, "boot-armed", () => messages.some((message) => message.type === "boot-armed"));
+      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"));
+      const deadline = Date.now() + 20_000;
+      while ((await ssrRuns()).length < 3 && Date.now() < deadline) await wait(100);
+      const [, killed = 0, retried = 0] = await ssrRuns();
+      expect(retried - killed).toBeGreaterThanOrEqual(9_500);
+    } finally {
+      proc.kill();
+      await proc.exited;
+    }
+  }, 60_000);
+
   test("a route build's registry check that has nothing to add reports no ssr status, so it cannot hide a failure", async () => {
     const { root } = track(await createTempApp("demo", path.join(import.meta.dir, "..", "local")));
     const appDir = path.join(root, "apps/demo");

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -165,7 +165,7 @@ class IncrementalBuilder {
       this.#logger.verbose(`build-route ok routeId=${msg.routeId} newEntries=${delta.newEntries.length}`);
       //? The builder's generation, not the route cache's: the cache's does not move when a fixed file maps to no entry,
       //? so the rebuild's ok would carry the failure's own number.
-      this.#sendBuildStatus("route", { generation: this.#generation, ok: true, files: msg.seeds });
+      this.#sendBuildStatus("route", { generation: this.#generation, ok: true, files: msg.seeds, scope: msg.routeId });
       return {
         type: "build-route-res",
         id: msg.id,
@@ -185,24 +185,30 @@ class IncrementalBuilder {
     } catch (err) {
       const errMsg = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
-      this.#sendBuildStatus("route", { generation: this.#generation, ok: false, files: msg.seeds, message: errMsg });
+      this.#sendBuildStatus("route", {
+        generation: this.#generation,
+        ok: false,
+        files: msg.seeds,
+        message: errMsg,
+        scope: msg.routeId,
+      });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
     }
   }
   #sendBuildStatus(
     phase: BuildPhase,
-    { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
+    {
+      generation,
+      ok,
+      files,
+      message,
+      scope,
+    }: { generation?: number; ok: boolean; files?: string[]; message?: string; scope?: string },
   ): void {
     if (typeof generation !== "number") return;
     BuilderChannel.emit({
       type: "build-status",
-      data: {
-        generation,
-        phase,
-        ok,
-        files: files ?? [],
-        message,
-      },
+      data: { generation, phase, ok, files: files ?? [], message, ...(scope !== undefined ? { scope } : {}) },
     });
   }
   async #enqueueFast<T>(label: string, fn: () => Promise<T>): Promise<T> {
@@ -445,11 +451,8 @@ class IncrementalBuilder {
       if (ssrToWorker) needs.unshift("ssr");
       const batch: BatchJob = { generation, needs, changedFiles: files, trace, ...(discovery ? { discovery } : {}) };
       // A worker's registry build rewrites the directory its patcher reads, so the next save waits for it.
-      if (needs.includes("csr") || needs.includes("ssr")) {
-        await this.#workQueue.enqueueBatch(batch);
-        if (needs.includes("csr")) this.#patcher?.forget();
-        if (needs.includes("ssr")) this.#ssrPatcher?.forget();
-      } else void this.#workQueue.enqueueBatch(batch).catch(this.#slowLaneFailed("batch"));
+      if (needs.includes("csr") || needs.includes("ssr")) await this.#workQueue.enqueueBatch(batch);
+      else void this.#workQueue.enqueueBatch(batch).catch(this.#slowLaneFailed("batch"));
       return;
     }
     if (discovery)
@@ -525,6 +528,9 @@ class IncrementalBuilder {
     const hold = await ServerGraphFile.touches(await ServerGraphFile.read(this.#artifactDir), files, (file) =>
       ServerGraphFile.clientExportsOf(file),
     );
+    //? Ahead of this save's own discovery job in the slow lane: which client entries a page still names decides which
+    //? pending roots this patch keeps.
+    this.#discovery.invalidate?.(files);
     return await this.#withSsrLock(
       async () => await this.#runSsrPatcher(patcher, files, { trace, hold, batchGeneration: generation }),
     );
@@ -532,14 +538,16 @@ class IncrementalBuilder {
 
   //* Adds the entries a route build names to the registry, since the tab requires them by id. A registry that cannot
   //* take them fails no route build: the page answers, and its tab waits for the registry while the overlay says why.
-  async #ensureSsrEntries(entries: string[]): Promise<void> {
+  async #ensureSsrEntries(entries: string[], { crashRetry = false }: { crashRetry?: boolean } = {}): Promise<void> {
     if (entries.length === 0) return;
     //? The boot build takes every entry the routes reach, so the first page answers now and its tab waits for the
     //? registry (boot.json) instead; whatever that build missed is added right after it lands.
     const arming = this.#ssrArming;
     if (arming) {
       void this.#runBeside(
-        arming.then(async () => await this.#ensureSsrEntries(entries)).catch(this.#slowLaneFailed("ssr-ensure")),
+        arming
+          .then(async () => await this.#ensureSsrEntries(entries, { crashRetry }))
+          .catch(this.#slowLaneFailed("ssr-ensure")),
       );
       return;
     }
@@ -558,6 +566,8 @@ class IncrementalBuilder {
       //? the SSR lock that save's patch waits on.
       if (this.#ssrBroken) return;
       if (this.#ssrCrashedAt !== null && Date.now() - this.#ssrCrashedAt < IncrementalBuilder.#crashRetryMs) {
+        //? Handed over just now with nothing run for them: the retry must find them to hand over again.
+        patcher?.releaseHandedOver();
         this.#retryAfterCrash(this.#ssrCrashedAt, entries);
         return;
       }
@@ -566,6 +576,9 @@ class IncrementalBuilder {
           `ssr-registry could not take a route's entries; the save that fixes it rebuilds it: ${ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot)}`,
         );
       });
+      //? A worker that died took these entries with it and left them pending nowhere: they are tried once more after the
+      //? crash window, but a retry that crashes again waits for the next route build or save.
+      if (this.#ssrCrashedAt !== null && !crashRetry) this.#retryAfterCrash(this.#ssrCrashedAt, entries);
     });
   }
 
@@ -580,7 +593,9 @@ class IncrementalBuilder {
         const retried = [...this.#crashRetryEntries];
         this.#crashRetryEntries.clear();
         if (this.shuttingDown || retried.length === 0) return;
-        void this.#runBeside(this.#ensureSsrEntries(retried)).catch(this.#slowLaneFailed("ssr-crash-retry"));
+        void this.#runBeside(this.#ensureSsrEntries(retried, { crashRetry: true })).catch(
+          this.#slowLaneFailed("ssr-crash-retry"),
+        );
       },
       Math.max(0, crashedAt + IncrementalBuilder.#crashRetryMs - Date.now()),
     );
@@ -654,8 +669,12 @@ class IncrementalBuilder {
 
   // Runs the worker directly, under the SSR lock its callers hold: queueing it could wait on a batch that waits on them.
   async #runSsrWorker(generation: number): Promise<void> {
-    const result = await this.#runBatch({ generation, needs: ["ssr"], changedFiles: [] });
-    this.#ssrPatcher?.forget();
+    let result: BuildBatchResult;
+    try {
+      result = await this.#runBatch({ generation, needs: ["ssr"], changedFiles: [] });
+    } finally {
+      this.#ssrPatcher?.forget();
+    }
     this.#noteSsrWorker(result);
     if (result.errors.ssr) throw new Error(result.errors.ssr);
   }
@@ -741,9 +760,20 @@ class IncrementalBuilder {
     //? The slow lane runs in order, so every batch up to this one has had its discovery job.
     this.#discoveredThrough = Math.max(this.#discoveredThrough, work.generation);
     // A worker writing ssr-dev must not overlap the boot build, which no longer runs in this lane.
-    if (work.needs.includes("ssr"))
-      await this.#withSsrLock(async () => this.#noteSsrWorker(await this.#runBatch(work)));
-    else await this.#runBatch(work);
+    //? Forgotten inside the lock: a route build's check waiting on it would patch the old state over the worker's.
+    try {
+      if (work.needs.includes("ssr"))
+        await this.#withSsrLock(async () => {
+          try {
+            this.#noteSsrWorker(await this.#runBatch(work));
+          } finally {
+            this.#ssrPatcher?.forget();
+          }
+        });
+      else await this.#runBatch(work);
+    } finally {
+      if (work.needs.includes("csr")) this.#patcher?.forget();
+    }
   }
 
   async #refreshDiscovery({ files, refresh, generation }: DiscoveryJob): Promise<void> {
@@ -762,8 +792,12 @@ class IncrementalBuilder {
     if (result.cssAssets) this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
     // A need the worker died before reporting goes red here instead of looking silently successful.
     if (result.crashed) {
+      const crashedNeeds = result.crashedNeeds ?? needs;
+      //? A worker that died wrote no failure for the roots handed to it: they must not wait on one that never comes.
+      if (crashedNeeds.includes("csr")) this.#patcher?.releaseHandedOver();
+      if (crashedNeeds.includes("ssr")) this.#ssrPatcher?.releaseHandedOver();
       // `base` is not a `BuildPhase` and never comes through here: `#buildBootDeps` throws into the degraded boot.
-      for (const need of result.crashedNeeds ?? needs)
+      for (const need of crashedNeeds)
         if (need !== "base")
           this.#sendBuildStatus(need, {
             generation,

package/integration/devStability.integration.test.ts

@@ -589,6 +589,7 @@ describe("dev resource budgets", () => {
     // A ceiling the replacement is back over within the interval is reported, and still enforced (recycles are
     // throttled), never disabled for the session. Whether it is back over depends on the machine's allocator, so the
     // warning is asserted only when it is; the decision itself is unit-tested (devHostPolicy).
+    const settledFrom = host.markLog();
     for (let i = 1; i <= 3; i++) {
       const { mark } = await harness.editUntilSeen(host, (attempt) =>
         harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-settled-${i}-${attempt}`),
@@ -596,8 +597,14 @@ describe("dev resource budgets", () => {
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
     const settled = await DevStabilityHarness.builderProcess(host.proc.pid);
-    if ((settled?.rssBytes ?? 0) >= 200 * MB)
-      await host.waitForLogSince(start, /ceiling costs about one boot build per interval/, WAIT_MS);
+    const warned = /ceiling costs about one boot build per interval/.test(host.logs.join("").slice(start));
+    //? Past the interval (a slow machine) the next report recycles instead of warning: either answer settles it.
+    if ((settled?.rssBytes ?? 0) >= 200 * MB && !warned)
+      await host.waitForLogSince(
+        settledFrom,
+        /ceiling costs about one boot build per interval|recycling builder pid=\d+|skipped: the builder fell to/,
+        WAIT_MS,
+      );
     expect(host.logs.join("").slice(start)).not.toMatch(/no longer enforcing it this session/);
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.25",
+  "version": "3.0.0-beta.26",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.0-beta.25",
+    "akanjs": "3.0.0-beta.26",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",