Initial commit: RehearsalHub POC

Full-stack self-hosted band rehearsal platform:

Backend (FastAPI + SQLAlchemy 2.0 async):
- Auth with JWT (register, login, /me, settings)
- Band management with Nextcloud folder integration
- Song management with audio version tracking
- Nextcloud scan to auto-import audio files
- Band membership with link-based invite system
- Song comments
- Audio analysis worker (BPM, key, loudness, waveform)
- Nextcloud activity watcher for auto-import
- WebSocket support for real-time annotation updates
- Alembic migrations (0001–0003)
- Repository pattern, Ruff + mypy configured

Frontend (React 18 + Vite + TypeScript strict):
- Login/register page with post-login redirect
- Home page with band list and creation form
- Band page with member panel, invite link, song list, NC scan
- Song page with waveform player, annotations, comment thread
- Settings page for per-user Nextcloud credentials
- Invite acceptance page (/invite/:token)
- ESLint v9 flat config + TypeScript strict mode

Infrastructure:
- Docker Compose: PostgreSQL, Redis, API, worker, watcher, nginx
- nginx reverse proxy for static files + /api/ proxy
- make check runs all linters before docker compose build

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

watcher/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim AS base
+WORKDIR /app
+RUN pip install uv
+
+FROM base AS production
+COPY pyproject.toml .
+RUN uv sync --no-dev --frozen || uv sync --no-dev
+COPY . .
+ENV PYTHONPATH=/app/src
+CMD ["uv", "run", "python", "-m", "watcher.main"]

watcher/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rehearsalhub-watcher"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "redis[hiredis]>=5.0",
+    "pydantic-settings>=2.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5",
+    "respx>=0.21",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/watcher"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

watcher/src/watcher/config.py

@@ -0,0 +1,24 @@
+from functools import lru_cache
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class WatcherSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    nextcloud_url: str = "http://nextcloud"
+    nextcloud_user: str = "ncadmin"
+    nextcloud_pass: str = ""
+
+    api_url: str = "http://api:8000"
+    redis_url: str = "redis://localhost:6379/0"
+    job_queue_key: str = "rh:jobs"
+
+    poll_interval: int = 30  # seconds
+
+    # File extensions to watch
+    audio_extensions: list[str] = [".wav", ".mp3", ".flac", ".aac", ".ogg", ".m4a"]
+
+
+@lru_cache
+def get_settings() -> WatcherSettings:
+    return WatcherSettings()  # type: ignore[call-arg]

watcher/src/watcher/event_loop.py

