@akanjs/devkit 3.0.0-beta.26 → 3.0.0-beta.28

package/mobile/nativeConfig.test.ts

@@ -45,26 +45,29 @@ const adminTarget: AkanMobileTargetConfig = {
   },
 };
 
+const updatesKey = Buffer.alloc(32, 7).toString("base64");
+
 describe("NativeConfig.build", () => {
-  test("turns the minimal app's push target into the runtime's config", () => {
+  test("turns the minimal app's push target into the runtime's config, single-instance carrying its link scheme", () => {
     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"],
+      platform: "android",
     });
 
     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"],
+      plugins: [...NativeConfig.basePlugins, "single-instance", "push"],
       capabilities: [
         {
           identifier: "app",
           description: "The plugins minimal ships, each with its default permissions",
-          permissions: [...NativeConfig.basePlugins, "push"].map((plugin) => `${plugin}:default`),
+          permissions: [...NativeConfig.basePlugins, "single-instance", "push"].map((plugin) => `${plugin}:default`),
         },
       ],
       deepLinks: { schemes: ["minimal"], domains: ["example.com"] },
@@ -83,6 +86,7 @@ describe("NativeConfig.build", () => {
       webDir: "/repo/apps/portal/.akan/mobile/admin/web",
       contributions: [],
       locales: ["en", "ko"],
+      platform: "android",
     });
 
     expect(warnings).toEqual(["Permission 'speech' has no native plugin yet; the app ships without it."]);
@@ -138,6 +142,7 @@ describe("NativeConfig.build", () => {
         { permission: "push", plugins: ["push"] },
       ],
       locales: ["en"],
+      platform: "android",
     });
 
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "camera"]);
@@ -152,6 +157,75 @@ describe("NativeConfig.build", () => {
     });
   });
 
+  test("updates bring their plugin and follow the binary's backend unless a channel is named", () => {
+    const build = (updates: AkanMobileTargetConfig["updates"], env?: "main" | "develop") =>
+      NativeConfig.build({
+        appPath: "/repo/apps/portal",
+        target: { ...adminTarget, updates },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "android",
+        env,
+      }).config;
+    const url = "https://updates.example.com/portal";
+    expect(build({ url, publicKey: updatesKey }, "develop").updates).toEqual({
+      url,
+      publicKey: updatesKey,
+      channel: "develop",
+    });
+    expect(build({ url, publicKey: updatesKey, channel: "beta", readyTimeout: 15_000 }, "main").updates).toEqual({
+      url,
+      publicKey: updatesKey,
+      channel: "beta",
+      readyTimeout: 15_000,
+    });
+    expect(build({ url, publicKey: updatesKey }).updates).toEqual({ url, publicKey: updatesKey });
+    expect(build({ url, publicKey: updatesKey }, "main").plugins).toContain("updates");
+    expect(build(undefined, "main").plugins).not.toContain("updates");
+  });
+
+  test("push, privacy and the icon and splash objects reach the runtime, paths from the app folder", () => {
+    const { config } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: {
+        ...adminTarget,
+        assets: {
+          icon: { image: "assets/icon.png", backgroundColor: "#ffffff" },
+          splash: { backgroundColor: { light: "#ffffff", dark: "#000000" }, autoHide: false },
+        },
+        native: {
+          push: { android: { smallIcon: "assets/noti.png", color: "#ff5a5f", channel: { id: "chat", name: "Chat" } } },
+          privacy: { tracking: false, accessedApis: { DiskSpace: ["E174.1"] } },
+        },
+      },
+      webDir: "/web",
+      contributions: [],
+      locales: ["en"],
+      platform: "android",
+    });
+    const abs = (relative: string) => path.resolve("/repo/apps/portal", relative);
+    expect(config.icon).toEqual({ image: abs("assets/icon.png"), backgroundColor: "#ffffff" });
+    expect(config.splash).toEqual({ backgroundColor: { light: "#ffffff", dark: "#000000" }, autoHide: false });
+    expect(config.push).toEqual({
+      android: { smallIcon: abs("assets/noti.png"), color: "#ff5a5f", channel: { id: "chat", name: "Chat" } },
+    });
+    expect(config.privacy).toEqual({ tracking: false, accessedApis: { DiskSpace: ["E174.1"] } });
+  });
+
+  test("an app id per platform gives each build its own", () => {
+    const idOn = (platform: "ios" | "android") =>
+      NativeConfig.build({
+        appPath: "/repo/apps/portal",
+        target: { ...adminTarget, appId: { ios: "com.puffinplanet.admin", android: "com.portal.admin" } },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform,
+      }).config.app.id;
+    expect([idOn("ios"), idOn("android")]).toEqual(["com.puffinplanet.admin", "com.portal.admin"]);
+  });
+
   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"])
