crossbind 2.0.0-beta.66 → 2.0.0-beta.68

package/README.md

@@ -8,7 +8,7 @@
   <p>
     <strong>Import C++ and Rust like JavaScript modules.</strong><br>
     Build, package, and run native libraries across browsers, Node.js, edge
-    runtimes, iOS, Android, and WASI.
+    runtimes, iOS, Android, and WASI, or ship them in a desktop or mobile app.
   </p>
 
   <p>
@@ -28,10 +28,12 @@
 </div>
 
 crossbind makes native libraries as easy to distribute and consume as
-JavaScript packages. A C++ header, an app-local Rust file, or a declared Cargo
-crate becomes an importable module; crossbind generates the binding layer,
-resolves the transitive native dependency graph, and selects the right artifact
-for every target.
+JavaScript packages. A C++ header, an app-local Rust file, a declared Cargo
+crate, or a ConanCenter package becomes an importable module; crossbind
+generates the binding layer, resolves the transitive native dependency graph,
+and selects the right artifact for every target. It also builds a web page and
+the native code it imports into an app for macOS, Linux, Windows, iOS, and
+Android.
 
 > **Note** — crossbind 2.0 is currently published on the npm `beta` channel.
 > The commands below use `@beta` deliberately.
@@ -133,11 +135,13 @@ native call:
 import { initNative, hello } from './native/hello.h';
 
 await initNative();
-console.log(hello('crossbind'));
+console.log(await hello('crossbind'));
 ```
 
 `initNative()` is exported by every generated native module. One call starts
-the runtime and binds all native modules imported by the application.
+the runtime and binds all native modules imported by the application. In a
+browser the module runs in a Web Worker by default, so each call returns a
+promise.
 
 ## Add crossbind to an existing Vite app
 
@@ -177,8 +181,8 @@ or start from the closest project in [`examples/`](https://github.com/crossbind/
 ## How it works
 
 ```text
-  C++ / Rust source                        header, .rs, or
-  or prebuilt port                         cargo: import
+  C++ / Rust source                        header, .rs, cargo:
+  or prebuilt port                         or conan: import
           |                                       |
           v                                       |
   versioned native package graph                  |
