feat(diagnostics): send a bug report to a private Gitea issue tracker (E16 S4)

- admin config group "Bug reports": Gitea address, repository, token (secret),
  and "Check the connection" — the repository must answer, take issues and
  be PRIVATE (a report carries its reporter's log); checked on every send too
- POST /api/debug-sessions/{id}/issue sends the SAVED draft: create the issue,
  upload each file on its own request (the measured API), then show the
  screenshots inline; progress is kept in the draft, so a send that stops
  half-way keeps its issue and the retry sends only what is missing; 5 new
  issues an hour per user; audited as issue_create
- the composer: Create issue (only where a tracker is set up, naming the
  repository), a partial-send banner with retry, and a Preview — the tracker's
  own rendering in a sandboxed frame, or the zip's markdown without one
- the recorder's refusals answer in the localized family (debug_session_*,
  screenshot_*, issue(s)_*), not bare codes the UI could only call generic
- a tracker refusal logs the status only: its message can quote the title back

backend/app/audit.py

@@ -58,6 +58,9 @@ class AuditAction:
     DOWNLOAD_CREDENTIAL_DELETE = "download_credential_delete"
     # The log itself was cleared (a single row survives the clear as tamper-evidence)
     AUDIT_CLEAR = "audit_clear"
+    # E16: a user sent a debug session's issue to the tracker — the one act that takes their log
+    # off this instance, so it is recorded (target = the session, summary = the issue's URL).
+    ISSUE_CREATE = "issue_create"
 
 
 def record(

backend/app/config.py

@@ -351,6 +351,13 @@ class Settings(BaseSettings):
     tmdb_api_base: str = "https://api.themoviedb.org/3"
     # Metadata language for TMDB fetches (keyword/overview locale). Stored EN by default.
     tmdb_language: str = "en-US"
+
+    # --- Bug reports (E16): where a debug session's issue goes. All three empty = no tracker; the
+    # composer still exports a zip. The repository must be PRIVATE — an issue carries the reporter's
+    # log — and app/issues/gitea.py refuses a public one. Runtime knobs (sysconfig, admin UI). ---
+    issues_gitea_url: str = ""
+    issues_gitea_repo: str = ""
+    issues_gitea_token: str = ""
     # How often the TMDB enrichment job fetches a batch of not-yet-enriched Plex titles, in minutes.
     tmdb_enrich_interval_min: int = 120
     # Titles fetched per TMDB enrichment run (TMDB is fast + generously rate-limited).

backend/app/debugsession.py

@@ -145,6 +145,8 @@ def serialize(session: DebugSession | None, screenshots: int = 0) -> dict | None
         "ended_at": session.ended_at.isoformat() if session.ended_at else None,
         "ended_reason": session.ended_reason,
         "issue_url": session.issue_url,
+        # A send that stopped half-way (app/issues/gitea.py): the files still to go.
+        "pending_files": ((session.draft or {}).get("delivery") or {}).get("pending") or [],
         "screenshots": screenshots,
         "draft": session.draft,
     }

backend/app/issues/gitea.py

