device-devtools-mcp 0.1.0

package/scripts/links.tsv

@@ -0,0 +1,44 @@
+android/find.sh	../common/find.sh
+android/key.sh	../common/key.sh
+android/measure.sh	../common/measure.sh
+android/open.sh	../common/open.sh
+android/screenshot.sh	../common/screenshot.sh
+android/scroll.sh	../common/scroll.sh
+android/snapshot.sh	../common/snapshot.sh
+android/swipe.sh	../common/swipe.sh
+android/tap.sh	../common/tap.sh
+android/wait.sh	../common/wait.sh
+android/waypoint.sh	../common/waypoint.sh
+app.sh	dispatch.sh
+back.sh	dispatch.sh
+controls.sh	dispatch.sh
+devices.sh	dispatch.sh
+doctor.sh	dispatch.sh
+find.sh	dispatch.sh
+ios/find.sh	../common/find.sh
+ios/key.sh	../common/key.sh
+ios/measure.sh	../common/measure.sh
+ios/open.sh	../common/open.sh
+ios/screenshot.sh	../common/screenshot.sh
+ios/scroll.sh	../common/scroll.sh
+ios/snapshot.sh	../common/snapshot.sh
+ios/swipe.sh	../common/swipe.sh
+ios/tap.sh	../common/tap.sh
+ios/wait.sh	../common/wait.sh
+ios/waypoint.sh	../common/waypoint.sh
+key.sh	dispatch.sh
+logs.sh	dispatch.sh
+measure.sh	dispatch.sh
+open.sh	dispatch.sh
+permission.sh	dispatch.sh
+screenshot.sh	dispatch.sh
+scroll.sh	dispatch.sh
+settings.sh	dispatch.sh
+setup.sh	dispatch.sh
+snapshot.sh	dispatch.sh
+swipe.sh	dispatch.sh
+tap.sh	dispatch.sh
+tree.sh	dispatch.sh
+type.sh	dispatch.sh
+wait.sh	dispatch.sh
+waypoint.sh	dispatch.sh

