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

package/akanApp/devHostPolicy.test.ts

@@ -28,6 +28,13 @@ import {
   shouldWarnBuilderRssCeilingTight,
 } from "./devHostPolicy";
 
+const status = (phase: BuildPhase, generation: number, ok: boolean): DevBuildStatus => ({
+  generation,
+  phase,
+  ok,
+  files: [],
+});
+
 const invalidateWithActions = (actions: DevChangeAction[]): Extract<BuilderMessage, { type: "invalidate" }> => ({
   type: "invalidate",
   kinds: ["code"],
@@ -158,8 +165,6 @@ describe("holding requests for a returning builder", () => {
   });
 
   test("holds through the drain too, not only after the process is gone", () => {
-    // The window this decision originally missed: the builder is still alive and refusing, which is
-    // the same gap as a restart from anyone waiting on a page.
     expect(shouldHoldForReturningBuilder({ status: "recycling", heldCount: 0 })).toBe(true);
   });
 
@@ -196,8 +201,6 @@ describe("builder rss recycle", () => {
     expect(decide({ ceilingBytes: null })).toBe("unbounded");
   });
 
-  // Rebooting on a generation whose build failed strands the dev server: the replacement hits the
-  // same compile error and exits before builder-ready.
   test("defers while the current generation has a failing build", () => {
     expect(decide({ buildFailed: true })).toBe("build-failed");
   });
@@ -208,34 +211,25 @@ describe("builder rss recycle", () => {
     expect(decide({ msSinceLastRecycle: 5_000, minIntervalMs: 1_000 })).toBe("recycle");
   });
 
-  // Says so, and keeps enforcing: a page load is two route builds, so an app whose builds sit over the
-  // ceiling reaches this on its first navigation — which is normal work, not a reason to drop the only
-  // bound the builder has.
   test("mentions a tight ceiling rather than acting on it", () => {
     expect(shouldWarnBuilderRssCeilingTight(1)).toBe(false);
     expect(shouldWarnBuilderRssCeilingTight(2)).toBe(true);
     expect(shouldWarnBuilderRssCeilingTight(1, 1)).toBe(true);
   });
 
-  // The one case recycling cannot fix, measured on the replacement before it has built anything: every
-  // future replacement lands on the same floor, so the loop would only ever cost boot builds.
   test("gives up only when a fresh builder is already over the ceiling", () => {
     expect(isRssCeilingUnreachable(ceiling + 1, ceiling)).toBe(true);
     expect(isRssCeilingUnreachable(ceiling - 1, ceiling)).toBe(false);
-    // An unreadable rss is no information, and no ceiling is nothing to be unreachable.
     expect(isRssCeilingUnreachable(null, ceiling)).toBe(false);
     expect(isRssCeilingUnreachable(ceiling + 1, null)).toBe(false);
   });
 
-  // Measured on Linux: the builder peaked at 522MiB and settled at 214MiB with no help, so a 400MiB
-  // ceiling recycled a process that was already back under it. The armed sample is always the peak.
   describe("settle check before committing", () => {
     test("waits when the builder is only modestly over the ceiling", () => {
       expect(decideBuilderRssSettle({ rssBytes: 522, ceilingBytes: 400 })).toBe("wait-and-recheck");
       expect(decideBuilderRssSettle({ rssBytes: 401, ceilingBytes: 400 })).toBe("wait-and-recheck");
     });
 
-    // No purge is going to rescue a builder this far over, so waiting only delays the inevitable.
     test("recycles immediately once far enough past the ceiling", () => {
       expect(decideBuilderRssSettle({ rssBytes: 600, ceilingBytes: 400 })).toBe("recycle-now");
       expect(decideBuilderRssSettle({ rssBytes: 900, ceilingBytes: 400 })).toBe("recycle-now");
@@ -268,7 +262,6 @@ describe("dev idle suspend", () => {
     expect(decide({ restartPending: true })).toBe("restart-pending");
   });
 
-  // A wake would boot straight back into the same compile error, and the developer is mid-fix anyway.
   test("never suspends on a red build", () => {
     expect(decide({ buildFailed: true })).toBe("build-failed");
   });
@@ -289,14 +282,13 @@ describe("dev idle suspend", () => {
   });
 
   test("blocks a suspend on a failure in any phase, not just the newest generation", () => {
-    const status = (phase: BuildPhase, ok: boolean): DevBuildStatus => ({ generation: 1, phase, ok, files: [] });
     expect(hasAnyBuildFailure(new Map())).toBe(false);
-    expect(hasAnyBuildFailure(new Map([["scan", status("scan", true)]]))).toBe(false);
+    expect(hasAnyBuildFailure(new Map([["scan", status("scan", 1, true)]]))).toBe(false);
     expect(
       hasAnyBuildFailure(
         new Map([
-          ["scan", status("scan", true)],
-          ["pages", status("pages", false)],
+          ["scan", status("scan", 1, true)],
+          ["pages", status("pages", 1, false)],
         ]),
       ),
     ).toBe(true);
@@ -332,8 +324,6 @@ describe("recycled builder state announcements", () => {
     },
   });
 
-  // Both identities are content hashes, so a recycle with no concurrent edit reproduces them exactly
-  // and must not reload the backend — that would refresh every browser on a memory recycle.
   test("suppresses an unchanged pages announcement and relays a moved one", () => {
     expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-abc.js"))).toBe(false);
     expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-def.js"))).toBe(true);
@@ -355,13 +345,6 @@ describe("recycled builder state announcements", () => {
 });
 
 describe("build status helpers", () => {
-  const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
-    generation,
-    phase,
-    ok,
-    files: [],
-  });
-
   test("tracks recovery by phase without unrelated phases masking failures", () => {
     const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
       ["pages", status("pages", 10, false)],
@@ -441,13 +424,6 @@ describe("backend recovery abandonment", () => {
 });
 
 describe("hasBuildFailureForGeneration", () => {
-  const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
-    generation,
-    phase,
-    ok,
-    files: [],
-  });
-
   test("detects a failing phase recorded for the same generation", () => {
     const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
       ["csr", status("csr", 3, false)],

package/akanApp/devHostPolicy.ts

@@ -11,11 +11,7 @@ import type { IncrementalBuilderStatus } from "../incrementalBuilder";
 
 const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 
-/**
- * How many requests may wait for a builder that is coming back. Generous — a page load asks for
- * several routes — but finite, so a builder that never returns cannot grow this without bound. Past
- * it, requests are failed as they were before, which is the behaviour this limit falls back to.
- */
+// A page load asks for several routes, but a builder that never returns must not grow the hold queue unbounded.
 const HELD_BUILDER_REQUEST_LIMIT = 64;
 
 export const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
@@ -25,8 +21,6 @@ const BUILDER_TIGHT_RSS_REPORT_LIMIT = 2;
 // Far enough above the ceiling that no purge would rescue it; recycle without waiting.
 const BUILDER_RSS_HARD_MULTIPLE = 1.5;
 
-// A sandbox between user turns pays for a watcher that is watching nothing change. Suspending build
-// capacity after this long returns the builder's residency until the next edit or route request.
 const DEV_IDLE_SUSPEND_MS = 300_000;
 
 // A wake that immediately suspends again would flap around whatever woke it.
@@ -34,7 +28,6 @@ const DEV_IDLE_MIN_UPTIME_MS = 30_000;
 
 export const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 
-/\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
 const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
 
 const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
@@ -53,10 +46,6 @@ export const shouldRestartBackendByDevPlan = (
 export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-builder") ?? false;
 
-/**
- * A backend that keeps dying isn't going to heal by retrying the same code; after this many
- * consecutive attempts the host idles and the next server-side edit triggers a fresh restart.
- */
 export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
   attempts >= maxAttempts;
 
@@ -69,11 +58,7 @@ export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, {
 
 export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
 
-/**
- * What a dev host tells a supervising process about itself. Reported rather than scraped: the parent
- * gets one pipe of interleaved child output, in which "this app is up" is indistinguishable from a line
- * that merely mentions it.
- */
+/** Reported, not scraped: in interleaved child output "this app is up" reads like any line mentioning it. */
 export type DevHostState = "starting" | "ready" | "restarting" | "recovering" | "suspended" | "failed" | "stopped";
 
 export interface DevHostEvent {
@@ -91,11 +76,7 @@ const devHostStateByBackendState = {
   stopped: "stopped",
 } as const satisfies { [key in BackendLifecycleState]: DevHostState };
 
-/**
- * The backend's own lifecycle collapsed to what a supervisor can act on. `stopped` is the one state
- * that is ambiguous on its own — a planned shutdown and a crash loop that ran out of retries both land
- * there — so the give-up flag is what separates "gone" from "broken".
- */
+/** `stopped` is both a planned shutdown and an exhausted crash loop; `gaveUp` maps the latter to `failed`. */
 export const devHostStateOf = (state: BackendLifecycleState, gaveUp: boolean): DevHostState =>
   state === "stopped" && gaveUp ? "failed" : devHostStateByBackendState[state];
 
@@ -192,12 +173,7 @@ export const shouldReplaceLastGoodMessage = (
 export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
   !backendReady || pendingReplayCount > 0;
 
-/**
- * Recycling the builder/backend on a generation whose build already failed is guaranteed to strand
- * the dev server: the rebooted builder hits the same compile error and exits before builder-ready.
- * Failing phase statuses for a generation arrive over IPC before that generation's invalidate, so
- * the host can check them here and defer the recycle until a healthy batch lands.
- */
+/** Failing statuses arrive before their generation's invalidate; recycling on one strands the dev server. */
 export const hasBuildFailureForGeneration = (
   statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
   generation: number | undefined,
@@ -211,15 +187,7 @@ export const hasBuildFailureForGeneration = (
 
 export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
 
-/**
- * Whether an over-ceiling builder should be replaced now.
- *
- * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
- * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
- * cases where a recycle cannot help are excluded: a generation whose build already failed (the
- * replacement would hit the same compile error), and a recycle so soon after the last one that the
- * ceiling is evidently unreachable for this app.
- */
+/** `Bun.build` never returns its native arenas, so recycling the builder is the only bound on its RSS. */
 export const decideBuilderRssRecycle = ({
   rssBytes,
   ceilingBytes,
@@ -242,11 +210,6 @@ export const decideBuilderRssRecycle = ({
 
 export type BuilderRssSettleDecision = "recycle-now" | "wait-and-recheck";
 
-/**
- * Whether an armed recycle should wait out the allocator's purge window before committing. A builder
- * far enough over the ceiling is not going to be rescued by a purge, so waiting there only delays a
- * recycle that has to happen.
- */
 export const decideBuilderRssSettle = ({
   rssBytes,
   ceilingBytes,
@@ -267,15 +230,7 @@ export type IdleSuspendDecision =
   | "too-soon"
   | "suspend";
 
-/**
- * Whether the dev host may drop its build capacity now. Every "no" here is a case where suspending
- * would either lose work or produce a wake that immediately re-suspends:
- *
- * - a red build means the developer is mid-fix and about to save again, and a wake would boot straight
- *   back into the same error via the degraded-boot path
- * - a pending restart/recovery already has its own plan for the builder
- * - `too-soon` keeps a wake from flapping around whatever triggered it
- */
+/** A red build means a save is imminent, and a wake would boot straight back into the same error. */
 export const decideIdleSuspend = ({
   enabled,
   suspended,
@@ -313,28 +268,13 @@ export const resolveIdleSuspendMs = (raw: string | undefined): number | null =>
   return Math.round(parsed);
 };
 
-/** Any red phase blocks a suspend, unlike the rss recycle which only cares about one generation. */
 export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
   [...statusByPhase.values()].some((status) => !status.ok);
 
-/**
- * A config change while suspended cannot be applied by restarting the builder alone — the dev host
- * itself has to re-read the config, which is the same path an ordinary config save takes.
- */
 export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
   !!batch && batch.kinds.has("config");
 
-/**
- * Whether a request that arrived while the builder was away should wait for the one coming back.
- *
- * A recycle or a crash-restart is a gap, not a failure — the request that lands in it is the page a
- * developer is waiting on. A stopped builder is a different thing: nothing is bringing it back, so
- * waiting would only delay the error.
- *
- * `recycling` is in here for the same reason as `restarting`, and was the hole this decision shipped
- * with: a draining builder is still alive, so the request reached it and came back refused while the
- * host still thought there was nothing to wait for.
- */
+// `recycling` too: a draining builder is alive and refuses; nothing brings a `stopped` one back, so it fails fast.
 const RETURNING_BUILDER_STATUSES = new Set<IncrementalBuilderStatus>(["starting", "recycling", "restarting"]);
 export const shouldHoldForReturningBuilder = ({
   status,
@@ -346,37 +286,17 @@ export const shouldHoldForReturningBuilder = ({
   limit?: number;
 }): boolean => RETURNING_BUILDER_STATUSES.has(status) && heldCount < limit;
 
-/**
- * Whether a builder that is over the ceiling again this soon after being replaced is worth saying so
- * about, once. Not a reason to stop enforcing the ceiling: the minimum interval already bounds what
- * this costs at one recycle per interval, and dropping the bound is how a container gets OOM-killed.
- *
- * This used to disable the ceiling for the session, on a count that a single page load reaches — two
- * route builds, two reports, both inside the interval. That is normal work on any app whose builds sit
- * above the ceiling, which is the same app the ceiling was derived for.
- */
+/** Warn only, never stop enforcing: dropping the ceiling is how a container gets OOM-killed. */
 export const shouldWarnBuilderRssCeilingTight = (
   reportsSinceRecycle: number,
   limit = BUILDER_TIGHT_RSS_REPORT_LIMIT,
 ): boolean => reportsSinceRecycle >= limit;
 
-/**
- * Whether recycling can ever bring this builder under the ceiling.
- *
- * Measured on a replacement the moment it is ready, before it has built anything on demand: that is
- * the floor every future replacement lands on, so a floor already over the ceiling is the one case
- * where the recycle loop is pure cost. It is also the case the escape hatch was always described as
- * being for — the previous rule inferred it from report timing and caught ordinary work instead.
- */
+/** Takes a fresh replacement's RSS: the floor every future replacement lands on. */
 export const isRssCeilingUnreachable = (freshRssBytes: number | null, ceilingBytes: number | null): boolean =>
   freshRssBytes !== null && ceilingBytes !== null && freshRssBytes >= ceilingBytes;
 
-/**
- * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
- * already has. Both payload identities are content hashes — `pages-[hash].js` and
- * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
- * save that raced the recycle moves them, and that is the case worth pushing.
- */
+/** Both identities are content hashes (`pages-[hash].js`, `<name>-[hash].css`), unchanged by a clean recycle. */
 export const shouldRelayRecycledFrontendState = (
   current:
     | Extract<BuilderMessage, { type: "pages-updated" }>
@@ -409,7 +329,6 @@ const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChange
   };
 };
 
-/** A deferred recycle accumulates every batch it skipped so the eventual restart covers them all. */
 export const mergeInvalidateMessages = (
   current: Extract<BuilderMessage, { type: "invalidate" }>,
   next: Extract<BuilderMessage, { type: "invalidate" }>,
@@ -429,14 +348,9 @@ export const buildStatusReplaySequence = (
   latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
 ): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
 
-/** `(mtimeMs, size)` per file — what a save moves, and what a rebuild of identical content does not. */
+/** `mtimeMs:size` per file. */
 export type SourceFingerprints = ReadonlyMap<string, string>;
 
-/**
- * Which of the files in `before` are no longer stamped the way they were.
- *
- * Only files present in `before` are compared. The question this answers is which *running* code went
- * stale while nothing was watching, and a file that did not exist then is not running anywhere.
- */
+/** Only files in `before`: a file that did not exist then is not running anywhere. */
 export const filesChangedSince = (before: SourceFingerprints, after: SourceFingerprints): string[] =>
   [...before].filter(([file, stamp]) => after.get(file) !== stamp).map(([file]) => file);

package/akanConfig/akanConfig.test.ts

@@ -33,6 +33,22 @@ const baseDevEnv = {
   workspaceRoot: "/workspace",
 };
 
+const loadExtAppConfig = async (tmpPrefix: string, appConfig: string, libConfig: string) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), tmpPrefix));
+  try {
+    fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
+    fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
+    fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), appConfig);
+    fs.writeFileSync(path.join(root, "libs/extlib/akan.config.ts"), libConfig);
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
+    fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
+    const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
+    return await AppExecutor.from(workspace, "extapp").getConfig();
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+};
+
 describe("AkanAppConfig", () => {
   test("applies defaults for route domains, i18n, image, mobile, and imports", () => {
     const config = new AkanAppConfig(app, ["shared"], packageJson, {}, baseDevEnv);
@@ -340,8 +356,7 @@ describe("AkanAppConfig", () => {
     expect(config.getMissingDatabaseModeDependencySpecs("cluster")).toEqual([
       `postgres@${runtimeDependencies.postgres}`,
     ]);
-    // The workspace-root install covers the toolchain/runtime plus every app Capacitor plugin
-    // (deduped — "@capacitor/core" appears in both source lists).
+    // The workspace-root install covers the toolchain plus every app Capacitor plugin, deduped (`@capacitor/core`).
     const expectedMobilePackages: string[] = [
       "@capacitor/cli",
       "@capacitor/core",
@@ -491,25 +506,13 @@ describe("AkanAppConfig lib externalLibs", () => {
   });
 
   test("reads them off every workspace lib config on load", async () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libext-"));
-    try {
-      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
-      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
-      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default { externalLibs: ['shiki'] };\n");
-      fs.writeFileSync(
-        path.join(root, "libs/extlib/akan.config.ts"),
-        "export default { externalLibs: ['puppeteer'] };\n",
-      );
-      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
-      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
-
-      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
-      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+    const config = await loadExtAppConfig(
+      "akan-config-libext-",
+      "export default { externalLibs: ['shiki'] };\n",
+      "export default { externalLibs: ['puppeteer'] };\n",
+    );
 
-      expect(config.externalLibs).toEqual(["shiki", "puppeteer"]);
-    } finally {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
+    expect(config.externalLibs).toEqual(["shiki", "puppeteer"]);
   });
 });
 
@@ -553,26 +556,14 @@ describe("AkanAppConfig lib docker runs", () => {
   });
 
   test("reads them off every workspace lib config on load", async () => {
-    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-libdocker-"));
-    try {
-      fs.mkdirSync(path.join(root, "apps/extapp"), { recursive: true });
-      fs.mkdirSync(path.join(root, "libs/extlib"), { recursive: true });
-      fs.writeFileSync(path.join(root, "apps/extapp/akan.config.ts"), "export default {};\n");
-      fs.writeFileSync(
-        path.join(root, "libs/extlib/akan.config.ts"),
-        "export default { docker: { preRuns: ['echo from-lib'], postRuns: [{ arm64: 'echo arm-only' }] } };\n",
-      );
-      fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "extrepo", version: "1.0.0" }));
-      fs.writeFileSync(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=extrepo\nAKAN_PUBLIC_SERVE_DOMAIN=ext.test\n");
-
-      const workspace = WorkspaceExecutor.fromRoot({ workspaceRoot: root, repoName: "extrepo" });
-      const config = await AppExecutor.from(workspace, "extapp").getConfig();
+    const config = await loadExtAppConfig(
+      "akan-config-libdocker-",
+      "export default {};\n",
+      "export default { docker: { preRuns: ['echo from-lib'], postRuns: [{ arm64: 'echo arm-only' }] } };\n",
+    );
 
-      expect(config.dockerfile).toContain("RUN echo from-lib");
-      expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
-    } finally {
-      fs.rmSync(root, { recursive: true, force: true });
-    }
+    expect(config.dockerfile).toContain("RUN echo from-lib");
+    expect(config.dockerfile).toContain('RUN if [ "$TARGETARCH" = "arm64"');
   });
 });