mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/devkit/nightly.py

@@ -0,0 +1,152 @@
+"""`mobster test nightly`: every check overnight on this Mac, and a morning report waiting for you."""
+
+import datetime
+import hashlib
+import json
+import os
+import plistlib
+import re
+import subprocess
+from pathlib import Path
+
+from . import DevError, agent_argv, self_argv
+
+LABEL = "dev.mobster.nightly"
+FOLDER = ".mobster/nightly"
+TIME = re.compile(r"([01]?\d|2[0-3]):([0-5]\d)")
+
+
+def label_for(root):
+    root = Path(root).resolve()
+    slug = re.sub(r"[^a-z0-9]+", "-", root.name.lower()).strip("-")[:30] or "project"
+    return f"{LABEL}.{slug}-{hashlib.sha256(str(root).encode()).hexdigest()[:8]}"
+
+
+# A per-user LaunchAgent, not a daemon: it reaches the person's simulators, Keychain and plugged-in iPhones.
+def plist_path(root, home=None):
+    return Path(home or Path.home()) / "Library" / "LaunchAgents" / f"{label_for(root)}.plist"
+
+
+def parse_time(text):
+    match = TIME.fullmatch(str(text or "").strip())
+    if not match:
+        raise DevError(f"--at {text} isn't a time.", "Give it as HH:MM on a 24-hour clock, such as 02:00.")
+    return int(match.group(1)), int(match.group(2))
+
+
+def turn_on(root, at, flags, *, home=None, run=None, uid=None):
+    """Write and load the LaunchAgent. Returns its plist path."""
+    hour, minute = parse_time(at)
+    root = Path(root).resolve()
+    argv, env = agent_argv()
+    path = plist_path(root, home)
+    (root / FOLDER).mkdir(parents=True, exist_ok=True)
+    data = {"Label": label_for(root), "ProgramArguments": [*argv, "test", "nightly", "run", *flags],
+            "WorkingDirectory": str(root), "StartCalendarInterval": {"Hour": hour, "Minute": minute},
+            "StandardOutPath": str(root / FOLDER / "launchd.log"),
+            "StandardErrorPath": str(root / FOLDER / "launchd.log"),
+            "ProcessType": "Background", "LowPriorityIO": True, "Nice": 5}
+    if env:
+        data["EnvironmentVariables"] = env
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(plistlib.dumps(data))
+    run = run or _launchctl
+    domain = f"gui/{os.getuid() if uid is None else uid}"
+    run(["launchctl", "bootout", domain, str(path)])
+    if run(["launchctl", "bootstrap", domain, str(path)]) != 0:
+        raise DevError("launchctl didn't load the nightly run.", f"Load it yourself: launchctl bootstrap {domain} "
+                                                                 f"{path}")
+    return path
+
+
+def turn_off(root, *, home=None, run=None, uid=None):
+    path = plist_path(root, home)
+    if not path.is_file():
+        return False
+    (run or _launchctl)(["launchctl", "bootout", f"gui/{os.getuid() if uid is None else uid}", str(path)])
+    path.unlink()
+    return True
+
+
+def _launchctl(argv):
+    try:
+        return subprocess.run(argv, capture_output=True, timeout=30).returncode
+    except (OSError, subprocess.SubprocessError):
+        return 1
+
+
+def status(root, *, home=None):
+    """{"on", "at", "flags", "last"}: the schedule and last night's latest.json."""
+    path = plist_path(root, home)
+    out = {"on": path.is_file(), "at": None, "flags": [], "last": None}
+    if path.is_file():
+        try:
+            data = plistlib.loads(path.read_bytes())
+            when = data.get("StartCalendarInterval") or {}
+            out["at"] = f"{int(when.get('Hour', 0)):02d}:{int(when.get('Minute', 0)):02d}"
+            arguments = data.get("ProgramArguments") or []
+            out["flags"] = arguments[arguments.index("run") + 1:] if "run" in arguments else []
+        except (ValueError, plistlib.InvalidFileException):
+            pass
+    try:
+        out["last"] = json.loads((Path(root) / FOLDER / "latest.json").read_text())
+    except (OSError, ValueError):
+        pass
+    return out
+
+
+def morning(doc, folder, date):
+    """morning.md: the verdict first, then each check that didn't pass with why and the command to run it again."""
+    from ..testkit.reports import counts_text
+    from ..verify.report import dots
+    summary = doc.get("summary") or {}
+    lines = [f"# Overnight checks, {date}", "", f"**{counts_text(summary)}**" + (
+        f" in {round((doc.get('durationMs') or 0) / 60000)} min" if doc.get("durationMs") else ""), ""]
+    bad = [(check, result) for check in doc.get("checks") or () for result in check.get("results") or ()
+           if result.get("status") != "passed" or result.get("flaky")]
+    for check, result in bad:
+        word = "flaky" if result.get("status") == "passed" else str(result.get("status")).replace("_", " ")
+        reason = (result.get("reason") or result.get("flakyReason") or {}).get("message") or ""
+        lines.append(f"- **{word}**: {check.get('name')} on {dots(result.get('device') or '')}"
+                     + (f". {reason}" if reason else ""))
+        if check.get("file"):
+            lines.append(f"  Run it again: `mobster test {check['file']}`")
+    if not bad:
+        lines.append("Every check passed.")
+    lines += ["", f"Report: {folder}/index.html"]
+    return "\n".join(lines) + "\n"
+
+
+def run_night(root, flags, *, runner=None, notifier=None, alert=None, today=None, environ=None):
+    """One night's run. Returns (exit code, morning.md's text)."""
+    environ = os.environ if environ is None else environ
+    root = Path(root).resolve()
+    date = (today or datetime.date.today()).isoformat()
+    folder = root / FOLDER / date
+    folder.mkdir(parents=True, exist_ok=True)
+    argv, env = self_argv()
+    argv = argv + ["test", "--video", "--json", "--html", str(folder), "--junit", str(folder / "junit.xml"), *flags]
+    if runner is None:
+        def runner(argv, cwd, env):
+            done = subprocess.run(argv, cwd=cwd, stdout=subprocess.PIPE, text=True, env=env)
+            return done.returncode, done.stdout
+    code, out = runner(argv, str(root), {**environ, **env})
+    try:
+        doc = json.loads(out.strip().splitlines()[-1])
+    except (ValueError, IndexError):
+        doc = {"summary": {}, "checks": [], "exitCode": code}
+    text = morning(doc, str(folder.relative_to(root)), date)
+    (folder / "morning.md").write_text(text, encoding="utf-8")
+    from ..testkit.reports import counts_text
+    headline = counts_text(doc.get("summary") or {}) or "couldn't run"
+    (root / FOLDER / "latest.json").write_text(json.dumps({"date": date, "exitCode": code, "headline": headline,
+                                                           "morning": str(folder / "morning.md")}, indent=1))
+    from .xcode import notify
+    (notifier or notify)(f"Overnight checks: {root.name}", headline)
+    if code != 0:
+        from .. import alerts
+        url = alerts.configured_url(environ)
+        if url:
+            (alert or alerts.deliver)(url, alerts.payload(f"Overnight checks: {root.name}",
+                                                          "failed" if code == 1 else "error"))
+    return code, text

