refactor(users): split into admin/auth_local/oauth feature folders (#153)

* refactor(users): split into admin/auth_local/oauth feature folders

Reorganize the users module intra-package from a type-folder layout
(endpoints/, service.py, oauth.py at top level) to a feature-folder
layout where each sub-feature owns its routes, service, views, and
components.

  modules/users/users/
    admin/          # service, REST API, Inertia views, React components
    auth_local/     # login/register/reset/verify/profile + accept-invite
    oauth/          # provider builders + per-provider routes (__init__.py
                    # re-exports the prior `users.oauth.{X}` surface)

Shared infrastructure stays at top level (deps, manager, backend, models,
contracts, mailer, middleware, bootstrap, pages, locales).
UsersModule.register_routes is now the single point of cross-feature
wiring; no feature imports from a sibling feature in either the API or
views layer. The login page's OAuth-provider list is cached once at boot
on app.state.users.oauth_providers so auth_local/views.py doesn't reach
into the oauth feature.

Framework filesystem conventions are preserved unchanged: pages/ stays
a single tree at the package root (required by
simple_module_hosting.manifest.compute_module_pages) and locales/ stays
in place.

Scope: the users module only. The scaffold templates, framework-conventions
docs, and other modules are deliberately not touched — this is a POC to
validate the layout before propagating it.

Verified locally: make lint, make doctor, full pytest (1010 passed), JS
tests (8 passed), and a live uvicorn+Vite run exercising the refactored
auth_local/api login wrapper, auth_local/views login page, admin/api
list, admin/views Inertia index, and the moved admin/components/*.tsx
imports.

* fix(users): read login_redirect_url lazily on OAuth callback

Address two issues raised in PR review:

1. `oauth/api.py` captured `settings.login_redirect_url` as a string at
   route-registration time, then closed over it. `UsersModule.on_startup`
   mutates `app.state.users.settings.login_redirect_url` (dashboard
   fallback), and admins can change it at runtime via the settings UI,
   so OAuth callbacks could redirect to a stale URL. Now the callback
   reads it from `request.app.state.users.settings` at request time.
   `_build_provider_router` no longer takes a `login_redirect_url`
   parameter.

2. The `register_routes` comment claimed constructing `UsersSettings()`
   "re-reads env_str-bound fields like OAuth client ids/secrets" — this
   is wrong: `env_str()` is evaluated when `UsersSettings` is defined
   (class-attribute defaults), so re-instantiating doesn't re-read env.
   Updated to accurately describe why a fresh instance is acceptable
   here (only `build_clients` reads it, and only static fields) and to
   point readers at `app.state.users.settings` for mutable fields.

Both issues were pre-existing latent behaviour surfaced by the review
of this PR. Tests still pass (1010); doctor clean.

Author: antosubash

docs/testing/fixtures.md

@@ -105,7 +105,7 @@ The admin has `*` permission (via `DEFAULT_ROLE_PERMISSIONS["admin"]`), so it by
 ```python
 @pytest.mark.asyncio
 async def test_non_admin_denied(client, db_session):
-    from users.service import UserService
+    from users.admin.service import UserService
     svc = UserService(db_session)
     await svc.create(email="u@e.com", password="x", roles=["viewer"])
     await db_session.commit()

modules/users/tests/test_api_auth.py

@@ -198,7 +198,7 @@ async def test_forgot_password_rate_limited_after_threshold(
         self, anon_client, users_app, users_db
     ):
         """After the configured attempt budget, /forgot-password returns 429."""
-        from users.rate_limit import ThroughputLimiter
+        from users.auth_local.rate_limit import ThroughputLimiter
 
         # Tighten the limit for the test so we don't need to hit 10 real endpoints
         users_app.state.users.auth_throughput_limiter = ThroughputLimiter(

modules/users/tests/test_rate_limit.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import pytest
-from users.rate_limit import LoginRateLimiter, ThroughputLimiter
+from users.auth_local.rate_limit import LoginRateLimiter, ThroughputLimiter
 
 
 @pytest.fixture

modules/users/tests/test_service_admin.py

@@ -10,10 +10,10 @@
 
 def _build_service(session, users_app):
     """Build a UserService directly (bypass FastAPI Depends)."""
+    from users.admin.service import UserService
     from users.db_adapter import UserDatabaseWithRoles
     from users.manager import UserManager
     from users.models import User
-    from users.service import UserService
 
     user_db = UserDatabaseWithRoles(session, User)
     manager = UserManager(

modules/users/tests/test_user_service.py

@@ -9,10 +9,10 @@
 
 def _build_service(session, users_app):
     """Build a UserService directly (bypass FastAPI Depends)."""
+    from users.admin.service import UserService
     from users.db_adapter import UserDatabaseWithRoles
     from users.manager import UserManager
     from users.models import User
-    from users.service import UserService
 
     user_db = UserDatabaseWithRoles(session, User)
     manager = UserManager(
@@ -77,10 +77,10 @@ async def test_get_list_item_unknown_user_raises_user_not_found(users_app):
 async def test_to_list_item_includes_created_at(users_app):
     """`UserListItem` carries `created_at` sourced from AuditMixin."""
     from fastapi_users.password import PasswordHelper
+    from users.admin.service import UserService
     from users.db_adapter import UserDatabaseWithRoles
     from users.manager import UserManager
     from users.models import User
-    from users.service import UserService
 
     async with users_app.state.sm.db.session_factory() as session:
         user = User(

modules/users/tests/test_views.py

@@ -187,7 +187,7 @@ async def test_admin_edit_page_unknown_user_returns_404(admin_client):
 @pytest.mark.anyio
 async def test_roles_payload_returns_id_name_dicts(users_app):
     """Helper reads the roles cache and returns id/name dicts in cache order."""
-    from users.endpoints.views import _roles_payload
+    from users.admin.views import _roles_payload
 
     payload = await _roles_payload(users_app)
 

modules/users/users/admin/__init__.py

@@ -0,0 +1 @@
+"""Admin user management. Intentionally empty — import via fully-qualified paths."""

…dules/users/users/endpoints/api_admin.py modules/users/users/admin/api.pymodules/users/users/endpoints/api_admin.py renamed to modules/users/users/admin/api.py modules/users/users/endpoints/api_admin.py renamed to modules/users/users/admin/api.py

@@ -1,8 +1,4 @@
-"""Admin REST endpoints for the users module.
-
-Split out of :mod:`.api` to keep per-file complexity manageable. Mounted
-into the main ``router`` via ``include_router`` at the bottom of ``api.py``.
-"""
+"""Admin REST endpoints for the users module."""
 
 from __future__ import annotations
 
@@ -13,6 +9,7 @@
 from simple_module_core.events import EventBus
 from simple_module_hosting.permissions import RequiresPermission
 
+from users.admin.service import UserService
 from users.constants import PERM_USERS_MANAGE, sanitize_list_filters
 from users.contracts.events import RoleAssigned, UserDisabled, UserInvited
 from users.contracts.schemas import (
@@ -23,7 +20,6 @@
 )
 from users.deps import get_event_bus, get_mailer, get_user_service
 from users.exceptions import UserNotFoundError
-from users.service import UserService
 
 admin_router = APIRouter(
     prefix="/admin",