device-devtools-mcp 0.1.0

package/scripts/ios/app.sh

@@ -0,0 +1,404 @@
+#!/usr/bin/env bash
+# app.sh — the app under test's lifecycle.
+#
+#   app.sh installed <id>   is some other app present?
+#   app.sh state              report whether it is running, and how
+#   app.sh launch             bring it up (no-op if already foreground)
+#   app.sh kill               terminate it
+#   app.sh relaunch           kill then launch, keeping stored data
+#   app.sh reset              uninstall and reinstall, discarding all data
+#   app.sh install [path] [--launch]
+#                             install a built .app bundle onto the configured device
+#   app.sh uninstall [id]     remove it
+#   app.sh build              build it from source
+#
+# INSTALL GOES TO THE DEVICE THE CONFIG SELECTS, and takes no UDID of its own.
+# Two phones on one desk is the normal case; installing onto one and reading the
+# other produces a session spent debugging a build that is not there, with
+# nothing anywhere saying so.
+#
+# Lifecycle goes through WebDriverAgent rather than the command line. It is
+# already connected, it is faster than shelling out, and it works the same way
+# on a device where `devicectl` does not (see README). Installation goes through
+# ios-deploy, because WebDriverAgent cannot install.
+#
+# Every state-changing verb verifies afterwards by reading the app's state back,
+# rather than trusting that the request was honoured.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  done, and verified
+# exit 1  usage error
+# exit 2  not configured for this verb, or a build/install failure
+# exit 3  WebDriverAgent unreachable — run doctor.sh
+# exit 4  the app did not reach the expected state
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+CMD="${1-}"
+[ -n "$CMD" ] || die "missing verb (usage: app.sh state|launch|kill|relaunch|reset|install|uninstall|build)" 1
+case "$CMD" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+shift
+
+# --snapshot IS ANSWERED ONCE, HERE, AND NOT BY EVERY VERB SEPARATELY.
+#
+# Each verb below counts its own arguments and refuses a stray one, which is
+# right and is also why a flag that applies to all of them cannot be added to
+# all of them: it would have to be subtracted from eight separate `[ $# -eq 0 ]`
+# guards. Taken out of the list up front, every verb sees exactly what it saw
+# before, and the screen is printed at the end of whichever one ran.
+DT_ARGV=()
+for a in ${@+"$@"}; do
+  case "$a" in
+    --snapshot) act_snapshot_on ;;
+    *) DT_ARGV+=("$a") ;;
+  esac
+done
+set -- ${DT_ARGV[@]+"${DT_ARGV[@]}"}
+
+load_config
+
+# Launch and terminate go through XCUITest, which waits for the app to reach an
+# idle state before it answers. Terminating the app under test was measured at
+# ~60s. The read timeout would abort long before that and report a driver that
+# is working normally as stuck.
+DT_HTTP_TIMEOUT="$(cfg '.timeouts.app_seconds' '90')"
+export DT_HTTP_TIMEOUT
+
+BUNDLE="$(cfg '.app.bundle_id' '')"
+[ -n "$BUNDLE" ] \
+  || die "app.bundle_id is not set in $DT_CONFIG — every verb here needs it" 2
+
+# WebDriverAgent's application states. Naming them is the difference between a
+# report a caller can act on and an integer they have to look up.
+# device_name_note <udid> — "  (Name)" when the phone will say, else nothing.
+# Cosmetic, and never allowed to fail: it exists so a person reading "installed
+# onto 00008030-…" can tell which handset that is.
+device_name_note() {
+  local n
+  n="$(ideviceinfo -u "$1" -k DeviceName 2>/dev/null || true)"
+  [ -n "$n" ] && printf '  (%s)' "$n"
+  return 0
+}
+
+# app_path_default — the path to reinstall from, in order of how much somebody
+# meant it: what was passed, what the config names, then what this checkout last
+# installed. The last one is the useful one in a build-install-drive loop, where
+# `reset` a minute after `install` should not have to be told the same path
+# twice.
+app_path_default() {
+  local given="${1-}" p
+  if [ -n "$given" ]; then printf '%s' "$given"; return 0; fi
+  p="$(cfg '.app.app_path' '')"
+  if [ -n "$p" ]; then printf '%s' "$p"; return 0; fi
+  p="$(cut -f6 "$(install_record)" 2>/dev/null || true)"
+  [ -n "$p" ] && [ -d "$p" ] && printf '%s' "$p"
+  return 0
+}
+
+# reset_launch — bring it up when --launch asked. A reset almost always wants
+# the app in front afterwards; the flag is still explicit, because "start from
+# nothing" and "start" are the two halves this verb deliberately keeps apart.
+reset_launch() {
+  [ "${LAUNCH_AFTER:-0}" -eq 1 ] || return 0
+  local resp err s
+  wda_drop_session
+  resp="$(session_post '/wda/apps/launch' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+  err="$(session_error "$resp")"
+  [ -z "$err" ] || die "reset, but launch failed — $err" 3
+  s="$(wait_for_state foreground "reset and launched but never reached the foreground")"
+  printf 'OK launched %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+  return 0
+}
+
+state_name() {
+  case "$1" in
+    1) printf 'not running' ;;
+    2) printf 'suspended' ;;
+    3) printf 'running in background' ;;
+    4) printf 'running in foreground' ;;
+    *) printf 'unknown (%s)' "$1" ;;
+  esac
+}
+
+app_state() {
+  local resp
+  resp="$(session_post '/wda/apps/state' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+  printf '%s' "$resp" | jq -r 'if (.value | type) == "number" then .value else (.value.value // 0) end' 2>/dev/null || printf '0'
+}
+
+# wait_state <predicate-description> <test-expression-on-$s>
+# Polls rather than sleeping, for the reason wait.sh exists.
+wait_for_state() {
+  local want="$1" desc="$2" s deadline=0
+  while [ "$deadline" -lt 20 ]; do
+    s="$(app_state)"
+    case "$want" in
+      foreground) [ "$s" = 4 ] && { printf '%s' "$s"; return 0; } ;;
+      stopped)    [ "$s" = 1 ] && { printf '%s' "$s"; return 0; } ;;
+    esac
+    deadline=$((deadline + 1))
+    sleep 0.3
+  done
+  printf '%s' "$s"
+  die "$desc — app is $(state_name "$s")" 4
+}
+
+case "$CMD" in
+  # installed <bundle-id> — is some OTHER app on this device?
+  #
+  # Every other verb here acts on the app under test. This one answers about an
+  # app a test merely depends on — a browser for a deep link, Maps for a
+  # hand-off — so a test can declare what it needs and be skipped where that is
+  # absent, rather than failing as though the product were broken.
+  #
+  # exit 4 for absent rather than exit 1, because "not there" is an answer.
+  installed)
+    [ $# -eq 1 ] || die "app.sh installed needs exactly one bundle id" 1
+    if [ "$(ios_kind)" = simulator ]; then
+      if xcrun simctl get_app_container "$(cfg '.device.udid')" "$1" app >/dev/null 2>&1; then
+        printf 'OK %s — installed\n' "$1"
+      else
+        die "$1 is not installed on the simulator" 4
+      fi
+    elif ! command -v ios-deploy >/dev/null 2>&1; then
+      die "cannot check for $1 — ios-deploy not found" 2
+    elif ios-deploy --id "$(cfg '.device.udid')" --no-wifi --exists --bundle_id "$1" >/dev/null 2>&1; then
+      printf 'OK %s — installed\n' "$1"
+    else
+      die "$1 is not installed on $(cfg '.device.udid')" 4
+    fi ;;
+
+  state)
+    [ $# -eq 0 ] || die "app.sh state takes no arguments" 1
+    s="$(app_state)"
+    printf 'OK %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+    ;;
+
+  launch)
+    # An explicit bundle id, for an app that is not the one under test — and for
+    # any app at all that registers no URL scheme, where `open` has nothing to
+    # work with. WebDriverAgent asks the OS by identifier, so no icon is
+    # involved and the home screen is not in the way.
+    [ $# -le 1 ] || die "app.sh launch takes at most one bundle id" 1
+    [ $# -eq 1 ] && BUNDLE="$1"
+    # A cached session may reference a process that no longer exists.
+    wda_drop_session
+    resp="$(session_post '/wda/apps/launch' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+    err="$(session_error "$resp")"
+    [ -z "$err" ] || die "launch failed — $err" 3
+    s="$(wait_for_state foreground "launched but never reached the foreground")"
+    printf 'OK launched %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+    ;;
+
+  kill)
+    [ $# -eq 0 ] || die "app.sh kill takes no arguments" 1
+    resp="$(session_post '/wda/apps/terminate' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+    err="$(session_error "$resp")"
+    [ -z "$err" ] || die "terminate failed — $err" 3
+    s="$(wait_for_state stopped "terminate was accepted but the app is still alive")"
+    wda_drop_session
+    printf 'OK killed %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+    ;;
+
+  relaunch)
+    [ $# -eq 0 ] || die "app.sh relaunch takes no arguments" 1
+    # Terminating an app that is not running is not an error worth stopping for:
+    # the point of relaunch is the end state, not the path to it.
+    session_post '/wda/apps/terminate' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')" >/dev/null
+    wait_for_state stopped "could not terminate before relaunching" >/dev/null
+    wda_drop_session
+    resp="$(session_post '/wda/apps/launch' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+    err="$(session_error "$resp")"
+    [ -z "$err" ] || die "relaunch failed at the launch step — $err" 3
+    s="$(wait_for_state foreground "relaunched but never reached the foreground")"
+    printf 'OK relaunched %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+    ;;
+
+  reset)
+    # relaunch keeps the app's container; reset does not. They are separate verbs
+    # rather than a flag because "start the app" and "start from nothing" are
+    # different intentions, and a test that needed the second while getting the
+    # first fails somewhere far away from the cause.
+    #
+    # On iOS there is no supported way to clear another app's data in place on a
+    # device that is not jailbroken, so this is uninstall followed by install,
+    # which is why it needs the built bundle.
+    LAUNCH_AFTER=0
+    ARGS=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --launch) LAUNCH_AFTER=1; shift ;;
+        -*) die "unknown argument: $1 (usage: app.sh reset [path] [--launch])" 1 ;;
+        *) [ -z "$ARGS" ] || die "app.sh reset takes one path" 1
+           ARGS="$1"; shift ;;
+      esac
+    done
+    set -- ${ARGS:+"$ARGS"}
+    udid="$(device_udid)"
+    wda_drop_session
+
+    # A simulator can erase an app's data in place, so reset does not need the
+    # built bundle there. On a device there is no supported way to do that
+    # without a jailbreak, which is why the device path is uninstall-reinstall
+    # and asks for the .app.
+    if [ "$(ios_kind)" = simulator ]; then
+      xcrun simctl uninstall "$udid" "$BUNDLE" >/dev/null 2>&1 \
+        || die "simctl could not uninstall $BUNDLE" 2
+      APP_PATH="$(app_path_default "${1-}")"
+      if [ -n "$APP_PATH" ]; then
+        APP_PATH="$(expand_path "$APP_PATH")"
+        [ -d "$APP_PATH" ] || die "not a bundle directory: $APP_PATH" 2
+        xcrun simctl install "$udid" "$APP_PATH" >/dev/null 2>&1 \
+          || die "uninstalled $BUNDLE but could not reinstall from $APP_PATH" 2
+    printf 'OK reset %s — uninstalled and reinstalled from %s\n' "$BUNDLE" "$APP_PATH"
+        reset_launch
+      else
+        printf 'OK reset %s — uninstalled; no app_path configured, so it was not reinstalled\n' "$BUNDLE"
+      fi
+      # The only branch that leaves before the end of the file, so it prints the
+      # screen for itself.
+      act_snapshot_now
+      exit 0
+    fi
+
+    need_cmd ios-deploy
+    APP_PATH="$(app_path_default "${1-}")"
+    [ -n "$APP_PATH" ] \
+      || die "reset needs the built .app — pass a path, set app.app_path in $DT_CONFIG, or run $(as_cmd app install) once and it will remember" 2
+    APP_PATH="$(expand_path "$APP_PATH")"
+    [ -d "$APP_PATH" ] || die "not a bundle directory: $APP_PATH" 2
+    ios-deploy --id "$udid" --no-wifi --uninstall_only --bundle_id "$BUNDLE" >/dev/null 2>&1 || true
+    ios-deploy --id "$udid" --no-wifi --exists --bundle_id "$BUNDLE" >/dev/null 2>&1 \
+      && die "uninstall did not remove $BUNDLE — is the device unlocked?" 4
+    ios-deploy --id "$udid" --no-wifi --bundle "$APP_PATH" >/dev/null 2>&1 \
+      || die "uninstalled $BUNDLE but could not reinstall from $APP_PATH — the device now has no copy of the app" 2
+    ios-deploy --id "$udid" --no-wifi --exists --bundle_id "$BUNDLE" >/dev/null 2>&1 \
+      || die "reinstall reported success but $BUNDLE is not present" 4
+    printf 'OK reset %s — reinstalled from %s\n' "$BUNDLE" "$APP_PATH"
+    reset_launch
+    ;;
+
+  install)
+    LAUNCH_AFTER=0
+    ARGS=""
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --launch) LAUNCH_AFTER=1; shift ;;
+        -*) die "unknown argument: $1 (usage: app.sh install [path] [--launch])" 1 ;;
+        *) [ -z "$ARGS" ] || die "app.sh install takes one path" 1
+           ARGS="$1"; shift ;;
+      esac
+    done
+    APP_PATH="$(app_path_default "$ARGS")"
+    [ -n "$APP_PATH" ] \
+      || die "no .app to install — pass a path or set app.app_path in $DT_CONFIG" 2
+    APP_PATH="$(expand_path "$APP_PATH")"
+    [ -d "$APP_PATH" ] || die "not a bundle directory: $APP_PATH" 2
+
+    facts="$(bundle_facts "$APP_PATH")" \
+      || die "no Info.plist in $APP_PATH — that is not an app bundle" 2
+    IFS='|' read -r B_ID B_VER B_BLD B_TEAM B_SIG <<< "$facts"
+    udid="$(device_udid)"
+    kind="$(ios_kind)"
+
+    # THE ONE ERROR WORTH CATCHING BEFORE THE OS GIVES ITS VERSION OF IT.
+    #
+    # A bundle built with CODE_SIGNING_ALLOWED=NO installs onto a simulator and
+    # is refused by a device, and the refusal reads `ApplicationVerificationFailed`
+    # — which sends people to look at profiles, entitlements and certificates,
+    # none of which are the problem. Makefiles set that flag; this is not rare.
+    if [ "$kind" != simulator ] && [ "$B_SIG" = unsigned ]; then
+      die "bundle is unsigned — build likely used CODE_SIGNING_ALLOWED=NO. A device will refuse it; a simulator would not. Rebuild with signing on, or install to a simulator" 2
+    fi
+
+    if [ -n "$B_ID" ] && [ "$B_ID" != "$BUNDLE" ]; then
+      printf 'NOTE the bundle is %s, and app.bundle_id says %s — every other verb will still drive %s\n' \
+        "$B_ID" "$BUNDLE" "$BUNDLE"
+    fi
+
+    if [ "$kind" = simulator ]; then
+      xcrun simctl install "$udid" "$APP_PATH" >/dev/null 2>&1 \
+        || die "simctl could not install $APP_PATH — is the simulator booted?" 2
+      xcrun simctl get_app_container "$udid" "${B_ID:-$BUNDLE}" app >/dev/null 2>&1 \
+        || die "install reported success but ${B_ID:-$BUNDLE} is not present — check the bundle id in $DT_CONFIG" 4
+    else
+      need_cmd ios-deploy
+      # The whole output, on failure only. installd's reason is in there and
+      # abbreviating it would throw away the one line that explains anything.
+      out="$(ios-deploy --id "$udid" --no-wifi --bundle "$APP_PATH" 2>&1)" || {
+        printf '%s\n' "$out" >&2
+        die "ios-deploy could not install $APP_PATH onto $udid — the output above is installd's reason; the device must be unlocked and trusting this Mac" 2
+      }
+      ios-deploy --id "$udid" --no-wifi --exists --bundle_id "${B_ID:-$BUNDLE}" >/dev/null 2>&1 \
+        || die "install reported success but ${B_ID:-$BUNDLE} is not present — check the bundle id in $DT_CONFIG" 4
+    fi
+
+    # What went on, and where. Written down as well as printed, because the
+    # device will not tell anyone afterwards.
+    when="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+    printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
+      "${B_ID:-$BUNDLE}" "$B_VER" "$B_BLD" "$B_TEAM" "$when" "$APP_PATH" > "$(install_record)"
+
+    printf 'OK installed %s\n' "${B_ID:-$BUNDLE}"
+    printf '   version  %s (%s)\n' "${B_VER:-?}" "${B_BLD:-?}"
+    printf '   signed   %s%s\n' "$B_SIG" "${B_TEAM:+, team $B_TEAM}"
+    printf '   onto     %s%s\n' "$udid" "$(device_name_note "$udid")"
+    printf '   from     %s\n' "$APP_PATH"
+
+    if [ "$LAUNCH_AFTER" -eq 1 ]; then
+      # What was installed is what gets launched and watched. wait_for_state
+      # reads $BUNDLE, so pointing it at the bundle just installed is what keeps
+      # the verification about the same app as the action.
+      BUNDLE="${B_ID:-$BUNDLE}"
+      wda_drop_session
+      resp="$(session_post '/wda/apps/launch' "$(jq -nc --arg b "$BUNDLE" '{bundleId: $b}')")"
+      err="$(session_error "$resp")"
+      [ -z "$err" ] || die "installed, but launch failed — $err" 3
+      s="$(wait_for_state foreground "installed and launched but never reached the foreground")"
+      printf 'OK launched %s — %s\n' "$BUNDLE" "$(state_name "$s")"
+    fi
+    ;;
+
+  uninstall)
+    [ $# -le 1 ] || die "app.sh uninstall takes at most one bundle id" 1
+    TARGET="${1:-$BUNDLE}"
+    udid="$(device_udid)"
+    if [ "$(ios_kind)" = simulator ]; then
+      xcrun simctl uninstall "$udid" "$TARGET" >/dev/null 2>&1 \
+        || die "simctl could not uninstall $TARGET" 2
+    else
+      need_cmd ios-deploy
+      ios-deploy --id "$udid" --no-wifi --uninstall_only --bundle_id "$TARGET" >/dev/null 2>&1 \
+        || die "ios-deploy could not uninstall $TARGET — is it installed?" 2
+      ios-deploy --id "$udid" --no-wifi --exists --bundle_id "$TARGET" >/dev/null 2>&1 \
+        && die "uninstall reported success but $TARGET is still present" 4
+    fi
+    [ "$TARGET" = "$(cut -f1 "$(install_record)" 2>/dev/null || true)" ] \
+      && rm -f "$(install_record)"
+    printf 'OK uninstalled %s from %s\n' "$TARGET" "$udid"
+    ;;
+
+  build)
+    [ $# -eq 0 ] || die "app.sh build takes no arguments" 1
+    BUILD_CMD="$(cfg '.app.build_command' '')"
+    [ -n "$BUILD_CMD" ] \
+      || die "app.build_command is not set in $DT_CONFIG — DeviceTools does not guess how to build your app" 2
+    # Build output is the one place a wall of text is correct: a compiler error
+    # is what the caller needs, and abbreviating it helps nobody.
+    ( eval "$BUILD_CMD" ) || die "build failed — see the output above" 2
+    printf 'OK built %s\n' "$BUNDLE"
+    ;;
+
+  *)
+    die "unknown verb '$CMD' (usage: app.sh state|launch|kill|relaunch|reset|install|uninstall|build)" 1
+    ;;
+esac
+
+# The screen the verb left behind, when it was asked for.
+act_snapshot_now

