mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/sim/doctor.py

@@ -0,0 +1,293 @@
+"""`mobster sim doctor`: what `mobster verify` needs on this Mac, and the command that fixes each gap."""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+from .. import doctor as mobster_doctor
+from .. import states
+from .models import SimError
+from .registry import SLOTS, free_slot, port_base, taken_ports
+from .xcode import parse_version
+
+OK, WARN, FAIL, SKIP = mobster_doctor.OK, mobster_doctor.WARN, mobster_doctor.FAIL, mobster_doctor.SKIP
+MIN_FREE_BYTES = 5 * 1024 ** 3
+# Measured on 28 Sep (iOS 26.4, Xcode 26.4): a freshly booted iPhone 17 Pro simulator's folder is 1.6 GB, and
+# the WebDriverAgent build 209 MB. Two simulators (MOBSTER_MAX_SIMS' default) and the build come to 3.4 GB.
+DISK_FIX = "Free at least 5 GB: each booted simulator takes 1.6 GB, and the WebDriverAgent build 0.2 GB"
+KEY_LABEL = "Smart key"
+
+
+def check(key, label, state, detail, fix=""):
+    return mobster_doctor.Check(key, label, state, detail, fix).public()
+
+
+def check_arch(manager):
+    machine = platform.machine()
+    if machine != "arm64":
+        translated = manager.run(["/usr/sbin/sysctl", "-n", "hw.optional.arm64"], timeout=5).out.strip() == "1"
+        if not translated:
+            return check("arch", "Apple silicon", FAIL, f"this Mac is {machine}",
+                         "Mobster's simulators need a Mac with Apple silicon")
+        return check("arch", "Apple silicon", WARN, "running under Rosetta",
+                     "Run the arm64 build of mobster: brew reinstall mobster")
+    return check("arch", "Apple silicon", OK, "arm64")
+
+
+def check_xcode(manager):
+    from .. import mac_tools
+    xcode, selected = mac_tools.developer_dir()
+    if not xcode:
+        return check("xcode", "Xcode", FAIL, "not installed (the Command Line Tools alone can't run simulators)",
+                     "Install Xcode from the App Store, then open it once")
+    app = str(Path(xcode).parent.parent)
+    env = {**os.environ, "DEVELOPER_DIR": xcode}
+    result = manager.run([str(Path(xcode) / "usr" / "bin" / "xcodebuild"), "-version"], timeout=60, env=env)
+    text = result.out + result.err
+    if not result.ok:
+        if "license" in text.lower():
+            return check("xcode", "Xcode", FAIL, "its license isn't accepted", "sudo xcodebuild -license accept")
+        return check("xcode", "Xcode", FAIL, f"xcodebuild failed: {result.last_line() or 'no output'}",
+                     "Open Xcode once to finish its setup")
+    version, build = parse_version(result.out)
+    detail = f"Xcode {version} ({build}) at {mobster_doctor._home(app)}"
+    if selected != xcode:
+        where = mobster_doctor._home(selected) if selected else "nothing"
+        return check("xcode", "Xcode", FAIL, f"{detail}, but xcode-select points at {where}",
+                     f"sudo xcode-select -s {app}")
+    return check("xcode", "Xcode", OK, detail)
+
+
+def check_first_launch(manager):
+    from .. import mac_tools
+    xcode, _ = mac_tools.developer_dir()
+    if not xcode:
+        return check("first_launch", "Xcode components", SKIP, "needs Xcode")
+    env = {**os.environ, "DEVELOPER_DIR": xcode}
+    result = manager.run([str(Path(xcode) / "usr" / "bin" / "xcodebuild"), "-checkFirstLaunchStatus"],
+                         timeout=60, env=env)
+    if result.ok:
+        return check("first_launch", "Xcode components", OK, "installed")
+    return check("first_launch", "Xcode components", FAIL, "Xcode's first-launch components aren't installed",
+                 "sudo xcodebuild -runFirstLaunch")
+
+
+def check_catalog(manager):
+    """The runtime and device type checks, from one `simctl list -j`."""
+    try:
+        catalog = manager._catalog()
+    except SimError as exc:
+        return [check("runtime", "iOS runtime", FAIL, str(exc), exc.fix),
+                check("device_type", "Device type", SKIP, "needs simctl")]
+    from . import simctl
+    try:
+        runtime = simctl.choose_runtime(catalog[0])
+    except SimError as exc:
+        missing = str(exc) == states.row("no_runtime").message
+        return [mobster_doctor.finding("runtime", "iOS runtime", FAIL, "no_runtime").public() if missing
+                else check("runtime", "iOS runtime", FAIL, str(exc), exc.fix),
+                check("device_type", "Device type", SKIP, "needs an iOS runtime")]
+    runtime_check = check("runtime", "iOS runtime", OK, runtime.name)
+    try:
+        device_type = simctl.choose_device_type(catalog[1], runtime)
+    except SimError as exc:
+        return [runtime_check, check("device_type", "Device type", FAIL, str(exc), exc.fix)]
+    return [runtime_check, check("device_type", "Device type", OK, device_type.name)]
+
+
+def check_git(manager, built):
+    from .. import mac_tools
+    git = mac_tools.xcode_tool("git")
+    if git:
+        return check("git", "git", OK, git)
+    if built:
+        return check("git", "git", SKIP, "not installed; not needed while WebDriverAgent is built")
+    return check("git", "git", FAIL, "not installed; the first WebDriverAgent build downloads its source with it",
+                 "Install Xcode, which includes git")
+
+
+def _existing(path):
+    path = Path(path)
+    while not path.exists() and path != path.parent:
+        path = path.parent
+    return path
+
+
+def check_disk(manager):
+    folder = _existing(manager.data_dir)
+    free = shutil.disk_usage(folder).free
+    detail = f"{free / 1024 ** 3:.0f} GB free for {mobster_doctor._home(manager.data_dir)}"
+    if free < MIN_FREE_BYTES:
+        return check("disk", "Free space", FAIL, detail, DISK_FIX)
+    return check("disk", "Free space", OK, detail)
+
+
+def wda_plan(manager):
+    from .wda import build_dir, find_xctestrun
+    try:
+        tools = manager.tools()
+    except Exception:
+        return None
+    return find_xctestrun(build_dir(manager.data_dir, tools.build))
+
+
+def check_wda_build(manager):
+    plan = wda_plan(manager)
+    if plan:
+        return check("wda_build", "WebDriverAgent", OK,
+                     f"built for this Xcode ({mobster_doctor._home(plan.parents[2])})")
+    return check("wda_build", "WebDriverAgent", WARN, "not built yet: the first run builds it, once per Xcode version",
+                 "mobster sim doctor --fix")
+
+
+def check_simulators(manager):
+    rows = manager.list()
+    if not rows:
+        return check("simulators", "Simulators", SKIP, "none yet: the first run creates one")
+    parts, stopped = [], []
+    for row in rows:
+        if row["state"] == "Booted":
+            state = "booted, WebDriverAgent " + ("ready" if row["wda"] == "ready" else "stopped")
+            if row["wda"] != "ready":
+                stopped.append(row)
+        else:
+            state = row["state"].lower()
+        parts.append(f"{row['name']} ({state}{', running a check' if row['in_use'] else ''})")
+    detail = "; ".join(parts)
+    if stopped:
+        return check("simulators", "Simulators", WARN, detail, "mobster sim prepare")
+    return check("simulators", "Simulators", OK, detail)
+
+
+def check_ports(manager):
+    base = port_base()
+    entries = manager.registry.read()
+    blocked = []
+    for entry in entries:
+        port = entry["wda_port"]
+        if manager.wda.listening(port) and manager.wda.owner(port) != entry["udid"]:
+            blocked.append(port)
+    span = f"{base}–{base + SLOTS - 1}"
+    try:
+        wda_port, _ = free_slot(base, taken_ports(entries), busy=manager.wda.listening)
+    except Exception as exc:
+        return check("ports", "Ports", FAIL, str(exc), getattr(exc, "fix", ""))
+    if blocked:
+        return check("ports", "Ports", WARN, f"another program listens on {', '.join(map(str, blocked))}: the next "
+                                             f"run moves that simulator to {wda_port}")
+    return check("ports", "Ports", OK, f"WebDriverAgent on 127.0.0.1:{span}, MJPEG on +1000; {wda_port} is free")
+
+
+# a key is reported as set or not set, never shown
+def check_key():
+    from .. import engines
+    model = engines.smart_model()
+    provider = engines.provider_name(model)
+    variable = "ANTHROPIC_API_KEY" if provider == "Anthropic" else "OPENAI_API_KEY"
+    from ..ai_plans import providers
+    routed = providers.get(engines.model_provider(model))
+    if routed is not None:
+        if engines.smart_key():
+            return check("key", KEY_LABEL, OK,
+                         f"{routed.name} is set: Smart runs flows on {engines.model_words(model)}")
+        return check("key", KEY_LABEL, WARN, f"you chose {routed.name}, and its key or sign-in is missing",
+                     f"Run mobster login {routed.id}, or mobster login for an API key")
+    if engines.smart_key():
+        return check("key", KEY_LABEL, OK, f"your {provider} key is set: Smart runs flows on {model}")
+    none_needed = "not set: launch-only and key-less checks need none"
+    if (os.environ.get("MOBSTER_SMART_MODEL") or "").strip() != model:
+        return check("key", KEY_LABEL, SKIP, f"{none_needed}; Smart needs your OpenAI or Anthropic key",
+                     "For Smart, put OPENAI_API_KEY=… or ANTHROPIC_API_KEY=… in an env file and pass --env-file PATH")
+    # MOBSTER_SMART_MODEL chose the model, and its provider's key is missing.
+    other, other_key = (("OpenAI", engines.openai_smart_key()) if provider == "Anthropic"
+                        else ("Anthropic", engines.anthropic_key()))
+    if not other_key:
+        return check("key", KEY_LABEL, SKIP, f"{none_needed}; Smart on {model} needs your {provider} key",
+                     f"For Smart, put {variable}=… in an env file and pass --env-file PATH")
+    unset = {name: value for name, value in os.environ.items() if name != "MOBSTER_SMART_MODEL"}
+    return check("key", KEY_LABEL, WARN, f"MOBSTER_SMART_MODEL is {model}, which needs {variable}; only your {other} "
+                                         "key is set, so Smart can't run",
+                 f"Add {variable}=… to your env file, or remove MOBSTER_SMART_MODEL to run Smart on "
+                 f"{engines.smart_model(unset)}")
+
+
+def _safe(key, label, function, *args):
+    try:
+        return function(*args)
+    except Exception as exc:  # a doctor reports; it never crashes
+        return check(key, label, FAIL, f"the check failed: {exc}")
+
+
+def run_checks(manager, fix=False):
+    checks = [_safe("arch", "Apple silicon", check_arch, manager),
+              _safe("xcode", "Xcode", check_xcode, manager),
+              _safe("first_launch", "Xcode components", check_first_launch, manager)]
+    xcode_ok = checks[1]["state"] == OK
+    if xcode_ok:
+        try:
+            checks += check_catalog(manager)
+        except Exception as exc:
+            checks += [check("runtime", "iOS runtime", FAIL, f"the check failed: {exc}"),
+                       check("device_type", "Device type", SKIP, "needs simctl")]
+    else:
+        checks += [check("runtime", "iOS runtime", SKIP, "needs Xcode"),
+                   check("device_type", "Device type", SKIP, "needs Xcode")]
+    checks.append(_safe("git", "git", check_git, manager, bool(xcode_ok and wda_plan(manager))))
+    checks.append(_safe("disk", "Free space", check_disk, manager))
+    # --fix only prepares a simulator: sudo and runtime downloads stay printed commands, never run
+    if fix:
+        checks.append(_prepare(manager, [item for item in checks if item["state"] == FAIL]))
+    if xcode_ok:
+        checks.append(_safe("wda_build", "WebDriverAgent", check_wda_build, manager))
+        checks.append(_safe("simulators", "Simulators", check_simulators, manager))
+        checks.append(_safe("ports", "Ports", check_ports, manager))
+    checks.append(_safe("key", KEY_LABEL, check_key))
+    from .. import android
+    if android.enabled():
+        from ..android import doctor as android_doctor
+        from ..android.emulator import EmulatorManager
+        try:
+            checks += android_doctor.run_checks(EmulatorManager(manager.data_dir))
+        except Exception as exc:
+            checks.append(check("android", "Android", FAIL, f"the check failed: {exc}"))
+    return checks
+
+
+def _prepare(manager, failures):
+    if failures:
+        return check("prepare", "Prepare", SKIP, "fix the problems above first")
+    try:
+        lease = manager.acquire()
+    except SimError as exc:
+        return check("prepare", "Prepare", FAIL, str(exc), exc.fix)
+    try:
+        target, seconds = lease.target, lease.timing.get("total", 0)
+    finally:
+        lease.release()
+    return check("prepare", "Prepare", OK, f"{target.name} is booted, with WebDriverAgent on "
+                                           f"{target.wda_url.split('//')[-1]} ({seconds:.1f} s)")
+
+
+def problems(checks):
+    return [item for item in checks if item["state"] == FAIL]
+
+
+def report(checks, color=False):
+    """One line per check, the fix under each problem, then a verdict line."""
+    from ..style import Palette
+    paint = Palette(color)
+    roles = {OK: "green", WARN: "amber", FAIL: "coral", SKIP: "tertiary"}  # the brand's, as `mobster doctor`
+    lines = ["Mobster sim doctor", ""]
+    for item in checks:
+        glyph = paint(mobster_doctor.GLYPHS[item["state"]], roles[item["state"]])
+        lines.append(f"  {glyph} {item['label']:<17} {item['detail']}")
+        if item["fix"] and item["state"] in {WARN, FAIL}:
+            lines.append(f"    {'':<17} {paint('→ ' + item['fix'], 'tertiary')}")
+    failed = problems(checks)
+    lines.append("")
+    if failed:
+        lines.append(f"{len(failed)} problem{'s' if len(failed) != 1 else ''} to fix before `mobster verify` can run.")
+    else:
+        lines.append("Ready for `mobster verify`.")
+    return "\n".join(lines)

