@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/lint/no-web-only-api-outside-webkit.grit

@@ -0,0 +1,44 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Browser APIs a native shell's WebView lacks: Android's WebView has no Web Share, an app:// page on iOS has no
+// service worker, no WebView has the Notification API, and iOS has no vibration. They stay legal on the web, so the
+// rule does not ban them — it keeps them in `webkit/`, the layer whose hooks branch on the platform (and is
+// excluded from this rule's scope in biome.base.json), and names the native side where one exists.
+//
+// Pinned to member access, so JSX text naming an API does not match; `Notification` only through its static entry
+// points, because the name is also the libs/shared model (`Notification.View`, `cnst.Notification`).
+or {
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `navigator.share`, `navigator.canShare` },
+    register_diagnostic(
+      span = $access,
+      message = "Android's WebView has no Web Share, so this does nothing in the app. Move it into a `webkit/` hook that branches on `isNativeApp()` from `akanjs/client/native`; the runtime's `share` plugin is the app side.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: or { `navigator.serviceWorker`, `Notification.requestPermission`, `Notification.permission` },
+    register_diagnostic(
+      span = $access,
+      message = "A native app page has no service worker or Notification API. Keep this in a `webkit/` hook behind `isNativeApp()`; native push is `push` from `akanjs/client/native`, and `usePushNotification` in libs/util wraps both.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: `navigator.geolocation`,
+    register_diagnostic(
+      span = $access,
+      message = "`navigator.geolocation` skips the app's location plugin and its permission flow. Use `useGeoLocation` from `akanjs/webkit`.",
+      severity = "warn"
+    )
+  },
+  JsStaticMemberExpression() as $access where {
+    $access <: `navigator.vibrate`,
+    register_diagnostic(
+      span = $access,
+      message = "iOS has no `navigator.vibrate`. Use `haptics` from `akanjs/client/native` in a `webkit/` hook.",
+      severity = "warn"
+    )
+  }
+}

package/lint/no-web-storage.grit

@@ -0,0 +1,30 @@
+engine biome(1.0)
+language js(typescript, jsx)
+
+// Web Storage works inside the native shells, so this is not about a crash: akanjs/client's `storage` is where the
+// backend is chosen per platform (the shell's Preferences — UserDefaults, SharedPreferences, a JSON file on the
+// desktop — in an app, localStorage on the web), `secretStorage` keeps credentials in the Keychain/Keystore and
+// clears them on a reinstall, and both answer nothing on the server where a bare `localStorage` read during SSR
+// throws.
+//
+// Only the global is matched — a reference, or a member of window/globalThis/self — pinned to those node kinds: a
+// bare snippet matches the name in any position, a field, an object key or JSX text included.
+or {
+  JsIdentifierExpression() as $access where {
+    $access <: or { `localStorage`, `sessionStorage` },
+    register_diagnostic(
+      span = $access,
+      message = "Web Storage bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. Use `storage` from `akanjs/client`, or `secretStorage` for tokens and credentials; a value that may be lost with the tab belongs in component state or the store.",
+      severity = "error"
+    )
+  },
+  JsStaticMemberExpression(object = $root, member = $name) as $access where {
+    $root <: or { `window`, `globalThis`, `self` },
+    $name <: or { `localStorage`, `sessionStorage` },
+    register_diagnostic(
+      span = $access,
+      message = "Web Storage bypasses the store akanjs picks per platform (the shell's Preferences in an app) and throws during SSR. Use `storage` from `akanjs/client`, or `secretStorage` for tokens and credentials; a value that may be lost with the tab belongs in component state or the store.",
+      severity = "error"
+    )
+  }
+}

package/linter.test.ts

