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

[thymikee]

Summary

• Replaces scripts/build-android-snapshot-helper.sh / build-android-ime-helper.sh / package-android-snapshot-helper.sh / package-android-ime-helper.sh (366 lines, ~75% duplicated) with scripts/build-android-helper.sh (158 lines) + scripts/package-android-helper.sh (136 lines), net −72 LOC.
• Helper is selected via AGENT_DEVICE_ANDROID_HELPER=snapshot|ime (used by package.json/CI) or a first positional arg, mirroring scripts/build-xcuitest-apple.sh's AGENT_DEVICE_XCUITEST_PLATFORM pattern.
• Per-helper differences (HELPER_DIR/PACKAGE_NAME, snapshot's test-compile+run step, ime's aapt2 compile resource step, and the manifest JSON field sets) live in plain case blocks — no shared abstraction over the divergent bits.
• All package.json entry points (build:android-snapshot-helper, package:android-snapshot-helper[:npm], build:android-ime-helper, package:android-ime-helper[:npm], build:android, prepack) keep their names and output paths — only their bodies now set the env var and point at the shared script names.
• Updated .github/workflows/release-android-snapshot-helper.yml (only workflow referencing the old filenames) and both helper READMEs.

Closes #1461

Verification

Ran locally with a real Android SDK (ANDROID_HOME set, build-tools 36.0.0, android-36 platform, JDK 17).

Build + package succeeded on both main and this branch for both helpers, including via both selection forms (AGENT_DEVICE_ANDROID_HELPER=snapshot ... and sh build-android-helper.sh snapshot ...).

classes.dex SHA-256 — identical on main vs. branch:

snapshot-helper: 9f8dab5199c6483b3daf49d3c1274fdbbfde6a2b47c17a968c4c43f3d5176efd
ime-helper:      f3e8dcaf2ff462133326cd5615f3fa4bbe06c6c2dbd5e5a0144f2e9fca85814a

unzip -l listing — snapshot-helper, main:

       40  01-01-1980 00:00   resources.arsc
      285  07-28-2026 16:50   META-INF/MANIFEST.MF
      412  07-28-2026 16:50   META-INF/ANDROIDD.SF
     1298  07-28-2026 16:50   META-INF/ANDROIDD.RSA
     1916  01-01-1980 00:00   AndroidManifest.xml
    32500  07-28-2026 16:49   classes.dex
    36451                     6 files

unzip -l listing — snapshot-helper, this branch:

       40  01-01-1980 00:00   resources.arsc
      285  07-28-2026 16:53   META-INF/MANIFEST.MF
      412  07-28-2026 16:53   META-INF/ANDROIDD.SF
     1298  07-28-2026 16:53   META-INF/ANDROIDD.RSA
     1916  01-01-1980 00:00   AndroidManifest.xml
    32500  07-28-2026 16:53   classes.dex
    36451                     6 files

Only the META-INF/* timestamps differ (each signing run stamps its own signature files) — entry names, sizes, and file count are identical. Same result for the ime-helper (7 entries, all sizes/names matched, only signature timestamps differ).

Manifest JSON — identical on main vs. branch except sha256 (expected: the APK signature, and therefore its hash, differs per signing run since the debug key produces a different signature each run). All other fields (packageName, versionCode, instrumentationRunner/serviceComponent, minSdk/targetSdk, outputFormat/statusProtocol/installArgs for snapshot, broadcastProtocol for ime) matched exactly.

Gates:

• pnpm check:tooling — green (lint, typecheck, layering, depgraph, production-exports, mcp-metadata, build, bundle-owner-files all pass).
• pnpm build:android — succeeds locally end-to-end, producing android/snapshot-helper/dist/* and android/ime-helper/dist/* at the unchanged paths.

Android SDK was available in this environment, so both the byte-level comparison and pnpm build:android were run directly rather than deferred — no additional CI/human verification should be needed for the build itself, though the release-android-snapshot-helper.yml workflow change is still worth a real CI run before the next release to confirm the AGENT_DEVICE_ANDROID_HELPER: snapshot env var wiring works end-to-end in Actions.

Test plan

• pnpm check:tooling
• pnpm build:android (local, real Android SDK)
• Byte-level APK content comparison (main vs. branch, both helpers)
• Both helper-selection forms exercised (env var, first positional arg)
• release-android-snapshot-helper.yml workflow run in real CI (not exercised here — recommend confirming on the next release)

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.87 MB	1.87 MB	-213 B
JS gzip	598.9 kB	598.8 kB	-128 B
npm tarball	714.6 kB	714.5 kB	-107 B
npm unpacked	2.50 MB	2.50 MB	-45 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	29.4 ms	30.5 ms	+1.1 ms
CLI --help	60.6 ms	61.7 ms	+1.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/reporting.js	-381 B	-156 B
dist/src/session.js	+328 B	+79 B
dist/src/cli-help.js	-160 B	-51 B

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-1466/
Built to branch gh-pages at 2026-07-28 15:03 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[thymikee]

Reviewed clean at df25baddd831c54adcbc424224b1233d3222bfa1.

The shared Android helper scripts retain each helper’s distinct compile/test/resource/package behavior and preserve public package-script names and output paths. The PR includes real Android SDK builds for both selectors plus artifact-equivalence evidence; checks are green. Ready for human review.