astrololo: generowanie tekstu jako moduł odłączalny (2/5)

Drugi z pięciu kroków budowy trzech produktów. Czysty refaktor — zachowanie
aplikacji się nie zmienia, liczba testów rośnie tylko o nowe.

DLACZEGO WARUNEK W SZABLONIE NIE WYSTARCZA. Dotąd generowanie było chowane przez
`{% if can(request, 'ai') %}`. To sprawia, że funkcji nie WIDAĆ, ale nie że jej
NIE MA: plik szablonu dalej leży w obrazie i dalej zawiera jej nazwy, więc `grep`
po kontenerze pokazuje wszystko, czego warunek nie pokazał na ekranie. Astroklient
ma nie mieć śladu, nie mieć wyłączoną funkcję — więc granica musi być KATALOGIEM.

CO SIĘ PRZENIOSŁO do app/dodatki/: dwa szablony, pięć plików statycznych, trasa
strumienia, cztery metody klienta warstwy logicznej, wpis w katalogu funkcji,
wpisy tras i zasobów, akcje formularza i reguły CSS nazywające funkcję
(`textarea.prompt`).

JAK APLIKACJA O TO PYTA. Neutralny most `app/rozszerzenia.py` odpowiada wyłącznie
na pytanie „czy coś jest podpięte i co wnosi". Sam nie wymienia ani jednej nazwy —
pilnuje tego osobny test, bo most jest w KAŻDYM obrazie. Dlatego też katalog
nazywa się `dodatki`, a nie `ai`: nazwa w instrukcji importu byłaby dokładnie tym
śladem, którego wydzielanie ma się pozbyć.

TRZY MIEJSCA, KTÓRE OKAZAŁY SIĘ TRUDNE:

1. Pola formularza. FastAPI czyta je z SYGNATURY, a wspólny handler nie może
   wymieniać `prompt_budget` ani `llm_provider`. Rozwiązane zależnością: moduł
   deklaruje własne pola u siebie, handler wie tylko, że dostaje słownik.
2. Klient warstwy logicznej jest wspólny, więc metody `prompt`/`horoscope`/
   `llm_models` musiały z niego wyjść. Wspólny klient daje teraz samą drogę
   w dół (`wywolaj`, `pobierz`, `strumien`) — z szyfrowaniem łącza i tokenem
   międzywarstwowym; co nią pojedzie, jest sprawą modułu.
3. Podtytuł ekranu Skompiluj miał wariant „z AI" i wariant bez. Zamiast warunku
   jedno zdanie prawdziwe niezależnie od tego, jakie moduły są w obrazie.

DOCKERFILE. `COPY . .` wnosiło do obrazu także testy — a plik testowy nazywa
funkcje wprost. Teraz wchodzi wyłącznie `app/`.

TEST GRANICY. `test_ai_tylko_w_module.py` przechodzi po wszystkim poza modułem
i szuka siedemnastu słów. Znalazł dwanaście resztek, których nie widziałem:
komentarze w main.py i security.py, przykład `models.js` w komentarzu features.py,
komentarze w compile.js i w trzech arkuszach, oraz regułę `textarea.prompt`,
która przy rozbijaniu CSS trafiła do arkuszy ekranów zamiast do modułu.

Ma też kontrolę pozytywną (te słowa MAJĄ padać w module — inaczej test
przechodziłby, gdyby funkcję wydrążono) i test odłączalności mostu.

SPRAWDZONE NA KOPII BEZ MODUŁU: aplikacja startuje, wszystkie ekrany oddają 200,
katalog ma 13 funkcji zamiast 14, trasy strumienia nie ma, spreparowane
`action=prompt` wraca do akcji domyślnej bez śladu, a `grep` po drzewie nie
znajduje ani jednego ze słów.

Testy: presentation 362, logic 342, data 37, render 41.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

services/presentation/app/main.py

@@ -19,13 +19,15 @@ from functools import lru_cache
 from pathlib import Path
 
 import httpx
