mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/sim/apps.py

@@ -0,0 +1,172 @@
+"""The app under test: its Info.plist, and emptying its containers on a reset."""
+
+import os
+import plistlib
+import re
+import shutil
+from io import BytesIO
+from pathlib import Path
+
+from .models import SimError
+
+SIMULATOR_PLATFORM = "iPhoneSimulator"
+BUILD_FOR_SIMULATOR = ("xcodebuild -scheme <Scheme> -destination 'generic/platform=iOS Simulator' "
+                       "-derivedDataPath .mobster/build CODE_SIGNING_ALLOWED=NO build")
+EMPTIED = ("Documents", "Library", "tmp")
+# The icon a report shows beside the app's name: 2 times its 16 px, with room to spare for a 3x screen.
+ICON_SIZE = 120
+# An icon file name the asset catalog writes (AppIcon60x60, AppIcon76x76~ipad), never a path.
+ICON_NAME = re.compile(r"[A-Za-z0-9 ._~-]{1,100}")
+ICON_FILE_LIMIT = 2_000_000
+
+
+def devices_root():
+    return Path.home() / "Library" / "Developer" / "CoreSimulator" / "Devices"
+
+
+def device_folder(udid):
+    return devices_root() / udid
+
+
+def read_info(app_path):
+    """The .app's Info.plist as a dict. SimError("install") when it isn't a readable app bundle."""
+    path = Path(app_path).expanduser()
+    if not path.is_dir():
+        raise SimError("install", f"{path} isn't an .app folder.",
+                       "Pass the .app that xcodebuild built for the iOS Simulator (a folder ending in .app).")
+    try:
+        with open(path / "Info.plist", "rb") as stream:
+            info = plistlib.load(stream)
+    except FileNotFoundError:
+        raise SimError("install", f"{path} has no Info.plist, so it isn't an app bundle.",
+                       "Pass the .app that xcodebuild built for the iOS Simulator.") from None
+    except (OSError, ValueError, plistlib.InvalidFileException):
+        raise SimError("install", f"{path}/Info.plist can't be read.", "Build the app again.") from None
+    if not isinstance(info, dict):
+        raise SimError("install", f"{path}/Info.plist isn't a dictionary.", "Build the app again.")
+    return info
+
+
+def version_text(info):
+    """ "1.0 (1)" from CFBundleShortVersionString and CFBundleVersion; either alone when that is all there is."""
+    short = str(info.get("CFBundleShortVersionString") or "").strip()
+    build = str(info.get("CFBundleVersion") or "").strip()
+    if short and build and short != build:
+        return f"{short} ({build})"
+    return short or build
+
+
+def display_name(info, bundle_id):
+    return str(info.get("CFBundleDisplayName") or info.get("CFBundleName") or bundle_id)
+
+
+# A device build's PNGs are Apple's CgBI variant, which Pillow can't read, so a device build has no icon here.
+def icon_png(app_path, info, size=ICON_SIZE):
+    from PIL import Image
+
+    folder = Path(app_path).expanduser()
+    names = list(info.get("CFBundleIconFiles") or ())
+    for key in ("CFBundleIcons", "CFBundleIcons~ipad"):
+        icons = info.get(key)
+        primary = icons.get("CFBundlePrimaryIcon") if isinstance(icons, dict) else None
+        if isinstance(primary, dict):
+            names += list(primary.get("CFBundleIconFiles") or ()) + [primary.get("CFBundleIconName")]
+    best = None
+    for name in {name for name in names if isinstance(name, str) and ICON_NAME.fullmatch(name) and ".." not in name}:
+        for file in folder.glob(f"{name}*.png"):
+            if file.parent != folder or not file.is_file() or file.stat().st_size > ICON_FILE_LIMIT:
+                continue
+            try:
+                with Image.open(file) as image:
+                    image.verify()
+                with Image.open(file) as image:
+                    area = image.width * image.height
+                    if image.width == image.height and image.width <= 1024 and (best is None or area > best[0]):
+                        best = (area, file)
+            except (OSError, ValueError, SyntaxError):
+                continue
+    if best is None:
+        return None
+    with Image.open(best[1]) as image:
+        icon = image.convert("RGBA").resize((size, size), Image.LANCZOS)
+    out = BytesIO()
+    icon.save(out, "PNG", optimize=True)
+    return out.getvalue()
+
+
+def url_schemes(info):
+    """The URL schemes the app declares (CFBundleURLTypes) as written, in order, without duplicates."""
+    schemes = []
+    for kind in info.get("CFBundleURLTypes") or ():
+        for scheme in (kind.get("CFBundleURLSchemes") or ()) if isinstance(kind, dict) else ():
+            scheme = str(scheme).strip()
+            if scheme and scheme not in schemes:
+                schemes.append(scheme)
+    return schemes
+
+
+def scheme_approvals(udid):
+    path = device_folder(udid) / "data" / "Library" / "Preferences" / "com.apple.launchservices.schemeapproval.plist"
+    try:
+        with open(path, "rb") as stream:
+            data = plistlib.load(stream)
+    except (OSError, ValueError, plistlib.InvalidFileException):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def built_for_simulator(info):
+    platforms = info.get("CFBundleSupportedPlatforms")
+    if isinstance(platforms, list) and platforms:
+        return SIMULATOR_PLATFORM in platforms
+    return str(info.get("DTPlatformName") or "").lower() == "iphonesimulator"
+
+
+def device_build_error(path):
+    return SimError("install", "This .app was built for a device. Build it for the iOS Simulator: "
+                               f"{BUILD_FOR_SIMULATOR}",
+                    f"Rebuild {Path(path).name} with -destination 'generic/platform=iOS Simulator'.")
+
+
+def inside(path, root):
+    """Whether ``path`` resolves (symlinks followed) to a place strictly inside ``root``."""
+    real, base = os.path.realpath(path), os.path.realpath(root)
+    return real != base and real.startswith(base.rstrip(os.sep) + os.sep)
+
+
+def guard_container(container, udid):
+    """The container's real path, or SimError("simulator") when it isn't inside this simulator's folder."""
+    folder = device_folder(udid)
+    if not folder.is_dir():
+        raise SimError("simulator", f"The simulator's folder {folder} is missing.",
+                       "Delete it with `mobster sim delete` and run again.")
+    if not container or not inside(container, folder):
+        raise SimError("simulator", f"The container {container} resolves outside this simulator's folder "
+                                    f"({os.path.realpath(container) if container else 'no path'}), so Mobster "
+                                    "didn't empty it.",
+                       "Use a simulator Mobster created (`mobster sim prepare`); a cloned one shares containers.")
+    root = Path(os.path.realpath(container))
+    for name in EMPTIED:
+        folder = root / name
+        if folder.is_symlink():
+            raise SimError("simulator", f"{folder} is a symbolic link, so Mobster didn't empty it.",
+                           "Erase the simulator with `mobster sim erase`.")
+    return root
+
+
+def empty_container(container, udid):
+    root = guard_container(container, udid)
+    removed = 0
+    for name in EMPTIED:
+        folder = root / name
+        if not folder.is_dir():
+            continue
+        for entry in list(os.scandir(folder)):
+            # a symlink is removed as a link, never followed
+            path = Path(entry.path)
+            if entry.is_dir(follow_symlinks=False):
+                shutil.rmtree(path)
+            else:
+                path.unlink()
+            removed += 1
+    return removed

