refactor(api-v3): split the 10,469-line blueprint into a package

web_interface/blueprints/api_v3.py held 111 routes, 56 helpers and 181
functions in one module -- 9% of the core by line count and three times the
next largest file. It becomes a package of nine route modules grouped by path
segment, plus __init__.py for the shared imports, constants, Blueprint and
helpers.

Every route module decorates the SAME api_v3 Blueprint object, so endpoint
names stay api_v3.<function>, the URL map is unchanged and app.py is untouched.
Verified: 111 routes before, 111 after, byte-identical rules, endpoints and
methods, and every endpoint still on the one blueprint.

  plugins   3,867   config    1,178   starlark  692   system  619
  fonts       452   misc        398   wifi      361   display 326   backup 212
  __init__  1,787 (imports, constants, Blueprint, 56 helpers)

Two things the URL-map check could not catch, both found by running the suite:

1. PROJECT_ROOT = Path(__file__).parent.parent.parent. Moving the code one
   directory deeper made that resolve to web_interface/ instead of the project
   root. Nothing failed at import; it surfaced as ~110 tests failing with 404s
   and "installation script not found", because every path built from it was
   one level too shallow. Now parents[3], and test_api_v3_url_map.py asserts
   PROJECT_ROOT/run.py exists so the next move cannot repeat it.

2. Module-attribute patching. Tests do
   monkeypatch.setattr(api_v3_module, "_BACKUP_EXPORT_DIR", ...) and a route
   module that binds such a name by value never sees the patch. The shared code
   therefore stays in __init__.py rather than moving to a _common submodule --
   it has to live on the module the tests patch -- and the eleven names tests
   patch are read back through the package (_pkg.X) instead of bound by value.
   Those eleven were found by AST-scanning every setattr in the test tree, not
   by guessing; "time" is among them, used to drive a fake clock through the
   second-resolution credential-backup filenames.

Test changes are confined to what genuinely moved: patch targets that now name
the owning route module, imports of helpers, and six tests that scan the api_v3
source as a file and now read the package directory.

Full suite: 4,278 passed, 68 skipped, 0 failed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9

test/web_interface/test_api_v3_backup_restore.py

@@ -230,7 +230,7 @@ class TestPluginReinstall:
     def test_missing_store_manager_is_reported_per_plugin(self, client, restore):
         restore.return_value = FakeResult(plugins_to_install=[{"plugin_id": "clock"}])
         api_v3.plugin_store_manager = None
-        with patch("web_interface.blueprints.api_v3.plugin_store_manager", None):
+        with patch("web_interface.blueprints.api_v3.backup.plugin_store_manager", None):
             body = post(client).get_json()
         assert body["data"]["plugins_failed"][0]["error"] == "Store manager unavailable"
 

test/web_interface/test_calendar_oauth_endpoints.py

@@ -77,7 +77,10 @@ class TestTheRoutesExistAtAll:
         oauth = Path(project_root) / 'web_interface/static/v3/js/widgets/google-oauth.js'
         assert '/api/v3/plugins/calendar/list-calendars' in picker.read_text(encoding='utf-8')
         assert '/api/v3/plugins/calendar/authenticate' in oauth.read_text(encoding='utf-8')
-        source = (Path(project_root) / 'web_interface/blueprints/api_v3.py').read_text(encoding='utf-8')
+        # api_v3 is a package now, so the route strings are spread across its
+        # modules; read the whole directory rather than one file.
+        pkg = Path(project_root) / 'web_interface/blueprints/api_v3'
+        source = "\n".join(f.read_text(encoding='utf-8') for f in sorted(pkg.glob('*.py')))
         assert "'/plugins/calendar/list-calendars'" in source
         assert "'/plugins/calendar/authenticate'" in source
 

test/web_interface/test_config_logging_omits_secrets.py

@@ -10,8 +10,8 @@ from pathlib import Path
 
 import pytest
 
-SOURCE = (Path(__file__).resolve().parents[2]
-          / "web_interface" / "blueprints" / "api_v3.py")
+API_V3_PKG = (Path(__file__).resolve().parents[2]
+              / "web_interface" / "blueprints" / "api_v3")
 
 #: Objects that still hold submitted secret values at the point these log
 #: calls run. Interpolating one whole into a log message leaks credentials.
@@ -19,7 +19,7 @@ UNREDACTED = ("plugin_config", "secrets_config", "current_secrets")
 
 
 def _logging_lines():
-    for number, line in enumerate(SOURCE.read_text(encoding="utf-8").splitlines(), 1):
+    for number, line in enumerate("\n".join(p.read_text(encoding="utf-8") for p in sorted(API_V3_PKG.glob("*.py"))).splitlines(), 1):
         stripped = line.strip()
         if stripped.startswith("#"):
             continue

test/web_interface/test_secret_separation_parity.py

@@ -15,8 +15,18 @@ from pathlib import Path
 
 from src.web_interface.secret_helpers import find_secret_fields, separate_secrets
 
