@akanjs/devkit 2.4.1-rc.1 → 2.4.1-rc.3

package/integration/devStability.integration.test.ts

@@ -149,7 +149,6 @@ describe("dev stability integration harness", () => {
       return;
     }
     const mark = host.markLog();
-    const hmrMark = hmr?.mark() ?? 0;
 
     await harness.replaceText("common/marker.ts", "initial-shared-marker", "updated-shared-marker");
 
@@ -159,13 +158,13 @@ describe("dev stability integration harness", () => {
     );
     const generation = plan[1];
     await host.waitForLogSince(mark, new RegExp(`\\[backend-reload\\].*generation=${generation}`));
-    if (hmr)
-      await hmr.waitForMessageSince(
-        hmrMark,
-        (msg) =>
-          typeof msg === "object" && msg !== null && "generation" in msg && String(msg.generation) === generation,
-      );
-    else await host.waitForLogSince(mark, new RegExp(`\\[SSR\\] pages-updated.*generation=${generation}`));
+    // Asserted backend-side, not through the probe. A shared edit restarts the backend, which closes
+    // the socket the probe opened, and the probe is a raw WebSocket that never reconnects. A real
+    // browser does: on reconnect it gets a `hello` and reloads when the buildId moved
+    // (`akanjs/server/hmr/clientScript.ts`). Requiring a probe message here only held while the client
+    // rebuild happened to finish before the restart killed the connection — a race this test lost the
+    // moment builds moved into a worker process and took ~240ms longer to start.
+    await host.waitForLogSince(mark, new RegExp(`\\[SSR\\] pages-updated.*generation=${generation}`));
     await harness.waitForHttpText("updated-shared-marker");
     hmr?.close();
   });
