@akanjs/cli 2.4.1-rc.2 → 2.4.1-rc.4

package/incrementalBuilder.proc.js

@@ -5,41 +5,129 @@ import {
 import {
   AppExecutor,
   WorkspaceExecutor
-} from "./index-a6sbyy0b.js";
+} from "./index-0t7pwff2.js";
+import"./index-61keag0s.js";
 import {
   AutoImportSync,
-  CsrArtifactBuilder,
   DevChangePlanner,
   DevGeneratedIndexSync,
-  FontOptimizer,
   GraphClientEntryDiscovery,
-  HmrWatcher,
-  PagesBundleBuilder,
   RouteClientBuilder,
-  SsrBaseArtifactBuilder,
+  SsrBaseArtifactBuilder
+} from "./index-khzzttv1.js";
+import {
+  HmrWatcher,
   WatchRootResolver
-} from "./index-a5rmdgy4.js";
-import"./index-61keag0s.js";
+} from "./index-0fn1r7gg.js";
 import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
+import path2 from "path";
+import { Logger as Logger2 } from "akanjs/common";
+
+// pkgs/@akanjs/devkit/incrementalBuilder/buildBatchRunner.ts
 import path from "path";
 import { Logger } from "akanjs/common";
+
+class BuildBatchRunner {
+  static #entryCandidates = (workspaceRoot) => [
+    path.join(workspaceRoot, "pkgs/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(workspaceRoot, "node_modules/@akanjs/devkit/incrementalBuilder/buildBatch.proc.ts"),
+    path.join(import.meta.dir, "buildBatch.proc.js"),
+    path.join(import.meta.dir, "buildBatch.proc.ts")
+  ];
+  #logger = new Logger("BuildBatchRunner");
+  #entry = null;
+  #workspaceRoot;
+  #cwd;
+  constructor({ workspaceRoot, cwd }) {
+    this.#workspaceRoot = workspaceRoot;
+    this.#cwd = cwd;
+  }
+  async#resolveEntry() {
+    if (this.#entry)
+      return this.#entry;
+    const candidates = BuildBatchRunner.#entryCandidates(this.#workspaceRoot);
+    for (const candidate of candidates) {
+      if (!await Bun.file(candidate).exists())
+        continue;
+      this.#entry = candidate;
+      return candidate;
+    }
+    throw new Error(`[build-batch] worker entry not found; looked in: ${candidates.join(", ")}`);
+  }
+  async run(request, onMessage = () => {
+    return;
+  }) {
+    const started = Date.now();
+    const entry = await this.#resolveEntry();
+    let result = null;
+    const proc = Bun.spawn(["bun", entry, JSON.stringify(request)], {
+      cwd: this.#cwd,
+      env: process.env,
+      stdio: ["ignore", "inherit", "inherit"],
+      serialization: "advanced",
+      ipc: (message2) => {
+        if (!message2 || typeof message2 !== "object")
+          return;
+        if (message2.type === "build-batch-result")
+          result = message2.data;
+        else
+          onMessage(message2);
+      }
+    });
+    const exitCode = await proc.exited;
+    if (result) {
+      this.#logger.verbose(`[build-batch] generation=${request.generation} needs=${request.needs.join(",")} done in ${Date.now() - started}ms`);
+      return result;
+    }
+    const message = `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
+    };
+  }
+}
+
+// pkgs/@akanjs/devkit/incrementalBuilder/builderReply.ts
+class BuilderReply {
+  static #flushTimeoutMs = 5000;
+  static async send(res) {
+    const send = process.send;
+    if (!send)
+      return;
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, BuilderReply.#flushTimeoutMs);
+      send.call(process, res, undefined, undefined, () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+}
+
+// pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
 class IncrementalBuilder {
-  #logger = new Logger("IncrementalBuilder");
+  #logger = new Logger2("IncrementalBuilder");
   #app;
   #artifact;
   #watch;
-  #cssCompiler;
   #optimizedFonts;
   #discovery;
+  #batchRunner;
   #changePlanner;
   #generatedIndexSync;
   #autoImportSync;
+  #watcher = null;
   #generation = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #workQueue = Promise.resolve();
+  #inFlight = 0;
+  #workCount = 0;
+  #shuttingDown = false;
   #cssRebuildQueue = Promise.resolve();
   #cssRebuildTimer = null;
   #pendingCssRebuild = null;
@@ -47,10 +135,13 @@ class IncrementalBuilder {
     this.#app = options.app;
     this.#artifact = options.artifact;
     this.#watch = options.watch;
-    this.#cssCompiler = options.cssCompiler;
     this.#optimizedFonts = options.optimizedFonts;
     this.#discovery = options.discovery;
     this.#generation = options.initialGeneration ?? 0;
+    this.#batchRunner = new BuildBatchRunner({
+      workspaceRoot: options.app.workspace.workspaceRoot,
+      cwd: options.app.cwdPath
+    });
     this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
     this.#autoImportSync = new AutoImportSync({ workspaceRoot: options.app.workspace.workspaceRoot });
@@ -59,7 +150,7 @@ class IncrementalBuilder {
     return `${this.#app.cwdPath}/.akan/artifact`;
   }
   async handleBuildRoute(msg) {
-    return this.#enqueueWork(`build-route:${msg.routeId}`, async () => this.#handleBuildRoute(msg));
+    await this.#enqueueWork(`build-route:${msg.routeId}`, async () => BuilderReply.send(await this.#handleBuildRoute(msg)));
   }
   async#handleBuildRoute(msg) {
     try {
@@ -111,6 +202,7 @@ class IncrementalBuilder {
   }
   async#enqueueWork(label, fn) {
     const started = Date.now();
+    this.#inFlight += 1;
     const run = this.#workQueue.then(fn, fn);
     this.#workQueue = run.then(() => {
       return;
@@ -120,14 +212,51 @@ class IncrementalBuilder {
     try {
       return await run;
     } finally {
+      this.#inFlight -= 1;
+      this.#workCount += 1;
       this.#logger.verbose(`[work-queue] ${label} finished in ${Date.now() - started}ms`);
+      this.#reportMetrics();
     }
   }
+  get #idle() {
+    return this.#inFlight === 0 && this.#cssRebuildTimer === null;
+  }
+  #reportMetrics() {
+    if (!this.#idle || this.#shuttingDown)
+      return;
+    process.send?.({
+      type: "builder-metrics",
+      data: { rssBytes: process.memoryUsage.rss(), generation: this.#generation, workCount: this.#workCount }
+    });
+  }
+  async shutdown(reason) {
+    if (this.#shuttingDown)
+      return;
+    this.#shuttingDown = true;
+    const started = Date.now();
+    this.#logger.info(`shutdown requested (${reason}); draining ${this.#inFlight} work item(s)`);
+    if (this.#cssRebuildTimer) {
+      clearTimeout(this.#cssRebuildTimer);
+      this.#cssRebuildTimer = null;
+      this.#pendingCssRebuild = null;
+    }
+    await this.#workQueue.catch(() => {
+      return;
+    });
+    await this.#cssRebuildQueue.catch(() => {
+      return;
+    });
+    this.#logger.info(`drained in ${Date.now() - started}ms; exiting for recycle`);
+    process.exit(0);
+  }
+  get shuttingDown() {
+    return this.#shuttingDown;
+  }
   batchTouchesPagesTree(appDir, batch) {
-    const absAppDir = path.resolve(appDir);
+    const absAppDir = path2.resolve(appDir);
     for (const f of batch.files) {
-      const abs = path.resolve(f);
-      if (!abs.startsWith(`${absAppDir}${path.sep}`) && abs !== absAppDir)
+      const abs = path2.resolve(f);
+      if (!abs.startsWith(`${absAppDir}${path2.sep}`) && abs !== absAppDir)
         continue;
       if (/\.(tsx|ts|jsx|js)$/.test(abs))
         return true;
@@ -135,67 +264,22 @@ class IncrementalBuilder {
     return false;
   }
   async batchMayChangePageKeys(appDir, batch) {
-    const absAppDir = path.resolve(appDir);
-    const pageKeys = new Set((await this.#app.getPageKeys()).map((key) => path.normalize(key)));
+    const absAppDir = path2.resolve(appDir);
+    const pageKeys = new Set((await this.#app.getPageKeys()).map((key) => path2.normalize(key)));
     for (const f of batch.files) {
-      const abs = path.resolve(f);
-      if (!abs.startsWith(`${absAppDir}${path.sep}`) && abs !== absAppDir)
+      const abs = path2.resolve(f);
+      if (!abs.startsWith(`${absAppDir}${path2.sep}`) && abs !== absAppDir)
         continue;
       if (!/\.(tsx|ts|jsx|js)$/.test(abs))
         continue;
-      const rel = path.normalize(path.relative(absAppDir, abs));
+      const rel = path2.normalize(path2.relative(absAppDir, abs));
       if (!await Bun.file(abs).exists() || !pageKeys.has(rel))
         return true;
     }
     return false;
   }
-  async rebuildCssArtifact(artifactDir, { refresh, generation, changedFiles }) {
-    const cssStarted = Date.now();
-    const cssByBasePathStarted = Date.now();
-    const cssByBasePath = await this.#cssCompiler.getCssByBasePath({ refresh });
-    this.#logger.verbose(`css-get-by-base-path ok (${Date.now() - cssByBasePathStarted}ms)`);
-    const fontStarted = Date.now();
-    const optimizedFonts = await this.#getOptimizedFonts(changedFiles ?? []);
-    this.#logger.verbose(`font-assets ready (${Date.now() - fontStarted}ms)`);
-    const cssAssetEntries = [];
-    const cssBase64ByUrl = {};
-    await Promise.all(Object.entries(cssByBasePath).flatMap(([basePath, baseCssText]) => {
-      const cssText = [baseCssText, optimizedFonts.css].filter(Boolean).join(`
-`);
-      if (!cssText)
-        return [];
-      return [
-        (async () => {
-          const cssAssetName = basePath || "root";
-          const cssHash = Bun.hash(`${basePath}
-${cssText}`).toString(36);
-          const cssRelPath = `styles/${cssAssetName}-${cssHash}.css`;
-          const cssUrl = `/_akan/styles/${cssAssetName}-${cssHash}.css`;
-          await Bun.write(path.join(artifactDir, cssRelPath), cssText);
-          cssAssetEntries.push([basePath, { cssUrl, cssRelPath }]);
-          cssBase64ByUrl[cssUrl] = Buffer.from(new TextEncoder().encode(cssText)).toString("base64");
-        })()
-      ];
-    }));
-    const cssAssets = Object.fromEntries(cssAssetEntries);
-    if (JSON.stringify(this.#artifact.cssAssets ?? {}) === JSON.stringify(cssAssets)) {
-      this.#logger.verbose("css-rebuild unchanged assets; broadcast skipped");
-      return;
-    }
-    this.#artifact = { ...this.#artifact, cssAssets };
-    this.#logger.verbose(`css-compile ok assets=${Object.keys(cssAssets).length} (${Date.now() - cssStarted}ms)`);
-    process.send?.({
-      type: "css-updated",
-      data: {
-        cssAssets,
-        cssBase64ByUrl,
-        generation,
-        changedFiles
-      }
-    });
-  }
-  scheduleCssRebuild(artifactDir, { refresh, generation, changedFiles }) {
-    this.#pendingCssRebuild = { artifactDir, refresh, generation, changedFiles };
+  scheduleCssRebuild({ generation, changedFiles }) {
+    this.#pendingCssRebuild = { generation, changedFiles };
     if (this.#cssRebuildTimer)
       clearTimeout(this.#cssRebuildTimer);
     this.#cssRebuildTimer = setTimeout(() => {
@@ -204,15 +288,13 @@ ${cssText}`).toString(36);
       this.#pendingCssRebuild = null;
       if (!next)
         return;
+      this.#inFlight += 1;
       this.#cssRebuildQueue = this.#cssRebuildQueue.then(async () => {
-        const started = Date.now();
-        await this.rebuildCssArtifact(next.artifactDir, {
-          refresh: next.refresh,
-          generation: next.generation,
-          changedFiles: next.changedFiles
+        await this.#runBatch({
+          generation: next.generation ?? this.#generation,
+          needs: ["css"],
+          changedFiles: next.changedFiles ?? []
         });
-        this.#sendBuildStatus("css", { generation: next.generation, ok: true, files: next.changedFiles });
-        this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
       }).catch((err) => {
         const message = err instanceof Error ? err.message : String(err);
         this.#logger.error(`css-rebuild failed: ${message}`);
@@ -222,29 +304,12 @@ ${cssText}`).toString(36);
           files: next.changedFiles,
           message
         });
+      }).finally(() => {
+        this.#inFlight -= 1;
+        this.#reportMetrics();
       });
     }, 150);
   }
-  async#getOptimizedFonts(changedFiles) {
-    if (!this.#shouldReoptimizeFonts(changedFiles)) {
-      this.#logger.verbose(`font-optimize cached files=${this.#optimizedFonts.files.length}`);
-      return this.#optimizedFonts;
-    }
-    const started = Date.now();
-    this.#optimizedFonts = await new FontOptimizer(this.#app, "start").optimize();
-    this.#logger.verbose(`font-optimize ok files=${this.#optimizedFonts.files.length} (${Date.now() - started}ms)`);
-    return this.#optimizedFonts;
-  }
-  #shouldReoptimizeFonts(changedFiles) {
-    if (changedFiles.length === 0)
-      return false;
-    return changedFiles.some((file) => {
-      const normalized = path.resolve(file);
-      if (/\.(woff2?|ttf|otf)$/i.test(normalized))
-        return true;
-      return this.#optimizedFonts.files.some((fontFile) => path.resolve(fontFile) === normalized);
-    });
-  }
   async installWatcher() {
     const [appDir, artifactDir] = [`${this.#app.cwdPath}/page`, this.#artifactDir];
     const roots = await new WatchRootResolver(this.#app).resolve();
@@ -255,7 +320,8 @@ ${cssText}`).toString(36);
         await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(appDir, artifactDir, batch));
       }
     });
-    watcher.start();
+    await watcher.start();
+    this.#watcher = watcher;
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
   async#handleWatchBatch(appDir, artifactDir, batch) {
@@ -269,6 +335,7 @@ ${cssText}`).toString(36);
     if (autoImport.changedFiles.length > 0)
       this.#logger.verbose(`[auto-import] inserted imports into ${autoImport.changedFiles.length} file(s)`);
     const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
+    await this.#watcher?.absorb([...autoImport.changedFiles, ...indexSync.changedFiles]);
     const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
       batch,
@@ -306,42 +373,60 @@ ${cssText}`).toString(36);
     } else if (kinds.includes("code") && rebuildClient && this.batchTouchesPagesTree(appDir, expandedBatch)) {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
-    if (kinds.includes("code") && rebuildClient && this.#shouldRebuildCsr()) {
-      try {
-        const started = Date.now();
-        await new CsrArtifactBuilder(this.#app).build();
-        this.#sendBuildStatus("csr", { generation, ok: true, files });
-        this.#logger.verbose(`csr-rebundle ok (${Date.now() - started}ms)`);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`csr-rebundle failed: ${message}`);
-        this.#sendBuildStatus("csr", { generation, ok: false, files, message });
-      }
-    } else if (kinds.includes("code") && rebuildClient) {
-      this.#logger.verbose(`csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`);
-    }
-    process.send?.(event);
+    const needs = [];
     if (kinds.includes("code") && rebuildClient) {
-      try {
-        const started = Date.now();
-        const next = await new PagesBundleBuilder(this.#app).build();
-        process.send?.({
-          type: "pages-updated",
-          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles: files }
-        });
-        this.#sendBuildStatus("pages", { generation, ok: true, files });
-        this.#logger.verbose(`pages-rebundle ok buildId=${next.buildId} (${Date.now() - started}ms)`);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`pages-rebundle failed: ${message}`);
-        this.#sendBuildStatus("pages", { generation, ok: false, files, message });
-      }
+      if (this.#shouldRebuildCsr())
+        needs.push("csr");
+      else
+        this.#logger.verbose(`csr-rebundle skipped; request /__csr or ?csr=true (or set AKAN_DEV_CSR_REBUILD=1) to enable per-save CSR rebuilds`);
+      needs.push("pages");
+      needs.push("css");
     }
-    if (kinds.includes("css") || kinds.includes("code") && rebuildClient) {
-      this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: files });
+    process.send?.(event);
+    if (needs.length > 0)
+      await this.#runBatch({ generation, needs, changedFiles: files });
+    else if (kinds.includes("css")) {
+      this.scheduleCssRebuild({ generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }
+  async#runBatch({
+    generation,
+    needs,
+    changedFiles
+  }) {
+    const started = Date.now();
+    const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) => process.send?.(msg));
+    if (result.optimizedFonts)
+      this.#optimizedFonts = result.optimizedFonts;
+    if (result.cssAssets)
+      this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
+    if (result.crashed) {
+      for (const need of needs)
+        this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
+    }
+    if (needs.includes("css"))
+      this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
+    return result;
+  }
+  async#batchRequest({
+    generation,
+    needs,
+    changedFiles
+  }) {
+    return {
+      appName: this.#app.name,
+      workspaceRoot: this.#app.workspace.workspaceRoot,
+      repoName: this.#app.workspace.repoName,
+      generation,
+      needs,
+      changedFiles,
+      pageKeys: await this.#app.getPageKeys(),
+      optimizedFonts: this.#optimizedFonts,
+      cssAssets: this.#artifact.cssAssets ?? null,
+      artifactDir: path2.resolve(this.#artifactDir)
+    };
+  }
   async boot() {
     if (this.#watch)
       await this.installWatcher();
@@ -351,34 +436,46 @@ ${cssText}`).toString(36);
   async announceRecoveredState(changedFiles) {
     const generation = ++this.#generation;
     await this.#enqueueWork("boot-recovered", async () => {
-      try {
-        const next = await new PagesBundleBuilder(this.#app).build();
-        process.send?.({
-          type: "pages-updated",
-          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles }
-        });
-        this.#sendBuildStatus("pages", { generation, ok: true, files: changedFiles, message: "Boot build recovered" });
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`recovered pages rebundle failed: ${message}`);
-        this.#sendBuildStatus("pages", { generation, ok: false, files: changedFiles, message });
+      await this.#runBatch({ generation, needs: ["pages", "css"], changedFiles });
+    });
+  }
+  async announceBootState() {
+    const generation = ++this.#generation;
+    const reason = "builder-recycle";
+    process.send?.({
+      type: "pages-updated",
+      data: {
+        bundlePath: this.#artifact.pagesBundlePath,
+        buildId: this.#artifact.pagesBundleBuildId,
+        generation,
+        changedFiles: [],
+        reason
       }
-      this.scheduleCssRebuild(this.#artifactDir, { refresh: true, generation, changedFiles });
     });
+    const cssAssets = this.#artifact.cssAssets ?? {};
+    const cssBase64ByUrl = Object.fromEntries(await Promise.all(Object.values(cssAssets).map(async ({ cssUrl, cssRelPath }) => [
+      cssUrl,
+      Buffer.from(await Bun.file(path2.join(this.#artifactDir, cssRelPath)).arrayBuffer()).toString("base64")
+    ])));
+    process.send?.({
+      type: "css-updated",
+      data: { cssAssets, cssBase64ByUrl, generation, changedFiles: [], reason }
+    });
+    this.#logger.verbose(`announced boot state after recycle generation=${generation}`);
   }
   async handleBuildCsr(msg) {
-    return this.#enqueueWork("build-csr", async () => {
+    await this.#enqueueWork("build-csr", async () => {
       const started = Date.now();
-      try {
-        await new CsrArtifactBuilder(this.#app).build();
-        this.#csrActive = true;
-        this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
-        return { type: "build-csr-res", id: msg.id, ok: true };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        this.#logger.error(`csr-build failed: ${message}`);
-        return { type: "build-csr-res", id: msg.id, ok: false, error: message };
+      const result = await this.#batchRunner.run(await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }));
+      const error = result.errors.csr;
+      if (error) {
+        this.#logger.error(`csr-build failed: ${error}`);
+        await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: false, error });
+        return;
       }
+      this.#csrActive = true;
+      this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
+      await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
   #shouldRebuildCsr() {
@@ -388,11 +485,21 @@ ${cssText}`).toString(36);
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
   static async#buildBootDeps(app) {
-    const { artifact, cssCompiler, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
-    if (IncrementalBuilder.#csrArmedByEnv())
-      await new CsrArtifactBuilder(app).build();
+    const { artifact, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
     const discovery = await GraphClientEntryDiscovery.create(app);
-    return { artifact, cssCompiler, optimizedFonts, discovery };
+    return { artifact, optimizedFonts, discovery };
+  }
+  async rearmCsrFromEnv() {
+    if (!IncrementalBuilder.#csrArmedByEnv())
+      return;
+    this.#csrActive = true;
+    await this.#enqueueWork("build-csr-rearm", async () => {
+      const result = await this.#batchRunner.run(await this.#batchRequest({ generation: this.#generation, needs: ["csr"], changedFiles: [] }));
+      if (result.errors.csr)
+        this.#logger.error(`csr-rearm failed: ${result.errors.csr}`);
+      else
+        this.#logger.verbose("csr-rearm ok; this session had CSR armed before the builder restarted");
+    });
   }
   static #recoverBoot(app, bootError, logger) {
     const firstMessage = bootError instanceof Error ? bootError.message : String(bootError);
@@ -430,13 +537,13 @@ ${cssText}`).toString(36);
             }
           }
         });
-        watcher.start();
+        await watcher.start();
         logger.warn(`[degraded] watching ${roots.length} roots for a fix`);
       })().catch(reject);
     });
   }
   static async main() {
-    const logger = new Logger("IncrementalBuilder");
+    const logger = new Logger2("IncrementalBuilder");
     const { appName, repoName, workspaceRoot } = WorkspaceExecutor.getBaseDevEnv();
     if (!workspaceRoot || !appName)
       throw new Error("AKAN_WORKSPACE_ROOT or AKAN_PUBLIC_APP_NAME is not set");
@@ -445,23 +552,34 @@ ${cssText}`).toString(36);
     const watch = process.env.AKAN_WATCH !== "0";
     let builder = null;
     const bootingError = "builder is recovering from a failed boot build; retry after the build error is fixed";
+    const recyclingError = "builder is recycling to release bundler memory; retry after it restarts";
     process.on("message", (msg) => {
       if (!msg || typeof msg !== "object")
         return;
-      if (msg.type === "build-route") {
+      if (msg.type === "builder-shutdown") {
         if (!builder) {
-          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error: bootingError });
+          logger.warn(`ignoring shutdown request (${msg.reason}); builder is still recovering from a failed boot`);
           return;
         }
-        builder.handleBuildRoute(msg).then((res) => process.send?.(res));
+        builder.shutdown(msg.reason);
+        return;
+      }
+      if (msg.type === "build-route") {
+        const error = builder?.shuttingDown ? recyclingError : bootingError;
+        if (!builder || builder.shuttingDown) {
+          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error });
+          return;
+        }
+        builder.handleBuildRoute(msg);
         return;
       }
       if (msg.type === "build-csr") {
-        if (!builder) {
-          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error: bootingError });
+        const error = builder?.shuttingDown ? recyclingError : bootingError;
+        if (!builder || builder.shuttingDown) {
+          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error });
           return;
         }
-        builder.handleBuildCsr(msg).then((res) => process.send?.(res));
+        builder.handleBuildCsr(msg);
       }
     });
     process.on("disconnect", () => {
@@ -481,6 +599,9 @@ ${cssText}`).toString(36);
     await builder.boot();
     if (recoveredFiles)
       await builder.announceRecoveredState(recoveredFiles);
+    else if (process.env.AKAN_BUILDER_ANNOUNCE_BOOT === "1")
+      await builder.announceBootState();
+    await builder.rearmCsrFromEnv();
   }
 }
 IncrementalBuilder.main().catch((err) => {