@akanjs/devkit 3.1.1 → 3.1.2-rc.0

package/executors.test.ts

@@ -376,6 +376,23 @@ describe("Workspace and app executor environment contracts", () => {
     });
   });
 
+  test("a workspace with no .env, as a fresh clone has, runs local unless the shell names an environment", async () => {
+    const root = await makeTempRoot();
+    delete process.env.AKAN_PUBLIC_ENV;
+
+    WorkspaceExecutor.defaultCloneToLocalEnv(root);
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env")).env).toBe("local");
+
+    process.env.AKAN_PUBLIC_ENV = "main";
+    WorkspaceExecutor.defaultCloneToLocalEnv(root);
+    expect(process.env.AKAN_PUBLIC_ENV).toBe("main");
+
+    delete process.env.AKAN_PUBLIC_ENV;
+    await writeFile(path.join(root, ".env"), "AKAN_PUBLIC_REPO_NAME=repo\n");
+    WorkspaceExecutor.defaultCloneToLocalEnv(root);
+    expect(WorkspaceExecutor.getBaseDevEnv(path.join(root, ".env")).env).toBe("debug");
+  });
+
   test("a build or tunnel for a real environment refuses a defaulted value, and a local one takes it", () => {
     const baseDevEnv = {
       repoName: "fixture-repo",
@@ -1305,7 +1322,8 @@ const createScannableLib = async (
   await writeJson(path.join(libDir, "tsconfig.json"), { compilerOptions: { target: "ESNext", paths: {} } });
   await writeText(path.join(libDir, "akan.config.ts"), config);
   await mkdir(path.join(libDir, "lib", "__scalar"), { recursive: true });
-  for (const [file, content] of Object.entries(files)) await writeText(path.join(libDir, file), content);
+  const libFiles = { "env/env.server.testing.ts": "export const env = {};\n", ...files };
+  for (const [file, content] of Object.entries(libFiles)) await writeText(path.join(libDir, file), content);
   return { ...temp, libDir };
 };
 

package/executors.ts

@@ -44,6 +44,7 @@ import {
 import { AkanAppConfig, AkanLibConfig, AkanWorkspaceConfig, decreaseBuildNum, increaseBuildNum } from "./akanConfig";
 import { getRootBoundarySegments, isRootBoundarySegments } from "./artifact/implicitRootLayout";
 import { CodegenLock } from "./codegenLock";
+import { EnvSeed } from "./envSeed";
 import { FileSys, getDirname } from "./fileSys";
 import { JsonFormatter } from "./jsonFormatter";
 import { Linter } from "./linter";
@@ -429,11 +430,13 @@ export class Executor {
       targetPath,
       scanInfo,
       overwrite = true,
+      dryRun = false,
     }: {
       templatePath: string;
       targetPath: string;
       scanInfo?: AppInfo | LibInfo | null;
       overwrite?: boolean;
+      dryRun?: boolean;
     },
     dict: { [key: string]: string } = {},
     options: { [key: string]: unknown } = {},
@@ -456,6 +459,7 @@ export class Executor {
       const filename = typeof result === "object" ? result.filename : path.basename(targetPath).replace(".js", ".ts");
       const content = typeof result === "object" ? result.content : result;
       const convertedTargetPath = convertPath(`${path.dirname(targetPath)}/${filename}`);
+      if (dryRun) return { filePath: this.getPath(convertedTargetPath), content, written: false };
       this.logger.verbose(`Apply template ${templatePath} to ${convertedTargetPath}`);
       return this.writeFile(convertedTargetPath, content, { overwrite });
     } else if (targetPath.endsWith(".template")) {
@@ -465,11 +469,13 @@ export class Executor {
         (data, [key, value]) => data.replace(new RegExp(`<%= ${key} %>`, "g"), value),
         content,
       );
+      if (dryRun) return { filePath: this.getPath(convertedTargetPath), content: convertedContent, written: false };
       this.logger.verbose(`Apply template ${templatePath} to ${convertedTargetPath}`);
       return this.writeFile(convertedTargetPath, convertedContent, { overwrite });
     } else if (staticTemplateFileExtensions.has(path.extname(targetPath).toLowerCase())) {
       const convertedTargetPath = convertPath(targetPath);
       const writePath = this.getPath(convertedTargetPath);
+      if (dryRun) return { filePath: writePath, content: "", written: false };
       if (!overwrite && (await FileSys.fileExists(writePath)))
         return { filePath: writePath, content: "", written: false };
       const dirname = path.dirname(writePath);
@@ -486,6 +492,7 @@ export class Executor {
     dict = {},
     options = {},
     overwrite = true,
+    dryRun = false,
   }: {
     basePath: string;
     template: string;
@@ -493,6 +500,7 @@ export class Executor {
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
+    dryRun?: boolean;
   }): Promise<WrittenFileContent[]> {
     const templateRoot = await this.#resolveTemplateRoot();
     const templatePath = `${templateRoot}${template ? `/${template}` : ""}`;
@@ -503,6 +511,7 @@ export class Executor {
           targetPath: path.join(basePath, path.basename(templatePath)),
           scanInfo,
           overwrite,
+          dryRun,
         },
         dict,
         options,
@@ -521,6 +530,7 @@ export class Executor {
                   targetPath: path.join(basePath, subdir),
                   scanInfo,
                   overwrite,
+                  dryRun,
                 },
                 dict,
                 options,
@@ -533,6 +543,7 @@ export class Executor {
                 scanInfo,
                 dict,
                 overwrite,
+                dryRun,
                 options,
               });
           }),
@@ -558,6 +569,7 @@ export class Executor {
     dict?: { [key: string]: string };
     options?: { [key: string]: unknown };
     overwrite?: boolean;
+    dryRun?: boolean;
   }): Promise<FileContent[]> {
     const fileContents = await this._applyTemplate({ ...options, dict: withCapitalizedDict(options.dict) });
     await this.#formatAppliedTemplate(fileContents.filter((fileContent) => fileContent.written));
@@ -712,6 +724,10 @@ export class WorkspaceExecutor extends Executor {
       defaulted,
     };
   }
+  //? A clone has no `.env` (gitignored for its secrets): it runs local, as a new workspace and env.server.ts do, not debug.
+  static defaultCloneToLocalEnv(workspaceRoot: string) {
+    if (!existsSync(path.join(workspaceRoot, ".env"))) process.env.AKAN_PUBLIC_ENV ??= "local";
+  }
   //? A build or tunnel for a real environment carries these into an image, a bundle or a host name it dials.
   static assertDeployableEnv(baseDevEnv: BaseDevEnv, environment: string, purpose: string) {
     const defaulted = environment === "local" ? [] : (baseDevEnv.defaulted ?? []);
@@ -804,11 +820,19 @@ export class WorkspaceExecutor extends Executor {
     };
     return await getDirs(basePath);
   }
-  async commit(message: string, { init = false, add = true }: { init?: boolean; add?: boolean } = {}) {
+  async commit(
+    message: string,
+    {
+      init = false,
+      add = true,
+      identity,
+    }: { init?: boolean; add?: boolean; identity?: { name: string; email: string } } = {},
+  ) {
     if (init) await this.spawn("git", ["init", "--quiet"]);
     if (add) await this.spawn("git", ["add", "."]);
+    const author = identity ? ["-c", `user.name=${identity.name}`, "-c", `user.email=${identity.email}`] : [];
     // Argument vector, not a shell string: a message carrying a double quote breaks the interpolated form.
-    await this.spawn("git", ["commit", "--quiet", "-m", message]);
+    await this.spawn("git", [...author, "commit", "--quiet", "-m", message]);
   }
   /** `git commit` exits non-zero on an empty index, so a re-runnable caller has to ask first. */
   async hasChanges() {
@@ -923,8 +947,23 @@ export class SysExecutor extends Executor {
     if (!this.hasScanInfo() && !allowEmpty) throw new Error("Scan info is not available");
     return this.#scanInfo as AllowEmpty extends true ? AppInfo | LibInfo | null : AppInfo | LibInfo;
   }
+  async #seedEnvFiles(): Promise<FileContent[]> {
+    const envDir = path.join(this.cwdPath, "env");
+    const missing = await new EnvSeed(envDir).missing();
+    if (!missing.length) return [];
+    const written = await Promise.all(
+      missing.map(({ fileName, content }) =>
+        this.writeFile(path.join(envDir, fileName), content, { overwrite: false, silent: true }),
+      ),
+    );
+    this.logger.info(
+      `${missing.map(({ fileName }) => `env/${fileName}`).join(", ")} were missing (gitignored, so a clone has none) and now hold local defaults: put this machine's values in them, or fetch the team's with \`akan download-env\`.`,
+    );
+    return written;
+  }
   #getScanTemplateTasks(scanInfo: AppInfo | LibInfo): (Promise<FileContent[]> | null)[] {
     return [
+      this.#seedEnvFiles(),
       this._applyTemplate({ basePath: "env", template: "env", scanInfo }),
       this._applyTemplate({ basePath: "lib", template: "lib", scanInfo }),
       this._applyTemplate({ basePath: ".", template: "server.ts", scanInfo }),

package/fileSys.test.ts

@@ -1,7 +1,9 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { getDirname } from "./fileSys";
+import { FileSys, getDirname } from "./fileSys";
 
 describe("getDirname", () => {
   test("converts file URLs to filesystem paths", () => {
@@ -19,3 +21,29 @@ describe("getDirname", () => {
     expect(dirname).toBe("C:\\Users\\ken78\\.bun\\install\\global\\node_modules\\@akanjs\\devkit");
   });
 });
+
+describe("FileSys.ensurePrivateDir", () => {
+  //? macOS refuses even the owner a chmod of a folder flagged user-immutable; Linux needs root for the same.
+  test.skipIf(process.platform !== "darwin")(
+    "warns instead of throwing when the folder's mode cannot be changed",
+    () => {
+      const root = mkdtempSync(path.join(tmpdir(), "akan-private-dir-"));
+      const dir = path.join(root, "locked");
+      mkdirSync(dir);
+      chmodSync(dir, 0o755);
+      Bun.spawnSync(["chflags", "uchg", dir]);
+      const warn = spyOn(FileSys.logger, "warn").mockImplementation(() => undefined);
+      try {
+        expect(FileSys.ensurePrivateDir(dir)).toBe(dir);
+        expect(statSync(dir).mode & 0o777).toBe(0o755);
+        expect(warn.mock.calls.map(([line]) => String(line))).toEqual([
+          expect.stringContaining(`${dir} stays at mode 755`),
+        ]);
+      } finally {
+        warn.mockRestore();
+        Bun.spawnSync(["chflags", "nouchg", dir]);
+        rmSync(root, { recursive: true, force: true });
+      }
+    },
+  );
+});

package/fileSys.ts

@@ -1,3 +1,4 @@
+import { chmodSync, mkdirSync, statSync } from "node:fs";
 import { lstat, rename, rm, stat } from "node:fs/promises";
 import nodePath from "node:path";
 import { fileURLToPath } from "node:url";
@@ -70,6 +71,19 @@ export class FileSys {
       }
     }
   }
+  //? `mkdir`'s mode only applies to a directory it creates, so one an older build made is tightened here.
+  static ensurePrivateDir(dir: string) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform === "win32") return dir;
+    const { mode, uid } = statSync(dir);
+    if ((mode & 0o077) === 0 || uid !== process.getuid?.()) return dir;
+    try {
+      chmodSync(dir, 0o700);
+    } catch (error) {
+      FileSys.logger.warn(`${dir} stays at mode ${(mode & 0o777).toString(8)}: ${(error as Error).message}`);
+    }
+    return dir;
+  }
   static async writeJson(path: string, content: object) {
     return await Bun.file(path).write(`${JSON.stringify(content, null, 2)}\n`);
   }

package/formSetterScanner.test.ts

@@ -10,8 +10,26 @@ const fileOf = (file: string, content: string): SourceFileInfo => ({
   sourceFile: ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX),
 });
 
+const taskConstant = fileOf(
+  "apps/demo/lib/task/task.constant.ts",
+  `export class TaskInput extends via((field) => ({
+  title: field(String),
+  type: field(String),
+  phone: field(String),
+  project: field(Project).optional(),
+  members: field([User]),
+})) {}
+
+export class TaskObject extends via(TaskInput, (field) => {
+  return { status: field(String) };
+}) {}
+
+export class TaskInsight extends via(Task, (field) => ({ onSale: field(Int) })) {}
+`,
+);
+
 const scan = (content: string) =>
-  new FormSetterScanner().scan([fileOf("apps/demo/lib/task/Task.Template.tsx", content)]);
+  new FormSetterScanner().scan([taskConstant, fileOf("apps/demo/lib/task/Task.Template.tsx", content)]);
 
 describe("FormSetterScanner", () => {
   test("a setter passed by reference publishes, so nothing is reported", () => {
@@ -73,6 +91,31 @@ describe("FormSetterScanner", () => {
     ).toEqual([]);
   });
 
+  test("a slice setter is not a field setter, though its name reads set…On…", () => {
+    expect(
+      scan(`export const Filters = () => (
+  <Select onChange={(page) => st.do.setPageOfTaskOnSale(page)} />
+);
+`),
+    ).toEqual([]);
+  });
+
+  test("a field is known from its model's constant, so another model's setter is not counted", () => {
+    expect(
+      scan(`export const General = () => (
+  <>
+    <Field.Text onChange={(title) => st.do.setTitleOnProject(title)} />
+    <Field.Text onChange={(onSale) => st.do.setOnSaleOnTask(onSale)} />
+  </>
+);
+`),
+    ).toEqual([]);
+    expect(
+      scan(`export const General = () => <Field.Text onChange={(status) => st.do.setStatusOnTask(status)} />;\n`)[0]
+        ?.message,
+    ).toContain("setStatusOnTask");
+  });
+
   test("only .tsx is scanned", () => {
     const content = `export const set = (v: string) => <X onChange={(t) => st.do.setTitleOnTask(t)} />;\n`;
     expect(new FormSetterScanner().scan([fileOf("apps/demo/lib/task/task.store.ts", content)])).toEqual([]);

package/formSetterScanner.ts

@@ -1,3 +1,4 @@
+import { capitalize, formSetterNames } from "akanjs/common";
 import ts from "typescript";
 import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
 
@@ -5,17 +6,61 @@ import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
 // forwarding wrappers; this counts every field left unpublished whatever the reason. A zero-parameter handler is a
 // button setting a constant, not a form control, so it is not counted.
 export class FormSetterScanner {
-  static #fieldSetter = /^set[A-Za-z0-9_$]*On[A-Za-z0-9_$]*$/;
+  static #constantPath = /(?:^|\/)lib\/([^_/][^/]*)\/\1\.constant\.ts$/;
+  static #baseFields = ["id", "createdAt", "updatedAt", "removedAt"];
 
   scan(sourceFiles: SourceFileInfo[]): QualityWarning[] {
-    return sourceFiles.filter((sourceFile) => sourceFile.file.endsWith(".tsx")).flatMap((f) => this.#scanFile(f));
+    const fieldSetters = FormSetterScanner.#fieldSettersOf(sourceFiles);
+    return sourceFiles
+      .filter((sourceFile) => sourceFile.file.endsWith(".tsx"))
+      .flatMap((f) => this.#scanFile(f, fieldSetters));
   }
 
-  #scanFile({ file, sourceFile }: SourceFileInfo): QualityWarning[] {
+  // Built forward from the constants: matching `set…On…` also caught slice setters such as `setPageOfProductOnSale`.
+  static #fieldSettersOf(sourceFiles: SourceFileInfo[]) {
+    const setters = new Set<string>();
+    for (const { file, sourceFile } of sourceFiles) {
+      const refName = FormSetterScanner.#constantPath.exec(file)?.[1];
+      if (!refName) continue;
+      const className = capitalize(refName);
+      const fullModelClasses = new Set([`${className}Input`, `${className}Object`, `Light${className}`, className]);
+      const keys = new Set(FormSetterScanner.#baseFields);
+      for (const statement of sourceFile.statements)
+        if (ts.isClassDeclaration(statement) && statement.name && fullModelClasses.has(statement.name.text))
+          for (const key of FormSetterScanner.#viaFieldKeysOf(statement)) keys.add(key);
+      for (const key of keys) setters.add(formSetterNames(className, key).setFieldOnModel);
+    }
+    return setters;
+  }
+
+  static #viaFieldKeysOf(declaration: ts.ClassDeclaration): string[] {
+    const via = declaration.heritageClauses?.find((clause) => clause.token === ts.SyntaxKind.ExtendsKeyword)?.types[0]
+      ?.expression;
+    if (!via || !ts.isCallExpression(via)) return [];
+    return via.arguments.flatMap((argument) => {
+      if (!ts.isArrowFunction(argument) && !ts.isFunctionExpression(argument)) return [];
+      const fields = FormSetterScanner.#returnedObjectOf(argument.body);
+      return (fields?.properties ?? []).flatMap((property) =>
+        property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name))
+          ? [property.name.text]
+          : [],
+      );
+    });
+  }
+
+  static #returnedObjectOf(body: ts.ConciseBody): ts.ObjectLiteralExpression | null {
+    let expression: ts.Node | undefined = body;
+    if (ts.isBlock(body)) expression = body.statements.find(ts.isReturnStatement)?.expression;
+    while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)))
+      expression = expression.expression;
+    return expression && ts.isObjectLiteralExpression(expression) ? expression : null;
+  }
+
+  #scanFile({ file, sourceFile }: SourceFileInfo, fieldSetters: Set<string>): QualityWarning[] {
     const wrapped: { setter: string; line: number }[] = [];
     const visit = (node: ts.Node) => {
       if (ts.isJsxAttribute(node)) {
-        const setter = FormSetterScanner.#wrappedSetterOf(node);
+        const setter = FormSetterScanner.#wrappedSetterOf(node, fieldSetters);
         if (setter) wrapped.push({ setter, line: FormSetterScanner.#lineOf(sourceFile, node) });
       }
       ts.forEachChild(node, visit);
@@ -40,17 +85,17 @@ export class FormSetterScanner {
   }
 
   /** The setter a handler prop writes behind a wrapper, or null when it is passed by reference or absent. */
-  static #wrappedSetterOf(attribute: ts.JsxAttribute): string | null {
+  static #wrappedSetterOf(attribute: ts.JsxAttribute, fieldSetters: Set<string>): string | null {
     if (!ts.isIdentifier(attribute.name) || !/^on[A-Z]/.test(attribute.name.text)) return null;
     const initializer = attribute.initializer;
     if (!initializer || !ts.isJsxExpression(initializer) || !initializer.expression) return null;
     const handler = initializer.expression;
     if (!ts.isArrowFunction(handler) && !ts.isFunctionExpression(handler)) return null;
     if (!handler.parameters.length) return null;
-    return FormSetterScanner.#setterCallIn(handler.body);
+    return FormSetterScanner.#setterCallIn(handler.body, fieldSetters);
   }
 
-  static #setterCallIn(node: ts.Node): string | null {
+  static #setterCallIn(node: ts.Node, fieldSetters: Set<string>): string | null {
     let found: string | null = null;
     const visit = (current: ts.Node) => {
       if (found) return;
@@ -61,7 +106,7 @@ export class FormSetterScanner {
           ts.isIdentifier(expression.expression) &&
           expression.expression.text === "st" &&
           expression.name.text === "do" &&
-          FormSetterScanner.#fieldSetter.test(name.text)
+          fieldSetters.has(name.text)
         ) {
           found = name.text;
           return;

package/frontendBuild/csrArtifactBuilder.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { type PageEntry, resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import type { App } from "../commandDecorators";
+import { type BarrelImportsPluginOptions, createBarrelImportsPlugin } from "../transforms/barrelImportsPlugin";
 import { createBrowserDirnamePlugin } from "../transforms/browserDirnamePlugin";
 import { SideEffectImportOrder } from "../transforms/sideEffectImportOrder";
 import { bundleDefine } from "./bundleDefine";
@@ -67,6 +68,7 @@ export class CsrArtifactBuilder {
     const options = CsrArtifactBuilder.bundleOptions(this.#app, this.#command, akanConfig.optimizeImports);
     const result = await Bun.build({
       ...options,
+      plugins: [...options.plugins, await CsrArtifactBuilder.barrelImportsPlugin(this.#app)],
       entrypoints: htmlBasePaths.map((basePath) => this.#generatedPath(CsrArtifactBuilder.htmlFilename(basePath))),
       files: generatedFiles,
       root: this.#generatedDir,
@@ -118,6 +120,11 @@ export class CsrArtifactBuilder {
     };
   }
 
+  //? Whole, the akanjs/ui barrel bundles every component and the optional peers (react-icons) they import.
+  static async barrelImportsPlugin(app: App, pipeAfter?: BarrelImportsPluginOptions["pipeAfter"]) {
+    return await createBarrelImportsPlugin(app, { barrels: ["akanjs/ui"], pipeAfter });
+  }
+
   /** Where a build records the `AKAN_PUBLIC_*` it inlined, which nothing in the minified bundle names. */
   static publicEnvPath(app: App) {
     return path.join(app.dist.cwdPath, ".akan", "artifact", "csr-public-env.json");

package/frontendBuild/mcpAppViewBuilder.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import path from "node:path";
 import { tempDirs, writeText as write } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
 import { McpAppViewBuilder } from "./mcpAppViewBuilder";
 
 const makeTempRoot = tempDirs("akan-mcp-app-views-");
@@ -132,6 +133,68 @@ describe("McpAppViewBuilder.discover", () => {
   });
 });
 
+describe("McpAppViewBuilder.build", () => {
+  test("rewrites the akanjs/ui barrel, trims the page to its apps and drops a lazy component nothing renders", async () => {
+    const root = await makeTempRoot();
+    const file = (rel: string) => path.join(root, rel);
+    await write(
+      file("node_modules/akanjs/package.json"),
+      JSON.stringify({
+        name: "akanjs",
+        exports: { "./ui": "./ui/index.ts", "./ui/*": "./ui/*", "./webkit": "./webkit.ts" },
+      }),
+    );
+    await write(
+      file("node_modules/akanjs/webkit.ts"),
+      "export const McpAppBoot = { run: (view: unknown) => console.info(view) };\n",
+    );
+    await write(
+      file("node_modules/akanjs/ui/index.ts"),
+      'export { Link } from "./Link";\nexport { Toolbox } from "./Toolbox";\n',
+    );
+    await write(file("node_modules/akanjs/ui/Link.ts"), 'export const Link = "a link";\n');
+    await write(
+      file("node_modules/akanjs/ui/Toolbox.ts"),
+      'console.info("a toolbox loaded");\nexport const Toolbox = "a toolbox";\n',
+    );
+    await write(file("apps/demo/ui/lazy.ts"), "export const lazy = (load: () => Promise<unknown>) => ({ load });\n");
+    await write(file("apps/demo/ui/Heavy.ts"), 'export default "a heavy chunk";\n');
+    await write(
+      file("apps/demo/ui/cards.ts"),
+      'import { lazy } from "./lazy";\nexport const Heavy = lazy(() => import("./Heavy"));\nexport const Card = "a card";\n',
+    );
+    await write(
+      file("apps/demo/page/home.tsx"),
+      [
+        'import { Link } from "akanjs/ui";',
+        'import { Card } from "../ui/cards";',
+        "const page = () => ({ app: (name: string, description: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, description, draw, render] }) });",
+        'export default page().app("showHome", "Show home.", () => [Link, Card]).render(() => "drawn by the render");',
+      ].join("\n"),
+    );
+    const app = {
+      cwdPath: file("apps/demo"),
+      dist: { cwdPath: file("dist/apps/demo") },
+      workspace: { workspaceRoot: root },
+      getTsConfig: async () => ({ compilerOptions: {} }),
+      getPublicEnv: () => ({}),
+      logger: { warn: () => undefined },
+    };
+
+    await new McpAppViewBuilder(app as never, "build").build(
+      [{ key: "./home.tsx", moduleAbsPath: file("apps/demo/page/home.tsx") }],
+      { basePaths: [], cssAssets: {}, options: CsrArtifactBuilder.bundleOptions(app as never, "build") },
+    );
+
+    const view = await Bun.file(file("dist/apps/demo/mcp-apps/showHome.html")).text();
+    expect(view).toContain("a link");
+    expect(view).toContain("a card");
+    expect(view).not.toContain("a toolbox");
+    expect(view).not.toContain("drawn by the render");
+    expect(view).not.toContain("a heavy chunk");
+  });
+});
+
 describe("McpAppViewBuilder.entryOf", () => {
   test("boots the one app with its page, the root layout and overrides it sits under, by relative path", () => {
     const view = {

package/frontendBuild/mcpAppViewBuilder.ts

@@ -78,7 +78,13 @@ export class McpAppViewBuilder {
     const pagePaths = [...new Set(views.map((view) => view.page.moduleAbsPath))];
     const result = await Bun.build({
       ...options,
-      plugins: [...options.plugins, McpAppPageTrimmer.plugin(pagePaths), PureLazyMarker.plugin()],
+      plugins: [
+        ...options.plugins,
+        //? Bun runs one onLoad per module, so the one rewriting the barrel also trims the pages and marks `lazy()`; the
+        //? marker plugin takes the TypeScript that one leaves to Bun, a package's own outside node_modules/akanjs.
+        await CsrArtifactBuilder.barrelImportsPlugin(this.#app, McpAppPageTrimmer.pipe(pagePaths)),
+        PureLazyMarker.plugin(),
+      ],
       entrypoints: views.map((view) => path.join(generatedDir, `${view.name}.html`)),
       files,
       root: generatedDir,

package/frontendBuild/optionalPeers.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import { mkdir, symlink } from "node:fs/promises";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import { resolveSsrPageEntries } from "../artifact/implicitRootLayout";
+import { tempDirs, writeText as write } from "../testHelpers";
+import { CsrArtifactBuilder } from "./csrArtifactBuilder";
+import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
+
+const makeTempRoot = tempDirs("akan-optional-peers-");
+const akanjsRoot = path.resolve(import.meta.dir, "../../../akanjs");
+const { peerDependenciesMeta } = (await Bun.file(path.join(akanjsRoot, "package.json")).json()) as {
+  peerDependenciesMeta: Record<string, { optional?: boolean }>;
+};
+//? The app installs these itself: they are peers so that it renders with one React.
+const appRenderer = new Set(["react", "react-dom", "react-server-dom-webpack"]);
+const optionalPeers = Object.entries(peerDependenciesMeta)
+  .filter(([name, meta]) => meta.optional && !appRenderer.has(name))
+  .map(([name]) => name);
+const optionalPeerImport = new RegExp(
+  `^(?:${optionalPeers.map((name) => name.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&")).join("|")})(?:/|$)`,
+);
+
+const recordOptionalPeers = (reached: string[]): BunPlugin => ({
+  name: "record-optional-peers",
+  setup(build) {
+    build.onResolve({ filter: optionalPeerImport }, ({ path: specifier, importer }) => {
+      reached.push(`${path.relative(akanjsRoot, importer)} -> ${specifier}`);
+      return { path: specifier, external: true };
+    });
+  },
+});
+
+const linkPackage = async (root: string, name: string, dir: string) => {
+  await mkdir(path.join(root, "node_modules"), { recursive: true });
+  await symlink(dir, path.join(root, "node_modules", name));
+};
+
+const writeApp = async (indexPage: string) => {
+  const root = await makeTempRoot();
+  const appDir = path.join(root, "apps/demo");
+  await linkPackage(root, "akanjs", akanjsRoot);
+  await linkPackage(root, "react", path.dirname(Bun.resolveSync("react/package.json", akanjsRoot)));
+  await write(
+    path.join(root, "tsconfig.json"),
+    JSON.stringify({ compilerOptions: { paths: { "@apps/*": ["./apps/*"] } } }),
+  );
+  await write(path.join(appDir, "client.ts"), "export {};\n");
+  await write(path.join(appDir, "env/env.client.ts"), "export const env = {};\n");
+  await write(path.join(appDir, "lib/dict.ts"), "export const getAllDictionary = () => ({});\n");
+  await write(path.join(appDir, "page/_index.tsx"), indexPage);
+  await write(path.join(appDir, "page/_overrides.tsx"), "export default {};\n");
+  return { root, appDir, pageKeys: ["./_index.tsx", "./_overrides.tsx"] };
+};
+
+const buildCsr = async (indexPage: string) => {
+  const { root, appDir, pageKeys } = await writeApp(indexPage);
+  const app = {
+    name: "demo",
+    cwdPath: appDir,
+    dist: { cwdPath: path.join(root, "dist/apps/demo") },
+    workspace: { workspaceRoot: root },
+    getPageKeys: async () => pageKeys,
+    getConfig: async () => ({ basePaths: [], optimizeImports: [], barrelImports: [] }),
+    getTsConfig: async () => ({ compilerOptions: { paths: { "@apps/*": ["./apps/*"] } } }),
+    getPublicEnv: () => ({}),
+    log: () => undefined,
+    verbose: () => undefined,
+    logger: { warn: () => undefined },
+  };
+  const reached: string[] = [];
+  const build = Bun.build;
+  const recorded = spyOn(Bun, "build").mockImplementation((config) =>
+    build({ ...config, plugins: [recordOptionalPeers(reached), ...(config.plugins ?? [])] }),
+  );
+
+  try {
+    await new CsrArtifactBuilder(app as never, "build").build();
+  } finally {
+    recorded.mockRestore();
+  }
+  return { root, reached };
+};
+
+describe("optional peers of akanjs", () => {
+  test("the generated root layout, the _overrides.tsx wrapper and the runtime entries import none", async () => {
+    const { appDir, pageKeys } = await writeApp("export default function Page() {\n  return null;\n}\n");
+    const generated = (await resolveSsrPageEntries({ appCwdPath: appDir, appName: "demo", pageKeys }))
+      .map(({ moduleAbsPath }) => moduleAbsPath)
+      .filter((file) => file.includes(`${path.sep}.akan${path.sep}`));
+    const runtime = [
+      path.join(akanjsRoot, "server/rscClient.tsx"),
+      path.join(akanjsRoot, "server/rscSegmentOutlet.tsx"),
+      path.join(akanjsRoot, "webkit/index.ts"),
+      ...VENDOR_SPECIFIERS.map((specifier) =>
+        path.join(akanjsRoot, "server/vendor", `${specifier.replaceAll("/", "-").replaceAll(".", "-")}.ts`),
+      ),
+    ];
+    expect(generated).toHaveLength(2);
+
+    //? No barrel rewrite, as a dev registry compiles every module an import names.
+    for (const target of ["browser", "bun"] as const) {
+      const reached: string[] = [];
+      const result = await Bun.build({
+        entrypoints: [...generated, ...runtime],
+        target,
+        throw: false,
+        plugins: [recordOptionalPeers(reached)],
+      });
+
+      expect(result.logs.map((log) => log.message)).toEqual([]);
+      expect(reached).toEqual([]);
+    }
+  });
+
+  test("the CSR shell build of a page drawing akanjs/ui components imports none", async () => {
+    const { reached } = await buildCsr(
+      'import { Link, System } from "akanjs/ui";\n\nexport default function Page() {\n  return (\n    <Link href="/">\n      <System.ThemeToggle />\n    </Link>\n  );\n}\n',
+    );
+
+    expect(reached).toEqual([]);
+  });
+
+  test("the MCP App view build of a page drawing akanjs/ui components imports none", async () => {
+    const { root, reached } = await buildCsr(
+      'import { page } from "akanjs/client";\nimport { Link } from "akanjs/ui";\n\nexport default page()\n  .app("showHome", "Show the home link.", () => <Link href="/">home</Link>)\n  .render(() => null);\n',
+    );
+
+    expect(await Bun.file(path.join(root, "dist/apps/demo/mcp-apps/showHome.html")).exists()).toBe(true);
+    expect(reached).toEqual([]);
+  });
+});