@akanjs/devkit 3.0.0-beta.3 → 3.0.0-beta.31

package/mobile/desktopServerStage.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AkanAppConfig } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import { tempDirs, writeText as write } from "../testHelpers";
+import type { PackageJson } from "../types";
+import { DesktopServerStage } from "./desktopServerStage";
+import { NativeApi } from "./nativeApi";
+import { NativeApp } from "./nativeApp";
+import { NativeConfig } from "./nativeConfig";
+
+const makeTempRoot = tempDirs("akan-desktop-server-");
+const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
+const baseDevEnv = {
+  repoName: "akanjs",
+  serveDomain: "akanjs.com",
+  env: "debug" as const,
+  portOffset: 0,
+  workspaceRoot: "/w",
+};
+const rootPackageJson: PackageJson = {
+  name: "repo",
+  version: "1.0.0",
+  description: "repo",
+  dependencies: { "@external/runtime": "2.0.0", pg: "8.0.0" },
+};
+const appConfig = (config: object = {}) =>
+  new AkanAppConfig({ name: "portal" } as never, [], rootPackageJson, config, baseDevEnv);
+
+describe("DesktopServerStage", () => {
+  test("starts from the image's env, as an API-only edge server on SQLite that the launcher gives a port", () => {
+    const env = DesktopServerStage.env(appConfig({ database: { modes: ["single", "cluster"] } }), "main");
+
+    expect(env).toMatchObject({
+      NODE_ENV: "production",
+      AKAN_PUBLIC_APP_NAME: "portal",
+      AKAN_PUBLIC_ENV: "main",
+      AKAN_PUBLIC_OPERATION_MODE: "edge",
+      AKAN_DATABASE_MODE: "single",
+      AKAN_DATABASE_MODES: "single",
+      AKAN_SSR: "false",
+      AKAN_CSR: "false",
+      AKAN_MCP: "false",
+      AKAN_SHUTDOWN_TIMEOUT_MS: "1000",
+    });
+    expect(env.PORT).toBeUndefined();
+    expect(env.AKAN_LOG_TO_FILE).toBeUndefined();
+  });
+
+  test("installs what the image does, minus the RSC renderer and the other modes' drivers", () => {
+    const config = appConfig({ database: { modes: ["single", "cluster"] }, externalLibs: ["@external/runtime"] });
+    const built = config.getProductionPackageJson();
+    const drivers = config.getDatabaseModeRuntimePackages("cluster");
+
+    const { dependencies } = DesktopServerStage.packageJson(config, built);
+
+    expect(Object.keys(dependencies ?? {}).sort()).toEqual(["@external/runtime", "react", "react-dom"]);
+    for (const driver of drivers) expect(Object.keys(built.dependencies ?? {})).toContain(driver);
+  });
+
+  test("keeps the image's trusted packages, so their install scripts run in the app's server too", () => {
+    const config = appConfig({ trustedDependencies: ["@external/runtime"], externalLibs: ["@external/runtime"] });
+    expect(DesktopServerStage.packageJson(config, config.getProductionPackageJson()).trustedDependencies).toEqual([
+      "@external/runtime",
+    ]);
+  });
+
+  test("says what the image installs that the desktop app's server goes without", () => {
+    const notice = (docker: unknown, carried: string[] = []) =>
+      DesktopServerStage.imageStepsNotice({ app: { name: "portal" }, docker } as never, carried);
+    const steps = { image: "oven/bun", preRuns: ["apt-get install -y ffmpeg"], postRuns: [], command: [] };
+    expect(notice({ ...steps, preRuns: [] })).toBeNull();
+    expect(notice(steps)).toEqual({
+      level: "warn",
+      message: expect.stringContaining(
+        "The image runs 1 docker step from the app and its libs, and a desktop app's server runs none of them",
+      ),
+    });
+    expect(notice("FROM ros:humble-ros-core")?.message).toStartWith(
+      "apps/portal/akan.config.ts writes its own Dockerfile",
+    );
+    expect(notice(steps, ["ffmpeg"])).toEqual({
+      level: "info",
+      message: expect.stringContaining("carries only bin: ffmpeg"),
+    });
+  });
+
+  const stageApp = async (spawn: (...args: unknown[]) => Promise<string> = async () => "") => {
+    const root = await makeTempRoot();
+    const dist = path.join(root, "dist/apps/portal");
+    const config = appConfig();
+    const app = {
+      cwdPath: path.join(root, "apps/portal"),
+      dist: { cwdPath: dist },
+      getConfig: async () => config,
+      getScanInfo: () => ({ getLibs: () => [] }),
+      logger: { info: () => undefined, warn: () => undefined },
+      spawn,
+    } as unknown as App;
+    return { dist, app, stage: new DesktopServerStage(app) };
+  };
+
+  test("carries everything the backend build wrote beside main.js but what only the image reads", async () => {
+    const { dist, stage } = await stageApp();
+    const carried = [
+      "main.js",
+      "server.js",
+      "chunk-5eap2n9b.js",
+      "akan.build.json",
+      "better-sqlite3-a1b2c3d4.node",
+      "engine-e5f6a7b8.wasm",
+      "model-c9d0e1f2.bin",
+      "private/service-account.json",
+    ];
+    const imageOnly = [
+      "Dockerfile",
+      "package.json",
+      "rscWorker.js",
+      "console.js",
+      "console-runtime.js",
+      "csr/index.html",
+      "public/favicon.ico",
+      ".akan/artifact/base-artifact.json",
+    ];
+    for (const file of [...carried, ...imageOnly]) await write(path.join(dist, file), file);
+
+    await stage.prepare("main");
+
+    const staged = await Array.fromAsync(new Bun.Glob("**/*").scan({ cwd: stage.dir, dot: true }));
+    expect(staged.map((file) => file.split(path.sep).join("/")).sort()).toEqual(carried.sort());
+    expect(await Bun.file(path.join(stage.dir, "better-sqlite3-a1b2c3d4.node")).text()).toBe(
+      "better-sqlite3-a1b2c3d4.node",
+    );
+  });
+
+  test("installs from the config alone, offline when Bun's cache holds the packages", async () => {
+    const spawned: unknown[][] = [];
+    const { stage } = await stageApp(async (...args) => {
+      spawned.push(args);
+      return "";
+    });
+
+    await stage.install();
+
+    expect(spawned).toEqual([[process.execPath, ["install", "--production", "--prefer-offline"], { cwd: stage.dir }]]);
+    const installed = (await Bun.file(path.join(stage.dir, "package.json")).json()) as PackageJson;
+    expect(Object.keys(installed.dependencies ?? {}).sort()).toEqual(["react", "react-dom"]);
+  });
+
+  test("an install that fails says it needs the registry or a Bun cache that holds the packages", async () => {
+    const { stage } = await stageApp(async () => {
+      throw new Error("error: GET https://registry.npmjs.org/scheduler - ConnectionRefused");
+    });
+
+    const failed = stage.install();
+
+    await expect(failed).rejects.toThrow(
+      "it needs the npm registry, or a Bun cache that already holds every one of them.\nerror: GET https://registry.npmjs.org/scheduler",
+    );
+  });
+
+  test("refuses an app whose database modes leave out single", () => {
+    expect(() => DesktopServerStage.assertCarriable(appConfig({ database: { modes: ["cluster"] } }))).toThrow(
+      "only database mode single runs",
+    );
+    expect(() =>
+      DesktopServerStage.assertCarriable(appConfig({ database: { modes: ["single", "cluster"] } })),
+    ).not.toThrow();
+  });
+
+  test("the runtime accepts a desktop config that carries the server, with single-instance on", async () => {
+    const root = await makeTempRoot();
+    await mkdir(path.join(root, "web"), { recursive: true });
+    await writeFile(path.join(root, "web/index.html"), "<html><head></head><body></body></html>");
+    await mkdir(path.join(root, "server"), { recursive: true });
+    await writeFile(path.join(root, "server/main.js"), "");
+    const server = { dir: path.join(root, "server"), entry: "main.js", env: { AKAN_PUBLIC_ENV: "main" } };
+
+    const { config } = NativeConfig.build({
+      appPath: root,
+      target: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
+      webDir: path.join(root, "web"),
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+      desktopServer: server,
+    });
+
+    expect(config.plugins).toContain("single-instance");
+    expect(config.desktop).toEqual({ server });
+    expect((await NativeApi.load(repoApp)).validateConfig(config, { appDir: root })).toEqual([]);
+  });
+
+  test("a phone build cannot carry the server", async () => {
+    const app = new NativeApp({ cwdPath: "/repo/apps/portal" } as never, {
+      name: "default",
+      config: { name: "default", appName: "Portal", appId: "com.portal.app", version: "1.0.0", buildNum: 1 },
+    });
+    const server = { dir: "/tmp/server", entry: "main.js", env: {} };
+    await expect(app.build("ios", { server })).rejects.toThrow("Only a desktop app carries its server");
+    await expect(app.run("android", { server })).rejects.toThrow("Only a desktop app carries its server");
+  });
+});

