@akanjs/devkit 2.3.5 → 2.3.6-rc.1

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -6,6 +6,8 @@ import {
   type ClientEntryDiscovery,
   CsrArtifactBuilder,
   type CssCompiler,
+  DevChangePlanner,
+  DevGeneratedIndexSync,
   FontOptimizer,
   GraphClientEntryDiscovery,
   HmrWatcher,
@@ -18,12 +20,13 @@ import {
 import { Logger } from "akanjs/common";
 import type {
   BaseBuildArtifact,
-  BuilderEvent,
   BuilderMessage,
   BuilderReq,
   BuilderRes,
+  BuildPhase,
   BuildRouteResultPayload,
 } from "akanjs/server";
+import { prepareDevWatchBatch } from "./devWatchBatch";
 
 interface IncrementalBuilderOptions {
   app: App;
@@ -42,6 +45,8 @@ class IncrementalBuilder {
   #cssCompiler: CssCompiler;
   #optimizedFonts: Awaited<ReturnType<FontOptimizer["optimize"]>>;
   #discovery: ClientEntryDiscovery;
+  #changePlanner: DevChangePlanner;
+  #generatedIndexSync: DevGeneratedIndexSync;
   #generation = 0;
   #workQueue: Promise<void> = Promise.resolve();
   #cssRebuildQueue: Promise<void> = Promise.resolve();
@@ -55,6 +60,8 @@ class IncrementalBuilder {
     this.#cssCompiler = options.cssCompiler;
     this.#optimizedFonts = options.optimizedFonts;
     this.#discovery = options.discovery;
+    this.#changePlanner = new DevChangePlanner({ workspaceRoot: options.app.workspace.workspaceRoot });
+    this.#generatedIndexSync = new DevGeneratedIndexSync({ workspaceRoot: options.app.workspace.workspaceRoot });
   }
 
   async handleBuildRoute(msg: BuilderReq): Promise<BuilderRes> {
@@ -72,6 +79,7 @@ class IncrementalBuilder {
         discovery: this.#discovery,
       }).build();
       this.#logger.verbose(`build-route ok routeId=${msg.routeId} newEntries=${delta.newEntries.length}`);
+      this.#sendBuildStatus("route", { generation: msg.generation, ok: true, files: msg.seeds });
       return {
         type: "build-route-res",
         id: msg.id,
@@ -90,9 +98,26 @@ class IncrementalBuilder {
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       this.#logger.error(`build-route failed routeId=${msg.routeId}: ${errMsg}`);
+      this.#sendBuildStatus("route", { generation: msg.generation, ok: false, files: msg.seeds, message: errMsg });
       return { type: "build-route-res", id: msg.id, ok: false, error: errMsg };
     }
   }
+  #sendBuildStatus(
+    phase: BuildPhase,
+    { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
+  ): void {
+    if (typeof generation !== "number") return;
+    process.send?.({
+      type: "build-status",
+      data: {
+        generation,
+        phase,
+        ok,
+        files: files ?? [],
+        message,
+      },
+    });
+  }
   async #enqueueWork<T>(label: string, fn: () => Promise<T>): Promise<T> {
     const started = Date.now();
     const run = this.#workQueue.then(fn, fn);
@@ -191,10 +216,18 @@ class IncrementalBuilder {
             generation: next.generation,
             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) => {
-          this.#logger.error(`css-rebuild failed: ${err instanceof Error ? err.message : err}`);
+          const message = err instanceof Error ? err.message : String(err);
+          this.#logger.error(`css-rebuild failed: ${message}`);
+          this.#sendBuildStatus("css", {
+            generation: next.generation,
+            ok: false,
+            files: next.changedFiles,
+            message,
+          });
         });
     }, 150);
   }
@@ -233,25 +266,43 @@ class IncrementalBuilder {
   }
 
   async #handleWatchBatch(appDir: string, artifactDir: string, batch: ChangeBatch) {
-    const kinds = [...batch.kinds] as ("code" | "css" | "config")[];
-    if (kinds.length === 0) return;
+    const rawKinds = new Set(batch.kinds);
+    if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
-    this.#logger.verbose(`[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${batch.files.length}`);
+    const indexSync = await this.#generatedIndexSync.syncForBatch(batch.files);
+    const { files, kinds, expandedBatch, event, hasSyncErrors } = prepareDevWatchBatch({
+      generation,
+      batch,
+      indexSync,
+      changePlanner: this.#changePlanner,
+    });
+    const devPlan = event.devPlan;
+    this.#logger.verbose(
+      `[hmr] batch generation=${generation} kinds=${kinds.join(",")} files=${files.length} generated=${indexSync.changedFiles.length} roles=${devPlan.roles.join(",") || "(none)"} actions=${devPlan.actions.join(",") || "(none)"}`,
+    );
+    for (const error of indexSync.errors) this.#logger.error(error);
 
     if (kinds.includes("code")) {
       const started = Date.now();
       if (kinds.includes("config")) this.#discovery = await GraphClientEntryDiscovery.create(this.#app);
-      else this.#discovery.invalidate?.(batch.files);
+      else this.#discovery.invalidate?.(files);
       this.#logger.verbose(
         `client-entry-discovery ${kinds.includes("config") ? "refreshed" : "invalidated"} (${Date.now() - started}ms)`,
       );
     }
 
