crossbind 2.0.0-beta.67 → 2.0.0-beta.69

package/src/actions/gradleProject.js

@@ -5,6 +5,8 @@ import { ANDROID_API_LEVEL } from '../utils/androidToolchain.js';
 import { HERMES } from '../utils/hermes.js';
 import resolveAppHostRoot from '../utils/resolveAppHost.js';
 import { SIGNING } from './androidGradle.js';
+import { appLinkParts } from '../utils/appLaunches.js';
+import { mergedVerification } from './mavenVerification.js';
 
 // The ABIs an Android app builds for: phones and Apple silicon's emulators, and the emulators of x86_64 machines.
 export const ANDROID_ABIS = ['arm64-v8a', 'x86_64'];
@@ -34,6 +36,14 @@ const backgroundValues = (color) => `<?xml version="1.0" encoding="utf-8"?>
 </resources>
 `;
 
+// The devices of app.permissions, which alone the page may ask for, whatever an extension's Java asks Android for.
+const permissionValues = (permissions) => `<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string-array name="crossbind_permissions">${permissions.map((name) => `\n        <item>${name}</item>`).join('')}
+    </string-array>
+</resources>
+`;
+
 // The Android permissions behind each of app.permissions, after the one every app asks for; the activity asks its user
 // for them when the page first uses the device.
 const INTERNET = '    <uses-permission android:name="android.permission.INTERNET" />';
@@ -42,22 +52,138 @@ const ANDROID_PERMISSIONS = {
     microphone: ['RECORD_AUDIO', 'MODIFY_AUDIO_SETTINGS'],
     location: ['ACCESS_COARSE_LOCATION', 'ACCESS_FINE_LOCATION'],
 };
-const usesPermissions = (permissions) => permissions
-    .flatMap((name) => ANDROID_PERMISSIONS[name])
-    .map((permission) => `    <uses-permission android:name="android.permission.${permission}" />`);
+// The permissions the app asks for beside INTERNET, each once: app.permissions' and its extensions'.
+const usesPermissions = (permissions, extensionPermissions) => [...new Set([
+    ...permissions.flatMap((name) => ANDROID_PERMISSIONS[name]).map((permission) => `android.permission.${permission}`),
+    ...extensionPermissions,
+])].filter((permission) => permission !== 'android.permission.INTERNET')
+    .map((permission) => `    <uses-permission android:name="${permission}" />`);
+
+// What an extension's own manifest adds to the app's: the elements of its manifest, and those of its application, which
+// go inside the app's, whose attributes are the app's alone. The app's manifest declares the android and tools prefixes.
+const APPLICATION_END = '    </application>';
+const PREFIXES = ['android', 'tools'];
 
