@akanjs/devkit 2.3.13 → 2.4.0-rc.1

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import {
   type App,
   AppExecutor,
+  AutoImportSync,
   type ChangeBatch,
   type ClientEntryDiscovery,
   CsrArtifactBuilder,
@@ -47,6 +48,7 @@ class IncrementalBuilder {
   #discovery: ClientEntryDiscovery;
   #changePlanner: DevChangePlanner;
   #generatedIndexSync: DevGeneratedIndexSync;
+  #autoImportSync: AutoImportSync;
   #generation = 0;
   #workQueue: Promise<void> = Promise.resolve();
   #cssRebuildQueue: Promise<void> = Promise.resolve();
@@ -62,6 +64,7 @@ class IncrementalBuilder {
     this.#discovery = options.discovery;
     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 });
   }
 
   async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
@@ -269,6 +272,13 @@ class IncrementalBuilder {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
+    //* Insert framework imports that are used but omitted (e.g. `Int` in *.constant.ts, `fetch` in
+    //* *.store.ts) before regenerating barrels. Edits land on files already in this batch, so they
+    //* rebuild in this same generation; the write is idempotent so it does not re-trigger the watcher.
+    const autoImport = await this.#autoImportSync.syncForBatch(batch.files);
+    for (const error of autoImport.errors) this.#logger.error(error);
+    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);
     const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
       generation,
@@ -298,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();
@@ -317,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();
@@ -358,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.3.13",
+  "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.3.13",
+    "akanjs": "2.4.0-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",