regstack 0.2.3__tar.gz → 0.2.5__tar.gz

{regstack-0.2.3 → regstack-0.2.5}/CHANGELOG.md

@@ -5,6 +5,42 @@ authoritative copy lives at
 [`docs/changelog.md`](docs/changelog.md) and is rendered into the
 Sphinx docs.
 
+## 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.install_indexes()` (alias for `install_schema()`).
+- `ObjectIdStr` alias for `IdStr` in `regstack.models._objectid`.
+- Re-exports of `UserAlreadyExistsError`,
+  `PendingAlreadyExistsError`, `MfaVerifyOutcome`, and
+  `MfaVerifyResult` from `regstack.backends.mongo.repositories.*`.
+  Their canonical home is `regstack.backends.protocols`.
+
+If you import any of these from the old paths, switch to:
+- `RegStack.install_schema()`
+- `from regstack.models._objectid import IdStr`
+- `from regstack.backends.protocols import UserAlreadyExistsError`
+  (and friends).
+
+The internal mongo `install_indexes(db, config)` function is unchanged.
+
 ## 0.2.3 — 2026-04-28
 
 Docs-only release. Restructured the API reference around the current

{regstack-0.2.3 → regstack-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regstack
-Version: 0.2.3
+Version: 0.2.5
 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.3 → regstack-0.2.5}/docs/architecture.md

