Code organization and refactoring

utils/__init__.py

@@ -0,0 +1,4 @@
+"""Utility functions package."""
+from .file_helpers import load_json_list, sync_state_from_file
+
+__all__ = ["load_json_list", "sync_state_from_file"]

utils/file_helpers.py

@@ -0,0 +1,28 @@
+"""File I/O helper utilities."""
+import json
+from pathlib import Path
+from services.server_state import STATE
+
+
+def load_json_list(path: Path):
+    """Load a JSON file and return it as a list."""
+    if not path.exists():
+        return []
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+async def sync_state_from_file(path: Path, kind: str):
+    """
+    Read JSON file (list of members dicts) and upsert into STATE.
+    Expected member dict keys: id, name, level, estimate, optionally status/hits.
+    """
+    arr = load_json_list(path)
+    received_ids = []
+    for m in arr:
+        try:
+            await STATE.upsert_member(m, kind)
+            received_ids.append(int(m["id"]))
+        except Exception as e:
+            print(f"Skipping bad member entry while syncing: {m} -> {e}")
+    await STATE.remove_missing_members(received_ids, kind)