device-devtools-mcp 0.1.0

package/scripts/ios/logs.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# logs.sh — device logs, collected in the background and read on demand.
+#
+#   logs.sh start                       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 has been collected
+#   --raw                               every line the device logged, not just
+#                                       the app's. The default keeps only the
+#                                       app's own output: the OS logs a great
+#                                       deal on an app's behalf under its
+#                                       process name, and none of that is the
+#                                       app talking. Use this when the default
+#                                       is empty and you need to know why.
+#   --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 A COLLECTOR RATHER THAN A QUERY
+#
+# `idevicesyslog` is a live stream, not a searchable store: there is no way to
+# ask it what happened thirty seconds ago. So collection has to be running
+# before the thing you want to read about happens. Reading without a collector
+# would quietly return nothing, which reads exactly like "there were no logs" —
+# so instead it starts one and says the history begins here.
+#
+# NO --subsystem
+#
+# `--subsystem` is an os_log concept. On a pre-iOS-17 device reached through
+# idevicesyslog the subsystem is not carried, so the flag would be a filter that
+# silently matched nothing. --process and --grep are what actually exist.
+#
+# exit 0  lines printed, or a lifecycle verb succeeded
+# exit 1  usage error
+# exit 2  environment problem
+# exit 4  nothing was being collected, or nothing matched
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+SINCE=""
+PROCESS=""
+GREP=""
+NETWORK=0
+RAW=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 ;;
+    --raw) RAW=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
+[ "$(ios_kind)" = simulator ] || need_cmd idevicesyslog
+
+SD="$(state_dir)"
+PIDFILE="$SD/syslog.pid"
+LOGFILE="$SD/syslog.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"
+}
+
+start_collector() {
+  local udid max source
+  udid="$(device_udid)"
+  max="$(cfg '.logs.max_lines_kept' '200000')"
+
+  # Different producer, same contract: one line per log record on stdout. The
+  # stamping and rotation below do not care which one is upstream.
+  if [ "$(ios_kind)" = simulator ]; then
+    source="xcrun simctl spawn '$udid' log stream --style syslog --level debug"
+  else
+    source="idevicesyslog -u '$udid'"
+  fi
+  # Two things happen in this writer, and both have to happen in the writer
+  # rather than in the reader.
+  #
+  # Each line is prefixed with the epoch second it arrived: idevicesyslog's own
+  # timestamps carry no year and no timezone, which makes "the last N seconds"
+  # unanswerable across midnight.
+  #
+  # And the file is rotated at max lines. The device produced 21,000 lines in
+  # thirty seconds during testing, so an uncapped collector left running fills
+  # the disk. Rotation belongs here because a reader that truncates a file an
+  # open writer is appending to leaves the writer's offset past the new end,
+  # and every later line lands after a gap of NULs.
+  nohup sh -c "$source 2>/dev/null | perl -e '
+    \$| = 1;
+    my (\$f, \$max) = @ARGV;
+    my \$n = 0;
+    open(my \$fh, q{>>}, \$f) or die;
+    \$fh->autoflush(1);
+    while (my \$l = <STDIN>) {
+      print \$fh time() . qq{\t} . \$l;
+      if (++\$n >= \$max) { close \$fh; rename(\$f, \$f . q{.1}); open(\$fh, q{>}, \$f) or die; \$fh->autoflush(1); \$n = 0; }
+    }' '$LOGFILE' '$max'" \
+    >/dev/null 2>&1 &
+  printf '%s' "$!" > "$PIDFILE"
+  for _ in $(seq 1 20); do
+    collector_pid >/dev/null 2>&1 && break
+    sleep 0.2
+  done
+}
+
+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
+    start_collector
+    pid="$(collector_pid)" || die "could not start idevicesyslog — see $LOGFILE" 2
+    printf 'OK logs — 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 have to go
+    # too or idevicesyslog keeps the USB 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
+      printf 'OK logs — collecting (pid %s, %s lines) since %s\n' \
+        "$pid" "$(wc -l < "$LOGFILE" 2>/dev/null | tr -d ' ' || echo 0)" \
+        "$(head -1 "$LOGFILE" 2>/dev/null | cut -f1 | xargs -I{} date -r {} '+%H:%M:%S' 2>/dev/null || echo 'unknown')"
+    else
+      printf 'OK logs — not collecting\n'
+    fi
+    exit 0
+    ;;
+esac
+
+# --- read ---------------------------------------------------------------------
+
+if ! collector_pid >/dev/null 2>&1; then
+  start_collector
+  collector_pid >/dev/null 2>&1 \
+    || die "log collection was not running and could not be started — see $LOGFILE" 2
+  die "log collection was not running; it is now — history begins here, so repeat the action and read again" 4
+fi
+
+[ -s "$LOGFILE" ] || [ -s "$LOGFILE.1" ] \
+  || die "nothing collected yet — the device has not logged since collection started" 4
+
+CUTOFF=0
+[ -n "$SINCE" ] && CUTOFF="$(( $(date +%s) - SINCE ))"
+[ -n "$LINES" ] || LINES="$(cfg '.logs.max_lines' '50')"
+
+# The rotated half first, so the result stays in chronological order.
+ROTATED=""
+[ -s "$LOGFILE.1" ] && ROTATED="$LOGFILE.1"
+out="$(awk -F'\t' -v cutoff="$CUTOFF" '$1 >= cutoff { sub(/^[0-9]+\t/, ""); print }' $ROTATED "$LOGFILE")"
+
+# THE APP'S OWN LINES BY DEFAULT.
+#
+# The whole device syslog is thirty-five thousand lines of other people's
+# processes, and even the lines carrying this app's process name are mostly the
+# OS logging on its behalf. --raw is the way back to all of it, and --process
+# says which other process to look at instead.
+UNFILTERED="$out"
+if [ -n "$PROCESS" ]; then
+  out="$(printf '%s\n' "$out" | grep -F -- "$PROCESS" || true)"
+elif [ "$RAW" -eq 0 ]; then
+  out="$(printf '%s\n' "$out" | log_filter)"
+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.
+  # Scoping to the app already happened above, unless --raw asked for
+  # everything, in which case the caller said what they wanted.
+  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
+
+# A blank string still prints one empty line, which would read as a result.
+out="$(printf '%s\n' "$out" | sed '/^[[:space:]]*$/d')"
+
+if [ -z "$out" ]; then
+  filters=""
+  [ -n "$SINCE" ]   && filters="$filters --since ${SINCE}s"
+  [ -n "$PROCESS" ] && filters="$filters --process $PROCESS"
+  [ -n "$GREP" ]    && filters="$filters --grep $GREP"
+
+  # "Nothing" and "nothing of yours" are different answers, and the second one
+  # is the common one: an app that never calls os_log still has the OS logging
+  # on its behalf, and saying how many of those there were is the difference
+  # between "the log is broken" and "this app does not log".
+  extra=""
+  if [ "$RAW" -eq 0 ] && [ -z "$PROCESS" ]; then
+    app="$(cfg '.app.bundle_id' '')"; app="${app##*.}"
+    if [ -n "$app" ]; then
+      mine="$(printf '%s\n' "$UNFILTERED" \
+              | grep -icE "^[A-Za-z]{3} +[0-9]+ +[0-9:.]+ +${app}[([]" || true)"
+      [ "${mine:-0}" -gt 0 ] \
+        && extra=" — $mine line(s) carry this app's process name, all of them from system frameworks; --raw shows them"
+    fi
+  fi
+  die "no log lines from the app under test${filters:- }${extra} — $(wc -l < "$LOGFILE" | tr -d ' ') lines collected in total" 4
+fi
+
+n="$(printf '%s\n' "$out" | wc -l | tr -d ' ')"
+if [ "$n" -le "$LINES" ]; then
+  printf '%s\n' "$out"
+else
+  # The tail, not the head: when something has just gone wrong, the most recent
+  # lines are the ones that say why.
+  printf '%s\n' "$out" | tail -n "$LINES"
+  printf '… %s earlier lines dropped (--lines N)\n' "$(( n - LINES ))"
+fi

package/scripts/ios/permission.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# permission.sh — grant or deny a privacy permission before the app asks.
+#
+#   permission.sh <name>=<allow|deny> [<name>=<allow|deny> ...]
+#
+#   permission.sh location=allow contacts=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.
+#
+# TWO LIMITS THIS PLATFORM HAS AND ANDROID DOES NOT
+#
+# A physical iPhone has no interface for setting privacy permissions from the
+# host. None: not in WebDriverAgent, not in Apple's own device tooling. So on a
+# device this fails and says so, rather than reporting a success it did not
+# achieve. Drive the dialog instead:
+#
+#   - tap: { label: Cho phép, optional: true }
+#
+# And even on a simulator, Apple's list has no camera service. `camera=allow` is
+# therefore refused rather than quietly skipped.
+#
+# exit 0  every permission is now in the requested state
+# exit 1  usage error, or a name this platform does not have
+# exit 2  a physical device, where this cannot be done at all
+# exit 3  driver 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
+BUNDLE="$(cfg '.app.bundle_id' '')"
+[ -n "$BUNDLE" ] || die "app.bundle_id is not set in $DT_CONFIG — permissions are granted to a bundle" 2
+
+[ "$(ios_kind)" = simulator ] \
+  || die "a physical iPhone has no host-side permission API — drive the dialog instead: tap: { label: <allow button>, optional: true }" 2
+
+UDID="$(device_udid)"
+
+# The neutral names, mapped onto Apple's service list. Names Android has and
+# this does not are absent on purpose: refusing is the point, since a permission
+# step that silently did nothing is worse than one that failed.
+ios_service() {
+  case "$1" in
+    microphone)      printf 'microphone' ;;
+    location)        printf 'location' ;;
+    location-always) printf 'location-always' ;;
+    contacts)        printf 'contacts' ;;
+    photos)          printf 'photos' ;;
+    photos-add)      printf 'photos-add' ;;
+    calendar)        printf 'calendar' ;;
+    reminders)       printf 'reminders' ;;
+    motion)          printf 'motion' ;;
+    siri)            printf 'siri' ;;
+    media)           printf 'media-library' ;;
+    *) return 1 ;;
+  esac
+}
+
+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
+
+  service="$(ios_service "$name" || true)"
+  if [ -z "$service" ]; then
+    case "$name" in
+      camera) die "iOS has no settable camera permission — Apple's privacy service list omits it. Drive the dialog: tap: { label: <allow button>, optional: true }" 1 ;;
+      notifications|storage|phone|sms) die "'$name' is an Android permission with no iOS equivalent — remove it from this test, or guard the step with platform:" 1 ;;
+      *) die "no such permission name '$name' — known here: microphone location location-always contacts photos photos-add calendar reminders motion siri media" 1 ;;
+    esac
+  fi
+
+  action=grant
+  [ "$want" = deny ] && action=revoke
+
+  # simctl says nothing useful on success and prints one line on failure, so its
+  # output is what gets reported rather than a generic message.
+  out="$(xcrun simctl privacy "$UDID" "$action" "$service" "$BUNDLE" 2>&1 || true)"
+  case "$out" in
+    "") ;;
+    *) die "could not $want '$name' for $BUNDLE — $(first_line "$out")" 4 ;;
+  esac
+
+  DONE="$DONE $name=$want"
+done
+
+# Apple exposes no way to read a permission back, so unlike the Android adapter
+# this cannot verify the result — only that the command reported no error. Said
+# here rather than left for someone to assume the two platforms check equally.
+printf 'OK permissions for %s —%s (applied, not read back: iOS exposes no query)\n' "$BUNDLE" "$DONE"