@@ -191,11 +195,13 @@ or start from the closest project in [`examples/`](https://github.com/crossbind/
                     + binding generation
                    + native build and link
                               |
-        +---------------------+---------------------+
-        |                     |                     |
-        v                     v                     v
-  browser / Node / edge   iOS / Android            WASI
-  JavaScript + Wasm       native library + JSI     command component
+                              v
+  browser, Node.js, edge     JavaScript + Wasm
+  Node.js, Electron          Node-API addon
+  iOS, Android               native library + JSI
+  desktop and mobile apps    your page + native host
+  macOS, Linux, Windows      native executable
+  WASI runtimes              command component
 ```
 
 There are two configuration surfaces:
@@ -212,18 +218,21 @@ contract.
 
 ## Runtimes
 
-| Runtime      | Output                                | Important behavior                                                                    |
-| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------- |
-| Browser      | JavaScript loader + WebAssembly       | Single-threaded by default; multithreaded builds need COOP/COEP headers in production |
-| Node.js      | JavaScript loader + WebAssembly       | Supports CommonJS or ESM and reads the host filesystem                                |
-| Edge         | JavaScript loader + WebAssembly       | Single-threaded, memory-backed, with no OPFS or nested worker mode                    |
-| React Native | Native iOS/Android libraries over JSI | No WebAssembly or browser isolation headers                                           |
-| WASI         | One `wasm32-wasip3` command component | No JavaScript host; run with a compatible WASI runtime such as wasmtime 47+           |
+| Runtime      | Output                                               | Important behavior                                                                      |
+| ------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Browser      | JavaScript loader + WebAssembly                      | Single-threaded by default; multithreaded builds need COOP/COEP headers in production   |
+| Node.js      | JavaScript loader + WebAssembly, or a Node-API addon | Supports CommonJS or ESM and reads the host filesystem; the addon loads in Electron too |
+| Edge         | JavaScript loader + WebAssembly                      | Single-threaded, memory-backed, with no OPFS or nested worker mode                      |
+| React Native | Native iOS/Android libraries over JSI                | No WebAssembly or browser isolation headers                                             |
+| Apps         | An app for macOS, Linux, Windows, iOS, and Android   | The page runs in the system webview, native code in the app's own process; no Node.js   |
+| Executables  | Native programs for macOS, Linux, and Windows        | No JavaScript host                                                                      |
+| WASI         | One `wasm32-wasip3` command component                | No JavaScript host; run with a compatible WASI runtime such as wasmtime 47+             |
 
 Threading and worker execution are independent choices:
 
 - `target.runtime: 'mt'` enables a multithreaded build.
-- `initNative({ useWorker: true })` moves the module into a browser Web Worker.
+- Browsers run the module in a Web Worker by default;
+  `initNative({ useWorker: false })` keeps it on the page thread.
 - Browser OPFS persistence requires `useWorker: true`.
 - Browser `mt` builds require COOP/COEP response headers in production.
 
@@ -304,7 +313,7 @@ for the supported type surface and configuration.
 ## Documentation
 
 - [Guide](https://crossbind.dev/guide/) — product concepts, quick start,
-  runtimes, bundlers, bindings, packages, and troubleshooting.
+  runtimes, apps, bundlers, bindings, packages, and troubleshooting.
 - [Runtime and configuration API](https://github.com/crossbind/crossbind/blob/main/docs/api/README.md)
   — canonical build-time and runtime behavior.
 - [Integration playbooks](https://github.com/crossbind/crossbind/blob/main/docs/playbooks/integration/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "crossbind",
-    "version": "2.0.0-beta.66",
+    "version": "2.0.0-beta.68",
     "license": "MIT",
     "homepage": "https://crossbind.dev",
     "repository": "https://github.com/crossbind/crossbind.git",
@@ -38,7 +38,7 @@
         "@rollup/plugin-virtual": "^3.0.2",
         "comlink": "^4.4.2",
         "commander": "^15.0.0",
-        "glob": "^13.0.6",
+        "glob": "^14.0.3",
         "log-update": "^8.0.0",
         "picocolors": "^1.1.1",
         "pngjs": "^7.0.0",

package/src/actions/androidGradle.js

@@ -8,6 +8,8 @@ import pullDockerImage, { getDockerImage } from '../utils/pullDockerImage.js';
 import { DOCKER_BASE, isUnderBase } from '../utils/replaceBasePathForDocker.js';
 import { DOCKER_RUN_SECURITY_ARGS } from '../utils/dockerSecurity.js';
 import { getContentHash } from '../utils/hash.js';
+import { readSecret } from '../utils/keychain.js';
+import { secretFile } from '../utils/secretFile.js';
 
 const ROLE = 'android-app';
 const PLATFORM = 'linux/amd64';
@@ -25,8 +27,12 @@ export const SIGNING = {
 };
 
 const listed = (names) => `${names.join(' and ')} ${names.length > 1 ? 'are' : 'is'}`;
+// A keystore's base64 text, as CI's secrets give it, in place of its file's path: no path runs to a hundred of base64's
+// letters alone.
+const KEYSTORE_TEXT = /^[A-Za-z0-9+/=\s]{100,}$/;
 
-// The keystore of the upload key, or null for none: a release is then signed with the debug key.
+// The keystore of the upload key, or null for none: a release is then signed with the debug key. The keystore is its
+// file, or its base64 text, which goes to a file for the image to mount.
 export function releaseSigning(env = process.env) {
     if (!env[SIGNING.keystore]) {
         const stray = [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]);
@@ -35,11 +41,32 @@ export function releaseSigning(env = process.env) {
     }
     const missing = [SIGNING.alias, SIGNING.password].filter((name) => !env[name]);
     if (missing.length) throw new Error(`crossbind: ${SIGNING.keystore} is set, but ${listed(missing)} not.`);
-    const file = path.resolve(env[SIGNING.keystore]);
+    const given = env[SIGNING.keystore];
+    const isText = !fs.existsSync(given) && KEYSTORE_TEXT.test(given);
+    const file = isText ? secretFile('upload.keystore', Buffer.from(given.replace(/\s/g, ''), 'base64')) : path.resolve(given);
     if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) throw new Error(`crossbind: ${SIGNING.keystore} names ${file}, which is no file.`);
     return { file, names: [SIGNING.alias, SIGNING.password, SIGNING.keyPassword].filter((name) => env[name]) };
 }
 
+// This machine's upload key, which ~/.crossbind.json names, for a build whose environment names none: its file and alias,
+// and its password from the environment, else the keychain, else none yet.
+export function machineUploadKey(env = process.env, system = state.config.system ?? {}) {
+    if (env[SIGNING.keystore] || !system.ANDROID_KEYSTORE) return null;
+    return {
+        keystore: system.ANDROID_KEYSTORE,
+        alias: env[SIGNING.alias] || system.ANDROID_KEY_ALIAS || 'upload',
+        password: env[SIGNING.password] || readSecret(path.resolve(system.ANDROID_KEYSTORE)),
+    };
+}
+
+// The environment a build signs with this machine's upload key in.
+export function uploadKeyEnv({ keystore, alias, password }) {
+    if (!password) {
+        throw new Error(`crossbind: this machine's upload key, ${keystore}, needs its password: set ${SIGNING.password}, or build on a terminal, which asks for it.`);
+    }
+    return { [SIGNING.keystore]: keystore, [SIGNING.alias]: alias, [SIGNING.password]: password };
+}
+
 // Gradle's caches and the Android tools' home outlive a container; the second keeps the debug key, which a new one would
 // replace, so that a later build still installs over the last.
 function homes() {
@@ -61,8 +88,8 @@ function containerArgs(signing) {
     ];
 }
 
