feat(diagnostics): the issue composer — draft, review, screenshots, zip export (E16 S3)

After Stop (or at the cap, or from Settings → Diagnosztika's past sessions)
one dialog drafts the issue: title, description, the steps drafted from the
session's markers and page changes (a marker without a label is named by its
time), the environment (version, browser, system, window, language). Beside
it, what goes with it: the browser and server logs — each reviewable line by
line, an unticked line is not sent — and the screenshots, removable, with
paste / drop / pick to add more.

- it saves as it goes (debug_sessions.draft, migration 0090): the rendered
  markdown in the user's language, the excluded rows, and its own fields to
  reopen as it was; a sent session is read-only
- the zip export (issue.md, client.log, server.log, screenshots) is built
  from the saved draft by app/issues/bundle.py — the one definition the Gitea
  delivery (S4) will share; .log, not .jsonl, which Gitea refuses
- the log line's level tags and clock move to components/logLineParts so the
  review list draws a level the way both log viewers do

backend/app/README.md

@@ -13,11 +13,12 @@ Three layers, by *who* runs the code — not by feature:
    response models, status-code mapping, serialization. It owns logic that runs *only* on a request.
    Business logic that a request happens to trigger does **not** live here if anything else runs it too.
 
-2. **`plex/`, `downloads/`, `sync/` — domain logic shared by more than one caller.** Anything the
+2. **`plex/`, `downloads/`, `sync/`, `issues/` — domain logic shared by more than one caller.** Anything the
    **scheduler or the worker** runs (not just a request) lives in one of these domain packages, so the
    route, the worker, and the scheduler share one definition. Examples from this codebase:
    `downloads/service.py` owns enqueue + the job state transitions (routes call it); `plex/sync.py` is
