@akanjs/devkit 3.0.0-beta.20 → 3.0.0-beta.22

package/mobile/nativeConfig.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanMobileTargetConfig } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { NativeApi } from "./nativeApi";
+import { NativeConfig } from "./nativeConfig";
+
+const makeTempRoot = tempDirs("akan-native-config-");
+const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
+
+const minimalTarget: AkanMobileTargetConfig = {
+  name: "default",
+  indexPath: "/explore",
+  appName: "minimal",
+  appId: "com.minimal.dev.app",
+  version: "0.0.1",
+  buildNum: 1,
+  permissions: ["push"],
+  native: { android: { googleServices: "secrets/google-services.json" } },
+  deepLinks: {
+    schemes: ["minimal"],
+    domains: ["example.com"],
+    ios: { teamId: "TEAMID" },
+    android: { sha256CertFingerprints: ["00:11"] },
+  },
+};
+
+const adminTarget: AkanMobileTargetConfig = {
+  name: "admin",
+  basePath: "admin",
+  appName: "Portal Admin",
+  appId: "com.portal.admin",
+  fileName: "portal-admin",
+  version: "2.1.0",
+  buildNum: 42,
+  assets: { icon: "assets/icon.png", splash: "assets/splash.png" },
+  permissions: ["camera", "location", "contacts", "speech"],
+  deepLinks: { domains: ["portal.example"] },
+  files: { "android/res/raw/chime.mp3": "assets/chime.mp3" },
+  native: {
+    plugins: ["iap"],
+    ios: { infoPlist: { ITSAppUsesNonExemptEncryption: false } },
+    android: { manifest: ['<queries><package android:name="com.kakao.talk" /></queries>'] },
+  },
+};
+
+describe("NativeConfig.build", () => {
+  test("turns the minimal app's push target into the runtime's config", () => {
+    const { config, warnings } = NativeConfig.build({
+      appPath: "/repo/apps/minimal",
+      target: minimalTarget,
+      webDir: "/repo/apps/minimal/.akan/mobile/default/web",
+      contributions: [{ permission: "push", plugins: ["push"] }],
+      locales: ["en", "ko"],
+    });
+
+    expect(warnings).toEqual([]);
+    expect(config).toEqual({
+      app: { id: "com.minimal.dev.app", name: "minimal", fileName: "minimal", version: "0.0.1", build: 1 },
+      web: { dir: "/repo/apps/minimal/.akan/mobile/default/web" },
+      plugins: [...NativeConfig.basePlugins, "push"],
+      capabilities: [
+        {
+          identifier: "app",
+          description: "The plugins minimal ships, each with its default permissions",
+          permissions: [...NativeConfig.basePlugins, "push"].map((plugin) => `${plugin}:default`),
+        },
+      ],
+      deepLinks: { schemes: ["minimal"], domains: ["example.com"] },
+      android: {
+        debugAppIdSuffix: ".debug",
+        googleServices: path.resolve("/repo/apps/minimal", "secrets/google-services.json"),
+      },
+      keyboard: { resize: "none" },
+    });
+  });
+
+  test("falls back to the builtin permission plugins, names the app in their texts, and lists basePath links per locale", () => {
+    const { config, warnings } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: adminTarget,
+      webDir: "/repo/apps/portal/.akan/mobile/admin/web",
+      contributions: [],
+      locales: ["en", "ko"],
+    });
+
+    expect(warnings).toEqual(["Permission 'speech' has no native plugin yet; the app ships without it."]);
+    expect(config).toEqual({
+      app: { id: "com.portal.admin", name: "Portal Admin", fileName: "portal-admin", version: "2.1.0", build: 42 },
+      web: { dir: "/repo/apps/portal/.akan/mobile/admin/web" },
+      plugins: [...NativeConfig.basePlugins, "camera", "geolocation", "contacts", "iap"],
+      capabilities: [
+        {
+          identifier: "app",
+          description: "The plugins Portal Admin ships, each with its default permissions",
+          permissions: [...NativeConfig.basePlugins, "camera", "geolocation", "contacts", "iap"].map(
+            (plugin) => `${plugin}:default`,
+          ),
+        },
+      ],
+      usageDescriptions: {
+        NSCameraUsageDescription: "Portal Admin requires access to the camera to take photos.",
+        NSPhotoLibraryAddUsageDescription: "Portal Admin requires access to the photo library to take photos.",
+        NSPhotoLibraryUsageDescription: "Portal Admin requires access to the photo library to take photos.",
+        NSLocationAlwaysAndWhenInUseUsageDescription:
+          "Portal Admin requires access to the location to get the user's location.",
+        NSLocationAlwaysUsageDescription: "Portal Admin requires access to the location to get the user's location.",
+        NSLocationWhenInUseUsageDescription: "Portal Admin requires access to the location to get the user's location.",
+        NSContactsUsageDescription: "Portal Admin requires access to the contacts to find people you know.",
+      },
+      deepLinks: { domains: [{ host: "portal.example", pathPrefixes: ["/en/admin", "/ko/admin"] }] },
+      native: {
+        ios: { infoPlist: { ITSAppUsesNonExemptEncryption: false } },
+        android: { manifest: ['<queries><package android:name="com.kakao.talk" /></queries>'] },
+        resources: [{ from: path.resolve("/repo/apps/portal", "assets/chime.mp3"), to: "android/res/raw/chime.mp3" }],
+      },
+      android: { debugAppIdSuffix: ".debug" },
+      keyboard: { resize: "none" },
+      icon: path.resolve("/repo/apps/portal", "assets/icon.png"),
+      splash: { image: path.resolve("/repo/apps/portal", "assets/splash.png") },
+    });
+  });
+
+  test("a plugin that claims a permission replaces the builtin one and adds its Android entries", () => {
+    const { config } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: { ...adminTarget, permissions: ["camera"], native: undefined, files: undefined, assets: undefined },
+      webDir: "/web",
+      contributions: [
+        {
+          permission: "camera",
+          plugins: ["camera"],
+          usageDescriptions: { cameraUsageDescription: "Scan receipts with $(PRODUCT_NAME)." },
+          androidPermissions: ["CAMERA"],
+          androidFeatures: ["android.hardware.camera"],
+        },
+        { permission: "push", plugins: ["push"] },
+      ],
+      locales: ["en"],
+    });
+
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "camera"]);
+    expect(config.usageDescriptions).toEqual({ NSCameraUsageDescription: "Scan receipts with Portal Admin." });
+    expect(config.native).toEqual({
+      android: {
+        manifest: [
+          '<uses-permission android:name="android.permission.CAMERA" />',
+          '<uses-feature android:name="android.hardware.camera" android:required="false" />',
+        ],
+      },
+    });
+  });
+
+  test("the runtime accepts both configs as they are", async () => {
+    const root = await makeTempRoot();
+    for (const file of ["secrets/google-services.json", "assets/chime.mp3"])
+      await mkdir(path.dirname(path.join(root, file)), { recursive: true }).then(() =>
+        writeFile(path.join(root, file), file.endsWith(".json") ? googleServicesJson : "x"),
+      );
+    for (const image of ["assets/icon.png", "assets/splash.png"])
+      await writeFile(path.join(root, image), Buffer.from(onePixelPng, "base64"));
+    await mkdir(path.join(root, "web"), { recursive: true });
+    await writeFile(path.join(root, "web/index.html"), "<html><head></head><body></body></html>");
+    const api = await NativeApi.load(repoApp);
+
+    for (const target of [minimalTarget, adminTarget]) {
+      const { config } = NativeConfig.build({
+        appPath: root,
+        target,
+        webDir: path.join(root, "web"),
+        contributions: [],
+        locales: ["en", "ko"],
+      });
+      expect(api.validateConfig(config, { appDir: root })).toEqual([]);
+    }
+  });
+
+  test("keeps a file name the runtime accepts", () => {
+    expect(NativeConfig.fileNameOf("minimal")).toBe("minimal");
+    expect(NativeConfig.fileNameOf("my app!")).toBe("my-app");
+    expect(NativeConfig.fileNameOf("...")).toBe("app");
+  });
+});
+
+const onePixelPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
+
+const googleServicesJson = JSON.stringify({
+  project_info: { project_number: "1", project_id: "demo", storage_bucket: "demo.appspot.com" },
+  client: [
+    {
+      client_info: { mobilesdk_app_id: "1:1:android:1", android_client_info: { package_name: "com.minimal.dev.app" } },
+      api_key: [{ current_key: "demo-key" }],
+    },
+    {
+      client_info: { mobilesdk_app_id: "1:1:android:2", android_client_info: { package_name: "com.portal.admin" } },
+      api_key: [{ current_key: "demo-key" }],
+    },
+  ],
+});

