@akanjs/devkit 3.0.0-beta.3 → 3.0.0-beta.30

package/applicationBuildReporter.ts

@@ -1,3 +1,5 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
 import { Logger } from "akanjs/common";
 
 export interface ApplicationBuildPhaseResult {
@@ -35,12 +37,12 @@ export class ApplicationBuildReporter {
     Logger.rawLog(`Done in ${ApplicationBuildReporter.formatDuration(result.durationMs)}`);
   }
 
-  static formatError(error: unknown): string {
+  static formatError(error: unknown, workspaceRoot = process.cwd()): string {
     if (error instanceof AggregateError) {
       const nestedMessages = error.errors
         .map(
           (nestedError, index) =>
-            ApplicationBuildReporter.formatError(nestedError).trim() || `Unknown error ${index + 1}`,
+            ApplicationBuildReporter.formatError(nestedError, workspaceRoot).trim() || `Unknown error ${index + 1}`,
         )
         .map((message) => message.replace(/^/gm, "  "))
         .join("\n");
@@ -48,13 +50,43 @@ export class ApplicationBuildReporter {
       return nestedMessages ? `${error.message}\n${nestedMessages}` : error.message;
     }
     if (error instanceof Error) {
-      const causeMessage = error.cause ? `\nCaused by: ${ApplicationBuildReporter.formatError(error.cause)}` : "";
-      return `${error.message}${causeMessage}`;
+      const causeMessage = error.cause
+        ? `\nCaused by: ${ApplicationBuildReporter.formatError(error.cause, workspaceRoot)}`
+        : "";
+      return `${ApplicationBuildReporter.#withLocation(error.message, error, workspaceRoot)}${causeMessage}`;
     }
-    if (typeof error === "object" && error !== null && "message" in error) return String(error.message);
+    if (typeof error === "object" && error !== null && "message" in error)
+      return ApplicationBuildReporter.#withLocation(String(error.message), error, workspaceRoot);
     return String(error);
   }
 
+  static #withLocation(message: string, error: object, workspaceRoot: string): string {
+    const { position } = error as { position?: { file: string; line: number; column: number } | null };
+    if (!position?.file) return message;
+    const file = ApplicationBuildReporter.#relativeToWorkspace(position.file, workspaceRoot);
+    const location = position.line > 0 ? `${file}:${position.line}:${position.column}` : file;
+    return message.includes(location) ? message : message.replace(/^.*/, (headline) => `${headline} (${location})`);
+  }
+
+  // Bun names the file by its realpath, so a workspace root reached through a symlink is matched by its own too.
+  static #relativeToWorkspace(file: string, workspaceRoot: string): string {
+    if (!path.isAbsolute(file)) return file;
+    for (const root of [workspaceRoot, ApplicationBuildReporter.#realpathOf(workspaceRoot)]) {
+      const relative = path.relative(root, file);
+      if (!relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+        return relative.replaceAll(path.sep, "/");
+    }
+    return file;
+  }
+
+  static #realpathOf(dir: string): string {
+    try {
+      return realpathSync(dir);
+    } catch {
+      return dir;
+    }
+  }
+
   static formatDuration(ms: number): string {
     if (ms < 1000) return `${ms}ms`;
     if (ms < 60_000) return `${Math.round(ms / 100) / 10}s`;

package/applicationBuildRunner.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { rm } from "node:fs/promises";
-import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { AkanAppConfig } from "./akanConfig";
+import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS, ApplicationBuildRunner } from "./applicationBuildRunner";
+import type { App } from "./commandDecorators";
+import { Executor } from "./executors";
 
 describe("ApplicationBuildRunner", () => {
   test("externalizes Akan optional backend dependencies", () => {
@@ -16,8 +21,8 @@ describe("ApplicationBuildRunner", () => {
   });
 
   test("a bundler that mangles identifiers loses the class name a Logger reads", async () => {
-    const dir = `${process.env.TMPDIR ?? "/tmp"}/akan-minify-${Bun.randomUUIDv7()}`;
-    const entry = `${dir}/entry.ts`;
+    const dir = path.join(os.tmpdir(), `akan-minify-${Bun.randomUUIDv7()}`);
+    const entry = path.join(dir, "entry.ts");
     await Bun.write(
       entry,
       `const serve = () => class Service { readonly name = this.constructor.name; };
@@ -26,7 +31,7 @@ console.info(new SampleService().name);
 `,
     );
     const build = async (minify: Bun.BuildConfig["minify"]) => {
-      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: `${dir}/out` });
+      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: path.join(dir, "out") });
       expect(result.success).toBe(true);
       const proc = Bun.spawn([process.execPath, result.outputs[0].path], { stdout: "pipe" });
       return (await new Response(proc.stdout).text()).trim();
@@ -42,4 +47,35 @@ console.info(new SampleService().name);
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("an image of a --env build boots the env its server carries, not the root .env's", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "akan-build-meta-"));
+    const baseDevEnv = {
+      repoName: "akanjs",
+      serveDomain: "akanjs.com",
+      env: "local" as const,
+      portOffset: 0,
+      workspaceRoot: root,
+    };
+    const config = new AkanAppConfig(
+      { name: "portal" } as never,
+      [],
+      { name: "repo", version: "1.0.0", description: "repo" },
+      {},
+      baseDevEnv,
+    );
+    const app = {
+      getConfig: async () => config,
+      dist: new Executor("dist", root),
+      workspace: { workspaceRoot: root },
+    } as unknown as App;
+    try {
+      await new ApplicationBuildRunner(app, { environment: "debug" }).buildAppMeta();
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("ENV AKAN_PUBLIC_ENV=debug\n");
+      await new ApplicationBuildRunner(app).buildAppMeta();
+      expect(await readFile(path.join(root, "Dockerfile"), "utf8")).toContain("ENV AKAN_PUBLIC_ENV=local\n");
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
 });

package/applicationBuildRunner.ts

@@ -15,6 +15,7 @@ import {
   SsrBaseArtifactBuilder,
 } from "./frontendBuild";
 import { Spinner } from "./spinner";
+import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -29,6 +30,8 @@ export type BuildProgressReporter = ApplicationBuildProgressReporter;
 export interface ApplicationBuildRunnerOptions {
   fast?: boolean;
   reporter?: BuildProgressReporter;
+  /** The backend env the build is for, when it is not the workspace's own (a mobile or desktop build's `--env`). */
+  environment?: string;
 }
 export interface BuildOptions {
   spinner?: boolean;
@@ -60,9 +63,8 @@ const SSR_RENDER_EXTERNALS = [
   "react-server-dom-webpack/client.browser",
 ] as const;
 
-// Identifier mangling renames every class, and `this.constructor.name` is what names a service's logger, an
-// `Exception`, a guard, and every frame of a stack trace — for ~2% of boot on server bytes nothing downloads.
-// `minify.keepNames` typechecks and does nothing as of Bun 1.4.2.
+// Mangling renames classes, and `this.constructor.name` names loggers, exceptions and guards; `minify.keepNames`
+// is a no-op as of Bun 1.4.2.
 export const AKAN_BACKEND_MINIFY = { whitespace: true, syntax: true, identifiers: false } as const;
 
 export const AKAN_OPTIONAL_BACKEND_EXTERNALS = [
@@ -77,29 +79,29 @@ export class ApplicationBuildRunner {
   #app: App;
   #fast: boolean;
   #reporter?: BuildProgressReporter;
+  #environment?: string;
+  #spinner?: boolean;
   #startedAt = Date.now();
   #phases: BuildPhaseResult[] = [];
 
-  constructor(app: App, { fast = false, reporter }: ApplicationBuildRunnerOptions = {}) {
+  constructor(app: App, { fast = false, reporter, environment }: ApplicationBuildRunnerOptions = {}) {
     this.#app = app;
     this.#fast = fast;
     this.#reporter = reporter;
+    this.#environment = environment;
   }
 
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
-    const phaseOptions = { spinner };
+    this.#spinner = spinner;
     const { web, assets } = await this.#app.getConfig();
-    await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"), undefined, {
-      spinner,
-    });
-    if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck(), undefined, phaseOptions);
+    await this.#runPhase("prepare", "Preparing output directory", () => this.#app.prepareCommand("build"));
+    if (!this.#fast) await this.#runPhase("typecheck", "Typechecking", () => this.typecheck());
     await this.#runPhase(
       "backend",
       "Compiling backend",
       () => this.#buildBackend(),
       (result) => `${result.entrypoints} entrypoints, ${result.outputs} outputs`,
-      phaseOptions,
     );
     await this.#runPhase(
       "ssr",
@@ -111,14 +113,12 @@ export class ApplicationBuildRunner {
           : web.ssr
             ? "skipped"
             : "disabled by akan.config.ts web.ssr",
-      phaseOptions,
     );
     await this.#runPhase(
       "csr",
       "Building CSR assets",
-      async () => (web.csr ? await this.#buildCsr() : null),
+      async () => (web.csr ? await new CsrArtifactBuilder(this.#app, "build").build() : null),
       (result) => result?.outputDir ?? (web.csr ? "skipped" : "disabled by akan.config.ts web.csr"),
-      phaseOptions,
     );
     await this.#runPhase(
       "assets",
@@ -128,7 +128,6 @@ export class ApplicationBuildRunner {
         result
           ? `${result.removed.length} font file(s) dropped, ${ApplicationBuildRunner.formatBytes(result.freedBytes)} freed; ${result.kept.length} kept`
           : "disabled by akan.config.ts assets.pruneFonts",
-      phaseOptions,
     );
     await this.#runPhase(
       "compress",
@@ -138,11 +137,8 @@ export class ApplicationBuildRunner {
         result.files > 0
           ? `${result.files} files, ${ApplicationBuildRunner.formatBytes(result.inputBytes)} -> gzip ${ApplicationBuildRunner.formatBytes(result.outputBytes)} / br ${ApplicationBuildRunner.formatBytes(result.brotliBytes)}`
           : "no files",
-      phaseOptions,
     );
-    await this.#runPhase("metadata", "Writing production metadata", () => this.#buildAppMeta(), undefined, {
-      spinner,
-    });
+    await this.#runPhase("metadata", "Writing production metadata", () => this.buildAppMeta());
     return {
       phases: this.#phases,
       durationMs: Date.now() - this.#startedAt,
@@ -154,7 +150,7 @@ export class ApplicationBuildRunner {
   async typecheck(options: TypecheckOptions = {}) {
     const { clean = false, incremental = true } = options;
     await this.#app.getPageKeys({ refresh: true });
-    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig({ incremental });
+    const { typecheckDir, tsconfigPath } = await this.#writeTypecheckTsconfig(incremental);
     if (clean) await rm(path.join(typecheckDir, "tsconfig.tsbuildinfo"), { force: true });
     await this.#checkProjectInChildProcess(tsconfigPath);
   }
@@ -164,19 +160,17 @@ export class ApplicationBuildRunner {
     label: string,
     task: () => Promise<T>,
     summarize?: (result: T) => string | undefined,
-    options: BuildPhaseRunOptions = {},
   ) {
     this.#reporter?.phaseStart?.({ id, label });
     const phaseStartedAt = Date.now();
-    const spinner = options.spinner
+    const spinner = this.#spinner
       ? new Spinner(label, { prefix: `${BUILD_PHASE_EMOJIS[id]} ${id}` }).start()
       : undefined;
     try {
       const result = await task();
       const phase = { id, label, durationMs: Date.now() - phaseStartedAt, summary: summarize?.(result) };
       this.#phases.push(phase);
-      const summary = phase.summary ? `: ${phase.summary}` : "";
-      spinner?.succeed(`${label}${summary}`);
+      spinner?.succeed(`${label}${phase.summary ? `: ${phase.summary}` : ""}`);
       this.#reporter?.phaseDone?.(phase);
       return result;
     } catch (error) {
@@ -186,71 +180,94 @@ export class ApplicationBuildRunner {
     }
   }
 
-  async #buildAppMeta() {
+  async buildAppMeta() {
     const akanConfig = await this.#app.getConfig();
+    const dockerfile = akanConfig.dockerfileFor(this.#environment ?? akanConfig.baseDevEnv.env);
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
-      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
+      this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, dockerfile),
+      this.#app.dist.writeJson("akan.build.json", {
+        buildId: await this.#resolveBuildId(),
+        akanVersion: akanConfig.akanVersion,
+        builtAt: new Date().toISOString(),
+      }),
     ]);
   }
 
+  //* Read back at runtime as `buildId` on the ops channel; a deployment's own AKAN_BUILD_ID still wins over it there.
+  async #resolveBuildId() {
+    const fromEnv = process.env.AKAN_BUILD_ID?.trim();
+    if (fromEnv) return fromEnv;
+    const root = this.#app.workspace.workspaceRoot;
+    const sha = Bun.spawnSync(["git", "rev-parse", "--short=12", "HEAD"], { cwd: root, stderr: "ignore" });
+    if (sha.exitCode !== 0) return null;
+    const dirty = Bun.spawnSync(["git", "status", "--porcelain", "--untracked-files=no"], {
+      cwd: root,
+      stderr: "ignore",
+    });
+    const suffix = dirty.exitCode === 0 && dirty.stdout.toString().trim() ? "-dirty" : "";
+    return `${sha.stdout.toString().trim()}${suffix}`;
+  }
+
   async #buildBackend() {
-    const akanConfig = await this.#app.getConfig();
-    const backendExternals = [
-      ...new Set([...akanConfig.externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]),
-    ];
-    const { web } = akanConfig;
+    const { externalLibs, web, baseDevEnv, branches } = await this.#app.getConfig();
     const backendEntryPoints = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
     }
-    const backendResult = await this.#buildOrThrow("backend", {
-      entrypoints: backendEntryPoints,
+    const sharedConfig = {
       outdir: this.#app.dist.cwdPath,
       target: "bun",
       minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
+      // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
-      plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
+    } satisfies Omit<Bun.BuildConfig, "entrypoints">;
+    const serverEnvPlugin = createServerEnvPlugin({
+      envDir: path.join(this.#app.cwdPath, "env"),
+      //? The root .env wins over the shell in baseDevEnv, so a `--env` build names its own; a desktop app runs it.
+      environment: this.#environment ?? baseDevEnv.env,
+      environments: ["local", "testing", ...branches],
     });
+    const backendConfig = {
+      ...sharedConfig,
+      plugins: [this.#createExternalSpecifiersPlugin(externalLibs), serverEnvPlugin],
+    };
+    //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot parse.
+    const [mainResult, serverResult] = [
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[0]] }),
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[1]], splitting: true }),
+    ];
     // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
     const rscWorkerResult = web.ssr
       ? await this.#buildOrThrow("rsc-worker", {