@@ -0,0 +1,194 @@
+"""The Gitea issue tracker a debug session's issue goes to (E16 S4) — measured against Gitea 1.27.1
+before a line of this was written (plans/e16-debug-issue.md, S0).
+
+Configured by an admin (sysconfig `issues_gitea_url` / `_repo` / `_token`, the token encrypted at
+rest). The repository must be PRIVATE: an issue carries its reporter's log — page titles, filter
+values, at Teljes what they typed into search — and a public repository would publish it. That is
+checked on every send, not only in the admin's "test connection", because a repository can be made
+public after the fact.
+
+What an issue is made of comes from `bundle.files` (the same files the zip export carries). Sending
+is three kinds of call, measured:
+  * `POST /repos/{repo}/issues` — the title and the body the user wrote;
+  * `POST /repos/{repo}/issues/{n}/assets?name=…` — ONE file per request (field `attachment`);
+  * `PATCH /repos/{repo}/issues/{n}` — the body again, with the screenshots shown inline once their
+    links exist.
+A private repository's attachment answers 404 to a browser not signed in to Gitea, which is why the
+composer's own preview shows our copies, never these links.
+
+Delivery keeps its progress in the session's draft (`delivery`: the issue number, the files still to
+upload, the links of those uploaded), so a failure half-way keeps the issue that exists and a retry
+sends only what is missing — never a second issue. Every step flushes; the caller commits, also
+when a step fails, so what did happen is kept.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Literal
+
+import httpx
+from sqlalchemy.orm import Session
+
+from app import logs, sysconfig
+from app.issues import bundle
+from app.models import DebugSession
+
+log = logs.get_logger(__name__)
+
+TIMEOUT_SECONDS = 20.0
+
+Reason = Literal[
+    "not_configured",  # url, repository or token missing
+    "unreachable",  # no answer, or a 5xx
+    "bad_token",  # 401/403: the token is wrong or lacks write:issue / read:repository
+    "repo_not_found",  # 404 on the repository
+    "public_repo",  # the repository is public — an issue would publish the reporter's log
+    "issues_disabled",  # the repository has its issue tracker switched off
+    "rejected",  # any other 4xx (a file type the instance does not allow, …)
+]
+
+
+class GiteaError(Exception):
+    def __init__(self, reason: Reason) -> None:
+        super().__init__(reason)
+        self.reason: Reason = reason
+
+
+def _settings(db: Session) -> tuple[str, str, str]:
+    return (
+        sysconfig.get_str(db, "issues_gitea_url").strip().rstrip("/"),
+        sysconfig.get_str(db, "issues_gitea_repo").strip().strip("/"),
+        sysconfig.get_str(db, "issues_gitea_token").strip(),
+    )
+
+
+def target(db: Session) -> dict | None:
+    """Where a report goes, for the composer to say so — the repository — or None when no tracker is
+    configured (the report can then only be downloaded)."""
+    url, repo, token = _settings(db)
+    return {"repo": repo} if url and repo and token else None
+
+
+@contextmanager
+def _client(db: Session) -> Iterator[tuple[httpx.Client, str]]:
+    url, repo, token = _settings(db)
+    if not (url and repo and token):
+        raise GiteaError("not_configured")
+    with httpx.Client(
+        base_url=f"{url}/api/v1",
+        headers={"Authorization": f"token {token}", "Accept": "application/json"},
+        timeout=TIMEOUT_SECONDS,
+    ) as client:
+        yield client, repo
+
+
+def _call(client: httpx.Client, method: str, path: str, **kwargs) -> httpx.Response:
+    try:
+        r = client.request(method, path, **kwargs)
+    except httpx.HTTPError as exc:
+        log.warning(
+            "the issue tracker did not answer",
+            extra=logs.event("issues.gitea.unreachable", path=path, error=type(exc).__name__),
+        )
+        raise GiteaError("unreachable") from None
+    if r.status_code < 400:
+        return r
+    # The status only: Gitea's message can quote back what was sent — the user's own title.
+    log.warning(
+        "the issue tracker refused a call",
+        extra=logs.event("issues.gitea.refused", path=path, status=r.status_code),
+    )
+    if r.status_code in (401, 403):
+        raise GiteaError("bad_token")
+    if r.status_code == 404:
+        raise GiteaError("repo_not_found")
+    if r.status_code >= 500:
+        raise GiteaError("unreachable")
+    raise GiteaError("rejected")
+
+
+def _private_repo(client: httpx.Client, repo: str) -> dict:
+    data = _call(client, "GET", f"/repos/{repo}").json()
+    if not data.get("private"):
+        raise GiteaError("public_repo")
+    if not data.get("has_issues"):
+        raise GiteaError("issues_disabled")
+    return data
+
+
+def check(db: Session) -> dict:
+    """The admin's "test connection": the repository answers, is private and takes issues."""
+    with _client(db) as (client, repo):
+        data = _private_repo(client, repo)
+    return {"repo": data.get("full_name") or repo, "url": data.get("html_url")}
+
+
+def preview(db: Session, text: str) -> str:
+    """The body as Gitea itself will render it (its markdown flavour, its sanitiser)."""
+    with _client(db) as (client, repo):
+        r = _call(client, "POST", "/markdown", json={"Text": text, "Mode": "gfm", "Context": repo})
+    return r.text
+
+
+def _save(session: DebugSession, state: dict) -> None:
+    # A new dict, so the JSONB column sees the change.
+    session.draft = {**(session.draft or {}), "delivery": state}
+
+
+def deliver(db: Session, session: DebugSession) -> str:
+    """Send the session's issue, or finish sending it; returns its URL. Flushes after every step."""
+    state = dict((session.draft or {}).get("delivery") or {})
+    files = bundle.files(db, session)
+    attachments = [f for f in files if f.name != "issue.md"]
+    with _client(db) as (client, repo):
+        _private_repo(client, repo)
+        if "number" not in state:
+            created = _call(
+                client,
+                "POST",
+                f"/repos/{repo}/issues",
+                json={"title": bundle.title_of(session), "body": bundle.body_of(session)},
+            ).json()
+            state = {
+                "number": created["number"],
+                "pending": [f.name for f in attachments],
+                "links": {},
+            }
+            session.issue_url = created["html_url"]
+            _save(session, state)
+            db.flush()
+            log.info(
+                "issue created",
+                extra=logs.event("issues.gitea.created", number=created["number"]),
+            )
+        number = state["number"]
+        for item in attachments:
+            if item.name not in state["pending"]:
+                continue
+            asset = _call(
+                client,
+                "POST",
+                f"/repos/{repo}/issues/{number}/assets",
+                params={"name": item.name},
+                files={"attachment": (item.name, item.data, item.mime)},
+            ).json()
+            state = {
+                **state,
+                "pending": [n for n in state["pending"] if n != item.name],
+                "links": {**state["links"], item.name: asset["browser_download_url"]},
+            }
+            _save(session, state)
+            db.flush()
+        shots = [n for n in state["links"] if n.startswith("screenshot-")]
+        if shots and not state.get("images_shown"):
+            images = "\n".join(f"![{n}]({state['links'][n]})" for n in sorted(shots))
+            body = f"{bundle.body_of(session)}\n\n---\n\n{images}"
+            _call(client, "PATCH", f"/repos/{repo}/issues/{number}", json={"body": body})
+            _save(session, {**state, "images_shown": True})
+            db.flush()
+    return session.issue_url or ""
+
+
+def pending(session: DebugSession) -> list[str]:
+    """The files a half-finished delivery still has to send."""
+    return list(((session.draft or {}).get("delivery") or {}).get("pending") or [])