@@ -27,8 +27,7 @@ describe("parseBiomeReport", () => {
   });
 
   test("reads a report behind leading text that carries a brace", () => {
-    // The whole reason the first-brace-to-last-brace slice was wrong: Biome prints configuration and IO
-    // diagnostics onto the same stream as the report, and those messages quote source and config.
+    // Biome prints configuration and IO diagnostics onto the report's stream, and they quote source and config.
     const output = [
       "configuration/deserialize: unknown key `overrides[0].includes { }`",
       "  the file `biome.jsonc` cannot be read",

package/linter.ts

@@ -58,16 +58,8 @@ interface LintResponse {
   warnings: LintMessage[];
 }
 
-/**
- * Extracts the `--reporter=json` report from Biome's output.
- *
- * Biome mixes configuration and IO diagnostics into the same stream as the report, so the output is not
- * always JSON alone. Slicing from the first `{` to the last `}` mis-parses as soon as that leading text
- * carries a brace of its own, which is not hypothetical: a config error printed ahead of the report made
- * one unchanged command alternate between 2 and 10 diagnostics. So every `{` is tried as a start, its
- * match is found by depth while string literals are skipped, and the first candidate that both parses and
- * carries a report field wins — a brace in prose parses as nothing, and `{"a":1}` in prose is not a report.
- */
+// Biome mixes config and IO diagnostics into the report stream, and that text can carry braces of its own, so every
+// `{` is tried as a start (string literals skipped) and the first candidate that parses and carries a report field wins.
 export const parseBiomeReport = (output: string): BiomeReport => {
   for (let start = output.indexOf("{"); start !== -1; start = output.indexOf("{", start + 1)) {
     const end = objectEndAt(output, start);
@@ -111,7 +103,19 @@ const asBiomeReport = (candidate: string): BiomeReport | null => {
 /** Biome reads `biome.json` first and `biome.jsonc` second; only the latter may carry comments. */
 const BIOME_CONFIG_FILES = ["biome.json", "biome.jsonc"] as const;
 
+const emptyResult = (filePath: string): LintResult => ({
+  filePath,
+  messages: [],
+  errorCount: 0,
+  warningCount: 0,
+  fixableErrorCount: 0,
+  fixableWarningCount: 0,
+});
+
 export class Linter {
+  //? Bun links a package bin as `<name>.exe` (plus a `.bunx` stub) on Windows, and a bare `<name>` elsewhere.
+  static readonly biomeBinName = process.platform === "win32" ? "biome.exe" : "biome";
+
   lintRoot: string;
   configPath: string;
   #biomeBin: string;
@@ -119,7 +123,7 @@ export class Linter {
   constructor(cwdPath: string) {
     this.lintRoot = this.#findBiomeRootPath(cwdPath);
     this.configPath = Linter.#configPathIn(this.lintRoot) ?? path.join(this.lintRoot, "biome.json");
-    const localBiomeBin = path.join(this.lintRoot, "node_modules/.bin/biome");
+    const localBiomeBin = path.join(this.lintRoot, "node_modules", ".bin", Linter.biomeBinName);
     this.#biomeBin = existsSync(localBiomeBin) ? localBiomeBin : "biome";
   }
 
@@ -199,16 +203,7 @@ export class Linter {
     for (const diagnostic of report.diagnostics ?? []) {
       if (diagnostic.severity !== "error" && diagnostic.severity !== "warning") continue;
       const diagnosticFilePath = this.#diagnosticFilePath(diagnostic, filePath);
-      const result =
-        resultsByPath.get(diagnosticFilePath) ??
-        ({
-          filePath: diagnosticFilePath,
-          messages: [],
-          errorCount: 0,
-          warningCount: 0,
-          fixableErrorCount: 0,
-          fixableWarningCount: 0,
-        } satisfies LintResult);
+      const result = resultsByPath.get(diagnosticFilePath) ?? emptyResult(diagnosticFilePath);
       const message = this.#createLintMessage(diagnostic);
       result.messages.push(message);
       if (message.severity === 2) result.errorCount += 1;
@@ -217,15 +212,7 @@ export class Linter {
     }
 
     return [
-      resultsByPath.get(filePath) ??
-        ({
-          filePath,
-          messages: [],
-          errorCount: 0,
-          warningCount: 0,
-          fixableErrorCount: 0,
-          fixableWarningCount: 0,
-        } satisfies LintResult),
+      resultsByPath.get(filePath) ?? emptyResult(filePath),
       ...[...resultsByPath.entries()].filter(([resultPath]) => resultPath !== filePath).map(([, result]) => result),
     ];
   }
@@ -269,22 +256,12 @@ export class Linter {
     return await this.lintFile(filePath);
   }
 
-  /**
-   * Lint a single file using Biome.
-   * @param filePath - Path to the file to lint
-   * @returns Array of Biome results in the legacy lint result shape
-   */
   async lintFile(filePath: string): Promise<LintResponse> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
     return await this.#checkFile(resolvedFilePath);
   }
 
-  /**
-   * Format lint results for console output
-   * @param results - Array of Biome results
-   * @returns Formatted string
-   */
   formatLintResults(results: LintResult[]): string {
     if (results.length === 0) return "No files to lint";
 
@@ -305,7 +282,7 @@ export class Linter {
             const sourceContent = readFileSync(result.filePath, "utf8");
             sourceLines = sourceContent.split("\n");
           } catch {
-            // Ignore read errors
+            //? An unreadable source only loses its code frame.
           }
         }
 
@@ -318,14 +295,12 @@ export class Linter {
           output.push(`\n  ${icon} ${typeColor(type)}: ${message.message}${ruleInfo}`);
           output.push(`     ${chalk.gray("at")} ${result.filePath}:${chalk.bold(`${message.line}:${message.column}`)}`);
 
-          // Show source line with underline
           if (sourceLines.length > 0 && message.line <= sourceLines.length) {
             const sourceLine = sourceLines[message.line - 1];
             const lineNumber = message.line.toString().padStart(5, " ");
 
             output.push(`\n${chalk.dim(`${lineNumber} |`)} ${sourceLine}`);
 
-            // Create underline
             const underlinePrefix = " ".repeat(message.column - 1);
             const underlineLength = message.endColumn ? message.endColumn - message.column : 1;
             const underline = "^".repeat(Math.max(1, underlineLength));
@@ -345,27 +320,7 @@ export class Linter {
     return summary.concat(output).join("\n");
   }
 
-  /**
-   * Get detailed lint information
-   * @param filePath - Path to the file to lint
-   * @returns Object containing detailed lint information
-   */
-  async getDetailedLintInfo(filePath: string): Promise<{
-    results: LintResult[];
-    details: {
-      line: number;
-      column: number;
-      message: string;
-      ruleId: string | null;
-      severity: "error" | "warning";
-    }[];
-    stats: {
-      errorCount: number;
-      warningCount: number;
-      fixableErrorCount: number;
-      fixableWarningCount: number;
-    };
-  }> {
+  async getDetailedLintInfo(filePath: string) {
     const { results } = await this.lintFile(filePath);
 
     const details = results.flatMap((result) =>
@@ -385,22 +340,13 @@ export class Linter {
         fixableErrorCount: acc.fixableErrorCount + result.fixableErrorCount,
         fixableWarningCount: acc.fixableWarningCount + result.fixableWarningCount,
       }),
-      {
-        errorCount: 0,
-        warningCount: 0,
-        fixableErrorCount: 0,
-        fixableWarningCount: 0,
-      },
+      { errorCount: 0, warningCount: 0, fixableErrorCount: 0, fixableWarningCount: 0 },
     );
 
     return { results, details, stats };
   }
 
-  /**
-   * Check if a file has lint errors
-   * @param filePath - Path to the file to check
-   * @returns true if there are no errors, false otherwise
-   */
+  /** Also false when the file cannot be linted at all. */
   async hasNoLintErrors(filePath: string): Promise<boolean> {
     try {
       const { results } = await this.lintFile(filePath);
@@ -410,32 +356,17 @@ export class Linter {
     }
   }
 
-  /**
-   * Get only error messages (excluding warnings)
-   * @param filePath - Path to the file to lint
-   * @returns Array of error messages
-   */
   async getErrors(filePath: string): Promise<LintMessage[]> {
     const { results } = await this.lintFile(filePath);
     return results.flatMap((result) => result.messages.filter((message) => message.severity === 2));
   }
 
-  /**
-   * Get only warning messages
-   * @param filePath - Path to the file to lint
-   * @returns Array of warning messages
-   */
   async getWarnings(filePath: string): Promise<LintMessage[]> {
     const { results } = await this.lintFile(filePath);
     return results.flatMap((result) => result.messages.filter((message) => message.severity === 1));
   }
 
-  /**
-   * Fix lint errors automatically
-   * @param filePath - Path to the file to fix
-   * @param dryRun - If true, returns the fixed content without writing to file
-   * @returns Fixed content and remaining issues
-   */
+  /** `dryRun` returns the fixed content in `output` without writing the file. */
   async fixFile(filePath: string, dryRun = false): Promise<LintResponse> {
     const resolvedFilePath = this.#resolveFilePath(filePath);
     if (!existsSync(resolvedFilePath)) throw new Error(`File not found: ${filePath}`);
@@ -451,19 +382,8 @@ export class Linter {
     return { ...lintResult, fixed: stdout !== source, output: stdout };
   }
 
-  /**
-   * Get Biome configuration for a file
-   * @param filePath - Path to the file
-   * @returns Biome configuration object
-   */
-  /**
-   * Applies Biome's safe fixes to many files in one process.
-   *
-   * One spawn, not one per file: Biome's startup dominates a small file, so the per-file path turns a
-   * fifteen-file scaffold into three seconds of process launches. Paths that do not exist are dropped
-   * rather than thrown on, because the caller is usually reporting what a template just wrote and a
-   * template is allowed to decline a file.
-   */
+  // One spawn for all files: Biome's startup dominates a small file. Missing paths are dropped (a template may
+  // decline a file).
   async fixFiles(filePaths: string[]): Promise<{ fixed: string[] }> {
     const resolved = filePaths.map((filePath) => this.#resolveFilePath(filePath)).filter(existsSync);
     if (resolved.length === 0) return { fixed: [] };
@@ -489,21 +409,11 @@ export class Linter {
     return JSON.parse(readFileSync(this.configPath, "utf8")) as unknown;
   }
 
-  /**
-   * Get rules that are causing errors in a file
-   * @param filePath - Path to the file to check
-   * @returns Object mapping rule IDs to their error counts
-   */
   async getProblematicRules(filePath: string): Promise<Record<string, number>> {
     const { results } = await this.lintFile(filePath);
     const ruleCounts: Record<string, number> = {};
-
-    results.forEach((result) => {
-      result.messages.forEach((message) => {
-        if (message.ruleId) ruleCounts[message.ruleId] = (ruleCounts[message.ruleId] || 0) + 1;
-      });
-    });
-
+    for (const message of results.flatMap((result) => result.messages))
+      if (message.ruleId) ruleCounts[message.ruleId] = (ruleCounts[message.ruleId] || 0) + 1;
     return ruleCounts;
   }
 }

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