package/mobile/nativeConfig.ts

@@ -0,0 +1,190 @@
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { AkanMobileTargetConfig, AkanNativeValue, AkanPluginNativeConfig, MobilePermission } from "akanjs";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+export interface NativeConfigInput {
+  /** The app folder; every relative path in the target resolves against it. */
+  appPath: string;
+  target: AkanMobileTargetConfig;
+  /** The assembled web root the app loads. */
+  webDir: string;
+  /** What the app's and its libs' plugins declare. */
+  contributions: AkanPluginNativeConfig[];
+  locales: readonly string[];
+}
+
+export interface NativeConfigResult {
+  config: AkanNativeConfig;
+  warnings: string[];
+}
+
+type NativeIos = NonNullable<NonNullable<AkanNativeConfig["native"]>["ios"]>;
+
+export class NativeConfig {
+  //* What every akanjs page may call: routing, lifecycle, links, storage, the device facts the runtime reads, and the
+  //* system sheet useCamera asks camera-or-library with.
+  static readonly basePlugins = [
+    "app",
+    "app-state",
+    "browser",
+    "opener",
+    "auth-session",
+    "device",
+    "dialog",
+    "keyboard",
+    "preferences",
+    "secure-storage",
+    "haptics",
+  ] as const;
+  //* Used when no plugin of the app or its libs claims the permission; speech has no native plugin yet.
+  static readonly builtinContributions: { [permission in MobilePermission]: AkanPluginNativeConfig } = {
+    camera: {
+      permission: "camera",
+      plugins: ["camera"],
+      usageDescriptions: {
+        cameraUsageDescription: "$(PRODUCT_NAME) requires access to the camera to take photos.",
+        photoAddUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+        photoUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+      },
+    },
+    contacts: {
+      permission: "contacts",
+      plugins: ["contacts"],
+      usageDescriptions: {
+        contactsUsageDescription: "$(PRODUCT_NAME) requires access to the contacts to find people you know.",
+      },
+    },
+    location: {
+      permission: "location",
+      plugins: ["geolocation"],
+      usageDescriptions: {
+        locationAlwaysUsageDescription: "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+        locationWhenInUseUsageDescription:
+          "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+      },
+    },
+    push: { permission: "push", plugins: ["push"] },
+    speech: { permission: "speech" },
+  };
+
+  static build({ appPath, target, webDir, contributions, locales }: NativeConfigInput): NativeConfigResult {
+    const warnings: string[] = [];
+    const applied = (target.permissions ?? []).flatMap((permission) => {
+      const claimed = contributions.filter((contribution) => contribution.permission === permission);
+      const used = claimed.length ? claimed : [NativeConfig.builtinContributions[permission]];
+      if (!used.some((contribution) => contribution.plugins?.length))
+        warnings.push(`Permission '${permission}' has no native plugin yet; the app ships without it.`);
+      return used;
+    });
+    const abs = (relative: string) => path.resolve(appPath, relative);
+    const plugins = [
+      ...new Set([
+        ...NativeConfig.basePlugins,
+        ...applied.flatMap((contribution) => contribution.plugins ?? []),
+        ...(target.native?.plugins ?? []),
+      ]),
+    ];
+    const usageDescriptions = Object.fromEntries(
+      Object.entries(
+        toIosInfoPlistUsageDescriptions(
+          Object.assign({}, ...applied.map((contribution) => contribution.usageDescriptions ?? {})),
+        ),
+      ).map(([key, text]) => [key, text.replaceAll("$(PRODUCT_NAME)", target.appName)]),
+    );
+    const ios = NativeConfig.#compact<NativeIos>({
+      infoPlist: NativeConfig.#merged(
+        applied.map((c) => c.infoPlist),
+        target.native?.ios?.infoPlist,
+      ),
+      entitlements: NativeConfig.#merged(
+        applied.map((c) => c.entitlements),
+        target.native?.ios?.entitlements,
+      ),
+    });
+    const manifest = [
+      ...[...new Set(applied.flatMap((c) => c.androidPermissions ?? []))].map(
+        (name) => `<uses-permission android:name="android.permission.${name}" />`,
+      ),
+      ...[...new Set(applied.flatMap((c) => c.androidFeatures ?? []))].map(
+        (name) => `<uses-feature android:name="${name}" android:required="false" />`,
+      ),
+      ...(target.native?.android?.manifest ?? []),
+    ];
+    const android = NativeConfig.#compact({
+      manifest,
+      application: target.native?.android?.application ?? [],
+      activity: target.native?.android?.activity ?? [],
+    });
+    const resources = Object.entries(target.files ?? {}).map(([to, from]) => ({ from: abs(from), to }));
+    const native = NativeConfig.#compact({ ios, android, resources });
+    const googleServices = target.native?.android?.googleServices;
+    const config: AkanNativeConfig = {
+      app: {
+        id: target.appId,
+        name: target.appName,
+        fileName: target.fileName ?? NativeConfig.fileNameOf(path.basename(appPath)),
+        version: target.version,
+        build: target.buildNum,
+      },
+      web: { dir: webDir },
+      plugins,
+      //? PL-11: named, not implied: every plugin with its own default permissions, which is what a build without
+      //? capabilities grants too, so a release states what it allows.
+      capabilities: [
+        {
+          identifier: "app",
+          description: `The plugins ${target.appName} ships, each with its default permissions`,
+          permissions: plugins.map((plugin) => `${plugin}:default`),
+        },
+      ],
+      ...(Object.keys(usageDescriptions).length ? { usageDescriptions } : {}),
+      ...(target.deepLinks?.schemes?.length || target.deepLinks?.domains?.length
+        ? { deepLinks: NativeConfig.#deepLinks(target, locales) }
+        : {}),
+      ...(native ? { native } : {}),
+      //? assetlinks.json vouches for `<appId>.debug` outside main, the suffix a debug build installs under.
+      android: { debugAppIdSuffix: ".debug", ...(googleServices ? { googleServices: abs(googleServices) } : {}) },
+      keyboard: { resize: "none" },
+      ...(target.assets?.icon ? { icon: abs(target.assets.icon) } : {}),
+      ...(target.assets?.splash ? { splash: { image: abs(target.assets.splash) } } : {}),
+    };
+    return { config, warnings };
+  }
+
+  /** Letters, digits, `.`, `_` and `-` only; the folder name of an akan app already is one almost always. */
+  static fileNameOf(name: string) {
+    return name.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[-.]+|[-.]+$/g, "") || "app";
+  }
+
+  /** Drops empty arrays and objects, and answers undefined when nothing is left. */
+  static #compact<T extends object>(value: { [key: string]: unknown }): T | undefined {
+    const kept = Object.entries(value).filter(([, entry]) =>
+      Array.isArray(entry)
+        ? entry.length > 0
+        : entry && typeof entry === "object"
+          ? Object.keys(entry).length > 0
+          : entry !== undefined,
+    );
+    return kept.length ? (Object.fromEntries(kept) as T) : undefined;
+  }
+
+  static #merged(
+    contributed: (Record<string, AkanNativeValue> | undefined)[],
+    own: Record<string, AkanNativeValue> | undefined,
+  ): Record<string, AkanNativeValue> {
+    return Object.assign({}, ...contributed, own);
+  }
+
+  //* Every route sits under /:lang, so an app link limited to a basePath lists it once per locale.
+  static #deepLinks(target: AkanMobileTargetConfig, locales: readonly string[]) {
+    const basePath = target.basePath?.replace(/^\/+|\/+$/g, "");
+    const pathPrefixes = basePath ? locales.map((locale) => `/${locale}/${basePath}`) : undefined;
+    return {
+      ...(target.deepLinks?.schemes?.length ? { schemes: target.deepLinks.schemes } : {}),
+      ...(target.deepLinks?.domains?.length
+        ? { domains: target.deepLinks.domains.map((host) => (pathPrefixes ? { host, pathPrefixes } : host)) }
+        : {}),
+    };
+  }
+}

