Show specific reason when hardware volume is unavailable (#152)

## Summary
- Split the generic `except (ImportError, OSError)` in
`hardware_volume.py` into separate handlers, each capturing a
descriptive `UNAVAILABLE_REASON`
- The CLI error message now tells the user exactly what's wrong: missing
Python package (`pulsectl-asyncio`) vs missing system library
(`libpulse0`) vs non-Linux platform
- Previously, the error always said "Install pulsectl-asyncio" even when
the package was installed but the system library was missing

Closes #151

## Test plan
- [ ] On Linux without `libpulse0`: verify error mentions `sudo apt-get
install libpulse0`
- [ ] On Linux without `pulsectl-asyncio`: verify error mentions `pip
install pulsectl-asyncio`
- [ ] On non-Linux: verify error mentions "only supported on Linux"
- [ ] On Linux with everything installed: verify hardware volume works
normally

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: balloob

sendspin/cli.py

@@ -14,6 +14,7 @@
 from typing import TYPE_CHECKING
 
 from sendspin.hardware_volume import AVAILABLE as HW_VOLUME_AVAILABLE
+from sendspin.hardware_volume import UNAVAILABLE_REASON as HW_VOLUME_UNAVAILABLE_REASON
 from sendspin.hardware_volume import async_check_available as hw_volume_check_available
 from sendspin.settings import ClientSettings, get_client_settings, get_serve_settings
 
@@ -591,8 +592,8 @@ async def _run_client_mode(args: argparse.Namespace) -> int:
             args.hardware_volume = is_daemon and HW_VOLUME_AVAILABLE
     if args.hardware_volume and not HW_VOLUME_AVAILABLE:
         raise CLIError(
-            "Hardware volume control is not available on this system. "
-            "Install pulsectl-asyncio on Linux, or use --hardware-volume false."
+            f"Hardware volume control is not available on this system. "
+            f"{HW_VOLUME_UNAVAILABLE_REASON or 'Use --hardware-volume false to disable.'}"
         )
     if args.hook_start is None:
         args.hook_start = settings.hook_start

sendspin/hardware_volume.py

@@ -10,13 +10,24 @@
 from typing import Any
 
 AVAILABLE = False
-if sys.platform.startswith("linux"):
+UNAVAILABLE_REASON: str | None = None
+if not sys.platform.startswith("linux"):
+    UNAVAILABLE_REASON = "Hardware volume control is only supported on Linux."
+else:
     try:
         import pulsectl_asyncio
 
         AVAILABLE = True
-    except (ImportError, OSError):
-        pass
+    except ImportError:
+        UNAVAILABLE_REASON = (
+            "pulsectl-asyncio package is not installed. "
+            "Install it with: pip install pulsectl-asyncio"
+        )
+    except OSError as _exc:
+        UNAVAILABLE_REASON = (
+            f"PulseAudio system library failed to load: {_exc}. "
+            "Install it with: sudo apt-get install libpulse0"
+        )
 
 logger = logging.getLogger(__name__)