refactor(export): centralize export state management and enhance error handling

- Introduced a new utility module for managing export state with atomic I/O and locking mechanisms.
- Updated the export API to validate request bodies and handle invalid 'since' parameters, returning appropriate error responses.
- Enhanced the README to clarify bulk export options and CLI export flag behaviors.
- Added unit tests for new error handling scenarios in the export API and improved logging for session parsing failures.
- Refactored existing code to utilize the new export state management utilities, ensuring consistency across API and CLI.

Author: leostar0412

README.md

@@ -19,12 +19,12 @@ Browse and export Claude Code chat history — Web GUI and CLI.
 - **Smooth transitions** — staggered card/message animations, crossfade content swaps
 - **Scroll-to-top button** in bottom-right corner
 - **Per-model badges** in session header
-- **Bulk export** — download all sessions, incremental updates, or latest-day slice as a zip; if there is nothing to export, the API returns **422** JSON (`Nothing to export`) instead of an empty zip
+- **Bulk export** — download all sessions, incremental updates, or latest-day slice as a zip; if there is nothing to export, the API returns **422** with JSON body `{"error": "Nothing to export", "since": "<mode>"}` (the `since` field echoes your request: `"all"`, `"last"`, or `"incremental"`) instead of an empty zip
 
 ### CLI Export
 - Standalone script to export all sessions to Markdown with YAML frontmatter
 - Rich Markdown: token usage, tool calls, thinking blocks, model info, timestamps
-- `--since last` — export every session that overlaps the **latest UTC calendar day** present in your history (zip name includes `last-MM-DD`)
+- `--since last` — export every session that overlaps the **latest UTC calendar day** present in your history (default zip name: `claude-code-export-last-MM-DD-YYYY-MM-DD.zip` — the first `MM-DD` is that latest UTC day, and `YYYY-MM-DD` is the export date)
 - `--since incremental` — export only sessions **new or changed since the last export** (file mtime + saved state)
 - `--project` flag to export a subset of projects
 
@@ -70,7 +70,7 @@ python scripts/export.py
 # Export to specific directory, no zip
 python scripts/export.py --out ./exports --no-zip
 
-# Latest calendar day (UTC): all sessions active on that day; zip like claude-code-export-last-04-06-2026-05-08.zip
+# Latest calendar day (UTC): all sessions active on that day; zip pattern claude-code-export-last-MM-DD-YYYY-MM-DD.zip (e.g. claude-code-export-last-04-06-2026-05-08.zip — 04-06 = latest UTC day, 2026-05-08 = export date)
 python scripts/export.py --since last
 
 # Incremental (only new/updated sessions since last run, using export state)

api/export_api.py

@@ -3,14 +3,17 @@
 import io
 import json
 import os
-import tempfile
-import threading
 import zipfile
-from contextlib import contextmanager
 from datetime import datetime
 
 from flask import Blueprint, current_app, jsonify, request, send_file
 
