devlog-tracker 0.30.0 → 0.31.0

package/core/scripts/tests/test-report.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# Self-check for report-devlog.sh (docs/design/read-side-and-promote.md B).
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+DEVLOG_DIR="$TMP_ROOT/.devlog"
+FAIL=0
+assert_line() {
+  local desc="$1" expected="$2" out="$3"
+  if printf '%s\n' "$out" | grep -qxF "$expected"; then echo "PASS: $desc"
+  else echo "FAIL: $desc (missing line [$expected] in: $out)"; FAIL=1; fi
+}
+assert_no_line_prefix() {
+  local desc="$1" prefix="$2" out="$3"
+  if printf '%s\n' "$out" | grep -q "^$prefix"; then echo "FAIL: $desc (found $prefix)"; FAIL=1
+  else echo "PASS: $desc"; fi
+}
+jcheck() {
+  local desc="$1" json="$2" expr="$3"
+  if ! command -v node >/dev/null 2>&1; then echo "SKIP: $desc (no node)"; return 0; fi
+  if printf '%s' "$json" | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')); process.exit(($expr)?0:1)"; then
+    echo "PASS: $desc"
+  else echo "FAIL: $desc"; FAIL=1; fi
+}
+
+# --- No .devlog -> NOT_STARTED ----------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "no .devlog -> NOT_STARTED" "NOT_STARTED" "$OUT"
+
+# --- Fixture ------------------------------------------------------------------
+mkdir -p "$DEVLOG_DIR"
+{
+  cat <<'EOF'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### User Input
+secret-input-text
+
+### Summary
+EOF
+  printf 'first "quoted" \\ back\ttab 中文\n'
+  cat <<'EOF'
+
+### Handoff
+#### 現況
+x
+
+### Status
+DONE
+
+## Round 2 — 2026-09-02T10:00:00+0800
+
+### Summary
+blocked one
+```
+## Round 9 fake inside fence
+```
+
+### Status
+BLOCKED
+
+## Checkpoint（Round 1-2）
+### 決策
+- keep it
+
+## Round 3 — 2026-09-03T10:00:00+0800
+
+### Summary
+in progress
+
+### 段落 探索
+seg body
+
+### Status
+INTERRUPTED
+[reason: dangling:next_prompt]
+
+## Kept 索引
+- `devlog.topic-a.md`：Round 5-5，kept_at 2026-09-05T00:00:00+0800，topic a
+EOF
+} > "$DEVLOG_DIR/devlog.md"
+cat > "$DEVLOG_DIR/devlog.archive.md" <<'EOF'
+## Round 0 — 2026-08-31T10:00:00+0800
+
+### Summary
+archived
+
+### Status
+DONE
+EOF
+cat > "$DEVLOG_DIR/devlog.topic-a.md" <<'EOF'
+## Round 5 — 2026-09-05T10:00:00+0800
+
+### Summary
+kept topic
+
+### Status
+DONE
+EOF
+cat > "$DEVLOG_DIR/devlog.feat-x.md" <<'EOF'
+## Round 1 — 2026-09-04T10:00:00+0800
+
+### Summary
+branch work
+
+### Status
+IN_PROGRESS
+EOF
+printf '# Lessons: foo\n\n## 2026-09-01T00:00:00+0800\nlesson.\n' > "$DEVLOG_DIR/devlog.lessons.foo.md"
+
+# --- Default KEY=VALUE --------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "branch" "BRANCH=main" "$OUT"
+assert_line "total rounds = archive + main, fenced fake ignored" "ROUNDS_TOTAL=4" "$OUT"
+assert_line "main rounds" "ROUNDS_MAIN=3" "$OUT"
+assert_line "archive rounds" "ROUNDS_ARCHIVE=1" "$OUT"
+assert_line "done count" "STATUS_DONE=2" "$OUT"
+assert_line "in-progress count (branch file not scanned)" "STATUS_IN_PROGRESS=0" "$OUT"
+assert_line "blocked count" "STATUS_BLOCKED=1" "$OUT"
+assert_line "interrupted count despite reason line" "STATUS_INTERRUPTED=1" "$OUT"
+assert_line "blocked ratio" "BLOCKED_RATIO=25" "$OUT"
+assert_line "checkpoints" "CHECKPOINTS=1" "$OUT"
+assert_line "kept topics" "KEPT_TOPICS=1" "$OUT"
+assert_line "lessons topics" "LESSONS_TOPICS=1" "$OUT"
+assert_line "first round at" "FIRST_ROUND_AT=2026-08-31T10:00:00+0800" "$OUT"
+assert_line "last round at" "LAST_ROUND_AT=2026-09-03T10:00:00+0800" "$OUT"
+assert_no_line_prefix "no advisory state -> no LESSONS_ADVISORY" "LESSONS_ADVISORY=" "$OUT"
+
+printf '%s\n' '{"count": 2, "threshold": 3}' > "$DEVLOG_DIR/.lessons-advisory-state"
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "advisory state present" "LESSONS_ADVISORY=2/3" "$OUT"
+rm -f "$DEVLOG_DIR/.lessons-advisory-state"
+
+# --- Empty devlog dir: zeros and none ----------------------------------------
+EMPTY_ROOT="$(mktemp -d)"
+mkdir -p "$EMPTY_ROOT/.devlog"
+OUT="$(CLAUDE_PROJECT_DIR="$EMPTY_ROOT" bash "$SCRIPT_DIR/report-devlog.sh")"
+assert_line "empty: zero rounds" "ROUNDS_TOTAL=0" "$OUT"
+assert_line "empty: zero ratio" "BLOCKED_RATIO=0" "$OUT"
+assert_line "empty: first none" "FIRST_ROUND_AT=none" "$OUT"
+rm -rf "$EMPTY_ROOT"
+
+# --- Unknown arg -> exit 2 ------------------------------------------------------
+bash "$SCRIPT_DIR/report-devlog.sh" --bogus >/dev/null 2>&1
+RC=$?
+if [ "$RC" -eq 2 ]; then echo "PASS: unknown arg exits 2"; else echo "FAIL: unknown arg exit $RC"; FAIL=1; fi
+
+# --- --json (no rounds) -------------------------------------------------------
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json)"
+jcheck "json: started + counts are numbers" "$J" 'd.started===true && d.rounds_total===4 && d.status_blocked===1 && d.blocked_ratio===25'
+jcheck "json: branch + times" "$J" 'd.branch==="main" && d.first_round_at==="2026-08-31T10:00:00+0800"'
+jcheck "json: no advisory -> null" "$J" 'd.lessons_advisory===null'
+jcheck "json: no rounds array without --rounds" "$J" '!("rounds" in d) && !("checkpoint_blocks" in d)'
+
+# --- --json --rounds ------------------------------------------------------------
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds)"
+jcheck "rounds: 4 entries, archive first" "$J" 'd.rounds.length===4 && d.rounds[0].branch==="archive" && d.rounds[0].n===0'
+jcheck "rounds: escaping survives quote/backslash/tab/CJK" "$J" 'd.rounds[1].summary.includes("\"quoted\"") && d.rounds[1].summary.includes("\\") && d.rounds[1].summary.includes("\t") && d.rounds[1].summary.includes("中文")'
+jcheck "rounds: fenced fake heading stays inside summary" "$J" 'd.rounds[2].summary.includes("## Round 9 fake inside fence")'
+jcheck "rounds: status parsed despite reason line" "$J" 'd.rounds[3].status==="INTERRUPTED"'
+jcheck "rounds: segments captured" "$J" 'd.rounds[3].segments.length===1 && d.rounds[3].segments[0]==="段落 探索\nseg body"'
+jcheck "rounds: handoff keeps #### lines" "$J" 'd.rounds[1].handoff.startsWith("#### 現況")'
+jcheck "rounds: line numbers" "$J" 'd.rounds[1].line===1 && d.rounds[1].file==="devlog.md"'
+jcheck "rounds: no input by default" "$J" 'd.rounds.every(r => !("input" in r))'
+jcheck "checkpoint_blocks: one block with body" "$J" 'd.checkpoint_blocks.length===1 && d.checkpoint_blocks[0].heading==="Checkpoint（Round 1-2）" && d.checkpoint_blocks[0].body.includes("keep it")'
+
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds --with-input)"
+jcheck "with-input: input field present" "$J" 'd.rounds[1].input==="secret-input-text"'
+
+# --- --json on NOT_STARTED ------------------------------------------------------
+NS_ROOT="$(mktemp -d)"
+J="$(CLAUDE_PROJECT_DIR="$NS_ROOT" bash "$SCRIPT_DIR/report-devlog.sh" --json)"
+jcheck "json NOT_STARTED" "$J" 'd.started===false'
+rm -rf "$NS_ROOT"
+
+# --- --all-branches ---------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/report-devlog.sh" --all-branches)"
+assert_line "all-branches: branch file added, kept file excluded" "ROUNDS_TOTAL=5" "$OUT"
+assert_line "all-branches: in-progress from branch file" "STATUS_IN_PROGRESS=1" "$OUT"
+assert_line "all-branches: last round from branch file" "LAST_ROUND_AT=2026-09-04T10:00:00+0800" "$OUT"
+J="$(bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds --all-branches)"
+jcheck "all-branches: feat-x rounds tagged" "$J" 'd.rounds.some(r => r.branch==="feat-x" && r.summary==="branch work")'
+jcheck "all-branches: no kept or lessons rounds" "$J" 'd.rounds.every(r => r.branch!=="topic-a" && !r.branch.startsWith("lessons."))'
+
+# --- control chars outside \t\r\n (e.g. pasted ANSI \033) escape to \uXXXX ------
+CTRL_ROOT="$(mktemp -d)"
+mkdir -p "$CTRL_ROOT/.devlog"
+printf '## Round 1 — 2026-09-06T10:00:00+0800\n\n### Summary\nboom\033[31mred\n\n### Status\nDONE\n' \
+  > "$CTRL_ROOT/.devlog/devlog.md"
+J="$(CLAUDE_PROJECT_DIR="$CTRL_ROOT" bash "$SCRIPT_DIR/report-devlog.sh" --json --rounds)"
+jcheck "control char (ESC) escapes to \\u001b, JSON still parses" "$J" 'd.rounds[0].summary.includes("\x1b")'
+rm -rf "$CTRL_ROOT"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/tests/test-round-start.sh

