u2-cli 0.1.0__py3-none-any.whl

u2/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+import typer
+import uiautomator2 as u2
+
+cli = typer.Typer(no_args_is_help=True)
+
+
+@dataclass
+class State:
+    serial: str = ""
+
+
+state = State()
+
+
+def get_device() -> u2.Device:
+    return u2.connect(state.serial) if state.serial else u2.connect()
+
+
+def out(success: bool, output: str, code: str = "") -> None:  # noqa: FBT001
+    typer.echo(json.dumps({"success": success, "output": output, "code": code}, ensure_ascii=False))
+
+
+@cli.callback()
+def main_callback(
+    serial: Optional[str] = typer.Option(None, "-s", "--serial", help="Android device serial"),
+) -> None:
+    if serial:
+        state.serial = serial
+
+
+from u2.device import device_app  # noqa: E402
+from u2.app import app_app  # noqa: E402
+from u2.screen import screen_app  # noqa: E402
+from u2.interact import interact_app  # noqa: E402
+from u2.element import element_app  # noqa: E402
+from u2.watch import watch_app  # noqa: E402
+
+cli.add_typer(device_app, name="device")
+cli.add_typer(app_app, name="app")
+cli.add_typer(screen_app, name="screen")
+cli.add_typer(interact_app, name="interact")
+cli.add_typer(element_app, name="element")
+cli.add_typer(watch_app, name="watch")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

