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

package/mobile/desktopServerStage.ts

@@ -0,0 +1,120 @@
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanAppConfig, MobileEnv } 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 {
+  //? The RSC worker's and the akan console's bundles: an API-only server starts neither.
+  static readonly skippedFiles = new Set(["rscWorker.js", "console.js", "console-runtime.js"]);
+  //? 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(
+        `native.desktop.server 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: MobileEnv): 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) };
+  }
+
+  async prepare(environment: MobileEnv): Promise<DesktopServerBundle> {
+    const config = await this.app.getConfig();
+    DesktopServerStage.assertCarriable(config);
+    const dist = this.app.dist.cwdPath;
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+    const entries = await readdir(dist, { withFileTypes: true });
+    for (const entry of entries) {
+      const carried =
+        (entry.isFile() &&
+          ((entry.name.endsWith(".js") && !DesktopServerStage.skippedFiles.has(entry.name)) ||
+            entry.name === "akan.build.json")) ||
+        (entry.isDirectory() && entry.name === "private");
+      if (carried) await cp(path.join(dist, entry.name), path.join(this.dir, entry.name), { recursive: true });
+    }
+    const built = (await Bun.file(path.join(dist, "package.json")).json()) as PackageJson;
+    await writeFile(
+      path.join(this.dir, "package.json"),
+      JSON.stringify(DesktopServerStage.packageJson(config, built), null, 2),
+    );
+    await this.app.spawn(process.execPath, ["install", "--production"], { cwd: this.dir });
+    //? 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 });
+    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,7 +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 { App } from "../commandDecorators";
-import { getMobileTargetChoices, resolveMobilePath, resolveMobileTargets, targetHtmlFilename } from "./mobileTarget";
+import {
+  appIdsOf,
+  getMobileTargetChoices,
+  resolveAppId,
+  resolveMobilePath,
+  resolveMobileTargets,
+  targetHtmlFilename,
+} from "./mobileTarget";
 
 const target = {
   name: "akanjs",
@@ -19,6 +26,17 @@ describe("mobile target helpers", () => {
     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(
+      "mobile.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");
@@ -36,6 +54,37 @@ describe("mobile target helpers", () => {
     await expect(resolveMobileTargets(app, undefined)).resolves.toEqual([{ name: "akanjs", config: target }]);
   });
 
+  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), mobile: { 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 mobile 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 mobile target config", async () => {
     const app = {
       getConfig: async () => ({

package/mobile/mobileTarget.ts

@@ -1,4 +1,5 @@
-import type { AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
+import type { AkanMobileAppId } from "akanjs";
+import type { AkanAppConfig, AkanMobileTargetConfig, MobileEnv } from "../akanConfig";
 import type { App } from "../commandDecorators";
 
 export type MobilePlatform = "ios" | "android";
@@ -20,10 +21,15 @@ export const getMobileTargets = async (app: App): Promise<ResolvedMobileTarget[]
   return Object.entries(config.mobile.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, mobile }: Pick<AkanAppConfig, "basePaths" | "mobile">) =>
+  basePaths.size > 0 && Object.values(mobile.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;
+  if (targetNames.length > 0 && !isTemplateOnly(config)) return targetNames;
   return [...config.basePaths];
 };
 
@@ -51,7 +57,7 @@ export const resolveMobileTargets = async (
   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 (!selection && targets.length === 1 && !isTemplateOnly(config)) return targets;
   if (!selection) {
     const choices = await getMobileTargetChoices(app);
     if (choices.length === 1) return resolveMobileTargets(app, choices[0]);
@@ -60,7 +66,7 @@ export const resolveMobileTargets = async (
   if (selection === "all") {
     if (Object.keys(config.mobile.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] : [];
@@ -76,6 +82,16 @@ export const resolveMobileTargets = async (
   throw new Error(`Mobile target '${selection}' was not found. Available: ${choices.join(", ")}`);
 };
 
+export const resolveAppId = (appId: AkanMobileAppId, platform: NativePlatform): string => {
+  if (typeof appId === "string") return appId;
+  const id = appId[platform] ?? appId.default;
+  if (!id) throw new Error(`mobile.appId names no id for ${platform}; give it ${platform} or default.`);
+  return id;
+};
+
+export const appIdsOf = (appId: AkanMobileAppId): string[] =>
+  typeof appId === "string" ? [appId] : Object.values(appId).filter((id): id is string => !!id);
+
 export const resolveMobilePath = (target: AkanMobileTargetConfig, pathname: string) => {
   const basePath = trimSlashes(target.basePath ?? "");
   const normalizedPath = `/${pathname.replace(/^\/+/, "")}`;

package/mobile/nativeApp.test.ts

@@ -22,7 +22,10 @@ const appDir = "/repo/apps/portal";
 
 const fakeApp = (plugins: AkanPlugin[] = []) =>
   ({
+    name: "portal",
     cwdPath: appDir,
+    workspace: { workspaceRoot: "/repo" },
+    getScanInfo: () => ({ getLibs: () => [] }),
     dist: { cwdPath: "/repo/dist/apps/portal" },
     getConfig: async () => ({ i18n: { locales: ["en", "ko"] }, api: { prefix: "/api", websocketPrefix: "/ws" } }),
     collectPlugins: async () => plugins,
@@ -69,13 +72,31 @@ describe("NativeApp", () => {
       target({ basePath: undefined, permissions: ["push"] }),
     );
 
-    const { config, warnings } = await app.config();
+    const { config, warnings } = await app.config({ platform: "android" });
 
     expect(warnings).toEqual([]);
     expect(config.plugins).toEqual([...NativeConfig.basePlugins, "push"]);
     expect(config.web.dir).toBe(path.join(appDir, ".akan/mobile/default/web"));
   });
 
+  test("a config nothing is built from (the update key's) stages no desktop bin", async () => {
+    const { config } = await new NativeApp(fakeApp(), target({ basePath: undefined })).config({
+      platform: "macos",
+      stageBin: false,
+    });
+    expect(config.desktop?.bin).toBeUndefined();
+  });
+
+  test("follows the updates channel of the backend env it is built for", async () => {
+    const updates = { url: "https://releases.example.com/portal", publicKey: `${"a".repeat(43)}=` };
+    const built = async (env?: "debug" | "main") =>
+      (await new NativeApp(fakeApp(), target({ basePath: undefined, updates }), env).config({ platform: "android" }))
+        .config.updates;
+
+    expect(await built("main")).toEqual({ ...updates, channel: "main" });
+    expect(await built("debug")).toEqual({ ...updates, channel: "debug" });
+  });
+
   test("a desktop app is this computer's platform", () => {
     expect(["darwin", "win32", "linux"].map((host) => NativeApp.desktopPlatform(host as NodeJS.Platform))).toEqual([
       "macos",

package/mobile/nativeApp.ts

@@ -1,8 +1,11 @@
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { MobileEnv } from "akanjs";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
+import { DesktopBin } from "./desktopBin";
+import type { DesktopServerBundle } from "./desktopServerStage";
 import {
   type DesktopPlatform,
   type MobilePlatform,
@@ -13,6 +16,7 @@ import {
 import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
 import { NativeAppLine, type NativeAppLineRead } from "./nativeAppLine";
 import { NativeConfig } from "./nativeConfig";
+import { NativePluginFolders } from "./nativePluginFolders";
 import { NativeWebDir } from "./nativeWebDir";
 
 type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
@@ -31,6 +35,14 @@ interface NativeDevBoot {
   lines: NativeAppLineRead[];
 }
 
+export interface NativeBuildOptions {
+  profile?: "debug" | "release";
+  /** The server a desktop app carries (the target's `native.desktop.server`), staged by DesktopServerStage. */
+  server?: DesktopServerBundle;
+  /** Windows: an NSIS setup program beside the app folder. */
+  installer?: boolean;
+}
+
 export interface NativeDevOptions extends NativeRunOptions {
   /** The akan dev server the gateway proxies. */
   upstream: string;
@@ -48,6 +60,7 @@ export class NativeApp {
   constructor(
     readonly app: App,
     readonly target: ResolvedMobileTarget,
+    readonly env?: MobileEnv,
   ) {
     this.targetRoot = path.join(app.cwdPath, ".akan", "mobile", target.name);
     this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
@@ -67,20 +80,48 @@ export class NativeApp {
     });
   }
 
-  async config() {
-    const [appConfig, plugins] = await Promise.all([this.app.getConfig(), this.app.collectPlugins()]);
+  /** Where a desktop build stages the executables it carries (akan.config.ts `bin`). */
+  get binDir() {
+    return path.join(this.targetRoot, "bin");
+  }
+
+  /** `stageBin: false` for a config nothing is built from (the update key's): staging downloads the `bin` sources. */
+  async config({
+    server,
+    platform,
+    stageBin = true,
+  }: {
+    server?: DesktopServerBundle;
+    platform: NativePlatform;
+    stageBin?: boolean;
+  }) {
+    const [appConfig, plugins, nativePlugins] = await Promise.all([
+      this.app.getConfig(),
+      this.app.collectPlugins(),
+      NativePluginFolders.of(this.app),
+    ]);
+    const desktop = platform === "macos" || platform === "windows" || platform === "linux";
+    const carried = desktop && stageBin ? await new DesktopBin(this.app, appConfig).stage(this.binDir) : [];
     return NativeConfig.build({
       appPath: this.app.cwdPath,
       target: this.target.config,
       webDir: this.web.dir,
       contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
       locales: appConfig.i18n.locales,
+      env: this.env,
+      platform,
+      nativePlugins,
+      ...(server ? { desktopServer: server } : {}),
+      ...(carried.length ? { desktopBin: this.binDir } : {}),
     });
   }
 
   /** The API and the config it is about to build, refused here when the runtime would refuse it later. */
-  async prepare() {
-    const [api, { config, warnings }] = await Promise.all([NativeApi.load(this.app.cwdPath), this.config()]);
+  async prepare(platform: NativePlatform, server?: DesktopServerBundle) {
+    const [api, { config, warnings }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, ...(server ? { server } : {}) }),
+    ]);
     for (const warning of warnings) this.app.logger.warn(warning);
     const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
     if (problems.length)
@@ -116,18 +157,25 @@ export class NativeApp {
     };
   }
 
-  async build(platform: NativePlatform, { profile = "release" }: { profile?: "debug" | "release" } = {}) {
+  async build(platform: NativePlatform, { profile = "release", server, installer = false }: NativeBuildOptions = {}) {
+    NativeApp.#assertServerPlatform(platform, server);
+    if (installer && platform !== "windows") throw new Error(`An installer is built for Windows, not for ${platform}.`);
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
-    return await api.build({ ...this.#task(platform, config), profile });
+    const { api, config } = await this.prepare(platform, server);
+    return await api.build({
+      ...this.#task(platform, config),
+      profile,
+      ...(installer ? { windows: { installer } } : {}),
+    });
   }
 
   async run(
     platform: NativePlatform,
-    { device, teamId, profile = "debug" }: NativeRunOptions & { profile?: "debug" | "release" } = {},
+    { device, teamId, profile = "debug", server }: NativeRunOptions & NativeBuildOptions = {},
   ) {
+    NativeApp.#assertServerPlatform(platform, server);
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
+    const { api, config } = await this.prepare(platform, server);
     return await api.run({
       ...this.#task(platform, config),
       profile,
@@ -137,21 +185,22 @@ export class NativeApp {
     });
   }
 
-  //* The gateway serves the page and its HMR socket on the app origin; API calls go to the dev server itself (baseEnv),
-  //* which an Android device reaches through the reversed port.
+  //* The gateway serves the page, its HMR socket and its API calls on the app origin. The dev server's own port is
+  //* reversed too: a browser the app hands off to (auth-session) opens it directly (baseEnv getServerOrigin).
   async dev(platform: NativePlatform, { upstream, lang, device, teamId }: NativeDevOptions) {
     const startedAt = performance.now();
     const boot: NativeDevBoot = { steps: [], lines: [] };
     this.#boot = boot;
     try {
       await mkdir(this.web.dir, { recursive: true });
-      const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
+      const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(platform), this.app.getConfig()]);
       const session = await api.dev({
         ...this.#task(platform, config),
         upstream,
         hmrPath: "/_akan/hmr",
         //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
         wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
+        reversePorts: [Number(new URL(upstream).port)],
         onLine: this.#appLine,
         startPath: this.startPath(lang),
         ...(device ? { device } : {}),
@@ -185,7 +234,7 @@ export class NativeApp {
 
   async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
+    const { api, config } = await this.prepare("ios");
     return await api.release({
       ...this.#task("ios", config),
       platform: "ios",
@@ -193,13 +242,67 @@ export class NativeApp {
     });
   }
 
+  /** Where publishUpdate writes: upload this folder as the target's updates.url. */
+  get updatesDir() {
+    return path.join(this.targetRoot, "updates");
+  }
+
+  /** A signed release installed apps take through the updates plugin, from a release build of this bundle. */
+  async publishUpdate(
+    platform: NativePlatform,
+    { channel, server }: { channel?: string; server?: DesktopServerBundle } = {},
+  ) {
+    NativeApp.#assertServerPlatform(platform, server);
+    if (!this.target.config.updates)
+      throw new Error(
+        `Mobile target '${this.target.name}' has no updates: { url, publicKey } in akan.config.ts; \`akan update-keygen ${this.app.name}\` prints the key.`,
+      );
+    await this.assembleWeb();
+    const { api, config } = await this.prepare(platform, server);
+    return await api.publishUpdate({
+      ...this.#task(platform, config),
+      platform,
+      out: this.updatesDir,
+      ...(channel ? { channel } : {}),
+    });
+  }
+
+  /** The key update releases of this target's app id on `platform` are signed with: made once, then read. */
+  async updateKeygen(platform: NativePlatform) {
+    const [api, { config }] = await Promise.all([
+      NativeApi.load(this.app.cwdPath),
+      this.config({ platform, stageBin: false }),
+    ]);
+    return api.updateKeygen({ config });
+  }
+
   async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
     const signing = NativeApp.androidSigning();
     await this.assembleWeb();
