chartremotely 0.2.0__py3-none-any.whl

chartremotely/shortcut.py

@@ -0,0 +1,56 @@
+"""Make this Mac's own copy of the ChartRemotely voice Shortcut.
+
+The template is the working Shortcut itself, exported with two placeholders
+where its address and token were. Filling them in is string substitution
+and nothing more: rebuilding a Shortcut's steps by hand has twice produced
+one that Siri runs differently from the original.
+"""
+
+from __future__ import annotations
+
+import plistlib
+import subprocess
+import tempfile
+from importlib import resources
+from pathlib import Path
+
+URL_MARK = "__CHARTREMOTELY_URL__"
+TOKEN_MARK = "__CHARTREMOTELY_TOKEN__"
+NAME = "ChartRemotely"
+
+
+def template() -> bytes:
+    return resources.files("chartremotely").joinpath("assets/shortcut-template.plist").read_bytes()
+
+
+def fill(raw: bytes, url: str, token: str) -> dict:
+    """The template with its placeholders replaced, as a Shortcut workflow."""
+    for value, mark in ((url, URL_MARK), (token, TOKEN_MARK)):
+        if not value or mark in value:
+            raise ValueError(f"no value for {mark}")
+    workflow = plistlib.loads(raw)
+
+    def walk(node):
+        if isinstance(node, dict):
+            return {k: walk(v) for k, v in node.items()}
+        if isinstance(node, list):
+            return [walk(v) for v in node]
+        if isinstance(node, str):
+            return node.replace(URL_MARK, url).replace(TOKEN_MARK, token)
+        return node
+
+    return walk(workflow)
+
+
+def build(url: str, token: str, out_dir: Path | None = None) -> Path:
+    """Write, sign and return this Mac's Shortcut. The file name is its library name."""
+    folder = Path(out_dir or tempfile.mkdtemp(prefix="chartremotely-"))
+    unsigned = folder / "unsigned.shortcut"
+    signed = folder / f"{NAME}.shortcut"
+    unsigned.write_bytes(plistlib.dumps(fill(template(), url, token), fmt=plistlib.FMT_BINARY))
+    try:
+        subprocess.run(["shortcuts", "sign", "-m", "anyone", "-i", str(unsigned), "-o", str(signed)],
+                       capture_output=True, check=True)
+    finally:
+        unsigned.unlink(missing_ok=True)
+    return signed

chartremotely/snapshot.py