backend/app/routes/_common.py

@@ -13,6 +13,8 @@ from sqlalchemy.orm import Session
 
 from app.db import Base
 from app.models import User
+from app.issues import gitea
+from app.refusal import refused
 from app.youtube.client import YouTubeError, refusal_reason
 
 M = TypeVar("M", bound=Base)
@@ -75,3 +77,24 @@ async def capped_body(request: Request, limit: int) -> bytes:
         if len(body) > limit:
             raise HTTPException(status_code=413, detail={"code": "too_large"})
     return bytes(body)
+
+
+def issue_refused(exc: gitea.GiteaError) -> HTTPException:
+    """The refusal an issue-tracker failure (E16) answers as — the send, the preview and the
+    admin's connection test alike. Literal reasons, one per case: the frontend's contract test reads
+    them to require a sentence for each in both languages."""
+    match exc.reason:
+        case "not_configured":
+            return refused(400, "issues_not_configured")
+        case "unreachable":
+            return refused(422, "issues_unreachable")
+        case "bad_token":
+            return refused(422, "issues_bad_token")
+        case "repo_not_found":
+            return refused(422, "issues_repo_not_found")
+        case "public_repo":
+            return refused(422, "issues_public_repo")
+        case "issues_disabled":
+            return refused(422, "issues_disabled")
+        case _:
+            return refused(422, "issues_rejected")