-    const { api, config } = await this.prepare();
+    const { api, config } = await this.prepare("android");
     return await api.release({ ...this.#task("android", config), platform: "android", signing, formats });
   }
 
+  /** An unsigned OTA update of this target's web bundle for `platform`, and the channel its binary follows. */
+  async packUpdate(platform: MobilePlatform, { out }: { out?: string } = {}) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare(platform);
+    if (!config.updates)
+      throw new Error(
+        `Mobile target '${this.target.name}' takes no updates: add mobile.updates: { url, publicKey } to akan.config.ts first.`,
+      );
+    const packed = await api.packUpdate({
+      ...this.#task(platform, config),
+      platform,
+      out: out ?? path.join(this.targetRoot, "updates", platform),
+    });
+    return { ...packed, channel: config.updates.channel ?? "production" };
+  }
+
+  static async compareBundles(appDir: string, shipped: string, bundle: string) {
+    return (await NativeApi.load(appDir)).compareBundles(shipped, bundle);
+  }
+
   //* The names the Gradle build read, so a CI that already holds these secrets keeps working.
   static androidSigning(env: Record<string, string | undefined> = process.env): AndroidSigning {
     const keystore = env.MYAPP_RELEASE_STORE_FILE;
@@ -232,6 +335,12 @@ export class NativeApp {
     return `/${home.join("/")}?${params}`;
   }
 
+  //? A phone runs no Bun, so only a desktop app can carry the server.
+  static #assertServerPlatform(platform: NativePlatform, server: DesktopServerBundle | undefined) {
+    if (server && (platform === "ios" || platform === "android"))
+      throw new Error(`Only a desktop app carries its server; ${platform} cannot run one.`);
+  }
+
   //* A desktop app builds only on its own OS, so the platform is this computer's.
   static desktopPlatform(host: NodeJS.Platform = process.platform): DesktopPlatform {
     if (host === "darwin") return "macos";

package/mobile/nativeAppLine.test.ts

@@ -24,6 +24,13 @@ describe("NativeAppLine", () => {
     });
   });
 
