proofreel 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. proofreel/__init__.py +36 -0
  2. proofreel/ax.py +88 -0
  3. proofreel/ax.swift +99 -0
  4. proofreel/cli.py +620 -0
  5. proofreel/conditions/__init__.py +84 -0
  6. proofreel/conditions/bluetooth-headset-call-mode/Info.plist +18 -0
  7. proofreel/conditions/bluetooth-headset-call-mode/apply.sh +8 -0
  8. proofreel/conditions/bluetooth-headset-call-mode/check.sh +2 -0
  9. proofreel/conditions/bluetooth-headset-call-mode/condition.toml +10 -0
  10. proofreel/conditions/bluetooth-headset-call-mode/headset.c +281 -0
  11. proofreel/conditions/bluetooth-headset-call-mode/host.sh +10 -0
  12. proofreel/conditions/bluetooth-headset-call-mode/probe.swift +76 -0
  13. proofreel/conditions/no-microphone/apply.sh +7 -0
  14. proofreel/conditions/no-microphone/check.sh +10 -0
  15. proofreel/conditions/no-microphone/condition.toml +7 -0
  16. proofreel/conditions/offline/apply.sh +21 -0
  17. proofreel/conditions/offline/check.sh +6 -0
  18. proofreel/conditions/offline/condition.toml +7 -0
  19. proofreel/conditions/quarantined-download/apply.sh +18 -0
  20. proofreel/conditions/quarantined-download/check.sh +10 -0
  21. proofreel/conditions/quarantined-download/condition.toml +10 -0
  22. proofreel/conditions/quarantined-download/host.sh +4 -0
  23. proofreel/conditions/run-from-dmg/apply.sh +17 -0
  24. proofreel/conditions/run-from-dmg/check.sh +11 -0
  25. proofreel/conditions/run-from-dmg/condition.toml +10 -0
  26. proofreel/conditions/run-from-dmg/host.sh +4 -0
  27. proofreel/conditions/slow-network/apply.sh +2 -0
  28. proofreel/conditions/slow-network/check.sh +2 -0
  29. proofreel/conditions/slow-network/condition.toml +21 -0
  30. proofreel/conditions/slow-network/remove.sh +2 -0
  31. proofreel/conditions/slow-network/shape.sh +115 -0
  32. proofreel/crash.py +129 -0
  33. proofreel/demo.py +156 -0
  34. proofreel/draw.py +109 -0
  35. proofreel/flow.py +81 -0
  36. proofreel/guest.py +162 -0
  37. proofreel/image.py +130 -0
  38. proofreel/images/debian-desktop.sh +64 -0
  39. proofreel/images/debian-seed/meta-data +2 -0
  40. proofreel/images/debian-seed/user-data +11 -0
  41. proofreel/keys.swift +67 -0
  42. proofreel/latency.py +98 -0
  43. proofreel/machine.js +163 -0
  44. proofreel/metrics.py +297 -0
  45. proofreel/motion.py +207 -0
  46. proofreel/ocr.swift +34 -0
  47. proofreel/page.css +315 -0
  48. proofreel/page.js +707 -0
  49. proofreel/page.py +188 -0
  50. proofreel/plugins.py +184 -0
  51. proofreel/probes/__init__.py +267 -0
  52. proofreel/probes/browser/observe.js +47 -0
  53. proofreel/probes/browser/probe.toml +53 -0
  54. proofreel/probes/browser/run.py +180 -0
  55. proofreel/probes/host-load/probe.toml +29 -0
  56. proofreel/probes/host-load/run.py +69 -0
  57. proofreel/probes/network/addon.py +92 -0
  58. proofreel/probes/network/probe.toml +13 -0
  59. proofreel/probes/network/run.py +27 -0
  60. proofreel/probes/network/start.sh +15 -0
  61. proofreel/probes/network/stop.sh +8 -0
  62. proofreel/probes/processes/probe.toml +31 -0
  63. proofreel/probes/processes/procs.py +146 -0
  64. proofreel/probes/processes/run.sh +6 -0
  65. proofreel/qemu.py +208 -0
  66. proofreel/recording.py +261 -0
  67. proofreel/redact.py +41 -0
  68. proofreel/render.py +199 -0
  69. proofreel/screen.py +294 -0
  70. proofreel/session.py +118 -0
  71. proofreel/suite.py +91 -0
  72. proofreel/tart.py +86 -0
  73. proofreel/tracks.js +107 -0
  74. proofreel/vm.py +303 -0
  75. proofreel-1.0.0.dist-info/METADATA +157 -0
  76. proofreel-1.0.0.dist-info/RECORD +79 -0
  77. proofreel-1.0.0.dist-info/WHEEL +4 -0
  78. proofreel-1.0.0.dist-info/entry_points.txt +2 -0
  79. proofreel-1.0.0.dist-info/licenses/LICENSE +21 -0
