Initial commit: AVWatch v1.0.0 with .gitignore and CLAUDE.md

avwatch/sources/base.py

@@ -0,0 +1,52 @@
+"""Source protocol shared by every version adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from ..http import HttpClient
+from ..models import Item, VersionCheck
+
+
+@dataclass
+class Context:
+    """Passed to every source. ``scratch`` lets an adapter fetch one shared
+    payload (a vendor-wide downloads feed, say) and reuse it across the dozens
+    of items that resolve from it."""
+
+    http: HttpClient
+    scratch: dict[str, Any] = field(default_factory=dict)
+
+    def memo(self, key: str, factory):
+        if key not in self.scratch:
+            self.scratch[key] = factory()
+        return self.scratch[key]
+
+
+class Source(Protocol):
+    kind: str
+
+    def check(self, item: Item, ctx: Context) -> VersionCheck:
+        ...
+
+
+def error(item: Item, detail: str) -> VersionCheck:
+    return VersionCheck(item_id=item.id, status="error", detail=detail)
+
+
+def manual(item: Item, detail: str = "No machine-readable feed; check by hand.") -> VersionCheck:
+    return VersionCheck(item_id=item.id, status="manual", detail=detail)
+
+
+def unconfigured(item: Item, detail: str) -> VersionCheck:
+    """AVWatch knows how to track this item, but the capability it needs is
+    not switched on.
+
+    Kept distinct from ``manual`` on purpose. "There is no firmware for this
+    passive splitter" and "your API key is missing so 60 items could not be
+    looked up" are completely different problems, and collapsing them into one
+    'check by hand' list makes a configuration gap look like the gear was
+    never tracked at all.
+    """
+    return VersionCheck(item_id=item.id, status="unconfigured", detail=detail)