@@ -164,18 +238,146 @@ describe("NativeConfig.build", () => {
     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 adminWithEverything: AkanMobileTargetConfig = {
+      ...adminTarget,
+      updates: { url: "https://updates.example.com/portal", publicKey: updatesKey },
+      native: {
+        ...adminTarget.native,
+        push: { android: { smallIcon: "assets/icon.png", color: "#ff5a5f" } },
+        privacy: { tracking: false },
+      },
+    };
+    for (const target of [minimalTarget, adminWithEverything]) {
       const { config } = NativeConfig.build({
         appPath: root,
+        env: "main",
         target,
         webDir: path.join(root, "web"),
         contributions: [],
         locales: ["en", "ko"],
+        platform: "android",
       });
       expect(api.validateConfig(config, { appDir: root })).toEqual([]);
     }
   });
 
+  test("ships the app's own native plugins by folder and names each by its id in the capability", async () => {
+    const root = await makeTempRoot();
+    const kiosk = await writeManifest(path.join(root, "native", "kiosk"), "kiosk");
+    await writeManifest(path.join(root, "vendor", "led-panel"), "led-panel");
+    const { config } = NativeConfig.build({
+      appPath: root,
+      target: { ...minimalTarget, permissions: [], native: { plugins: ["./vendor/led-panel"] }, deepLinks: undefined },
+      webDir: path.join(root, "web"),
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+      nativePlugins: [{ id: "kiosk", dir: kiosk, owner: "apps/board" }],
+    });
+
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "./vendor/led-panel", kiosk]);
+    expect(config.capabilities?.[0]?.permissions).toEqual(
+      [...NativeConfig.basePlugins, "led-panel", "kiosk"].map((id) => `${id}:default`),
+    );
+    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);
+    expect(api.validateConfig(config, { appDir: root })).toEqual([]);
+  });
+
+  test("ships a native/ folder once when the target also lists it by path or by id", async () => {
+    const root = await makeTempRoot();
+    const kiosk = await writeManifest(path.join(root, "native", "kiosk"), "kiosk");
+    const { config } = NativeConfig.build({
+      appPath: root,
+      target: {
+        ...minimalTarget,
+        permissions: [],
+        native: { plugins: ["./native/kiosk/", "kiosk", "haptics"] },
+        deepLinks: undefined,
+      },
+      webDir: path.join(root, "web"),
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+      nativePlugins: [{ id: "kiosk", dir: kiosk, owner: "apps/board" }],
+    });
+
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, kiosk]);
+  });
+
+  test("hands an unattended app's settings on: page recovery, a kiosk window, screen capture and Android autoplay", async () => {
+    const root = await makeTempRoot();
+    const { config } = NativeConfig.build({
+      appPath: root,
+      target: {
+        ...minimalTarget,
+        permissions: [],
+        deepLinks: undefined,
+        native: {
+          android: { autoplay: true },
+          desktop: { recovery: "reload", window: { fullscreen: true, skipTaskbar: true }, screenCapture: "auto" },
+        },
+      },
+      webDir: path.join(root, "web"),
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+      desktopBin: root,
+    });
+
+    expect(config.desktop).toEqual({
+      recovery: "reload",
+      window: { fullscreen: true, skipTaskbar: true },
+      screenCapture: "auto",
+      bin: root,
+    });
+    expect(config.android).toEqual({ debugAppIdSuffix: ".debug", autoplay: true });
+    await mkdir(path.join(root, "web"), { recursive: true });
+    await writeFile(path.join(root, "web/index.html"), "<html><head></head><body></body></html>");
+    expect((await NativeApi.load(repoApp)).validateConfig(config, { appDir: root })).toEqual([]);
+  });
+
+  test("an app with updates ships the updates plugin and its settings", () => {
+    const updates = { url: "https://releases.example.com/board", publicKey: `${"a".repeat(43)}=`, channel: "pilot" };
+    const { config } = NativeConfig.build({
+      appPath: "/repo/apps/board",
+      target: { ...minimalTarget, permissions: [], deepLinks: undefined, native: undefined, updates },
+      webDir: "/web",
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+    });
+
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "updates"]);
+    expect(config.updates).toEqual(updates);
+  });
+
+  test("an updates channel left unnamed is the backend env the binary is built for", () => {
+    const updates = { url: "https://releases.example.com/board", publicKey: `${"a".repeat(43)}=` };
+    const build = (env?: "debug" | "main", channel?: string) =>
+      NativeConfig.build({
+        appPath: "/repo/apps/board",
+        target: {
+          ...minimalTarget,
+          permissions: [],
+          deepLinks: undefined,
+          native: undefined,
+          updates: { ...updates, ...(channel ? { channel } : {}) },
+        },
+        webDir: "/web",
+        contributions: [],
+        locales: ["en"],
+        platform: "macos",
+        ...(env ? { env } : {}),
+      }).config.updates;
+
+    expect(build("debug")).toEqual({ ...updates, channel: "debug" });
+    expect(build("main")).toEqual({ ...updates, channel: "main" });
+    expect(build("debug", "pilot")).toEqual({ ...updates, channel: "pilot" });
+    expect(build()).toEqual(updates);
+  });
+
   test("keeps a file name the runtime accepts", () => {
     expect(NativeConfig.fileNameOf("minimal")).toBe("minimal");
     expect(NativeConfig.fileNameOf("my app!")).toBe("my-app");
@@ -183,6 +385,15 @@ describe("NativeConfig.build", () => {
   });
 });
 