proofreel/__init__.py ADDED
@@ -0,0 +1,36 @@
1
+ """Record an agent driving a screen, and turn it into a review video and page."""
2
+
3
+ import hashlib
4
+ import os
5
+ import shutil
6
+ import subprocess
7
+ import tempfile
8
+ from importlib import resources
9
+ from pathlib import Path
10
+
11
+ __version__ = "1.0.0"
12
+
13
+ HOME = Path(os.environ.get("PROOFREEL_HOME", Path.home() / ".proofreel"))
14
+
15
+
16
+ class Problem(Exception):
17
+ """A failure that a person or agent can fix. The message says what happened and how to fix it."""
18
+
19
+
20
+ def swift_tool(source, *flags):
21
+ """A Swift file of this package, compiled once on the host. The name holds a hash of the source and the flags,
22
+ so a change builds it again. The build goes to a temporary file first, so parallel runs never see half a binary."""
23
+ text = resources.files(__name__).joinpath(source).read_bytes()
24
+ digest = hashlib.sha256(text + repr(flags).encode()).hexdigest()[:12]
25
+ binary = HOME / "bin" / f"proofreel-{Path(source).stem}-{digest}"
26
+ if binary.exists():
27
+ return binary
28
+ if not shutil.which("swiftc"):
29
+ raise Problem(f"{source} is built with swiftc, so it needs a macOS host with Xcode or the Command Line Tools.")
30
+ binary.parent.mkdir(parents=True, exist_ok=True)
31
+ with tempfile.TemporaryDirectory(dir=binary.parent) as temp, \
32
+ resources.as_file(resources.files(__name__).joinpath(source)) as path:
33
+ built = Path(temp) / binary.name
34
+ subprocess.run(["swiftc", "-O", *flags, str(path), "-o", str(built)], check=True, capture_output=True)
35
+ built.replace(binary)
36
+ return binary
proofreel/ax.py ADDED
@@ -0,0 +1,88 @@
1
+ """Read the accessibility (AX) tree of a macOS guest, and find elements by their label.
2
+
3
+ A small helper (ax.swift) runs in the guest over SSH. macOS gives the Accessibility grant to the process that SSH
4
+ starts (/usr/libexec/sshd-keygen-wrapper), so the app under test needs no permission of its own.
5
+ """
6
+
7
+ import json
8
+ import time
9
+
10
+ from . import Problem, guest
11
+
12
+
13
+ def tree(run, app=None):
14
+ """The AX tree of the app's windows (the front app by default), and the main screen size in points. The helper
15
+ is compiled on the host and copied to the guest the first time."""
16
+ result = guest.GUESTS["macos"].helper(run, "ax.swift", *(["--app", app] if app else []))
17
+ if result.returncode:
18
+ raise Problem(f"AX: {result.stderr.strip() or f'the helper failed ({result.returncode})'}")
19
+ return json.loads(result.stdout)
20
+
21
+
22
+ def to_pixels(point, scale):
23
+ return round(point * scale)
24
+
25
+
26
+ def intersect(a, b):
27
+ left, top = max(a[0], b[0]), max(a[1], b[1])
28
+ return left, top, max(0, min(a[0] + a[2], b[0] + b[2]) - left), max(0, min(a[1] + a[3], b[1] + b[3]) - top)
29
+
30
+
31
+ def flatten(node, scale, clip, depth=0):
32
+ """Each element with its depth, center, and box in screen pixels. Visible: its center is in its window and scroll areas."""
33
+ frame = node.get("frame")
34
+ if frame and (depth == 0 or node["role"] == "AXScrollArea"):
35
+ clip = intersect(clip, frame)
36
+ element = {k: v for k, v in node.items() if k != "children"}
37
+ element["depth"] = depth
38
+ element["visible"] = False
39
+ if frame and frame[2] > 0 and frame[3] > 0:
40
+ cx, cy = frame[0] + frame[2] / 2, frame[1] + frame[3] / 2
41
+ element.update(x=to_pixels(cx, scale), y=to_pixels(cy, scale),
42
+ box=[to_pixels(v, scale) for v in frame],
43
+ visible=clip[0] <= cx < clip[0] + clip[2] and clip[1] <= cy < clip[1] + clip[3])
44
+ yield element
45
+ for child in node.get("children", []):
46
+ yield from flatten(child, scale, clip, depth + 1)
47
+
48
+
49
+ def elements(run, screen, app=None):
50
+ data = tree(run, app)
51
+ scale = screen.size()[0] / data["screen"]["w"]
52
+ clip = (0, 0, data["screen"]["w"], data["screen"]["h"])
53
+ return [element for window in data["windows"] for element in flatten(window, scale, clip)]
54
+
55
+
56
+ def names(element):
57
+ return [v for k in ("title", "description", "label", "value", "id") if isinstance(v := element.get(k), str)
58
+ and not (k == "id" and v.startswith("_NS:"))]
59
+
60
+
61
+ def has_role(element, role):
62
+ want = role.lower().removeprefix("ax")
63
+ return any((element.get(k) or "").lower().removeprefix("ax") == want for k in ("role", "subrole"))
64
+
65
+
66
+ def matches(items, label, role=None):
67
+ """Visible elements named the label, then ones whose name contains it. Case is ignored."""
68
+ want = label.strip().lower()
69
+ pool = [e for e in items if e["visible"] and (not role or has_role(e, role))]
70
+ exact = [e for e in pool if any(name.strip().lower() == want for name in names(e))]
71
+ return exact + [e for e in pool if e not in exact and any(want in name.lower() for name in names(e))]
72
+
73
+
74
+ def wait_for(run, screen, label, seconds, present=True, app=None, role=None):
75
+ end = time.time() + seconds
76
+ while True:
77
+ found = matches(elements(run, screen, app), label, role)
78
+ if bool(found) == present or time.time() > end:
79
+ return found
80
+ time.sleep(0.5)
81
+
82
+
83
+ def describe(element, indent=True):
84
+ where = f"{element['x']:5} {element['y']:5}" if element["visible"] else f"{'-':>5} {'-':>5}"
85
+ role = element["role"] + (f"/{element['subrole']}" if element.get("subrole") else "")
86
+ shown = " ".join(json.dumps(name, ensure_ascii=False) for name in dict.fromkeys(names(element)))
87
+ flags = "".join([" disabled" if element.get("enabled") is False else "", " focused" if element.get("focused") else ""])
88
+ return f"{where} {' ' * element['depth'] if indent else ''}{role} {shown}{flags}".rstrip()
proofreel/ax.swift ADDED
@@ -0,0 +1,99 @@
1
+ import AppKit
2
+ import ApplicationServices
3
+
4
+ var appName: String?
5
+ var maxDepth = 60
6
+ var budget = 4000
7
+ var args = CommandLine.arguments.dropFirst().makeIterator()
8
+ while let arg = args.next() {
9
+ switch arg {
10
+ case "--app": appName = args.next()
11
+ case "--front": appName = nil
12
+ case "--depth": maxDepth = Int(args.next() ?? "") ?? maxDepth
13
+ default:
14
+ FileHandle.standardError.write("usage: proofreel-ax [--app <name>|--front] [--depth N]\n".data(using: .utf8)!)
15
+ exit(2)
16
+ }
17
+ }
18
+
19
+ func fail(_ message: String, _ code: Int32) -> Never {
20
+ FileHandle.standardError.write((message + "\n").data(using: .utf8)!)
21
+ exit(code)
22
+ }
23
+
24
+ guard AXIsProcessTrusted() else {
25
+ fail("This process has no Accessibility permission. Grant it to the process that starts it (over SSH: /usr/libexec/sshd-keygen-wrapper).", 3)
26
+ }
27
+
28
+ func attribute(_ element: AXUIElement, _ name: String) -> AnyObject? {
29
+ var value: AnyObject?
30
+ return AXUIElementCopyAttributeValue(element, name as CFString, &value) == .success ? value : nil
31
+ }
32
+
33
+ func text(_ value: AnyObject?, limit: Int = 200) -> String? {
34
+ guard let string = value as? String, !string.isEmpty else { return nil }
35
+ return string.count > limit ? String(string.prefix(limit)) + "…" : string
36
+ }
37
+
38
+ func plain(_ value: AnyObject?) -> Any? {
39
+ if let string = text(value) { return string }
40
+ if let number = value as? NSNumber { return number }
41
+ if let url = value as? URL { return url.absoluteString }
42
+ return nil
43
+ }
44
+
45
+ func frame(_ element: AXUIElement) -> [Double]? {
46
+ var point = CGPoint.zero, size = CGSize.zero
47
+ guard let position = attribute(element, kAXPositionAttribute), let extent = attribute(element, kAXSizeAttribute),
48
+ CFGetTypeID(position) == AXValueGetTypeID(), CFGetTypeID(extent) == AXValueGetTypeID(),
49
+ AXValueGetValue(position as! AXValue, .cgPoint, &point), AXValueGetValue(extent as! AXValue, .cgSize, &size)
50
+ else { return nil }
51
+ return [point.x, point.y, size.width, size.height].map { (Double($0) * 10).rounded() / 10 }
52
+ }
53
+
54
+ func node(_ element: AXUIElement, _ depth: Int) -> [String: Any] {
55
+ budget -= 1
56
+ var out: [String: Any] = ["role": attribute(element, kAXRoleAttribute) as? String ?? "?"]
57
+ out["subrole"] = text(attribute(element, kAXSubroleAttribute))
58
+ out["title"] = text(attribute(element, kAXTitleAttribute))
59
+ out["description"] = text(attribute(element, kAXDescriptionAttribute))
60
+ out["id"] = text(attribute(element, kAXIdentifierAttribute))
61
+ out["value"] = plain(attribute(element, kAXValueAttribute))
62
+ if let titled = attribute(element, kAXTitleUIElementAttribute), CFGetTypeID(titled) == AXUIElementGetTypeID() {
63
+ let label = titled as! AXUIElement
64
+ out["label"] = text(attribute(label, kAXValueAttribute)) ?? text(attribute(label, kAXTitleAttribute))
65
+ }
66
+ out["enabled"] = attribute(element, kAXEnabledAttribute) as? Bool
67
+ out["focused"] = (attribute(element, kAXFocusedAttribute) as? Bool) == true ? true : nil
68
+ out["frame"] = frame(element)
69
+ let children = attribute(element, kAXChildrenAttribute) as? [AXUIElement] ?? []
70
+ if depth < maxDepth && budget > 0 && !children.isEmpty {
71
+ out["children"] = children.prefix(budget).map { node($0, depth + 1) }
72
+ }
73
+ return out
74
+ }
75
+
76
+ func match(_ app: NSRunningApplication, _ name: String) -> Bool {
77
+ let want = name.lowercased()
78
+ return app.localizedName?.lowercased() == want || app.bundleIdentifier?.lowercased() == want
79
+ }
80
+
81
+ let apps = NSWorkspace.shared.runningApplications
82
+ let found = appName.map { name in
83
+ apps.first { match($0, name) } ?? apps.first { $0.localizedName?.lowercased().contains(name.lowercased()) == true }
84
+ } ?? NSWorkspace.shared.frontmostApplication
85
+ guard let pid = found?.processIdentifier else { fail(appName.map { "No running app named \($0)." } ?? "No app is in front.", 4) }
86
+
87
+ let app = AXUIElementCreateApplication(pid)
88
+ AXUIElementSetMessagingTimeout(app, 3)
89
+ let windows = attribute(app, kAXWindowsAttribute) as? [AXUIElement] ?? []
90
+ let display = CGDisplayBounds(CGMainDisplayID())
91
+ let result: [String: Any] = [
92
+ "app": NSRunningApplication(processIdentifier: pid)?.localizedName ?? "",
93
+ "pid": pid,
94
+ "screen": ["w": display.width, "h": display.height],
95
+ "windows": windows.map { node($0, 0) },
96
+ ]
97
+ let data = try JSONSerialization.data(withJSONObject: result, options: [.sortedKeys])
98
+ FileHandle.standardOutput.write(data)
99
+ FileHandle.standardOutput.write("\n".data(using: .utf8)!)