regstack 0.2.4__tar.gz → 0.2.6__tar.gz

{regstack-0.2.4 → regstack-0.2.6}/CHANGELOG.md

@@ -5,6 +5,36 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 0.2.6 — 2026-04-28
+
+Bug fix.
+
+- **Fix:** `/admin/stats` reported `pending_registrations: 0` on
+  every SQL backend. The route reached into the Mongo repo's private
+  `_collection` attribute and silently fell back to `0` when the
+  attribute was absent. Added `count_unexpired(now=None)` to
+  `PendingRepoProtocol` with Mongo + SQL implementations and routed
+  through `rs.clock.now()` so the count respects the injected clock.
+  New parametrized integration test exercises the count on every
+  backend.
+
+## 0.2.5 — 2026-04-28
+
+Bug fix + tooling.
+
+- **Fix:** `regstack doctor` against a SQL backend crashed with
+  `asyncio.run() cannot be called from a running event loop`. The
+  schema check called `regstack.backends.sql.migrations.current()`,
+  which used `asyncio.run()` internally — invalid inside doctor's own
+  `asyncio.run`. Added `current_async()` and switched the doctor
+  command to use it. Sync `current()` is preserved for the migrate
+  CLI.
+- **New:** `inv coverage [--no-html] [--fail-under=N]` runs the full
+  three-backend matrix under coverage and writes term + HTML reports.
+  Branch coverage is on by default.
+- Test coverage uplift on the CLI: `cli/init.py` 14% → 88%,
+  `cli/doctor.py` 61% → 87%. Total: **85% → 87.1%**.
+
 ## 0.2.4 — 2026-04-28
 
 **Breaking** — back-compat shims removed:

{regstack-0.2.4 → regstack-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.4
+Version: 0.2.6
 Summary: Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB.
 Project-URL: Homepage, https://github.com/jdrumgoole/regstack
 Project-URL: Repository, https://github.com/jdrumgoole/regstack

{regstack-0.2.4 → regstack-0.2.6}/docs/changelog.md

@@ -3,6 +3,67 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 0.2.6 — 2026-04-28
+
+**Bug fix.**
+
+### Fixed
+
+- ``/admin/stats`` reported ``pending_registrations: 0`` on every SQL
+  backend. The route reached into the Mongo repo's private
+  ``_collection`` attribute and silently fell back to ``0`` when the
+  attribute was absent — the kind of failure that survives a
+  multi-backend refactor when the integration tests don't pin the
+  number.
+
+### Added
+
+- ``PendingRepoProtocol.count_unexpired(now=None) -> int``, with Mongo
+  and SQL implementations. "Unexpired" rather than a raw row count
+  because SQL backends accumulate dead rows until ``purge_expired``
+  runs; an admin looking at "pending: 47" wants 47 *live* rows.
+- The admin stats route now routes the count through
+  ``rs.clock.now()``. Without this, ``FrozenClock``-driven tests
+  would see every row as "expired" because the route would be reading
+  wall-clock time while the rest of the system runs on the injected
+  clock. Same shape of clock-injection drift the bulk-revoke fix
+  closed earlier.
+- New parametrized integration test
+  ``test_stats_pending_registrations_count_unexpired`` runs against
+  SQLite + Mongo + Postgres and confirms the count excludes expired
+  rows on every backend.
+
+## 0.2.5 — 2026-04-28
+
+**Bug fix + tooling.**
+
+### Fixed
+
+- ``regstack doctor`` against a SQL backend crashed with
+  ``asyncio.run() cannot be called from a running event loop``. The
+  schema check called
+  ``regstack.backends.sql.migrations.current()``, which used
+  ``asyncio.run()`` internally — invalid inside doctor's own
+  ``asyncio.run``. Added ``current_async()`` and switched the doctor
+  command to use it. Sync ``current()`` is preserved for the migrate
+  CLI (which runs outside an event loop).
+
+### Added
+
+- ``inv coverage [--no-html] [--fail-under=N]`` — runs the full
+  three-backend matrix under coverage, combines per-pytest-xdist-worker
+  ``.coverage`` files, prints the term-with-missing report, and writes
+  ``htmlcov/``. Branch coverage is on by default.
+- ``[tool.coverage.*]`` config in ``pyproject.toml``.
+- ``tests/unit/test_cli_init.py`` — six tests driving the
+  ``regstack init`` wizard via ``CliRunner(input=...)``. Lifts
+  ``cli/init.py`` from 14% → 88%.
+- ``tests/unit/test_cli_doctor.py`` — four tests for the SQLite
+  ``regstack doctor`` paths. Lifts ``cli/doctor.py`` from 61% → 87%.
+
+Total line coverage on the full backend matrix: **85% → 87.1%**
+(branch coverage is also newly enabled).
+
 ## 0.2.4 — 2026-04-28
 
 **Breaking** — every back-compat shim left over from the

{regstack-0.2.4 → regstack-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.2.4"
+version = "0.2.6"
 description = "Embeddable user registration, login, and account management for FastAPI apps. SQLite / Postgres / MongoDB."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -119,3 +119,25 @@ python_version = "3.11"
 strict = true
 warn_unreachable = true
 plugins = ["pydantic.mypy"]
+
+[tool.coverage.run]
+source = ["src/regstack"]
+branch = true
+parallel = true
+# `concurrency = ["thread"]` is implicit; pytest-xdist workers each write
+# their own .coverage.<host>.<pid>.<token> file and `coverage combine`
+# folds them together — see the `coverage` invoke task.
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+precision = 1
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "\\.\\.\\.$",                   # body-less Protocol methods
+]
+
+[tool.coverage.html]
+directory = "htmlcov"

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/backends/mongo/repositories/pending_repo.py

@@ -64,6 +64,10 @@ class PendingRepo:
         result = await self._collection.delete_many({"expires_at": {"$lt": cutoff}})
         return int(result.deleted_count)
 
+    async def count_unexpired(self, now: datetime | None = None) -> int:
+        cutoff = now or datetime.now(UTC)
+        return await self._collection.count_documents({"expires_at": {"$gt": cutoff}})
+
     @staticmethod
     def _hydrate(doc: dict[str, Any] | None) -> PendingRegistration | None:
         if doc is None:

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/backends/protocols.py

@@ -154,6 +154,22 @@ class PendingRepoProtocol(Protocol):
         """
         ...
 
+    async def count_unexpired(self, now: datetime | None = None) -> int:
+        """Count pending-registration rows whose ``expires_at`` is in the future.
+
+        "Unexpired" rather than a raw row-count because SQL backends
+        accumulate dead rows until ``purge_expired`` runs — a raw
+        count would double-report a verification email that's been
+        unanswered for a month and a fresh one sent today.
+
+        Args:
+            now: Reference instant. Defaults to ``datetime.now(UTC)``.
+
+        Returns:
+            Number of pending rows with ``expires_at > now``.
+        """
+        ...
+
 
 @runtime_checkable
 class BlacklistRepoProtocol(Protocol):

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/backends/sql/migrations/__init__.py

@@ -71,23 +71,29 @@ async def upgrade_async(database_url: str, revision: str = "head") -> None:
 
 def current(database_url: str) -> str | None:
     """Return the current revision recorded in alembic_version, or None
-    if the table doesn't exist (i.e. fresh DB)."""
-    engine = create_async_engine(database_url)
-
-    async def _read() -> str | None:
-        async with engine.connect() as conn:
-            return await conn.run_sync(_current_sync)
+    if the table doesn't exist (i.e. fresh DB).
 
+    Synchronous; do NOT call from inside a running event loop —
+    use :func:`current_async` instead.
+    """
     import asyncio
 
+    return asyncio.run(_current_async_impl(database_url))
+
+
+async def current_async(database_url: str) -> str | None:
+    """Async variant of :func:`current` — safe to call from inside an
+    already-running event loop (e.g. ``regstack doctor``)."""
+    return await _current_async_impl(database_url)
+
+
+async def _current_async_impl(database_url: str) -> str | None:
+    engine = create_async_engine(database_url)
     try:
-        return asyncio.run(_read())
+        async with engine.connect() as conn:
+            return await conn.run_sync(_current_sync)
     finally:
-        # ``engine.dispose`` is async too; close on a fresh loop.
-        async def _close() -> None:
-            await engine.dispose()
-
-        asyncio.run(_close())
+        await engine.dispose()
 
 
 def _current_sync(connection) -> str | None:

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/backends/sql/repositories/pending_repo.py

@@ -4,7 +4,7 @@ import uuid
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import delete, select
+from sqlalchemy import delete, func, select
 
 from regstack.backends.sql.schema import pending_table
 from regstack.models.pending_registration import PendingRegistration
@@ -56,6 +56,14 @@ class SqlPendingRepo:
             result = await conn.execute(delete(self._t).where(self._t.c.expires_at < cutoff))
         return int(result.rowcount or 0)
 
+    async def count_unexpired(self, now: datetime | None = None) -> int:
+        cutoff = now or datetime.now(UTC)
+        async with self._engine.connect() as conn:
+            result = await conn.execute(
+                select(func.count()).select_from(self._t).where(self._t.c.expires_at > cutoff)
+            )
+        return int(result.scalar_one())
+
 
 def _pending_values(p: PendingRegistration) -> dict:
     return {

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/cli/doctor.py

@@ -127,10 +127,10 @@ async def _check_schema(config) -> CheckResult:
                 )
             return CheckResult("schema", True, "core indexes present")
         # SQL backends: compare alembic_version to the bundled head.
-        from regstack.backends.sql.migrations import current, head_revision
+        from regstack.backends.sql.migrations import current_async, head_revision
 
         url = config.database_url.get_secret_value()
-        live = current(url)
+        live = await current_async(url)
         head = head_revision()
         if live is None:
             return CheckResult(

{regstack-0.2.4 → regstack-0.2.6}/src/regstack/routers/admin.py

@@ -50,13 +50,7 @@ def build_admin_router(rs: RegStack) -> APIRouter:
         active = await rs.users.count(is_active=True)
         verified = await rs.users.count(is_verified=True)
         supers = await rs.users.count(is_superuser=True)
-        # PendingRegistrations don't have a count() yet — peek through the
-        # mongo backend; SQL backends will add a typed count too.
-        pending_count_doc = getattr(rs.pending, "_collection", None)
-        if pending_count_doc is not None:
-            pending = await pending_count_doc.count_documents({})
-        else:  # pragma: no cover — used by SQL backends in Phase 2
-            pending = 0
+        pending = await rs.pending.count_unexpired(rs.clock.now())
         return AdminStats(
             total_users=total,
             active_users=active,

regstack-0.2.6/src/regstack/version.py

@@ -0,0 +1 @@
+__version__ = "0.2.6"

{regstack-0.2.4 → regstack-0.2.6}/tasks.py

@@ -95,6 +95,48 @@ def test_serial(c: Context, k: str = "") -> None:
     c.run(cmd, pty=True)
 
 
+@task
+def coverage(
+    c: Context,
+    pg_url: str = _DEFAULT_PG_URL,
+    html: bool = True,
+    fail_under: int = 0,
+) -> None:
+    """Run the full backend matrix under coverage.
+
+    Combines per-worker .coverage.* files (pytest-xdist runs one
+    coverage instance per worker; settings.parallel = true plus
+    `coverage combine` glues them back together) and prints the
+    line-coverage report. With --html (default), also writes an
+    HTML report under ``htmlcov/``.
+
+    Set ``--fail-under=N`` to make the task exit non-zero when total
+    line coverage drops below N percent — useful in CI.
+    """
+    # Wipe stale coverage state so partial reruns don't leave double-counted
+    # data files behind.
+    c.run("uv run coverage erase", pty=True, warn=True)
+    env = {
+        "REGSTACK_TEST_BACKENDS": "sqlite,mongo,postgres",
+        "REGSTACK_TEST_POSTGRES_URL": pg_url,
+        # pytest-cov picks settings up from [tool.coverage.*] in pyproject.toml.
+        "COVERAGE_PROCESS_START": "pyproject.toml",
+    }
+    c.run(
+        "uv run python -m pytest -n auto --cov=src/regstack --cov-report=",
+        pty=True,
+        env=env,
+    )
+    c.run("uv run coverage combine", pty=True, warn=True)
+    report_cmd = "uv run coverage report"
+    if fail_under > 0:
+        report_cmd += f" --fail-under={fail_under}"
+    c.run(report_cmd, pty=True)
+    if html:
+        c.run("uv run coverage html", pty=True)
+        print("\nHTML report: htmlcov/index.html")
+
+
 @task
 def e2e(c: Context) -> None:
     """Run Playwright end-to-end suite."""

{regstack-0.2.4 → regstack-0.2.6}/tests/integration/test_admin_router.py

@@ -161,6 +161,62 @@ async def test_admin_resend_verification(make_client) -> None:
         assert r.status_code == 400
 
 
+@pytest.mark.asyncio
+async def test_stats_pending_registrations_count_unexpired(make_client) -> None:
+    """Admin stats must report pending-registration count correctly on every backend.
+
+    Before this test landed, the stats route reached into Mongo's private
+    ``_collection`` attribute and silently returned 0 on SQL backends. The
+    parametrized ``backend_kind`` fixture means this asserts the count
+    against SQLite, MongoDB, and PostgreSQL in turn — a gap that survived
+    the multi-backend refactor because the existing admin tests didn't
+    pin this number.
+
+    Also seeds an already-expired pending row directly via the repo to
+    confirm the count excludes it (the SQL backend has no TTL reaper, so
+    this distinction matters).
+    """
+    from datetime import timedelta
+
+    from regstack.models.pending_registration import PendingRegistration
+
+    async with make_client(
+        require_verification=True,
+        enable_admin_router=True,
+    ) as (rs, client):
+        await rs.bootstrap_admin("admin@example.com", "adminadminadmin")
+        admin_token = await _login(client, "admin@example.com", "adminadminadmin")
+        headers = {"authorization": f"Bearer {admin_token}"}
+
+        # Two fresh registrations → two unexpired pending rows.
+        await client.post(REGISTER, json=ALICE)
+        await client.post(REGISTER, json=BOB)
+
+        r = await client.get(ADMIN_STATS, headers=headers)
+        assert r.status_code == 200
+        assert r.json()["pending_registrations"] == 2
+
+        # Insert a stale pending row directly, anchored to ``rs.clock`` so
+        # it's "in the past" from the route's POV (which also reads the
+        # injected clock). Mongo would reap it via TTL eventually; SQL
+        # leaves it in place until purge_expired runs. Either way,
+        # count_unexpired must exclude it.
+        stale = PendingRegistration(
+            email="stale@example.com",
+            hashed_password="x",
+            full_name="Stale",
+            token_hash="stale-token-hash",
+            expires_at=rs.clock.now() - timedelta(hours=1),
+        )
+        await rs.pending.upsert(stale)
+
+        r = await client.get(ADMIN_STATS, headers=headers)
+        assert r.status_code == 200
+        assert r.json()["pending_registrations"] == 2, (
+            f"stale row should not be counted: {r.json()}"
+        )
+
+
 @pytest.mark.asyncio
 async def test_admin_404_for_unknown_user(make_client) -> None:
     async with make_client(enable_admin_router=True) as (rs, client):

regstack-0.2.6/tests/unit/test_cli_doctor.py

@@ -0,0 +1,164 @@
+"""Tests for the ``regstack doctor`` CLI command.
+
+Targets the SQLite branch (no infrastructure required) and exercises:
+
+- the JWT-secret quality check (missing / too short / present)
+- the backend ``ping`` path
+- the schema check before and after ``install_schema``
+- the email-factory check
+- the ``--send-test-email`` path against the console backend
+- the ``--check-dns`` path with a domain we expect to fail
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import secrets
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from regstack.cli.__main__ import cli
+from regstack.cli._runtime import open_regstack
+
+
+def _write_sqlite_config(
+    tmp_path: Path,
+    *,
+    from_address: str = "noreply@example.com",
+) -> tuple[Path, Path]:
+    sqlite_path = tmp_path / "doctor.db"
+    cfg = tmp_path / "regstack.toml"
+    cfg.write_text(
+        f"""\
+app_name = "doctor-test"
+base_url = "http://localhost:8000"
+database_url = "sqlite+aiosqlite:///{sqlite_path}"
+
+jwt_ttl_seconds = 7200
+require_verification = false
+allow_registration = true
+
+[email]
+backend = "console"
+from_address = "{from_address}"
+from_name = "doctor-test"
+
+[sms]
+backend = "null"
+"""
+    )
+    return cfg, sqlite_path
+
+
+@pytest.fixture
+def doctor_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> tuple[Path, str]:
+    """Strip ambient REGSTACK_* vars, then set a known JWT secret + DB URL.
+
+    Returns ``(config_path, jwt_secret)``.
+    """
+    for var in list(os.environ):
+        if var.startswith("REGSTACK_"):
+            monkeypatch.delenv(var, raising=False)
+    secret = secrets.token_urlsafe(64)
+    cfg_path, sqlite_path = _write_sqlite_config(tmp_path)
+    monkeypatch.setenv("REGSTACK_JWT_SECRET", secret)
+    monkeypatch.setenv("REGSTACK_DATABASE_URL", f"sqlite+aiosqlite:///{sqlite_path}")
+    return cfg_path, secret
+
+
+def test_doctor_reports_schema_missing_then_present(
+    doctor_env: tuple[Path, str],
+) -> None:
+    """Pre-install: doctor reports schema missing. Post-install: green."""
+    cfg_path, _ = doctor_env
+    runner = CliRunner()
+
+    # Pre-install: schema check fails (alembic_version table missing).
+    result = runner.invoke(cli, ["doctor", "--config", str(cfg_path)])
+    assert result.exit_code >= 1
+    assert "schema" in result.output
+    assert "alembic_version table missing" in result.output
+    assert "jwt secret" in result.output
+    assert "email backend" in result.output
+
+    # Install schema, then re-run.
+    async def _install() -> None:
+        async with open_regstack(cfg_path) as rs:
+            await rs.install_schema()
+
+    asyncio.run(_install())
+
+    result = runner.invoke(cli, ["doctor", "--config", str(cfg_path)])
+    assert result.exit_code == 0, result.output
+    assert "at head" in result.output
+
+
+def test_doctor_flags_short_jwt_secret(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    for var in list(os.environ):
+        if var.startswith("REGSTACK_"):
+            monkeypatch.delenv(var, raising=False)
+    cfg_path, sqlite_path = _write_sqlite_config(tmp_path)
+    monkeypatch.setenv("REGSTACK_JWT_SECRET", "too-short")
+    monkeypatch.setenv("REGSTACK_DATABASE_URL", f"sqlite+aiosqlite:///{sqlite_path}")
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["doctor", "--config", str(cfg_path)])
+    assert result.exit_code >= 1
+    assert "jwt secret" in result.output
+    assert "too short" in result.output
+
+
+def test_doctor_send_test_email_via_console(doctor_env: tuple[Path, str]) -> None:
+    """--send-test-email succeeds against the console backend (it just prints)."""
+    cfg_path, _ = doctor_env
+
+    # Bring schema up so the schema check passes — otherwise the failed
+    # schema check makes doctor exit non-zero and we can't observe the
+    # send-test-email check independently.
+    async def _install() -> None:
+        async with open_regstack(cfg_path) as rs:
+            await rs.install_schema()
+
+    asyncio.run(_install())
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "doctor",
+            "--config",
+            str(cfg_path),
+            "--send-test-email",
+            "probe@example.com",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert "email send" in result.output
+    assert "probe@example.com" in result.output
+
+
+def test_doctor_check_dns_runs_lookups(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """--check-dns runs SPF/DKIM/MX lookups for the sender domain.
+
+    We use ``example.com`` as the sender — it's RFC 2606 reserved so it
+    accepts no traffic, which is fine here: we only care that doctor
+    actually invokes the dig probes (the labels appear in output) and
+    handles whatever response comes back without crashing.
+    """
+    for var in list(os.environ):
+        if var.startswith("REGSTACK_"):
+            monkeypatch.delenv(var, raising=False)
+    cfg_path, sqlite_path = _write_sqlite_config(tmp_path, from_address="probe@example.com")
+    monkeypatch.setenv("REGSTACK_JWT_SECRET", secrets.token_urlsafe(64))
+    monkeypatch.setenv("REGSTACK_DATABASE_URL", f"sqlite+aiosqlite:///{sqlite_path}")
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["doctor", "--config", str(cfg_path), "--check-dns"])
+    # The schema check fails (we didn't install it), so exit code ≥ 1 —
+    # we just care that the DNS check labels are present in output.
+    assert "dns mx" in result.output
+    assert "dns spf" in result.output
+    assert "dns dmarc" in result.output