@akanjs/devkit 3.0.0-beta.17 → 3.0.0-beta.19

package/abstractDoc.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import type { SysExecutor } from "./executors";
 
 export type AbstractKind = "domain" | "service" | "scalar" | "other";
@@ -5,10 +6,8 @@ export type AbstractKind = "domain" | "service" | "scalar" | "other";
 /** One `*.abstract.md` file: the agent-facing summary a module carries next to its source. */
 export class AbstractDoc {
   static readonly suffix = ".abstract.md";
-  /** `akan quality` warns above this and points at `akan compact`. */
+  /** `akan quality` warns above this. */
   static readonly maxLines = 300;
-  /** `akan compact` floor, and the line budget it compacts down to, so a compacted file is never a candidate again. */
-  static readonly compactMinLines = 40;
   // Abstracts only live in facet folders; globbing the sys root instead would walk node_modules.
   static readonly #facetRoots = "{lib,ui,webkit,srvkit,common,plugin}";
 
@@ -27,7 +26,9 @@ export class AbstractDoc {
     return folder.startsWith("_") ? "service" : "domain";
   }
   static async findAll(sys: SysExecutor, { module }: { module?: string | null } = {}) {
-    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`)).sort();
+    const filePaths = (await sys.getAllFiles(`${AbstractDoc.#facetRoots}/**/*${AbstractDoc.suffix}`))
+      .map((filePath) => filePath.split(path.sep).join("/"))
+      .sort();
     const docs = await Promise.all(filePaths.map((filePath) => AbstractDoc.read(sys, filePath)));
     if (!module) return docs;
     return docs.filter((doc) => doc.moduleName === module || doc.folderName === module);

package/akanApp/akanApp.host.ts

@@ -621,28 +621,37 @@ export class AkanAppHost {
     );
   }
   /**
-   * Another process's RSS, read from the OS rather than asked of the process. `/proc` where it exists,
-   * `ps` otherwise (macOS has no `/proc`). Null when it cannot be read, which callers treat as
-   * "no new information" rather than as zero.
+   * Another process's RSS, read from the OS rather than asked of the process. `tasklist` on Windows, `/proc`
+   * where it exists, `ps` otherwise (macOS has no `/proc`). Null when it cannot be read, which callers treat
+   * as "no new information" rather than as zero.
    */
   static async readProcessRssBytes(pid: number): Promise<number | null> {
+    if (process.platform === "win32")
+      return await AkanAppHost.#readRssKbVia(
+        ["tasklist", "/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"],
+        AkanAppHost.#tasklistRssKb,
+      );
     const status = await Bun.file(`/proc/${pid}/status`)
       .text()
       .catch(() => null);
     const vmRssKb = status === null ? null : /VmRSS:\s+(\d+) kB/.exec(status)?.[1];
     if (vmRssKb) return Number(vmRssKb) * 1024;
-    return await AkanAppHost.#readRssViaPs(pid);
+    return await AkanAppHost.#readRssKbVia(["ps", "-o", "rss=", "-p", String(pid)], (output) => Number(output.trim()));
   }
   /**
-   * `ps`, bounded. An absent `ps` is already handled — it answers `null`, which callers read as "no new
-   * information" — but a `ps` that never answers was not: the only caller awaits it after a 20s settle,
+   * `ps` or `tasklist`, bounded. An absent tool is already handled — it answers `null`, which callers read as
+   * "no new information" — but a `ps` that never answers was not: the only caller awaits it after a 20s settle,
    * so the recycle it was about to commit simply never happened, silently. The harness has hit exactly
    * this hang while shelling out to `ps` under load.
    */
-  static async #readRssViaPs(pid: number, timeoutMs = PS_RSS_TIMEOUT_MS): Promise<number | null> {
+  static async #readRssKbVia(
+    command: string[],
+    parseKb: (output: string) => number,
+    timeoutMs = PS_RSS_TIMEOUT_MS,
+  ): Promise<number | null> {
     let proc: Bun.Subprocess<"ignore", "pipe", "ignore">;
     try {
-      proc = Bun.spawn(["ps", "-o", "rss=", "-p", String(pid)], { stdio: ["ignore", "pipe", "ignore"] });
+      proc = Bun.spawn(command, { stdio: ["ignore", "pipe", "ignore"] });
     } catch {
       return null;
     }
@@ -650,7 +659,7 @@ export class AkanAppHost {
     try {
       const output = await new Response(proc.stdout).text();
       await proc.exited;
-      const rssKb = Number(output.trim());
+      const rssKb = parseKb(output);
       return Number.isFinite(rssKb) && rssKb > 0 ? rssKb * 1024 : null;
     } catch {
       return null;
@@ -658,6 +667,11 @@ export class AkanAppHost {
       clearTimeout(killer);
     }
   }
+  /** `Mem Usage` is the working set — what `process.memoryUsage.rss()` reports on Windows — in locale-grouped KB. */
+  static #tasklistRssKb(output: string): number {
+    const memUsage = /"([^"]*)"\s*$/m.exec(output)?.[1];
+    return memUsage ? Number(memUsage.replace(/\D/g, "")) : Number.NaN;
+  }
   #cancelRssRecycle(): void {
     this.#rssRecycleReason = null;
     this.#rssRecycleOver = null;

