@akanjs/devkit 3.0.0-alpha.10 → 3.0.0-alpha.100

package/devkitUtils.test.ts

@@ -6,8 +6,6 @@ import { ApplicationBuildReporter } from "./applicationBuildReporter";
 import { resolveSignalTestPreloadPath } from "./applicationTestPreload";
 import { TypeScriptDependencyScanner } from "./dependencyScanner";
 import { AppExecutor, WorkspaceExecutor } from "./executors";
-import { extractDependencies } from "./extractDeps";
-import { getModelFileData } from "./getModelFileData";
 import type { PackageJson, TsConfigJson } from "./types";
 
 const tempRoots: string[] = [];
@@ -27,65 +25,6 @@ afterEach(async () => {
   await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
 });
 
-describe("extractDependencies", () => {
-  const packageJson: PackageJson = {
-    name: "fixture",
-    version: "1.0.0",
-    description: "fixture",
-    dependencies: {
-      react: "19.0.0",
-      "@scope/pkg": "1.0.0",
-      lodash: "4.0.0",
-    },
-    devDependencies: {
-      typescript: "6.0.0",
-      vite: "5.0.0",
-    },
-  };
-
-  test("extracts runtime package versions from imports and requires", () => {
-    const deps = extractDependencies(
-      [
-        {
-          path: "index.ts",
-          text: [
-            'import React from "react";',
-            'import { value } from "@scope/pkg/subpath";',
-            'import type { Type } from "typescript";',
-            'const lodash = require("lodash/fp");',
-            'const fs = require("node:fs");',
-            'const path = require("path");',
-            "",
-          ].join("\n"),
-        },
-        { path: "style.css", text: '@import "vite";' },
-      ],
-      packageJson,
-      ["vite"],
-    );
-
-    expect(deps).toEqual({
-      "@scope/pkg": "1.0.0",
-      lodash: "4.0.0",
-      react: "19.0.0",
-      typescript: "6.0.0",
-      vite: "5.0.0",
-    });
-  });
-
-  test("reports missing dependency sections and missing versions", () => {
-    expect(() =>
-      extractDependencies([{ path: "index.ts", text: 'import React from "react";' }], {
-        name: "broken",
-        version: "1.0.0",
-        description: "broken",
-      }),
-    ).toThrow("No dependencies found");
-
-    expect(() => extractDependencies([], packageJson, ["missing"])).toThrow("No version found for missing");
-  });
-});
-
 describe("resolveSignalTestPreloadPath", () => {
   test("resolves the preload file from an installed akanjs package", async () => {
     const root = await makeTempRoot();
@@ -252,49 +191,6 @@ describe("scan convention", () => {
   });
 });
 
-describe("getModelFileData", () => {
-  test("reads model files and derives imported local, scalar, and lib models", async () => {
-    const root = await makeTempRoot();
-    const cwd = process.cwd();
-    process.chdir(root);
-    try {
-      await write(
-        path.join(root, "apps/demo/lib/post/post.constant.ts"),
-        [
-          'import { cnst as shared } from "@libs/shared";',
-          'import { User } from "../user/user.constant";',
-          'import { Money } from "../_money/money.constant";',
-          "export const Post = {};",
-          "",
-        ].join("\n"),
-      );
-      await write(
-        path.join(root, "apps/demo/lib/post/Post.Unit.tsx"),
-        "export default function Unit() { return null; }\n",
-      );
-      await write(
-        path.join(root, "apps/demo/lib/post/Post.View.tsx"),
-        "export default function View() { return null; }\n",
-      );
-
-      const data = await getModelFileData("apps/demo", "post");
-      expect(data).toMatchObject({
-        moduleType: "app",
-        moduleName: "demo",
-        modelName: "post",
-        importModelNames: ["user"],
-        hasImportScalar: true,
-        importLibNames: ["shared"],
-      });
-      expect(data.constantFileStr).toContain("export const Post");
-      expect(data.unitFileStr).toContain("Unit");
-      expect(data.viewFileStr).toContain("View");
-    } finally {
-      process.chdir(cwd);
-    }
-  });
-});
-
 describe("ApplicationBuildReporter", () => {
   test("formats duration, phase lines, and nested errors", () => {
     expect(ApplicationBuildReporter.formatDuration(999)).toBe("999ms");

package/executors.test.ts

@@ -31,7 +31,6 @@ const rootPackageJson = (extra: Partial<PackageJson> = {}): PackageJson => ({
     react: "19.0.0",
     "react-dom": "19.0.0",
     "react-server-dom-webpack": "19.0.0",
-    sharp: "1.0.0",
     lodash: "4.0.0",
   },
   devDependencies: {
@@ -128,6 +127,49 @@ describe("Executor filesystem helpers", () => {
     expect(await readFile(path.join(root, "local/docker-compose.yaml"), "utf8")).toBe("custom");
   });
 
+  test("hands every scaffolded TypeScript file to the formatter, and nothing else", async () => {
+    // A template emits identifiers it cannot sort — `import { fetch, Task, usePage }` is right for a model
+    // named Task and wrong for Zoo — and unsorted imports fail `biome check`. So the scaffold is formatted
+    // on the way out, or it is red for most model names whatever the template says.
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    const formatted: string[] = [];
+    exec.getLinter = () =>
+      ({
+        fixFiles: async (filePaths: string[]) => {
+          formatted.push(...filePaths);
+          return { fixed: [] };
+        },
+      }) as unknown as ReturnType<Executor["getLinter"]>;
+
+    await exec.applyTemplate({
+      basePath: "apps/demo/page/task",
+      template: "crudSinglePage",
+      dict: { model: "task", appName: "demo" },
+    });
+
+    expect(formatted).toEqual([path.join(root, "apps/demo/page/task/_index.tsx")]);
+  });
+
+  test("a formatter that cannot run does not fail the scaffold", async () => {
+    // `create-akan-workspace` scaffolds before `bun install`, so there is no local Biome binary and often
+    // no config above the target. An unformatted file is a lint fix; a failed scaffold is not.
+    const root = await makeTempRoot();
+    const exec = new Executor("fixture", root);
+    exec.getLinter = () => {
+      throw new Error("biome.json not found");
+    };
+
+    const created = await exec.applyTemplate({
+      basePath: "apps/demo/page/task",
+      template: "crudSinglePage",
+      dict: { model: "task", appName: "demo" },
+    });
+
+    expect(created).toHaveLength(1);
+    expect(await readFile(path.join(root, "apps/demo/page/task/_index.tsx"), "utf8")).toContain("Task.Zone.Card");
+  });
+
   test("applies hidden files and directories from CLI templates", async () => {
     const root = await makeTempRoot();
     const exec = new Executor("fixture", root);
@@ -204,6 +246,7 @@ describe("Workspace and app executor environment contracts", () => {
       serveDomain: "example.com",
       env: "local",
       portOffset: 10,
+      workspaceId: undefined,
     });
 
     delete process.env.AKAN_PUBLIC_REPO_NAME;
@@ -234,6 +277,7 @@ describe("Workspace and app executor environment contracts", () => {
       serveDomain: "file.example.com",
       env: "develop",
       portOffset: 7,
+      workspaceId: undefined,
     });
   });
 
@@ -271,6 +315,11 @@ describe("Workspace and app executor environment contracts", () => {
     const prepared = await app.prepareCommand("build");
     expect(prepared.env.AKAN_COMMAND_TYPE).toBe("build");
     expect(prepared.env.AKAN_PUBLIC_BASE_PATHS).toBe("admin");
+    // Bundling reads `process.env` through getPublicEnv and `define`s every AKAN_PUBLIC_* into a literal, so a
+    // dev port published here would be baked into the artifact and outrank the PORT the container is run with.
+    expect(process.env.AKAN_PUBLIC_APP_NAME).toBe("demo");
+    expect(process.env.AKAN_PUBLIC_CLIENT_PORT).toBeUndefined();
+    expect(process.env.AKAN_PUBLIC_SERVER_PORT).toBeUndefined();
     expect((await stat(path.join(root, "dist/apps/demo/private"))).isDirectory()).toBe(true);
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
@@ -622,6 +671,64 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  describe("root layout source validation during page key discovery", () => {
+    const makeRouteValidationApp = async (appName: string, config: string, files: Record<string, string>) => {
+      const root = await makeTempRoot();
+      process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+      process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+      process.env.AKAN_PUBLIC_ENV = "local";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      await mkdir(path.join(root, "apps", appName), { recursive: true });
+      await writeFile(path.join(root, `apps/${appName}/akan.config.ts`), config);
+      for (const [file, source] of Object.entries(files)) {
+        const filePath = path.join(root, `apps/${appName}/page`, file);
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(filePath, source);
+      }
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      return AppExecutor.from(workspace, appName);
+    };
+    const wsConnectLayout = [
+      "export const wsConnect = false;",
+      "export default function Layout({ children }) { return children; }",
+      "",
+    ].join("\n");
+
+    test("accepts wsConnect on a configured base-path root layout", async () => {
+      process.env.AKAN_PUBLIC_BASE_PATHS = "web,admin";
+      const app = await makeRouteValidationApp(
+        "base-path-root-ws",
+        [
+          "export default {",
+          '  routes: [{ basePath: "web", domains: {} }, { basePath: "admin", domains: {} }],',
+          "};",
+          "",
+        ].join("\n"),
+        { "admin/_layout.tsx": wsConnectLayout },
+      );
+
+      await expect(app.getPageKeys({ refresh: true })).resolves.toEqual(["./admin/_layout.tsx"]);
+    });
+
+    test("rejects wsConnect on a nested layout", async () => {
+      const app = await makeRouteValidationApp(
+        "nested-layout-ws",
+        'export default { routes: [{ basePath: "admin", domains: {} }] };\n',
+        { "admin/users/_layout.tsx": wsConnectLayout },
+      );
+
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(/unsupported export "wsConnect"/);
+    });
+
+    test("accepts wsConnect on a grouped root layout", async () => {
+      const app = await makeRouteValidationApp("grouped-root-ws", "export default {};\n", {
+        "(docs)/_layout.tsx": wsConnectLayout,
+      });
+
+      await expect(app.getPageKeys({ refresh: true })).resolves.toEqual(["./(docs)/_layout.tsx"]);
+    });
+  });
+
   test("accepts metadata route exports during page key discovery", async () => {
     const root = await makeTempRoot();
     process.env.AKAN_PUBLIC_REPO_NAME = "repo";
@@ -760,6 +867,29 @@ describe("Workspace and app executor environment contracts", () => {
     expect(offsetMinimalStart.env.AKAN_PUBLIC_CLIENT_PORT).toBe("8286");
     expect(offsetMinimalStart.env.AKAN_PUBLIC_SERVER_PORT).toBe("8286");
   });
+
+  test("pins the start command to development so an ambient NODE_ENV cannot pick the production router", async () => {
+    const root = await makeTempRoot();
+    process.env.AKAN_PUBLIC_REPO_NAME = "repo";
+    process.env.AKAN_PUBLIC_SERVE_DOMAIN = "example.com";
+    process.env.AKAN_PUBLIC_ENV = "local";
+    await writeJson(path.join(root, "package.json"), rootPackageJson());
+    await mkdir(path.join(root, "apps/ambient"), { recursive: true });
+    await writeFile(path.join(root, "apps/ambient/akan.config.ts"), "export default {};\n");
+
+    const originalNodeEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+    try {
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      const started = await AppExecutor.from(workspace, "ambient").prepareCommand("start");
+      expect(started.env.NODE_ENV).toBe("development");
+      // The builder runs in this process and bakes NODE_ENV into the dev bundles it emits.
+      expect(process.env.NODE_ENV).toBe("development");
+    } finally {
+      if (originalNodeEnv === undefined) delete process.env.NODE_ENV;
+      else process.env.NODE_ENV = originalNodeEnv;
+    }
+  });
 });
 
 describe("PkgExecutor package generation", () => {
@@ -773,7 +903,7 @@ describe("PkgExecutor package generation", () => {
       exports: { "./extra": { import: "./extra.ts" } },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
 
     const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
@@ -783,12 +913,12 @@ describe("PkgExecutor package generation", () => {
     expect(distPackageJson).toMatchObject({
       name: "@sample/tool",
       type: "module",
-      engines: { bun: ">=1.3.13" },
+      engines: { bun: ">=1.4.0" },
       dependencies: { lodash: "4.0.0" },
       devDependencies: { typescript: "6.0.0" },
       peerDependencies: { react: "19.0.0" },
       peerDependenciesMeta: { react: { optional: true } },
-      optionalDependencies: { sharp: "1.0.0" },
+      optionalDependencies: { "@sample/native": "1.0.0" },
     });
     expect(distPackageJson.exports?.["."]).toEqual({
       import: "./index.ts",

package/executors.ts

@@ -23,6 +23,7 @@ import { pathToFileURL } from "node:url";
 import type { AkanPlugin, AkanSyncContext, PluginRuntimeContext } from "akanjs";
 import {
   capitalize,
+  getPageSourceFileViolation,
   isRouteSourceFile,
   Logger,
   parseRouteModuleKey,
@@ -39,6 +40,8 @@ import {
   upsertAgentBlock,
 } from "./agentsIndex";
 import { AkanAppConfig, AkanLibConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
+import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
+import { CodegenLock } from "./codegenLock";
 import { FileSys } from "./fileSys";
 import { getDirname } from "./getDirname";
 import { Linter } from "./linter";
@@ -233,7 +236,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command,
@@ -342,7 +345,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command: modulePath,
@@ -430,7 +433,9 @@ export class Executor {
     const writePath = this.getPath(filePath);
     const dir = path.dirname(writePath);
     if (!(await FileSys.dirExists(dir))) await mkdir(dir, { recursive: true });
-    let contentStr = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+    //? Biome formats every tracked .json and always ends a file with a newline, so a JSON write without one
+    //? loses a byte to `akan lint` and takes it back on the next `akan sync` — a permanent one-line git diff.
+    let contentStr = typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`;
 
     if (await FileSys.fileExists(writePath)) {
       const currentContent = await FileSys.readText(writePath);
@@ -686,7 +691,30 @@ export class Executor {
         Object.entries(options.dict ?? {}).map(([key, value]) => [capitalize(key), capitalize(value)]),
       ),
     };
-    return this._applyTemplate({ ...options, dict });
+    const fileContents = await this._applyTemplate({ ...options, dict });
+    await this.#formatAppliedTemplate(fileContents);
+    return fileContents;
+  }
+
+  /**
+   * A template emits identifiers it cannot sort. `import { fetch, Task, usePage }` is correctly ordered for
+   * a model named Task and wrong for one named Zoo, and `organizeImports` fails `biome check` — so a
+   * scaffold that is not formatted on the way out is red for most model names, whatever the template says.
+   *
+   * Best-effort: `create-akan-workspace` scaffolds before `bun install`, so there is no local Biome binary
+   * and often no config above the target yet. An unformatted file is a lint fix; a failed scaffold is not.
+   */
+  async #formatAppliedTemplate(fileContents: FileContent[]) {
+    const filePaths = fileContents
+      .map((fileContent) => fileContent.filePath)
+      .filter((filePath) => filePath.endsWith(".ts") || filePath.endsWith(".tsx"));
+    if (filePaths.length === 0) return;
+    try {
+      const { fixed } = await this.getLinter().fixFiles(filePaths);
+      if (fixed.length > 0) this.logger.verbose(`Formatted ${fixed.length} scaffolded file(s)`);
+    } catch (err) {
+      this.logger.verbose(`Skipped formatting scaffolded files: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
   // Async so `typescript` (~65MB resident) is loaded only by the commands that actually typecheck,
   // not by every process that imports an executor. `typeCheckAsync` below runs in a subprocess and
@@ -909,9 +937,30 @@ export class WorkspaceExecutor extends Executor {
     return await getDirs(basePath);
   }
   async commit(message: string, { init = false, add = true }: { init?: boolean; add?: boolean } = {}) {
-    if (init) await this.exec(`git init --quiet`);
-    if (add) await this.exec(`git add .`);
-    await this.exec(`git commit --quiet -m "${message}"`);
+    if (init) await this.spawn("git", ["init", "--quiet"]);
+    if (add) await this.spawn("git", ["add", "."]);
+    // Argument vector, not a shell string: a message carrying a double quote breaks the interpolated form.
+    await this.spawn("git", ["commit", "--quiet", "-m", message]);
+  }
+  /** `git commit` exits non-zero on an empty index, so a re-runnable caller has to ask first. */
+  async hasChanges() {
+    return !!(await this.spawn("git", ["status", "--porcelain"])).trim();
+  }
+  /**
+   * Workspace-relative paths git knows about, sorted. `untracked` adds files that exist but are not
+   * committed yet, still honoring `.gitignore` — which is what a freshly copied library looks like.
+   *
+   * Reading the file set from git is what keeps generated barrels, the `page/**` and `public/libs`
+   * symlinks, env values and the lockfile out of it without any caller restating that list.
+   */
+  async listGitFiles(paths: string[], { untracked = false }: { untracked?: boolean } = {}) {
+    if (!paths.length) return [];
+    const mode = untracked ? ["--cached", "--others", "--exclude-standard"] : ["--cached"];
+    const stdout = await this.spawn("git", ["ls-files", "-z", ...mode, "--", ...paths]);
+    return stdout
+      .split("\0")
+      .filter((file) => !!file)
+      .sort();
   }
   async #getDirHasFile(basePath: string, targetFilename: string) {
     const AVOID_DIRS = ["node_modules", "dist", "public", "webkit"];
@@ -1006,6 +1055,16 @@ export class SysExecutor extends Executor {
     const path = this.type === "app" ? `apps/${this.name}/lib` : `libs/${this.name}/lib`;
     return await this.workspace.getDirInModule(path, this.name);
   }
+  async getPageConventionViolations(): Promise<{ relativePath: string; reason: string }[]> {
+    if (!(await this.exists("page"))) return [];
+    const violations: { relativePath: string; reason: string }[] = [];
+    for (const entry of await this.getAllFiles("**/*", { cwd: this.getPath("page") })) {
+      const relativePath = entry.split(path.sep).join("/");
+      const reason = getPageSourceFileViolation(relativePath);
+      if (reason) violations.push({ relativePath: `page/${relativePath}`, reason });
+    }
+    return violations;
+  }
 
   #scanInfo: AppInfo | LibInfo | null = null;
   hasScanInfo() {
@@ -1078,18 +1137,22 @@ export class SysExecutor extends Executor {
         : await LibInfo.fromExecutor(this as unknown as LibExecutor, {
             refresh,
           });
-    if (write) {
-      await Promise.all(this.#getScanTemplateTasks(scanInfo));
-      await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
-      if (this.type === "lib") this.#updateDependencies(scanInfo);
+    //* `writeLib` regenerates every dependency lib's barrels, and each mounting app's `akan start`
+    //* regenerates the same ones — so this region races the other dev servers in the workspace and the
+    //* builders that watch what it writes.
+    if (write)
+      await CodegenLock.run(this.workspace.workspaceRoot, `scan:${this.name}`, async () => {
+        await Promise.all(this.#getScanTemplateTasks(scanInfo));
+        await this.writeJson(`akan.${this.type}.json`, scanInfo.getScanResult());
+        if (this.type === "lib") this.#updateDependencies(scanInfo);
 
-      if (writeLib) {
-        const libInfos = [...scanInfo.getLibInfos().values()];
-        await this.#updateDependencies(scanInfo);
-        await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
-      }
-      await this.syncAgentsIndex(scanInfo);
-    }
+        if (writeLib) {
+          const libInfos = [...scanInfo.getLibInfos().values()];
+          await this.#updateDependencies(scanInfo);
+          await Promise.all(libInfos.flatMap((libInfo) => libInfo.exec.#getScanTemplateTasks(libInfo)));
+        }
+        await this.syncAgentsIndex(scanInfo);
+      });
     this.#scanInfo = scanInfo;
     return scanInfo;
   }
@@ -1347,6 +1410,8 @@ export class AppExecutor extends SysExecutor {
     const databaseMode = process.env.AKAN_DATABASE_MODE ?? akanConfig.defaultDatabaseMode ?? "single";
     const routeEnv = {
       AKAN_PUBLIC_BASE_PATHS: [...akanConfig.basePaths].join(","),
+      AKAN_PUBLIC_API_PREFIX: akanConfig.api.prefix,
+      AKAN_PUBLIC_WS_PREFIX: akanConfig.api.websocketPrefix,
       AKAN_DATABASE_MODE: databaseMode,
     };
     Object.assign(process.env, routeEnv);
@@ -1355,15 +1420,30 @@ export class AppExecutor extends SysExecutor {
       //* generated against and typechecked. Drop the cache so the build phases re-read it without them.
       this.#excludeDevOnlyPages = true;
       this.#pageKeys = null;
-      if (await this.exists(this.dist.cwdPath)) await this.dist.exec(`rm -rf ${this.dist.cwdPath}`);
+      await this.dist.removeDir(this.dist.cwdPath);
       await Promise.all([this.dist.mkdir("private"), this.dist.mkdir("public")]);
       //* Lib assets are symlinks in the app dir (see syncAssets). dist is the docker build context and the
       //* release tarball root, neither of which follows a link out of itself, so materialize them here.
+      //* `public/` has exactly one reader — the web router's catch-all — so an api-only build leaves it out.
       await Promise.all([
         this.cp("private", `${this.dist.cwdPath}/private`, { dereference: true }),
-        this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true }),
+        ...(akanConfig.web.ssr ? [this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true })] : []),
       ]);
-    } else await this.removeDir(".akan");
+    } else {
+      await this.removeDir(".akan");
+      //? `web` is a build declaration: `akan start` keeps the full dev surface because the incremental
+      //? builder is also the file watcher, so switching it off would take server-code HMR with it.
+      if (!akanConfig.web.ssr || !akanConfig.web.csr)
+        this.logger.verbose(
+          `akan.config.ts disables web.${!akanConfig.web.ssr ? "ssr" : "csr"}; \`akan start\` still serves it, \`akan build\` will not`,
+        );
+    }
+    //? `akan start` is the dev server, and it must say so rather than inherit an answer. Bun auto-loads the
+    //? workspace `.env`, so NODE_ENV=production can reach this process without ever being exported in a shell —
+    //? and a dev server that believes it is production serves from the production route cache, whose every
+    //? route throws because a dev artifact carries no routes manifest. Written into `process.env` and not only
+    //? into the child env because the builder runs here and bakes NODE_ENV into the bundles it emits.
+    if (type === "start") process.env.NODE_ENV = "development";
     const devPort = type === "start" ? (await this.getDevPort()).toString() : undefined;
     const env = this.getCommandEnv({
       AKAN_COMMAND_TYPE: type,
@@ -1375,7 +1455,15 @@ export class AppExecutor extends SysExecutor {
     // which filters to AKAN_PUBLIC_*) sees AKAN_PUBLIC_APP_NAME — otherwise SSR throws
     // "environment variable AKAN_PUBLIC_APP_NAME is required". Only AKAN_PUBLIC_* is baked into bundles, so
     // this does not leak non-public env.
-    if (type === "build") Object.assign(process.env, env);
+    // The port keys are this machine's dev allocation, and `define` turns an `AKAN_PUBLIC_*` into a literal the
+    // artifact can never be run with a different value for — a baked port would outrank the `PORT` the container
+    // is started with and send every SSR self-call to a port nothing bound.
+    if (type === "build") {
+      const buildEnv = { ...env };
+      delete buildEnv.AKAN_PUBLIC_CLIENT_PORT;
+      delete buildEnv.AKAN_PUBLIC_SERVER_PORT;
+      Object.assign(process.env, buildEnv);
+    }
     return { env };
   }
   #publicEnv: Record<string, string> | null = null;
@@ -1452,7 +1540,8 @@ export class AppExecutor extends SysExecutor {
           );
         }
         if (!owner) owners.set(routeId, { absPath, fromLib });
-        const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
+        const layoutSegments = getRootBoundarySegments(key);
+        const isRootLayout = layoutSegments !== null && isRootBoundarySegments(layoutSegments, akanConfig.basePaths);
         const routeSource = await Bun.file(absPath).text();
         const validator = await AppExecutor.#getRouteSourceValidator();
         if (parsed.kind === "overrides") validator.validateOverridesSourceExports(routeSource, absPath);
@@ -1701,7 +1790,7 @@ export class LibExecutor extends SysExecutor {
   #akanConfig: AkanLibConfig | null = null;
   override async getConfig({ refresh }: { refresh?: boolean } = {}) {
     if (this.#akanConfig && !refresh) return this.#akanConfig;
-    this.#akanConfig = await AkanLibConfig.from(this);
+    this.#akanConfig = await AkanLibConfig.from(this, { bustImportCache: refresh });
     return this.#akanConfig;
   }
 }
@@ -1807,7 +1896,7 @@ export class PkgExecutor extends Executor {
           default: "./index.ts",
         },
       },
-      engines: { bun: ">=1.3.13" },
+      engines: { bun: ">=1.4.0" },
       ...dependencyMaps,
     };
     await Promise.all([this.dist.writeJson("package.json", distPkgJson), this.writeJson("package.json", distPkgJson)]);