@@ -0,0 +1,98 @@
+"""Event loop: poll Nextcloud activity, detect audio uploads, push to API."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from watcher.config import WatcherSettings
+from watcher.nc_client import NextcloudWatcherClient
+
+log = logging.getLogger("watcher.event_loop")
+
+# Persist last seen activity ID across polls (in-process state; persistent across restarts
+# would require a small DB or file, but good enough for a POC)
+_last_activity_id: int = 0
+
+
+def is_audio_file(path: str, extensions: list[str]) -> bool:
+    return Path(path).suffix.lower() in extensions
+
+
+def is_band_audio_path(path: str) -> bool:
+    """Check if the path looks like /bands/<slug>/songs/**"""
+    parts = path.strip("/").split("/")
+    return len(parts) >= 3 and parts[0] == "bands"
+
+
+def extract_nc_file_path(activity: dict[str, Any]) -> str | None:
+    """Extract the server-relative file path from an activity event."""
+    objects = activity.get("objects", {})
+    for file_id, file_path in objects.items():
+        if isinstance(file_path, str):
+            return file_path
+    return activity.get("object_name")
+
+
+async def register_version_with_api(
+    nc_file_path: str,
+    nc_file_etag: str | None,
+    api_url: str,
+) -> bool:
+    """
+    Call POST /api/v1/songs/{song_id}/versions to register the new file.
+    We infer song context from the path: /bands/{slug}/songs/{song_folder}/file.ext
+    In a full implementation this would look up the song_id from the API.
+    Here we emit a best-effort registration event.
+    """
+    try:
+        payload = {
+            "nc_file_path": nc_file_path,
+            "nc_file_etag": nc_file_etag,
+        }
+        async with httpx.AsyncClient(timeout=10.0) as c:
+            resp = await c.post(f"{api_url}/api/v1/internal/nc-upload", json=payload)
+            return resp.status_code in (200, 201)
+    except Exception as exc:
+        log.warning("Failed to register version with API: %s", exc)
+        return False
+
+
+async def poll_once(
+    nc_client: NextcloudWatcherClient,
+    settings: WatcherSettings,
+) -> None:
+    global _last_activity_id
+
+    activities = await nc_client.get_activities(since_id=_last_activity_id)
+    if not activities:
+        return
+
+    for activity in activities:
+        activity_id = activity.get("activity_id", 0)
+        subject = activity.get("subject", "")
+
+        if subject not in ("file_created", "file_changed"):
+            _last_activity_id = max(_last_activity_id, activity_id)
+            continue
+
+        nc_path = extract_nc_file_path(activity)
+        if nc_path is None:
+            _last_activity_id = max(_last_activity_id, activity_id)
+            continue
+
+        if not is_audio_file(nc_path, settings.audio_extensions):
+            _last_activity_id = max(_last_activity_id, activity_id)
+            continue
+
+        if not is_band_audio_path(nc_path):
+            _last_activity_id = max(_last_activity_id, activity_id)
+            continue
+
+        log.info("Detected audio upload: %s", nc_path)
+        etag = await nc_client.get_file_etag(nc_path)
+        await register_version_with_api(nc_path, etag, settings.api_url)
+        _last_activity_id = max(_last_activity_id, activity_id)

watcher/src/watcher/main.py

@@ -0,0 +1,38 @@
+"""Nextcloud watcher daemon entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from watcher.config import get_settings
+from watcher.event_loop import poll_once
+from watcher.nc_client import NextcloudWatcherClient
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+log = logging.getLogger("watcher")
+
+
+async def main() -> None:
+    settings = get_settings()
+    nc = NextcloudWatcherClient(
+        base_url=settings.nextcloud_url,
+        username=settings.nextcloud_user,
+        password=settings.nextcloud_pass,
+    )
+
+    log.info("Waiting for Nextcloud to become available...")
+    while not await nc.is_healthy():
+        await asyncio.sleep(10)
+    log.info("Nextcloud is ready. Starting poll loop (interval=%ds)", settings.poll_interval)
+
+    while True:
+        try:
+            await poll_once(nc, settings)
+        except Exception as exc:
+            log.exception("Poll error: %s", exc)
+        await asyncio.sleep(settings.poll_interval)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

watcher/src/watcher/nc_client.py

@@ -0,0 +1,82 @@
+"""Nextcloud OCS API client for the watcher service."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class NextcloudWatcherClient:
+    def __init__(self, base_url: str, username: str, password: str) -> None:
+        self._base = base_url.rstrip("/")
+        self._auth = (username, password)
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            auth=self._auth,
+            headers={"OCS-APIRequest": "true"},
+            timeout=15.0,
+        )
+
+    async def get_activities(
+        self, since_id: int = 0, limit: int = 100
+    ) -> list[dict[str, Any]]:
+        """
+        Fetch recent file activity events from the Nextcloud Activity app.
+        Returns a list of activity dicts sorted oldest-first.
+        """
+        url = f"{self._base}/ocs/v2.php/apps/activity/api/v2/activity/files"
+        params: dict[str, Any] = {
+            "since": since_id,
+            "limit": limit,
+            "format": "json",
+            "sort": "asc",
+        }
+        async with self._client() as c:
+            resp = await c.get(url, params=params)
+            resp.raise_for_status()
+        data = resp.json()
+        return data.get("ocs", {}).get("data", []) or []
+
+    async def get_file_etag(self, file_path: str) -> str | None:
+        """PROPFIND to get the ETag for a file."""
+        url = f"{self._base}/remote.php/dav/files/{self._auth[0]}/{file_path.lstrip('/')}"
+        body = (
+            '<?xml version="1.0"?>'
+            '<d:propfind xmlns:d="DAV:"><d:prop><d:getetag/></d:prop></d:propfind>'
+        )
+        async with self._client() as c:
+            resp = await c.request(
+                "PROPFIND",
+                url,
+                headers={"Depth": "0", "Content-Type": "application/xml"},
+                content=body,
+            )
+            if resp.status_code == 404:
+                return None
+            resp.raise_for_status()
+
+        import xml.etree.ElementTree as ET
+
+        root = ET.fromstring(resp.text)
+        ns = "{DAV:}"
+        for response in root.findall(f"{ns}response"):
+            propstat = response.find(f"{ns}propstat")
+            if propstat is not None:
+                prop = propstat.find(f"{ns}prop")
+                if prop is not None:
+                    etag = prop.findtext(f"{ns}getetag")
+                    if etag:
+                        return etag.strip('"')
+        return None
+
+    async def is_healthy(self) -> bool:
+        """Return True if Nextcloud is reachable and initialized."""
+        try:
+            async with self._client() as c:
+                resp = await c.get(f"{self._base}/status.php")
+                data = resp.json()
+                return data.get("installed", False)
+        except Exception:
+            return False

watcher/tests/conftest.py

@@ -0,0 +1,17 @@
+"""Watcher test fixtures."""
+
+import pytest
+
+from watcher.config import WatcherSettings
+
+
+@pytest.fixture
+def settings():
+    return WatcherSettings(
+        nextcloud_url="http://nc.test",
+        nextcloud_user="admin",
+        nextcloud_pass="secret",
+        api_url="http://api.test",
+        redis_url="redis://localhost:6379/0",
+        poll_interval=5,
+    )

watcher/tests/test_event_loop.py

@@ -0,0 +1,118 @@
+"""Tests for watcher event loop logic."""
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from watcher.event_loop import (
+    extract_nc_file_path,
+    is_audio_file,
+    is_band_audio_path,
+    poll_once,
+)
+
+
+def test_is_audio_file_matches_extensions():
+    extensions = [".wav", ".mp3", ".flac"]
+    assert is_audio_file("/bands/foo/songs/bar/take1.wav", extensions)
+    assert is_audio_file("/bands/foo/songs/bar/take1.MP3", extensions)
+    assert not is_audio_file("/bands/foo/songs/bar/cover.jpg", extensions)
+    assert not is_audio_file("/bands/foo/songs/bar/notes.txt", extensions)
+
+
+def test_is_band_audio_path():
+    assert is_band_audio_path("/bands/myband/songs/mysong/take.wav")
+    assert is_band_audio_path("bands/slug/songs/")
+    assert not is_band_audio_path("/nextcloud/files/random.wav")
+    assert not is_band_audio_path("/")
+
+
+def test_extract_nc_file_path_from_objects():
+    activity = {"objects": {"42": "/bands/foo/songs/bar/take.wav"}}
+    path = extract_nc_file_path(activity)
+    assert path == "/bands/foo/songs/bar/take.wav"
+
+
+def test_extract_nc_file_path_from_object_name():
+    activity = {"objects": {}, "object_name": "/bands/foo/songs/bar/take.wav"}
+    path = extract_nc_file_path(activity)
+    assert path == "/bands/foo/songs/bar/take.wav"
+
+
+def test_extract_nc_file_path_returns_none_when_missing():
+    activity = {"objects": {}}
+    path = extract_nc_file_path(activity)
+    assert path is None
+
+
+@pytest.mark.asyncio
+async def test_poll_once_ignores_non_audio_files(settings):
+    from watcher.nc_client import NextcloudWatcherClient
+
+    nc = AsyncMock(spec=NextcloudWatcherClient)
+    nc.get_activities.return_value = [
+        {
+            "activity_id": 1,
+            "subject": "file_created",
+            "objects": {"1": "/bands/foo/songs/bar/image.jpg"},
+        }
+    ]
+
+    with patch("watcher.event_loop.register_version_with_api") as mock_register:
+        await poll_once(nc, settings)
+        mock_register.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_poll_once_registers_audio_upload(settings):
+    from watcher.nc_client import NextcloudWatcherClient
+
+    nc = AsyncMock(spec=NextcloudWatcherClient)
+    nc.get_activities.return_value = [
+        {
+            "activity_id": 5,
+            "subject": "file_created",
+            "objects": {"10": "/bands/myband/songs/mysong/take1.wav"},
+        }
+    ]
+    nc.get_file_etag.return_value = "abc123"
+
+    with patch(
+        "watcher.event_loop.register_version_with_api", new_callable=AsyncMock, return_value=True
+    ) as mock_register:
+        await poll_once(nc, settings)
+        mock_register.assert_called_once_with(
+            "/bands/myband/songs/mysong/take1.wav",
+            "abc123",
+            settings.api_url,
+        )
+
+
+@pytest.mark.asyncio
+async def test_poll_once_ignores_non_file_events(settings):
+    from watcher.nc_client import NextcloudWatcherClient
+
+    nc = AsyncMock(spec=NextcloudWatcherClient)
+    nc.get_activities.return_value = [
+        {
+            "activity_id": 2,
+            "subject": "shared",  # not file_created or file_changed
+            "objects": {"5": "/bands/foo/songs/bar/take.wav"},
+        }
+    ]
+
+    with patch("watcher.event_loop.register_version_with_api") as mock_register:
+        await poll_once(nc, settings)
+        mock_register.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_poll_once_empty_activities_does_nothing(settings):
+    from watcher.nc_client import NextcloudWatcherClient
+
+    nc = AsyncMock(spec=NextcloudWatcherClient)
+    nc.get_activities.return_value = []
+
+    with patch("watcher.event_loop.register_version_with_api") as mock_register:
+        await poll_once(nc, settings)
+        mock_register.assert_not_called()

watcher/tests/test_nc_client.py

@@ -0,0 +1,80 @@
+"""Tests for Nextcloud OCS client."""
+
+import pytest
+import respx
+import httpx
+
+from watcher.nc_client import NextcloudWatcherClient
+
+
+@pytest.fixture
+def client():
+    return NextcloudWatcherClient(
+        base_url="http://nc.test", username="admin", password="secret"
+    )
+
+
+@pytest.mark.asyncio
+async def test_get_activities_returns_list(client):
+    mock_response = {
+        "ocs": {
+            "data": [
+                {
+                    "activity_id": 1,
+                    "subject": "file_created",
+                    "objects": {"123": "/bands/myband/songs/song1/take1.wav"},
+                }
+            ]
+        }
+    }
+    with respx.mock:
+        respx.get("http://nc.test/ocs/v2.php/apps/activity/api/v2/activity/files").mock(
+            return_value=httpx.Response(200, json=mock_response)
+        )
+        activities = await client.get_activities(since_id=0)
+
+    assert len(activities) == 1
+    assert activities[0]["subject"] == "file_created"
+
+
+@pytest.mark.asyncio
+async def test_get_activities_returns_empty_on_no_data(client):
+    mock_response = {"ocs": {"data": []}}
+    with respx.mock:
+        respx.get("http://nc.test/ocs/v2.php/apps/activity/api/v2/activity/files").mock(
+            return_value=httpx.Response(200, json=mock_response)
+        )
+        activities = await client.get_activities()
+
+    assert activities == []
+
+
+@pytest.mark.asyncio
+async def test_is_healthy_true_when_installed(client):
+    with respx.mock:
+        respx.get("http://nc.test/status.php").mock(
+            return_value=httpx.Response(200, json={"installed": True, "version": "28.0.0"})
+        )
+        result = await client.is_healthy()
+
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_is_healthy_false_when_not_installed(client):
+    with respx.mock:
+        respx.get("http://nc.test/status.php").mock(
+            return_value=httpx.Response(200, json={"installed": False})
+        )
+        result = await client.is_healthy()
+
+    assert result is False
+
+
+@pytest.mark.asyncio
+async def test_is_healthy_false_on_connection_error(client):
+    with respx.mock:
+        respx.get("http://nc.test/status.php").mock(side_effect=httpx.ConnectError("refused"))
+        result = await client.is_healthy()
+
+    assert result is False