@akanjs/devkit 2.4.0-rc.0 → 2.4.0-rc.1

package/akanApp/akanApp.host.test.ts

@@ -6,6 +6,8 @@ import {
   createBackendBuildStatus,
   isLegacyBackendFallbackFile,
   mergeBackendRestartReasons,
+  normalizeBackendReportedGeneration,
+  shouldAbandonBackendRecovery,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldReplaceLastGoodMessage,
@@ -209,3 +211,28 @@ describe("legacy backend graph fallback", () => {
     expect(isLegacyBackendFallbackFile(`${root}/apps/akan/page/_index.tsx`, root)).toBe(false);
   });
 });
+
+describe("backend recovery abandonment", () => {
+  test("keeps retrying below the attempt ceiling and abandons at it", () => {
+    expect(shouldAbandonBackendRecovery(0)).toBe(false);
+    expect(shouldAbandonBackendRecovery(4)).toBe(false);
+    expect(shouldAbandonBackendRecovery(5)).toBe(true);
+    expect(shouldAbandonBackendRecovery(9)).toBe(true);
+  });
+
+  test("honors a custom attempt ceiling", () => {
+    expect(shouldAbandonBackendRecovery(2, 3)).toBe(false);
+    expect(shouldAbandonBackendRecovery(3, 3)).toBe(true);
+  });
+});
+
+describe("normalizeBackendReportedGeneration", () => {
+  test("drops the gateway's unknown-generation sentinel", () => {
+    expect(normalizeBackendReportedGeneration(-1)).toBeUndefined();
+  });
+
+  test("keeps real generations including zero", () => {
+    expect(normalizeBackendReportedGeneration(0)).toBe(0);
+    expect(normalizeBackendReportedGeneration(7)).toBe(7);
+  });
+});

package/akanApp/akanApp.host.ts

@@ -8,9 +8,12 @@ import { IncrementalBuilderHost } from "../incrementalBuilder";
 
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route"]);
 const BACKEND_RESTART_DEBOUNCE_MS = 120;
-const BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
+// Must exceed the gateway's child-wait budget (AkanApp child shutdown, ~5s in dev) so the gateway
+// is never SIGKILLed while its replicas are still shutting down — that's what strands orphans.
+const BACKEND_GRACEFUL_TIMEOUT_MS = 8_000;
 const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
 const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
+const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 const BACKEND_STDERR_TAIL_LIMIT = 40;
 const BUILDER_READY_TIMEOUT_MS = 150000;
 const BUILDER_START_MAX_ATTEMPTS = 3;