-from fastapi import FastAPI, File, Form, HTTPException, Query, Request, UploadFile
+from fastapi import (FastAPI, Depends, File, Form, HTTPException, Query, Request,
+                     UploadFile)
 from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse, Response
 from fastapi.templating import Jinja2Templates
 
 import base64
 
 from app import accounts as accounts_store
+from app import rozszerzenia
 from app import chartwheel as chartwheel_mod
 from app import features
 from app import session
@@ -42,7 +44,11 @@ from app.config import DEFAULT_LOCATION_LABEL, default_form
 # gdyby obok leżał ich katalog. Znalezione testem przechodzącym po trasach aplikacji.
 app = FastAPI(title="astrololo · warstwa prezentacji",
               docs_url=None, redoc_url=None, openapi_url=None)
-templates = Jinja2Templates(directory="app/templates")
+# Katalogi modułów opcjonalnych idą PRZED wspólnym: moduł może dołożyć szablon,
+# którego wspólny zestaw nie ma. Wspólne szablony wołają je przez neutralne
+# gniazda `{% include "_dodatki_*" ignore missing %}` — bez modułu gniazdo jest
+# po prostu puste, a nie „wyłączone".
+templates = Jinja2Templates(directory=[*rozszerzenia.katalog_szablonow(), "app/templates"])
 # Szczegóły awarii idą TUTAJ, nie na ekran (patrz _logic_error).
 log = logging.getLogger("astrololo.prezentacja")
 logic = LogicClient()
@@ -88,10 +94,13 @@ def _bez_komentarzy(tresc: str, sufiks: str) -> str:
 @lru_cache(maxsize=None)
 def _asset_body(name: str) -> bytes | None:
     """Treść zasobu tak, jak pójdzie na drut — albo None, gdy go nie ma."""
-    sciezka = (_STATIC_DIR / name).resolve()
-    korzen = _STATIC_DIR.resolve()
-    # Wyjście poza katalog zasobów: `..` w ścieżce albo dowiązanie na zewnątrz.
-    if korzen not in sciezka.parents or not sciezka.is_file():
+    for katalog in (*rozszerzenia.katalog_zasobow(), str(_STATIC_DIR)):
+        korzen = Path(katalog).resolve()
+        sciezka = (Path(katalog) / name).resolve()
+        # Wyjście poza katalog zasobów: `..` w ścieżce albo dowiązanie na zewnątrz.
+        if korzen in sciezka.parents and sciezka.is_file():
+            break
+    else:
         return None
     surowe = sciezka.read_bytes()
     sufiks = sciezka.suffix.lower()
@@ -202,7 +211,10 @@ def _build_utc(date: str, time: str, tz_offset: float) -> tuple[str, str]:
 # Akcja formularza → uprawnienie, którego wymaga. Akcji spoza tej mapy nie
 # ograniczamy; akcja Z mapy, na którą konto nie ma prawa, jest traktowana jak
 # NIEZNANA — czyli wraca do zachowania domyślnego ekranu.
-_AKCJE_POD_UPRAWNIENIEM = {"prompt": "ai", "horoscope": "ai", "export": "export"}
+# Akcje własne tego ekranu plus te, które wnoszą moduły opcjonalne. Aplikacja
+# nie wypisuje ich z nazwy — gdyby wypisywała, nazwa funkcji byłaby w kodzie
+# także tam, gdzie modułu nie ma.
+_AKCJE_POD_UPRAWNIENIEM = {"export": "export", **rozszerzenia.akcje()}
 
 
 def _dozwolona_akcja(request: Request, action: str, domyslna: str) -> str:
@@ -218,25 +230,6 @@ def _dozwolona_akcja(request: Request, action: str, domyslna: str) -> str:
     return action
 
 