-// The links of app.urlSchemes the activity opens, from a browser as well, before the end of the activity's element.
+// A manifest's text without its comments, removed until none is left, as removing one may join others into one.
+function withoutComments(text) {
+    let current = text;
+    let previous;
+    do {
+        previous = current;
+        current = current.replace(/<!--[\s\S]*?-->/g, '');
+    } while (current !== previous);
+    return current;
+}
+
+function manifestParts(name, file) {
+    const text = withoutComments(fs.readFileSync(file, 'utf8').replace(/<\?xml[\s\S]*?\?>/, ''));
+    const root = /^\s*<manifest\b([^>]*)>([\s\S]*)<\/manifest>\s*$/.exec(text);
+    if (!root) throw new Error(`crossbind: the extension ${name}'s manifest ${file} is no <manifest> of elements, as an AndroidManifest.xml is.`);
+    const other = [...root[1].matchAll(/xmlns:([\w-]+)/g)].map(([, prefix]) => prefix).find((prefix) => !PREFIXES.includes(prefix));
+    if (other) throw new Error(`crossbind: the extension ${name}'s manifest ${file} declares the prefix ${other}, which the app's has not: it takes android and tools.`);
+    const attribute = [...root[1].matchAll(/([\w:.-]+)\s*=/g)].map(([, key]) => key).find((key) => !key.startsWith('xmlns'));
+    if (attribute) throw new Error(`crossbind: the extension ${name}'s manifest ${file} gives its <manifest> ${attribute}, which is the app's own.`);
+    // The permissions it asks for are those its permissions list, which the app asks for once each.
+    if (/<uses-permission[\s/>]/.test(root[2])) {
+        throw new Error(`crossbind: the extension ${name}'s manifest ${file} asks for a permission with <uses-permission>, which its app.android.permissions lists, as the app asks for each once.`);
+    }
+    const applications = [...root[2].matchAll(/<application\b([^>]*?)(?:\/>|>([\s\S]*?)<\/application>)/g)];
+    if (applications.length > 1) throw new Error(`crossbind: the extension ${name}'s manifest ${file} holds ${applications.length} <application> elements, of which it takes one.`);
+    const [application] = applications;
+    if (application && application[1].trim() !== '') {
+        throw new Error(`crossbind: the extension ${name}'s manifest ${file} gives its <application> attributes, which are the app's own: it holds what the extension adds to the app's alone.`);
+    }
+    return { manifest: application ? root[2].replace(application[0], '') : root[2], application: application?.[2] ?? '' };
+}
+
+// An extension's elements, as the app's manifest holds them, at the indentation of their place there.
+function indented(text, indent) {
+    const lines = text.split('\n').filter((line, index, all) => line.trim() !== '' || (index > all.findIndex((one) => one.trim() !== '')
+        && index < all.findLastIndex((one) => one.trim() !== '')));
+    const margin = Math.min(...lines.filter((line) => line.trim() !== '').map((line) => /^[ \t]*/.exec(line)[0].length));
+    return lines.map((line) => (line.trim() === '' ? '' : `${indent}${line.slice(margin).trimEnd()}`)).join('\n');
+}
+
+// What the activity opens, from a browser or a file manager as well, before the end of the activity's element.
 const ACTIVITY_END = '        </activity>';