package/scripts/ios/settings.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# settings.sh — the device conditions a person would change by hand.
+#
+#   settings.sh appearance  light|dark
+#   settings.sh textsize    <named size>
+#   settings.sh orientation portrait|landscape
+#
+# ON A SIMULATOR these go through simctl and are immediate.
+#
+# ON A PHYSICAL iPHONE THERE IS NO API FOR ANY OF THIS, AND THIS VERB REFUSES.
+#
+# iOS exposes no way to set appearance, text size or rotation on a real device
+# from outside it. The only implementation available is the one a person would
+# use — open Settings, navigate, tap the switch — and that has never been run
+# here. Shipping an untested walk through another app's interface would be a
+# claim this repository does not make: docs/RELEASE.md lists what has evidence
+# beside it, and this would have none.
+#
+# So on a device it exits 2 and says to change it by hand. That is a worse
+# answer than working, and a much better one than appearing to work.
+#
+# exit 0  set
+# exit 1  usage error
+# exit 2  not supported on this target
+# exit 3  the simulator refused it
+
+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 <appearance|textsize|orientation> <value>" 1
+[ $# -eq 2 ] || die "too many arguments (usage: settings.sh <key> <value>)" 1
+
+case "$KEY" in
+  appearance|textsize|orientation) ;;
+  *) die "unknown setting '$KEY' — appearance, textsize or orientation" 1 ;;
+esac
+
+load_config
+UDID="$(device_udid)"
+
+if [ "$(ios_kind)" != simulator ]; then
+  die "settings on a physical iPhone is not implemented — iOS exposes no API for it, and driving the Settings app by hand has never been run here. Change '$KEY' on the device, or point the config at a simulator" 2
+fi
+
+need_cmd xcrun
+
+case "$KEY" in
+  appearance)
+    case "$VAL" in light|dark) ;; *) die "appearance is light or dark, got '$VAL'" 1 ;; esac
+    xcrun simctl ui "$UDID" appearance "$VAL" >/dev/null 2>&1 \
+      || die "simctl refused it — is the simulator booted?" 3
+    ;;
+  textsize)
+    # simctl takes a named content size, not a scale. The names are the ones
+    # Settings shows, and passing a number gets a message from simctl that does
+    # not say so, which is why the list is here.
+    case "$VAL" in
+      extra-small|small|medium|large|extra-large|extra-extra-large|extra-extra-extra-large) ;;
+      accessibility-medium|accessibility-large|accessibility-extra-large) ;;
+      accessibility-extra-extra-large|accessibility-extra-extra-extra-large) ;;
+      *) die "textsize takes a named size, not a number: extra-small, small, medium, large, extra-large, extra-extra-large, extra-extra-extra-large, or accessibility-medium through accessibility-extra-extra-extra-large — got '$VAL'" 1 ;;
+    esac
+    xcrun simctl ui "$UDID" content_size "$VAL" >/dev/null 2>&1 \
+      || die "simctl refused it — is the simulator booted?" 3
+    ;;
+  orientation)
+    case "$VAL" in portrait|landscape) ;; *) die "orientation is portrait or landscape, got '$VAL'" 1 ;; esac
+    die "simctl cannot rotate a simulator — rotate it from the Simulator's Device menu, or use an Android target" 2
+    ;;
+esac
+
+printf 'OK settings — %s is now %s\n' "$KEY" "$VAL"

