unstrap 0.1.0__py3-none-any.whl

unstrap/__init__.py

@@ -0,0 +1,3 @@
+"""Unstrap: copy Garmin watch data off the watch over USB (MTP) and upload it."""
+
+__version__ = "0.1.0"

unstrap/api.py

@@ -0,0 +1,186 @@
+"""HTTP client for the Unstrap sync API (plan §4). Retries only what is safe to retry."""
+
+from __future__ import annotations
+
+import platform
+import random
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from unstrap import __version__
+from unstrap.transport import DeviceInfo, RemoteFile
+
+DEFAULT_SERVER = "https://unstrap.sweatstack.no"
+MAX_ATTEMPTS = 5
+
+
+class ApiError(Exception):
+    """The server said no. `message` is meant for people and is printed as-is."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class ClientTooOld(ApiError):
+    pass
+
+
+class ServerUnreachable(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class HashedFile:
+    path: str
+    size: int
+    sha256: str
+
+    def as_json(self) -> dict[str, Any]:
+        return {"path": self.path, "size": self.size, "sha256": self.sha256}
+
+
+def user_agent(mtp_rs_version: str | None) -> str:
+    system = f"{platform.system()} {platform.machine()}".strip()
+    return f"unstrap/{__version__} ({system}; mtp-rs/{mtp_rs_version or 'none'})"
+
+
+class Api:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_SERVER,
+        *,
+        agent: str | None = None,
+        client: httpx.Client | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.Client(timeout=httpx.Timeout(60.0, connect=15.0))
+        self._agent = agent or user_agent(None)
+        self._sleep = sleep
+
+    def close(self) -> None:
+        self._client.close()
+
+    # -- plumbing ---------------------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        token: str | None = None,
+        json: Any = None,
+        content: bytes | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        h = {"user-agent": self._agent, **(headers or {})}
+        if token:
+            h["authorization"] = f"Bearer {token}"
+        url = f"{self.base_url}/api/v1{path}"
+        last: Exception | None = None
+        for attempt in range(MAX_ATTEMPTS):
+            try:
+                res = self._client.request(method, url, json=json, content=content, headers=h)
+            except httpx.TransportError as e:
+                last = e
+                self._backoff(attempt, None)
+                continue
+            if res.status_code == 429 or res.status_code >= 500:
+                last = ApiError(res.status_code, *_error(res))
+                self._backoff(attempt, res.headers.get("retry-after"))
+                continue
+            if res.status_code >= 400:
+                code, message = _error(res)
+                if res.status_code == 426:
+                    raise ClientTooOld(426, code, message)
+                raise ApiError(res.status_code, code, message)
+            try:
+                data: dict[str, Any] = res.json()
+            except ValueError as e:
+                # E.g. a captive portal or proxy answering in HTML (review M3).
+                raise ServerUnreachable(
+                    f"Unexpected answer from {self.base_url} (a Wi-Fi login page or proxy?)"
+                ) from e
+            return data
+        if isinstance(last, ApiError):
+            raise last
+        raise ServerUnreachable(f"Can't reach {self.base_url}: {last}")
+
+    def _backoff(self, attempt: int, retry_after: str | None) -> None:
+        if attempt + 1 >= MAX_ATTEMPTS:
+            return
+        if retry_after and retry_after.isdigit():
+            delay = min(float(retry_after), 60.0)
+        else:
+            delay = min(2.0**attempt, 30.0) * (0.5 + random.random() / 2)
+        self._sleep(delay)
+
+    # -- endpoints --------------------------------------------------------------------------------
+
+    def healthz(self) -> bool:
+        try:
+            res = self._client.get(f"{self.base_url}/healthz", headers={"user-agent": self._agent})
+        except httpx.TransportError:
+            return False
+        return res.status_code == 200
+
+    def start(self, device: DeviceInfo, listing: Sequence[RemoteFile]) -> dict[str, Any]:
+        dev: dict[str, Any] = {"usb_serial": device.usb_serial, "unit_id": device.unit_id}
+        if device.product:
+            dev["product"] = device.product[:100]
+        if device.firmware:
+            dev["firmware"] = device.firmware[:32]
+        body = {"device": dev, "listing": [{"path": f.path, "size": f.size} for f in listing]}
+        return self._request("POST", "/syncs", json=body)
+
+    def prove(
+        self, sync_id: int, token: str, nonce: str, proofs: list[dict[str, str]]
+    ) -> dict[str, Any]:
+        body = {"nonce": nonce, "proofs": proofs}
+        return self._request("POST", f"/syncs/{sync_id}/prove", token=token, json=body)
+
+    def check(self, sync_id: int, token: str, files: Sequence[HashedFile]) -> list[str]:
+        body = {"files": [f.as_json() for f in files]}
+        res = self._request("POST", f"/syncs/{sync_id}/check", token=token, json=body)
+        return list(res["missing"])
+
+    def put_blob(self, sync_id: int, token: str, file: HashedFile, data: bytes) -> bool:
+        headers = {
+            "unstrap-path": quote(file.path, safe=""),
+            "content-type": "application/octet-stream",
+        }
+        res = self._request(
+            "PUT",
+            f"/syncs/{sync_id}/blobs/{file.sha256}",
+            token=token,
+            content=data,
+            headers=headers,
+        )
+        return bool(res.get("stored"))
+
+    def finish(
+        self,
+        sync_id: int,
+        token: str,
+        files: Sequence[HashedFile],
+        stats: dict[str, int | str | bool],
+        errors: list[str],
+    ) -> dict[str, Any]:
+        body = {"files": [f.as_json() for f in files], "stats": stats, "errors": errors[:100]}
+        return self._request("POST", f"/syncs/{sync_id}/finish", token=token, json=body)
+
+
+def _error(res: httpx.Response) -> tuple[str, str]:
+    try:
+        err = res.json()["error"]
+        return str(err["code"]), str(err["message"])
+    except (ValueError, KeyError, TypeError):
+        return "http_error", f"Server returned HTTP {res.status_code}."

unstrap/cli.py

@@ -0,0 +1,271 @@
+"""`unstrap`: copy a Garmin watch's data off the watch and upload it (plan §5.2).
+
+Headless and non-interactive: it never asks anything, so it runs the same from a terminal,
+cron or the Raspberry Pi box. Human output goes to stderr; `--json` prints a report to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import platform
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TextIO
+
+from unstrap import __version__
+from unstrap.api import DEFAULT_SERVER, Api, ApiError, ClientTooOld, ServerUnreachable, user_agent
+from unstrap.sync import WAIT_FOR_DEVICE_SECONDS, SyncReport, run_sync
+from unstrap.transport import Transport, TransportError
+from unstrap.transport.directory import DirectoryTransport
+from unstrap.transport.mtp_rs import (
+    MISSING_BINARY,
+    SUPPORTED_MTP_RS,
+    MtpRsTransport,
+    find_binary,
+)
+
+# Exit codes (plan §5.2).
+OK, OTHER, NO_DEVICE, SERVER_UNREACHABLE, PARTIAL, TOO_OLD, STUCK = 0, 1, 2, 3, 4, 5, 6
+
+TAGLINE = "Plug in. Pull out. Done."
+LINUX_HELP = "https://unstrap.sweatstack.no/linux"
+
+ADVICE = {
+    "no_device": (
+        "No Garmin watch found. Plug it in at the watch face (no buttons held) and check "
+        "Settings > System > USB Mode is MTP."
+    ),
+    "stuck": "The watch stopped responding. Unplug it, plug it back in, and run unstrap again.",
+    "permission": f"No permission to open the watch over USB. See {LINUX_HELP}",
+    "busy": (
+        "Another program is using the watch (Garmin Express, Android File Transfer, "
+        f"a file manager). Close it and try again. See {LINUX_HELP}"
+    ),
+}
+
+
+class Output:
+    def __init__(self, stream: TextIO, quiet: bool) -> None:
+        self.stream = stream
+        self.quiet = quiet
+
+    def __call__(self, message: str = "") -> None:
+        if not self.quiet:
+            print(message, file=self.stream, flush=True)
+
+
+def _add_common(parser: argparse.ArgumentParser, *, top_level: bool) -> None:
+    """Options accepted before or after the subcommand (review M3: `unstrap sync --json`)."""
+
+    def default(value: object) -> object:
+        # Subcommand copies must not overwrite a value given before the subcommand.
+        return value if top_level else argparse.SUPPRESS
+
+    parser.add_argument(
+        "--server",
+        default=default(os.environ.get("UNSTRAP_SERVER", DEFAULT_SERVER)),
+        help="Unstrap server (env UNSTRAP_SERVER)",
+    )
+    parser.add_argument(
+        "--device", default=default(None), help="USB serial of the watch, if several are connected"
+    )
+    parser.add_argument(
+        "--source",
+        type=Path,
+        default=default(None),
+        help=(
+            "read a copy of the watch's files on this computer (a folder containing GARMIN/, "
+            "or the GARMIN folder itself) instead of the USB watch. Leave out to use the watch."
+        ),
+    )
+    parser.add_argument(
+        "--json", action="store_true", default=default(False), help="print a JSON report on stdout"
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", default=default(False))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="unstrap",
+        description="Your watch data, set free. " + TAGLINE,
+    )
+    parser.add_argument("--version", action="version", version=f"unstrap {__version__}")
+    _add_common(parser, top_level=True)
+    sub = parser.add_subparsers(dest="command")
+    sync = sub.add_parser("sync", help="sync the watch (the default)")
+    _add_common(sync, top_level=False)
+    sync.add_argument("--save", type=Path, help="also keep a complete local copy in this folder")
+    sync.add_argument("--dry-run", action="store_true", help="list the watch; upload nothing")
+    for name, text in [
+        ("info", "show the connected watch; upload nothing"),
+        ("doctor", "check that everything needed for a sync works"),
+    ]:
+        _add_common(sub.add_parser(name, help=text), top_level=False)
+    return parser
+
+
+def make_transport(args: argparse.Namespace) -> Transport:
+    if args.source is not None:
+        return DirectoryTransport(args.source, usb_serial=args.device)
+    binary = find_binary()
+    if binary is None:
+        raise TransportError("other", MISSING_BINARY)
+    return MtpRsTransport(binary, device=args.device)
+
+
+def _mtp_version(transport: Transport) -> str | None:
+    return transport.version() if isinstance(transport, MtpRsTransport) else None
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    command = args.command or "sync"
+    out = Output(sys.stderr, quiet=False)
+    try:
+        if command == "doctor":
+            return doctor(args, out)
+        transport = make_transport(args)
+        if command == "info":
+            return info(transport, args, out)
+        return sync(transport, args, out)
+    except TransportError as e:
+        if e.code in ADVICE:
+            out(ADVICE[e.code])
+            out(f"  Details: {e}")  # always: generic advice must never hide the real reason
+        else:
+            out(str(e) if e.code == "bad_source" else f"Watch error: {e}")
+        return {"no_device": NO_DEVICE, "stuck": STUCK}.get(e.code, OTHER)
+    except ClientTooOld as e:
+        out(e.message)
+        return TOO_OLD
+    except ServerUnreachable as e:
+        out(f"{e}. Check your internet connection and try again.")
+        return SERVER_UNREACHABLE
+    except ApiError as e:
+        out(f"The server refused: {e.message}")
+        return OTHER
+    except KeyboardInterrupt:
+        out("Stopped. Run unstrap again to continue where it stopped.")
+        return OTHER
+
+
+def sync(transport: Transport, args: argparse.Namespace, out: Output) -> int:
+    human = Output(sys.stderr, quiet=args.json)
+    human(f"Unstrap {__version__}. {TAGLINE}")
+    human("Waiting for a Garmin watch...")
+    device = transport.wait_for_device(WAIT_FOR_DEVICE_SECONDS)
+    human(f"Found {device.product or 'a Garmin watch'} (unit ID {device.unit_id})")
+    if getattr(args, "dry_run", False):
+        listing = transport.list_files()
+        total = sum(f.size for f in listing)
+        human(f"Dry run: {len(listing)} files ({total / 1e6:.1f} MB) would be synced.")
+        human("Nothing uploaded.")
+        if args.json:
+            print(json.dumps({"unit_id": device.unit_id, "listed": len(listing), "bytes": total}))
+        return OK
+    api = Api(args.server, agent=user_agent(_mtp_version(transport)))
+    try:
+        report = run_sync(
+            transport,
+            api,
+            say=(lambda m: human(f"  {m}")) if args.verbose else (lambda _m: None),
+            save_dir=getattr(args, "save", None),
+            device=device,
+        )
+    finally:
+        api.close()
+    if args.json:
+        print(json.dumps(report.as_json(), indent=2))
+    else:
+        print_summary(report, args.server, human)
+    return PARTIAL if report.status == "partial" else OK
+
+
+def print_summary(r: SyncReport, server: str, say: Output) -> None:
+    mb = r.uploaded_bytes / 1e6
+    say(f"Read {r.read} new or changed files, uploaded {r.uploaded} ({mb:.1f} MB).")
+    if r.saved:
+        say(f"Saved {r.saved} files to your local copy.")
+    if r.changed:
+        say(
+            f"{len(r.changed)} files changed on the watch during the sync; next sync includes them."
+        )
+    for e in r.errors[:5]:
+        say(f"  problem: {e}")
+    if r.status == "partial":
+        say(f"Some files couldn't be recorded ({len(r.unrecorded)}). Run unstrap again later.")
+    say(f"Done in {r.seconds:.1f} s. You can unplug your watch.")
+    say("")
+    if r.store_status == "claimed":
+        if r.owner_hint:
+            say(f"This watch is linked to {r.owner_hint}. If that isn't you, add it to your own")
+            say(f"account before syncing again: {server}/watches/add?unit={r.unit_id}")
+    else:
+        days = r.retention_days or 30
+        say(f"Not linked to an account yet (kept for {days} days). To add it: sign in at")
+        say(f'{server}, choose "Add a watch", then sync again within 10 minutes.')
+
+
+def info(transport: Transport, args: argparse.Namespace, out: Output) -> int:
+    device = transport.wait_for_device(WAIT_FOR_DEVICE_SECONDS)
+    data = {
+        "product": device.product,
+        "unit_id": device.unit_id,
+        "usb_serial": device.usb_serial,
+        "firmware": device.firmware,
+    }
+    if args.json:
+        print(json.dumps(data, indent=2))
+    else:
+        out(f"{device.product or 'Garmin watch'}")
+        out(f"  Unit ID:    {device.unit_id}   (enter this on the website)")
+        out(f"  USB serial: {device.usb_serial}")
+        out(f"  Firmware:   {device.firmware or 'unknown'}")
+    return OK
+
+
+def doctor(args: argparse.Namespace, out: Output) -> int:
+    """Check every link in the chain and say exactly what to fix (plan §5.2)."""
+    ok = True
+
+    def check(passed: bool, label: str, fix: str = "") -> None:
+        nonlocal ok
+        ok &= passed
+        out(f"[{'ok' if passed else 'FAIL'}] {label}")
+        if not passed and fix:
+            out(f"       {fix}")
+
+    system = f"{platform.system()} {platform.machine()}"
+    out(f"Unstrap {__version__} on {system}, Python {platform.python_version()}")
+    if args.source is None:
+        binary = find_binary()
+        check(binary is not None, f"mtp-rs program: {binary}", MISSING_BINARY)
+        if binary is not None:
+            t = MtpRsTransport(binary, device=args.device)
+            version = t.version()
+            check(
+                version == SUPPORTED_MTP_RS,
+                f"mtp-rs version {version}",
+                f"Expected {SUPPORTED_MTP_RS}. Reinstall: uvx unstrap@latest",
+            )
+            try:
+                d = t.wait_for_device(timeout=5)
+                check(True, f"watch: {d.product} (unit ID {d.unit_id})")
+                check(len(t.list_files()) > 0, "watch files readable", ADVICE["stuck"])
+            except TransportError as e:
+                check(False, "watch", ADVICE.get(e.code, str(e)))
+                if platform.system() == "Linux":
+                    out(f"       On Linux, see {LINUX_HELP} (udev rule, gvfs).")
+    api = Api(args.server)
+    try:
+        check(api.healthz(), f"server {args.server}", "Check your internet connection.")
+    finally:
+        api.close()
+    return OK if ok else OTHER
+
+
+if __name__ == "__main__":
+    sys.exit(main())

