@akanjs/devkit 2.3.5 → 2.3.6-rc.1

package/akanApp/akanApp.host.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { Logger } from "akanjs/common";
-import type { BuilderMessage } from "akanjs/server";
+import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeRole } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
@@ -16,6 +16,9 @@ const BUILDER_START_MAX_ATTEMPTS = 3;
 const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const NON_SOURCE_EXT_RE =
   /\.(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"];
+const RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts", "useServer.ts"]);
 const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
   "import-statement",
   "require-call",
@@ -23,6 +26,126 @@ const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
   "dynamic-import",
 ]);
 
+export const shouldRestartBackendByDevPlan = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): 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");
+
+export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
+
+export interface BackendRestartReason {
+  generation?: number;
+  files: string[];
+  roles: Extract<DevChangeRole, "server" | "shared" | "barrel" | "config">[];
+}
+
+interface LastGoodFrontendState {
+  pages?: Extract<BuilderMessage, { type: "pages-updated" }>;
+  css?: Extract<BuilderMessage, { type: "css-updated" }>;
+}
+
+const RESTART_ROLE_ORDER: BackendRestartReason["roles"] = ["server", "shared", "barrel", "config"];
+
+const generationValue = (generation: number | undefined): number => generation ?? -1;
+
+export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string): boolean => {
+  const abs = path.resolve(file);
+  const ext = path.extname(abs).toLowerCase();
+  if (!SOURCE_EXTS.has(ext)) return false;
+  const rel = path.relative(path.resolve(workspaceRoot), abs);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  const parts = rel.split(path.sep).filter(Boolean);
+  const [scope] = parts;
+  if (scope !== "apps" && scope !== "libs" && scope !== "pkgs") return false;
+
+  const base = path.basename(abs);
+  return (
+    parts.includes("srvkit") ||
+    parts.includes("common") ||
+    SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
+    RUNTIME_METADATA_BASENAMES.has(base) ||
+    base === "main.ts" ||
+    base === "server.ts"
+  );
+};
+
+export const shouldMarkBuildPhaseRecovered = (
+  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  status: DevBuildStatus,
+): boolean => {
+  const previous = previousByPhase.get(status.phase);
+  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
+};
+
+export const createBackendBuildStatus = ({
+  generation,
+  ok,
+  files = [],
+  message,
+}: {
+  generation: number;
+  ok: boolean;
+  files?: string[];
+  message?: string;
+}): DevBuildStatus => ({
+  generation,
+  phase: "backend",
+  ok,
+  files,
+  message,
+});
+
+export const backendRestartReasonFromMessage = (
+  message: Extract<BuilderMessage, { type: "invalidate" }>,
+): BackendRestartReason => {
+  const roleSet = new Set<BackendRestartReason["roles"][number]>();
+  for (const role of message.devPlan?.roles ?? []) {
+    if (role === "server" || role === "shared" || role === "barrel" || role === "config") roleSet.add(role);
+  }
+  return {
+    generation: message.devPlan?.generation ?? message.generation,
+    files: [...new Set(message.files)].sort(),
+    roles: RESTART_ROLE_ORDER.filter((role) => roleSet.has(role)),
+  };
+};
+
+export const mergeBackendRestartReasons = (
+  current: BackendRestartReason | null,
+  next: BackendRestartReason,
+): BackendRestartReason => ({
+  generation:
+    generationValue(next.generation) >= generationValue(current?.generation) ? next.generation : current?.generation,
+  files: [...new Set([...(current?.files ?? []), ...next.files])].sort(),
+  roles: RESTART_ROLE_ORDER.filter((role) => current?.roles.includes(role) || next.roles.includes(role)),
+});
+
+export const shouldReplaceLastGoodMessage = (
+  current:
+    | Extract<BuilderMessage, { type: "pages-updated" }>
+    | Extract<BuilderMessage, { type: "css-updated" }>
+    | undefined,
+  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
+): boolean => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
+
+export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
+  !backendReady || pendingReplayCount > 0;
+
+export const buildStatusReplaySequence = (
+  pendingReplay: readonly DevBuildStatus[],
+  latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
+
 class BackendImportGraph {
   readonly #app: App;
   readonly #logger: Logger;
@@ -32,6 +155,7 @@ class BackendImportGraph {
   readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
   #files = new Set<string>();
   #ready = false;
+  #lastRefreshSucceeded = false;
 
   constructor(app: App, logger: Logger) {
     this.#app = app;
@@ -42,6 +166,10 @@ class BackendImportGraph {
     return this.#ready;
   }
 
+  get lastRefreshSucceeded() {
+    return this.#lastRefreshSucceeded;
+  }
+
   has(file: string) {
     return this.#files.has(path.resolve(file));
   }
@@ -51,10 +179,12 @@ class BackendImportGraph {
       const files = await this.#build();
       this.#files = files;
       this.#ready = true;
+      this.#lastRefreshSucceeded = true;
       this.#logger.verbose(`[backend-graph] scanned ${files.size} files`);
       return true;
     } catch (err) {
       this.#ready = this.#files.size > 0;
+      this.#lastRefreshSucceeded = false;
       this.#logger.warn(
         `[backend-graph] scan failed; ${this.#ready ? "using previous graph" : "using fallback rules"}: ${err instanceof Error ? err.message : String(err)}`,
       );
@@ -136,9 +266,13 @@ export class AkanAppHost {
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
   #backendRecoveryAttempts = 0;
-  #restartFiles = new Set<string>();
-  #latestPagesUpdated: Extract<BuilderMessage, { type: "pages-updated" }> | null = null;
-  #latestCssUpdated: Extract<BuilderMessage, { type: "css-updated" }> | null = null;
+  #backendLifecycleState: BackendLifecycleState = "stopped";
+  #pendingRestartReason: BackendRestartReason | null = null;
+  #backendStartStatus: { generation?: number; files: string[] } | null = null;
+  #backendBuildStatusGeneration = 0;
+  #lastGoodFrontend: LastGoodFrontendState = {};
+  #buildStatusByPhase = new Map<BuildPhase, DevBuildStatus>();
+  #pendingBuildStatusReplay: DevBuildStatus[] = [];
   #builderMessageQueue: Promise<void> = Promise.resolve();
   #backendGraph: BackendImportGraph;
   constructor(
@@ -183,7 +317,9 @@ export class AkanAppHost {
     if (environment === "local") return "localhost";
     return await createTunnel(type, { app: this.app, environment });
   }
-  #startBackend() {
+  #startBackend(startStatus: { generation?: number; files: string[] } | null = null) {
+    this.#backendStartStatus = startStatus;
+    this.#setBackendLifecycleState("starting");
     this.#backendReady = false;
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
@@ -194,6 +330,8 @@ export class AkanAppHost {
         if (msg.type === "backend-ready") {
           this.#backendReady = true;
           this.#backendRecoveryAttempts = 0;
+          this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
+          this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
           this.#replayBuilderState();
           return;
@@ -214,9 +352,57 @@ export class AkanAppHost {
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
   }
+  #nextBackendBuildStatusGeneration(generation?: number): number {
+    if (typeof generation === "number") {
+      this.#backendBuildStatusGeneration = Math.max(this.#backendBuildStatusGeneration, generation);
+      return generation;
+    }
+    this.#backendBuildStatusGeneration += 1;
+    return this.#backendBuildStatusGeneration;
+  }
+  #recordBackendBuildStatus({
+    generation,
+    ok,
+    files,
+    message,
+  }: {
+    generation?: number;
+    ok: boolean;
+    files?: string[];
+    message?: string;
+  }): DevBuildStatus {
+    const status = createBackendBuildStatus({
+      generation: this.#nextBackendBuildStatusGeneration(generation),
+      ok,
+      files,
+      message,
+    });
+    this.#recordBuildStatus(status);
+    return status;
+  }
+  #recordBackendReadyStatus(): void {
+    const previous = this.#buildStatusByPhase.get("backend");
+    const startStatus = this.#backendStartStatus;
+    if (startStatus || previous?.ok === false) {
+      const status = this.#recordBackendBuildStatus({
+        generation: startStatus?.generation ?? previous?.generation,
+        ok: true,
+        files: startStatus?.files ?? previous?.files ?? [],
+        message: "Backend ready",
+      });
+      this.#sendOrQueueBuildStatus(status);
+    }
+    this.#backendStartStatus = null;
+  }
+  #setBackendLifecycleState(next: BackendLifecycleState, detail?: string): void {
+    if (this.#backendLifecycleState === next && !detail) return;
+    const prev = this.#backendLifecycleState;
+    this.#backendLifecycleState = next;
+    this.logger.verbose(`[backend-lifecycle] ${prev} -> ${next}${detail ? ` ${detail}` : ""}`);
+  }
   #sendToBackend(message: BuilderMessage) {
     if (!this.#backend || !this.#backendReady) {
-      if (message.type === "css-updated" || message.type === "pages-updated") {
+      if (message.type === "css-updated" || message.type === "pages-updated" || message.type === "build-status") {
         this.logger.verbose(`backend is not ready; will replay ${message.type}`);
         return;
       }
@@ -236,6 +422,7 @@ export class AkanAppHost {
     const backend = this.#backend;
     this.#plannedBackendStops.add(backend);
     this.#backendReady = false;
+    this.#setBackendLifecycleState("stopping", `pid=${backend.pid}`);
     this.logger.verbose(`stopping backend pid=${backend.pid}`);
     try {
       backend.kill("SIGTERM");
@@ -250,10 +437,16 @@ export class AkanAppHost {
       }
     } finally {
       if (this.#backend === backend) this.#backend = null;
+      this.#setBackendLifecycleState("stopped", `pid=${backend.pid}`);
     }
   }
-  #scheduleBackendRestart(files: string[]) {
-    for (const file of files) this.#restartFiles.add(file);
+  #scheduleBackendRestart(reason: BackendRestartReason) {
+    this.#pendingRestartReason = mergeBackendRestartReasons(this.#pendingRestartReason, reason);
+    const pending = this.#pendingRestartReason;
+    this.#setBackendLifecycleState(
+      "restart-pending",
+      `generation=${pending.generation ?? "(unknown)"} files=${pending.files.length} roles=${pending.roles.join(",") || "(none)"}`,
+    );
     if (this.#backendRecoveryTimer) {
       clearTimeout(this.#backendRecoveryTimer);
       this.#backendRecoveryTimer = null;
@@ -261,22 +454,31 @@ export class AkanAppHost {
     if (this.#restartTimer) clearTimeout(this.#restartTimer);
     this.#restartTimer = setTimeout(() => {
       this.#restartTimer = null;
-      const changed = [...this.#restartFiles];
-      this.#restartFiles.clear();
-      void this.#restartBackend(changed);
+      const next = this.#pendingRestartReason;
+      this.#pendingRestartReason = null;
+      if (next) void this.#restartBackend(next);
     }, BACKEND_RESTART_DEBOUNCE_MS);
   }
-  async #restartBackend(files: string[]) {
-    this.logger.verbose(`[backend-reload] restarting backend for ${files.length} file(s)`);
+  async #restartBackend(reason: BackendRestartReason) {
+    this.logger.verbose(
+      `[backend-reload] restarting backend generation=${reason.generation ?? "(unknown)"} files=${reason.files.length} roles=${reason.roles.join(",") || "(none)"}`,
+    );
     this.#backendRecoveryAttempts = 0;
     await Promise.all([this.#stopBackend(), this.#backendGraph.refresh()]);
-    this.#startBackend();
+    this.#startBackend({ generation: reason.generation, files: reason.files });
   }
   #scheduleBackendRecovery(reason: string) {
     if (this.#backendRecoveryTimer || this.#backend) 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);
     this.#backendRecoveryAttempts = attempt + 1;
+    const failureStatus = this.#recordBackendBuildStatus({
+      ok: false,
+      files: [],
+      message: `Backend exited unexpectedly (${reason}); restarting in ${delay}ms`,
+    });
+    this.#sendOrQueueBuildStatus(failureStatus);
     this.logger.warn(
       `[backend-recovery] backend exited unexpectedly (${reason}); restarting in ${delay}ms (attempt ${this.#backendRecoveryAttempts})`,
     );
@@ -284,7 +486,7 @@ export class AkanAppHost {
       this.#backendRecoveryTimer = null;
       if (this.#backend) return;
       void this.#backendGraph.refresh().finally(() => {
-        if (!this.#backend) this.#startBackend();
+        if (!this.#backend) this.#startBackend({ generation: failureStatus.generation, files: failureStatus.files });
       });
     }, delay);
   }
@@ -296,8 +498,13 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
-    if (message.type === "pages-updated") this.#latestPagesUpdated = message;
-    if (message.type === "css-updated") this.#latestCssUpdated = message;
+    if (message.type === "build-status") {
+      this.#recordBuildStatus(message.data);
+      this.#sendOrQueueBuildStatus(message.data);
+      return;
+    }
+    if (message.type === "pages-updated") this.#recordLastGood(message);
+    if (message.type === "css-updated") this.#recordLastGood(message);
     if (message.type === "invalidate") {
       await this.#handleInvalidate(message);
       return;
@@ -305,26 +512,152 @@ 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;
+    }
     if (await this.#shouldRestartBackend(message)) {
-      this.#scheduleBackendRestart(message.files);
+      this.#scheduleBackendRestart(backendRestartReasonFromMessage(message));
       return;
     }
     this.#sendToBackend(message);
   }
-  #replayBuilderState() {
+  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 {
+    if (message.type === "pages-updated") {
+      if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.pages, message)) return;
+      this.#lastGoodFrontend.pages = message;
+      this.logger.verbose(
+        `[last-good] pages generation=${message.data.generation ?? "(unknown)"} buildId=${message.data.buildId}`,
+      );
+      return;
+    }
+    if (!shouldReplaceLastGoodMessage(this.#lastGoodFrontend.css, message)) return;
+    this.#lastGoodFrontend.css = message;
+    this.logger.verbose(
+      `[last-good] css generation=${message.data.generation ?? "(unknown)"} assets=${Object.keys(message.data.cssAssets).length}`,
+    );
+  }
+  #recordDevHostRestartRequired(message: Extract<BuilderMessage, { type: "invalidate" }>): void {
+    const generation = message.devPlan?.generation ?? message.generation;
+    const detail = `generation=${generation ?? "(unknown)"} files=${message.files.length}`;
+    this.logger.warn(
+      `[dev-host] config change requires a manual restart until controlled dev-host restart is implemented (${detail})`,
+    );
+    if (typeof generation === "number") {
+      const status: DevBuildStatus = {
+        generation,
+        phase: "scan",
+        ok: false,
+        files: message.files,
+        message: "Config change requires restarting `akan start` to apply.",
+      };
+      this.#recordBuildStatus(status);
+      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);
+    const label = `[build-status] generation=${status.generation} phase=${status.phase} ok=${status.ok} files=${status.files.length}`;
+    if (status.ok) this.logger.verbose(`${label}${recovered ? " recovered=1" : ""}`);
+    else this.logger.warn(`${label}${status.message ? ` message=${status.message}` : ""}`);
+  }
+  #sendOrQueueBuildStatus(status: DevBuildStatus): void {
+    if (!this.#backend || shouldQueueBuildStatusReplay(this.#backendReady, this.#pendingBuildStatusReplay.length)) {
+      this.#pendingBuildStatusReplay.push(status);
+      this.logger.verbose(
+        `backend is not ready; will replay build-status generation=${status.generation} phase=${status.phase}`,
+      );
+      return;
+    }
+    this.#sendToBackend({ type: "build-status", data: status });
+  }
+  #replayBuilderState(): void {
     if (!this.#backendReady) return;
-    if (this.#latestCssUpdated) this.#sendToBackend(this.#latestCssUpdated);
-    if (this.#latestPagesUpdated) this.#sendToBackend(this.#latestPagesUpdated);
+    if (this.#lastGoodFrontend.css) this.#sendToBackend(this.#lastGoodFrontend.css);
+    if (this.#lastGoodFrontend.pages) this.#sendToBackend(this.#lastGoodFrontend.pages);
+    const queuedStatuses = this.#pendingBuildStatusReplay.splice(0);
+    for (const status of buildStatusReplaySequence(queuedStatuses, this.#buildStatusByPhase)) {
+      this.#sendToBackend({ type: "build-status", data: status });
+    }
   }
   async #shouldRestartBackend(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<boolean> {
     if (message.kinds.length === 1 && message.kinds[0] === "css") return false;
-    if (!this.#backendGraph.ready && message.kinds.includes("code")) await this.#backendGraph.refresh();
-    return message.files.some((file) => this.#isBackendFile(file));
+    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;
+    }
+    if (message.kinds.includes("code")) await this.#backendGraph.refresh();
+    if (message.files.some((file) => this.#isBackendFile(file))) return true;
+    if (!this.#backendGraph.lastRefreshSucceeded) {
+      const fallbackFiles = message.files.filter((file) =>
+        isLegacyBackendFallbackFile(file, this.app.workspace.workspaceRoot),
+      );
+      if (fallbackFiles.length > 0) {
+        this.logger.warn(
+          `[backend-graph] using path-role fallback for legacy invalidate; restart files=${fallbackFiles.length}`,
+        );
+        return true;
+      }
+    }
+    return false;
   }
   #isBackendFile(file: string): boolean {
     return this.#backendGraph.has(file);
   }
-  async #startBuilder() {
+  async #startBuilder(): Promise<IncrementalBuilderHost> {
     const startTime = Date.now();
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
@@ -345,7 +678,7 @@ export class AkanAppHost {
     }
     throw lastError instanceof Error ? lastError : new Error(String(lastError));
   }
-  #waitForBuilderReady(attempt: number) {
+  #waitForBuilderReady(attempt: number): Promise<void> {
     return new Promise<void>((resolve, reject) => {
       if (!this.#builder) throw new Error("Builder Not Found");
       let settled = false;
@@ -372,7 +705,7 @@ export class AkanAppHost {
       });
     });
   }
-  #sendToBuilder(message: BuilderMessage) {
+  #sendToBuilder(message: BuilderMessage): void {
     if (this.#builder?.send(message)) return;
     if (message.type === "build-route") {
       this.#sendToBackend({
@@ -385,7 +718,7 @@ export class AkanAppHost {
     }
     this.logger.warn("akanAppHost builder is not running");
   }
-  #stopBuilder() {
+  #stopBuilder(): void {
     if (!this.#builder) return;
     this.#builder.stop();
     this.#builder = null;