package/mobile/desktopServerStage.ts

@@ -0,0 +1,138 @@
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanAppConfig, NativeEnv } from "../akanConfig";
+import type { App } from "../commandDecorators";
+import type { PackageJson } from "../types";
+import { DesktopBin } from "./desktopBin";
+
+/** What a desktop build hands the native runtime as `desktop.server`. */
+export interface DesktopServerBundle {
+  dir: string;
+  entry: string;
+  env: Record<string, string>;
+}
+
+//* A desktop app's carried server is the backend `akan build` wrote into dist, installed on its own as the image's
+//* `bun install --production` does. It is staged outside dist: installing there would put host packages into the
+//* image's `COPY . .`.
+export class DesktopServerStage {
+  //? An API-only server starts neither the RSC worker nor the akan console and serves no CSR, public/ or SSR artifact,
+  //? and `install` wrote its own package.json. The rest of dist is the server's: its chunks, a `.node`, a `.wasm`.
+  static readonly uncarried = new Set([
+    "Dockerfile",
+    "package.json",
+    "rscWorker.js",
+    "console.js",
+    "console-runtime.js",
+    "csr",
+    "public",
+    ".akan",
+  ]);
+  //? Only the RSC worker loads it, and its peer webpack makes 35 of the 43 MB an install would add.
+  static readonly rscRenderer = "react-server-dom-webpack";
+
+  readonly dir: string;
+
+  constructor(readonly app: App) {
+    this.dir = path.join(app.cwdPath, ".akan", "desktop", "server");
+  }
+
+  static assertCarriable(config: AkanAppConfig) {
+    if (!config.database.modes.includes("single"))
+      throw new Error(
+        `desktop.server in native puts the server in the app, where only database mode single runs (no Redis or Postgres); apps/${config.app.name}/akan.config.ts declares ${config.database.modes.join(", ")}.`,
+      );
+  }
+
+  static env(config: AkanAppConfig, environment: NativeEnv): Record<string, string> {
+    //? The launcher picks the port, and the log file stays on: a user's computer has no log collector.
+    const { PORT: _port, AKAN_LOG_TO_FILE: _fileLog, ...image } = config.getProductionEnv(environment);
+    return {
+      ...image,
+      //? Neither the developer's machine (local, which derives a forgeable JWT secret) nor a deployment (cloud).
+      AKAN_PUBLIC_OPERATION_MODE: "edge",
+      AKAN_DATABASE_MODE: "single",
+      AKAN_DATABASE_MODES: "single",
+      //? API only: the shell serves the CSR bundle, and an RSC worker would need a bun on the user's PATH.
+      AKAN_SSR: "false",
+      AKAN_CSR: "false",
+      AKAN_MCP: "false",
+      //? Ahead of the launcher's 1.5 s grace before it signals, which sits inside the shell's 2 s quit budget.
+      AKAN_SHUTDOWN_TIMEOUT_MS: "1000",
+    };
+  }
+
+  //? The image's steps install into a Linux image the desktop app never runs in, so its server has none of it.
+  static imageStepsNotice(
+    config: Pick<AkanAppConfig, "app" | "docker">,
+    carried: string[],
+  ): { level: "warn" | "info"; message: string } | null {
+    const steps =
+      typeof config.docker === "string" ? null : config.docker.preRuns.length + config.docker.postRuns.length;
+    if (steps === 0) return null;
+    const image =
+      steps === null
+        ? `apps/${config.app.name}/akan.config.ts writes its own Dockerfile`
+        : `The image runs ${steps} docker step${steps === 1 ? "" : "s"} from the app and its libs`;
+    return carried.length
+      ? {
+          level: "info",
+          message: `${image}; the desktop app's server runs none of them and carries only bin: ${carried.join(", ")}.`,
+        }
+      : {
+          level: "warn",
+          message: `${image}, and a desktop app's server runs none of them: declare in bin the executables its code spawns, or those calls fail on the user's computer.`,
+        };
+  }
+
+  static packageJson(config: AkanAppConfig, built: PackageJson): PackageJson {
+    const otherDrivers = new Set(
+      config.database.modes
+        .filter((mode) => mode !== "single")
+        .flatMap((mode) => config.getDatabaseModeRuntimePackages(mode)),
+    );
+    const dependencies = Object.entries(built.dependencies ?? {}).filter(
+      ([name]) =>
+        config.externalLibs.includes(name) || (name !== DesktopServerStage.rscRenderer && !otherDrivers.has(name)),
+    );
+    return { ...built, dependencies: Object.fromEntries(dependencies) };
+  }
+
+  //* The packages come from the config alone, so they install before `akan build` runs: a machine that cannot install
+  //* them stops at once instead of after the whole build.
+  async install() {
+    const config = await this.app.getConfig();
+    DesktopServerStage.assertCarriable(config);
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(
+      path.join(this.dir, "package.json"),
+      JSON.stringify(DesktopServerStage.packageJson(config, config.getProductionPackageJson()), null, 2),
+    );
+    try {
+      await this.app.spawn(process.execPath, ["install", "--production", "--prefer-offline"], { cwd: this.dir });
+    } catch (error) {
+      throw new Error(
+        `The desktop app's server could not install its packages in ${this.dir}: it needs the npm registry, or a Bun cache that already holds every one of them.\n${error instanceof Error ? error.message : String(error)}`,
+        { cause: error },
+      );
+    }
+    //? Launcher links only: a link out of the app bundle breaks its signature, and the server runs none of them.
+    await rm(path.join(this.dir, "node_modules", ".bin"), { recursive: true, force: true });
+  }
+
+  //? Copies the build beside what `install` put in the stage, so it runs after both.
+  async prepare(environment: NativeEnv): Promise<DesktopServerBundle> {
+    const config = await this.app.getConfig();
+    const dist = this.app.dist.cwdPath;
+    await mkdir(this.dir, { recursive: true });
+    for (const name of await readdir(dist))
+      if (!DesktopServerStage.uncarried.has(name))
+        await cp(path.join(dist, name), path.join(this.dir, name), { recursive: true });
+    const scanInfo = this.app.getScanInfo({ allowEmpty: true }) ?? (await this.app.scan({ write: false }));
+    const carried = [...DesktopBin.select(config, scanInfo.getLibs()).keys()];
+    const notice = DesktopServerStage.imageStepsNotice(config, carried);
+    if (notice) this.app.logger[notice.level](notice.message);
+    return { dir: this.dir, entry: "main.js", env: DesktopServerStage.env(config, environment) };
+  }
+}

