Add HTTP transport, auth, cache, client, and tests

Introduce core networking, auth, caching, and client logic plus comprehensive tests.

- Add musher._auth: credential resolution chain (env, OS keyring, XDG config file).
- Add musher._http: HTTPTransport wrapper around httpx with auth headers and error mapping to SDK exceptions.
- Expand musher._cache: content-addressable blob storage and JSON manifest storage with atomic writes and clear() implementation.
- Implement AsyncClient: HTTP-backed resolve, fetch_asset, and pull (concurrent fetching, checksum verification, blob caching).
- Implement synchronous Client: background event loop/thread runner for sync APIs and proper shutdown.
- Update musher._config: use XDG cache dir, auto-discover env vars and credential chain, increase default timeout.
- Update pyproject.toml: optional keyring dependency declared.
- Minor example tweak to show token discovery comment.
- Add/modify tests: reset global config fixture; new tests for auth, cache, client (async + sync), config, and http transport.

These changes wire up the SDK transport and caching behavior, implement integrity checking, and add extensive unit coverage.

Author: justinmerrell

examples/inspect_manifest.py

@@ -6,9 +6,10 @@
 
 
 async def main():
+    # Token auto-discovered from MUSHER_API_KEY env var, keyring, or config file.
+    # Optionally set explicitly:
     musher.configure(token="your-token-here")
 
-    # Resolve without pulling asset content (will raise NotImplementedError until implemented)
     async with musher.AsyncClient() as client:
         result = await client.resolve("myorg/my-bundle:1.0.0")
 

pyproject.toml

@@ -10,6 +10,9 @@ dependencies = [
     "pydantic>=2.12",
 ]
 
+[project.optional-dependencies]
+keyring = ["keyring>=25.0"]
+
 [dependency-groups]
 dev = [
     "ruff>=0.15.2",

src/musher/_auth.py

@@ -0,0 +1,63 @@
+"""Credential resolution chain (CLI-compatible)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+from pathlib import Path
+
+_log = logging.getLogger(__name__)
+
+
+def _xdg_config_home() -> Path:
+    """Return XDG_CONFIG_HOME, defaulting to ~/.config."""
+    return Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+
+
+def resolve_token() -> str | None:
+    """Resolve an API token using the same 3-tier priority as the CLI.
+
+    1. ``MUSHER_API_KEY`` environment variable
+    2. OS keyring — service ``dev.musher.musher``, username ``api-key``
+    3. File fallback — ``$XDG_CONFIG_HOME/musher/api-key`` (must be 0600)
+    """
+    # 1. Environment variable
+    env_token = os.environ.get("MUSHER_API_KEY")
+    if env_token:
+        return env_token
+
+    # 2. OS keyring (optional dependency)
+    keyring_token = _try_keyring()
+    if keyring_token:
+        return keyring_token
+
+    # 3. File fallback
+    return _try_file()
+
+
+def _try_keyring() -> str | None:
+    """Attempt to read token from OS keyring. Returns None if unavailable."""
+    try:
+        import keyring  # type: ignore[import-untyped]  # noqa: PLC0415
+
+        token = keyring.get_password("dev.musher.musher", "api-key")
+        if token:
+            return token
+    except Exception:  # noqa: BLE001
+        _log.debug("keyring lookup failed", exc_info=True)
+    return None
+
+
+def _try_file() -> str | None:
+    """Read token from $XDG_CONFIG_HOME/musher/api-key if permissions are safe."""
+    key_file = _xdg_config_home() / "musher" / "api-key"
+    if not key_file.is_file():
+        return None
+
+    # Check permissions — must be owner-only (0600)
+    mode = key_file.stat().st_mode
+    if mode & (stat.S_IRWXG | stat.S_IRWXO):
+        return None
+
+    return key_file.read_text().strip() or None

src/musher/_cache.py

@@ -1,19 +1,24 @@
-"""XDG-compliant disk cache for downloaded bundles."""
+"""Content-addressable disk cache for bundle blobs and manifests."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import json
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
 
 from musher._config import get_config
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
 
 class BundleCache:
-    """Local disk cache for bundle assets.
+    """Local disk cache with content-addressable blob storage.
+
+    Layout::
 
-    Defaults to ``~/.cache/musher/bundles/`` (XDG_CACHE_HOME compliant).
+        $XDG_CACHE_HOME/musher/
+          blobs/sha256/<first-2-chars>/<full-hash>
+          manifests/<namespace>/<slug>/<version>.json
     """
 
     def __init__(self, cache_dir: Path | None = None) -> None:
@@ -23,18 +28,63 @@ def __init__(self, cache_dir: Path | None = None) -> None:
     def cache_dir(self) -> Path:
         return self._cache_dir
 
-    def get(self, ref: str, version: str) -> bytes | None:
-        """Retrieve a cached bundle. Returns None on cache miss."""
-        raise NotImplementedError
+    # ── Blob operations ────────────────────────────────────────────
+
+    def get_blob(self, content_sha256: str) -> bytes | None:
+        """Retrieve a cached blob by SHA-256 hash. Returns ``None`` on miss."""
+        path = self._blob_path(content_sha256)
+        if path.is_file():
+            return path.read_bytes()
+        return None
+
+    def put_blob(self, content_sha256: str, data: bytes) -> None:
+        """Store a blob using atomic write (tmp + rename)."""
+        path = self._blob_path(content_sha256)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(dir=path.parent)
+        tmp = Path(tmp_name)
+        try:
+            with open(fd, "wb") as f:  # noqa: PTH123
+                f.write(data)
+            tmp.rename(path)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+
+    # ── Manifest operations ────────────────────────────────────────
 
-    def put(self, ref: str, version: str, data: bytes) -> None:
-        """Store a bundle in the cache."""
-        raise NotImplementedError
+    def get_manifest(self, namespace: str, slug: str, version: str) -> dict[str, Any] | None:
+        """Retrieve a cached manifest. Returns ``None`` on miss."""
+        path = self._manifest_path(namespace, slug, version)
+        if path.is_file():
+            return json.loads(path.read_text())
+        return None
 
-    def evict(self, ref: str, version: str) -> None:
-        """Remove a specific bundle from the cache."""
-        raise NotImplementedError
+    def put_manifest(self, namespace: str, slug: str, version: str, data: dict[str, Any]) -> None:
+        """Store a manifest as JSON using atomic write."""
+        path = self._manifest_path(namespace, slug, version)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(dir=path.parent, suffix=".json")
+        tmp = Path(tmp_name)
+        try:
+            with open(fd, "w") as f:  # noqa: PTH123
+                json.dump(data, f)
+            tmp.rename(path)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+
+    # ── Maintenance ────────────────────────────────────────────────
 
     def clear(self) -> None:
-        """Remove all cached bundles."""
-        raise NotImplementedError
+        """Remove all cached data."""
+        if self._cache_dir.is_dir():
+            shutil.rmtree(self._cache_dir)
+
+    # ── Internal ───────────────────────────────────────────────────
+
+    def _blob_path(self, content_sha256: str) -> Path:
+        return self._cache_dir / "blobs" / "sha256" / content_sha256[:2] / content_sha256
+
+    def _manifest_path(self, namespace: str, slug: str, version: str) -> Path:
+        return self._cache_dir / "manifests" / namespace / slug / f"{version}.json"