mobster-cli 0.4.3__py3-none-any.whl

mobile_agent/team_signing/writes.py

@@ -0,0 +1,268 @@
+"""The three App Store Connect writes that sign the helper, as a card the person approves.
+
+``plan`` reads the team (its iPhones, the helper's App ID, its development certificates and Mobster's profiles) and
+returns a ``Card``: only the writes still needed, each with the exact body that is sent. ``execute`` sends them, after
+the person approved the card's digest, in order, through ``asc.Client.write`` (which sends nothing the approval
+doesn't name, and journals first). Run again after a failure: what Apple already has is read, not written.
+
+The writes, and nothing else:
+
+1. ``register_device``: an iPhone's UDID and name, once per phone and team.
+2. ``create_certificate``: a development certificate from a certificate signing request made on this Mac. The private
+   key never leaves it.
+3. ``create_profile``: one development profile for the helper's App ID, listing the certificate and every phone.
+   Apple's API has no profile update, so adding a phone makes a new profile that lists all of them; Mobster doesn't
+   delete the old one.
+
+The App ID itself is not one of them. It must exist on the team (Xcode makes it on a first build; the portal's
+Identifiers page does too), and ``plan`` says so when it doesn't.
+"""
+
+import hashlib
+from dataclasses import dataclass, field
+
+from ..devkit import DevError, asc
+
+PROFILE_PREFIX = "Mobster helper"
+CERTIFICATE_TYPE = "DEVELOPMENT"
+PROFILE_TYPE = "IOS_APP_DEVELOPMENT"
+
+
+def ref(name):
+    return {asc.REF: name}
+
+
+def device_body(name, udid):
+    return {"data": {"type": "devices", "attributes": {"name": name, "platform": "IOS", "udid": udid}}}
+
+
+def certificate_body(csr_pem):
+    return {
+        "data": {"type": "certificates", "attributes": {"certificateType": CERTIFICATE_TYPE, "csrContent": csr_pem}}
+    }
+
+
+def profile_body(name, bundle_id, certificates, devices):
+    """``certificates`` and ``devices`` are ids, or ref(...) for ones the same run makes."""
+
+    def many(kind, ids):
+        return {"data": [{"type": kind, "id": item} for item in ids]}
+
+    return {
+        "data": {
+            "type": "profiles",
+            "attributes": {"name": name, "profileType": PROFILE_TYPE},
+            "relationships": {
+                "bundleId": {"data": {"type": "bundleIds", "id": bundle_id}},
+                "certificates": many("certificates", certificates),
+                "devices": many("devices", devices),
+            },
+        }
+    }
+
+
+@dataclass(frozen=True)
+class Step:
+    write: str  # an asc.WRITES name
+    produces: str  # what later steps call its answer: "device:<udid>", "certificate", "profile"
+    title: str  # the card's line for it
+    template: dict  # the exact body, with {"$ref": produces-of-an-earlier-step} where Apple's id goes
+    summary: dict  # what the ledger records about it (never the CSR)
+    lines: tuple  # (label, value) pairs the card shows
+
+
+@dataclass(frozen=True)
+class Card:
+    bundle: dict  # the helper's App ID on the team: {id, identifier, name}
+    steps: tuple  # of Step, in the order they are sent
+    certificate_id: str = ""  # the certificate the profile lists when no step makes one
+    profile: dict = field(default_factory=dict)  # an existing profile that already does the job, if any
+    devices: dict = field(default_factory=dict)  # UDID -> Apple's id, for the phones already registered
+
+    def approval(self):
+        return asc.Approval([(step.write, step.template) for step in self.steps])
+
+    @property
+    def digest(self):
+        return self.approval().digest
+
+    @property
+    def needed(self):
+        return bool(self.steps)
+
+    def public(self, key=None):
+        """What the approval card shows, as JSON: the exact request of each write. No token, key or secret."""
+
+        def shown(value):
+            if isinstance(value, dict):
+                if set(value) == {asc.REF}:
+                    return f"<the id Apple gives {value[asc.REF].replace(':', ' ')}>"
+                return {k: shown(v) for k, v in value.items()}
+            if isinstance(value, list):
+                return [shown(item) for item in value]
+            return value
+
+        return {
+            "digest": self.digest,
+            "needed": self.needed,
+            "key": key,
+            "bundle": self.bundle,
+            "steps": [
+                {
+                    "number": number,
+                    "write": step.write,
+                    "title": step.title,
+                    "method": "POST",
+                    "url": asc.API + asc.WRITES[step.write][0],
+                    "lines": [{"label": label, "value": value} for label, value in step.lines],
+                    "body": shown(step.template),
+                }
+                for number, step in enumerate(self.steps, 1)
+            ],
+        }
+
+
+def canonical_ids(*parts):
+    return asc.canonical(list(parts))
+
+
+def profile_prefix(bundle_identifier, base=PROFILE_PREFIX):
+    return f"{base} {bundle_identifier} "
+
+
+def plan(client, *, bundle_identifier, phones, csr_pem=None, certificate_serial=None, stamp, base=PROFILE_PREFIX):
+    """The card for these ``phones`` ([{name, udid}]) on this team.
+
+    ``csr_pem`` is the certificate signing request made on this Mac (or a function that makes it), needed only when no
+    certificate is. ``certificate_serial``
+    is the serial of the certificate Mobster made here before, if any: it is reused while Apple still lists it.
+    ``stamp`` ("20261018") starts a new profile's name, and ``base`` starts every name (a test uses its own,
+    so it never meets the real helper's profiles). DevError when the App ID, a phone's status or the request is
+    wrong."""
+    bundle = client.bundle_id(bundle_identifier)
+    if bundle is None:
+        # Xcode keeps a wildcard App ID ("XC Wildcard") for a team that has built an app. A profile for it covers any
+        # bundle id, the helper's included.
+        bundle = client.bundle_id("*")
+    if bundle is None:
+        raise DevError(
+            f"Your team has no App ID for {bundle_identifier}, and Mobster doesn't register App IDs.",
+            "Open developer.apple.com › Certificates, Identifiers & Profiles › Identifiers, add an "
+            f"explicit iOS App ID {bundle_identifier}, then try again.",
+        )
+    registered = {item["udid"]: item for item in client.devices()}
+    steps, devices = [], {}
+    for phone in phones:
+        udid, name = phone["udid"], phone["name"]
+        known = registered.get(udid)
+        if known and known["status"] != "ENABLED":
+            raise DevError(
+                f"“{known['name']}” is registered on your team and disabled.",
+                "Enable it in developer.apple.com › Certificates, Identifiers & Profiles › Devices.",
+            )
+        if known:
+            devices[udid] = known["id"]
+            continue
+        steps.append(
+            Step(
+                "register_device",
+                f"device:{udid}",
+                f"Register “{name}” with your team",
+                device_body(name, udid),
+                {"name": name, "udid": udid},
+                (("Name", name), ("UDID", udid), ("Platform", "iOS")),
+            )
+        )
+    certificates = {item["serial"]: item for item in client.development_certificates()}
+    have = certificates.get(certificate_serial) if certificate_serial else None
+    certificate_id = have["id"] if have else ""
+    if not have:
+        csr_pem = csr_pem() if callable(csr_pem) else csr_pem
+        if not csr_pem:
+            raise DevError("Mobster needs a certificate signing request to ask for a certificate.")
+        digest = hashlib.sha256(csr_pem.encode()).hexdigest()[:16]
+        steps.append(
+            Step(
+                "create_certificate",
+                "certificate",
+                "Create a development certificate",
+                certificate_body(csr_pem),
+                {"csr_sha256": digest},
+                (
+                    ("Type", CERTIFICATE_TYPE),
+                    ("Key", "made on this Mac, never leaves it"),
+                    ("Request", f"sha256 {digest}"),
+                ),
+            )
+        )
+    existing = [
+        row
+        for row in client.development_profiles(profile_prefix(bundle_identifier, base))
+        if row["bundle"] == bundle["id"]
+    ]
+    members = [devices.get(phone["udid"]) or ref(f"device:{phone['udid']}") for phone in phones]
+    if not steps:
+        known = set(members)
+        reusable = next(
+            (row for row in existing if certificate_id in row["certificates"] and known <= set(row["devices"])), None
+        )
+        if reusable:
+            return Card(bundle, (), certificate_id, reusable, devices)
+    # A new profile keeps every phone an earlier Mobster profile for this App ID listed (another Mac's, a phone
+    # Mobster no longer manages), so adding a phone never drops one.
+    kept = sorted(
+        {device for row in existing for device in row["devices"]} - {i for i in members if isinstance(i, str)}
+    )
+    # The name is the same for the same card on the same day (a card and its approval run apart), and differs when the
+    # phones or the certificate do.
+    fingerprint = hashlib.sha256(
+        canonical_ids(
+            sorted(phone["udid"] for phone in phones),
+            certificate_id or hashlib.sha256((csr_pem or "").encode()).hexdigest(),
+        ).encode()
+    ).hexdigest()[:6]
+    name = f"{profile_prefix(bundle_identifier, base)}{stamp}-{fingerprint}"
+    listed = [*members, *kept]
+    steps.append(
+        Step(
+            "create_profile",
+            "profile",
+            "Create a development profile for Mobster's helper",
+            profile_body(name, bundle["id"], [certificate_id or ref("certificate")], listed),
+            {"name": name, "bundle": bundle_identifier, "phones": len(listed)},
+            (
+                ("Name", name),
+                ("App ID", bundle_identifier),
+                ("Type", "iOS App Development"),
+                ("Lists", f"{len(listed)} iPhone{'s' if len(listed) != 1 else ''} and the certificate"),
+            ),
+        )
+    )
+    return Card(bundle, tuple(steps), certificate_id, {}, devices)
+
+
+def _render(template, answers):
+    if isinstance(template, dict):
+        if set(template) == {asc.REF}:
+            return answers[template[asc.REF]]["id"]
+        return {key: _render(value, answers) for key, value in template.items()}
+    if isinstance(template, list):
+        return [_render(item, answers) for item in template]
+    return template
+
+
+def execute(client, card, approved, ledger, on_answer=None):
+    """Send the card's writes, in order. ``approved`` is the digest the person approved: it must be this card's.
+    Returns the answers by what each step produces ({"certificate": {id, attributes}, ...}). ``on_answer(step, answer)``
+    runs right after each write, to keep what Apple handed back (the certificate) before anything else can fail.
+    Stops at the first failure; the ones already made stay made, and a later ``plan`` sees them."""
+    if approved != card.digest:
+        raise DevError("The card changed after you approved it, so Mobster sent nothing.", "Look at it again.")
+    approval, answers = card.approval(), {}
+    for step in card.steps:
+        answers[step.produces] = client.write(
+            step.write, _render(step.template, answers), approval=approval, ledger=ledger, summary=step.summary
+        )
+        if on_answer is not None:
+            on_answer(step, answers[step.produces])
+    return answers

