fix(v0.4.2): code-fence truncation + changelog page (#71)

Fixes two user-reported issues:

1) "Full Directory Tree is not being displayed properly" — the converter's
   truncate_chars / truncate_lines cut content mid-code-block and left the
   opening ``` without a matching close fence. The markdown parser then
   swallowed everything below as one giant code block. Fixed by counting
   unbalanced fences in the kept portion and injecting a closing fence
   before the truncation marker. Also hardened parse_jsonl to survive
   corrupt UTF-8 bytes (errors="replace") and stray non-dict records
   that used to crash filter_records.

2) "add changelog page" — CHANGELOG.md now renders as a first-class page
   at /changelog.html with its own nav link, narrow reading column,
   keep-a-changelog typography, and the same theme/print styles as the
   rest of the wiki.

Test delta: +5 truncation tests, +5 changelog page tests. 163 passing
total (was 158). 30 previously-mangled session files regenerated via
llmwiki sync.

Author: Pratiyush

CHANGELOG.md

@@ -11,6 +11,12 @@ Versions below 1.0 are pre-production — API and file formats may change.
 ### Added
 
 - **Session metrics frontmatter** (#63) — converter now emits five new keys per session as JSON inline: `tool_counts`, `token_totals` (input / cache_creation / cache_read / output), `turn_count`, `hour_buckets` (UTC-normalised ISO-hour → activity count), and `duration_seconds`. Foundation for the v0.8 visualization stack (#64 heatmap / #65 tool chart / #66 token card). Stdlib-only; byte-identical on re-run. 24 new tests.
+- **Changelog page** (#72) — `CHANGELOG.md` now renders as a first-class page at `site/changelog.html` with a nav-bar link, narrow reading column, keep-a-changelog typography, and the same theme/print styles as the rest of the wiki.
+
+### Fixed
+
+- **Code-fence truncation eating pages** (#72) — `truncate_chars` / `truncate_lines` used to cut content mid-code-block, leaving the opening ` ``` ` without a closing fence. The markdown parser then swallowed everything that followed as one giant block (user-visible example: the "Full Directory Tree" section on subagent pages). Fixed by counting unbalanced fences in the kept portion and injecting a closing fence before the truncation marker. 5 new tests; 30 previously-mangled session files regenerated.
+- **Sync crash on corrupt JSONL bytes** (#72) — a single stray non-UTF-8 byte in a session transcript used to abort the entire `llmwiki sync` run with `UnicodeDecodeError`. `parse_jsonl` now opens with `errors="replace"` and silently drops non-dict records (rare stray scalars from partial writes that previously crashed `filter_records` with `AttributeError`).
 
 ## [0.4.0] — 2026-04-08
 

llmwiki/build.py

@@ -337,6 +337,7 @@ def link(href: str, label: str, key: str) -> str:
       {link("index.html", "Home", "home")}
       {link("projects/index.html", "Projects", "projects")}
       {link("sessions/index.html", "Sessions", "sessions")}
+      {link("changelog.html", "Changelog", "changelog")}
       <button class="nav-search-btn" id="open-palette" aria-label="Open command palette">
         <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
         <span>Search</span>
@@ -839,6 +840,61 @@ def render_index(
     return out_path
 
 
+# ─── changelog page ────────────────────────────────────────────────────────
+
+def render_changelog(out_dir: Path) -> Optional[Path]:
+    """Render ``CHANGELOG.md`` (repo root) to ``site/changelog.html``.
+
+    Returns None if CHANGELOG.md is missing. Shown as its own top-level page
+    so visitors can see what's new / what shipped without clicking through to
+    GitHub. Keep-a-changelog headings become an in-page TOC via the existing
+    `toc` markdown extension.
+    """
+    src = REPO_ROOT / "CHANGELOG.md"
+    if not src.exists():
+        return None
+    raw = src.read_text(encoding="utf-8")
+
+    # Pull the top H1 ("Changelog") and use it as the hero title; render
+    # everything else as the body. Strip the leading H1 line to avoid a
+    # duplicate title.
+    body_md = raw
+    lines = raw.splitlines()
+    if lines and lines[0].lstrip().startswith("# "):
+        body_md = "\n".join(lines[1:]).lstrip("\n")
+
+    content_html = md_to_html(body_md)
+
+    body = f"""<section class="section changelog-body">
+  <div class="container narrow">
+    <article class="article">
+      {content_html}
+    </article>
+  </div>
+</section>
+</main>
+"""
+
+    page = (
+        page_head(
+            "Changelog — LLM Wiki",
+            "Release notes for llmwiki — features, fixes, and version history.",
+            css_prefix="",
+        )
+        + nav_bar("changelog", link_prefix="")
+        + hero(
+            "Changelog",
+            "Every release, every fix. Keep-a-changelog format, semver.",
+        )
+        + body
+        + page_foot(js_prefix="")
+    )
+
+    out_path = out_dir / "changelog.html"
+    out_path.write_text(page, encoding="utf-8")
+    return out_path
+
+
 # ─── search index ──────────────────────────────────────────────────────────
 
 def build_search_index(
@@ -1182,6 +1238,22 @@ def build_search_index(
 .footer { padding: 32px 0; border-top: 1px solid var(--border); margin-top: 48px; background: var(--bg-alt); }
 .footer p { font-size: 0.85rem; color: var(--text-muted); text-align: center; }
 
+/* Changelog page — narrow reading column + keep-a-changelog typography */
+.container.narrow { max-width: 760px; }
+.changelog-body { padding: 40px 0 64px; }
+.changelog-body .article h2 { margin-top: 48px; padding-bottom: 8px; border-bottom: 1px solid var(--border); font-size: 1.5rem; }
+.changelog-body .article h2:first-child { margin-top: 0; }
+.changelog-body .article h3 { margin-top: 28px; font-size: 1.1rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.04em; }
+.changelog-body .article h4 { margin-top: 20px; font-size: 0.98rem; }
+.changelog-body .article ul { margin: 12px 0 20px; padding-left: 22px; }
+.changelog-body .article li { margin: 6px 0; line-height: 1.6; }
+.changelog-body .article li > code,
+.changelog-body .article p > code { font-size: 0.86rem; padding: 1px 6px; background: var(--bg-code); border-radius: 4px; }
+.changelog-body .article p { line-height: 1.7; }
+.changelog-body .article a { color: var(--accent); }
+.changelog-body .article hr { margin: 36px 0; border: 0; border-top: 1px solid var(--border); }
+.changelog-body .article blockquote { margin: 16px 0; padding: 8px 16px; border-left: 3px solid var(--accent); color: var(--text-secondary); background: var(--bg-alt); border-radius: 0 4px 4px 0; }
+
 /* v0.4: Related pages panel */
 .related-pages { margin-top: 48px; padding-top: 24px; border-top: 1px solid var(--border); }
 .related-pages h3 { font-size: 1.05rem; color: var(--text-secondary); margin-bottom: 12px; }
@@ -2243,7 +2315,11 @@ def build_site(
     render_projects_index(groups, out_dir)
     render_sessions_index(sources, groups, out_dir)
     render_index(groups, sources, out_dir, synthesis=synthesis)
-    print("  wrote index.html, projects/index.html, sessions/index.html")
+    cl_path = render_changelog(out_dir)
+    print(
+        "  wrote index.html, projects/index.html, sessions/index.html"
+        + (", changelog.html" if cl_path else "")
+    )
 
     # Search index
     idx_path = build_search_index(sources, groups, out_dir)

llmwiki/convert.py

@@ -197,15 +197,23 @@ def __len__(self) -> int:
 def parse_jsonl(path: Path) -> list[dict[str, Any]]:
     out: list[dict[str, Any]] = []
     try:
-        with path.open(encoding="utf-8") as f:
+        # ``errors="replace"`` lets us survive the occasional corrupt byte in a
+        # session transcript (e.g. a truncated UTF-8 sequence from a killed
+        # tool). Before the fix a single bad byte would abort the whole sync.
+        with path.open(encoding="utf-8", errors="replace") as f:
             for line_no, line in enumerate(f, 1):
                 line = line.strip()
                 if not line:
                     continue
                 try:
-                    out.append(json.loads(line))
+                    rec = json.loads(line)
                 except json.JSONDecodeError:
-                    pass
+                    continue
+                # Only keep dict-shaped records. JSONL files occasionally
+                # contain stray scalars (e.g. numbers, strings) from partial
+                # writes, which used to crash downstream filter_records.
+                if isinstance(rec, dict):
+                    out.append(rec)
     except OSError:
         pass
     return out
@@ -283,10 +291,26 @@ def __call__(self, text: str) -> str:
         return text
 
 
+def _close_open_fence(text: str) -> str:
+    """If ``text`` contains an odd number of ``\\`\\`\\``` fence markers,
+    append a closing fence so downstream markdown parsers don't swallow the
+    rest of the page as one giant code block. Counts only lines whose first
+    non-whitespace characters are triple backticks (real fences, not inline
+    code). See #72 — truncated tool results used to eat everything below them.
+    """
+    fence_count = sum(
+        1 for line in text.splitlines() if line.lstrip().startswith("```")
+    )
+    if fence_count % 2 == 1:
+        return text + "\n```"
+    return text
+
+
 def truncate_chars(text: str, max_chars: int) -> str:
     if not text or len(text) <= max_chars:
         return text
-    return text[:max_chars] + f"\n…(truncated, {len(text) - max_chars} more chars)"
+    kept = _close_open_fence(text[:max_chars])
+    return kept + f"\n…(truncated, {len(text) - max_chars} more chars)"
 
 
 def truncate_lines(text: str, max_lines: int) -> str:
@@ -295,7 +319,7 @@ def truncate_lines(text: str, max_lines: int) -> str:
     lines = text.splitlines()
     if len(lines) <= max_lines:
         return text
-    kept = "\n".join(lines[:max_lines])
+    kept = _close_open_fence("\n".join(lines[:max_lines]))
     return kept + f"\n…(truncated, {len(lines) - max_lines} more lines)"
 
 

tests/test_changelog_page.py

@@ -0,0 +1,71 @@
+"""Tests for the first-class /changelog page (#72).
+
+``llmwiki.build.render_changelog`` reads ``CHANGELOG.md`` at the repo root and
+renders it to ``site/changelog.html``. These tests pin the contract so a
+future refactor doesn't silently drop the page or mangle its layout.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from llmwiki.build import render_changelog
+
+
+@pytest.fixture
+def tmp_out(tmp_path: Path) -> Path:
+    out = tmp_path / "site"
+    out.mkdir()
+    return out
+
+
+def test_render_changelog_writes_file(tmp_out: Path):
+    out = render_changelog(tmp_out)
+    assert out is not None
+    assert out.exists()
+    assert out.name == "changelog.html"
+
+
+def test_render_changelog_contains_hero_and_nav(tmp_out: Path):
+    render_changelog(tmp_out)
+    html = (tmp_out / "changelog.html").read_text(encoding="utf-8")
+    # Hero
+    assert "Changelog" in html
+    # Nav link is marked active
+    assert 'class="active"' in html
+    # No duplicate top-level "# Changelog" H1 inside article (we strip it
+    # so the hero owns the title).
+    assert html.count("<h1>Changelog</h1>") == 1
+
+
+def test_render_changelog_renders_markdown_headings(tmp_out: Path):
+    render_changelog(tmp_out)
+    html = (tmp_out / "changelog.html").read_text(encoding="utf-8")
+    # Keep-a-changelog headings come through as <h2>
+    assert "[Unreleased]" in html or "Unreleased" in html
+    assert "<h2" in html
+
+
+def test_render_changelog_returns_none_when_missing(tmp_path: Path, monkeypatch):
+    # Point REPO_ROOT at an empty tmp dir so CHANGELOG.md is missing.
+    import llmwiki.build as build
+
+    empty = tmp_path / "empty_repo"
+    empty.mkdir()
+    monkeypatch.setattr(build, "REPO_ROOT", empty)
+    out_dir = tmp_path / "site"
+    out_dir.mkdir()
+    assert render_changelog(out_dir) is None
+    assert not (out_dir / "changelog.html").exists()
+
+
+def test_render_changelog_is_well_formed_html(tmp_out: Path):
+    render_changelog(tmp_out)
+    html = (tmp_out / "changelog.html").read_text(encoding="utf-8")
+    assert html.startswith("<!DOCTYPE html>")
+    assert html.rstrip().endswith("</html>")
+    # Narrow reading column class applied so the changelog doesn't span
+    # the full 1080px content width.
+    assert "container narrow" in html

tests/test_convert.py

@@ -43,6 +43,54 @@ def test_truncate_lines_long():
     assert "truncated" in out
 
 
+# ─── #72: code-fence balance preservation ───────────────────────────────
+# When truncate_chars / truncate_lines cuts mid-code-block, the opening
+# ``` must get a matching close fence so downstream markdown parsers
+# don't consume the entire rest of the page.
+
+
+def test_truncate_chars_closes_open_fence():
+    src = "```\nline1\nline2\nline3\nline4\nline5\nline6\nline7\n"
+    out = truncate_chars(src, 20)
+    # fence count in the returned text should be even (open + auto-close)
+    fences = [ln for ln in out.splitlines() if ln.lstrip().startswith("```")]
+    assert len(fences) % 2 == 0
+    assert len(fences) >= 2  # at least the original open + one close
+    assert "truncated" in out
+
+
+def test_truncate_lines_closes_open_fence():
+    src = "```\nroot/\n├── a\n├── b\n├── c\n├── d\n"
+    out = truncate_lines(src, 3)
+    fences = [ln for ln in out.splitlines() if ln.lstrip().startswith("```")]
+    assert len(fences) % 2 == 0
+    assert "truncated" in out
+
+
+def test_truncate_chars_balanced_fence_unchanged():
+    # Already balanced ``` open + close — truncation should NOT add extras.
+    src = "```\nshort\n```\nmore text that pushes over the char budget"
+    out = truncate_chars(src, 20)
+    fences = [ln for ln in out.splitlines() if ln.lstrip().startswith("```")]
+    # Only the original two fences should be present; no phantom third.
+    assert len(fences) == 2
+
+
+def test_truncate_chars_no_fence_no_change():
+    # Plain text without any fence — no injected close.
+    src = "a" * 100
+    out = truncate_chars(src, 10)
+    assert "```" not in out
+
+
+def test_truncate_chars_fenced_lang_marker():
+    # Fence with a language marker (```python) must still be detected.
+    src = "```python\n" + "x = 1\n" * 50
+    out = truncate_chars(src, 30)
+    fences = [ln for ln in out.splitlines() if ln.lstrip().startswith("```")]
+    assert len(fences) % 2 == 0
+
+
 def test_redactor_username_in_path():
     config = {"redaction": {"real_username": "alice", "replacement_username": "USER", "extra_patterns": []}}
     r = Redactor(config)