+          ...backendConfig,
           entrypoints: [this.#resolveRscWorkerBuildEntry()],
-          outdir: this.#app.dist.cwdPath,
-          target: "bun",
-          minify: AKAN_BACKEND_MINIFY,
-          naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
           conditions: ["react-server"],
-          // `akan build` must embed production react-server-dom regardless of the shell's NODE_ENV.
-          define: { "process.env.NODE_ENV": JSON.stringify("production") },
-          plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
         })
       : null;
     const consoleRuntimeResult = await this.#buildOrThrow("console-runtime", {
+      ...sharedConfig,
       entrypoints: [this.#resolveConsoleRuntimeBuildEntry()],
-      outdir: this.#app.dist.cwdPath,
-      target: "bun",
-      minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "console-runtime.[ext]", chunk: "chunk-[hash].[ext]" },
-      define: { "process.env.NODE_ENV": JSON.stringify("production") },
     });
     await this.#writeConsoleShim();
+    const results = [mainResult, serverResult, rscWorkerResult, consoleRuntimeResult];
     return {
       entrypoints: backendEntryPoints.length + (rscWorkerResult ? 2 : 1),
-      outputs:
-        backendResult.outputs.length + (rscWorkerResult?.outputs.length ?? 0) + consoleRuntimeResult.outputs.length + 1,
+      outputs: results.reduce((sum, result) => sum + (result?.outputs.length ?? 0), 1),
     };
   }
 
   async #writeConsoleShim() {
     await Bun.write(
       path.join(this.#app.dist.cwdPath, "console.js"),
-      `import { cnst, db, dict, option, server, sig, srv } from "./server.js";
-import { assertAkanConsoleAllowed, startAkanConsole } from "./console-runtime.js";
+      `process.env.AKAN_COMMAND_TYPE = "console";
+const { cnst, db, dict, option, server, sig, srv } = await import("./server.js");
+const { assertAkanConsoleAllowed, startAkanConsole } = await import("./console-runtime.js");
 
 const run = async () => {
-  assertAkanConsoleAllowed(server.env);
+  assertAkanConsoleAllowed();
   await server.start({ listen: false, web: false });
   try {
     await startAkanConsole(server, { globals: { cnst, db, dict, option, sig, srv } });
@@ -283,10 +300,6 @@ void run().catch((error) => {
     }
   }
 
-  async #buildCsr() {
-    return await new CsrArtifactBuilder(this.#app, "build").build();
-  }
-
   async #buildSsr() {
     const pageKeys = await this.#app.getPageKeys();
     if (pageKeys.length === 0) {
@@ -298,7 +311,7 @@ void run().catch((error) => {
     return { base, allRoutes };
   }
 
-  async #writeTypecheckTsconfig({ incremental = true }: TypecheckOptions = {}) {
+  async #writeTypecheckTsconfig(incremental: boolean) {
     const typecheckDir = path.join(this.#app.cwdPath, ".akan", "typecheck");
     await mkdir(typecheckDir, { recursive: true });
     //* TypeScript's `include` globs do not cross a symlink, so synced lib pages need their real path.
@@ -367,11 +380,10 @@ void run().catch((error) => {
     return result;
   }
 
-  #createExternalSpecifiersPlugin(specifiers: readonly string[]): BunPlugin {
-    const uniqueSpecifiers = [...new Set(specifiers)];
-    const escaped = uniqueSpecifiers.map((specifier) => specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  #createExternalSpecifiersPlugin(externalLibs: readonly string[]): BunPlugin {
+    const specifiers = new Set([...externalLibs, ...SSR_RENDER_EXTERNALS, ...AKAN_OPTIONAL_BACKEND_EXTERNALS]);
+    const escaped = [...specifiers].map((specifier) => specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
     const filter = new RegExp(`^(${escaped.join("|")})(?:/.*)?$`);
-
     return {
       name: "akan-backend-externalize-specifiers",
       setup(build) {
@@ -380,9 +392,5 @@ void run().catch((error) => {
     };
   }
 
-  static formatBytes(bytes: number): string {
-    if (bytes < 1024) return `${bytes}B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
-  }
+  static formatBytes = FontPruner.formatBytes;
 }

package/applicationTestPreload.ts

@@ -8,7 +8,7 @@ export interface SignalTestPreloadTarget {
 
 export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarget) {
   const candidates: string[] = [];
-  const addResolvedPackageCandidate = (basePath: string) => {
+  for (const basePath of [target.cwdPath, process.cwd(), path.dirname(Bun.main), import.meta.dir]) {
     try {
       candidates.push(
         path.join(path.dirname(Bun.resolveSync("akanjs/package.json", basePath)), SIGNAL_TEST_PRELOAD_PATH),
@@ -16,13 +16,7 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
     } catch {
       // Source workspaces and published installs can resolve Akan packages from different roots.
     }
-  };
-
-  addResolvedPackageCandidate(target.cwdPath);
-  addResolvedPackageCandidate(process.cwd());
-  addResolvedPackageCandidate(path.dirname(Bun.main));
-  addResolvedPackageCandidate(import.meta.dir);
-
+  }
   candidates.push(
     path.join(target.cwdPath, "../../node_modules/akanjs", SIGNAL_TEST_PRELOAD_PATH),
     path.join(target.cwdPath, "../../pkgs/akanjs", SIGNAL_TEST_PRELOAD_PATH),
@@ -33,10 +27,7 @@ export async function resolveSignalTestPreloadPath(target: SignalTestPreloadTarg
   );
 
   const uniqueCandidates = [...new Set(candidates)];
-  for (const candidate of uniqueCandidates) {
-    if (await Bun.file(candidate).exists()) return candidate;
-  }
-
+  for (const candidate of uniqueCandidates) if (await Bun.file(candidate).exists()) return candidate;
   throw new Error(
     `Failed to locate ${SIGNAL_TEST_PRELOAD_PATH} from ${target.cwdPath}.\nProbed paths:\n${uniqueCandidates
       .map((candidate) => `  - ${candidate}`)

package/artifact/implicitRootLayout.test.ts

@@ -1,25 +1,9 @@
-import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
+import { describe, expect, test } from "bun:test";
 import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
 import { resolveSsrPageEntries } from "./implicitRootLayout";
 
-const tempRoots: string[] = [];
-
-const makeTempRoot = async () => {
-  const root = await mkdtemp(path.join(os.tmpdir(), "akan-implicit-root-layout-"));
-  tempRoots.push(root);
-  return root;
-};
-
-const write = async (filePath: string, content: string) => {
-  await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, content);
-};
-
-afterEach(async () => {
-  await Promise.all(tempRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
-});
+const makeTempRoot = tempDirs("akan-implicit-root-layout-");
 
 describe("resolveSsrPageEntries", () => {
   test("inherits root layout static exports for grouped root boundaries", async () => {
@@ -31,11 +15,11 @@ describe("resolveSsrPageEntries", () => {
     await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
     await write(
       rootLayoutPath,
-      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const metadata = { title: "Root" };\n',
+      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const head = null;\n',
     );
     await write(
       groupedLayoutPath,
-      'export function generateMetadata() { return { title: "Home" }; }\nexport default function Layout({ children }) { return children; }\n',
+      "export function generateHead() { return null; }\nexport default function Layout({ children }) { return children; }\n",
     );
 
     const entries = await resolveSsrPageEntries({
@@ -54,15 +38,10 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
     expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
-    expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
-    expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");
-    expect(generatedSource).toContain("if (userLayout.metadata !== undefined) return userLayout.metadata;");
-    expect(generatedSource).toContain(
-      "if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);",
-    );
-    expect(generatedSource).toContain("return inheritedLayout.metadata;");
-    expect(generatedSource).not.toContain("Object.keys(userLayout.metadata)");
-    expect(generatedSource).not.toContain("Object.keys(inheritedLayout.metadata)");
+    expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
+    expect(generatedSource).toContain("if (userLayout.generateHead) return userLayout.generateHead(props);");
+    expect(generatedSource).toContain("return inheritedLayout.head;");
+    expect(generatedSource).not.toContain("generateMetadata");
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
@@ -171,4 +150,27 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("? await UserLayout({ params, searchParams, children })");
     expect(generatedSource).toContain("  return layout;\n}");
   });
+
+  test("prunes generated wrappers whose route file moved away", async () => {
+    const appRoot = await makeTempRoot();
+    const pageRoot = path.join(appRoot, "page");
+    await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
+    await write(path.join(pageRoot, "a", "_overrides.tsx"), "export default {};\n");
+    await write(path.join(pageRoot, "b", "_overrides.tsx"), "export default {};\n");
+    await write(path.join(pageRoot, "(home)", "_layout.tsx"), "export default ({ children }) => children;\n");
+    const resolve = async (pageKeys: string[]) =>
+      await resolveSsrPageEntries({ appCwdPath: appRoot, appName: "demo", pageKeys });
+    const generatedPaths = async (pageKeys: string[]) =>
+      (await resolve(pageKeys))
+        .filter((entry) => entry.moduleAbsPath.includes(`${path.sep}.akan${path.sep}`))
+        .map((entry) => entry.moduleAbsPath);
+
+    const before = await generatedPaths(["./(home)/_layout.tsx", "./a/_overrides.tsx", "./a/x.tsx"]);
+    const after = await generatedPaths(["./b/_overrides.tsx", "./b/y.tsx"]);
+
+    expect(before).toHaveLength(2);
+    for (const stale of before) expect(await Bun.file(stale).exists()).toBe(false);
+    expect(after).toHaveLength(2);
+    for (const fresh of after) expect(await Bun.file(fresh).exists()).toBe(true);
+  });
 });