u2/app.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+
+from u2 import get_device, out
+
+app_app = typer.Typer(no_args_is_help=True)
+
+
+@app_app.command()
+def start(
+    package: str = typer.Argument(..., help="Package name"),
+    activity: Optional[str] = typer.Option(None, "--activity", "-a", help="Activity to launch"),
+    wait: bool = typer.Option(False, "--wait", help="Wait for app to start"),  # noqa: FBT001, FBT002
+    stop: bool = typer.Option(False, "--stop", help="Stop before starting"),  # noqa: FBT001, FBT002
+) -> None:
+    """Start an app by package name."""
+    try:
+        d = get_device()
+        d.app_start(package, activity=activity, wait=wait, stop=stop)
+        code = f"d.app_start({package!r}"
+        if activity:
+            code += f", activity={activity!r}"
+        if wait:
+            code += ", wait=True"
+        if stop:
+            code += ", stop=True"
+        code += ")"
+        out(True, f"Started: {package}", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command()
+def stop(package: str = typer.Argument(..., help="Package name")) -> None:
+    """Stop an app by package name."""
+    try:
+        d = get_device()
+        d.app_stop(package)
+        out(True, f"Stopped: {package}", f"d.app_stop({package!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command()
+def install(path: str = typer.Argument(..., help="APK path or URL")) -> None:
+    """Install an APK from path or URL."""
+    try:
+        d = get_device()
+        d.app_install(path)
+        out(True, f"Installed: {path}", f"d.app_install({path!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command()
+def uninstall(package: str = typer.Argument(..., help="Package name")) -> None:
+    """Uninstall an app by package name."""
+    try:
+        d = get_device()
+        success = d.app_uninstall(package)
+        msg = f"Uninstalled: {package}" if success else f"Failed to uninstall: {package}"
+        out(success, msg, f"d.app_uninstall({package!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command()
+def clear(package: str = typer.Argument(..., help="Package name")) -> None:
+    """Clear app data."""
+    try:
+        d = get_device()
+        d.app_clear(package)
+        out(True, f"Cleared: {package}", f"d.app_clear({package!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command(name="list")
+def list_apps(
+    filter: Optional[str] = typer.Option(  # noqa: A002
+        None,
+        "-f",
+        "--filter",
+        help="Filter: -3 (third-party), -s (system), -d (disabled), -e (enabled)",
+    ),
+) -> None:
+    """List installed apps."""
+    try:
+        d = get_device()
+        packages = d.app_list(filter) if filter else d.app_list()
+        code = f"d.app_list({filter!r})" if filter else "d.app_list()"
+        out(True, json.dumps(packages), code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command()
+def current() -> None:
+    """Show the current foreground app."""
+    try:
+        d = get_device()
+        info = d.app_current()
+        out(True, json.dumps(info), "d.app_current()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@app_app.command(name="wait-activity")
+def wait_activity(
+    activity: str = typer.Argument(..., help="Activity name to wait for"),
+    timeout: float = typer.Option(10.0, "--timeout", "-t", help="Timeout in seconds"),
+) -> None:
+    """Wait for a specific activity to appear."""
+    try:
+        d = get_device()
+        found = d.wait_activity(activity, timeout=timeout)
+        code = f"d.wait_activity({activity!r}, timeout={timeout})"
+        out(found, f"Activity {'found' if found else 'not found'}: {activity}", code)
+    except Exception as e:
+        out(False, str(e))

u2/device.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Optional
+
+import typer
+
+from u2 import get_device, out
+
+device_app = typer.Typer(no_args_is_help=True)
+
+
+@device_app.command()
+def info() -> None:
+    """Show device info."""
+    try:
+        d = get_device()
+        result = d.device_info
+        out(True, json.dumps(result), "d.device_info")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def battery() -> None:
+    """Show battery info."""
+    try:
+        d = get_device()
+        b = d.adb_device.battery()
+        result = dataclasses.asdict(b)
+        out(True, json.dumps(result), "d.adb_device.battery()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command(name="wlan-ip")
+def wlan_ip() -> None:
+    """Show WLAN IP address."""
+    try:
+        d = get_device()
+        ip = d.wlan_ip
+        out(True, ip or "", "d.wlan_ip")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def shell(cmd: str = typer.Argument(..., help="Shell command to run")) -> None:
+    """Run an adb shell command."""
+    try:
+        d = get_device()
+        resp = d.shell(cmd)
+        out(True, resp.output, f"d.shell({cmd!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def keyevent(key: str = typer.Argument(..., help="Key name or keycode")) -> None:
+    """Send a key event (e.g. home, back, power)."""
+    try:
+        d = get_device()
+        d.press(key)
+        out(True, f"Sent key: {key}", f"d.press({key!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def push(
+    src: str = typer.Argument(..., help="Local source path"),
+    dst: str = typer.Argument(..., help="Remote destination path"),
+) -> None:
+    """Push a file to the device."""
+    try:
+        d = get_device()
+        d.push(src, dst)
+        out(True, f"Pushed {src} -> {dst}", f"d.push({src!r}, {dst!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def pull(
+    src: str = typer.Argument(..., help="Remote source path"),
+    dst: str = typer.Argument(..., help="Local destination path"),
+) -> None:
+    """Pull a file from the device."""
+    try:
+        d = get_device()
+        d.pull(src, dst)
+        out(True, f"Pulled {src} -> {dst}", f"d.pull({src!r}, {dst!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command(name="screen-on")
+def screen_on() -> None:
+    """Turn the screen on."""
+    try:
+        d = get_device()
+        d.screen_on()
+        out(True, "Screen on", "d.screen_on()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command(name="screen-off")
+def screen_off() -> None:
+    """Turn the screen off."""
+    try:
+        d = get_device()
+        d.screen_off()
+        out(True, "Screen off", "d.screen_off()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@device_app.command()
+def orientation(
+    value: Optional[str] = typer.Argument(
+        None, help="Set orientation: natural, left, right, upsidedown (omit to get)"
+    ),
+) -> None:
+    """Get or set screen orientation."""
+    try:
+        d = get_device()
+        if value is None:
+            current = d.orientation
+            out(True, current, "d.orientation")
+        else:
+            d.orientation = value  # type: ignore[assignment]
+            out(True, f"Orientation set to: {value}", f"d.orientation = {value!r}")
+    except Exception as e:
+        out(False, str(e))

u2/element.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import typer
+
+from u2 import get_device, out
+
+element_app = typer.Typer(no_args_is_help=True)
+
+# Shared selector options reused across commands
+_TEXT = typer.Option(None, "--text", "-t", help="Element text")
+_RESOURCE_ID = typer.Option(None, "--resource-id", "-r", help="Resource ID")
+_CLASS_NAME = typer.Option(None, "--class-name", "-c", help="Class name")
+_XPATH = typer.Option(None, "--xpath", "-x", help="XPath expression")
+_DESCRIPTION = typer.Option(None, "--description", "-d", help="Content description")
+
+
+def _build_selector(
+    text: Optional[str],
+    resource_id: Optional[str],
+    class_name: Optional[str],
+    description: Optional[str],
+) -> dict:
+    sel: dict = {}
+    if text is not None:
+        sel["text"] = text
+    if resource_id is not None:
+        sel["resourceId"] = resource_id
+    if class_name is not None:
+        sel["className"] = class_name
+    if description is not None:
+        sel["description"] = description
+    return sel
+
+
+@element_app.command()
+def find(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    timeout: float = typer.Option(0.0, "--timeout", "-T", help="Wait up to N seconds for elements"),
+) -> None:
+    """Find elements matching the given selector."""
+    try:
+        d = get_device()
+        if xpath:
+            el = d.xpath(xpath)
+            if timeout > 0:
+                el.wait(timeout=timeout)
+            elements = el.all()
+            results = [e.elem.attrib for e in elements]
+            code = f"d.xpath({xpath!r}).all()"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            el = d(**sel)
+            count = el.count
+            results = [el[i].info for i in range(count)]
+            code = f"d({', '.join(f'{k}={v!r}' for k, v in sel.items())}).info"
+        out(True, json.dumps(results), code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command()
+def wait(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    timeout: float = typer.Option(10.0, "--timeout", "-T", help="Timeout in seconds"),
+) -> None:
+    """Wait for an element to appear."""
+    try:
+        d = get_device()
+        if xpath:
+            found = d.xpath(xpath).wait(timeout=timeout)
+            code = f"d.xpath({xpath!r}).wait(timeout={timeout})"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            found = d(**sel).wait(exists=True, timeout=timeout)
+            sel_str = ", ".join(f"{k}={v!r}" for k, v in sel.items())
+            code = f"d({sel_str}).wait(exists=True, timeout={timeout})"
+        out(bool(found), "Element found" if found else "Element not found", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command()
+def exists(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+) -> None:
+    """Check if an element exists."""
+    try:
+        d = get_device()
+        if xpath:
+            found = d.xpath(xpath).exists
+            code = f"d.xpath({xpath!r}).exists"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            found = bool(d(**sel).exists)
+            code = f"d({', '.join(f'{k}={v!r}' for k, v in sel.items())}).exists"
+        out(True, str(found).lower(), code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command(name="get-text")
+def get_text(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    timeout: float = typer.Option(10.0, "--timeout", "-T", help="Timeout in seconds"),
+) -> None:
+    """Get text content of a matching element."""
+    try:
+        d = get_device()
+        if xpath:
+            el = d.xpath(xpath)
+            el.wait(timeout=timeout)
+            value = el.get_text()
+            code = f"d.xpath({xpath!r}).get_text()"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            value = d(**sel).get_text(timeout=timeout)
+            code = f"d({', '.join(f'{k}={v!r}' for k, v in sel.items())}).get_text()"
+        out(True, value or "", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command(name="set-text")
+def set_text(
+    value: str = typer.Argument(..., help="Text to set"),
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    timeout: float = typer.Option(10.0, "--timeout", "-T", help="Timeout in seconds"),
+) -> None:
+    """Set text on a matching element."""
+    try:
+        d = get_device()
+        if xpath:
+            el = d.xpath(xpath)
+            el.wait(timeout=timeout)
+            el.set_text(value)
+            code = f"d.xpath({xpath!r}).set_text({value!r})"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            d(**sel).set_text(value, timeout=timeout)
+            code = f"d({', '.join(f'{k}={v!r}' for k, v in sel.items())}).set_text({value!r})"
+        out(True, f"Set text to: {value!r}", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command()
+def tap(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    timeout: float = typer.Option(10.0, "--timeout", "-T", help="Timeout in seconds"),
+) -> None:
+    """Tap a matching element."""
+    try:
+        d = get_device()
+        if xpath:
+            el = d.xpath(xpath)
+            el.wait(timeout=timeout)
+            el.click()
+            code = f"d.xpath({xpath!r}).click()"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            d(**sel).click(timeout=timeout)
+            code = f"d({', '.join(f'{k}={v!r}' for k, v in sel.items())}).click()"
+        out(True, "Tapped element", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@element_app.command(name="long-tap")
+def long_tap(
+    text: Optional[str] = _TEXT,
+    resource_id: Optional[str] = _RESOURCE_ID,
+    class_name: Optional[str] = _CLASS_NAME,
+    xpath: Optional[str] = _XPATH,
+    description: Optional[str] = _DESCRIPTION,
+    duration: float = typer.Option(0.5, "--duration", "-D", help="Hold duration in seconds"),
+    timeout: float = typer.Option(10.0, "--timeout", "-T", help="Timeout in seconds"),
+) -> None:
+    """Long-tap a matching element."""
+    try:
+        d = get_device()
+        if xpath:
+            el = d.xpath(xpath)
+            el.wait(timeout=timeout)
+            el.long_click()
+            code = f"d.xpath({xpath!r}).long_click()"
+        else:
+            sel = _build_selector(text, resource_id, class_name, description)
+            d(**sel).long_click(duration=duration, timeout=timeout)
+            sel_str = ", ".join(f"{k}={v!r}" for k, v in sel.items())
+            code = f"d({sel_str}).long_click(duration={duration})"
+        out(True, "Long-tapped element", code)
+    except Exception as e:
+        out(False, str(e))

u2/interact.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import typer
+
+from u2 import get_device, out
+
+interact_app = typer.Typer(no_args_is_help=True)
+
+
+@interact_app.command()
+def tap(
+    x: int = typer.Argument(..., help="X coordinate"),
+    y: int = typer.Argument(..., help="Y coordinate"),
+) -> None:
+    """Tap at screen coordinates."""
+    try:
+        d = get_device()
+        d.click(x, y)
+        out(True, f"Tapped at ({x}, {y})", f"d.click({x}, {y})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@interact_app.command(name="long-tap")
+def long_tap(
+    x: int = typer.Argument(..., help="X coordinate"),
+    y: int = typer.Argument(..., help="Y coordinate"),
+    duration: float = typer.Option(0.5, "--duration", "-d", help="Press duration in seconds"),
+) -> None:
+    """Long tap at screen coordinates."""
+    try:
+        d = get_device()
+        d.long_click(x, y, duration=duration)
+        out(True, f"Long-tapped at ({x}, {y})", f"d.long_click({x}, {y}, duration={duration})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@interact_app.command()
+def swipe(
+    fx: int = typer.Argument(..., help="From X coordinate"),
+    fy: int = typer.Argument(..., help="From Y coordinate"),
+    tx: int = typer.Argument(..., help="To X coordinate"),
+    ty: int = typer.Argument(..., help="To Y coordinate"),
+    duration: float = typer.Option(0.5, "--duration", "-d", help="Swipe duration in seconds"),
+) -> None:
+    """Swipe from one point to another."""
+    try:
+        d = get_device()
+        d.swipe(fx, fy, tx, ty, duration=duration)
+        code = f"d.swipe({fx}, {fy}, {tx}, {ty}, duration={duration})"
+        out(True, f"Swiped ({fx},{fy}) -> ({tx},{ty})", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@interact_app.command()
+def drag(
+    sx: int = typer.Argument(..., help="Start X coordinate"),
+    sy: int = typer.Argument(..., help="Start Y coordinate"),
+    ex: int = typer.Argument(..., help="End X coordinate"),
+    ey: int = typer.Argument(..., help="End Y coordinate"),
+    duration: float = typer.Option(0.5, "--duration", "-d", help="Drag duration in seconds"),
+) -> None:
+    """Drag from one point to another."""
+    try:
+        d = get_device()
+        d.drag(sx, sy, ex, ey, duration=duration)
+        code = f"d.drag({sx}, {sy}, {ex}, {ey}, duration={duration})"
+        out(True, f"Dragged ({sx},{sy}) -> ({ex},{ey})", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@interact_app.command(name="type")
+def type_text(
+    text: str = typer.Argument(..., help="Text to type into the focused element"),
+) -> None:
+    """Type text into the focused element (supports Unicode/Chinese via clipboard paste)."""
+    try:
+        d = get_device()
+        d.set_clipboard(text)
+        d.send_action("paste")
+        out(True, f"Typed: {text!r}", f"d.set_clipboard('{text}'); d.send_action('paste')")
+    except Exception as e:
+        out(False, str(e))
+    except Exception as e:
+        out(False, str(e))
+
+
+@interact_app.command()
+def clear() -> None:
+    """Clear text in the focused element."""
+    try:
+        d = get_device()
+        d.clear_text()
+        out(True, "Cleared focused element", "d.clear_text()")
+    except Exception as e:
+        out(False, str(e))

u2/screen.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+import io
+import sys
+import xml.etree.ElementTree as ET
+from typing import Optional
+
+import typer
+
+from u2 import get_device, out
+
+# Attributes kept in simplified output (all others dropped)
+_KEEP_ATTRS = {"text", "resource-id", "content-desc", "bounds", "class"}
+# Boolean attributes included only when "true"
+_BOOL_ATTRS = {
+    "clickable", "scrollable", "checkable", "checked", "selected", "long-clickable", "focused"
+}
+# Class name suffixes used as short labels
+_CLASS_SHORT = {
+    "TextView": "text",
+    "EditText": "input",
+    "Button": "button",
+    "ImageView": "image",
+    "ImageButton": "image-button",
+    "CheckBox": "checkbox",
+    "RadioButton": "radio",
+    "Switch": "switch",
+    "ToggleButton": "toggle",
+    "SeekBar": "seekbar",
+    "ProgressBar": "progress",
+    "ListView": "list",
+    "RecyclerView": "list",
+    "ScrollView": "scroll",
+    "HorizontalScrollView": "scroll-h",
+    "ViewPager": "pager",
+    "WebView": "web",
+    "FrameLayout": "frame",
+    "LinearLayout": "linear",
+    "RelativeLayout": "relative",
+    "ConstraintLayout": "constraint",
+    "CoordinatorLayout": "coordinator",
+    "Toolbar": "toolbar",
+    "TabLayout": "tabs",
+    "BottomNavigationView": "bottom-nav",
+    "NavigationView": "nav",
+}
+
+
+def _short_class(class_name: str) -> str:
+    suffix = class_name.rsplit(".", 1)[-1]
+    return _CLASS_SHORT.get(suffix, suffix)
+
+
+def _simplify_node(node: ET.Element) -> dict | None:
+    """Convert an XML node to a simplified dict, or None if the node should be pruned."""
+    attrib = node.attrib
+
+    # Drop invisible nodes and their subtrees
+    if attrib.get("visible-to-user") == "false":
+        return None
+
+    children = []
+    for child in node:
+        simplified = _simplify_node(child)
+        if simplified is not None:
+            children.append(simplified)
+
+    # Build the simplified representation
+    entry: dict = {}
+
+    class_name = attrib.get("class", "")
+    short = _short_class(class_name)
+    if short != class_name:
+        entry["type"] = short
+    else:
+        entry["type"] = class_name
+
+    text = attrib.get("text", "").strip()
+    if text:
+        entry["text"] = text
+
+    desc = attrib.get("content-desc", "").strip()
+    if desc and desc != text:
+        entry["desc"] = desc
+
+    rid = attrib.get("resource-id", "")
+    if rid:
+        # Strip package prefix for brevity: "com.example:id/foo" -> "foo"
+        entry["id"] = rid.split("/", 1)[-1] if "/" in rid else rid
+
+    bounds = attrib.get("bounds", "")
+    if bounds:
+        entry["bounds"] = bounds
+
+    for attr in _BOOL_ATTRS:
+        if attrib.get(attr) == "true":
+            entry[attr] = True
+
+    # Prune container nodes that carry no info and have exactly one child
+    no_info = not any(k in entry for k in ("text", "desc", "id"))
+    no_flags = not any(entry.get(a) for a in _BOOL_ATTRS)
+    if no_info and no_flags and len(children) == 1:
+        return children[0]
+
+    if children:
+        entry["children"] = children
+
+    return entry
+
+
+def _simplify_xml(xml: str) -> str:
+    import json
+
+    root = ET.fromstring(xml)
+    # The root is <hierarchy>, its child is the top-level node
+    nodes = []
+    for child in root:
+        result = _simplify_node(child)
+        if result is not None:
+            nodes.append(result)
+
+    top = nodes[0] if len(nodes) == 1 else nodes
+    return json.dumps(top, ensure_ascii=False)
+
+screen_app = typer.Typer(no_args_is_help=True)
+
+
+@screen_app.command()
+def screenshot(
+    path: Optional[str] = typer.Argument(
+        None, help="Output file path (omit to write PNG to stdout)"
+    ),
+) -> None:
+    """Take a screenshot. Saves to file or writes PNG bytes to stdout."""
+    try:
+        d = get_device()
+        if path:
+            d.screenshot(path)
+            out(True, f"Screenshot saved to: {path}", f"d.screenshot({path!r})")
+        else:
+            img = d.screenshot()
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            sys.stdout.buffer.write(buf.getvalue())
+    except Exception as e:
+        out(False, str(e))
+
+
+@screen_app.command()
+def dump(
+    compressed: bool = typer.Option(False, "--compressed", help="Use compressed hierarchy"),  # noqa: FBT001, FBT002
+    pretty: bool = typer.Option(False, "--pretty", help="Pretty-print XML"),  # noqa: FBT001, FBT002
+    simplify: bool = typer.Option(  # noqa: FBT001, FBT002
+        False, "--simplify", "-s", help="Strip noise, return compact JSON"
+    ),
+) -> None:
+    """Dump UI hierarchy as XML, or simplified JSON with --simplify."""
+    try:
+        d = get_device()
+        xml = d.dump_hierarchy(compressed=compressed)
+        if simplify:
+            result = _simplify_xml(xml)
+            out(True, result, "d.dump_hierarchy() [simplified]")
+        else:
+            out(True, xml, f"d.dump_hierarchy(compressed={compressed}, pretty={pretty})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@screen_app.command()
+def size() -> None:
+    """Show screen size."""
+    try:
+        d = get_device()
+        w, h = d.window_size()
+        out(True, f"{w}x{h}", "d.window_size()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@screen_app.command()
+def brightness(
+    value: Optional[int] = typer.Argument(None, help="Brightness level 0-255 (omit to get)"),
+) -> None:
+    """Get or set screen brightness (0-255)."""
+    try:
+        d = get_device()
+        if value is None:
+            resp = d.shell("settings get system screen_brightness")
+            out(True, resp.output.strip(), "d.shell('settings get system screen_brightness')")
+        else:
+            cmd = f"settings put system screen_brightness {value}"
+            d.shell(cmd)
+            out(True, f"Brightness set to: {value}", f"d.shell({cmd!r})")
+    except Exception as e:
+        out(False, str(e))

u2/watch.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import time
+
+import typer
+
+from u2 import get_device, out
+
+watch_app = typer.Typer(no_args_is_help=True)
+
+
+@watch_app.command()
+def add(
+    name: str = typer.Argument(..., help="Watcher name"),
+    xpath: str = typer.Option(..., "--xpath", "-x", help="XPath expression to watch for"),
+    action: str = typer.Option("click", "--action", "-a", help="Action: click, back, home"),
+    timeout: float = typer.Option(30.0, "--timeout", "-t", help="Watch duration in seconds"),
+) -> None:
+    """Register a watcher and run it for a duration."""
+    try:
+        d = get_device()
+        w = d.watcher(name).when(xpath)
+        code_action: str
+        if action == "click":
+            w.click()
+            code_action = ".click()"
+        elif action in ("back", "home", "recent"):
+            w.press(action)
+            code_action = f".press({action!r})"
+        else:
+            out(False, f"Unknown action: {action!r}. Use: click, back, home, recent")
+            return
+
+        code = f"d.watcher({name!r}).when({xpath!r}){code_action}"
+        d.watcher.start()
+        time.sleep(timeout)
+        d.watcher.stop()
+        out(True, f"Watcher '{name}' ran for {timeout}s", code)
+    except Exception as e:
+        out(False, str(e))
+
+
+@watch_app.command()
+def remove(
+    name: str = typer.Argument(..., help="Watcher name (use '__all__' to remove all)"),
+) -> None:
+    """Remove a named watcher (note: only meaningful within same process)."""
+    try:
+        d = get_device()
+        if name == "__all__":
+            d.watcher.remove()
+            out(True, "Removed all watchers", "d.watcher.remove()")
+        else:
+            d.watcher.remove(name)
+            out(True, f"Removed watcher: {name}", f"d.watcher.remove({name!r})")
+    except Exception as e:
+        out(False, str(e))
+
+
+@watch_app.command(name="list")
+def list_watchers() -> None:
+    """List registered watchers (note: only meaningful within same process)."""
+    try:
+        d = get_device()
+        running = d.watcher.running()
+        out(True, f"Watcher running: {running}", "d.watcher.running()")
+    except Exception as e:
+        out(False, str(e))
+
+
+@watch_app.command()
+def run(
+    xpath: str = typer.Option(..., "--xpath", "-x", help="XPath expression to watch for"),
+    action: str = typer.Option("click", "--action", "-a", help="Action: click, back, home"),
+) -> None:
+    """Run watcher once and report if it triggered."""
+    try:
+        d = get_device()
+        w = d.watcher("__run__").when(xpath)
+        code_action: str
+        if action == "click":
+            w.click()
+            code_action = ".click()"
+        elif action in ("back", "home", "recent"):
+            w.press(action)
+            code_action = f".press({action!r})"
+        else:
+            out(False, f"Unknown action: {action!r}. Use: click, back, home, recent")
+            return
+
+        triggered = d.watcher.run()
+        d.watcher.remove("__run__")
+        code = f"d.watcher('__run__').when({xpath!r}){code_action}; d.watcher.run()"
+        out(triggered, "Watcher triggered" if triggered else "Watcher did not trigger", code)
+    except Exception as e:
+        out(False, str(e))

u2_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: u2-cli
+Version: 0.1.0
+Summary: CLI tool for executing uiautomator2 commands to control Android devices from the AI Agent
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: typer>=0.24.1
+Requires-Dist: uiautomator2>=3.5.0
+Description-Content-Type: text/markdown
+
+# u2-cli
+CLI tool for executing uiautomator2 commands to control Android devices from the AI Agent

u2_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+u2/__init__.py,sha256=j0NAPdAW0NtZx2BKtqISllrTXYZOfq2wW1bw15t5KRA,1327
+u2/app.py,sha256=9BWBp3yJMN5lMeVyFSHNIH6UAyAa-vKQVN3pLpidGeQ,3827
+u2/device.py,sha256=6Y28bPUNuWOagei_Px1POT2xC-PKh95iiw7DzzqXtJM,3513
+u2/element.py,sha256=sA-XU5Dglg5B1QgG9ojqGKrrM-HEBcUvepqCxb0D8L0,7793
+u2/interact.py,sha256=7Ct_ATZgpCq_1wKDM2Ev3zUDFRlSJCFCGI2lJuVKPZQ,3238
+u2/screen.py,sha256=96ZEhfwOhf4YMLM9zMByHY9H33b_d727FGbzGxBGvak,5834
+u2/watch.py,sha256=JLp3lMZgK6aSv36xFulfVgZ4kKlWjBGdbHt2G6oEYG0,3202
+u2_cli-0.1.0.dist-info/METADATA,sha256=HjMC_gID75sZsqZ06sSIhoQPdiPKkpISUfpOcHVDoFU,399
+u2_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+u2_cli-0.1.0.dist-info/entry_points.txt,sha256=e9l8ereIB7Lp2gG2bc0a3R2kqsxkcfKq_-M447haFqU,31
+u2_cli-0.1.0.dist-info/licenses/LICENSE,sha256=hYRaJ2ed2IMo9RmO96UxUSTt9iwL49leBY5kVtDymRo,1063
+u2_cli-0.1.0.dist-info/RECORD,,

u2_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

u2_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+u2 = u2:main

u2_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lanbao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.