chartremotely 0.2.0__py3-none-any.whl

chartremotely/ax.py

@@ -0,0 +1,278 @@
+"""macOS Accessibility and input primitives.
+
+Everything awkward about driving thinkorswim lives here so the drivers above
+stay readable. thinkorswim is a Java/Swing application, which breaks several
+reasonable assumptions:
+
+* Its accessibility tree is real, but chart children are populated lazily -
+  walking ``AXChildren`` misses the symbol field entirely. Hit-testing finds
+  it. See :func:`element_at`.
+* ``AXValue`` is read-only on its text fields, while ``AXFocused`` is
+  settable. You focus a field and type into it; you cannot write it.
+* Its menu items answer to ``AXPick``, not ``AXPress``.
+* Its aggregation list is a *lightweight* popup painted inside the window.
+  It ignores process-targeted mouse events completely, so it needs a real
+  HID click - which in turn needs the target to be unobstructed.
+* AWT ignores ``CGEventKeyboardSetUnicodeString``; only real virtual
+  keycodes register.
+"""
+
+from __future__ import annotations
+
+import time
+
+import Quartz
+from AppKit import NSWorkspace
+from ApplicationServices import (
+    AXUIElementCopyActionNames,
+    AXUIElementCopyAttributeValue,
+    AXUIElementCopyElementAtPosition,
+    AXUIElementCreateApplication,
+    AXUIElementIsAttributeSettable,
+    AXUIElementPerformAction,
+    AXUIElementSetAttributeValue,
+    AXValueGetValue,
+    kAXErrorSuccess,
+    kAXValueCGPointType,
+    kAXValueCGSizeType,
+)
+
+APP_NAME = "thinkorswim"
+
+# Virtual keycodes. AWT ignores unicode-string events, so every character
+# must be sent as the key a human would press.
+KEYCODE = {
+    "a": 0, "b": 11, "c": 8, "d": 2, "e": 14, "f": 3, "g": 5, "h": 4,
+    "i": 34, "j": 38, "k": 40, "l": 37, "m": 46, "n": 45, "o": 31, "p": 35,
+    "q": 12, "r": 15, "s": 1, "t": 17, "u": 32, "v": 9, "w": 13, "x": 7,
+    "y": 16, "z": 6,
+    "0": 29, "1": 18, "2": 19, "3": 20, "4": 21,
+    "5": 23, "6": 22, "7": 26, "8": 28, "9": 25,
+    ".": 47, "/": 44, "-": 27, ":": 41, "$": 21,
+}
+KEY_RETURN, KEY_ESCAPE, KEY_DOWN = 36, 53, 125
+
+
+class NotRunning(RuntimeError):
+    """thinkorswim is not running."""
+
+
+def running_app():
+    for a in NSWorkspace.sharedWorkspace().runningApplications():
+        if APP_NAME.lower() in (a.localizedName() or "").lower():
+            return a
+    raise NotRunning(f"{APP_NAME} is not running")
+
+
+def handle(app=None):
+    return AXUIElementCreateApplication((app or running_app()).processIdentifier())
+
+
+def activate(app=None) -> None:
+    """Bring thinkorswim forward, and wait for it to actually be forward.
+
+    This must happen BEFORE any hit-testing.
+    ``AXUIElementCopyElementAtPosition`` resolves against the application's
+    menu bar - not the window under the point - when the app is not
+    frontmost, so every lookup silently returns ``AXMenuBar``.
+    """
+    (app or running_app()).activateWithOptions_(2)
+    time.sleep(0.6)
+
+
+def attr(element, name):
+    err, value = AXUIElementCopyAttributeValue(element, name, None)
+    return value if err == kAXErrorSuccess else None
+
+
+def settable(element, name) -> bool:
+    err, is_settable = AXUIElementIsAttributeSettable(element, name, None)
+    return bool(is_settable) if err == kAXErrorSuccess else False
+
+
+def set_attr(element, name, value) -> bool:
+    return AXUIElementSetAttributeValue(element, name, value) == kAXErrorSuccess
+
+
+def actions(element) -> list[str]:
+    err, names = AXUIElementCopyActionNames(element, None)
+    return list(names) if err == kAXErrorSuccess else []
+
+
+def perform(element, action) -> bool:
+    """Run an action. Menu items want ``AXPick``; buttons want ``AXPress``."""
+    return AXUIElementPerformAction(element, action) == kAXErrorSuccess
+
+
+def _geo(element, name, kind):
+    value = attr(element, name)
+    if value is None:
+        return None
+    ok, out = AXValueGetValue(value, kind, None)
+    return out if ok else None
+
+
+def position(element):
+    return _geo(element, "AXPosition", kAXValueCGPointType)
+
+
+def size(element):
+    return _geo(element, "AXSize", kAXValueCGSizeType)
+
+
+def centre(element) -> tuple[int, int] | None:
+    p, s = position(element), size(element)
+    return (int(p.x + s.width / 2), int(p.y + s.height / 2)) if p and s else None
+
+
+def element_at(ax_app, x: float, y: float):
+    """Hit-test a screen point. Requires the app to be frontmost."""
+    err, element = AXUIElementCopyElementAtPosition(ax_app, float(x), float(y), None)
+    return element if err == kAXErrorSuccess else None
+
+
+def window(ax_app, title_prefix: str):
+    for w in attr(ax_app, "AXWindows") or []:
+        if (attr(w, "AXTitle") or "").startswith(title_prefix):
+            return w
+    return None
+
+
+def walk(element, visit, depth: int = 0, budget: list[int] | None = None) -> None:
+    """Depth-first walk. Chart subtrees are lazy, so this cannot find
+    everything - use it for dialogs, and hit-testing for charts."""
+    budget = budget if budget is not None else [80000]
+    budget[0] -= 1
+    if budget[0] <= 0 or depth > 45:
+        return
+    visit(element)
+    for child in attr(element, "AXChildren") or []:
+        walk(child, visit, depth + 1, budget)
+
+
+def find(root, *, role=None, label=None, predicate=None) -> list:
+    """Collect matching descendants. ``label`` checks title, value and
+    description - thinkorswim scatters captions across all three."""
+    hits = []
+
+    def visit(element):
+        if role and attr(element, "AXRole") != role:
+            return
+        if label is not None and label not in (
+            attr(element, "AXTitle"), attr(element, "AXValue"),
+            attr(element, "AXDescription"),
+        ):
+            return
+        if predicate and not predicate(element):
+            return
+        hits.append(element)
+
+    walk(root, visit)
+    return hits
+
+
+# --------------------------------------------------------------------------
+# Input
+
+
+def key(code: int, flags: int = 0, pid: int | None = None) -> None:
+    """Send a keystroke, to a process when given a pid.
+
+    ``CGEventPost(kCGHIDEventTap)`` delivers to whatever holds keyboard
+    focus, which is not reliably thinkorswim when another window floats
+    always-on-top - the keystrokes land in that window instead.
+    ``CGEventPostToPid`` removes the race.
+    """
+    for down in (True, False):
+        event = Quartz.CGEventCreateKeyboardEvent(None, code, down)
+        Quartz.CGEventSetFlags(event, flags)
+        if pid is None:
+            Quartz.CGEventPost(Quartz.kCGHIDEventTap, event)
+        else:
+            Quartz.CGEventPostToPid(pid, event)
+        time.sleep(0.012)
+
+
+def type_text(text: str, pid: int | None = None) -> None:
+    for ch in text.lower():
+        code = KEYCODE.get(ch)
+        if code is None:
+            continue
+        key(code, Quartz.kCGEventFlagMaskShift if ch in "$:" else 0, pid)
+        time.sleep(0.02)
+
+
+def escape(pid: int) -> None:
+    key(KEY_ESCAPE, 0, pid)
+
+
+# --------------------------------------------------------------------------
+# Occlusion. A real HID click goes to whatever is visually on top, so
+# clicking blind can land in another application entirely.
+
+
+def _regular_pids() -> set[int]:
+    """Ordinary windowed apps.
+
+    System overlays - Notification Center above all - keep permanent
+    full-screen windows at high layers with alpha 1.0 that are visually
+    empty. Counting those as obstructions blocks every click forever.
+    """
+    return {a.processIdentifier()
+            for a in NSWorkspace.sharedWorkspace().runningApplications()
+            if a.activationPolicy() == 0}
+
+
+def occluders_at(x: float, y: float, tos_pid: int) -> list[int]:
+    """Pids of regular apps whose windows sit above thinkorswim at a point."""
+    regular = _regular_pids()
+    found, seen_target = [], False
+    for w in Quartz.CGWindowListCopyWindowInfo(
+            Quartz.kCGWindowListOptionOnScreenOnly, Quartz.kCGNullWindowID):
+        pid = w.get("kCGWindowOwnerPID")
+        b = w.get("kCGWindowBounds") or {}
+        covers = (b.get("X", 0) <= x <= b.get("X", 0) + b.get("Width", 0)
+                  and b.get("Y", 0) <= y <= b.get("Y", 0) + b.get("Height", 0))
+        if pid == tos_pid and covers:
+            seen_target = True
+        elif (covers and not seen_target and pid in regular
+              and w.get("kCGWindowLayer", 0) >= 0 and w.get("kCGWindowAlpha", 1)):
+            found.append(pid)
+    return list(dict.fromkeys(found))
+
+
+def hide_apps(pids) -> list:
+    apps = [a for a in NSWorkspace.sharedWorkspace().runningApplications()
+            if a.processIdentifier() in pids and not a.isHidden()]
+    for a in apps:
+        a.hide()
+    if apps:
+        time.sleep(0.6)
+    return apps
+
+
+def unhide_apps(apps) -> None:
+    for a in apps:
+        a.unhide()
+
+
+class Obstructed(RuntimeError):
+    """The click target is covered and the click was refused."""
+
+
+def click(x: int, y: int, tos_pid: int) -> None:
+    """Real HID click, refused unless the target is provably unobstructed."""
+    blockers = occluders_at(x, y, tos_pid)
+    if blockers:
+        names = sorted({(a.localizedName() or "?")
+                        for a in NSWorkspace.sharedWorkspace().runningApplications()
+                        if a.processIdentifier() in blockers})
+        raise Obstructed(f"target at ({x},{y}) is covered by {', '.join(names)}")
+    Quartz.CGEventPost(Quartz.kCGHIDEventTap, Quartz.CGEventCreateMouseEvent(
+        None, Quartz.kCGEventMouseMoved, Quartz.CGPointMake(x, y),
+        Quartz.kCGMouseButtonLeft))
+    time.sleep(0.25)
+    for kind in (Quartz.kCGEventLeftMouseDown, Quartz.kCGEventLeftMouseUp):
+        Quartz.CGEventPost(Quartz.kCGHIDEventTap, Quartz.CGEventCreateMouseEvent(
+            None, kind, Quartz.CGPointMake(x, y), Quartz.kCGMouseButtonLeft))
+        time.sleep(0.12)