-   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline.
+   run by both the admin route and the scheduler; `downloads/pipeline.py` is the worker's child pipeline;
+   `issues/bundle.py` is the one definition of a bug report's files, for the zip export and the tracker.
 
 3. **Flat `app/*.py` core modules — cross-cutting primitives.** `auth`, `sysconfig`, `quota`, `audit`,
    `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`, `logs` (the one logging

backend/app/debugsession.py

@@ -127,6 +127,13 @@ def level_for(user: User, session: DebugSession | None) -> tuple[str, datetime |
     return session.level, session.until
 
 
+def save_draft(session: DebugSession, draft: dict) -> None:
+    """Keep the composer's draft (the caller validated and commits). Shape: `title`, `body` (the
+    rendered markdown an export or an issue carries), `excluded` (log row ids taken out of the
+    evidence) and `form` (the composer's own fields, to reopen it as it was)."""
+    session.draft = draft
+
+
 def serialize(session: DebugSession | None, screenshots: int = 0) -> dict | None:
     if session is None:
         return None
@@ -139,6 +146,7 @@ def serialize(session: DebugSession | None, screenshots: int = 0) -> dict | None
         "ended_reason": session.ended_reason,
         "issue_url": session.issue_url,
         "screenshots": screenshots,
+        "draft": session.draft,
     }
 
 
@@ -231,23 +239,24 @@ def _evidence(session: DebugSession):
     return (LogEvent.debug_session_id == session.id, not_(upload_line.is_(True)))
 
 
-def bundle(db: Session, session: DebugSession) -> tuple[list[LogEvent], int]:
+def bundle(
+    db: Session, session: DebugSession, *, drop_excluded: bool = False
+) -> tuple[list[LogEvent], int]:
     """The session's log rows, browser and server interleaved in time, capped at BUNDLE_MAX — and
-    how many rows it has in all, so a cut bundle can say so."""
+    how many rows it has in all, so a cut bundle can say so. `drop_excluded` leaves out the rows
+    the user took out in the composer: what an export or an issue carries."""
+    where = list(_evidence(session))
+    excluded = (session.draft or {}).get("excluded") or [] if drop_excluded else []
+    if excluded:
+        where.append(LogEvent.id.not_in(excluded))
     rows = list(
         db.scalars(
-            select(LogEvent)
-            .where(*_evidence(session))
-            .order_by(LogEvent.ts, LogEvent.id)
-            .limit(BUNDLE_MAX)
+            select(LogEvent).where(*where).order_by(LogEvent.ts, LogEvent.id).limit(BUNDLE_MAX)
         )
     )
     total = len(rows)
     if total == BUNDLE_MAX:
-        total = (
-            db.scalar(select(func.count()).select_from(LogEvent).where(*_evidence(session)))
-            or total
-        )
+        total = db.scalar(select(func.count()).select_from(LogEvent).where(*where)) or total
     return rows, total
 
 

backend/app/issues/__init__.py

@@ -0,0 +1,3 @@
+"""Bug reports built from debug sessions (E16): the files an issue carries, and where they go —
+downloaded as a zip, or (S4) sent to a Gitea issue tracker. The session itself — what is recorded
+and tagged — is the core module `app/debugsession.py`."""

backend/app/issues/bundle.py

@@ -0,0 +1,77 @@
+"""What an issue from a debug session carries, as files — one definition for the zip export and the
+Gitea upload, so the two cannot drift apart.
+
+  * `issue.md` — the title and the body the user wrote and reviewed in the composer (rendered there,
+    in their language; the server does not rewrite it);
+  * `client.log` / `server.log` — the session's evidence (`debugsession.bundle`) minus the rows the
+    user took out, one JSON object per line, browser rows and server rows apart. `.log`, not
+    `.jsonl`: Gitea refuses that extension (measured, plans/e16 S0);
+  * the screenshots, in the order they were taken.
+
+Every row is already redacted twice (at capture, and again when stored), and nothing here adds a
+field the review list did not show.
+"""
+
+import io
+import json
+import zipfile
+from dataclasses import dataclass
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app import debugsession, logsink
+from app.models import DebugScreenshot, DebugSession
+
+_EXT = {"image/png": "png", "image/jpeg": "jpg", "image/webp": "webp"}
+
+
+@dataclass(frozen=True)
+class IssueFile:
+    name: str
+    data: bytes
+    mime: str
+
+
+def title_of(session: DebugSession) -> str:
+    # Not a sentence of ours: the composer always saves a title in the user's language, and a
+    # session exported before it ever saved is named by its date alone, in no language at all.
+    title = ((session.draft or {}).get("title") or "").strip()
+    return title or f"{session.started_at:%Y-%m-%d %H:%M} · {session.id}"
+
+
+def body_of(session: DebugSession) -> str:
+    return ((session.draft or {}).get("body") or "").strip()
+
+
+def _lines(rows) -> bytes:
+    return "".join(
+        json.dumps(logsink.serialize(r), ensure_ascii=False, default=str) + "\n" for r in rows
+    ).encode()
+
+
+def files(db: Session, session: DebugSession) -> list[IssueFile]:
+    """The session's issue as files: the text, the two logs, the screenshots."""
+    rows, _ = debugsession.bundle(db, session, drop_excluded=True)
+    text = f"# {title_of(session)}\n\n{body_of(session)}\n"
+    out = [
+        IssueFile("issue.md", text.encode(), "text/markdown"),
+        IssueFile("client.log", _lines(r for r in rows if r.source == "web"), "text/plain"),
+        IssueFile("server.log", _lines(r for r in rows if r.source != "web"), "text/plain"),
+    ]
+    shots = db.scalars(
+        select(DebugScreenshot)
+        .where(DebugScreenshot.session_id == session.id)
+        .order_by(DebugScreenshot.id)
+    )
+    for n, shot in enumerate(shots, start=1):
+        out.append(IssueFile(f"screenshot-{n}.{_EXT.get(shot.mime, 'bin')}", shot.data, shot.mime))
+    return out
+
+
+def zipped(items: list[IssueFile]) -> bytes:
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        for item in items:
+            z.writestr(item.name, item.data)
+    return buf.getvalue()

backend/app/models.py

@@ -619,6 +619,8 @@ class DebugSession(Base):
     # app/debugsession.py `EndReason`: stopped by the user, or past `until`.
     ended_reason: Mapped[str | None] = mapped_column(String(16))
     issue_url: Mapped[str | None] = mapped_column(String(512))
+    # The issue being written from it (E16 S3; app/debugsession.py `save_draft` holds its shape).
+    draft: Mapped[dict | None] = mapped_column(JSONB)
 
 
 class DebugScreenshot(Base):

backend/app/routes/debug_sessions.py

@@ -10,10 +10,12 @@ form — one image per request, capped while it arrives, and kept only if its by
 those types, whatever the Content-Type claimed.
 """
 
+import json
 from datetime import datetime, timezone
+from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
@@ -21,6 +23,7 @@ from sqlalchemy.orm import Session
 from app import debugsession, logs, logsink
 from app.auth import require_human
 from app.db import get_db
+from app.issues import bundle
 from app.models import DebugScreenshot, DebugSession, User
 from app.routes._common import capped_body, not_found, owned_or_404
 from app.utils import iso
@@ -111,6 +114,59 @@ def session_events(
     return {"items": [logsink.serialize(r) for r in rows], "total": total}
 
 
+# --- the draft and its export ---------------------------------------------------------------
+# The composer's own fields (steps, description…) are its business, kept whole so it reopens as it
+# was — bounded here so a draft cannot become a place to store anything else.
+FORM_MAX_BYTES = 64 * 1024
+
+
+class DraftIn(BaseModel):
+    title: str = Field(max_length=200)
+    # The rendered markdown the export and the issue carry.
+    body: str = Field(max_length=50_000)
+    # Log rows taken out of the evidence in the review.
+    excluded: list[int] = Field(default_factory=list, max_length=debugsession.BUNDLE_MAX)
+    form: dict[str, Any] = Field(default_factory=dict)
+
+
+@router.put("/{sid}/draft")
+def save_draft(
+    sid: str,
+    body: DraftIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    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"})
+    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())
+    db.commit()
+    return {"ok": True, "session": _view(db, session)}
+
+
+@router.get("/{sid}/export")
+def export_session(
+    sid: str, user: User = Depends(require_human), db: Session = Depends(get_db)
+) -> Response:
+    """The issue as a zip — the text, the two logs and the screenshots — for an instance without an
+    issue tracker, or for sending it by hand. Built from the SAVED draft: what the composer shows is
+    what it saved."""
+    session = owned_or_404(db, DebugSession, sid, user, what="debug_session")
+    data = bundle.zipped(bundle.files(db, session))
+    name = f"siftlode-debug-{session.started_at:%Y%m%d-%H%M}-{session.id[:6]}.zip"
+    return Response(
+        content=data,
+        media_type="application/zip",
+        headers={
+            "Content-Disposition": f'attachment; filename="{name}"',
+            "Cache-Control": "no-store",
+        },
+    )
+
+
 # --- screenshots ---------------------------------------------------------------------------
 def _shot_view(shot: DebugScreenshot) -> dict:
     return {"id": shot.id, "mime": shot.mime, "size": shot.size, "created_at": iso(shot.created_at)}