-const urlFilter = (schemes) => [
-    '            <intent-filter>',
+const viewFilter = (data, isVerified = false) => [
+    `            <intent-filter${isVerified ? ' android:autoVerify="true"' : ''}>`,
     '                <action android:name="android.intent.action.VIEW" />',
     '                <category android:name="android.intent.category.DEFAULT" />',
     '                <category android:name="android.intent.category.BROWSABLE" />',
-    ...schemes.map((scheme) => `                <data android:scheme="${scheme}" />`),
+    ...data.map((attributes) => `                <data ${attributes} />`),
     '            </intent-filter>',
 ].join('\n');
+// The links of the app's schemes.
+const urlFilter = (schemes) => viewFilter(schemes.map((scheme) => `android:scheme="${scheme}"`));
+// The files of the app's types, which other apps hand it as content: addresses alone, as a file: one would have the app
+// read its own: by their MIME types, as Android matches what a content provider gives, else by their names' extensions,
+// which a provider's path shows or not; .*\\. takes one dot, and Android's pattern a single match.
+const fileFilters = (fileTypes) => fileTypes.map(({ extensions, mimeTypes }) => viewFilter(['android:scheme="content"', ...(mimeTypes.length > 0
+    ? mimeTypes.map((mime) => `android:mimeType="${mime}"`)
+    : ['android:host="*"', 'android:mimeType="*/*"', ...extensions.flatMap((ending) => [`android:pathPattern=".*\\\\.${ending}"`, `android:pathPattern=".*\\\\..*\\\\.${ending}"`])])]));
+// The https links of app.links, which Android verifies against each site's assetlinks.json.
+const linkFilters = (links) => links.map((link) => {
+    const { host, path: prefix } = appLinkParts(link);
+    return viewFilter(['android:scheme="https"', `android:host="${host}"`, ...(prefix ? [`android:pathPrefix="${prefix}"`] : [])], true);
+});
 
-const buildGradle = ({ id, label, version, abis, icon, launchMode, theme }) => `// crossbind writes this project anew on every build: the module comes prebuilt in src/main/jniLibs/, and the app's
+// The app's quick actions, Android's static shortcuts of its icon, which shows the app's icon beside each, or the
+// launcher's own without one: Android empties a static shortcut's task first, so a tap starts the host's trampoline,
+// which hands it to the activity that runs, with its page. Each label is a resource, as Android takes none other.
+const SHORTCUTS_META = '            <meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />';
+const shortcutsXml = (items, id, icon) => `<?xml version="1.0" encoding="utf-8"?>
+<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
+${items.map(({ type }, index) => [
+        `    <shortcut android:shortcutId="${type}"${icon ? ` android:icon="${icon}"` : ''} android:shortcutShortLabel="@string/crossbind_shortcut_${index}">`,
+        `        <intent android:action="dev.crossbind.app.SHORTCUT" android:targetPackage="${id}" android:targetClass="dev.crossbind.app.CrossbindShortcutActivity">`,
+        // Android reads an extra's value of digits, or true or false, as a number or a boolean: after a prefix, each is text.
+        `            <extra android:name="dev.crossbind.app.shortcut" android:value="type:${type}" />`,
+        '        </intent>',
+        '    </shortcut>',
+    ].join('\n')).join('\n')}
+</shortcuts>
+`;
+// Text as a string resource holds it as it is: XML's escapes, and a backslash before what aapt reads otherwise, a quote,
+// an apostrophe, a backslash and an @ or a ? that starts it after any space; formatted="false" keeps a % as it is.
+const androidText = (text) => text.replace(/[\\'"]/g, '\\$&').replace(/^(\s*)([@?])/, '$1\\$2').replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+const shortcutLabels = (items) => `<?xml version="1.0" encoding="utf-8"?>
+<resources>
+${items.map(({ title }, index) => `    <string name="crossbind_shortcut_${index}" formatted="false">${androidText(title)}</string>`).join('\n')}
+</resources>
+`;
+
+// The class of each extension's Java, which the activity calls by the extension's name, in the extensions' order.
+const extensionsJava = (java) => `// crossbind writes this file from the app's extensions: the class of each one's Java, under its name, and the holder of
+// each of the host's roles it holds.
+package dev.crossbind.app;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+final class Extensions {
+    // In the order of the app's extensions, in which each hears what the activity does.
+    static final Map<String, Extension> ALL;
+    // By the role, as page-dialogs, whose requests the activity hands its holder's Java.
+    static final Map<String, Extension> ROLES;
+
+    static {
+        Map<String, Extension> all = new LinkedHashMap<>();${java.map(({ name, className }) => `
+        all.put(${JSON.stringify(name)}, new ${className}());`).join('')}
+        ALL = Collections.unmodifiableMap(all);
+        Map<String, Extension> roles = new HashMap<>();${java.flatMap(({ name, roles = [] }) => roles.map((role) => `
+        roles.put(${JSON.stringify(role)}, all.get(${JSON.stringify(name)}));`)).join('')}
+        ROLES = Collections.unmodifiableMap(roles);
+    }
+
+    private Extensions() {}
+}
+`;
+
+const buildGradle = ({ id, label, version, abis, icon, launchMode, theme, libraries = [] }) => `// crossbind writes this project anew on every build: the module comes prebuilt in src/main/jniLibs/, and the app's
 // files are in src/main/assets/app/.
 plugins {
     id 'com.android.application'
@@ -133,27 +259,66 @@ dependencies {
         }
     }
     implementation 'androidx.webkit:webkit:${ANDROIDX_WEBKIT}'
-}
+${libraries.map((library) => `    implementation '${library}'\n`).join('')}}
 `;
 
 // An Android app as a Gradle project, written anew from the parts its ABI targets built: each brings its libraries,
-// the first also the app's files. Gradle adds Hermes and androidx.webkit from Maven, and makes the APK or the bundle.
-// The icons given are the files of the app's launcher icon under res/; without them it has the system's.
-export default function writeGradleProject(to, { parts, id, label, version, icons = null, urlSchemes = [], background = null, permissions = [] }) {
+// the first also the app's files. Gradle adds Hermes, androidx.webkit and its extensions' libraries from Maven, and makes
+// the APK or the bundle.
+// The icons given are the files of the app's launcher icon under res/; without them it has the system's. Each of java
+// is an extension's folder of Java sources, by package, which the app's sources take beside the activity, and the
+// class in it the activity calls.
+export default function writeGradleProject(to, {
+    parts, id, label, version, icons = null, urlSchemes = [], fileTypes = [], links = [], shortcutItems = [], background = null, permissions = [],
+    java = [], extensionPermissions = [], manifests = [], resources = [], maven = [],
+}) {
     const { name } = state.config.general;
     if (parts.length === 0) throw new Error(`crossbind: no part of the Android app ${name} is built, so there is no Gradle project to write.`);
+    // What the extensions add is read before the project goes, which a manifest crossbind refuses then leaves as it was.
+    const added = manifests.map(({ name: extension, file }) => manifestParts(extension, file));
+    // An app whose extensions ask Maven for libraries checks every file Gradle resolves, which it then resolves online.
+    const verification = maven.length > 0 ? mergedVerification(
+        fs.readFileSync(path.join(resolveAppHostRoot(), 'android-verification-metadata.xml'), 'utf8'),
+        maven.map(({ name: extension, verification: file }) => ({ name: extension, xml: fs.readFileSync(file, 'utf8') })),
+    ) : null;
     fs.rmSync(to, { recursive: true, force: true });
     fs.cpSync(path.join(resolveAppHostRoot(), 'android'), to, { recursive: true });
+    if (verification) fs.writeFileSync(path.join(to, 'gradle', 'verification-metadata.xml'), verification);
     const main = path.join(to, 'app', 'src', 'main');
     const manifest = path.join(main, 'AndroidManifest.xml');
     const text = fs.readFileSync(manifest, 'utf8');
-    if (!text.includes(ACTIVITY_END) || !text.includes(INTERNET)) {
+    if (!text.includes(ACTIVITY_END) || !text.includes(INTERNET) || !text.includes(APPLICATION_END)) {
         throw new Error(`crossbind: ${manifest}, from the app host, has no activity or permissions to give app.urlSchemes and app.permissions: update @crossbind/core-app-host to match crossbind.`);
     }
+    const own = (key, indent) => added.map((part) => part[key]).filter((part) => part.trim() !== '').map((part) => indented(part, indent));
+    // A replacer, as the extensions' text may hold what a replacement string reads as a pattern, as $&.
     fs.writeFileSync(manifest, text
-        .replace(INTERNET, [INTERNET, ...usesPermissions(permissions)].join('\n'))
-        .replace(ACTIVITY_END, urlSchemes.length > 0 ? `${urlFilter(urlSchemes)}\n${ACTIVITY_END}` : ACTIVITY_END));
+        .replace(INTERNET, () => [INTERNET, ...usesPermissions(permissions, extensionPermissions), ...own('manifest', '    ')].join('\n'))
+        .replace(ACTIVITY_END, () => [
+            ...(urlSchemes.length > 0 ? [urlFilter(urlSchemes)] : []), ...fileFilters(fileTypes), ...linkFilters(links),
+            ...(shortcutItems.length > 0 ? [SHORTCUTS_META] : []), ACTIVITY_END,
+        ].join('\n'))
+        .replace(APPLICATION_END, () => [...own('application', '        '), APPLICATION_END].join('\n')));
+    fs.writeFileSync(path.join(main, 'java', 'dev', 'crossbind', 'app', 'Extensions.java'), extensionsJava(java));
+    // The Java and Kotlin sources of an extension's folder alone, which may hold its manifest and resources as well: the
+    // Android Gradle plugin compiles Kotlin beside the Java.
+    java.forEach(({ name: extension, dir }) => {
+        const sources = path.join(main, 'java');
+        const files = fs.readdirSync(dir, { recursive: true }).filter((file) => /\.(java|kt)$/.test(file) && fs.statSync(path.join(dir, file), { throwIfNoEntry: false })?.isFile());
+        files.forEach((file) => {
+            if (fs.existsSync(path.join(sources, file))) {
+                throw new Error(`crossbind: the extension ${extension} has ${file} in its Java, which the app's Gradle project has already.`);
+            }
+        });
+        files.forEach((file) => {
+            fs.mkdirSync(path.dirname(path.join(sources, file)), { recursive: true });
+            fs.copyFileSync(path.join(dir, file), path.join(sources, file));
+        });
+    });
     parts.forEach(({ arch, dir }) => fs.cpSync(path.join(dir, 'lib'), path.join(main, 'jniLibs', arch), { recursive: true }));