+  test("a carried server's line keeps the level its logger wrote, and one without a level stays visible", () => {
+    const line = "[server] [minimal] 81 - 09/30/2026, 12:30:06 PM   ERROR  boom +2ms";
+    expect(NativeAppLine.read(line)).toEqual({ level: "error", message: line });
+    expect(NativeAppLine.read("[server] \u001b[32m[minimal] 81 -\u001b[39m WARN  slow").level).toBe("warn");
+    expect(NativeAppLine.read("[server]     at run (main.js:1:2)").level).toBe("info");
+  });
+
   test("a second window is named, the first is not", () => {
     expect(NativeAppLine.read("[page#2 info] [App] ready")).toEqual({ level: "info", message: "[page#2:App] ready" });
   });

package/mobile/nativeAppLine.ts

@@ -13,6 +13,10 @@ export class NativeAppLine {
   static readonly #page = /^\[page(\+)?(?:#(\d+))? (trace|verbose|debug|log|info|warn|error)\] ?(.*)$/;
   static readonly #logcat = /^([VDIWEFA])\/([^(]+?)\s*\(\s*\d+\):\s?(.*)$/;
   static readonly #named = /^\[([^\]\s]+)\] ([\s\S]*)$/;
+  //? A server the desktop app carries (host server.ts): `[server] <its own log line>`, whose level word the akan logger
+  //? wrote; a line without one (a crash's stack) is still the app's and stays visible.
+  static readonly #server = /^\[server\] /;
+  static readonly #serverLevel = /\b(TRACE|VERBOSE|DEBUG|INFO|WARN|ERROR)\b/;
   static readonly #logcatLevels: { [priority: string]: LogLevel } = {
     V: "verbose",
     D: "debug",
@@ -42,6 +46,10 @@ export class NativeAppLine {
       });
     }
     if (line.startsWith("[akan-native")) return NativeAppLine.#hostLine(line, "info");
+    if (NativeAppLine.#server.test(line)) {
+      const word = NativeAppLine.#serverLevel.exec(Bun.stripANSI(line))?.[1];
+      return { level: word ? (word.toLowerCase() as LogLevel) : "info", message: line };
+    }
     return { level: verbose ? "info" : "debug", message: line };
   }