device-devtools-mcp 0.1.0

package/scripts/android/logs.sh

@@ -0,0 +1,289 @@
+#!/usr/bin/env bash
+# logs.sh — device logs.
+#
+#   logs.sh start                       clear the buffer and begin collecting
+#   logs.sh stop                        stop collecting
+#   logs.sh status                      is it collecting, and since when
+#   logs.sh [--since Ns] [--process P] [--grep S] [--lines N]
+#                                       read what is available
+#   --network                           only lines that look like HTTP requests
+#                                       or responses, from the app under test.
+#                                       THIS IS NOT A PROXY: it filters what the
+#                                       app itself chose to print, so it shows no
+#                                       bodies, no headers the app did not log,
+#                                       and nothing at all from an app that logs
+#                                       none of it. In exchange it needs no CA
+#                                       certificate on the device and certificate
+#                                       pinning cannot block it.
+#                                       The regex is logs.network_pattern.
+#
+# WHY READING WORKS HERE WITHOUT A COLLECTOR, UNLIKE iOS
+#
+# logcat keeps a ring buffer on the device, so the recent past can be asked for
+# after the fact. The iOS adapter cannot do that — idevicesyslog is a live
+# stream with no history — which is why it must start a collector and tell you
+# the history begins now. On Android a read with no collector running still
+# returns real logs, and says where they came from.
+#
+# A collector is still worth starting for a long run. The ring buffer is a few
+# hundred kilobytes per buffer, and a chatty app overruns it in under a minute,
+# so anything older than that is gone. `start` clears the buffer first, which
+# also scopes everything read afterwards to the current run.
+#
+# NO --subsystem
+#
+# That is an os_log concept and has no equivalent here. `--process` filters on
+# the tag or package, and `--grep` on the message, which is what logcat has.
+#
+# exit 0  lines printed, or a lifecycle verb succeeded
+# exit 1  usage error
+# exit 2  environment problem
+# exit 4  nothing matched
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+SINCE=""
+PROCESS=""
+GREP=""
+NETWORK=0
+LINES=""
+VERB="read"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    start|stop|status) VERB="$1"; shift ;;
+    --since)
+      [ $# -ge 2 ] || die "--since needs a number of seconds" 1
+      case "${2%s}" in (*[!0-9]*|"") die "--since needs seconds, e.g. --since 30 or --since 30s, got: $2" 1 ;; esac
+      SINCE="${2%s}"; shift 2 ;;
+    --process)
+      [ $# -ge 2 ] || die "--process needs a name" 1
+      PROCESS="$2"; shift 2 ;;
+    --network) NETWORK=1; shift ;;
+    --grep)
+      [ $# -ge 2 ] || die "--grep needs a string" 1
+      GREP="$2"; shift 2 ;;
+    --lines)
+      [ $# -ge 2 ] || die "--lines needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--lines needs a positive integer, got: $2" 1 ;; esac
+      LINES="$2"; shift 2 ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: logs.sh [start|stop|status] [--since Ns] [--process P] [--grep S] [--lines N])" 1 ;;
+  esac
+done
+
+load_config
+need_cmd adb
+
+SD="$(state_dir)"
+PIDFILE="$SD/logcat.pid"
+LOGFILE="$SD/logcat.log"
+
+collector_pid() {
+  [ -f "$PIDFILE" ] || return 1
+  local p
+  p="$(cat "$PIDFILE" 2>/dev/null || true)"
+  [ -n "$p" ] || return 1
+  kill -0 "$p" 2>/dev/null || return 1
+  printf '%s' "$p"
+}
+
+# device_now — the device's clock, in epoch seconds.
+#
+# Every cutoff is computed from this and never from the host's clock. logcat
+# stamps its records with the device's time, and on an emulator or a phone that
+# has been off the network the two disagree; a --since built on the host clock
+# then silently returns the wrong window, which is worse than returning nothing.
+device_now() {
+  local t
+  t="$(adb_dev shell date +%s 2>/dev/null | tr -d '\r ')"
+  case "$t" in
+    ''|*[!0-9]*) die "could not read the device clock — run $(as_cmd doctor)" 3 ;;
+  esac
+  printf '%s' "$t"
+}
+
+# The collector asks logcat for `-v epoch`, so records arrive already stamped
+# with an unambiguous absolute time.
+#
+# The obvious alternative — stamping each line in awk with systime() — does not
+# work: systime() is a gawk extension and macOS ships the one true awk, which
+# answers "calling undefined function systime". Because the collector runs
+# detached with its output discarded, that failure was completely silent and
+# produced an empty log file that looked exactly like a quiet device.
+#
+# Rotation stays in the writer for the same reason it does on iOS: truncating a
+# file that an open writer is appending to leaves its offset past the new end,
+# and every later line lands after a gap of NULs.
+start_collector() {
+  local max serial
+  serial="$(device_serial)"
+  max="$(cfg '.logs.max_lines_kept' '200000')"
+  adb -s "$serial" logcat -c >/dev/null 2>&1 || true
+  nohup sh -c "adb -s '$serial' logcat -v epoch 2>/dev/null | awk -v f='$LOGFILE' -v max='$max' '
+    { n++
+      print >> f
+      fflush(f)
+      if (n >= max) { close(f); system(\"mv \" f \" \" f \".1\"); n = 0 }
+    }'" >/dev/null 2>&1 &
+  printf '%s' "$!" > "$PIDFILE"
+  local i=0
+  while [ "$i" -lt 20 ]; do
+    collector_pid >/dev/null 2>&1 && break
+    sleep 0.2
+    i=$((i + 1))
+  done
+}
+
+# Epoch seconds to the device's local wall clock, without a subprocess per line.
+# strftime() is another gawk extension, so the offset is fetched once and the
+# arithmetic done by hand.
+TZ_OFFSET=""
+tz_offset() {
+  [ -n "$TZ_OFFSET" ] && { printf '%s' "$TZ_OFFSET"; return 0; }
+  local z sign h m
+  z="$(adb_dev shell date +%z 2>/dev/null | tr -d '\r ')"
+  case "$z" in
+    [+-][0-9][0-9][0-9][0-9])
+      sign="${z%"${z#?}"}"; h="${z:1:2}"; m="${z:3:2}"
+      TZ_OFFSET="$(( ${sign}1 * (10#$h * 3600 + 10#$m * 60) ))" ;;
+    *) TZ_OFFSET=0 ;;
+  esac
+  printf '%s' "$TZ_OFFSET"
+}
+
+format_lines() {
+  awk -v off="$(tz_offset)" '
+    {
+      if ($1 ~ /^[0-9]+\.[0-9]+$/) {
+        sec = int($1) + off
+        tod = sec % 86400
+        stamp = sprintf("%02d:%02d:%02d", int(tod / 3600), int((tod % 3600) / 60), tod % 60)
+        $1 = stamp
+      }
+      print
+    }'
+}
+
+case "$VERB" in
+  start)
+    if pid="$(collector_pid)"; then
+      printf 'OK logs — already collecting (pid %s, %s lines)\n' \
+        "$pid" "$(wc -l < "$LOGFILE" 2>/dev/null | tr -d ' ' || echo 0)"
+      exit 0
+    fi
+    rm -f "$LOGFILE" "$LOGFILE.1"
+    start_collector
+    pid="$(collector_pid)" || die "could not start logcat — run $(as_cmd doctor)" 2
+    printf 'OK logs — buffer cleared, collecting (pid %s) into %s\n' "$pid" "$LOGFILE"
+    exit 0
+    ;;
+
+  stop)
+    if ! pid="$(collector_pid)"; then
+      printf 'OK logs — not collecting\n'
+      exit 0
+    fi
+    # The collector is a shell wrapping a pipeline, so the children go too or
+    # adb keeps the logcat channel open.
+    pkill -P "$pid" 2>/dev/null || true
+    kill "$pid" 2>/dev/null || true
+    rm -f "$PIDFILE"
+    printf 'OK logs — stopped (%s lines kept in %s)\n' \
+      "$(wc -l < "$LOGFILE" 2>/dev/null | tr -d ' ' || echo 0)" "$LOGFILE"
+    exit 0
+    ;;
+
+  status)
+    if pid="$(collector_pid)"; then
+      since="$(awk '$1 ~ /^[0-9]+\.[0-9]+$/ { print int($1); exit }' "$LOGFILE" 2>/dev/null || true)"
+      printf 'OK logs — collecting (pid %s, %s lines) since %s\n' \
+        "$pid" "$(wc -l < "$LOGFILE" 2>/dev/null | tr -d ' ' || echo 0)" \
+        "$( [ -n "$since" ] && date -r "$since" '+%H:%M:%S' 2>/dev/null || echo 'unknown' )"
+    else
+      printf 'OK logs — not collecting (reads fall back to the device ring buffer)\n'
+    fi
+    exit 0
+    ;;
+esac
+
+# --- read ---------------------------------------------------------------------
+
+[ -n "$LINES" ] || LINES="$(cfg '.logs.max_lines' '50')"
+
+if collector_pid >/dev/null 2>&1; then
+  SOURCE="collector"
+  CUTOFF=0
+  [ -n "$SINCE" ] && CUTOFF="$(( $(device_now) - SINCE ))"
+  ROTATED=""
+  [ -s "$LOGFILE.1" ] && ROTATED="$LOGFILE.1"
+  # The rotated half first, so the result stays in chronological order.
+  raw="$(awk -v cutoff="$CUTOFF" '$1 + 0 >= cutoff' $ROTATED "$LOGFILE" 2>/dev/null || true)"
+else
+  SOURCE="device ring buffer"
+  if [ -n "$SINCE" ]; then
+    # `-t 30s` is not a thing: logcat wants a real timestamp, and it wants it in
+    # the device's own local time. Asking the device to format its own clock is
+    # what keeps this correct when the phone and the Mac disagree.
+    STAMP="$(adb_dev shell "date -d @$(( $(device_now) - SINCE )) +'%m-%d %H:%M:%S.000'" 2>/dev/null | tr -d '\r')"
+    if [ -n "$STAMP" ]; then
+      raw="$(adb_dev logcat -d -v epoch -T "$STAMP" 2>/dev/null || true)"
+    else
+      raw="$(adb_dev logcat -d -v epoch 2>/dev/null || true)"
+    fi
+  else
+    raw="$(adb_dev logcat -d -v epoch 2>/dev/null || true)"
+  fi
+fi
+
+[ -n "$raw" ] || die "no logs available from the $SOURCE" 4
+
+out="$raw"
+if [ -n "$PROCESS" ]; then
+  out="$(printf '%s\n' "$out" | grep -F -- "$PROCESS" || true)"
+fi
+if [ -n "$GREP" ]; then
+  out="$(printf '%s\n' "$out" | grep -F -i -- "$GREP" || true)"
+fi
+
+if [ "$NETWORK" -eq 1 ]; then
+  # THIS IS NOT A PROXY, AND IT CANNOT BE ONE HERE. A proxy needs its CA
+  # certificate installed on the device, and the app under test pins its
+  # certificates — it would see a handshake failure and nothing else. So this
+  # filters the app's own log output: what the app chose to print, and nothing
+  # more. No bodies, no headers the app did not log, and nothing at all from an
+  # app that logs nothing.
+  #
+  # THE PATTERN IS STRICTER THAN IT LOOKS, AND THE DEVICE IS WHY. A plain
+  # /GET|POST|.../ matched bluetoothd on the phone this was built against,
+  # because BD_VSC_OLYMPIC_GET_EXT_ADV_DROPPED contains GET. So a verb has to
+  # sit on a word boundary AND be followed by something that looks like a URL.
+  # "forgetting the cache" was never a GET either.
+  # The Network panel means the app's traffic. Without this the filter searches
+  # the whole device syslog, which on this phone is thirty-five thousand lines
+  # of other people's processes.
+  app="$(cfg '.app.package' '')"
+  if [ -n "$app" ]; then
+    out="$(printf '%s\n' "$out" | grep -i -F -- "$app" || true)"
+  fi
+  PAT="$(cfg '.logs.network_pattern' '(^|[^A-Za-z0-9_])(GET|POST|PUT|PATCH|DELETE)[[:space:]]+(https?://|/)|HTTP/[0-9]')"
+  out="$(printf '%s\n' "$out" | awk -v pat="$PAT" '$0 ~ pat' || true)"
+  if [ -z "$out" ]; then
+    die "no log lines matched /$PAT/ — this reads the app's own logging rather than a proxy, so an app that does not print its requests shows nothing here. Set logs.network_pattern in the config to match how yours logs them" 4
+  fi
+fi
+
+if [ -z "$out" ]; then
+  what=""
+  [ -n "$PROCESS" ] && what=" --process '$PROCESS'"
+  [ -n "$GREP" ] && what="$what --grep '$GREP'"
+  die "nothing matched$what in the $SOURCE" 4
+fi
+
+n="$(printf '%s\n' "$out" | wc -l | tr -d ' ')"
+if [ "$n" -gt "$LINES" ]; then
+  printf '%s\n' "$out" | tail -n "$LINES" | format_lines
+  printf '… %s earlier line(s) not shown (--lines N)\n' "$(( n - LINES ))"
+else
+  printf '%s\n' "$out" | format_lines
+fi

