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

package/akanApp/akanApp.host.test.ts

@@ -10,6 +10,7 @@ import {
   shouldQueueBuildStatusReplay,
   shouldReplaceLastGoodMessage,
   shouldRestartBackendByDevPlan,
+  shouldRestartBuilderByDevPlan,
   shouldRestartDevHostByDevPlan,
 } from "./akanApp.host";
 
@@ -37,6 +38,10 @@ describe("shouldRestartBackendByDevPlan", () => {
     expect(shouldRestartBackendByDevPlan(invalidateWithActions(["restart-backend", "report-error"]))).toBe(false);
   });
 
+  test("does not use backend-only restart when builder recycle is required", () => {
+    expect(shouldRestartBackendByDevPlan(invalidateWithActions(["restart-backend", "restart-builder"]))).toBe(false);
+  });
+
   test("falls back when no devPlan is present", () => {
     expect(
       shouldRestartBackendByDevPlan({
@@ -49,6 +54,10 @@ describe("shouldRestartBackendByDevPlan", () => {
 });
 
 describe("shouldRestartDevHostByDevPlan", () => {
+  test("detects explicit restart-builder actions", () => {
+    expect(shouldRestartBuilderByDevPlan(invalidateWithActions(["restart-builder"]))).toBe(true);
+  });
+
   test("detects explicit restart-dev-host actions", () => {
     expect(shouldRestartDevHostByDevPlan(invalidateWithActions(["restart-dev-host"]))).toBe(true);
   });

package/akanApp/akanApp.host.ts

@@ -31,9 +31,13 @@ export const shouldRestartBackendByDevPlan = (
 ): boolean | null => {
   if (!message.devPlan) return null;
   if (message.devPlan.actions.includes("report-error")) return false;
+  if (message.devPlan.actions.includes("restart-builder")) return false;
   return message.devPlan.actions.includes("restart-backend");
 };
 
+export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
+  message.devPlan?.actions.includes("restart-builder") ?? false;
+
 export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 
@@ -508,6 +512,14 @@ export class AkanAppHost {
     this.#sendToBackend(message);
   }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
+    if (shouldRestartBuilderByDevPlan(message)) {
+      try {
+        await this.#restartDevChildren(message);
+      } catch (err) {
+        this.#recordDevHostRestartFailure(message, err);
+      }
+      return;
+    }
     if (shouldRestartDevHostByDevPlan(message)) {
       this.#recordDevHostRestartRequired(message);
       return;
@@ -518,6 +530,29 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  async #restartDevChildren(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
+    const generation = message.devPlan?.generation ?? message.generation;
+    this.logger.warn(
+      `[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`,
+    );
+    if (this.#restartTimer) {
+      clearTimeout(this.#restartTimer);
+      this.#restartTimer = null;
+    }
+    if (this.#backendRecoveryTimer) {
+      clearTimeout(this.#backendRecoveryTimer);
+      this.#backendRecoveryTimer = null;
+    }
+    this.#pendingRestartReason = null;
+    this.#lastGoodFrontend = {};
+    this.#buildStatusByPhase.clear();
+    this.#pendingBuildStatusReplay = [];
+    await this.#stopBackend();
+    this.#stopBuilder();
+    await this.#backendGraph.refresh();
+    await this.#startBuilder();
+    this.#startBackend({ generation, files: message.files });
+  }
   #recordLastGood(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
   ): void {
@@ -553,6 +588,20 @@ export class AkanAppHost {
       this.#sendOrQueueBuildStatus(status);
     }
   }
+  #recordDevHostRestartFailure(message: Extract<BuilderMessage, { type: "invalidate" }>, err: unknown): void {
+    const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
+    const detail = err instanceof Error ? err.message : String(err);
+    this.logger.warn(`[dev-host] runtime metadata restart failed generation=${generation}: ${detail}`);
+    const status: DevBuildStatus = {
+      generation,
+      phase: "scan",
+      ok: false,
+      files: message.files,
+      message: `Runtime metadata change requires restarting \`akan start\` to apply: ${detail}`,
+    };
+    this.#recordBuildStatus(status);
+    this.#sendOrQueueBuildStatus(status);
+  }
   #recordBuildStatus(status: DevBuildStatus): void {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
     this.#buildStatusByPhase.set(status.phase, status);

package/frontendBuild/devChangePlanner.ts

@@ -50,6 +50,7 @@ export class DevChangePlanner {
       const reasons = new Set<string>();
       const fileRoles = this.#rolesForFile(file, { isGenerated: generatedSet.has(path.resolve(file)), reasons });
       for (const role of fileRoles) roles.add(role);
+      if (reasons.has("runtime-metadata")) actions.add("restart-builder");
       if (reasons.size > 0) reasonByFile[path.resolve(file)] = [...reasons].sort();
     }
 
@@ -104,6 +105,9 @@ export class DevChangePlanner {
       roles.add("shared");
       reasons.add("shared-path");
     }
+    if (isSource && this.#isRuntimeMetadataFile(parts, base)) {
+      reasons.add("runtime-metadata");
+    }
 
     if (roles.has("server") && roles.has("client")) {
       roles.delete("server");
@@ -148,6 +152,14 @@ export class DevChangePlanner {
     );
   }
 
+  #isRuntimeMetadataFile(parts: string[], base: string): boolean {
+    const parent = parts.at(-2);
+    if (parent === "lib" && RUNTIME_METADATA_BASENAMES.has(base)) return true;
+    const libIndex = parts.lastIndexOf("lib");
+    if (libIndex < 0 || parts.length <= libIndex + 1) return false;
+    return base.endsWith(".dictionary.ts") || base.endsWith(".signal.ts");
+  }
+
   #isBarrelFacetChild(parts: string[]): boolean {
     if (parts.length < 4) return false;
     const [scope, , facet, child] = parts;

package/frontendBuild/frontendBuild.test.ts

@@ -338,6 +338,27 @@ describe("DevChangePlanner", () => {
       planner.plan({ generation: 2, files: [`${root}/apps/akan/akan.config.ts`], kinds: ["config"] }).actions,
     ).toEqual(["restart-dev-host"]);
   });
+
+  test("recycles builder for macro-backed dictionary and signal metadata changes", () => {
+    const root = "/repo";
+    const planner = new DevChangePlanner({ workspaceRoot: root });
+    const dictionaryPlan = planner.plan({
+      generation: 3,
+      files: [`${root}/apps/demo/lib/_demo/demo.dictionary.ts`],
+      kinds: ["code"],
+    });
+    const signalPlan = planner.plan({
+      generation: 4,
+      files: [`${root}/libs/shared/lib/admin/admin.signal.ts`],
+      kinds: ["code"],
+    });
+
+    expect(dictionaryPlan.actions).toEqual(["rebuild-client", "restart-backend", "restart-builder"]);
+    expect(dictionaryPlan.reasonByFile[`${root}/apps/demo/lib/_demo/demo.dictionary.ts`]).toContain(
+      "runtime-metadata",
+    );
+    expect(signalPlan.actions).toContain("restart-builder");
+  });
 });
 
 describe("CssImportResolver", () => {

package/integration/devStability.integration.test.ts

@@ -3,7 +3,7 @@ import { DevGeneratedIndexSync } from "../frontendBuild";
 import { DevStabilityHarness } from "./devStabilityHarness";
 
 const integrationEnabled = process.env.AKAN_DEV_STABILITY_INTEGRATION === "1";
-const INTEGRATION_TIMEOUT_MS = 60_000;
+const INTEGRATION_TIMEOUT_MS = 120_000;
 const harnesses: DevStabilityHarness[] = [];
 
 const integrationTest = (name: string, fn: () => Promise<void>): void => {
@@ -125,6 +125,40 @@ describe("dev stability integration harness", () => {
     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();

package/integration/devStabilityHarness.ts

@@ -26,7 +26,7 @@ export interface DevStabilityHmrProbe {
   close(): void;
 }
 
-const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_TIMEOUT_MS = 60_000;
 
 const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -196,6 +196,38 @@ export default function Page() {
       this.writeFile(
         "srvkit/backendMarker.ts",
         `export const backendMarker = "initial-backend-marker";
+`,
+      ),
+      this.writeFile(
+        "lib/_fixture/fixture.service.ts",
+        `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+`,
+      ),
+      this.writeFile(
+        "lib/_fixture/fixture.signal.ts",
+        `import { endpoint, internal } from "akanjs/signal";
+
+import * as srv from "../srv";
+
+export class FixtureInternal extends internal(srv.fixture, () => ({})) {}
+
+export class FixtureEndpoint extends endpoint(srv.fixture, () => ({})) {}
+`,
+      ),
+      this.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: ["Initial Dictionary", "초기 사전"],
+    removeMe: ["Remove Me", "삭제 예정"],
+  });
 `,
       ),
       this.writeFile(
@@ -222,7 +254,7 @@ export default function Page() {
 
   async startHost(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<DevStabilityHost> {
     const logs: string[] = [];
-    const proc = Bun.spawn(["bun", "run", "akan", "start", this.appName], {
+    const proc = Bun.spawn(["bash", "-lc", `bun run akan start ${JSON.stringify(this.appName)}`], {
       cwd: this.workspaceRoot,
       env: {
         ...process.env,
@@ -237,7 +269,16 @@ export default function Page() {
     const consume = async (stream: ReadableStream<Uint8Array> | null) => {
       if (!stream) return;
       const decoder = new TextDecoder();
-      for await (const chunk of stream) logs.push(decoder.decode(chunk));
+      const reader = stream.getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          logs.push(decoder.decode(value, { stream: true }));
+        }
+      } finally {
+        reader.releaseLock();
+      }
     };
     void consume(proc.stdout);
     void consume(proc.stderr);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.3.6-rc.0",
+  "version": "2.3.6-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.6-rc.0",
+    "akanjs": "2.3.6-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "^5.5.20",