mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/runner_hints.py

@@ -0,0 +1,86 @@
+"""What the USB helper's failures say, in plain words: xcodebuild errors, runner log causes and automation prompts."""
+
+import datetime
+import re
+
+# xcodebuild failures users can act on, in their words.
+BUILD_HINTS = (
+    ("isn't registered in your developer account",
+     "This iPhone isn't registered with your Apple team. Open Xcode › Settings › Accounts, select the team, "
+     "and let Xcode register the device (or register it in the Apple Developer portal)."),
+    ("No Accounts", "Sign in to Xcode with your Apple ID: Xcode › Settings › Accounts."),
+    ("No signing certificate", "Xcode has no signing certificate for this team yet. Open Xcode › Settings › Accounts "
+                               "and choose Manage Certificates › Apple Development."),
+    ("Developer Mode",
+     "Turn on Developer Mode on the iPhone: Settings › Privacy & Security › Developer Mode, then restart it."),
+    ("is not available", "The iPhone isn't available to Xcode. Unlock it, keep it connected, and trust this Mac."),
+    ("requires a development team", "Choose your Apple development team and build again."),
+    ("requires Xcode, but active developer directory",
+     "Mobster couldn't find Xcode. Install it from the Mac App Store and open it once, then build again."),
+    ("agreed to the Xcode", "Accept the Xcode license: open Xcode and agree, then build again."),
+    ("invalid active developer path", "Install Xcode from the Mac App Store and open it once, then build again."),
+    ("Could not resolve host",
+     "Mobster couldn't download WebDriverAgent. Check your internet connection and build again."),
+    ("Unable to find a destination", "Xcode can't use your iPhone yet. Unlock it, keep it connected and turn on "
+                                     "Developer Mode. If iOS is newer than your Xcode, update Xcode."),
+)
+EXPOSED_HINT = ("Mobster stopped its helper on your iPhone because it answered on the phone's network address, "
+                "where anyone on that network could reach it. Build it again, then start it.")
+# A free Apple account's signature lasts 7 days; after that iOS refuses to launch the runner.
+EXPIRED_HINT = "Mobster's helper needs a refresh: its signature expired. Refresh it in Setup."
+# A runner held back because the phone is locked (DeviceManager.runner_waiting): it launches when the phone is unlocked.
+LOCKED_START_HINT = "Unlock your iPhone. Mobster's helper starts as soon as it is unlocked."
+# Why a started runner is not answering yet, read from the tail of its log.
+RUNNER_HINTS = (
+    ("because the device is locked", "locked", LOCKED_START_HINT),
+    # iOS asks for the passcode to let UI automation start unless Settings › Developer › Enable UI Automation is on;
+    # nobody answering it fails the start after 60 s.
+    ("Timed out while enabling automation mode", "ui_automation_off",
+     "On your iPhone, turn on Settings › Developer › Enable UI Automation, and keep it unlocked while Mobster's helper "
+     "starts."),
+    ("Developer Mode", "developer_mode_off",
+     "Turn on Developer Mode on the iPhone: Settings › Privacy & Security › Developer Mode."),
+    ("has not been explicitly trusted", "trust_needed",
+     "On the iPhone, open Settings › General › VPN & Device Management and trust your developer app."),
+    ("invalid code signature", "trust_needed",
+     "On the iPhone, open Settings › General › VPN & Device Management and trust your developer app."),
+    ("is not available", None,
+     "The iPhone isn't available to Xcode. Keep it connected, unlocked and trusting this Mac."),
+)
+
+# The runner says "Running tests..." and, once iOS has turned on automation mode, "Test Suite 'All tests' started"
+# about 2 s later (Michelle's iPhone 16, iOS 18.3.1, 17 Oct 2026: 1.9 s). With Settings › Developer › Enable UI
+# Automation off, iOS waits for the passcode instead and the start fails after 60 s. Waiting this long already names
+# the cause, so the person can act during the first launch instead of after two 60 s timeouts.
+AUTOMATION_WAIT_S = 8.0
+AUTOMATION_WAITING = "Mobster: iOS hasn't enabled automation mode for the helper yet"
+AUTOMATION_WAIT_HINT = ("On your iPhone, turn on Settings › Developer › Enable UI Automation. If it asks for its "
+                        "passcode, enter it. Mobster's helper starts by itself after that.")
+# The pre-arm (L13): iOS 17 and later wait for the passcode before a first UI-test session unless Settings › Developer
+# › Enable UI Automation is on, and no API on the Mac reads that switch (CoreDevice's details, DDI services and lockdown
+# say nothing of it; checked 17 Oct 2026, iOS 18.3.1). So for a phone whose helper has never answered, Mobster asks
+# for the switch while the helper installs, in the build's ~50 s, so the first launch passes instead of timing out.
+PREARM_MIN_IOS = 17
+PREARM_ASK = ("On your iPhone, open Settings › Developer and turn on Enable UI Automation, so Mobster's helper "
+              "starts on the first try.")
+RUNNER_STAMP = re.compile(r"^(\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d+[+-]\d{4}) WebDriverAgentRunner-Runner\[")
+
+
+def runner_stamp(line):
+    """The epoch seconds a runner log line was written (its own "2026-10-17 19:47:46.812939-0700" prefix), or None."""
+    match = RUNNER_STAMP.match(line)
+    if match is None:
+        return None
+    try:
+        return datetime.datetime.strptime(match.group(1), "%Y-%m-%d %H:%M:%S.%f%z").timestamp()
+    except ValueError:
+        return None
+
+
+def build_hint(lines):
+    text = "\n".join(lines)
+    for needle, hint in BUILD_HINTS:
+        if needle in text:
+            return hint
+    errors = [line.strip() for line in lines if "error:" in line]
+    return errors[-1][:300] if errors else "The build failed. See the build log for details."