+    // A release keeps its libraries as linked beside the stripped ones it ships, for Google Play's crash reports.
+    parts.filter(({ dir }) => fs.existsSync(path.join(dir, 'symbols')))
+        .forEach(({ arch, dir }) => fs.cpSync(path.join(dir, 'symbols'), path.join(to, 'symbols', arch), { recursive: true }));
     fs.cpSync(path.join(parts[0].dir, 'app'), path.join(main, 'assets', 'app'), { recursive: true });
     if (icons) {
         Object.entries({ ...icons, 'mipmap-anydpi/ic_launcher.xml': ADAPTIVE_ICON }).forEach(([file, content]) => {
@@ -163,9 +328,27 @@ export default function writeGradleProject(to, { parts, id, label, version, icon
     }
     fs.mkdirSync(path.join(main, 'res', 'values'), { recursive: true });
     fs.writeFileSync(path.join(main, 'res', 'values', 'background.xml'), backgroundValues(background));
+    fs.writeFileSync(path.join(main, 'res', 'values', 'permissions.xml'), permissionValues(permissions));
+    if (shortcutItems.length > 0) {
+        fs.mkdirSync(path.join(main, 'res', 'xml'), { recursive: true });
+        fs.writeFileSync(path.join(main, 'res', 'xml', 'shortcuts.xml'), shortcutsXml(shortcutItems, id, icons ? '@mipmap/ic_launcher' : null));
+        fs.writeFileSync(path.join(main, 'res', 'values', 'shortcuts.xml'), shortcutLabels(shortcutItems));
+    }
+    // An extension's resources join the app's, of which they replace none.
+    resources.forEach(({ name: extension, dir }) => {
+        fs.readdirSync(dir, { recursive: true }).forEach((file) => {
+            const into = path.join(main, 'res', file);
+            if (fs.existsSync(into) && !fs.statSync(into).isDirectory()) {
+                throw new Error(`crossbind: the extension ${extension} has ${file} in its resources, which the app's Gradle project has already.`);
+            }
+        });
+        fs.cpSync(dir, path.join(main, 'res'), { recursive: true });
+    });
     fs.writeFileSync(path.join(to, 'app', 'build.gradle'), buildGradle({
         id, label, version, abis: parts.map(({ arch }) => arch), icon: icons ? '@mipmap/ic_launcher' : '@android:drawable/sym_def_app_icon',
-        launchMode: urlSchemes.length > 0 ? 'singleTask' : 'standard', theme: background ? '@style/CrossbindBackground' : DAY_NIGHT,
+        launchMode: urlSchemes.length + fileTypes.length + links.length + shortcutItems.length > 0 ? 'singleTask' : 'standard',
+        theme: background ? '@style/CrossbindBackground' : DAY_NIGHT,
+        libraries: [...new Set(maven.flatMap(({ coordinates }) => coordinates))],
     }));
     return to;
 }

package/src/actions/iosDevice.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
+import { EXEC_MAX_BUFFER } from './run.js';
+import { appTeam } from './buildApp.js';
+import { xcodebuild, xcodeTeams } from './xcodebuild.js';
+import state from '../state/index.js';
+import { appId } from '../utils/appOptions.js';
+
+// How much of what devicectl says as it launches the app is read for a failure; the app's own output follows it.
+const SAID_LIMIT = 64 * 1024;
+const LAUNCHED = /Launched application with/;
+// Addresses of this Mac that no device reaches.
+const LOOPBACK = ['localhost', '127.0.0.1', '::1'];
+// Vite's --host for every address of this Mac.
+const EVERY_ADDRESS = [true, '0.0.0.0', '::'];
+
+const developerModeFix = (name) => `Developer Mode is off on ${name}: turn it on in Settings › Privacy & Security › Developer Mode, which restarts ${name}, and run again.`;
+
+// What a failed install or launch on the device means, in devicectl's words, and what the developer does about it.
+const FIXES = [
+    { pattern: /device was still locked|device is currently locked/i, fix: ({ name }) => `unlock ${name}, and run again.` },
+    { pattern: /developer mode is not enabled/i, fix: ({ name }) => developerModeFix(name) },
+    {
+        pattern: /0xe8008012|provisioning profile cannot be installed on this device/i,
+        fix: ({ name }) => `the app's profile leaves ${name} out, which Xcode registers with the team as it builds for it: run again, and if it stays out, run the app on ${name} from Xcode once.`,
+    },
+    {
+        pattern: /not been explicitly trusted by the user/i,
+        fix: ({ name }) => `${name} does not trust the app's developer yet, as with a free team's first app: on ${name}, open Settings › General › VPN & Device Management, trust the Apple Development entry, and run again.`,
+    },
+];
+
+function tool(program, args, options = {}) {
+    const result = spawnSync(program, args, { encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER, ...options });
+    if (result.status !== 0) {
+        throw new Error(`crossbind: ${program} ${args.join(' ')} failed: ${`${result.stdout ?? ''}${result.stderr ?? ''}`.trim() || result.error?.message}`);
+    }
+    return result.stdout;
+}
+
+// devicectl's output, or its failure with what it said and, where known, what to do on `device`.
+function devicectl(args, device = null) {
+    const result = spawnSync('xcrun', ['devicectl', ...args], { encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER });
+    if (result.status === 0) return result.stdout;
+    const said = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() || result.error?.message;
+    const fix = device && FIXES.find(({ pattern }) => pattern.test(said));
+    throw new Error([`crossbind: devicectl ${args.join(' ')} failed: ${said}`, ...(fix ? [`crossbind: ${fix.fix(device)}`] : [])].join('\n'));
+}
+
+// The iPhones and iPads this Mac reaches, on a cable or over the network; devicectl lists the Simulators too.
+function physicalDevices() {
+    return JSON.parse(devicectl(['list', 'devices', '--json-output', '-'])).result.devices
+        .filter(({ hardwareProperties: hardware, connectionProperties: connection }) => hardware?.reality === 'physical'
+            && hardware.platform === 'iOS' && connection?.transportType)
+        .map(({ deviceProperties: properties, hardwareProperties: hardware, connectionProperties: connection }) => ({
+            name: properties?.name ?? hardware.udid,
+            udid: hardware.udid,
+            isWired: connection.transportType === 'wired',
+            isPaired: connection.pairingState === 'paired',
+            developerMode: properties?.developerModeStatus,
+        }));
+}
+
+// iOS names a device with ’, as Ada’s iPhone, where a terminal types '.
+const plainName = (name) => name.replaceAll('’', "'");
+
+function pick(devices, choice) {
+    const found = choice ? devices.filter(({ name, udid }) => plainName(name) === plainName(choice) || udid === choice) : devices;
+    if (found.length === 1) return found[0];
+    if (found.length > 1) {
+        const names = found.map(({ name }) => name);
+        // A name two devices share names neither; a UDID is one device's.
+        const example = new Set(names).size === names.length ? `"${found.at(-1).name}"` : found.at(-1).udid;
+        throw new Error(`crossbind: ${found.length} iPhones and iPads are connected (${names.join(', ')}): name one, as --device ${example}.`);
+    }
+    throw new Error(choice
+        ? `crossbind: no iPhone or iPad named ${choice} is connected; connected: ${devices.map(({ name }) => name).join(', ') || 'none'}.`
+        : 'crossbind: no iPhone or iPad is connected. Connect one with a cable, unlock it, and tap Trust on it if it asks.');
+}
+
+// The iPhone or iPad an app runs on in development: the one `choice` names, by its name or UDID, else the only one
+// connected. It gets paired with this Mac, which the phone's Trust allows, and runs development apps once its Developer
+// Mode is on.
+export function connectedIosDevice(choice) {
+    let device = pick(physicalDevices(), choice);
+    if (!device.isPaired) {
+        console.log(`crossbind: tap Trust on ${device.name}, then enter its passcode, to pair it with this Mac.`);
+        devicectl(['manage', 'pair', '--device', device.udid], device);
+        device = pick(physicalDevices(), device.udid);
+    }
+    // A device just paired may not say yet; its install then names the fix, if it needs one.
+    if (device.developerMode === 'disabled') throw new Error(`crossbind: ${developerModeFix(device.name)}`);
+    return { name: device.name, udid: device.udid, isWired: device.isWired };
+}
+
+// What `crossbind app dev --device` hands Vite as CROSSBIND_APP_DEVICE: the device it names, else the UDID of the only
+// one connected.
+export function iosDeviceOption(choice, platform) {
+    if (platform !== 'ios') {
+        throw new Error('crossbind: --device opens an iOS app on an iPhone or iPad: add -p ios. An Android app opens on the attached device already, which ANDROID_SERIAL picks among several.');
+    }
+    return choice === true || choice === '' ? connectedIosDevice().udid : choice;
+}
+
+// The network interfaces the device's USB connection makes on this Mac, which ioreg holds under the USB device whose
+// serial number is the device's UDID without its dash. plutil turns no binary, date or non-finite value into JSON,
+// which ioreg's tree holds and the lookup needs none of.
+function cableInterfaces({ name, udid }) {
+    const tree = spawnSync('ioreg', ['-a', '-r', '-c', 'IOUSBHostDevice', '-l'], { encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER }).stdout;
+    if (!tree) return [];
+    const input = tree.replace(/<(data|date|real)>[^<]*<\/\1>/g, '<string></string>');
+    const json = spawnSync('plutil', ['-convert', 'json', '-o', '-', '-'], { input, encoding: 'utf8', maxBuffer: EXEC_MAX_BUFFER });
+    if (json.status !== 0) {
+        throw new Error(`crossbind: cannot read the USB devices ioreg lists, among them the cable to ${name}: ${(json.stderr ?? '').trim() || json.error?.message}`);
+    }
+    const serial = udid.replaceAll('-', '');
+    const nodes = (node) => [node, ...(node.IORegistryEntryChildren ?? []).flatMap(nodes)];
+    const usb = [JSON.parse(json.stdout)].flat().flatMap(nodes).find((node) => node['USB Serial Number'] === serial);
+    return usb ? nodes(usb).map((node) => node['BSD Name']).filter(Boolean) : [];
+}
+
+function defaultRouteInterface() {
+    return spawnSync('route', ['-n', 'get', 'default'], { encoding: 'utf8' }).stdout?.match(/interface:\s*(\S+)/)?.[1];
+}
+
+// The address of this Mac that the device reaches the dev server at: on the device's own cable, which needs no network,
+// else on the default route's network, which the device must share. A .local name or the CoreDevice tunnel reaches
+// nothing from the app.
+export function iosDeviceAddress(device) {
+    const route = device.isWired ? null : defaultRouteInterface();
+    if (/^(utun|ipsec|ppp)/.test(route ?? '')) {
+        throw new Error(`crossbind: this Mac's default route goes through ${route}, a VPN, which ${device.name} cannot reach: give this Mac's address on the phone's network with --host <address>, or connect the phone with a cable.`);
+    }
+    const interfaces = device.isWired ? cableInterfaces(device) : [route].filter(Boolean);
+    const address = interfaces.map((name) => os.networkInterfaces()[name]?.find(({ family }) => family === 'IPv4')?.address).find(Boolean);
+    if (address) return address;
+    throw new Error(device.isWired
+        ? `crossbind: this Mac has no address on the cable to ${device.name} yet: plug it in again, or give the address the phone reaches this Mac at with --host <address>.`
+        : `crossbind: this Mac has no network address ${device.name} could reach it at: join the network the phone is on, or give an address with --host <address>.`);
+}
+
+// Where the dev server is for the device: the address Vite's own --host names, else the one this Mac has for the
+// device, and the host Vite listens on, that one address unless --host asks for every one.
+export function iosDevServer(device, requested) {
+    if (LOOPBACK.includes(requested)) {
+        throw new Error(`crossbind: ${device.name} cannot reach this Mac at ${requested}: give --host an address the phone reaches, or leave --host out.`);
+    }
+    if (EVERY_ADDRESS.includes(requested)) return { address: iosDeviceAddress(device), host: requested };
+    const address = typeof requested === 'string' ? requested : iosDeviceAddress(device);
+    return { address, host: address };
+}
+
+function noTeam() {
+    const teams = xcodeTeams({ withPersonal: true }).map(({ id, name }) => `${id} (${name})`);
+    const which = teams.length > 0
+        ? `one of the teams Xcode is signed in to: ${teams.join(', ')}`
+        : 'the team of an account you sign in to in Xcode, under Settings › Accounts; a free Apple Account has a Personal Team';
+    return `crossbind: an app on an iPhone or iPad is signed for an Apple team: set app.team in crossbind.config.js, or XCODE_DEVELOPMENT_TEAM in ~/.crossbind.json, to ${which}.`;
+}
+
+// Builds an iOS app's Xcode project for the device, signed for the app's team by Xcode, which registers the device and
+// the bundle id with the team and makes the profile as it needs, and returns the app. xcodebuild takes a destination
+// only with a scheme, which Xcode makes of the project's target.
+export function buildForIosDevice(project, device) {
+    const { name } = state.config.general;
+    const team = appTeam();
+    if (!team) throw new Error(noTeam());
+    const products = `${state.config.paths.build}/xcode`;
+    fs.mkdirSync(products, { recursive: true });
+    xcodebuild(`the build for ${device.name}`, [
+        '-project', `${project}/${name}.xcodeproj`, '-scheme', name, '-configuration', 'Debug', '-sdk', 'iphoneos', '-destination', `id=${device.udid}`,
+        '-allowProvisioningUpdates', '-allowProvisioningDeviceRegistration', `SYMROOT=${products}`, 'build',
+    ], { log: `${products}/device.log`, facts: { team, id: appId(state.config) } });
+    return `${products}/Debug-iphoneos/${name}.app`;
+}
+
+// Installs an iOS app on the device and opens it with `env` in its environment. The process returned is devicectl,
+// which xcrun runs in its own place: it carries the app's output and ends with the app, and a signal to it ends the app
+// too. A launch the phone refuses, as one that waits for the developer's trust, names its fix.
+export default function openOnIosDevice(app, { env = {}, stdio = 'pipe', device } = {}) {
+    devicectl(['device', 'install', 'app', '--device', device.udid, app], device);
+    const bundleId = tool('plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', `${app}/Info.plist`]).trim();
+    const [input, output, errors] = typeof stdio === 'string' ? [stdio, stdio, stdio] : stdio;
+    const child = spawn('xcrun', [
+        'devicectl', 'device', 'process', 'launch', '--device', device.udid, '--console', '--terminate-existing',
+        '--environment-variables', JSON.stringify(env), bundleId,
+    ], { stdio: [input, output, 'pipe'] });
+    child.stderr.setEncoding('utf8');
+    let said = '';
+    child.stderr.on('data', (text) => {
+        if (errors === 'inherit') process.stderr.write(text);
+        if (said === null) return;
+        said += text;
+        const fix = FIXES.find(({ pattern }) => pattern.test(said));
+        if (fix) process.stderr.write(`crossbind: ${fix.fix(device)}\n`);
+        if (fix || LAUNCHED.test(said) || said.length > SAID_LIMIT) said = null;
+    });
+    return { child, close: () => child.kill() };
+}

package/src/actions/iosSimulator.js

@@ -43,8 +43,8 @@ export function buildForSimulator(project, configuration = 'Release') {
     return `${products}/${configuration}-iphonesimulator/${name}.app`;
 }
 
-// Opens a Simulator build of an iOS app, with `env` in its environment. The process returned carries the app's output
-// and ends with the app; close() ends the app.
+// Opens a Simulator build of an iOS app, with `env` in its environment, in the Simulator of the device returned. The
+// process returned carries the app's output and ends with the app; close() ends the app.
 export default function openInSimulator(app, { env = {}, show = false, stdio = 'pipe' } = {}) {
     const device = simulator();
     // Simulator.app only shows the device, which runs the app without it as well.
@@ -59,5 +59,5 @@ export default function openInSimulator(app, { env = {}, show = false, stdio = '
         childEnv[`SIMCTL_CHILD_${key}`] = value;
     });
     const child = spawn('xcrun', ['simctl', 'launch', '--console-pty', '--terminate-running-process', device, bundleId], { env: childEnv, stdio });
-    return { child, close: () => spawnSync('xcrun', ['simctl', 'terminate', device, bundleId]) };
+    return { child, device, close: () => spawnSync('xcrun', ['simctl', 'terminate', device, bundleId]) };
 }