@akanjs/devkit 3.0.0-beta.9 → 3.0.1

package/mobile/desktopBin.test.ts

@@ -0,0 +1,182 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type { AkanBinConfig, BinPlatform } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { DesktopBin } from "./desktopBin";
+
+const makeTempRoot = tempDirs("akan-desktop-bin-");
+const here = DesktopBin.platform() as BinPlatform;
+const elsewhere: BinPlatform = here === "linux-x64" ? "darwin-arm64" : "linux-x64";
+const script = "#!/bin/sh\necho carried\n";
+
+const fakeApp = (cwdPath: string, libs: string[] = []) =>
+  ({
+    name: "portal",
+    cwdPath,
+    getScanInfo: () => ({ getLibs: () => libs }),
+    logger: { info: () => {}, warn: () => {} },
+    spawn: async (command: string, args: string[], { cwd }: { cwd?: string } = {}) => {
+      const proc = Bun.spawnSync([command, ...args], { cwd });
+      if (proc.exitCode !== 0) throw new Error(proc.stderr.toString());
+      return proc.stdout.toString();
+    },
+  }) as never;
+
+const stage = async (
+  root: string,
+  bin: AkanBinConfig,
+  { libBins = [], libs = [] }: { libBins?: { lib: string; bin: AkanBinConfig }[]; libs?: string[] } = {},
+) => {
+  const binDir = path.join(root, "apps/portal/.akan/native/default/bin");
+  const config = { app: { name: "portal" }, bin, libBins } as never;
+  const carried = await new DesktopBin(fakeApp(path.join(root, "apps/portal"), libs), config).stage(binDir);
+  return { carried, binDir };
+};
+
+let requests = 0;
+const served = new Map<string, Uint8Array<ArrayBuffer>>();
+const files = Bun.serve({
+  port: 0,
+  fetch(req) {
+    requests++;
+    const body = served.get(new URL(req.url).pathname);
+    return body ? new Response(body) : new Response("missing", { status: 404 });
+  },
+});
+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" } } };
+    const other = { gst: { [here]: { path: "/other/gst" } } };
+    const chosen = DesktopBin.select(
+      {
+        app: { name: "portal" } as never,
+        bin: own,
+        libBins: [
+          { lib: "media", bin: lib },
+          { lib: "robotics", bin: other },
+        ],
+      },
+      ["media"],
+    );
+    expect([...chosen.entries()]).toEqual([
+      ["ffmpeg", { owner: "apps/portal/akan.config.ts", platforms: own.ffmpeg }],
+      ["ffprobe", { owner: "libs/media/akan.config.ts", platforms: lib.ffprobe }],
+    ]);
+  });
+
+  test("two libs may repeat an entry but not change it", () => {
+    const select = (second: AkanBinConfig) => () =>
+      DesktopBin.select(
+        {
+          app: { name: "portal" } as never,
+          bin: {},
+          libBins: [
+            { lib: "media", bin: { ffmpeg: { [here]: { path: "/lib/ffmpeg" } } } },
+            { lib: "video", bin: second },
+          ],
+        },
+        ["media", "video"],
+      );
+    expect(select({ ffmpeg: { [here]: { path: "/lib/ffmpeg" } } })).not.toThrow();
+    expect(select({ ffmpeg: { [here]: { path: "/video/ffmpeg" } } })).toThrow(
+      "libs/media/akan.config.ts and libs/video/akan.config.ts declare bin.ffmpeg differently",
+    );
+  });
+
+  test("keeps an extension on Windows, where PATH lookup needs one", () => {
+    expect(DesktopBin.fileName("ffmpeg", "/x/ffmpeg.exe", "win32")).toBe("ffmpeg.exe");
+    expect(DesktopBin.fileName("ffmpeg", "/x/ffmpeg", "win32")).toBe("ffmpeg.exe");
+    expect(DesktopBin.fileName("tool", "/x/tool.cmd", "win32")).toBe("tool.cmd");
+    expect(DesktopBin.fileName("ffmpeg", "/x/ffmpeg.exe", "darwin")).toBe("ffmpeg");
+  });
+
+  test("names a download by its URL's extension alone, so no URL writes outside the cache folder", () => {
+    expect(DesktopBin.downloadName("https://x.dev/r/ffmpeg-7.1-linux64.tar.xz")).toBe("download.tar.xz");
+    expect(DesktopBin.downloadName("https://x.dev/r/FFmpeg.ZIP?token=1")).toBe("download.zip");
+    expect(DesktopBin.downloadName("https://x.dev/r/ffmpeg.exe")).toBe("download.exe");
+    expect(DesktopBin.downloadName("https://x.dev/r/ffmpeg")).toBe("download");
+    expect(DesktopBin.downloadName("https://x.dev/r/ffmpeg%E0.zip")).toBe("download.zip");
+    expect(DesktopBin.downloadName("https://x.dev/a/..%2F..%2Fevil.zip")).toBe("download.zip");
+    expect(DesktopBin.downloadName("https://x.dev/a/..%5C..%5Cevil.zip")).toBe("download.zip");
+  });
+
+  test("unpacks with the OS's own tools", () => {
+    expect(DesktopBin.extractCommand("/c/a.zip", "/d", "linux")).toEqual(["unzip", "-q", "-o", "/c/a.zip", "-d", "/d"]);
+    expect(DesktopBin.extractCommand("/c/a.zip", "/d", "darwin")).toEqual(["tar", "-xf", "/c/a.zip", "-C", "/d"]);
+    expect(DesktopBin.extractCommand("C:\\c\\a.zip", "C:\\d", "win32")[0]).toMatch(/System32[\\/]tar\.exe$/);
+  });
+
+  test("copies a file into the app's bin folder, executable", async () => {
+    const root = await makeTempRoot();
+    writeFileSync(path.join(root, "tool"), script);
+    const { carried, binDir } = await stage(root, { tool: { [here]: { path: path.join(root, "tool") } } });
+    const staged = path.join(binDir, DesktopBin.fileName("tool", "tool"));
+    expect(carried).toEqual(["tool"]);
+    expect(readFileSync(staged, "utf8")).toBe(script);
+    if (process.platform !== "win32") expect(statSync(staged).mode & 0o111).toBe(0o111);
+  });
+
+  test("empties the folder first, so a bin taken out of the config is not carried again", async () => {
+    const root = await makeTempRoot();
+    writeFileSync(path.join(root, "tool"), script);
+    writeFileSync(path.join(root, "other"), script);
+    await stage(root, { tool: { [here]: { path: path.join(root, "tool") } } });
+    const { binDir } = await stage(root, { other: { [here]: { path: path.join(root, "other") } } });
+    expect(readdirSync(binDir)).toEqual([DesktopBin.fileName("other", "other")]);
+  });
+
+  test("downloads once, checks the hash, and reuses the file it kept", async () => {
+    const root = await makeTempRoot();
+    served.set("/ffmpeg", new TextEncoder().encode(script));
+    const bin = { ffmpeg: { [here]: { url: `${files.url}ffmpeg`, sha256: hash(script) } } };
+    const before = requests;
+    await stage(root, bin);
+    await stage(root, bin);
+    expect(requests - before).toBe(1);
+    await expect(
+      stage(await makeTempRoot(), { ffmpeg: { [here]: { url: `${files.url}ffmpeg`, sha256: "0".repeat(64) } } }),
+    ).rejects.toThrow(`hashes to ${hash(script)}, not the declared`);
+  });
+
+  test("takes the executable out of an archive", async () => {
+    const root = await makeTempRoot();
+    mkdirSync(path.join(root, "pkg/ffmpeg-7.1/bin"), { recursive: true });
+    writeFileSync(path.join(root, "pkg/ffmpeg-7.1/bin/ffmpeg"), script);
+    Bun.spawnSync(["tar", "-czf", path.join(root, "ffmpeg.tar.gz"), "-C", path.join(root, "pkg"), "ffmpeg-7.1"]);
+    served.set("/ffmpeg.tar.gz", new Uint8Array(readFileSync(path.join(root, "ffmpeg.tar.gz"))));
+    const { binDir } = await stage(root, {
+      ffmpeg: {
+        [here]: {
+          url: `${files.url}ffmpeg.tar.gz`,
+          sha256: hash(readFileSync(path.join(root, "ffmpeg.tar.gz"))),
+          file: "ffmpeg-7.1/bin/ffmpeg",
+        },
+      },
+    });
+    expect(readFileSync(path.join(binDir, DesktopBin.fileName("ffmpeg", "ffmpeg")), "utf8")).toBe(script);
+    await expect(
+      stage(await makeTempRoot(), {
+        ffmpeg: { [here]: { path: path.join(root, "ffmpeg.tar.gz"), file: "ffmpeg-7.1/bin/ffprobe" } },
+      }),
+    ).rejects.toThrow("the archive holds no ffmpeg-7.1/bin/ffprobe");
+  });
+
+  test("refuses an entry with no file for this computer, and carries nothing for a lib the app does not use", async () => {
+    const root = await makeTempRoot();
+    await expect(stage(root, { ffmpeg: { [elsewhere]: { path: "/x/ffmpeg" } } })).rejects.toThrow(
+      `apps/portal/akan.config.ts: bin.ffmpeg names no ${here} file`,
+    );
+    const unused = await stage(root, {}, { libBins: [{ lib: "media", bin: { ffmpeg: { [here]: { path: "/x" } } } }] });
+    expect(unused.carried).toEqual([]);
+  });
+});