@@ -469,6 +468,9 @@ describe("dev resource budgets", () => {
 
     const idleTotal = await DevStabilityHarness.processTreeRssBytes(host.proc.pid);
     const idleWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, { excludeBuilder: true });
+    const idleBuilder = await DevStabilityHarness.builderProcess(host.proc.pid);
+    // Nothing should be building at idle, so the disposable worker must not be resident.
+    expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
     // Measured ~670MB for this fixture; the headroom covers machine variance, not a reintroduced
     // eager import (the cheapest of those is ~30MB, and the devkit barrel cycle was 236MB).
     expect(idleTotal).toBeLessThan(1_000 * MB);
@@ -482,23 +484,104 @@ describe("dev resource budgets", () => {
       const afterSave = host.logs.join("").slice(mark);
       expect(afterSave).toMatch(/csr-rebundle skipped/);
       expect(afterSave).not.toMatch(/csr-rebundle ok/);
-      // The debounced CSS rebuild is still writing after `pages-rebundle ok`, and Bun drops a watcher
-      // event that lands in the same window as a write burst (`06-watcher-dropped-event.md`). Saving
-      // again before this save's last artifact write lands loses the next edit outright, which showed
-      // up as this test hanging for the full 90s wait on iteration 2.
+      // Bun drops a watcher event that lands in the same window as a write burst
+      // (`06-watcher-dropped-event.md`), so saving again before this generation has fully settled loses
+      // the next edit outright — this test hanging for the full 90s wait on iteration 2. Waiting for
+      // the builder alone is not enough: the backend is still applying the reload after that, and it
+      // writes too. Wait for the backend to finish, then leave the drop window (measured under 200ms).
       await host.waitForLogSince(mark, /css-rebuild checked/, WAIT_MS);
+      await host.waitForLogSince(mark, /\[hmr\] backend apply/, WAIT_MS);
+      await Bun.sleep(300);
     }
 
     // Each in-place reload re-imports the pages bundle under a fresh `?v=`, and Bun's ESM registry
     // never evicts — so without a recycle the worker grows for the life of the process.
     await host.waitForLogSince(start, /rolling recycle worker reason=pages-reload-accumulation/, WAIT_MS);
 
-    // The dev host, gateway, replica and rsc worker must all stay flat across saves. The builder is
-    // still expected to grow — `Bun.build` retains native arenas that no GC reclaims, which the
-    // bounded-builder work addresses — so it is excluded here rather than silently tolerated.
+    // The dev host, gateway, replica and rsc worker must all stay flat across saves.
     const afterWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, {
       excludeBuilder: true,
     });
     expect(afterWithoutBuilder - idleWithoutBuilder).toBeLessThan(120 * MB);
+
+    // And so must the builder. It used to be excluded from this budget because `Bun.build` retains
+    // native arenas no GC reclaims, which made it grow ~120MB per save on this fixture; every build
+    // that scales per save now runs in a process that exits, so its memory goes back to the OS.
+    const afterBuilder = await DevStabilityHarness.builderProcess(host.proc.pid);
+    expect(afterBuilder?.pid).toBe(idleBuilder?.pid);
+    expect((afterBuilder?.rssBytes ?? 0) - (idleBuilder?.rssBytes ?? 0)).toBeLessThan(30 * MB);
+    // The worker is transient: three generations built, and none of them is still around.
+    expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
+  });
+
+  budgetTest("recycles the builder at an unmeetable ceiling and keeps developing through it", async () => {
+    const harness = await createHarness();
+    // Deliberately *below* this fixture's post-boot builder. Moving every per-save build into a
+    // disposable worker means the builder no longer grows into a ceiling, so a ceiling it is already
+    // over is the only way left to drive the recycle path end to end — and it is also the case the
+    // escape hatch exists for: an app whose boot floor simply does not fit under the limit.
+    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
+    const start = host.markLog();
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+
+    // One save is enough: the builder reports its rss as soon as the batch drains, and the host arms
+    // the recycle from that report. The old pid comes from the log rather than from `ps`, so this does
+    // not race the swap it is about to observe.
+    const firstSave = host.markLog();
+    await harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, "marker-1");
+    await host.waitForLogSince(firstSave, /pages-rebundle ok/, WAIT_MS);
+
+    // The host decides, the builder drains rather than being killed, and the replacement comes up.
+    const recycleLog = await host.waitForLogSince(
+      start,
+      /recycling builder pid=(\d+) \((rss=\d+MiB>=200MiB after \d+ build\(s\))\)/,
+      WAIT_MS,
+    );
+    await host.waitForLogSince(start, /exiting for recycle/, WAIT_MS);
+    await host.waitForLogSince(start, /builder spawned pid=\d+ .*restart=1/, WAIT_MS);
+    await host.waitForLogSince(start, /builder ready after restart/, WAIT_MS);
+    // The backend read `base-artifact.json` once at boot, so the replacement has to re-announce what
+    // it booted with or the backend keeps serving the artifact of the builder that just exited.
+    await host.waitForLogSince(start, /announced boot state after recycle/, WAIT_MS);
+
+    const recycled = await DevStabilityHarness.builderProcess(host.proc.pid);
+    expect(recycled).not.toBeNull();
+    expect(String(recycled?.pid)).not.toBe(recycleLog[1]);
+
+    // And the dev server is still a dev server: the replacement watches, rebuilds and serves.
+    //
+    // Waiting for readiness above is load-bearing, not padding. The watcher is installed at the end of
+    // the boot build, so a save during the recycle is seen by neither builder — this test lost one
+    // exactly that way. The settle wait on top is for Bun's dropped-event bug: the recycle boot writes
+    // a burst of artifacts, and a save inside that window is never reported at all
+    // (`06-watcher-dropped-event.md`).
+    await Bun.sleep(500);
+    const attempts: string[] = [];
+    for (let attempt = 1; attempt <= 4; attempt++) {
+      const mark = host.markLog();
+      await harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-after-recycle-${attempt}`);
+      const seen = await host
+        .waitForLogSince(mark, /pages-rebundle ok/, 15_000)
+        .then(() => true)
+        .catch(() => false);
+      attempts.push(`${attempt}=${seen ? "rebuilt" : "silent"}`);
+      if (seen) break;
+      await Bun.sleep(750);
+    }
+    console.info(
+      `[recycle-guard] ${recycleLog[2]}; builder ${recycleLog[1]} -> ${recycled?.pid} at ${Math.round((recycled?.rssBytes ?? 0) / MB)}MiB; post-recycle saves: ${attempts.join(" ")}`,
+    );
+    expect(attempts.join(" ")).toMatch(/rebuilt/);
+    await harness.waitForHttpText("marker-after-recycle", WAIT_MS);
+
+    // A replacement that is still over the ceiling proves the ceiling cannot be met, and the host has
+    // to stop rather than recycle forever. Two reports inside the minimum interval is the threshold.
+    for (let i = 1; i <= 3; i++) {
+      await Bun.sleep(500);
+      const mark = host.markLog();
+      await harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-settled-${i}`);
+      await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
+    }
+    await host.waitForLogSince(start, /ceiling cannot be met for this app/, WAIT_MS);
   });
 });