@@ -0,0 +1,88 @@
+"""Crop a capture to the chart, and shrink it into something that can travel.
+
+Only the chart's own pane leaves the machine. A thinkorswim window also shows
+the account number, net liquidation value, buying power and cash, and a
+snapshot is a picture sent to wherever the patron is — so the crop is the
+point, not a nicety. When the chart's pane cannot be told apart from the whole
+window, there is no snapshot: failing closed is the only safe answer.
+
+A window capture on a Retina display is a multi-megabyte PNG. It crosses the
+relay as text inside a JSON reply and sits for a moment in the operator's
+database, so it is re-encoded as a modest JPEG first: enough to read the
+chart, small enough not to matter.
+
+Pure on purpose. The capture itself needs the macOS drivers; turning bytes
+into a reply does not, so this module stays importable - and testable -
+where PyObjC is absent. ``sips`` is the system's own image tool, which keeps
+the dependency list empty.
+"""
+
+from __future__ import annotations
+
+import base64
+import subprocess
+import tempfile
+from pathlib import Path
+
+#: Longest side of the image sent back, in pixels.
+MAX_SIDE = 1600
+#: JPEG quality, 0-100.
+QUALITY = 70
+#: What every successful reply starts with. The operator checks for it.
+PREFIX = "data:image/jpeg;base64,"
+
+Rect = tuple[int, int, int, int]
+
+
+class ChartNotIsolated(LookupError):
+    """The chart's own pane could not be told apart from the whole window."""
+
+
+def chart_crop(hit: tuple[int, int], panes: list[Rect], window: Rect,
+               image: tuple[int, int]) -> Rect:
+    """The chart's pane, in the capture's own pixels.
+
+    ``hit`` is a point inside the chart (its symbol field), ``panes`` the
+    containers the accessibility tree reports and ``window`` the window, all
+    in screen points. ``image`` is the capture's size in pixels, which differs
+    from the window's size in points on a Retina display.
+
+    The chart's pane is the smallest container around the symbol field. The
+    window itself never counts: sending it would send the account panel.
+    """
+    wx, wy, ww, wh = window
+    hx, hy = hit
+    inside = [r for r in panes
+              if r[0] <= hx < r[0] + r[2] and r[1] <= hy < r[1] + r[3]
+              and r[2] * r[3] < ww * wh]
+    if not inside:
+        raise ChartNotIsolated("could not tell the chart apart from the rest of the window")
+    x, y, w, h = min(inside, key=lambda r: r[2] * r[3])
+    sx, sy = image[0] / ww, image[1] / wh
+    left, top = max(0, round((x - wx) * sx)), max(0, round((y - wy) * sy))
+    right = min(image[0], round((x - wx + w) * sx))
+    bottom = min(image[1], round((y - wy + h) * sy))
+    return left, top, right - left, bottom - top
+
+
+def sips_argv(src: Path, dst: Path, max_side: int = MAX_SIDE,
+              quality: int = QUALITY) -> list[str]:
+    """The ``sips`` command that resizes and re-encodes one capture."""
+    return ["sips", "-Z", str(max_side),
+            "-s", "format", "jpeg",
+            "-s", "formatOptions", str(quality),
+            str(src), "--out", str(dst)]
+
+
+def as_reply(jpeg: bytes) -> str:
+    """A JPEG, as the one-line text reply the relay carries."""
+    return PREFIX + base64.b64encode(jpeg).decode("ascii")
+
+
+def shrink(png: bytes) -> bytes:
+    """Re-encode a PNG capture as a downscaled JPEG."""
+    with tempfile.TemporaryDirectory() as tmp:
+        src, dst = Path(tmp) / "chart.png", Path(tmp) / "chart.jpg"
+        src.write_bytes(png)
+        subprocess.run(sips_argv(src, dst), check=True, capture_output=True)
+        return dst.read_bytes()

chartremotely/studies.py