-def _llm_catalog_for(request: Request) -> dict:
-    """Katalog modeli — pusty, gdy konto nie generuje tekstu przez model.
-
-    Katalog trafia do strony jako blok JSON, więc bez tego ograniczenia nazwy
-    dostawców, modeli i rozmiary okien kontekstu byłyby w źródle KAŻDEJ strony
-    Interpretacji i Kalendarza, także dla kont, które o modelach nie mają prawa
-    wiedzieć."""
-    return _llm_catalog() if "ai" in _perms(request) else {}
-
-
-def _llm_catalog() -> dict:
-    """Podpowiedzi modeli dla pola wyboru. Awaria logiki nie może wywrócić strony —
-    pole modelu jest tekstowe, więc bez katalogu nadal da się wpisać model ręcznie."""
-    try:
-        return logic.llm_models()
-    except httpx.HTTPError:
-        return {"providers": {}, "defaults": {}}
-
-
 def _report_records(report: dict | None) -> int:
     """Ile rekordów baz niesie raport — do dziennika audytowego (PRE-17).
 
@@ -287,7 +280,7 @@ def chart_form(request: Request):
     return templates.TemplateResponse(
         request, "chart.html",
         {"result": None, "form": default_form(), "location_label": DEFAULT_LOCATION_LABEL,
-         "llm_catalog": _llm_catalog_for(request)},
+         **rozszerzenia.kontekst_szablonu(request)},
     )
 
 
@@ -372,7 +365,7 @@ def compile_build(
     tables: bool = Form(False),               # LOG-23 — żywioły/faza/godziny w podsumowaniu
     wheel_orientation: str = Form(chartwheel_mod.ASC_LEFT),   # LOG-05 — obrót koła
 ):
-    """Składa raport: horoskop liczymy TU NA NOWO, a części od AI (interpretacja
+    """Składa raport: horoskop liczymy TU NA NOWO, a części z przeglądarki (interpretacja
     natalna i predykcje okresowe) dokłada przeglądarka z magazynu (PRE-22/23).
 
     Horoskop liczymy ponownie (czysta funkcja wejścia — tanio powtórzyć, bez
@@ -417,7 +410,7 @@ def compile_build(
 def compile_pdf(payload: dict):
     """Składa raport PDF (PRE-24) — woła usługę render po szyfrowanym łączu.
 
-    Wejście z przeglądarki, bo części od AI (interpretacja natalna i predykcje)
+    Wejście z przeglądarki, bo część kawałków (interpretacja natalna i predykcje)
     mieszkają w magazynie lokalnym. Kosmogram i tabele liczymy TU, żeby PDF
     zawierał dokładnie to, co widać na stronie.
 
@@ -584,7 +577,7 @@ def interpret_form(request: Request):
     return templates.TemplateResponse(
         request, "interpret.html",
         {"result": None, "form": default_form(), "location_label": DEFAULT_LOCATION_LABEL,
-         "llm_catalog": _llm_catalog_for(request)},
+         **rozszerzenia.kontekst_szablonu(request)},
     )
 
 
@@ -599,16 +592,16 @@ def interpret_run(
     lon: float = Form(0.0),
     group: bool = Form(False),
     action: str = Form("report"),
-    prompt_budget: str = Form("medium"),
-    llm_provider: str = Form("local"),
-    llm_model: str = Form(""),
+    # Pola wnoszone przez moduły opcjonalne. FastAPI czyta pola z sygnatury, a ta
+    # nie może ich wymieniać — w obrazie bez modułu byłyby nazwą nieistniejącej
+    # funkcji wpisaną w kod. Zależność przenosi deklarację do modułu.
+    dodatki: dict = Depends(rozszerzenia.pola_formularza()),
 ):
     form = {"person": person, "date": date, "time": time, "tz_offset": tz_offset,
-            "lat": lat, "lon": lon, "group": group, "prompt_budget": prompt_budget,
-            "llm_provider": llm_provider, "llm_model": llm_model}
+            "lat": lat, "lon": lon, "group": group, **dodatki}
     action = _dozwolona_akcja(request, action, "report")
     ctx: dict = {"form": form, "result": None, "error": None, "moment": None,
-                 "llm_catalog": _llm_catalog_for(request)}
+                 **rozszerzenia.kontekst_szablonu(request)}
     try:
         iso_utc, label = _build_utc(date, time, tz_offset)
         ctx["moment"] = label
