crossbind 2.0.0-beta.68 → 2.0.0-beta.69

package/src/actions/xcodeProject.js

@@ -3,13 +3,15 @@ import { spawnSync } from 'node:child_process';
 import state from '../state/index.js';
 import { IOS_DEPLOYMENT_TARGET } from '../utils/iosToolchain.js';
 import { textPlist, xmlPlist } from '../utils/plist.js';
-import { PRIVACY_CATEGORIES } from '../utils/appOptions.js';
+import { mergedPlist } from '../utils/appExtensions.js';
+import { appLinkParts, iosDocumentTypes, iosShortcutItems } from '../utils/appLaunches.js';
+import { privacyManifest, writeTargets } from './xcodeTargets.js';
 
 // The SDKs an iOS app builds for, one target each, and the slice of Hermes' release each takes.
 export const IOS_SDKS = ['iphoneos', 'iphonesimulator'];
 export const HERMES_SLICES = { iphoneos: 'ios-arm64', iphonesimulator: 'ios-arm64_x86_64-simulator' };
 // What the host's own code needs from the system: Xcode adds it only for the sources it compiles itself.
-const SYSTEM_LIBS = ['-framework', 'UIKit', '-framework', 'WebKit', '-framework', 'CoreGraphics', '-lc++'];
+const SYSTEM_LIBS = ['-framework', 'UIKit', '-framework', 'WebKit', '-framework', 'CoreGraphics', '-framework', 'Security', '-framework', 'UserNotifications', '-lc++'];
 
 const MAIN = `// crossbind writes this project anew on every build: the app comes prebuilt in lib/, and its files are in app/.
 int crossbind_app_main(int argc, char *argv[]);
@@ -19,7 +21,7 @@ int main(int argc, char *argv[]) { return crossbind_app_main(argc, argv); }
 
 const OBJECT_NAMES = ['project', 'mainGroup', 'products', 'target', 'product', 'main', 'info', 'app', 'hermes', 'mainBuild',
     'appBuild', 'hermesLink', 'hermesEmbed', 'sources', 'frameworks', 'resources', 'embed', 'projectDebug', 'projectRelease',
-    'targetDebug', 'targetRelease', 'projectConfigs', 'targetConfigs', 'assets', 'assetsBuild', 'privacy', 'privacyBuild'];
+    'targetDebug', 'targetRelease', 'projectConfigs', 'targetConfigs', 'assets', 'assetsBuild', 'privacy', 'privacyBuild', 'embedTargets'];
 // Xcode names its objects by 24 hex digits. Fixed ones leave the project unchanged while what it holds is.
 const ID = Object.fromEntries(OBJECT_NAMES.map((name, index) => [name, `CB${(index + 1).toString(16).toUpperCase().padStart(22, '0')}`]));
 
@@ -40,7 +42,14 @@ const ORIENTATIONS = ['UIInterfaceOrientationPortrait', 'UIInterfaceOrientationL
 // The color set of app.window.backgroundColor, which the launch screen shows.
 const LAUNCH_COLOR = 'LaunchBackground';
 
-const infoPlist = (name, urlSchemes, hasBackground, usage, encryption) => xmlPlist({
+// The entitlement of the domains whose sites' links iOS hands the app, once each site's apple-app-site-association names
+// it, and the one of the App Groups it shares with the targets of its extensions'.
+const ASSOCIATED_DOMAINS = 'com.apple.developer.associated-domains';
+const APP_GROUPS = 'com.apple.security.application-groups';
+
+// The app's Info.plist, with the keys its extensions give, and the App Group its native code reads where the targets of
+// its extensions' share one.
+const infoPlist = (name, urlSchemes, fileTypes, activityTypes, shortcutItems, hasBackground, usage, encryption, multipleWindows, appGroup, plist) => xmlPlist(mergedPlist({
     CFBundleDevelopmentRegion: 'en',
     CFBundleDisplayName: name,
     CFBundleExecutable: '$(EXECUTABLE_NAME)',
@@ -53,15 +62,20 @@ const infoPlist = (name, urlSchemes, hasBackground, usage, encryption) => xmlPli
     CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
     ...(encryption === null ? {} : { ITSAppUsesNonExemptEncryption: encryption }),
     LSRequiresIPhoneOS: true,
-    UIApplicationSceneManifest: { UIApplicationSupportsMultipleScenes: false },
+    UIApplicationSceneManifest: { UIApplicationSupportsMultipleScenes: multipleWindows },
     UILaunchScreen: hasBackground ? { UIColorName: LAUNCH_COLOR } : {},
     UISupportedInterfaceOrientations: ORIENTATIONS,
     'UISupportedInterfaceOrientations~ipad': [...ORIENTATIONS, 'UIInterfaceOrientationPortraitUpsideDown'],
+    ...iosDocumentTypes(fileTypes, '$(PRODUCT_BUNDLE_IDENTIFIER)'),
+    ...(activityTypes.length > 0 ? { NSUserActivityTypes: activityTypes } : {}),
+    ...(shortcutItems.length > 0 ? { UIApplicationShortcutItems: iosShortcutItems(shortcutItems) } : {}),
     // The reasons of app.permissions, without which iOS lets the app use none of those devices.
     ...usage,
-});
+    ...(appGroup ? { CrossbindAppGroup: appGroup } : {}),
+}, plist));
 
-function objects(name, targetSettings, hasAssets, hasPrivacy) {
+// The project's objects: the app's target, and the targets its extensions add, which the app depends on and embeds.
+function objects(name, targetSettings, hasAssets, hasPrivacy, added) {
     const file = (path, type) => ({ isa: 'PBXFileReference', lastKnownFileType: type, path, sourceTree: '<group>' });
     const phase = (isa, files, extra = {}) => ({ isa, buildActionMask: 2147483647, files, runOnlyForDeploymentPostprocessing: 0, ...extra });
     const configuration = (configurationName, buildSettings) => ({ isa: 'XCBuildConfiguration', buildSettings, name: configurationName });
@@ -77,9 +91,11 @@ function objects(name, targetSettings, hasAssets, hasPrivacy) {
         [ID.privacy]: file('PrivacyInfo.xcprivacy', 'text.xml'),
         [ID.privacyBuild]: { isa: 'PBXBuildFile', fileRef: ID.privacy },
     } : {};
+    const hasTargets = added.targets.length > 0;
     return {
         ...assets,
         ...privacy,
+        ...added.objects,
         [ID.main]: file('main.m', 'sourcecode.c.objc'),
         [ID.info]: file('Info.plist', 'text.plist.xml'),
         [ID.app]: file('app', 'folder'),
@@ -95,18 +111,19 @@ function objects(name, targetSettings, hasAssets, hasPrivacy) {
         [ID.frameworks]: phase('PBXFrameworksBuildPhase', [ID.hermesLink]),
         [ID.resources]: phase('PBXResourcesBuildPhase', [ID.appBuild, ...(hasAssets ? [ID.assetsBuild] : []), ...(hasPrivacy ? [ID.privacyBuild] : [])]),
         [ID.embed]: phase('PBXCopyFilesBuildPhase', [ID.hermesEmbed], { dstPath: '', dstSubfolderSpec: 10, name: 'Embed Frameworks' }),
+        ...(hasTargets ? { [ID.embedTargets]: phase('PBXCopyFilesBuildPhase', added.embedded, { dstPath: '', dstSubfolderSpec: 13, name: 'Embed Foundation Extensions' }) } : {}),
         [ID.mainGroup]: {
             isa: 'PBXGroup',
-            children: [ID.main, ID.info, ID.app, ...(hasAssets ? [ID.assets] : []), ...(hasPrivacy ? [ID.privacy] : []), ID.hermes, ID.products],
+            children: [ID.main, ID.info, ID.app, ...(hasAssets ? [ID.assets] : []), ...(hasPrivacy ? [ID.privacy] : []), ID.hermes, ...added.groups, ID.products],
             sourceTree: '<group>',
         },
-        [ID.products]: { isa: 'PBXGroup', children: [ID.product], name: 'Products', sourceTree: '<group>' },
+        [ID.products]: { isa: 'PBXGroup', children: [ID.product, ...added.products], name: 'Products', sourceTree: '<group>' },
         [ID.target]: {
             isa: 'PBXNativeTarget',
             buildConfigurationList: ID.targetConfigs,
-            buildPhases: [ID.sources, ID.frameworks, ID.resources, ID.embed],
+            buildPhases: [ID.sources, ID.frameworks, ID.resources, ID.embed, ...(hasTargets ? [ID.embedTargets] : [])],
             buildRules: [],
-            dependencies: [],
+            dependencies: added.dependencies,
             name,
             productName: name,
             productReference: ID.product,
@@ -123,7 +140,7 @@ function objects(name, targetSettings, hasAssets, hasPrivacy) {
             productRefGroup: ID.products,
             projectDirPath: '',
             projectRoot: '',
-            targets: [ID.target],
+            targets: [ID.target, ...added.targets],
         },
         [ID.projectDebug]: configuration('Debug', PROJECT_SETTINGS),
         [ID.projectRelease]: configuration('Release', PROJECT_SETTINGS),
@@ -152,22 +169,26 @@ function writeAssets(catalog, icon, background) {
     }
 }
 
-// The privacy manifest of app.privacy, without which App Store Connect refuses an app that calls required reason API.
-const privacyManifest = (privacy) => xmlPlist({
-    NSPrivacyAccessedAPITypes: Object.entries(privacy).map(([name, reasons]) => ({
-        NSPrivacyAccessedAPIType: PRIVACY_CATEGORIES[name].type,
-        NSPrivacyAccessedAPITypeReasons: reasons,
-    })),
-});
-
 // An iOS app as an Xcode project, written anew from the parts its SDK targets built: each brings its archives and
 // their link line, and its slice of Hermes; the first also the app's files. Xcode signs the app and runs it, in the
-// Simulator or on a device, and makes every size of its icon from the one PNG given.
+// Simulator or on a device, with the entitlements given, and makes every size of its icon from the one PNG given. The
+// targets of Apple's app extensions its extensions add build with it, the App Group in the app's entitlements as well
+// where one of them asks for it.
 export default function writeXcodeProject(to, {
-    parts, identity, label, version, build = version, icon = null, urlSchemes = [], background = null, usage = {}, encryption = null, privacy = {},
+    parts, identity, label, version, build = version, icon = null, urlSchemes = [], fileTypes = [], links = [], activityTypes = [], shortcutItems = [],
+    background = null, usage = {}, encryption = null, multipleWindows = false, privacy = {}, entitlements = {}, plist = [], targets = [], appGroup = null,
 }) {
     const { name } = state.config.general;
     if (parts.length === 0) throw new Error(`crossbind: no part of the iOS app ${name} is built, so there is no Xcode project to write.`);
+    // Xcode keeps what it builds of each target by the target's name, which a Mac's file system takes in either case.
+    const named = targets.find((target) => target.name.toLowerCase() === name.toLowerCase());
+    if (named) throw new Error(`crossbind: the extension ${named.owner} names an iOS target ${named.name}, as the app itself is named: Xcode builds no two targets of one name.`);
+    // The extensions' keys merge before the project goes, which a conflict between them then leaves as it was.
+    const group = appGroup && targets.some((target) => target.appGroup) ? appGroup : null;
+    const info = infoPlist(label, urlSchemes, fileTypes, activityTypes, shortcutItems, Boolean(background), usage, encryption, multipleWindows, group, plist);
+    const domains = links.map((link) => `applinks:${appLinkParts(link).host}`);
+    const joinedTo = (given, key, values) => (values.length > 0 ? { ...given, [key]: [...new Set([...(given[key] ?? []), ...values])] } : given);
+    const signed = joinedTo(joinedTo(entitlements, ASSOCIATED_DOMAINS, domains), APP_GROUPS, group ? [group] : []);
     fs.rmSync(to, { recursive: true, force: true });
     fs.mkdirSync(`${to}/${name}.xcodeproj`, { recursive: true });
     const linkFlags = {};
@@ -184,24 +205,28 @@ export default function writeXcodeProject(to, {
     if (result.status !== 0) throw new Error(`crossbind: cannot make Hermes' xcframework for ${to}: ${result.stderr || result.error?.message}`);
 
     fs.writeFileSync(`${to}/main.m`, MAIN);
