witbitz-code 1.2.0__py3-none-any.whl

witbitz_code/cli.py

@@ -0,0 +1,223 @@
+"""witbitz-code — connect the Spaces Code section to OpenCode on this computer (docs/opencode-relay.md). The same commands
+as the single-file Node download (tools/witbitz-code.mjs):
+
+  witbitz-code pair [--name desk]       scan the QR with the Spaces app → this computer joins that account
+  witbitz-code serve [--port 4096]      start OpenCode (if it is not running) and the connector
+  witbitz-code status                   what this computer is paired with
+  witbitz-code rotate                   new secrets (no scan) — restart serve afterwards
+  witbitz-code unpair [--account a@b]   remove this computer from an account
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from typing import Any
+
+import httpx
+
+from . import __version__
+from . import pair as pair_cmd
+from . import pairings as pp
+from . import codetools, plugins, policy
+from ._js import to_number, truthy
+from .connector import pairings_for_port, start_connector
+
+HELP = f"""witbitz-code {__version__} — reach OpenCode on this computer from the Spaces Code section, end-to-end encrypted.
+
+  pair [--name <name>]         show a QR code; scan it in Spaces (Settings → Back up & recovery → Add a device)
+  serve [--port <n>] [--no-opencode]
+                               start OpenCode on 127.0.0.1 (unless it is already running) and the connector
+  status                       list this computer's pairings
+  rotate [--account <email>]   replace the pairing secret(s) without a scan, then restart serve
+  unpair [--account <email>]   remove this computer from an account
+
+Nothing listens on the network: OpenCode stays on 127.0.0.1 and the connector dials out to wss://code-relay.witbitz.chat.
+"""
+
+
+def _err(msg: str) -> None:
+    print(msg, file=sys.stderr, flush=True)
+
+
+def _flag(args: list[str], name: str, dflt: str = "") -> str:
+    if name not in args:
+        return dflt
+    i = args.index(name)
+    return args[i + 1] if i + 1 < len(args) else ""
+
+
+async def is_listening(port: int) -> bool:
+    try:
+        async with httpx.AsyncClient(trust_env=False, timeout=1.5) as c:
+            await c.get(f"http://127.0.0.1:{port}/")
+        return True
+    except httpx.HTTPError:
+        return False
+
+
+class _Stop:
+    """Ctrl-C / SIGTERM → a flag, installed BEFORE OpenCode is started so a signal during startup cannot orphan it. The
+    first signal asks politely; the handlers are then removed, so a second Ctrl-C interrupts even a stuck shutdown."""
+
+    def __init__(self) -> None:
+        self.event = asyncio.Event()
+        self._loop = asyncio.get_running_loop()
+        self._sigs: list[int] = []
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                self._loop.add_signal_handler(sig, self._fire)
+                self._sigs.append(sig)
+            except (NotImplementedError, RuntimeError):
+                pass  # Windows: Ctrl-C arrives as KeyboardInterrupt, and the finally blocks still stop OpenCode
+
+    def _fire(self) -> None:
+        self.event.set()
+        self.remove()
+
+    def remove(self) -> None:
+        for sig in self._sigs:
+            try:
+                self._loop.remove_signal_handler(sig)
+            except (NotImplementedError, RuntimeError, ValueError):
+                pass
+        self._sigs = []
+
+
+async def _wait_for_stop(stop: _Stop, child: asyncio.subprocess.Process | None) -> int:
+    """Until Ctrl-C / SIGTERM (→ 0) or OpenCode exits (→ its code)."""
+    waiters = [asyncio.ensure_future(stop.event.wait())]
+    if child is not None:
+        waiters.append(asyncio.ensure_future(child.wait()))
+    try:
+        await asyncio.wait(waiters, return_when=asyncio.FIRST_COMPLETED)
+    finally:
+        for w in waiters:
+            w.cancel()
+    if not stop.event.is_set() and child is not None and child.returncode is not None:
+        _err(f"witbitz-code: OpenCode exited ({child.returncode}) — stopping")
+        return child.returncode or 0
+    return 0
+
+
+async def _start_opencode(exe: str, port: int, media: dict | None = None, tools: tuple[dict, dict] | None = None) -> asyncio.subprocess.Process:
+    password = pp.read_env_password()
+    # Subagents ask like their parent, and a refused call does not end the turn (policy.py) — merged by OpenCode over the
+    # user's own config, which is never written.
+    tools_env, tools_config = tools or ({}, {})  # codetools.py: the lsp tool, ast-grep on PATH, the hint naming it
+    env = {**os.environ, **tools_env, **({"OPENCODE_SERVER_PASSWORD": password} if password else {}),
+           "OPENCODE_CONFIG_CONTENT": policy.config_content(os.environ.get("OPENCODE_CONFIG_CONTENT"), policy.merge_config(media or {}, tools_config))}
+    # The resolved path, not "opencode": on Windows the npm install is opencode.cmd, which a bare name does not find.
+    # Its own process group there, so stopping it can take the whole tree (cmd.exe → node) with it.
+    extra = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if sys.platform == "win32" else {}
+    return await asyncio.create_subprocess_exec(exe, "serve", "--port", str(port), "--hostname", "127.0.0.1", env=env, **extra)
+
+
+async def _stop_opencode(child: asyncio.subprocess.Process) -> None:
+    if child.returncode is not None:
+        return
+    if sys.platform == "win32":
+        subprocess.run(["taskkill", "/T", "/F", "/PID", str(child.pid)], capture_output=True, check=False)
+    else:
+        child.terminate()
+    try:
+        await asyncio.wait_for(child.wait(), 5)
+    except asyncio.TimeoutError:
+        child.kill()
+        await child.wait()
+
+
+async def serve(args: list[str]) -> int:
+    port_n = to_number(_flag(args, "--port", "4096"))
+    port = int(port_n) if truthy(port_n) and port_n == port_n and float(port_n).is_integer() else 4096
+    everything = pp.load_pairings(log=lambda _m: None)
+    if not everything:
+        _err("witbitz-code: this computer is not paired yet — run: witbitz-code pair")
+        return 1
+    # One OpenCode per port, one connector per OpenCode: two `serve`s (one per account) must never both answer a channel.
+    pairings = pairings_for_port(everything, port)
+    if not pairings:
+        _err(f"witbitz-code: no pairing uses OpenCode on port {port} — pair with: witbitz-code pair --port {port}")
+        return 1
+    # Our OpenCode plugins — project notes, and the agent's progress updates the Code section shows between its work rows —
+    # written into OpenCode's config folder on every start (plugins.py). OpenCode reads them when it starts, so one already
+    # running picks them up at its next restart.
+    try:
+        if plugins.install():
+            _err(f"witbitz-code: installed OpenCode plugins (project notes, progress updates) in {plugins.opencode_config_dir()}")
+    except OSError as e:
+        _err(f"witbitz-code: could not install the OpenCode plugins in {plugins.opencode_config_dir()} ({e}) — the agent works without progress updates or notes")
+    # The media tools (plugins.py media_config) — one MCP server of image/PDF/video/audio tools, run with this computer's node.
+    media, note = plugins.media_config()
+    if note:
+        _err(note)
+    # Structure (codetools.py): OpenCode's lsp tool, ast-grep fetched once (pinned), and the hint that names it.
+    tools_env, tools_config, note = await asyncio.to_thread(codetools.code_tools, plugins.opencode_config_dir())
+    if note:
+        _err(note)
+    stop = _Stop()
+    child = None
+    try:
+        if not await is_listening(port) and "--no-opencode" not in args:
+            exe = shutil.which("opencode")
+            if not exe:
+                _err("witbitz-code: OpenCode is not installed (or not on PATH). Install it, then run serve again:")
+                _err("  npm install -g opencode-ai        or        curl -fsSL https://opencode.ai/install | bash")
+                return 1
+            _err(f"witbitz-code: starting OpenCode on 127.0.0.1:{port}")
+            child = await _start_opencode(exe, port, media, (tools_env, tools_config))
+            for _ in range(40):
+                if stop.event.is_set() or child.returncode is not None or await is_listening(port):
+                    break
+                await asyncio.sleep(0.25)
+        if stop.event.is_set():
+            return 0
+        connector = await start_connector(pairings)
+        served = ", ".join(f'"{p.get("name")}" → {p.get("account") or "account"}' for p in pairings)
+        _err(f"witbitz-code: serving {served} through the sealed relay (Ctrl-C to stop)")
+        try:
+            return await _wait_for_stop(stop, child)
+        finally:
+            await connector.aclose()
+    finally:
+        if child is not None:
+            await _stop_opencode(child)
+        stop.remove()
+
+
+async def _main(argv: list[str]) -> int:
+    cmd, rest = (argv[0], argv[1:]) if argv else ("", [])
+    if cmd == "pair":
+        return await pair_cmd.main(rest)
+    if cmd == "serve":
+        return await serve(rest)
+    if cmd == "status":
+        return await pair_cmd.main(["--status"])
+    if cmd == "rotate":
+        return await pair_cmd.main(["--rotate", *rest])
+    if cmd == "unpair":
+        return await pair_cmd.main(["--unpair", *rest])
+    if cmd in ("version", "--version", "-v"):
+        print(__version__)
+        return 0
+    print(HELP)
+    return 2 if cmd and cmd not in ("help", "--help", "-h") else 0
+
+
+def main(argv: list[str] | None = None) -> Any:
+    try:
+        code = asyncio.run(_main(sys.argv[1:] if argv is None else argv))
+    except KeyboardInterrupt:
+        code = 0
+    except Exception as e:  # network failures in pair/rotate/unpair end here, as the JS FATAL does
+        _err(f"witbitz-code: FATAL — {e}")
+        code = 1
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

witbitz_code/codetools.py

@@ -0,0 +1,128 @@
+"""What `serve` adds to the OpenCode it starts so the agent can work on code structurally — the twin of tools/code-tools.mjs.
+
+OpenCode's own `lsp` tool (off by default; OPENCODE_EXPERIMENTAL_LSP_TOOL turns it on), a pinned ast-grep fetched once from
+npm's per-platform @ast-grep/cli packages and put first on the agent's PATH, and a short instructions file naming it —
+written only when it is there. tests/test_codetools.py holds the pins and the hint equal to the JS ones.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import platform as _platform
+import shutil
+import sys
+import tarfile
+import urllib.request
+import uuid
+from pathlib import Path
+
+LSP_TOOL_ENV = {"OPENCODE_EXPERIMENTAL_LSP_TOOL": "true"}
+AST_GREP_VERSION = "0.45.3"
+AST_GREP_ASSETS = {
+    "linux-x64": ("linux-x64-gnu", "53828b0acd21dde9f866be2c8513135bf90db9f0c2d931475b8029c534be4ce9"),
+    "linux-arm64": ("linux-arm64-gnu", "cb2243c783debf759ac3c75390d64c3811b7d6b7e1b742aea0ce61d7c1b136ac"),
+    "darwin-arm64": ("darwin-arm64", "3975513c7cce01bbdc68543c1618aa8b04a75b54fd0142d08805e906dca7cdc7"),
+    "darwin-x64": ("darwin-x64", "75a69dc05c97174749cbb4ff8a79b8b30f4db6b52a5728784a3af3f8364b0559"),
+    "win32-x64": ("win32-x64-msvc", "e11a5f9d6f831ae79d04d6a7430a43de53f903a1333a2d4e8a9fdd3d9df52c92"),
+    "win32-arm64": ("win32-arm64-msvc", "f3ae45e870ae66b1e0cde72bc55f6e349159a7980b5711f0ebad6b9d839cd27c"),
+}
+INSTRUCTIONS_NAME = "witbitz-code-tools.md"
+INSTRUCTIONS = """ast-grep is installed for SYNTAX-AWARE search and rewrite — prefer it to regex or sed for code structure (calls, imports, functions), because it ignores comments and strings:
+- find: `ast-grep run -p 'fetchUser($ID)' -l ts` ($NAME matches one node, $$$ARGS any number)
+- rewrite every match: `ast-grep run -p 'fetchUser($ID)' -r 'loadUser($ID)' -l ts -U`, then review with `git diff`
+Run it as `ast-grep` (on Linux `sg` is a different program).
+
+Tools you may expect from other setups, and what stands in for them here — do not go looking or report them missing:
+- list → glob (file names by pattern) or read on a directory.
+- todoread → todowrite returns the whole list on every write.
+- multiedit / patch → edit, one file at a time, or apply_patch where your model is offered it.
+- websearch → web_search (witbitz-media): confidential, answered by a search agent inside a hardware enclave; then webfetch a source for its full text.
+- browser → browser_open / browser_navigate / browser_snapshot / browser_click / browser_type / browser_key / browser_scroll / browser_back / browser_screenshot, when this computer offers them; act from a snapshot's numbered refs, not from a screenshot.
+- lsp is here when the config enables a language server for the file type (Python: pyright); otherwise run the project's own typecheck or lint.
+"""
+
+
+def _platform_key() -> str:
+    osname = {"linux": "linux", "darwin": "darwin", "win32": "win32"}.get(sys.platform, sys.platform)
+    machine = _platform.machine().lower()
+    arch = {"x86_64": "x64", "amd64": "x64", "aarch64": "arm64", "arm64": "arm64"}.get(machine, machine)
+    return f"{osname}-{arch}"
+
+
+def tools_dir(env: dict | None = None) -> Path:
+    env = os.environ if env is None else env
+    return Path(env.get("WITBITZ_TOOLS_DIR") or (Path.home() / ".cache" / "witbitz" / "tools"))
+
+
+def _download(url: str) -> bytes:
+    with urllib.request.urlopen(url, timeout=120) as r:  # registry.npmjs.org; the bytes are checked against the pin below
+        return r.read()
+
+
+def ensure_ast_grep(env: dict | None = None, root: Path | None = None, key: str | None = None, download=_download, assets=AST_GREP_ASSETS) -> tuple[Path | None, bool, str]:
+    """→ (the directory holding ast-grep or None, fetched now?, why not). Never raises."""
+    env = os.environ if env is None else env
+    root = Path(root) if root else tools_dir(env)
+    key = key or _platform_key()
+    exe = "ast-grep.exe" if key.startswith("win32") else "ast-grep"
+    home = root / f"ast-grep-{AST_GREP_VERSION}"
+    if (home / exe).exists():
+        return home, False, ""
+    if env.get("WITBITZ_TOOLS_FETCH") == "0":
+        return None, False, "fetching is off (WITBITZ_TOOLS_FETCH=0)"
+    if key not in assets:
+        return None, False, f"no ast-grep build for {key}"
+    suffix, pin = assets[key]
+    tmp = root / f"{home.name}.{uuid.uuid4().hex[:8]}"
+    try:
+        data = download(f"https://registry.npmjs.org/@ast-grep/cli-{suffix}/-/cli-{suffix}-{AST_GREP_VERSION}.tgz")
+        got = hashlib.sha256(data).hexdigest()
+        if got != pin:
+            return None, False, f"refused: its SHA-256 is {got}, not the pinned {pin}"
+        tmp.mkdir(parents=True)
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as t:
+            for m in t.getmembers():  # only package/<name> files — never a path that climbs out
+                if m.isfile() and m.name.startswith("package/") and "/" not in m.name[len("package/"):]:
+                    target = tmp / m.name[len("package/"):]
+                    with t.extractfile(m) as src, open(target, "wb") as dst:
+                        shutil.copyfileobj(src, dst)
+                    os.chmod(target, 0o755 if m.mode & 0o111 else 0o644)
+        if not (tmp / exe).exists():
+            return None, False, f"the package has no {exe}"
+        shutil.rmtree(home, ignore_errors=True)
+        tmp.rename(home)
+        return home, True, ""
+    except Exception as e:  # noqa: BLE001 — a computer without it still serves
+        return None, False, str(e) or e.__class__.__name__
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def instructions_config(config_dir: Path) -> dict:
+    f = Path(config_dir) / INSTRUCTIONS_NAME
+    try:
+        same = f.read_text(encoding="utf-8") == INSTRUCTIONS
+    except (OSError, UnicodeDecodeError):
+        same = False
+    if not same:
+        f.parent.mkdir(parents=True, exist_ok=True)
+        f.write_text(INSTRUCTIONS, encoding="utf-8", newline="")
+    return {"instructions": [str(f)]}
+
+
+def code_tools(config_dir: Path, env: dict | None = None, **kw) -> tuple[dict, dict, str]:
+    """→ (env additions, config block, a line for the log or "")."""
+    env = os.environ if env is None else env
+    home, fetched, why = ensure_ast_grep(env, **kw)
+    add = dict(LSP_TOOL_ENV)
+    config: dict = {}
+    if home:
+        add["PATH"] = f"{home}{os.pathsep}{env.get('PATH', '')}"
+        try:
+            config = instructions_config(config_dir)
+        except OSError:
+            pass
+    note = (f"witbitz-code: fetched ast-grep {AST_GREP_VERSION} into {home} (pinned SHA-256)" if fetched else "") if home else f"witbitz-code: no ast-grep ({why}) — the agent works without it"
+    return add, config, note