mobile_agent/sim/governor.py

@@ -0,0 +1,90 @@
+"""How much the Mac can take: whether another simulator may boot, and when to wait instead of starting heavy work."""
+
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+
+from .models import SimError
+
+GB = 1 << 30
+SIM_GB = 4                 # free memory one more simulator needs
+MAX_SIMS_CEILING = 4       # simulators per device type and runtime when MOBSTER_MAX_SIMS is unset
+LOAD_WAIT = 30.0           # how long a boot or a WebDriverAgent build waits for the Mac to settle
+LOAD_POLL = 2.0
+
+
+@dataclass(frozen=True)
+class Pressure:
+    load: float            # the 1-minute load average
+    cores: int
+    free_gb: float         # memory that can be handed out now: free, inactive and speculative pages
+
+
+def read_pressure(run=subprocess.run):
+    cores = os.cpu_count() or 1
+    try:
+        load = os.getloadavg()[0]
+    except OSError:
+        load = 0.0
+    free = None
+    try:
+        out = run(["vm_stat"], capture_output=True, text=True, timeout=5).stdout
+        size = int(re.search(r"page size of (\d+) bytes", out).group(1))
+        pages = sum(int(re.search(rf"Pages {name}:\s+(\d+)", out).group(1))
+                    for name in ("free", "inactive", "speculative"))
+        free = pages * size / GB
+    except (OSError, subprocess.SubprocessError, AttributeError, ValueError):
+        pass
+    # memory that can't be read counts as plenty: the load check and the simulator ceiling still apply
+    return Pressure(load, cores, free if free is not None else float(MAX_SIMS_CEILING * SIM_GB))
+
+
+def load_limit(environ=None):
+    """The 1-minute load at which the Mac counts as saturated: one runnable task per core, or $MOBSTER_MAX_LOAD."""
+    environ = os.environ if environ is None else environ
+    text = str(environ.get("MOBSTER_MAX_LOAD") or "").strip()
+    if not text:
+        return None
+    try:
+        value = float(text)
+    except ValueError:
+        value = 0.0
+    if value <= 0:
+        raise SimError("environment", f"MOBSTER_MAX_LOAD is {text!r}; it must be a load average above 0.",
+                       "Unset it to treat the Mac as saturated at one runnable task per core.")
+    return value
+
+
+class Governor:
+    """Reads the Mac's load and memory (``sample``) and decides. Tests pass a ``sample`` that returns a Pressure."""
+
+    def __init__(self, sample=read_pressure, sleep=time.sleep, clock=time.monotonic):
+        self.sample, self.sleep, self.clock = sample, sleep, clock
+
+    def saturated(self, pressure=None):
+        pressure = pressure or self.sample()
+        return pressure.load >= (load_limit() or pressure.cores)
+
+    def memory_room(self, running, pressure=None, starting=0):
+        """Whether another simulator may boot while ``running`` are up: one needs 4 GB free; the first always may.
+        ``starting`` of them are still booting and haven't taken their memory yet, so SIM_GB is set aside for each."""
+        return running < 1 or (pressure or self.sample()).free_gb - SIM_GB * starting >= SIM_GB
+
+    def wait_for_calm(self, say, what, *, timeout=LOAD_WAIT):
+        """Return once the Mac isn't saturated. After ``timeout`` seconds, refuse: never start anyway."""
+        pressure = self.sample()
+        if not self.saturated(pressure):
+            return 0.0
+        began = self.clock()
+        say(f"Waiting to {what}: the Mac is busy (load {pressure.load:.0f} on {pressure.cores} cores)")
+        while self.clock() - began < timeout:
+            self.sleep(LOAD_POLL)
+            pressure = self.sample()
+            if not self.saturated(pressure):
+                return self.clock() - began
+        raise SimError("busy", f"The Mac is busy (load {pressure.load:.0f} on {pressure.cores} cores), so Mobster "
+                               f"didn't {what}. Nothing was started.",
+                       "Try again in a minute, or stop other heavy jobs. Set MOBSTER_MAX_LOAD to change when the Mac "
+                       "counts as busy.")

