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

package/frontendBuild/csrDevModuleCompiler.test.ts

@@ -117,6 +117,27 @@ describe("CsrDevModuleCompiler", () => {
         "",
       ].join("\n"),
     );
+    //? The shape of an app's useClient.ts: a macro whose module graph reaches server code that reads import.meta.
+    await Bun.write(
+      file("apps/demo/lib/macroDep.ts"),
+      'import { createRequire } from "node:module";\nconst req = createRequire(import.meta.url);\nexport const depUrl = import.meta.url;\nexport const hasRequire = typeof req;\n',
+    );
+    await Bun.write(
+      file("apps/demo/lib/macro.ts"),
+      'import { depUrl, hasRequire } from "./macroDep";\nexport const serialized = () => ({ depUrl, hasRequire });\n',
+    );
+    await Bun.write(
+      file("apps/demo/lib/useClient.ts"),
+      [
+        'import { used } from "barrel";',
+        'import { serialized } from "./macro" with { type: "macro" };',
+        "export const signal = serialized();",
+        "export const own = import.meta.url;",
+        'export const label = "import.meta.url";',
+        "export const barrel = used;",
+        "",
+      ].join("\n"),
+    );
     await Bun.write(file("node_modules/with-bin/index.mjs"), "#!/usr/bin/env node\nexport const a = 1;\n");
     await Bun.write(file("node_modules/awaits/index.mjs"), "export const a = await Promise.resolve(1);\n");
     await Bun.write(file("apps/demo/ui/awaits.ts"), "export const a = await Promise.resolve(1);\n");
@@ -213,6 +234,17 @@ describe("CsrDevModuleCompiler", () => {
     });
   });
 