-API_V3_PATH = (Path(__file__).resolve().parents[2]
-               / "web_interface" / "blueprints" / "api_v3.py")
+API_V3_PKG = (Path(__file__).resolve().parents[2]
+              / "web_interface" / "blueprints" / "api_v3")
+
+
+def _api_v3_source() -> str:
+    """Every module of the api_v3 package as one string.
+
+    It used to be a single file; the inline copies this guards against could
+    now reappear in any module of the package.
+    """
+    return "\n".join(p.read_text(encoding="utf-8")
+                     for p in sorted(API_V3_PKG.glob("*.py")))
 
 # The migration is complete: any inline reimplementation is a regression.
 EXPECTED_INLINE_COPIES = 0
@@ -24,7 +34,7 @@ EXPECTED_INLINE_COPIES = 0
 
 class TestNoInlineCopies:
     def _count(self, name: str) -> int:
-        source = API_V3_PATH.read_text(encoding="utf-8")
+        source = _api_v3_source()
         return len(re.findall(rf"^\s*def {name}\(", source, flags=re.MULTILINE))
 
     def test_no_inline_find_secret_fields(self):
@@ -46,7 +56,7 @@ class TestNoInlineCopies:
     def test_canonical_import_present(self):
         # Tripwire: the endpoints still need the helpers, so removing the
         # import means either dead secret handling or a new local copy.
-        source = API_V3_PATH.read_text(encoding="utf-8")
+        source = _api_v3_source()
         assert re.search(
             r"from src\.web_interface\.secret_helpers import .*find_secret_fields",
             source,

test/web_interface/test_starlark_pixlet_routes.py

@@ -63,14 +63,14 @@ class TestRoutesAreRegistered:
 
 class TestInstallPixlet:
     def test_it_does_not_404(self, client):
-        with patch('web_interface.blueprints.api_v3.subprocess.run') as run:
+        with patch('web_interface.blueprints.api_v3.starlark.subprocess.run') as run:
             run.return_value = MagicMock(returncode=0, stdout="ok", stderr="")
             resp = client.post('/api/v3/starlark/install-pixlet')
         assert resp.status_code != 404, "the route is still missing"
         assert resp.get_json().get('message') != 'Resource not found'
 
     def test_success_is_reported_in_the_shape_the_button_reads(self, client):
-        with patch('web_interface.blueprints.api_v3.subprocess.run') as run:
+        with patch('web_interface.blueprints.api_v3.starlark.subprocess.run') as run:
             run.return_value = MagicMock(returncode=0, stdout="done", stderr="")
             resp = client.post('/api/v3/starlark/install-pixlet')
         body = resp.get_json()
@@ -78,7 +78,7 @@ class TestInstallPixlet:
         assert 'message' in body, "the JS shows data.message on success"
 
     def test_a_failed_download_says_why(self, client):
-        with patch('web_interface.blueprints.api_v3.subprocess.run') as run:
+        with patch('web_interface.blueprints.api_v3.starlark.subprocess.run') as run:
             run.return_value = MagicMock(returncode=1, stdout="", stderr="no such release")
             resp = client.post('/api/v3/starlark/install-pixlet')
         body = resp.get_json()
@@ -88,7 +88,7 @@ class TestInstallPixlet:
 
     def test_a_timeout_is_reported_rather_than_hanging(self, client):
         import subprocess as sp
-        with patch('web_interface.blueprints.api_v3.subprocess.run',
+        with patch('web_interface.blueprints.api_v3.starlark.subprocess.run',
                    side_effect=sp.TimeoutExpired(cmd='x', timeout=300)):
             resp = client.post('/api/v3/starlark/install-pixlet')
         assert resp.get_json()['status'] == 'error'

test/web_interface/test_systemctl_sudoers_alignment.py

@@ -19,7 +19,12 @@ import re
 from pathlib import Path
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
-API_V3 = PROJECT_ROOT / "web_interface" / "blueprints" / "api_v3.py"
+# api_v3 is a package; a sudo systemctl call can live in any of its modules.
+API_V3_PKG = PROJECT_ROOT / "web_interface" / "blueprints" / "api_v3"
+
+
+def _api_v3_source() -> str:
+    return "\n".join(p.read_text() for p in sorted(API_V3_PKG.glob("*.py")))
 SUDOERS_SCRIPT = PROJECT_ROOT / "scripts" / "install" / "configure_web_sudo.sh"
 
 
@@ -51,7 +56,7 @@ def _granted_systemctl_rules(script: str) -> set[tuple[str, str]]:
 
 
 def test_every_sudo_systemctl_call_is_granted() -> None:
-    calls = _sudo_systemctl_calls(API_V3.read_text())
+    calls = _sudo_systemctl_calls(_api_v3_source())
     rules = _granted_systemctl_rules(SUDOERS_SCRIPT.read_text())
 
     assert calls, "expected to find sudo systemctl calls in api_v3.py"
@@ -68,7 +73,7 @@ def test_every_sudo_systemctl_call_is_granted() -> None:
 def test_units_are_fully_qualified() -> None:
     """Privileged systemctl calls must name the unit as <name>.service so they
     match the sudoers grants, which use the fully-qualified unit name."""
-    calls = _sudo_systemctl_calls(API_V3.read_text())
+    calls = _sudo_systemctl_calls(_api_v3_source())
     unqualified = {(v, u) for v, u in calls if not u.endswith(".service")}
     assert not unqualified, (
         "sudo systemctl calls must use fully-qualified .service unit names: "