mobile_agent/terminal_image.py

@@ -0,0 +1,81 @@
+"""`mobster screen`: the phone's screen in the terminal, from WDA's sessionless GET /screenshot (nothing is tapped)."""
+
+import base64
+import io
+import os
+import sys
+
+
+def protocol(env=None):
+    """"kitty", "iterm" or "blocks" for the terminal described by ``env``."""
+    env = os.environ if env is None else env
+    term, program = env.get("TERM", ""), env.get("TERM_PROGRAM", "")
+    if env.get("KITTY_WINDOW_ID") or term == "xterm-kitty" or program.lower() == "ghostty" or term == "xterm-ghostty":
+        return "kitty"
+    if program in {"iTerm.app", "WezTerm"} or env.get("LC_TERMINAL") == "iTerm2":
+        return "iterm"
+    return "blocks"
+
+
+def kitty(png, columns):
+    """Kitty graphics protocol: base64 PNG in 4096-byte chunks, scaled to ``columns`` cells wide."""
+    data = base64.b64encode(png).decode()
+    chunks = [data[i:i + 4096] for i in range(0, len(data), 4096)] or [""]
+    out = []
+    for index, chunk in enumerate(chunks):
+        more = 1 if index < len(chunks) - 1 else 0
+        head = f"a=T,f=100,c={columns},q=2,m={more}" if index == 0 else f"m={more}"
+        out.append(f"\033_G{head};{chunk}\033\\")
+    return "".join(out) + "\n"
+
+
+def iterm(png, columns):
+    data = base64.b64encode(png).decode()
+    return f"\033]1337;File=inline=1;size={len(png)};width={columns};preserveAspectRatio=1:{data}\a\n"
+
+
+def blocks(png, columns):
+    """Half-block characters with 24-bit color, ``columns`` wide."""
+    from PIL import Image
+    image = Image.open(io.BytesIO(png)).convert("RGB")
+    width, height = image.size
+    rows = max(2, round(height * columns / width))
+    rows += rows % 2
+    image = image.resize((columns, rows), Image.LANCZOS)
+    pixels = image.load()
+    lines = []
+    for y in range(0, rows, 2):
+        cells = []
+        for x in range(columns):
+            top, bottom = pixels[x, y], pixels[x, y + 1]
+            cells.append(f"\033[38;2;{top[0]};{top[1]};{top[2]}m\033[48;2;{bottom[0]};{bottom[1]};{bottom[2]}m▀")
+        lines.append("".join(cells) + "\033[0m")
+    return "\n".join(lines) + "\n"
+
+
+def show_screen(wda_url, out=None, width=None, stream=None):
+    from .transport import wda_screenshot
+    stream = stream or sys.stdout
+    image = wda_screenshot(wda_url, timeout=5)
+    if image is None:
+        print(f"mobster: no screen from WebDriverAgent at {wda_url}. Is it running? (`mobster doctor`)",
+              file=sys.stderr)
+        return 3
+    png = base64.b64decode(image.split(",", 1)[1])
+    if out is not None:
+        out.write_bytes(png)
+        print(str(out), file=stream)
+        return 0
+    if not stream.isatty():
+        print("mobster: stdout is not a terminal; pass --out FILE to save the PNG.", file=sys.stderr)
+        return 2
+    try:
+        columns = os.get_terminal_size().columns
+    except OSError:
+        columns = 80
+    kind = protocol()
+    cells = width or (min(40, columns - 2) if kind != "blocks" else min(36, columns - 2))
+    render = {"kitty": kitty, "iterm": iterm, "blocks": blocks}[kind]
+    stream.write(render(png, cells))
+    stream.flush()
+    return 0

