@hot-updater/android-helper 1.2.0-rc.12 → 1.2.0-rc.13

package/dist/index.cjs

@@ -31,6 +31,9 @@ let os = require("os");
 os = __toESM(os, 1);
 let jszip = require("jszip");
 jszip = __toESM(jszip, 1);
+let module$1 = require("module");
+let _hot_updater_protocol_native_artifact = require("@hot-updater/protocol/native-artifact");
+let fast_xml_parser = require("fast-xml-parser");
 let crypto = require("crypto");
 crypto = __toESM(crypto, 1);
 let stream_promises = require("stream/promises");
@@ -116,10 +119,34 @@ function getTaskNames(moduleName, tasks) {
 * Get gradle wrapper command based on platform
 */
 const getGradleWrapper = () => process.platform.startsWith("win") ? "gradlew.bat" : "./gradlew";
+/** A variable a POSIX shell can't name, as the signing environment's are. */
+const isShellName = (name) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+/**
+* The command that runs the wrapper with `env`. The wrapper's `#!/bin/sh` is
+* dash on Debian and Ubuntu, which silently drops a variable whose name isn't
+* a shell name, such as `ORG_GRADLE_PROJECT_android.injected.signing.store.file`:
+* the build then signs with the project's own config. bash keeps them.
+*/
+const gradleCommand = (env) => {
+	const wrapper = getGradleWrapper();
+	return wrapper === "./gradlew" && Object.keys(env ?? {}).some((name) => !isShellName(name)) ? ["bash", [wrapper]] : [wrapper, []];
+};
 /**
 * Run gradle build with specified tasks and arguments
 */
-async function runGradle({ tasks, logPrefix, args, env, androidProjectPath, appModuleName, logHeader = [] }) {
+async function runGradle(args) {
+	const logFilePath = await runGradleTasks(args);
+	return {
+		...await findBuildDirectory({
+			androidProjectPath: args.androidProjectPath,
+			moduleName: args.appModuleName,
+			tasks: args.tasks
+		}),
+		logFilePath
+	};
+}
+/** Runs tasks that leave no artifact to find, and returns the build log, or null. */
+async function runGradleTasks({ tasks, logPrefix, args, env, androidProjectPath, appModuleName, logHeader = [] }) {
 	const gradleArgs = getTaskNames(appModuleName, tasks);
 	gradleArgs.push("-x", "lint");
 	if (args.extraParams) gradleArgs.push(...args.extraParams);
@@ -138,7 +165,8 @@ async function runGradle({ tasks, logPrefix, args, env, androidProjectPath, appM
 	});
 	let logFilePath = null;
 	try {
-		const gradle = (0, execa.execa)(getGradleWrapper(), gradleArgs, {
+		const [command, prefix] = gradleCommand(env);
+		const gradle = (0, execa.execa)(command, [...prefix, ...gradleArgs], {
 			cwd: androidProjectPath,
 			env,
 			all: true,
@@ -162,14 +190,7 @@ async function runGradle({ tasks, logPrefix, args, env, androidProjectPath, appM
 	} finally {
 		await logger.close();
 	}
-	return {
-		...await findBuildDirectory({
-			androidProjectPath,
-			moduleName: appModuleName,
-			tasks
-		}),
-		logFilePath
-	};
+	return logFilePath;
 }
 /**
 * Find the build output directory and artifact path
@@ -462,21 +483,297 @@ const readBuiltVersionCode = async ({ artifactPath, androidProjectPath }) => {
 	}
 };
 //#endregion
+//#region src/utils/sandboxManifest.ts
+const MAIN = "android.intent.action.MAIN";
+const LAUNCHER = "android.intent.category.LAUNCHER";
+const SHORTCUTS = "android.app.shortcuts";
+const ANDROID = "android:";
+const asArray = (value) => value === void 0 || value === null || value === "" ? [] : Array.isArray(value) ? value : [value];
+const attribute = (element, name) => {
+	const value = element[`${ANDROID}${name}`];
+	return typeof value === "string" ? value : void 0;
+};
+const filtersOf = (component) => asArray(component["intent-filter"]).map((filter) => ({
+	actions: asArray(filter["action"]),
+	categories: asArray(filter["category"]),
+	data: asArray(filter["data"]),
+	attributes: Object.fromEntries(Object.entries(filter).filter(([name]) => name.startsWith(ANDROID)))
+}));
+const opensAsLauncher = ({ actions, categories }) => actions.some((action) => attribute(action, "name") === MAIN) && categories.some((category) => attribute(category, "name") === LAUNCHER);
+/** Task settings a sandbox activity can't share a task with: what, and how to fix it. */
+const taskRefusal = (name, activity) => {
+	const launchMode = attribute(activity, "launchMode");
+	if (launchMode === "singleInstance" || launchMode === "singleInstancePerTask") return `Sandbox builds don't support launchMode ${launchMode} on the launcher ${name}.\nUse singleTask or the default launch mode.`;
+	if (attribute(activity, "taskAffinity") !== void 0) return `Sandbox builds don't support taskAffinity on the launcher ${name}.\nRemove it from this build variant.`;
+	const documents = attribute(activity, "documentLaunchMode");
+	if (documents !== void 0 && documents !== "none") return `Sandbox builds don't support documentLaunchMode ${documents} on the launcher ${name}.\nRemove it from this build variant.`;
+	return null;
+};
+/**
+* The launcher entry of a variant's merged manifest, which already holds what
+* its flavors, build type and libraries declare. It refuses what a sandbox
+* build can't take over: none or several entries, a filter it can't move whole,
+* and task settings its activity can't share a task with.
+*/
+const resolveSandboxLauncher = (mergedManifest) => {
+	const application = new fast_xml_parser.XMLParser({
+		ignoreAttributes: false,
+		attributeNamePrefix: ""
+	}).parse(mergedManifest)?.manifest?.application;
+	const activities = asArray(application?.["activity"]);
+	const aliases = asArray(application?.["activity-alias"]);
+	const entries = [...activities.map((element) => ({
+		kind: "activity",
+		element
+	})), ...aliases.map((element) => ({
+		kind: "activity-alias",
+		element
+	}))].flatMap(({ kind, element }) => {
+		const filters = filtersOf(element).filter(opensAsLauncher);
+		return filters.length === 0 ? [] : [{
+			kind,
+			element,
+			filters
+		}];
+	});
+	const names = entries.map(({ element }) => attribute(element, "name") ?? "?");
+	if (entries.length === 0) throw new Error("A sandbox build needs a launcher, and this variant's manifest has none.\nAdd a MAIN + LAUNCHER intent filter to an activity.");
+	if (entries.length > 1) throw new Error(`A sandbox build needs one launcher, and this variant has ${names.length}: ${names.join(", ")}.\nKeep one for this build variant.`);
+	const { kind, element, filters } = entries[0];
+	const name = names[0];
+	if (filters.length > 1) throw new Error(`The launcher ${name} has ${filters.length} MAIN + LAUNCHER filters, and a sandbox build can move one.\nKeep one for this build variant.`);
+	if (attribute(element, "enabled") === "false") throw new Error(`The launcher ${name} is disabled in the manifest, and a sandbox build can't tell when it would open.\nEnable it for this build variant.`);
+	const targetActivity = kind === "activity-alias" ? attribute(element, "targetActivity") : void 0;
+	const activity = kind === "activity" ? element : activities.find((item) => attribute(item, "name") === targetActivity);
+	if (activity === void 0) throw new Error(`The launcher ${name} targets ${targetActivity ?? "no activity"}, which this variant's manifest doesn't declare.\nFix its android:targetActivity.`);
+	const refusal = taskRefusal(name, activity);
+	if (refusal !== null) throw new Error(refusal);
+	const shortcuts = asArray(element["meta-data"]).find((item) => attribute(item, "name") === SHORTCUTS);
+	const label = attribute(element, "label");
+	const icon = attribute(element, "icon");
+	const roundIcon = attribute(element, "roundIcon");
+	const shortcutsResource = shortcuts && attribute(shortcuts, "resource");
+	return {
+		kind,
+		name,
+		...targetActivity === void 0 ? {} : { targetActivity },
+		filter: filters[0],
+		...label === void 0 ? {} : { label },
+		...icon === void 0 ? {} : { icon },
+		...roundIcon === void 0 ? {} : { roundIcon },
+		...shortcutsResource === void 0 ? {} : { shortcuts: shortcutsResource }
+	};
+};
+const xml = (text) => text.replace(/&/gu, "&amp;").replace(/"/gu, "&quot;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
+const attributesOf = (element) => Object.entries(element).filter(([, value]) => typeof value === "string").map(([name, value]) => ` ${name}="${xml(value)}"`).join("");
+/** A launcher filter, element by element: the merger matches a filter by content. */
+const filterXml = ({ actions, categories, data, attributes }, extra = "") => [
+	`<intent-filter${attributesOf(attributes)}${extra}>`,
+	...actions.map((item) => `  <action${attributesOf(item)} />`),
+	...categories.map((item) => `  <category${attributesOf(item)} />`),
+	...data.map((item) => `  <data${attributesOf(item)} />`),
+	"</intent-filter>"
+].map((line) => `      ${line}`).join("\n");
+const optional = (name, value) => value === void 0 ? "" : ` android:${name}="${xml(value)}"`;
+/**
+* The manifest a sandbox build overlays on the app's. `tools:replace` wins over
+* a channel the app's manifest sets, as an Expo project's does. The launcher's
+* filter, label, icon and static shortcuts move to the sandbox's activity, which
+* also takes the links of `appId`'s URL scheme; the rest of the app's activity
+* stays, so its own links still reach it. `appId` is the scheme's `packageName`,
+* before the `.sandbox` suffix, so a preview link needs no build to derive it.
+*/
+const sandboxManifestOverlay = ({ channel, appId, launcher }) => `<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
+  <application>
+    <meta-data android:name="com.hotupdater.CHANNEL" android:value="${xml(channel)}" tools:replace="android:value" />
+    <meta-data android:name="${_hot_updater_protocol_native_artifact.SANDBOX_META_DATA}" android:value="true" />
+    <activity android:name="${_hot_updater_protocol_native_artifact.SANDBOX_ACTIVITY}" android:exported="true" android:launchMode="singleTop" android:theme="@style/HotUpdaterSandboxTheme" android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize|smallestScreenSize|uiMode"${optional("label", launcher.label)}${optional("icon", launcher.icon)}${optional("roundIcon", launcher.roundIcon)}>
+${filterXml(launcher.filter)}
+      <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="${(0, _hot_updater_protocol_native_artifact.sandboxUrlSchemeOf)(appId)}" />
+      </intent-filter>
+      <meta-data android:name="com.hotupdater.sandbox.HOST_ACTIVITY" android:value="${xml(launcher.name)}" />${launcher.shortcuts === void 0 ? "" : `\n      <meta-data android:name="${SHORTCUTS}" android:resource="${xml(launcher.shortcuts)}" />`}
+    </activity>
+    <${launcher.kind} android:name="${xml(launcher.name)}"${optional("targetActivity", launcher.targetActivity)}>
+${filterXml(launcher.filter, " tools:node=\"remove\"")}${launcher.shortcuts === void 0 ? "" : `\n      <meta-data android:name="${SHORTCUTS}" tools:node="remove" />`}
+    </${launcher.kind}>
+    <provider android:name="com.hotupdater.HotUpdaterSandboxProcess" android:authorities="\${applicationId}.hotupdater.sandbox" android:exported="false" />
+  </application>
+</manifest>
+`;
+/** Newest first: the manifest of the task that ran last, under `directory`. */
+const manifestsUnder = (directory) => {
+	if (!fs.default.existsSync(directory)) return [];
+	return fs.default.readdirSync(directory, { recursive: true }).map(String).filter((file) => path.default.basename(file) === "AndroidManifest.xml").map((file) => path.default.join(directory, file)).sort((a, b) => fs.default.statSync(b).mtimeMs - fs.default.statSync(a).mtimeMs);
+};
+/** The Gradle task that merges a variant's manifest. */
+const mergeManifestTask = (variant) => `process${variant.charAt(0).toUpperCase()}${variant.slice(1)}MainManifest`;
+/**
+* The manifest the merge task of `variant` wrote: AGP 7 and 8 keep it under
+* `build/intermediates/merged_manifest`, in a directory per variant.
+*/
+const readMergedManifest = ({ androidProjectPath, appModuleName, variant }) => {
+	const variantDirectory = `${variant.charAt(0).toLowerCase()}${variant.slice(1)}`;
+	const intermediates = path.default.join(androidProjectPath, appModuleName, "build/intermediates");
+	const [manifest] = ["merged_manifest", "merged_manifests"].flatMap((name) => manifestsUnder(path.default.join(intermediates, name, variantDirectory)));
+	if (manifest === void 0) throw new Error(`Couldn't find the merged manifest of ${variant} under android/${appModuleName}/build/intermediates.\nBuild the variant once, then try again.`);
+	return fs.default.readFileSync(manifest, "utf-8");
+};
+//#endregion
+//#region src/utils/sandboxGradle.ts
+const UNSUPPORTED_DSL = `Sandbox builds don't support AGP 9's default DSL yet.
+Set android.newDsl=false in android/gradle.properties.`;
+/** The message when the build type has a manifest the overlay would replace. */
+const ownManifest = (manifest) => `A sandbox build can't merge with ${manifest}.\nMove what it declares to src/main/AndroidManifest.xml.`;
+/** Text as a single-quoted Groovy string. */
+const groovyString = (text) => `'${text.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'").replace(/\n/gu, "\\n")}'`;
+/**
+* The init script of one sandbox build, so no project file changes: on the app
+* module, it appends the sandbox's suffix to defaultConfig, where AGP puts any
+* flavor's and build type's after it, and adds `overlay` to the variant's build
+* type. It runs in `finalizeDsl`, after the project's own settings.
+*/
+const sandboxInitScript = ({ appModuleName, variant, overlay, minVersionCode }) => `// Written by hot-updater for one sandbox build.
+def appModule = ${groovyString(`:${appModuleName}`)}
+def variant = ${groovyString(variant.toLowerCase())}
+def overlay = new File(${groovyString(overlay)})
+def minVersionCode = ${minVersionCode ?? "null"}
+allprojects { project ->
+  if (project.path != appModule) return
+  project.plugins.withId('com.android.application') {
+    def components = project.extensions.getByName('androidComponents')
+    if (components.pluginVersion.major >= 9 && project.findProperty('android.newDsl')?.toString() != 'false') {
+      throw new GradleException(${groovyString(UNSUPPORTED_DSL)})
+    }
+    components.finalizeDsl { dsl ->
+      def buildType = dsl.buildTypes.collect { it.name }
+        .findAll { variant.endsWith(it.toLowerCase()) }
+        .max { it.length() }
+      if (buildType == null) {
+        throw new GradleException("No build type of \${project.path} builds variant \${variant}.")
+      }
+      def manifest = dsl.sourceSets.getByName(buildType).manifest
+      def own = manifest.srcFile
+      if (own.exists()) {
+        throw new GradleException(${groovyString(ownManifest("@MANIFEST@"))}.replace('@MANIFEST@', 'android/' + project.rootDir.toPath().relativize(own.toPath())))
+      }
+      dsl.defaultConfig.applicationIdSuffix = (dsl.defaultConfig.applicationIdSuffix ?: '') + ${groovyString(_hot_updater_protocol_native_artifact.SANDBOX_APPLICATION_ID_SUFFIX)}
+      manifest.srcFile(overlay)
+      if (minVersionCode != null) {
+        dsl.defaultConfig.versionCode = Math.max(dsl.defaultConfig.versionCode ?: 0, minVersionCode)
+        dsl.productFlavors.each { flavor ->
+          if (flavor.versionCode != null) flavor.versionCode = Math.max(flavor.versionCode, minVersionCode)
+        }
+      }
+    }
+  }
+}
+`;
+/**
+* Runs `build` with the Gradle arguments of a scheme: none for a normal one. A
+* sandbox scheme's attach the SDK's sandbox layer and name the init script,
+* written outside the project with its manifest overlay, and removed after.
+* Kotlin compiles from scratch, since the sandbox layer's sources come and go.
+* `readEffectiveManifest` is the variant's merged manifest before the overlay,
+* which the overlay takes the launcher from.
+*/
+const withSandboxGradleArgs = async (scheme, readEffectiveManifest, build, { minVersionCode } = {}) => {
+	if (!scheme.sandbox) return build([]);
+	if (!scheme.packageName) throw new Error(`The sandbox scheme ${scheme.hotUpdaterSchemeName} sets no packageName, which its URL scheme comes from.\nSet packageName on the scheme.`);
+	const launcher = resolveSandboxLauncher(await readEffectiveManifest());
+	const directory = await fs.default.promises.mkdtemp(path.default.join(os.default.tmpdir(), "hot-updater-sandbox-"));
+	try {
+		const overlay = path.default.join(directory, "AndroidManifest.xml");
+		const initScript = path.default.join(directory, "sandbox.init.gradle");
+		await fs.default.promises.writeFile(overlay, sandboxManifestOverlay({
+			channel: (0, _hot_updater_protocol_native_artifact.sandboxChannelOf)(scheme.hotUpdaterSchemeName),
+			appId: scheme.packageName,
+			launcher
+		}));
+		await fs.default.promises.writeFile(initScript, sandboxInitScript({
+			appModuleName: scheme.appModuleName,
+			variant: scheme.variant,
+			overlay,
+			...minVersionCode === void 0 ? {} : { minVersionCode }
+		}));
+		return await build([
+			"--init-script",
+			initScript,
+			`-PhotUpdaterSandbox=${scheme.hotUpdaterSchemeName}`,
+			"-Pkotlin.incremental=false"
+		]);
+	} finally {
+		await fs.default.promises.rm(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+};
+/** The major version of the Android Gradle Plugin the project pins, or null. */
+const readAgpMajor = (androidProjectPath) => {
+	const rootBuild = ["build.gradle", "build.gradle.kts"].map((file) => path.default.join(androidProjectPath, file)).filter((file) => fs.default.existsSync(file)).map((file) => fs.default.readFileSync(file, "utf-8")).join("\n");
+	const pinned = /com\.android\.tools\.build:gradle:(\d+)/u.exec(rootBuild);
+	if (pinned) return Number(pinned[1]);
+	try {
+		const manifest = (0, module$1.createRequire)(path.default.join(androidProjectPath, "package.json")).resolve("react-native/package.json");
+		const catalog = fs.default.readFileSync(path.default.join(path.default.dirname(manifest), "gradle/libs.versions.toml"), "utf-8");
+		const agp = /^\s*agp\s*=\s*"(\d+)/mu.exec(catalog);
+		return agp ? Number(agp[1]) : null;
+	} catch {
+		return null;
+	}
+};
+/**
+* Why a sandbox build of a scheme can't work, read from the project's files
+* before anything is built, or null. The init script checks again, with what
+* Gradle actually resolved.
+*/
+const findSandboxGradleBlocker = ({ variant = "Release", appModuleName = "app" }) => {
+	const androidProjectPath = path.default.join((0, _hot_updater_cli_tools.getCwd)(), "android");
+	if (!fs.default.existsSync(androidProjectPath)) return null;
+	const properties = path.default.join(androidProjectPath, "gradle.properties");
+	const newDsl = fs.default.existsSync(properties) ? /^\s*android\.newDsl\s*=\s*(\S+)/mu.exec(fs.default.readFileSync(properties, "utf-8"))?.[1] : void 0;
+	if (newDsl === "true" || newDsl === void 0 && (readAgpMajor(androidProjectPath) ?? 0) >= 9) return UNSUPPORTED_DSL;
+	const buildType = /([A-Z]?[a-z0-9]+)$/u.exec(variant)?.[1]?.toLowerCase();
+	const manifest = `${appModuleName}/src/${buildType}/AndroidManifest.xml`;
+	return buildType && fs.default.existsSync(path.default.join(androidProjectPath, manifest)) ? ownManifest(`android/${manifest}`) : null;
+};
+//#endregion
 //#region src/buildAndroid.ts
-const buildAndroid = async ({ schemeConfig, minBundleId = (0, _hot_updater_cli_tools.createMinBundleId)(), credentials, logHeader }) => {
+const buildAndroid = async ({ schemeConfig, minBundleId = (0, _hot_updater_cli_tools.createMinBundleId)(), credentials, logHeader, minVersionCode }) => {
 	const androidProjectPath = path.default.join((0, _hot_updater_cli_tools.getCwd)(), "android");
-	const result = await runGradle({
-		args: { extraParams: [`-PMIN_BUNDLE_ID=${minBundleId}`] },
-		env: await resolveGradleSigningEnv({
-			schemeConfig,
-			credentials
-		}),
+	const env = await resolveGradleSigningEnv({
+		schemeConfig,
+		credentials
+	});
+	const result = await withSandboxGradleArgs(schemeConfig, async () => {
+		await runGradleTasks({
+			args: { extraParams: [`-PMIN_BUNDLE_ID=${minBundleId}`] },
+			env,
+			appModuleName: schemeConfig.appModuleName,
+			tasks: [mergeManifestTask(schemeConfig.variant)],
+			logPrefix: `android-${schemeConfig.hotUpdaterSchemeName}-manifest`,
+			androidProjectPath,
+			logHeader
+		});
+		return readMergedManifest({
+			androidProjectPath,
+			appModuleName: schemeConfig.appModuleName,
+			variant: schemeConfig.variant
+		});
+	}, (sandboxArgs) => runGradle({
+		args: { extraParams: [`-PMIN_BUNDLE_ID=${minBundleId}`, ...sandboxArgs] },
+		env,
 		appModuleName: schemeConfig.appModuleName,
 		tasks: schemeConfig.aab ? [`bundle${schemeConfig.variant}`] : [`assemble${schemeConfig.variant}`],
 		logPrefix: `android-${schemeConfig.hotUpdaterSchemeName}-build`,
 		androidProjectPath,
 		logHeader
-	});
+	}), minVersionCode === void 0 ? {} : { minVersionCode });
 	return {
 		...result,
 		builtApp: await readBuiltApp({
@@ -486,6 +783,105 @@ const buildAndroid = async ({ schemeConfig, minBundleId = (0, _hot_updater_cli_t
 	};
 };
 //#endregion
+//#region src/device.ts
+/** The SDK's adb, or the one on the PATH without an SDK in the environment. */
+const adbPath = () => {
+	const sdk = process.env["ANDROID_HOME"] || process.env["ANDROID_SDK_ROOT"];
+	const executable = process.platform.startsWith("win") ? "adb.exe" : "adb";
+	const fromSdk = sdk && path.default.join(sdk, "platform-tools", executable);
+	return fromSdk && fs.default.existsSync(fromSdk) ? fromSdk : executable;
+};
+const adb = async (args) => {
+	try {
+		return (await (0, execa.execa)(adbPath(), args)).stdout;
+	} catch (error) {
+		const { code, stderr, stdout, shortMessage } = error;
+		if (code === "ENOENT") throw new Error("adb isn't installed.\nInstall Android platform-tools, or set ANDROID_HOME.");
+		throw new Error(stderr?.trim() || stdout?.trim() || shortMessage || String(error));
+	}
+};
+/** What `adb devices` lists. */
+const listAdbDevices = async () => (await adb(["devices"])).split("\n").slice(1).map((line) => line.trim().split(/\s+/u)).flatMap(([serial, state]) => serial && state ? [{
+	serial,
+	state
+}] : []);
+/**
+* The device to install on: `serial`, as adb's own `ANDROID_SERIAL` names it
+* too, or else the only one that takes commands.
+*/
+const selectAdbDevice = (devices, serial = process.env["ANDROID_SERIAL"] || void 0) => {
+	if (serial !== void 0) {
+		const device = devices.find((candidate) => candidate.serial === serial);
+		if (device === void 0) throw new Error(`${serial} isn't connected.\nList them: adb devices`);
+		if (device.state !== "device") throw new Error(`${serial} is ${device.state}.\nList them: adb devices`);
+		return device;
+	}
+	const ready = devices.filter(({ state }) => state === "device");
+	const [only] = ready;
+	if (only === void 0) throw new Error("No Android device or emulator is connected.\nStart an emulator or connect a phone, then run this again.");
+	if (ready.length > 1) throw new Error([
+		`${ready.length} Android devices are connected:`,
+		...ready.map(({ serial }) => `  ${serial}`),
+		"Pick one with --device <serial>."
+	].join("\n"));
+	return only;
+};
+/** A failure adb reports for an install another install of the app stands in the way of. */
+const NEEDS_UNINSTALL = /^INSTALL_FAILED_(UPDATE_INCOMPATIBLE|VERSION_DOWNGRADE)\b/u;
+const LAUNCHER_CATEGORY = "android.intent.category.LAUNCHER";
+/** An application ID's form, checked before it reaches the device's shell. */
+const APP_ID = /^[A-Za-z][A-Za-z0-9_.]*$/u;
+/** `<application ID>/<activity>`, as `resolve-activity --brief` prints it. */
+const ACTIVITY = /^[A-Za-z0-9_.]+\/[A-Za-z0-9_.$]+$/u;
+/**
+* Installs an APK on a device, and opens its launcher activity. `appId` is
+* the APK's own application ID, whatever suffix its build gave it.
+*/
+const installOnAndroidDevice = async ({ serial, apkPath, appId }) => {
+	if (!APP_ID.test(appId)) throw new Error(`The APK's application ID isn't valid: ${appId}`);
+	try {
+		await adb([
+			"-s",
+			serial,
+			"install",
+			"-r",
+			apkPath
+		]);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const failure = /Failure \[([^\]]+)\]/u.exec(message)?.[1] ?? message;
+		throw new Error(NEEDS_UNINSTALL.test(failure) ? `The installed ${appId} can't be replaced: ${failure}\nUninstall it: adb -s ${serial} uninstall ${appId}` : `adb couldn't install the APK: ${failure}`);
+	}
+	const activity = (await adb([
+		"-s",
+		serial,
+		"shell",
+		"cmd",
+		"package",
+		"resolve-activity",
+		"--brief",
+		"-c",
+		LAUNCHER_CATEGORY,
+		appId
+	])).trim().split("\n").at(-1)?.trim();
+	if (activity === void 0 || !ACTIVITY.test(activity)) throw new Error(`${appId} is installed, and has no launcher activity to open.`);
+	const started = await adb([
+		"-s",
+		serial,
+		"shell",
+		"am",
+		"start",
+		"-a",
+		"android.intent.action.MAIN",
+		"-c",
+		LAUNCHER_CATEGORY,
+		"-n",
+		`'${activity}'`
+	]);
+	const error = /^Error: .*$/mu.exec(started)?.[0];
+	if (error !== void 0) throw new Error(`${appId} is installed, and didn't open. ${error}`);
+};
+//#endregion
 //#region src/uploadToPlay.ts
 const API_URL = "https://androidpublisher.googleapis.com";
 /** Where Google serves resumable upload sessions, as its docs show both. */
@@ -708,11 +1104,9 @@ const checkPlayAccess = async ({ serviceAccount: { json }, packageName, fetch =
 	}
 };
 /**
-* Whether Google Play's internal testing track already releases the
-* `.aab`'s version code, as when a reused native build was uploaded
-* before. It reads the track in an edit it then deletes, changing nothing.
+* Reads the app in an edit it then deletes, changing nothing.
 */
-const findPlayInternalRelease = async ({ versionCode, packageName, serviceAccount: { json }, fetch = globalThis.fetch }) => {
+const readInEdit = async ({ packageName, serviceAccount: { json }, fetch }, read) => {
 	const { app, request } = createPlayClient({
 		json,
 		packageName,
@@ -726,8 +1120,7 @@ const findPlayInternalRelease = async ({ versionCode, packageName, serviceAccoun
 	}
 	const edit = `${API_URL}${app}/edits/${encodeURIComponent(editId)}`;
 	try {
-		const { releases = [] } = await request("Reading the internal track", "GET", `${edit}/tracks/${INTERNAL_TRACK}`);
-		return releases.some(({ versionCodes = [] }) => versionCodes.includes(String(versionCode)));
+		return await read(request, edit);
 	} catch (error) {
 		throw explain(error, packageName);
 	} finally {
@@ -735,6 +1128,43 @@ const findPlayInternalRelease = async ({ versionCode, packageName, serviceAccoun
 	}
 };
 /**
+* The status of the internal testing release holding `versionCode`, such as
+* `completed` or `draft`, or null when the track doesn't hold it: never
+* uploaded, or replaced by a newer release, which testers get instead.
+*/
+const readPlayInternalRelease = ({ versionCode, packageName, serviceAccount, fetch = globalThis.fetch }) => readInEdit({
+	packageName,
+	serviceAccount,
+	fetch
+}, async (request, edit) => {
+	const { releases = [] } = await request("Reading the internal track", "GET", `${edit}/tracks/${INTERNAL_TRACK}`);
+	const release = releases.find(({ versionCodes = [] }) => versionCodes.includes(String(versionCode)));
+	return release ? release.status ?? "completed" : null;
+});
+/**
+* Whether Google Play's internal testing track already releases the
+* `.aab`'s version code, as when a reused native build was uploaded before.
+*/
+const findPlayInternalRelease = async (options) => await readPlayInternalRelease(options) !== null;
+/**
+* The highest version code Google Play has taken for the app, on any track,
+* or null with none: a new `.aab` needs one above it.
+*/
+const readPlayHighestVersionCode = ({ packageName, serviceAccount, fetch = globalThis.fetch }) => readInEdit({
+	packageName,
+	serviceAccount,
+	fetch
+}, async (request, edit) => {
+	const { bundles = [] } = await request("Reading the app's bundles", "GET", `${edit}/bundles`);
+	const codes = bundles.flatMap(({ versionCode }) => versionCode ?? []);
+	return codes.length > 0 ? Math.max(...codes) : null;
+});
+/**
+* The link that opts a tester in to the app's testing tracks. A build on the
+* internal track installs through it, for the testers Play Console lists.
+*/
+const playTestingUrl = (packageName) => `https://play.google.com/apps/testing/${encodeURIComponent(packageName)}`;
+/**
 * The common name of every Android debug certificate: Android Studio's and
 * the Android Gradle plugin's (`CN=Android Debug, O=Android, C=US`), and React
 * Native's template `debug.keystore` (`CN=Android Debug, OU=Android,
@@ -1084,9 +1514,16 @@ exports.checkPlayAccess = checkPlayAccess;
 exports.enrichNativeBuildAndroidScheme = enrichNativeBuildAndroidScheme;
 exports.extractBuiltInBundle = extractBuiltInBundle;
 exports.findPlayInternalRelease = findPlayInternalRelease;
+exports.findSandboxGradleBlocker = findSandboxGradleBlocker;
+exports.installOnAndroidDevice = installOnAndroidDevice;
+exports.listAdbDevices = listAdbDevices;
 exports.playConsoleInviteUrl = playConsoleInviteUrl;
+exports.playTestingUrl = playTestingUrl;
 exports.readBuiltApp = readBuiltApp;
 exports.readBuiltPackageName = readBuiltPackageName;
 exports.readBuiltVersionCode = readBuiltVersionCode;
+exports.readPlayHighestVersionCode = readPlayHighestVersionCode;
+exports.readPlayInternalRelease = readPlayInternalRelease;
 exports.resolvePlayUploadServiceAccount = resolvePlayUploadServiceAccount;
+exports.selectAdbDevice = selectAdbDevice;
 exports.uploadToPlay = uploadToPlay;