fix: normalize nullable pull request authors (#56)

Closes #54

README.md

@@ -28,6 +28,11 @@ Gitea connection directly, request
 `user`, `repos`, `issues`, and `pull_requests`. Never commit the token or place
 it in a tracked configuration file.
 
+For service monitoring, GET `/healthz` is a liveness check that confirms the
+API process is running and does not contact Gitea. GET `/readyz` is the
+readiness check: it validates the configured Gitea credentials and returns
+HTTP 503 with an error when Gitea is unavailable or authentication fails.
+
 Run the test suite with:
 
 ```bash

frontend/index.html

@@ -102,10 +102,20 @@ textarea { resize: vertical; min-height: 120px; }
     <details class="panel" data-panel-key="gitea-events" open>
       <summary><h2>Gitea event stream</h2></summary>
       <div id="gitea-events" class="muted" aria-live="polite">Loading…</div>
+      <div id="gitea-events-status" class="small" aria-live="polite">Waiting for activity…</div>
     </details>
     <details class="panel" data-panel-key="widgets" open>
       <summary><h2>Live Widgets</h2></summary>
-      <div id="widgets" class="stack"></div>
+      <div id="widgets" class="stack">
+        <div class="widget">
+          <h3>Live clock</h3>
+          <div class="small" id="widget-clock">—</div>
+        </div>
+        <div class="widget">
+          <h3>Repo mix</h3>
+          <div class="small" id="repo-mix">Loading…</div>
+        </div>
+      </div>
     </details>
   </section>
 
@@ -149,6 +159,7 @@ textarea { resize: vertical; min-height: 120px; }
 
 <div class="footer">Creative AI-imbued UI • stackchain-dashboard</div>
 
+<script src="/static/markdown.js"></script>
 <script>
 (function(){
   const qs = (s, el=document) => el.querySelector(s);
@@ -245,13 +256,19 @@ textarea { resize: vertical; min-height: 120px; }
     ).join('') : '<div class="muted">No recent Gitea activity.</div>';
   }
 
+  function setEventStreamStatus(message) {
+    qs('#gitea-events-status').textContent = message;
+  }
+
   async function loadEventStream() {
+    setEventStreamStatus('Updating…');
     try {
       const res = await fetch('/api/v1/events', { headers: { Accept: 'application/json' } });
       if (!res.ok) throw new Error('HTTP ' + res.status);
       paintEventStream(await res.json());
+      setEventStreamStatus('Updated ' + fmt(new Date()));
     } catch (e) {
-      qs('#gitea-events').innerHTML = '<div class="muted">Event stream unavailable.</div>';
+      setEventStreamStatus('Update failed · showing last activity');
     }
   }
 
@@ -311,14 +328,7 @@ textarea { resize: vertical; min-height: 120px; }
   qs('#md-input').addEventListener('input', renderMD);
   function renderMD() {
     const raw = qs('#md-input').value || '';
-    const html = raw.replace(/^#{1,6}\s.*$/gm, (m)=>{ const lvl=m.match(/^(#{1,6})/)[1].length; return '<h'+lvl+'>'+m.replace(/^#{1,6}\s/,'')+'</h'+lvl+'>'; })
-      .replace(/\*\*(.+?)\*\*/g,'<strong>$1</strong>')
-      .replace(/\*(.+?)\*/g,'<em>$1</em>')
-      .replace(/`([^`]+)`/g,'<code>$1</code>')
-      .replace(/^\-\s?(.+)$/gm,'<li>$1</li>')
-      .replace(/(<li>.*<\/li>)/s,'<ul>$1</ul>')
-      .replace(/\n/g,'<br>');
-    qs('#md-preview').innerHTML = '<pre>' + escapeHtml(raw) + '</pre><div style="margin-top:8px;">' + html + '</div>';
+    qs('#md-preview').innerHTML = '<pre>' + escapeHtml(raw) + '</pre><div style="margin-top:8px;">' + renderMarkdown(raw) + '</div>';
   }
 
   /* Commands */
@@ -351,33 +361,20 @@ textarea { resize: vertical; min-height: 120px; }
   tickWidgets();
 
   /* Widgets */
-  const widgetOrder = ['countdown','repoAtAGlance'];
-  const widgetRegistry = {
-    countdown: () => ({ title: 'Live clock', html: '<div class="small" id="widget-clock">—</div>' }),
-    repoAtAGlance: async () => {
-      const el = qs('#repo-mix');
-      if (!el) return { title:'Repo mix', html:'<div class="small">Unavailable</div>' };
-      try {
-        const res = await fetch('/api/v1/context', { headers: { Accept: 'application/json' } });
-        const data = await res.json();
-        const repos = data.repos || [];
-        const issues = (data.issues||[]).filter(i=>i.state==='open');
-        const prs = data.pull_requests || [];
-        el.innerHTML = '<div class="kv"><div class="label">Repos</div><div class="value">' + repos.length + '</div><div class="label">Open issues</div><div class="value">' + issues.length + '</div><div class="label">Open PRs</div><div class="value">' + prs.length + '</div></div>';
-      } catch (e) { el.innerHTML = '<div class="muted">Widget unavailable.</div>'; }
-      return { title:'Repo mix', html:'<div class="small" id="repo-mix">Loading…</div>' };
-    },
-  };
-  const widgetsEl = qs('#widgets');
-  function paintWidgets() {
-    widgetsEl.innerHTML = '';
-    widgetOrder.forEach(async k => {
-      const w = await widgetRegistry[k]();
-      const node = document.createElement('div'); node.className='widget'; node.innerHTML = '<h3>' + escapeHtml(w.title) + '</h3>' + w.html;
-      widgetsEl.appendChild(node);
-    });
+  async function updateRepoMix() {
+    const el = qs('#repo-mix');
+    try {
+      const res = await fetch('/api/v1/context', { headers: { Accept: 'application/json' } });
+      const data = await res.json();
+      const repos = data.repos || [];
+      const issues = (data.issues||[]).filter(i=>i.state==='open');
+      const prs = data.pull_requests || [];
+      el.innerHTML = '<div class="kv"><div class="label">Repos</div><div class="value">' + repos.length + '</div><div class="label">Open issues</div><div class="value">' + issues.length + '</div><div class="label">Open PRs</div><div class="value">' + prs.length + '</div></div>';
+    } catch (e) {
+      el.innerHTML = '<div class="muted">Widget unavailable.</div>';
+    }
   }
-  paintWidgets();
+  updateRepoMix();
 
   function widgetTick() { const el=qs('#widget-clock'); if(el) el.textContent = fmt(new Date()); }
   setInterval(widgetTick, 1000);

frontend/markdown.js

@@ -0,0 +1,29 @@
+(function (root, factory) {
+  const renderMarkdown = factory();
+  if (typeof module === 'object' && module.exports) module.exports = renderMarkdown;
+  root.renderMarkdown = renderMarkdown;
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  function escapeHtml(value) {
+    return String(value || '').replace(/[&<>"']/g, (character) => ({
+      '&': '&amp;',
+      '<': '&lt;',
+      '>': '&gt;',
+      '"': '&quot;',
+      "'": '&#39;',
+    })[character]);
+  }
+
+  return function renderMarkdown(raw) {
+    return escapeHtml(raw)
+      .replace(/^#{1,6}\s.*$/gm, (line) => {
+        const level = line.match(/^(#{1,6})/)[1].length;
+        return '<h' + level + '>' + line.replace(/^#{1,6}\s/, '') + '</h' + level + '>';
+      })
+      .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+      .replace(/\*(.+?)\*/g, '<em>$1</em>')
+      .replace(/`([^`]+)`/g, '<code>$1</code>')
+      .replace(/^-\s?(.+)$/gm, '<li>$1</li>')
+      .replace(/(<li>.*<\/li>)/s, '<ul>$1</ul>')
+      .replace(/\n/g, '<br>');
+  };
+});

src/main.py

@@ -1,4 +1,6 @@
 import asyncio
+import math
+from pathlib import Path
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -12,6 +14,7 @@ from src.views import router as frontend_router
 
 app = FastAPI(title="Stackchain Dashboard")
 CONTEXT_TIMEOUT_SECONDS = 5.0
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
 
 app.add_middleware(
     CORSMiddleware,
@@ -21,6 +24,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.mount("/static", StaticFiles(directory=FRONTEND_DIR), name="static")
 app.include_router(frontend_router)
 
 
@@ -30,6 +34,27 @@ def health() -> dict[str, str]:
     return {"status": "ok", "service": "stackchain-dashboard"}
 
 
+@app.get("/readyz")
+async def readiness():
+    """Return readiness after verifying the configured Gitea connection."""
+    try:
+        user = await current_user()
+    except Exception as exc:
+        return JSONResponse(
+            {
+                "status": "not_ready",
+                "service": "stackchain-dashboard",
+                "error": str(exc),
+            },
+            status_code=503,
+        )
+    return {
+        "status": "ready",
+        "service": "stackchain-dashboard",
+        "gitea_user": user["login"],
+    }
+
+
 @app.get("/api/v1/context")
 async def context() -> JSONResponse:
     try:
@@ -54,32 +79,27 @@ async def context() -> JSONResponse:
                 {"panel": "gitea", "action": "set GITEA_URL + GITEA_TOKEN", "target": "/root/stackchain-dashboard/.env or systemd env", "priority": "high"},
             ],
             "error": error_message,
-        })
+        }, headers={
+            "Retry-After": str(max(1, math.ceil(CONTEXT_TIMEOUT_SECONDS)))
+        } if isinstance(e, TimeoutError) else None)
     user_model = User(id=user_data["id"], login=user_data["login"], full_name=user_data.get("full_name", ""), email=user_data.get("email", ""))
     repo_models = [
-        Repo(id=r["id"], name=r["name"], full_name=r["full_name"], description=r.get("description", ""), url=r["html_url"], updated_at=r.get("updated_at", ""))
+        Repo(id=r["id"], name=r["name"], full_name=r["full_name"], description=r.get("description") or "", url=r["html_url"], updated_at=r.get("updated_at", ""))
         for r in repo_data[:50]
         if isinstance(r, dict)
     ]
     issue_models = [
-        Issue(id=i["id"], number=i["number"], title=i["title"], state=i["state"], labels=[l.get("name", "") for l in i.get("labels", [])], assignees=[a.get("login", "") for a in i.get("assignees", [])], url=i["html_url"])
+        Issue(id=i["id"], number=i["number"], title=i["title"], state=i["state"], labels=[l.get("name", "") for l in (i.get("labels") or [])], assignees=[a.get("login", "") for a in (i.get("assignees") or [])], url=i["html_url"])
         for i in issues_data[:50]
         if isinstance(i, dict)
     ]
     pr_models = [
-        PullRequest(id=p["id"], number=p["number"], title=p["title"], state=p["state"], user=p.get("user", {}).get("login", ""), url=p["html_url"])
+        PullRequest(id=p["id"], number=p["number"], title=p["title"], state=p["state"], user=(p.get("user") or {}).get("login", ""), url=p["html_url"])
         for p in prs_data[:50]
         if isinstance(p, dict)
     ]
     ctx = compute(user_model, repo_models, issue_models, pr_models)
-    return JSONResponse({
-        "user": ctx.user.dict(),
-        "repos": [r.dict() for r in ctx.repos],
-        "issues": [i.dict() for i in ctx.issues],
-        "pull_requests": [p.dict() for p in ctx.pull_requests],
-        "view": ctx.view,
-        "deltas": [d.dict() for d in ctx.deltas],
-    })
+    return JSONResponse(ctx.model_dump())
 
 
 @app.get("/api/v1/events")

src/models.py

@@ -36,17 +36,17 @@ class PullRequest(BaseModel):
     url: str
 
 
+class SuggestionDelta(BaseModel):
+    panel: str
+    action: str
+    target: str = ""
+    priority: str = "medium"
+
+
 class ViewContext(BaseModel):
     user: User
     repos: list[Repo] = []
     issues: list[Issue] = []
     pull_requests: list[PullRequest] = []
     view: str = "dashboard"
-    deltas: list[dict] = []
-
-
-class SuggestionDelta(BaseModel):
-    panel: str
-    action: str
-    target: str = ""
-    priority: str = "medium"
+    deltas: list[SuggestionDelta] = []

src/release_engine.py

@@ -147,6 +147,8 @@ class GiteaClient:
                 return json.loads(raw) if raw else None
         except error.HTTPError as exc:
             detail = exc.read().decode(errors="replace")
+            if exc.code == 401:
+                detail += " (authentication rejected; refresh the cron GITEA_TOKEN)"
             raise RuntimeError(f"Gitea {method} {path} failed: HTTP {exc.code}: {detail}") from exc
 
     @staticmethod

src/views.py

@@ -1,9 +1,12 @@
+from pathlib import Path
+
 from fastapi import APIRouter
 from fastapi.responses import HTMLResponse
 
 router = APIRouter()
+DASHBOARD_FILE = Path(__file__).resolve().parent.parent / "frontend" / "index.html"
 
 
 @router.get("/", response_class=HTMLResponse)
 async def dashboard() -> str:
-    return open("frontend/index.html").read()
+    return DASHBOARD_FILE.read_text()

tests/test_context_timeout.py

@@ -1,4 +1,5 @@
 import asyncio
+import json
 
 import pytest
 
@@ -27,6 +28,95 @@ async def test_context_returns_fallback_when_gitea_exceeds_deadline(monkeypatch)
     response = await main.context()
 
     assert response.status_code == 200
+    assert response.headers["retry-after"] == "1"
     assert b'"repos":[]' in response.body
     assert b'"error":"Gitea context request timed out after 0.01s"' in response.body
-    assert cancelled.is_set()
+    assert cancelled.is_set()
+
+
+@pytest.mark.anyio
+async def test_context_normalizes_nullable_issue_collections(monkeypatch):
+    async def user():
+        return {"id": 1, "login": "timmy"}
+
+    async def empty_collection():
+        return []
+
+    async def issue_collection():
+        return [{
+            "id": 50,
+            "number": 50,
+            "title": "Nullable metadata",
+            "state": "open",
+            "labels": None,
+            "assignees": None,
+            "html_url": "https://forge.example/issues/50",
+        }]
+
+    monkeypatch.setattr(main, "current_user", user)
+    monkeypatch.setattr(main, "repos", empty_collection)
+    monkeypatch.setattr(main, "issues", issue_collection)
+    monkeypatch.setattr(main, "pull_requests", empty_collection)
+
+    response = await main.context()
+    issue = json.loads(response.body)["issues"][0]
+
+    assert issue["labels"] == []
+    assert issue["assignees"] == []
+
+
+@pytest.mark.anyio
+async def test_context_normalizes_nullable_repository_description(monkeypatch):
+    async def user():
+        return {"id": 1, "login": "timmy"}
+
+    async def empty_collection():
+        return []
+
+    async def repo_collection():
+        return [{
+            "id": 54,
+            "name": "dashboard",
+            "full_name": "stackchain/dashboard",
+            "description": None,
+            "html_url": "https://forge.example/stackchain/dashboard",
+        }]
+
+    monkeypatch.setattr(main, "current_user", user)
+    monkeypatch.setattr(main, "repos", repo_collection)
+    monkeypatch.setattr(main, "issues", empty_collection)
+    monkeypatch.setattr(main, "pull_requests", empty_collection)
+
+    response = await main.context()
+    repository = json.loads(response.body)["repos"][0]
+
+    assert repository["description"] == ""
+
+
+@pytest.mark.anyio
+async def test_context_normalizes_nullable_pull_request_author(monkeypatch):
+    async def user():
+        return {"id": 1, "login": "timmy"}
+
+    async def empty_collection():
+        return []
+
+    async def pull_request_collection():
+        return [{
+            "id": 56,
+            "number": 56,
+            "title": "Nullable author",
+            "state": "open",
+            "user": None,
+            "html_url": "https://forge.example/pulls/56",
+        }]
+
+    monkeypatch.setattr(main, "current_user", user)
+    monkeypatch.setattr(main, "repos", empty_collection)
+    monkeypatch.setattr(main, "issues", empty_collection)
+    monkeypatch.setattr(main, "pull_requests", pull_request_collection)
+
+    response = await main.context()
+    pull_request = json.loads(response.body)["pull_requests"][0]
+
+    assert pull_request["user"] == ""

tests/test_event_stream.py

@@ -20,6 +20,21 @@ def test_dashboard_has_realtime_gitea_event_stream_widget():
     assert "event.repo?.full_name" in html
 
 
+def test_event_stream_reports_when_activity_was_refreshed():
+    html = DASHBOARD.read_text()
+
+    assert 'id="gitea-events-status"' in html
+    assert "setEventStreamStatus('Updating…')" in html
+    assert "setEventStreamStatus('Updated ' + fmt(new Date()))" in html
+
+
+def test_event_stream_reports_refresh_failure_without_erasing_visible_events():
+    html = DASHBOARD.read_text()
+
+    assert "setEventStreamStatus('Update failed · showing last activity')" in html
+    assert "qs('#gitea-events').innerHTML = '<div class=\"muted\">Event stream unavailable.</div>'" not in html
+
+
 @pytest.mark.anyio
 async def test_event_stream_returns_recent_authenticated_gitea_activity(monkeypatch):
     expected = [{"type": "create", "actor": {"login": "timmy"}}]

tests/test_health.py

@@ -1,6 +1,39 @@
-from src.main import app, health
+import pytest
+
+from src import main
 
 
 def test_health_endpoint_reports_service_liveness_without_gitea_access():
-    assert any(getattr(route, "path", None) == "/healthz" for route in app.routes)
-    assert health() == {"status": "ok", "service": "stackchain-dashboard"}
+    assert any(getattr(route, "path", None) == "/healthz" for route in main.app.routes)
+    assert main.health() == {"status": "ok", "service": "stackchain-dashboard"}
+
+
+@pytest.mark.anyio
+async def test_readiness_endpoint_reports_connected_gitea_user(monkeypatch):
+    async def connected_user():
+        return {"login": "timmy"}
+
+    monkeypatch.setattr(main, "current_user", connected_user)
+
+    response = await main.readiness()
+
+    assert any(getattr(route, "path", None) == "/readyz" for route in main.app.routes)
+    assert response == {
+        "status": "ready",
+        "service": "stackchain-dashboard",
+        "gitea_user": "timmy",
+    }
+
+
+@pytest.mark.anyio
+async def test_readiness_endpoint_returns_503_when_gitea_is_unavailable(monkeypatch):
+    async def unavailable_user():
+        raise RuntimeError("connection refused")
+
+    monkeypatch.setattr(main, "current_user", unavailable_user)
+
+    response = await main.readiness()
+
+    assert response.status_code == 503
+    assert b'"status":"not_ready"' in response.body
+    assert b'"error":"connection refused"' in response.body

tests/test_markdown_renderer.py

@@ -0,0 +1,25 @@
+import json
+import subprocess
+from pathlib import Path
+
+
+RENDERER = Path(__file__).parent.parent / "frontend" / "markdown.js"
+
+
+def test_markdown_renderer_escapes_raw_html_before_rendering_heading():
+    payload = "# <img src=x onerror=alert(document.domain)>"
+    script = (
+        f"const render = require({json.dumps(str(RENDERER))});"
+        f"process.stdout.write(render({json.dumps(payload)}));"
+    )
+
+    result = subprocess.run(
+        ["node", "-e", script],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+    assert result.stdout == (
+        "<h1>&lt;img src=x onerror=alert(document.domain)&gt;</h1>"
+    )

tests/test_readme.py

@@ -23,3 +23,12 @@ def test_readme_documents_a_complete_local_quickstart():
     assert "uvicorn src.main:app" in text
     assert "http://127.0.0.1:8000/api/v1/context" in text
     assert "uvicorn==" in REQUIREMENTS.read_text()
+
+
+def test_readme_documents_liveness_and_gitea_readiness_checks():
+    text = README.read_text()
+
+    assert "`/healthz`" in text
+    assert "`/readyz`" in text
+    assert "does not contact Gitea" in text
+    assert "HTTP 503" in text

tests/test_release_engine.py

@@ -1,4 +1,6 @@
 import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
 from pathlib import Path
 
 import pytest
@@ -6,6 +8,7 @@ import pytest
 from src.release_engine import (
     CommandResult,
     EngineConfig,
+    GiteaClient,
     Issue,
     ReleaseEngine,
     RunState,
@@ -15,6 +18,28 @@ from src.release_engine import (
 )
 
 
+def test_stale_token_error_explains_how_to_restore_cron_authentication():
+    class UnauthorizedHandler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            self.send_response(401)
+            self.end_headers()
+            self.wfile.write(b'{"message":"user does not exist [uid: 0, name: ]"}')
+
+        def log_message(self, format, *args):
+            pass
+
+    server = HTTPServer(("127.0.0.1", 0), UnauthorizedHandler)
+    thread = threading.Thread(target=server.handle_request)
+    thread.start()
+    try:
+        client = GiteaClient(f"http://127.0.0.1:{server.server_port}", "stale-token")
+        with pytest.raises(RuntimeError, match="refresh the cron GITEA_TOKEN"):
+            client.list_open_issues("stackchain/stackchain-dashboard")
+    finally:
+        thread.join(timeout=2)
+        server.server_close()
+
+
 class FakeClient:
     def __init__(self, issues, verified_assignee="timmy", existing_pr=None):
         self.issues = issues

tests/test_repository_hygiene.py

@@ -0,0 +1,18 @@
+import subprocess
+
+
+def test_python_bytecode_is_not_tracked():
+    tracked = subprocess.run(
+        ["git", "ls-files"],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout.splitlines()
+
+    bytecode = [
+        path
+        for path in tracked
+        if "__pycache__" in path.split("/") or path.endswith((".pyc", ".pyo"))
+    ]
+
+    assert bytecode == []

tests/test_views.py

@@ -0,0 +1,12 @@
+import pytest
+
+from src.views import dashboard
+
+
+@pytest.mark.anyio
+async def test_dashboard_renders_outside_repository_working_directory(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+
+    html = await dashboard()
+
+    assert "Stackchain Dashboard" in html

tests/test_widgets.py

@@ -0,0 +1,11 @@
+import pytest
+
+from src.views import dashboard
+
+
+@pytest.mark.anyio
+async def test_dashboard_renders_repo_mix_placeholder_before_javascript_runs():
+    html = await dashboard()
+    server_rendered_html = html.split("<script>", 1)[0]
+
+    assert '<div class="small" id="repo-mix">Loading…</div>' in server_rendered_html