mobile_agent/testkit/__init__.py

@@ -0,0 +1 @@
+"""Track `testing`: `mobster test` for app developers, on top of verify (SPEC §3.8)."""

mobile_agent/testkit/a11y_baseline.py

@@ -0,0 +1,132 @@
+"""The project's accessibility baseline (.mobster/a11y-baseline.json), so CI fails only on new findings."""
+
+import fcntl
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from ..paths import write_text_atomic
+from .input_files import read_bytes
+
+SCHEMA = "mobster.a11y-baseline/1"
+FILE = "a11y-baseline.json"
+MAX_BYTES = 1_000_000
+
+
+class BaselineError(Exception):
+    """The baseline file can't be used: one sentence that says what to do."""
+
+
+def path(root):
+    return Path(root) / ".mobster" / FILE
+
+
+def snapshot(root):
+    """The old bytes, even when their JSON is malformed. A refresh must not overwrite a changed file."""
+    file = path(root)
+    if not file.exists() and not file.is_symlink():
+        return "missing"
+    try:
+        return hashlib.sha256(read_bytes(file, MAX_BYTES)).hexdigest()
+    except (OSError, ValueError):
+        raise BaselineError(f".mobster/{FILE} cannot be safely read for replacement. Fix the file first.") from None
+
+
+def refresh_error(doc, entries):
+    """A replacement needs complete observations from every requested accessibility cell."""
+    if doc.get("stopped") or doc.get("stopReason"):
+        return "The suite stopped before the accessibility baseline could be updated."
+    rows = doc.get("checks") or ()
+    if len(rows) != len(entries):
+        return "The suite did not report every check needed for the accessibility baseline."
+    audited = 0
+    for entry, row in zip(entries, rows):
+        cells = row.get("results") or ()
+        if not cells or any(cell.get("status") in ("couldnt_run", "needs_review") for cell in cells):
+            return "A check could not complete, so the accessibility baseline was not updated."
+        check = entry.check
+        if check is None:
+            return "A saved check could not be read, so the accessibility baseline was not updated."
+        if check.a11y or "a11y" in check.audit:
+            audited += len(cells)
+            for cell in cells:
+                if cell.get("status") == "failed" and not (
+                        (cell.get("reason") or {}).get("class") == "finding" and
+                        any(item.get("audit") == "a11y" and item.get("level") == "fail"
+                            for item in cell.get("findings") or () if isinstance(item, dict))):
+                    return "An accessibility check failed before its findings were complete. The baseline was kept."
+                if len({run.get("repetition") for run in cell.get("runs") or ()}) != 1:
+                    return ("An accessibility check ran under --repeat or did not start, so the baseline was "
+                            "not updated. Run it again without --repeat.")
+                coverage = cell.get("screenCoverage") or {}
+                if coverage.get("complete") is not True or type(coverage.get("a11yScreens")) is not int or \
+                        coverage["a11yScreens"] < 1:
+                    return "An accessibility scan was incomplete, so the baseline was not updated."
+    if not audited:
+        return "No check scanned accessibility, so the baseline was not updated."
+    return None
+
+
+def load(root):
+    """The baseline's keys (a frozenset); empty without a file."""
+    file = path(root)
+    if not file.is_file():
+        return frozenset()
+    try:
+        data = json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        raise BaselineError(f".mobster/{FILE} can't be read as JSON. Fix it, or run `mobster test --a11y "
+                            "--update-a11y-baseline` to write it again.") from None
+    # Another schema stops the run: it would otherwise hide nothing and fail everything, or the reverse.
+    found = data.get("findings") if isinstance(data, dict) and data.get("schema") == SCHEMA else None
+    if not isinstance(found, list) or not all(isinstance(key, str) for key in found):
+        raise BaselineError(f".mobster/{FILE} isn't a {SCHEMA} file. Run `mobster test --a11y "
+                            "--update-a11y-baseline` to write it again.")
+    return frozenset(found)
+
+
+def keys(doc):
+    """Every a11y finding's key in a results.json document, sorted."""
+    out = set()
+    for check in doc.get("checks") or ():
+        for result in check.get("results") or ():
+            out.update(item["key"] for item in result.get("findings") or ()
+                       if isinstance(item, dict) and item.get("audit") == "a11y" and isinstance(item.get("key"), str))
+    return sorted(out)
+
+
+def write(root, doc, *, expected_snapshot=None):
+    """Write the document's findings as the project's baseline. Returns how many keys it holds."""
+    found = keys(doc)
+    payload = json.dumps({"schema": SCHEMA, "findings": found}, indent=1, ensure_ascii=False) + "\n"
+    if expected_snapshot is None:
+        write_text_atomic(path(root), payload)
+        return len(found)
+    lock = path(root).with_name(".a11y-baseline.lock")
+    try:
+        descriptor = os.open(lock, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    except OSError:
+        raise BaselineError("The accessibility baseline cannot be locked for replacement. Fix its folder.") from None
+    try:
+        fcntl.flock(descriptor, fcntl.LOCK_EX)
+        if snapshot(root) != expected_snapshot:
+            raise BaselineError("The accessibility baseline changed during this suite. Start a new run.")
+        write_text_atomic(path(root), payload)
+    except OSError:
+        raise BaselineError("The accessibility baseline could not be written. Fix its folder and run again.") from None
+    finally:
+        fcntl.flock(descriptor, fcntl.LOCK_UN)
+        os.close(descriptor)
+    return len(found)
+
+
+def counts(doc):
+    """{"new", "known", "warnings"}: a11y findings by level in a document (new = fail), for the report."""
+    out = {"new": 0, "known": 0, "warnings": 0}
+    for check in doc.get("checks") or ():
+        for result in check.get("results") or ():
+            for item in result.get("findings") or ():
+                if isinstance(item, dict) and item.get("audit") == "a11y":
+                    out[{"fail": "new", "known": "known"}.get(item.get("level"), "warnings")] += 1
+    return out