crossbind 2.0.0-beta.67 → 2.0.0-beta.68

package/src/actions/xcodeProject.js

@@ -3,6 +3,7 @@ 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';
 
 // The SDKs an iOS app builds for, one target each, and the slice of Hermes' release each takes.
 export const IOS_SDKS = ['iphoneos', 'iphonesimulator'];
@@ -18,7 +19,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'];
+    'targetDebug', 'targetRelease', 'projectConfigs', 'targetConfigs', 'assets', 'assetsBuild', 'privacy', 'privacyBuild'];
 // 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')}`]));
 
@@ -39,7 +40,7 @@ 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) => xmlPlist({
+const infoPlist = (name, urlSchemes, hasBackground, usage, encryption) => xmlPlist({
     CFBundleDevelopmentRegion: 'en',
     CFBundleDisplayName: name,
     CFBundleExecutable: '$(EXECUTABLE_NAME)',
@@ -50,6 +51,7 @@ const infoPlist = (name, urlSchemes, hasBackground, usage) => xmlPlist({
     CFBundleShortVersionString: '$(MARKETING_VERSION)',
     ...(urlSchemes.length > 0 ? { CFBundleURLTypes: [{ CFBundleURLName: '$(PRODUCT_BUNDLE_IDENTIFIER)', CFBundleURLSchemes: urlSchemes }] } : {}),
     CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
+    ...(encryption === null ? {} : { ITSAppUsesNonExemptEncryption: encryption }),
     LSRequiresIPhoneOS: true,
     UIApplicationSceneManifest: { UIApplicationSupportsMultipleScenes: false },
     UILaunchScreen: hasBackground ? { UIColorName: LAUNCH_COLOR } : {},
@@ -59,7 +61,7 @@ const infoPlist = (name, urlSchemes, hasBackground, usage) => xmlPlist({
     ...usage,
 });
 
-function objects(name, targetSettings, hasAssets) {
+function objects(name, targetSettings, hasAssets, hasPrivacy) {
     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 });
@@ -71,8 +73,13 @@ function objects(name, targetSettings, hasAssets) {
         [ID.assets]: file('Assets.xcassets', 'folder.assetcatalog'),
         [ID.assetsBuild]: { isa: 'PBXBuildFile', fileRef: ID.assets },
     } : {};
+    const privacy = hasPrivacy ? {
+        [ID.privacy]: file('PrivacyInfo.xcprivacy', 'text.xml'),
+        [ID.privacyBuild]: { isa: 'PBXBuildFile', fileRef: ID.privacy },
+    } : {};
     return {
         ...assets,
+        ...privacy,
         [ID.main]: file('main.m', 'sourcecode.c.objc'),
         [ID.info]: file('Info.plist', 'text.plist.xml'),
         [ID.app]: file('app', 'folder'),
@@ -86,10 +93,12 @@ function objects(name, targetSettings, hasAssets) {
         [ID.hermesEmbed]: { isa: 'PBXBuildFile', fileRef: ID.hermes, settings: { ATTRIBUTES: ['CodeSignOnCopy', 'RemoveHeadersOnCopy'] } },
         [ID.sources]: phase('PBXSourcesBuildPhase', [ID.mainBuild]),
         [ID.frameworks]: phase('PBXFrameworksBuildPhase', [ID.hermesLink]),
-        [ID.resources]: phase('PBXResourcesBuildPhase', [ID.appBuild, ...(hasAssets ? [ID.assetsBuild] : [])]),
+        [ID.resources]: phase('PBXResourcesBuildPhase', [ID.appBuild, ...(hasAssets ? [ID.assetsBuild] : []), ...(hasPrivacy ? [ID.privacyBuild] : [])]),
         [ID.embed]: phase('PBXCopyFilesBuildPhase', [ID.hermesEmbed], { dstPath: '', dstSubfolderSpec: 10, name: 'Embed Frameworks' }),
         [ID.mainGroup]: {
-            isa: 'PBXGroup', children: [ID.main, ID.info, ID.app, ...(hasAssets ? [ID.assets] : []), ID.hermes, ID.products], sourceTree: '<group>',
+            isa: 'PBXGroup',
+            children: [ID.main, ID.info, ID.app, ...(hasAssets ? [ID.assets] : []), ...(hasPrivacy ? [ID.privacy] : []), ID.hermes, ID.products],
+            sourceTree: '<group>',
         },
         [ID.products]: { isa: 'PBXGroup', children: [ID.product], name: 'Products', sourceTree: '<group>' },
         [ID.target]: {
@@ -143,10 +152,20 @@ 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.
-export default function writeXcodeProject(to, { parts, identity, label, version, icon = null, urlSchemes = [], background = null, usage = {} }) {
+export default function writeXcodeProject(to, {
+    parts, identity, label, version, build = version, icon = null, urlSchemes = [], background = null, usage = {}, encryption = null, privacy = {},
+}) {
     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.`);
     fs.rmSync(to, { recursive: true, force: true });
@@ -165,8 +184,10 @@ export default function writeXcodeProject(to, { parts, identity, label, version,
     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));
+    fs.writeFileSync(`${to}/Info.plist`, infoPlist(label, urlSchemes, Boolean(background), usage, encryption));
     writeAssets(`${to}/Assets.xcassets`, icon, background);
+    const hasPrivacy = Object.keys(privacy).length > 0;
+    if (hasPrivacy) fs.writeFileSync(`${to}/PrivacyInfo.xcprivacy`, privacyManifest(privacy));
     const targetSettings = {
         ...(icon ? { ASSETCATALOG_COMPILER_APPICON_NAME: 'AppIcon' } : {}),
         PRODUCT_NAME: name,
@@ -175,12 +196,12 @@ export default function writeXcodeProject(to, { parts, identity, label, version,
         CODE_SIGN_STYLE: 'Automatic',
         INFOPLIST_FILE: 'Info.plist',
         MARKETING_VERSION: version,
-        CURRENT_PROJECT_VERSION: version,
+        CURRENT_PROJECT_VERSION: build,
         LD_RUNPATH_SEARCH_PATHS: ['$(inherited)', '@executable_path/Frameworks'],
         ...linkFlags,
     };
     fs.writeFileSync(`${to}/${name}.xcodeproj/project.pbxproj`, textPlist({
-        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings, Boolean(icon || background)), rootObject: ID.project,
+        archiveVersion: 1, classes: {}, objectVersion: 56, objects: objects(name, targetSettings, Boolean(icon || background), hasPrivacy), rootObject: ID.project,
     }));
     return to;
 }

package/src/bin.js

@@ -15,8 +15,13 @@ import buildWasiCommand from './actions/buildWasiCommand.js';
 import buildNode, { addonsInPackages, bundleNodeLoader, publishNodeData } from './actions/buildNode.js';
 import buildNativeCommand from './actions/buildNativeCommand.js';
 import buildApp, { appOutputPath, assertAppRunner, publishApp } from './actions/buildApp.js';
-import { releaseSigning } from './actions/androidGradle.js';
 import { UPDATER_KEY, newUpdaterKey } from './actions/appUpdate.js';
+import {
+    makeUploadKey, releaseSigningEnv, showUploadKeyPassword, useUploadKey,
+} from './actions/uploadKey.js';
+import { publishAndroid } from './actions/publishAndroid.js';
+import { publishIos } from './actions/publishIos.js';
+import { iosDeviceOption } from './actions/iosDevice.js';
 import buildExternal from './actions/buildExternal.js';
 import buildPackageTypes from './actions/buildTypes.js';
 import buildLib from './actions/buildLib.js';
@@ -116,30 +121,51 @@ function projectVite() {
     }
 }
 
+// The project's Vite, as `crossbind app dev`, `build` and `publish` run it, and its exit code once it ends. A signal sent
+// to crossbind alone reaches Vite too, which ends through its exit hooks; Ctrl-C reaches both. Once Vite has ended,
+// signals stop crossbind again, as at the questions a publish asks after its build.
+function runVite(args, env) {
+    const vite = spawn(process.execPath, [projectVite(), ...args], { stdio: 'inherit', cwd: state.config.paths.project, env });
+    const forwards = ['SIGINT', 'SIGTERM', 'SIGHUP'].map((signal) => [signal, () => vite.kill(signal)]);
+    forwards.forEach(([signal, forward]) => process.prependListener(signal, forward));
+    return new Promise((resolve) => {
+        vite.on('exit', (code, signal) => {
+            forwards.forEach(([name, forward]) => process.off(name, forward));
+            resolve(code ?? 128 + os.constants.signals[signal]);
+        });
+    });
+}
+
+function assertAppProject() {
+    if (state.config.target.runtimeEnv !== 'app') {
+        throw new Error("crossbind: crossbind app builds an app, which this project is not: set target: { runtimeEnv: 'app' } in crossbind.config.js, as the desktop-app template does.");
+    }
+}
+
 const commandApp = program.command('app').description('build the project as an app, or open it on the dev server');
 [
     ['dev', 'open the app on the dev server, and open it anew as its native code changes'],
     ['build', 'build the app with its page: for Android also its APK, and with an upload key its bundle'],
-].forEach(([name, description]) => commandApp.command(name).description(description)
-    .addOption(new Option('-p, --platform <platform>', "the app's platform (default: CROSSBIND_APP_PLATFORM, else this machine's)").choices(APP_PLATFORMS))
-    // Vite's own options, as --port or --mode, go on to Vite.
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action(({ platform }, command) => {
-        if (state.config.target.runtimeEnv !== 'app') {
-            throw new Error("crossbind: crossbind app builds an app, which this project is not: set target: { runtimeEnv: 'app' } in crossbind.config.js, as the desktop-app template does.");
-        }
-        // An Android build checks its upload key before the native build, not after it.
-        if (name === 'build' && (platform ?? process.env.CROSSBIND_APP_PLATFORM) === 'android') releaseSigning();
-        const vite = spawn(process.execPath, [projectVite(), ...(name === 'build' ? ['build'] : []), ...command.args], {
-            stdio: 'inherit',
-            cwd: state.config.paths.project,
-            env: platform ? { ...process.env, CROSSBIND_APP_PLATFORM: platform } : process.env,
+].forEach(([name, description]) => {
+    const appCommand = commandApp.command(name).description(description)
+        .addOption(new Option('-p, --platform <platform>', "the app's platform (default: CROSSBIND_APP_PLATFORM, else this machine's)").choices(APP_PLATFORMS));
+    if (name === 'dev') {
+        appCommand.option('--device [name]', 'open an iOS app on a connected iPhone or iPad, the one named or else the only one, rather than in the Simulator');
+    }
+    appCommand
+        // Vite's own options, as --port or --mode, go on to Vite.
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async ({ platform, device }, command) => {
+            assertAppProject();
+            // An Android build checks its upload key before the native build, not after it.
+            const isAndroidBuild = name === 'build' && (platform ?? process.env.CROSSBIND_APP_PLATFORM) === 'android';
+            const { env: signing } = isAndroidBuild ? await releaseSigningEnv() : { env: {} };
+            const onDevice = device === undefined ? {} : { CROSSBIND_APP_DEVICE: iosDeviceOption(device, platform ?? process.env.CROSSBIND_APP_PLATFORM) };
+            const env = { ...process.env, ...signing, ...(platform ? { CROSSBIND_APP_PLATFORM: platform } : {}), ...onDevice };
+            process.exit(await runVite([...(name === 'build' ? ['build'] : []), ...command.args], env));
         });
-        // A signal sent to crossbind alone reaches Vite too, which ends through its exit hooks; Ctrl-C reaches both.
-        ['SIGINT', 'SIGTERM', 'SIGHUP'].forEach((signal) => process.prependListener(signal, () => vite.kill(signal)));
-        vite.on('exit', (code, signal) => process.exit(code ?? 128 + os.constants.signals[signal]));
-    }));
+});
 
 commandApp.command('updater-key')
     .description("make the key pair that signs a desktop app's updates")
@@ -149,6 +175,41 @@ commandApp.command('updater-key')
         console.log(`crossbind: ${UPDATER_KEY}, kept secret where the app is built: ${privateKey}`);
     });
 
+commandApp.command('upload-key')
+    .description("make this machine's upload key, which signs an Android app's bundle for Google Play")
+    .option('--use <keystore>', 'make a key you have the upload key instead, once it opens with its password')
+    .option('--alias <alias>', 'the alias of the key in the keystore --use names', 'upload')
+    .option('--no-keychain', 'keep the password in no keychain, so builds ask for it')
+    .option('--show-password', 'print the password the keychain keeps, for another machine or CI')
+    .action(async ({ use, alias, keychain, showPassword }) => {
+        if (showPassword) showUploadKeyPassword();
+        else if (use) await useUploadKey(use, { alias, isKeychain: keychain });
+        else await makeUploadKey({ isKeychain: keychain });
+    });
+
+commandApp.command('publish')
+    .description('build the app and send it to its store: an Android bundle to a Google Play track, an iOS app to App Store Connect for TestFlight')
+    .addOption(new Option('-p, --platform <platform>', "the store's platform (default: CROSSBIND_APP_PLATFORM)").choices(['android', 'ios']))
+    .option('--track <track>', 'the Google Play track the release goes on: internal, alpha, beta, production or one of your own', 'internal')
+    .option('--draft', 'leave the Google Play release a draft, which Play Console rolls out')
+    // Vite's own options, as --mode, go on to Vite.
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action(async ({ platform, track, draft }, command) => {
+        assertAppProject();
+        const store = platform ?? process.env.CROSSBIND_APP_PLATFORM;
+        if (store === 'android') {
+            await publishAndroid({ track, status: draft ? 'draft' : 'completed', viteArgs: command.args }, { runVite });
+            return;
+        }
+        if (store !== 'ios') throw new Error('crossbind: crossbind app publish takes -p android or -p ios, the platform of the store it sends the app to.');
+        const playOptions = ['track', 'draft'].filter((option) => command.getOptionValueSource(option) === 'cli');
+        if (playOptions.length > 0) {
+            throw new Error(`crossbind: ${playOptions.map((option) => `--${option}`).join(' and ')} ${playOptions.length > 1 ? 'are' : 'is'} Google Play's; App Store Connect hands every iOS upload to TestFlight.`);
+        }
+        await publishIos({ viteArgs: command.args }, { runVite });
+    });
+
 program.command('licenses')
     .description('list bundled native dependencies with SPDX license, versions and source URL')
     .option('--notices [file]', 'write a THIRD-PARTY-NOTICES markdown file (default: THIRD-PARTY-NOTICES.md)')

package/src/index.js

@@ -8,6 +8,9 @@ export {
 } from './actions/buildApp.js';
 export { checkInstaller } from './actions/appInstaller.js';
 export { default as openInSimulator, buildForSimulator } from './actions/iosSimulator.js';
+export {
+    default as openOnIosDevice, buildForIosDevice, connectedIosDevice, iosDeviceAddress, iosDevServer,
+} from './actions/iosDevice.js';
 export { default as openOnDevice, adbPath } from './actions/androidDevice.js';
 export { buildApk } from './actions/androidGradle.js';
 export { default as isSourceNewer } from './actions/isSourceNewer.js';

package/src/program.js

@@ -22,7 +22,9 @@ export const handleFatal = (e) => {
         if (e?.cause?.message) message += `\n  caused by: ${e.cause.message.split('\n')[0]}`;
         console.error(message);
     }
-    process.exit(1);
+    // Writes to a pipe are asynchronous, so exiting at once would cut what is still queued, such as the failed
+    // command's output run.js printed: exit after both streams have written it.
+    process.stdout.write('', () => process.stderr.write('', () => process.exit(1)));
 };
 
 export const createProgram = () => new Command()

package/src/utils/appApiHeader.js

@@ -12,6 +12,10 @@ export function compilesAsApp(target) {
     return state.config.target?.runtimeEnv === 'app' && runtimeEnvsOf(target.platform).includes('app');
 }
 
+// What an app's own code compiles with: CROSSBIND_APP, and on iOS its debug information, from which the archive's dSYM
+// gives App Store Connect its files and lines; Android's NDK keeps that by default.
+export const appCompileOptions = (target) => (compilesAsApp(target) ? ['-DCROSSBIND_APP', ...(target.platform === 'ios' ? ['-g'] : [])] : []);
+
 export function appApiHeader() {
     const header = `${resolveAppHostRoot()}/cpp/include/crossbind/app.h`;
     if (!fs.existsSync(header)) {

package/src/utils/appOptions.js

@@ -146,6 +146,46 @@ export function usageDescriptions(config, platform) {
     return Object.fromEntries(Object.entries(appPermissions(config)).flatMap(([name, reason]) => keys[name].map((key) => [key, reason])));
 }
 
+// Apple's categories of required reason API, each with the type a privacy manifest names it by and the reasons Apple
+// takes for it, from "Describing use of required reason API".
+export const PRIVACY_CATEGORIES = {
+    fileTimestamp: { type: 'NSPrivacyAccessedAPICategoryFileTimestamp', reasons: ['DDA9.1', 'C617.1', '3B52.1', '0A2A.1'] },
+    systemBootTime: { type: 'NSPrivacyAccessedAPICategorySystemBootTime', reasons: ['35F9.1', '8FFB.1', '3D61.1'] },
+    diskSpace: { type: 'NSPrivacyAccessedAPICategoryDiskSpace', reasons: ['85F4.1', 'E174.1', '7D9E.1', 'B728.1'] },
+    activeKeyboards: { type: 'NSPrivacyAccessedAPICategoryActiveKeyboards', reasons: ['3EC4.1', '54BD.1'] },
+    userDefaults: { type: 'NSPrivacyAccessedAPICategoryUserDefaults', reasons: ['CA92.1', '1C8F.1', 'C56D.1', 'AC6B.1'] },
+};
+
+// The reasons an iOS app's privacy manifest gives for the required reason API it calls: app.privacy, each category with
+// Apple's reasons that fit, as { fileTimestamp: ['C617.1'] }.
+export function appPrivacy(config) {
+    const privacy = config.app.privacy ?? {};
+    const names = Object.keys(PRIVACY_CATEGORIES).join(', ');
+    if (typeof privacy !== 'object' || privacy === null || Array.isArray(privacy)) {
+        throw new Error(`crossbind: app.privacy ${JSON.stringify(privacy)} is no object of ${names}, each with Apple's reasons for it, as { fileTimestamp: ['C617.1'] } is.`);
+    }
+    const unknown = Object.keys(privacy).filter((name) => !Object.hasOwn(PRIVACY_CATEGORIES, name));
+    if (unknown.length > 0) throw new Error(`crossbind: app.privacy takes ${names}; ${unknown.join(', ')} is none of them.`);
+    Object.entries(privacy).forEach(([name, reasons]) => {
+        const allowed = PRIVACY_CATEGORIES[name].reasons;
+        if (!Array.isArray(reasons) || reasons.length === 0 || reasons.some((reason) => !allowed.includes(reason))) {
+            throw new Error(`crossbind: app.privacy.${name} ${JSON.stringify(reasons)} is no list of Apple's reasons for it, which are ${allowed.join(', ')}; Apple's "Describing use of required reason API" says what each covers.`);
+        }
+    });
+    return privacy;
+}
+
+// Whether an iOS app uses encryption that export rules do not exempt, which its Info.plist tells App Store Connect so that
+// it stops asking for every build: app.encryption. It is a legal statement, so there is none without it.
+export function appEncryption(config) {
+    const encryption = config.app.encryption;
+    if (encryption === undefined) return null;
+    if (typeof encryption !== 'boolean') {
+        throw new Error(`crossbind: app.encryption ${JSON.stringify(encryption)} is no boolean: set it to false when the app uses no encryption, or only what export rules exempt as the system's HTTPS, and to true when it uses any other.`);
+    }
+    return encryption;
+}
+
 // The version a Windows app's executable carries: package.json's, whose numbers are its file version.
 function windowsVersion(config) {
     const version = config.package?.version ?? '1.0.0';

package/src/utils/ask.js

@@ -0,0 +1,38 @@
+import readline from 'node:readline';
+import { Writable } from 'node:stream';
+
+// Whether someone is at a terminal to answer a question, as no one is in CI or behind a pipe.
+export const hasTerminal = () => Boolean(process.stdin.isTTY && process.stderr.isTTY);
+
+function ask(question, { input, output, isHidden }) {
+    output.write(question);
+    // A hidden answer is echoed into nothing, while the terminal, in raw mode, shows none of it either.
+    const echo = isHidden ? new Writable({ write: (chunk, encoding, done) => done() }) : output;
+    const reader = readline.createInterface({ input, output: echo, terminal: isHidden });
+    return new Promise((resolve, reject) => {
+        let isAnswered = false;
+        reader.once('line', (line) => {
+            isAnswered = true;
+            reader.close();
+            if (isHidden) output.write('\n');
+            resolve(line);
+        });
+        reader.once('SIGINT', () => {
+            reader.close();
+            output.write('\n');
+            reject(new Error('crossbind: stopped at the question.'));
+        });
+        reader.once('close', () => {
+            if (!isAnswered) reject(new Error('crossbind: the terminal closed before an answer.'));
+        });
+    });
+}
+
+// An answer typed on the terminal that the terminal does not show, as a password.
+export const askHidden = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: true });
+
+// An answer typed on the terminal.
+export const askLine = (question, { input = process.stdin, output = process.stderr } = {}) => ask(question, { input, output, isHidden: false });
+
+// A yes or no typed on the terminal: yes unless it starts with n.
+export const askYesNo = async (question, streams) => !/^\s*n/i.test(await askLine(question, streams));

package/src/utils/configWriter.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import { parseAst } from 'rollup/parseAst';
+
+// The kinds of crossbind.config whose default export can be an object literal to write into.
+const CONFIG_EXTENSIONS = ['js', 'mjs', 'cjs'];
+const DEFAULT_INDENT = '    ';
+
+const indentOf = (source, at) => source.slice(source.lastIndexOf('\n', at - 1) + 1).match(/^[ \t]*/)[0];
+const isOneLine = (source, from, to) => !source.slice(from, to).includes('\n');
+const insert = (source, at, text) => `${source.slice(0, at)}${text}${source.slice(at)}`;
+const propertyOf = (object, name) => object.properties.find((property) => property.type === 'Property' && !property.computed
+    && (property.key.name ?? property.key.value) === name);
+// A spread may carry the key, and would win over one written before it.
+const hasSpread = (object) => object.properties.some((property) => property.type === 'SpreadElement');
+// A value as one writes it in a config by hand: { fileTimestamp: ['C617.1'] }.
+function literal(value) {
+    if (typeof value === 'string') return `'${value.replace(/[\\']/g, '\\$&')}'`;
+    if (Array.isArray(value)) return `[${value.map(literal).join(', ')}]`;
+    if (value !== null && typeof value === 'object') return `{ ${Object.entries(value).map(([key, item]) => `${key}: ${literal(item)}`).join(', ')} }`;
+    return JSON.stringify(value);
+}
+export const entry = (key, value) => `${key}: ${literal(value)}`;
+
+// How far an object's keys sit in from the line it opens on.
+function indentUnit(source, object) {
+    const [first] = object.properties;
+    if (!first || isOneLine(source, object.start, first.start)) return DEFAULT_INDENT;
+    return indentOf(source, first.start).slice(indentOf(source, object.start).length) || DEFAULT_INDENT;
+}
+
+// The config's source with `key: value` first in its app section, which it makes where there is none, or null where it
+// cannot place it safely: the default export must be an object literal, its app one too, without the key or a spread.
+export function withAppOption(source, key, value) {
+    const exported = parseAst(source).body.find((node) => node.type === 'ExportDefaultDeclaration')?.declaration;
+    if (exported?.type !== 'ObjectExpression') return null;
+    const unit = indentUnit(source, exported);
+    const text = entry(key, value);
+    const app = propertyOf(exported, 'app');
+    if (!app) {
+        if (hasSpread(exported)) return null;
+        const [first] = exported.properties;
+        if (!first || isOneLine(source, exported.start, first.start)) return insert(source, exported.start + 1, ` app: { ${text} },`);
+        const indent = indentOf(source, first.start);
+        return insert(source, exported.start + 1, `\n${indent}app: {\n${indent}${unit}${text},\n${indent}},`);
+    }
+    if (app.value.type !== 'ObjectExpression' || propertyOf(app.value, key) || hasSpread(app.value)) return null;
+    const [first] = app.value.properties;
+    if (!first) {
+        const indent = indentOf(source, app.start);
+        return `${source.slice(0, app.value.start)}{\n${indent}${unit}${text},\n${indent}}${source.slice(app.value.end)}`;
+    }
+    if (isOneLine(source, app.value.start, first.start)) return insert(source, app.value.start + 1, ` ${text},`);
+    return insert(source, app.value.start + 1, `\n${indentOf(source, first.start)}${text},`);
+}
+
+// Writes `key: value` into the project's crossbind.config, and says whether it could.
+export function writeAppOption(project, key, value) {
+    const file = CONFIG_EXTENSIONS.map((extension) => `${project}/crossbind.config.${extension}`).find((candidate) => fs.existsSync(candidate));
+    if (!file) return false;
+    const changed = withAppOption(fs.readFileSync(file, 'utf8'), key, value);
+    if (changed === null) return false;
+    fs.writeFileSync(file, changed);
+    return true;
+}

package/src/utils/hermes.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import withDirLock from './dirLock.js';
 import downloadAndExtractFile from './downloadAndExtractFile.js';
+import logger from './logger.js';
 
 // The Hermes React Native publishes on Maven Central for Apple platforms: the macOS framework, the iOS xcframework,
 // hermesc and the headers. A new version also moves third_party/jsi of @crossbind/core-app-host to its tag, and the
@@ -25,6 +26,29 @@ export default async function resolveHermes() {
     return `${dir}/source/destroot`;
 }
 
+// The dSYMs of the release's frameworks, with which App Store Connect shows Hermes' frames in an iOS app's crash reports
+// as functions and lines.
+export const HERMES_DSYM = {
+    url: `https://repo1.maven.org/maven2/com/facebook/hermes/hermes-ios/${HERMES.version}/hermes-ios-${HERMES.version}-hermes-framework-dSYM-release.tar.gz`,
+    sha256: '5cea3dd57ecadb42c40d1cc8acf2e178dbfbe6a230410742d997ff3fe313a9c0',
+};
+
+// The dSYM of the device's framework, downloaded once and checked against the pinned sha256. The release's 360 MB hold
+// every Apple platform's, of which only the device's 80 MB are kept.
+export async function resolveHermesDsym() {
+    const dir = `${hermesDir()}-dsym`;
+    const dsym = `${dir}/source/iphoneos/hermesvm.framework.dSYM`;
+    if (!fs.existsSync(dsym)) logger.info(`crossbind: downloading the dSYM of Hermes ${HERMES.version} once, 360 MB of which 80 MB stay, for crash reports.`);
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+    await withDirLock(`${dir}.lock`, async () => {
+        await downloadAndExtractFile(HERMES_DSYM.url, dir, HERMES_DSYM.sha256);
+        fs.rmSync(`${dir}/${path.basename(HERMES_DSYM.url)}`, { force: true });
+        fs.readdirSync(`${dir}/source`).filter((entry) => entry !== 'iphoneos')
+            .forEach((entry) => fs.rmSync(`${dir}/source/${entry}`, { recursive: true, force: true }));
+    });
+    return dsym;
+}
+
 // Linux and Windows have no published Hermes, so crossbind's linux and windows images build the release's source, with
 // their static libc++: JSI hands std types across, and the host and the project's archives build there too.
 export const HERMES_SOURCE = {

package/src/utils/keychain.js

@@ -0,0 +1,54 @@
+import { spawnSync } from 'node:child_process';
+
+// The keychain names a secret by a service and an account: an upload key's password by this service, with the key's own
+// path as the account.
+const SERVICE = 'crossbind upload key';
+// security -i reads a command line whose quoted words take a backslash before a quote or a backslash.
+const quoted = (word) => `"${word.replace(/[\\"]/g, '\\$&')}"`;
+// Windows PowerShell, which imports its core modules from its own home: a pwsh 7 parent's PSModulePath hides them.
+const powershell = (script) => ['-NoProfile', '-NonInteractive', '-Command', `Import-Module (Join-Path $PSHOME 'Modules\\Microsoft.PowerShell.Security'); ${script}`];
+const STORE_DPAPI = 'ConvertTo-SecureString -String $env:CROSSBIND_KEYCHAIN_SECRET -AsPlainText -Force | ConvertFrom-SecureString | Set-Content -LiteralPath $env:CROSSBIND_KEYCHAIN_FILE -NoNewline';
+const READ_DPAPI = "$secret = Get-Content -LiteralPath $env:CROSSBIND_KEYCHAIN_FILE -Raw | ConvertTo-SecureString; [Console]::Out.Write([System.Net.NetworkCredential]::new('', $secret).Password)";
+
+const run = (program, args, options = {}) => spawnSync(program, args, { encoding: 'utf8', ...options });
+
+// Each system's keychain, given the secret on stdin or in the environment, never on a command line. On Windows it is the
+// user's DPAPI, in a file beside the key that only that user on that machine can read, so the path alone names it.
+const KEYCHAINS = {
+    darwin: {
+        store: (service, key, secret) => run('security', ['-i'], { input: `add-generic-password -U -s ${quoted(service)} -a ${quoted(key)} -w ${quoted(secret)}\n` }),
+        read: (service, key) => run('security', ['find-generic-password', '-s', service, '-a', key, '-w']),
+    },
+    win32: {
+        store: (service, key, secret) => run('powershell.exe', powershell(STORE_DPAPI), {
+            env: { ...process.env, CROSSBIND_KEYCHAIN_SECRET: secret, CROSSBIND_KEYCHAIN_FILE: `${key}.dpapi` },
+        }),
+        read: (service, key) => run('powershell.exe', powershell(READ_DPAPI), { env: { ...process.env, CROSSBIND_KEYCHAIN_FILE: `${key}.dpapi` } }),
+    },
+    linux: {
+        store: (service, key, secret) => run('secret-tool', ['store', '--label', service, 'service', service, 'account', key], { input: secret }),
+        read: (service, key) => run('secret-tool', ['lookup', 'service', service, 'account', key]),
+    },
+};
+
+const keychainOf = (platform) => KEYCHAINS[platform] ?? KEYCHAINS.linux;
+
+// Whether the system has a keychain to keep a password in: macOS and Windows always, Linux where secret-tool is.
+export const hasKeychain = ({ platform = process.platform } = {}) => ['darwin', 'win32'].includes(platform) || !run('secret-tool', ['--help']).error;
+
+// An upload key's password, or another service's secret, from the system's keychain, or null when it keeps none or there
+// is no keychain.
+export function readSecret(key, { platform = process.platform, service = SERVICE } = {}) {
+    const result = keychainOf(platform).read(service, key);
+    if (result.error || result.status !== 0) return null;
+    // security ends what it prints with a newline.
+    return result.stdout.replace(/\n$/, '') || null;
+}
+
+// Keeps an upload key's password, or another service's secret, in the system's keychain, and says whether it did: Linux
+// without secret-tool and its service has none. A secret counts as kept once it reads back, as security -i fails without
+// an exit code.
+export function storeSecret(key, secret, { platform = process.platform, service = SERVICE } = {}) {
+    keychainOf(platform).store(service, key, secret);
+    return readSecret(key, { platform, service }) === secret;
+}

package/src/utils/openUrl.js

@@ -0,0 +1,11 @@
+import { spawn } from 'node:child_process';
+
+const OPENERS = { darwin: ['open'], win32: ['cmd', '/c', 'start', '""'] };
+
+// Opens an address in the user's browser where the system can; whoever calls it prints the address too.
+export default function openUrl(url) {
+    const [program, ...args] = OPENERS[process.platform] ?? ['xdg-open'];
+    const opener = spawn(program, [...args, url], { stdio: 'ignore', detached: true });
+    opener.on('error', () => {});
+    opener.unref();
+}

package/src/utils/password.js

@@ -0,0 +1,34 @@
+import { randomBytes } from 'node:crypto';
+
+// NIST SP 800-63B-4's least length for a password that alone guards what it locks, as an upload key's does.
+export const MIN_PASSWORD_LENGTH = 15;
+// Rows a password can run along, either way and around: the alphabet, the digits, and a keyboard's.
+const ROWS = ['abcdefghijklmnopqrstuvwxyz', '0123456789', 'qwertyuiopasdfghjklzxcvbnm', '1qaz2wsx3edc4rfv5tgb6yhn7ujm8ik9ol0p', 'q1w2e3r4t5y6u7i8o9p0'];
+// Long passwords others try first, which the rules above let through.
+const GUESSED = ['correcthorsebatterystaple', 'thequickbrownfoxjumpsoverthelazydog', 'crossbinduploadkey', 'androiduploadkey'];
+
+// What the user reads before typing an upload key's password.
+export const PASSWORD_RULES = [
+    `${MIN_PASSWORD_LENGTH} characters or more; spaces and any characters are welcome, so a few words make a good one`,
+    'not one part repeated, not a run as 1234, abcd or qwerty, and not a well-known password',
+];
+
+const runsAlong = (text, row) => {
+    const around = row.repeat(Math.ceil(text.length / row.length) + 1);
+    return around.includes(text) || [...around].reverse().join('').includes(text);
+};
+
+// Why a password is too weak to lock an upload key, or null when it is not. NIST asks for no mix of kinds of characters.
+export function passwordProblem(password) {
+    const length = [...password].length;
+    if (length < MIN_PASSWORD_LENGTH) return `it has ${length} characters and needs at least ${MIN_PASSWORD_LENGTH}`;
+    if (/\p{Cc}/u.test(password)) return 'it has a control character, which no terminal types';
+    const plain = password.toLowerCase();
+    if (/^(.+?)\1+$/su.test(plain)) return 'it repeats one part';
+    if (ROWS.some((row) => runsAlong(plain, row))) return 'it runs along a row, as 1234, abcd and qwerty do';
+    if (GUESSED.includes(plain.replace(/\s+/g, ''))) return 'it is a password others guess first';
+    return null;
+}
+
+// A password crossbind makes: 18 random bytes, 144 bits, as 24 characters any terminal and keytool take.
+export const makePassword = () => randomBytes(18).toString('base64url');