package/scripts/ios/setup.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# setup.sh — build and sign WebDriverAgent for the configured target.
+#
+#   setup.sh [--force]
+#
+# WHY THIS EXISTS AS A COMMAND
+#
+# The README asked a new user to clone WebDriverAgent, rewrite its bundle
+# identifiers with sed, and get an xcodebuild signing invocation right. Every
+# step of that is knowledge this repository already has — it is what CI does on
+# every macOS run, and what the person who set this machine up did once by hand.
+# A hundred lines of prose is a worse copy of a script.
+#
+# WHAT IT WILL NOT DO
+#
+# Sign in to Xcode, and register a device with Apple. Both are interactive
+# credential operations, and a tool that appeared to do them would be lying
+# about where the failure came from. When either is missing the build fails with
+# a message Apple wrote for a different audience, so the log is read here and
+# the actual cause is named.
+#
+# exit 0  WebDriverAgent is built for this target
+# exit 1  usage error
+# exit 2  configuration, checkout, or build problem
+
+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 git
+need_cmd xcodebuild
+
+say() { printf '%s %s — %s\n' "$1" "$2" "$3"; }
+
+PROJECT="$(expand_path "$(cfg '.wda.project')")"
+WDA_DIR="$(dirname "$PROJECT")"
+PREFIX="$(cfg '.wda.bundle_id_prefix')"
+TEAM="$(cfg '.wda.team_id' '')"
+SCHEME="$(cfg '.wda.scheme' 'WebDriverAgentRunner')"
+KIND="$(ios_kind)"
+UDID="$(device_udid)"
+DERIVED="$(wda_derived)"
+
+# --- 1. the checkout ----------------------------------------------------------
+
+if [ -d "$PROJECT" ]; then
+  say OK checkout "WebDriverAgent already at $WDA_DIR"
+else
+  mkdir -p "$(dirname "$WDA_DIR")" || die "could not create $(dirname "$WDA_DIR")" 2
+  # --depth 1: nobody here needs its history, and a shallow clone is a tenth of
+  # the download on a connection that may be someone's phone.
+  git clone --depth 1 https://github.com/appium/WebDriverAgent.git "$WDA_DIR" >/dev/null 2>&1 \
+    || die "could not clone WebDriverAgent into $WDA_DIR — check the path in wda.project and that the directory is writable" 2
+  say OK checkout "cloned into $WDA_DIR"
+  [ -d "$PROJECT" ] \
+    || die "cloned, but $PROJECT does not exist — wda.project should point at <checkout>/WebDriverAgent.xcodeproj" 2
+fi
+
+# --- 2. the bundle identifiers ------------------------------------------------
+#
+# Upstream ships com.facebook.* identifiers, which nobody outside Meta can sign.
+# The .orig copy is kept because this edits a file the user owns and will one
+# day want to `git pull` over.
+
+PBX="$PROJECT/project.pbxproj"
+[ -f "$PBX" ] || die "no project file at $PBX" 2
+
+if grep -q 'com\.facebook\.WebDriverAgentRunner' "$PBX" 2>/dev/null || [ "$FORCE" -eq 1 ]; then
+  [ -f "$PBX.orig" ] || cp "$PBX" "$PBX.orig"
+  sed -i '' \
+    -e "s/com\.facebook\.WebDriverAgentRunner/$PREFIX.WebDriverAgentRunner/g" \
+    -e "s/com\.facebook\.WebDriverAgentLib/$PREFIX.WebDriverAgentLib/g" \
+    "$PBX" \
+    || die "could not rewrite bundle identifiers in $PBX" 2
+  say OK identifiers "rewritten to $PREFIX.* (original kept as project.pbxproj.orig)"
+else
+  say OK identifiers "already $PREFIX.*"
+fi
+
+# --- 3. the build -------------------------------------------------------------
+#
+# A SIMULATOR BUILD IS NOT SIGNED, AND THAT IS THE WHOLE REASON iOS RUNS IN CI.
+#
+# CODE_SIGNING_ALLOWED=NO makes the simulator build need no account, no team and
+# no device registration — which is what lets a hosted macOS runner do this.
+# A device build needs all three, and the command line is where the team goes:
+# the only DEVELOPMENT_TEAM entries in the project belong to a tvOS target, so
+# editing the project file looks like it worked and changes nothing.
+
+LOG="$(state_dir)/wda-build.log"
+if [ "$KIND" = simulator ]; then
+  DEST="id=$UDID"
+  set -- build-for-testing -project "$PROJECT" -scheme "$SCHEME" \
+        -destination "$DEST" -derivedDataPath "$DERIVED" CODE_SIGNING_ALLOWED=NO
+  say OK target "simulator $UDID — no signing required"
+else
+  [ -n "$TEAM" ] \
+    || die "wda.team_id is empty, and a device build must be signed — README.md explains where to find the real Team ID, which is not the value in parentheses in security find-identity" 2
+  DEST="id=$UDID"
+  set -- build-for-testing -project "$PROJECT" -scheme "$SCHEME" \
+        -destination "$DEST" -derivedDataPath "$DERIVED" \
+        -allowProvisioningUpdates DEVELOPMENT_TEAM="$TEAM" CODE_SIGN_STYLE=Automatic
+  say OK target "device $UDID — signing with team $TEAM"
+fi
+
+printf 'RUN xcodebuild build-for-testing (this takes a few minutes the first time)\n'
+if xcodebuild "$@" >"$LOG" 2>&1; then
+  say OK build "WebDriverAgent built into $DERIVED"
+else
+  # THE LOG KNOWS WHY. SAY IT.
+  #
+  # Every string below is one xcodebuild prints, and each has a different
+  # remedy. "See the log" is the answer a tool gives when it has not looked, and
+  # the log is four hundred lines of which one matters.
+  why="the build failed"
+  if grep -q 'Unable to find a destination matching' "$LOG" 2>/dev/null; then
+    # Found the first time this was run against a real iPhone: the phone was
+    # paired and listed by idevice_id, and Xcode still could not see it. That is
+    # what a locked screen, a pulled cable or an untrusted computer looks like
+    # from here, and the message Apple prints names none of them.
+    if [ "$KIND" = simulator ]; then
+      why="Xcode has no simulator with UDID $UDID — check device.udid against xcrun simctl list devices"
+    # NOT `xctrace … | grep -q`, AND NOT `printf … | grep -q` EITHER.
+    #
+    # grep -q exits the moment it matches, so the write end takes SIGPIPE.
+    # Under `set -o pipefail` — which lib.sh sets — the first spelling reported
+    # 141 even though the string was found, and the branch never fired: the
+    # message said "never seen" about a device Xcode was listing. Feeding it
+    # from printf instead fixed the exit code and left the shell writing into a
+    # closed pipe, which prints `printf: write error: Broken pipe` on stderr for
+    # every device that IS found. A case pattern has neither problem.
+    elif case "$(xcrun xctrace list devices 2>/dev/null)" in *"$UDID"*) true ;; *) false ;; esac; then
+      # Xcode knows the device and still will not build for it. Measured: the
+      # phone had been unplugged, and it lingers in the device list because it
+      # is remembered, not because it is reachable. Saying "no such device"
+      # there sends someone to check the UDID, which is correct.
+      why="Xcode knows device $UDID but cannot reach it — it is remembered from a previous session, not connected now: plug it in over USB and unlock the screen"
+    else
+      why="Xcode has never seen device $UDID — attach it over USB, unlock the screen, and trust this computer when it asks; note that idevice_id -l can list a device Xcode does not have"
+    fi
+  elif grep -q 'No Account for Team' "$LOG" 2>/dev/null; then
+    why="no Apple ID in Xcode is a member of team $TEAM — Xcode → Settings → Accounts → +, then run this again. This is the one step that cannot be scripted"
+  elif grep -q "isn't registered in your developer account" "$LOG" 2>/dev/null; then
+    why="the device is not registered in team $TEAM — register $UDID at developer.apple.com under Devices, in that team, then run this again. Check the UDID character by character: two iPhones of the same model differ only in the middle"
+  elif grep -q 'Provisioning profile .* doesn' "$LOG" 2>/dev/null; then
+    why="the provisioning profile does not include $UDID — register the device in team $TEAM at developer.apple.com, then run this again"
+  elif grep -q 'requires a development team' "$LOG" 2>/dev/null; then
+    why="the build wants a development team and wda.team_id is '$TEAM'"
+  elif grep -q 'xcode-select' "$LOG" 2>/dev/null; then
+    why="the command line tools are selected instead of Xcode — sudo xcode-select --switch /Applications/Xcode.app"
+  fi
+  die "$why — full log at $LOG" 2
+fi
+
+# --- 4. what came out ---------------------------------------------------------
+#
+# An .xctestrun is what doctor actually runs, so its absence is the failure
+# worth catching here rather than three commands later.
+XCTESTRUN="$(ls "$DERIVED"/Build/Products/*.xctestrun 2>/dev/null | head -1 || true)"
+[ -n "$XCTESTRUN" ] \
+  || die "the build reported success but no .xctestrun is in $DERIVED/Build/Products — full log at $LOG" 2
+say OK product "$(basename "$XCTESTRUN")"
+
+if [ "$KIND" = device ]; then
+  printf 'NOTE the first launch on a device needs the certificate trusted by hand: Settings → General → VPN & Device Management\n'
+fi
+printf 'NEXT %s\n' "$(as_cmd doctor --recover)"