mobile_agent/devkit/shots.py

@@ -0,0 +1,203 @@
+"""App Store screenshots from your real flows, as full-resolution PNGs in the folders `fastlane deliver` reads."""
+
+import json
+import plistlib
+import re
+import subprocess
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from ..sim import simctl
+
+# App Store Connect's screenshot sizes (Screenshot specifications, developer.apple.com/help/app-store-connect,
+# read 14 Oct 2026): the display class, the simulators that have it (newest first), and the portrait pixel sizes
+# Apple accepts for it. 6.9" is required for an iPhone app; 13" for an app that runs on iPad.
+SIZES = {
+    "6.9": ("iPhone 6.9-inch", ("iPhone 17 Pro Max", "iPhone 16 Pro Max", "iPhone 16 Plus"),
+            ((1320, 2868), (1290, 2796), (1260, 2736))),
+    "6.5": ("iPhone 6.5-inch", ("iPhone 14 Plus", "iPhone 11 Pro Max"), ((1284, 2778), (1242, 2688))),
+    "6.3": ("iPhone 6.3-inch", ("iPhone 17 Pro", "iPhone 17", "iPhone 16 Pro", "iPhone 16"),
+            ((1206, 2622), (1179, 2556))),
+    "13": ("iPad 13-inch", ("iPad Pro 13-inch (M5)", "iPad Pro 13-inch (M4)", "iPad Air 13-inch (M3)"),
+           ((2064, 2752), (2048, 2732))),
+}
+# The App Store's locale codes for an .lproj with a language only.
+LOCALES = {"en": "en-US", "de": "de-DE", "es": "es-ES", "fr": "fr-FR", "nl": "nl-NL", "pt": "pt-PT", "ar": "ar-SA",
+           "nb": "no", "zh-Hans": "zh-Hans", "zh-Hant": "zh-Hant", "zh_CN": "zh-Hans", "zh_TW": "zh-Hant"}
+STATUS_BAR = ("--time", "9:41", "--dataNetwork", "wifi", "--wifiMode", "active", "--wifiBars", "3",
+              "--cellularMode", "active", "--cellularBars", "4", "--batteryState", "charged", "--batteryLevel", "100")
+
+
+@dataclass(frozen=True)
+class Shot:
+    index: int
+    check: object        # verify.checks.Check
+    size: str
+    device: str
+    locale: str
+
+    @property
+    def name(self):
+        slug = re.sub(r"-+", "-", re.sub(r"[^a-z0-9]+", "-", self.check.name.lower())).strip("-")[:40] or "shot"
+        return f"{self.index:02d}_{self.size.replace('.', '')}_{slug}.png"
+
+
+def app_locales(app_path):
+    """The App Store locales a built .app ships: its .lproj folders (Base left out), else CFBundleLocalizations."""
+    found = []
+    folder = Path(app_path or "")
+    if folder.is_dir():
+        found = sorted(p.stem for p in folder.glob("*.lproj") if p.stem not in ("Base",))
+        if not found:
+            try:
+                with open(folder / "Info.plist", "rb") as handle:
+                    found = list(plistlib.load(handle).get("CFBundleLocalizations") or [])
+            except (OSError, ValueError, plistlib.InvalidFileException):
+                found = []
+    return [asc_locale(item) for item in found] or ["en-US"]
+
+
+def asc_locale(code):
+    code = str(code).replace("_", "-")
+    if code in LOCALES:
+        return LOCALES[code]
+    return code
+
+
+def launch_args(locale):
+    """``-AppleLanguages (de-DE) -AppleLocale de_DE``: the app runs in that language, the rest of iOS unchanged."""
+    language = locale if locale != "no" else "nb"
+    region = locale.replace("-", "_") if "-" in locale and not locale.startswith("zh-") else language
+    return ("-AppleLanguages", f"({language})", "-AppleLocale", region)
+
+
+def is_ipad_app(app_path):
+    try:
+        with open(Path(app_path) / "Info.plist", "rb") as handle:
+            family = plistlib.load(handle).get("UIDeviceFamily") or []
+    except (OSError, ValueError, plistlib.InvalidFileException, TypeError):
+        return False
+    return 2 in family
+
+
+def available_device_types(run=None):
+    """Names of the simulator device types this Mac's Xcode has."""
+    run = run or (lambda argv: subprocess.run(argv, capture_output=True, text=True, timeout=60).stdout)
+    try:
+        data = json.loads(run(["xcrun", "simctl", "list", "devicetypes", "-j"]))
+    except (ValueError, OSError, subprocess.SubprocessError):
+        return []
+    return [item.get("name") for item in data.get("devicetypes") or () if item.get("name")]
+
+
+def device_for(size, available):
+    """The first simulator of ``size`` this Mac has, or None."""
+    for name in SIZES[size][1]:
+        if name in available:
+            return name
+    return None
+
+
+def plan_shots(checks, *, sizes, locales, available):
+    """Every (check × size × locale) as Shots, and the notes on sizes this Mac can't make."""
+    shots, notes = [], []
+    for size in sizes:
+        if size not in SIZES:
+            raise ValueError(f"{size} isn't a screenshot size Mobster knows: {', '.join(SIZES)}")
+        device = device_for(size, available)
+        if device is None:
+            notes.append(f"No {SIZES[size][0]} simulator on this Mac ({', '.join(SIZES[size][1][:2])}), so no "
+                         f"{size}\" shots. Add one in Xcode › Settings › Components.")
+            continue
+        for locale in locales:
+            for index, check in enumerate(checks, 1):
+                shots.append(Shot(index, check, size, device, locale))
+    return shots, notes
+
+
+class StatusBarAndShot:
+    """A simulator manager that sets the status bar to 9:41 on each lease and shoots the screen as it goes back."""
+
+    def __init__(self, manager, path, *, run=simctl.run):
+        self._manager, self.path = manager, Path(path)
+        self._run = run
+        self.taken = False
+
+    def __getattr__(self, name):
+        return getattr(self._manager, name)
+
+    def acquire(self, *args, **kwargs):
+        lease = self._manager.acquire(*args, **kwargs)
+        self._run(["xcrun", "simctl", "status_bar", lease.target.udid, "override", *STATUS_BAR])
+        return _ShotLease(self, lease)
+
+
+class _ShotLease:
+    def __init__(self, owner, lease):
+        self._owner, self._lease, self.target = owner, lease, lease.target
+
+    def __getattr__(self, name):
+        return getattr(self._lease, name)
+
+    def __enter__(self):
+        return self.target
+
+    def __exit__(self, *exc):
+        self.release()
+
+    def release(self):
+        owner, udid = self._owner, self.target.udid
+        # the shot is taken as the lease goes back: the run's verdict is decided by then
+        if not owner.taken:
+            owner.path.parent.mkdir(parents=True, exist_ok=True)
+            owner.taken = simctl.screenshot(udid, owner.path, timeout=60, runner=owner._run).ok
+            owner._run(["xcrun", "simctl", "status_bar", udid, "clear"])
+        self._lease.release()
+
+
+def png_size(path):
+    data = Path(path).read_bytes()[:24]
+    if data[:8] != b"\x89PNG\r\n\x1a\n":
+        return None
+    return int.from_bytes(data[16:20], "big"), int.from_bytes(data[20:24], "big")
+
+
+def take(shots, *, out, runs_dir, manager=None, verify=None, progress=None):
+    """Run every shot. Returns {"shots": [...], "ok": bool} and writes screenshots.json in ``out``."""
+    from ..verify.runner import verify as verify_run
+    verify = verify or verify_run
+    progress = progress or (lambda line: None)
+    if manager is None:
+        from ..sim import SimulatorManager
+        manager = SimulatorManager(progress=progress)
+    out = Path(out)
+    rows = []
+    for number, shot in enumerate(shots, 1):
+        target = out / shot.locale / shot.name
+        target.unlink(missing_ok=True)
+        check = replace(shot.check, device=shot.device, runtime=None,
+                        launch_args=tuple(shot.check.launch_args) + launch_args(shot.locale))
+        progress(f"[{number}/{len(shots)}] {shot.check.name}: {shot.device}, {shot.locale}")
+        wrapped = StatusBarAndShot(manager, target)
+        try:
+            result = verify(check, runs_dir=runs_dir, manager=wrapped)
+        except KeyboardInterrupt:
+            raise
+        except Exception as error:  # one shot's failure never stops the rest
+            result = {"verdict": "couldnt_run", "summary": f"{type(error).__name__}: {error}"}
+        verdict = result.get("verdict") or "couldnt_run"
+        if verdict == "couldnt_run" and target.is_file():
+            target.unlink()
+        size = png_size(target) if target.is_file() else None
+        accepted = SIZES[shot.size][2]
+        row = {"check": shot.check.name, "size": shot.size, "device": shot.device, "locale": shot.locale,
+               "verdict": verdict, "file": str(target.relative_to(out)) if target.is_file() else None,
+               "pixels": list(size) if size else None,
+               "fits": bool(size and (tuple(size) in accepted or (size[1], size[0]) in accepted)),
+               "summary": result.get("summary"), "run": result.get("run_id")}
+        rows.append(row)
+    doc = {"schema": "mobster.screenshots/1", "shots": rows,
+           "ok": bool(rows) and all(row["file"] and row["fits"] for row in rows)}
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "screenshots.json").write_text(json.dumps(doc, indent=1, ensure_ascii=False) + "\n", encoding="utf-8")
+    return doc

