@akanjs/devkit 2.4.1 → 2.4.2-rc.0

package/akanConfig/akanConfig.ts

@@ -182,6 +182,8 @@ export class AkanAppConfig implements AppConfigResult {
   /** True only when the app's akan.config.ts explicitly declares a `mobile` section (vs. the synthesized default). */
   hasMobileConfig: boolean;
   secrets: string[];
+  /** Raw setting; resolved against the app's lib deps at sync time (see `AppExecutor.syncPages`). */
+  syncPageLibs: string[] | boolean;
   baseDevEnv: BaseDevEnv;
   libs: string[];
   /** Live-only: plugins declared in this app's `akan.config.ts` (never serialized). */
@@ -219,6 +221,7 @@ export class AkanAppConfig implements AppConfigResult {
     process.env.AKAN_PUBLIC_LOCALES = this.i18n.locales.join(",");
     this.publicEnv = (config?.publicEnv as string[] | undefined) ?? ([] as string[]);
     this.secrets = (config?.secrets as string[] | undefined) ?? ([] as string[]);
+    this.syncPageLibs = (config?.syncPageLibs as string[] | boolean | undefined) ?? false;
     this.hasMobileConfig = Boolean(config.mobile);
     this.mobile = this.#resolveMobileConfig(config.mobile);
     this.docker = this.#makeDockerContent(config?.docker ?? {});

package/applicationBuildRunner.ts

@@ -272,6 +272,13 @@ void run().catch((error) => {
   async #writeTypecheckTsconfig({ incremental = true }: TypecheckOptions = {}) {
     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.
+    const libPageIncludes = (await this.#app.getPageRoots())
+      .filter((root) => root.keyPrefix)
+      .flatMap((root) => {
+        const rel = path.relative(typecheckDir, root.realDir).split(path.sep).join("/");
+        return [`${rel}/**/*.ts`, `${rel}/**/*.tsx`];
+      });
     const tsconfig = {
       extends: "../../tsconfig.json",
       compilerOptions: {
@@ -285,6 +292,7 @@ void run().catch((error) => {
         "../../client.ts",
         "../../page/**/*.ts",
         "../../page/**/*.tsx",
+        ...libPageIncludes,
         "../../../../pkgs/akanjs/*/types/**/*.d.ts",
       ],
       references: [],

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;
   }

package/fileSys.ts

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { lstat, stat } from "node:fs/promises";
 import { Logger } from "akanjs/common";
 
 export class FileSys {
@@ -16,6 +16,12 @@ export class FileSys {
       .then(() => true)
       .catch(() => false);
   }
+  //* Unlike `exists`, this reports a symlink whose target is gone, so stale links can be cleaned up.
+  static async entryExists(path: string) {
+    return await lstat(path)
+      .then(() => true)
+      .catch(() => false);
+  }
   static async readText(path: string) {
     return await Bun.file(path).text();
   }

package/frontendBuild/fontOptimizer.ts

@@ -388,12 +388,20 @@ export class FontOptimizer {
   }
 
   async #collectAutoSubsetText() {
-    const roots = ["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir));
+    //* Synced lib pages hold app-visible text too, and a glob never crosses the symlink that mounts them.
+    const libPageRoots = (await this.#app.getPageRoots()).filter((root) => root.keyPrefix).map((root) => root.dir);
+    const roots = [...["page", "ui"].map((dir) => path.join(this.#app.cwdPath, dir)), ...libPageRoots];
     const glob = new Bun.Glob("**/*.{ts,tsx,js,jsx,html,md}");
     const parts: string[] = [];
     await Promise.all(
       roots.map(async (root) => {
-        if (!(await Bun.file(root).exists())) return;
+        if (
+          !(await stat(root).then(
+            (entry) => entry.isDirectory(),
+            () => false,
+          ))
+        )
+          return;
         for await (const filePath of glob.scan({ cwd: root, absolute: true })) {
           parts.push(await Bun.file(filePath).text());
         }

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 // (~40MB) into a process that then holds them for the whole dev session. Phase 2 moved css compilation
 // into the batch worker, so this process has no use for them — `entryModuleGraph.test.ts` keeps it that way.
 import type { App } from "@akanjs/devkit/commandDecorators";
-import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
+import { AppExecutor, type PageRoot, WorkspaceExecutor } from "@akanjs/devkit/executors";
 import { AutoImportSync } from "@akanjs/devkit/frontendBuild/autoImportSync";
 import type { ClientEntryDiscovery } from "@akanjs/devkit/frontendBuild/clientBuildTypes";
 import { GraphClientEntryDiscovery } from "@akanjs/devkit/frontendBuild/clientEntryDiscovery";
@@ -209,23 +209,31 @@ class IncrementalBuilder {
   get shuttingDown(): boolean {
     return this.#shuttingDown;
   }
-  batchTouchesPagesTree(appDir: string, batch: ChangeBatch): boolean {
-    const absAppDir = path.resolve(appDir);
+  //* Watch events name the file's real path, so synced lib pages are matched by `realDir` while their
+  //* page key still carries the app-relative `(libs)/(<lib>)` prefix.
+  static #matchPageRoot(roots: PageRoot[], abs: string): PageRoot | null {
+    for (const root of roots) {
+      const absRoot = path.resolve(root.realDir);
+      if (abs === absRoot || abs.startsWith(`${absRoot}${path.sep}`)) return root;
+    }
+    return null;
+  }
+  batchTouchesPagesTree(roots: PageRoot[], batch: ChangeBatch): boolean {
     for (const f of batch.files) {
       const abs = path.resolve(f);
-      if (!abs.startsWith(`${absAppDir}${path.sep}`) && abs !== absAppDir) continue;
+      if (!IncrementalBuilder.#matchPageRoot(roots, abs)) continue;
       if (/\.(tsx|ts|jsx|js)$/.test(abs)) return true;
     }
     return false;
   }
-  async batchMayChangePageKeys(appDir: string, batch: ChangeBatch): Promise<boolean> {
-    const absAppDir = path.resolve(appDir);
+  async batchMayChangePageKeys(roots: PageRoot[], batch: ChangeBatch): Promise<boolean> {
     const pageKeys = new Set((await this.#app.getPageKeys()).map((key) => path.normalize(key)));
     for (const f of batch.files) {
       const abs = path.resolve(f);
-      if (!abs.startsWith(`${absAppDir}${path.sep}`) && abs !== absAppDir) continue;
+      const root = IncrementalBuilder.#matchPageRoot(roots, abs);
+      if (!root) continue;
       if (!/\.(tsx|ts|jsx|js)$/.test(abs)) continue;
-      const rel = path.normalize(path.relative(absAppDir, abs));
+      const rel = path.normalize(`${root.keyPrefix}${path.relative(path.resolve(root.realDir), abs)}`);
       if (!(await Bun.file(abs).exists()) || !pageKeys.has(rel)) return true;
     }
     return false;
@@ -265,13 +273,13 @@ class IncrementalBuilder {
     }, 150);
   }
   async installWatcher() {
-    const [appDir, artifactDir] = [`${this.#app.cwdPath}/page`, this.#artifactDir];
+    const artifactDir = this.#artifactDir;
     const roots = await new WatchRootResolver(this.#app).resolve();
     const watcher = new HmrWatcher({
       roots,
       logger: this.#logger,
       onBatch: async (batch: ChangeBatch) => {
-        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(appDir, artifactDir, batch));
+        await this.#enqueueWork("hmr-batch", async () => this.#handleWatchBatch(artifactDir, batch));
       },
     });
     await watcher.start();
@@ -279,7 +287,7 @@ class IncrementalBuilder {
     this.#logger.verbose(`watching ${roots.length} roots`);
   }
 
-  async #handleWatchBatch(appDir: string, artifactDir: string, batch: ChangeBatch) {
+  async #handleWatchBatch(artifactDir: string, batch: ChangeBatch) {
     const rawKinds = new Set(batch.kinds);
     if (rawKinds.size === 0) return;
     const generation = ++this.#generation;
@@ -330,11 +338,12 @@ class IncrementalBuilder {
       this.#logger.verbose(`client rebuild skipped; devPlan actions=${devPlan.actions.join(",") || "(none)"}`);
     }
 
-    if (kinds.includes("code") && rebuildClient && (await this.batchMayChangePageKeys(appDir, expandedBatch))) {
+    const pageRoots = await this.#app.getPageRoots();
+    if (kinds.includes("code") && rebuildClient && (await this.batchMayChangePageKeys(pageRoots, expandedBatch))) {
       const started = Date.now();
       await this.#app.getPageKeys({ refresh: true });
       this.#logger.verbose(`pageKeys updated, app pageKeys are refreshed (${Date.now() - started}ms)`);
-    } else if (kinds.includes("code") && rebuildClient && this.batchTouchesPagesTree(appDir, expandedBatch)) {
+    } else if (kinds.includes("code") && rebuildClient && this.batchTouchesPagesTree(pageRoots, expandedBatch)) {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.1",
+  "version": "2.4.2-rc.0",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.1",
+    "akanjs": "2.4.2-rc.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/packageExportsMap.ts

@@ -67,7 +67,7 @@ export class PackageExportsMap {
     for (const { prefix, suffix, target } of this.#patterns) {
       if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
       if (subpath.length < prefix.length + suffix.length) continue;
-      return target.replace("*", subpath.slice(prefix.length, subpath.length - suffix.length));
+      return target.replace(/\*/g, subpath.slice(prefix.length, subpath.length - suffix.length));
     }
     return null;
   }

package/routeSourceValidator.ts

@@ -1,5 +1,11 @@
 import ts from "typescript";
 
+/** What the build needs out of a route module without evaluating it. */
+export interface RouteSourceInfo {
+  /** `pageConfig.devOnly === true`, read straight off the AST. */
+  devOnly: boolean;
+}
+
 /**
  * Static enforcement of the `page/` route conventions, split out of `executors.ts` so that importing
  * an executor does not pull `typescript` (+65MB resident) into the module graph. Both validators need
@@ -53,7 +59,7 @@ export class RouteSourceValidator {
     filePath: string,
     kind: "page" | "layout",
     options: { rootLayout?: boolean } = {},
-  ) {
+  ): RouteSourceInfo {
     const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
     const allowed =
       kind === "page"
@@ -117,6 +123,50 @@ export class RouteSourceValidator {
     if (exported.has("metadata") && exported.has("generateMetadata")) {
       throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${filePath}`);
     }
+    return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
+  }
+
+  /**
+   * `devOnly` decides whether the route exists in the production build at all, so it is read from the
+   * source rather than from an evaluated module — the build never imports route files to enumerate them.
+   * That is why only a literal is accepted: anything the parser cannot settle would otherwise ship a
+   * route the author believed was excluded.
+   */
+  static #readDevOnly(sourceFile: ts.SourceFile, filePath: string): boolean {
+    for (const statement of sourceFile.statements) {
+      if (!ts.isVariableStatement(statement)) continue;
+      const isExported = ts.getModifiers(statement)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+      if (!isExported) continue;
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || declaration.name.text !== "pageConfig") continue;
+        const initializer = RouteSourceValidator.#unwrapExpression(declaration.initializer);
+        if (!initializer || !ts.isObjectLiteralExpression(initializer)) continue;
+        for (const property of initializer.properties) {
+          if (!ts.isPropertyAssignment(property)) continue;
+          const name = property.name;
+          const key = ts.isIdentifier(name) ? name.text : ts.isStringLiteral(name) ? name.text : null;
+          if (key !== "devOnly") continue;
+          const value = RouteSourceValidator.#unwrapExpression(property.initializer);
+          if (value?.kind === ts.SyntaxKind.TrueKeyword) return true;
+          if (value?.kind === ts.SyntaxKind.FalseKeyword) return false;
+          throw new Error(
+            `[route-convention] pageConfig.devOnly must be a literal true or false in ${filePath} — the build reads it without evaluating the module`,
+          );
+        }
+      }
+    }
+    return false;
+  }
+
+  static #unwrapExpression(expression?: ts.Expression): ts.Expression | undefined {
+    let current = expression;
+    while (
+      current &&
+      (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current))
+    ) {
+      current = current.expression;
+    }
+    return current;
   }
 
   /**

package/scanInfo.ts

@@ -422,6 +422,10 @@ export class AppInfo extends ScanInfo {
     return this.scanResult as AppScanResult;
   }
 
+  setRoutes(routes: string[]) {
+    (this.scanResult as AppScanResult).routes = routes;
+  }
+
   static async #getAllLibDeps(exec: AppExecutor, libDeps: string[], libSet = new Set<string>()) {
     await Promise.all(
       libDeps.map(async (libName) => {