-    fs.writeFileSync(`${to}/Info.plist`, infoPlist(label, urlSchemes, Boolean(background), usage, encryption));
+    fs.writeFileSync(`${to}/Info.plist`, info);
     writeAssets(`${to}/Assets.xcassets`, icon, background);
     const hasPrivacy = Object.keys(privacy).length > 0;
     if (hasPrivacy) fs.writeFileSync(`${to}/PrivacyInfo.xcprivacy`, privacyManifest(privacy));
+    const hasEntitlements = Object.keys(signed).length > 0;
+    if (hasEntitlements) fs.writeFileSync(`${to}/${name}.entitlements`, xmlPlist(signed));
     const targetSettings = {
         ...(icon ? { ASSETCATALOG_COMPILER_APPICON_NAME: 'AppIcon' } : {}),
         PRODUCT_NAME: name,
         PRODUCT_BUNDLE_IDENTIFIER: identity.id,
         DEVELOPMENT_TEAM: identity.team,
         CODE_SIGN_STYLE: 'Automatic',
+        ...(hasEntitlements ? { CODE_SIGN_ENTITLEMENTS: `${name}.entitlements` } : {}),
         INFOPLIST_FILE: 'Info.plist',
         MARKETING_VERSION: version,
         CURRENT_PROJECT_VERSION: build,
         LD_RUNPATH_SEARCH_PATHS: ['$(inherited)', '@executable_path/Frameworks'],
         ...linkFlags,
     };