package/scripts/relink.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# relink.sh — put back the symlinks a package manager threw away.
+#
+#   relink.sh            create any that are missing, report what changed
+#   relink.sh --check    say whether the tree is complete, change nothing
+#   relink.sh --write    regenerate scripts/links.tsv from the tree
+#
+# WHY THIS EXISTS AT ALL
+#
+# The verb surface is symlinks. `scripts/tap.sh` points at dispatch.sh, which
+# resolves the platform and execs the adapter; `scripts/ios/tap.sh` points at
+# `../common/tap.sh`, and the symlink's own DIRECTORY is what makes
+# `source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"` reach the iOS adapter rather
+# than the Android one. That is not a shortcut, it is the dispatch mechanism.
+#
+# `npm pack` does not carry symlinks. Measured, not assumed: a tarball of this
+# repository came out with 63 files instead of 110 and ZERO symlinks — not
+# dereferenced into copies, simply absent. Every verb was missing, and the MCP
+# server would have answered `unknown tool` to all twenty-one of them while
+# looking perfectly installed.
+#
+# So the links are written down and put back. scripts/links.tsv is GENERATED
+# from the tree, never hand-edited, and a self-test fails if the two disagree —
+# a hand-kept list is the second copy of a truth, and it is the copy that goes
+# stale.
+#
+# WHY NOT A postinstall SCRIPT. `npm install --ignore-scripts` is common, some
+# organisations enforce it, and a tool that is silently broken under a security
+# setting is worse than one that is loudly broken. This runs from the entry
+# point instead, where it cannot be turned off, and it is a no-op in the normal
+# case — a git checkout already has its links.
+#
+# exit 0  the tree is complete (or was made complete)
+# exit 1  usage error
+# exit 2  something is in the way, or --check found the tree incomplete
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MANIFEST="$HERE/links.tsv"
+
+MODE=create
+case "${1-}" in
+  --check) MODE=check ;;
+  --write) MODE=write ;;
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+  "") ;;
+  *) printf 'unknown argument: %s (usage: relink.sh [--check|--write])\n' "$1" >&2; exit 1 ;;
+esac
+
+# --write regenerates the manifest from what is actually on disk, so the
+# repository stays the source of truth and this file only ever transcribes it.
+if [ "$MODE" = write ]; then
+  find "$HERE" -type l \
+    | sed "s|^$HERE/||" \
+    | sort \
+    | while IFS= read -r l; do
+        printf '%s\t%s\n' "$l" "$(readlink "$HERE/$l")"
+      done > "$MANIFEST.new"
+  mv "$MANIFEST.new" "$MANIFEST"
+  printf 'wrote %s — %s link(s)\n' "$MANIFEST" "$(grep -c . < "$MANIFEST" | tr -d ' ')"
+  exit 0
+fi
+
+[ -f "$MANIFEST" ] || {
+  printf 'no link manifest at %s — this checkout is incomplete\n' "$MANIFEST" >&2
+  exit 2
+}
+
+missing=0
+made=0
+while IFS=$'\t' read -r link target; do
+  [ -n "$link" ] || continue
+  full="$HERE/$link"
+
+  # Already a symlink pointing where it should: nothing to do, and the common
+  # case, because a git checkout carries them.
+  if [ -L "$full" ] && [ "$(readlink "$full")" = "$target" ]; then
+    continue
+  fi
+
+  # A REGULAR FILE IN THE WAY IS NOT SOMETHING TO REPLACE. It means somebody
+  # made a verb into a real script deliberately, or an installer dereferenced
+  # the link into a copy. Either way, silently overwriting their file to restore
+  # a link is a worse answer than saying what is there.
+  if [ -e "$full" ] && [ ! -L "$full" ]; then
+    printf 'in the way: %s is a regular file, not a link to %s\n' "$link" "$target" >&2
+    missing=$((missing + 1))
+    continue
+  fi
+
+  missing=$((missing + 1))
+  [ "$MODE" = check ] && continue
+
+  mkdir -p "$(dirname "$full")" 2>/dev/null || true
+  rm -f "$full" 2>/dev/null || true
+  if ln -s "$target" "$full" 2>/dev/null; then
+    made=$((made + 1))
+  else
+    printf 'could not create %s -> %s\n' "$link" "$target" >&2
+  fi
+done < "$MANIFEST"
+
+if [ "$MODE" = check ]; then
+  if [ "$missing" -eq 0 ]; then
+    printf 'OK the verb surface is complete — %s link(s)\n' "$(grep -c . < "$MANIFEST" | tr -d ' ')"
+    exit 0
+  fi
+  printf '%s of %s link(s) are missing — run relink.sh\n' \
+    "$missing" "$(grep -c . < "$MANIFEST" | tr -d ' ')" >&2
+  exit 2
+fi
+
+if [ "$made" -eq 0 ] && [ "$missing" -eq 0 ]; then
+  printf 'OK nothing to do — the verb surface is already complete\n'
+elif [ "$made" -eq "$missing" ]; then
+  printf 'OK restored %s link(s) that the package manager dropped\n' "$made"
+else
+  printf 'restored %s of %s missing link(s)\n' "$made" "$missing" >&2
+  exit 2
+fi

package/scripts/run.sh

