device-devtools-mcp 0.1.0

package/scripts/android/doctor.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+# doctor.sh — is this machine able to drive the app right now?
+#
+#   doctor.sh [--start-ua2]
+#
+# Eight checks, always the same eight, always in this order, one line each:
+#
+#   OK|WARN|FAIL <name> — <detail>
+#
+# The order is the dependency order, so the first FAIL is the thing to fix; the
+# checks below it are reported anyway rather than skipped, because "we stopped
+# looking" and "we looked and it was fine" must not print the same way.
+#
+# --start-ua2 restarts a UiAutomator2 server that is installed but not running.
+# Without it this script only reports; it changes nothing. --recover is the same
+# flag under the platform-neutral name every other script uses when it tells you
+# to run this.
+#
+# exit 0  everything needed is present (WARN is allowed)
+# exit 2  at least one FAIL
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+START_UA2=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --start-ua2) START_UA2=1; shift ;;
+    # --recover is the platform-neutral spelling, so that any caller can ask any
+    # adapter to put itself right without knowing what "right" involves here.
+    --recover) START_UA2=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: doctor.sh [--start-ua2|--recover])" 1 ;;
+  esac
+done
+
+FAILED=0
+# The status word is the whole point of these nine lines, so it is the only
+# thing tinted. The check names stay plain: they are a fixed list in a fixed
+# order and colouring them would suggest one matters more than another.
+say() {
+  local col=""
+  case "$1" in OK) col="$C_PASS" ;; WARN) col="$C_NOTE" ;; FAIL) col="$C_FAIL" ;; esac
+  printf '%s%s%s %s — %s\n' "$col" "$1" "${col:+$C_OFF}" "$2" "$3"
+  [ "$1" = FAIL ] && FAILED=1
+  return 0
+}
+
+# --- 1. sdk ------------------------------------------------------------------
+if command -v adb >/dev/null 2>&1; then
+  say OK sdk "adb $(adb version 2>/dev/null | awk 'NR==1{print $NF}')"
+else
+  say FAIL sdk "adb not on PATH — install Android platform-tools, see README.md"
+fi
+
+# --- 2. jq -------------------------------------------------------------------
+if command -v jq >/dev/null 2>&1; then
+  say OK jq "$(jq --version 2>/dev/null)"
+else
+  say FAIL jq "jq not on PATH — see README.md setup"
+fi
+
+# Everything below needs the config to be readable at all.
+load_config
+
+SERIAL="$(cfg '.device.serial' '')"
+PORT="$(cfg '.ua2.local_port' '6790')"
+DEVICE_PORT="$(cfg '.ua2.device_port' '6790')"
+PKG="$(cfg '.app.package' '')"
+
+# --- 3. device ---------------------------------------------------------------
+DEVICE_OK=0
+if [ -z "$SERIAL" ]; then
+  say FAIL device "device.serial is not set in $DT_CONFIG — run 'adb devices' and copy the serial"
+elif ! command -v adb >/dev/null 2>&1; then
+  say FAIL device "cannot look for $SERIAL without adb"
+else
+  STATE="$(adb devices 2>/dev/null | awk -v s="$SERIAL" '$1 == s { print $2; exit }')"
+  case "$STATE" in
+    device)
+      DEVICE_OK=1
+      REL="$(adb_dev shell getprop ro.build.version.release 2>/dev/null | tr -d '\r')"
+      say OK device "$SERIAL — Android ${REL:-?} ($(android_kind))" ;;
+    unauthorized)
+      say FAIL device "$SERIAL is unauthorized — accept the USB debugging prompt on the device" ;;
+    offline)
+      say FAIL device "$SERIAL is offline — reconnect it, or run 'adb kill-server'" ;;
+    "")
+      ATTACHED="$(adb devices 2>/dev/null | awk 'NR>1 && $1 != "" { printf "%s ", $1 }')"
+      if [ -z "$ATTACHED" ]; then
+        say FAIL device "$SERIAL not attached, and no device is — plug one in or start the emulator"
+      else
+        say FAIL device "$SERIAL not attached; attached: ${ATTACHED% }"
+      fi ;;
+    *)
+      say FAIL device "$SERIAL is in state '$STATE'" ;;
+  esac
+fi
+
+# --- 4. ua2-apk --------------------------------------------------------------
+#
+# Two packages, and both matter: the server and the instrumentation that starts
+# it. Reporting only the first turns "the test runner APK is missing" into the
+# much less useful "the server will not start".
+UA2_PKG=io.appium.uiautomator2.server
+UA2_TEST_PKG=io.appium.uiautomator2.server.test
+APK_OK=0
+if [ "$DEVICE_OK" -eq 0 ]; then
+  say FAIL ua2-apk "cannot check without a working device connection"
+else
+  HAVE_SRV=0; HAVE_TEST=0
+  pkg_installed "$UA2_PKG" && HAVE_SRV=1
+  pkg_installed "$UA2_TEST_PKG" && HAVE_TEST=1
+  if [ "$HAVE_SRV" -eq 1 ] && [ "$HAVE_TEST" -eq 1 ]; then
+    APK_OK=1
+    VER="$(adb_dev shell dumpsys package "$UA2_PKG" 2>/dev/null | awk -F= '/versionName/ { print $2; exit }' | tr -d '\r')"
+    say OK ua2-apk "UiAutomator2 server ${VER:-installed}"
+  elif [ "$HAVE_SRV" -eq 1 ]; then
+    say FAIL ua2-apk "$UA2_TEST_PKG missing — both packages are needed; run: scripts/setup.sh"
+  else
+    say FAIL ua2-apk "$UA2_PKG not installed — run: scripts/setup.sh"
+  fi
+fi
+
+# --- 5. forward --------------------------------------------------------------
+#
+# Idempotent by construction: `adb forward` replaces an existing mapping for the
+# same local port rather than adding a second one, so establishing it here costs
+# nothing when it is already there and removes a whole class of "it worked
+# yesterday" from the user's day.
+#
+# TAKING A PORT THAT BELONGS TO ANOTHER DEVICE IS NOT RECOVERY, IT IS THEFT.
+#
+# Because the mapping is replaced rather than added, a second config naming the
+# same local port silently redirects the first one's traffic to this device. It
+# happened here with an emulator and a phone: the emulator's suite went on
+# running, reading a Huawei's screen, and failed with `expected 'Clock', found
+# 'Chỉnh sửa báo thức'` — a real device answering a question about a different
+# one. On a fleet that is a green run against hardware nobody tested.
+#
+# So the port is only taken when it is free or already ours.
+OWNER=""
+if [ "$DEVICE_OK" -eq 1 ]; then
+  OWNER="$(adb forward --list 2>/dev/null \
+    | awk -v p="tcp:$PORT" '$2 == p { print $1; exit }')"
+fi
+
+FORWARD_OK=0
+if [ "$DEVICE_OK" -eq 0 ]; then
+  say FAIL forward "cannot forward without a working device connection"
+elif [ -n "$OWNER" ] && [ "$OWNER" != "$(device_serial)" ]; then
+  say FAIL forward "127.0.0.1:$PORT is already forwarded to $OWNER, and taking it would point this config at that device — give one of them its own ua2.local_port"
+elif adb_dev forward "tcp:$PORT" "tcp:$DEVICE_PORT" >/dev/null 2>&1; then
+  FORWARD_OK=1
+  say OK forward "127.0.0.1:$PORT → device:$DEVICE_PORT"
+else
+  say FAIL forward "adb forward tcp:$PORT → tcp:$DEVICE_PORT failed"
+fi
+
+# --- 6. ua2 ------------------------------------------------------------------
+ua2_ready() {
+  curl -sS -m 5 "http://127.0.0.1:$PORT/status" 2>/dev/null \
+    | jq -e '.value.ready == true' >/dev/null 2>&1
+}
+
+# A COLD START IS NOT A WARM START, AND CI IS ALWAYS COLD.
+#
+# Ten seconds was measured against a server that had been run before. Installing
+# the APK first — which CI does on every job, and which a human does once —
+# leaves the runtime with the dexopt and first-run work still to do, and it took
+# longer than that. The check then reported a driver that was starting normally
+# as broken, and a second identical run passed.
+#
+# Sixty seconds is the budget now. Nothing waits that long in the normal case:
+# it polls, so a warm start still returns in about a second. What the number
+# controls is only how patient the failure is.
+UA2_START_SECONDS=60
+
+start_ua2() {
+  # Instrumentation runs for as long as the server lives, so it is detached and
+  # its output discarded; the readiness check below is the real answer.
+  adb_dev shell am instrument -w -e disableAnalytics true \
+    "$UA2_TEST_PKG/androidx.test.runner.AndroidJUnitRunner" >/dev/null 2>&1 &
+  local i
+  i=0
+  while [ "$i" -lt "$UA2_START_SECONDS" ]; do
+    sleep 1
+    ua2_ready && return 0
+    i=$((i + 1))
+  done
+  return 1
+}
+
+UA2_OK=0
+if [ "$FORWARD_OK" -eq 0 ]; then
+  say FAIL ua2 "cannot reach the server without a port forward"
+elif ua2_ready; then
+  UA2_OK=1
+  BUILD="$(curl -sS -m 5 "http://127.0.0.1:$PORT/status" 2>/dev/null | jq -r '.value.build.version // "?"')"
+  say OK ua2 "responding on 127.0.0.1:$PORT, build $BUILD"
+elif [ "$APK_OK" -eq 0 ]; then
+  say FAIL ua2 "not responding on 127.0.0.1:$PORT, and the server APK is missing"
+elif [ "$START_UA2" -eq 1 ]; then
+  if start_ua2; then
+    UA2_OK=1
+    say OK ua2 "started, responding on 127.0.0.1:$PORT"
+  else
+    say FAIL ua2 "installed but did not become ready within ${UA2_START_SECONDS}s of starting"
+  fi
+else
+  say FAIL ua2 "installed but not running on 127.0.0.1:$PORT — re-run with --start-ua2"
+fi
+
+# --- 7. ua2-session ----------------------------------------------------------
+#
+# A server that answers /status can still refuse to create a session, and every
+# verb needs one. Checking the thing the verbs actually depend on is the point
+# of a doctor.
+if [ "$UA2_OK" -eq 0 ]; then
+  say FAIL ua2-session "cannot create a session without a responding server"
+else
+  ua2_drop_session
+  SID="$(curl -sS -m 20 -X POST "http://127.0.0.1:$PORT/session" \
+      -H 'Content-Type: application/json' \
+      -d '{"capabilities":{"alwaysMatch":{},"firstMatch":[{}]}}' 2>/dev/null \
+      | jq -r '.value.sessionId // .sessionId // empty' 2>/dev/null)"
+  if [ -n "$SID" ]; then
+    printf '%s' "$SID" > "$(session_file)"
+    N="$(curl -sS -m 10 "http://127.0.0.1:$PORT/session/$SID/source?format=xml" 2>/dev/null \
+        | jq -r '.value // empty' 2>/dev/null | awk -f "$TREE_AWK" 2>/dev/null | wc -l | tr -d ' ')"
+    say OK ua2-session "created, screen has ${N:-0} elements"
+  else
+    say FAIL ua2-session "the server would not create a session — try --start-ua2"
+  fi
+fi
+
+# --- 8. app ------------------------------------------------------------------
+#
+# WARN, not FAIL: reading the screen and driving whatever is in the foreground
+# works without the app under test being installed, and a doctor that fails
+# for a package the user has not built yet is a doctor people stop running.
+if [ -z "$PKG" ]; then
+  say WARN app "app.package is not set in $DT_CONFIG — lifecycle verbs will not work"
+elif [ "$DEVICE_OK" -eq 0 ]; then
+  say WARN app "cannot check $PKG without a working device connection"
+elif pkg_installed "$PKG"; then
+  VER="$(adb_dev shell dumpsys package "$PKG" 2>/dev/null | awk -F= '/versionName/ { print $2; exit }' | tr -d '\r')"
+  say OK app "$PKG${VER:+ $VER} installed"
+else
+  say WARN app "$PKG is not installed — run $(as_cmd app install)"
+fi
+
+[ "$FAILED" -eq 0 ] || exit 2
+exit 0