@@ -0,0 +1,265 @@
+"""Manage the chart's studies.
+
+Not on the voice path - this is the one-time setup that puts a useful chart
+on the wall. It drives thinkorswim's Edit Studies dialog, which behaves
+differently from the chart itself in several ways worth knowing:
+
+* the Studies toolbar control is a toggle that can be left "on" with no menu
+  showing, so a blind press closes it instead of opening it
+* its menu items answer to ``AXPick``
+* the study list rows answer to NEITHER press nor keyboard - selecting one
+  needs a real click, and "Add selected" stays greyed until something is
+  genuinely selected
+* button captions live in ``AXDescription``, not ``AXTitle``
+* its combo boxes are not settable, but accept type-ahead once focused:
+  send "d" and CHART becomes DAY
+"""
+
+from __future__ import annotations
+
+import time
+
+from . import ax, config, layout
+
+DIALOG = "Edit Studies and Strategies"
+
+# A chart for reading structure: where price traded, whether volatility is
+# compressed, and the session's volume-weighted mean.
+PRESET = (
+    ("VolumeProfile", None),
+    ("squeeze", "TTM_Squeeze"),
+    ("vwap", "VWAP"),      # the period-resetting one, NOT AnchoredVWAP
+)
+
+
+class DialogError(RuntimeError):
+    """The studies dialog could not be opened or driven."""
+
+
+def _dialog(ax_app):
+    for window in ax.attr(ax_app, "AXWindows") or []:
+        if (ax.attr(window, "AXTitle") or "") == DIALOG:
+            return window
+    return None
+
+
+def _labelled(element, caption: str) -> bool:
+    return caption in (ax.attr(element, "AXTitle"), ax.attr(element, "AXDescription"))
+
+
+def _button(root, caption: str):
+    hits = ax.find(root, role="AXButton", predicate=lambda el: _labelled(el, caption))
+    return hits[0] if hits else None
+
+
+def open_dialog(app=None):
+    """Studies toolbar -> "Edit studies...". Returns the dialog element."""
+    app = app or ax.running_app()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    if _dialog(ax_app) is not None:
+        return _dialog(ax_app)
+
+    prefix = config.load()["window_prefix"]
+    spot = layout.find_in_panes(
+        ax_app, prefix,
+        lambda el: el is not None and ax.attr(el, "AXRole") == "AXCheckBox"
+        and _labelled(el, "Studies"))
+    if spot is None:
+        raise DialogError("Studies control not found; is a chart visible?")
+
+    toggle = ax.element_at(ax_app, *spot)
+    # Cycle a stuck-open toggle: pressing it while already "on" would close
+    # the menu, and the stale items left behind do not respond to AXPick.
+    if ax.attr(toggle, "AXValue") in (0, "0", False, None):
+        ax.perform(toggle, "AXPress")
+        time.sleep(1.4)
+    else:
+        ax.perform(toggle, "AXPress")
+        time.sleep(0.8)
+        ax.perform(toggle, "AXPress")
+        time.sleep(1.4)
+
+    item = None
+    for window in ax.attr(ax_app, "AXWindows") or []:
+        for candidate in ax.find(window, role="AXMenuItem"):
+            label = (ax.attr(candidate, "AXTitle") or ax.attr(candidate, "AXValue")
+                     or ax.attr(candidate, "AXDescription") or "")
+            if str(label).strip().lower().startswith("edit studies"):
+                item = candidate
+                break
+        if item:
+            break
+    if item is None:
+        raise DialogError("'Edit studies...' not found in the Studies menu")
+
+    ax.perform(item, "AXPick")   # menu items take AXPick, not AXPress
+    time.sleep(3.0)
+    dialog = _dialog(ax_app)
+    if dialog is None:
+        raise DialogError("the studies dialog did not open")
+    return dialog
+
+
+def applied(ax_app=None) -> list[str]:
+    """Studies currently on the chart."""
+    dialog = _dialog(ax_app or ax.handle())
+    if dialog is None:
+        return []
+    names = []
+    for element in ax.find(dialog, role="AXStaticText"):
+        value = ax.attr(element, "AXValue")
+        if isinstance(value, str) and "(" in value and value.strip():
+            names.append(value.strip()[:46])
+    return list(dict.fromkeys(names))   # the dialog renders each row twice
+
+
+def _row_label(row) -> str:
+    found = []
+    ax.walk(row, lambda el: found.append(
+        ax.attr(el, "AXValue") or ax.attr(el, "AXTitle") or ax.attr(el, "AXDescription")))
+    return next((str(v).strip() for v in found if isinstance(v, str) and v.strip()), "")
+
+
+def add(search: str, exact: str | None = None, app=None) -> bool:
+    """Filter the catalogue and add one study.
+
+    ``exact`` matters: the list is alphabetical, so searching "vwap" offers
+    AnchoredVWAP first and a naive "take the first row" picks the wrong one.
+    """
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    ax_app = ax.handle(app)
+    dialog = _dialog(ax_app)
+    if dialog is None:
+        raise DialogError("the studies dialog is not open")
+    want = (exact or search).lower()
+
+    # The filter field is the text field inside a combo box - the same
+    # distinctive shape as the chart's symbol entry. Picking "the first wide
+    # text field" grabs something else and the catalogue never filters,
+    # leaving the category tree ("All Studies", "Alpha Studies") in view.
+    def _is_filter(element):
+        parent = ax.attr(element, "AXParent")
+        return bool(parent is not None and ax.attr(parent, "AXRole") == "AXComboBox")
+
+    fields = ax.find(dialog, role="AXTextField", predicate=_is_filter)
+    if not fields:
+        raise DialogError("the study filter field was not found")
+    ax.set_attr(fields[0], "AXFocused", True)
+    time.sleep(0.3)
+    ax.key(ax.KEYCODE["a"], 1 << 20, pid)      # command-A
+    time.sleep(0.1)
+    ax.type_text(search, pid)
+    time.sleep(1.2)
+
+    rows = ax.find(dialog, role="AXRow",
+                   predicate=lambda el: (ax.position(el) or type("", (), {"x": 9e9})).x < 900)
+    target = next((r for r in rows if _row_label(r).lower() == want), None)
+    if target is None:
+        raise DialogError(f"no study named {want!r}; offered: "
+                          f"{[_row_label(r) for r in rows][:5]}")
+    button = _button(dialog, "Add selected")
+    if button is None:
+        raise DialogError("'Add selected' not found")
+
+    # Rows answer to neither AXPress nor the keyboard: only a real click
+    # selects one, and until one is selected the button stays greyed.
+    spot, target_spot = ax.centre(button), ax.centre(target)
+    blockers = ax.occluders_at(*target_spot, pid) + ax.occluders_at(*spot, pid)
+    hidden = ax.hide_apps(list(dict.fromkeys(blockers)))
+    try:
+        ax.click(*target_spot, pid)
+        time.sleep(0.6)
+        ax.click(*spot, pid)
+        time.sleep(1.4)
+    finally:
+        ax.unhide_apps(hidden)
+    return True
+
+
+def press(caption: str, app=None) -> bool:
+    """Press a labelled button in the dialog."""
+    app = app or ax.running_app()
+    dialog = _dialog(ax.handle(app))
+    button = _button(dialog, caption) if dialog else None
+    if button is None:
+        return False
+    return ax.perform(button, "AXPress")
+
+
+def setup(row_height: str | None = None, per: str = "CHART", app=None) -> list[str]:
+    """Rebuild the study set from scratch. Idempotent.
+
+    ``row_height`` should match the underlying's strike increment so profile
+    buckets land on tradable strikes.
+    """
+    app = app or ax.running_app()
+    cfg = config.load()
+    height = row_height or cfg["row_height"]
+    open_dialog(app)
+    press("Remove all", app)
+    time.sleep(0.8)
+    for search, exact in PRESET:
+        add(search, exact, app)
+    configure_volume_profile(height, per, app)
+    # Read the result BEFORE closing: applied() inspects the dialog, which
+    # no longer exists once OK is pressed.
+    result = applied()
+    press("OK", app)
+    time.sleep(2.5)
+    config.update(row_height=height)
+    return result
+
+
+def configure_volume_profile(row_height: str = "1.0", per: str = "CHART", app=None) -> bool:
+    """Set the profile's row height and period in its customiser."""
+    app = app or ax.running_app()
+    ax_app = ax.handle(app)
+    dialog = _dialog(ax_app)
+    if dialog is None:
+        raise DialogError("the studies dialog is not open")
+
+    rows = [el for el in ax.find(dialog, role="AXStaticText")
+            if str(ax.attr(el, "AXValue") or "").startswith("VolumeProfile")]
+    if not rows:
+        raise DialogError("VolumeProfile is not in the applied list")
+    # Find the row's settings control structurally: the buttons sharing its
+    # vertical band, rightmost last. A fixed pixel offset from the label
+    # would break the moment the dialog is resized or relaid out.
+    row_spot = ax.centre(rows[0])
+
+    def _same_band(element):
+        p, s = ax.position(element), ax.size(element)
+        return bool(p and s and p.y <= row_spot[1] <= p.y + s.height
+                    and p.x > row_spot[0])
+
+    controls = sorted(ax.find(dialog, role="AXButton", predicate=_same_band),
+                      key=lambda el: ax.position(el).x)
+    if not controls:
+        raise DialogError("the VolumeProfile settings control was not found")
+    gear = controls[-1]
+    ax.perform(gear, "AXPress")
+    time.sleep(2.5)
+
+    sheet = next((w for w in ax.attr(ax_app, "AXWindows") or []
+                  if (ax.attr(w, "AXTitle") or "").startswith("VolumeProfile")), None)
+    if sheet is None:
+        raise DialogError("the VolumeProfile customiser did not open")
+
+    combos = sorted(ax.find(sheet, role="AXComboBox"),
+                    key=lambda el: (ax.position(el).y, ax.position(el).x))
+    if len(combos) < 3:
+        raise DialogError("unexpected customiser layout")
+    # Combos are not settable, but type-ahead works once focused.
+    for combo, letter in ((combos[0], "c"), (combos[2], per[0].lower())):
+        ax.set_attr(combo, "AXFocused", True)
+        time.sleep(0.35)
+        ax.key(ax.KEYCODE[letter], 0, app.processIdentifier())
+        time.sleep(0.7)
+
+    ok = _button(sheet, "OK")
+    if ok is not None:
+        ax.perform(ok, "AXPress")
+        time.sleep(2.0)
+    return True