package/mobile/nativeWebDir.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanMobileTargetConfig } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { NativeWebDir } from "./nativeWebDir";
+
+const makeTempRoot = tempDirs("akan-native-web-");
+
+const target: AkanMobileTargetConfig = {
+  name: "admin",
+  basePath: "/admin/",
+  indexPath: "/home",
+  appName: "Portal",
+  appId: "com.portal.admin",
+  version: "1.0.0",
+  buildNum: 1,
+};
+
+const write = async (file: string, content: string) => {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, content);
+};
+
+describe("NativeWebDir", () => {
+  test("injects the target global once, first in <head>, even when the inlined bundle names it", () => {
+    const bundle = '<script type="module">if(!window.__AKAN_MOBILE_TARGET__)boot("</head>")</script>';
+    const html = NativeWebDir.injectTarget(`<html><HEAD lang="en">${bundle}</head><body></body></html>`, target);
+
+    expect(html).toBe(
+      `<html><HEAD lang="en">\n<script>window.__AKAN_MOBILE_TARGET__={"name":"admin","basePath":"admin","indexPath":"/home"};</script>${bundle}</head><body></body></html>`,
+    );
+    expect(NativeWebDir.injectTarget(html, target)).toBe(html);
+  });
+
+  test("assembles the page, the pruned public folder and the fonts, from scratch every time", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "dist/csr/admin.html"), "<html><head></head><body>app</body></html>");
+    await write(path.join(root, "dist/public/images/logo.png"), "png");
+    await write(path.join(root, "dist/public/index.html"), "stale page from public");
+    await write(path.join(root, "dist/.akan/artifact/fonts/pretendard/400.woff2"), "font");
+    const web = new NativeWebDir(path.join(root, "web"));
+    await write(path.join(root, "web/leftover.txt"), "from the last build");
+
+    const files = await web.assemble(target, {
+      html: path.join(root, "dist/csr/admin.html"),
+      publicDir: path.join(root, "dist/public"),
+      fontsDir: path.join(root, "dist/.akan/artifact/fonts"),
+    });
+
+    expect(files).toEqual(["_akan/fonts/pretendard/400.woff2", "images/logo.png", "index.html"]);
+    expect(await Bun.file(path.join(root, "web/index.html")).text()).toContain("window.__AKAN_MOBILE_TARGET__");
+  });
+
+  test("builds without a public folder or fonts", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "index.html"), "<html><head></head></html>");
+
+    const files = await new NativeWebDir(path.join(root, "web")).assemble(target, {
+      html: path.join(root, "index.html"),
+      publicDir: path.join(root, "missing-public"),
+    });
+
+    expect(files).toEqual(["index.html"]);
+  });
+
+  test("refuses a missing bundle and a public folder that takes the runtime's reserved path", async () => {
+    const root = await makeTempRoot();
+    const web = new NativeWebDir(path.join(root, "web"));
+    await expect(web.assemble(target, { html: path.join(root, "none.html") })).rejects.toThrow(
+      "CSR html for mobile target 'admin' not found",
+    );
+
+    await write(path.join(root, "index.html"), "<html><head></head></html>");
+    await write(path.join(root, "public/__akan_native/x.js"), "x");
+    await expect(
+      web.assemble(target, { html: path.join(root, "index.html"), publicDir: path.join(root, "public") }),
+    ).rejects.toThrow("public/__akan_native is reserved for the native runtime");
+  });
+});