@@ -72,7 +72,6 @@ The façade exposes:
 - `backend` — the active `regstack.backends.base.Backend`.
 - `install_schema()` — install indexes (Mongo) or run
   [Alembic](https://alembic.sqlalchemy.org/) migrations (SQL).
-  `install_indexes()` is kept as a back-compat alias.
 - `aclose()` — tear down the backend's connection pool.
 - `bootstrap_admin(email, password)`,
   `add_template_dir(path)`, `set_email_backend(...)`,

{regstack-0.2.3 → regstack-0.2.5}/docs/changelog.md

@@ -3,6 +3,70 @@
 All notable changes to this project are documented here. Versions follow
 [Semantic Versioning](https://semver.org/) once `1.0.0` ships.
 
+## 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
+multi-backend refactor has been removed.
+
+### Removed
+
+- `RegStack.install_indexes()` — the 0.1.x alias for
+  `install_schema()`. Call `install_schema()`.
+- `ObjectIdStr` alias for `IdStr` in `regstack.models._objectid`.
+  Import `IdStr` directly.
+- `__all__`-based re-exports of `UserAlreadyExistsError`,
+  `PendingAlreadyExistsError`, `MfaVerifyOutcome`, and
+  `MfaVerifyResult` from `regstack.backends.mongo.repositories.*` and
+  the package `__init__`. Their canonical home is
+  `regstack.backends.protocols`; that's where every consumer in the
+  package itself already imports them.
+
+### Migration
+
+| Old                                                                              | New                                                            |
+|----------------------------------------------------------------------------------|----------------------------------------------------------------|
+| `await regstack.install_indexes()`                                               | `await regstack.install_schema()`                              |
+| `from regstack.models._objectid import ObjectIdStr`                              | `from regstack.models._objectid import IdStr`                  |
+| `from regstack.backends.mongo.repositories.user_repo import UserAlreadyExistsError`     | `from regstack.backends.protocols import UserAlreadyExistsError`     |
+| `from regstack.backends.mongo.repositories.pending_repo import PendingAlreadyExistsError` | `from regstack.backends.protocols import PendingAlreadyExistsError`  |
+| `from regstack.backends.mongo.repositories.mfa_code_repo import MfaVerifyOutcome, MfaVerifyResult` | `from regstack.backends.protocols import MfaVerifyOutcome, MfaVerifyResult` |
+
+The internal Mongo helper
+`regstack.backends.mongo.indexes.install_indexes(db, config)` is
+unchanged — that's the function `MongoBackend.install_schema` calls
+to actually create the indexes.
+
 ## 0.2.3 — 2026-04-28
 
 **Docs-only release.** API reference rewritten around the current

{regstack-0.2.3 → regstack-0.2.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "regstack"
-version = "0.2.3"
+version = "0.2.5"
 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.3 → regstack-0.2.5}/src/regstack/app.py

@@ -213,14 +213,6 @@ class RegStack:
         """
         await self.backend.install_schema()
 
-    async def install_indexes(self) -> None:
-        """Backwards-compatible alias for :meth:`install_schema`.
-
-        Kept for the 0.1.x ``install_indexes()`` name. New callers
-        should use :meth:`install_schema`.
-        """
-        await self.install_schema()
-
     async def aclose(self) -> None:
         """Tear down the backend's connection pool.
 

regstack-0.2.5/src/regstack/backends/mongo/repositories/__init__.py

@@ -0,0 +1,13 @@
+from regstack.backends.mongo.repositories.blacklist_repo import BlacklistRepo
+from regstack.backends.mongo.repositories.login_attempt_repo import LoginAttemptRepo
+from regstack.backends.mongo.repositories.mfa_code_repo import MfaCodeRepo
+from regstack.backends.mongo.repositories.pending_repo import PendingRepo
+from regstack.backends.mongo.repositories.user_repo import UserRepo
+
+__all__ = [
+    "BlacklistRepo",
+    "LoginAttemptRepo",
+    "MfaCodeRepo",
+    "PendingRepo",
+    "UserRepo",
+]

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/backends/mongo/repositories/mfa_code_repo.py

@@ -13,9 +13,6 @@ if TYPE_CHECKING:
     from regstack.auth.clock import Clock
 
 
-__all__ = ["MfaCodeRepo", "MfaVerifyOutcome", "MfaVerifyResult"]
-
-
 class MfaCodeRepo:
     def __init__(self, db: AsyncDatabase, collection_name: str, *, clock: Clock) -> None:
         self._collection = db[collection_name]

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/backends/mongo/repositories/pending_repo.py

@@ -13,9 +13,6 @@ if TYPE_CHECKING:
     from pymongo.asynchronous.database import AsyncDatabase
 
 
-__all__ = ["PendingAlreadyExistsError", "PendingRepo"]
-
-
 class PendingRepo:
     def __init__(self, db: AsyncDatabase, collection_name: str) -> None:
         self._collection = db[collection_name]

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/backends/mongo/repositories/user_repo.py

@@ -14,9 +14,6 @@ if TYPE_CHECKING:
     from pymongo.asynchronous.database import AsyncDatabase
 
 
-__all__ = ["UserAlreadyExistsError", "UserRepo"]
-
-
 def _bulk_revoke_cutoff(now: datetime) -> datetime:
     """The cutoff timestamp recorded on the user document. Stored at full
     microsecond precision; the JWT ``iat`` claim is also emitted as a float

{regstack-0.2.3 → regstack-0.2.5}/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.3 → regstack-0.2.5}/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.3 → regstack-0.2.5}/src/regstack/models/_objectid.py

@@ -7,10 +7,6 @@ the backend:
 - SQL backends use UUID4 hex (32-char).
 - Hosts with their own ID strategy can substitute anything else as long
   as it round-trips as a string.
-
-Historically this was named ``ObjectIdStr`` and validated 24-char hex
-only. The rename and relaxed contract landed when the SQL backends
-arrived; the old name is kept as an alias for any external imports.
 """
 
 from __future__ import annotations
@@ -49,7 +45,3 @@ class _IdValidator:
 
 
 IdStr = Annotated[str, _IdValidator]
-
-# Back-compat alias — the contract is now "any non-empty string", so
-# anyone reaching for ObjectIdStr keeps the same surface area.
-ObjectIdStr = IdStr

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/models/login_attempt.py

@@ -5,7 +5,7 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, EmailStr, Field
 
-from regstack.models._objectid import ObjectIdStr
+from regstack.models._objectid import IdStr
 
 
 def _utcnow() -> datetime:
@@ -19,7 +19,7 @@ class LoginAttempt(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 
-    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    id: IdStr | None = Field(default=None, alias="_id")
     email: EmailStr
     when: datetime = Field(default_factory=_utcnow)
     ip: str | None = None

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/models/mfa_code.py

@@ -5,7 +5,7 @@ from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from regstack.models._objectid import ObjectIdStr
+from regstack.models._objectid import IdStr
 
 MfaKind = Literal["phone_setup", "login_mfa"]
 
@@ -24,7 +24,7 @@ class MfaCode(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 
-    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    id: IdStr | None = Field(default=None, alias="_id")
     user_id: str
     kind: MfaKind
     code_hash: str

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/models/pending_registration.py

@@ -5,7 +5,7 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, EmailStr, Field
 
-from regstack.models._objectid import ObjectIdStr
+from regstack.models._objectid import IdStr
 
 
 def _utcnow() -> datetime:
@@ -23,7 +23,7 @@ class PendingRegistration(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 
-    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    id: IdStr | None = Field(default=None, alias="_id")
     email: EmailStr
     hashed_password: str
     full_name: str | None = None

{regstack-0.2.3 → regstack-0.2.5}/src/regstack/models/user.py

@@ -5,7 +5,7 @@ from typing import Annotated, Any
 
 from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
 
-from regstack.models._objectid import ObjectIdStr
+from regstack.models._objectid import IdStr
 
 
 def _utcnow() -> datetime:
@@ -25,7 +25,7 @@ class BaseUser(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True, extra="allow")
 
-    id: ObjectIdStr | None = Field(default=None, alias="_id")
+    id: IdStr | None = Field(default=None, alias="_id")
     email: EmailStr
     hashed_password: str
     is_active: bool = True

regstack-0.2.5/src/regstack/version.py

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

{regstack-0.2.3 → regstack-0.2.5}/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.5/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