unstrap/policy.py

@@ -0,0 +1,76 @@
+"""Folder policy: which files are synced. Mirrors server/src/lib/policy.ts (a test checks it).
+
+The server sends its policy in every `POST /syncs` response; this copy is used before that
+(listing) and as defence in depth: the client never reads anything outside it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class FolderPolicy:
+    folder: str  # e.g. "GARMIN/Activity"
+    immutable: bool
+
+
+FOLDERS: tuple[FolderPolicy, ...] = (
+    FolderPolicy("GARMIN/Activity", immutable=True),
+    FolderPolicy("GARMIN/SUMMARY", immutable=True),
+    FolderPolicy("GARMIN/Monitor", immutable=False),
+    FolderPolicy("GARMIN/Sleep", immutable=False),
+    FolderPolicy("GARMIN/HRVStatus", immutable=False),
+    FolderPolicy("GARMIN/Metrics", immutable=False),
+    FolderPolicy("GARMIN/Debug/MetricsBackup", immutable=False),
+    FolderPolicy("GARMIN/Records", immutable=False),
+    FolderPolicy("GARMIN/Totals", immutable=False),
+    FolderPolicy("GARMIN/Goals", immutable=False),
+    FolderPolicy("GARMIN/Settings", immutable=False),
+    FolderPolicy("GARMIN/Sports", immutable=False),
+    FolderPolicy("GARMIN/Schedule", immutable=False),
+    FolderPolicy("GARMIN/Location", immutable=False),
+    FolderPolicy("GARMIN/Workouts", immutable=False),
+    FolderPolicy("GARMIN/Courses", immutable=False),
+)
+_EXTRA_DIRS = {
+    "GARMIN/Workouts/Guided": "GARMIN/Workouts",
+    "GARMIN/Workouts/Schedule": "GARMIN/Workouts",
+}
+_BY_FOLDER = {p.folder: p for p in FOLDERS}
+
+# Never list or read these: credentials, firmware, maps, crash risk. Reading
+# GARMIN/Debug/err_log.txt locked up a real fenix 6 until it was physically replugged.
+NEVER: tuple[str, ...] = (
+    "GARMIN/Debug",
+    "GARMIN/WIFI",
+    "GARMIN/Apps",
+    "GARMIN/Text",
+    "GARMIN/RemoteSW",
+    "GARMIN/http",
+    "GARMIN/EVNTLOGS",
+    "GARMIN/PointCache",
+    "GARMIN/TempFIT",
+)
+
+_FILENAME = re.compile(r"^(?!\.)[\w.\s()&,!'\[\]+#@-]{1,128}$", re.UNICODE)
+
+
+def policy_for(path: str) -> FolderPolicy | None:
+    """The policy for a watch path like "GARMIN/Activity/x.fit", or None if it isn't synced."""
+    directory, _, name = path.rpartition("/")
+    if not directory or not name.lower().endswith(".fit") or not _FILENAME.match(name):
+        return None
+    if "\x00" in name or "/" in name or "\\" in name:
+        return None
+    return _BY_FOLDER.get(_EXTRA_DIRS.get(directory, directory))
+
+
+def is_synced(path: str) -> bool:
+    return policy_for(path) is not None
+
+
+def is_immutable(path: str) -> bool:
+    p = policy_for(path)
+    return p is not None and p.immutable

