@akanjs/devkit 2.4.1-rc.7 → 2.4.2-rc.0

package/executors.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, readlink, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -21,6 +21,8 @@ const writeJson = async (filePath: string, value: object) => {
   await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
 };
 
+const PAGE_SOURCE = "export default function Page() {\n  return null;\n}\n";
+
 const rootPackageJson = (extra: Partial<PackageJson> = {}): PackageJson => ({
   name: "fixture",
   version: "1.0.0",
@@ -271,6 +273,293 @@ describe("Workspace and app executor environment contracts", () => {
     expect((await stat(path.join(root, "dist/apps/demo/public"))).isDirectory()).toBe(true);
   });
 
+  describe("syncPages", () => {
+    // `AppExecutor.from` memoises by name, so each test needs a name no other test has used.
+    const makeAppWithLibPages = async (
+      appName: string,
+      { config = "export default {};\n", libs = { shared: ["about"] } as Record<string, string[] | null> } = {},
+    ) => {
+      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";
+      process.env.PORT_OFFSET = "0";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      for (const [lib, routes] of Object.entries(libs)) {
+        await mkdir(path.join(root, "libs", lib), { recursive: true });
+        for (const route of routes ?? []) {
+          await mkdir(path.join(root, "libs", lib, "page", route), { recursive: true });
+          await writeFile(path.join(root, "libs", lib, "page", route, "_index.tsx"), PAGE_SOURCE);
+        }
+      }
+      await mkdir(path.join(root, "apps", appName, "page"), { recursive: true });
+      await writeFile(path.join(root, "apps", appName, "akan.config.ts"), config);
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      return { root, app: AppExecutor.from(workspace, appName), appRoot: path.join(root, "apps", appName) };
+    };
+
+    test("links every lib dep that ships a page folder when enabled with true", async () => {
+      const { app, appRoot } = await makeAppWithLibPages("pages-true", {
+        config: "export default { syncPageLibs: true };\n",
+        libs: { shared: ["about"], util: null },
+      });
+      expect(await app.syncPages(["shared", "util"])).toBe(true);
+
+      const link = path.join(appRoot, "page/(libs)/(shared)");
+      expect((await lstat(link)).isSymbolicLink()).toBe(true);
+      expect(await lstat(path.join(appRoot, "page/(libs)/(util)")).catch(() => null)).toBeNull();
+      expect(await app.getPageKeys({ refresh: true })).toEqual(["./(libs)/(shared)/about/_index.tsx"]);
+    });
+
+    test("is a no-op when the links already match the config", async () => {
+      const { app } = await makeAppWithLibPages("pages-noop", {
+        config: "export default { syncPageLibs: ['shared'] };\n",
+      });
+      expect(await app.syncPages(["shared"])).toBe(true);
+      expect(await app.syncPages(["shared"])).toBe(false);
+    });
+
+    test("removes the synced page folder when disabled", async () => {
+      const { app, appRoot } = await makeAppWithLibPages("pages-disable", {
+        config: "export default { syncPageLibs: true };\n",
+      });
+      await app.syncPages(["shared"]);
+      expect((await lstat(path.join(appRoot, "page/(libs)/(shared)"))).isSymbolicLink()).toBe(true);
+
+      await writeFile(path.join(appRoot, "akan.config.ts"), "export default { syncPageLibs: false };\n");
+      await app.getConfig({ refresh: true });
+      expect(await app.syncPages(["shared"])).toBe(true);
+      expect(await lstat(path.join(appRoot, "page/(libs)")).catch(() => null)).toBeNull();
+    });
+
+    test("clears a link whose lib page folder was deleted, and keeps the workspace walkable", async () => {
+      const { root, app, appRoot } = await makeAppWithLibPages("pages-dangling", {
+        config: "export default { syncPageLibs: true };\n",
+      });
+      await app.syncPages(["shared"]);
+      await rm(path.join(root, "libs/shared/page"), { recursive: true, force: true });
+
+      // A dangling link sits 3 levels under apps/, which is inside the workspace app scan's walk.
+      expect(await app.workspace.getApps()).toEqual(["pages-dangling"]);
+      expect(await app.syncPages(["shared"])).toBe(true);
+      expect(await lstat(path.join(appRoot, "page/(libs)")).catch(() => null)).toBeNull();
+    });
+
+    test("rejects a lib the app does not depend on, and one without a page folder", async () => {
+      const { app } = await makeAppWithLibPages("pages-unknown", {
+        config: "export default { syncPageLibs: ['missing'] };\n",
+      });
+      await expect(app.syncPages(["shared"])).rejects.toThrow("does not depend on it");
+
+      const { app: noPage } = await makeAppWithLibPages("pages-nopage", {
+        config: "export default { syncPageLibs: ['util'] };\n",
+        libs: { util: null },
+      });
+      await expect(noPage.syncPages(["util"])).rejects.toThrow("libs/util/page does not exist");
+    });
+
+    test("links into every basePath when the app declares subRoutes", async () => {
+      const { app, appRoot } = await makeAppWithLibPages("pages-baseroutes", {
+        config: [
+          "export default {",
+          "  syncPageLibs: true,",
+          '  routes: [{ basePath: "admin", domains: {} }, { basePath: "shop", domains: {} }],',
+          "};",
+          "",
+        ].join("\n"),
+      });
+      await app.syncPages(["shared"]);
+
+      expect((await lstat(path.join(appRoot, "page/admin/(libs)/(shared)"))).isSymbolicLink()).toBe(true);
+      expect((await lstat(path.join(appRoot, "page/shop/(libs)/(shared)"))).isSymbolicLink()).toBe(true);
+      expect(await app.getPageKeys({ refresh: true })).toEqual([
+        "./admin/(libs)/(shared)/about/_index.tsx",
+        "./shop/(libs)/(shared)/about/_index.tsx",
+      ]);
+    });
+
+    test("rejects a lib route that collides with an app route", async () => {
+      const { app, appRoot } = await makeAppWithLibPages("pages-collide", {
+        config: "export default { syncPageLibs: true };\n",
+      });
+      await mkdir(path.join(appRoot, "page/(marketing)/about"), { recursive: true });
+      await writeFile(path.join(appRoot, "page/(marketing)/about/_index.tsx"), PAGE_SOURCE);
+      await app.syncPages(["shared"]);
+
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow('duplicate page route "/:lang/about"');
+    });
+
+    test("rejects two libs that mount the same route", async () => {
+      const { app } = await makeAppWithLibPages("pages-collide-libs", {
+        config: "export default { syncPageLibs: true };\n",
+        libs: { shared: ["about"], social: ["about"] },
+      });
+      await app.syncPages(["shared", "social"]);
+
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow('duplicate page route "/:lang/about"');
+    });
+  });
+
+  describe("syncAssets", () => {
+    // `AppExecutor.from` memoises by name, so each test needs a name no other test has used.
+    const makeAppWithLibAssets = async (appName: 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";
+      process.env.PORT_OFFSET = "0";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      await mkdir(path.join(root, "libs/shared/public"), { recursive: true });
+      await writeFile(path.join(root, "libs/shared/public/logo.png"), "logo");
+      await mkdir(path.join(root, "libs/shared/private"), { recursive: true });
+      await writeFile(path.join(root, "libs/shared/private/rules.json"), "{}");
+      await mkdir(path.join(root, "apps", appName), { recursive: true });
+      await writeFile(path.join(root, "apps", appName, "akan.config.ts"), "export default {};\n");
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      return { root, app: AppExecutor.from(workspace, appName), appRoot: path.join(root, "apps", appName) };
+    };
+
+    test("links lib assets into the app instead of copying them", async () => {
+      const { app, appRoot } = await makeAppWithLibAssets("assets-link");
+      await app.syncAssets(["shared"]);
+
+      const publicLink = path.join(appRoot, "public/libs/shared");
+      const privateLink = path.join(appRoot, "private/libs/shared");
+      expect((await lstat(publicLink)).isSymbolicLink()).toBe(true);
+      expect((await lstat(privateLink)).isSymbolicLink()).toBe(true);
+      expect(await readFile(path.join(publicLink, "logo.png"), "utf8")).toBe("logo");
+      expect(await readFile(path.join(privateLink, "rules.json"), "utf8")).toBe("{}");
+      if (process.platform !== "win32") expect(path.isAbsolute(await readlink(publicLink))).toBe(false);
+    });
+
+    test("drops links for deps that no longer ship assets", async () => {
+      const { app, appRoot } = await makeAppWithLibAssets("assets-drop");
+      await app.syncAssets(["shared"]);
+      await app.syncAssets([]);
+
+      expect(await lstat(path.join(appRoot, "public/libs")).catch(() => null)).toBeNull();
+      expect(await lstat(path.join(appRoot, "private/libs")).catch(() => null)).toBeNull();
+    });
+
+    test("removes a link whose target disappeared", async () => {
+      const { root, app, appRoot } = await makeAppWithLibAssets("assets-dangling");
+      await app.syncAssets(["shared"]);
+      await rm(path.join(root, "libs/shared/public"), { recursive: true, force: true });
+
+      const publicLink = path.join(appRoot, "public/libs/shared");
+      await app.removeDir(publicLink);
+      expect(await lstat(publicLink).catch(() => null)).toBeNull();
+    });
+
+    test("removing a linked dir with a trailing separator keeps the lib source", async () => {
+      const { root, app, appRoot } = await makeAppWithLibAssets("assets-trailing");
+      await app.syncAssets(["shared"]);
+
+      const publicLink = path.join(appRoot, "public/libs/shared");
+      await app.removeDir(`${publicLink}${path.sep}`);
+      expect(await lstat(publicLink).catch(() => null)).toBeNull();
+      expect(await readFile(path.join(root, "libs/shared/public/logo.png"), "utf8")).toBe("logo");
+    });
+
+    test("materializes linked lib assets into dist on build", async () => {
+      const { root, app } = await makeAppWithLibAssets("assets-dist");
+      await app.syncAssets(["shared"]);
+      await app.prepareCommand("build");
+
+      const distPublicLib = path.join(root, "dist/apps/assets-dist/public/libs/shared");
+      expect((await lstat(distPublicLib)).isSymbolicLink()).toBe(false);
+      expect(await readFile(path.join(distPublicLib, "logo.png"), "utf8")).toBe("logo");
+      expect(await readFile(path.join(root, "dist/apps/assets-dist/private/libs/shared/rules.json"), "utf8")).toBe(
+        "{}",
+      );
+    });
+  });
+
+  describe("devOnly routes", () => {
+    // `AppExecutor.from` memoises by name, so each test needs a name no other test has used.
+    const makeAppWithRoutes = async (appName: string, routes: 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";
+      process.env.PORT_OFFSET = "0";
+      await writeJson(path.join(root, "package.json"), rootPackageJson());
+      await mkdir(path.join(root, "apps", appName, "page"), { recursive: true });
+      await writeFile(path.join(root, "apps", appName, "akan.config.ts"), "export default {};\n");
+      for (const [rel, source] of Object.entries(routes)) {
+        const filePath = path.join(root, "apps", appName, "page", rel);
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(filePath, source);
+      }
+      const workspace = new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" });
+      return { root, app: AppExecutor.from(workspace, appName) };
+    };
+    const devOnlyPage = `export const pageConfig = { devOnly: true };\n${PAGE_SOURCE}`;
+    const layout = "export default function Layout({ children }) { return children; }\n";
+    const devOnlyLayout = `export const pageConfig = { devOnly: true };\n${layout}`;
+
+    test("keeps dev-only routes outside of a build", async () => {
+      const { app } = await makeAppWithRoutes("devonly-start", {
+        "_index.tsx": PAGE_SOURCE,
+        "debug/_index.tsx": devOnlyPage,
+      });
+
+      expect(await app.getPageKeys({ refresh: true })).toEqual(["./_index.tsx", "./debug/_index.tsx"]);
+    });
+
+    test("drops a dev-only page from the build", async () => {
+      const { app } = await makeAppWithRoutes("devonly-page", {
+        "_index.tsx": PAGE_SOURCE,
+        "debug/_index.tsx": devOnlyPage,
+      });
+      await app.prepareCommand("build");
+
+      expect(await app.getPageKeys()).toEqual(["./_index.tsx"]);
+    });
+
+    test("drops a dev-only layout together with every route under it", async () => {
+      const { app } = await makeAppWithRoutes("devonly-layout", {
+        "_index.tsx": PAGE_SOURCE,
+        "(dev)/_layout.tsx": devOnlyLayout,
+        "(dev)/debug/_index.tsx": PAGE_SOURCE,
+        "(dev)/debug/deep/_index.tsx": PAGE_SOURCE,
+        "keep/_index.tsx": PAGE_SOURCE,
+      });
+      await app.prepareCommand("build");
+
+      expect(await app.getPageKeys()).toEqual(["./_index.tsx", "./keep/_index.tsx"]);
+    });
+
+    test("treats devOnly: false as a normal route", async () => {
+      const { app } = await makeAppWithRoutes("devonly-false", {
+        "_index.tsx": `export const pageConfig = { devOnly: false, cache: true };\n${PAGE_SOURCE}`,
+      });
+      await app.prepareCommand("build");
+
+      expect(await app.getPageKeys()).toEqual(["./_index.tsx"]);
+    });
+
+    test("rejects a devOnly value the build cannot read statically", async () => {
+      const { app } = await makeAppWithRoutes("devonly-dynamic", {
+        "_index.tsx": `export const pageConfig = { devOnly: process.env.NODE_ENV !== "production" };\n${PAGE_SOURCE}`,
+      });
+
+      await expect(app.getPageKeys({ refresh: true })).rejects.toThrow(
+        "pageConfig.devOnly must be a literal true or false",
+      );
+    });
+
+    test("reads devOnly through a satisfies annotation", async () => {
+      const { app } = await makeAppWithRoutes("devonly-satisfies", {
+        "_index.tsx": PAGE_SOURCE,
+        "debug/_index.tsx": `export const pageConfig = { devOnly: true } satisfies { devOnly: boolean };\n${PAGE_SOURCE}`,
+      });
+      await app.prepareCommand("build");
+
+      expect(await app.getPageKeys()).toEqual(["./_index.tsx"]);
+    });
+  });
+
   describe("getDevPort", () => {
     const makeWorkspaceWithApps = async (names: string[]) => {
       const root = await makeTempRoot();

package/executors.ts

@@ -8,7 +8,16 @@ import {
   spawn,
 } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { copyFile, mkdir, readdir as readDirEntries, stat } from "node:fs/promises";
+import {
+  copyFile,
+  cp as cpEntry,
+  mkdir,
+  readdir as readDirEntries,
+  realpath,
+  rm,
+  stat,
+  symlink,
+} from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { AkanPlugin, AkanSyncContext, PluginRuntimeContext } from "akanjs";
@@ -33,6 +42,15 @@ import { Spinner } from "./spinner";
 import type { TypeChecker } from "./typeChecker";
 import type { FileContent, PackageJson, TsConfigJson } from "./types";
 
+export interface PageRoot {
+  /** App-relative location of the route files, i.e. the symlink for a synced lib. */
+  dir: string;
+  /** Where the files actually live, which is what a file watcher reports. */
+  realDir: string;
+  /** Prefix that turns a `dir`-relative path into an app page key (empty for the app's own `page`). */
+  keyPrefix: string;
+}
+
 const staticTemplateFileExtensions = new Set([
   ".avif",
   ".bmp",
@@ -389,8 +407,10 @@ export class Executor {
     return this;
   }
   async removeDir(dirPath: string) {
-    const readPath = this.getPath(dirPath);
-    if (await FileSys.dirExists(readPath)) await $`rm -rf ${readPath}`;
+    //* XXX: `path.join(…, ".")` drops a trailing separator — `rm -rf link/` resolves through a symlink
+    //* and wipes its target, while `rm -rf link` only unlinks it.
+    const readPath = path.join(this.getPath(dirPath), ".");
+    if (await FileSys.entryExists(readPath)) await rm(readPath, { recursive: true, force: true });
     this.logger.verbose(`Remove directory ${readPath}`);
     return this;
   }
@@ -435,13 +455,16 @@ export class Executor {
     const readPath = this.getPath(filePath);
     return await FileSys.readJson<object>(readPath);
   }
-  async cp(srcPath: string, destPath: string) {
+  async cp(srcPath: string, destPath: string, { dereference = false }: { dereference?: boolean } = {}) {
     const src = this.getPath(srcPath);
     const dest = this.getPath(destPath);
     if (!(await FileSys.exists(src))) return;
     const isDirectory = (await stat(src)).isDirectory();
     if (!(await FileSys.exists(dest)) && isDirectory) await mkdir(dest, { recursive: true });
-    await $`cp -r ${src}${isDirectory ? "/." : ""} ${dest}`;
+    //* `cp -r` keeps symlinks on GNU coreutils but follows them on macOS, so anything that must land as
+    //* real files regardless of platform has to say so explicitly.
+    if (dereference) await cpEntry(src, dest, { recursive: isDirectory, dereference: true, force: true });
+    else await $`cp -r ${src}${isDirectory ? "/." : ""} ${dest}`;
   }
   log(msg: string) {
     this.logger.info(msg);
@@ -890,7 +913,9 @@ export class WorkspaceExecutor extends Executor {
         dirs.map(async (dir) => {
           if (AVOID_DIRS.includes(dir)) return;
           const dirPath = path.join(dirname, dir);
-          if ((await stat(dirPath)).isDirectory()) {
+          //* A dangling symlink (e.g. a synced lib page whose source was deleted) must not fail the walk —
+          //* this runs for `getApps`, so throwing here would break every command until it is repaired.
+          if (await FileSys.dirExists(dirPath)) {
             const hasTargetFile = await FileSys.fileExists(path.join(dirPath, targetFilename));
             if (hasTargetFile) results.push(`${prefix}${dir}`);
             if (maxDepth > 0) await getDirs(dirPath, maxDepth - 1, results, `${prefix}${dir}/`);
@@ -1299,11 +1324,17 @@ export class AppExecutor extends SysExecutor {
     };
     Object.assign(process.env, routeEnv);
     if (type === "build") {
+      //* `scanSync` already read the route set, and it reads it unfiltered — dev-only routes are still
+      //* 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 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.
       await Promise.all([
-        this.cp("private", `${this.dist.cwdPath}/private`),
-        this.cp("public", `${this.dist.cwdPath}/public`),
+        this.cp("private", `${this.dist.cwdPath}/private`, { dereference: true }),
+        this.cp("public", `${this.dist.cwdPath}/public`, { dereference: true }),
       ]);
     } else await this.removeDir(".akan");
     const devPort = type === "start" ? (await this.getDevPort()).toString() : undefined;
@@ -1351,75 +1382,192 @@ export class AppExecutor extends SysExecutor {
   }
 
   #pageKeys: string[] | null = null;
+  /** Set once `prepareCommand("build")` runs, so every later consumer of the route set agrees on it. */
+  #excludeDevOnlyPages = false;
   async getPageKeys({ refresh }: { refresh?: boolean } = {}): Promise<string[]> {
     if (this.#pageKeys && !refresh) return this.#pageKeys;
     const akanConfig = await this.getConfig();
     const glob = new Bun.Glob("**/*");
     const pageKeys: string[] = [];
-    const pageDir = `${this.cwdPath}/page`;
-    if (!(await FileSys.dirExists(pageDir))) {
-      this.#pageKeys = [];
-      return this.#pageKeys;
-    }
-    for await (const rel of glob.scan({
-      cwd: pageDir,
-      absolute: false,
-      onlyFiles: true,
-    })) {
-      const segments = rel.split(path.sep);
-      if (segments.some((s) => s === "node_modules")) continue;
-      const posix = segments.join("/");
-      const absPath = path.join(pageDir, posix);
-      validatePageSourceFile(posix, { filePath: absPath });
-      if (!isRouteSourceFile(posix)) continue;
-      const key = `./${posix}`;
-      validateSubRoutePageKey(key, akanConfig.basePaths, {
-        appName: this.name,
-        filePath: absPath,
-      });
-      const parsed = parseRouteModuleKey(key);
-      if (parsed.isInternalRootLayout) {
-        throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
+    const owners = new Map<string, { absPath: string; fromLib: boolean }>();
+    const devOnlyKeys = new Set<string>();
+    const devOnlyDirs: string[] = [];
+    for (const root of await this.getPageRoots()) {
+      if (!(await FileSys.dirExists(root.dir))) continue;
+      for await (const rel of glob.scan({
+        cwd: root.dir,
+        absolute: false,
+        onlyFiles: true,
+      })) {
+        const segments = rel.split(path.sep);
+        if (segments.some((s) => s === "node_modules")) continue;
+        const posix = `${root.keyPrefix}${segments.join("/")}`;
+        const absPath = path.join(root.dir, ...segments);
+        validatePageSourceFile(posix, { filePath: absPath });
+        if (!isRouteSourceFile(posix)) continue;
+        const key = `./${posix}`;
+        validateSubRoutePageKey(key, akanConfig.basePaths, {
+          appName: this.name,
+          filePath: absPath,
+        });
+        const parsed = parseRouteModuleKey(key);
+        if (parsed.isInternalRootLayout) {
+          throw new Error(`[route-convention] __root_layout is reserved for Akan.js generated root layout: ${absPath}`);
+        }
+        const fromLib = !!root.keyPrefix;
+        const routeId = `${parsed.kind}:${parsed.pattern}`;
+        const owner = owners.get(routeId);
+        //* App-owned routes have always been allowed to collide (two groups, one pattern); only report a
+        //* collision once a synced lib is involved, where neither side can see the other.
+        if (owner && (owner.fromLib || fromLib)) {
+          throw new Error(
+            `[route-convention] duplicate ${parsed.kind} route "${parsed.pattern}" in app "${this.name}":\n- ${owner.absPath}\n- ${absPath}`,
+          );
+        }
+        if (!owner) owners.set(routeId, { absPath, fromLib });
+        const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
+        const routeSource = await Bun.file(absPath).text();
+        const validator = await AppExecutor.#getRouteSourceValidator();
+        if (parsed.kind === "overrides") validator.validateOverridesSourceExports(routeSource, absPath);
+        else {
+          const info = validator.validateRouteSourceExports(routeSource, absPath, parsed.kind, {
+            rootLayout: isRootLayout,
+          });
+          if (info.devOnly) {
+            devOnlyKeys.add(key);
+            //* A layout owns its directory, so a dev-only one takes the whole subtree with it — leaving its
+            //* pages behind would ship them stripped of the chrome they were written under.
+            if (parsed.kind === "layout") devOnlyDirs.push(key.replace(/[^/]+$/, ""));
+          }
+        }
+        pageKeys.push(key);
       }
-      const isRootLayout = parsed.kind === "layout" && parsed.moduleSegments.at(-1) === "_layout";
-      const routeSource = await Bun.file(absPath).text();
-      const validator = await AppExecutor.#getRouteSourceValidator();
-      if (parsed.kind === "overrides") validator.validateOverridesSourceExports(routeSource, absPath);
-      else validator.validateRouteSourceExports(routeSource, absPath, parsed.kind, { rootLayout: isRootLayout });
-      pageKeys.push(key);
     }
     pageKeys.sort();
-    this.#pageKeys = pageKeys;
+    this.#pageKeys = this.#excludeDevOnlyPages ? this.#dropDevOnlyPages(pageKeys, devOnlyKeys, devOnlyDirs) : pageKeys;
     return this.#pageKeys;
   }
+  #dropDevOnlyPages(pageKeys: string[], devOnlyKeys: Set<string>, devOnlyDirs: string[]): string[] {
+    if (!devOnlyKeys.size) return pageKeys;
+    const isDevOnly = (key: string) => devOnlyKeys.has(key) || devOnlyDirs.some((dir) => key.startsWith(dir));
+    const dropped = pageKeys.filter(isDevOnly);
+    this.log(`[route] excluded ${dropped.length} dev-only route file(s) from the build: ${dropped.join(", ")}`);
+    return pageKeys.filter((key) => !isDevOnly(key));
+  }
+  /**
+   * Every directory that contributes route files, as `page`-relative key prefixes. Lib roots are the
+   * symlinks `syncPages` created, so route keys stay app-relative while `realDir` is what a file watcher
+   * reports. Enumeration never crosses a symlink (neither Bun's glob nor TypeScript's `include` does),
+   * which is why linked page folders have to be listed here instead of found by walking `page`.
+   */
+  async getPageRoots(): Promise<PageRoot[]> {
+    const akanConfig = await this.getConfig();
+    const pageDir = `${this.cwdPath}/page`;
+    const roots: PageRoot[] = [{ dir: pageDir, realDir: pageDir, keyPrefix: "" }];
+    for (const parent of AppExecutor.#pageLibParents(akanConfig.basePaths)) {
+      const libsDir = `${pageDir}/${parent}${AppExecutor.#pageLibsDir}`;
+      const entries = await readDirEntries(libsDir).catch(() => [] as string[]);
+      for (const entry of entries.sort()) {
+        const dir = `${libsDir}/${entry}`;
+        if (!(await FileSys.dirExists(dir))) continue;
+        roots.push({ dir, realDir: await realpath(dir), keyPrefix: `${parent}${AppExecutor.#pageLibsDir}/${entry}/` });
+      }
+    }
+    return roots;
+  }
   setPageKeys(pageKeys: string[]) {
     this.#pageKeys = pageKeys;
   }
 
-  async syncAssets(libDeps: string[]) {
-    const projectPublicPath = `${this.cwdPath}/public`;
-    const projectAssetsPath = `${this.cwdPath}/private`;
-    const projectPublicLibPath = `${projectPublicPath}/libs`;
-    const projectAssetsLibPath = `${projectAssetsPath}/libs`;
-    await Promise.all([this.removeDir(projectPublicLibPath), this.removeDir(projectAssetsLibPath)]);
-    const targetPublicDeps = [] as string[];
-    for (const dep of libDeps) {
-      if (await this.exists(`${this.workspace.workspaceRoot}/libs/${dep}/public`)) targetPublicDeps.push(dep);
+  static readonly #pageLibsDir = "(libs)";
+  /** Where `(libs)` may live: once at the page root, or once per basePath when the app declares subRoutes. */
+  static #pageLibParents(basePaths: Iterable<string>): string[] {
+    const parents = [...basePaths].map((basePath) => `${basePath}/`);
+    return parents.length ? parents : [""];
+  }
+  /** Returns whether the linked page set changed, which is what makes the app's route keys stale. */
+  async syncPages(libDeps: string[]): Promise<boolean> {
+    const akanConfig = await this.getConfig();
+    const parents = AppExecutor.#pageLibParents(akanConfig.basePaths);
+    const libs = await this.#resolvePageLibs(akanConfig.syncPageLibs, libDeps);
+    //* Listed rather than taken from `getPageRoots`, which drops links whose target is gone — those are
+    //* exactly the ones a sync has to clean up.
+    const linked = (
+      await Promise.all(
+        parents.map(async (parent) => {
+          const libsDir = `${this.cwdPath}/page/${parent}${AppExecutor.#pageLibsDir}`;
+          const entries = await readDirEntries(libsDir).catch(() => [] as string[]);
+          return entries.map((entry) => `${parent}${AppExecutor.#pageLibsDir}/${entry}/`);
+        }),
+      )
+    ).flat();
+    const wanted = parents.flatMap((parent) => libs.map((lib) => `${parent}${AppExecutor.#pageLibsDir}/(${lib})/`));
+    if (linked.sort().join(",") === wanted.sort().join(",")) return false;
+    await Promise.all(
+      parents.map((parent) => this.removeDir(`${this.cwdPath}/page/${parent}${AppExecutor.#pageLibsDir}`)),
+    );
+    for (const parent of parents) {
+      if (!libs.length) break;
+      const libsDir = `${this.cwdPath}/page/${parent}${AppExecutor.#pageLibsDir}`;
+      await this.mkdir(libsDir);
+      await Promise.all(
+        libs.map((lib) =>
+          AppExecutor.#linkLibAsset(`${this.workspace.workspaceRoot}/libs/${lib}/page`, `${libsDir}/(${lib})`),
+        ),
+      );
+    }
+    this.#pageKeys = null;
+    return true;
+  }
+  async #resolvePageLibs(syncPageLibs: string[] | boolean, libDeps: string[]): Promise<string[]> {
+    if (!syncPageLibs) return [];
+    const hasPageDir = async (lib: string) =>
+      await FileSys.dirExists(`${this.workspace.workspaceRoot}/libs/${lib}/page`);
+    if (syncPageLibs === true) {
+      const libs: string[] = [];
+      for (const lib of libDeps) if (await hasPageDir(lib)) libs.push(lib);
+      return libs;
     }
-    const targetAssetsDeps = [] as string[];
+    for (const lib of syncPageLibs) {
+      if (!libDeps.includes(lib))
+        throw new Error(
+          `[syncPageLibs] app "${this.name}" lists lib "${lib}" but does not depend on it (deps: ${libDeps.join(", ") || "none"})`,
+        );
+      if (!(await hasPageDir(lib)))
+        throw new Error(`[syncPageLibs] app "${this.name}" lists lib "${lib}" but libs/${lib}/page does not exist`);
+    }
+    return [...syncPageLibs];
+  }
+  async syncAssets(libDeps: string[]) {
+    await Promise.all((["public", "private"] as const).map((facet) => this.#syncLibAssets(facet, libDeps)));
+  }
+  async #syncLibAssets(facet: "public" | "private", libDeps: string[]) {
+    const libLinkPath = `${this.cwdPath}/${facet}/libs`;
+    await this.removeDir(libLinkPath);
+    const targetDeps = [] as string[];
     for (const dep of libDeps) {
-      if (await this.exists(`${this.workspace.workspaceRoot}/libs/${dep}/private`)) targetAssetsDeps.push(dep);
+      if (await this.exists(`${this.workspace.workspaceRoot}/libs/${dep}/${facet}`)) targetDeps.push(dep);
     }
-    await Promise.all(targetPublicDeps.map((dep) => this.mkdir(`${projectPublicLibPath}/${dep}`)));
-    await Promise.all(targetAssetsDeps.map((dep) => this.mkdir(`${projectAssetsLibPath}/${dep}`)));
-    await Promise.all([
-      ...targetPublicDeps.map((dep) =>
-        this.cp(`${this.workspace.workspaceRoot}/libs/${dep}/public`, `${projectPublicLibPath}/${dep}`),
-      ),
-      ...targetAssetsDeps.map((dep) =>
-        this.cp(`${this.workspace.workspaceRoot}/libs/${dep}/private`, `${projectAssetsLibPath}/${dep}`),
+    if (!targetDeps.length) return;
+    await this.mkdir(libLinkPath);
+    await Promise.all(
+      targetDeps.map((dep) =>
+        AppExecutor.#linkLibAsset(`${this.workspace.workspaceRoot}/libs/${dep}/${facet}`, `${libLinkPath}/${dep}`),
       ),
-    ]);
+    );
+  }
+  static async #linkLibAsset(targetPath: string, linkPath: string) {
+    //* A relative link keeps working when the workspace is mounted at another path (containers, CI);
+    //* Windows junctions are the exception and resolve their target as an absolute path.
+    const isWindows = process.platform === "win32";
+    try {
+      const target = isWindows ? targetPath : path.relative(path.dirname(linkPath), targetPath);
+      await symlink(target, linkPath, isWindows ? "junction" : "dir");
+    } catch (error) {
+      if (!isWindows) throw error;
+      await mkdir(linkPath, { recursive: true });
+      await cpEntry(targetPath, linkPath, { recursive: true, dereference: true, force: true });
+    }
   }
   async scanSync({ refresh = false, write = true }: { refresh?: boolean; write?: boolean } = {}) {
     const scanInfo = (await this.scan({
@@ -1428,6 +1576,9 @@ export class AppExecutor extends SysExecutor {
       writeLib: write,
     })) as AppInfo;
     if (write) await this.syncAssets(scanInfo.getScanResult().libDeps);
+    //* `scan` read the routes off the page tree this sync may be about to change, so re-read them.
+    if (write && (await this.syncPages(scanInfo.getScanResult().libDeps)))
+      scanInfo.setRoutes(await this.getPageKeys({ refresh: true }));
     if (write) await this.#runPluginSyncAssets();
     return scanInfo;
   }