brain-of-reese/app/api/ui_settings.py

"""UI settings admin API (phase 91, task 01).

The persistence surface of the admin Theme tab (the tab itself lands in
tasks 04/05): the single ``ui_settings`` row (id 1) that stores what the
admin sets — the app name, input placeholder, footer text, and the 17
palette colors (the 9 identity colors + the 8 semantic state colors,
phase 93 — B3 revised). The whole router sits behind
:func:`app.core.auth.require_admin` (router-wide ``dependencies`` — the
:mod:`app.api.tokens` pattern): anonymous callers AND token users get
403 on every route (only the admin themes the deployment).

Routes (under ``/api`` via the ``main`` registration):

* ``GET /api/ui-settings`` — the EFFECTIVE values (the resolver's
  DB-over-env / DB-over-built-in merge, B1): a missing row reports the
  env strings + the built-in palette, so a fresh tab shows the live
  theme. Creates nothing.
* ``PUT /api/ui-settings`` — a FULL replacement of the row: each
  string is trimmed (empty → NULL, >300 → 422 naming the field), each
  color must match ``^#[0-9a-fA-F]{6}$`` (lowercased on store, else 422
  naming the field), and — the owner-locked normalization — a color
  equal to its built-in is stored as NULL, so "save the defaults"
  leaves the row empty and the served HTML stays byte-identical (the
  no-op injection contract, task 02). Upserts the id-1 row (SELECT →
  update-or-insert); a concurrent PUT is single-admin — last writer
  wins. Returns the new effective values.
"""
from __future__ import annotations

import re

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.config import Settings, get_settings
from app.core import theming
from app.core.auth import require_admin
from app.db import get_db
from app.models import UiSettings
from app.schemas import UiSettingsIn, UiSettingsOut

router = APIRouter(
    prefix="/ui-settings",
    tags=["ui-settings"],
    dependencies=[Depends(require_admin)],  # phase 91: the Theme tab is admin-only
)

#: The ``#rrggbb`` shape the color pickers produce (case-insensitive;
#: lowercased on store so the stored/tagged hex is canonical).
_HEX_COLOR = re.compile(r"^#[0-9a-fA-F]{6}$")
#: The strings' column length (mirrors ``ui_settings`` VARCHAR(300)).
_MAX_STRING_LEN = 300


def _validate_strings(payload: UiSettingsIn) -> dict[str, str | None]:
    """Trim the 3 display strings: empty after the trim → ``None``
    (the clear operation), >300 chars after the trim → 422 naming the
    field (the house fixed-detail style — the detail never varies by
    value beyond naming the field)."""
    values: dict[str, str | None] = {}
    for field in theming.STRING_FIELDS:
        raw = getattr(payload, field)
        if raw is None:
            values[field] = None
            continue
        value = raw.strip()
        if len(value) > _MAX_STRING_LEN:
            raise HTTPException(
                status_code=422, detail=f"{field} is too long (max 300)"
            )
        values[field] = value or None
    return values


def _validate_colors(payload: UiSettingsIn) -> dict[str, str | None]:
    """Validate + normalize the 17 palette colors (the 9 identity +
    the 8 semantic state — all ``COLOR_FIELDS``-driven, phase 93):
    strict ``#rrggbb`` (else 422 naming the field), lowercased on
    store, and a value equal to its BUILT-IN is stored as ``None`` —
    the owner-locked normalization that keeps "save the defaults"
    byte-identical (the row stays empty, the no-op injection
    contract)."""
    values: dict[str, str | None] = {}
    for field in theming.COLOR_FIELDS:
        raw = getattr(payload, field)
        if raw is None:
            values[field] = None
            continue
        if _HEX_COLOR.fullmatch(raw) is None:
            raise HTTPException(
                status_code=422, detail=f"{field} must be a #rrggbb hex color"
            )
        value = raw.lower()
        values[field] = None if value == theming.BUILTIN_COLORS[field] else value
    return values


@router.get("", response_model=UiSettingsOut)
def get_ui_settings(
    settings: Settings = Depends(get_settings),  # noqa: B008
    db: Session = Depends(get_db),  # noqa: B008
) -> UiSettingsOut:
    """The effective UI settings — DB-over-env / DB-over-built-in (B1).

    Reads only: a missing row means "defaults" (the env strings + the
    built-in palette), so a fresh deployment's tab shows the live theme
    with an empty row, and nothing is ever upserted by a read.
    """
    return UiSettingsOut(**theming.effective_settings(db, settings))


@router.put("", response_model=UiSettingsOut)
def update_ui_settings(
    payload: UiSettingsIn,
    settings: Settings = Depends(get_settings),  # noqa: B008
    db: Session = Depends(get_db),  # noqa: B008
) -> UiSettingsOut:
    """Replace the single row with the body's 20 values (validated and
    normalized — see the module docstring), then report the new
    effective values.

    Upsert on the id-1 row (SELECT → update-or-insert; the Python-side
    ``default=1`` supplies the PK on the insert). Concurrency is
    single-admin (one owner, one tab) — the last writer wins and no
    lock is taken: a lost race just means the other admin's PUT is the
    effective one.
    """
    strings = _validate_strings(payload)
    colors = _validate_colors(payload)
    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
    if row is None:
        row = UiSettings(id=1)
        db.add(row)
    for field in theming.STRING_FIELDS:
        setattr(row, field, strings[field])
    for field in theming.COLOR_FIELDS:
        setattr(row, field, colors[field])
    db.commit()
    return UiSettingsOut(**theming.effective_settings(db, settings))