@@ -652,6 +652,13 @@ else
 fi
 rm -f "$DEVLOG_DIR/.checkpoint-state"
 
+# --- 19b: report / timeline are admin (read-side) commands too -------------
+for ADMIN_CMD in report timeline; do
+  rm -f "$DEVLOG_DIR/.round-current.md" "$DEVLOG_DIR/.round-open"
+  printf '{"prompt":"<command-name>/devlog-tracker:%s</command-name>"}' "$ADMIN_CMD" | bash "$SCRIPT_DIR/round-start.sh"
+  assert_file_absent "admin $ADMIN_CMD: no .round-current.md" "$DEVLOG_DIR/.round-current.md"
+done
+
 # --- 20: a namespaced-but-different command name is not falsely exempted ---
 # "lessons-on" must not match the "lessons" case arm (prefix collision guard).
 LESSONS_ON_PROMPT='<command-name>/devlog-tracker:lessons-on</command-name><command-message>lessons-on</command-message><command-args></command-args>'
@@ -677,6 +684,15 @@ else
 fi
 rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
 
+# --- 21b: /devlog-tracker:pr and :promote are NOT exempt (outward / file writes)
+for WORK_CMD in pr promote; do
+  rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+  printf '{"prompt":"<command-name>/devlog-tracker:%s</command-name>"}' "$WORK_CMD" | bash "$SCRIPT_DIR/round-start.sh"
+  CUR_BODY="$(cat "$DEVLOG_DIR/.round-current.md" 2>/dev/null || echo '')"
+  assert_contains "$WORK_CMD command still opens a Round" "## Round 1 —" "$CUR_BODY"
+done
+rm -f "$DEVLOG_DIR/devlog.md" "$DEVLOG_DIR/.round-open" "$DEVLOG_DIR/.turn-start" "$DEVLOG_DIR/.round-current.md"
+
 # --- workspace claim on next prompt ----------------------------------------
 WS="$TMP_ROOT/ws"
 mkdir -p "$WS/.devlog"