chartremotely/cli.py

@@ -0,0 +1,136 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="chartremotely",
+        description="Remote control of desktop charting applications on macOS.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    show = sub.add_parser("show", help="put a security on the chart")
+    show.add_argument("name", nargs="+", help="ticker or spoken company name")
+    show.add_argument("--scale", default="", help="time frame mnemonic")
+
+    scale = sub.add_parser("scale", help="change the chart's time frame")
+    scale.add_argument("phrase", nargs="+")
+
+    sub.add_parser("read", help="report the chart's symbol and scale")
+    sub.add_parser("scales", help="list the time frames this chart offers")
+    sub.add_parser("learn", help="rediscover the chart's controls")
+    sub.add_parser("doctor", help="check everything this agent needs")
+    sub.add_parser("token", help="print the agent's access token")
+
+    setup = sub.add_parser("studies", help="rebuild the chart's study set")
+    setup.add_argument("--row-height", default=None,
+                       help="profile row height; match the strike increment (1.0, 2.5)")
+
+    serve = sub.add_parser("serve", help="run the local listener")
+    serve.add_argument("--port", type=int, default=None)
+
+    pair = sub.add_parser("pair", help="adopt this display to an operator")
+    pair.add_argument("--operator", default=None, help="operator base URL")
+
+    relay = sub.add_parser("relay", help="hold a connection open for the operator")
+    relay.add_argument("--operator", default=None)
+
+    sub.add_parser("setup", help="pair this Mac and make its voice Shortcut, step by step")
+
+    perms = sub.add_parser("permissions", help="report (or request) Accessibility and Screen Recording")
+    perms.add_argument("--request", action="store_true", help="ask macOS to prompt for them")
+    perms.add_argument("--out", default=None, help="write the answer as JSON to this file")
+
+    args = parser.parse_args(argv)
+
+    # Imported lazily so `doctor` can explain a missing dependency rather
+    # than dying on an ImportError.
+    if args.command == "doctor":
+        from .doctor import report
+        return report()
+    if args.command == "token":
+        from .config import ensure_token
+        print(ensure_token())
+        return 0
+    if args.command == "pair":
+        from .relay import pair as do_pair
+        print("Give this code to your MCP client: ", end="", flush=True)
+        try:
+            do_pair(args.operator, on_code=lambda c: print(c, flush=True))
+        except Exception as exc:  # noqa: BLE001 - surface the reason plainly
+            print(f"pairing failed: {exc}")
+            return 2
+        print("paired")
+        return 0
+    if args.command == "setup":
+        from .setup import SetupError
+        from .setup import run as run_setup
+        try:
+            return run_setup()
+        except (SetupError, RuntimeError, OSError) as exc:
+            print(f"setup stopped: {exc}")
+            print("Fix that, then run `chartremotely setup` again; finished steps are skipped.")
+            return 2
+    if args.command == "permissions":
+        import json
+        from pathlib import Path
+
+        from .services import permissions
+        answer = json.dumps(permissions(args.request))
+        if args.out:
+            Path(args.out).write_text(answer)
+        print(answer)
+        return 0
+    if args.command == "relay":
+        from .relay import run
+        run(args.operator)
+        return 0
+    if args.command == "serve":
+        from .server import serve as run
+        run(args.port)
+        return 0
+
+    from . import symbol, timeframe
+    from .vocab import ERR, cmd_resolve, cmd_set, dispatch
+
+    if args.command == "show":
+        spoken = " ".join(args.name)
+        ticker = spoken if _looks_like_ticker(spoken) else cmd_resolve(spoken)
+        if ticker.startswith(ERR):
+            print(ticker)
+            return 2
+        print(cmd_set(ticker, args.scale))
+        return 0
+    if args.command == "scale":
+        print(dispatch("scale " + " ".join(args.phrase)))
+        return 0
+    if args.command == "read":
+        print(dispatch("read"))
+        return 0
+    if args.command == "scales":
+        for label in timeframe.presets():
+            print(" ", label)
+        return 0
+    if args.command == "studies":
+        from . import studies
+        for line in studies.setup(args.row_height):
+            print(" ", line)
+        return 0
+    if args.command == "learn":
+        symbol.learn()
+        timeframe.learn()
+        print("controls rediscovered")
+        return 0
+    return 1
+
+
+def _looks_like_ticker(text: str) -> bool:
+    from .symbol import TICKER
+    return bool(TICKER.match(text.strip().upper()))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