package/mobile/desktopBin.ts

@@ -0,0 +1,144 @@
+import { chmod, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  type AkanAppConfig,
+  type AkanBinConfig,
+  type AkanBinSource,
+  type AkanBinUrlSource,
+  type BinPlatform,
+  binPlatforms,
+} from "../akanConfig";
+import type { App } from "../commandDecorators";
+
+type BinPlatforms = AkanBinConfig[string];
+export type DesktopArch = "arm64" | "x64";
+
+//* 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(arch: string = process.arch): BinPlatform | null {
+    const platform = `${process.platform}-${arch}`;
+    return (binPlatforms as readonly string[]).includes(platform) ? (platform as BinPlatform) : null;
+  }
+
+  /** The app's own entries, then those of the libs it depends on: the app's wins a name, two libs may not differ on one. */
+  static select(config: Pick<AkanAppConfig, "app" | "bin" | "libBins">, libs: string[]) {
+    const chosen = new Map<string, { owner: string; platforms: BinPlatforms }>();
+    for (const [name, platforms] of Object.entries(config.bin))
+      chosen.set(name, { owner: `apps/${config.app.name}/akan.config.ts`, platforms });
+    for (const { lib, bin } of config.libBins) {
+      if (!libs.includes(lib)) continue;
+      const owner = `libs/${lib}/akan.config.ts`;
+      for (const [name, platforms] of Object.entries(bin)) {
+        const held = chosen.get(name);
+        if (!held) chosen.set(name, { owner, platforms });
+        else if (held.owner.startsWith("libs/") && JSON.stringify(held.platforms) !== JSON.stringify(platforms))
+          throw new Error(
+            `${held.owner} and ${owner} declare bin.${name} differently; declare it in apps/${config.app.name}/akan.config.ts to pick one.`,
+          );
+      }
+    }
+    return chosen;
+  }
+
+  /** Windows finds an executable on PATH by its extension, so the carried file keeps one. */
+  static fileName(name: string, executable: string, platform: NodeJS.Platform = process.platform) {
+    if (platform !== "win32" || /\.(exe|cmd|bat|com)$/i.test(name)) return name;
+    return `${name}${path.extname(executable).toLowerCase() || ".exe"}`;
+  }
+
+  //? Only the extension is taken from the URL: unzip and a Windows PATH lookup read it, and a decoded name could carry
+  //? a separator or `..` out of the cache folder.
+  static downloadName(url: string) {
+    const extension = /(?:\.tar)?\.[A-Za-z0-9]{1,8}$/.exec(path.posix.basename(new URL(url).pathname))?.[0] ?? "";
+    return `download${extension.toLowerCase()}`;
+  }
+
+  static extractCommand(archive: string, dir: string, platform: NodeJS.Platform = process.platform): string[] {
+    if (platform === "linux" && /\.zip$/i.test(archive)) return ["unzip", "-q", "-o", archive, "-d", dir];
+    //? Windows' own bsdtar reads zip, and a GNU tar ahead of it on PATH (Git's) takes `C:` for a remote host.
+    const tar =
+      platform === "win32" ? path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe") : "tar";
+    return [tar, "-xf", archive, "-C", dir];
+  }
+
+  static async sha256(file: string) {
+    return new Bun.CryptoHasher("sha256").update(await Bun.file(file).arrayBuffer()).digest("hex");
+  }
+
+  get #cacheDir() {
+    return path.join(this.app.cwdPath, ".akan", "cache", "bin");
+  }
+
+  /** Copies each chosen executable into `dir`, emptied first, and answers the names it carries. */
+  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(arch);
+    if (!platform)
+      throw new Error(
+        `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 });
+    for (const [name, { owner, platforms }] of chosen) {
+      const source = platforms[platform];
+      if (!source)
+        throw new Error(
+          `${owner}: bin.${name} names no ${platform} file, the platform this desktop app is built for (it names ${Object.keys(platforms).join(", ") || "none"}).`,
+        );
+      const executable = await this.#executable(`${owner}: bin.${name}.${platform}`, source);
+      const target = path.join(dir, DesktopBin.fileName(name, executable));
+      await Bun.write(target, Bun.file(executable));
+      await chmod(target, 0o755);
+      this.app.logger.info(`The desktop app carries ${name} from ${"url" in source ? source.url : source.path}`);
+    }
+    return [...chosen.keys()];
+  }
+
+  async #executable(at: string, source: AkanBinSource): Promise<string> {
+    const file = "url" in source ? await this.#download(at, source) : source.path;
+    if (!(await Bun.file(file).exists())) throw new Error(`${at}: ${file} does not exist`);
+    if (!source.file) return file;
+    const key = "url" in source ? source.sha256 : await DesktopBin.sha256(file);
+    const executable = path.join(await this.#extract(file, key), ...source.file.split("/"));
+    if (!(await Bun.file(executable).exists())) throw new Error(`${at}: the archive holds no ${source.file}`);
+    return executable;
+  }
+
+  async #download(at: string, { url, sha256 }: AkanBinUrlSource): Promise<string> {
+    const dir = path.join(this.#cacheDir, sha256);
+    const file = path.join(dir, DesktopBin.downloadName(url));
+    if (await Bun.file(file).exists()) return file;
+    await mkdir(dir, { recursive: true });
+    this.app.logger.info(`Downloading ${url}`);
+    const res = await fetch(url, { signal: AbortSignal.timeout(600_000) });
+    if (!res.ok) throw new Error(`${at}: ${url} answered ${res.status}`);
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    const digest = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+    if (digest !== sha256) throw new Error(`${at}: ${url} hashes to ${digest}, not the declared ${sha256}`);
+    await Bun.write(`${file}.partial`, bytes);
+    await rename(`${file}.partial`, file);
+    return file;
+  }
+
+  async #extract(archive: string, key: string): Promise<string> {
+    const dir = path.join(this.#cacheDir, key, "extracted");
+    if (await Bun.file(`${dir}.done`).exists()) return dir;
+    await rm(dir, { recursive: true, force: true });
+    await mkdir(dir, { recursive: true });
+    const [command = "tar", ...args] = DesktopBin.extractCommand(archive, dir);
+    if (command === "unzip" && !Bun.which("unzip"))
+      throw new Error(`${archive} is a zip, and this computer has no unzip: install it, or use a .tar.gz or .tar.xz.`);
+    await this.app.spawn(command, args, { cwd: dir });
+    await writeFile(`${dir}.done`, "");
+    return dir;
+  }
+}

package/mobile/desktopServerStage.test.ts

@@ -0,0 +1,252 @@
+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", rclnodejs: "1.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("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([
+      "@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 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");
+    });
+
+    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");
+  });
+});