build(android): unify the 4 helper build/package scripts behind one parameterized pair

.github/workflows/release-android-snapshot-helper.yml

@@ -72,10 +72,11 @@ jobs:
         id: package
         env:
           RELEASE_ASSET_DIR: ${{ github.workspace }}/.tmp/release-assets
+          AGENT_DEVICE_ANDROID_HELPER: snapshot
         run: |
           set -euo pipefail
           mkdir -p "${RELEASE_ASSET_DIR}"
-          sh ./scripts/package-android-snapshot-helper.sh \
+          sh ./scripts/package-android-helper.sh \
             "${{ steps.meta.outputs.version }}" \
             "${{ steps.meta.outputs.tag }}" \
             "${RELEASE_ASSET_DIR}"

.gitignore

@@ -40,5 +40,3 @@ android/snapshot-helper/build/
 android/snapshot-helper/dist/
 android/ime-helper/build/
 android/ime-helper/dist/
-android/multitouch-helper/build/
-android/multitouch-helper/dist/

android/ime-helper/README.md

@@ -21,7 +21,7 @@ verified the same way (bundled npm-packaged dist + version-keyed manifest.json),
 
 ```sh
 VERSION="$(node -p 'require("./package.json").version')"
-sh ./scripts/build-android-ime-helper.sh "$VERSION" .tmp/android-ime-helper
+AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/build-android-helper.sh "$VERSION" .tmp/android-ime-helper
 ```
 
 ## Run

android/snapshot-helper/README.md

@@ -15,7 +15,7 @@ requires a stable signing certificate for `adb install -r` upgrades.
 
 ```sh
 VERSION="$(node -p 'require("./package.json").version')"
-sh ./scripts/build-android-snapshot-helper.sh "$VERSION" .tmp/android-snapshot-helper
+AGENT_DEVICE_ANDROID_HELPER=snapshot sh ./scripts/build-android-helper.sh "$VERSION" .tmp/android-snapshot-helper
 ```
 
 The build uses Android SDK command-line tools directly. It expects `ANDROID_HOME` or

package.json

@@ -88,14 +88,14 @@
     "build:xcuitest:tvos:clean": "pnpm clean:xcuitest:tvos && pnpm build:xcuitest:tvos",
     "build:xcuitest:visionos": "AGENT_DEVICE_XCUITEST_PLATFORM=visionos sh ./scripts/build-xcuitest-apple.sh",
     "build:xcuitest:visionos:clean": "pnpm clean:xcuitest:visionos && pnpm build:xcuitest:visionos",
-    "build:android-snapshot-helper": "sh ./scripts/build-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
-    "package:android-snapshot-helper": "sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
-    "package:android-snapshot-helper:npm": "rm -rf android/snapshot-helper/dist && sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android/snapshot-helper/dist",
+    "build:android-snapshot-helper": "AGENT_DEVICE_ANDROID_HELPER=snapshot sh ./scripts/build-android-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
+    "package:android-snapshot-helper": "AGENT_DEVICE_ANDROID_HELPER=snapshot sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
+    "package:android-snapshot-helper:npm": "rm -rf android/snapshot-helper/dist && AGENT_DEVICE_ANDROID_HELPER=snapshot sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android/snapshot-helper/dist",
     "package:apple-runner:npm": "node scripts/package-apple-runner-source.mjs",
     "build:android": "pnpm package:android-snapshot-helper:npm && pnpm package:android-ime-helper:npm",
-    "build:android-ime-helper": "sh ./scripts/build-android-ime-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
-    "package:android-ime-helper": "sh ./scripts/package-android-ime-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
-    "package:android-ime-helper:npm": "rm -rf android/ime-helper/dist && sh ./scripts/package-android-ime-helper.sh $(node -p \"require('./package.json').version\") android/ime-helper/dist",
+    "build:android-ime-helper": "AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/build-android-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
+    "package:android-ime-helper": "AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-ime-helper",
+    "package:android-ime-helper:npm": "rm -rf android/ime-helper/dist && AGENT_DEVICE_ANDROID_HELPER=ime sh ./scripts/package-android-helper.sh $(node -p \"require('./package.json').version\") android/ime-helper/dist",
     "build:macos-helper": "swift build -c release --package-path apple/macos-helper",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",