+    const added = writeTargets(to, targets, { project: ID.project, identity, label, version, build, appGroup });
     fs.writeFileSync(`${to}/${name}.xcodeproj/project.pbxproj`, textPlist({
-        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings, Boolean(icon || background), hasPrivacy), rootObject: ID.project,
+        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings, Boolean(icon || background), hasPrivacy, added), rootObject: ID.project,
     }));
     return to;
 }

package/src/actions/xcodeTargets.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { xmlPlist } from '../utils/plist.js';
+import { PRIVACY_CATEGORIES } from '../utils/appOptions.js';
+import { isHeader, targetFrameworks, targetModule, targetPlist, widgetsWithoutBackground } from '../utils/appTargets.js';
+
+const APP_GROUPS = 'com.apple.security.application-groups';
+// The kind of each file Xcode compiles or copies into a target, by its ending: a folder is copied as it is, and an asset
+// catalog compiled.
+const FILE_TYPES = {
+    '.swift': 'sourcecode.swift', '.m': 'sourcecode.c.objc', '.mm': 'sourcecode.cpp.objcpp', '.c': 'sourcecode.c.c', '.cpp': 'sourcecode.cpp.cpp',
+    '.cc': 'sourcecode.cpp.cpp', '.cxx': 'sourcecode.cpp.cpp', '.h': 'sourcecode.c.h', '.hpp': 'sourcecode.cpp.h', '.xcassets': 'folder.assetcatalog',
+    '.storyboard': 'file.storyboard', '.xib': 'file.xib', '.strings': 'text.plist.strings', '.xcstrings': 'text.json.xcstrings', '.png': 'image.png',
+    '.json': 'text.json',
+};
+
+// The privacy manifest of these reasons for Apple's required reason API, which App Store Connect asks of each bundle that
+// calls one.
+export const privacyManifest = (privacy) => xmlPlist({
+    NSPrivacyAccessedAPITypes: Object.entries(privacy).map(([name, reasons]) => ({
+        NSPrivacyAccessedAPIType: PRIVACY_CATEGORIES[name].type,
+        NSPrivacyAccessedAPITypeReasons: reasons,
+    })),
+});
+
+// Xcode names its objects by 24 hex digits: each target's go by its place among them, apart from the app's own.
+const idOf = (target, index) => `CE${target.toString(16).toUpperCase().padStart(4, '0')}${index.toString(16).toUpperCase().padStart(18, '0')}`;
+
+// Writes a target's folder beside the app's project, targets/<name>/: its sources and resources in files/, where they are
+// in their extension, its Info.plist, and its entitlements, the App Group among them where it asks for it, and its
+// privacy manifest where it has them.
+function writeTargetFiles(to, target, { label, appGroup }) {
+    const dir = `targets/${target.name}`;
+    fs.mkdirSync(`${to}/${dir}/files`, { recursive: true });
+    [...target.sources, ...(target.resources ?? [])].forEach((file) => fs.cpSync(path.join(target.root, file), `${to}/${dir}/files/${file}`, { recursive: true }));
+    fs.writeFileSync(`${to}/${dir}/Info.plist`, xmlPlist(targetPlist(target, label, appGroup)));
+    const own = target.entitlements ?? {};
+    const entitlements = target.appGroup ? { ...own, [APP_GROUPS]: [...new Set([...(own[APP_GROUPS] ?? []), appGroup])] } : own;
+    const hasEntitlements = Object.keys(entitlements).length > 0;
+    if (hasEntitlements) fs.writeFileSync(`${to}/${dir}/${target.name}.entitlements`, xmlPlist(entitlements));
+    const hasPrivacy = Object.keys(target.privacy ?? {}).length > 0;
+    if (hasPrivacy) fs.writeFileSync(`${to}/${dir}/PrivacyInfo.xcprivacy`, privacyManifest(target.privacy));
+    return { dir, hasEntitlements, hasPrivacy };
+}
+
+const linkedFrameworks = (frameworks) => (frameworks.length > 0 ? { OTHER_LDFLAGS: ['$(inherited)', ...frameworks.flatMap((name) => ['-framework', name])] } : {});
+
+// A target's build settings: its bundle, of the app's id and its name, signed as the app is, with the app's version and
+// build, and its own deployment target and frameworks.
+const targetSettings = (target, { dir, hasEntitlements }, { identity, version, build }) => ({
+    PRODUCT_NAME: target.name,
+    PRODUCT_MODULE_NAME: targetModule(target.name),
+    PRODUCT_BUNDLE_IDENTIFIER: `${identity.id}.${target.name}`,
+    DEVELOPMENT_TEAM: identity.team,
+    CODE_SIGN_STYLE: 'Automatic',
+    ...(hasEntitlements ? { CODE_SIGN_ENTITLEMENTS: `${dir}/${target.name}.entitlements` } : {}),
+    INFOPLIST_FILE: `${dir}/Info.plist`,
+    MARKETING_VERSION: version,
+    CURRENT_PROJECT_VERSION: build,
+    SKIP_INSTALL: 'YES',
+    APPLICATION_EXTENSION_API_ONLY: 'YES',
+    // Objective-C's @import, and the frameworks it links of itself.
+    CLANG_ENABLE_MODULES: 'YES',
+    LD_RUNPATH_SEARCH_PATHS: ['$(inherited)', '@executable_path/Frameworks', '@executable_path/../../Frameworks'],
+    ...(target.sources.some((file) => file.endsWith('.swift')) ? { SWIFT_VERSION: '5.0' } : {}),
+    ...(target.deploymentTarget ? { IPHONEOS_DEPLOYMENT_TARGET: target.deploymentTarget } : {}),
+    ...linkedFrameworks(targetFrameworks(target)),
+});
+
+// The project's objects of one target, by ids of its place among them: its files, build phases, configurations and the
+// target, with what the app's target takes of it, a dependency on it and the copy of its product into the app's PlugIns.
+function targetObjects(target, place, written, options) {
+    const objects = {};
+    let count = 0;
+    const add = (object) => {
+        count += 1;
+        objects[idOf(place, count)] = object;
+        return idOf(place, count);
+    };
+    const reference = (file, type) => add({ isa: 'PBXFileReference', lastKnownFileType: type, path: file, sourceTree: '<group>' });
+    const typeOf = (file) => FILE_TYPES[path.extname(file)] ?? (fs.statSync(path.join(target.root, file)).isDirectory() ? 'folder' : 'file');
+    const phase = (isa, files) => add({ isa, buildActionMask: 2147483647, files: files.map((fileRef) => add({ isa: 'PBXBuildFile', fileRef })), runOnlyForDeploymentPostprocessing: 0 });
+    // Its headers are in its group, which its sources import from beside them, and compile with them.
+    const headers = target.sources.filter(isHeader).map((file) => reference(`files/${file}`, typeOf(file)));
+    const sources = target.sources.filter((file) => !isHeader(file)).map((file) => reference(`files/${file}`, typeOf(file)));
+    const resources = [...(target.resources ?? []).map((file) => reference(`files/${file}`, typeOf(file))),
+        ...(written.hasPrivacy ? [reference('PrivacyInfo.xcprivacy', 'text.xml')] : [])];
+    const info = reference('Info.plist', 'text.plist.xml');
+    const signed = written.hasEntitlements ? [reference(`${target.name}.entitlements`, 'text.plist.entitlements')] : [];
+    const product = add({ isa: 'PBXFileReference', explicitFileType: 'wrapper.app-extension', includeInIndex: 0, path: `${target.name}.appex`, sourceTree: 'BUILT_PRODUCTS_DIR' });
+    const group = add({ isa: 'PBXGroup', children: [info, ...signed, ...headers, ...sources, ...resources], path: written.dir, sourceTree: '<group>' });
+    const phases = [phase('PBXSourcesBuildPhase', sources), phase('PBXFrameworksBuildPhase', []), phase('PBXResourcesBuildPhase', resources)];
+    const buildSettings = targetSettings(target, written, options);
+    const configurations = ['Debug', 'Release'].map((name) => add({ isa: 'XCBuildConfiguration', buildSettings, name }));
+    const list = add({ isa: 'XCConfigurationList', buildConfigurations: configurations, defaultConfigurationIsVisible: 0, defaultConfigurationName: 'Release' });
+    const native = add({
+        isa: 'PBXNativeTarget', buildConfigurationList: list, buildPhases: phases, buildRules: [], dependencies: [], name: target.name,
+        productName: target.name, productReference: product, productType: 'com.apple.product-type.app-extension',
+    });
+    const proxy = add({ isa: 'PBXContainerItemProxy', containerPortal: options.project, proxyType: 1, remoteGlobalIDString: native, remoteInfo: target.name });
+    const dependency = add({ isa: 'PBXTargetDependency', target: native, targetProxy: proxy });
+    const embedded = add({ isa: 'PBXBuildFile', fileRef: product, settings: { ATTRIBUTES: ['RemoveHeadersOnCopy'] } });
+    return { objects, group, product, native, dependency, embedded };
+}
+
+// Writes the folder of each target of Apple's app extensions the app's extensions add, and gives the project's objects
+// for them: each a target whose bundle is the app's id and its name, which the app builds first and embeds in its PlugIns.
+export function writeTargets(to, targets, options) {
+    widgetsWithoutBackground(targets, (target, file) => fs.readFileSync(path.join(target.root, file), 'utf8')).forEach((name) => {
+        console.warn(`crossbind: the widget target ${name} names no containerBackground in its Swift, which iOS 17 asks of a widget's view: a debug build `
+            + 'draws "Please adopt containerBackground API" in its place. Its view gives its background with .containerBackground(.background, for: .widget).');
+    });
+    const made = targets.map((target, place) => targetObjects(target, place, writeTargetFiles(to, target, options), options));
+    return {
+        objects: Object.assign({}, ...made.map(({ objects }) => objects)),
+        groups: made.map(({ group }) => group),
+        products: made.map(({ product }) => product),
+        dependencies: made.map(({ dependency }) => dependency),
+        targets: made.map(({ native }) => native),
+        embedded: made.map(({ embedded }) => embedded),
+    };
+}

package/src/actions/xcodebuild.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { EXEC_MAX_BUFFER } from './run.js';
+
+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;
+
+// What a failed build, 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. A cause may need another build, as one in what was built does.
+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 CROSSBIND_APPLE_API_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,
+    },
+];
+
+// 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, from crossbind's causes first, then those the caller adds: the error says whether the
+// user can mend it and try again, the page where, and the cause it found.
+export function xcodebuild(what, args, { log, facts = {}, causes = [] }) {
+    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, ...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 });
+}
+
+// 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()];
+}