backend/app/routes/config.py

@@ -18,7 +18,8 @@ from app.auth import admin_user
 from app.db import get_db
 from app.models import User
 from app.refusal import refused
-from app.routes._common import not_found
+from app.issues import gitea
+from app.routes._common import issue_refused, not_found
 from app.refusal import setting_refused
 
 router = APIRouter(prefix="/api/admin/config", tags=["admin"])
@@ -131,3 +132,16 @@ def send_test_email(
     if not sent:
         raise refused(422, "smtp_failed")
     return {"ok": True, "sent": True, "to": user.email}
+
+
+@router.post("/test-issues")
+def test_issue_tracker(
+    _: User = Depends(admin_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Check the configured issue tracker (E16): the repository answers with this token, takes
+    issues, and is PRIVATE — the one it must be, since an issue carries its reporter's log."""
+    try:
+        return {"ok": True, **gitea.check(db)}
+    except gitea.GiteaError as exc:
+        raise issue_refused(exc) from None

backend/app/routes/debug_sessions.py

@@ -20,12 +20,15 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
-from app import debugsession, logs, logsink
+from app import audit, debugsession, logs, logsink
+from app.audit import AuditAction
 from app.auth import require_human
 from app.db import get_db
-from app.issues import bundle
+from app.issues import bundle, gitea
+from app.ratelimit import RateLimiter
+from app.refusal import refused
 from app.models import DebugScreenshot, DebugSession, User
-from app.routes._common import capped_body, not_found, owned_or_404
+from app.routes._common import capped_body, issue_refused, not_found, owned_or_404
 from app.utils import iso
 
 router = APIRouter(prefix="/api/debug-sessions", tags=["diagnostics"])
@@ -58,7 +61,7 @@ def start_session(
         db.rollback()
         session = debugsession.open_session(db, user)
         if session is None:
-            raise HTTPException(status_code=409, detail={"code": "session_conflict"})
+            raise refused(409, "debug_session_conflict") from None
     # The rest of THIS request is part of the session too.
     level, until = debugsession.level_for(user, session)
     logs.set_user(user.id, level, until, session.id)
@@ -139,7 +142,7 @@ def save_draft(
     session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
     if session.issue_url is not None:
         # Sent: the issue is on the tracker now, and a draft edited after it would say otherwise.
-        raise HTTPException(status_code=409, detail={"code": "already_sent"})
+        raise refused(409, "issue_already_sent")
     if len(json.dumps(body.form, ensure_ascii=False).encode()) > FORM_MAX_BYTES:
         raise HTTPException(status_code=413, detail={"code": "too_large"})
     debugsession.save_draft(session, body.model_dump())
@@ -167,6 +170,72 @@ def export_session(
     )
 
 
+# --- the issue tracker (S4) -----------------------------------------------------------------
+# Issues a user may OPEN per hour — finishing a half-sent one is not counted. The composer sends one
+# at a time; this is room for a bad afternoon, not a pace anything legitimate keeps up.
+_new_issues = RateLimiter(max_events=5, window_seconds=3600)
+
+
+@router.post("/{sid}/issue")
+def send_issue(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> dict:
+    """Send the session's issue to the tracker — from the SAVED draft, as the export is built — or
+    finish a send that stopped half-way (the issue exists; only what is missing is sent)."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    new = session.issue_url is None
+    if not new and not gitea.pending(session):
+        return {"ok": True, "session": _view(db, session)}
+    if new:
+        if not ((session.draft or {}).get("title") or "").strip():
+            raise refused(422, "issue_title_required")
+        if not _new_issues.allow(str(user.id)):
+            raise refused(429, "issues_rate_limited")
+    try:
+        gitea.deliver(db, session)
+    except gitea.GiteaError as exc:
+        # Keep what did happen: an issue created before an upload failed stays linked, and the
+        # retry sends only the files still missing.
+        _record_created(db, user, session, new)
+        db.commit()
+        raise issue_refused(exc) from None
+    _record_created(db, user, session, new)
+    db.commit()
+    return {"ok": True, "session": _view(db, session)}
+
+
+def _record_created(db: Session, user: User, session: DebugSession, new: bool) -> None:
+    if new and session.issue_url:
+        audit.record(
+            db,
+            user.id,
+            AuditAction.ISSUE_CREATE,
+            target_type="debug_session",
+            target_id=session.id,
+            summary=session.issue_url,
+        )
+
+
+class PreviewIn(BaseModel):
+    text: str = Field(max_length=50_000)
+
+
+@router.post("/{sid}/preview")
+def preview_issue(
+    sid: str,
+    body: PreviewIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The body as the tracker will render it. Gitea sanitises its own output; the composer still
+    shows it in a sandboxed frame, never in the app's own document."""
+    owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    try:
+        return {"ok": True, "html": gitea.preview(db, body.text)}
+    except gitea.GiteaError as exc:
+        raise issue_refused(exc) from None
+
+
 # --- screenshots ---------------------------------------------------------------------------
 def _shot_view(shot: DebugScreenshot) -> dict:
     return {"id": shot.id, "mime": shot.mime, "size": shot.size, "created_at": iso(shot.created_at)}
@@ -201,13 +270,23 @@ def add_screenshot(
     try:
         shot = debugsession.add_screenshot(db, session, data)
     except debugsession.ScreenshotRefused as exc:
-        raise HTTPException(
-            status_code=422, detail={"code": "screenshot_refused", "reason": exc.code}
-        ) from exc
+        raise _screenshot_refused(exc.code) from None
     db.commit()
     return {"ok": True, "screenshot": _shot_view(shot)}
 
 
+def _screenshot_refused(code: str) -> HTTPException:
+    # Literal reasons, one per case: the frontend's contract test reads them to require a sentence
+    # for each in both languages.
+    if code == "already_sent":
+        return refused(409, "screenshot_already_sent")
+    if code == "too_many":
+        return refused(422, "screenshot_too_many", limit=debugsession.SCREENSHOTS_MAX)
+    if code == "empty":
+        return refused(422, "screenshot_empty")
+    return refused(422, "screenshot_not_an_image")
+
+
 def _session_screenshot(db: Session, sid: str, shot_id: int, user: User) -> DebugScreenshot:
     session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
     shot = db.get(DebugScreenshot, shot_id)

backend/app/routes/me.py

@@ -18,6 +18,7 @@ from app.auth import (
     purge_user,
 )
 from app import debugsession, diagnostics
+from app.issues import gitea
 from app import email as email_mod
 from app import logs
 from app import sysconfig
@@ -160,6 +161,8 @@ def get_me(
         "diagnostics": diagnostics.state(db, user),
         # The live debug session, if one is recording (E16) — a reload resumes it.
         "debug_session": _live_session(db, user),
+        # Where a bug report goes (E16 S4): the tracker's repository, or None — download only.
+        "issues": gitea.target(db),
     }
 
 

backend/app/sysconfig.py

@@ -192,6 +192,10 @@ SPECS: tuple[ConfigSpec, ...] = (
     # --- TMDB enrichment (E5 S2; optional) — the API key is the only secret ---
     ConfigSpec("tmdb_api_key", "str", "tmdb", "tmdb_api_key", secret=True),
     ConfigSpec("tmdb_language", "str", "tmdb", "tmdb_language"),
+    # --- Bug reports (E16): the Gitea issue tracker a debug session's issue goes to ---
+    ConfigSpec("issues_gitea_url", "str", "issues", "issues_gitea_url"),
+    ConfigSpec("issues_gitea_repo", "str", "issues", "issues_gitea_repo"),
+    ConfigSpec("issues_gitea_token", "str", "issues", "issues_gitea_token", secret=True),
     # (tmdb_enrich_interval_min is a scheduler job, tuned from the Scheduler dashboard; tmdb_enrich_batch
     # is a config.py default — both stay out of SPECS, like plex_sync_interval_min.)
 )