@akanjs/devkit 3.0.0-beta.30 → 3.0.0-beta.32

package/akanConfig/akanConfig.test.ts

@@ -477,6 +477,18 @@ describe("AkanAppConfig", () => {
     ).toThrow("unknown basePath");
   });
 
+  test("a desktop server is true or { omit }, its names trimmed, deduplicated and sorted", () => {
+    const resolve = (server: unknown) =>
+      new AkanAppConfig(app, [], packageJson, { native: { desktop: { server } } } as never, baseDevEnv).native.targets
+        .default.desktop?.server;
+
+    expect(resolve(true)).toBe(true);
+    expect(resolve({ omit: [" rclnodejs", "protobufjs", "rclnodejs"] })).toEqual({ omit: ["protobufjs", "rclnodejs"] });
+    expect(resolve({})).toEqual({ omit: [] });
+    expect(() => resolve({ omit: "rclnodejs" })).toThrow("native.desktop.server.omit in apps/");
+    expect(() => resolve({ exclude: ["rclnodejs"] })).toThrow("native.desktop.server.exclude in apps/");
+  });
+
   test("an app without basePaths has one target, default, with no basePath and the section's settings", () => {
     const config = new AkanAppConfig(
       app,
@@ -491,6 +503,29 @@ describe("AkanAppConfig", () => {
     expect(config.native.targets.default).toMatchObject({ indexPath: "/explore", desktop: { server: true } });
   });
 
+  test("a platform section may name its own indexPath, normalized like the section's", () => {
+    const config = new AkanAppConfig(
+      app,
+      [],
+      packageJson,
+      {
+        native: {
+          indexPath: "/mobile",
+          ios: { indexPath: "cockpit/" },
+          desktop: { indexPath: " / ", server: true },
+        },
+      },
+      baseDevEnv,
+    );
+
+    expect(config.native.targets.default).toMatchObject({
+      indexPath: "/mobile",
+      ios: { indexPath: "/cockpit" },
+      desktop: { indexPath: "/", server: true },
+    });
+    expect(config.native.targets.default.android).toBeUndefined();
+  });
+
   test("a target takes the native section with its own fields over it: objects merge, lists and values replace", () => {
     const config = new AkanAppConfig(
       app,

package/akanConfig/akanConfig.ts

@@ -17,6 +17,7 @@ import {
   type AkanNativeAppConfig,
   type AkanNativeAppResult,
   type AkanNativeDeepLinks,
+  type AkanNativeDesktopConfig,
   type AkanNativeSettings,
   type AkanNativeTarget,
   type AkanNativeUpdatesConfig,
@@ -293,9 +294,11 @@ export class AkanAppConfig implements AppConfigResult {
         } = merged;
         const indexPath = normalizeIndexPath(rawIndexPath);
         const deepLinks = normalizeDeepLinks(rawDeepLinks);
-        const { teamId: rawTeamId, ...iosRest } = merged.ios ?? {};
+        const { teamId: rawTeamId, ...iosRest } = AkanAppConfig.#platformIndexPath(merged.ios ?? {});
         const teamId = rawTeamId?.trim();
-        const { sha256CertFingerprints: rawFingerprints, ...androidRest } = merged.android ?? {};
+        const { sha256CertFingerprints: rawFingerprints, ...androidRest } = AkanAppConfig.#platformIndexPath(
+          merged.android ?? {},
+        );
         const fingerprints = normalizeStringList(rawFingerprints);
         const target: AkanNativeTarget = {
           ...rest,
@@ -307,6 +310,15 @@ export class AkanAppConfig implements AppConfigResult {
           ...(merged.android
             ? { android: { ...androidRest, ...(fingerprints ? { sha256CertFingerprints: fingerprints } : {}) } }
             : {}),
+          ...(merged.desktop
+            ? {
+                desktop: AkanAppConfig.#desktopServer(
+                  AkanAppConfig.#platformIndexPath(merged.desktop),
+                  `${where}.desktop.server`,
+                  configPath,
+                ),
+              }
+            : {}),
           appName: merged.appName ?? this.app.name,
           appId: merged.appId ?? appId,
           version: merged.version ?? version,
@@ -318,6 +330,27 @@ export class AkanAppConfig implements AppConfigResult {
     );
     return { appName, appId, ...(root.fileName ? { fileName: root.fileName } : {}), version, buildNum, targets };
   }
+  //? `true` or `{ omit }`: each omitted name trimmed once, so two targets that omit the same packages stage one server.
+  static #desktopServer<T extends { server?: AkanNativeDesktopConfig["server"] }>(
+    desktop: T,
+    where: string,
+    configPath: string,
+  ): T {
+    const { server } = desktop;
+    if (server === undefined || typeof server === "boolean") return desktop;
+    if (!AkanAppConfig.#isPlainObject(server))
+      throw new Error(`${where} in ${configPath} must be true or { omit: string[] }.`);
+    const omit = server.omit;
+    if (omit !== undefined && (!Array.isArray(omit) || omit.some((name) => typeof name !== "string" || !name.trim())))
+      throw new Error(`${where}.omit in ${configPath} must be a list of package names.`);
+    const names = [...new Set((omit ?? []).map((name) => name.trim()))].sort();
+    return { ...desktop, server: { omit: names } };
+  }
+  static #platformIndexPath<T extends { indexPath?: string }>(section: T): T {
+    const { indexPath: rawIndexPath, ...rest } = section;
+    const indexPath = normalizeIndexPath(rawIndexPath);
+    return { ...rest, ...(indexPath ? { indexPath } : {}) } as T;
+  }
   /** `own` over `base`: plain objects merge key by key, and any other value, a list included, replaces. */
   static #overlay(base: AkanNativeSettings, own: AkanNativeSettings): AkanNativeSettings {
     const merge = (kept: unknown, value: unknown, top: boolean, key: string): unknown => {
@@ -356,8 +389,9 @@ export class AkanAppConfig implements AppConfigResult {
       "android",
       "desktop",
     ],
-    ios: ["teamId", "infoPlist", "entitlements", "privacy", "files"],
+    ios: ["indexPath", "teamId", "infoPlist", "entitlements", "privacy", "files"],
     android: [
+      "indexPath",
       "sha256CertFingerprints",
       "googleServices",
       "push",
@@ -367,7 +401,8 @@ export class AkanAppConfig implements AppConfigResult {
       "activity",
       "files",
     ],
-    desktop: ["server", "recovery", "window", "screenCapture"],
+    desktop: ["indexPath", "server", "recovery", "window", "screenCapture", "entitlements"],
+    desktopServer: ["omit"],
     deepLinks: ["schemes", "domains"],
   } as const;
   //* Settings that moved when `mobile` became `native` are named with where they went, instead of "unknown".
@@ -399,6 +434,12 @@ export class AkanAppConfig implements AppConfigResult {
     check(settings.ios, AkanAppConfig.#nativeKeys.ios, `${where}.ios`, "ios");
     check(settings.android, AkanAppConfig.#nativeKeys.android, `${where}.android`, "android");
     check(settings.desktop, AkanAppConfig.#nativeKeys.desktop, `${where}.desktop`, "desktop");
+    check(
+      settings.desktop?.server,
+      AkanAppConfig.#nativeKeys.desktopServer,
+      `${where}.desktop.server`,
+      "desktopServer",
+    );
     check(settings.deepLinks, AkanAppConfig.#nativeKeys.deepLinks, `${where}.deepLinks`, "deepLinks");
   }
   static readonly #androidFilePattern = /^(?:res\/[^/]+\/[^/]+|assets\/.+)$/;

package/akanConfig/types.ts

@@ -14,6 +14,7 @@ export type {
   AkanNativeAppResult,
   AkanNativeDeepLinks,
   AkanNativeDesktopConfig,
+  AkanNativeDesktopServerConfig,
   AkanNativeIosConfig,
   AkanNativeSettings,
   AkanNativeTarget,

package/mobile/desktopBin.test.ts

@@ -48,6 +48,11 @@ afterAll(() => files.stop(true));
 const hash = (bytes: Uint8Array | string) => new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
 
 describe("DesktopBin", () => {
+  test("a build carries the file of the CPU it is for", () => {
+    expect(DesktopBin.platform("x64")).toBe(`${process.platform}-x64` as BinPlatform);
+    expect(DesktopBin.platform("ia32")).toBeNull();
+  });
+
   test("carries the app's own entries and those of the libs it depends on, the app's first", () => {
     const own = { ffmpeg: { [here]: { path: "/a/ffmpeg" } } };
     const lib = { ffmpeg: { [here]: { path: "/lib/ffmpeg" } }, ffprobe: { [here]: { path: "/lib/ffprobe" } } };

package/mobile/desktopBin.ts

@@ -11,18 +11,19 @@ import {
 import type { App } from "../commandDecorators";
 
 type BinPlatforms = AkanBinConfig[string];
+export type DesktopArch = "arm64" | "x64";
 
-//* A desktop app is built on the computer it runs on, so only that platform's file is fetched. It is copied byte for
-//* byte into the folder the app carries as `desktop.bin`: no extended attribute, so no quarantine flag, travels
-//* into the bundle.
+//* A desktop app is built on its own OS, for this computer's CPU or the one `--arch` names, so only that platform's file
+//* is fetched. It is copied byte for byte into the folder the app carries as `desktop.bin`: no extended attribute, so
+//* no quarantine flag, travels into the bundle.
 export class DesktopBin {
   constructor(
     readonly app: App,
     readonly config: AkanAppConfig,
   ) {}
 
-  static platform(): BinPlatform | null {
-    const platform = `${process.platform}-${process.arch}`;
+  static platform(arch: string = process.arch): BinPlatform | null {
+    const platform = `${process.platform}-${arch}`;
     return (binPlatforms as readonly string[]).includes(platform) ? (platform as BinPlatform) : null;
   }
 
@@ -76,14 +77,14 @@ export class DesktopBin {
   }
 
   /** Copies each chosen executable into `dir`, emptied first, and answers the names it carries. */
-  async stage(dir: string): Promise<string[]> {
+  async stage(dir: string, arch: DesktopArch = process.arch as DesktopArch): Promise<string[]> {
     const scanInfo = this.app.getScanInfo({ allowEmpty: true }) ?? (await this.app.scan({ write: false }));
     const chosen = DesktopBin.select(this.config, scanInfo.getLibs());
     if (!chosen.size) return [];
-    const platform = DesktopBin.platform();
+    const platform = DesktopBin.platform(arch);
     if (!platform)
       throw new Error(
-        `bin: this computer is ${process.platform}-${process.arch}, and a bin names only ${binPlatforms.join(", ")}.`,
+        `bin: this desktop app is for ${process.platform}-${arch}, and a bin names only ${binPlatforms.join(", ")}.`,
       );
     await rm(dir, { recursive: true, force: true });
     await mkdir(dir, { recursive: true });

package/mobile/desktopServerStage.test.ts

@@ -23,7 +23,7 @@ const rootPackageJson: PackageJson = {
   name: "repo",
   version: "1.0.0",
   description: "repo",
-  dependencies: { "@external/runtime": "2.0.0", pg: "8.0.0" },
+  dependencies: { "@external/runtime": "2.0.0", pg: "8.0.0", rclnodejs: "1.0.0" },
 };
 const appConfig = (config: object = {}) =>
   new AkanAppConfig({ name: "portal" } as never, [], rootPackageJson, config, baseDevEnv);
@@ -59,6 +59,17 @@ describe("DesktopServerStage", () => {
     for (const driver of drivers) expect(Object.keys(built.dependencies ?? {})).toContain(driver);
   });
 
+  test("leaves out what desktop.server.omit names, an external lib included, while the image keeps it", () => {
+    const config = appConfig({ externalLibs: ["rclnodejs", "@external/runtime"] });
+    const built = config.getProductionPackageJson();
+
+    const { dependencies } = DesktopServerStage.packageJson(config, built, ["rclnodejs"]);
+
+    expect(Object.keys(dependencies ?? {})).toContain("@external/runtime");
+    expect(Object.keys(dependencies ?? {})).not.toContain("rclnodejs");
+    expect(Object.keys(config.getProductionPackageJson().dependencies ?? {})).toContain("rclnodejs");
+  });
+
   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([
@@ -148,6 +159,43 @@ describe("DesktopServerStage", () => {
     expect(Object.keys(installed.dependencies ?? {}).sort()).toEqual(["react", "react-dom"]);
   });
 
+  test("an omitted package another dependency still installs stops the stage, naming who needs it", async () => {
+    const installing =
+      (pulled: boolean) =>
+      async (...args: unknown[]) => {
+        const nodeModules = path.join((args[2] as { cwd: string }).cwd, "node_modules");
+        await write(path.join(nodeModules, "react/package.json"), JSON.stringify({ name: "react" }));
+        if (pulled) {
+          await write(path.join(nodeModules, "rclnodejs/package.json"), JSON.stringify({ name: "rclnodejs" }));
+          await write(
+            path.join(nodeModules, "@robot/bridge/package.json"),
+            JSON.stringify({ name: "@robot/bridge", dependencies: { rclnodejs: "^1" } }),
+          );
+        }
+        return "";
+      };
+    await (await stageApp(installing(false))).stage.install(undefined, ["rclnodejs"]);
+    await expect((await stageApp(installing(true))).stage.install(undefined, ["rclnodejs"])).rejects.toThrow(
+      "another dependency still installs: rclnodejs (needed by @robot/bridge)",
+    );
+  });
+
+  test("installs another CPU's optional packages for that CPU", () => {
+    const other = process.arch === "arm64" ? "x64" : "arm64";
+    expect(DesktopServerStage.installArgs()).toEqual(["install", "--production", "--prefer-offline"]);
+    expect(DesktopServerStage.installArgs(process.arch as "arm64" | "x64")).toEqual([
+      "install",
+      "--production",
+      "--prefer-offline",
+    ]);
+    expect(DesktopServerStage.installArgs(other)).toEqual([
+      "install",
+      "--production",
+      "--prefer-offline",
+      `--cpu=${other}`,
+    ]);
+  });
+
   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");

package/mobile/desktopServerStage.ts

@@ -85,7 +85,8 @@ export class DesktopServerStage {
         };
   }
 
-  static packageJson(config: AkanAppConfig, built: PackageJson): PackageJson {
+  //? `omit` (the target's `desktop.server.omit`) wins over externalLibs: the image keeps those packages, the app does not.
+  static packageJson(config: AkanAppConfig, built: PackageJson, omit: string[] = []): PackageJson {
     const otherDrivers = new Set(
       config.database.modes
         .filter((mode) => mode !== "single")
@@ -93,24 +94,47 @@ export class DesktopServerStage {
     );
     const dependencies = Object.entries(built.dependencies ?? {}).filter(
       ([name]) =>
-        config.externalLibs.includes(name) || (name !== DesktopServerStage.rscRenderer && !otherDrivers.has(name)),
+        !omit.includes(name) &&
+        (config.externalLibs.includes(name) || (name !== DesktopServerStage.rscRenderer && !otherDrivers.has(name))),
     );
     return { ...built, dependencies: Object.fromEntries(dependencies) };
   }
 
+  /** The packages in `nodeModules` that depend on `name`: what still pulls an omitted package in. */
+  static async dependentsOf(nodeModules: string, name: string): Promise<string[]> {
+    const dependents = new Set<string>();
+    for await (const manifest of new Bun.Glob("**/package.json").scan({ cwd: nodeModules, onlyFiles: true })) {
+      const json = (await Bun.file(path.join(nodeModules, manifest))
+        .json()
+        .catch(() => null)) as PackageJson | null;
+      if (!json?.name || json.name === name) continue;
+      const declared = { ...json.dependencies, ...json.optionalDependencies, ...json.peerDependencies };
+      if (name in declared) dependents.add(json.name);
+    }
+    return [...dependents].sort();
+  }
+
+  //? `--cpu` installs another CPU's optional packages: an addon's prebuilt binary for the app's CPU, not this computer's.
+  static installArgs(arch?: "arm64" | "x64"): string[] {
+    return ["install", "--production", "--prefer-offline", ...(arch && arch !== process.arch ? [`--cpu=${arch}`] : [])];
+  }
+
   //* 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() {
+  async install(arch?: "arm64" | "x64", omit: string[] = []) {
     const config = await this.app.getConfig();
     DesktopServerStage.assertCarriable(config);
     await rm(this.dir, { recursive: true, force: true });
     await mkdir(this.dir, { recursive: true });
+    const built = config.getProductionPackageJson();
+    for (const name of omit.filter((name) => !(name in (built.dependencies ?? {}))))
+      this.app.logger.warn(`desktop.server.omit names ${name}, which the server does not depend on directly.`);
     await writeFile(
       path.join(this.dir, "package.json"),
-      JSON.stringify(DesktopServerStage.packageJson(config, config.getProductionPackageJson()), null, 2),
+      JSON.stringify(DesktopServerStage.packageJson(config, built, omit), null, 2),
     );
     try {
-      await this.app.spawn(process.execPath, ["install", "--production", "--prefer-offline"], { cwd: this.dir });
+      await this.app.spawn(process.execPath, DesktopServerStage.installArgs(arch), { 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)}`,
@@ -119,6 +143,22 @@ export class DesktopServerStage {
     }
     //? 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 });
+    await this.#assertOmitted(omit);
+  }
+
+  //? Leaving a package out of package.json keeps out only what nothing else needs; another dependency still installs it.
+  async #assertOmitted(omit: string[]) {
+    const nodeModules = path.join(this.dir, "node_modules");
+    const kept: string[] = [];
+    for (const name of omit) {
+      if (!(await Bun.file(path.join(nodeModules, name, "package.json")).exists())) continue;
+      const dependents = await DesktopServerStage.dependentsOf(nodeModules, name);
+      kept.push(`${name} (needed by ${dependents.join(", ") || "a package that names it"})`);
+    }
+    if (kept.length)
+      throw new Error(
+        `desktop.server.omit leaves out packages another dependency still installs: ${kept.join("; ")}. Omit those too, or keep the package.`,
+      );
   }
 
   //? Copies the build beside what `install` put in the stage, so it runs after both.

package/mobile/nativeApp.test.ts

@@ -86,15 +86,48 @@ describe("NativeApp", () => {
     ).toMatch(/^portal\/admin ios ready · iPhone 16 · http:\/\/localhost:8283 · 12\.\ds$/);
   });
 
+  test("an installer is what a person downloads, on the desktops that have one", () => {
+    expect(() => NativeApp.assertInstaller("windows", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("macos", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("linux", true)).not.toThrow();
+    expect(() => NativeApp.assertInstaller("ios", true)).toThrow(/not for ios/);
+  });
+
   test("opens a dev build on its target's home, the CSR shell under the locale", () => {
-    expect(new NativeApp(fakeApp(), target({ indexPath: "/explore" })).startPath("en")).toBe(
+    expect(new NativeApp(fakeApp(), target({ indexPath: "/explore" })).startPath("en", "ios")).toBe(
       "/en/explore?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fexplore",
     );
-    expect(new NativeApp(fakeApp(), target({ name: "admin", basePath: "/admin/" })).startPath("ko")).toBe(
+    expect(new NativeApp(fakeApp(), target({ name: "admin", basePath: "/admin/" })).startPath("ko", "android")).toBe(
       "/ko/admin?csr=true&akanMobileTarget=admin&akanMobileBasePath=admin",
     );
   });
 
+  test("a platform section's indexPath wins on that platform, and the others keep the target's", () => {
+    const app = new NativeApp(fakeApp(), target({ indexPath: "/mobile", desktop: { indexPath: "/", server: true } }));
+
+    expect(app.indexPath("ios")).toBe("/mobile");
+    expect(app.indexPath("android")).toBe("/mobile");
+    expect(app.indexPath("macos")).toBe("/");
+    expect(app.indexPath("windows")).toBe("/");
+    expect(app.startPath("en", "macos")).toBe("/en?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2F");
+    expect(app.startPath("en", "ios")).toBe(
+      "/en/mobile?csr=true&akanMobileTarget=default&akanMobileIndexPath=%2Fmobile",
+    );
+  });
+
+  test("assembles each platform's web root with that platform's indexPath", async () => {
+    const root = await makeTempRoot();
+    await writeText(path.join(root, "dist/csr/index.html"), "<html><head></head><body></body></html>");
+    const app = { ...fakeApp(), cwdPath: root, dist: { cwdPath: path.join(root, "dist") } } as unknown as App;
+    const nativeApp = new NativeApp(app, target({ indexPath: "/mobile", desktop: { indexPath: "/console" } }));
+    const injected = async () => await Bun.file(path.join(nativeApp.web.dir, "index.html")).text();
+
+    await nativeApp.assembleWeb("linux");
+    expect(await injected()).toContain('"indexPath":"/console"');
+    await nativeApp.assembleWeb("android");
+    expect(await injected()).toContain('"indexPath":"/mobile"');
+  });
+
   test("builds its config from the app's locales and the plugins' native contributions", async () => {
     const push: AkanPlugin = { name: "push-notification", native: { permission: "push", plugins: ["push"] } };
     const app = new NativeApp(

package/mobile/nativeApp.ts

@@ -3,7 +3,7 @@ import type { AkanNativeConfig } from "@akanjs/native/config";
 import type { NativeEnv } from "akanjs";
 import type { App } from "../commandDecorators";
 import { Executor } from "../executors";
-import { DesktopBin } from "./desktopBin";
+import { type DesktopArch, DesktopBin } from "./desktopBin";
 import type { DesktopServerBundle } from "./desktopServerStage";
 import {
   type DesktopPlatform,
@@ -38,8 +38,10 @@ export interface NativeBuildOptions {
   profile?: "debug" | "release";
   /** The server a desktop app carries (the target's `desktop.server`), staged by DesktopServerStage. */
   server?: DesktopServerBundle;
-  /** Windows: an NSIS setup program beside the app folder. */
+  /** What a person downloads beside the app: a Windows NSIS setup program, a macOS dmg, a Linux AppImage. */
   installer?: boolean;
+  /** The CPU the desktop app runs on, of the same OS; a macOS app is arm64 only. Default this computer's. */
+  arch?: DesktopArch;
 }
 
 export interface NativeDevOptions extends NativeRunOptions {
@@ -74,14 +76,24 @@ export class NativeApp {
     return path.join(this.targetRoot, "dev", platform);
   }
 
+  /** Where the app starts on `platform`: its platform section's `indexPath`, else the target's. */
+  indexPath(platform: NativePlatform) {
+    const { config } = this.target;
+    const section = platform === "ios" ? config.ios : platform === "android" ? config.android : config.desktop;
+    return section?.indexPath ?? config.indexPath;
+  }
+
   /** The web root, from the production build the native commands run first. */
-  async assembleWeb() {
+  async assembleWeb(platform: NativePlatform) {
     const dist = this.app.dist.cwdPath;
-    return await this.web.assemble(this.target.config, {
-      html: path.join(dist, "csr", targetHtmlFilename(this.target.config)),
-      publicDir: path.join(dist, "public"),
-      fontsDir: path.join(dist, ".akan", "artifact", "fonts"),
-    });
+    return await this.web.assemble(
+      { ...this.target.config, indexPath: this.indexPath(platform) },
+      {
+        html: path.join(dist, "csr", targetHtmlFilename(this.target.config)),
+        publicDir: path.join(dist, "public"),
+        fontsDir: path.join(dist, ".akan", "artifact", "fonts"),
+      },
+    );
   }
 
   /** Where a desktop build stages the executables it carries (akan.config.ts `bin`). */
@@ -94,10 +106,12 @@ export class NativeApp {
     server,
     platform,
     stageBin = true,
+    arch,
   }: {
     server?: DesktopServerBundle;
     platform: NativePlatform;
     stageBin?: boolean;
+    arch?: DesktopArch;
   }) {
     const [appConfig, plugins, nativePlugins] = await Promise.all([
       this.app.getConfig(),
@@ -105,7 +119,7 @@ export class NativeApp {
       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) : [];
+    const carried = desktop && stageBin ? await new DesktopBin(this.app, appConfig).stage(this.binDir, arch) : [];
     return NativeConfig.build({
       appPath: this.app.cwdPath,
       target: this.target.config,
@@ -121,10 +135,10 @@ export class NativeApp {
   }
 
   /** The API and the config it is about to build, refused here when the runtime would refuse it later. */
-  async prepare(platform: NativePlatform, server?: DesktopServerBundle) {
+  async prepare(platform: NativePlatform, server?: DesktopServerBundle, arch?: DesktopArch) {
     const [api, { config, warnings }] = await Promise.all([
       NativeApi.load(this.app.cwdPath),
-      this.config({ platform, ...(server ? { server } : {}) }),
+      this.config({ platform, ...(server ? { server } : {}), ...(arch ? { arch } : {}) }),
     ]);
     for (const warning of warnings) this.app.logger.warn(warning);
     this.#assertValid(api, config);
@@ -165,15 +179,35 @@ export class NativeApp {
     };
   }
 
-  async build(platform: NativePlatform, { profile = "release", server, installer = false }: NativeBuildOptions = {}) {
+  async build(
+    platform: NativePlatform,
+    { profile = "release", server, installer = false, arch }: 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(platform, server);
+    NativeApp.assertInstaller(platform, installer);
+    await this.assembleWeb(platform);
+    const { api, config } = await this.prepare(platform, server, arch);
     return await api.build({
       ...this.#task(platform, config),
       profile,
-      ...(installer ? { windows: { installer } } : {}),
+      ...(arch ? { arch } : {}),
+      ...(platform === "windows"
+        ? {
+            windows: {
+              ...(installer ? { installer } : {}),
+              ...(profile === "release" ? NativeApp.#windowsSigning(api) : {}),
+            },
+          }
+        : {}),
+      ...(platform === "macos"
+        ? {
+            macos: {
+              ...(profile === "release" ? api.macosDistributionFromEnv(process.env) : {}),
+              ...(installer ? { dmg: true } : {}),
+            },
+          }
+        : {}),
+      ...(platform === "linux" && installer ? { linux: { appImage: true } } : {}),
     });
   }
 
@@ -182,7 +216,7 @@ export class NativeApp {
     { device, teamId, profile = "debug", server }: NativeRunOptions & NativeBuildOptions = {},
   ) {
     NativeApp.#assertServerPlatform(platform, server);
-    await this.assembleWeb();
+    await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server);
     return await api.run({
       ...this.#task(platform, config),
@@ -211,7 +245,7 @@ export class NativeApp {
         wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
         reversePorts: [Number(new URL(upstream).port)],
         onLine: this.#appLine,
-        startPath: this.startPath(lang),
+        startPath: this.startPath(lang, platform),
         ...(device ? { device } : {}),
         ...(teamId ? { ios: { signing: { teamId } } } : {}),
       });
@@ -242,7 +276,7 @@ export class NativeApp {
   }
 
   async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
-    await this.assembleWeb();
+    await this.assembleWeb("ios");
     const { api, config } = await this.prepare("ios");
     return await api.release({
       ...this.#task("ios", config),
@@ -263,13 +297,16 @@ export class NativeApp {
   ) {
     NativeApp.#assertServerPlatform(platform, server);
     this.#assertUpdates();
-    await this.assembleWeb();
+    await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform, server);
     return await api.publishUpdate({
       ...this.#task(platform, config),
       platform,
       out: this.updatesDir,
       ...(channel ? { channel } : {}),
+      //? The updater keeps the installed app's signature, so a release is signed as the downloaded app was.
+      ...(platform === "macos" ? { macos: api.macosDistributionFromEnv(process.env) } : {}),
+      ...(platform === "windows" ? { windows: NativeApp.#windowsSigning(api) } : {}),
     });
   }
 
@@ -324,14 +361,14 @@ export class NativeApp {
 
   async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
     const signing = NativeApp.androidSigning();
-    await this.assembleWeb();
+    await this.assembleWeb("android");
     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();
+    await this.assembleWeb(platform);
     const { api, config } = await this.prepare(platform);
     if (!config.updates)
       throw new Error(
@@ -370,17 +407,29 @@ export class NativeApp {
 
   /** The first page of a dev build, the target's home as a release bundle opens it; the dev server answers the CSR
    * shell only for `?csr=true`. */
-  startPath(lang: string) {
+  startPath(lang: string, platform: NativePlatform) {
     const basePath = this.target.config.basePath?.replace(/^\/+|\/+$/g, "");
+    const indexPath = this.indexPath(platform);
     const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
     if (basePath) params.set("akanMobileBasePath", basePath);
-    if (this.target.config.indexPath) params.set("akanMobileIndexPath", this.target.config.indexPath);
-    const home = [lang, basePath, this.target.config.indexPath]
+    if (indexPath) params.set("akanMobileIndexPath", indexPath);
+    const home = [lang, basePath, indexPath]
       .flatMap((part) => (part ?? "").split("/"))
       .filter((segment) => segment.length > 0);
     return `/${home.join("/")}?${params}`;
   }
 
+  static #windowsSigning(api: NativeBuildApiModule) {
+    const signing = api.windowsSigningFromEnv(process.env);
+    return signing ? { signing } : {};
+  }
+
+  //* `installer` is the file a person downloads: a setup program on Windows, a disk image on macOS, an AppImage on Linux.
+  static assertInstaller(platform: NativePlatform, installer: boolean) {
+    if (installer && (platform === "ios" || platform === "android"))
+      throw new Error(`An installer is built for a desktop app (Windows, macOS, Linux), not for ${platform}.`);
+  }
+
   //? 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"))

package/mobile/nativeConfig.test.ts

@@ -341,6 +341,30 @@ describe("NativeConfig.build", () => {
     expect((await NativeApi.load(repoApp)).validateConfig(config, { appDir: root })).toEqual([]);
   });
 
+  test("a desktop app's own entitlements reach the macOS build, and the runtime accepts them", async () => {
+    const root = await makeTempRoot();
+    const entitlements = { "com.apple.security.cs.disable-library-validation": true };
+    const { config } = NativeConfig.build({
+      appPath: root,
+      target: {
+        ...minimalTarget,
+        permissions: [],
+        deepLinks: undefined,
+        android: undefined,
+        desktop: { entitlements },
+      },
+      webDir: path.join(root, "web"),
+      contributions: [],
+      locales: ["en"],
+      platform: "macos",
+    });
+
+    expect(config.native?.macos).toEqual({ entitlements });
+    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({

package/mobile/nativeConfig.ts

@@ -161,7 +161,8 @@ export class NativeConfig {
       ...Object.entries(target.ios?.files ?? {}).map(([to, from]) => ({ from: abs(from), to: `ios/${to}` })),
       ...Object.entries(target.android?.files ?? {}).map(([to, from]) => ({ from: abs(from), to: `android/${to}` })),
     ];
-    const native = NativeConfig.#compact({ ios, android, resources });
+    const macos = NativeConfig.#compact({ entitlements: target.desktop?.entitlements });
+    const native = NativeConfig.#compact({ ios, macos, android, resources });
     const googleServices = target.android?.googleServices;
     const pushAndroid = target.android?.push;
     const desktop = NativeConfig.#compact<NonNullable<AkanNativeConfig["desktop"]>>({
@@ -234,10 +235,7 @@ export class NativeConfig {
   }
 
   //? akanConfig refuses a target whose merged updates lack url or publicKey; the type still has them optional.
-  static #updates(
-    target: AkanNativeTarget,
-    env?: NativeEnv,
-  ): NonNullable<AkanNativeConfig["updates"]> | undefined {
+  static #updates(target: AkanNativeTarget, env?: NativeEnv): NonNullable<AkanNativeConfig["updates"]> | undefined {
     const { url, publicKey, channel = env, ...rest } = target.updates ?? {};
     return url && publicKey ? { ...rest, url, publicKey, ...(channel ? { channel } : {}) } : undefined;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-beta.30",
+  "version": "3.0.0-beta.32",
   "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.30",
+    "akanjs": "3.0.0-beta.32",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",