package/scripts/android/permission.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# permission.sh — grant or deny a runtime permission before the app asks.
+#
+#   permission.sh <name>=<allow|deny> [<name>=<allow|deny> ...]
+#
+#   permission.sh camera=allow location=deny
+#
+# WHY THIS IS A STEP AND NOT AUTOMATIC
+#
+# Other tools dismiss permission dialogs for you. That hides whether the app
+# asked at all — and for a production app, whether it asks, and for what, is itself
+# under test. A prompt that quietly stops appearing is a real regression, and a
+# tool that taps it away can never report one.
+#
+# So the decision is written in the test. Granting up front also means the
+# dialog never appears, which is more reliable than racing to tap it; when you
+# do want to exercise the dialog itself, leave this out and use
+# `tap: { label: Allow, optional: true }`.
+#
+# Names are platform-neutral and each maps to whatever the platform calls it.
+# A name this platform cannot express is refused rather than silently ignored,
+# because a permission step that did nothing is worse than one that failed.
+#
+#   camera microphone location location-always contacts photos calendar
+#   notifications storage phone sms
+#
+# exit 0  every permission is now in the requested state
+# exit 1  usage error, or a name this platform does not have
+# exit 2  environment or configuration problem
+# exit 3  device unreachable — run doctor.sh
+# exit 4  the change was applied but did not take
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+[ $# -ge 1 ] || die "missing permission (usage: permission.sh <name>=<allow|deny> [...])" 1
+case "$1" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+
+load_config
+PKG="$(cfg '.app.package' '')"
+[ -n "$PKG" ] || die "app.package is not set in $DT_CONFIG — permissions are granted to a package" 2
+
+# One neutral name can cover several Android permissions: "contacts" is read and
+# write, and "storage" changed shape in Android 13. All of them are applied, and
+# ones the device does not define are skipped rather than failing the step — a
+# device that has no READ_MEDIA_IMAGES is not a test failure.
+android_perms() {
+  case "$1" in
+    camera)          printf 'android.permission.CAMERA' ;;
+    microphone)      printf 'android.permission.RECORD_AUDIO' ;;
+    location)        printf 'android.permission.ACCESS_FINE_LOCATION android.permission.ACCESS_COARSE_LOCATION' ;;
+    location-always) printf 'android.permission.ACCESS_BACKGROUND_LOCATION android.permission.ACCESS_FINE_LOCATION' ;;
+    contacts)        printf 'android.permission.READ_CONTACTS android.permission.WRITE_CONTACTS' ;;
+    photos)          printf 'android.permission.READ_MEDIA_IMAGES android.permission.READ_EXTERNAL_STORAGE' ;;
+    calendar)        printf 'android.permission.READ_CALENDAR android.permission.WRITE_CALENDAR' ;;
+    notifications)   printf 'android.permission.POST_NOTIFICATIONS' ;;
+    storage)         printf 'android.permission.READ_EXTERNAL_STORAGE android.permission.WRITE_EXTERNAL_STORAGE' ;;
+    phone)           printf 'android.permission.READ_PHONE_STATE' ;;
+    sms)             printf 'android.permission.READ_SMS android.permission.SEND_SMS' ;;
+    *) return 1 ;;
+  esac
+}
+
+pkg_installed "$PKG" \
+  || die "$PKG is not installed — run $(as_cmd app install)" 4
+
+# granted <permission> — true when the package currently holds it.
+granted() {
+  adb_dev shell dumpsys package "$PKG" 2>/dev/null | tr -d '\r' \
+    | awk -v p="$1" '$0 ~ p": granted=true" { found = 1 } END { exit found ? 0 : 1 }'
+}
+
+DONE=""
+for pair in "$@"; do
+  case "$pair" in
+    *=*) ;;
+    *) die "expected <name>=<allow|deny>, got '$pair'" 1 ;;
+  esac
+  name="${pair%%=*}"
+  want="${pair#*=}"
+  case "$want" in
+    allow|deny) ;;
+    *) die "'$name' must be allow or deny, got '$want'" 1 ;;
+  esac
+
+  perms="$(android_perms "$name" || true)"
+  [ -n "$perms" ] \
+    || die "no such permission name '$name' — known: camera microphone location location-always contacts photos calendar notifications storage phone sms" 1
+
+  applied=0
+  for p in $perms; do
+    if [ "$want" = allow ]; then
+      adb_dev shell pm grant "$PKG" "$p" >/dev/null 2>&1 && applied=$((applied + 1)) || true
+    else
+      adb_dev shell pm revoke "$PKG" "$p" >/dev/null 2>&1 && applied=$((applied + 1)) || true
+    fi
+  done
+
+  # Not every name resolves on every Android version, but at least one of the
+  # permissions behind a name has to. Zero means the app does not declare any of
+  # them, which makes the step a silent no-op — and a permission step that did
+  # nothing is exactly what this refuses to be.
+  [ "$applied" -gt 0 ] \
+    || die "could not $want '$name' for $PKG — the app declares none of: $perms" 4
+
+  # Verified against the package manager rather than trusted from the exit code
+  # of pm, which reports success for a permission the app never declared.
+  first="${perms%% *}"
+  if [ "$want" = allow ]; then
+    granted "$first" || die "granted '$name' to $PKG but $first still reads as not granted" 4
+  else
+    granted "$first" && die "revoked '$name' from $PKG but $first still reads as granted" 4
+  fi
+
+  DONE="$DONE $name=$want"
+done
+
+printf 'OK permissions for %s —%s\n' "$PKG" "$DONE"

