refactor: extract import_garmin_gear() + add backfill script

Move gear backfill logic from the route handler into
import_garmin_gear(data_dir, user_dir) in garmin_sync.py so it can be
called both from the API and from the CLI script.

scripts/backfill_garmin_gear.py finds all users with Garmin credentials
and runs the backfill for each, printing a per-user summary.

bincio/extract/garmin_sync.py

@@ -244,3 +244,145 @@ def run_garmin_sync(data_dir: Path, user_dir: Path) -> dict:
         elif event["type"] == "error":
             raise RuntimeError(event["message"])
     return result
+
+
+def import_garmin_gear(data_dir: Path, user_dir: Path) -> dict:
+    """Backfill gear for all existing activities by querying Garmin's gear-activities API.
+
+    For each gear item, fetches the list of activities from Garmin and matches them
+    to local activities by UTC start timestamp (±60 s). Writes a sidecar and calls
+    merge_one for each match that doesn't already have gear set.
+
+    Returns {"gear_added": int, "activities_updated": int}.
+    """
+    import contextlib
+    import re
+    import uuid
+
+    import yaml
+
+    from bincio.extract.garmin_api import GarminError, get_client
+    from bincio.render.merge import merge_one
+    from bincio.serve.routers.gear import _load as _gear_load
+    from bincio.serve.routers.gear import _save as _gear_save
+
+    client = get_client(data_dir, user_dir)
+
+    # Fetch gear list from Garmin
+    prof = client.connectapi("/userprofile-service/socialProfile")
+    profile_id = prof.get("profileId") if isinstance(prof, dict) else None
+    if not profile_id:
+        raise GarminError("Could not read Garmin profile ID")
+    garmin_gear = client.get_gear(profile_id)
+
+    if not isinstance(garmin_gear, list) or not garmin_gear:
+        return {"gear_added": 0, "activities_updated": 0}
+
+    # Build / update local gear registry
+    registry = _gear_load(user_dir)
+    known = {g.get("garmin_id") for g in registry if g.get("garmin_id")}
+    uuid_to_name: dict[str, str] = {}
+    gear_added = 0
+
+    for g in garmin_gear:
+        guuid = g.get("uuid") or ""
+        name = (g.get("customMakeModel") or g.get("displayName") or
+                f"{g.get('gearMakeName', '')} {g.get('gearModelName', '')}".strip())
+        if not name or not guuid:
+            continue
+        uuid_to_name[guuid] = name
+        if guuid not in known:
+            gear_type = g.get("gearTypeName", "").lower()
+            if gear_type not in ("bike", "shoes", "skis"):
+                gear_type = "other"
+            retired = g.get("gearStatusName") == "retired"
+            registry.append({"id": str(uuid.uuid4()), "name": name,
+                              "type": gear_type, "retired": retired, "garmin_id": guuid})
+            known.add(guuid)
+            gear_added += 1
+        else:
+            for item in registry:
+                if item.get("garmin_id") == guuid:
+                    item["name"] = name
+
+    _gear_save(user_dir, registry)
+
+    # Build timestamp → activity_id map from index shards
+    ts_to_id: dict[int, str] = {}
+    merged_dir = user_dir / "_merged"
+    shard_dir = merged_dir if merged_dir.exists() else user_dir
+    for shard_path in sorted(shard_dir.glob("index*.json")):
+        try:
+            idx = json.loads(shard_path.read_text(encoding="utf-8"))
+            for a in idx.get("activities", []):
+                started = a.get("started_at") or ""
+                if started and a.get("id"):
+                    dt = datetime.fromisoformat(started.replace("Z", "+00:00"))
+                    ts_to_id[int(dt.astimezone(UTC).timestamp())] = a["id"]
+        except (OSError, json.JSONDecodeError, KeyError):
+            continue
+
+    edits_dir = user_dir / "edits"
+    edits_dir.mkdir(exist_ok=True)
+    activities_updated = 0
+
+    for guuid, gear_name in uuid_to_name.items():
+        try:
+            gear_acts = client.get_gear_activities(guuid, limit=10000)
+        except Exception:
+            continue
+        if not isinstance(gear_acts, list):
+            continue
+
+        for ga in gear_acts:
+            gmt = ga.get("startTimeGMT") or ""
+            if not gmt:
+                continue
+            try:
+                dt = datetime.strptime(gmt, "%Y-%m-%d %H:%M:%S").replace(tzinfo=UTC)
+                ts = int(dt.timestamp())
+            except ValueError:
+                continue
+
+            act_id = None
+            for delta in range(0, 61):
+                act_id = ts_to_id.get(ts + delta) or ts_to_id.get(ts - delta)
+                if act_id:
+                    break
+            if not act_id:
+                continue
+
+            # Skip if activity already has gear set
+            act_json = user_dir / "activities" / f"{act_id}.json"
+            if act_json.exists():
+                try:
+                    if json.loads(act_json.read_text(encoding="utf-8")).get("gear"):
+                        continue
+                except (OSError, json.JSONDecodeError):
+                    pass
+
+            sidecar = edits_dir / f"{act_id}.md"
+            fm, body = {}, ""
+            if sidecar.exists():
+                try:
+                    text = sidecar.read_text(encoding="utf-8")
+                    parts = re.split(r"^---[ \t]*$", text, maxsplit=2, flags=re.MULTILINE)
+                    if len(parts) >= 3:
+                        fm = yaml.safe_load(parts[1]) or {}
+                        body = parts[2].strip()
+                except Exception:
+                    pass
+                if fm.get("gear"):
+                    continue
+
+            fm["gear"] = gear_name
+            fm_text = yaml.safe_dump(fm, default_flow_style=False, allow_unicode=True).strip()
+            content = f"---\n{fm_text}\n---\n"
+            if body:
+                content += f"\n{body}\n"
+            sidecar.write_text(content, encoding="utf-8")
+            with contextlib.suppress(Exception):
+                merge_one(user_dir, act_id)
+            activities_updated += 1
+
+    return {"gear_added": gear_added, "activities_updated": activities_updated}