package/scripts/ios/back.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# back.sh — go back one screen.
+#
+#   back.sh [--method nav|swipe]
+#
+# Android has a system back button. iOS does not, and pretending otherwise is
+# how a cross-platform abstraction starts lying. On iOS "back" is either the
+# navigation bar's leading button or an edge swipe, and which one works depends
+# on the app.
+#
+# So this tries the navigation bar first and falls back to the edge swipe, and
+# it says which one it used. An honest heuristic, named as a heuristic, beats a
+# silent one — when a test fails you can see whether the gesture was even the
+# right idea.
+#
+# It then verifies that the screen actually changed. A back that does nothing is
+# worse than a back that fails: the test carries on believing it moved.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  went back, and the screen changed
+# exit 1  usage error
+# exit 3  WebDriverAgent unreachable — run doctor.sh
+# exit 4  nothing to go back to, or the screen did not change
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+METHOD=auto
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --method)
+      [ $# -ge 2 ] || die "--method needs nav or swipe" 1
+      case "$2" in nav|swipe) METHOD="$2" ;; *) die "--method must be nav or swipe, got: $2" 1 ;; esac
+      shift 2 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: back.sh [--method nav|swipe])" 1 ;;
+  esac
+done
+
+load_config
+
+src="$(fetch_source)"
+before="$(drv_fingerprint "$src")"
+act_before
+
+read -r WIN_W WIN_H <<< "$(window_size)"
+
+# The leading button of a navigation bar: a Button inside a NavigationBar,
+# within the left third of the screen. Matching by position rather than by label
+# is deliberate — the back button's label is the previous screen's title, which
+# changes with every screen and with the app's language.
+nav_button="$(printf '%s' "$src" | jq -r --argjson third "$((WIN_W / 3))" "$JQ_CLEAN"'
+  def bar_children($inbar):
+    . as $n
+    | (if ($n.type // "") == "NavigationBar" then true else $inbar end) as $under
+    | (if $under and (($n.type // "") == "Button")
+         and ((($n.isVisible // "") == "1"))
+         and ((.rect.x // 0) + ((.rect.width // 0) / 2) < $third)
+         and ((.rect.width // 0) > 0)
+       then [{x: (.rect.x // 0), y: (.rect.y // 0), w: (.rect.width // 0), h: (.rect.height // 0),
+              lb: (.label | clean)}] else [] end)
+    + ([ (.children // [])[] | bar_children($under) ] | add // []);
+  (.value | bar_children(false)) | .[0] // empty
+  | "\(.x + (.w / 2) | floor)|\(.y + (.h / 2) | floor)|\(.lb)"
+' 2>/dev/null || true)"
+
+used=""
+if [ "$METHOD" != swipe ] && [ -n "$nav_button" ]; then
+  IFS='|' read -r BX BY BLB <<< "$nav_button"
+  err="$(drv_tap "$BX" "$BY" || true)"
+  [ -z "$err" ] || die "tapping the navigation back button at $BX,$BY failed — $err" 3
+  used="navigation bar button at $BX,$BY${BLB:+ \"$BLB\"}"
+elif [ "$METHOD" = nav ]; then
+  die "no navigation bar back button on this screen — try --method swipe" 4
+else
+  FY=$(( WIN_H / 2 ))
+  TX=$(( WIN_W * 60 / 100 ))
+  err="$(drv_drag 2 "$FY" "$TX" "$FY" 100 || true)"
+  [ -z "$err" ] || die "edge swipe failed — $err" 3
+  used="edge swipe from 2,$FY"
+fi
+
+after="$(drv_fingerprint "$(fetch_source)")"
+[ "$before" != "$after" ] \
+  || die "went back using the $used but the screen did not change — there may be nothing to go back to" 4
+
+# back already refuses when the screen did not move, so the SCREEN line here
+# is not the verdict — it is which screen you have arrived at, and what the app
+# said on the way.
+act_report BACK "$used"
+journal_append back "" "" "" "" "" 0 0 0 0 "$DT_ACT_HASH"

package/scripts/ios/controls.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# controls.sh — the things on this screen you can actually act on.
+#
+#   controls.sh [--all]
+#
+# One line per interactive element, in find.sh's columns:
+#
+#   type | id | label | text | x,y,w,h
+#
+# This is usually a better first question than `tree`. A screen with 150
+# elements has perhaps a dozen you can tap, and those dozen are what a test is
+# written against; the rest is layout.
+#
+# HOW THIS DIFFERS FROM THE ANDROID ADAPTER, AND WHY IT IS WEAKER
+#
+# Android publishes `clickable` on the element, so its answer is exact. iOS does
+# not publish anything equivalent, so this infers from the element's type — and
+# the type is already known to be unreliable here: on the app this was built
+# against, the same password field appeared as a plain TextField on one launch
+# and a SecureTextField on the next.
+#
+# So this list is a good starting point and not a guarantee. A control missing
+# from it may still be tappable, and `tap` on a coordinate always works. Said
+# plainly rather than left for someone to discover.
+#
+# --all adds container types that are often tappable rows in practice.
+#
+# exit 0  at least one control
+# exit 1  usage error
+# exit 3  WebDriverAgent unreachable — run doctor.sh
+# exit 4  nothing interactive on screen
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+ALL=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all) ALL=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: controls.sh [--all])" 1 ;;
+  esac
+done
+
+load_config
+src="$(fetch_source)"
+
+# The types a user can act on live in lib.sh, because tree.sh needs the same
+# list to avoid hiding an unlabelled control.
+CORE="$DT_TAPPABLE_TYPES"
+EXTRA='Cell|CollectionView|Tab|TabBar|NavigationBar|Icon|Image'
+
+if [ "$ALL" -eq 1 ]; then
+  WANT="$CORE|$EXTRA"
+else
+  WANT="$CORE"
+fi
+
+rows="$(printf '%s' "$src" | jq -r --arg want "$WANT" "$JQ_CLEAN"'
+  (.value | walk(0))
+  | map(select(.vis and .w > 0 and .h > 0))
+  | map(select(.t | test("^(" + $want + ")$")))
+  | .[]
+  | "\(.t) | \(.id) | \(.lb) | \(.v) | \(.x),\(.y),\(.w),\(.h)"
+')"
+
+[ -n "$rows" ] || die "nothing interactive on screen — is the app in the foreground?" 4
+
+printf '%s\n' "$rows"

package/scripts/ios/devices.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# devices.sh — what is attached, one per line.
+#
+#   devices.sh [--ready]
+#
+# Output, pipe-separated so it parses without a JSON reader:
+#
+#   <udid> | <kind> | <name> | <state>
+#
+# kind is device or simulator. state is ready, not-paired or locked. A device
+# that is attached but not usable is still listed, with the reason, because
+# "nothing attached" and "attached but you never tapped Trust" call for
+# completely different actions.
+#
+# Simulators are listed only when booted. A shut-down simulator is not a device
+# anything can drive, and listing it would put an unusable entry into a fleet.
+#
+# --ready lists only the ones that can be driven.
+#
+# exit 0  at least one device listed
+# exit 1  usage error
+# exit 2  neither libimobiledevice nor xcrun is available
+# exit 4  nothing attached (or nothing ready, with --ready)
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+READY_ONLY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ready) READY_ONLY=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: devices.sh [--ready])" 1 ;;
+  esac
+done
+
+load_config
+
+have_imd=0; command -v idevice_id >/dev/null 2>&1 && have_imd=1
+have_xcrun=0; command -v xcrun >/dev/null 2>&1 && have_xcrun=1
+[ "$have_imd" -eq 1 ] || [ "$have_xcrun" -eq 1 ] \
+  || die "neither idevice_id nor xcrun is available — brew install libimobiledevice, or install Xcode" 2
+
+emit() {  # emit <udid> <kind> <name> <state>
+  [ "$READY_ONLY" -eq 0 ] || [ "$4" = ready ] || return 0
+  printf '%s | %s | %s | %s\n' "$1" "$2" "$3" "$4"
+  N=$(( N + 1 ))
+}
+N=0
+
+if [ "$have_imd" -eq 1 ]; then
+  while IFS= read -r udid; do
+    [ -n "$udid" ] || continue
+    # ideviceinfo answers only for a paired device that is unlocked enough to be
+    # queried, so its failure is the signal, not an error to be swallowed.
+    name="$(ideviceinfo -u "$udid" -k DeviceName 2>/dev/null | tr -d '\r')"
+    if [ -n "$name" ]; then
+      ver="$(ideviceinfo -u "$udid" -k ProductVersion 2>/dev/null | tr -d '\r')"
+      emit "$udid" device "${name}${ver:+ (iOS $ver)}" ready
+    else
+      emit "$udid" device "$udid" not-paired
+    fi
+  done <<< "$(idevice_id -l 2>/dev/null | tr -d '\r')"
+fi
+
+if [ "$have_xcrun" -eq 1 ]; then
+  while IFS='|' read -r udid name; do
+    [ -n "$udid" ] || continue
+    emit "$udid" simulator "$name" ready
+  done <<< "$(xcrun simctl list devices -j 2>/dev/null \
+    | jq -r '.devices | to_entries[] | .value[]
+             | select(.state == "Booted")
+             | "\(.udid)|\(.name)"' 2>/dev/null)"
+fi
+
+if [ "$N" -eq 0 ]; then
+  if [ "$READY_ONLY" -eq 1 ]; then
+    die "no device is ready — run $(as_cmd devices) without --ready to see what is attached" 4
+  fi
+  die "nothing attached — connect a device over USB or boot a simulator" 4
+fi