@@ -627,16 +620,12 @@ def interpret_run(
                 media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                 headers={"Content-Disposition": 'attachment; filename="interpretacje.xlsx"'},
             )
-        if action == "prompt":
-            ctx["prompt_result"] = logic.prompt(
-                profile="natal", when_utc_iso=iso_utc, lat=lat, lon=lon, budget=prompt_budget,
-                provider=llm_provider, model=llm_model,
-            )
-        elif action == "horoscope":
-            ctx["prompt_result"] = logic.horoscope(
-                profile="natal", when_utc_iso=iso_utc, lat=lat, lon=lon,
-                budget=prompt_budget, provider=llm_provider, model=llm_model,
-            )
+        # Akcja może należeć do modułu opcjonalnego. `None` znaczy „nie jego",
+        # więc ekran robi to, co robi normalnie.
+        wynik = rozszerzenia.obsluz(action, profil="natal", iso_utc=iso_utc,
+                                    lat=lat, lon=lon, dodatki=dodatki)
+        if wynik is not None:
+            ctx["wynik_dodatku"] = wynik
         else:
             ctx["result"] = logic.report(when_utc_iso=iso_utc, lat=lat, lon=lon, group=group)
             security.audit_records(request, _report_records(ctx["result"]))
@@ -653,7 +642,7 @@ def timeline_form(request: Request):
     return templates.TemplateResponse(
         request, "timeline.html",
         {"result": None, "form": default_form(), "location_label": DEFAULT_LOCATION_LABEL,
-         "llm_catalog": _llm_catalog_for(request)},
+         **rozszerzenia.kontekst_szablonu(request)},
     )
 
 
@@ -669,31 +658,25 @@ def timeline_run(
     from_date: str = Form(...),
     to_date: str = Form(...),
     action: str = Form("timeline"),
-    prompt_budget: str = Form("medium"),
-    llm_provider: str = Form("local"),
-    llm_model: str = Form(""),
+    # Pola wnoszone przez moduły opcjonalne. FastAPI czyta pola z sygnatury, a ta
+    # nie może ich wymieniać — w obrazie bez modułu byłyby nazwą nieistniejącej
+    # funkcji wpisaną w kod. Zależność przenosi deklarację do modułu.
+    dodatki: dict = Depends(rozszerzenia.pola_formularza()),
 ):
-    form = {"person": person, "date": date, "time": time, "tz_offset": tz_offset, "lat": lat, "lon": lon,
-            "from_date": from_date, "to_date": to_date, "prompt_budget": prompt_budget,
-            "llm_provider": llm_provider, "llm_model": llm_model}
+    form = {"person": person, "date": date, "time": time, "tz_offset": tz_offset,
+            "lat": lat, "lon": lon, "from_date": from_date, "to_date": to_date,
+            **dodatki}
     action = _dozwolona_akcja(request, action, "timeline")
     ctx: dict = {"form": form, "result": None, "error": None, "moment": None,
-                 "llm_catalog": _llm_catalog_for(request)}
+                 **rozszerzenia.kontekst_szablonu(request)}
     try:
         iso_utc, label = _build_utc(date, time, tz_offset)
         ctx["moment"] = label