+const writeManifest = async (dir: string, id: string) => {
+  await mkdir(dir, { recursive: true });
+  await writeFile(
+    path.join(dir, "native-plugin.json"),
+    JSON.stringify({ id, apiVersion: 1, methods: [], events: [], web: null, desktop: null, ios: null, android: null }),
+  );
+  return dir;
+};
+
 const onePixelPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
 
 const googleServicesJson = JSON.stringify({

package/mobile/nativeConfig.ts

@@ -1,6 +1,16 @@
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
-import type { AkanMobileTargetConfig, AkanNativeValue, AkanPluginNativeConfig, MobilePermission } from "akanjs";
+import type {
+  AkanMobileTargetConfig,
+  AkanNativeValue,
+  AkanPluginNativeConfig,
+  MobileEnv,
+  MobilePermission,
+} from "akanjs";
+import type { DesktopServerBundle } from "./desktopServerStage";
+import { type NativePlatform, resolveAppId } from "./mobileTarget";
+import type { NativePluginFolder } from "./nativePluginFolders";
 import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
 
 export interface NativeConfigInput {
@@ -12,6 +22,15 @@ export interface NativeConfigInput {
   /** What the app's and its libs' plugins declare. */
   contributions: AkanPluginNativeConfig[];
   locales: readonly string[];
+  /** The backend the binary talks to; an updates channel left unnamed follows it. */
+  env?: MobileEnv;
+  platform: NativePlatform;
+  /** A desktop build that carries its server (the target's `native.desktop.server`). */
+  desktopServer?: DesktopServerBundle;
+  /** The plugins in the app's and its libs' `native/` folders. */
+  nativePlugins?: NativePluginFolder[];
+  /** A desktop build's staged `bin` executables (DesktopBin). */
+  desktopBin?: string;
 }
 
 export interface NativeConfigResult {
@@ -68,7 +87,18 @@ export class NativeConfig {
     speech: { permission: "speech" },
   };
 
-  static build({ appPath, target, webDir, contributions, locales }: NativeConfigInput): NativeConfigResult {
+  static build({
+    appPath,
+    target,
+    webDir,
+    contributions,
+    locales,
+    env,
+    platform,
+    desktopServer,
+    nativePlugins = [],
+    desktopBin,
+  }: NativeConfigInput): NativeConfigResult {
     const warnings: string[] = [];
     const applied = (target.permissions ?? []).flatMap((permission) => {
       const claimed = contributions.filter((contribution) => contribution.permission === permission);
@@ -78,13 +108,30 @@ export class NativeConfig {
       return used;
     });
     const abs = (relative: string) => path.resolve(appPath, relative);
+    const updates = NativeConfig.#updates(target, env);
+    const folders = new Set(nativePlugins.map((plugin) => path.resolve(plugin.dir)));
+    const folderIds = new Set(nativePlugins.map((plugin) => plugin.id));
+    //? A `native/<id>` folder ships by itself; listed again, by path or by id, it would reach the runtime twice.
+    const listed = (target.native?.plugins ?? []).filter((spec) =>
+      NativeConfig.#isId(spec) ? !folderIds.has(spec) : !folders.has(path.resolve(appPath, spec)),
+    );
     const plugins = [
       ...new Set([
         ...NativeConfig.basePlugins,
+        //? Windows and Linux open a link by starting the app again; without the hand-over it runs as a second app and
+        //? the instance whose auth-session start() waits for the callback never hears it.
+        ...(target.deepLinks?.schemes?.length ? ["single-instance"] : []),
         ...applied.flatMap((contribution) => contribution.plugins ?? []),
-        ...(target.native?.plugins ?? []),
+        //? A second copy of the app would start a second server on the same data.
+        ...(desktopServer ? ["single-instance"] : []),
+        ...(updates ? ["updates"] : []),
+        ...listed,
+        ...nativePlugins.map((plugin) => plugin.dir),
       ]),
     ];
+    const pluginIds = plugins.map(
+      (spec) => nativePlugins.find((plugin) => plugin.dir === spec)?.id ?? NativeConfig.#pluginId(appPath, spec),
+    );
     const usageDescriptions = Object.fromEntries(
       Object.entries(
         toIosInfoPlistUsageDescriptions(
@@ -119,9 +166,17 @@ export class NativeConfig {
     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 pushAndroid = target.native?.push?.android;
+    const desktop = NativeConfig.#compact<NonNullable<AkanNativeConfig["desktop"]>>({
+      recovery: target.native?.desktop?.recovery,
+      screenCapture: target.native?.desktop?.screenCapture,
+      window: NativeConfig.#compact({ ...target.native?.desktop?.window }),
+      server: desktopServer,
+      bin: desktopBin,
+    });
     const config: AkanNativeConfig = {
       app: {
-        id: target.appId,
+        id: resolveAppId(target.appId, platform),
         name: target.appName,
         fileName: target.fileName ?? NativeConfig.fileNameOf(path.basename(appPath)),
         version: target.version,
@@ -135,7 +190,7 @@ export class NativeConfig {
         {
           identifier: "app",
           description: `The plugins ${target.appName} ships, each with its default permissions`,
-          permissions: plugins.map((plugin) => `${plugin}:default`),
+          permissions: pluginIds.map((id) => `${id}:default`),
         },
       ],
       ...(Object.keys(usageDescriptions).length ? { usageDescriptions } : {}),
@@ -143,20 +198,74 @@ export class NativeConfig {
         ? { deepLinks: NativeConfig.#deepLinks(target, locales) }
         : {}),
       ...(native ? { native } : {}),
+      ...(updates ? { updates } : {}),
+      ...(pushAndroid
+        ? {
+            push: {
+              android: { ...pushAndroid, ...(pushAndroid.smallIcon ? { smallIcon: abs(pushAndroid.smallIcon) } : {}) },
+            },
+          }
+        : {}),
+      ...(target.native?.privacy ? { privacy: target.native.privacy } : {}),
       //? assetlinks.json vouches for `<appId>.debug` outside main, the suffix a debug build installs under.
-      android: { debugAppIdSuffix: ".debug", ...(googleServices ? { googleServices: abs(googleServices) } : {}) },
+      android: {
+        debugAppIdSuffix: ".debug",
+        ...(googleServices ? { googleServices: abs(googleServices) } : {}),
+        ...(target.native?.android?.autoplay ? { autoplay: true } : {}),
+      },
       keyboard: { resize: "none" },
-      ...(target.assets?.icon ? { icon: abs(target.assets.icon) } : {}),
-      ...(target.assets?.splash ? { splash: { image: abs(target.assets.splash) } } : {}),
+      ...(desktop ? { desktop } : {}),
+      ...(target.assets?.icon ? { icon: NativeConfig.#icon(target.assets.icon, abs) } : {}),
+      ...(target.assets?.splash ? { splash: NativeConfig.#splash(target.assets.splash, abs) } : {}),
     };
     return { config, warnings };
   }
 
+  static #icon(
+    icon: NonNullable<NonNullable<AkanMobileTargetConfig["assets"]>["icon"]>,
+    abs: (relative: string) => string,
+  ): NonNullable<AkanNativeConfig["icon"]> {
+    return typeof icon === "string" ? abs(icon) : { ...icon, image: abs(icon.image) };
+  }
+
+  static #splash(
+    splash: NonNullable<NonNullable<AkanMobileTargetConfig["assets"]>["splash"]>,
+    abs: (relative: string) => string,
+  ): NonNullable<AkanNativeConfig["splash"]> {
+    if (typeof splash === "string") return { image: abs(splash) };
+    return { ...splash, ...(splash.image ? { image: abs(splash.image) } : {}) };
+  }
+
+  //? akanConfig refuses a target whose merged updates lack url or publicKey; the type still has them optional.
+  static #updates(
+    target: AkanMobileTargetConfig,
+    env?: MobileEnv,
+  ): NonNullable<AkanNativeConfig["updates"]> | undefined {
+    const { url, publicKey, channel = env, ...rest } = target.updates ?? {};
+    return url && publicKey ? { ...rest, url, publicKey, ...(channel ? { channel } : {}) } : undefined;
+  }
+
   /** 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";
   }
 
+  //? A permission names a plugin by its id, and a plugin given by folder is named in its manifest; a spec the runtime
+  //? cannot read is left as it is for the runtime to report.
+  static #pluginId(appPath: string, spec: string) {
+    if (NativeConfig.#isId(spec)) return spec;
+    try {
+      const { id } = JSON.parse(readFileSync(path.join(path.resolve(appPath, spec), "native-plugin.json"), "utf8"));
+      return typeof id === "string" ? id : spec;
+    } catch {
+      return spec;
+    }
+  }
+
+  static #isId(spec: string) {
+    return !spec.startsWith(".") && !path.isAbsolute(spec);
+  }
+
   /** 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]) =>

package/mobile/nativePluginFolders.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { NativePluginFolders } from "./nativePluginFolders";
+
+const makeTempRoot = tempDirs("akan-native-plugin-folders-");
+
+const writePlugin = async (root: string, folder: string, id: unknown = folder) => {
+  const dir = path.join(root, "native", folder);
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, "native-plugin.json"), JSON.stringify({ id, apiVersion: 1, methods: [] }));
+  return dir;
+};
+
+const fakeApp = (root: string, libs: string[]) =>
+  ({
+    name: "board",
+    cwdPath: path.join(root, "apps", "board"),
+    workspace: { workspaceRoot: root },
+    getScanInfo: () => ({ getLibs: () => libs }),
+  }) as unknown as App;
+
+describe("NativePluginFolders", () => {
+  test("finds each plugin folder in native/, by name", async () => {
+    const root = await makeTempRoot();
+    const kiosk = await writePlugin(root, "kiosk");
+    const audio = await writePlugin(root, "audio-output");
+    await writeFile(path.join(root, "native", "README.md"), "notes");
+
+    expect(await NativePluginFolders.in(root, "apps/board")).toEqual([
+      { id: "audio-output", dir: audio, owner: "apps/board" },
+      { id: "kiosk", dir: kiosk, owner: "apps/board" },
+    ]);
+  });
+
+  test("answers nothing for an app with no native folder", async () => {
+    expect(await NativePluginFolders.in(await makeTempRoot(), "apps/board")).toEqual([]);
+  });
+
+  test("refuses a folder without a manifest, or one named apart from its id", async () => {
+    const root = await makeTempRoot();
+    await mkdir(path.join(root, "native", "helpers"), { recursive: true });
+    await expect(NativePluginFolders.in(root, "apps/board")).rejects.toThrow(
+      "apps/board/native/helpers has no native-plugin.json",
+    );
+
+    const other = await makeTempRoot();
+    await writePlugin(other, "kiosk-tools", "kiosk");
+    await expect(NativePluginFolders.in(other, "libs/kiosk")).rejects.toThrow(
+      'libs/kiosk/native/kiosk-tools/native-plugin.json has id "kiosk"; name the folder after its id.',
+    );
+  });
+
+  test("the app's own plugin wins an id, and two libs may not both hold one", () => {
+    const app = { id: "kiosk", dir: "/w/apps/board/native/kiosk", owner: "apps/board" };
+    const libKiosk = { id: "kiosk", dir: "/w/libs/signage/native/kiosk", owner: "libs/signage" };
+    const libAudio = { id: "audio", dir: "/w/libs/signage/native/audio", owner: "libs/signage" };
+
+    expect(NativePluginFolders.select([app], [libKiosk, libAudio])).toEqual([app, libAudio]);
+    expect(() =>
+      NativePluginFolders.select(
+        [],
+        [libKiosk, { ...libKiosk, dir: "/w/libs/venue/native/kiosk", owner: "libs/venue" }],
+      ),
+    ).toThrow('libs/signage and libs/venue both hold native plugin "kiosk"; give the app its own native/kiosk');
+  });
+
+  test("an app ships its own plugins and those of the libs it depends on, not of other libs", async () => {
+    const root = await makeTempRoot();
+    const own = await writePlugin(path.join(root, "apps", "board"), "kiosk");
+    const used = await writePlugin(path.join(root, "libs", "signage"), "audio");
+    await writePlugin(path.join(root, "libs", "unused"), "camera-rig");
+
+    expect(await NativePluginFolders.of(fakeApp(root, ["signage"]))).toEqual([
+      { id: "kiosk", dir: own, owner: "apps/board" },
+      { id: "audio", dir: used, owner: "libs/signage" },
+    ]);
+  });
+});

package/mobile/nativePluginFolders.ts

@@ -0,0 +1,60 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+
+export interface NativePluginFolder {
+  id: string;
+  /** Absolute: the native build takes a plugin that is not builtin by its folder. */
+  dir: string;
+  /** Whose `native/` holds it: `apps/<app>` or `libs/<lib>`. */
+  owner: string;
+}
+
+//* An app's and its libs' own native plugins, each in `native/<id>/` beside its `native-plugin.json`. Every mobile and
+//* desktop target of the app ships them (the manifest says per platform what runs there); a lib's reach only the apps
+//* that depend on it.
+export class NativePluginFolders {
+  static readonly folder = "native";
+
+  static async in(root: string, owner: string): Promise<NativePluginFolder[]> {
+    const base = path.join(root, NativePluginFolders.folder);
+    const entries = await readdir(base, { withFileTypes: true }).catch(() => []);
+    const folders = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    return await Promise.all(
+      folders.sort().map(async (name) => {
+        const where = `${owner}/${NativePluginFolders.folder}/${name}`;
+        const manifest = Bun.file(path.join(base, name, "native-plugin.json"));
+        if (!(await manifest.exists()))
+          throw new Error(`${where} has no native-plugin.json; a folder in native/ is one native plugin.`);
+        const { id } = (await manifest.json()) as { id?: unknown };
+        if (id !== name)
+          throw new Error(`${where}/native-plugin.json has id ${JSON.stringify(id)}; name the folder after its id.`);
+        return { id, dir: path.join(base, name), owner };
+      }),
+    );
+  }
+
+  /** The app's own plugin wins an id; two libs may not both claim one. */
+  static select(own: NativePluginFolder[], fromLibs: NativePluginFolder[]): NativePluginFolder[] {
+    const chosen = new Map(own.map((plugin) => [plugin.id, plugin]));
+    for (const plugin of fromLibs) {
+      const held = chosen.get(plugin.id);
+      if (!held) chosen.set(plugin.id, plugin);
+      else if (held.owner.startsWith("libs/"))
+        throw new Error(
+          `${held.owner} and ${plugin.owner} both hold native plugin "${plugin.id}"; give the app its own native/${plugin.id} to pick one.`,
+        );
+    }
+    return [...chosen.values()];
+  }
+
+  static async of(app: App): Promise<NativePluginFolder[]> {
+    const scanInfo = app.getScanInfo({ allowEmpty: true }) ?? (await app.scan({ write: false }));
+    const root = app.workspace.workspaceRoot;
+    const [own, ...fromLibs] = await Promise.all([
+      NativePluginFolders.in(app.cwdPath, `apps/${app.name}`),
+      ...scanInfo.getLibs().map((lib) => NativePluginFolders.in(path.join(root, "libs", lib), `libs/${lib}`)),
+    ]);
+    return NativePluginFolders.select(own ?? [], fromLibs.flat());
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.26",
+  "version": "3.0.0-beta.28",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -47,7 +47,7 @@
     "@earendil-works/pi-tui": "0.86.1",
     "@inquirer/prompts": "^8.4.3",
     "@tailwindcss/node": "^4.3.0",
-    "akanjs": "3.0.0-beta.26",
+    "akanjs": "3.0.0-beta.28",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",