mobile_agent/sim/biometrics.py

@@ -0,0 +1,84 @@
+"""Simulator biometric events through the notifyutil backend used by Appium."""
+
+import re
+
+from ..devices import wda_url
+from .models import SimError
+
+# Appium's names: https://github.com/appium/appium-ios-simulator/blob/f104016afea238b138054d7c9b868dfbec77be72/lib/extensions/biometric.ts
+ENROLLMENT = "com.apple.BiometricKit.enrollmentChanged"
+BIOMETRICS = {"face-id": "pearl", "touch-id": "fingerTouch"}
+ACTIONS = ("status", "enroll", "unenroll", "match", "nonmatch")
+
+
+def perform(manager, udid, action, biometric_type="face-id"):
+    # no acquire_udid: it dismisses the authentication prompt this command exercises
+    if action not in ACTIONS or biometric_type not in BIOMETRICS:
+        raise SimError("simulator", "Unknown biometric action or type.",
+                       "See `mobster sim biometric --help`.")
+    # Claim the current port under the registry lock: acquire() may move a runner
+    # to a different port while preparing it. Never lock a stale address.
+    lease = None
+    try:
+        with manager.registry.edit() as entries:
+            entry = dict(manager._entry(udid, entries))
+            lease = manager._try_lease(wda_url(entry["wda_port"]))
+            if lease is None:
+                raise SimError("busy", f"{entry['name']} is running a check.",
+                               "Wait for it to finish, or stop it, before sending biometric events.")
+        current = manager._guard_owned(entry, manager._devices())
+        if current is None or current.state != "Booted":
+            raise SimError("simulator", "Biometric testing needs a booted Mobster simulator.",
+                           "Run `mobster sim prepare`, then use the UDID from `mobster sim list`.")
+        return _perform(manager, entry["udid"], action, biometric_type)
+    finally:
+        if lease is not None:
+            lease.close()
+
+
+def _notify(manager, udid, *args):
+    result = manager.simctl("spawn", udid, "notifyutil", *args, timeout=30)
+    if not result.ok:
+        raise SimError("simulator", f"The simulator biometric command did not complete: "
+                       f"{result.last_line() or 'notifyutil failed'}",
+                       "Inspect the app and `mobster sim biometric <UDID> status` before sending another event.")
+    return result.out
+
+
+def deliver(manager, udid, action, biometric_type="face-id"):
+    """``action`` on simulator ``udid`` without the lease check ``perform`` makes: for a check run that holds the
+    simulator itself (a Face ID match while its app waits for one). The caller owns the lease."""
+    if action not in ACTIONS or biometric_type not in BIOMETRICS:
+        raise SimError("simulator", "Unknown biometric action or type.", "See `mobster sim biometric --help`.")
+    return _perform(manager, udid, action, biometric_type)
+
+
+def _enrolled(manager, udid):
+    output = _notify(manager, udid, "-g", ENROLLMENT)
+    match = re.fullmatch(re.escape(ENROLLMENT) + r"\s+([01])", output.strip())
+    if match is None:
+        raise SimError("simulator", "The simulator did not report a recognized biometric enrollment state.",
+                       "Use Simulator's Features menu to inspect enrollment; this runtime may be unsupported.")
+    return match[1] == "1"
+
+
+def _perform(manager, udid, action, biometric_type):
+    if action in ("enroll", "unenroll"):
+        enabled = action == "enroll"
+        _notify(manager, udid, "-s", ENROLLMENT, "1" if enabled else "0")
+        _notify(manager, udid, "-p", ENROLLMENT)
+        enrolled = _enrolled(manager, udid)
+        if enrolled != enabled:
+            raise SimError("simulator", "The simulator did not confirm the requested biometric enrollment.",
+                           "Inspect enrollment in Simulator's Features menu before trying again.")
+    else:
+        enrolled = _enrolled(manager, udid)
+        if action in ("match", "nonmatch"):
+            if not enrolled:
+                raise SimError("simulator", "The simulator has no enrolled biometric.",
+                               f"Run `mobster sim biometric {udid} enroll` before sending a match event.")
+            outcome = "match" if action == "match" else "nomatch"
+            notification = f"com.apple.BiometricKit_Sim.{BIOMETRICS[biometric_type]}.{outcome}"
+            _notify(manager, udid, "-p", notification)
+    return {"udid": udid, "action": action, "type": biometric_type, "enrolled": enrolled,
+            "event_sent": action in ("match", "nonmatch")}