package/scripts/android/settings.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# settings.sh — the device conditions a person would change by hand.
+#
+#   settings.sh orientation portrait|landscape
+#   settings.sh appearance  light|dark
+#   settings.sh textsize    <scale>       1.0, 1.15, 1.3, 1.5
+#
+# These are the conditions a layout breaks under, and none of them is visible in
+# the accessibility tree — dark mode and text size change colours and metrics
+# that neither driver reports. So the way to find out is to set them and look,
+# which is what this verb is for.
+#
+# exit 0  set
+# exit 1  usage error
+# exit 3  device unreachable — run doctor.sh
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+case "${1-}" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+KEY="${1-}"; VAL="${2-}"
+[ -n "$KEY" ] && [ -n "$VAL" ] \
+  || die "usage: settings.sh <orientation|appearance|textsize> <value>" 1
+[ $# -eq 2 ] || die "too many arguments (usage: settings.sh <key> <value>)" 1
+
+load_config
+need_cmd adb
+
+case "$KEY" in
+  orientation)
+    case "$VAL" in
+      portrait)  rot=0 ;;
+      landscape) rot=1 ;;
+      *) die "orientation is portrait or landscape, got '$VAL'" 1 ;;
+    esac
+    # Auto-rotate has to go off first, or the accelerometer puts it straight
+    # back and the verb reports a change that lasted half a second.
+    adb_dev shell settings put system accelerometer_rotation 0 >/dev/null 2>&1 \
+      || die "could not reach the device — run $(as_cmd doctor)" 3
+    adb_dev shell settings put system user_rotation "$rot" >/dev/null 2>&1 \
+      || die "could not reach the device — run $(as_cmd doctor)" 3
+    ;;
+  appearance)
+    case "$VAL" in
+      light) mode=no ;;
+      dark)  mode=yes ;;
+      *) die "appearance is light or dark, got '$VAL'" 1 ;;
+    esac
+    adb_dev shell "cmd uimode night $mode" >/dev/null 2>&1 \
+      || die "could not reach the device — run $(as_cmd doctor)" 3
+    ;;
+  textsize)
+    case "$VAL" in
+      *[!0-9.]*|"") die "textsize is a scale like 1.0 or 1.3, got '$VAL'" 1 ;;
+    esac
+    adb_dev shell settings put system font_scale "$VAL" >/dev/null 2>&1 \
+      || die "could not reach the device — run $(as_cmd doctor)" 3
+    ;;
+  *) die "unknown setting '$KEY' — orientation, appearance or textsize" 1 ;;
+esac
+
+printf 'OK settings — %s is now %s\n' "$KEY" "$VAL"

