feat(flags): serve /api/flags, and keep the public proxy off it

The endpoint and its exposure control ship together on purpose. The
moment /api/flags exists, app/api/[...path] forwards it — and the
response names every unreleased feature the codebase knows about, along
with whether it is on. Publishing that is the opposite of shipping dark.

Denied on an exact first-segment match, not a prefix, so /api/flagship
does not go down with /api/flags. Next reads the endpoint server-side
over the Docker network, which never transits the public proxy.

jest.setup.js now guards its browser globals. It runs for every suite,
including the one that declares @jest-environment node to exercise the
route handler — NextRequest needs Fetch API globals jsdom lacks, and
there is no window there to define matchMedia on.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015mWQnpye9F299NVRCCSRvj

backend/app.py

@@ -35,6 +35,7 @@ from .data_loader import (
     search_schools_typesense,
 )
 from .data_loader import get_data_info as get_db_info
+from . import flags
 from .places import build_place_registry
 from .schemas import METRIC_DEFINITIONS, RANKING_COLUMNS, SCHOOL_COLUMNS
 from .utils import clean_for_json, convert_to_native
@@ -459,6 +460,7 @@ def validate_postcode(postcode: Optional[str]) -> Optional[str]:
 async def lifespan(app: FastAPI):
     """Application lifespan - startup and shutdown events."""
     global _sitemaps
+    flags.init()
     print("Loading school data from marts...")
     df = load_school_data()
     if df.empty:
@@ -1263,6 +1265,18 @@ async def get_place(request: Request, kind: str, slug: str,
     }
 
 
+@app.get("/api/flags")
+@limiter.limit(f"{settings.rate_limit_per_minute}/minute")
+async def get_feature_flags(request: Request):
+    """Every declared flag and its current value.
+
+    Internal only. The Next proxy denies this path, because the response names
+    every unreleased feature the codebase knows about — which is exactly what
+    shipping dark is meant to keep quiet.
+    """
+    return flags.all_flags()
+
+
 @app.get("/api/data-info")
 @limiter.limit(f"{settings.rate_limit_per_minute}/minute")
 async def get_data_info(request: Request):

backend/tests/test_flags.py

@@ -72,3 +72,24 @@ def test_a_flag_older_than_the_limit_fails_this_test():
         "Remove the flag and the code branches it guards, or move its `added` "
         "date deliberately."
     )
+
+
+def _client():
+    from fastapi.testclient import TestClient
+    from backend import app as app_module
+    return TestClient(app_module.app, raise_server_exceptions=False)
+
+
+def test_the_flags_endpoint_lists_every_declared_flag(monkeypatch):
+    monkeypatch.setattr(flags, "_client", None)
+    body = _client().get("/api/flags").json()
+    assert set(body) == set(flags.REGISTRY)
+
+
+def test_the_flags_endpoint_answers_false_when_unleash_is_unreachable(monkeypatch):
+    # The endpoint must still answer. A frontend that cannot read flags renders
+    # everything dark, which is right; one that gets a 500 renders nothing.
+    monkeypatch.setattr(flags, "_client", None)
+    res = _client().get("/api/flags")
+    assert res.status_code == 200
+    assert all(v is False for v in res.json().values())