qa-agent-kit 0.6.0__py3-none-any.whl

qakit/tools/device_lock.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""One test iPhone, many sessions: a first-come lock around everything that drives the phone.
+
+Two Claude sessions QA-ing two apps on the one USB iPhone (2026-10-28) fight over the foreground app and the phone-wide settings
+(dark mode, text size, VoiceOver, simulated location): both runs fail, or pass on the wrong screen. `device_qa.py` holds this lock
+for test, traits, perf, upgrade, release and devmode; a second session waits in arrival order and says who holds the phone.
+Raw xcodebuild/devicectl/xctrace work goes through `device_qa.py lock run -- <command>`; `device_qa.py lock status` shows the queue.
+
+The lock is flock(2) on ~/.qakit/device-qa/<udid>.lock: the kernel drops it when the holder exits or crashes, so nothing goes
+stale. flock alone is not first-come, so a waiting session leaves a ticket in <udid>.queue/ and only the oldest live ticket may
+take the lock.
+
+A holder puts QAKIT_DEVICE_HELD=<udid>:<pid> in its environment, so the commands it starts (`lock run -- <script>` whose
+script calls `device_qa.py test`) share its turn instead of queueing behind their own parent until the timeout.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import fcntl
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+LOCKS = Path(os.environ.get("QAKIT_DEVICE_LOCKS") or Path.home() / ".qakit/device-qa")
+HELD = "QAKIT_DEVICE_HELD"
+
+
+class DeviceBusy(RuntimeError):
+    """The phone is held and the caller asked not to wait (or waited past its timeout)."""
+
+
+def alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:   # someone else's process: alive
+        return True
+    return True
+
+
+def ticket_pid(name: str) -> int:
+    return int(name.split("-", 1)[1].split(".", 1)[0])
+
+
+def next_in_line(tickets: list[str], is_alive: Callable[[int], bool] = alive) -> str | None:
+    """The oldest ticket ('<ns>-<pid>.json') whose process still runs: tickets sort by arrival time."""
+    for name in sorted(tickets, key=lambda n: int(n.split("-", 1)[0])):
+        if is_alive(ticket_pid(name)):
+            return name
+    return None
+
+
+class DeviceLock:
+    """`with DeviceLock(udid, note):` holds the phone for the block. `note` says who (app, command, session) to those waiting."""
+
+    def __init__(self, udid: str, note: str, *, wait: bool = True, timeout: float = 4 * 3600, poll: float = 5, root: Path | None = None,
+                 log: Callable[[str], None] = lambda message: print(message, file=sys.stderr, flush=True)) -> None:
+        self.root = root or LOCKS
+        self.udid, self.note, self.wait, self.timeout, self.poll, self.log = udid or "no-device", note, wait, timeout, poll, log
+        self.fd: int | None = None
+
+    @property
+    def queue(self) -> Path:
+        return self.root / f"{self.udid}.queue"
+
+    @property
+    def holder_file(self) -> Path:
+        return self.root / f"{self.udid}.holder.json"
+
+    def holder(self) -> dict[str, Any] | None:
+        """Who holds the phone now: the holder file of a process that still runs, else None."""
+        try:
+            info = json.loads(self.holder_file.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        return info if alive(int(info.get("pid", 0))) else None
+
+    def waiting(self) -> list[dict[str, Any]]:
+        """Live tickets in arrival order."""
+        names = sorted((p.name for p in self.queue.glob("*.json")), key=lambda n: int(n.split("-", 1)[0])) if self.queue.is_dir() else []
+        out = []
+        for name in names:
+            if alive(ticket_pid(name)):
+                try:
+                    out.append(json.loads((self.queue / name).read_text(encoding="utf-8")))
+                except (OSError, ValueError):
+                    pass
+        return out
+
+    def describe(self, info: dict[str, Any] | None) -> str:
+        return f"{info.get('note', '?')} (pid {info.get('pid')}, since {info.get('since', '?')})" if info else "another session"
+
+    def __enter__(self) -> "DeviceLock":
+        holder = self.holder()
+        if holder and holder.get("pid") != os.getpid() and os.environ.get(HELD) == f"{self.udid}:{holder.get('pid')}":
+            return self   # started by the holder: its turn is ours (fd stays None, so __exit__ releases nothing)
+        # ponytail: the marker is inherited, not proven ancestry; a session that copies another's environment could jump the
+        # queue. Upgrade trigger: that happens once -> walk the parent chain (ps -o ppid) instead.
+        self.queue.mkdir(parents=True, exist_ok=True)
+        self.fd = os.open(self.root / f"{self.udid}.lock", os.O_RDWR | os.O_CREAT, 0o644)
+        ticket = self.queue / f"{time.time_ns()}-{os.getpid()}.json"
+        ticket.write_text(json.dumps({"pid": os.getpid(), "note": self.note, "since": dt.datetime.now().strftime("%H:%M:%S")},
+                                     ensure_ascii=False), encoding="utf-8")
+        deadline, said = time.monotonic() + self.timeout, 0.0
+        try:
+            while True:
+                names = [p.name for p in self.queue.glob("*.json")]
+                for name in names:   # tickets of sessions that died while waiting
+                    if name != ticket.name and not alive(ticket_pid(name)):
+                        (self.queue / name).unlink(missing_ok=True)
+                if next_in_line(names) == ticket.name:
+                    try:
+                        fcntl.flock(self.fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                        break
+                    except BlockingIOError:
+                        pass
+                who = self.describe(self.holder())
+                if not self.wait or time.monotonic() > deadline:
+                    raise DeviceBusy(f"the test phone is in use by {who}")
+                if time.monotonic() - said >= 60:
+                    ahead = sum(1 for n in names if int(n.split("-", 1)[0]) < int(ticket.name.split("-", 1)[0]) and alive(ticket_pid(n)))
+                    self.log(f"waiting for the test phone: held by {who}; {ahead} ahead in the queue")
+                    said = time.monotonic()
+                time.sleep(self.poll)
+        except BaseException:
+            os.close(self.fd)
+            self.fd = None
+            raise
+        finally:
+            ticket.unlink(missing_ok=True)
+        self.holder_file.write_text(json.dumps({"pid": os.getpid(), "note": self.note, "since": dt.datetime.now().strftime("%H:%M:%S"),
+                                                "cwd": os.getcwd()}, ensure_ascii=False), encoding="utf-8")
+        os.environ[HELD] = f"{self.udid}:{os.getpid()}"
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self.fd is None:
+            return
+        try:
+            if json.loads(self.holder_file.read_text(encoding="utf-8")).get("pid") == os.getpid():
+                self.holder_file.unlink(missing_ok=True)
+        except (OSError, ValueError):
+            pass
+        os.environ.pop(HELD, None)
+        fcntl.flock(self.fd, fcntl.LOCK_UN)
+        os.close(self.fd)
+        self.fd = None