package/mobile/nativeWebDir.ts

@@ -0,0 +1,62 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import type { AkanMobileTargetConfig } from "akanjs";
+
+export interface NativeWebDirSources {
+  /** The target's CSR bundle: one HTML file with its scripts and styles inlined. */
+  html: string;
+  /** The build's own copy of `public/`, already pruned of fonts nothing reads. */
+  publicDir?: string;
+  /** Subset fonts, served from `/_akan/fonts` as the page's `<FontFace>` names them. */
+  fontsDir?: string;
+}
+
+export class NativeWebDir {
+  //* The runtime serves its bridge from this prefix and refuses a web root that has one of its own.
+  static readonly reservedEntry = "__akan_native";
+
+  constructor(readonly dir: string) {}
+
+  //* The bundle is inlined into this page and its own code names the global, so only the tag marks an injection;
+  //* it goes first in <head>, ahead of every script, because the page reads it as it boots.
+  static injectTarget(html: string, target: Pick<AkanMobileTargetConfig, "name" | "basePath" | "indexPath">) {
+    if (html.includes(NativeWebDir.#targetTag)) return html;
+    const basePath = target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
+    const script = `${NativeWebDir.#targetTag}${JSON.stringify({
+      name: target.name,
+      basePath,
+      indexPath: target.indexPath,
+    })};</script>`;
+    const head = /<head(?:\s[^>]*)?>/i.exec(html);
+    if (!head) return `${script}\n${html}`;
+    const at = head.index + head[0].length;
+    return `${html.slice(0, at)}\n${script}${html.slice(at)}`;
+  }
+  static readonly #targetTag = "<script>window.__AKAN_MOBILE_TARGET__=";
+
+  /** Rebuilds the folder from scratch and answers its files as web paths: relative, `/`-separated and sorted. */
+  async assemble(target: AkanMobileTargetConfig, { html, publicDir, fontsDir }: NativeWebDirSources) {
+    if (!(await Bun.file(html).exists()))
+      throw new Error(`CSR html for mobile target '${target.name}' not found: ${html}`);
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    if (publicDir && (await NativeWebDir.#isDir(publicDir))) await cp(publicDir, this.dir, { recursive: true });
+    if (fontsDir && (await NativeWebDir.#isDir(fontsDir)))
+      await cp(fontsDir, path.join(this.dir, "_akan", "fonts"), { recursive: true });
+    if (await NativeWebDir.#isDir(path.join(this.dir, NativeWebDir.reservedEntry)))
+      throw new Error(`public/${NativeWebDir.reservedEntry} is reserved for the native runtime.`);
+    await Bun.write(path.join(this.dir, "index.html"), NativeWebDir.injectTarget(await Bun.file(html).text(), target));
+    const files = await Array.fromAsync(new Bun.Glob("**/*").scan({ cwd: this.dir, onlyFiles: true, dot: true }));
+    //? Bun.Glob answers with the platform's separator, so a Windows scan reads `_akan\fonts\…`.
+    return files.map((file) => file.split(path.sep).join("/")).sort();
+  }
+
+  static async #isDir(dir: string) {
+    try {
+      return (await stat(dir)).isDirectory();
+    } catch {
+      // A missing folder is a source the build did not produce, not an error.
+      return false;
+    }
+  }
+}

package/mobile/placeholderAppId.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import { isPlaceholderAppId } from "./placeholderAppId";
+
+describe("isPlaceholderAppId", () => {
+  test("flags placeholder bundle identifiers that Apple's portal already claims", () => {
+    for (const appId of ["com.myapp.app", "com.myorg.myapp", "com.example.foo", "com.changeme.app", ""]) {
+      expect(isPlaceholderAppId(appId)).toBe(true);
+    }
+    for (const appId of ["com.minimal.app", "com.nearthlab.leadingflight", "io.akanjs.demo"]) {
+      expect(isPlaceholderAppId(appId)).toBe(false);
+    }
+  });
+});

package/mobile/placeholderAppId.ts

@@ -0,0 +1,16 @@
+// Placeholder bundle IDs are already claimed on Apple's portal, so device signing fails with "cannot be registered
+// to your development team".
+export const PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp",
+] as const;
+const placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+
+export const isPlaceholderAppId = (appId: string | null | undefined): boolean => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized) return true;
+  if ((PLACEHOLDER_APP_IDS as readonly string[]).includes(normalized)) return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};

package/mobile/usageDescriptions.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+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/mobile/usageDescriptions.ts

@@ -0,0 +1,24 @@
+import { capitalize } from "akanjs/common";
+
+//* 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]);
+    }),
+  );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.20",
+  "version": "3.0.0-beta.22",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,8 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-beta.20",
+    "akanjs": "3.0.0-beta.22",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",
@@ -64,13 +63,9 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@capacitor/cli": "^8.3.4",
     "react": "19.2.7"
   },
   "peerDependenciesMeta": {
-    "@capacitor/cli": {
-      "optional": true
-    },
     "react": {
       "optional": true
     }

package/qualityScanner.ts

@@ -7,7 +7,7 @@ import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
 import { FormSetterScanner } from "./formSetterScanner";
 import { fileWarning, formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
-import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles } from "./workspaceLayout";
+import { isAllowedLibFacetRootFile, rootAllowedDirs, rootAllowedFiles, rootEntryHintOf } from "./workspaceLayout";
 
 type QualitySeverity = "warning";
 type QualityScope = "global" | "file" | "convention" | "layout" | "ssr" | "agent";
@@ -425,7 +425,9 @@ export class AkanQualityScanner {
             `akan.layout.${type}-root-${kind}`,
             "layout",
             sourceFile.file,
-            `Unexpected ${type} root ${kind} "${name}". Keep ${type} code in conventional ${type} folders.`,
+            `Unexpected ${type} root ${kind} "${name}". ${
+              rootEntryHintOf(type, name) ?? `Keep ${type} code in conventional ${type} folders.`
+            }`,
           ),
         );
     }