feat(v0.6): content-freshness badges on every built page (#57) (#69)

Closes #57.

New module `llmwiki.freshness` computes the age of a page from its
frontmatter (last_updated → ended → started → date, in that order) and
renders a color-coded pill:

  - green   — updated ≤ 14 days ago
  - yellow  — updated 15–60 days ago
  - red     — updated > 60 days ago
  - unknown — no resolvable timestamp or clock skew (future)

Thresholds are configurable via config.json::

    { "freshness": { "green_days": 7, "yellow_days": 30 } }

The relative-time formatter is compact (today / yesterday / N days /
N weeks / N months / N years).

All timestamps are normalised to naive UTC before subtraction so tz
skew between session files and the build host cannot shift pages
across buckets by accident. "Build now" is cached once per build so
every page shows the same clock.

Badges render:
  - in the session page hero strip, after "N min read"
  - on every project card (projects/index.html) — reflecting the
    newest session in that project
  - on every session card inside a project page

34 new tests in tests/test_freshness.py covering:
  - ISO datetime parsing (UTC, Z suffix, offset, date-only, empty,
    malformed)
  - Last-updated resolution priority
  - Relative-time formatting for all bucket boundaries
  - Exact boundary tests: 14 → green, 15 → yellow, 60 → yellow,
    61 → red
  - Far past (1000 days = red)
  - Far future clock skew (-5 days = unknown)
  - Config loading: missing file, custom thresholds, inverted
    thresholds rejected, bad JSON tolerated, missing section kept
    defaults

Author: Pratiyush

llmwiki/build.py

@@ -33,12 +33,14 @@
 import subprocess
 import sys
 from collections import defaultdict
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Optional
 
 import markdown
 
 from llmwiki import REPO_ROOT
+from llmwiki.freshness import freshness_badge, load_freshness_config
 
 # ─── paths ─────────────────────────────────────────────────────────────────
 
@@ -213,6 +215,29 @@ def short_started(meta: dict[str, Any]) -> str:
     return s[:16].replace("T", " ")
 
 
+# ─── freshness (content staleness) ────────────────────────────────────────
+# Cached once per build so every page sees the same "now" and the same
+# thresholds. Populated lazily by render_freshness().
+_FRESHNESS_CONFIG: Optional[tuple[int, int]] = None
+_BUILD_NOW: Optional[datetime] = None
+
+
+def render_freshness(meta: dict[str, Any]) -> str:
+    """Render a freshness badge for a page's frontmatter using cached config.
+
+    Thresholds come from ``config.json`` (freshness.green_days /
+    yellow_days) or the module defaults. Build-time "now" is cached the
+    first call so the whole site renders with one consistent clock.
+    """
+    global _FRESHNESS_CONFIG, _BUILD_NOW
+    if _FRESHNESS_CONFIG is None:
+        _FRESHNESS_CONFIG = load_freshness_config()
+    if _BUILD_NOW is None:
+        _BUILD_NOW = datetime.utcnow()
+    green, yellow = _FRESHNESS_CONFIG
+    return freshness_badge(meta, now=_BUILD_NOW, green_days=green, yellow_days=yellow)
+
+
 # ─── html template helpers ─────────────────────────────────────────────────
 
 def page_head(title: str, description: str, css_prefix: str = "") -> str:
@@ -462,6 +487,7 @@ def render_session(
     if meta.get("tool_calls"):
         bits.append(f'{html.escape(str(meta["tool_calls"]))} tools')
     bits.append(f'<span class="muted">{reading_min} min read</span>')
+    bits.append(render_freshness(meta))
     meta_strip = " · ".join(bits) if bits else ""
 
     tools_list = get_tools_list(meta)
@@ -541,10 +567,12 @@ def card(p: Path, meta: dict[str, Any]) -> str:
         umsgs = meta.get("user_messages", "")
         tcalls = meta.get("tool_calls", "")
         href = f"../sessions/{project_slug}/{p.stem}.html"
+        badge = render_freshness(meta)
         return f"""  <a class="card" href="{href}">
     <div class="card-title">{html.escape(str(slug))}</div>
     <div class="card-meta">{html.escape(str(date))} · {html.escape(str(model))}</div>
     <div class="card-stats muted">{html.escape(str(umsgs))} messages · {html.escape(str(tcalls))} tool calls</div>
+    <div class="card-badge">{badge}</div>
   </a>"""
 
     cards_main = "\n".join(card(p, m) for p, m, _ in main_sessions)
@@ -607,10 +635,18 @@ def render_projects_index(
     for project, sessions in sorted(groups.items(), key=lambda x: -len(x[1])):
         main_count = sum(1 for p, _, _ in sessions if "subagent" not in p.name)
         sub_count = len(sessions) - main_count
+        # Freshness reflects the newest session in the project.
+        newest_meta = max(
+            (m for _, m, _ in sessions),
+            key=lambda m: str(m.get("ended") or m.get("started") or m.get("date") or ""),
+            default={},
+        )
+        badge = render_freshness(newest_meta)
         cards.append(
             f"""  <a class="card" href="{html.escape(project)}.html">
     <div class="card-title">{html.escape(project)}</div>
     <div class="card-meta">{main_count} main · {sub_count} sub-agent</div>
+    <div class="card-badge">{badge}</div>
   </a>"""
         )
 
@@ -1058,6 +1094,31 @@ def build_search_index(
 .card-title { font-weight: 600; font-size: 0.95rem; margin-bottom: 4px; color: var(--text); }
 .card-meta { font-size: 0.82rem; color: var(--text-secondary); }
 .card-stats { font-size: 0.78rem; margin-top: 6px; }
+.card-badge { margin-top: 8px; }
+
+/* Content-freshness badge (#57) */
+.freshness {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 2px 10px; border-radius: 999px;
+  font-size: 0.72rem; font-weight: 600; white-space: nowrap;
+  border: 1px solid;
+}
+.freshness::before {
+  content: ""; width: 6px; height: 6px; border-radius: 50%;
+  background: currentColor;
+}
+.fresh-green   { color: #15803d; background: #dcfce7; border-color: #86efac; }
+.fresh-yellow  { color: #b45309; background: #fef3c7; border-color: #fcd34d; }
+.fresh-red     { color: #b91c1c; background: #fee2e2; border-color: #fca5a5; }
+.fresh-unknown { color: #6b7280; background: #f3f4f6; border-color: #d1d5db; }
+:root[data-theme="dark"] .fresh-green   { color: #86efac; background: #052e16; border-color: #065f46; }
+:root[data-theme="dark"] .fresh-yellow  { color: #fcd34d; background: #3a2a06; border-color: #78350f; }
+:root[data-theme="dark"] .fresh-red     { color: #fca5a5; background: #3a0a0a; border-color: #7f1d1d; }
+:root[data-theme="dark"] .fresh-unknown { color: #9ca3af; background: #1f2937; border-color: #374151; }
+@media print {
+  .freshness { background: #fff !important; color: #000 !important; border-color: #ccc !important; }
+  .freshness::before { background: #000 !important; }
+}
 
 /* Sub-agent collapsible */
 .sub-section { margin-top: 32px; }

llmwiki/freshness.py

@@ -0,0 +1,158 @@
+"""Content-freshness badges — v0.6 (#57).
+
+Computes the age of a page (in days) from its frontmatter and returns a
+color-coded badge rendered as HTML. Ages are bucketed into:
+
+- ``fresh-green``  — updated ≤ ``green_days`` ago (default 14)
+- ``fresh-yellow`` — updated ≤ ``yellow_days`` ago (default 60)
+- ``fresh-red``    — updated > ``yellow_days`` ago
+- ``fresh-unknown`` — no resolvable timestamp OR clock skew (future)
+
+Thresholds can be overridden via ``config.json``::
+
+    {
+      "freshness": {
+        "green_days": 14,
+        "yellow_days": 60
+      }
+    }
+
+The badge text uses a compact relative-time formatter (today / yesterday /
+N days / N weeks / N months / N years). All timestamps are normalised to
+naive UTC before subtraction so timezone skew between session files and
+the build host cannot move pages across buckets by accident.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+from llmwiki import REPO_ROOT
+
+DEFAULT_GREEN_DAYS = 14
+DEFAULT_YELLOW_DAYS = 60
+
+
+def load_freshness_config(repo_root: Path = REPO_ROOT) -> tuple[int, int]:
+    """Return ``(green_days, yellow_days)`` from ``config.json`` or defaults."""
+    candidate = repo_root / "config.json"
+    if not candidate.exists():
+        return DEFAULT_GREEN_DAYS, DEFAULT_YELLOW_DAYS
+    try:
+        data = json.loads(candidate.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return DEFAULT_GREEN_DAYS, DEFAULT_YELLOW_DAYS
+    fresh = data.get("freshness") or {}
+    try:
+        green = int(fresh.get("green_days", DEFAULT_GREEN_DAYS))
+        yellow = int(fresh.get("yellow_days", DEFAULT_YELLOW_DAYS))
+    except (TypeError, ValueError):
+        return DEFAULT_GREEN_DAYS, DEFAULT_YELLOW_DAYS
+    if green < 0 or yellow < green:
+        return DEFAULT_GREEN_DAYS, DEFAULT_YELLOW_DAYS
+    return green, yellow
+
+
+def parse_timestamp(value: Any) -> Optional[datetime]:
+    """Parse an ISO datetime or ``YYYY-MM-DD`` into a naive UTC datetime.
+
+    Returns ``None`` for empty, missing, or malformed values.
+    """
+    if value is None:
+        return None
+    s = str(value).strip()
+    if not s:
+        return None
+    # Try ISO datetime first (with or without timezone)
+    if "T" in s or "+" in s[10:] or "Z" in s:
+        clean = s.replace("Z", "+00:00")
+        try:
+            dt = datetime.fromisoformat(clean)
+        except ValueError:
+            return None
+        if dt.tzinfo is not None:
+            dt = dt.astimezone(timezone.utc).replace(tzinfo=None)
+        return dt
+    # Fall back to date-only
+    try:
+        return datetime.strptime(s[:10], "%Y-%m-%d")
+    except ValueError:
+        return None
+
+
+def resolve_last_updated(meta: dict[str, Any]) -> Optional[datetime]:
+    """Pick the newest timestamp available from a page's frontmatter.
+
+    Prefers ``last_updated`` (explicit), then ``ended``, ``started``, ``date``.
+    """
+    for key in ("last_updated", "ended", "started", "date"):
+        dt = parse_timestamp(meta.get(key))
+        if dt is not None:
+            return dt
+    return None
+
+
+def format_relative_time(age_days: int) -> str:
+    """Compact human label for an age in days (never more than 2 words)."""
+    if age_days < 0:
+        return "unknown"
+    if age_days == 0:
+        return "today"
+    if age_days == 1:
+        return "yesterday"
+    if age_days < 14:
+        return f"{age_days} days ago"
+    if age_days < 60:
+        weeks = age_days // 7
+        return f"{weeks} week{'s' if weeks != 1 else ''} ago"
+    if age_days < 365:
+        months = age_days // 30
+        return f"{months} month{'s' if months != 1 else ''} ago"
+    years = age_days // 365
+    return f"{years} year{'s' if years != 1 else ''} ago"
+
+
+def freshness_class(
+    age_days: Optional[int],
+    green_days: int = DEFAULT_GREEN_DAYS,
+    yellow_days: int = DEFAULT_YELLOW_DAYS,
+) -> str:
+    """Return the CSS class for a given age. ``None`` or negative → unknown."""
+    if age_days is None or age_days < 0:
+        return "fresh-unknown"
+    if age_days <= green_days:
+        return "fresh-green"
+    if age_days <= yellow_days:
+        return "fresh-yellow"
+    return "fresh-red"
+
+
+def freshness_badge(
+    meta: dict[str, Any],
+    now: Optional[datetime] = None,
+    green_days: int = DEFAULT_GREEN_DAYS,
+    yellow_days: int = DEFAULT_YELLOW_DAYS,
+) -> str:
+    """Render a freshness badge for a page given its frontmatter.
+
+    ``now`` lets tests inject a deterministic clock; otherwise ``utcnow()``.
+    """
+    dt = resolve_last_updated(meta)
+    if dt is None:
+        return (
+            '<span class="freshness fresh-unknown" '
+            'title="No last-updated timestamp">updated unknown</span>'
+        )
+    current = now if now is not None else datetime.utcnow()
+    age = (current - dt).days
+    cls = freshness_class(age, green_days, yellow_days)
+    label = format_relative_time(age)
+    iso = dt.strftime("%Y-%m-%d")
+    return (
+        f'<span class="freshness {cls}" '
+        f'title="Last updated {html.escape(iso)}">updated {html.escape(label)}</span>'
+    )