package/integration/devStabilityHarness.ts

@@ -281,7 +281,7 @@ export const dictionary = serviceDictionary(["en", "ko"])
       const decoder = new TextDecoder();
       const reader = stream.getReader();
       try {
-        while (true) {
+        for (;;) {
           const { done, value } = await reader.read();
           if (done) break;
           logs.push(decoder.decode(value, { stream: true }));
@@ -460,6 +460,12 @@ export const dictionary = serviceDictionary(["en", "ko"])
    * process, whose growth across saves is `Bun.build` native arena retention rather than a leak the
    * other processes could be blamed for.
    */
+  // Matched precisely, not by directory: the disposable build worker lives at
+  // `incrementalBuilder/buildBatch.proc.ts`, so a substring match on `incrementalBuilder` would count
+  // the worker as the watcher and make every builder measurement depend on spawn timing.
+  static readonly #builderCmd = "incrementalBuilder.proc";
+  static readonly #buildWorkerCmd = "buildBatch.proc";
+
   static async processTreeRssBytes(
     rootPid: number,
     { excludeBuilder = false }: { excludeBuilder?: boolean } = {},
@@ -471,11 +477,31 @@ export const dictionary = serviceDictionary(["en", "ko"])
         .filter((row) => pids.has(row.pid))
         // `bun run akan …` is the npm-script shell wrapper, not a dev process.
         .filter((row) => !row.cmd.startsWith("bash -lc") && !row.cmd.includes("cli/build.ts"))
-        .filter((row) => !excludeBuilder || !row.cmd.includes("incrementalBuilder"))
+        .filter((row) => !excludeBuilder || !row.cmd.includes(DevStabilityHarness.#builderCmd))
         .reduce((total, row) => total + row.rssKb * 1024, 0)
     );
   }
 
+  /**
+   * The long-lived builder process on its own: its RSS is what bundler-arena retention used to move,
+   * and its pid is what changes when the host recycles it, so a bounded-builder assertion needs both.
+   */
+  static async builderProcess(rootPid: number): Promise<{ pid: number; rssBytes: number } | null> {
+    return DevStabilityHarness.#findProcess(rootPid, DevStabilityHarness.#builderCmd);
+  }
+
+  /** The disposable per-generation build worker, which should only exist while a build is running. */
+  static async buildWorkerProcess(rootPid: number): Promise<{ pid: number; rssBytes: number } | null> {
+    return DevStabilityHarness.#findProcess(rootPid, DevStabilityHarness.#buildWorkerCmd);
+  }
+
+  static async #findProcess(rootPid: number, cmdIncludes: string) {
+    const rows = await DevStabilityHarness.#psRows();
+    const pids = DevStabilityHarness.#collectDescendants(rows, rootPid);
+    const found = rows.find((row) => pids.has(row.pid) && row.cmd.includes(cmdIncludes));
+    return found ? { pid: found.pid, rssBytes: found.rssKb * 1024 } : null;
+  }
+
   /** Pids of `rootPid` and everything under it, deepest first, so callers can signal children before parents. */
   static async descendantPids(rootPid: number | undefined): Promise<number[]> {
     if (!rootPid) return [];

package/local/optimize-resource/ipcprobe/child.ts

@@ -0,0 +1 @@
+process.send?.({ type: "done", value: 42 });

package/local/optimize-resource/ipcprobe/parent.ts

@@ -0,0 +1,11 @@
+const started = Date.now();
+let got: unknown = null;
+const proc = Bun.spawn(["bun", `${import.meta.dir}/child.ts`], {
+  stdio: ["ignore", "inherit", "inherit"],
+  serialization: "advanced",
+  ipc: (m) => { got = m; },
+});
+const timeout = new Promise((r) => setTimeout(() => r("TIMEOUT"), 4000));
+const outcome = await Promise.race([proc.exited, timeout]);
+console.info(JSON.stringify({ outcome, got, ms: Date.now() - started }));
+if (outcome === "TIMEOUT") proc.kill();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.1-rc.1",
+  "version": "2.4.1-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.1-rc.1",
+    "akanjs": "2.4.1-rc.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/packageExports.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { PackageExportsMap } from "@akanjs/devkit/packageExportsMap";
+
+// Guards the published shape of this package, which the monorepo cannot exercise on its own.
+//
+// Inside the monorepo Bun resolves `@akanjs/devkit/executors` through the root tsconfig `paths`
+// (`@akanjs/devkit/*` -> `pkgs/@akanjs/devkit/*`), and that resolver probes extensions and directory
+// indexes. A published consumer has no such mapping: it goes through this package's `exports` map,
+// whose targets are matched *exactly*. So `"./*": "./*"` type-checked, built, and passed every test
+// here while every subpath import failed at runtime for anyone installing the tarball:
+//
+//   error: Cannot find module '@akanjs/devkit/executors' from
+//     '<consumer>/node_modules/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts'
+//
+// `PackageRunner.verifyDistPackage` runs the same check against the built dist tree of every
+// publishable package at release time; these tests keep this package honest on every run.
+
+const packageDir = import.meta.dir;
+const exportsMap = await PackageExportsMap.from(packageDir);
+
+/** Every facet the root barrel re-exports, as the subpath a consumer would import. */
+const barrelFacets = async (): Promise<string[]> => {
+  const barrel = await Bun.file(path.join(packageDir, "index.ts")).text();
+  return [...barrel.matchAll(/^export (?:type )?\* from "\.\/([^"]+)";$/gm)].map((match) => `./${match[1]}`);
+};
+
+/** Every `@akanjs/devkit/<subpath>` specifier written anywhere in the two packages that use them. */
+const importedSubpaths = async (): Promise<string[]> => {
+  const repoRoot = path.resolve(packageDir, "../../..");
+  const glob = new Bun.Glob("pkgs/@akanjs/{cli,devkit}/**/*.{ts,tsx}");
+  const found = new Set<string>();
+  for await (const relative of glob.scan({ cwd: repoRoot })) {
+    if (relative.includes("node_modules/") || relative.includes("/dist/")) continue;
+    const source = await Bun.file(path.join(repoRoot, relative)).text();
+    for (const match of source.matchAll(/"@akanjs\/devkit\/([a-zA-Z0-9_./-]+)"/g)) found.add(`./${match[1]}`);
+  }
+  return [...found].sort();
+};
+
+describe("published exports map", () => {
+  test("resolves every facet the root barrel re-exports", async () => {
+    const facets = await barrelFacets();
+    expect(facets.length).toBeGreaterThan(30);
+    expect(exportsMap.findUnreachable(facets)).toEqual([]);
+  });
+
+  test("resolves every subpath the monorepo actually imports", async () => {
+    const subpaths = await importedSubpaths();
+    expect(subpaths.length).toBeGreaterThan(20);
+    expect(exportsMap.findUnreachable(subpaths)).toEqual([]);
+  });
+
+  test("covers both facet shapes and keeps explicit extensions intact", () => {
+    // A single wildcard cannot serve all three: `./*` -> `./*.ts` reaches bare files, directory
+    // facets need their own literal entry, and `./*.ts` -> `./*.ts` keeps an already-suffixed
+    // specifier from becoming `./cloud/cloudApi.ts.ts`.
+    expect(exportsMap.resolve("./executors")).toBe("./executors.ts");
+    expect(exportsMap.resolve("./frontendBuild")).toBe("./frontendBuild/index.ts");
+    expect(exportsMap.resolve("./cloud/cloudApi.ts")).toBe("./cloud/cloudApi.ts");
+    expect(exportsMap.resolve("./package.json")).toBe("./package.json");
+  });
+
+  test("every directory facet has a literal entry, since the wildcard cannot probe index.ts", async () => {
+    const facets = await barrelFacets();
+    const missing = facets.filter(
+      (subpath) =>
+        existsSync(path.join(packageDir, subpath, "index.ts")) && exportsMap.resolve(subpath) !== `${subpath}/index.ts`,
+    );
+    expect(missing).toEqual([]);
+  });
+});

package/packageExportsMap.ts

@@ -0,0 +1,96 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+
+export interface UnreachableSubpath {
+  subpath: string;
+  /** The path the `exports` map yields, or null when no entry matches the subpath at all. */
+  target: string | null;
+}
+
+/**
+ * The subset of Node's `exports` resolution that Bun applies to a published package.
+ *
+ * Exports targets are matched **exactly**: no extension is appended and no `index.ts` is probed. That
+ * is invisible inside this monorepo, where `@akanjs/devkit/*` and `akanjs/*` resolve through the root
+ * tsconfig `paths` instead — a resolver that *does* probe both. A map of `{"./*": "./*"}` therefore
+ * type-checks, builds, and passes every test while every subpath import fails for anyone who installs
+ * the tarball. This class exists so that gap can be asserted against before publishing.
+ */
+export class PackageExportsMap {
+  /** Reads `<packageDir>/package.json` and builds the map from its `exports` field. */
+  static async from(packageDir: string) {
+    const manifest = (await Bun.file(path.join(packageDir, "package.json")).json()) as { exports?: unknown };
+    return new PackageExportsMap(packageDir, manifest.exports);
+  }
+  /** Picks the target a runtime import would follow, walking conditional objects in Bun's order. */
+  static #runtimeTargetOf(value: unknown): string | null {
+    if (typeof value === "string") return value;
+    if (Array.isArray(value)) {
+      // Bun takes the first entry and stops; it does not fall through on a missing file.
+      for (const entry of value) {
+        const target = PackageExportsMap.#runtimeTargetOf(entry);
+        if (target) return target;
+      }
+      return null;
+    }
+    if (!value || typeof value !== "object") return null;
+    const conditions = value as Record<string, unknown>;
+    for (const condition of ["bun", "import", "default", "require", "types"]) {
+      if (!(condition in conditions)) continue;
+      const target = PackageExportsMap.#runtimeTargetOf(conditions[condition]);
+      if (target) return target;
+    }
+    return null;
+  }
+  #packageDir: string;
+  #literals = new Map<string, string>();
+  #patterns: { prefix: string; suffix: string; target: string }[] = [];
+  constructor(packageDir: string, exportsField: unknown) {
+    this.#packageDir = packageDir;
+    if (!exportsField || typeof exportsField !== "object") return;
+    for (const [key, value] of Object.entries(exportsField as Record<string, unknown>)) {
+      if (!key.startsWith(".")) continue; // a bare conditional map has no subpaths to check
+      const target = PackageExportsMap.#runtimeTargetOf(value);
+      if (!target) continue;
+      const star = key.indexOf("*");
+      if (star === -1) this.#literals.set(key, target);
+      else this.#patterns.push({ prefix: key.slice(0, star), suffix: key.slice(star + 1), target });
+    }
+    // Node picks the most specific pattern: longest prefix first, then longest suffix. So `./*.ts`
+    // wins over `./*`, which is what keeps an already-suffixed specifier from gaining a second `.ts`.
+    this.#patterns.sort((a, b) => b.prefix.length - a.prefix.length || b.suffix.length - a.suffix.length);
+  }
+  /** Returns the target an `exports` lookup yields, or null when the subpath is unexported. */
+  resolve(subpath: string): string | null {
+    const literal = this.#literals.get(subpath);
+    if (literal) return literal;
+    for (const { prefix, suffix, target } of this.#patterns) {
+      if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
+      if (subpath.length < prefix.length + suffix.length) continue;
+      return target.replace("*", subpath.slice(prefix.length, subpath.length - suffix.length));
+    }
+    return null;
+  }
+  /**
+   * Resolves a subpath and reports whether the target it yields is a readable file.
+   *
+   * A directory does not count. `{"./*": "./*"}` maps `./commandDecorators` onto the directory of
+   * that name, which exists but is not a module — an `existsSync` check here reports such a subpath
+   * as reachable while the import still fails.
+   */
+  resolveToFile(subpath: string): { target: string | null; exists: boolean } {
+    const target = this.resolve(subpath);
+    if (!target) return { target: null, exists: false };
+    const stat = statSync(path.join(this.#packageDir, target), { throwIfNoEntry: false });
+    return { target, exists: !!stat?.isFile() };
+  }
+  /** Returns the given subpaths that no consumer could import, in input order. */
+  findUnreachable(subpaths: Iterable<string>): UnreachableSubpath[] {
+    const unreachable: UnreachableSubpath[] = [];
+    for (const subpath of subpaths) {
+      const { target, exists } = this.resolveToFile(subpath);
+      if (!exists) unreachable.push({ subpath, target });
+    }
+    return unreachable;
+  }
+}