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

package/akanApp/akanApp.host.ts

@@ -588,16 +588,22 @@ export class AkanAppHost {
   }
   async #handleInvalidate(message: Extract<BuilderMessage, { type: "invalidate" }>) {
     this.#logDevPlan(message);
-    if (shouldRestartBuilderByDevPlan(message)) {
+    // Config changes subsume builder restarts: the dev-host restart recycles builder and backend
+    // AND re-runs the prepare step, so check it first when a batch carries both actions.
+    if (shouldRestartDevHostByDevPlan(message)) {
       try {
-        await this.#restartDevChildren(message);
+        await this.#restartDevHost(message);
       } catch (err) {
-        this.#recordDevHostRestartFailure(message, err);
+        this.#recordDevHostRestartFailure(message, err, "Config");
       }
       return;
     }
-    if (shouldRestartDevHostByDevPlan(message)) {
-      this.#recordDevHostRestartRequired(message);
+    if (shouldRestartBuilderByDevPlan(message)) {
+      try {
+        await this.#restartDevChildren(message);
+      } catch (err) {
+        this.#recordDevHostRestartFailure(message, err, "Runtime metadata");
+      }
       return;
     }
     if (await this.#shouldRestartBackend(message)) {
@@ -611,6 +617,27 @@ export class AkanAppHost {
     this.logger.warn(
       `[dev-host] recycling builder/backend for runtime metadata generation=${generation ?? "(unknown)"} files=${message.files.length}`,
     );
+    await this.#recycleDevChildren(message);
+  }
+  /**
+   * Controlled dev-host restart for config changes (akan.config.ts, tsconfig, package.json):
+   * re-runs the prepare step so env and codegen reflect the new config, then recycles the builder
+   * and backend. The config module is re-imported with a cache-busting query; modules it imports
+   * keep their cached instances, so a change inside an imported plugin file still needs a manual
+   * `akan start` restart.
+   */
+  async #restartDevHost(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
+    const generation = message.devPlan?.generation ?? message.generation;
+    this.logger.warn(
+      `[dev-host] config change detected; restarting dev host generation=${generation ?? "(unknown)"} files=${message.files.length}`,
+    );
+    await this.#recycleDevChildren(message, { refreshConfig: true });
+  }
+  async #recycleDevChildren(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    { refreshConfig = false }: { refreshConfig?: boolean } = {},
+  ): Promise<void> {
+    const generation = message.devPlan?.generation ?? message.generation;
     if (this.#restartTimer) {
       clearTimeout(this.#restartTimer);
       this.#restartTimer = null;
@@ -625,6 +652,13 @@ export class AkanAppHost {
     this.#pendingBuildStatusReplay = [];
     await this.#stopBackend();
     this.#stopBuilder();
+    if (refreshConfig) {
+      await this.app.getConfig({ refresh: true });
+      // Merge instead of replace: start() enriched this.env with values prepare doesn't produce
+      // (e.g. REDIS_HOST from the tunnel), and the spawned children must keep seeing them.
+      const { env } = await this.app.prepareCommand("start");
+      Object.assign(this.env, env);
+    }
     await this.#backendGraph.refresh();
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
@@ -646,34 +680,20 @@ export class AkanAppHost {
       `[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 {
+  #recordDevHostRestartFailure(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    err: unknown,
+    kind: "Config" | "Runtime metadata",
+  ): 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}`);
+    this.logger.warn(`[dev-host] ${kind.toLowerCase()} 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}`,
+      message: `${kind} change requires restarting \`akan start\` to apply: ${detail}`,
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);

package/akanConfig/akanConfig.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { PackageJson } from "../types";
@@ -264,8 +265,22 @@ describe("AkanAppConfig", () => {
       `postgres@${runtimeDependencies.postgres}`,
       `protobufjs@${runtimeDependencies.protobufjs}`,
     ]);
-    expect(config.getMobileRuntimePackages()).toEqual(["firebase"]);
-    expect(config.getMissingMobileDependencySpecs()).toEqual([`firebase@${runtimeDependencies.firebase}`]);
+    expect(config.getMobileRuntimePackages()).toEqual([
+      "firebase",
+      "@capacitor/cli",
+      "@capacitor/core",
+      "@capacitor/ios",
+      "@capacitor/android",
+      "@capacitor/assets",
+    ]);
+    expect(config.getMissingMobileDependencySpecs()).toEqual([
+      `firebase@${runtimeDependencies.firebase}`,
+      `@capacitor/cli@${runtimeDependencies["@capacitor/cli"]}`,
+      `@capacitor/core@${runtimeDependencies["@capacitor/core"]}`,
+      `@capacitor/ios@${runtimeDependencies["@capacitor/ios"]}`,
+      `@capacitor/android@${runtimeDependencies["@capacitor/android"]}`,
+      `@capacitor/assets@${runtimeDependencies["@capacitor/assets"]}`,
+    ]);
   });
 
   test("normalizes multiple mobile targets and validates base paths", () => {
@@ -344,3 +359,26 @@ describe("AkanLibConfig", () => {
     expect(new AkanLibConfig(lib, config).externalLibs).toEqual(["firebase-admin"]);
   });
 });
+
+describe("AkanAppConfig.importConfigModule", () => {
+  test("busting the import cache re-evaluates an edited config module", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "akan-config-bust-"));
+    try {
+      const configPath = path.join(root, "akan.config.ts");
+      fs.writeFileSync(configPath, "export default { basePaths: ['first'] };\n");
+      const first = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root);
+      expect(first.basePaths).toEqual(["first"]);
+
+      fs.writeFileSync(configPath, "export default { basePaths: ['second'] };\n");
+      const stale = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root);
+      expect(stale.basePaths).toEqual(["first"]);
+
+      const busted = await AkanAppConfig.importConfigModule<{ basePaths: string[] }>(root, {
+        bustImportCache: true,
+      });
+      expect(busted.basePaths).toEqual(["second"]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/akanConfig/akanConfig.ts

@@ -52,9 +52,18 @@ const WORKSPACE_BARREL_FACETS = ["ui", "webkit", "common", "client", "server"] a
 const SSR_RUNTIME_PACKAGES = ["react", "react-dom", "react-server-dom-webpack"] as const;
 const NATIVE_RUNTIME_PACKAGES = ["sharp"] as const;
 const DEFAULT_BACKEND_RUNTIME_PACKAGES = ["croner"] as const;
-// Native-only client packages that are not bundled into the base bootstrap; installed
-// on demand when a mobile target is built or started (e.g. firebase for push tokens).
-const MOBILE_RUNTIME_PACKAGES = ["firebase"] as const;
+// Packages required to build/run a mobile target that are not part of the base bootstrap;
+// installed on demand when a mobile target is built or started. Covers the firebase client
+// (push tokens) plus the Capacitor toolchain (`npx cap` / `npx @capacitor/assets`), which is
+// otherwise declared only as optional peers and never auto-installed on a fresh workspace.
+const MOBILE_RUNTIME_PACKAGES = [
+  "firebase",
+  "@capacitor/cli",
+  "@capacitor/core",
+  "@capacitor/ios",
+  "@capacitor/android",
+  "@capacitor/assets",
+] as const;
 const DATABASE_MODE_RUNTIME_PACKAGES = {
   single: [],
   multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
@@ -339,9 +348,26 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
       command,
     };
   }
-  static async from(app: App) {
+  static #importGeneration = 0;
+  /**
+   * Bun caches dynamic imports by path, so a plain re-import after the user edits the config file
+   * returns the stale module. `bustImportCache` appends a fresh query string to force re-evaluation
+   * of the config module itself; modules it imports keep their cached instances.
+   */
+  static async importConfigModule<T = unknown>(
+    cwdPath: string,
+    { bustImportCache = false }: { bustImportCache?: boolean } = {},
+  ): Promise<T> {
+    const configPath = `${cwdPath}/akan.config.ts`;
+    const importPath = bustImportCache
+      ? `${configPath}?akanConfigGeneration=${++AkanAppConfig.#importGeneration}`
+      : configPath;
+    return (await import(importPath).then((mod: { default: T }) => mod.default)) as T;
+  }
+
+  static async from(app: App, { bustImportCache = false }: { bustImportCache?: boolean } = {}) {
     const [configImp, baseDevEnv, libs, rootPackageJson] = await Promise.all([
-      import(`${app.cwdPath}/akan.config.ts`).then((mod) => mod.default),
+      AkanAppConfig.importConfigModule(app.cwdPath, { bustImportCache }),
       WorkspaceExecutor.getBaseDevEnv(path.join(app.workspace.workspaceRoot, ".env")),
       app.workspace.getLibs(),
       app.workspace.getPackageJson(),

package/executors.ts

@@ -1463,7 +1463,9 @@ export class AppExecutor extends SysExecutor {
   #akanConfig: AkanAppConfig | null = null;
   override async getConfig({ refresh }: { refresh?: boolean } = {}) {
     if (this.#akanConfig && !refresh) return this.#akanConfig;
-    this.#akanConfig = await AkanAppConfig.from(this);
+    // A refresh means the config file may have been edited; bust the import cache so the fresh
+    // module is evaluated instead of Bun's cached instance.
+    this.#akanConfig = await AkanAppConfig.from(this, { bustImportCache: refresh });
     return this.#akanConfig;
   }
 

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -356,7 +356,9 @@ class IncrementalBuilder {
         this.#sendBuildStatus("pages", { generation, ok: false, files, message });
       }
     }
-    if (kinds.includes("code") || kinds.includes("css")) {
+    // Server-only code edits cannot introduce class names the CSS scanner would pick up; only a
+    // client rebuild or a direct stylesheet edit can change the compiled CSS.
+    if (kinds.includes("css") || (kinds.includes("code") && rebuildClient)) {
       this.scheduleCssRebuild(artifactDir, { refresh: true, generation, changedFiles: files });
       this.#logger.verbose(`css-rebuild scheduled generation=${generation}`);
     }

package/integration/devStability.integration.test.ts

@@ -203,6 +203,32 @@ export const dictionary = serviceDictionary(["en", "ko"])
     hmr?.close();
   });
 
+  integrationTest("config edits restart the dev host and keep serving", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost();
+    const initialHtml = await harness.tryWaitForHttpText("initial-shared-marker", 3_000);
+    if (!initialHtml) {
+      expect(host.proc.killed).toBe(false);
+      return;
+    }
+    const mark = host.markLog();
+
+    await harness.writeFile(
+      "akan.config.ts",
+      `import type { AppConfig } from "akanjs";
+
+const config: AppConfig = { externalLibs: [] };
+export default config;
+`,
+    );
+
+    await host.waitForLogSince(mark, /\[dev-plan\].*actions=.*restart-dev-host/);
+    await host.waitForLogSince(mark, /\[dev-host\] config change detected; restarting dev host/);
+    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);
+  });
+
   integrationTest("client build failure reports error and recovers after fix", async () => {
     const harness = await createHarness();
     const host = await harness.startHost();

package/package.json

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

package/scanInfo.ts

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { rm } from "node:fs/promises";
+import path from "node:path";
 import type {
   AppConfigResult,
   AppScanResult,
@@ -71,6 +71,7 @@ const appRootAllowedDirs = new Set([
   "srvkit",
   "webkit",
   "common",
+  "secrets",
 ]);
 const libRootAllowedFiles = new Set([
   "cnst.ts",