@@ -39,6 +42,17 @@ 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;
+
+/** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
+export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
+  generation >= 0 ? generation : undefined;
+
 export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 
@@ -339,6 +353,18 @@ export class AkanAppHost {
           this.#replayBuilderState();
           return;
         }
+        if (msg.type === "build-status") {
+          // The gateway reports replica boot failures (crash loops, port conflicts) this way so
+          // they reach the build-status log and the HMR overlay like any other build failure.
+          const status = this.#recordBackendBuildStatus({
+            generation: normalizeBackendReportedGeneration(msg.data.generation),
+            ok: msg.data.ok,
+            files: msg.data.files,
+            message: msg.data.message,
+          });
+          this.#sendOrQueueBuildStatus(status);
+          return;
+        }
         if (backendMsgTypeSet.has(msg.type)) this.#sendToBuilder(msg);
       },
       serialization: "advanced",
@@ -504,6 +530,17 @@ export class AkanAppHost {
   }
   #scheduleBackendRecovery(reason: string) {
     if (this.#backendRecoveryTimer || this.#backend) return;
+    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.logger.error(`[backend-recovery] ${message}`);
+      if (this.#backendStderrTail.length > 0) {
+        this.logger.error(`[backend-recovery] recent backend stderr:\n${this.#backendStderrTail.join("\n")}`);
+      }
+      const abandonedStatus = this.#recordBackendBuildStatus({ ok: false, files: [], message });
+      this.#sendOrQueueBuildStatus(abandonedStatus);
+      return;
+    }
     this.#setBackendLifecycleState("recovering", reason);
     const attempt = this.#backendRecoveryAttempts;
     const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
@@ -550,6 +587,7 @@ export class AkanAppHost {
     this.#sendToBackend(message);
   }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
+    this.#logDevPlan(message);
     if (shouldRestartBuilderByDevPlan(message)) {
       try {
         await this.#restartDevChildren(message);
@@ -666,13 +704,18 @@ export class AkanAppHost {
       this.#sendToBackend({ type: "build-status", data: status });
     }
   }
+  /** One log line per planned generation, regardless of which action branch handles it. */
+  #logDevPlan(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
+    if (!message.devPlan) return;
+    const { generation, roles, actions, reasonByFile } = message.devPlan;
+    this.logger.verbose(
+      `[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`,
+    );
+  }
+
   async #shouldRestartBackend(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<boolean> {
     if (message.kinds.length === 1 && message.kinds[0] === "css") return false;
     if (message.devPlan) {
-      const { generation, roles, actions, reasonByFile } = message.devPlan;
-      this.logger.verbose(
-        `[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`,
-      );
       const shouldRestart = shouldRestartBackendByDevPlan(message) ?? false;
       if (shouldRestart && message.kinds.includes("code")) await this.#backendGraph.refresh();
       return shouldRestart;

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -308,15 +308,22 @@ class IncrementalBuilder {
     }
     if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
 
-    if (kinds.includes("code") && (await this.batchMayChangePageKeys(appDir, expandedBatch))) {
+    // Server-only generations (e.g. a .service.ts or srvkit edit) must not rebuild or refresh the
+    // client: a fresh pages buildId would broadcast rsc-refresh to browsers for no visible change.
+    const rebuildClient = devPlan.actions.includes("rebuild-client");
+    if (kinds.includes("code") && !rebuildClient) {
+      this.#logger.verbose(`client rebuild skipped; devPlan actions=${devPlan.actions.join(",") || "(none)"}`);
+    }
+
+    if (kinds.includes("code") && rebuildClient && (await this.batchMayChangePageKeys(appDir, expandedBatch))) {
       const started = Date.now();
       await this.#app.getPageKeys({ refresh: true });
       this.#logger.verbose(`pageKeys updated, app pageKeys are refreshed (${Date.now() - started}ms)`);
-    } else if (kinds.includes("code") && this.batchTouchesPagesTree(appDir, expandedBatch)) {
+    } 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") && this.#shouldRebuildCsr()) {
+    if (kinds.includes("code") && rebuildClient && this.#shouldRebuildCsr()) {
       try {
         const started = Date.now();
         await new CsrArtifactBuilder(this.#app).build();
@@ -327,13 +334,13 @@ class IncrementalBuilder {
         this.#logger.error(`csr-rebundle failed: ${message}`);
         this.#sendBuildStatus("csr", { generation, ok: false, files, message });
       }
-    } else if (kinds.includes("code")) {
+    } else if (kinds.includes("code") && rebuildClient) {
       this.#logger.verbose(`csr-rebundle skipped; set AKAN_DEV_CSR_REBUILD=1 to enable per-save CSR rebuilds`);
     }
 
     process.send?.(event);
 
-    if (kinds.includes("code")) {
+    if (kinds.includes("code") && rebuildClient) {
       try {
         const started = Date.now();
         const next = await new PagesBundleBuilder(this.#app).build();
@@ -368,6 +375,12 @@ class IncrementalBuilder {
           return;
       }
     });
+    // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
+    // as an orphaned watcher that keeps rebuilding for nobody.
+    process.on("disconnect", () => {
+      this.#logger.warn("host IPC channel closed; exiting builder");
+      process.exit(0);
+    });
     if (this.#watch) await this.installWatcher();
     process.send?.({ type: "builder-ready" });
     this.#logger.verbose(`ready (watch=${this.#watch})`);

package/integration/devStability.integration.test.ts

@@ -45,6 +45,50 @@ const waitForFileIncludes = async (filePath: string, text: string, timeoutMs = 5
   return null;
 };
 
+interface GatewayHealth {
+  status: string;
+  pid?: number;
+  children: Array<{ idx: number; role: string; status: string; ready: boolean; pid?: number }>;
+}
+
+const fetchGatewayHealth = async (port: number): Promise<GatewayHealth | null> => {
+  const res = await fetch(`http://127.0.0.1:${port}/_akan/app/health`).catch(() => null);
+  if (!res?.ok) return null;
+  return (await res.json()) as GatewayHealth;
+};
+
+const waitForGatewayHealth = async (
+  port: number,
+  predicate: (health: GatewayHealth) => boolean,
+  timeoutMs = 60_000,
+): Promise<GatewayHealth> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const health = await fetchGatewayHealth(port);
+    if (health && predicate(health)) return health;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error(`Timed out waiting for gateway health on port ${port}`);
+};
+
+const isProcessAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const waitForProcessesGone = async (pids: number[], timeoutMs = 15_000): Promise<boolean> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    if (pids.every((pid) => !isProcessAlive(pid))) return true;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  return false;
+};
+
 afterEach(async () => {
   await Promise.all(harnesses.splice(0).map((harness) => harness.cleanup()));
 });
@@ -205,16 +249,20 @@ export const dictionary = serviceDictionary(["en", "ko"])
   integrationTest("barrel add/delete includes generated indexes in watch generation", async () => {
     const harness = await createHarness();
     const sync = new DevGeneratedIndexSync({ workspaceRoot: harness.workspaceRoot });
-    const facets = ["common", "ui"] as const;
-
-    for (const facet of facets) {
-      const exportName = `${facet}TmpExample`;
+    // `common` barrels export camelCase names; `ui` barrels export PascalCase component names. Each facet's
+    // fixture file must follow its own casing convention or the barrel deliberately skips it.
+    const facets = [
+      { facet: "common", moduleName: "tmpExample", fileName: "tmpExample.ts", exportName: "commonTmpExample" },
+      { facet: "ui", moduleName: "TmpExample", fileName: "TmpExample.tsx", exportName: "TmpExample" },
+    ] as const;
+
+    for (const { facet, moduleName, fileName, exportName } of facets) {
       const indexPath = `${facet}/index.ts`;
-      const absChangedFile = `${harness.appDir}/${facet}/tmpExample.ts`;
+      const absChangedFile = `${harness.appDir}/${facet}/${fileName}`;
       const absIndexPath = `${harness.appDir}/${indexPath}`;
 
       await harness.writeFile(
-        `${facet}/tmpExample.ts`,
+        `${facet}/${fileName}`,
         `export const ${exportName} = "added-${facet}-example";
 `,
       );
@@ -222,21 +270,105 @@ export const dictionary = serviceDictionary(["en", "ko"])
       const added = await sync.syncForBatch([absChangedFile]);
       expect(added.errors).toEqual([]);
       expect(added.changedFiles).toContain(absIndexPath);
-      const addedIndex = await waitForFileIncludes(absIndexPath, "tmpExample");
+      const addedIndex = await waitForFileIncludes(absIndexPath, moduleName);
       expect(addedIndex).not.toBeNull();
-      expect(addedIndex ?? "").toContain("tmpExample");
+      expect(addedIndex ?? "").toContain(moduleName);
 
-      await harness.removeFile(`${facet}/tmpExample.ts`);
+      await harness.removeFile(`${facet}/${fileName}`);
       const removed = await sync.syncForBatch([absChangedFile]);
       expect(removed.errors).toEqual([]);
       expect(removed.changedFiles).toContain(absIndexPath);
-      const deletedIndex = await waitForFileIncludes(absIndexPath, "tmpExample", 1_000);
-      if (deletedIndex) throw new Error(`${indexPath} still contains tmpExample after delete`);
+      const deletedIndex = await waitForFileIncludes(absIndexPath, moduleName, 1_000);
+      if (deletedIndex) throw new Error(`${indexPath} still contains ${moduleName} after delete`);
       const finalIndex = await Bun.file(absIndexPath).text();
       expect(finalIndex).toBeString();
     }
   });
 
+  integrationTest("backend boot failure stops the crash loop, surfaces build-status, and recovers on fix", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const failureMark = host.markLog();
+
+    // The service file is part of the generated server graph (`akan start` regenerates server.ts
+    // from lib/), so a module-level throw here breaks every replica boot.
+    await harness.writeFile(
+      "lib/_fixture/fixture.service.ts",
+      `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+
+throw new Error("intentional-backend-boot-crash");
+`,
+    );
+
+    // The gateway abandons the replica after three failed boots instead of retrying forever...
+    await host.waitForLogSince(failureMark, /\[child-crash-loop\].*failed 3 consecutive boots/);
+    // ...and the failure reaches the dev host's build-status pipeline (HMR overlay path).
+    await host.waitForLogSince(failureMark, /\[build-status\].*phase=backend.*ok=false/);
+    expect(host.proc.killed).toBe(false);
+
+    const recoveryMark = host.markLog();
+    await harness.writeFile(
+      "lib/_fixture/fixture.service.ts",
+      `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+`,
+    );
+
+    await host.waitForLogSince(recoveryMark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    expect(host.proc.killed).toBe(false);
+  });
+
+  integrationTest("SIGKILL'd gateway leaves no orphaned replicas and the host recovers", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const port = await harness.resolvePort();
+
+    const healthy = await waitForGatewayHealth(
+      port,
+      (health) =>
+        typeof health.pid === "number" &&
+        health.children.length > 0 &&
+        health.children.every((child) => child.ready && typeof child.pid === "number"),
+    );
+    const gatewayPid = healthy.pid as number;
+    const childPids = healthy.children.map((child) => child.pid as number);
+    const mark = host.markLog();
+
+    process.kill(gatewayPid, "SIGKILL");
+
+    // Children must notice the closed IPC channel and exit instead of orphaning (they would
+    // otherwise keep holding their ws ports and break every subsequent boot).
+    expect(await waitForProcessesGone(childPids)).toBe(true);
+
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    const recovered = await waitForGatewayHealth(
+      port,
+      (health) => typeof health.pid === "number" && health.pid !== gatewayPid && health.children.some((c) => c.ready),
+    );
+    expect(recovered.pid).not.toBe(gatewayPid);
+    expect(host.proc.killed).toBe(false);
+  });
+
+  integrationTest("occupied preferred ws port falls back to an ephemeral port and stays bootable", async () => {
+    const harness = await createHarness();
+    const port = await harness.resolvePort();
+    // The gateway assigns child 0 the deterministic ws port `port + 10_000`; occupy it up front
+    // the way an orphaned replica from a killed run would.
+    const blocker = Bun.serve({ port: port + 10_000, fetch: () => new Response("occupied") });
+    try {
+      const host = await harness.startHost();
+      await host.waitForLog(/falling back to an ephemeral port/);
+      const health = await waitForGatewayHealth(port, (h) => h.children.some((child) => child.ready));
+      expect(health.children.some((child) => child.ready)).toBe(true);
+      expect(host.proc.killed).toBe(false);
+    } finally {
+      blocker.stop(true);
+    }
+  });
+
   integrationTest("route and css phase-5 scope remains smoke-level in this harness", async () => {
     const manualSmoke = [
       "route add/delete should be covered by a later browser-driven test",

package/integration/devStabilityHarness.ts

@@ -259,6 +259,9 @@ export const dictionary = serviceDictionary(["en", "ko"])
       env: {
         ...process.env,
         AKAN_VERBOSE: "1",
+        // The dev-plan/hmr assertions match verbose-level Logger lines; without this the log
+        // stream only carries info/warn/error and those waits time out with empty tails.
+        AKAN_PUBLIC_LOG_LEVEL: "verbose",
         NODE_NO_WARNINGS: "1",
         PORT_OFFSET: String(this.portOffset),
       },
@@ -422,9 +425,21 @@ export const dictionary = serviceDictionary(["en", "ko"])
   }
 
   async resolvePort(): Promise<number> {
-    const apps = await readdir(path.join(this.workspaceRoot, "apps")).catch(() => []);
-    const appIndex = Math.max([...new Set([...apps, this.appName])].sort().indexOf(this.appName), 0);
-    return 8282 + appIndex + this.portOffset;
+    // Mirror the CLI's `getDevPort()` exactly (apps = directories containing akan.config.ts,
+    // locale-sorted): counting stray entries like .DS_Store would put us one port off the gateway.
+    const appsDir = path.join(this.workspaceRoot, "apps");
+    const entries = await readdir(appsDir, { withFileTypes: true }).catch(() => []);
+    const checked = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) =>
+          (await Bun.file(path.join(appsDir, entry.name, "akan.config.ts")).exists()) ? entry.name : null,
+        ),
+    );
+    const apps = [...new Set([...checked.filter((name): name is string => name !== null), this.appName])].sort((a, b) =>
+      a.localeCompare(b),
+    );
+    return 8282 + Math.max(apps.indexOf(this.appName), 0) + this.portOffset;
   }
 }
 

package/package.json

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