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

package/routeSourceValidator.test.ts

@@ -43,7 +43,7 @@ describe("RouteSourceValidator route chains", () => {
   const chain = (source: string, kind: "page" | "layout", pattern: string) =>
     RouteSourceValidator.validateRouteSourceExports(source, `page/${kind}.tsx`, kind, { pattern });
 
-  test("reads params, prompt and devOnly off a page() chain without evaluating it", () => {
+  test("reads params, prompt, apps and devOnly off a page() chain without evaluating it", () => {
     const source = [
       'import { page } from "akanjs/client";',
       "export default page()",
@@ -51,11 +51,13 @@ describe("RouteSourceValidator route chains", () => {
       '  .search("status", String)',
       "  .config({ transition: 'stack', devOnly: true })",
       '  .prompt("briefProject", "Brief one project.")',
-      "  .render(async ({ projectId }) => null);",
+      '  .app("showProject", "Show one project.", ({ projectId }) => null)',
+      '  .app("showBoard", "Show its board.", ({ projectId }) => null)',
+      "  .render(async ({ projectId, showProject }) => showProject);",
     ].join("\n");
     expect(chain(source, "page", "/:lang/project/:projectId")).toEqual({
       devOnly: true,
-      chain: { kind: "page", params: ["projectId"], prompt: "briefProject" },
+      chain: { kind: "page", params: ["projectId"], prompt: "briefProject", apps: ["showProject", "showBoard"] },
     });
   });
 
@@ -88,16 +90,29 @@ describe("RouteSourceValidator route chains", () => {
     expect(() => chain("export default page().param(name, ID).render(() => null);", "page", "/:lang/:x")).toThrow(
       ".param() takes a string literal first",
     );
+    expect(() => chain('export default page().app(name, "x", () => null).render(() => null);', "page", "/")).toThrow(
+      ".app() takes a string literal first",
+    );
     expect(() => chain("export default page().config({ devOnly: flag }).render(() => null);", "page", "/")).toThrow(
       "devOnly must be a literal true or false",
     );
+    const indirect = [
+      'const memo = page().app("showMemo", "x", () => null).render(() => null);',
+      "export default memo;",
+    ];
+    expect(() => chain(indirect.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
+    const renamed = [indirect[0], "export { memo as default };"];
+    expect(() => chain(renamed.join("\n"), "page", "/")).toThrow('exports its chain through "memo"');
   });
 
-  test("still reads the legacy shape as before", () => {
+  test("still reads the legacy shape as before, which never takes a guard", () => {
     const source = [
       "export default function Page() { return null; }",
       "export const pageConfig = { devOnly: false };",
     ].join("\n");
     expect(chain(source, "page", "/")).toEqual({ devOnly: false });
+    expect(() => chain(`${source}\nexport const guard = async () => undefined;`, "page", "/")).toThrow(
+      "exports guard beside a legacy default",
+    );
   });
 });

package/routeSourceValidator.ts

@@ -15,6 +15,8 @@ export interface RouteSourceChain {
   params: string[];
   /** The `.prompt()` name, when the page publishes itself as an MCP prompt. */
   prompt?: string;
+  /** The `.app()` names, each one MCP App the build gives a view of its own. */
+  apps: string[];
 }
 
 interface ChainStage {
@@ -80,6 +82,10 @@ export class RouteSourceValidator {
       throw new Error(`[route-convention] head and generateHead cannot both be exported in ${filePath}`);
     }
     const chain = RouteSourceValidator.#readChain(sourceFile, filePath);
+    if (!chain && exported.has("guard"))
+      throw new Error(
+        `[route-convention] ${filePath} exports guard beside a legacy default; declare it with .guard() on its chain`,
+      );
     if (!chain) return { devOnly: RouteSourceValidator.#readDevOnly(sourceFile, filePath) };
     const named = [...exported].filter((name) => name !== "default");
     if (named.length)
@@ -93,34 +99,75 @@ export class RouteSourceValidator {
     if (options.pattern) RouteSourceValidator.#assertChainParams(chain, options.pattern, filePath);
     return {
       devOnly: chain.devOnly,
-      chain: { kind: chain.kind, params: chain.params, ...(chain.prompt ? { prompt: chain.prompt } : {}) },
+      chain: {
+        kind: chain.kind,
+        params: chain.params,
+        ...(chain.prompt ? { prompt: chain.prompt } : {}),
+        apps: chain.apps,
+      },
     };
   }
 
   // Null for the legacy shape. Read off the source because the build enumerates routes without importing them.
   static #readChain(sourceFile: ts.SourceFile, filePath: string) {
     for (const statement of sourceFile.statements) {
+      const local = RouteSourceValidator.#defaultLocalOf(statement);
+      if (local && RouteSourceValidator.#bindsChain(sourceFile, local))
+        throw new Error(
+          `[route-convention] ${filePath} exports its chain through "${local}"; write \`export default page()…\` — the build reads the chain without evaluating the module`,
+        );
       if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
-      let node = RouteSourceValidator.#unwrapExpression(statement.expression);
-      const stages: ChainStage[] = [];
-      while (node && ts.isCallExpression(node)) {
-        const callee = node.expression;
-        if (ts.isPropertyAccessExpression(callee)) {
-          stages.unshift({ name: callee.name.text, args: node.arguments });
-          node = callee.expression;
-          continue;
-        }
-        if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
-          return RouteSourceValidator.#chainOf(callee.text as RouteSourceChain["kind"], stages, filePath);
-        return null;
+      const walked = RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(statement.expression));
+      return walked ? RouteSourceValidator.#chainOf(walked.kind, walked.stages, filePath) : null;
+    }
+    return null;
+  }
+
+  static #defaultLocalOf(statement: ts.Statement): string | undefined {
+    if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+      const node = RouteSourceValidator.#unwrapExpression(statement.expression);
+      return node && ts.isIdentifier(node) ? node.text : undefined;
+    }
+    if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier || statement.isTypeOnly) return undefined;
+    const clause = statement.exportClause;
+    if (!clause || !ts.isNamedExports(clause)) return undefined;
+    const element = clause.elements.find((element) => !element.isTypeOnly && element.name.text === "default");
+    return element?.propertyName && ts.isIdentifier(element.propertyName) ? element.propertyName.text : undefined;
+  }
+
+  static #walkChain(start: ts.Expression | undefined) {
+    let node = start;
+    const stages: ChainStage[] = [];
+    while (node && ts.isCallExpression(node)) {
+      const callee = node.expression;
+      if (ts.isPropertyAccessExpression(callee)) {
+        stages.unshift({ name: callee.name.text, args: node.arguments });
+        node = callee.expression;
+        continue;
       }
+      if (ts.isIdentifier(callee) && chainRoots.has(callee.text))
+        return { kind: callee.text as RouteSourceChain["kind"], stages };
       return null;
     }
     return null;
   }
 
+  static #bindsChain(sourceFile: ts.SourceFile, name: string) {
+    return sourceFile.statements.some(
+      (statement) =>
+        ts.isVariableStatement(statement) &&
+        statement.declarationList.declarations.some(
+          (declaration) =>
+            ts.isIdentifier(declaration.name) &&
+            declaration.name.text === name &&
+            !!RouteSourceValidator.#walkChain(RouteSourceValidator.#unwrapExpression(declaration.initializer)),
+        ),
+    );
+  }
+
   static #chainOf(kind: RouteSourceChain["kind"], stages: ChainStage[], filePath: string) {
     const params: string[] = [];
+    const apps: string[] = [];
     let prompt: string | undefined;
     let devOnly = false;
     const literal = (stage: ChainStage) => {
@@ -134,10 +181,11 @@ export class RouteSourceValidator {
     for (const stage of stages) {
       if (stage.name === "param") params.push(literal(stage));
       else if (stage.name === "prompt") prompt = literal(stage);
+      else if (stage.name === "app") apps.push(literal(stage));
       else if (stage.name === "config")
         devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
     }
-    return { kind, params, prompt, devOnly };
+    return { kind, params, prompt, apps, devOnly };
   }
 
   /** The same rule the loader applies: a page names every `[x]` it sits under, a layout may name a subset. */

package/scanInfo.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
 import type {
   AppConfigResult,
@@ -295,11 +296,19 @@ class ScanInfo {
 }
 
 export const isAkanFrameworkDependency = (dep: string) => dep === "akanjs" || dep.startsWith("akanjs/");
+export interface MigrationScanEntry {
+  id: string;
+  checksum: string;
+}
+
 export class AppInfo extends ScanInfo {
+  static readonly migrationDir = "script/migration";
+  static readonly #migrationIdRe = /^\d{12}_[A-Za-z][A-Za-z0-9]*$/;
   readonly type = "app";
   readonly exec: AppExecutor;
   readonly akanConfig: AppConfigResult;
   readonly libDeps: string[];
+  readonly migrations: MigrationScanEntry[];
 
   static appInfos = new Map<string, AppInfo>();
   static async fromExecutor(exec: AppExecutor, options: { refresh?: boolean } = {}) {
@@ -314,17 +323,21 @@ export class AppInfo extends ScanInfo {
         LibInfo.libInfos.set(libName, await LibInfo.fromExecutor(libExecutor));
       }),
     );
-    const libDeps = await AppInfo.#getAllLibDeps(exec, scanResult.libDeps);
-    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps);
+    const [libDeps, migrations] = await Promise.all([
+      AppInfo.#getAllLibDeps(exec, scanResult.libDeps),
+      AppInfo.scanMigrations(exec),
+    ]);
+    const appInfo = new AppInfo(exec, scanResult as AppScanResult, libDeps, migrations);
     AppInfo.appInfos.set(exec.name, appInfo);
     return appInfo;
   }
 
-  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[]) {
+  constructor(exec: AppExecutor, scanResult: AppScanResult, libDeps: string[], migrations: MigrationScanEntry[] = []) {
     super(scanResult);
     this.exec = exec;
     this.akanConfig = scanResult.akanConfig;
     this.libDeps = libDeps;
+    this.migrations = migrations;
   }
   override getScanResult(): AppScanResult {
     return this.scanResult as AppScanResult;
@@ -334,6 +347,26 @@ export class AppInfo extends ScanInfo {
     (this.scanResult as AppScanResult).routes = routes;
   }
 
+  //* Line endings and a BOM dropped: an editor or autocrlf would otherwise record another checksum for the same script.
+  static async scanMigrations(exec: AppExecutor) {
+    const files = (await exec.readdir(AppInfo.migrationDir)).filter(
+      (file) => file.endsWith(".ts") && !/\.(test|spec|d)\.ts$/.test(file),
+    );
+    return await Promise.all(
+      files.map(async (file) => {
+        const id = file.slice(0, -".ts".length);
+        if (!AppInfo.#migrationIdRe.test(id))
+          throw new Error(
+            `${AppInfo.migrationDir}/${file}: a migration is named <yyyyMMddHHmm>_<camelName>.ts; create one with \`akan create-migration\``,
+          );
+        const source = (await exec.readFile(`${AppInfo.migrationDir}/${file}`))
+          .replace(/^\uFEFF/, "")
+          .replaceAll("\r\n", "\n");
+        return { id, checksum: createHash("sha256").update(source).digest("hex") };
+      }),
+    );
+  }
+
   static async #getAllLibDeps(exec: AppExecutor, libDeps: string[], libSet = new Set<string>()) {
     await Promise.all(
       libDeps.map(async (libName) => {

package/transforms/mcpAppPageTrimmer.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { symlink } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { McpAppPageTrimmer } from "./mcpAppPageTrimmer";
+
+const makeTempRoot = tempDirs("akan-mcp-app-trim-");
+
+describe("McpAppPageTrimmer", () => {
+  test("hands every stage but the apps a function that draws nothing, and keeps the rest of the chain as written", () => {
+    const source = [
+      'import { fetch, Memo } from "@apps/minimal/client";',
+      'import { Screen } from "@apps/minimal/ui";',
+      "export default page()",
+      '  .param("memoId", ID)',
+      "  .config({ topInset: 48 })",
+      "  .guard(async ({ memoId }) => { await fetch.memo(memoId); })",
+      "  .head(<title>Memo</title>)",
+      "  .loading(() => <Screen>loading</Screen>)",
+      '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+      "  .render(({ memoId, showMemo }) => (",
+      '    <Screen className="pb-10">{showMemo}</Screen>',
+      "  ));",
+    ].join("\n");
+    expect(McpAppPageTrimmer.trim(source, "memo.tsx")).toBe(
+      [
+        'import { fetch, Memo } from "@apps/minimal/client";',
+        'import { Screen } from "@apps/minimal/ui";',
+        "export default page()",
+        '  .param("memoId", ID)',
+        "  .config({ topInset: 48 })",
+        "  .guard(() => null)",
+        "  .head(() => null)",
+        "  .loading(() => null)",
+        '  .app("showMemo", "Show one memo.", ({ memoId }) => <Memo.Zone.View view={fetch.viewMemo(memoId).memoView} />)',
+        "  .render(() => null);",
+      ].join("\n"),
+    );
+  });
+
+  test("trims a page reached through a link, as a synced lib page is", async () => {
+    const root = await makeTempRoot();
+    await writeText(
+      path.join(root, "libs/shared/page/login.tsx"),
+      [
+        "const page = () => ({ render: (draw: () => string) => draw });",
+        'export default page().render(() => "drawn by the render");',
+      ].join("\n"),
+    );
+    await symlink(path.join(root, "libs/shared/page"), path.join(root, "linked"));
+    await writeText(path.join(root, "entry.ts"), 'import login from "./linked/login.tsx";\nexport { login };\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "linked/login.tsx")])],
+    });
+    const [output] = result.outputs;
+    expect(result.success).toBe(true);
+    expect(await output?.text()).not.toContain("drawn by the render");
+  });
+
+  test("drops a lazy component only the page's render drew, with what it imports", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "Globe.ts"), 'export default "a heavy globe";\n');
+    await writeText(
+      path.join(root, "trip.tsx"),
+      [
+        "const lazy = (load: () => Promise<unknown>) => ({ load });",
+        'const Globe = lazy(() => import("./Globe"));',
+        "const page = () => ({ app: (name: string, draw: () => unknown) => ({ render: (render: () => unknown) => [name, draw, render] }) });",
+        'export default page().app("showTrip", () => "a trip card").render(() => Globe);',
+      ].join("\n"),
+    );
+    await writeText(path.join(root, "entry.ts"), 'import trip from "./trip.tsx";\nconsole.info(trip);\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [McpAppPageTrimmer.plugin([path.join(root, "trip.tsx")])],
+      splitting: false,
+    });
+    const text = (await result.outputs[0]?.text()) ?? "";
+    expect(result.success).toBe(true);
+    expect(text).toContain("a trip card");
+    expect(text).not.toContain("a heavy globe");
+  });
+
+  test("leaves a module with no chain as it is", () => {
+    const legacy = "export default function Page() { return <main />; }\nexport const pageConfig = {};";
+    expect(McpAppPageTrimmer.trim(legacy, "legacy.tsx")).toBe(legacy);
+  });
+});

package/transforms/mcpAppPageTrimmer.ts

@@ -0,0 +1,70 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+import { PureLazyMarker } from "./pureLazyMarker";
+
+type ChainStage = ts.CallExpression & { expression: ts.PropertyAccessExpression };
+
+//* An MCP App's view runs its page's `.app()` loads and no other stage, so the view build hands each such stage a
+//* function that draws nothing, and the bundler drops what only the page's own markup reached.
+export class McpAppPageTrimmer {
+  static readonly #unused = new Set(["render", "head", "loading", "guard"]);
+
+  /** Trims exactly `pagePaths`: the rest of the graph loads as it does for the CSR shell. */
+  static plugin(pagePaths: string[]): BunPlugin {
+    return {
+      name: "akan-mcp-app-page",
+      setup(build) {
+        if (!pagePaths.length) return;
+        //? The bundler loads a module by the path a link points at: a synced lib page is one under `page/(libs)`.
+        const loadedPaths = new Set(
+          pagePaths.flatMap((pagePath) => [pagePath, McpAppPageTrimmer.#realPathOf(pagePath)]),
+        );
+        const filter = new RegExp(`^(?:${[...loadedPaths].map((pagePath) => RegExp.escape(pagePath)).join("|")})$`);
+        //? The bundler runs one onLoad per module, so this one also marks the page's own `lazy()` components.
+        build.onLoad({ filter }, async (args) => ({
+          contents: PureLazyMarker.mark(McpAppPageTrimmer.trim(await Bun.file(args.path).text(), args.path), args.path),
+          loader: path.extname(args.path).slice(1) as "tsx" | "ts" | "jsx" | "js",
+        }));
+      },
+    };
+  }
+
+  static trim(source: string, filePath: string): string {
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const spans = McpAppPageTrimmer.#stagesOf(sourceFile)
+      .flatMap((stage) => {
+        const [first] = stage.arguments;
+        if (!first || !McpAppPageTrimmer.#unused.has(stage.expression.name.text)) return [];
+        return [{ start: first.getStart(sourceFile), end: first.getEnd() }];
+      })
+      .sort((a, b) => b.start - a.start);
+    let trimmed = source;
+    for (const { start, end } of spans) trimmed = `${trimmed.slice(0, start)}() => null${trimmed.slice(end)}`;
+    return trimmed;
+  }
+
+  static #realPathOf(filePath: string) {
+    try {
+      return realpathSync(filePath);
+    } catch {
+      return filePath;
+    }
+  }
+
+  static #stagesOf(sourceFile: ts.SourceFile): ChainStage[] {
+    const stages: ChainStage[] = [];
+    for (const statement of sourceFile.statements) {
+      if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+      let node: ts.Expression = statement.expression;
+      while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node))
+        node = node.expression;
+      while (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        stages.push(node as ChainStage);
+        node = node.expression.expression;
+      }
+    }
+    return stages;
+  }
+}

package/transforms/pureLazyMarker.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { tempDirs, writeText } from "../testHelpers";
+import { PureLazyMarker } from "./pureLazyMarker";
+
+const makeTempRoot = tempDirs("akan-pure-lazy-");
+
+describe("PureLazyMarker", () => {
+  test("marks each lazy() a declaration holds, and nothing else", () => {
+    const source = [
+      'import { lazy } from "akanjs/webkit";',
+      'export const Globe = lazy(() => import("./Globe_Dynamic"), { ssr: false });',
+      "const Editor: Component = lazy(() =>",
+      '  import("./Editor"),',
+      ");",
+      'const sample = `const Chart = lazy(() => import("./Chart"));`;',
+      'register(lazy(() => import("./Side")));',
+    ].join("\n");
+    expect(PureLazyMarker.mark(source, "ui.tsx")).toBe(
+      [
+        'import { lazy } from "akanjs/webkit";',
+        'export const Globe = /* @__PURE__ */ lazy(() => import("./Globe_Dynamic"), { ssr: false });',
+        "const Editor: Component = /* @__PURE__ */ lazy(() =>",
+        '  import("./Editor"),',
+        ");",
+        'const sample = `const Chart = lazy(() => import("./Chart"));`;',
+        'register(lazy(() => import("./Side")));',
+      ].join("\n"),
+    );
+    const plain = "export const one = 1;";
+    expect(PureLazyMarker.mark(plain, "plain.ts")).toBe(plain);
+  });
+
+  test("lets the bundler drop a barrel's lazy component that nothing renders, with what it imports", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "lazy.ts"), "export const lazy = (load: () => Promise<unknown>) => ({ load });\n");
+    await writeText(path.join(root, "Heavy.ts"), 'export default "a heavy chunk";\n');
+    await writeText(
+      path.join(root, "ui.ts"),
+      [
+        'import { lazy } from "./lazy";',
+        'export const Heavy = lazy(() => import("./Heavy"));',
+        'export const Card = "a card";',
+      ].join("\n"),
+    );
+    await writeText(path.join(root, "entry.ts"), 'import { Card } from "./ui";\nconsole.info(Card);\n');
+    const result = await Bun.build({
+      entrypoints: [path.join(root, "entry.ts")],
+      plugins: [PureLazyMarker.plugin()],
+      splitting: false,
+    });
+    const [output] = result.outputs;
+    expect(result.success).toBe(true);
+    const text = (await output?.text()) ?? "";
+    expect(text).toContain("a card");
+    expect(text).not.toContain("a heavy chunk");
+  });
+});

package/transforms/pureLazyMarker.ts

@@ -0,0 +1,42 @@
+import type { BunPlugin } from "bun";
+import ts from "typescript";
+
+//* A view inlines every module its loads reach, so a `lazy()` component that nothing renders (one of a barrel's, or
+//* of an `_overrides.tsx` manifest's) would still carry its chunk. `lazy()` only builds a component, so its call is
+//* marked pure, and the bundler drops it, chunk and all, wherever its result goes unread.
+export class PureLazyMarker {
+  static plugin(): BunPlugin {
+    return {
+      name: "akan-pure-lazy",
+      setup(build) {
+        build.onLoad({ filter: /\.tsx?$/ }, async (args) => {
+          const file = Bun.file(args.path);
+          //? A view's own entry lives only in the build's `files`, where the bundler reads it without a plugin.
+          if (!(await file.exists())) return undefined;
+          const source = await file.text();
+          const marked = PureLazyMarker.mark(source, args.path);
+          return marked === source
+            ? undefined
+            : { contents: marked, loader: args.path.endsWith(".tsx") ? "tsx" : "ts" };
+        });
+      },
+    };
+  }
+
+  static mark(source: string, filePath: string): string {
+    if (!source.includes("lazy(")) return source;
+    const kind = filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, kind);
+    const starts: number[] = [];
+    const visit = (node: ts.Node) => {
+      const call = ts.isVariableDeclaration(node) ? node.initializer : undefined;
+      if (call && ts.isCallExpression(call) && ts.isIdentifier(call.expression) && call.expression.text === "lazy")
+        starts.push(call.getStart(sourceFile));
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return starts
+      .sort((a, b) => b - a)
+      .reduce((marked, start) => `${marked.slice(0, start)}/* @__PURE__ */ ${marked.slice(start)}`, source);
+  }
+}