test: HTTP/CLI route matrix and structured API error codes

- Add ErrorCode enum and error_response() helper; migrate api/search,
  api/sessions, and api/export_api error paths to include stable "code"
- Validate search limit query param (400 SEARCH_INVALID_LIMIT; cap at 500)
- Add tests/conftest.py, fixtures, test_api_routes, test_cli_e2e,
  test_error_codes, test_search; extend test_export_api_bulk for codes
- Document error code catalog in README

Author: clean6378-max-it

README.md

@@ -19,7 +19,22 @@ 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** with JSON body `{"error": "Nothing to export", "since": "<mode>"}` (the `since` field echoes your request: `"all"`, `"last"`, or `"incremental"`) 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", "code": "EXPORT_NOTHING_TO_EXPORT", "since": "<mode>"}` (the `since` field echoes your request: `"all"`, `"last"`, or `"incremental"`) instead of an empty zip
+
+### API error codes
+
+JSON error responses include a machine-readable `"code"` (stable `UPPER_SNAKE_CASE`) and a human-readable `"error"` message. Common codes:
+
+| Code | Typical HTTP | Meaning |
+|------|--------------|---------|
+| `SEARCH_INVALID_LIMIT` | 400 | Query param `limit` is not a positive integer |
+| `INVALID_PATH` | 400 | Path traversal or unsafe project/session path |
+| `SESSION_NOT_FOUND` | 404 | Session file missing or excluded |
+| `INVALID_REQUEST_BODY` | 400 | POST body is not a JSON object |
+| `INVALID_SINCE_MODE` | 400 | Bulk export `since` is not `all`, `last`, or `incremental` |
+| `EXPORT_NOTHING_TO_EXPORT` | 422 | No sessions matched the export scope |
+| `PARSE_ERROR` | 500 | Session file could not be parsed |
+| `INTERNAL_ERROR` | 500 | Unexpected failure (e.g. stats computation) |
 
 ### CLI Export
 - Standalone script to export all sessions to Markdown with YAML frontmatter

api/error_codes.py