mobile_agent/sim/cli.py

@@ -0,0 +1,271 @@
+"""`mobster sim` (and `python -m mobile_agent.sim`): Mobster's own headless simulators."""
+
+import argparse
+import json
+import sys
+import time
+
+from .models import SimError
+
+EXIT_OK, EXIT_FAILED, EXIT_USAGE = 0, 1, 2
+
+
+def add_arguments(parser, helpers):
+    from .biometrics import ACTIONS, BIOMETRICS
+    formatter = getattr(parser, "formatter_class", argparse.HelpFormatter)
+    subs = parser.add_subparsers(dest="sim_command", metavar="<command>", required=True,
+                                 help="what to do with Mobster's simulators")
+    prog = parser.prog
+
+    def command(name, help, description):
+        return subs.add_parser(name, prog=f"{prog} {name}", help=help, description=description,
+                               formatter_class=formatter)
+
+    listing = command("list", "list Mobster's simulators",
+                      "List the simulators Mobster created, with their state and WebDriverAgent address.")
+    listing.add_argument("--json", action="store_true", help="print JSON instead of a table")
+
+    release = command("release", "ask the agents you started to let go of their simulators",
+                      "Ask each `mobster mcp` server started by the same app as this shell, such as the agent that "
+                      "runs this command, to release the simulator it holds. It lets go at its next sweep, within "
+                      "15 seconds. A simulator another app's agent holds is left alone.")
+    release.add_argument("--all-mine", action="store_true", required=True,
+                         help="every simulator held by an agent started from the same app as this shell")
+
+    prepare = command("prepare", "create, boot and start WebDriverAgent, timing each phase",
+                      "Create the simulator if needed, boot it headless, build WebDriverAgent the first time, start "
+                      "it on 127.0.0.1, and print how long each phase took. It stays up afterwards.")
+    prepare.add_argument("--device", metavar="NAME", help="the simulator device type (default: iPhone 17 Pro, else "
+                                                          "the newest iPhone the runtime supports)")
+    prepare.add_argument("--runtime", metavar="NAME", help="the iOS runtime, such as \"iOS 26.4\" (default: the "
+                                                           "newest installed)")
+    prepare.add_argument("--json", action="store_true", help="print the simulator and the phase times as JSON")
+
+    biometric = command("biometric", "test biometric enrollment and authentication on a simulator",
+                        "Read or change biometric enrollment, or send a Face ID or Touch ID test event to an "
+                        "idle, booted Mobster simulator. Real devices are never supported. A sent event does "
+                        "not confirm that the app authenticated.")
+    biometric.add_argument("udid", metavar="UDID", help="the booted Mobster simulator")
+    biometric.add_argument("action", choices=ACTIONS,
+                           help="read enrollment, enable or disable it, or send a match or nonmatch event")
+    biometric.add_argument("--type", choices=tuple(BIOMETRICS), default="face-id", dest="biometric_type",
+                           help="the biometric event type (default: face-id; enrollment is shared)")
+    biometric.add_argument("--json", action="store_true", help="print enrollment and event delivery as JSON")
+
+    shutdown = command("shutdown", "stop WebDriverAgent and shut down Mobster's simulators",
+                       "Stop WebDriverAgent and shut down every Mobster simulator that isn't running a check, or "
+                       "the one named.")
+    shutdown.add_argument("udid", nargs="?", metavar="UDID", help="only this simulator")
+
+    erase = command("erase", "erase one Mobster simulator",
+                    "Shut down and erase one Mobster simulator: its apps and data go, and the next run boots it "
+                    "fresh.")
+    erase.add_argument("udid", metavar="UDID", help="the simulator to erase")
+
+    delete = command("delete", "delete Mobster's simulators",
+                     "Shut down and delete Mobster's simulators. Only UDIDs in Mobster's registry whose names start "
+                     "with “Mobster · ” are deleted; any other UDID is refused.")
+    which = delete.add_mutually_exclusive_group(required=True)
+    which.add_argument("udid", nargs="?", metavar="UDID", help="the simulator to delete")
+    which.add_argument("--all", action="store_true", help="delete every Mobster simulator")
+
+    prune = command("prune", "remove unused simulators and stale WebDriverAgent builds",
+                    "Delete Mobster simulators unused for 14 days, WebDriverAgent builds for Xcode versions no "
+                    "longer installed, and registry entries for simulators that are gone.")
+    prune.add_argument("--json", action="store_true", help="print what was removed as JSON")
+
+    from .. import android
+    if android.enabled():
+        droid = command("android", "list, boot or stop Android emulators and devices",
+                        "List Android devices (emulators and USB phones), boot an emulator and hold it for a run, or "
+                        "shut down the emulators Mobster booted. Emulators you started yourself are never stopped.")
+        droid.add_argument("action", choices=("list", "boot", "shutdown"), help="what to do")
+        droid.add_argument("avd", nargs="?", metavar="AVD", help="the virtual device to boot or stop")
+        droid.add_argument("--json", action="store_true", help="print JSON instead of a table")
+
+    doctor = command("doctor", "check what `mobster verify` needs",
+                     "Check Xcode, the iOS runtime, the device type, git, disk space, WebDriverAgent, Mobster's "
+                     "simulators, ports, and your OpenAI or Anthropic key for Smart, and print the fix for each "
+                     "problem. It never runs sudo and never downloads a runtime.")
+    doctor.add_argument("--fix", action="store_true", help="prepare the simulator: create, boot and build "
+                                                           "WebDriverAgent once")
+    doctor.add_argument("--json", action="store_true",
+                        help="print {\"ok\", \"checks\": [{\"key\", \"label\", \"state\", \"detail\", \"fix\"}]}")
+
+
+def run(args) -> int:
+    return _run(args, _progress_lines())
+
+
+def _progress_lines():
+    try:
+        from ..devtools import ProgressLines
+    except ImportError:
+        return _progress
+    return ProgressLines(sys.stderr)
+
+
+def _run(args, progress) -> int:
+    from .api import SimulatorManager
+    as_json = bool(getattr(args, "json", False))
+    manager = SimulatorManager(progress=progress)
+    end = getattr(progress, "end", lambda: None)  # a "Still …" line on a terminal
+    name = getattr(args, "sim_command", None)
+    try:
+        if name == "list":
+            return _list(manager, as_json)
+        if name == "release":
+            asked = manager.release_mine()
+            print(f"Asked {len(asked)} simulator{'s' if len(asked) != 1 else ''} to let go. They are free within "
+                  "15 seconds." if asked else "None of your agents holds a simulator.")
+            return EXIT_OK
+        if name == "prepare":
+            return _prepare(manager, args, as_json, end)
+        if name == "biometric":
+            result = manager.biometric(args.udid, args.action, biometric_type=args.biometric_type)
+            if as_json:
+                _print_json(result)
+            elif result["event_sent"]:
+                print(f"Sent {args.biometric_type} {args.action} event. Check the app for the result.")
+            else:
+                print("Biometric enrollment: " + ("enabled" if result["enrolled"] else "disabled"))
+            return EXIT_OK
+        if name == "android":
+            return _android(manager, args, as_json)
+        if name == "shutdown":
+            manager.shutdown(args.udid)
+            if not manager.registry.read():
+                print("No Mobster simulators.")
+            return EXIT_OK
+        if name == "erase":
+            manager.erase(args.udid)
+            return EXIT_OK
+        if name == "delete":
+            deleted = manager.delete(None if args.all else args.udid)
+            if not deleted:
+                print("No Mobster simulators to delete.")
+            return EXIT_OK
+        if name == "prune":
+            removed = manager.prune()
+            if as_json:
+                _print_json(removed)
+            else:
+                lines = [f"Deleted {udid}" for udid in removed["simulators"]]
+                lines += [f"Forgot {udid}: it no longer exists" for udid in removed["entries"]]
+                lines += [f"Removed {path}" for path in removed["wda_builds"]]
+                print("\n".join(lines) or "Nothing to prune.")
+            return EXIT_OK
+        if name == "doctor":
+            from .doctor import problems, report
+            checks = manager.doctor(fix=bool(args.fix))
+            end()
+            if as_json:
+                _print_json({"ok": not problems(checks), "checks": checks})
+            else:
+                print(report(checks, color=_color()))
+            return EXIT_FAILED if problems(checks) else EXIT_OK
+        print(f"mobster sim: unknown command {name!r}", file=sys.stderr)
+        return EXIT_USAGE
+    except SimError as exc:
+        end()
+        if as_json:
+            _print_json({"ok": False, "error": {"kind": exc.kind, "message": str(exc), "fix": exc.fix}})
+        print(f"mobster sim: {exc}" + (f"\n  {exc.fix}" if exc.fix else ""), file=sys.stderr)
+        return EXIT_FAILED
+    except KeyboardInterrupt:
+        end()
+        return 130
+    except Exception as exc:  # never raise into mobster's main
+        end()
+        print(f"mobster sim: {type(exc).__name__}: {exc}", file=sys.stderr)
+        return EXIT_FAILED
+
+
+def _progress(message):
+    print(message, file=sys.stderr, flush=True)
+
+
+def _print_json(value):
+    print(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def _color():
+    try:
+        from ..style import color_enabled
+        return color_enabled(sys.stdout)
+    except Exception:
+        return False
+
+
+def _list(manager, as_json):
+    rows = manager.list()
+    if as_json:
+        _print_json({"simulators": rows})
+        return EXIT_OK
+    if not rows:
+        print("No Mobster simulators yet. `mobster sim prepare` creates one.")
+        return EXIT_OK
+    table = [("NAME", "STATE", "WEBDRIVERAGENT", "HELD BY", "UDID")]
+    for row in rows:
+        wda = row["wda_url"].split("//")[-1] if row["wda"] == "ready" else "stopped"
+        holder = row["holder"]
+        held = (f"{holder['client']} ({holder['session']}), {_since(holder['since'])}" if holder
+                else "a Mobster process" if row["in_use"] else "-")
+        table.append((row["name"], row["state"], wda, held, row["udid"]))
+    widths = [max(len(line[column]) for line in table) for column in range(len(table[0]) - 1)]
+    for line in table:
+        print("  ".join(cell.ljust(width) for cell, width in zip(line, widths)) + "  " + line[-1])
+    return EXIT_OK
+
+
+def _android(manager, args, as_json):
+    from ..android.emulator import EmulatorManager
+    droid = EmulatorManager(manager.data_dir)
+    if args.action == "boot":
+        lease = droid.acquire(args.avd)
+        target = lease.target
+        lease.release()  # the emulator stays up for the next run
+        print(f"Ready  {target.name} ({target.serial})")
+    elif args.action == "shutdown":
+        stopped = droid.shutdown(args.avd)
+        print("\n".join(f"Stopped {name}" for name in stopped) or "No Mobster emulators to stop.")
+    else:
+        rows = droid.devices()
+        if as_json:
+            _print_json({"devices": rows})
+        elif not rows:
+            print("No Android devices. `mobster sim android boot` starts an emulator.")
+        for row in rows if not as_json else ():
+            print(f"{row['name']:<24} {row['kind']:<9} {row['state']:<12} {'in use' if row['in_use'] else 'idle':<7} "
+                  f"{row['serial']}")
+    return EXIT_OK
+
+
+def _since(epoch):
+    minutes = max(0, int((time.time() - float(epoch or time.time())) // 60))
+    return f"{minutes} min" if minutes < 60 else f"{minutes // 60} h {minutes % 60} min"
+
+
+PHASES = (("create", "create"), ("boot", "boot"), ("configure", "settings"),
+          ("wda_build", "WebDriverAgent build"), ("wda_start", "WebDriverAgent start"))
+
+
+def _prepare(manager, args, as_json, end=lambda: None):
+    lease = manager.acquire(args.device, args.runtime)
+    try:
+        target, timing = lease.target, dict(lease.timing)
+    finally:
+        lease.release()
+    end()
+    if as_json:
+        _print_json({"udid": target.udid, "name": target.name, "device_type": target.device_type,
+                     "runtime": target.runtime, "wda_url": target.wda_url, "mjpeg_url": target.mjpeg_url,
+                     "xctestrun": target.xctestrun, "timing": timing})
+        return EXIT_OK
+    phases = [f"{label} {timing[key]:.1f} s" for key, label in PHASES if key in timing]
+    print(f"Ready  {target.name}")
+    print(f"  UDID            {target.udid}")
+    print(f"  WebDriverAgent  {target.wda_url} (MJPEG {target.mjpeg_url})")
+    print(f"  Took            {timing.get('total', 0):.1f} s" + (f": {', '.join(phases)}" if phases else
+                                                                     ", already up"))
+    return EXIT_OK