witbitz_code/compress.py

@@ -0,0 +1,25 @@
+"""gzip codec for synced account docs — a port of spaces/public/compress.js.
+
+Large index docs are wrapped { z: <gzip, standard base64> } to dodge the store's 413 ceiling; small docs stay PLAIN so any
+reader unwraps transparently. The compressed bytes need not match the browser's, only open there — the tests prove both
+directions.
+"""
+
+from __future__ import annotations
+
+import gzip
+from typing import Any
+
+from . import _js
+
+HAS_GZIP = True
+json_bytes = _js.json_bytes
+
+
+def gzip_b64(obj: Any) -> str:
+    data = _js.stringify(None if obj is _js.UNDEFINED else obj).encode("utf-8")
+    return _js.btoa(gzip.compress(data, mtime=0))
+
+
+def gunzip_b64(b64: str) -> Any:
+    return _js.parse(gzip.decompress(_js.atob(b64)).decode("utf-8-sig", "replace"))

witbitz_code/computers.py

@@ -0,0 +1,189 @@
+"""The account's PAIRED COMPUTERS registry (docs/opencode-relay.md §3.1) — a port of spaces/public/codeComputers.js.
+
+A sealed `op:'state'` doc named 'computers' in the account's index room. Every signed-in device reads it and the pairing
+tool writes it, so there is ONE merge rule for all of them, defined in the JS module and reproduced here exactly:
+
+  { v: 1, computers: { <id>: { name, relay, secret, pairedAt, mod } | { removed: true, mod } } }
+
+Last-writer-wins PER ENTRY on `mod`; on a tie a removal wins. A removal is a tombstone that keeps no secret, so an unpair
+propagates instead of being re-added by a device that has not heard of it yet.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import time
+from typing import Any
+from urllib.parse import unquote
+
+from . import _js
+
+COMPUTERS_DOC = "computers"
+
+_ID = re.compile(r"[A-Za-z0-9_-]{8,64}")
+_SECRET = re.compile(r"[A-Za-z0-9_-]{43}")
+
+# ── okRelay: `new URL(u)` is wss:, or ws: on localhost ────────────────────────────────────────────────────────────────
+# A WHATWG-URL subset, enough to agree with the browser on what the registry may hold: scheme, authority, port, and the
+# IPv4 shorthands (ws://127.1 IS 127.0.0.1 to a browser).
+_FORBIDDEN_HOST = re.compile(r"[\x00-\x20#%/:<>?@\[\\\]^|\x7f]")
+
+
+def _ipv4_number(part: str) -> int | None:
+    if part == "":
+        return None
+    try:
+        if re.fullmatch(r"0[xX][0-9a-fA-F]*", part):
+            return int(part[2:] or "0", 16)
+        if len(part) > 1 and part.startswith("0"):
+            return int(part[1:], 8) if re.fullmatch(r"[0-7]+", part[1:]) else None
+        return int(part) if re.fullmatch(r"[0-9]+", part) else None
+    except ValueError:
+        return None
+
+
+def _parse_host(host: str) -> str | None:
+    """Host → its serialized form, or None when a browser would reject the URL."""
+    if host.startswith("["):
+        return host.lower() if re.fullmatch(r"\[[0-9A-Fa-f:.]*:[0-9A-Fa-f:.]*\]", host) else None
+    try:
+        host = unquote(host, errors="strict")
+    except UnicodeDecodeError:
+        return None
+    host = host.lower()
+    if host == "" or _FORBIDDEN_HOST.search(host):
+        return None
+    parts = host.split(".")
+    if parts[-1] == "" and len(parts) > 1:
+        parts = parts[:-1]
+    last = parts[-1]
+    if re.fullmatch(r"[0-9]+", last) or re.fullmatch(r"0[xX][0-9a-fA-F]*", last):  # "ends in a number" → must be IPv4
+        nums = [_ipv4_number(p) for p in parts]
+        if len(parts) > 4 or any(n is None for n in nums) or any(n > 255 for n in nums[:-1]):
+            return None
+        if nums[-1] >= 256 ** (5 - len(nums)):
+            return None
+        value = sum(n * 256 ** (3 - i) for i, n in enumerate(nums[:-1])) + nums[-1]
+        return ".".join(str((value >> s) & 255) for s in (24, 16, 8, 0))
+    return host
+
+
+def ok_relay(u: Any) -> bool:
+    s = _js.js_string(u)
+    s = re.sub(r"\A[\x00-\x20]+|[\x00-\x20]+\Z", "", s)
+    s = re.sub(r"[\t\n\r]", "", s)
+    m = re.match(r"([A-Za-z][A-Za-z0-9+.-]*):", s)
+    if not m:
+        return False
+    scheme = m.group(1).lower()
+    if scheme not in ("ws", "wss"):
+        return False
+    rest = re.sub(r"\A[/\\]*", "", s[m.end():])  # special schemes: any run of slashes or backslashes, even none
+    authority = re.split(r"[/\\?#]", rest, maxsplit=1)[0]
+    if "@" in authority:
+        authority = authority.rsplit("@", 1)[1]
+    hp = re.fullmatch(r"(\[[^\]]*\]|[^:]*)(?::([0-9]*))?", authority)
+    if not hp:
+        return False
+    if hp.group(2) and int(hp.group(2)) > 65535:
+        return False
+    host = _parse_host(hp.group(1))
+    if host is None:
+        return False
+    return scheme == "wss" or host in ("127.0.0.1", "localhost")
+
+
+def _num(v: Any) -> float:
+    """A real number — not true, not "0x10", not [7]."""
+    return _js.clean_number(v) if _js.is_num(v) and math.isfinite(v) and v > 0 else 0
+
+
+# ── the registry ──────────────────────────────────────────────────────────────────────────────────────────────────────
+def norm_entry(e: Any) -> dict | None:
+    """One entry → its canonical shape, or None when it is not usable."""
+    if not isinstance(e, dict):
+        return None  # (an array is an object to JS, but has no `mod`, so it ends here too)
+    get = e.get
+    mod = _num(get("mod", _js.UNDEFINED))
+    if not mod:
+        return None
+    if _js.truthy(get("removed", _js.UNDEFINED)):
+        return {"removed": True, "mod": mod}
+    secret, relay = get("secret", _js.UNDEFINED), get("relay", _js.UNDEFINED)
+    if not isinstance(secret, str) or not _SECRET.fullmatch(secret) or not ok_relay(relay):
+        return None
+    name = get("name", _js.UNDEFINED)
+    return {
+        # cut by character (code point, as Array.from), never mid-emoji
+        "name": "".join(list(_js.utf16_join([_js.js_string(name if _js.truthy(name) else "computer")]))[:80]),
+        "relay": _js.js_string(relay),
+        "secret": secret,
+        "pairedAt": _num(get("pairedAt", _js.UNDEFINED)) or mod,
+        "mod": mod,
+    }
+
+
+def norm_registry(doc: Any) -> dict:
+    """Any doc (or nothing) → {v: 1, computers: {…}} with only well-formed entries."""
+    out: dict = {"v": 1, "computers": {}}
+    src = doc.get("computers") if isinstance(doc, dict) else None
+    if not isinstance(src, dict):
+        return out  # (an array here has only index keys, which no id can match)
+    for cid, e in src.items():
+        # An id is only ever data, even one spelled like a built-in ("constructor", "__proto__") — the JS side keeps its
+        # entry maps prototype-free for exactly this.
+        if not isinstance(cid, str) or not _ID.fullmatch(cid):
+            continue
+        n = norm_entry(e)
+        if n:
+            out["computers"][cid] = n
+    return out
+
+
+def merge_registry(a: Any, b: Any) -> dict:
+    """Merge two registries: per id the higher `mod` wins; a tie goes to the removal. Pure."""
+    x, y = norm_registry(a), norm_registry(b)
+    out = {"v": 1, "computers": dict(x["computers"])}
+    for cid, e in y["computers"].items():
+        cur = out["computers"].get(cid)
+        if cur is None or e["mod"] > cur["mod"] or (e["mod"] == cur["mod"] and e.get("removed") and not cur.get("removed")):
+            out["computers"][cid] = e
+    return out
+
+
+def same_registry(a: Any, b: Any) -> bool:
+    return _js.stringify(_sort_keys(norm_registry(a))) == _js.stringify(_sort_keys(norm_registry(b)))
+
+
+def _sort_keys(r: dict) -> dict:
+    return {"v": 1, "computers": {cid: r["computers"][cid] for cid in sorted(r["computers"])}}
+
+
+def live_computers(reg: Any) -> list[dict]:
+    """The computers you can connect to, oldest pairing first: [{id, name, relay, secret}]."""
+    entries = [(cid, e) for cid, e in norm_registry(reg)["computers"].items() if not e.get("removed")]
+    entries.sort(key=lambda p: (p[1]["pairedAt"], p[0].encode("utf-16-be", "surrogatepass")))
+    return [{"id": cid, "name": e["name"], "relay": e["relay"], "secret": e["secret"]} for cid, e in entries]
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def with_computer(reg: Any, cid: str, entry: dict, now: float | None = None) -> dict:
+    """Add or update one computer (the pairing tool's write)."""
+    now = _now_ms() if now is None else now
+    prev = norm_registry(reg)["computers"].get(cid)
+    mod = max(now, prev["mod"] + 1 if prev else 0)
+    new = {k: entry[k] for k in ("name", "relay", "secret") if k in entry}
+    new["pairedAt"] = prev["pairedAt"] if prev and not prev.get("removed") else now
+    new["mod"] = mod
+    return merge_registry(reg, {"computers": {cid: new}})
+
+
+def without_computer(reg: Any, cid: str, now: float | None = None) -> dict:
+    """Tombstone one computer (unpair / "Remove" in Settings)."""
+    now = _now_ms() if now is None else now
+    prev = norm_registry(reg)["computers"].get(cid)
+    return merge_registry(reg, {"computers": {cid: {"removed": True, "mod": max(now, prev["mod"] + 1 if prev else 0)}}})