package/core/scripts/tests/test-timeline.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Self-check for timeline-devlog.sh (docs/design/read-side-and-promote.md C).
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMP_ROOT"' EXIT
+export CLAUDE_PROJECT_DIR="$TMP_ROOT"
+DEVLOG_DIR="$TMP_ROOT/.devlog"
+FAIL=0
+pass() { echo "PASS: $1"; }
+fail() { echo "FAIL: $1"; FAIL=1; }
+
+# --- NO_NODE: node missing from PATH (checked before anything else) ----------
+EMPTY_BIN="$TMP_ROOT/empty-bin"
+mkdir -p "$EMPTY_BIN"
+BASH_BIN="$(command -v bash)"
+OUT="$(PATH="$EMPTY_BIN" "$BASH_BIN" "$SCRIPT_DIR/timeline-devlog.sh" 2>&1)"
+[ "$OUT" = "NO_NODE" ] && pass "no node -> NO_NODE" || fail "no node -> NO_NODE (got $OUT)"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "SKIP: remaining timeline checks need node"
+  if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0; else echo "Some checks FAILED."; exit 1; fi
+fi
+
+# --- NOT_STARTED --------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh")"
+[ "$OUT" = "NOT_STARTED" ] && pass "no .devlog -> NOT_STARTED" || fail "NOT_STARTED (got $OUT)"
+[ ! -e "$DEVLOG_DIR" ] && pass "NOT_STARTED creates nothing" || fail "NOT_STARTED created .devlog"
+
+# --- End to end -----------------------------------------------------------------
+mkdir -p "$DEVLOG_DIR"
+cat > "$DEVLOG_DIR/devlog.md" <<'EOF2'
+## Round 1 — 2026-09-01T10:00:00+0800
+
+### User Input
+secret-input-text
+
+### Summary
+<script>alert(1)</script> 中文摘要
+
+### Status
+DONE
+EOF2
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh")"
+case "$OUT" in
+  "OUT=$(cd "$DEVLOG_DIR" && pwd)/timeline.html") pass "default OUT path is absolute .devlog/timeline.html" ;;
+  *) fail "default OUT (got $OUT)" ;;
+esac
+HTML="$DEVLOG_DIR/timeline.html"
+grep -q '中文摘要' "$HTML" && pass "summary rendered" || fail "summary missing"
+grep -q '<script>alert' "$HTML" && fail "raw script tag leaked" || pass "script tag escaped"
+grep -q 'secret-input-text' "$HTML" && fail "User Input leaked" || pass "User Input not included"
+[ ! -e "$HTML.tmp" ] && pass "no leftover tmp file" || fail "leftover $HTML.tmp"
+
+# --- --out ------------------------------------------------------------------------
+OUT="$(bash "$SCRIPT_DIR/timeline-devlog.sh" --out "$TMP_ROOT/custom.html")"
+[ -s "$TMP_ROOT/custom.html" ] && pass "--out writes the given path" || fail "--out ($OUT)"
+
+# --- unknown arg ------------------------------------------------------------------
+bash "$SCRIPT_DIR/timeline-devlog.sh" --bogus >/dev/null 2>&1
+RC=$?
+[ "$RC" -eq 2 ] && pass "unknown arg exits 2" || fail "unknown arg exit $RC"
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/core/scripts/timeline-devlog.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# /devlog-tracker:timeline and `npx devlog-tracker timeline`
+# (docs/design/read-side-and-promote.md C): report-devlog.sh --json --rounds
+# piped into timeline-render.js, written to .devlog/timeline.html (gitignored).
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+
+# Checked before sourcing anything: Claude plugin users may not have Node.
+command -v node >/dev/null 2>&1 || { echo "NO_NODE"; exit 0; }
+
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+ALL=0
+OUT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all-branches) ALL=1 ;;
+    --out) shift; OUT="${1:-}" ;;
+    *) echo "UNKNOWN_ARG=$1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+devlog_resolve_paths "${DEVLOG_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-.}}"
+[ -d "$DEVLOG_DIR" ] || { echo "NOT_STARTED"; exit 0; }
+[ -n "$OUT" ] || OUT="$DEVLOG_DIR/timeline.html"
+
+ARGS=(--json --rounds)
+[ "$ALL" -eq 1 ] && ARGS+=(--all-branches)
+
+JSON_TMP="$(mktemp "${TMPDIR:-/tmp}/devlog-timeline.XXXXXX")" || exit 1
+trap 'rm -f "$JSON_TMP" "$OUT.tmp"' EXIT
+bash "$SCRIPT_DIR/report-devlog.sh" "${ARGS[@]}" > "$JSON_TMP" || exit 1
+node "$SCRIPT_DIR/timeline-render.js" < "$JSON_TMP" > "$OUT.tmp" || exit 1
+mv "$OUT.tmp" "$OUT" || exit 1
+
+OUT_DIR="$(cd "$(dirname "$OUT")" && pwd)"
+echo "OUT=$OUT_DIR/$(basename "$OUT")"