chartremotely/symbol.py

@@ -0,0 +1,160 @@
+"""Drive the chart's symbol field.
+
+``AXValue`` on that field is read-only, so the symbol cannot be written
+directly. ``AXFocused`` *is* settable, so the field is focused and typed
+into - which is also why the vocabulary can be kept narrow: this module can
+only ever put text in one box.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+import Quartz
+
+from . import ax, config, layout
+
+# Accepts tickers, futures (/ES), indices (.SPX) and share classes (BRK/B).
+TICKER = re.compile(r"^[./$]?[A-Z]{1,6}([/.][A-Z]{1,2})?(:[A-Z]+)?$")
+
+class NotFound(RuntimeError):
+    """The symbol field could not be located or did not validate."""
+
+
+def to_ticker(text: str) -> str:
+    """Normalise a ticker. Name resolution happens in :mod:`resolve`."""
+    t = re.sub(r"[^A-Z0-9./$-]", "", text.strip().upper())
+    # The SEC writes share classes as BRK-B; thinkorswim wants BRK/B.
+    return re.sub(r"-([A-Z]{1,2})$", r"/\1", t)
+
+
+def validate(element) -> tuple[bool, str]:
+    """True only for something that really is a symbol entry field.
+
+    This is the guard that keeps a stale offset from typing a ticker into
+    whatever else happens to be at those coordinates.
+    """
+    if element is None or ax.attr(element, "AXRole") != "AXTextField":
+        return False, "not a text field"
+    parent = ax.attr(element, "AXParent")
+    if parent is None or ax.attr(parent, "AXRole") != "AXComboBox":
+        return False, "parent is not a combo box"
+    if not ax.settable(element, "AXFocused"):
+        return False, "field does not accept focus"
+    value = ax.attr(element, "AXValue")
+    if not isinstance(value, str) or not TICKER.match(value.strip()):
+        return False, f"current value {value!r} is not ticker-shaped"
+    return True, value.strip()
+
+
+def discover(ax_app, window_prefix: str) -> tuple[int, int] | None:
+    """Find the symbol field without assuming where the chart is.
+
+    Searches each pane the accessibility tree reports, relative to that
+    pane's own bounds. No screen coordinates are assumed, so a user whose
+    chart sits bottom-right - or who rearranges it at lunchtime - is found
+    the same way.
+    """
+    return layout.find_in_panes(
+        ax_app, window_prefix, lambda el: validate(el)[0])
+
+
+def discover_all(ax_app, window_prefix: str) -> list[tuple[int, int]]:
+    """Every symbol field on screen, for layouts holding several charts."""
+    hits = []
+    for rect in layout.panes(ax_app, window_prefix):
+        hits += layout.scan_all(ax_app, rect, lambda el: validate(el)[0])
+    return hits
+
+
+def learn(app=None) -> dict:
+    """Locate the field and record its window-relative offset."""
+    app = app or ax.running_app()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    cfg = config.load()
+    found = discover(ax_app, cfg["window_prefix"])
+    if found is None:
+        raise NotFound("no symbol field found; is a chart visible?")
+    win = ax.window(ax_app, cfg["window_prefix"])
+    if win is None:
+        raise NotFound(f"no window titled {cfg['window_prefix']!r}")
+    origin = ax.position(win)
+    return config.update(symbol_dx=int(found[0] - origin.x),
+                         symbol_dy=int(found[1] - origin.y))
+
+
+def locate(ax_app, cfg: dict):
+    """Resolve the field through the window's CURRENT position.
+
+    The stored offset only proposes where to look; validation decides
+    whether to act. A small ring absorbs minor layout drift, and a full
+    rediscovery handles the rest.
+    """
+    win = ax.window(ax_app, cfg["window_prefix"])
+    if win is None:
+        raise NotFound(f"no window titled {cfg['window_prefix']!r}")
+    origin = ax.position(win)
+
+    if cfg.get("symbol_dx") is not None:
+        x, y = int(origin.x) + cfg["symbol_dx"], int(origin.y) + cfg["symbol_dy"]
+        ok, info = validate(ax.element_at(ax_app, x, y))
+        if ok:
+            return ax.element_at(ax_app, x, y), info
+        for r in (4, 8, 12):
+            for dx, dy in ((r, 0), (-r, 0), (0, r), (0, -r), (r, r), (-r, -r)):
+                ok, info = validate(ax.element_at(ax_app, x + dx, y + dy))
+                if ok:
+                    return ax.element_at(ax_app, x + dx, y + dy), info
+
+    found = discover(ax_app, cfg["window_prefix"])
+    if found is None:
+        raise NotFound("symbol field did not validate and could not be rediscovered")
+    config.update(symbol_dx=int(found[0] - origin.x),
+                  symbol_dy=int(found[1] - origin.y))
+    element = ax.element_at(ax_app, *found)
+    return element, validate(element)[1]
+
+
+def current(app=None) -> str:
+    """What the field reports.
+
+    Note this can be STALE: thinkorswim does not push accessibility updates,
+    so after a change it may still report the previous symbol. Use it to
+    confirm the field is reachable, never to confirm a change took.
+    """
+    app = app or ax.running_app()
+    ax.activate(app)
+    _, value = locate(ax.handle(app), config.load())
+    return value
+
+
+def show(ticker: str, app=None) -> str:
+    """Put a ticker in the chart. Returns the symbol that was displaced."""
+    ticker = to_ticker(ticker)
+    if not ticker or not TICKER.match(ticker):
+        raise ValueError(f"not a valid ticker: {ticker!r}")
+
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    ax.activate(app)
+    field, previous = locate(ax.handle(app), config.load())
+
+    if not ax.set_attr(field, "AXFocused", True):
+        raise NotFound("could not focus the symbol field")
+    time.sleep(0.15)
+
+    ax.key(ax.KEYCODE["a"], Quartz.kCGEventFlagMaskCommand, pid)
+    time.sleep(0.10)
+    ax.type_text(ticker, pid)
+
+    # thinkorswim pops an autocomplete list as you type. A Return arriving
+    # before it renders is swallowed and the list stays open over the chart.
+    # Let it settle, accept it, then commit - the second Return is a no-op
+    # on an already-committed field.
+    time.sleep(0.35)
+    ax.key(ax.KEY_RETURN, 0, pid)
+    time.sleep(0.25)
+    ax.key(ax.KEY_RETURN, 0, pid)
+    return previous

chartremotely/tailnet.py

@@ -0,0 +1,51 @@
+"""This Mac's place on the patron's tailnet.
+
+The voice Shortcut reaches the agent at an HTTPS address that exists only
+inside the patron's Tailscale network. ``tailscale serve`` gives the Mac that
+address and forwards ``/chart`` to the agent's loopback listener.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+
+DOWNLOAD = "https://tailscale.com/download/mac"
+APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+
+
+class TailnetError(RuntimeError):
+    """Tailscale is missing, signed out, or refused."""
+
+
+def cli() -> str:
+    found = shutil.which("tailscale")
+    if found:
+        return found
+    if shutil.which(APP_CLI) or subprocess.run(["test", "-x", APP_CLI], check=False).returncode == 0:
+        return APP_CLI
+    raise TailnetError(f"Tailscale is not installed. Install it from {DOWNLOAD}, sign in, then run setup again.")
+
+
+def status() -> dict:
+    ran = subprocess.run([cli(), "status", "--json"], capture_output=True, text=True, check=False)
+    if ran.returncode != 0:
+        raise TailnetError("Tailscale is not running or not signed in. Open Tailscale and sign in.")
+    return json.loads(ran.stdout or "{}")
+
+
+def chart_url(state: dict) -> str:
+    """The Shortcut's address: this Mac's tailnet name plus ``/chart``."""
+    name = ((state.get("Self") or {}).get("DNSName") or "").rstrip(".")
+    if not name:
+        raise TailnetError("Tailscale reports no name for this Mac. Is MagicDNS on?")
+    return f"https://{name}/chart"
+
+
+def serve(port: int) -> None:
+    """Forward ``/chart`` on the tailnet address to the agent. Persistent and tailnet-only."""
+    ran = subprocess.run([cli(), "serve", "--bg", "--set-path", "/chart", f"http://127.0.0.1:{port}"],
+                         capture_output=True, text=True, check=False)
+    if ran.returncode != 0:
+        raise TailnetError(f"tailscale serve refused: {(ran.stderr or ran.stdout).strip()[:200]}")