+from utils.export_state_store import (
+    EXPORT_STATE_FILE,
+    atomic_write_export_state,
+    export_state_lock,
+    load_export_state_from_disk,
+)
 from utils.session_path import (
     get_claude_projects_dir,
     list_projects,
@@ -24,64 +27,22 @@
 from utils.slugify import slugify
 from utils.export_day_filter import collect_sessions_for_latest_activity_day
 
-try:
-    import fcntl
-except ImportError:
-    fcntl = None  # Windows: fall back to threading lock (same process only)
-
 export_bp = Blueprint("export", __name__)
 
-_STATE_FILE = os.path.join(
-    os.path.expanduser("~"), ".claude-code-chat-browser", "export_state.json"
-)
-
-_fallback_lock = threading.Lock()
+# Tests monkeypatch this path; keep in sync with utils.export_state_store.
+_STATE_FILE = EXPORT_STATE_FILE
 
 
-@contextmanager
 def _state_lock():
-    """Serialize export_state.json reads/writes (POSIX: flock; else threading)."""
-    if fcntl is not None:
-        lock_path = _STATE_FILE + ".lock"
-        os.makedirs(os.path.dirname(lock_path), exist_ok=True)
-        lock_fp = open(lock_path, "a+")
-        try:
-            fcntl.flock(lock_fp.fileno(), fcntl.LOCK_EX)
-            yield
-        finally:
-            fcntl.flock(lock_fp.fileno(), fcntl.LOCK_UN)
-            lock_fp.close()
-    else:
-        with _fallback_lock:
-            yield
+    return export_state_lock(_STATE_FILE)
 
 
 def _load_state_from_disk() -> dict:
-    if os.path.exists(_STATE_FILE):
-        try:
-            with open(_STATE_FILE, encoding="utf-8") as f:
-                return json.load(f)
-        except Exception:
-            pass
-    return {}
+    return load_export_state_from_disk(_STATE_FILE)
 
 
 def _atomic_write_state(state: dict) -> None:
-    """Write state atomically (temp file + replace) under _state_lock."""
-    dir_name = os.path.dirname(_STATE_FILE) or "."
-    os.makedirs(dir_name, exist_ok=True)
-    fd, tmp_path = tempfile.mkstemp(dir=dir_name, suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            json.dump(state, f, indent=2)
-        os.replace(tmp_path, _STATE_FILE)
-    except BaseException:
-        try:
-            if os.path.exists(tmp_path):
-                os.unlink(tmp_path)
-        except OSError:
-            pass
-        raise
+    atomic_write_export_state(state, _STATE_FILE)
 
 
 def _read_state() -> dict:
@@ -115,10 +76,15 @@ def get_export_state():
 
 @export_bp.route("/api/export", methods=["POST"])
 def bulk_export():
-    body = request.get_json(silent=True) or {}
+    body = request.get_json(silent=True)
+    if body is None:
+        body = {}
+    if not isinstance(body, dict):
+        return jsonify({"error": "Invalid request body"}), 400
+
     since = body.get("since", "all")
     if since not in ("all", "last", "incremental"):
-        since = "all"
+        return jsonify({"error": "Invalid since mode", "since": since}), 400
 
     base = (
         current_app.config.get("CLAUDE_PROJECTS_DIR")

scripts/export.py

@@ -36,7 +36,11 @@
 )
 from utils.slugify import slugify
 from utils.export_day_filter import collect_sessions_for_latest_activity_day
-
+from utils.export_state_store import (
+    atomic_write_export_state,
+    export_state_lock,
+    load_export_state_from_disk,
+)
 
 STATE_DIR = os.path.join(os.path.expanduser("~"), ".claude-code-chat-browser")
 STATE_FILE = os.path.join(STATE_DIR, "export_state.json")
@@ -766,28 +770,28 @@ def _load_state() -> dict:
 
         {"<session-uuid>": <mtime-float>, ...}
     """
-    if not os.path.isfile(STATE_FILE):
-        return {}
-    with open(STATE_FILE, "r") as f:
-        data = json.load(f)
-    # Migrate: if the file has neither "sessions" nor "lastExportTime" it is
-    # the old flat dict of session_id → mtime.
-    if "sessions" not in data and "lastExportTime" not in data:
-        return {"sessions": data}
-    return data
+    with export_state_lock(STATE_FILE):
+        return load_export_state_from_disk(STATE_FILE)
 
 
 def _save_state(sessions: dict, count: int, out_dir: str):
-    """Persist export state with standardised fields matching cursor-chat-browser."""
-    os.makedirs(STATE_DIR, exist_ok=True)
-    state = {
-        "lastExportTime": datetime.now().isoformat(),
-        "exportedCount": count,
-        "exportDir": out_dir,
-        "sessions": sessions,
-    }
-    with open(STATE_FILE, "w") as f:
-        json.dump(state, f, indent=2)
+    """Persist export state with standardised fields matching cursor-chat-browser.
+
+    Merges ``sessions`` into any concurrent updates on disk (same lock/atomic
+    path as the web API).
+    """
+    with export_state_lock(STATE_FILE):
+        disk = load_export_state_from_disk(STATE_FILE)
+        disk["lastExportTime"] = datetime.now().isoformat()
+        disk["exportedCount"] = count
+        disk["exportDir"] = out_dir
+        base = disk.get("sessions")
+        if not isinstance(base, dict):
+            base = {}
+        merged = dict(base)
+        merged.update(sessions)
+        disk["sessions"] = merged
+        atomic_write_export_state(disk, STATE_FILE)
 
 
 def _die(msg: str):

tests/test_export_api_bulk.py

@@ -23,6 +23,34 @@ def isolated_state(tmp_path, monkeypatch):
     return path
 
 
+def test_bulk_export_invalid_since_returns_400(isolated_state, tmp_path):
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.config["CLAUDE_PROJECTS_DIR"] = str(tmp_path)
+    app.register_blueprint(export_bp)
+    client = app.test_client()
+    resp = client.post("/api/export", json={"since": "lst"})
+    assert resp.status_code == 400
+    body = resp.get_json()
+    assert body["error"] == "Invalid since mode"
+    assert body["since"] == "lst"
+
+
+def test_bulk_export_non_object_json_returns_400(isolated_state, tmp_path):
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.config["CLAUDE_PROJECTS_DIR"] = str(tmp_path)
+    app.register_blueprint(export_bp)
+    client = app.test_client()
+    resp = client.post(
+        "/api/export",
+        data=json.dumps(["all"]),
+        content_type="application/json",
+    )
+    assert resp.status_code == 400
+    assert resp.get_json()["error"] == "Invalid request body"
+
+
 def test_bulk_export_empty_returns_422_json(isolated_state, tmp_path):
     app = Flask(__name__)
     app.config["TESTING"] = True

tests/test_export_day_filter.py

@@ -1,7 +1,10 @@
 """Unit tests for utils/export_day_filter.py."""
 
+import logging
 from datetime import date
 
+import pytest
+
 from utils.export_day_filter import (
     collect_sessions_for_latest_activity_day,
     day_overlaps_session,
@@ -61,3 +64,58 @@ def parse_session(path):
     assert n == 2
     assert len(rows) == 1
     assert rows[0][2]["title"] == "One"
+
+
+def test_collect_latest_day_logs_parse_failure(caplog):
+    """Parse errors must be visible: they can change which day wins ``d = max(...)``."""
+
+    def list_sessions(path):
+        return [
+            {"id": "a", "path": "broken.jsonl", "modified": 0.0},
+            {"id": "b", "path": "good.jsonl", "modified": 0.0},
+        ]
+
+    def parse_session(path):
+        if path == "broken.jsonl":
+            raise ValueError("simulated corrupt jsonl")
+        return {
+            "title": "OK",
+            "metadata": {
+                "first_timestamp": "2026-04-05T10:00:00Z",
+                "last_timestamp": "2026-04-05T12:00:00Z",
+            },
+        }
+
+    projects = [{"name": "proj", "path": "/x", "display_name": "P"}]
+    with caplog.at_level(logging.ERROR, logger="utils.export_day_filter"):
+        d, rows, n = collect_sessions_for_latest_activity_day(
+            projects,
+            list_sessions=list_sessions,
+            parse_session=parse_session,
+            is_session_excluded=lambda *a, **k: False,
+            rules=[],
+        )
+    assert "broken.jsonl" in caplog.text
+    assert "simulated corrupt jsonl" in caplog.text
+    assert d == date(2026, 4, 5)
+    assert n == 2
+    assert len(rows) == 1
+
+
+def test_collect_latest_day_abort_on_parse_error():
+    def list_sessions(path):
+        return [{"id": "a", "path": "bad.jsonl", "modified": 0.0}]
+
+    def parse_session(path):
+        raise RuntimeError("fail fast")
+
+    projects = [{"name": "proj", "path": "/x", "display_name": "P"}]
+    with pytest.raises(RuntimeError, match="fail fast"):
+        collect_sessions_for_latest_activity_day(
+            projects,
+            list_sessions=list_sessions,
+            parse_session=parse_session,
+            is_session_excluded=lambda *a, **k: False,
+            rules=[],
+            abort_on_parse_error=True,
+        )

utils/export_day_filter.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import logging
 from datetime import date, datetime, timezone
 
+logger = logging.getLogger(__name__)
+
 
 def iso_timestamp_to_date(ts: str | None) -> date | None:
     """First 10 chars of an ISO timestamp as a UTC calendar date."""
@@ -46,12 +49,17 @@ def collect_sessions_for_latest_activity_day(
     parse_session,
     is_session_excluded,
     rules,
+    abort_on_parse_error: bool = False,
 ) -> tuple[date | None, list[tuple[dict, dict, dict, date, date]], int]:
     """Parse sessions in *projects*, skip untitled/excluded, return (D, rows, n_scanned).
 
-    *D* is the latest session **end** calendar date (UTC). Each row is
-    ``(project, sess_info, session, start_date, end_date)`` for sessions that
-    overlap *D*. *n_scanned* counts every ``.jsonl`` file visited.
+    *D* is the latest session **end** calendar date (UTC) from successfully
+    parsed sessions only (``d = max(...)`` over parsed rows). Parse failures are
+    logged and skipped unless *abort_on_parse_error* is true, in which case the
+    first failure is re-raised.
+
+    Each row is ``(project, sess_info, session, start_date, end_date)`` for
+    sessions that overlap *D*. *n_scanned* counts every ``.jsonl`` file visited.
     """
     parsed: list[tuple[dict, dict, dict, date, date]] = []
     total_scan = 0
@@ -60,7 +68,15 @@ def collect_sessions_for_latest_activity_day(
             total_scan += 1
             try:
                 session = parse_session(sess_info["path"])
-            except Exception:
+            except Exception as e:
+                logger.error(
+                    "Failed to parse session for latest-day selection %s: %s: %s",
+                    sess_info["path"],
+                    type(e).__name__,
+                    e,
+                )
+                if abort_on_parse_error:
+                    raise
                 continue
             if session["title"] == "Untitled Session":
                 continue