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

package/frontendBuild/ssrDevBundler.ts

@@ -16,7 +16,7 @@ import { VENDOR_SPECIFIERS } from "./vendorSpecifiers";
 //* (the app's client runtime) and every `"use client"` entry; React and the akanjs vendor facets stay the import map's,
 //* so the page keeps one React and one store registry.
 export class SsrDevBundler extends DevRegistryBundler {
-  static readonly #formatVersion = 1;
+  static readonly #formatVersion = 2;
   static readonly bootstrapKey = "";
   readonly reloadsOnEntryChange = false;
   #discovery: ClientEntryDiscovery | null = null;

package/integration/devStability.integration.test.ts

@@ -153,6 +153,41 @@ describe("dev stability integration harness", () => {
     hmr?.close();
   });
 
+  integrationTest(
+    "server edits landing while a restart stops the backend leave the port to the backend it tracks",
+    async () => {
+      const harness = await createHarness();
+      const host = await harness.startHost();
+      const port = await harness.resolvePort();
+      const writeMarker = (label: string) =>
+        harness.writeFile("srvkit/backendMarker.ts", `export const backendMarker = "${label}";\n`);
+
+      const { mark } = await harness.editUntilSeen(host, (attempt) => writeMarker(`burst-first-${attempt}`), {
+        evidence: /stopping backend pid=\d+/,
+      });
+      // Each lands past the 120ms debounce, so a restart timer fires while the one before still waits for its exit.
+      for (let idx = 0; idx < 8; idx++) {
+        await writeMarker(`burst-${idx}`);
+        await new Promise((resolve) => setTimeout(resolve, 200));
+      }
+
+      const trackedPid = () =>
+        [
+          ...host.logs
+            .join("")
+            .slice(mark)
+            .matchAll(/backend spawned pid=(\d+)/g),
+        ].at(-1)?.[1];
+      const settled = await waitForGatewayHealth(
+        port,
+        (health) => String(health.pid) === trackedPid() && health.children.some((child) => child.ready),
+      );
+      expect(String(settled.pid)).toBe(trackedPid() ?? "");
+      const since = host.logs.join("").slice(mark);
+      expect(since).not.toMatch(/already in use|not starting a second one/);
+    },
+  );
+
   integrationTest("client-only valid edits refresh browser state without backend restart", async () => {
     const harness = await createHarness();
     const host = await harness.startHost();

package/mobile/desktopBin.test.ts

@@ -0,0 +1,177 @@
+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/mobile/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("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,143 @@
+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];
+
+//* 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.
+export class DesktopBin {
+  constructor(
+    readonly app: App,
+    readonly config: AkanAppConfig,
+  ) {}
+
+  static platform(): BinPlatform | null {
+    const platform = `${process.platform}-${process.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): 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();
+    if (!platform)
+      throw new Error(
+        `bin: this computer is ${process.platform}-${process.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,129 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AkanAppConfig } from "../akanConfig";
+import { tempDirs } 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"),
+    });
+  });
+
+  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,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";