🚨 chore(server-ci): fix install, lint, and format

- Workflow installs into a project venv instead of --system (PEP 668)
- Run ruff/pytest via uv run so they pick up the venv
- ruff format the whole tree (was missing in the initial scaffolds)
- conftest.py: imports consolidated to top of file (E402)
- auth.py: Annotated[..., Depends(...)] dep instead of default (B008)
- auth.py: shorten thread-offload comment (E501)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vitofico

.github/workflows/server-ci.yaml

@@ -24,11 +24,13 @@ jobs:
       - name: Set up Python
         run: uv python install 3.12
       - name: Install
-        run: uv pip install --system -e ".[dev]"
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
       - name: Lint
-        run: ruff check . && ruff format --check .
+        run: uv run ruff check . && uv run ruff format --check .
       - name: Test
-        run: pytest -v
+        run: uv run pytest -v
 
   image:
     needs: test

server/migrations/env.py

@@ -35,7 +35,11 @@ def _ensure_url() -> None:
 
 def run_migrations_offline() -> None:
     _ensure_url()
-    context.configure(url=config.get_main_option("sqlalchemy.url"), target_metadata=target_metadata, literal_binds=True)
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+    )
     with context.begin_transaction():
         context.run_migrations()
 

server/migrations/versions/0001_initial.py