scripts/build-android-helper.sh

@@ -0,0 +1,158 @@
+#!/bin/sh
+set -eu
+
+HELPER="${AGENT_DEVICE_ANDROID_HELPER:-}"
+if [ -z "$HELPER" ]; then
+  HELPER="${1:-}"
+  [ "$#" -ge 1 ] && shift
+fi
+
+if [ "$#" -ne 2 ]; then
+  echo "Usage: AGENT_DEVICE_ANDROID_HELPER=<snapshot|ime> $0 <version> <output-dir>" >&2
+  echo "   or: $0 <snapshot|ime> <version> <output-dir>" >&2
+  exit 1
+fi
+
+VERSION="$1"
+OUTPUT_DIR="$2"
+PROJECT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+MIN_SDK=23
+TARGET_SDK=36
+KEYSTORE="$PROJECT_DIR/android/snapshot-helper/debug.keystore"
+
+# Per-helper config: HELPER_DIR/PACKAGE_NAME/APK name always differ; RUN_TEST_CLASS is
+# only set for the snapshot helper (it has a unit test to compile+run); RESOURCE_DIR is
+# only set for the ime helper (it has a res/ dir that needs an aapt2 compile pass).
+case "$HELPER" in
+  snapshot)
+    HELPER_DIR="$PROJECT_DIR/android/snapshot-helper"
+    PACKAGE_NAME="com.callstack.agentdevice.snapshothelper"
+    RUN_TEST_CLASS="com.callstack.agentdevice.snapshothelper.PointerEventScheduleTest"
+    RESOURCE_DIR=""
+    ;;
+  ime)
+    HELPER_DIR="$PROJECT_DIR/android/ime-helper"
+    PACKAGE_NAME="com.callstack.agentdevice.imehelper"
+    RUN_TEST_CLASS=""
+    RESOURCE_DIR="$PROJECT_DIR/android/ime-helper/res"
+    ;;
+  *)
+    echo "Unknown Android helper: '$HELPER' (expected 'snapshot' or 'ime')" >&2
+    exit 1
+    ;;
+esac
+
+APK_BASENAME="agent-device-android-$HELPER-helper-$VERSION.apk"
+
+SDK_ROOT="${ANDROID_HOME:-${ANDROID_SDK_ROOT:-}}"
+if [ -z "$SDK_ROOT" ] || [ ! -d "$SDK_ROOT" ]; then
+  echo "ANDROID_HOME or ANDROID_SDK_ROOT must point to an Android SDK" >&2
+  exit 1
+fi
+
+ANDROID_JAR="$SDK_ROOT/platforms/android-$TARGET_SDK/android.jar"
+if [ ! -f "$ANDROID_JAR" ]; then
+  echo "Missing Android platform jar: $ANDROID_JAR" >&2
+  exit 1
+fi
+
+BUILD_TOOLS_DIR="$(
+  find "$SDK_ROOT/build-tools" -maxdepth 1 -mindepth 1 -type d 2>/dev/null | sort -V | tail -n 1
+)"
+if [ -z "$BUILD_TOOLS_DIR" ] || [ ! -x "$BUILD_TOOLS_DIR/aapt2" ]; then
+  echo "Missing Android build tools under $SDK_ROOT/build-tools" >&2
+  exit 1
+fi
+
+VERSION_CODE="$(
+  printf '%s\n' "$VERSION" | awk -F. '
+    /^[0-9]+[.][0-9]+[.][0-9]+$/ {
+      print ($1 * 1000000) + ($2 * 1000) + $3
+      next
+    }
+    { print 1 }
+  '
+)"
+
+BUILD_DIR="$HELPER_DIR/build"
+CLASSES_DIR="$BUILD_DIR/classes"
+TEST_CLASSES_DIR="$BUILD_DIR/test-classes"
+DEX_DIR="$BUILD_DIR/dex"
+RES_COMPILED_DIR="$BUILD_DIR/res-compiled"
+UNSIGNED_APK="$BUILD_DIR/helper-unsigned.apk"
+ALIGNED_APK="$BUILD_DIR/helper-aligned.apk"
+APK_PATH="$OUTPUT_DIR/$APK_BASENAME"
+
+rm -rf "$BUILD_DIR"
+mkdir -p "$CLASSES_DIR" "$TEST_CLASSES_DIR" "$DEX_DIR" "$RES_COMPILED_DIR" "$OUTPUT_DIR"
+
+javac \
+  --release 11 \
+  -classpath "$ANDROID_JAR" \
+  -d "$CLASSES_DIR" \
+  $(find "$HELPER_DIR/src/main/java" -name '*.java' | sort)
+
+if [ -n "$RUN_TEST_CLASS" ]; then
+  javac \
+    --release 11 \
+    -classpath "$ANDROID_JAR:$CLASSES_DIR" \
+    -d "$TEST_CLASSES_DIR" \
+    $(find "$HELPER_DIR/src/test/java" -name '*.java' | sort)
+
+  java \
+    -classpath "$ANDROID_JAR:$CLASSES_DIR:$TEST_CLASSES_DIR" \
+    "$RUN_TEST_CLASS"
+fi
+
+"$BUILD_TOOLS_DIR/d8" \
+  --min-api "$MIN_SDK" \
+  --classpath "$ANDROID_JAR" \
+  --output "$DEX_DIR" \
+  $(find "$CLASSES_DIR" -name '*.class' | sort)
+
+if [ -n "$RESOURCE_DIR" ]; then
+  "$BUILD_TOOLS_DIR/aapt2" compile \
+    --dir "$RESOURCE_DIR" \
+    -o "$RES_COMPILED_DIR"
+
+  "$BUILD_TOOLS_DIR/aapt2" link \
+    --manifest "$HELPER_DIR/AndroidManifest.xml" \
+    -I "$ANDROID_JAR" \
+    --min-sdk-version "$MIN_SDK" \
+    --target-sdk-version "$TARGET_SDK" \
+    --version-code "$VERSION_CODE" \
+    --version-name "$VERSION" \
+    -R "$RES_COMPILED_DIR"/*.flat \
+    -o "$UNSIGNED_APK"
+else
+  "$BUILD_TOOLS_DIR/aapt2" link \
+    --manifest "$HELPER_DIR/AndroidManifest.xml" \
+    -I "$ANDROID_JAR" \
+    --min-sdk-version "$MIN_SDK" \
+    --target-sdk-version "$TARGET_SDK" \
+    --version-code "$VERSION_CODE" \
+    --version-name "$VERSION" \
+    -o "$UNSIGNED_APK"
+fi
+
+zip -q -j "$UNSIGNED_APK" "$DEX_DIR/classes.dex"
+
+"$BUILD_TOOLS_DIR/zipalign" -f 4 "$UNSIGNED_APK" "$ALIGNED_APK"
+
+if [ ! -f "$KEYSTORE" ]; then
+  echo "Missing Android helper signing keystore: $KEYSTORE" >&2
+  exit 1
+fi
+
+"$BUILD_TOOLS_DIR/apksigner" sign \
+  --ks "$KEYSTORE" \
+  --ks-pass pass:android \
+  --key-pass pass:android \
+  --out "$APK_PATH" \
+  "$ALIGNED_APK"
+
+"$BUILD_TOOLS_DIR/apksigner" verify --min-sdk-version "$MIN_SDK" "$APK_PATH"
+
+printf 'apk=%s\n' "$APK_PATH"
+printf 'package=%s\n' "$PACKAGE_NAME"
+printf 'version_code=%s\n' "$VERSION_CODE"