mobile_agent/sim/holders.py

@@ -0,0 +1,88 @@
+"""Who holds each simulator: one small file per simulator, written while a process holds its lease.
+
+The lease itself is a file lock the system frees when its owner dies, so a record whose process is gone is ignored.
+"""
+
+import contextlib
+import json
+import os
+import time
+from pathlib import Path
+
+FOLDER = "holders"
+RELEASE_SUFFIX = ".release"
+
+
+def _path(data_dir, udid, suffix=".json"):
+    return Path(data_dir) / FOLDER / f"{udid}{suffix}"
+
+
+def alive(pid):
+    try:
+        os.kill(int(pid), 0)
+    except PermissionError:
+        return True
+    except (OSError, ValueError, TypeError):
+        return False
+    return True
+
+
+def claim(data_dir, udid, who):
+    """Record this process as the holder. ``who``: {"client", "session"}."""
+    record = {"pid": os.getpid(), "ppid": os.getppid(), "client": str(who.get("client") or "mobster")[:40],
+              "session": str(who.get("session") or f"pid {os.getpid()}")[:80], "since": time.time()}
+    with contextlib.suppress(OSError):
+        folder = _path(data_dir, udid).parent
+        folder.mkdir(parents=True, exist_ok=True)
+        _path(data_dir, udid).write_text(json.dumps(record))
+        _path(data_dir, udid, RELEASE_SUFFIX).unlink(missing_ok=True)
+    return record
+
+
+def read(data_dir, udid):
+    """The live holder's record, or None."""
+    try:
+        record = json.loads(_path(data_dir, udid).read_text())
+    except (OSError, ValueError):
+        return None
+    return record if isinstance(record, dict) and alive(record.get("pid")) else None
+
+
+def clear(data_dir, udid):
+    """Forget the holder, only when it is this process."""
+    record = read(data_dir, udid)
+    if record is not None and record.get("pid") != os.getpid():
+        return
+    with contextlib.suppress(OSError):
+        _path(data_dir, udid).unlink(missing_ok=True)
+        _path(data_dir, udid, RELEASE_SUFFIX).unlink(missing_ok=True)
+
+
+def words(record):
+    minutes = max(0, int((time.time() - float(record.get("since") or time.time())) // 60))
+    return f"{record.get('client')} ({record.get('session')}), {minutes} min"
+
+
+def ancestors(pid=None):
+    """The process ids from ``pid`` up to launchd, found with ps."""
+    import subprocess
+    chain, pid = [], pid or os.getpid()
+    while pid and pid > 1 and len(chain) < 32:
+        chain.append(pid)
+        try:
+            out = subprocess.run(["ps", "-o", "ppid=", "-p", str(pid)], capture_output=True, text=True,
+                                 timeout=5).stdout.strip()
+            pid = int(out)
+        except (OSError, ValueError, subprocess.SubprocessError):
+            break
+    return chain
+
+
+def request_release(data_dir, udid):
+    """Ask the holder to let go; its server notices at its next sweep."""
+    with contextlib.suppress(OSError):
+        _path(data_dir, udid, RELEASE_SUFFIX).write_text("")
+
+
+def release_requested(data_dir, udid):
+    return _path(data_dir, udid, RELEASE_SUFFIX).exists() and read(data_dir, udid) is not None

mobile_agent/sim/models.py

@@ -0,0 +1,62 @@
+"""The values the simulator manager hands out and raises; ``api`` and the package re-export them."""
+
+import threading
+from dataclasses import dataclass
+from typing import Optional
+
+from ..errors import SimError as SimError
+
+SIM_KINDS = ("environment", "simulator", "wda", "install", "launch", "busy")
+
+
+@dataclass(frozen=True)
+class AppInfo:
+    bundle_id: str
+    name: str             # CFBundleDisplayName, else CFBundleName, else the bundle id
+    version: str          # "1.0 (1)"
+    path: Optional[str]   # the .app, or None for an app looked up by bundle id
+    icon: Optional[bytes] = None  # its home screen icon as a PNG (apps.icon_png), when its bundle has one to read
+    executable: Optional[str] = None  # CFBundleExecutable: the process name its log and crash reports carry
+
+
+@dataclass(frozen=True)
+class SimTarget:
+    udid: str
+    name: str             # "Mobster · iPhone 17 Pro · iOS 26.4"
+    device_type: str      # "iPhone 17 Pro"
+    runtime: str          # "iOS 26.4"
+    wda_url: str          # "http://127.0.0.1:8310"
+    mjpeg_url: str        # "http://127.0.0.1:9310"
+    xctestrun: str        # the built runner plan (for the restarter)
+
+
+class SimLease:
+    """Holds one simulator's device lease; ``release()`` is idempotent."""
+    target: SimTarget
+
+    def __init__(self, target: SimTarget, leases=(), timing: Optional[dict] = None, on_release=None):
+        self.target = target
+        self._on_release = on_release
+        self.timing = dict(timing or {})
+        self._leases = list(leases)
+        self._lock = threading.Lock()
+
+    def release(self) -> None:
+        with self._lock:
+            leases, self._leases = self._leases, []
+            on_release, self._on_release = self._on_release, None
+        try:
+            if on_release is not None:
+                on_release()
+        finally:
+            for lease in leases:
+                try:
+                    lease.close()
+                except OSError:
+                    pass
+
+    def __enter__(self) -> SimTarget:
+        return self.target
+
+    def __exit__(self, *exc) -> None:
+        self.release()