package/scripts/android/setup.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# setup.sh — put the UiAutomator2 driver on the device.
+#
+#   setup.sh [--force]
+#
+# WHY THIS EXISTS AS A COMMAND
+#
+# Provisioning an Android device is four steps: fetch a pinned release and
+# install two APKs. A person following a README had to find the same two URLs by
+# hand. The knowledge was already written down — it was simply written down
+# somewhere no user looks.
+#
+# TWO PACKAGES, AND BOTH ARE REQUIRED.
+#
+# `io.appium.uiautomator2.server` is the server; `…server.test` is the
+# instrumentation that starts it. Installing only the first leaves a device that
+# fails later with "the server will not start", which sends people looking at
+# ports. doctor reports them separately for the same reason.
+#
+# Idempotent: an APK already downloaded is not fetched again, and `adb install
+# -r` replaces cleanly. --force re-downloads, which is what a corrupted or
+# truncated file needs.
+#
+# exit 0  the driver is installed and verified
+# exit 1  usage error
+# exit 2  something could not be downloaded or installed
+# exit 3  no device
+
+source "$(dirname "$0")/lib.sh"
+load_config
+
+FORCE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --force) FORCE=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1" 1 ;;
+  esac
+done
+
+need_cmd curl
+need_cmd adb
+
+say() { printf '%s %s — %s\n' "$1" "$2" "$3"; }
+
+VERSION="$(cfg '.ua2.version' 'v10.6.2')"
+APK_DIR="$(expand_path "$(cfg '.ua2.apk_dir' '~/tools/uiautomator2')")"
+SERVER_APK="$APK_DIR/appium-uiautomator2-server-$VERSION.apk"
+TEST_APK="$APK_DIR/appium-uiautomator2-server-debug-androidTest.apk"
+BASE="https://github.com/appium/appium-uiautomator2-server/releases/download/$VERSION"
+
+mkdir -p "$APK_DIR" || die "could not create $APK_DIR" 2
+
+fetch() {  # fetch <url> <dest>
+  if [ -s "$2" ] && [ "$FORCE" -eq 0 ]; then
+    say OK apk "$(basename "$2") already at $2"
+    return 0
+  fi
+  # To a temporary name first: a half-downloaded APK left at the final path
+  # looks present to every check above and fails at install with a message
+  # about the archive rather than about the download.
+  # curl's own stderr is suppressed and its exit code translated. "curl: (56)
+  # The requested URL returned error: 404" above our message is two lines
+  # saying one thing, and the one that names the remedy is the second.
+  curl -fsSL -o "$2.part" "$1" 2>/dev/null \
+    || { rm -f "$2.part"
+         die "could not download $(basename "$2") from $1 — check the network, or set ua2.version to a release that exists" 2; }
+  mv "$2.part" "$2"
+  say OK apk "$(basename "$2") downloaded"
+}
+
+fetch "$BASE/appium-uiautomator2-server-$VERSION.apk" "$SERVER_APK"
+fetch "$BASE/appium-uiautomator2-server-debug-androidTest.apk" "$TEST_APK"
+
+SERIAL="$(device_serial)"
+adb -s "$SERIAL" get-state >/dev/null 2>&1 \
+  || die "device '$SERIAL' is not connected — run $(as_cmd devices) to see what is" 3
+
+# -g grants the runtime permissions the server needs up front. Without it the
+# first test that touches a permission dialog fails in a way that looks like the
+# app's fault.
+for apk in "$SERVER_APK" "$TEST_APK"; do
+  out="$(adb -s "$SERIAL" install -r -g "$apk" 2>&1 </dev/null)" \
+    || die "could not install $(basename "$apk"): $(printf '%s' "$out" | tr '\n' ' ' | head -c 200)" 2
+done
+say OK install "both packages installed on $SERIAL"
+
+UA2_PKG=io.appium.uiautomator2.server
+pkg_installed "$UA2_PKG" \
+  || die "installed without error but $UA2_PKG is not present — try: adb -s $SERIAL uninstall $UA2_PKG, then run this again" 2
+pkg_installed "$UA2_PKG.test" \
+  || die "installed without error but $UA2_PKG.test is not present — try: adb -s $SERIAL uninstall $UA2_PKG.test, then run this again" 2
+
+VER="$(adb -s "$SERIAL" shell dumpsys package "$UA2_PKG" 2>/dev/null </dev/null \
+       | awk -F= '/versionName/ { print $2; exit }' | tr -d '\r')"
+say OK verified "UiAutomator2 server ${VER:-$VERSION} on $SERIAL"
+printf 'NEXT scripts/doctor.sh\n'