@@ -0,0 +1,415 @@
+#!/usr/bin/env bash
+# run.sh — several steps, one call.
+#
+#   run.sh --steps '<json array>' [--var NAME=VALUE]... [--vars '<json object>']
+#   run.sh --steps @path/to/steps.json
+#
+# WHY THIS EXISTS
+#
+# Measured on a real production app: logging in with an already-activated account
+# and opening Settings took twelve calls, of which six were snapshots taken only
+# to see what the previous action had produced. A person does the same thing in
+# about twenty seconds and has no concept of a "call" at all.
+#
+# --snapshot removed the reads. This removes the rest: gõ mật khẩu rồi bấm đăng
+# nhập is one continuous act for a person and was four separate round trips
+# here. Each round trip re-sends the whole conversation to the model, so the
+# NUMBER of calls is the cost, not the size of what any one of them returns.
+#
+#   run --steps '[
+#     {"tap":  "label:Đăng nhập"},
+#     {"type": "{{ password }}"},
+#     {"key":  "hide"},
+#     {"tap":  "label:Xác nhận"},
+#     {"wait": "screen:Home"}
+#   ]'
+#
+# A STEP IS AN OBJECT WITH EXACTLY ONE VERB IN IT. The verb's value is what you
+# would have typed after it; every other key becomes --key value, and a key
+# whose value is true becomes a bare --key. Two positional arguments go in an
+# array: {"swipe": ["label:A", "label:B"]}.
+#
+# WHAT IT REFUSES, AND WHY EACH REFUSAL IS THERE
+#
+# NO UIDS. A uid means "the seventh thing on the screen I was last shown", and
+# inside a batch there is no such screen — the numbering the caller was looking
+# at is two steps stale by the time step three runs. Selectors resolve against
+# whatever is actually there, so they are the only spelling that can mean
+# anything here.
+#
+# THE WHOLE LIST IS CHECKED BEFORE THE FIRST STEP RUNS. A typo in step seven
+# must not be discovered after step six has already tapped something in a live session.
+#
+# IT STOPS AT THE FIRST FAILURE, AND SHOWS THE SCENE. A batch that reported only
+# "step 3 failed" would trade one clear error for a black box: it hides the very
+# screens that make it debuggable. So the transcript carries every step's own
+# output, and a failure is followed by a snapshot of where it stopped.
+#
+# VARIABLES ARE NOT WRITTEN INTO THE STEPS. {{ name }} is filled from --var,
+# then from DEVICETOOLS_VAR_<NAME> in the environment, then from .vars in the
+# config. A password in a step list is a password in a shell history, in a
+# process table and in a model's context; and the substituted value is masked
+# back to {{ name }} in everything this prints.
+#
+# THERE IS NO `expect`, BECAUSE `wait` ALREADY IS ONE. An assertion is a wait
+# with a short deadline: {"wait": "screen:Auth.LoginView", "timeout": 2} fails in
+# two seconds if the app is not where the flow was written to start. A second
+# verb meaning the same thing is a second thing to keep true.
+#
+#   --steps S     the list, as JSON, or @file to read it from one
+#   --var N=V     one variable; repeatable
+#   --vars J      several, as a JSON object
+#   --dry-run     validate and print what would run, touch nothing
+#   --logs        keep the LOG block on every step, not only the failing one
+#
+# LOGS ARE OFF FOR STEPS THAT WORKED, AND THAT IS ABOUT COST.
+#
+# Every action attaches the app's log lines since it began. Alone that is a few
+# lines; in a batch of eight it was fifty-six, almost all of them
+# `UIAccessibility: Attempting to send notification` — more noise than the whole
+# batch produced in signal, and growing with the length of the batch, which is
+# exactly the thing this verb exists to make longer. So a step that succeeded
+# has its LOG block dropped and the step that FAILED keeps its own, which is the
+# one anybody is reading. --logs keeps them all.
+#
+# exit 0  every step ran
+# exit 1  usage error, or the step list is not usable
+# exit *  the exit code of the step that stopped it
+#
+# NOT A TEST RUNNER. Nothing here asserts, scores, retries or records a
+# baseline. `wait` is how a step checks something, and it checks it by waiting
+# for it. The file that used to be called run.sh in this repository was a test
+# runner and was deleted; this is not it coming back.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+# The verbs a batch may contain. Not every verb: `measure` takes a uid and
+# nothing else, so it cannot be spelled here at all, and `doctor`, `devices` and
+# `setup` are things you run when a batch has already gone wrong.
+RUN_VERBS="tap type swipe scroll back key wait expect snapshot screenshot app open logs waypoint flow"
+
+# `expect` IS `wait` WITH A DEADLINE THAT MEANS "NOW", AND NOTHING ELSE.
+#
+# It is spelling, not a second implementation: the step runs wait.sh, and if it
+# names no timeout it gets this one. The distinction it buys is real — a wait is
+# "this will arrive", an expect is "this is already true" — and a flow's first
+# step is almost always the second. On the app this was built against, logging
+# in has three different routes depending on whether the device is activated, so
+# a flow that does not check where it starts taps into a screen it was not
+# written for.
+#
+# It is not a verb outside a batch and not a tool: there is still one wait.sh.
+EXPECT_TIMEOUT=3
+
+# Keys whose value is a selector, and which therefore may not carry a uid.
+SEL_KEYS="target from to until"
+
+# Verbs whose POSITIONAL argument is a selector. `type` is not one of them: its
+# argument is the text to type, and "888888" is an OTP, not a uid.
+SEL_VERBS="tap wait swipe expect"
+
+STEPS=""
+VARS='{}'
+DRY=0
+KEEP_LOGS=0
+
+add_var() {  # add_var NAME=VALUE
+  local kv="$1" k v
+  case "$kv" in *=*) ;; *) die "--var wants NAME=VALUE, got '$kv'" 1 ;; esac
+  k="${kv%%=*}"; v="${kv#*=}"
+  case "$k" in
+    ""|*[!A-Za-z0-9_]*) die "a variable name may only hold letters, digits and underscores — got '$k'" 1 ;;
+  esac
+  VARS="$(printf '%s' "$VARS" | jq -c --arg k "$k" --arg v "$v" '.[$k] = $v')"
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --steps)
+      [ $# -ge 2 ] || die "--steps needs a JSON array, or @file" 1
+      case "$2" in
+        @*) STEPS="$(cat "$(expand_path "${2#@}")" 2>/dev/null || true)"
+            [ -n "$STEPS" ] || die "could not read the step list at ${2#@}" 1 ;;
+        *)  STEPS="$2" ;;
+      esac
+      shift 2 ;;
+    --var)
+      [ $# -ge 2 ] || die "--var needs NAME=VALUE" 1
+      add_var "$2"; shift 2 ;;
+    --vars)
+      [ $# -ge 2 ] || die "--vars needs a JSON object" 1
+      printf '%s' "$2" | jq -e 'type == "object"' >/dev/null 2>&1 \
+        || die "--vars must be a JSON object of name to value" 1
+      VARS="$(jq -cn --argjson a "$VARS" --argjson b "$2" '$a * $b')"
+      shift 2 ;;
+    --dry-run) DRY=1; shift ;;
+    --logs) KEEP_LOGS=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: run.sh --steps '<json>' [--var N=V] [--dry-run])" 1 ;;
+  esac
+done
+
+[ -n "$STEPS" ] || die "missing --steps (usage: run.sh --steps '[{\"tap\":\"label:X\"}]')" 1
+load_config
+
+# --- variables ----------------------------------------------------------------
+#
+# The environment and the config are read after the flags, so a --var on the
+# command line wins. DEVICETOOLS_VAR_* is how the MCP server hands a secret to a
+# child without it appearing in an argument list.
+for name in $(env | sed -n 's/^\(DEVICETOOLS_VAR_[A-Za-z0-9_]*\)=.*/\1/p'); do
+  k="${name#DEVICETOOLS_VAR_}"
+  [ "$(printf '%s' "$VARS" | jq -r --arg k "$k" 'has($k)')" = true ] && continue
+  VARS="$(printf '%s' "$VARS" | jq -c --arg k "$k" --arg v "${!name}" '.[$k] = $v')"
+done
+
+cfg_vars="$(jq -c '.vars // {}' "$DT_CONFIG" 2>/dev/null || printf '{}')"
+VARS="$(jq -cn --argjson a "$cfg_vars" --argjson b "$VARS" '$a * $b')"
+
+# HANDED DOWN THROUGH THE ENVIRONMENT, NOT THROUGH AN ARGUMENT LIST.
+#
+# A {"flow": "login"} step runs a whole flow inside this one, and that flow
+# needs the same password. Passing it as `--var password=…` would put it in the
+# child's command line, where it is visible in the process table to every
+# process on the machine. The environment is the channel this tool already
+# documents for exactly that, and it is the one the MCP server uses.
+while IFS=$'\t' read -r k v; do
+  [ -n "$k" ] || continue
+  export "DEVICETOOLS_VAR_$k=$v"
+done <<< "$(printf '%s' "$VARS" | jq -r 'to_entries[] | "\(.key)\t\(.value)"')"
+
+# --- the step list ------------------------------------------------------------
+
+printf '%s' "$STEPS" | jq -e 'type == "array" and length > 0' >/dev/null 2>&1 \
+  || die "--steps must be a non-empty JSON array of step objects" 1
+
+# Substitution first, so validation sees what will actually run: a {{ var }}
+# holding "7" is a uid whichever way it was spelled.
+EXPANDED="$(printf '%s' "$STEPS" | jq -c --argjson vars "$VARS" '
+  def subst:
+    if type == "string"
+    then reduce ($vars | to_entries[]) as $v (.;
+           gsub("\\{\\{ *" + $v.key + " *\\}\\}"; $v.value))
+    else . end;
+  walk(subst)
+' 2>/dev/null)" || die "the step list is not valid JSON" 1
+
+# A LEFTOVER PLACEHOLDER IS A MISSING VARIABLE, NOT A STRING TO TYPE.
+#
+# Without this, a flow whose password was never supplied types the eleven
+# characters "{{ password }}" into a login form and reports success,
+# because something did change on the screen.
+missing="$(printf '%s' "$EXPANDED" | jq -r '
+  [ .. | strings | match("\\{\\{ *([A-Za-z0-9_]+) *\\}\\}"; "g").captures[0].string ]
+  | unique | join(", ")')"
+[ -z "$missing" ] \
+  || die "no value for: $missing — pass --var $(printf '%s' "$missing" | cut -d, -f1)=… , set DEVICETOOLS_VAR_… in the environment, or add it under .vars in $DT_CONFIG" 1
+
+# --- validation, all of it, before anything runs ------------------------------
+
+N="$(printf '%s' "$EXPANDED" | jq 'length')"
+
+step_verb() {  # step_verb <step-json> — the one verb key, or a refusal
+  local s="$1" keys hit="" k
+  printf '%s' "$s" | jq -e 'type == "object"' >/dev/null 2>&1 \
+    || { printf 'not an object'; return 1; }
+  keys="$(printf '%s' "$s" | jq -r 'keys_unsorted[]')"
+  for k in $keys; do
+    case " $RUN_VERBS " in *" $k "*) hit="$hit $k" ;; esac
+  done
+
+  # `snapshot` IS BOTH A VERB AND A FLAG, AND THE VERB LIST WAS EATING IT.
+  #
+  # {"tap": "label:X", "snapshot": true} is the single most useful step anyone
+  # can write — act, and get the screen back in the same call — and it was
+  # refused as "two verbs in one step". Every other verb takes --snapshot; the
+  # only reading in which `snapshot` here is a verb is when it is the ONLY verb.
+  set -- $hit
+  if [ $# -gt 1 ]; then
+    hit=""
+    for k in "$@"; do
+      [ "$k" = snapshot ] || hit="$hit $k"
+    done
+    set -- $hit
+  fi
+
+  case $# in
+    0) printf 'no verb in it — one key must be one of: %s' "$RUN_VERBS"; return 1 ;;
+    1) printf '%s' "$1"; return 0 ;;
+    *) printf 'two verbs in one step (%s) — a step does one thing' "${hit# }"; return 1 ;;
+  esac
+}
+
+i=0
+while [ "$i" -lt "$N" ]; do
+  s="$(printf '%s' "$EXPANDED" | jq -c ".[$i]")"
+  v="$(step_verb "$s")" || die "step $((i + 1)): $v" 1
+
+  # No uids — BUT ONLY WHERE A SELECTOR IS WHAT THE VERB EXPECTS.
+  #
+  # This checked the positional argument of every verb, and `type`'s positional
+  # argument is the text to type. So a batch could not type an OTP, a PIN, an
+  # amount, a card number or a phone number — on a production app, close to every
+  # field there is. Substitution runs before validation, so {{ otp }} did not
+  # get round it either: it became 888888 and was then refused as a uid.
+  #
+  # It also meant `flow` could not hold a login, which is the one example the
+  # tool's own description gives for why flows exist.
+  #
+  # So the positional is only checked for the verbs whose positional IS a
+  # selector. The named keys below are checked everywhere, because those names
+  # only ever carry selectors.
+  case " $SEL_VERBS " in
+    *" $v "*) pos_check=true ;;
+    *)        pos_check=false ;;
+  esac
+  bad="$(printf '%s' "$s" | jq -r --arg v "$v" --arg sel "$SEL_KEYS" --argjson pos "$pos_check" '
+    ($sel | split(" ")) as $keys
+    | [ (if $pos then (.[$v] | if type == "array" then .[] else . end) else empty end),
+        (.[$keys[]]? // empty) ]
+    | map(select(type == "string"))
+    | map(select(test("^[0-9]+$") or startswith("uid:")))
+    | join(", ")')"
+  [ -z "$bad" ] \
+    || die "step $((i + 1)) ($v): '$bad' is a uid, and a uid names a position on a screen that is already two steps old by the time this step runs. Use id:, label:, kind:, text: or xy:" 1
+
+  i=$((i + 1))
+done
+
+# --- masking ------------------------------------------------------------------
+#
+# Everything printed goes through this. The substituted value is put back as
+# {{ name }}, so a transcript that ends up in a log, a ticket or a model's
+# context carries the shape of the flow and not the credential.
+mask() {
+  local s="$1" k v
+  while IFS=$'\t' read -r k v; do
+    [ -n "$v" ] || continue
+    # The replacement is built first. Backslash-escaping the braces inline puts
+    # the backslashes themselves into the output — the transcript then reads
+    # `tap label:\{\{ password \}\}`, which is masked and also wrong.
+    rep="{{ $k }}"
+    s="${s//"$v"/$rep}"
+  done <<< "$(printf '%s' "$VARS" | jq -r 'to_entries[] | "\(.key)\t\(.value)"')"
+  printf '%s' "$s"
+}
+
+# step_line <n> <verb> <step-json> — how the step is announced.
+#
+# `type` is announced as a length and never as text, the same rule the verb
+# itself follows: it drives a login form and this output is read by a
+# model and written to a log.
+step_line() {
+  local n="$1" v="$2" s="$3" args
+  if [ "$v" = type ]; then
+    # The text becomes a count and never a string; the FLAGS still show, or a
+    # step written {"type": …, "snapshot": true} would silently look like one
+    # that was not.
+    args="$(printf '%s' "$s" | jq -r '
+      [ (.type | tostring | length | "(\(.) chars)") ]
+      + [ to_entries[] | select(.key != "type")
+          | if (.value | type) == "boolean"
+            then (if .value then "--" + .key else empty end)
+            else "--" + .key + " " + (.value | tostring) end ]
+      | join(" ")')"
+  else
+    args="$(printf '%s' "$s" | jq -r --arg v "$v" '
+      [ (.[$v] | if type == "array" then .[] else . end | tostring | select(. != "true")) ]
+      + [ to_entries[] | select(.key != $v)
+          | if (.value | type) == "boolean"
+            then (if .value then "--" + .key else empty end)
+            else "--" + .key + " " + (.value | tostring) end ]
+      | join(" ")')"
+  fi
+  args="$(mask "$args")"
+  # A verb with no arguments — {"snapshot": true} — must not print a trailing
+  # space, because the transcript is compared byte for byte by the self-test.
+  printf 'STEP %s/%s %s%s' "$n" "$N" "$v" "${args:+ $args}"
+}
+
+# --- running ------------------------------------------------------------------
+
+printf 'RUN    %s step%s\n' "$N" "$( [ "$N" = 1 ] || printf s )"
+
+i=0
+ran=0
+while [ "$i" -lt "$N" ]; do
+  s="$(printf '%s' "$EXPANDED" | jq -c ".[$i]")"
+  v="$(step_verb "$s")" || die "step $((i + 1)): $v" 1
+  n=$((i + 1))
+
+  printf '%s\n' "$(step_line "$n" "$v" "$s")"
+
+
+  # NUL-separated, read straight into an array, so an argument is an argument
+  # whatever is in it. Same rule as the MCP server's argv_from, for the same
+  # reason: the app on the other end of this is somebody's production app, and there is no
+  # quoting to get wrong if nothing is ever re-parsed.
+  args=()
+  while IFS= read -r -d '' one; do args+=("$one"); done < <(
+    printf '%s' "$s" | jq -j --arg v "$v" '
+      ( .[$v]
+        | if type == "array" then .[] elif type == "boolean" then empty else . end
+        | tostring ) + "\u0000",
+      ( to_entries[] as $e
+        | select($e.key != $v)
+        | if ($e.value | type) == "boolean"
+          then (if $e.value then "--" + $e.key + "\u0000" else empty end)
+          else "--" + $e.key + "\u0000" + ($e.value | tostring) + "\u0000"
+          end )')
+
+  # A DRY RUN STILL DESCENDS INTO A NESTED BATCH.
+  #
+  # Skipping a {"flow": "login"} step would leave the composed list unchecked,
+  # which is most of what there is to check: whether the flow exists, whether
+  # its own steps are valid, and whether it includes itself. The child is run
+  # with --dry-run, so it touches the device exactly as little as this does.
+  if [ "$DRY" -eq 1 ]; then
+    case "$v" in
+      flow|run) args+=(--dry-run) ;;
+      *) i="$n"; ran="$n"; continue ;;
+    esac
+  fi
+
+  script="$v"
+  if [ "$v" = expect ]; then
+    script=wait
+    printf '%s' "$s" | jq -e 'has("timeout")' >/dev/null 2>&1 \
+      || args+=(--timeout "$EXPECT_TIMEOUT")
+  fi
+
+  rc=0
+  out="$("$DT_HOME/scripts/$script.sh" ${args[@]+"${args[@]}"} 2>&1)" || rc=$?
+
+  # The LOG block of a step that worked. See the note in the header.
+  if [ "$rc" -eq 0 ] && [ "$KEEP_LOGS" -eq 0 ]; then
+    out="$(printf '%s\n' "$out" | strip_log_block)"
+  fi
+  [ -z "$out" ] || printf '%s\n' "$(mask "$out")" | sed 's/^/  /'
+
+  if [ "$rc" -ne 0 ]; then
+    printf 'RUN    FAILED at step %s of %s — %s step(s) ran, EXIT %s\n' "$n" "$N" "$ran" "$rc"
+    # THE SCENE, NOT JUST THE VERDICT. A batch that reports only which step
+    # failed has swapped a legible error for a black box: the caller can no
+    # longer see the intermediate screens, so it cannot tell a wrong selector
+    # from a screen that never arrived.
+    #
+    # Except when the step that failed was itself a batch — it has already
+    # printed the screen, and a nested flow three deep would otherwise fetch and
+    # print the same tree three times on its way back up.
+    case "$v" in
+      flow|run) ;;
+      *) printf '\n'; "$DT_HOME/scripts/snapshot.sh" 2>&1 | sed 's/^/  /' || true ;;
+    esac
+    exit "$rc"
+  fi
+
+  ran="$n"
+  i="$n"
+done
+
+if [ "$DRY" -eq 1 ]; then
+  printf 'RUN    dry — %s step(s) validated, nothing was sent to the device\n' "$N"
+else
+  printf 'RUN    OK %s of %s step(s)\n' "$ran" "$N"
+fi