-function docker(args, what) {
-    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT });
+function docker(args, what, env = process.env) {
+    const result = spawnSync('docker', args, { encoding: 'utf8', maxBuffer: OUTPUT_LIMIT, env });
     if (result.error) throw new Error(`crossbind: cannot run docker for ${what}: ${result.error.message}`, { cause: result.error });
     if (result.status !== 0) {
         const output = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim().split('\n').slice(-FAILURE_LINES).join('\n');
@@ -79,20 +106,28 @@ function inContainer(project) {
     return path.posix.join(DOCKER_BASE, ...path.relative(state.config.paths.base, dir).split(path.sep));
 }
 
-// An Android app as the files it ships: its release APK, and with an upload key also the bundle Google Play takes, beside
-// the Gradle project as <project>.apk and <project>.aab.
+// An Android app as the files it ships: its release APK, and with an upload key, the environment's or this machine's,
+// also the bundle Google Play takes, beside the Gradle project as <project>.apk and <project>.aab.
 export function packageAndroidRelease(project) {
-    const signing = releaseSigning();
+    const key = machineUploadKey();
+    const env = key ? { ...process.env, ...uploadKeyEnv(key) } : process.env;
+    const signing = releaseSigning(env);
     pullDockerImage(ROLE, PLATFORM);
     docker(['run', '--rm', ...containerArgs(signing), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
-        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`);
+        ...GRADLE, '--no-daemon', 'assembleRelease', ...(signing ? ['bundleRelease'] : [])], `packaging ${path.basename(project)}`, env);
     const outputs = `${project}/app/build/outputs`;
     fs.copyFileSync(`${outputs}/apk/release/app-release.apk`, `${project}.apk`);
     fs.rmSync(`${project}.aab`, { force: true });
+    // The zip of native debug symbols Google Play takes, each ABI's libraries at its root, which the image's JDK makes.
+    fs.rmSync(`${project}-symbols.zip`, { force: true });
+    if (fs.existsSync(`${project}/symbols`)) {
+        docker(['run', '--rm', ...containerArgs(null), '-w', inContainer(project), getDockerImage(ROLE, PLATFORM),
+            'jar', '--create', '--no-manifest', '--file', `../${path.basename(project)}-symbols.zip`, '-C', 'symbols', '.'], `zipping the symbols of ${path.basename(project)}`);
+    }
     if (signing) {
         fs.copyFileSync(`${outputs}/bundle/release/app-release.aab`, `${project}.aab`);
     } else {
-        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. Set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with your upload key and make the bundle too.`);
+        console.warn(`crossbind: ${path.basename(project)}.apk is signed with this machine's debug key: it installs for testing, and Google Play takes no app signed so. crossbind app upload-key makes an upload key, which signs it and makes the bundle too; or set ${SIGNING.keystore}, ${SIGNING.alias} and ${SIGNING.password} to sign it with yours.`);
     }
 }
 

package/src/actions/appInstaller.js

@@ -6,7 +6,7 @@ import { appleSigning } from './appleSigning.js';
 import { updaterSigning } from './appUpdate.js';
 import { inWindowsImage, jsignScript, windowsSigning } from './windowsSigning.js';
 import state from '../state/index.js';
-import { appDisplayName, appId, appUrlSchemes } from '../utils/appOptions.js';
+import { appCategory, appDisplayName, appId, appUrlSchemes } from '../utils/appOptions.js';
 import { readAppIcon, windowsIcon } from '../utils/appIcon.js';
 import { imageRoleFor } from '../utils/pullDockerImage.js';
 import { isUnderBase } from '../utils/replaceBasePathForDocker.js';
@@ -61,12 +61,13 @@ export function debianControl({ name, version, arch, author, description, label
 
 // The desktop entry a Linux menu shows an app by. GTK names the app's window after the command that started it, and
 // GNOME on Wayland shows the icon of the entry whose file has that name.
-// A link of one of its schemes opens it with the link as its argument, %u.
-export function desktopEntry({ label, command, hasIcon, urlSchemes = [] }) {
+// A link of one of its schemes opens it with the link as its argument, %u. A menu shows it under its categories.
+export function desktopEntry({ label, command, hasIcon, urlSchemes = [], categories = null }) {
     const isLinked = urlSchemes.length > 0;
     return [
         '[Desktop Entry]', 'Type=Application', `Name=${label}`, `Exec=${command}${isLinked ? ' %u' : ''}`, ...(hasIcon ? [`Icon=${command}`] : []),
-        ...(isLinked ? [`MimeType=${urlSchemes.map((scheme) => `x-scheme-handler/${scheme};`).join('')}`] : []), 'Terminal=false', '',
+        ...(isLinked ? [`MimeType=${urlSchemes.map((scheme) => `x-scheme-handler/${scheme};`).join('')}`] : []),
+        ...(categories ? [`Categories=${categories};`] : []), 'Terminal=false', '',
     ].join('\n');
 }
 
@@ -106,7 +107,9 @@ function debianPackage(app, target) {
     const icon = `${app}/resources/icon.png`;
     const hasIcon = fs.existsSync(icon);
     if (hasIcon) fs.copyFileSync(icon, `${dir('usr/share/icons/hicolor/512x512/apps')}/${name}.png`);
-    fs.writeFileSync(`${dir('usr/share/applications')}/${name}.desktop`, desktopEntry({ label, command: name, hasIcon, urlSchemes: appUrlSchemes(state.config) }));
+    fs.writeFileSync(`${dir('usr/share/applications')}/${name}.desktop`, desktopEntry({
+        label, command: name, hasIcon, urlSchemes: appUrlSchemes(state.config), categories: appCategory(state.config)?.linux,
+    }));
     const { author, description } = state.config.package ?? {};
     fs.writeFileSync(`${dir('DEBIAN')}/control`, debianControl({ name, version: packageVersion(), arch: target.arch, author, description, label }));
     run(null, ['dpkg-deb', '--build', '--root-owner-group', root, `${app}.deb`], null, target);

package/src/actions/appSetup.js

@@ -0,0 +1,116 @@
+import state from '../state/index.js';
+import { askLine, askYesNo } from '../utils/ask.js';
+import { entry, writeAppOption } from '../utils/configWriter.js';
+import { PRIVACY_CATEGORIES } from '../utils/appOptions.js';
+import { readAppIcon } from '../utils/appIcon.js';
+
+// What only the project can answer, which `crossbind app publish` asks on a terminal and writes into crossbind.config.js
+// once the user says yes.
+
+// An id both stores take: dot-separated parts of letters and digits, each starting with a letter, as Apple's take no
+// underscore and Google's no hyphen.
+const STORE_APP_ID = /^[A-Za-z][A-Za-z0-9]*(\.[A-Za-z][A-Za-z0-9]*)+$/;
+
+const REASONS_PAGE = 'https://developer.apple.com/documentation/bundleresources/describing-use-of-required-reason-api';
+// Apple's reasons an app may give, in short; that page has their rules. 0A2A.1 and C56D.1 are for third-party SDKs alone.
+const REASONS = {
+    'DDA9.1': 'to show file timestamps to the user; they stay on the device',
+    'C617.1': "for the timestamps, size or other metadata of files in the app's container, app group container or CloudKit container",
+    '3B52.1': 'for those of files or folders the user granted access to, as with a document picker',
+    '35F9.1': 'to measure the time between events in the app, or for timers; only that time may leave the device',
+    '8FFB.1': "to turn the times of the app's events into absolute timestamps, which may leave the device; the boot time may not",
+    '3D61.1': 'in an optional bug report the user chooses to send, which shows it prominently',
+    '85F4.1': 'to show disk space to the user; it stays on the device',
+    'E174.1': 'to check for space before writing files, or to delete files when space runs low, in a way the user notices; it stays on the device',
+    '7D9E.1': 'in an optional bug report the user chooses to send, which shows it prominently',
+    'B728.1': 'in a health research app, to tell participants that low disk space hampers the research',
+    '3EC4.1': 'in a custom keyboard app, to find the keyboards active on the device',
+    '54BD.1': 'to show the right interface for the active keyboard in text fields, in a way the user notices; it stays on the device',
+    'CA92.1': 'for information only the app itself reads and writes',
+    '1C8F.1': "for information only the apps and extensions of the app's App Group read and write",
+    'AC6B.1': 'for the managed app configuration MDM sets, or the feedback MDM reads',
+};
+
+// Writes app.<key> into crossbind.config.js once the user says yes, and into this run's config. One the config sets
+// already is the user's to change.
+async function writeAppAnswer(key, value) {
+    const text = entry(key, value);
+    if (state.config.app[key] !== undefined) throw new Error(`crossbind: set app.${text} in crossbind.config.js in place of the app.${key} there, and publish again.`);
+    if (!await askYesNo(`Write app.${text} into crossbind.config.js? [Y/n] `)) throw new Error(`crossbind: set app.${text} in crossbind.config.js to publish.`);
+    if (!writeAppOption(state.config.paths.project, key, value)) {
+        throw new Error(`crossbind: crossbind.config.js is no config crossbind can write app.${key} into safely: set app.${text} in it yourself.`);
+    }
+    state.config.app = { ...state.config.app, [key]: value };
+}
+
+// Asks for the app's id, which the store keeps for good, under the name the store gives it.
+export async function askAppId(store, term) {
+    console.log(`crossbind: ${store} knows an app by its ${term}, app.id, and keeps it for good.`);
+    for (;;) {
+        const id = (await askLine(`The ${term}, as com.example.myapp: `)).trim();
+        if (STORE_APP_ID.test(id)) {
+            await writeAppAnswer('id', id);
+            return id;
+        }
+        console.log(`That is no ${term} both stores take, which is dot-separated parts of letters and digits, each starting with a letter.`);
+    }
+}
+
+function iconProblem(icon) {
+    try {
+        readAppIcon({ ...state.config, app: { ...state.config.app, icon } });
+        return null;
+    } catch (error) {
+        return error.message;
+    }
+}
+
+// Asks for the app's icon, without which App Store Connect takes no iOS app.
+export async function askIcon() {
+    console.log('crossbind: App Store Connect takes no iOS app without an icon, app.icon: a square PNG, at best 1024 × 1024.');
+    for (;;) {
+        const icon = (await askLine("Its path, from the project's folder: ")).trim();
+        const problem = iconProblem(icon);
+        if (!problem) {
+            await writeAppAnswer('icon', icon);
+            return;
+        }
+        console.log(problem);
+    }
+}
+
+// Asks whether the app's encryption is iOS's own alone, which App Store Connect otherwise asks for every build. The answer
+// is a legal statement, so there is no default.
+export async function askEncryption() {
+    console.log('crossbind: App Store Connect asks for every build whether the app uses encryption that export rules do not exempt, until app.encryption answers it.');
+    for (;;) {
+        const answer = (await askLine('Does the app use only the encryption iOS provides, as HTTPS through iOS, or none at all? [y/n] ')).trim();
+        if (/^[yn]/i.test(answer)) {
+            await writeAppAnswer('encryption', /^n/i.test(answer));
+            return;
+        }
+        console.log('Answer y or n.');
+    }
+}
+
+async function askReasons(reasons) {
+    for (;;) {
+        const picks = (await askLine('Which apply, as 1 or 1,2? ')).split(',').map((pick) => pick.trim()).filter(Boolean);
+        const chosen = picks.map((pick) => reasons[Number(pick) - 1]);
+        if (chosen.length > 0 && chosen.every(Boolean)) return [...new Set(chosen)];
+        console.log(`Name one or more of 1 to ${reasons.length}, separated by commas.`);
+    }
+}
+
+// Asks for Apple's reasons for each category of required reason API the app calls with none in app.privacy.
+export async function askPrivacy(unreasoned) {
+    console.log(`crossbind: App Store Connect refuses an iOS app that calls required reason API without Apple's reasons for it (ITMS-91053), which app.privacy gives; ${REASONS_PAGE} has the rules of each.`);
+    const privacy = { ...state.config.app.privacy };
+    for (const { category, symbols } of unreasoned) {
+        const reasons = PRIVACY_CATEGORIES[category].reasons.filter((reason) => Object.hasOwn(REASONS, reason));
+        console.log(`The app calls ${category} API (${symbols.join(', ')}). Apple's reasons for it:`);
+        reasons.forEach((reason, index) => console.log(`  ${index + 1}) ${reason} ${REASONS[reason]}`));
+        privacy[category] = await askReasons(reasons);
+    }
+    await writeAppAnswer('privacy', privacy);
+}

package/src/actions/appStoreConnect.js

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import state from '../state/index.js';
+import { APPLE_SIGNING } from './appleSigning.js';
+import { EXEC_MAX_BUFFER } from './run.js';
+import { PRIVACY_CATEGORIES } from '../utils/appOptions.js';
+import { xmlPlist } from '../utils/plist.js';
+
+export const APP_STORE_CONNECT = 'https://appstoreconnect.apple.com/apps';
+const DEVELOPER_ACCOUNT = 'https://developer.apple.com/account';
+// The lines of a failed xcodebuild's output that say why; its log has the rest.
+const REASON_LINES = 15;
+
+// An upload to an app App Store Connect does not have yet, which only its site makes.
+const MISSING_APP = {
+    pattern: /No suitable application records were found|App record with bundle identifier .* not found/i,
+    hint: ({ id }) => `App Store Connect has no app ${id}: create it at ${APP_STORE_CONNECT}, a new iOS app with ${id} as its bundle ID, which this publish registered with Apple.`,
+    page: APP_STORE_CONNECT,
+};
+
+// What a failed archive or upload means where xcodebuild's own words leave it unclear: what the user mends in Xcode or
+// on Apple's sites, and the page where.
+const CAUSES = [
+    {
+        pattern: /login details for account .* were rejected|No Accounts?\b|No Account for Team/i,
+        hint: ({ team }) => `Xcode is signed in to no account of team ${team}, or its sign-in has lapsed: sign in again in Xcode, under Settings › Accounts.`,
+    },
+    {
+        pattern: /PLA Update available|Program License Agreement/i,
+        hint: () => `Apple has a new Program License Agreement, which the team's Account Holder accepts at ${DEVELOPER_ACCOUNT}.`,
+        page: DEVELOPER_ACCOUNT,
+    },
+    {
+        pattern: /Cloud signing permission error/i,
+        hint: () => `the API key may not sign in the cloud, which takes its Admin role: use an Admin key, make an Apple Distribution certificate once in Xcode, under Settings › Accounts › Manage Certificates, or unset ${APPLE_SIGNING.key} to upload with Xcode's account.`,
+    },
+    {
+        pattern: /cannot be registered to your development team because it is not available/i,
+        hint: ({ id }) => `another team registered the bundle id ${id} with Apple first: set app.id in crossbind.config.js to an id of your own, as one under a domain you own.`,
+        // The id is in what was built, so the same step tried again fails the same way.
+        needsRebuild: true,
+    },
+    MISSING_APP,
+];
+
+// Where a publish keeps the archive, its export and their logs.
+const storeDir = () => `${state.config.paths.build}/app-store`;
+
+const keyArgs = (key) => (key ? ['-authenticationKeyPath', key.key, '-authenticationKeyID', key.keyId, '-authenticationKeyIssuerID', key.issuer] : []);
+
+// Runs xcodebuild with its output in `log`, which it returns. Its failure names the lines that say why, and what to do
+// where those leave it unclear.
+export function xcodebuild(what, args, log, facts) {
+    const out = fs.openSync(log, 'w');
+    let result;
+    try {
+        result = spawnSync('xcodebuild', args, { stdio: ['ignore', out, out] });
+    } finally {
+        fs.closeSync(out);
+    }
+    if (result.error) throw new Error(`crossbind: cannot run xcodebuild, which comes with Xcode: ${result.error.message}`, { cause: result.error });
+    if (result.signal) throw new Error(`crossbind: ${what} stopped on ${result.signal}.`);
+    const output = fs.readFileSync(log, 'utf8');
+    if (result.status === 0) return output;
+    const reasons = [...new Set(output.split('\n').map((line) => line.trim()).filter((line) => /\berror\b|ITMS-/i.test(line)))].slice(-REASON_LINES);
+    const cause = CAUSES.find(({ pattern }) => pattern.test(output));
+    const lines = [`crossbind: ${what} failed; xcodebuild's log is ${log}.`, ...reasons.map((line) => `  ${line}`), ...(cause ? [`crossbind: ${cause.hint(facts)}`] : [])];
+    throw Object.assign(new Error(lines.join('\n')), { isMendable: Boolean(cause) && !cause.needsRebuild, page: cause?.page ?? null, reason: cause ?? null });
+}
+
+const archivedApp = (archive) => `${archive}/Products/Applications/${state.config.general.name}.app`;
+
+// The entitlements file the Xcode project names, or null without one.
+function projectEntitlements(project) {
+    const settings = fs.readFileSync(`${project}/${state.config.general.name}.xcodeproj/project.pbxproj`, 'utf8');
+    const file = settings.match(/"?CODE_SIGN_ENTITLEMENTS"?\s*=\s*"?([^";]+)"?;/)?.[1];
+    return file ? path.resolve(project, file.replace('$(SRCROOT)/', '')) : null;
+}
+
+// Signs an archived app ad hoc, its frameworks first, which takes no certificate. The signature carries the app's
+// entitlements to the upload, which an unsigned app would lose, and the upload replaces it with its distribution one.
+function signAdHoc(app, entitlements) {
+    const frameworks = fs.existsSync(`${app}/Frameworks`) ? fs.readdirSync(`${app}/Frameworks`).map((name) => `${app}/Frameworks/${name}`) : [];
+    [...frameworks, app].forEach((code) => {
+        const withEntitlements = code === app && entitlements ? ['--entitlements', entitlements, '--generate-entitlement-der'] : [];
+        const result = spawnSync('codesign', ['--force', '--sign', '-', '--timestamp=none', ...withEntitlements, code], { encoding: 'utf8' });
+        if (result.error || result.status !== 0) {
+            throw new Error(`crossbind: codesign could not sign ${code} ad hoc: ${(result.stderr || result.error?.message || '').trim()}`);
+        }
+    });
+}
+
+// Archives the app of the iOS Xcode project crossbind wrote unsigned, then signs it ad hoc with the entitlements the
+// project names. The upload signs it for distribution, so the archive needs no development certificate, profile, device
+// or Apple account.
+export function archiveIosApp(project, { facts }) {
+    const { name } = state.config.general;
+    const archive = `${storeDir()}/${name}.xcarchive`;
+    fs.rmSync(archive, { recursive: true, force: true });
+    fs.mkdirSync(storeDir(), { recursive: true });
+    xcodebuild('the archive', [
+        'archive', '-project', `${project}/${name}.xcodeproj`, '-scheme', name, '-configuration', 'Release', '-destination', 'generic/platform=iOS',
+        '-archivePath', archive, 'CODE_SIGNING_ALLOWED=NO',
+    ], `${storeDir()}/archive.log`, facts);
+    signAdHoc(archivedApp(archive), projectEntitlements(project));
+    return archive;
+}
+
+export const archivedBinary = (archive) => `${archivedApp(archive)}/${state.config.general.name}`;
+
+// The reasons the archived app's privacy manifest gives, by category: what App Store Connect reads, whatever the config
+// the build read said.
+export function archivedPrivacy(archive) {
+    const manifest = `${archivedApp(archive)}/PrivacyInfo.xcprivacy`;
+    if (!fs.existsSync(manifest)) return {};
+    const result = spawnSync('plutil', ['-convert', 'json', '-o', '-', manifest], { encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(`crossbind: cannot read ${manifest}: ${result.stderr || result.error?.message}`);
+    const names = Object.fromEntries(Object.entries(PRIVACY_CATEGORIES).map(([name, { type }]) => [type, name]));
+    return Object.fromEntries((JSON.parse(result.stdout).NSPrivacyAccessedAPITypes ?? [])
+        .filter(({ NSPrivacyAccessedAPIType: type }) => Object.hasOwn(names, type))
+        .map(({ NSPrivacyAccessedAPIType: type, NSPrivacyAccessedAPITypeReasons: reasons }) => [names[type], reasons]));
+}
+
+// Hermes comes prebuilt, so the archive has no dSYM of it, which App Store Connect asks for.
+export function addHermesDsym(archive, dsym) {
+    fs.cpSync(dsym, `${archive}/dSYMs/hermesvm.framework.dSYM`, { recursive: true });
+}
+
+// The options of an export for App Store Connect: an upload with the app's dSYMs, or an .ipa alone.
+function writeExportOptions(file, { destination, team, isBuildManaged }) {
+    fs.writeFileSync(file, xmlPlist({
+        destination,
+        manageAppVersionAndBuildNumber: isBuildManaged,
+        method: 'app-store-connect',
+        signingStyle: 'automatic',
+        teamID: team,
+        uploadSymbols: destination === 'upload',
+    }));
+    return file;
+}
+
+// Registers the app's bundle id with Apple, as App Store Connect's form for a new app lists registered ids alone. An
+// upload asks for the app record before it signs, so it registers nothing; an export to an .ipa, with no build number
+// to look up, signs at once, which registers the id.
+function registerBundleId(archive, { team, key, facts }) {
+    const options = writeExportOptions(`${storeDir()}/RegisterOptions.plist`, { destination: 'export', team, isBuildManaged: false });
+    xcodebuild('the registration of the bundle id', [
+        '-exportArchive', '-archivePath', archive, '-exportOptionsPlist', options, '-exportPath', `${storeDir()}/register`, '-allowProvisioningUpdates',
+        ...keyArgs(key),
+    ], `${storeDir()}/register.log`, facts);
+}
+
+// Exports the archive for App Store Connect and uploads it with its dSYMs, signed for distribution in the cloud by Xcode's
+// account or an Admin key, else with an Apple Distribution certificate in the keychain, with the entitlements of its ad
+// hoc signature, which the App ID gets the capabilities of. Xcode numbers the build unless CROSSBIND_APP_BUILD_NUMBER
+// did, and writes nothing to -exportPath, which xcodebuild asks for all the same.
+export function uploadIosArchive(archive, { team, key, isBuildManaged, facts }) {
+    const options = writeExportOptions(`${storeDir()}/ExportOptions.plist`, { destination: 'upload', team, isBuildManaged });
+    let output;
+    try {
+        output = xcodebuild('the upload', [
+            '-exportArchive', '-archivePath', archive, '-exportOptionsPlist', options, '-exportPath', `${storeDir()}/export`, '-allowProvisioningUpdates',
+            ...keyArgs(key),
+        ], `${storeDir()}/upload.log`, facts);
+    } catch (error) {
+        if (error.reason === MISSING_APP) {
+            console.log(`crossbind: App Store Connect has no app ${facts.id} yet, so this publish registers its bundle id with Apple first.`);
+            registerBundleId(archive, { team, key, facts });
+        }
+        throw error;
+    }
+    // What App Store Connect warns of, as a dSYM it could not take, goes up with the app all the same.
+    output.split('\n').filter((line) => line.startsWith('warning: exportArchive')).forEach((line) => console.warn(`crossbind: ${line}`));
+}
+
+// The teams of the accounts signed in to Xcode that upload to App Store Connect, which a free personal team does not,
+// from Xcode's settings; `withPersonal` adds those free teams, which sign for their own devices.
+export function xcodeTeams({ withPersonal = false } = {}) {
+    const settings = spawnSync('defaults', ['export', 'com.apple.dt.Xcode', '-'], { maxBuffer: EXEC_MAX_BUFFER });
+    if (settings.status !== 0) return [];
+    const teams = spawnSync('plutil', ['-extract', 'IDEProvisioningTeamByIdentifier', 'json', '-o', '-', '-'], {
+        input: settings.stdout, encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER,
+    });
+    if (teams.status !== 0) return [];
+    const signing = Object.values(JSON.parse(teams.stdout)).flat().filter((team) => withPersonal || !team.isFreeProvisioningTeam);
+    return [...new Map(signing.map((team) => [team.teamID, { id: team.teamID, name: team.teamName }])).values()];
+}