mobile_agent/devkit/testflight.py

@@ -0,0 +1,155 @@
+"""TestFlight builds for a project: list them, choose one, install it on an iPhone, and record the install."""
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .. import env_file
+from ..verify.runs import ensure_gitignore
+from . import DevError, asc
+
+RECORD_DIR = ("runs", "testflight")
+READY = frozenset({"IN_BETA_TESTING", "READY_FOR_BETA_TESTING"})
+WHY = {"PROCESSING": "Apple is still processing it", "PROCESSING_EXCEPTION": "Apple couldn't process it",
+       "MISSING_EXPORT_COMPLIANCE": "it needs export compliance answered in App Store Connect",
+       "IN_EXPORT_COMPLIANCE_REVIEW": "it is in export compliance review",
+       "WAITING_FOR_BETA_REVIEW": "it is waiting for beta review", "IN_BETA_REVIEW": "it is in beta review",
+       "BETA_REJECTED": "beta review rejected it", "EXPIRED": "it expired"}
+BUNDLE = re.compile(r"[A-Za-z0-9][A-Za-z0-9.\-]{0,200}")
+
+
+def check_row(row):
+    """``row`` (asc.build_row) with ``installable`` and, when it isn't, ``why`` in a sentence."""
+    states = [state for state in (row.get("internal"), row.get("external")) if state]
+    if row.get("expired") or "EXPIRED" in states:
+        why = "it expired (TestFlight builds last 90 days)"
+    elif row.get("processing") != "VALID":
+        why = WHY.get(row.get("processing")) or "Apple hasn't finished processing it"
+    elif not any(state in READY for state in states):
+        why = next((WHY[state] for state in states if state in WHY), "no tester group has it")
+    else:
+        return {**row, "installable": True, "why": ""}
+    return {**row, "installable": False, "why": why}
+
+
+def builds(client, bundle, *, limit=20):
+    """(app, rows): the app and its builds, newest first."""
+    app = client.app(bundle)
+    return app, [check_row(row) for row in client.builds(app["id"], limit=limit)]
+
+
+def choose(rows, build=None, version=None):
+    if build is None and version is None:
+        for row in rows:
+            if row["installable"]:
+                return row
+        raise DevError("No build of this app can be installed from TestFlight right now."
+                       + (f" The newest, {_name(rows[0])}, {rows[0]['why']}." if rows else " It has no builds."),
+                       "Upload a build, or add it to a tester group in App Store Connect." if not rows else
+                       "Fix that in App Store Connect, or upload a new build.")
+    found = [row for row in rows if (build is None or str(row["build"]) == str(build))
+             and (version is None or row["version"] == version)]
+    if not found:
+        raise DevError(f"TestFlight has no build {version + ' ' if version else ''}{build or ''}".strip()
+                       + f" in the newest {len(rows)} builds.", "Run `mobster testflight list` to see them.")
+    row = found[0]
+    if not row["installable"]:
+        raise DevError(f"Build {_name(row)} can't be installed: {row['why']}.",
+                       "Pick another build, or fix it in App Store Connect.")
+    return row
+
+
+def _name(row):
+    return f"{row['version'] or '?'} ({row['build']})"
+
+
+# -- the record ----------------------------------------------------------------------------------------------------
+
+def _record_path(root, bundle):
+    if not BUNDLE.fullmatch(bundle or ""):
+        raise DevError(f"{bundle!r} isn't a bundle ID.", "Pass the app's bundle ID, such as com.example.habits.")
+    return Path(root) / ".mobster" / Path(*RECORD_DIR) / f"{bundle}.json"
+
+
+def read_record(root, bundle):
+    """The record of the last install of ``bundle`` in this project, or None."""
+    try:
+        data = json.loads(_record_path(root, bundle).read_text())
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError):
+        raise DevError("The previous TestFlight install record cannot be read.",
+                       "Check the iPhone and reconcile the record before installing again.") from None
+    if not isinstance(data, dict) or data.get("status") not in {"installing", "installed"}:
+        raise DevError("The previous TestFlight install record is invalid.",
+                       "Check the iPhone and reconcile the record before installing again.")
+    return data
+
+
+def _write_record(root, bundle, data):
+    path = _record_path(root, bundle)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    ensure_gitignore(path.parent.parent)
+    temp = path.with_suffix(".tmp")
+    with env_file.open_private(temp, "w") as handle:
+        handle.write(json.dumps(data, sort_keys=True))
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temp, path)
+    descriptor = os.open(path.parent, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def recorded_build(root, bundle, *, devices=()):
+    try:
+        data = read_record(root, bundle)
+    except DevError:
+        return None  # metadata cannot prevent the suite from writing its actual verdict
+    # an install whose outcome is unknown names no build: it may not be on the phone
+    if (not data or data.get("status") != "installed"
+            or (devices and not set(devices).intersection(data.get("devices") or ()))):
+        return None
+    return {key: data.get(key) for key in ("bundleId", "version", "build", "installedAt")}
+
+
+# -- the install ---------------------------------------------------------------------------------------------------
+
+def install(client, record, wda, bundle, *, root, build=None, version=None, progress=None, now=None, **options):
+    with env_file.writer(_record_path(root, bundle)):
+        app, rows = builds(client, bundle, limit=50)
+        row = choose(rows, build, version)
+        newest = next(item for item in rows if item["installable"])
+        if row["id"] != newest["id"]:
+            raise DevError(
+                f"TestFlight installs the newest build, {_name(newest)}, from the app's page, and you asked for "
+                f"{_name(row)}. Mobster won't pick from Previous Builds for you.",
+                f"On the iPhone, open TestFlight, tap {app['name']}, tap Previous Builds, tap {_name(row)}, then tap "
+                f"Install. Then run `mobster test --device NAME --testflight {bundle}`.")
+        earlier = read_record(root, bundle)
+        unknown = bool(earlier) and earlier.get("status") == "installing"
+        if unknown and earlier.get("buildId") != row["id"]:
+            raise DevError("An earlier TestFlight install has an unknown outcome.",
+                           "Check that build on the iPhone before requesting a different build.")
+        stamp = (now or (lambda: datetime.now(timezone.utc)))().strftime("%Y-%m-%dT%H:%M:%SZ")
+        entry = {"bundleId": bundle, "version": row["version"], "build": row["build"], "buildId": row["id"],
+                 "startedAt": stamp, "devices": [value for value in (record.get("id"), record.get("name")) if value]}
+        _write_record(root, bundle, {**entry, "status": "installing"})  # before the first tap, so a crash is "unknown"
+        try:
+            result = asc.testflight_install(record, wda, app["id"], progress=progress, tap=not unknown,
+                                            expected=(row["version"], row["build"]), **options)
+        except asc.UnknownOutcome:
+            raise  # the record stays "installing"
+        except DevError:  # no tap went out (terms, no button, a simulator, or watch-only): the old record stands
+            if earlier:
+                _write_record(root, bundle, earlier)
+            else:
+                _record_path(root, bundle).unlink(missing_ok=True)
+            raise
+        finished = {**entry, "status": "installed", "installedAt": stamp}
+        _write_record(root, bundle, finished)
+        return {"result": result, "row": row, "app": app, "record": finished}

mobile_agent/devkit/testflight_cli.py

@@ -0,0 +1,127 @@
+"""`mobster testflight`: your app's TestFlight builds, listed and installed on an iPhone."""
+
+import json
+import sys
+from pathlib import Path
+
+from . import DevError, main, say, subcommands
+
+
+def add_arguments(parser, helpers):
+    add = subcommands(parser, "testflight_command")
+
+    key = add("key", help="add, show or remove this project's App Store Connect API key (kept in the Keychain)",
+              description="Keep an App Store Connect API key for this project in your login Keychain, readable only "
+                          "by Mobster's own programs, and never printed. Make one in App Store Connect › Users and "
+                          "Access › Integrations. The key is this project's: a folder with .mobster/ above the "
+                          "current one, or the current folder. --shared keeps it for every project instead.")
+    key.add_argument("action", choices=("add", "show", "remove"), help="add, show or remove")
+    key.add_argument("--key-id", metavar="ID", help="with add: the key's Key ID")
+    key.add_argument("--issuer-id", metavar="UUID", help="with add: the Issuer ID (a team key; none for an "
+                                                        "individual key)")
+    key.add_argument("--p8", metavar="FILE", help="with add: the AuthKey_<Key ID>.p8 file Apple gave you")
+    key.add_argument("--shared", action="store_true", help="the key every project uses, not this project's")
+
+    listing = add("list", help="list the app's builds and whether TestFlight can install each, newest first")
+    listing.add_argument("--app", required=True, metavar="BUNDLE", help="the app's bundle ID")
+    listing.add_argument("--limit", type=int, default=10, metavar="N", help="how many (default: 10)")
+    listing.add_argument("--json", action="store_true", help="print JSON")
+
+    install = add("install", help="install a TestFlight build on your iPhone through the TestFlight app",
+                  description="Install the newest installable build, or the one --build names, on your iPhone: "
+                              "Mobster opens the app's page in TestFlight and taps Install or Update, then waits "
+                              "for Open. You must be a tester of the app. Mobster never accepts TestFlight's terms "
+                              "for you, never picks from Previous Builds (it prints the taps instead), and after a "
+                              "tap it can't confirm it never taps again.",
+                  epilog="after it: mobster test --device NAME --testflight BUNDLE, whose report names the build")
+    install.add_argument("--app", required=True, metavar="BUNDLE", help="the app's bundle ID")
+    install.add_argument("--build", metavar="N", help="the build number (default: the newest installable)")
+    install.add_argument("--version", metavar="V", help="the version the build belongs to, such as 1.4.2")
+    install.add_argument("--device", metavar="NAME", help="the iPhone (default: your iPhone)")
+    install.add_argument("--timeout", type=int, default=600, metavar="SECONDS",
+                         help="how long to wait for TestFlight (default: 600)")
+    install.add_argument("--json", action="store_true", help="print JSON")
+
+
+def run(args, *, client=None, store=None, devices=None, wda=None, cwd=None):
+    handlers = {"key": _key, "list": _list, "install": _install}
+    return main("testflight", handlers, args, client=client, store=store, devices=devices, wda=wda,
+                cwd=Path(cwd or Path.cwd()))
+
+
+def project_of(cwd):
+    from ..verify.checks import project_root
+    return Path(project_root(Path(cwd))).resolve()
+
+
+def _client(client, store, root):
+    if client is not None:
+        return client
+    from . import asc
+    return asc.Client(asc.load_key(store=store, project=root))
+
+
+def _key(args, *, store, cwd, **_):
+    from . import asc
+    root = None if args.shared else project_of(cwd)
+    if args.action == "add":
+        if not args.key_id or not args.p8:
+            raise DevError("key add needs --key-id and --p8 (and --issuer-id for a team key).")
+        try:
+            text = Path(args.p8).expanduser().read_text()
+        except OSError:
+            raise DevError(f"Mobster can't read {args.p8}.", "Pass the path of the .p8 file.") from None
+        key = asc.save_key(args.key_id, args.issuer_id, text, store=store, project=root)
+        say(f"Saved the {key.public()['kind']} key {key.key_id} in your Keychain for "
+            f"{'every project' if root is None else root.name}. You can delete {Path(args.p8).name} now, or keep "
+            "it somewhere safe.")
+    elif args.action == "remove":
+        asc.remove_key(store=store, project=root)
+        say("Removed the key from your Keychain.")
+    else:
+        info = asc.load_key(store=store, project=root).public()
+        say(f"Key ID     {info['keyId']}\nIssuer ID  {info['issuerId'] or 'none (an individual key)'}\n"
+            f"From       {info['source']}")
+    return 0
+
+
+def _list(args, *, client, store, cwd, **_):
+    from . import testflight
+    app, rows = testflight.builds(_client(client, store, project_of(cwd)), args.app,
+                                  limit=max(1, min(args.limit, 200)))
+    if args.json:
+        say(json.dumps({"app": app, "builds": rows}, ensure_ascii=False))
+        return 0
+    lines = [f"{app['name']} ({args.app}), newest first:"]
+    for row in rows:
+        when = str(row["uploaded"] or "")[:16].replace("T", " ")
+        lines.append(f"  {row['version'] or '?'} ({row['build']})  {when}  "
+                     + ("can install" if row["installable"] else f"can't install: {row['why']}"))
+    if not rows:
+        lines.append("  no builds yet")
+    say("\n".join(lines))
+    return 0
+
+
+def _install(args, *, client, store, devices, wda, cwd, **_):
+    from . import testflight
+    if devices is None or wda is None:
+        from ..phone_io import choose_device
+        from ..phone_io import wda as phone_wda
+        devices, wda = devices or choose_device, wda or phone_wda
+    root = project_of(cwd)
+    record = devices(args.device)
+    done = testflight.install(_client(client, store, root), record, wda, args.app, root=root, build=args.build,
+                              version=args.version, timeout=max(30, min(args.timeout, 3600)),
+                              progress=lambda line: say(line, sys.stderr))
+    row = done["row"]
+    name = f"{row['version'] or '?'} ({row['build']})"
+    if args.json:
+        say(json.dumps({"device": record.get("name"), "app": args.app, "result": done["result"],
+                        "build": {"version": row["version"], "build": row["build"]}}))
+    elif done["result"] == "already":
+        say(f"{args.app} {name} is already on {record.get('name')}: TestFlight says Open.")
+    else:
+        say(f"Installed {args.app} {name} from TestFlight on {record.get('name')}. Test it with: "
+            f"mobster test --device \"{record.get('name')}\" --testflight {args.app}")
+    return 0