@11agents/cli 0.1.23 → 0.1.25

package/mobile-runtime/python/src/device_control/appium_manager.py

@@ -0,0 +1,403 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import signal
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adb import resolve_adb_bin
+from .appium_client import AppiumClient
+
+
+DEFAULT_APPIUM_SERVER = "http://127.0.0.1:4723"
+
+
+class AppiumEnsureError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class AppiumEnsureResult:
+    status: str
+    server_url: str
+    appium_bin: str
+    android_sdk_root: str
+    pid: int | None
+    log_path: str
+    smoke_udids: list[str]
+    message: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "server_url": self.server_url,
+            "appium_bin": self.appium_bin,
+            "android_sdk_root": self.android_sdk_root,
+            "pid": self.pid,
+            "log_path": self.log_path,
+            "smoke_udids": self.smoke_udids,
+            "message": self.message,
+        }
+
+
+def ensure_appium_server(
+    server_url: str = DEFAULT_APPIUM_SERVER,
+    *,
+    udids: list[str] | None = None,
+    start: bool = True,
+    restart: bool = False,
+    smoke: bool = True,
+    project_root: str | Path | None = None,
+    startup_timeout_s: float = 45,
+) -> AppiumEnsureResult:
+    root = Path(project_root).expanduser() if project_root else find_project_root()
+    normalized_url = normalize_server_url(server_url)
+    appium_bin = resolve_appium_bin(root)
+    sdk_root = resolve_android_sdk_root()
+    log_path = _log_path(root, normalized_url)
+    pid: int | None = _read_managed_pid(root, normalized_url)
+
+    if restart:
+        stop_managed_appium(normalized_url, project_root=root, allow_unmanaged_appium=True)
+        pid = None
+
+    status = _get_status(normalized_url)
+    started = False
+    if status is None:
+        if not start:
+            raise AppiumEnsureError(f"Appium is not reachable at {normalized_url}")
+        _require_local_server(normalized_url)
+        pid = _start_appium(normalized_url, appium_bin, sdk_root, log_path, root)
+        started = True
+        status = _wait_for_status(normalized_url, startup_timeout_s)
+        if status is None:
+            raise AppiumEnsureError(f"Appium did not become ready within {int(startup_timeout_s)}s; log={log_path}")
+
+    smoke_udids = [item for item in (udids or []) if item]
+    if smoke and smoke_udids:
+        try:
+            for udid in smoke_udids:
+                smoke_appium_session(normalized_url, udid)
+        except Exception as exc:
+            if not started and (_is_managed_process(root, normalized_url) or _local_appium_pid(normalized_url)):
+                stop_managed_appium(normalized_url, project_root=root, allow_unmanaged_appium=True)
+                pid = _start_appium(normalized_url, appium_bin, sdk_root, log_path, root)
+                status = _wait_for_status(normalized_url, startup_timeout_s)
+                if status is None:
+                    raise AppiumEnsureError(f"Appium restart did not become ready; log={log_path}") from exc
+                for udid in smoke_udids:
+                    smoke_appium_session(normalized_url, udid)
+            else:
+                raise AppiumEnsureError(
+                    f"Appium smoke session failed for {smoke_udids[0]} at {normalized_url}: {exc}. "
+                    f"Use `11agents mobile ensure-appium --restart --device Dxx` if a stale local server is occupying the port. "
+                    f"log={log_path}"
+                ) from exc
+
+    return AppiumEnsureResult(
+        status="started" if started else "running",
+        server_url=normalized_url,
+        appium_bin=str(appium_bin),
+        android_sdk_root=str(sdk_root),
+        pid=pid or _read_managed_pid(root, normalized_url) or _local_appium_pid(normalized_url),
+        log_path=str(log_path),
+        smoke_udids=smoke_udids if smoke else [],
+        message="ok",
+    )
+
+
+def stop_managed_appium(
+    server_url: str = DEFAULT_APPIUM_SERVER,
+    *,
+    project_root: str | Path | None = None,
+    allow_unmanaged_appium: bool = False,
+) -> bool:
+    root = Path(project_root).expanduser() if project_root else find_project_root()
+    normalized_url = normalize_server_url(server_url)
+    pid_file = _pid_file(root, normalized_url)
+    pid = _read_managed_pid(root, normalized_url)
+    if not pid and allow_unmanaged_appium:
+        pid = _local_appium_pid(normalized_url)
+    if not pid:
+        if pid_file.exists():
+            pid_file.unlink()
+        return False
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        pid_file.unlink(missing_ok=True)
+        return False
+    deadline = time.time() + 8
+    while time.time() < deadline:
+        if not _pid_running(pid):
+            pid_file.unlink(missing_ok=True)
+            return True
+        time.sleep(0.2)
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    pid_file.unlink(missing_ok=True)
+    return True
+
+
+def smoke_appium_session(server_url: str, udid: str) -> None:
+    appium = AppiumClient(server_url)
+    try:
+        appium.start_session(_smoke_capabilities(udid))
+        appium.source()
+    finally:
+        try:
+            appium.delete_session()
+        except Exception:
+            pass
+
+
+def find_project_root() -> Path:
+    candidates = [Path.cwd(), *Path.cwd().parents, Path(__file__).resolve()]
+    candidates.extend(Path(__file__).resolve().parents)
+    for candidate in candidates:
+        root = candidate if candidate.is_dir() else candidate.parent
+        if (root / "pyproject.toml").exists() and (root / "src" / "device_control").exists():
+            return root
+    return Path.cwd()
+
+
+def resolve_appium_bin(project_root: str | Path | None = None) -> Path:
+    root = Path(project_root).expanduser() if project_root else find_project_root()
+    env_bin = os.environ.get("APPIUM_BIN", "")
+    candidates = [
+        Path(env_bin).expanduser() if env_bin else None,
+        root / "node_modules" / ".bin" / "appium",
+        Path(shutil.which("appium")) if shutil.which("appium") else None,
+    ]
+    for candidate in candidates:
+        if candidate and candidate.exists():
+            return candidate
+    raise AppiumEnsureError(
+        "Appium binary not found. Install project node dependencies or set APPIUM_BIN. "
+        f"Expected project binary: {root / 'node_modules' / '.bin' / 'appium'}"
+    )
+
+
+def resolve_android_sdk_root() -> Path:
+    env_candidates = [os.environ.get("ANDROID_SDK_ROOT", ""), os.environ.get("ANDROID_HOME", "")]
+    candidates: list[Path] = [Path(item).expanduser() for item in env_candidates if item]
+    candidates.extend(
+        [
+            Path.home() / "Library" / "Android" / "sdk",
+            Path("/Users/edy/Library/Android/sdk"),
+            Path("/opt/homebrew/share/android-commandlinetools"),
+        ]
+    )
+    adb_path = _resolve_adb_path()
+    if adb_path and adb_path.parent.name == "platform-tools":
+        candidates.append(adb_path.parent.parent)
+    for candidate in sorted(Path("/opt/homebrew/Caskroom/android-platform-tools").glob("*"), reverse=True):
+        candidates.append(candidate)
+
+    for candidate in candidates:
+        if _has_platform_tools(candidate):
+            return candidate
+    raise AppiumEnsureError(
+        "Android SDK root not found. Set ANDROID_SDK_ROOT or ANDROID_HOME to a directory containing platform-tools/adb."
+    )
+
+
+def normalize_server_url(server_url: str) -> str:
+    parsed = urllib.parse.urlparse(server_url or DEFAULT_APPIUM_SERVER)
+    scheme = parsed.scheme or "http"
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 4723
+    return f"{scheme}://{host}:{port}"
+
+
+def _start_appium(server_url: str, appium_bin: Path, sdk_root: Path, log_path: Path, project_root: Path) -> int:
+    parsed = urllib.parse.urlparse(server_url)
+    host = parsed.hostname or "127.0.0.1"
+    port = str(parsed.port or 4723)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    env = os.environ.copy()
+    env["ANDROID_HOME"] = str(sdk_root)
+    env["ANDROID_SDK_ROOT"] = str(sdk_root)
+    command = [str(appium_bin), "--address", host, "--port", port, "--log-level", "info"]
+    log_handle = log_path.open("ab")
+    proc = subprocess.Popen(
+        command,
+        cwd=str(project_root),
+        env=env,
+        stdout=log_handle,
+        stderr=subprocess.STDOUT,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+        close_fds=True,
+    )
+    _pid_file(project_root, server_url).write_text(
+        json.dumps(
+            {
+                "pid": proc.pid,
+                "server_url": server_url,
+                "appium_bin": str(appium_bin),
+                "android_sdk_root": str(sdk_root),
+                "log_path": str(log_path),
+                "started_at_epoch": int(time.time()),
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        ),
+        encoding="utf-8",
+    )
+    return proc.pid
+
+
+def _get_status(server_url: str) -> dict | None:
+    try:
+        req = urllib.request.Request(f"{server_url}/status", method="GET")
+        with urllib.request.urlopen(req, timeout=3) as resp:
+            raw = resp.read().decode()
+        return json.loads(raw) if raw else {}
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError):
+        return None
+
+
+def _wait_for_status(server_url: str, timeout_s: float) -> dict | None:
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        status = _get_status(server_url)
+        if status is not None:
+            return status
+        time.sleep(0.5)
+    return None
+
+
+def _require_local_server(server_url: str) -> None:
+    host = urllib.parse.urlparse(server_url).hostname or ""
+    if host not in {"127.0.0.1", "localhost", "::1"}:
+        raise AppiumEnsureError(f"Refusing to auto-start Appium for non-local server {server_url}")
+
+
+def _resolve_adb_path() -> Path | None:
+    adb_bin = resolve_adb_bin()
+    resolved = shutil.which(adb_bin) or adb_bin
+    path = Path(resolved).expanduser()
+    try:
+        return path.resolve()
+    except FileNotFoundError:
+        return None
+
+
+def _has_platform_tools(path: Path) -> bool:
+    return path.exists() and (path / "platform-tools" / "adb").exists()
+
+
+def _state_dir(project_root: Path) -> Path:
+    path = project_root / "artifacts" / "appium"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _port_label(server_url: str) -> str:
+    parsed = urllib.parse.urlparse(server_url)
+    host = (parsed.hostname or "127.0.0.1").replace(":", "_")
+    return f"{host}-{parsed.port or 4723}"
+
+
+def _pid_file(project_root: Path, server_url: str) -> Path:
+    return _state_dir(project_root) / f"appium-{_port_label(server_url)}.pid.json"
+
+
+def _log_path(project_root: Path, server_url: str) -> Path:
+    return _state_dir(project_root) / f"appium-{_port_label(server_url)}.log"
+
+
+def _read_managed_pid(project_root: Path, server_url: str) -> int | None:
+    pid_file = _pid_file(project_root, server_url)
+    if not pid_file.exists():
+        return None
+    try:
+        payload = json.loads(pid_file.read_text(encoding="utf-8"))
+        pid = int(payload.get("pid") or 0)
+    except Exception:
+        pid_file.unlink(missing_ok=True)
+        return None
+    if pid and _pid_running(pid):
+        return pid
+    pid_file.unlink(missing_ok=True)
+    return None
+
+
+def _pid_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def _is_managed_process(project_root: Path, server_url: str) -> bool:
+    return _read_managed_pid(project_root, server_url) is not None
+
+
+def _local_appium_pid(server_url: str) -> int | None:
+    parsed = urllib.parse.urlparse(server_url)
+    host = parsed.hostname or ""
+    if host not in {"127.0.0.1", "localhost", "::1"}:
+        return None
+    port = str(parsed.port or 4723)
+    try:
+        proc = subprocess.run(
+            ["lsof", "-nP", f"-iTCP:{port}", "-sTCP:LISTEN", "-t"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    for line in proc.stdout.splitlines():
+        try:
+            pid = int(line.strip())
+        except ValueError:
+            continue
+        if _pid_command_contains(pid, "appium"):
+            return pid
+    return None
+
+
+def _pid_command_contains(pid: int, needle: str) -> bool:
+    try:
+        proc = subprocess.run(
+            ["ps", "-p", str(pid), "-o", "command="],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+    return needle.lower() in proc.stdout.lower()
+
+
+def _smoke_capabilities(udid: str) -> dict:
+    return {
+        "platformName": "Android",
+        "appium:automationName": "UiAutomator2",
+        "appium:udid": udid,
+        "appium:noReset": True,
+        "appium:newCommandTimeout": 120,
+        "appium:disableWindowAnimation": True,
+        "appium:skipDeviceInitialization": True,
+        "appium:ignoreHiddenApiPolicyError": True,
+        "appium:disableSuppressAccessibilityService": True,
+        "appium:settings[enableNotificationListener]": False,
+        "appium:autoLaunch": False,
+    }