fix: normalize nullable user profile fields (#73)

Merge pull request 'Fix markdown renderer under dashboard subpath' (#64)

frontend/commands.js

@@ -0,0 +1,10 @@
+(function (root, factory) {
+  const filterCommands = factory();
+  if (typeof module === 'object' && module.exports) module.exports = filterCommands;
+  if (root) root.filterCommands = filterCommands;
+})(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  return function filterCommands(commands, filter) {
+    const term = String(filter || '').toLowerCase();
+    return commands.filter(command => command.name.toLowerCase().includes(term));
+  };
+});

frontend/index.html

@@ -159,6 +159,8 @@ textarea { resize: vertical; min-height: 120px; }
 
 <div class="footer">Creative AI-imbued UI • stackchain-dashboard</div>
 
+<script src="static/markdown.js"></script>
+<script src="static/commands.js"></script>
 <script>
 (function(){
   const qs = (s, el=document) => el.querySelector(s);
@@ -193,7 +195,7 @@ textarea { resize: vertical; min-height: 120px; }
   async function load() {
     setStatus('Loading…');
     try {
-      const res = await fetch('/api/v1/context', { headers: { Accept: 'application/json' } });
+      const res = await fetch('api/v1/context', { headers: { Accept: 'application/json' } });
       if (!res.ok) throw new Error('HTTP ' + res.status);
       const data = await res.json();
       liveMode = true;
@@ -262,7 +264,7 @@ textarea { resize: vertical; min-height: 120px; }
   async function loadEventStream() {
     setEventStreamStatus('Updating…');
     try {
-      const res = await fetch('/api/v1/events', { headers: { Accept: 'application/json' } });
+      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()));
@@ -273,7 +275,7 @@ textarea { resize: vertical; min-height: 120px; }
 
   async function tickWidgets() {
     try {
-      const res = await fetch('/api/v1/context', { headers: { Accept: 'application/json' } });
+      const res = await fetch('api/v1/context', { headers: { Accept: 'application/json' } });
       const data = await res.json();
       qs('#layout-hint').innerHTML = '<div class="kv"><div class="label">Active view</div><div class="value">' + escapeHtml(data.view || 'dashboard') + '</div><div class="label">Deltas</div><div class="value">' + (data.deltas||[]).length + '</div></div>';
     } catch (e) {
@@ -327,14 +329,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 */
@@ -346,11 +341,10 @@ textarea { resize: vertical; min-height: 120px; }
   ];
   function renderCommands(filter) {
     const el = qs('#cmd-results');
-    const term = String(filter||'').toLowerCase();
-    const items = commands.filter(c => c.name.toLowerCase().includes(term));
+    const items = filterCommands(commands, filter);
     el.innerHTML = items.map((c, idx) => '<div class="cmd-item" data-idx="' + idx + '">' + escapeHtml(c.name) + '</div>').join('');
     el.querySelectorAll('.cmd-item').forEach((item) => {
-      item.addEventListener('click', () => { commands[Number(item.dataset.idx)].run(); qs('#cmd-palette').classList.remove('open'); qs('#cmd-input').value=''; });
+      item.addEventListener('click', () => { items[Number(item.dataset.idx)].run(); qs('#cmd-palette').classList.remove('open'); qs('#cmd-input').value=''; });
     });
   }
   qs('#open-palette').addEventListener('click', () => { qs('#cmd-palette').classList.add('open'); qs('#cmd-input').focus(); renderCommands(''); });
@@ -370,7 +364,7 @@ textarea { resize: vertical; min-height: 120px; }
   async function updateRepoMix() {
     const el = qs('#repo-mix');
     try {
-      const res = await fetch('/api/v1/context', { headers: { Accept: 'application/json' } });
+      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');

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,5 +1,6 @@
 import asyncio
 import math
+from pathlib import Path
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -13,6 +14,9 @@ from src.views import router as frontend_router
 
 app = FastAPI(title="Stackchain Dashboard")
 CONTEXT_TIMEOUT_SECONDS = 5.0
+EVENT_STREAM_TIMEOUT_SECONDS = 5.0
+READINESS_TIMEOUT_SECONDS = 5.0
+FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
 
 app.add_middleware(
     CORSMiddleware,
@@ -22,6 +26,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.mount("/static", StaticFiles(directory=FRONTEND_DIR), name="static")
 app.include_router(frontend_router)
 
 
@@ -35,15 +40,26 @@ def health() -> dict[str, str]:
 async def readiness():
     """Return readiness after verifying the configured Gitea connection."""
     try:
-        user = await current_user()
+        user = await asyncio.wait_for(
+            current_user(), timeout=READINESS_TIMEOUT_SECONDS
+        )
     except Exception as exc:
+        timed_out = isinstance(exc, TimeoutError)
+        error_message = (
+            f"Gitea readiness check timed out after {READINESS_TIMEOUT_SECONDS:g}s"
+            if timed_out
+            else str(exc)
+        )
         return JSONResponse(
             {
                 "status": "not_ready",
                 "service": "stackchain-dashboard",
-                "error": str(exc),
+                "error": error_message,
             },
             status_code=503,
+            headers={
+                "Retry-After": str(max(1, math.ceil(READINESS_TIMEOUT_SECONDS)))
+            } if timed_out else None,
         )
     return {
         "status": "ready",
@@ -79,20 +95,20 @@ async def context() -> JSONResponse:
         }, 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", ""))
+    user_model = User(id=user_data["id"], login=user_data["login"], full_name=user_data.get("full_name") or "", email=user_data.get("email") or "")
     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", ""))
-        for r in repo_data[:50]
+        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 or [])[: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") or [])], assignees=[a.get("login", "") for a in (i.get("assignees") or [])], url=i["html_url"])
-        for i in issues_data[:50]
+        for i in (issues_data or [])[: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"])
-        for p in prs_data[:50]
+        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 or [])[:50]
         if isinstance(p, dict)
     ]
     ctx = compute(user_model, repo_models, issue_models, pr_models)
@@ -100,5 +116,33 @@ async def context() -> JSONResponse:
 
 
 @app.get("/api/v1/events")
-async def event_stream() -> list[dict]:
-    return await activity_events()
+async def event_stream():
+    try:
+        return await asyncio.wait_for(
+            activity_events(), timeout=EVENT_STREAM_TIMEOUT_SECONDS
+        )
+    except TimeoutError:
+        return JSONResponse(
+            {
+                "error": (
+                    "Gitea event stream request timed out after "
+                    f"{EVENT_STREAM_TIMEOUT_SECONDS:g}s"
+                )
+            },
+            status_code=503,
+            headers={
+                "Retry-After": str(
+                    max(1, math.ceil(EVENT_STREAM_TIMEOUT_SECONDS))
+                )
+            },
+        )
+    except Exception:
+        return JSONResponse(
+            {"error": "Gitea event stream is temporarily unavailable"},
+            status_code=503,
+            headers={
+                "Retry-After": str(
+                    max(1, math.ceil(EVENT_STREAM_TIMEOUT_SECONDS))
+                )
+            },
+        )

tests/test_api_paths.py

@@ -0,0 +1,20 @@
+import re
+from pathlib import Path
+from urllib.parse import urljoin
+
+
+DASHBOARD_HTML = Path(__file__).parent.parent / "frontend" / "index.html"
+
+
+def test_api_requests_resolve_inside_dashboard_subpath():
+    html = DASHBOARD_HTML.read_text()
+    api_paths = re.findall(r"fetch\(['\"]([^'\"]*api/v1/[^'\"]*)['\"]", html)
+
+    assert api_paths
+    assert {
+        urljoin("https://forge.alexanderwhitestone.com/dashboard/", path)
+        for path in api_paths
+    } == {
+        "https://forge.alexanderwhitestone.com/dashboard/api/v1/context",
+        "https://forge.alexanderwhitestone.com/dashboard/api/v1/events",
+    }

tests/test_command_palette.py

@@ -0,0 +1,48 @@
+import json
+import subprocess
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urljoin
+
+
+FRONTEND = Path(__file__).parents[1] / "frontend"
+COMMANDS = FRONTEND / "commands.js"
+
+
+class ScriptSourceParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.sources = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag == "script":
+            source = dict(attrs).get("src")
+            if source:
+                self.sources.append(source)
+
+
+def test_filtered_command_runs_the_matching_action():
+    script = f"""
+const filterCommands = require({json.dumps(str(COMMANDS))});
+let action = '';
+const commands = [
+  {{ name: 'Open whiteboard', run: () => {{ action = 'whiteboard'; }} }},
+  {{ name: 'Refresh now', run: () => {{ action = 'refresh'; }} }},
+];
+const matches = filterCommands(commands, 'refresh');
+if (matches.length !== 1) throw new Error(`expected one match, got ${{matches.length}}`);
+matches[0].run();
+if (action !== 'refresh') throw new Error(`expected refresh, got ${{action}}`);
+"""
+
+    subprocess.run(["node", "-e", script], check=True, capture_output=True, text=True)
+
+
+def test_command_script_resolves_inside_dashboard_subpath():
+    parser = ScriptSourceParser()
+    parser.feed((FRONTEND / "index.html").read_text())
+    command_source = next(source for source in parser.sources if source.endswith("commands.js"))
+
+    assert urljoin(
+        "https://forge.alexanderwhitestone.com/dashboard/", command_source
+    ) == "https://forge.alexanderwhitestone.com/dashboard/static/commands.js"

tests/test_context_timeout.py

@@ -62,4 +62,108 @@ async def test_context_normalizes_nullable_issue_collections(monkeypatch):
     issue = json.loads(response.body)["issues"][0]
 
     assert issue["labels"] == []
-    assert issue["assignees"] == []
+    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"] == ""
+
+
+@pytest.mark.anyio
+async def test_context_normalizes_null_collection_payloads(monkeypatch):
+    async def user():
+        return {"id": 1, "login": "timmy"}
+
+    async def null_collection():
+        return None
+
+    monkeypatch.setattr(main, "current_user", user)
+    monkeypatch.setattr(main, "repos", null_collection)
+    monkeypatch.setattr(main, "issues", null_collection)
+    monkeypatch.setattr(main, "pull_requests", null_collection)
+
+    response = await main.context()
+    context = json.loads(response.body)
+
+    assert context["repos"] == []
+    assert context["issues"] == []
+    assert context["pull_requests"] == []
+
+
+@pytest.mark.anyio
+async def test_context_normalizes_nullable_user_profile_fields(monkeypatch):
+    async def user():
+        return {
+            "id": 1,
+            "login": "timmy",
+            "full_name": None,
+            "email": None,
+        }
+
+    async def empty_collection():
+        return []
+
+    monkeypatch.setattr(main, "current_user", user)
+    monkeypatch.setattr(main, "repos", empty_collection)
+    monkeypatch.setattr(main, "issues", empty_collection)
+    monkeypatch.setattr(main, "pull_requests", empty_collection)
+
+    response = await main.context()
+    context = json.loads(response.body)
+
+    assert response.status_code == 200
+    assert context["user"]["full_name"] == ""
+    assert context["user"]["email"] == ""

tests/test_event_stream.py

@@ -1,3 +1,5 @@
+import asyncio
+import json
 from pathlib import Path
 
 import pytest
@@ -49,6 +51,45 @@ async def test_event_stream_returns_recent_authenticated_gitea_activity(monkeypa
     assert response == expected
 
 
+@pytest.mark.anyio
+async def test_event_stream_returns_retryable_response_when_gitea_exceeds_deadline(monkeypatch):
+    cancelled = asyncio.Event()
+
+    async def hanging_activity_events():
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelled.set()
+
+    monkeypatch.setattr(main, "EVENT_STREAM_TIMEOUT_SECONDS", 0.01)
+    monkeypatch.setattr(main, "activity_events", hanging_activity_events)
+
+    response = await main.event_stream()
+
+    assert response.status_code == 503
+    assert response.headers["retry-after"] == "1"
+    assert json.loads(response.body) == {
+        "error": "Gitea event stream request timed out after 0.01s"
+    }
+    assert cancelled.is_set()
+
+
+@pytest.mark.anyio
+async def test_event_stream_returns_retryable_response_when_gitea_request_fails(monkeypatch):
+    async def failing_activity_events():
+        raise ConnectionError("connection refused")
+
+    monkeypatch.setattr(main, "activity_events", failing_activity_events)
+
+    response = await main.event_stream()
+
+    assert response.status_code == 503
+    assert response.headers["retry-after"] == "5"
+    assert json.loads(response.body) == {
+        "error": "Gitea event stream is temporarily unavailable"
+    }
+
+
 @pytest.mark.anyio
 async def test_activity_events_fetches_feed_for_authenticated_user(monkeypatch):
     paths = []

tests/test_health.py

@@ -1,3 +1,6 @@
+import asyncio
+import json
+
 import pytest
 
 from src import main
@@ -37,3 +40,29 @@ async def test_readiness_endpoint_returns_503_when_gitea_is_unavailable(monkeypa
     assert response.status_code == 503
     assert b'"status":"not_ready"' in response.body
     assert b'"error":"connection refused"' in response.body
+
+
+@pytest.mark.anyio
+async def test_readiness_endpoint_times_out_and_cancels_stalled_gitea_check(monkeypatch):
+    cancelled = asyncio.Event()
+
+    async def hanging_user():
+        try:
+            await asyncio.sleep(0.05)
+            return {"login": "too-late"}
+        finally:
+            cancelled.set()
+
+    monkeypatch.setattr(main, "READINESS_TIMEOUT_SECONDS", 0.01, raising=False)
+    monkeypatch.setattr(main, "current_user", hanging_user)
+
+    response = await main.readiness()
+
+    assert response.status_code == 503
+    assert response.headers["retry-after"] == "1"
+    assert json.loads(response.body) == {
+        "status": "not_ready",
+        "service": "stackchain-dashboard",
+        "error": "Gitea readiness check timed out after 0.01s",
+    }
+    assert cancelled.is_set()

tests/test_markdown_renderer.py

@@ -0,0 +1,52 @@
+import json
+import subprocess
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import urljoin
+
+
+FRONTEND = Path(__file__).parent.parent / "frontend"
+RENDERER = FRONTEND / "markdown.js"
+
+
+class ScriptSourceParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.sources = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag == "script":
+            source = dict(attrs).get("src")
+            if source:
+                self.sources.append(source)
+
+
+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>"
+    )
+
+
+def test_markdown_script_resolves_inside_dashboard_subpath():
+    parser = ScriptSourceParser()
+    parser.feed((FRONTEND / "index.html").read_text())
+    markdown_source = next(
+        source for source in parser.sources if source.endswith("markdown.js")
+    )
+
+    assert urljoin(
+        "https://forge.alexanderwhitestone.com/dashboard/", markdown_source
+    ) == "https://forge.alexanderwhitestone.com/dashboard/static/markdown.js"