@@ -4,9 +4,9 @@
 Revises:
 Create Date: 2026-05-05 00:00:00.000000
 """
-from alembic import op
-import sqlalchemy as sa
 
+import sqlalchemy as sa
+from alembic import op
 
 revision = "0001"
 down_revision = None
@@ -21,22 +21,39 @@ def upgrade() -> None:
         sa.Column("user_id", sa.String(), nullable=False),
         sa.Column("metadata_id", sa.String(), nullable=True),
         sa.Column("content_hash", sa.String(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
         sa.UniqueConstraint("user_id", "metadata_id", name="uq_documents_user_metadata"),
         sa.UniqueConstraint("user_id", "content_hash", name="uq_documents_user_content_hash"),
     )
     op.create_index("ix_documents_user", "documents", ["user_id"])
 
     op.create_table(
         "progress",
-        sa.Column("document_pk", sa.BigInteger(), sa.ForeignKey("documents.pk", ondelete="CASCADE"), primary_key=True),
+        sa.Column(
+            "document_pk",
+            sa.BigInteger(),
+            sa.ForeignKey("documents.pk", ondelete="CASCADE"),
+            primary_key=True,
+        ),
         sa.Column("locator", sa.String(), nullable=False),
         sa.Column("percent", sa.Float(), nullable=False),
         sa.Column("client_updated_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("received_at", sa.DateTime(timezone=True), server_default=sa.text("now()"), nullable=False),
+        sa.Column(
+            "received_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
         sa.CheckConstraint("percent >= 0 AND percent <= 1", name="ck_progress_percent_range"),
     )
-    op.create_index("ix_progress_document_client_updated_at", "progress", ["document_pk", "client_updated_at"])
+    op.create_index(
+        "ix_progress_document_client_updated_at", "progress", ["document_pk", "client_updated_at"]
+    )
 
 
 def downgrade() -> None:

server/opds_sync/api/health.py

@@ -17,5 +17,7 @@ async def readyz() -> dict:
         async with session_scope() as s:
             await s.execute(text("select 1"))
     except Exception as e:  # noqa: BLE001 — readiness must not leak details
-        raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="db unreachable") from e
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="db unreachable"
+        ) from e
     return {"status": "ready"}

server/opds_sync/api/progress.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from typing import Annotated, Literal
 
 from fastapi import APIRouter, Depends, Query
@@ -37,7 +37,7 @@ class ProgressPushResult(BaseModel):
     @field_serializer("server_client_updated_at")
     def _serialize_dt(self, v: datetime) -> str:
         if v.tzinfo is None:
-            v = v.replace(tzinfo=timezone.utc)
+            v = v.replace(tzinfo=UTC)
         return v.isoformat()
 
 

server/opds_sync/core/auth.py

@@ -2,9 +2,8 @@
 
 import asyncio
 import logging
-from typing import Protocol
+from typing import Annotated, Protocol
 
-import httpx
 import jwt
 from fastapi import Depends, HTTPException, Request, status
 from jwt import PyJWKClient
@@ -23,7 +22,7 @@ def __init__(self, jwks_url: str) -> None:
         self._client = PyJWKClient(jwks_url, cache_keys=True, lifespan=24 * 3600)
 
     async def get_signing_key(self, kid: str):
-        # PyJWKClient is sync; in practice the JWKS is small and cached, so a thread offload is fine.
+        # PyJWKClient is sync; the JWKS is small and cached, so a thread offload is fine.
         # If this becomes hot, switch to httpx + manual JWKS parsing.
         return await asyncio.to_thread(self._client.get_signing_key, kid)
 
@@ -59,7 +58,10 @@ async def get_validator(request: Request) -> JwtValidator:
     return request.app.state.jwt_validator
 
 
-async def current_user_id(request: Request, validator: JwtValidator = Depends(get_validator)) -> str:
+async def current_user_id(
+    request: Request,
+    validator: Annotated[JwtValidator, Depends(get_validator)],
+) -> str:
     auth = request.headers.get("authorization")
     if not auth or not auth.lower().startswith("bearer "):
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="missing bearer")

server/opds_sync/core/identity.py

@@ -14,7 +14,7 @@ def normalize_metadata_id(raw: str | None) -> str | None:
     if not s:
         return None
     if s.startswith("urn:"):
-        s = s[len("urn:"):]
+        s = s[len("urn:") :]
     s = _SCHEME_PREFIX.sub("", s, count=1)
     s = _WHITESPACE_AND_HYPHEN.sub("", s)
     return s or None

server/opds_sync/db/models.py

@@ -30,9 +30,13 @@ class Document(Base):
     user_id: Mapped[str] = mapped_column(String, nullable=False)
     metadata_id: Mapped[str | None] = mapped_column(String, nullable=True)
     content_hash: Mapped[str] = mapped_column(String, nullable=False)
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
 
-    progress: Mapped["Progress | None"] = relationship(back_populates="document", uselist=False, cascade="all, delete-orphan")
+    progress: Mapped["Progress | None"] = relationship(
+        back_populates="document", uselist=False, cascade="all, delete-orphan"
+    )
 
 
 class Progress(Base):
@@ -42,10 +46,14 @@ class Progress(Base):
         Index("ix_progress_document_client_updated_at", "document_pk", "client_updated_at"),
     )
 
-    document_pk: Mapped[int] = mapped_column(BigInteger, ForeignKey("documents.pk", ondelete="CASCADE"), primary_key=True)
+    document_pk: Mapped[int] = mapped_column(
+        BigInteger, ForeignKey("documents.pk", ondelete="CASCADE"), primary_key=True
+    )
     locator: Mapped[str] = mapped_column(String, nullable=False)
     percent: Mapped[float] = mapped_column(Float, nullable=False)
     client_updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
-    received_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    received_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
 
     document: Mapped[Document] = relationship(back_populates="progress")

server/tests/conftest.py

@@ -1,22 +1,33 @@
-import pytest
+import time
 from collections.abc import AsyncIterator, Iterator
 
+import jwt
+import pytest
+from alembic import command
+from alembic.config import Config as AlembicConfig
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from testcontainers.postgres import PostgresContainer
+
 
 def pytest_collection_modifyitems(items):
     """Ensure test_schema runs before test_progress to avoid committed-row cross-pollution."""
+
     def _key(item):
         path = item.nodeid
         if "test_schema" in path:
             return 0
         if "test_progress" in path:
             return 1
         return 2
-    items.sort(key=_key)
 
-from alembic import command
-from alembic.config import Config as AlembicConfig
-from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
-from testcontainers.postgres import PostgresContainer
+    items.sort(key=_key)
 
 
 @pytest.fixture(scope="session")
@@ -49,13 +60,6 @@ async def session(engine: AsyncEngine) -> AsyncIterator[AsyncSession]:
         await s.rollback()
 
 
-import time
-
-import jwt
-from cryptography.hazmat.primitives import serialization
-from cryptography.hazmat.primitives.asymmetric import rsa
-
-
 @pytest.fixture(scope="session")
 def signing_key():
     key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
@@ -81,10 +85,20 @@ def audience() -> str:
 @pytest.fixture
 def make_token(signing_key, issuer, audience):
     priv, _ = signing_key
+
     def _make(sub: str, ttl: int = 60, **extra) -> str:
         now = int(time.time())
-        claims = {"sub": sub, "iss": issuer, "aud": audience, "iat": now, "nbf": now, "exp": now + ttl, **extra}
+        claims = {
+            "sub": sub,
+            "iss": issuer,
+            "aud": audience,
+            "iat": now,
+            "nbf": now,
+            "exp": now + ttl,
+            **extra,
+        }
         return jwt.encode(claims, priv, algorithm="RS256", headers={"kid": "test-key"})
+
     return _make
 
 
@@ -97,6 +111,7 @@ def app_under_test(postgres_url, alembic_upgrade, monkeypatch, signing_key, issu
 
     # Bust the lru_cache so the env vars take effect.
     from opds_sync.config import get_settings
+
     get_settings.cache_clear()
 
     from opds_sync.core.auth import JwksFetcher, JwtValidator
@@ -106,7 +121,9 @@ def app_under_test(postgres_url, alembic_upgrade, monkeypatch, signing_key, issu
 
     class StaticJwks(JwksFetcher):
         async def get_signing_key(self, kid):  # type: ignore[override]
-            class _K: key = pub  # noqa: E701
+            class _K:
+                key = pub  # noqa: E701
+
             return _K()
 
     app = create_app()

server/tests/integration/test_health.py

@@ -3,6 +3,7 @@
 
 async def test_healthz_returns_200():
     from opds_sync.main import create_app
+
     app = create_app()
     transport = ASGITransport(app=app)
     async with AsyncClient(transport=transport, base_url="http://test") as client:
@@ -15,9 +16,11 @@ async def test_readyz_returns_200_when_db_reachable(postgres_url, alembic_upgrad
     monkeypatch.setenv("OPDS_SYNC_DATABASE_URL", postgres_url)
     # Bust the lru_cache on get_settings so the new env var is honoured
     from opds_sync.config import get_settings
+
     get_settings.cache_clear()
 
     from opds_sync.main import create_app
+
     app = create_app()
     transport = ASGITransport(app=app)
     async with AsyncClient(transport=transport, base_url="http://test") as client: