@akanjs/devkit 3.1.0-rc.21 → 3.1.0-rc.22

package/applicationBuildRunner.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { describe, expect, spyOn, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AkanAppConfig } from "./akanConfig";
@@ -111,6 +111,45 @@ console.info(new SampleService().name);
     }
   });
 
+  test("bakes into the bundles every AKAN_PUBLIC_* its Dockerfile carries, and names the shell values it outranked", async () => {
+    const { root, workspace } = await createTempApp("portal");
+    const keys = ["AKAN_PUBLIC_ENV", "AKAN_PUBLIC_REPO_NAME", "AKAN_PUBLIC_SERVE_DOMAIN"] as const;
+    const shellEnv = Object.fromEntries(keys.map((key) => [key, process.env[key]]));
+    await writeFile(
+      path.join(root, ".env"),
+      "AKAN_PUBLIC_ENV=main\nAKAN_PUBLIC_REPO_NAME=repo\nAKAN_PUBLIC_SERVE_DOMAIN=akanjs.com\n",
+    );
+    await Promise.all(["private", "public"].map((dir) => mkdir(path.join(root, "apps", "portal", dir))));
+    Object.assign(process.env, {
+      AKAN_PUBLIC_ENV: "local",
+      AKAN_PUBLIC_REPO_NAME: "shell-repo",
+      AKAN_PUBLIC_SERVE_DOMAIN: "localhost",
+    });
+    const app = AppExecutor.from(workspace, "portal");
+    const warn = spyOn(app.logger, "warn").mockImplementation(() => undefined);
+    const runner = new ApplicationBuildRunner(app);
+    runner.typecheck = async () => {
+      throw new Error("stopped after prepare");
+    };
+    try {
+      await expect(runner.build()).rejects.toThrow("stopped after prepare");
+      const define = bundleDefine(app, "build", "csr") as { [key: string]: string };
+      const imageEnv = (await app.getConfig()).getProductionEnv();
+      for (const key of keys) expect(define[`process.env.${key}`]).toBe(JSON.stringify(imageEnv[key]));
+      expect(imageEnv.AKAN_PUBLIC_SERVE_DOMAIN).toBe("akanjs.com");
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0]?.[0]).toBe(
+        "The workspace .env outranks this process's environment: the bundles and the image take AKAN_PUBLIC_ENV=main (not local), AKAN_PUBLIC_REPO_NAME=repo (not shell-repo), AKAN_PUBLIC_SERVE_DOMAIN=akanjs.com (not localhost).",
+      );
+    } finally {
+      for (const key of keys) {
+        if (shellEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = shellEnv[key];
+      }
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   test("a build for a real environment stops before any phase when the serve domain is only the local default", async () => {
     const { root, workspace } = await createTempApp("portal");
     await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");

package/applicationBuildRunner.ts

@@ -18,6 +18,7 @@ import { Spinner } from "./spinner";
 import { createServerEnvPlugin } from "./transforms/serverEnvPlugin";
 import { ServerEnvProfile } from "./transforms/serverEnvProfile";
 import { ProjectTypecheck } from "./typecheck/projectTypecheck";
+import type { BaseDevEnv } from "./types";
 
 export interface TypecheckOptions {
   clean?: boolean;
@@ -97,14 +98,34 @@ export class ApplicationBuildRunner {
     return path.join(this.#app.cwdPath, "env");
   }
 
+  //? Bundles bake AKAN_PUBLIC_* from process.env, where the shell outranks the .env that the server env and the
+  //? Dockerfile read: a page built otherwise drops the image's tokens as foreign or dials another serve domain.
+  #pinImageEnv(baseDevEnv: BaseDevEnv, environment: string) {
+    const imageEnv = {
+      AKAN_PUBLIC_ENV: environment,
+      AKAN_PUBLIC_REPO_NAME: baseDevEnv.repoName,
+      AKAN_PUBLIC_SERVE_DOMAIN: baseDevEnv.serveDomain,
+    };
+    const outranked = Object.entries(imageEnv).filter(([key, value]) => {
+      const given = process.env[key];
+      return !!given && given !== value && !(key === "AKAN_PUBLIC_ENV" && this.#environment);
+    });
+    if (outranked.length)
+      this.#app.logger.warn(
+        `The workspace .env outranks this process's environment: the bundles and the image take ${outranked
+          .map(([key, value]) => `${key}=${value} (not ${process.env[key]})`)
+          .join(", ")}.`,
+      );
+    Object.assign(process.env, imageEnv);
+  }
+
   async build({ spinner = false }: BuildOptions = {}): Promise<BuildResult> {
     // serial build is needed because of Bun.build is unstable for parallel build
     this.#spinner = spinner;
     const { web, assets, baseDevEnv } = await this.#app.getConfig();
     const environment = this.#environment ?? baseDevEnv.env;
     WorkspaceExecutor.assertDeployableEnv(baseDevEnv, environment, "akan build");
-    //? Bundles bake AKAN_PUBLIC_ENV from process.env, where the shell outranks the .env that picked the server env.
-    process.env.AKAN_PUBLIC_ENV = environment;
+    this.#pinImageEnv(baseDevEnv, environment);
     //? Before any phase: a profile that would ship a secret stops the build, not the image after it.
     if (this.#profile)
       await ServerEnvProfile.assertShippable({ envDir: this.#envDir, environment, profile: this.#profile });

package/artifact/implicitRootLayout.test.ts

@@ -36,7 +36,9 @@ describe("resolveSsrPageEntries", () => {
     const generatedSource = await Bun.file(groupedRoot?.moduleAbsPath ?? "").text();
     // Both user modules go through the route resolver, so a `rootLayout()` chain and the legacy exports read alike.
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
-    expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
+    expect(generatedSource).toContain(
+      'const inheritedLayout = assertGuardOnChain("page/_layout.tsx", resolveRouteModule(inheritedModule as never',
+    );
     expect(generatedSource).not.toContain("<System.Provider");
     expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
     // The ancestor root is a level of the route tree, which merges its head; this boundary returns only its own.
@@ -48,6 +50,9 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");
     // The ancestor root is its own level of the stack, so inheriting its loading would nest it inside itself.
     expect(generatedSource).toContain("export const Loading = userLayout.Loading;");
+    // Its guard runs from that level too, ahead of this one, and an MCP view takes its providers from there.
+    expect(generatedSource).toContain("export const guard = userLayout.guard;");
+    expect(generatedSource).not.toContain("McpAppRoot");
     expect(generatedSource).toContain(
       "<UserLayout params={params} searchParams={searchParams}>{children}</UserLayout>",
     );
@@ -77,6 +82,11 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain("export const viewport = userLayout.viewport ?? inheritedLayout.viewport;");
     expect(generatedSource).toContain("viewport={viewport}");
     expect(generatedSource).toContain("[inheritedLayout, userLayout].map((layout)");
+    expect(generatedSource).toContain(
+      "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);",
+    );
+    expect(generatedSource).toContain("export function McpAppRoot({ children, params, path }: McpAppRootProps) {");
+    expect(generatedSource).toContain("<System.App");
     expect(generatedSource).toContain('import { allDictionary } from "../dict/useDict.ts";');
     expect(generatedSource).toContain(
       'allDictionary={process.env.AKAN_PUBLIC_RENDER_ENV === "ssr" ? allDictionary : undefined}',

package/artifact/implicitRootLayout.ts

@@ -16,8 +16,11 @@ const IMPLICIT_DICT_DIR = path.join(".akan", "generated", "dict");
 const IMPLICIT_OVERRIDES_DIR = path.join(".akan", "generated", "overrides");
 const OVERRIDES_KEY_RE = /^\.\/(.+\/)?_overrides\.(tsx|ts|jsx|js)$/;
 
+const posixRelative = (fromDir: string, toAbsPath: string) =>
+  path.relative(fromDir, toAbsPath).split(path.sep).join("/");
+
 const importSpecifier = (fromAbsPath: string, toAbsPath: string) => {
-  const rel = path.relative(path.dirname(fromAbsPath), toAbsPath).split(path.sep).join("/");
+  const rel = posixRelative(path.dirname(fromAbsPath), toAbsPath);
   return rel.startsWith(".") ? rel : `./${rel}`;
 };
 
@@ -162,14 +165,14 @@ async function writeGeneratedRootLayoutFile(opts: {
     ? `import { st } from "@apps/${opts.appName}/client";\nvoid st;\n`
     : `import "@apps/${opts.appName}/client";\n`;
   //? resolveRouteModule reads a rootLayout() chain and the legacy named exports alike.
-  const inheritedLabel = inheritedSourceAbsPath ? path.relative(opts.appCwdPath, inheritedSourceAbsPath) : "";
+  const inheritedLabel = inheritedSourceAbsPath ? posixRelative(opts.appCwdPath, inheritedSourceAbsPath) : "";
   const inheritedImport = inheritedSourceSpecifier
-    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)}).module as LayoutModule;\n`
+    ? `import * as inheritedModule from ${JSON.stringify(inheritedSourceSpecifier)};\nconst inheritedLayout = assertGuardOnChain(${JSON.stringify(inheritedLabel)}, resolveRouteModule(inheritedModule as never, ${JSON.stringify(inheritedLabel)})).module as LayoutModule;\n`
     : "const inheritedLayout: LayoutModule = {};\n";
   const prefix = opts.boundary.segments.find((segment) => !/^\(.+\)$/.test(segment)) ?? null;
-  const userLabel = opts.boundary.sourceAbsPath ? path.relative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
+  const userLabel = opts.boundary.sourceAbsPath ? posixRelative(opts.appCwdPath, opts.boundary.sourceAbsPath) : "";
   const userImport = sourceSpecifier
-    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)}).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
+    ? `import * as userModule from ${JSON.stringify(sourceSpecifier)};\nconst userLayout = assertGuardOnChain(${JSON.stringify(userLabel)}, resolveRouteModule(userModule as never, ${JSON.stringify(userLabel)})).module as LayoutModule;\nconst UserLayout = userLayout.default as (props: LayoutProps) => ReactNode | Promise<ReactNode>;\n`
     : "const UserLayout = ({ children }: LayoutProps) => children;\nconst userLayout: LayoutModule = {};\n";
   const isAsyncUserLayout = opts.boundary.sourceAbsPath
     ? await AsyncDefaultExportDetector.detect(opts.boundary.sourceAbsPath)
@@ -191,6 +194,10 @@ async function writeGeneratedRootLayoutFile(opts: {
   const layoutReturn = isAsyncUserLayout ? "layout" : userLayoutElement;
   //? Under an ancestor root boundary the route tree merges that root's head itself; merging it here would repeat it.
   const headLayouts = opts.includeSystemProvider ? "[inheritedLayout, userLayout]" : "[userLayout]";
+  //? Likewise for the guard: an ancestor root boundary runs its own from its own layer.
+  const guardExport = opts.includeSystemProvider
+    ? "export const guard = RouteGuards.compose(inheritedLayout.guard, userLayout.guard);"
+    : "export const guard = userLayout.guard;";
   const layoutExports = `export async function generateHead(props: PageProps) {
   const heads = await Promise.all(
     ${headLayouts}.map((layout) => (layout.generateHead ? layout.generateHead(props) : layout.head)),
@@ -202,14 +209,16 @@ export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
 export const Loading = userLayout.Loading;
+${guardExport}
 
 ${layoutSignature}({ children, params, searchParams }: LayoutProps) {
 ${layoutBinding}  return `;
   const source = opts.includeSystemProvider
     ? `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { loadFonts, resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, loadFonts, RouteGuards, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 import { System } from "akanjs/ui";
+import type { McpAppRootProps } from "akanjs/webkit";
 import { env } from "@apps/${opts.appName}/env/env.client";
 import { allDictionary } from ${JSON.stringify(dictMacroSpecifier)};
 ${clientImport}${inheritedImport}${userImport}
@@ -242,9 +251,25 @@ ${layoutExports}(
     </System.Provider>
   );
 }
+
+export function McpAppRoot({ children, params, path }: McpAppRootProps) {
+  return (
+    <System.App
+      params={params}
+      path={path}
+      env={env}
+      theme={theme}
+      viewport={viewport}
+      fonts={loadFonts(userFonts)}
+      className={defaultFontClassName}
+    >
+      {children}
+    </System.App>
+  );
+}
 `
     : `import type { LayoutModule, LayoutProps, PageProps } from "akanjs/client";
-import { resolveRouteModule, RouteHead } from "akanjs/client";
+import { assertGuardOnChain, resolveRouteModule, RouteHead } from "akanjs/client";
 import type { ReactNode } from "react";
 ${inheritedImport}${userImport}
 ${layoutExports}${layoutReturn};

package/biome.base.json

@@ -196,7 +196,10 @@
     },
     {
       "includes": ["{apps,libs}/**/*.tsx", "!**/*.test.tsx", "!**/*.spec.tsx"],
-      "plugins": ["./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit"]
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-unpublished-form-setter.grit",
+        "./node_modules/@akanjs/devkit/lint/no-conditional-st-hook.grit"
+      ]
     },
     {
       "includes": [

package/frontendBuild/csrArtifactBuilder.ts

@@ -6,6 +6,7 @@ import type { App } from "../commandDecorators";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { bundleDefine } from "./bundleDefine";
 import { CsrEntryFiles } from "./csrEntryFiles";
+import { type McpAppView, McpAppViewBuilder } from "./mcpAppViewBuilder";
 import { PagesBundleBuilder } from "./pagesBundleBuilder";
 import { PagesEntrySourceGenerator } from "./pagesEntrySourceGenerator";
 
@@ -77,11 +78,32 @@ export class CsrArtifactBuilder {
     }
 
     await this.#inlineCsrArtifacts(cssAssets);
+    await this.#buildMcpAppViews(pageEntries, { basePaths, cssAssets, options });
     if (this.#command === "build") await CsrArtifactBuilder.writePublicEnv(this.#app, options.define);
     this.#app.verbose(`[csr-build] output -> ${this.#outputDir}`);
     return { outputDir: this.#outputDir };
   }
 
+  /** The MCP App views alone: a dev server under the CSR registry reads them, with no `csr/` to build beside them. */
+  async buildMcpAppViews(): Promise<McpAppView[]> {
+    const pageKeys = await this.#app.getPageKeys();
+    if (pageKeys.length === 0) return [];
+    const pageEntries = await resolveSsrPageEntriesForApp(this.#app, pageKeys);
+    const akanConfig = await this.#app.getConfig();
+    return await this.#buildMcpAppViews(pageEntries, {
+      basePaths: [...akanConfig.basePaths],
+      cssAssets: await this.#loadCssAssets(),
+      options: CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports),
+    });
+  }
+
+  async #buildMcpAppViews(pageEntries: PageEntry[], option: Parameters<McpAppViewBuilder["build"]>[1]) {
+    const views = await new McpAppViewBuilder(this.#app, this.#command).build(pageEntries, option);
+    if (views.length)
+      this.#app.verbose(`[csr-build] ${views.length} MCP App view(s): ${views.map((view) => view.name).join(", ")}`);
+    return views;
+  }
+
   //? No `env` option: Bun inlines the `.env` it read at process start over `define`, so a native build's `--env` lost.
   static bundleOptions(app: App, command: "build" | "start", optimizeImports: string[] = []) {
     return {

package/frontendBuild/fontPruner.ts

@@ -103,6 +103,7 @@ export class FontPruner {
       { dir: path.join(this.#artifactRoot, "client-ssr"), label: ".akan/artifact/client-ssr", needles: bundled },
       { dir: path.join(this.#artifactRoot, "server"), label: ".akan/artifact/server", needles: bundled },
       { dir: path.join(this.#app.dist.cwdPath, "csr"), label: "csr", needles: bundled },
+      { dir: path.join(this.#app.dist.cwdPath, "mcp-apps"), label: "mcp-apps", needles: bundled },
     ];
     for (const root of roots) {
       const pending = root.needles.filter((candidate) => !referrers.has(candidate.rel));

package/frontendBuild/mcpAppViewBuilder.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { McpAppViewBuilder } from "./mcpAppViewBuilder";
+
+const makeTempRoot = tempDirs("akan-mcp-app-views-");
+
+const memoPage = [
+  'import { page } from "akanjs/client";',
+  "export default page()",
+  '  .param("memoId", ID)',
+  '  .app("showMemo", "Show one memo.", ({ memoId }) => null)',
+  '  .app("showMemoImages", "Show its images.", ({ memoId }) => null)',
+  "  .render(() => null);",
+].join("\n");
+
+describe("McpAppViewBuilder.discover", () => {
+  test("finds each app of each page, under the root layout that renders the system provider", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("generated/(home)/__root_layout.tsx"), "export const guard = userLayout.guard;\n");
+    await write(file("page/(home)/memo/[memoId].tsx"), memoPage);
+    await write(
+      file("page/admin/report.tsx"),
+      'export default page().app("showReport", "Show the report.", () => null).render(() => null);',
+    );
+    await write(file("page/plain.tsx"), "export default page().render(() => null);");
+    const entries = [
+      { key: "./__root_layout.tsx", moduleAbsPath: file("generated/__root_layout.tsx") },
+      { key: "./(home)/__root_layout.tsx", moduleAbsPath: file("generated/(home)/__root_layout.tsx") },
+      { key: "./(home)/memo/[memoId].tsx", moduleAbsPath: file("page/(home)/memo/[memoId].tsx") },
+      { key: "./admin/report.tsx", moduleAbsPath: file("page/admin/report.tsx") },
+      { key: "./plain.tsx", moduleAbsPath: file("page/plain.tsx") },
+    ];
+    const views = await McpAppViewBuilder.discover(entries, ["admin"]);
+    expect(views.map(({ name, page, root, basePath }) => [name, page.key, root?.key, basePath])).toEqual([
+      ["showMemo", "./(home)/memo/[memoId].tsx", "./__root_layout.tsx", ""],
+      ["showMemoImages", "./(home)/memo/[memoId].tsx", "./__root_layout.tsx", ""],
+      ["showReport", "./admin/report.tsx", "./__root_layout.tsx", "admin"],
+    ]);
+  });
+
+  test("takes the overrides over each page by route, outermost first, and none from a sibling group", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/(home)/memo.tsx"), memoPage);
+    const entries = [
+      { key: "./(home)/memo.tsx", moduleAbsPath: file("page/(home)/memo.tsx") },
+      { key: "./(home)/memo/_overrides.tsx", moduleAbsPath: file("generated/memo_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+      { key: "./(home)/_overrides.tsx", moduleAbsPath: file("generated/home_overrides.tsx") },
+      { key: "./(tab)/_overrides.tsx", moduleAbsPath: file("generated/tab_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.rootOverrides).toEqual([]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual([
+      "./_overrides.tsx",
+      "./(home)/_overrides.tsx",
+      "./(home)/memo/_overrides.tsx",
+    ]);
+  });
+
+  test("puts the overrides on the root layout's node and above it outside that layout, as the route tree does", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/(home)/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("page/(home)/memo.tsx"), memoPage);
+    const entries = [
+      { key: "./(home)/__root_layout.tsx", moduleAbsPath: file("generated/(home)/__root_layout.tsx") },
+      { key: "./(home)/memo.tsx", moduleAbsPath: file("page/(home)/memo.tsx") },
+      { key: "./(home)/memo/_overrides.tsx", moduleAbsPath: file("generated/memo_overrides.tsx") },
+      { key: "./(home)/_overrides.tsx", moduleAbsPath: file("generated/home_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.root?.key).toBe("./(home)/__root_layout.tsx");
+    expect(view?.rootOverrides.map((entry) => entry.key)).toEqual(["./_overrides.tsx", "./(home)/_overrides.tsx"]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual(["./(home)/memo/_overrides.tsx"]);
+  });
+
+  test("keeps an override inside the root layout when its folder holds a layout above the root's", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("generated/oauth/__root_layout.tsx"), "export function McpAppRoot() {}\n");
+    await write(file("page/(libs)/(shared)/oauth/consent.tsx"), memoPage);
+    const entries = [
+      { key: "./(libs)/(shared)/oauth/__root_layout.tsx", moduleAbsPath: file("generated/oauth/__root_layout.tsx") },
+      { key: "./(libs)/(shared)/_layout.tsx", moduleAbsPath: file("page/(libs)/(shared)/_layout.tsx") },
+      { key: "./(libs)/(shared)/oauth/consent.tsx", moduleAbsPath: file("page/(libs)/(shared)/oauth/consent.tsx") },
+      { key: "./(libs)/(shared)/oauth/_overrides.tsx", moduleAbsPath: file("generated/oauth_overrides.tsx") },
+      { key: "./(libs)/(shared)/_overrides.tsx", moduleAbsPath: file("generated/shared_overrides.tsx") },
+      { key: "./_overrides.tsx", moduleAbsPath: file("generated/_overrides.tsx") },
+    ];
+    const [view] = await McpAppViewBuilder.discover(entries, []);
+    expect(view?.rootOverrides.map((entry) => entry.key)).toEqual([
+      "./_overrides.tsx",
+      "./(libs)/(shared)/oauth/_overrides.tsx",
+    ]);
+    expect(view?.overrides.map((entry) => entry.key)).toEqual(["./(libs)/(shared)/_overrides.tsx"]);
+  });
+
+  test("names two pages that claim one app, and a page with no root layout to provide for it", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/a.tsx"), memoPage);
+    await write(file("page/b.tsx"), memoPage);
+    const entries = [
+      { key: "./a.tsx", moduleAbsPath: file("page/a.tsx") },
+      { key: "./b.tsx", moduleAbsPath: file("page/b.tsx") },
+    ];
+    await expect(McpAppViewBuilder.discover(entries, [])).rejects.toThrow(
+      'app "showMemo" is declared by both ./a.tsx and ./b.tsx',
+    );
+    const [view] = await McpAppViewBuilder.discover(entries.slice(0, 1), []);
+    expect(view?.root).toBeNull();
+  });
+
+  test("refuses a name MCP would not list, and two that differ only in case", async () => {
+    const appRoot = await makeTempRoot();
+    const file = (rel: string) => path.join(appRoot, rel);
+    await write(file("page/a.tsx"), memoPage);
+    await write(file("page/b.tsx"), memoPage.replace('"showMemo"', '"ShowMemo"'));
+    await write(file("page/c.tsx"), memoPage.replace('"showMemo"', '"../showMemo"'));
+    const entryOf = (name: string) => ({ key: `./${name}.tsx`, moduleAbsPath: file(`page/${name}.tsx`) });
+    await expect(McpAppViewBuilder.discover([entryOf("a"), entryOf("b")], [])).rejects.toThrow(
+      'apps "showMemo" (./a.tsx) and "ShowMemo" (./b.tsx) differ only in case',
+    );
+    await expect(McpAppViewBuilder.discover([entryOf("c")], [])).rejects.toThrow(
+      'app name "../showMemo" in ./c.tsx must match',
+    );
+  });
+});
+
+describe("McpAppViewBuilder.entryOf", () => {
+  test("boots the one app with its page, the root layout and overrides it sits under, by relative path", () => {
+    const view = {
+      name: "showMemo",
+      page: { key: "./memo/[memoId].tsx", moduleAbsPath: "/app/page/memo/[memoId].tsx" },
+      root: { key: "./__root_layout.tsx", moduleAbsPath: "/app/.akan/generated/root-layouts/__root_layout.tsx" },
+      rootOverrides: [{ key: "./_overrides.tsx", moduleAbsPath: "/app/.akan/generated/overrides/_overrides.tsx" }],
+      overrides: [{ key: "./memo/_overrides.tsx", moduleAbsPath: "/app/.akan/generated/overrides/memo.tsx" }],
+      basePath: "admin",
+    };
+    expect(McpAppViewBuilder.entryOf(view, "/app/.akan/generated/mcp-apps")).toBe(
+      [
+        'import { McpAppBoot } from "akanjs/webkit";',
+        'import * as page from "../../../page/memo/[memoId].tsx";',
+        'import * as root from "../root-layouts/__root_layout.tsx";',
+        'import rootOverride0 from "../overrides/_overrides.tsx";',
+        'import override0 from "../overrides/memo.tsx";',
+        "void McpAppBoot.run({",
+        '  app: "showMemo",',
+        "  page,",
+        "  root,",
+        "  rootOverrides: [rootOverride0],",
+        "  overrides: [override0],",
+        '  basePath: "admin",',
+        "});",
+        "",
+      ].join("\n"),
+    );
+    expect(
+      McpAppViewBuilder.entryOf(
+        { ...view, root: null, rootOverrides: [], overrides: [] },
+        "/app/.akan/generated/mcp-apps",
+      ),
+    ).toContain("const root = {};\nvoid McpAppBoot.run({");
+  });
+});