"""Jails router — v2 (pre-production).

This router contains the next-generation version of the jails API,
intended for the v2 breaking-change release. It is registered in
``app/main.py`` but is NOT active for production traffic until the
v2 launch milestone is completed.

To activate v2 for a specific endpoint, move the handler from the v1
router to this router and remove the ``include_in_schema=False`` flag.

Until then, all endpoints here return ``404 Not Found`` so they do not
interfere with live v1 traffic.
"""

from __future__ import annotations

from fastapi import APIRouter, status
from fastapi.responses import JSONResponse

#: Set to ``True`` once v2 is declared production-ready.
_V2_ENABLED: bool = False

router: APIRouter = APIRouter(prefix="/api/v2/jails", tags=["Jails (v2)"])


@router.get(
    "",
    include_in_schema=False,
)
async def jails_v2_placeholder() -> JSONResponse:
    """Placeholder handler — v2 not yet enabled.

    Returns 404 so this router never serves real traffic until v2 is
    explicitly activated. When v2 goes live, remove this handler and
    expose the real endpoints.
    """
    return JSONResponse(
        status_code=status.HTTP_404_NOT_FOUND,
        content={"detail": "v2 endpoint not yet available"},
    )