-        if action == "prompt":
-            ctx["prompt_result"] = logic.prompt(
-                profile="period", when_utc_iso=iso_utc, lat=lat, lon=lon,
-                budget=prompt_budget, from_date=from_date, to_date=to_date,
-                provider=llm_provider, model=llm_model,
-            )
-        elif action == "horoscope":
-            ctx["prompt_result"] = logic.horoscope(
-                profile="period", when_utc_iso=iso_utc, lat=lat, lon=lon,
-                budget=prompt_budget, provider=llm_provider, model=llm_model,
-                from_date=from_date, to_date=to_date,
-            )
+        wynik = rozszerzenia.obsluz(action, profil="period", iso_utc=iso_utc,
+                                    lat=lat, lon=lon, dodatki=dodatki,
+                                    od=from_date, do=to_date)
+        if wynik is not None:
+            ctx["wynik_dodatku"] = wynik
         else:
             ctx["result"] = logic.timeline(
                 when_utc_iso=iso_utc, lat=lat, lon=lon,
@@ -706,61 +689,6 @@ def timeline_run(
     return templates.TemplateResponse(request, "timeline.html", ctx)
 
 
-# ---------------- Postęp pisania horoskopu (strumień do okna z logiem) ----------------
-@app.post("/horoscope/stream")
-def horoscope_stream(
-    profile: str = Form("natal"),
-    date: str = Form(...),
-    time: str = Form(...),
-    tz_offset: float = Form(0.0),
-    lat: float = Form(0.0),
-    lon: float = Form(0.0),
-    prompt_budget: str = Form("medium"),
-    llm_provider: str = Form("local"),
-    llm_model: str = Form(""),
-    from_date: str = Form(""),
-    to_date: str = Form(""),
-):
-    """Przekazuje strumień postępu z logiki i DOKLEJA gotowy HTML wyniku.
-
-    Dzięki temu okno postępu wstawia dokładnie ten sam widok, który wyrenderowałoby
-    przeładowanie strony — jedno źródło prawdy dla wyglądu wyniku.
-    """
-    from fastapi.responses import StreamingResponse
-
-    try:
-        iso_utc, _ = _build_utc(date, time, tz_offset)
-    except ValueError as e:
-        return JSONResponse({"detail": f"Niepoprawne dane wejściowe: {e}"}, status_code=422)
-
-    payload: dict = {
-        "profile": profile, "when_utc": iso_utc, "lat": lat, "lon": lon,
-        "budget": prompt_budget, "provider": llm_provider, "model": llm_model,
-    }
-    if profile == "period" and from_date and to_date:
-        payload["from_date"], payload["to_date"] = from_date, to_date
-
-    def relay():
-        try:
-            for raw in logic.horoscope_stream(payload):
-                try:
-                    event = json.loads(raw)
-                except ValueError:
-                    continue
-                if event.get("type") == "result":
-                    html = templates.get_template("_prompt_result.html").render(
-                        prompt_result=event.get("result") or {}
-                    )
-                    event["html"] = html
-                yield json.dumps(event, ensure_ascii=False) + "\n"
-        except httpx.HTTPError as e:
-            yield json.dumps({"type": "error", "message": _logic_error(e)},
-                             ensure_ascii=False) + "\n"
-
-    return StreamingResponse(relay(), media_type="application/x-ndjson",
-                             headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"})
-
-
 # ---------------- Geokoder (proxy OSM/Nominatim dla wyszukiwarki lokalizacji) ----------------
 @app.get("/geocode")
 def geocode_search(q: str = Query("", description="Nazwa / adres / POI do wyszukania")):
@@ -946,7 +874,10 @@ def _accounts_context(request: Request, error: str = "", done: str = "") -> dict
         "users": users,
         "catalog": features.ALL,
         "screens": features.SCREENS,
-        "extras": features.EXTRAS,
+        # Rozszerzenia własne PLUS wniesione przez moduły opcjonalne — inaczej
+        # administrator nie mógłby nadać uprawnienia do funkcji, która w tym
+        # obrazie istnieje.
+        "extras": features.EXTRAS + features.DOKLADANE,
         "admin_login": security.app_user(),
         "store_path": accounts_store.store_path(),
         "error": error, "done": done,
@@ -1082,3 +1013,11 @@ def health() -> dict:
     # Sama „ok" — nazwa warstwy mówiła, że warstw jest więcej i jak się nazywa.
     # Kubernetes i compose czytają wyłącznie kod odpowiedzi.
     return {"status": "ok"}
+
+
+# ── moduły opcjonalne ──────────────────────────────────────────────────────
+# Na końcu pliku, bo moduł dostaje gotowe zależności (klienta logiki, szablony,
+# pomocnicze funkcje), a te muszą już istnieć. Bez modułu w obrazie to wywołanie
+# nie robi nic i aplikacja nie ma pojęcia, że czegoś brakuje.
+rozszerzenia.zamontuj(app, logic=logic, templates=templates,
+                      buduj_utc=_build_utc, blad=_logic_error)