android-device-control 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- android_device_control/__init__.py +1 -0
- android_device_control/android_mcp.py +107 -0
- android_device_control/device_info.py +182 -0
- android_device_control/messages.py +164 -0
- android_device_control/phone.py +568 -0
- android_device_control/receipts.py +224 -0
- android_device_control-0.1.0.dist-info/METADATA +151 -0
- android_device_control-0.1.0.dist-info/RECORD +12 -0
- android_device_control-0.1.0.dist-info/WHEEL +5 -0
- android_device_control-0.1.0.dist-info/entry_points.txt +6 -0
- android_device_control-0.1.0.dist-info/licenses/LICENSE +21 -0
- android_device_control-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,568 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Small fail-closed ADB controller for an explicitly selected Android device.
|
|
3
|
+
|
|
4
|
+
Authentication-screen detection uses English accessibility labels and password
|
|
5
|
+
field metadata. It is a conservative guard, not a complete OTP detector: an
|
|
6
|
+
unlabeled or non-English recovery screen can go undetected, so callers must
|
|
7
|
+
still inspect the live UI and handle sensitive screens manually.
|
|
8
|
+
"""
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import argparse
|
|
12
|
+
import hashlib
|
|
13
|
+
import ipaddress
|
|
14
|
+
import json
|
|
15
|
+
import os
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
import shlex
|
|
18
|
+
import re
|
|
19
|
+
import subprocess
|
|
20
|
+
import sys
|
|
21
|
+
import time
|
|
22
|
+
from urllib.parse import urlsplit
|
|
23
|
+
import xml.etree.ElementTree as ET
|
|
24
|
+
|
|
25
|
+
KEYS = {"back": 4, "home": 3, "enter": 66, "tab": 61,
|
|
26
|
+
"delete": 67, "escape": 111, "up": 19, "down": 20,
|
|
27
|
+
"left": 21, "right": 22}
|
|
28
|
+
EDIT_CLASS = "android.widget.EditText"
|
|
29
|
+
MAX_SETTLE_SECONDS = 10.0
|
|
30
|
+
SETTLE_INTERVAL_SECONDS = 0.35
|
|
31
|
+
MIN_SWIPE_MS = 100
|
|
32
|
+
MAX_SWIPE_MS = 1500
|
|
33
|
+
SENSITIVE_SCREEN = re.compile(
|
|
34
|
+
r"\b(?:password|passcode|one[ -]?time(?: password)?|"
|
|
35
|
+
r"verification(?: code)?|security code|authentication|authenticator|otp|2fa|"
|
|
36
|
+
r"two[ -]?factor|account recovery|recover account|forgot password|reset password|"
|
|
37
|
+
r"enter code|confirm your identity|identity check)\b", re.IGNORECASE)
|
|
38
|
+
SENSITIVE_AUTH_HEADING = re.compile(r"^\s*(?:sign[ -]?in|log[ -]?in)\b", re.IGNORECASE)
|
|
39
|
+
SAFE_FIELD_LABEL = re.compile(
|
|
40
|
+
r"\b(?:name|first name|last name|full name|display name|page name|username|"
|
|
41
|
+
r"user name|handle|email|email address|bio|description|website|search|title)\b",
|
|
42
|
+
re.IGNORECASE)
|
|
43
|
+
PACKAGE_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+")
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class PhoneError(RuntimeError):
|
|
47
|
+
pass
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def run(args: list[str], *, timeout: int = 15) -> bytes:
|
|
51
|
+
try:
|
|
52
|
+
result = subprocess.run(args, capture_output=True, timeout=timeout)
|
|
53
|
+
except (OSError, subprocess.TimeoutExpired) as exc:
|
|
54
|
+
raise PhoneError(f"command failed: {type(exc).__name__}") from exc
|
|
55
|
+
if result.returncode:
|
|
56
|
+
# Never relay stdout/stderr from the device: applications can include secrets.
|
|
57
|
+
raise PhoneError(f"ADB command failed (exit {result.returncode})")
|
|
58
|
+
return result.stdout
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def adb(device: str, *args: str, timeout: int = 15) -> bytes:
|
|
62
|
+
if not device or not re.fullmatch(r"[A-Za-z0-9._:-]+", device):
|
|
63
|
+
raise PhoneError("provide an explicit valid device serial")
|
|
64
|
+
return run(["adb", "-s", device, *args], timeout=timeout)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def devices() -> str:
|
|
68
|
+
data = run(["adb", "devices", "-l"]).decode("utf-8", "replace")
|
|
69
|
+
return "\n".join(data.splitlines()[:])
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def foreground_component(output: str) -> str:
|
|
73
|
+
"""Extract only the focused package/component from a window-manager dump."""
|
|
74
|
+
match = re.search(
|
|
75
|
+
r"^\s*mCurrentFocus=Window\{[^}\r\n]*?\bu\d+\s+"
|
|
76
|
+
r"([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)/"
|
|
77
|
+
r"([A-Za-z.][A-Za-z0-9_$.]*)\s*\}",
|
|
78
|
+
output,
|
|
79
|
+
re.MULTILINE,
|
|
80
|
+
)
|
|
81
|
+
if match:
|
|
82
|
+
return f"{match.group(1)}/{match.group(2)}"
|
|
83
|
+
raise PhoneError("foreground package/component unavailable from Android window manager")
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def foreground(device: str) -> str:
|
|
87
|
+
output = adb(device, "shell", "dumpsys", "window").decode("utf-8", "replace")
|
|
88
|
+
return foreground_component(output)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def validate_target_package(package: str) -> None:
|
|
92
|
+
if not PACKAGE_NAME.fullmatch(package):
|
|
93
|
+
raise PhoneError("package must be an explicit Android package name")
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def validate_public_url(url: str) -> None:
|
|
97
|
+
# Keep the URL out of diagnostics and support only ordinary, non-secret URLs.
|
|
98
|
+
try:
|
|
99
|
+
parsed = urlsplit(url)
|
|
100
|
+
hostname = parsed.hostname
|
|
101
|
+
_ = parsed.port # Reject malformed ports.
|
|
102
|
+
except ValueError as exc:
|
|
103
|
+
raise PhoneError("URL is malformed; provide a non-secret HTTPS or loopback HTTP URL") from exc
|
|
104
|
+
if (parsed.scheme not in ("https", "http") or not hostname
|
|
105
|
+
or parsed.username is not None or parsed.password is not None
|
|
106
|
+
or any(ord(char) < 0x20 or ord(char) == 0x7f for char in url)):
|
|
107
|
+
raise PhoneError("URL must be a non-secret HTTPS URL or loopback HTTP URL without credentials")
|
|
108
|
+
if parsed.scheme == "http":
|
|
109
|
+
normalized_host = hostname.rstrip(".").lower()
|
|
110
|
+
try:
|
|
111
|
+
is_loopback = ipaddress.ip_address(normalized_host).is_loopback
|
|
112
|
+
except ValueError:
|
|
113
|
+
is_loopback = normalized_host == "localhost"
|
|
114
|
+
if not is_loopback:
|
|
115
|
+
raise PhoneError("HTTP is allowed only for a loopback URL")
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def open_target(device: str, package: str, url: str | None = None) -> str:
|
|
119
|
+
validate_target_package(package)
|
|
120
|
+
if url is not None:
|
|
121
|
+
validate_public_url(url)
|
|
122
|
+
|
|
123
|
+
# Refuse to issue navigation from a visible login, recovery, OTP, or
|
|
124
|
+
# authenticator screen. This checks accessibility metadata only.
|
|
125
|
+
stable_tree(device)
|
|
126
|
+
if url is None:
|
|
127
|
+
launcher = ("-a", "android.intent.action.MAIN", "-c", "android.intent.category.LAUNCHER")
|
|
128
|
+
result = adb(device, "shell", "cmd", "package", "resolve-activity", "--brief", *launcher, "-p", package)
|
|
129
|
+
component = re.search(rf"^{re.escape(package)}/[A-Za-z.][A-Za-z0-9_$.]*\r?$",
|
|
130
|
+
result.decode("utf-8", "replace"), re.MULTILINE)
|
|
131
|
+
if not component:
|
|
132
|
+
raise PhoneError("no launcher activity found for the requested package")
|
|
133
|
+
adb(device, "shell", "am", "start", "-W", *launcher,
|
|
134
|
+
"-n", shlex.quote(component[0].strip()), timeout=30)
|
|
135
|
+
else:
|
|
136
|
+
adb(device, "shell", "am", "start", "-W", "-a", "android.intent.action.VIEW",
|
|
137
|
+
"-d", shlex.quote(url), "-p", package, timeout=30)
|
|
138
|
+
|
|
139
|
+
focused = foreground(device)
|
|
140
|
+
focused_package = focused.split("/", 1)[0]
|
|
141
|
+
if focused_package != package:
|
|
142
|
+
raise PhoneError("navigation did not reach the requested foreground package")
|
|
143
|
+
return f"foreground {focused}"
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def fetch_tree(device: str) -> tuple[ET.Element, bytes]:
|
|
147
|
+
# exec-out captures XML from /dev/tty without leaving screen data on device.
|
|
148
|
+
raw = adb(device, "exec-out", "uiautomator", "dump", "/dev/tty", timeout=20)
|
|
149
|
+
start = raw.find(b"<?xml")
|
|
150
|
+
end_marker = raw.find(b"</hierarchy>", start)
|
|
151
|
+
if start < 0 or end_marker < 0:
|
|
152
|
+
raise PhoneError("fresh UI hierarchy unavailable; no action taken")
|
|
153
|
+
xml = raw[start:end_marker + len(b"</hierarchy>")]
|
|
154
|
+
try:
|
|
155
|
+
return ET.fromstring(xml), xml
|
|
156
|
+
except ET.ParseError as exc:
|
|
157
|
+
raise PhoneError("UI hierarchy was malformed; no action taken") from exc
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def has_password(root: ET.Element) -> bool:
|
|
161
|
+
return any(node.get("password", "false").lower() == "true" for node in root.iter())
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def sensitive_screen(root: ET.Element) -> bool:
|
|
165
|
+
if has_password(root):
|
|
166
|
+
return True
|
|
167
|
+
# Sync is an entry in Firefox settings, separate from the account form.
|
|
168
|
+
sync_titles = {child for node in root.iter()
|
|
169
|
+
if any(child.get("resource-id") == "android:id/summary"
|
|
170
|
+
and child.get("text") == "Synchronise tabs, bookmarks, passwords and more."
|
|
171
|
+
for child in node)
|
|
172
|
+
for child in node if child.get("package") == "org.mozilla.firefox"
|
|
173
|
+
and child.get("resource-id") == "android:id/title"}
|
|
174
|
+
# Match only accessibility labels and hints; never put entered field values
|
|
175
|
+
# in diagnostics. A conservative false positive is safer than exposing an
|
|
176
|
+
# authentication, recovery, or one-time-code screen.
|
|
177
|
+
labels = [value for node in root.iter()
|
|
178
|
+
for key in ("text", "content-desc", "hint")
|
|
179
|
+
if (value := node.get(key, ""))
|
|
180
|
+
if not (key == "text" and node in sync_titles and value == "Sign in")
|
|
181
|
+
# Firefox's menu advertises Sync before any login UI is open.
|
|
182
|
+
if not (key == "content-desc" and node.get("package") == "org.mozilla.firefox"
|
|
183
|
+
and value == "Sign in Synchronise passwords, bookmarks and more")]
|
|
184
|
+
return any(SENSITIVE_SCREEN.search(label) or SENSITIVE_AUTH_HEADING.match(label)
|
|
185
|
+
for label in labels)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def guard_screen(root: ET.Element) -> None:
|
|
189
|
+
if sensitive_screen(root):
|
|
190
|
+
raise PhoneError("sensitive authentication or recovery screen; snapshot/action blocked")
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def build_refs(root: ET.Element) -> tuple[list[str], dict[str, dict[str, object]]]:
|
|
194
|
+
lines: list[str] = []
|
|
195
|
+
refs: dict[str, dict[str, object]] = {}
|
|
196
|
+
|
|
197
|
+
def visit(node: ET.Element, depth: int = 0) -> None:
|
|
198
|
+
attrs = node.attrib
|
|
199
|
+
bounds = attrs.get("bounds", "")
|
|
200
|
+
if bounds and bounds != "[0,0][0,0]":
|
|
201
|
+
text = attrs.get("text", "")
|
|
202
|
+
desc = attrs.get("content-desc", "")
|
|
203
|
+
cls = attrs.get("class", "").rsplit(".", 1)[-1]
|
|
204
|
+
click = attrs.get("clickable") == "true"
|
|
205
|
+
edit = attrs.get("class") == EDIT_CLASS
|
|
206
|
+
# Edit fields may expose OTPs or other private input as node text.
|
|
207
|
+
label = (desc or attrs.get("hint", "")) if edit else (text or desc)
|
|
208
|
+
if click or edit or label:
|
|
209
|
+
ref = str(len(refs) + 1)
|
|
210
|
+
nums = [int(n) for n in re.findall(r"-?\d+", bounds)]
|
|
211
|
+
if len(nums) != 4:
|
|
212
|
+
raise PhoneError("invalid accessibility bounds")
|
|
213
|
+
x, y = (nums[0] + nums[2]) // 2, (nums[1] + nums[3]) // 2
|
|
214
|
+
safe_label = "[hidden sensitive field]" if attrs.get("password") == "true" else label
|
|
215
|
+
flags = []
|
|
216
|
+
if click:
|
|
217
|
+
flags.append("click")
|
|
218
|
+
if edit:
|
|
219
|
+
flags.append("edit")
|
|
220
|
+
if attrs.get("focused") == "true":
|
|
221
|
+
flags.append("focused")
|
|
222
|
+
if attrs.get("enabled") == "false":
|
|
223
|
+
flags.append("disabled")
|
|
224
|
+
label_part = f" {json.dumps(safe_label, ensure_ascii=False)}" if safe_label else ""
|
|
225
|
+
lines.append(f"[{ref}] {cls}{label_part} {{{','.join(flags)}}} ({x},{y})")
|
|
226
|
+
refs[ref] = {"x": x, "y": y, "click": click, "edit": edit,
|
|
227
|
+
"enabled": attrs.get("enabled") != "false",
|
|
228
|
+
"focused": attrs.get("focused") == "true"}
|
|
229
|
+
for child in node:
|
|
230
|
+
visit(child, depth + 1)
|
|
231
|
+
|
|
232
|
+
visit(root)
|
|
233
|
+
return lines, refs
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def state_path(device: str) -> Path:
|
|
237
|
+
base = Path(os.environ.get("ANDROID_CONTROL_STATE", Path.home() / ".cache" / "android-control"))
|
|
238
|
+
return base / (hashlib.sha256(device.encode()).hexdigest()[:20] + ".json")
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def save_state(path: Path, digest: str, refs: dict[str, dict[str, object]]) -> None:
|
|
242
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
243
|
+
payload = json.dumps({"sha256": digest, "refs": refs}, separators=(",", ":"))
|
|
244
|
+
# Direct write avoids creating and then deleting temporary files. A partial
|
|
245
|
+
# write fails schema validation on the next action, which stops safely.
|
|
246
|
+
with path.open("w", encoding="utf-8") as stream:
|
|
247
|
+
os.chmod(path, 0o600)
|
|
248
|
+
stream.write(payload)
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def load_state(path: Path) -> dict[str, object]:
|
|
252
|
+
try:
|
|
253
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
254
|
+
if (not isinstance(data, dict)
|
|
255
|
+
or set(data) != {"sha256", "refs"}
|
|
256
|
+
or not isinstance(data["sha256"], str)
|
|
257
|
+
or not re.fullmatch(r"[0-9a-f]{64}", data["sha256"])
|
|
258
|
+
or not isinstance(data["refs"], dict)):
|
|
259
|
+
raise ValueError("schema")
|
|
260
|
+
for ref, target in data["refs"].items():
|
|
261
|
+
if (not isinstance(ref, str) or not ref.isdigit()
|
|
262
|
+
or not isinstance(target, dict)
|
|
263
|
+
or set(target) != {"x", "y", "click", "edit", "enabled", "focused"}
|
|
264
|
+
or type(target["x"]) is not int
|
|
265
|
+
or type(target["y"]) is not int
|
|
266
|
+
or any(type(target[key]) is not bool
|
|
267
|
+
for key in ("click", "edit", "enabled", "focused"))):
|
|
268
|
+
raise ValueError("target schema")
|
|
269
|
+
return data
|
|
270
|
+
except (OSError, TypeError, ValueError, json.JSONDecodeError) as exc:
|
|
271
|
+
raise PhoneError("no usable snapshot state; run snapshot first") from exc
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def stable_tree(device: str, settle: float = 0.0) -> tuple[ET.Element, bytes]:
|
|
275
|
+
if not 0 <= settle <= MAX_SETTLE_SECONDS:
|
|
276
|
+
raise PhoneError(f"settle must be between 0 and {MAX_SETTLE_SECONDS:g} seconds")
|
|
277
|
+
root, xml = fetch_tree(device)
|
|
278
|
+
guard_screen(root)
|
|
279
|
+
if settle == 0:
|
|
280
|
+
return root, xml
|
|
281
|
+
deadline = time.monotonic() + settle
|
|
282
|
+
prior = hashlib.sha256(xml).digest()
|
|
283
|
+
while time.monotonic() < deadline:
|
|
284
|
+
time.sleep(min(SETTLE_INTERVAL_SECONDS, max(0, deadline - time.monotonic())))
|
|
285
|
+
root, xml = fetch_tree(device)
|
|
286
|
+
guard_screen(root)
|
|
287
|
+
current = hashlib.sha256(xml).digest()
|
|
288
|
+
if current == prior:
|
|
289
|
+
return root, xml
|
|
290
|
+
prior = current
|
|
291
|
+
raise PhoneError("UI did not settle before timeout; no snapshot state saved")
|
|
292
|
+
|
|
293
|
+
|
|
294
|
+
def snapshot(device: str, settle: float = 0.0) -> str:
|
|
295
|
+
root, xml = stable_tree(device, settle)
|
|
296
|
+
lines, refs = build_refs(root)
|
|
297
|
+
digest = hashlib.sha256(xml).hexdigest()
|
|
298
|
+
save_state(state_path(device), digest, refs)
|
|
299
|
+
return "\n".join([f"# device={device} refs={len(refs)} sha256={digest[:12]}", *lines])
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def screen_size(device: str) -> tuple[int, int]:
|
|
303
|
+
output = adb(device, "shell", "wm", "size").decode("ascii", "replace")
|
|
304
|
+
sizes = re.findall(r"(\d+)x(\d+)", output)
|
|
305
|
+
if not sizes:
|
|
306
|
+
raise PhoneError("could not read screen dimensions")
|
|
307
|
+
width, height = map(int, sizes[-1])
|
|
308
|
+
if width <= 0 or height <= 0:
|
|
309
|
+
raise PhoneError("invalid screen dimensions")
|
|
310
|
+
return width, height
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def checked_screen(device: str) -> tuple[ET.Element, bytes, int, int]:
|
|
314
|
+
root, xml = fetch_tree(device)
|
|
315
|
+
guard_screen(root)
|
|
316
|
+
width, height = screen_size(device)
|
|
317
|
+
return root, xml, width, height
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
def checked_gesture(device: str, action: list[str]) -> None:
|
|
321
|
+
root, xml, _, _ = checked_screen(device)
|
|
322
|
+
# Recheck immediately before input; refuse if the visible screen changed.
|
|
323
|
+
again, again_xml = fetch_tree(device)
|
|
324
|
+
guard_screen(again)
|
|
325
|
+
if hashlib.sha256(xml).digest() != hashlib.sha256(again_xml).digest():
|
|
326
|
+
raise PhoneError("screen changed before gesture; no action taken")
|
|
327
|
+
adb(device, *action)
|
|
328
|
+
|
|
329
|
+
|
|
330
|
+
def scroll(device: str, direction: str) -> str:
|
|
331
|
+
vectors = {
|
|
332
|
+
"down": (0.50, 0.72, 0.50, 0.30),
|
|
333
|
+
"up": (0.50, 0.30, 0.50, 0.72),
|
|
334
|
+
"left": (0.80, 0.50, 0.20, 0.50),
|
|
335
|
+
"right": (0.20, 0.50, 0.80, 0.50),
|
|
336
|
+
}
|
|
337
|
+
if direction not in vectors:
|
|
338
|
+
raise PhoneError("direction must be up, down, left, or right")
|
|
339
|
+
_, _, width, height = checked_screen(device)
|
|
340
|
+
points = vectors[direction]
|
|
341
|
+
x1, y1 = round(points[0] * width), round(points[1] * height)
|
|
342
|
+
x2, y2 = round(points[2] * width), round(points[3] * height)
|
|
343
|
+
checked_gesture(device, ["shell", "input", "swipe", str(x1), str(y1), str(x2), str(y2), "300"])
|
|
344
|
+
return f"scrolled {direction}"
|
|
345
|
+
|
|
346
|
+
|
|
347
|
+
def swipe(device: str, coords: list[int], duration_ms: int = 300) -> str:
|
|
348
|
+
if len(coords) != 4 or any(type(value) is not int for value in coords):
|
|
349
|
+
raise PhoneError("swipe requires four integer screen coordinates")
|
|
350
|
+
if not MIN_SWIPE_MS <= duration_ms <= MAX_SWIPE_MS:
|
|
351
|
+
raise PhoneError(f"swipe duration must be {MIN_SWIPE_MS}–{MAX_SWIPE_MS} ms")
|
|
352
|
+
_, _, width, height = checked_screen(device)
|
|
353
|
+
x1, y1, x2, y2 = coords
|
|
354
|
+
if not all(0 <= x <= width and 0 <= y <= height for x, y in ((x1, y1), (x2, y2))):
|
|
355
|
+
raise PhoneError("swipe coordinates fall outside the current screen")
|
|
356
|
+
checked_gesture(device, ["shell", "input", "swipe", *(str(value) for value in coords), str(duration_ms)])
|
|
357
|
+
return "swiped"
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
def tap_label(device: str, label: str) -> str:
|
|
361
|
+
if not label or label.strip() != label:
|
|
362
|
+
raise PhoneError("provide a non-empty exact accessibility label")
|
|
363
|
+
root, xml = fetch_tree(device)
|
|
364
|
+
guard_screen(root)
|
|
365
|
+
parents = {child: parent for parent in root.iter() for child in parent}
|
|
366
|
+
targets: dict[int, tuple[int, int]] = {}
|
|
367
|
+
width, height = screen_size(device)
|
|
368
|
+
for node in root.iter():
|
|
369
|
+
if label not in (node.get("text", ""), node.get("content-desc", "")):
|
|
370
|
+
continue
|
|
371
|
+
target = node
|
|
372
|
+
while target is not None and target.get("clickable") != "true":
|
|
373
|
+
target = parents.get(target)
|
|
374
|
+
if target is None or target.get("enabled") == "false":
|
|
375
|
+
continue
|
|
376
|
+
bounds = target.get("bounds", "")
|
|
377
|
+
nums = [int(value) for value in re.findall(r"-?\d+", bounds)]
|
|
378
|
+
if len(nums) != 4:
|
|
379
|
+
continue
|
|
380
|
+
left, top, right, bottom = nums
|
|
381
|
+
if (left < 0 or top < 0 or right > width or bottom > height
|
|
382
|
+
or left >= right or top >= bottom):
|
|
383
|
+
continue
|
|
384
|
+
x, y = (left + right) // 2, (top + bottom) // 2
|
|
385
|
+
targets[id(target)] = (x, y)
|
|
386
|
+
if len(targets) != 1:
|
|
387
|
+
raise PhoneError(f"expected one enabled clickable match for label; found {len(targets)}")
|
|
388
|
+
(x, y), = targets.values()
|
|
389
|
+
again, again_xml = fetch_tree(device)
|
|
390
|
+
guard_screen(again)
|
|
391
|
+
if hashlib.sha256(xml).digest() != hashlib.sha256(again_xml).digest():
|
|
392
|
+
raise PhoneError("screen changed before tap; no action taken")
|
|
393
|
+
adb(device, "shell", "input", "tap", str(x), str(y))
|
|
394
|
+
return f"tapped exact label {json.dumps(label, ensure_ascii=False)}"
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
def screenshot(device: str, output: str) -> str:
|
|
398
|
+
if not output:
|
|
399
|
+
raise PhoneError("choose a new screenshot path explicitly")
|
|
400
|
+
root, before_xml = fetch_tree(device)
|
|
401
|
+
guard_screen(root)
|
|
402
|
+
path = Path(output).expanduser()
|
|
403
|
+
if path.exists():
|
|
404
|
+
raise PhoneError("screenshot path already exists; refusing to overwrite")
|
|
405
|
+
if not path.parent.is_dir():
|
|
406
|
+
raise PhoneError("screenshot parent directory must already exist")
|
|
407
|
+
image = adb(device, "exec-out", "screencap", "-p", timeout=20)
|
|
408
|
+
if not image.startswith(b"\x89PNG\r\n\x1a\n"):
|
|
409
|
+
raise PhoneError("device did not return a PNG screenshot")
|
|
410
|
+
# Accessibility read and framebuffer capture are separate operations. A
|
|
411
|
+
# matching post-capture tree catches navigation/race changes, but cannot
|
|
412
|
+
# prove that the image contains no sensitive pixels unsupported by labels.
|
|
413
|
+
after, after_xml = fetch_tree(device)
|
|
414
|
+
guard_screen(after)
|
|
415
|
+
if hashlib.sha256(after_xml).digest() != hashlib.sha256(before_xml).digest():
|
|
416
|
+
raise PhoneError("screen changed during screenshot; image was not saved")
|
|
417
|
+
try:
|
|
418
|
+
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
|
|
419
|
+
except FileExistsError as exc:
|
|
420
|
+
raise PhoneError("screenshot path already exists; refusing to overwrite") from exc
|
|
421
|
+
with os.fdopen(fd, "wb") as stream:
|
|
422
|
+
stream.write(image)
|
|
423
|
+
return str(path.resolve())
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
def checked_target(device: str, ref: str) -> dict[str, object]:
|
|
427
|
+
path = state_path(device)
|
|
428
|
+
old = load_state(path)
|
|
429
|
+
root, xml = fetch_tree(device)
|
|
430
|
+
guard_screen(root)
|
|
431
|
+
if hashlib.sha256(xml).hexdigest() != old["sha256"]:
|
|
432
|
+
raise PhoneError("screen changed since snapshot; no action taken; snapshot again")
|
|
433
|
+
target = old["refs"].get(ref)
|
|
434
|
+
if not target:
|
|
435
|
+
raise PhoneError(f"unknown ref {ref}; no action taken")
|
|
436
|
+
if not target["enabled"]:
|
|
437
|
+
raise PhoneError("target is disabled; no action taken")
|
|
438
|
+
_, current_refs = build_refs(root)
|
|
439
|
+
current = current_refs.get(ref)
|
|
440
|
+
keys = ("x", "y", "click", "edit", "enabled", "focused")
|
|
441
|
+
if not current or any(current.get(key) != target.get(key) for key in keys):
|
|
442
|
+
raise PhoneError("target no longer matches the fresh UI tree; no action taken")
|
|
443
|
+
return target
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def tap(device: str, ref: str) -> str:
|
|
447
|
+
target = checked_target(device, ref)
|
|
448
|
+
if not target["click"]:
|
|
449
|
+
raise PhoneError("target is not an accessible clickable control")
|
|
450
|
+
adb(device, "shell", "input", "tap", str(target["x"]), str(target["y"]))
|
|
451
|
+
return f"tapped ref {ref}"
|
|
452
|
+
|
|
453
|
+
|
|
454
|
+
def key(device: str, key_name: str) -> str:
|
|
455
|
+
code = KEYS.get(key_name.lower())
|
|
456
|
+
if code is None:
|
|
457
|
+
raise PhoneError(f"key must be one of: {', '.join(KEYS)}")
|
|
458
|
+
root, _ = fetch_tree(device)
|
|
459
|
+
guard_screen(root)
|
|
460
|
+
adb(device, "shell", "input", "keyevent", str(code))
|
|
461
|
+
return f"key {key_name.lower()}"
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
def focused_safe_field(root: ET.Element, placeholder: str | None = None) -> ET.Element:
|
|
465
|
+
guard_screen(root)
|
|
466
|
+
focused = [n for n in root.iter() if n.get("class") == EDIT_CLASS and n.get("focused") == "true"]
|
|
467
|
+
if len(focused) != 1:
|
|
468
|
+
raise PhoneError("exactly one focused editable field is required")
|
|
469
|
+
node = focused[0]
|
|
470
|
+
if node.get("enabled") == "false":
|
|
471
|
+
raise PhoneError("focused field is disabled")
|
|
472
|
+
value = node.get("text", "")
|
|
473
|
+
is_exact_placeholder = (placeholder is not None and placeholder != ""
|
|
474
|
+
and value == placeholder and node.get("hint", "") == placeholder)
|
|
475
|
+
if value and not is_exact_placeholder:
|
|
476
|
+
raise PhoneError("focused field is not empty; refusing to append or replace")
|
|
477
|
+
field_label = " ".join((node.get("hint", ""), node.get("content-desc", "")))
|
|
478
|
+
if not SAFE_FIELD_LABEL.search(field_label):
|
|
479
|
+
raise PhoneError("focused field lacks a recognized non-sensitive label; refusing text entry")
|
|
480
|
+
return node
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
def type_text(device: str, text: str, placeholder: str | None = None) -> str:
|
|
484
|
+
if not text or not text.isascii() or any(c in "\r\n\t" for c in text):
|
|
485
|
+
raise PhoneError("type accepts non-empty, single-line ASCII text only")
|
|
486
|
+
root, original_xml = fetch_tree(device)
|
|
487
|
+
focused_safe_field(root, placeholder)
|
|
488
|
+
# The focused field or screen may have changed while this request was
|
|
489
|
+
# prepared. Require an identical fresh hierarchy immediately before input.
|
|
490
|
+
before_send, before_send_xml = fetch_tree(device)
|
|
491
|
+
focused_safe_field(before_send, placeholder)
|
|
492
|
+
if hashlib.sha256(original_xml).digest() != hashlib.sha256(before_send_xml).digest():
|
|
493
|
+
raise PhoneError("screen or focused field changed before text entry; no text sent")
|
|
494
|
+
escaped = shlex.quote(text.replace(" ", "%s"))
|
|
495
|
+
adb(device, "shell", "input", "text", escaped)
|
|
496
|
+
after, _ = fetch_tree(device)
|
|
497
|
+
guard_screen(after)
|
|
498
|
+
matches = [n for n in after.iter() if n.get("class") == EDIT_CLASS and n.get("focused") == "true"]
|
|
499
|
+
if (len(matches) != 1 or matches[0].get("enabled") == "false"
|
|
500
|
+
or not SAFE_FIELD_LABEL.search(" ".join((matches[0].get("hint", ""),
|
|
501
|
+
matches[0].get("content-desc", ""))))
|
|
502
|
+
or matches[0].get("text", "") != text):
|
|
503
|
+
raise PhoneError("typed value did not verify in the focused field")
|
|
504
|
+
return f"typed and verified {len(text)} characters"
|
|
505
|
+
|
|
506
|
+
|
|
507
|
+
def main(argv: list[str] | None = None) -> int:
|
|
508
|
+
parser = argparse.ArgumentParser(description=__doc__)
|
|
509
|
+
subs = parser.add_subparsers(dest="command", required=True)
|
|
510
|
+
subs.add_parser("devices")
|
|
511
|
+
for name in ("snapshot", "tap", "tap-label", "key", "type", "scroll", "swipe", "screenshot",
|
|
512
|
+
"foreground", "open"):
|
|
513
|
+
sub = subs.add_parser(name)
|
|
514
|
+
sub.add_argument("--device", required=True, help="explicit adb serial")
|
|
515
|
+
if name == "open":
|
|
516
|
+
sub.add_argument("package", help="explicit Android package name")
|
|
517
|
+
sub.add_argument("--url", help="non-secret HTTPS URL, or HTTP on loopback only")
|
|
518
|
+
elif name == "snapshot":
|
|
519
|
+
sub.add_argument("--settle", type=float, default=0.0,
|
|
520
|
+
help=f"wait for a stable tree, at most {MAX_SETTLE_SECONDS:g} seconds")
|
|
521
|
+
elif name == "tap":
|
|
522
|
+
sub.add_argument("ref")
|
|
523
|
+
elif name == "tap-label":
|
|
524
|
+
sub.add_argument("label")
|
|
525
|
+
elif name == "key":
|
|
526
|
+
sub.add_argument("key")
|
|
527
|
+
elif name == "type":
|
|
528
|
+
sub.add_argument("--placeholder", help="exact accessibility text and hint treated as an empty field")
|
|
529
|
+
sub.add_argument("text")
|
|
530
|
+
elif name == "scroll":
|
|
531
|
+
sub.add_argument("direction", choices=("up", "down", "left", "right"))
|
|
532
|
+
elif name == "swipe":
|
|
533
|
+
sub.add_argument("coords", nargs=4, type=int, metavar=("X1", "Y1", "X2", "Y2"))
|
|
534
|
+
sub.add_argument("--ms", type=int, default=300)
|
|
535
|
+
elif name == "screenshot":
|
|
536
|
+
sub.add_argument("output", help="new PNG path; existing files are never overwritten")
|
|
537
|
+
args = parser.parse_args(argv)
|
|
538
|
+
try:
|
|
539
|
+
if args.command == "devices":
|
|
540
|
+
print(devices())
|
|
541
|
+
elif args.command == "snapshot":
|
|
542
|
+
print(snapshot(args.device, args.settle))
|
|
543
|
+
elif args.command == "tap":
|
|
544
|
+
print(tap(args.device, args.ref))
|
|
545
|
+
elif args.command == "tap-label":
|
|
546
|
+
print(tap_label(args.device, args.label))
|
|
547
|
+
elif args.command == "key":
|
|
548
|
+
print(key(args.device, args.key))
|
|
549
|
+
elif args.command == "type":
|
|
550
|
+
print(type_text(args.device, args.text, args.placeholder))
|
|
551
|
+
elif args.command == "scroll":
|
|
552
|
+
print(scroll(args.device, args.direction))
|
|
553
|
+
elif args.command == "swipe":
|
|
554
|
+
print(swipe(args.device, args.coords, args.ms))
|
|
555
|
+
elif args.command == "screenshot":
|
|
556
|
+
print(screenshot(args.device, args.output))
|
|
557
|
+
elif args.command == "foreground":
|
|
558
|
+
print(foreground(args.device))
|
|
559
|
+
elif args.command == "open":
|
|
560
|
+
print(open_target(args.device, args.package, args.url))
|
|
561
|
+
return 0
|
|
562
|
+
except PhoneError as exc:
|
|
563
|
+
print(str(exc), file=sys.stderr)
|
|
564
|
+
return 2
|
|
565
|
+
|
|
566
|
+
|
|
567
|
+
if __name__ == "__main__":
|
|
568
|
+
raise SystemExit(main())
|