mobile_agent/runner_renewal.py

@@ -0,0 +1,205 @@
+"""Renews the runner before its signature runs out, and rebuilds it after an update changes its patches."""
+
+import threading
+import time
+
+from .signing import renew_window
+
+# After a renewal that failed, try again this much later (Xcode or Apple may be down).
+RETRY_AFTER = 6 * 3600
+# With less than this left a failed renewal is tried again sooner: a quarter of the time left, at least this often.
+RETRY_FLOOR = 15 * 60
+# While the runner is stopped, CoreDevice's lock reading is reused for this long: the watch loop ticks every 5 s.
+LOCK_READ_EVERY = 30
+
+
+def coredevice_locked(udid):
+    """The phone's lock as CoreDevice reports it: True, False, or None when it can't say."""
+    from .wireless import devicectl
+    return devicectl.read_lock_state(udid) if udid else None
+
+
+class RunnerRenewal:
+    def __init__(self, manager, busy=lambda: False, clock=time.time, builder=None, restarter=None,
+                 lock_reader=coredevice_locked):
+        self.manager, self.busy, self.clock = manager, busy, clock
+        self.builder = builder or (lambda team: manager.start_build(team, renewal=True))
+        self.restarter = restarter or manager.start_runner
+        self.lock_reader = lock_reader
+        self.lock_read = (None, None)   # (when, reading) of the newest CoreDevice lock read
+        self.lock = threading.Lock()
+        # What a renewal was started for (the signature's expiry, or ("patches", digest) for an out-of-date runner),
+        # when, and whether it is still building.
+        self.renewed_for = None
+        self.attempted_at = None
+        self.building = False
+        self.restart_pending = False
+        self.error = None
+
+    # -- when ----------------------------------------------------------------------
+
+    def expires_at(self):
+        return self.manager.signature_expiry()
+
+    def out_of_date(self):
+        """A runner built with other WDA patches than this Mobster has: an update changed them."""
+        check = getattr(self.manager, "out_of_date", None)
+        try:
+            return bool(check()) if callable(check) else False
+        except Exception:  # noqa: BLE001
+            return False
+
+    def target(self):
+        """What a renewal now would be for: ("patches", digest) for an out-of-date runner,
+        else the signature's expiry."""
+        if self.out_of_date():
+            from .wda import patches as wda_patches
+            return ("patches", wda_patches.patch_digest())
+        return self.expires_at()
+
+    def _unlocked_by_coredevice(self, udid, now):
+        """CoreDevice's lock reading while the runner can't give one, reused for LOCK_READ_EVERY seconds."""
+        at, reading = self.lock_read
+        if at is None or now - at >= LOCK_READ_EVERY or now < at:
+            try:
+                reading = self.lock_reader(udid)
+            except Exception:  # noqa: BLE001
+                reading = None
+            reading = reading if isinstance(reading, bool) else None
+            self.lock_read = (now, reading)
+        return None if reading is None else not reading
+
+    def reason_to_wait(self, now=None):
+        """Why a renewal can't start now (a short id), or None when it can."""
+        now = self.clock() if now is None else now
+        manager = self.manager
+        settings = manager.settings()
+        expires = self.expires_at()
+        stale = self.out_of_date()
+        if not stale:
+            if expires is None:
+                return "unknown_expiry"
+            if expires - now > renew_window():
+                return "not_due"
+        if not settings.get("team") or not settings.get("udid"):
+            return "not_set_up"
+        if settings.get("built_for", settings.get("udid")) != settings.get("udid"):
+            return "not_set_up"
+        # never for a locked or disconnected phone: xcodebuild stalls on it, with nobody there to see why
+        device = manager.device()
+        if device is None or not device.get("trusted"):
+            return "disconnected"
+        health = manager.health
+        if health.get("responsive") is None:
+            # Nothing answers for the phone (the runner is stopped, expired or out of date): CoreDevice says.
+            unlocked = self._unlocked_by_coredevice(device.get("udid") or settings.get("udid"), now)
+            if unlocked is None:
+                return "runner_stopped"
+            if not unlocked:
+                return "locked"
+        elif health.get("locked") is not False or health.get("responsive") is not True:
+            return "locked"
+        presence = getattr(manager, "presence", None)
+        if presence is not None and presence.is_owner_active():
+            return "owner_active"  # the owner is on the phone: a build and install would reach into their hands
+        if self.busy():
+            return "busy"
+        if manager.build.get("state") == "running":
+            return "building"
+        if self.renewed_for == self.target() and (self.building or self.error is None):
+            return "done"
+        if self.attempted_at is not None:
+            # An out-of-date runner has no deadline of its own: a failed rebuild is tried again RETRY_AFTER later.
+            deadline = expires if expires is not None and not stale else self.attempted_at + 4 * RETRY_AFTER
+            if now - self.attempted_at < self.retry_after(deadline, self.attempted_at):
+                return "retry_later"
+        return None
+
+    @staticmethod
+    def retry_after(expires, now):
+        left = max(0.0, expires - now)
+        return min(RETRY_AFTER, max(RETRY_FLOOR, left / 4))
+
+    # -- the watch loop's tick -------------------------------------------------------
+
+    def tick(self):
+        """Called every few seconds by DeviceManager.watch. Returns True when it started a build."""
+        with self.lock:
+            self._follow_build()
+            if self.signed_here():
+                return False
+            if self.reason_to_wait() is not None:
+                return False
+            team = self.manager.settings()["team"]
+            self.renewed_for, self.attempted_at, self.error = self.target(), self.clock(), None
+            self.restart_pending = self.manager.runner is not None and self.manager.runner.running
+            try:
+                self.builder(team)
+            except Exception as error:  # a build refused up front (no phone, Xcode broke) is retried later
+                self.error = str(error)[:300]
+                return False
+            self.building = True
+            return True
+
+    def signed_here(self):
+        """A helper signed on this Mac with the team's profile (team_signing) isn't renewed by a build: its profile
+        lasts a year, and Setup shows the card to sign it again when it ends. A build here would need Xcode."""
+        driver = (self.manager.settings() or {}).get("driver") if hasattr(self.manager, "settings") else None
+        return isinstance(driver, str) and driver != "xcodebuild"
+
+    def _follow_build(self):
+        """After our build: remember a failure, and restart a running runner between tasks."""
+        if not self.building:
+            if self.restart_pending and not self.busy():
+                self.restart_pending = False
+                try:
+                    self.restarter()
+                except Exception as error:
+                    self.error = str(error)[:300]
+            return
+        state = self.manager.build.get("state")
+        if state == "running":
+            return
+        self.building = False
+        if state == "failed":
+            self.error = self.manager.build.get("error") or "The renewal build failed."
+            self.restart_pending = False
+        elif state == "succeeded":
+            if not isinstance(self.renewed_for, tuple) and self.expires_at() == self.renewed_for:
+                # Xcode signed with the same profile again: say so rather than claim a renewal.
+                self.error = "Xcode reused the old signature. Refresh Mobster's helper again from Settings."
+            if self.restart_pending and not self.busy():
+                self.restart_pending = False
+                try:
+                    self.restarter()
+                except Exception as error:
+                    self.error = str(error)[:300]
+
+    # -- what Setup shows --------------------------------------------------------------
+
+    def status(self):
+        """{"state", "error", "attempted_at"}: idle, due (waiting for the phone), renewing or failed."""
+        now = self.clock()
+        window = renew_window()
+        expires = self.expires_at()
+        reason = self.reason_to_wait(now)
+        if self.building:
+            state = "renewing"
+        elif self.error:
+            state = "failed"
+        elif (self.out_of_date() or expires is not None and expires - now <= window) and reason in {
+                "disconnected", "locked", "runner_stopped", "owner_active", "busy", "building",
+                                                  "retry_later"}:
+            state = "due"
+        else:
+            state = "idle"
+        return {"state": state, "waiting_for": reason if state == "due" else None, "error": self.error,
+                "attempted_at": round(self.attempted_at * 1000) if self.attempted_at else None,
+                "window_hours": window // 3600,
+                # When the signature runs out (epoch ms) and how long is left: the fleet view and the Mac app's
+                # notification say "renewal due" with this deadline while the phone is away, locked or in use.
+                "deadline": round(expires * 1000) if expires is not None else None,
+                "hours_left": round((expires - now) / 3600, 1) if expires is not None else None,
+                "overdue": bool(expires is not None and expires <= now)}
+
+    public = status