package/mobile/index.ts

@@ -1 +1,10 @@
+export * from "./desktopBin";
+export * from "./desktopServerStage";
 export * from "./mobileTarget";
+export * from "./nativeApi";
+export * from "./nativeApp";
+export * from "./nativeConfig";
+export * from "./nativePluginFolders";
+export * from "./nativeWebDir";
+export * from "./placeholderAppId";
+export * from "./usageDescriptions";

package/mobile/mobileTarget.test.ts

@@ -1,7 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import type { AkanMobileTargetConfig } from "../akanConfig";
+import type { AkanNativeTarget } from "../akanConfig";
 import type { App } from "../commandDecorators";
-import { getMobileTargetChoices, resolveMobilePath, resolveMobileTargets, targetHtmlFilename } from "./mobileTarget";
+import {
+  appIdsOf,
+  getMobileTargetChoices,
+  resolveAppId,
+  resolveMobilePath,
+  resolveMobileTargets,
+  targetHtmlFilename,
+} from "./mobileTarget";
 
 const target = {
   name: "akanjs",
@@ -10,25 +17,36 @@ const target = {
   appId: "com.akanjs.app",
   version: "1.0.0",
   buildNum: 1,
-} as AkanMobileTargetConfig;
+} as AkanNativeTarget;
 