package/core/scripts/timeline-render.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+'use strict';
+// report-devlog.sh --json --rounds 的輸出 → 一份自足的 HTML 時間軸
+// （docs/design/read-side-and-promote.md C）。零相依；所有 devlog 文字先跳脫
+// 再轉 Markdown 子集，不輸出任何來自 devlog 的原始 HTML。
+
+const STATUSES = ['DONE', 'IN_PROGRESS', 'BLOCKED', 'INTERRUPTED'];
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// http(s) 與相對路徑可以當連結；其他 scheme（javascript:、data: …）與
+// protocol-relative（//host）一律不給連結。
+function safeHref(url) {
+  const u = String(url).trim();
+  // A leading/embedded C0 control char (e.g. \u0001) hides the real scheme
+  // from the tests below, but browsers strip it and still run it — reject.
+  if (/[\u0000-\u001F\u007F]/.test(u)) return null;
+  if (/^https?:\/\//i.test(u)) return u;
+  if (u.startsWith('//')) return null;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(u)) return null;
+  return u;
+}
+
+function emphasis(raw) {
+  return escapeHtml(raw).replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+}
+
+function inline(text) {
+  return String(text)
+    .split(/(`[^`]+`)/)
+    .map((part) => {
+      if (/^`[^`]+`$/.test(part)) return `<code>${escapeHtml(part.slice(1, -1))}</code>`;
+      const re = /\[([^\]]+)\]\(([^)\s]+)\)/g;
+      let out = '';
+      let last = 0;
+      let m;
+      while ((m = re.exec(part))) {
+        out += emphasis(part.slice(last, m.index));
+        const href = safeHref(m[2]);
+        out += href === null ? emphasis(m[0]) : `<a href="${escapeHtml(href)}">${emphasis(m[1])}</a>`;
+        last = re.lastIndex;
+      }
+      return out + emphasis(part.slice(last));
+    })
+    .join('');
+}
+
+const FENCE = /^\s*```/;
+const HEADING = /^(#{1,4})\s+(.*)$/;
+const LIST_ITEM = /^(\s*)([-*]|\d+\.)\s+(.*)$/;
+const TABLE_ROW = /^\s*\|/;
+const TABLE_SEP = /^\s*\|?\s*:?-{3,}/;
+
+function tableCells(line) {
+  return line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim());
+}
+
+function renderMarkdown(md) {
+  const lines = String(md || '').split('\n');
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (FENCE.test(line)) {
+      const buf = [];
+      i++;
+      while (i < lines.length && !FENCE.test(lines[i])) buf.push(lines[i++]);
+      i++;
+      out.push(`<pre><code>${escapeHtml(buf.join('\n'))}</code></pre>`);
+      continue;
+    }
+    const h = HEADING.exec(line);
+    if (h) {
+      const level = Math.min(h[1].length + 2, 6);
+      out.push(`<h${level}>${inline(h[2])}</h${level}>`);
+      i++;
+      continue;
+    }
+    if (TABLE_ROW.test(line) && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1])) {
+      const head = tableCells(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && TABLE_ROW.test(lines[i])) rows.push(tableCells(lines[i++]));
+      const th = head.map((c) => `<th>${inline(c)}</th>`).join('');
+      const tb = rows.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join('')}</tr>`).join('');
+      out.push(`<table><thead><tr>${th}</tr></thead><tbody>${tb}</tbody></table>`);
+      continue;
+    }
+    if (LIST_ITEM.test(line)) {
+      const m = LIST_ITEM.exec(line);
+      const ordered = /\d/.test(m[2]);
+      const items = [];
+      while (i < lines.length) {
+        const m = LIST_ITEM.exec(lines[i]);
+        if (m) {
+          const isOrdered = /\d/.test(m[2]);
+          if (isOrdered !== ordered) break; // Different list type, stop here
+          items.push({ nested: m[1].length >= 2, text: m[3] });
+          i++;
+        } else if (items.length && /^\s{2,}\S/.test(lines[i])) {
+          items[items.length - 1].text += ' ' + lines[i].trim();
+          i++;
+        } else break;
+      }
+      const tag = ordered ? 'ol' : 'ul';
+      const lis = items.map((it) => `<li${it.nested ? ' class="nested"' : ''}>${inline(it.text)}</li>`).join('');
+      out.push(`<${tag}>${lis}</${tag}>`);
+      continue;
+    }
+    if (/^\s*$/.test(line)) {
+      i++;
+      continue;
+    }
+    // 至少吃掉目前這一行，避免「像表格但不是表格」的行卡住迴圈。
+    const para = [line];
+    i++;
+    while (
+      i < lines.length &&
+      !/^\s*$/.test(lines[i]) &&
+      !FENCE.test(lines[i]) &&
+      !HEADING.test(lines[i]) &&
+      !LIST_ITEM.test(lines[i]) &&
+      !TABLE_ROW.test(lines[i])
+    ) {
+      para.push(lines[i++]);
+    }
+    out.push(`<p>${para.map(inline).join('<br>')}</p>`);
+  }
+  return out.join('\n');
+}
+
+function statusOf(s) {
+  return STATUSES.includes(s) ? s : 'NONE';
+}
+
+function roundCard(r) {
+  const st = statusOf(r.status);
+  const parts = [];
+  if (r.input) parts.push(`<h4>User Input</h4><pre><code>${escapeHtml(r.input)}</code></pre>`);
+  if (r.reply) parts.push(`<h4>Reply</h4>${renderMarkdown(r.reply)}`);
+  if (r.handoff) parts.push(`<h4>Handoff</h4>${renderMarkdown(r.handoff)}`);
+  for (const seg of r.segments || []) parts.push(`<div class="seg">${renderMarkdown('#### ' + seg)}</div>`);
+  const details = parts.length ? `<details><summary>詳細</summary>${parts.join('\n')}</details>` : '';
+  return `<article class="card round" data-status="${st}" data-branch="${escapeHtml(r.branch)}">
+<header><span class="badge b-${st}">${st === 'NONE' ? '—' : st}</span><strong>Round ${Number(r.n)}</strong><time>${escapeHtml(r.at || '')}</time><span class="branch">${escapeHtml(r.branch)}</span></header>
+<div class="summary">${renderMarkdown(r.summary)}</div>
+${details}
+</article>`;
+}
+
+function checkpointCard(c) {
+  return `<article class="card checkpoint" data-status="CHECKPOINT" data-branch="${escapeHtml(c.branch)}">
+<header><span class="badge b-CHECKPOINT">CHECKPOINT</span><strong>${escapeHtml(c.heading)}</strong><span class="branch">${escapeHtml(c.branch)}</span></header>
+<details open><summary>內容</summary>${renderMarkdown(c.body)}</details>
+</article>`;
+}
+
+// Round 依時間排序；Checkpoint 沒有時間，排在同一檔案中位於它之前的最後一個
+// Round 後面。
+function timelineItems(data) {
+  const rounds = data.rounds || [];
+  const items = rounds.map((r, idx) => ({ key: r.at || '', order: 0, idx, html: roundCard(r) }));
+  (data.checkpoint_blocks || []).forEach((c, idx) => {
+    let prev = null;
+    for (const r of rounds) {
+      if (r.file === c.file && r.line < c.line && (!prev || r.line > prev.line)) prev = r;
+    }
+    items.push({ key: prev ? prev.at || '' : '', order: 1, idx, html: checkpointCard(c) });
+  });
+  items.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : a.order - b.order || a.idx - b.idx));
+  return items.map((it) => it.html);
+}
+
+const CSS = `:root{--bg:#f7f7f5;--fg:#1f2328;--muted:#656d76;--card:#fff;--line:#d0d7de;--code:#eff1f3;
+--done:#1a7f37;--progress:#0969da;--blocked:#cf222e;--interrupted:#9a6700;--checkpoint:#8250df;--none:#6e7781}
+@media (prefers-color-scheme:dark){:root{--bg:#0d1117;--fg:#e6edf3;--muted:#8d96a0;--card:#161b22;--line:#30363d;--code:#1f242c;
+--done:#3fb950;--progress:#4493f8;--blocked:#f85149;--interrupted:#d29922;--checkpoint:#ab7df8;--none:#8d96a0}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.6 system-ui,-apple-system,"Segoe UI","Noto Sans TC",sans-serif}
+main{max-width:920px;margin:0 auto;padding:24px 16px 64px}h1{font-size:22px;margin:0 0 4px}.meta{color:var(--muted);font-size:13px;margin-bottom:16px}
+.stats{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:16px}.stat{background:var(--card);border:1px solid var(--line);border-radius:8px;padding:6px 12px;font-size:13px}
+.stat b{font-size:17px;margin-right:4px}.filters{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:20px}
+.filters input,.filters select{font:inherit;padding:6px 10px;border:1px solid var(--line);border-radius:6px;background:var(--card);color:var(--fg)}
+.filters input{flex:1;min-width:160px}.card{background:var(--card);border:1px solid var(--line);border-left:4px solid var(--none);border-radius:8px;padding:12px 16px;margin-bottom:12px;overflow-wrap:anywhere}
+.card[data-status=DONE]{border-left-color:var(--done)}.card[data-status=IN_PROGRESS]{border-left-color:var(--progress)}
+.card[data-status=BLOCKED]{border-left-color:var(--blocked)}.card[data-status=INTERRUPTED]{border-left-color:var(--interrupted)}
+.card[data-status=CHECKPOINT]{border-left-color:var(--checkpoint);background:color-mix(in srgb,var(--checkpoint) 6%,var(--card))}
+.card header{display:flex;flex-wrap:wrap;align-items:center;gap:8px;font-size:14px}.card time,.card .branch{color:var(--muted);font-size:12px}
+.badge{font-size:11px;font-weight:600;padding:1px 8px;border-radius:999px;color:#fff;background:var(--none)}
+.b-DONE{background:var(--done)}.b-IN_PROGRESS{background:var(--progress)}.b-BLOCKED{background:var(--blocked)}.b-INTERRUPTED{background:var(--interrupted)}.b-CHECKPOINT{background:var(--checkpoint)}
+details summary{cursor:pointer;color:var(--muted);font-size:13px;margin-top:6px}code{background:var(--code);padding:1px 4px;border-radius:4px;font-size:.9em}
+pre{background:var(--code);padding:10px;border-radius:6px;overflow-x:auto}pre code{padding:0;background:none}
+table{border-collapse:collapse;display:block;overflow-x:auto}th,td{border:1px solid var(--line);padding:4px 8px;text-align:left}
+li.nested{margin-left:1.5em}h3,h4,h5,h6{margin:12px 0 4px}.seg{border-top:1px dashed var(--line);margin-top:8px}.empty{color:var(--muted)}`;
+
+const SCRIPT = `(function(){var q=document.getElementById('q'),s=document.getElementById('fs'),b=document.getElementById('fb');
+function f(){var t=q.value.toLowerCase(),sv=s.value,bv=b.value;document.querySelectorAll('.card').forEach(function(c){
+c.hidden=!((!sv||c.dataset.status===sv)&&(!bv||c.dataset.branch===bv)&&(!t||c.textContent.toLowerCase().indexOf(t)>=0));});}
+[q,s,b].forEach(function(e){e.addEventListener('input',f);});})();`;
+
+function render(data) {
+  const d = data || {};
+  const branches = [...new Set([...(d.rounds || []), ...(d.checkpoint_blocks || [])].map((x) => x.branch))].sort();
+  const stat = (label, n) => `<span class="stat"><b>${Number(n) || 0}</b>${label}</span>`;
+  const range = d.first_round_at ? `${escapeHtml(d.first_round_at)} → ${escapeHtml(d.last_round_at || '')}` : '沒有 Round';
+  const items = timelineItems(d);
+  const opt = (v, label) => `<option value="${escapeHtml(v)}">${escapeHtml(label)}</option>`;
+  return `<!doctype html>
+<html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Devlog Timeline</title><style>${CSS}</style></head><body><main>
+<h1>Devlog Timeline</h1>
+<div class="meta">branch ${escapeHtml(d.branch || '')} · ${range}</div>
+<div class="stats">${stat('Rounds', d.rounds_total)}${stat('DONE', d.status_done)}${stat('IN_PROGRESS', d.status_in_progress)}${stat('BLOCKED', d.status_blocked)}${stat('INTERRUPTED', d.status_interrupted)}${stat('Checkpoints', d.checkpoints)}</div>
+<div class="filters"><input id="q" type="search" placeholder="關鍵字篩選">
+<select id="fs">${opt('', '全部 Status')}${[...STATUSES, 'CHECKPOINT'].map((s) => opt(s, s)).join('')}</select>
+<select id="fb">${opt('', '全部 branch')}${branches.map((b) => opt(b, b)).join('')}</select></div>
+${items.length ? items.join('\n') : '<p class="empty">沒有 Round 可顯示。</p>'}
+</main><script>${SCRIPT}</script></body></html>
+`;
+}
+
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    input += chunk;
+  });
+  process.stdin.on('end', () => {
+    let data;
+    try {
+      data = JSON.parse(input);
+    } catch (e) {
+      process.stderr.write('INVALID_JSON\n');
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(render(data));
+  });
+}
+
+module.exports = { render, renderMarkdown, inline, escapeHtml, safeHref, timelineItems };