package/akanConfig/akanConfig.test.ts

@@ -249,31 +249,65 @@ describe("AkanAppConfig", () => {
       ...akanPackageJson.dependencies,
       ...akanPackageJson.peerDependencies,
     };
-    const singleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "single" }, baseDevEnv);
-    const multipleConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "multiple" }, baseDevEnv);
-    const clusterConfig = new AkanAppConfig(app, [], packageJson, { defaultDatabaseMode: "cluster" }, baseDevEnv);
-
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("ioredis");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("bullmq");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
-    expect(singleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("protobufjs");
-
-    expect(multipleConfig.getProductionPackageJson().dependencies).toMatchObject({
-      "@libsql/client": runtimeDependencies["@libsql/client"],
+    const configOf = (database: { modes: ("single" | "multiple" | "cluster")[] }) =>
+      new AkanAppConfig(app, [], packageJson, { database }, baseDevEnv);
+    const dependenciesOf = (config: AkanAppConfig) => config.getProductionPackageJson().dependencies ?? {};
+    const singleConfig = configOf({ modes: ["single"] });
+    const multipleConfig = configOf({ modes: ["multiple"] });
+    const clusterConfig = configOf({ modes: ["cluster"] });
+    const edgeAndCloud = configOf({ modes: ["single", "cluster"] });
+
+    for (const driver of ["ioredis", "bullmq", "postgres", "@libsql/client", "protobufjs"])
+      expect(dependenciesOf(singleConfig)).not.toHaveProperty(driver);
+    expect(dependenciesOf(multipleConfig)).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
       ioredis: runtimeDependencies.ioredis,
-      protobufjs: runtimeDependencies.protobufjs,
     });
-    expect(multipleConfig.getProductionPackageJson().dependencies).not.toHaveProperty("postgres");
-
-    expect(clusterConfig.getProductionPackageJson().dependencies).toMatchObject({
+    expect(dependenciesOf(clusterConfig)).toMatchObject({
       bullmq: runtimeDependencies.bullmq,
       ioredis: runtimeDependencies.ioredis,
       postgres: runtimeDependencies.postgres,
-      protobufjs: runtimeDependencies.protobufjs,
     });
-    expect(clusterConfig.getProductionPackageJson().dependencies).not.toHaveProperty("@libsql/client");
+    // multiple opens the same SQLite as single and Redis replaced protobuf on the wire, so neither ships by default.
+    for (const config of [multipleConfig, clusterConfig])
+      for (const driver of ["@libsql/client", "protobufjs"]) expect(dependenciesOf(config)).not.toHaveProperty(driver);
+    expect(dependenciesOf(multipleConfig)).not.toHaveProperty("postgres");
+    // One image for an edge site and a cloud cluster carries both modes' drivers, and says which it carries.
+    expect(dependenciesOf(edgeAndCloud)).toMatchObject({ postgres: runtimeDependencies.postgres });
+    expect(edgeAndCloud.dockerfile).toContain("ENV AKAN_DATABASE_MODES=single,cluster");
+    expect(singleConfig.dockerfile).toContain("ENV AKAN_DATABASE_MODES=single");
+  });
+
+  test("runs single when the app declares no mode", () => {
+    expect(new AkanAppConfig(app, [], packageJson, {}, baseDevEnv).database.modes).toEqual(["single"]);
+  });
+
+  test("refuses a mode name that is not one of the three, naming the file", () => {
+    expect(
+      () => new AkanAppConfig(app, [], packageJson, { database: { modes: ["clsuter" as "cluster"] } }, baseDevEnv),
+    ).toThrow("database.modes in apps/portal/akan.config.ts");
+  });
+
+  test("resolves a command's mode within the declared ones", () => {
+    const previous = process.env.AKAN_DATABASE_MODE;
+    try {
+      const config = new AkanAppConfig(
+        app,
+        [],
+        packageJson,
+        { database: { modes: ["single", "cluster"] } },
+        baseDevEnv,
+      );
+      delete process.env.AKAN_DATABASE_MODE;
+      expect(config.resolveDatabaseMode()).toBe("single");
+      process.env.AKAN_DATABASE_MODE = "cluster";
+      expect(config.resolveDatabaseMode()).toBe("cluster");
+      process.env.AKAN_DATABASE_MODE = "multiple";
+      expect(() => config.resolveDatabaseMode()).toThrow('Add "multiple" to database.modes');
+    } finally {
+      if (previous === undefined) delete process.env.AKAN_DATABASE_MODE;
+      else process.env.AKAN_DATABASE_MODE = previous;
+    }
   });
 
   test("resolves database mode runtime packages and missing install specs", () => {
@@ -300,20 +334,11 @@ describe("AkanAppConfig", () => {
     );
 
     expect(config.getDatabaseModeRuntimePackages("single")).toEqual([]);
-    expect(config.getDatabaseModeRuntimePackages("multiple")).toEqual([
-      "@libsql/client",
-      "bullmq",
-      "ioredis",
-      "protobufjs",
-    ]);
-    expect(config.getDatabaseModeRuntimePackages("cluster")).toEqual(["bullmq", "ioredis", "postgres", "protobufjs"]);
-    expect(config.getMissingDatabaseModeDependencySpecs("multiple")).toEqual([
-      `@libsql/client@${runtimeDependencies["@libsql/client"]}`,
-      `protobufjs@${runtimeDependencies.protobufjs}`,
-    ]);
+    expect(config.getDatabaseModeRuntimePackages("multiple")).toEqual(["bullmq", "ioredis"]);
+    expect(config.getDatabaseModeRuntimePackages("cluster")).toEqual(["bullmq", "ioredis", "postgres"]);
+    expect(config.getMissingDatabaseModeDependencySpecs("multiple")).toEqual([]);
     expect(config.getMissingDatabaseModeDependencySpecs("cluster")).toEqual([
       `postgres@${runtimeDependencies.postgres}`,
-      `protobufjs@${runtimeDependencies.protobufjs}`,
     ]);
     // The workspace-root install covers the toolchain/runtime plus every app Capacitor plugin
     // (deduped — "@capacitor/core" appears in both source lists).

package/akanConfig/akanConfig.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AkanPlugin } from "akanjs";
-import { normalizeRoutePrefix } from "akanjs/base";
+import { DatabaseModes, normalizeRoutePrefix } from "akanjs/base";
 import { type AkanI18nConfig, resolveAkanI18nConfig } from "akanjs/common";
 import type { AkanImageConfig } from "akanjs/server";
 import type { App, Lib } from "../commandDecorators";
@@ -11,6 +11,7 @@ import type { BaseDevEnv, PackageJson } from "../types";
 import {
   type AkanApiConfig,
   type AkanAssetsConfig,
+  type AkanDatabaseConfig,
   type AkanMobileConfig,
   type AkanMobileTargetConfig,
   type AkanRouteConfig,
@@ -93,16 +94,6 @@ const MOBILE_APP_CAPACITOR_PLUGINS = [
   "@capacitor/push-notifications",
   "capacitor-plugin-safe-area",
 ] as const;
-const DATABASE_MODE_RUNTIME_PACKAGES = {
-  single: [],
-  multiple: ["@libsql/client", "bullmq", "ioredis", "protobufjs"],
-  cluster: ["bullmq", "ioredis", "postgres", "protobufjs"],
-} satisfies Record<DatabaseMode, readonly string[]>;
-const AKAN_RUNTIME_PACKAGES = new Set<string>([
-  ...SSR_RUNTIME_PACKAGES,
-  ...MOBILE_RUNTIME_PACKAGES,
-  ...Object.values(DATABASE_MODE_RUNTIME_PACKAGES).flat(),
-]);
 const DEFAULT_AKAN_IMAGE_CONFIG: AkanImageConfig = {
   deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
   imageSizes: [32, 48, 64, 96, 128, 256, 384],
@@ -211,7 +202,7 @@ export class AkanAppConfig implements AppConfigResult {
   docker: DockerConfig;
   /** The Dockerfile `akan build` writes: the declared string verbatim, or one assembled from the parts. */
   dockerfile: string;
-  defaultDatabaseMode: DatabaseMode;
+  database: AkanDatabaseConfig;
   web: AkanWebConfig;
   externalLibs: string[];
   barrelImports: string[];
@@ -250,7 +241,7 @@ export class AkanAppConfig implements AppConfigResult {
     this.baseDevEnv = baseDevEnv;
     this.plugins = plugins;
     this.#applyRoutes(config?.routes);
-    this.defaultDatabaseMode = config?.defaultDatabaseMode ?? "single";
+    this.database = AkanAppConfig.#database(app, config);
     this.externalLibs = [...new Set([...(config?.externalLibs ?? []), ...libContributions.externalLibs])];
     this.barrelImports = [
       ...DEFAULT_BARREL_IMPORTS,
@@ -458,6 +449,7 @@ ENV AKAN_PUBLIC_LOCALES=${this.i18n.locales.join(",")}
 ENV AKAN_PUBLIC_API_PREFIX=${this.api.prefix}
 ENV AKAN_PUBLIC_WS_PREFIX=${this.api.websocketPrefix}
 ENV AKAN_PUBLIC_OPERATION_MODE=cloud
+ENV AKAN_DATABASE_MODES=${this.database.modes.join(",")}
 ENV AKAN_LOG_TO_FILE=0
 ${webEnvLines}
 CMD [${command.map((c) => `"${c}"`).join(",")}]`;
@@ -526,14 +518,31 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
     return akanPackageJson.dependencies?.[lib] ?? akanPackageJson.peerDependencies?.[lib];
   }
   #getProductionRuntimePackages() {
-    return [...this.externalLibs, ...SSR_RUNTIME_PACKAGES, ...this.getDatabaseModeRuntimePackages()];
+    return [
+      ...this.externalLibs,
+      ...SSR_RUNTIME_PACKAGES,
+      ...this.database.modes.flatMap((mode) => this.getDatabaseModeRuntimePackages(mode)),
+    ];
   }
-  getDatabaseModeRuntimePackages(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
-    return [...DATABASE_MODE_RUNTIME_PACKAGES[databaseMode]];
+  getDatabaseModeRuntimePackages(databaseMode: DatabaseMode) {
+    return [...DatabaseModes.drivers[databaseMode]];
   }
-  getMissingDatabaseModeDependencySpecs(databaseMode: DatabaseMode = this.defaultDatabaseMode) {
+  getMissingDatabaseModeDependencySpecs(databaseMode: DatabaseMode) {
     return this.#getMissingDependencySpecs(this.getDatabaseModeRuntimePackages(databaseMode));
   }
+  /** The mode a CLI command runs this app in: the shell's `AKAN_DATABASE_MODE` if the app declares it, else the first. */
+  resolveDatabaseMode() {
+    return DatabaseModes.resolve({
+      requested: process.env.AKAN_DATABASE_MODE,
+      declared: this.database.modes.join(","),
+      local: true,
+    });
+  }
+  static #database(app: App, config: AppConfigDeclaration): AkanDatabaseConfig {
+    const declared = config?.database?.modes?.filter((mode): mode is DatabaseMode => !!mode);
+    const modes = declared?.length ? declared : ["single"];
+    return { modes: DatabaseModes.parseList(modes.join(","), `database.modes in apps/${app.name}/akan.config.ts`) };
+  }
   getMobileRuntimePackages() {
     // The app Capacitor plugins are installed at the workspace root too, so bun can resolve the
     // app's "*" declarations to a hoisted, peer-pinned version instead of fetching latest.
@@ -558,6 +567,9 @@ CMD [${command.map((c) => `"${c}"`).join(",")}]`;
         return `${lib}@${version}`;
       });
   }
+  get akanVersion() {
+    return getAkanPackageJson().version;
+  }
   getProductionPackageJson(data: Partial<PackageJson> = {}): PackageJson {
     return {
       name: this.app.name,

package/akanConfig/types.ts

@@ -2,6 +2,7 @@ export type {
   AkanApiConfig,
   AkanAssetsConfig,
   AkanConfigFile,
+  AkanDatabaseConfig,
   AkanExecutor,
   AkanMobileConfig,
   AkanMobileTargetConfig,

package/applicationBuildRunner.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { AKAN_BACKEND_MINIFY, AKAN_OPTIONAL_BACKEND_EXTERNALS } from "./applicationBuildRunner";
 
 describe("ApplicationBuildRunner", () => {
@@ -16,8 +18,8 @@ describe("ApplicationBuildRunner", () => {
   });
 
   test("a bundler that mangles identifiers loses the class name a Logger reads", async () => {
-    const dir = `${process.env.TMPDIR ?? "/tmp"}/akan-minify-${Bun.randomUUIDv7()}`;
-    const entry = `${dir}/entry.ts`;
+    const dir = path.join(os.tmpdir(), `akan-minify-${Bun.randomUUIDv7()}`);
+    const entry = path.join(dir, "entry.ts");
     await Bun.write(
       entry,
       `const serve = () => class Service { readonly name = this.constructor.name; };
@@ -26,7 +28,7 @@ console.info(new SampleService().name);
 `,
     );
     const build = async (minify: Bun.BuildConfig["minify"]) => {
-      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: `${dir}/out` });
+      const result = await Bun.build({ entrypoints: [entry], target: "bun", minify, outdir: path.join(dir, "out") });
       expect(result.success).toBe(true);
       const proc = Bun.spawn([process.execPath, result.outputs[0].path], { stdout: "pipe" });
       return (await new Response(proc.stdout).text()).trim();

package/applicationBuildRunner.ts

@@ -191,9 +191,29 @@ export class ApplicationBuildRunner {
     await Promise.all([
       this.#app.dist.writeJson("package.json", akanConfig.getProductionPackageJson()),
       this.#app.dist.writeFile(`${this.#app.dist.cwdPath}/Dockerfile`, akanConfig.dockerfile),
+      this.#app.dist.writeJson("akan.build.json", {
+        buildId: await this.#resolveBuildId(),
+        akanVersion: akanConfig.akanVersion,
+        builtAt: new Date().toISOString(),
+      }),
     ]);
   }
 
+  //* Read back at runtime as `buildId` on the ops channel; a deployment's own AKAN_BUILD_ID still wins over it there.
+  async #resolveBuildId() {
+    const fromEnv = process.env.AKAN_BUILD_ID?.trim();
+    if (fromEnv) return fromEnv;
+    const root = this.#app.workspace.workspaceRoot;
+    const sha = Bun.spawnSync(["git", "rev-parse", "--short=12", "HEAD"], { cwd: root, stderr: "ignore" });
+    if (sha.exitCode !== 0) return null;
+    const dirty = Bun.spawnSync(["git", "status", "--porcelain", "--untracked-files=no"], {
+      cwd: root,
+      stderr: "ignore",
+    });
+    const suffix = dirty.exitCode === 0 && dirty.stdout.toString().trim() ? "-dirty" : "";
+    return `${sha.stdout.toString().trim()}${suffix}`;
+  }
+
   async #buildBackend() {
     const akanConfig = await this.#app.getConfig();
     const backendExternals = [
@@ -204,15 +224,21 @@ export class ApplicationBuildRunner {
     for (const entrypoint of backendEntryPoints) {
       if (!(await Bun.file(entrypoint).exists())) throw new Error(`Backend entrypoint not found: ${entrypoint}`);
     }
-    const backendResult = await this.#buildOrThrow("backend", {
-      entrypoints: backendEntryPoints,
+    const backendConfig = {
       outdir: this.#app.dist.cwdPath,
       target: "bun",
       minify: AKAN_BACKEND_MINIFY,
       naming: { entry: "[name].[ext]", chunk: "chunk-[hash].[ext]" },
       define: { "process.env.NODE_ENV": JSON.stringify("production") },
       plugins: backendExternals.length > 0 ? [this.#createExternalSpecifiersPlugin(backendExternals)] : [],
-    });
+    } satisfies Omit<Bun.BuildConfig, "entrypoints">;
+    //* Built apart so main.js keeps its own module copies; splitting moves lazy vendor `import()`s out of the boot
+    //* parse (minimal: server.js import 79ms → 24ms, 59MB → 36MB RSS).
+    const [mainResult, serverResult] = [
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[0]] }),
+      await this.#buildOrThrow("backend", { ...backendConfig, entrypoints: [backendEntryPoints[1]], splitting: true }),
+    ];
+    const backendResult = { outputs: [...mainResult.outputs, ...serverResult.outputs] };
     // Nothing spawns the RSC worker without SSR, so an api-only image does not carry it.
     const rscWorkerResult = web.ssr
       ? await this.#buildOrThrow("rsc-worker", {
@@ -246,11 +272,12 @@ export class ApplicationBuildRunner {
   async #writeConsoleShim() {
     await Bun.write(
       path.join(this.#app.dist.cwdPath, "console.js"),
-      `import { cnst, db, dict, option, server, sig, srv } from "./server.js";
-import { assertAkanConsoleAllowed, startAkanConsole } from "./console-runtime.js";
+      `process.env.AKAN_COMMAND_TYPE = "console";
+const { cnst, db, dict, option, server, sig, srv } = await import("./server.js");
+const { assertAkanConsoleAllowed, startAkanConsole } = await import("./console-runtime.js");
 
 const run = async () => {
-  assertAkanConsoleAllowed(server.env);
+  assertAkanConsoleAllowed();
   await server.start({ listen: false, web: false });
   try {
     await startAkanConsole(server, { globals: { cnst, db, dict, option, sig, srv } });

package/artifact/implicitRootLayout.test.ts

@@ -31,11 +31,11 @@ describe("resolveSsrPageEntries", () => {
     await write(path.join(appRoot, "env", "env.client.ts"), "export const env = {};\n");
     await write(
       rootLayoutPath,
-      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const metadata = { title: "Root" };\n',
+      'export const theme = "dark";\nexport const fonts = [{ name: "pretendard" }];\nexport const head = null;\n',
     );
     await write(
       groupedLayoutPath,
-      'export function generateMetadata() { return { title: "Home" }; }\nexport default function Layout({ children }) { return children; }\n',
+      "export function generateHead() { return null; }\nexport default function Layout({ children }) { return children; }\n",
     );
 
     const entries = await resolveSsrPageEntries({
@@ -54,15 +54,10 @@ describe("resolveSsrPageEntries", () => {
     expect(generatedSource).toContain('import * as inheritedModule from "../../../page/_layout.tsx";');
     expect(generatedSource).toContain("const inheritedLayout = resolveRouteModule(inheritedModule as never");
     expect(generatedSource).not.toContain("<System.Provider");
-    expect(generatedSource).toContain("export async function generateMetadata(props: PageProps)");
-    expect(generatedSource).toContain("if (userLayout.generateMetadata) return userLayout.generateMetadata(props);");
-    expect(generatedSource).toContain("if (userLayout.metadata !== undefined) return userLayout.metadata;");
-    expect(generatedSource).toContain(
-      "if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);",
-    );
-    expect(generatedSource).toContain("return inheritedLayout.metadata;");
-    expect(generatedSource).not.toContain("Object.keys(userLayout.metadata)");
-    expect(generatedSource).not.toContain("Object.keys(inheritedLayout.metadata)");
+    expect(generatedSource).toContain("export async function generateHead(props: PageProps)");
+    expect(generatedSource).toContain("if (userLayout.generateHead) return userLayout.generateHead(props);");
+    expect(generatedSource).toContain("return inheritedLayout.head;");
+    expect(generatedSource).not.toContain("generateMetadata");
     expect(generatedSource).toContain("export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;");
     expect(generatedSource).toContain("export const Error = userLayout.Error ?? inheritedLayout.Error;");
     expect(generatedSource).toContain("export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;");

package/artifact/implicitRootLayout.ts

@@ -236,13 +236,6 @@ export async function generateHead(props: PageProps) {
   return inheritedLayout.head;
 }
 
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;
@@ -258,7 +251,6 @@ ${layoutBinding}  return (
       theme={userLayout.theme ?? inheritedLayout.theme}
       fonts={loadFonts(userFonts)}
       className={defaultFontClassName}
-      gaTrackingId={userLayout.gaTrackingId ?? inheritedLayout.gaTrackingId}
       layoutStyle={userLayout.layoutStyle ?? inheritedLayout.layoutStyle}
       reconnect={userLayout.reconnect ?? inheritedLayout.reconnect ?? false}
       wsConnect={userLayout.wsConnect ?? inheritedLayout.wsConnect ?? true}
@@ -280,13 +272,6 @@ export async function generateHead(props: PageProps) {
   return inheritedLayout.head;
 }
 
-export async function generateMetadata(props: PageProps) {
-  if (userLayout.generateMetadata) return userLayout.generateMetadata(props);
-  if (userLayout.metadata !== undefined) return userLayout.metadata;
-  if (inheritedLayout.generateMetadata) return inheritedLayout.generateMetadata(props);
-  return inheritedLayout.metadata;
-}
-
 export const NotFound = userLayout.NotFound ?? inheritedLayout.NotFound;
 export const Error = userLayout.Error ?? inheritedLayout.Error;
 export const pageConfig = userLayout.pageConfig ?? inheritedLayout.pageConfig;

package/artifact/routeSeedIndex.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import path from "node:path";
 import { computeRouteSeedIndex, serializeRouteSeedIndexForArtifact } from "./routeSeedIndex";
 
 describe("computeRouteSeedIndex", () => {
@@ -19,10 +20,10 @@ describe("computeRouteSeedIndex", () => {
     ]);
 
     const leaf = index.entries.find((entry) => entry.routeId === "/:lang/foo");
-    expect(leaf?.seeds).toContain("/app/page/foo.tsx");
-    expect(leaf?.seeds).not.toContain("/app/page/foo/_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(leaf?.seeds).toContain("/app/page/_layout.tsx");
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/foo.tsx"));
+    expect(leaf?.seeds).not.toContain(path.resolve("/app/page/foo/_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(leaf?.seeds).toContain(path.resolve("/app/page/_layout.tsx"));
 
     expect(() =>
       computeRouteSeedIndex([
@@ -42,8 +43,8 @@ describe("computeRouteSeedIndex", () => {
       { key: "./robots.txt.tsx", moduleAbsPath: "/app/page/robots.txt.tsx" },
     ]);
     const robots = index.entries.find((entry) => entry.routeId === "/robots.txt");
-    expect(robots?.seeds).not.toContain("/app/.akan/generated/root-layouts/__root_layout.tsx");
-    expect(robots?.seeds).not.toContain("/app/page/_layout.tsx");
+    expect(robots?.seeds).not.toContain(path.resolve("/app/.akan/generated/root-layouts/__root_layout.tsx"));
+    expect(robots?.seeds).not.toContain(path.resolve("/app/page/_layout.tsx"));
   });
 
   test("serializes seed paths relative to the artifact directory", () => {

package/biome.base.json

@@ -154,7 +154,12 @@
       ]
     },
     {
-      "includes": ["{apps,libs}/**/page/**/*.ts", "{apps,libs}/**/page/**/*.tsx"],
+      "includes": [
+        "{apps,libs}/**/page/**/*.ts",
+        "{apps,libs}/**/page/**/*.tsx",
+        "{apps,libs}/**/*.Unit.tsx",
+        "{apps,libs}/**/*.View.tsx"
+      ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/non-scalar-props-restricted.grit"]
     },
     {

package/capacitorApp.test.ts

@@ -24,6 +24,7 @@ import {
   sanitizeIosNativeRunEnv,
   selectLocalDevHost,
   sortIosRunTargets,
+  toIosInfoPlistUsageDescriptions,
   writeRootCapacitorConfig,
 } from "./capacitorApp";
 
@@ -234,7 +235,7 @@ describe("iOS native run helpers", () => {
     expect(deviceCommand.xcodebuildArgs).toContain("id=device-1");
     expect(deviceCommand.xcodebuildArgs).toContain("App QA");
     expect(deviceCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/device-1/Build/Products/Debug-iphoneos/App.app"),
     );
 
     const simulatorCommand = buildIosNativeRunCommand({
@@ -243,7 +244,7 @@ describe("iOS native run helpers", () => {
     });
     expect(simulatorCommand.xcodebuildArgs).toContain("platform=iOS Simulator,id=sim-1");
     expect(simulatorCommand.appPath).toBe(
-      "/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app",
+      path.join("/repo/apps/minimal/ios/DerivedData/sim-1/Build/Products/Debug-iphonesimulator/App.app"),
     );
   });
 
@@ -370,3 +371,28 @@ describe("raiseGradleMinSdkVersion", () => {
     expect(raiseGradleMinSdkVersion("minSdkVersion = 28", 26)).toBeNull();
   });
 });
+
+describe("toIosInfoPlistUsageDescriptions", () => {
+  test("writes Apple's real Info.plist keys, not NS + the description name", () => {
+    expect(
+      toIosInfoPlistUsageDescriptions({
+        cameraUsageDescription: "camera",
+        photoAddUsageDescription: "add",
+        photoUsageDescription: "read",
+        locationAlwaysUsageDescription: "always",
+      }),
+    ).toEqual({
+      NSCameraUsageDescription: "camera",
+      NSPhotoLibraryAddUsageDescription: "add",
+      NSPhotoLibraryUsageDescription: "read",
+      NSLocationAlwaysAndWhenInUseUsageDescription: "always",
+      NSLocationAlwaysUsageDescription: "always",
+    });
+  });
+
+  test("keeps the NS prefix convention for a key it does not know", () => {
+    expect(toIosInfoPlistUsageDescriptions({ bluetoothAlwaysUsageDescription: "ble" })).toEqual({
+      NSBluetoothAlwaysUsageDescription: "ble",
+    });
+  });
+});

package/capacitorApp.ts

@@ -489,7 +489,7 @@ export function classifyIosRunFailure(log: string): IosRunFailureClassification
     kind: "unknown",
     title: "iOS native run failed.",
     detail:
-      "Review the xcodebuild/devicectl output above. You can retry with --noAllowProvisioningUpdates to use the conservative path.",
+      "Review the xcodebuild/devicectl output above. You can retry with --no-allow-provisioning-updates to use the conservative path.",
   };
 }
 
@@ -597,6 +597,29 @@ export function raiseGradleMinSdkVersion(content: string, floor: number = ANDROI
   return content.replace(/(minSdkVersion\s*=\s*)\d+/, `$1${floor}`);
 }
 
+//* Apple's Info.plist keys do not follow the description names (photo → NSPhotoLibrary…), so each one is spelled out.
+const iosUsageDescriptionKeys = {
+  cameraUsageDescription: ["NSCameraUsageDescription"],
+  photoAddUsageDescription: ["NSPhotoLibraryAddUsageDescription"],
+  photoUsageDescription: ["NSPhotoLibraryUsageDescription"],
+  contactsUsageDescription: ["NSContactsUsageDescription"],
+  //? iOS 11+ reads the AlwaysAndWhenInUse key; the Always key only serves iOS 10 and below.
+  locationAlwaysUsageDescription: ["NSLocationAlwaysAndWhenInUseUsageDescription", "NSLocationAlwaysUsageDescription"],
+  locationWhenInUseUsageDescription: ["NSLocationWhenInUseUsageDescription"],
+  microphoneUsageDescription: ["NSMicrophoneUsageDescription"],
+  speechRecognitionUsageDescription: ["NSSpeechRecognitionUsageDescription"],
+} as const;
+
+export const toIosInfoPlistUsageDescriptions = (descriptions: { [key: string]: string }) =>
+  Object.fromEntries(
+    Object.entries(descriptions).flatMap(([key, value]) => {
+      const plistKeys: readonly string[] = Object.hasOwn(iosUsageDescriptionKeys, key)
+        ? iosUsageDescriptionKeys[key as keyof typeof iosUsageDescriptionKeys]
+        : [`NS${capitalize(key)}`];
+      return plistKeys.map((plistKey) => [plistKey, value]);
+    }),
+  );
+
 const mergeAllowNavigation = (configured: unknown, localIp: string | undefined) => {
   const values = Array.isArray(configured)
     ? configured.filter((value): value is string => typeof value === "string")
@@ -1469,9 +1492,7 @@ export class CapacitorApp {
     if (next !== content) await editor.setContent(next).save();
   }
   async #setPermissionInIos(permissions: { [key: string]: string }) {
-    const updateNs = Object.fromEntries(
-      Object.entries(permissions).map(([key, value]) => [`NS${capitalize(key)}`, value]),
-    );
+    const updateNs = toIosInfoPlistUsageDescriptions(permissions);
     await Promise.all([
       this.project.ios.updateInfoPlist(this.iosTargetName, "Debug", updateNs),
       this.project.ios.updateInfoPlist(this.iosTargetName, "Release", updateNs),