-    if (kinds.includes("code") && (await this.batchMayChangePageKeys(appDir, batch))) {
+    if (hasSyncErrors) {
+      this.#sendBuildStatus("barrel", { generation, ok: false, files, message: indexSync.errors.join("\n") });
+      process.send?.(event);
+      return;
+    }
+    if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
+
+    if (kinds.includes("code") && (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, batch)) {
+    } else if (kinds.includes("code") && this.batchTouchesPagesTree(appDir, expandedBatch)) {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
 
@@ -259,15 +310,17 @@ class IncrementalBuilder {
       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) {
-        this.#logger.error(`csr-rebundle failed: ${err instanceof Error ? err.message : 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")) {
       this.#logger.verbose(`csr-rebundle skipped; set AKAN_DEV_CSR_REBUILD=1 to enable per-save CSR rebuilds`);
     }
 
-    const event: BuilderEvent = { type: "invalidate", kinds, files: batch.files, generation };
     process.send?.(event);
 
     if (kinds.includes("code")) {
@@ -276,15 +329,18 @@ class IncrementalBuilder {
         const next = await new PagesBundleBuilder(this.#app).build();
         process.send?.({
           type: "pages-updated",
-          data: { bundlePath: next.bundlePath, buildId: next.buildId, generation, changedFiles: batch.files },
+          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) {
-        this.#logger.error(`pages-rebundle failed: ${err instanceof Error ? err.message : 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 (kinds.includes("code") || kinds.includes("css")) {
-      this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: batch.files });
+      this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }
   }

package/incrementalBuilder/index.ts

@@ -1 +1,2 @@
+export * from "./devWatchBatch";
 export * from "./incrementalBuilder.host";

package/integration/devStability.integration.test.ts

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { DevGeneratedIndexSync } from "../frontendBuild";
+import { DevStabilityHarness } from "./devStabilityHarness";
+
+const integrationEnabled = process.env.AKAN_DEV_STABILITY_INTEGRATION === "1";
+const INTEGRATION_TIMEOUT_MS = 120_000;
+const harnesses: DevStabilityHarness[] = [];
+
+const integrationTest = (name: string, fn: () => Promise<void>): void => {
+  if (integrationEnabled) test(name, fn, INTEGRATION_TIMEOUT_MS);
+  else test.skip(name, fn);
+};
+
+const createHarness = async (): Promise<DevStabilityHarness> => {
+  const harness = new DevStabilityHarness();
+  harnesses.push(harness);
+  await harness.createFixture();
+  return harness;
+};
+
+const isRefreshMessage = (msg: unknown): boolean =>
+  typeof msg === "object" &&
+  msg !== null &&
+  "type" in msg &&
+  (msg.type === "client-refresh" || msg.type === "rsc-refresh" || msg.type === "reload");
+
+const isBuildStatus =
+  (status: "error" | "ok") =>
+  (msg: unknown): boolean =>
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    msg.type === "build-status" &&
+    "status" in msg &&
+    msg.status === status;
+
+const waitForFileIncludes = async (filePath: string, text: string, timeoutMs = 5_000): Promise<string | null> => {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const file = Bun.file(filePath);
+    const contents = (await file.exists()) ? await file.text() : "";
+    if (contents.includes(text)) return contents;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return null;
+};
+
+afterEach(async () => {
+  await Promise.all(harnesses.splice(0).map((harness) => harness.cleanup()));
+});
+
+describe("dev stability integration harness", () => {
+  integrationTest("server-only valid edits restart backend without client refresh", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const hmr = await harness.tryConnectHmrProbe();
+    const mark = host.markLog();
+    const hmrMark = hmr?.mark() ?? 0;
+
+    await harness.replaceText("srvkit/backendMarker.ts", "initial-backend-marker", "updated-backend-marker");
+
+    await host.waitForLogSince(mark, /\[backend-reload\]|Shutting down gracefully|stopping backend/);
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    expect(host.proc.killed).toBe(false);
+    expect(host.logs.join("").slice(mark)).not.toMatch(/\[hmr\].*(client-refresh|rsc-refresh)/);
+    await hmr?.waitForNoMessageSince(hmrMark, isRefreshMessage);
+    hmr?.close();
+  });
+
+  integrationTest("client-only valid edits refresh browser state without backend restart", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const hmr = await harness.tryConnectHmrProbe();
+    const initialHtml = await harness.tryWaitForHttpText("initial-client-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      hmr?.close();
+      return;
+    }
+    const mark = host.markLog();
+    const hmrMark = hmr?.mark() ?? 0;
+
+    await harness.replaceText("ui/ClientMarker.tsx", "initial-client-marker", "updated-client-marker");
+
+    await host.waitForLogSince(mark, /\[dev-plan\].*roles=.*client.*actions=.*rebuild-client/);
+    if (hmr) {
+      const message = await hmr.waitForMessageSince(hmrMark, isRefreshMessage);
+      expect(message).toBeTruthy();
+    } else {
+      await host.waitForLogSince(mark, /\[hmr\].*(client-refresh|rsc-refresh|reload)|\[SSR\] pages-updated/);
+    }
+    expect(host.logs.join("").slice(mark)).not.toMatch(/\[backend-reload\]/);
+    hmr?.close();
+  });
+
+  integrationTest("shared valid edits rebuild client and restart backend in one generation", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const hmr = await harness.tryConnectHmrProbe();
+    const initialHtml = await harness.tryWaitForHttpText("initial-shared-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      hmr?.close();
+      return;
+    }
+    const mark = host.markLog();
+    const hmrMark = hmr?.mark() ?? 0;
+
+    await harness.replaceText("common/marker.ts", "initial-shared-marker", "updated-shared-marker");
+
+    const plan = await host.waitForLogSince(
+      mark,
+      /\[dev-plan\] generation=(\d+).*roles=.*shared.*actions=.*rebuild-client.*restart-backend/,
+    );
+    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}`));
+    await harness.waitForHttpText("updated-shared-marker");
+    hmr?.close();
+  });
+
+  integrationTest("dictionary edits recycle runtime metadata and replace stale snapshots", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const hmr = await harness.tryConnectHmrProbe();
+    const initialHtml = await harness.tryWaitForHttpText("initial-shared-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      hmr?.close();
+      return;
+    }
+    const mark = host.markLog();
+
+    await harness.writeFile(
+      "lib/_fixture/fixture.dictionary.ts",
+      `import { serviceDictionary } from "akanjs/dictionary";
+
+import type { FixtureEndpoint } from "./fixture.signal";
+
+export const dictionary = serviceDictionary(["en", "ko"])
+  .endpoint<FixtureEndpoint>(() => ({}))
+  .translate({
+    hello: ["Updated Dictionary", "업데이트 사전"],
+  });
+`,
+    );
+
+    await host.waitForLogSince(mark, /\[dev-plan\].*actions=.*restart-builder/);
+    await host.waitForLogSince(mark, /\[dev-host\] recycling builder\/backend for runtime metadata/);
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
+    await harness.waitForHttpText("initial-shared-marker");
+    expect(host.proc.killed).toBe(false);
+    hmr?.close();
+  });
+
+  integrationTest("client build failure reports error and recovers after fix", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const hmr = await harness.tryConnectHmrProbe();
+    const initialHtml = await harness.tryWaitForHttpText("initial-client-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      hmr?.close();
+      return;
+    }
+    const failureMark = host.markLog();
+    const failureHmrMark = hmr?.mark() ?? 0;
+
+    await harness.writeFile(
+      "ui/ClientMarker.tsx",
+      `export function ClientMarker() {
+  return <p>broken</p>
+`,
+    );
+
+    await host.waitForLogSince(
+      failureMark,
+      /\[build-status\].*phase=pages.*ok=false|\[build-status\].*phase=csr.*ok=false/,
+    );
+    if (hmr) await hmr.waitForMessageSince(failureHmrMark, isBuildStatus("error"));
+    await harness.waitForHttpText("initial-client-marker");
+    const recoveryMark = host.markLog();
+    const recoveryHmrMark = hmr?.mark() ?? 0;
+
+    await harness.writeFile(
+      "ui/ClientMarker.tsx",
+      `export function ClientMarker() {
+  return <p data-testid="client-marker">recovered-client-marker</p>;
+}
+`,
+    );
+
+    await host.waitForLogSince(recoveryMark, /\[build-status\].*ok=true/);
+    if (hmr) await hmr.waitForMessageSince(recoveryHmrMark, isBuildStatus("ok"));
+    await harness.waitForHttpText("recovered-client-marker");
+    hmr?.close();
+  });
+
+  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`;
+      const indexPath = `${facet}/index.ts`;
+      const absChangedFile = `${harness.appDir}/${facet}/tmpExample.ts`;
+      const absIndexPath = `${harness.appDir}/${indexPath}`;
+
+      await harness.writeFile(
+        `${facet}/tmpExample.ts`,
+        `export const ${exportName} = "added-${facet}-example";
+`,
+      );
+
+      const added = await sync.syncForBatch([absChangedFile]);
+      expect(added.errors).toEqual([]);
+      expect(added.changedFiles).toContain(absIndexPath);
+      const addedIndex = await waitForFileIncludes(absIndexPath, "tmpExample");
+      expect(addedIndex).not.toBeNull();
+      expect(addedIndex ?? "").toContain("tmpExample");
+
+      await harness.removeFile(`${facet}/tmpExample.ts`);
+      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 finalIndex = await Bun.file(absIndexPath).text();
+      expect(finalIndex).toBeString();
+    }
+  });
+
+  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",
+      "css build failure should preserve active stylesheet and report build-status",
+    ];
+
+    expect(manualSmoke).toHaveLength(2);
+  });
+});