chartremotely/config.py

@@ -0,0 +1,68 @@
+"""One configuration file, in one place.
+
+Replaces the scattered ``~/.config/tos-symbol.json`` and
+``~/.config/tos-chart-token`` of the prototype.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from pathlib import Path
+
+CONFIG_DIR = Path(os.path.expanduser("~/.config/chartremotely"))
+CONFIG_PATH = CONFIG_DIR / "config.json"
+DATA_DIR = Path(os.path.expanduser("~/.local/share/chartremotely"))
+
+DEFAULTS: dict = {
+    # Window whose title starts with this holds the chart. The build number
+    # is deliberately excluded so a thinkorswim update does not break it.
+    "window_prefix": "Main@thinkorswim",
+    # Offsets are relative to the WINDOW, not the screen, so moving or
+    # resizing the window does not invalidate them.
+    "symbol_dx": None,
+    "symbol_dy": None,
+    "aggregation_dx": None,
+    "aggregation_dy": None,
+    # Row height should match the underlying's strike increment so volume
+    # profile buckets land on tradable strikes.
+    "row_height": "1.0",
+    # The SEC wants a contactable address on registry requests.
+    "contact": None,
+    # Set once the agent is adopted by an operator.
+    "operator_url": None,
+    "agent_id": None,
+    "agent_secret": None,
+    "token": None,
+    "port": 8899,
+}
+
+
+def load() -> dict:
+    cfg = dict(DEFAULTS)
+    if CONFIG_PATH.exists():
+        cfg.update(json.loads(CONFIG_PATH.read_text()))
+    return cfg
+
+
+def save(cfg: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    tmp = CONFIG_PATH.with_suffix(".tmp")
+    tmp.write_text(json.dumps(cfg, indent=2))
+    tmp.chmod(0o600)
+    tmp.replace(CONFIG_PATH)
+
+
+def update(**changes) -> dict:
+    cfg = load()
+    cfg.update(changes)
+    save(cfg)
+    return cfg
+
+
+def ensure_token() -> str:
+    cfg = load()
+    if not cfg.get("token"):
+        cfg = update(token=secrets.token_urlsafe(32))
+    return cfg["token"]

chartremotely/doctor.py

@@ -0,0 +1,118 @@
+"""Check everything the agent needs, and say what to do about each failure.
+
+Written for someone who cannot see the screen. When a wall display in
+another building goes quiet, this is the first thing to run - so every
+check names the fix, not just the symptom.
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+
+from . import config
+
+OK, BAD, WARN = "  ok  ", " FAIL ", " warn "
+
+
+def _check_pyobjc() -> tuple[str, str]:
+    try:
+        import Quartz  # noqa: F401
+        from ApplicationServices import AXUIElementCreateApplication  # noqa: F401
+    except ImportError:
+        return BAD, 'PyObjC missing - pip install "chartremotely[macos]"'
+    return OK, "PyObjC present"
+
+
+def _check_app() -> tuple[str, str]:
+    from . import ax
+    try:
+        app = ax.running_app()
+    except ax.NotRunning:
+        return BAD, "thinkorswim is not running - start it"
+    return OK, f"thinkorswim running (pid {app.processIdentifier()})"
+
+
+def _check_accessibility() -> tuple[str, str]:
+    """A denied grant looks like an empty tree, not an error."""
+    from . import ax
+    try:
+        app = ax.running_app()
+    except ax.NotRunning:
+        return WARN, "skipped - thinkorswim is not running"
+    windows = ax.attr(ax.handle(app), "AXWindows")
+    if not windows:
+        return BAD, ("no accessibility access - grant it in System Settings > "
+                     "Privacy & Security > Accessibility. This cannot be automated.")
+    return OK, f"accessibility granted ({len(windows)} windows visible)"
+
+
+def _check_controls() -> tuple[str, str]:
+    from . import ax, symbol, timeframe
+    cfg = config.load()
+    try:
+        ax_app = ax.handle()
+        ax.activate()
+    except ax.NotRunning:
+        return WARN, "skipped - thinkorswim is not running"
+    found_symbol = symbol.discover(ax_app, cfg["window_prefix"])
+    found_scale = timeframe.discover(ax_app, cfg["window_prefix"])
+    if not found_symbol:
+        return BAD, "no symbol field found - is a chart visible in the window?"
+    if not found_scale:
+        return WARN, "symbol field found, but no aggregation control - scale changes unavailable"
+    return OK, f"symbol field at {found_symbol}, aggregation at {found_scale}"
+
+
+def _check_registry() -> tuple[str, str]:
+    from . import registry
+    if not registry.CACHE.exists():
+        return WARN, "security registry not cached yet - it downloads on first use"
+    try:
+        rows = registry.load()
+    except (OSError, ValueError) as exc:
+        return BAD, f"registry unreadable: {exc}"
+    if not config.load().get("contact"):
+        return WARN, (f"{len(rows)} securities cached, but no contact address set - "
+                      "the SEC answers 403 without one. Set it in config.json.")
+    return OK, f"{len(rows)} securities cached"
+
+
+def _check_listener() -> tuple[str, str]:
+    cfg = config.load()
+    port = cfg["port"]
+    token = cfg.get("token")
+    if not token:
+        return WARN, "no token yet - it is generated when the listener first starts"
+    request = urllib.request.Request(
+        f"http://127.0.0.1:{port}/chart", data=b"read",
+        headers={"X-Token": token}, method="POST")
+    try:
+        with urllib.request.urlopen(request, timeout=5) as response:
+            return OK, f"listener answering on :{port} - {response.read().decode().strip()}"
+    except urllib.error.URLError:
+        return WARN, f"nothing listening on :{port} - run: chartremotely serve"
+
+
+CHECKS = (
+    ("PyObjC", _check_pyobjc),
+    ("thinkorswim", _check_app),
+    ("Accessibility", _check_accessibility),
+    ("Chart controls", _check_controls),
+    ("Registry", _check_registry),
+    ("Listener", _check_listener),
+)
+
+
+def report() -> int:
+    """Print every check. Returns non-zero if any hard check failed."""
+    failed = False
+    for name, check in CHECKS:
+        try:
+            status, detail = check()
+        except Exception as exc:  # noqa: BLE001 - a doctor must never crash
+            status, detail = BAD, f"check raised: {exc}"
+        if status == BAD:
+            failed = True
+        print(f"[{status}] {name:<16} {detail}")
+    return 1 if failed else 0