device-devtools-mcp 0.1.0

package/scripts/ios/tree.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# tree.sh — the accessibility tree, reduced to something an agent can afford to read.
+#
+#   tree.sh [--all] [--depth N] [--grep S]
+#
+# One line per element:
+#
+#   depth | type | id | label | value | x,y,w,h
+#
+# Raw /source JSON for a single screen measured 107 KB (~27k tokens) on the
+# device this was built against. Reduced, the same screen is ~1.7 KB (~430
+# tokens). Raw JSON must never reach the agent, so this script is the only
+# supported way to read the tree.
+#
+# By default an element is shown when it is visible AND it either carries an
+# identifier, a label or a value, or is of a type a user can act on. An
+# invisible element with a label is noise; an unlabelled button is not, because
+# it can still be reached by coordinate or by structure, and a screen whose only
+# three controls are unlabelled would otherwise read as having nothing to tap.
+#
+#   --all        every element, no filter and no cap
+#   --full       do not truncate strings at 48 characters
+#   --depth N    only elements at depth <= N
+#   --grep S     case-insensitive substring of id, label, value or type.
+#                Searches the whole tree, including elements the default filter
+#                hides, so it can find something that is present but off-screen.
+#
+# Output is capped at tree.max_lines from the config and always ends with
+#   … N more elements (--all)
+# when truncated, so a partial tree can never be mistaken for a complete one.
+#
+# exit 0  at least one element printed
+# exit 1  usage error
+# exit 3  WebDriverAgent unreachable — run doctor.sh
+# exit 4  nothing matched
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+ALL=0
+FULL=0
+DEPTH=-1
+GREP=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all) ALL=1; shift ;;
+    # Repair needs exact strings. A label cut at 48 characters cannot be turned
+    # into a selector that matches, so a caller capturing a failure dump asks for
+    # this while everything an agent reads interactively keeps the cap.
+    --full) FULL=1; shift ;;
+    --depth)
+      [ $# -ge 2 ] || die "--depth needs a number" 1
+      case "$2" in (*[!0-9]*|"") die "--depth needs a non-negative integer, got: $2" 1 ;; esac
+      DEPTH="$2"; shift 2 ;;
+    --grep)
+      [ $# -ge 2 ] || die "--grep needs a string" 1
+      GREP="$2"; shift 2 ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: tree.sh [--all] [--full] [--depth N] [--grep S])" 1 ;;
+  esac
+done
+
+load_config
+MAXLINES="$(cfg '.tree.max_lines' '60')"
+
+src="$(wda_get '/source?format=json')"
+printf '%s' "$src" | jq -e '.value' >/dev/null 2>&1 \
+  || die "WebDriverAgent returned no tree — run $(as_cmd doctor)" 3
+
+# One jq pass: flatten, sanitise, filter, format.
+#
+# Labels come from application copy and can contain newlines and pipes, both of
+# which would break the line-oriented contract. They are neutralised here rather
+# than downstream, so every consumer sees the same shape. Long strings are
+# truncated for the same reason the whole script exists: an unbounded label is
+# an unbounded token cost.
+rows="$(printf '%s' "$src" | jq -r --argjson all "$ALL" --argjson depth "$DEPTH" --arg grep "$GREP" --argjson full "$FULL" --arg tappable "$DT_TAPPABLE_TYPES" '
+  def clean:
+    if . == null then ""
+    elif type != "string" then tostring
+    else gsub("[\n\r\t]+"; " ") | gsub("\\|"; "/") | gsub("  +"; " ") | ltrimstr(" ") | rtrimstr(" ")
+    end;
+  def cut($n): if $full == 1 then . elif (. | length) > $n then (.[0:$n] + "…") else . end;
+
+  def walk($d):
+    [ { d: $d,
+        t:  (.type          | clean),
+        id: (.rawIdentifier | clean),
+        lb: (.label         | clean),
+        v:  (.value         | clean),
+        x: (.rect.x // 0), y: (.rect.y // 0),
+        w: (.rect.width // 0), h: (.rect.height // 0),
+        vis: ((.isVisible // "") == "1")
+      } ]
+    + ([ (.children // [])[] | walk($d + 1) ] | add // []);
+
+  (.value | walk(0))
+  | map(select($depth < 0 or .d <= $depth))
+  | map(select(
+      $grep != "" or $all == 1
+      or (.vis and (.id != "" or .lb != "" or .v != ""
+                    or (.t | test("^(" + $tappable + ")$"))))
+    ))
+  | map(select(
+      $grep == ""
+      or (([.id, .lb, .v, .t] | join(" ") | ascii_downcase)
+          | contains($grep | ascii_downcase))
+    ))
+  | .[]
+  | "\(.d) | \(.t) | \(.id | cut(48)) | \(.lb | cut(48)) | \(.v | cut(48)) | \(.x),\(.y),\(.w),\(.h)"
+')"
+
+if [ -z "$rows" ]; then
+  total="$(printf '%s' "$src" | jq -r '[.. | objects | select(has("type"))] | length' 2>/dev/null || echo '?')"
+  if [ -n "$GREP" ]; then
+    die "no elements matched --grep '$GREP' ($total elements in tree)" 4
+  fi
+  die "no elements matched (tree has $total elements, try --all)" 4
+fi
+
+n="$(printf '%s\n' "$rows" | wc -l | tr -d ' ')"
+
+if [ "$ALL" -eq 1 ] || [ "$n" -le "$MAXLINES" ]; then
+  printf '%s\n' "$rows"
+else
+  printf '%s\n' "$rows" | take_lines "$MAXLINES"
+  printf '… %s more elements (--all)\n' "$(( n - MAXLINES ))"
+fi

package/scripts/ios/type.sh

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+# type.sh — type into whatever currently has keyboard focus, then prove it.
+#
+#   type.sh <text>
+#
+# Verification is the point of this script. Sending keystrokes is one HTTP call;
+# knowing they landed is what stops an agent from building a chain of reasoning
+# on a field that never received the text.
+#
+# WHY IT VERIFIES BY DIFF RATHER THAN BY FOCUS
+#
+# The obvious implementation reads the focused element and checks its value.
+# That does not work here: WebDriverAgent reports `isFocused` on every element,
+# and on the app this was built against zero elements report it as true even
+# while a field visibly holds the caret. So instead this snapshots the value of
+# every text input before and after typing, and reports which one changed.
+#
+# Verification is tiered, because a masked field cannot echo back what you typed:
+#
+#   verified              the field now reads exactly what was typed
+#   verified by change    the field changed but reads something else — a masked
+#                         secure field, or an input mask reformatting as you go
+#   screen changed        no text input in the tree at all, which is how OTP and
+#                         PIN fields are normally built; something moved
+#   nothing changed       exit 4; the keystrokes went nowhere
+#
+# What was typed is reported as a length, not as text, because this runs against
+# a production app and stdout ends up in CI logs. The field's own contents are
+# echoed only when they differ from what was typed, which is the case where a
+# human debugging a failure genuinely needs to see them.
+#
+# --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  typed, and something changed to prove it
+# exit 1  usage error
+# exit 3  WebDriverAgent unreachable — run doctor.sh
+# exit 4  no keyboard on screen, or nothing changed after typing
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+TEXT=""
+HAVE_TEXT=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    # Text that begins with a dash is a real thing to type — a negative amount,
+    # a date — and so is a mistyped flag. Refusing the ambiguous case and
+    # offering `--` is the only reading where a typo cannot end up keyed into a
+    # password field.
+    --) shift
+        [ $# -ge 1 ] || die "-- must be followed by the text to type" 1
+        [ "$HAVE_TEXT" -eq 0 ] || die "type.sh takes one text argument; quote text containing spaces" 1
+        TEXT="$1"; HAVE_TEXT=1; shift ;;
+    -*) die "unknown argument: $1 (usage: type.sh <text> [--snapshot]; use -- before text starting with a dash)" 1 ;;
+    *)
+      [ "$HAVE_TEXT" -eq 0 ] || die "type.sh takes one text argument; quote text containing spaces" 1
+      TEXT="$1"; HAVE_TEXT=1; shift ;;
+  esac
+done
+[ "$HAVE_TEXT" -eq 1 ] || die "missing text (usage: type.sh <text> [--snapshot])" 1
+
+load_config
+
+# rect -> value, one line per text input. The rect is the key because it is the
+# only property of an input that reliably survives the value changing.
+snapshot_inputs() {
+  printf '%s' "$1" | jq -r "$JQ_CLEAN"'
+    (.value | walk(0))
+    | map(select(.vis and .w > 0 and .h > 0))
+    | map(select(.t | test("TextField|SecureTextField|TextView|SearchField")))
+    | .[] | "\(.x),\(.y),\(.w),\(.h)\t\(.t)\t\(.v)"
+  '
+}
+
+# Fetches are assigned to their own variable rather than nested inside another
+# substitution. A failure in `f "$(g)"` is discarded — the exit status seen is
+# f's, not g's — so nesting a call that can fail hides the failure.
+src="$(fetch_source)"
+
+# THE KEYBOARD IS THE PRECONDITION. A TEXT INPUT IN THE TREE IS NOT.
+#
+# Typing with nothing focused makes WebDriverAgent hang until the HTTP timeout
+# rather than returning an error, so the keyboard is checked first. Ten seconds
+# of silence followed by "stuck on this request" is a much worse answer than
+# this one, and this one is also true.
+if ! printf '%s' "$src" | jq -e '[.. | objects | select(.type? == "Keyboard")] | length > 0' >/dev/null 2>&1; then
+  die "no keyboard on screen — tap a field to focus it before typing" 4
+fi
+
+# There used to be a second guard above this one: refuse unless the tree holds
+# something recognisable as a text input. It refused a real OTP sheet with the
+# number pad open and the field holding focus.
+#
+# The reason is a pattern, not an accident. An OTP or PIN field is routinely a
+# real UITextField with `alpha = 0` sitting behind drawn boxes, inside a
+# container that sets isAccessibilityElement = true and so collapses its whole
+# subtree into one node. XCUITest skips a zero-alpha view and reports the
+# container, so the tree shows `Other "8 8 8 8"` and no input anywhere. The
+# keystrokes would have landed; the guard was checking for a thing whose absence
+# is normal.
+#
+# So it is gone, and verification below drops a tier rather than refusing.
+before="$(snapshot_inputs "$src")"
+before_digest="$(content_digest "$src")"
+
+act_before
+payload="$(jq -nc --arg t "$TEXT" '{value: [$t]}')"
+resp="$(session_post '/wda/keys' "$payload")"
+err="$(session_error "$resp")"
+[ -z "$err" ] || die "typing failed — $err" 3
+
+src="$(fetch_source)"
+after="$(snapshot_inputs "$src")"
+after_digest="$(content_digest "$src")"
+
+# Which input changed, if any. Keyed on rect, so a field that moved is treated
+# as a different field rather than silently mismatched.
+#
+# The blank-line guard is load bearing: `printf '%s\n' "$empty"` emits one empty
+# line, which awk counts as a record. Without it, an empty "after" manufactures
+# a phantom changed input and reports success.
+changed="$(awk -F'\t' -v OFS='\t' '
+  $1 == "" { next }
+  NR == FNR { was[$1] = $3; seen[$1] = 1; next }
+  { if (!seen[$1] || was[$1] != $3) print $1, $2, was[$1], $3 }
+' <(printf '%s\n' "$before") <(printf '%s\n' "$after"))"
+
+# VERIFICATION DROPS A TIER, IT DOES NOT REFUSE.
+#
+#   an input changed        the strongest evidence, and the usual case
+#   the screen changed      no input in the tree, but something moved — which
+#                           is all an invisible OTP field can ever offer
+#   nothing changed at all   the keystrokes went nowhere; exit 4
+if [ -n "$changed" ]; then
+  n="$(printf '%s\n' "$changed" | wc -l | tr -d ' ')"
+  line="$(first_line "$changed")"
+  rect="$(printf '%s' "$line" | cut -f1)"
+  # NOT `type`. It is a shell builtin, so the failure below read
+  # `type: unbound variable` and looked like a missing command rather than a
+  # missing value.
+  field_type="$(printf '%s' "$line" | cut -f2)"
+  now="$(printf '%s' "$line" | cut -f4)"
+
+  if [ "$now" = "$TEXT" ]; then
+    verdict="verified"
+  else
+    case "$now" in
+      *"$TEXT") verdict="verified, appended" ;;
+      *) verdict="verified by change only — field reads '$now', which is expected for a masked or reformatting input" ;;
+    esac
+  fi
+  [ "$n" -gt 1 ] && verdict="$verdict ($n inputs changed, reporting the first)"
+  act_report TYPE "${#TEXT} char(s) — $field_type at $rect, $verdict"
+elif [ "$before_digest" != "$after_digest" ]; then
+  act_report TYPE "${#TEXT} char(s) — no text input in the tree, and the screen changed. Typical of an OTP or PIN field: the value cannot be read back from here, so this is evidence the keystrokes landed, not proof of what they were"
+else
+  # THE LENGTH, NOT THE TEXT. The success path has always reported a character
+  # count because this drives a production app and stdout ends up in CI logs;
+  # the failure path printed the string itself, where a password would have
+  # gone. A failure is not a reason to say more than a success may.
+  die "typed ${#TEXT} char(s) and nothing on screen changed — the keyboard was up but the keystrokes went nowhere; tap the field again" 4
+fi
+# `${field_type-}`, NOT `$field_type`. This line is shared by all three
+# outcomes, and only the first of them sets it — the OTP path reports "no text
+# input in the tree" precisely because there was none to name. Under `set -u`
+# that printed `type: unbound variable` on stderr after a step that had
+# succeeded. It has been here since before the batch verb existed and only
+# became reachable when `type` stopped being refused inside one.
+#
+# The typed text is recorded, and has to be: `waypoint goto` replays it to walk
+# back to where you were, and it cannot retype a password it does not have. It
+# lives in .state/, which is gitignored and per-machine, and is the one place in
+# this tool that holds a credential in the clear.
+journal_append type "$TEXT" "${field_type-}" "" "" "" 0 0 0 0 "$DT_ACT_HASH"