+  test("a macro runs with its modules' own import.meta, and the file importing it still reads the browser's", async () => {
+    const { modules } = await compile("apps/demo/lib/useClient.ts", { prepass: true });
+    const module = modules.find((compiled) => compiled.id === "apps/demo/lib/useClient.ts");
+    expect(module?.deps.some((dep) => dep.includes(`${path.join("node_modules", "barrel")}${path.sep}`))).toBe(true);
+    expect(run(module)).toMatchObject({
+      signal: { depUrl: Bun.pathToFileURL(file("apps/demo/lib/macroDep.ts")).href, hasRequire: "function" },
+      own: `${origin}/apps/demo/lib/useClient.ts`,
+      label: "import.meta.url",
+    });
+  });
+
   test("a file or re-export the browser build tree-shook away resolves with the browser condition", async () => {
     const { modules, resolver } = await compile("apps/demo/entry.ts", { prepass: true });
     const ids = modules.map((module) => module.id);

package/frontendBuild/csrDevModuleCompiler.ts

@@ -44,6 +44,7 @@ export interface CsrDevCompileResult {
 //* modules it changed instead of reloading one scope-hoisted file.
 export class CsrDevModuleCompiler {
   static readonly #storeRoot = /(?:^|\/)lib\/st\.ts$/;
+  static readonly #macroImport = /\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']/;
   static readonly #factoryArgument =
     /(?<![\w$.])(?:require|module|exports|__akanImport|\$RefreshReg\$|\$RefreshSig\$)(?![\w$]|\s*:)/;
   static readonly #helperPatches = [
@@ -140,6 +141,7 @@ export class CsrDevModuleCompiler {
       ),
     );
     const misses: string[] = [];
+    const macroOutputs = vendor ? new Map<string, string>() : await this.#evaluateMacros(files);
     let result: Awaited<ReturnType<typeof Bun.build>>;
     try {
       result = await Bun.build({
@@ -157,7 +159,7 @@ export class CsrDevModuleCompiler {
         //? down, and Bun's cjs output keeps `import.meta.env` and spells `import.meta.url` as this disk's `file://` path.
         define: { ...this.#context.define, "import.meta": "__akanMeta" },
         optimizeImports: this.#context.optimizeImports,
-        plugins: [this.#registryPlugin(vendor, misses)],
+        plugins: [this.#registryPlugin(vendor, misses, macroOutputs)],
       });
     } catch (error) {
       if (vendor && error instanceof AggregateError) return await this.#withoutFailed(files, error);
@@ -254,11 +256,52 @@ export class CsrDevModuleCompiler {
     };
   }
 
-  #registryPlugin(vendor: boolean, misses: string[]): BunPlugin {
+  //? Bun applies `define` to the modules a macro imports too, and runs them in this process, where the `import.meta`
+  //? rewrite leaves a free `__akanMeta` that no factory header declares. So a file importing a macro has its macros run
+  //? first by a build of its own, with every other import left as written, and the module build reads that output.
+  async #evaluateMacros(files: string[]): Promise<Map<string, string>> {
+    const sources = await Promise.all(files.map(async (file) => [file, await Bun.file(file).text()] as const));
+    const importers = sources.filter(([, source]) => CsrDevModuleCompiler.#macroImport.test(source));
+    const outputs = await Promise.all(
+      importers.map(async ([file]) => {
+        const result = await Bun.build({
+          entrypoints: [file],
+          target: "browser",
+          format: "esm",
+          plugins: [
+            {
+              name: "akan-csr-macro-pass",
+              setup: (build) =>
+                void build.onResolve({ filter: /.*/ }, (args) =>
+                  args.importer ? { path: args.path, external: true } : undefined,
+                ),
+            },
+          ],
+        });
+        const [output] = result.outputs;
+        if (!output) throw new Error(`[csr-dev] ${this.#paths.idOf(file)}: its macro pass wrote no output`);
+        const text = await output.text();
+        return [
+          [file, text],
+          [CsrDevPaths.realpath(file), text],
+        ] as const;
+      }),
+    );
+    return new Map(outputs.flat());
+  }
+
+  #registryPlugin(vendor: boolean, misses: string[], macroOutputs: Map<string, string>): BunPlugin {
     return {
       name: "akan-csr-registry",
       setup: (build) => {
         build.onLoad({ filter: /\.css$/ }, () => ({ contents: "", loader: "js" }));
+        if (macroOutputs.size > 0) {
+          const exact = [...macroOutputs.keys()].map((file) => file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+          build.onLoad({ filter: new RegExp(`^(?:${exact.join("|")})$`) }, (args) => {
+            const contents = macroOutputs.get(args.path);
+            return contents === undefined ? undefined : { contents, loader: "js" };
+          });
+        }
         if (!vendor)
           build.onLoad({ filter: /\.tsx$/ }, async (args) => {
             if (CsrDevPaths.isVendorFile(args.path)) return undefined;

package/frontendBuild/ssrBaseArtifactBuilder.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { optimize } from "@tailwindcss/node";
-import type { AkanWebConfig } from "akanjs";
+import type { AkanMobileAppId, AkanWebConfig } from "akanjs";
 import type { BaseBuildArtifact } from "akanjs/server";
 import { resolveSsrPageEntriesForApp } from "../artifact/implicitRootLayout";
 import { computeRouteSeedIndex, type RouteSeedIndex, saveRouteSeedIndex } from "../artifact/routeSeedIndex";
@@ -89,7 +89,8 @@ export class SsrBaseArtifactBuilder {
         .filter((target) => (target.deepLinks?.domains?.length ?? 0) > 0)
         .map((target) => ({
           targetName: target.name,
-          appId: target.appId,
+          iosAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "ios"),
+          androidAppId: SsrBaseArtifactBuilder.#appIdOn(target.appId, "android"),
           domains: target.deepLinks?.domains ?? [],
           iosTeamId: target.deepLinks?.ios?.teamId,
           androidSha256CertFingerprints: target.deepLinks?.android?.sha256CertFingerprints,
@@ -223,6 +224,10 @@ export class SsrBaseArtifactBuilder {
   }
 
   // Checked against the written asset, not the compiled text: it is the only stylesheet an SSR render serves.
+  static #appIdOn(appId: AkanMobileAppId, platform: "ios" | "android"): string | null {
+    return typeof appId === "string" ? appId : (appId[platform] ?? appId.default ?? null);
+  }
+
   static #warnDroppedImports(app: App, cssRelPath: string, css: string, imported: ImportedStylesheet[]) {
     for (const { cssPath, declaredNames } of imported) {
       if (declaredNames.length === 0 || declaredNames.some((name) => css.includes(`${name}:`))) continue;

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;
+  }
+}