@@ -0,0 +1,29 @@
+"""Stable machine-readable error codes for API JSON error responses."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from flask import Response, jsonify
+
+
+class ErrorCode(StrEnum):
+    SEARCH_INVALID_LIMIT = "SEARCH_INVALID_LIMIT"
+    INVALID_PATH = "INVALID_PATH"
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
+    INVALID_REQUEST_BODY = "INVALID_REQUEST_BODY"
+    INVALID_SINCE_MODE = "INVALID_SINCE_MODE"
+    PARSE_ERROR = "PARSE_ERROR"
+    EXPORT_NOTHING_TO_EXPORT = "EXPORT_NOTHING_TO_EXPORT"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+def error_response(
+    code: ErrorCode,
+    message: str,
+    status: int,
+    **extra: object,
+) -> tuple[Response, int]:
+    body: dict[str, object] = {"error": message, "code": str(code)}
+    body.update(extra)
+    return jsonify(body), status

api/export_api.py

@@ -8,6 +8,7 @@
 
 from flask import Blueprint, current_app, jsonify, request, send_file
 
+from api.error_codes import ErrorCode, error_response
 from utils.export_state_store import (
     EXPORT_STATE_FILE,
     atomic_write_export_state,
@@ -80,11 +81,20 @@ def bulk_export():
     if body is None:
         body = {}
     if not isinstance(body, dict):
-        return jsonify({"error": "Invalid request body"}), 400
+        return error_response(
+            ErrorCode.INVALID_REQUEST_BODY,
+            "Invalid request body",
+            400,
+        )
 
     since = body.get("since", "all")
     if since not in ("all", "last", "incremental"):
-        return jsonify({"error": "Invalid since mode", "since": since}), 400
+        return error_response(
+            ErrorCode.INVALID_SINCE_MODE,
+            "Invalid since mode",
+            400,
+            since=since,
+        )
 
     base = (
         current_app.config.get("CLAUDE_PROJECTS_DIR")
@@ -226,14 +236,11 @@ def bulk_export():
         _write_state(new_sessions_map, count)
 
     if count == 0:
-        return (
-            jsonify(
-                {
-                    "error": "Nothing to export",
-                    "since": since,
-                }
-            ),
+        return error_response(
+            ErrorCode.EXPORT_NOTHING_TO_EXPORT,
+            "Nothing to export",
             422,
+            since=since,
         )
 
     buf.seek(0)
@@ -267,16 +274,24 @@ def export_session(project_name, session_id):
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return jsonify({"error": "Invalid path"}), 400
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return jsonify({"error": "Session not found"}), 404
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            "Session not found",
+            404,
+        )
 
     fmt = request.args.get("format", "md")
     session = parse_session(filepath)
     rules = current_app.config.get("EXCLUSION_RULES") or []
     if is_session_excluded(rules, session, project_name):
-        return jsonify({"error": "Session not found"}), 404
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            "Session not found",
+            404,
+        )
     stats = compute_stats(session)
     title_slug = slugify(session["title"], default="session")
 

api/search.py

@@ -4,6 +4,7 @@
 
 from flask import Blueprint, current_app, jsonify, request
 
+from api.error_codes import ErrorCode, error_response
 from utils.session_path import get_claude_projects_dir, list_projects, list_sessions
 from utils.jsonl_parser import parse_session
 from utils.exclusion_rules import is_session_excluded
@@ -36,7 +37,12 @@ def search():
     try:
         max_results = _parse_limit(request.args.get("limit"))
     except ValueError:
-        return jsonify({"error": "Invalid limit: must be a positive integer"}), 400
+        return error_response(
+            ErrorCode.SEARCH_INVALID_LIMIT,
+            "Invalid limit: must be a positive integer",
+            400,
+        )
+
     base = current_app.config.get("CLAUDE_PROJECTS_DIR") or get_claude_projects_dir()
     projects = list_projects(base)
 
@@ -58,7 +64,6 @@ def search():
             for msg in session["messages"]:
                 text = msg.get("text", "") or msg.get("content", "")
                 if query in text.lower():
-                    # Find the matching snippet
                     idx = text.lower().index(query)
                     start = max(0, idx - 80)
                     end = min(len(text), idx + len(query) + 80)

api/sessions.py

@@ -2,8 +2,9 @@
 
 import os
 
-from flask import Blueprint, current_app, jsonify, abort
+from flask import Blueprint, current_app, jsonify
 
+from api.error_codes import ErrorCode, error_response
 from utils.session_path import get_claude_projects_dir, safe_join
 from utils.jsonl_parser import parse_session
 from utils.session_stats import compute_stats
@@ -18,25 +19,32 @@ def get_session(project_name, session_id):
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return jsonify({"error": "Invalid path"}), 400
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return jsonify({"error": f"Session {session_id} not found"}), 404
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            f"Session {session_id} not found",
+            404,
+        )
 
     try:
         session = parse_session(filepath)
         rules = current_app.config.get("EXCLUSION_RULES") or []
         if is_session_excluded(rules, session, project_name):
-            return jsonify({"error": "Session not found"}), 404
+            return error_response(
+                ErrorCode.SESSION_NOT_FOUND,
+                "Session not found",
+                404,
+            )
         return jsonify(session)
     except Exception:
-        # Full traceback (class name, message, stack) goes to the server log
-        # via logger.exception. The HTTP body returns a stable, generic
-        # message — never the class name or `e` itself, which would leak
-        # internal field names, file paths, and user values to any client
-        # (issue #25).
         current_app.logger.exception("Failed to parse session %s", session_id)
-        return jsonify({"error": "Failed to parse session"}), 500
+        return error_response(
+            ErrorCode.PARSE_ERROR,
+            "Failed to parse session",
+            500,
+        )
 
 
 @sessions_bp.route("/api/sessions/<path:project_name>/<session_id>/stats")
@@ -45,17 +53,23 @@ def get_session_stats(project_name, session_id):
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return jsonify({"error": "Invalid path"}), 400
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return jsonify({"error": f"Session {session_id} not found"}), 404
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            f"Session {session_id} not found",
+            404,
+        )
 
     try:
         session = parse_session(filepath)
         stats = compute_stats(session)
         return jsonify(stats)
     except Exception:
-        # Same pattern as get_session above — full detail to the server log,
-        # generic message in the HTTP body (issue #25).
         current_app.logger.exception("Failed to compute stats for %s", session_id)
-        return jsonify({"error": "Failed to compute session stats"}), 500
+        return error_response(
+            ErrorCode.INTERNAL_ERROR,
+            "Failed to compute session stats",
+            500,
+        )

tests/conftest.py

@@ -12,8 +12,28 @@
 FIXTURES = Path(__file__).parent / "fixtures"
 
 
+def assert_error_response(resp, *, expected_code: str | None = None):
+    """Assert JSON error body has error + code; optionally match code string."""
+    assert resp.status_code >= 400
+    body = resp.get_json()
+    assert body is not None
+    assert "error" in body
+    assert isinstance(body["error"], str)
+    assert "code" in body
+    if expected_code is not None:
+        assert body["code"] == expected_code
+
+
+@pytest.fixture
+def export_state_file(tmp_path, monkeypatch):
+    """Isolate export state JSON to tmp_path for full-app export tests."""
+    path = tmp_path / "export_state.json"
+    monkeypatch.setattr("api.export_api._STATE_FILE", str(path))
+    return path
+
+
 @pytest.fixture
-def client(tmp_path):
+def client(tmp_path, export_state_file):
     """Flask test client with two seeded sessions in 'test-project'."""
     project_dir = tmp_path / "test-project"
     project_dir.mkdir(parents=True)
@@ -25,7 +45,7 @@ def client(tmp_path):
 
 
 @pytest.fixture
-def client_single(tmp_path):
+def client_single(tmp_path, export_state_file):
     """Flask test client with one seeded session — for search/limit tests."""
     project_dir = tmp_path / "test-project"
     project_dir.mkdir(parents=True)
@@ -36,15 +56,15 @@ def client_single(tmp_path):
 
 
 @pytest.fixture
-def client_empty(tmp_path):
+def client_empty(tmp_path, export_state_file):
     """Flask test client with an empty projects directory."""
     app = create_app(base_dir=str(tmp_path))
     app.config["TESTING"] = True
     return app.test_client()
 
 
 @pytest.fixture
-def client_thinking(tmp_path):
+def client_thinking(tmp_path, export_state_file):
     """Flask test client with a session containing thinking content blocks."""
     project_dir = tmp_path / "test-project"
     project_dir.mkdir(parents=True)

tests/test_api_integration.py

@@ -10,11 +10,7 @@
 from __future__ import annotations
 
 
-def _assert_error_shape(resp):
-    body = resp.get_json()
-    assert body is not None
-    assert "error" in body
-    # Wednesday will add "code" field — uncomment after structured error codes land.
+from tests.conftest import assert_error_response as _assert_error_shape
 
 
 # --- /api/projects ---