-describe("mobile target helpers", () => {
+describe("native target helpers", () => {
   test("maps deep links into target base paths without duplicating prefixes", () => {
     expect(resolveMobilePath(target, "/order/123")).toBe("/akanjs/order/123");
     expect(resolveMobilePath(target, "/akanjs/order/123")).toBe("/akanjs/order/123");
     expect(resolveMobilePath({ ...target, basePath: undefined }, "/order/123")).toBe("/order/123");
   });
 
+  test("an app id per platform falls back to default, and a platform with neither is refused", () => {
+    const appId = { default: "com.yeollege", ios: "com.puffinplanet.yeollege" };
+    expect(resolveAppId(appId, "ios")).toBe("com.puffinplanet.yeollege");
+    expect(resolveAppId(appId, "android")).toBe("com.yeollege");
+    expect(resolveAppId("com.one.app", "macos")).toBe("com.one.app");
+    expect(() => resolveAppId({ ios: "com.puffinplanet.yeollege" }, "android")).toThrow(
+      "native.appId names no id for android",
+    );
+    expect(appIdsOf(appId)).toEqual(["com.yeollege", "com.puffinplanet.yeollege"]);
+  });
+
   test("selects the self-contained html file for a target", () => {
     expect(targetHtmlFilename(target)).toBe("akanjs.html");
     expect(targetHtmlFilename({ ...target, basePath: undefined })).toBe("index.html");
   });
 
-  test("uses the configured mobile target as the only choice when one target is configured", async () => {
+  test("uses the configured native target as the only choice when one target is configured", async () => {
     const app = {
       getConfig: async () => ({
         basePaths: new Set(["akanjs", "soft", "office"]),
-        mobile: { targets: { akanjs: target } },
+        native: { targets: { akanjs: target } },
       }),
     } as unknown as App;
 
@@ -36,11 +54,42 @@ describe("mobile target helpers", () => {
     await expect(resolveMobileTargets(app, undefined)).resolves.toEqual([{ name: "akanjs", config: target }]);
   });
 
-  test("resolves a route base path onto the default mobile target config", async () => {
+  test("a target naming no basePath is a template in an app with basePaths, never a page of its own", async () => {
+    const template = { ...target, name: "default", basePath: undefined };
+    const appWith = (basePaths: string[]) =>
+      ({
+        name: "angelo",
+        getConfig: async () => ({ basePaths: new Set(basePaths), native: { targets: { default: template } } }),
+      }) as unknown as App;
+
+    const two = appWith(["soft", "office"]);
+    await expect(getMobileTargetChoices(two)).resolves.toEqual(["soft", "office"]);
+    await expect(resolveMobileTargets(two, undefined)).rejects.toThrow(
+      "Multiple native targets found for angelo. Pass --target <soft|office|all>.",
+    );
+    await expect(resolveMobileTargets(two, "office")).resolves.toEqual([
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+    await expect(resolveMobileTargets(two, "all")).resolves.toEqual([
+      { name: "soft", config: { ...template, name: "soft", basePath: "soft" } },
+      { name: "office", config: { ...template, name: "office", basePath: "office" } },
+    ]);
+
+    const one = appWith(["soft"]);
+    const soft = [{ name: "soft", config: { ...template, name: "soft", basePath: "soft" } }];
+    await expect(resolveMobileTargets(one, undefined)).resolves.toEqual(soft);
+    await expect(resolveMobileTargets(one, "all")).resolves.toEqual(soft);
+
+    await expect(resolveMobileTargets(appWith([]), undefined)).resolves.toEqual([
+      { name: "default", config: template },
+    ]);
+  });
+
+  test("resolves a route base path onto the default native target config", async () => {
     const app = {
       getConfig: async () => ({
         basePaths: new Set(["akanjs", "soft", "office"]),
-        mobile: { targets: { akanjs: target } },
+        native: { targets: { akanjs: target } },
       }),
     } as unknown as App;
 

package/mobile/mobileTarget.ts

@@ -1,45 +1,52 @@
-import type { AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
+import type { AkanNativeAppId } from "akanjs";
+import type { AkanAppConfig, AkanNativeTarget, NativeEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 
 export type MobilePlatform = "ios" | "android";
+export type DesktopPlatform = "macos" | "windows" | "linux";
+export type NativePlatform = MobilePlatform | DesktopPlatform;
 export type MobileTargetSelection = string | "all" | undefined;
 
 export interface ResolvedMobileTarget {
   name: string;
-  config: AkanMobileTargetConfig;
+  config: AkanNativeTarget;
 }
 
-export const MOBILE_ENVS = ["local", "debug", "develop", "main"] as const satisfies readonly MobileEnv[];
+export const MOBILE_ENVS = ["local", "debug", "develop", "main"] as const satisfies readonly NativeEnv[];
+
+const trimSlashes = (value: string) => value.replace(/^\/+|\/+$/g, "");
 
 export const getMobileTargets = async (app: App): Promise<ResolvedMobileTarget[]> => {
   const config = await app.getConfig();
-  return Object.entries(config.mobile.targets).map(([name, target]) => ({ name, config: target }));
+  return Object.entries(config.native.targets).map(([name, target]) => ({ name, config: target }));
 };
 
+//* An app with basePaths builds a CSR page per basePath and none at its root, so a target naming no basePath opens
+//* nothing on its own there; it is the template each basePath's target is made from.
+const isTemplateOnly = ({ basePaths, native }: Pick<AkanAppConfig, "basePaths" | "native">) =>
+  basePaths.size > 0 && Object.values(native.targets).every((target) => !target.basePath);
+
 export const getMobileTargetChoices = async (app: App): Promise<string[]> => {
   const config = await app.getConfig();
-  const targetNames = Object.keys(config.mobile.targets);
-  if (targetNames.length > 0) return targetNames;
-  const basePaths = [...config.basePaths];
-  return basePaths;
+  const targetNames = Object.keys(config.native.targets);
+  if (targetNames.length > 0 && !isTemplateOnly(config)) return targetNames;
+  return [...config.basePaths];
 };
 
 const resolveMobileTargetByBasePath = (
   targets: ResolvedMobileTarget[],
   basePath: string,
 ): ResolvedMobileTarget | undefined => {
-  const normalizedBasePath = basePath.replace(/^\/+|\/+$/g, "");
-  const byBasePath = targets.find((target) => target.config.basePath?.replace(/^\/+|\/+$/g, "") === normalizedBasePath);
+  const normalizedBasePath = trimSlashes(basePath);
+  const byBasePath = targets.find(
+    ({ config }) => config.basePath !== undefined && trimSlashes(config.basePath) === normalizedBasePath,
+  );
   if (byBasePath) return byBasePath;
   const [template] = targets;
   if (!template) return undefined;
   return {
     name: normalizedBasePath,
-    config: {
-      ...template.config,
-      name: normalizedBasePath,
-      basePath: normalizedBasePath,
-    },
+    config: { ...template.config, name: normalizedBasePath, basePath: normalizedBasePath },
   };
 };
 
@@ -49,17 +56,17 @@ export const resolveMobileTargets = async (
 ): Promise<ResolvedMobileTarget[]> => {
   const config = await app.getConfig();
   const targets = await getMobileTargets(app);
-  if (targets.length === 0) throw new Error(`No mobile targets configured for ${app.name}`);
-  if (!selection && targets.length === 1) return targets;
+  if (targets.length === 0) throw new Error(`No native targets configured for ${app.name}`);
+  if (!selection && targets.length === 1 && !isTemplateOnly(config)) return targets;
   if (!selection) {
     const choices = await getMobileTargetChoices(app);
     if (choices.length === 1) return resolveMobileTargets(app, choices[0]);
-    throw new Error(`Multiple mobile targets found for ${app.name}. Pass --target <${choices.join("|")}|all>.`);
+    throw new Error(`Multiple native targets found for ${app.name}. Pass --target <${choices.join("|")}|all>.`);
   }
   if (selection === "all") {
-    if (Object.keys(config.mobile.targets).length > 1) return targets;
+    if (Object.keys(config.native.targets).length > 1) return targets;
     const basePaths = [...config.basePaths];
-    if (basePaths.length > 1) {
+    if (basePaths.length > 1 || isTemplateOnly(config)) {
       return basePaths.flatMap((basePath) => {
         const resolved = resolveMobileTargetByBasePath(targets, basePath);
         return resolved ? [resolved] : [];
@@ -70,18 +77,30 @@ export const resolveMobileTargets = async (
   const target = targets.find((candidate) => candidate.name === selection);
   if (target) return [target];
   const basePathTarget = resolveMobileTargetByBasePath(targets, selection);
-  if (basePathTarget && config.basePaths.has(selection.replace(/^\/+|\/+$/g, ""))) return [basePathTarget];
+  if (basePathTarget && config.basePaths.has(trimSlashes(selection))) return [basePathTarget];
   const choices = await getMobileTargetChoices(app);
-  throw new Error(`Mobile target '${selection}' was not found. Available: ${choices.join(", ")}`);
+  throw new Error(`Native target '${selection}' was not found. Available: ${choices.join(", ")}`);
+};
+
+export const resolveAppId = (appId: AkanNativeAppId, platform: NativePlatform): string => {
+  if (typeof appId === "string") return appId;
+  const id = appId[platform] ?? appId.default;
+  if (!id) throw new Error(`native.appId names no id for ${platform}; give it ${platform} or default.`);
+  return id;
 };
 
-export const resolveMobilePath = (target: AkanMobileTargetConfig, pathname: string) => {
-  const basePath = target.basePath?.replace(/^\/+|\/+$/g, "");
+export const appIdsOf = (appId: AkanNativeAppId): string[] =>
+  typeof appId === "string" ? [appId] : Object.values(appId).filter((id): id is string => !!id);
+
+export const resolveMobilePath = (target: AkanNativeTarget, pathname: string) => {
+  const basePath = trimSlashes(target.basePath ?? "");
   const normalizedPath = `/${pathname.replace(/^\/+/, "")}`;
   if (!basePath) return normalizedPath;
   if (normalizedPath === `/${basePath}` || normalizedPath.startsWith(`/${basePath}/`)) return normalizedPath;
   return `/${basePath}${normalizedPath === "/" ? "" : normalizedPath}`;
 };
 
-export const targetHtmlFilename = (target: AkanMobileTargetConfig) =>
-  target.basePath?.replace(/^\/+|\/+$/g, "") ? `${target.basePath.replace(/^\/+|\/+$/g, "")}.html` : "index.html";
+export const targetHtmlFilename = (target: AkanNativeTarget) => {
+  const basePath = trimSlashes(target.basePath ?? "");
+  return basePath ? `${basePath}.html` : "index.html";
+};

package/mobile/nativeApi.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tempDirs } from "../testHelpers";
+import { NativeApi } from "./nativeApi";
+
+const makeTempRoot = tempDirs("akan-native-api-");
+const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
+
+describe("NativeApi", () => {
+  test("inside this repo, loads the workspace package and checks its major", async () => {
+    expect(NativeApi.entryOf(repoApp)).toBe(path.resolve(import.meta.dir, "../../native/packages/cli/src/api.ts"));
+    const api = await NativeApi.load(repoApp);
+    expect(api.API_VERSION.split(".")[0]).toBe(String(NativeApi.supportedMajor));
+  });
+
+  test("elsewhere, looks for the copy akanjs vendors, and says so when it is missing", async () => {
+    const root = await realpath(await makeTempRoot());
+    await mkdir(path.join(root, "node_modules/akanjs"), { recursive: true });
+    await writeFile(
+      path.join(root, "node_modules/akanjs/package.json"),
+      JSON.stringify({ name: "akanjs", exports: { "./package.json": "./package.json" } }),
+    );
+
+    expect(NativeApi.entryOf(root)).toBe(
+      path.join(root, "node_modules/akanjs/vendor/@akanjs/native/packages/cli/src/api.ts"),
+    );
+    await expect(NativeApi.load(root)).rejects.toThrow("The installed akanjs has no native build");
+  });
+});

package/mobile/nativeApi.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import type * as NativeBuildApi from "@akanjs/native/api";
+
+export type NativeBuildApiModule = typeof NativeBuildApi;
+
+export class NativeApi {
+  //* The build API versions itself; a major this devkit was not written against is refused before anything builds.
+  static readonly supportedMajor = 0;
+
+  /** The API of the akanjs the app installed: the workspace package inside this repo, akanjs's vendored copy elsewhere. */
+  static entryOf(appDir: string): string {
+    const workspaceEntry = NativeApi.#resolve("@akanjs/native/api", appDir);
+    if (workspaceEntry) return workspaceEntry;
+    const akanjsPackage = NativeApi.#resolve("akanjs/package.json", appDir);
+    if (!akanjsPackage) throw new Error(`akanjs is not installed for ${appDir}; the native build ships inside it.`);
+    return path.join(path.dirname(akanjsPackage), "vendor", "@akanjs", "native", "packages", "cli", "src", "api.ts");
+  }
+
+  static async load(appDir: string): Promise<NativeBuildApiModule> {
+    const entry = NativeApi.entryOf(appDir);
+    if (!(await Bun.file(entry).exists()))
+      throw new Error(`The installed akanjs has no native build at ${entry}; update akanjs.`);
+    const api = (await import(entry)) as NativeBuildApiModule;
+    const major = Number(api.API_VERSION.split(".")[0]);
+    if (major !== NativeApi.supportedMajor)
+      throw new Error(
+        `The native build API is ${api.API_VERSION}, and this akan CLI speaks ${NativeApi.supportedMajor}.x; install matching versions of akanjs and @akanjs/cli.`,
+      );
+    return api;
+  }
+
+  static #resolve(specifier: string, from: string) {
+    try {
+      return Bun.resolveSync(specifier, from);
+    } catch {
+      // Not installed where the app can reach it, which the caller answers with the next place to look.
+      return null;
+    }
+  }
+}