unstrap/sync.py

@@ -0,0 +1,267 @@
+"""One sync, end to end (plan §4.1): list → start → prove → [read → check → upload]* → finish.
+
+Pure orchestration: the transport (watch) and API (server) are injected, so this is tested
+without hardware or network.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import shutil
+import tempfile
+import time
+from collections.abc import Callable, Iterator, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from unstrap.api import Api, HashedFile
+from unstrap.transport import DeviceInfo, RemoteFile, Transport, TransportError
+
+WAIT_FOR_DEVICE_SECONDS = 30.0
+BATCH_FILES = 10
+BATCH_BYTES = 5 * 1024 * 1024
+UPLOAD_CONCURRENCY = 6
+
+Say = Callable[[str], None]
+
+
+@dataclass(frozen=True)
+class _Session:
+    """One server-side sync: the API plus this sync's id and capability token."""
+
+    api: Api
+    sync_id: int
+    token: str
+
+
+@dataclass
+class SyncReport:
+    """Everything a person (or `--json`) needs to know about one sync."""
+
+    unit_id: str
+    usb_serial: str
+    product: str | None
+    listed: int = 0
+    read: int = 0
+    uploaded: int = 0
+    uploaded_bytes: int = 0
+    store: str | None = None  # "new" | "existing"
+    status: str | None = None  # "ok" | "partial"
+    store_status: str | None = None  # "claimed" | "unclaimed"
+    owner_hint: str | None = None
+    retention_days: int | None = None
+    unrecorded: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    # Mutable files the watch rewrote between listing and reading; the next sync gets them.
+    changed: list[str] = field(default_factory=list)
+    saved: int = 0
+    seconds: float = 0.0
+
+    def as_json(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def proof_mac(nonce: bytes, data: bytes) -> str:
+    return hmac.new(nonce, data, hashlib.sha256).hexdigest()
+
+
+def b64url_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def batches(
+    paths: Sequence[str], sizes: dict[str, int], max_files: int, max_bytes: int
+) -> Iterator[list[str]]:
+    """Group paths so each batch stays under both limits (a single big file is its own batch)."""
+    batch: list[str] = []
+    total = 0
+    for p in paths:
+        size = sizes.get(p, 0)
+        if batch and (len(batch) >= max_files or total + size > max_bytes):
+            yield batch
+            batch, total = [], 0
+        batch.append(p)
+        total += size
+    if batch:
+        yield batch
+
+
+def run_sync(
+    transport: Transport,
+    api: Api,
+    *,
+    say: Say = lambda _m: None,
+    save_dir: Path | None = None,
+    device: DeviceInfo | None = None,
+    batch_files: int = BATCH_FILES,
+    batch_bytes: int = BATCH_BYTES,
+    clock: Callable[[], float] = time.monotonic,
+) -> SyncReport:
+    started = clock()
+    info = device or transport.wait_for_device(WAIT_FOR_DEVICE_SECONDS)
+    report = SyncReport(unit_id=info.unit_id, usb_serial=info.usb_serial, product=info.product)
+    listing: list[RemoteFile] = transport.list_files()
+    report.listed = len(listing)
+    sizes = {f.path: f.size for f in listing}
+    say(f"Listing {len(listing)} files")
+
+    start = api.start(info, listing)
+    sync_id, token = int(start["sync_id"]), str(start["token"])
+    challenge = start["challenge"]
+    hashed: list[HashedFile] = []
+
+    try:
+        with tempfile.TemporaryDirectory(prefix="unstrap-") as tmp_name:
+            tmp = Path(tmp_name)
+            session = _Session(api, sync_id, token)
+            proved = _prove(transport, session, challenge, sizes, tmp, say)
+            report.store = proved["store"]
+            server_wants = {p for p in proved["fetch"] if p in sizes}
+            fetch = sorted(server_wants)
+            if save_dir is not None:
+                fetch += _missing_from_mirror(listing, save_dir, server_wants)
+            transport.plan(fetch)
+            say(f"Reading {len(fetch)} new or changed files")
+            for i, batch in enumerate(batches(fetch, sizes, batch_files, batch_bytes)):
+                hashed += _upload_batch(
+                    transport, session, batch, tmp / f"b{i}", server_wants, sizes, save_dir, report
+                )
+                say(f"Read {report.read} of {len(fetch)}")
+    finally:
+        transport.close()
+
+    stats: dict[str, int | str | bool] = {
+        "listed": report.listed,
+        "read": report.read,
+        "uploaded": report.uploaded,
+    }
+    done = api.finish(sync_id, token, hashed, stats, report.errors)
+    report.status = done.get("status")
+    report.store_status = done.get("store_status")
+    report.owner_hint = done.get("owner_hint")
+    report.retention_days = done.get("retention_days")
+    report.unrecorded = list(done.get("unrecorded", []))
+    report.seconds = round(clock() - started, 1)
+    return report
+
+
+def _prove(
+    transport: Transport,
+    session: _Session,
+    challenge: dict[str, Any],
+    sizes: dict[str, int],
+    tmp: Path,
+    say: Say,
+) -> dict[str, Any]:
+    """Answer the possession challenge with HMAC(nonce, file bytes) (plan §3.3)."""
+    nonce = b64url_decode(challenge["nonce"])
+    challenged = [p for p in challenge["paths"] if p in sizes]
+    proofs = []
+    if challenged:
+        say("Verifying this watch")
+        # A challenged file may have vanished (e.g. rotated away): just leave it out. Wrong or
+        # missing answers never count against us; any one correct answer proves the watch.
+        got = _fetch_each(transport, challenged, tmp / "proof", report=None)
+        proofs = [{"path": p, "mac": proof_mac(nonce, f.read_bytes())} for p, f in got.items()]
+    return session.api.prove(session.sync_id, session.token, challenge["nonce"], proofs)
+
+
+def _upload_batch(
+    transport: Transport,
+    session: _Session,
+    batch: list[str],
+    batch_dir: Path,
+    server_wants: set[str],
+    sizes: dict[str, int],
+    save_dir: Path | None,
+    report: SyncReport,
+) -> list[HashedFile]:
+    """Read one batch from the watch, then check and upload what the server lacks."""
+    try:
+        got = transport.fetch(batch, batch_dir)
+    except TransportError as e:
+        if e.code != "not_found":
+            raise  # watch gone or stuck: stop; the next sync resumes (plan §4.5)
+        got = _fetch_each(transport, batch, batch_dir, report)
+    files = [HashedFile(p, local.stat().st_size, sha256_file(local)) for p, local in got.items()]
+    report.read += len(files)
+    if save_dir is not None:
+        report.saved += _save(got, save_dir)
+    # A mutable file the watch rewrote since listing no longer matches the listed size; the
+    # server would reject it, and the next sync lists it afresh. Not an error (review M3).
+    for f in files:
+        if f.path in server_wants and f.size != sizes.get(f.path):
+            report.changed.append(f.path)
+    to_server = [f for f in files if f.path in server_wants and f.size == sizes.get(f.path)]
+    if to_server:
+        missing = set(session.api.check(session.sync_id, session.token, to_server))
+        uploads: dict[str, HashedFile] = {}
+        for f in to_server:
+            if f.sha256 in missing:
+                uploads.setdefault(f.sha256, f)  # same content at two paths: upload once
+        # A few uploads in parallel: each is a server round trip of ~0.5 s, so sequential uploads
+        # would dominate a first sync. The server makes quota and bookkeeping atomic (review M2).
+        with ThreadPoolExecutor(max_workers=UPLOAD_CONCURRENCY) as pool:
+            stored = list(
+                pool.map(
+                    lambda f: session.api.put_blob(
+                        session.sync_id, session.token, f, got[f.path].read_bytes()
+                    ),
+                    uploads.values(),
+                )
+            )
+        # Count what the server actually stored (a concurrent duplicate answers stored=false).
+        for f, ok in zip(uploads.values(), stored, strict=True):
+            if ok:
+                report.uploaded += 1
+                report.uploaded_bytes += f.size
+    shutil.rmtree(batch_dir, ignore_errors=True)
+    return to_server
+
+
+def _fetch_each(
+    transport: Transport, batch: list[str], dest: Path, report: SyncReport | None
+) -> dict[str, Path]:
+    """Read files one by one, skipping any that vanished (e.g. Monitor rotation)."""
+    got: dict[str, Path] = {}
+    for p in batch:
+        try:
+            got.update(transport.fetch([p], dest))
+        except TransportError as e:
+            if e.code != "not_found":
+                raise
+            if report is not None:
+                report.errors.append(f"{p}: {e}")
+    return got
+
+
+def _missing_from_mirror(
+    listing: Sequence[RemoteFile], save_dir: Path, already: set[str]
+) -> list[str]:
+    """--save keeps a complete local mirror, including files the server already has."""
+    out = []
+    for f in listing:
+        local = save_dir / f.path
+        if f.path not in already and (not local.is_file() or local.stat().st_size != f.size):
+            out.append(f.path)
+    return out
+
+
+def _save(got: dict[str, Path], save_dir: Path) -> int:
+    for path, local in got.items():
+        target = save_dir / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(local, target)
+    return len(got)

unstrap/transport/__init__.py

@@ -0,0 +1,3 @@
+from unstrap.transport.base import DeviceInfo, RemoteFile, Transport, TransportError
+
+__all__ = ["DeviceInfo", "RemoteFile", "Transport", "TransportError"]

unstrap/transport/base.py

@@ -0,0 +1,71 @@
+"""Read-only access to a watch. There are deliberately no write or delete methods."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Protocol
+
+ErrorCode = Literal["no_device", "stuck", "not_found", "permission", "busy", "bad_source", "other"]
+
+
+class TransportError(Exception):
+    """A watch access problem with a code the CLI maps to advice and an exit code."""
+
+    def __init__(self, code: ErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code: ErrorCode = code
+
+
+_USB_SERIAL = re.compile(r"^[0-9a-f]{12}$")
+
+
+@dataclass(frozen=True)
+class DeviceInfo:
+    usb_serial: str  # 12 lowercase hex digits; low 32 bits = unit ID
+    product: str | None = None
+    firmware: str | None = None
+
+    def __post_init__(self) -> None:
+        if not _USB_SERIAL.match(self.usb_serial):
+            raise TransportError(
+                "other", f"{self.usb_serial!r} is not a Garmin USB serial (12 hex digits)"
+            )
+
+    @property
+    def unit_id(self) -> str:
+        return str(int(self.usb_serial[-8:], 16))
+
+
+@dataclass(frozen=True)
+class RemoteFile:
+    path: str  # "GARMIN/Activity/2026-10-18-12-33-45.fit"
+    size: int
+
+
+class Transport(Protocol):
+    def wait_for_device(self, timeout: float) -> DeviceInfo:
+        """Block until a watch is available (or raise TransportError("no_device"))."""
+        ...
+
+    def list_files(self) -> list[RemoteFile]:
+        """Every file under GARMIN/ that the folder policy syncs (never the NEVER folders)."""
+        ...
+
+    def fetch(self, paths: Sequence[str], dest: Path) -> dict[str, Path]:
+        """Make `paths` readable locally (path → local file). Raises for policy violations.
+
+        Returned files may differ in size from the listing if the watch rewrote them meanwhile;
+        the caller decides what to do with that.
+        """
+        ...
+
+    def plan(self, paths: Sequence[str]) -> None:
+        """Everything this sync will fetch, so the transport can choose how to read it."""
+        ...
+
+    def close(self) -> None:
+        """Release temporary resources."""
+        ...

unstrap/transport/directory.py

@@ -0,0 +1,74 @@
+"""A directory tree as a "watch": tests, development, captured snapshots, mass-storage watches."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+from unstrap.policy import is_synced
+from unstrap.transport.base import DeviceInfo, RemoteFile, TransportError
+
+
+class DirectoryTransport:
+    """Reads a folder that contains `GARMIN/` exactly like the watch exposes it."""
+
+    def __init__(self, root: Path, usb_serial: str | None = None) -> None:
+        # Accept the GARMIN folder itself as well as the folder that contains it.
+        self.root = root.parent if root.name == "GARMIN" and root.is_dir() else root
+        self._usb_serial = usb_serial
+
+    def wait_for_device(self, timeout: float) -> DeviceInfo:
+        garmin = self.root / "GARMIN"
+        if not garmin.is_dir():
+            # Not "no watch found": --source means "read this folder instead of the USB watch",
+            # and a wrong folder must not look like a missing watch.
+            where = "doesn't exist" if not self.root.exists() else "has no GARMIN folder in it"
+            raise TransportError(
+                "bad_source",
+                f"--source {self.root} {where}. --source reads a copy of the watch's files on "
+                "this computer; leave it out to sync the watch on USB.",
+            )
+        xml_path = garmin / "GarminDevice.xml"
+        xml = xml_path.read_text(errors="replace") if xml_path.is_file() else ""
+        serial = self._usb_serial
+        if serial is None:
+            m = re.search(r"<Id>(\d{1,10})</Id>", xml)
+            if not m:
+                raise TransportError(
+                    "not_found", "No unit ID: pass a USB serial or add GarminDevice.xml"
+                )
+            serial = f"{int(m.group(1)):012x}"
+        product = re.search(r"<Description>([^<]{1,100})</Description>", xml)
+        firmware = re.search(r"<SoftwareVersion>([^<]{1,32})</SoftwareVersion>", xml)
+        return DeviceInfo(
+            usb_serial=serial.lower(),
+            product=f"Garmin {product.group(1)}" if product else None,
+            firmware=firmware.group(1) if firmware else None,
+        )
+
+    def list_files(self) -> list[RemoteFile]:
+        garmin = self.root / "GARMIN"
+        files = []
+        for p in sorted(garmin.rglob("*")):
+            rel = p.relative_to(self.root).as_posix()
+            if p.is_file() and is_synced(rel):
+                files.append(RemoteFile(rel, p.stat().st_size))
+        return files
+
+    def fetch(self, paths: Sequence[str], dest: Path) -> dict[str, Path]:
+        out = {}
+        for path in paths:
+            if not is_synced(path):
+                raise TransportError("other", f"refusing to read {path}: outside the folder policy")
+            local = self.root / path
+            if not local.is_file():
+                raise TransportError("not_found", f"{path} disappeared from the watch")
+            out[path] = local  # already local; no copy needed
+        return out
+
+    def plan(self, paths: Sequence[str]) -> None:
+        pass
+
+    def close(self) -> None:
+        pass

unstrap/transport/mtp_rs.py

@@ -0,0 +1,327 @@
+"""Watch access through the `mtp-rs` CLI (plan §5.3). Read-only: only devices/info/ls/get are run.
+
+Behaviour verified against mtp-rs 0.9.1 and a real fenix 6 (fixtures/capture-2026-10-19):
+JSON on stdout, `error: <message>` on stderr, exit codes 0 ok, 1 other (e.g. local path
+exists), 2 no device, 5 remote path not found, 6 open timed out (watch busy or stuck).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import time
+from collections import defaultdict
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from unstrap.policy import NEVER, is_synced
+from unstrap.transport.base import DeviceInfo, ErrorCode, RemoteFile, TransportError
+
+GARMIN_VENDOR_ID = 0x091E
+SUPPORTED_MTP_RS = "0.9.1"
+COMMAND_TIMEOUT_SECONDS = 300
+
+# Cost model for choosing per-file vs whole-folder downloads (measured, plan §4.2).
+SESSION_SECONDS = 0.3
+PER_OBJECT_LISTING_SECONDS = 0.005
+BYTES_PER_SECOND = 2.5e6
+
+Runner = Callable[[list[str]], subprocess.CompletedProcess[str]]
+
+
+# Platform wheels of unstrap bundle mtp-rs here (mtp/build_wheels.py).
+VENDORED = Path(__file__).resolve().parents[1] / "_vendor" / "mtp-rs"
+
+MISSING_BINARY = (
+    f"No mtp-rs program for this computer. Install mtp-rs {SUPPORTED_MTP_RS} "
+    "(https://github.com/vdavid/mtp-rs) and put it on your PATH, or set UNSTRAP_MTP_RS."
+)
+
+
+def find_binary() -> Path | None:
+    """UNSTRAP_MTP_RS, then the copy bundled in the wheel, then mtp-rs on PATH."""
+    override = os.environ.get("UNSTRAP_MTP_RS")
+    if override:
+        return Path(override) if Path(override).is_file() else None
+    if VENDORED.is_file():
+        return VENDORED
+    found = shutil.which("mtp-rs")
+    return Path(found) if found else None
+
+
+@dataclass
+class Listing:
+    files: list[RemoteFile]
+    objects_per_folder: dict[str, int]
+    bytes_per_folder: dict[str, int]  # including subfolders
+    clean_folders: set[str]  # every file below is synced by the policy
+
+
+class MtpRsTransport:
+    def __init__(
+        self,
+        binary: Path,
+        *,
+        device: str | None = None,
+        runner: Runner | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        stuck_retries: int = 2,
+    ) -> None:
+        self.binary = binary
+        self.device = device
+        self._run_override = runner
+        self._sleep = sleep
+        self._stuck_retries = stuck_retries
+        self._listing: Listing | None = None
+        self._planned: dict[str, int] = {}
+        self._cache_root: Path | None = None
+        self._folder_cache: dict[str, Path] = {}
+
+    # -- process plumbing -------------------------------------------------------------------
+
+    def _run(self, args: list[str]) -> subprocess.CompletedProcess[str]:
+        cmd = [str(self.binary), *args]
+        try:
+            if self._run_override is not None:
+                return self._run_override(cmd)
+            return subprocess.run(
+                cmd, capture_output=True, text=True, timeout=COMMAND_TIMEOUT_SECONDS, check=False
+            )
+        except subprocess.TimeoutExpired:
+            # A hung watch: treat like the watch's own "open timed out" (advice: replug).
+            return subprocess.CompletedProcess(cmd, 6, "", "error: mtp-rs did not respond\n")
+        except OSError as e:
+            raise TransportError("other", f"Can't run mtp-rs at {self.binary}: {e}") from e
+
+    def _device_args(self) -> list[str]:
+        return ["--device", self.device] if self.device else []
+
+    def _call(self, *args: str, retry_stuck: bool = True) -> subprocess.CompletedProcess[str]:
+        """Run mtp-rs; map failures to TransportError. Retries 'open timed out' a few times."""
+        attempts = self._stuck_retries + 1 if retry_stuck else 1
+        for attempt in range(attempts):
+            res = self._run([*self._device_args(), *args])
+            if res.returncode == 0:
+                return res
+            code = _error_code(res)
+            if code == "stuck" and attempt + 1 < attempts:
+                self._sleep(2.0)
+                continue
+            raise TransportError(code, _message(res))
+        raise AssertionError("unreachable")
+
+    # -- Transport -----------------------------------------------------------------------------
+
+    def version(self) -> str:
+        res = self._run(["--version"])
+        return res.stdout.strip().removeprefix("mtp-rs ").strip()
+
+    def wait_for_device(self, timeout: float) -> DeviceInfo:
+        deadline = time.monotonic() + timeout
+        last: TransportError | None = None
+        while True:
+            try:
+                return self._try_open()
+            except TransportError as e:
+                if e.code not in ("no_device", "stuck"):
+                    raise
+                last = e
+            if time.monotonic() >= deadline:
+                raise last or TransportError("no_device", "No Garmin watch found")
+            self._sleep(1.0)
+
+    def _try_open(self) -> DeviceInfo:
+        res = self._run(["--json", "devices"])
+        if res.returncode != 0:
+            raise TransportError(_error_code(res), _message(res))
+        devices = [
+            d
+            for d in json.loads(res.stdout or "[]")
+            if d.get("vendor_id") == GARMIN_VENDOR_ID and _real_serial(d.get("serial_number"))
+        ]
+        if not devices:
+            raise TransportError("no_device", "No Garmin watch found")
+        if self.device is None:
+            if len(devices) > 1:
+                serials = ", ".join(d["serial_number"] for d in devices)
+                raise TransportError(
+                    "other", f"More than one Garmin connected ({serials}); use --device"
+                )
+            self.device = str(devices[0]["serial_number"])
+        info = json.loads(self._call("--json", "info", retry_stuck=False).stdout)
+        model = info.get("model")
+        maker = info.get("manufacturer") or "Garmin"
+        return DeviceInfo(
+            usb_serial=str(info.get("serial_number") or self.device).lower(),
+            product=f"{maker} {model}" if model else None,
+            firmware=info.get("device_version"),
+        )
+
+    def list_files(self) -> list[RemoteFile]:
+        res = self._call("--json", "ls", "--recursive", "/GARMIN")
+        self._listing = parse_recursive_listing(json.loads(res.stdout))
+        return self._listing.files
+
+    def plan(self, paths: Sequence[str]) -> None:
+        """Remember how many files per folder this sync needs, for the cost model (review M3)."""
+        counts: dict[str, int] = defaultdict(int)
+        for p in paths:
+            counts[p.rpartition("/")[0]] += 1
+        self._planned = dict(counts)
+
+    def close(self) -> None:
+        if self._cache_root is not None:
+            shutil.rmtree(self._cache_root, ignore_errors=True)
+            self._cache_root = None
+            self._folder_cache.clear()
+
+    def fetch(self, paths: Sequence[str], dest: Path) -> dict[str, Path]:
+        dest.mkdir(parents=True, exist_ok=True)
+        for p in paths:
+            if not is_synced(p):
+                raise TransportError("other", f"refusing to read {p}: outside the folder policy")
+        listing = self._listing or parse_recursive_listing(
+            json.loads(self._call("--json", "ls", "--recursive", "/GARMIN").stdout)
+        )
+        by_folder: dict[str, list[str]] = defaultdict(list)
+        for p in paths:
+            by_folder[p.rpartition("/")[0]].append(p)
+        out: dict[str, Path] = {}
+        for folder, wanted in by_folder.items():
+            planned = max(self._planned.get(folder, 0), len(wanted))
+            whole = folder in self._folder_cache or (
+                folder in listing.clean_folders
+                and _folder_is_safe(folder)
+                and choose_whole_folder(
+                    planned,
+                    listing.objects_per_folder.get(folder, planned),
+                    listing.bytes_per_folder.get(folder, 0),
+                )
+            )
+            if whole:
+                out.update(self._from_folder(folder, wanted, dest))
+            else:
+                for p in wanted:
+                    out[p] = self._get_file(p, dest)
+        return out
+
+    def _get_file(self, path: str, dest: Path) -> Path:
+        local = dest / path
+        local.parent.mkdir(parents=True, exist_ok=True)
+        if local.exists():
+            local.unlink()
+        self._call("get", f"/{path}", str(local))
+        return local
+
+    def _from_folder(self, folder: str, wanted: list[str], dest: Path) -> dict[str, Path]:
+        """Copy wanted files out of a folder downloaded once per sync (cached until close())."""
+        cached = self._folder_cache.get(folder)
+        if cached is None:
+            if self._cache_root is None:
+                self._cache_root = Path(tempfile.mkdtemp(prefix="unstrap-folders-"))
+            cached = self._cache_root / str(len(self._folder_cache))  # must not exist yet
+            self._call("get", f"/{folder}", str(cached))
+            self._folder_cache[folder] = cached
+        out = {}
+        for p in wanted:
+            src = cached / p.rpartition("/")[2]
+            if not src.is_file():
+                raise TransportError("not_found", f"{p} disappeared from the watch")
+            final = dest / p
+            final.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(src, final)
+            out[p] = final
+        return out
+
+
+def choose_whole_folder(wanted: int, objects: int, folder_bytes: int) -> bool:
+    """Per-file gets re-list the parent folder each time; a folder get reads everything once."""
+    per_file = wanted * (SESSION_SECONDS + PER_OBJECT_LISTING_SECONDS * objects)
+    whole = SESSION_SECONDS + folder_bytes / BYTES_PER_SECOND
+    return whole < per_file
+
+
+def _folder_is_safe(folder: str) -> bool:
+    """Never bulk-download a folder that contains (or is) a never-read folder."""
+    return not any(n == folder or n.startswith(folder + "/") for n in NEVER)
+
+
+def parse_recursive_listing(doc: dict[str, Any]) -> Listing:
+    """Rebuild paths from `ls --recursive --json /GARMIN` (objects carry parent handles only)."""
+    objects = doc.get("objects", [])
+    by_handle = {o["handle"]: o for o in objects}
+    cache: dict[int, str] = {}
+
+    def path_of(handle: int) -> str:
+        if handle in cache:
+            return cache[handle]
+        o = by_handle[handle]
+        parent = o.get("parent")
+        prefix = path_of(parent) if parent in by_handle else "GARMIN"
+        cache[handle] = f"{prefix}/{o['filename']}"
+        return cache[handle]
+
+    files: list[RemoteFile] = []
+    objects_per_folder: dict[str, int] = defaultdict(int)
+    bytes_per_folder: dict[str, int] = defaultdict(int)
+    folders: set[str] = set()
+    dirty: set[str] = set()
+    for o in objects:
+        p = path_of(o["handle"])
+        folder = p.rpartition("/")[0]
+        objects_per_folder[folder] += 1
+        if o.get("kind") != "file":
+            folders.add(p)
+            continue
+        size = int(o.get("size", 0))
+        ancestors = _ancestors(folder)
+        for a in ancestors:
+            bytes_per_folder[a] += size
+        if is_synced(p):
+            files.append(RemoteFile(p, size))
+        else:
+            dirty.update(ancestors)  # a folder get here would read a non-policy file
+    return Listing(
+        sorted(files, key=lambda f: f.path),
+        dict(objects_per_folder),
+        dict(bytes_per_folder),
+        (folders | set(objects_per_folder)) - dirty,
+    )
+
+
+def _ancestors(folder: str) -> list[str]:
+    parts = folder.split("/")
+    return ["/".join(parts[: i + 1]) for i in range(len(parts))]
+
+
+def _real_serial(serial: object) -> bool:
+    # While booting, watches enumerate as PID 0x0003 with serial "Not Provided".
+    return (
+        isinstance(serial, str)
+        and len(serial) == 12
+        and all(c in "0123456789abcdefABCDEF" for c in serial)
+    )
+
+
+def _message(res: subprocess.CompletedProcess[str]) -> str:
+    lines = [ln for ln in (res.stderr or "").splitlines() if ln.startswith("error:")]
+    return (
+        lines[-1].removeprefix("error:").strip()
+        if lines
+        else f"mtp-rs exited with {res.returncode}"
+    )
+
+
+def _error_code(res: subprocess.CompletedProcess[str]) -> ErrorCode:
+    msg = _message(res).lower()
+    if "permission denied" in msg or "access denied" in msg:
+        return "permission"
+    if "busy" in msg or "claimed" in msg:
+        return "busy"
+    codes: dict[int, ErrorCode] = {2: "no_device", 5: "not_found", 6: "stuck"}
+    return codes.get(res.returncode, "other")

unstrap-0.1.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: unstrap
+Version: 0.1.0
+Summary: Your watch data, set free. Copies everything your Garmin watch records, straight off the watch over USB.
+Author: SweatStack
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# unstrap
+
+Your watch data, set free. Plug in your Garmin watch and run:
+
+```sh
+uvx unstrap
+```
+
+See the project README for how it works.

unstrap-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+unstrap/__init__.py,sha256=PWSFwjqCW7XQ0V57uP5WKS3e225pstV4Kx6khYpEvKA,105
+unstrap/api.py,sha256=tpKfx40FPEZrUjgkC_kB-3DV-0yo6Mf0-NI5M_tC-A0,6445
+unstrap/cli.py,sha256=ZewFc-P2vV16Hh92iEcYiLJzVFpsrNSjezZqo9XIWr4,10423
+unstrap/policy.py,sha256=mr5aTD38cU-SrxaPx-E9D5q4hqbIQHZFe6uZiYVCtww,2604
+unstrap/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+unstrap/sync.py,sha256=uFqkTMqOuGBxvNG7jOePfQFPSG8e5m0hesi9IzLc3gw,9548
+unstrap/transport/__init__.py,sha256=ZiTtFlJWdllTWdKiS3Qb6ukhcoHKAjjX5uYU7CWI4vs,156
+unstrap/transport/base.py,sha256=IA6O7bhdIHEnocZ4Wx4GiuhjQ0p2210xrxXuqN3efpg,2206
+unstrap/transport/directory.py,sha256=FOY9ISX7w9v3jXfKTH-ZwX6Obc389L8SJygRBrULPO0,3124
+unstrap/transport/mtp_rs.py,sha256=RH53THZYvxJ61qtWWCbtx0iWeARYoqm01uONrcMTgCQ,12643
+unstrap-0.1.0.dist-info/METADATA,sha256=XiB0xBeRNK2uu_d88UHN9yMrqS9FVw9YdR937gWr6SI,631
+unstrap-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+unstrap-0.1.0.dist-info/entry_points.txt,sha256=-_hhzqSUxMGFX0zPPns7Wz4yAGCfgLGWYHbcyiQLwzA,45
+unstrap-0.1.0.dist-info/licenses/LICENSE,sha256=VdfjL69g2_81MnwprFdz5EvGPfSWNweyCg1WsY5_jCY,1067
+unstrap-0.1.0.dist-info/RECORD,,

unstrap-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

unstrap-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+unstrap = unstrap.cli:main

unstrap-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SweatStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.