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,32 @@
+"""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": code}
+    reserved = frozenset({"error", "code"})
+    for key, value in extra.items():
+        if key not in reserved:
+            body[key] = value
+    return jsonify(body), status

api/export_api.py

@@ -9,9 +9,9 @@
 
 from flask import Blueprint, current_app, request, send_file
 
-from api._flask_types import FlaskReturn, json_error, json_response
+from api._flask_types import FlaskReturn, json_response
+from api.error_codes import ErrorCode, error_response
 from models.export import ExportStateDict
-
 from utils.export_state_store import (
     EXPORT_STATE_FILE,
     atomic_write_export_state,
@@ -84,11 +84,20 @@ def bulk_export() -> FlaskReturn:
     if body is None:
         body = {}
     if not isinstance(body, dict):
-        return json_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 json_error({"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,11 +235,15 @@ def bulk_export() -> FlaskReturn:
             )
             zf.writestr("manifest.jsonl", manifest_str)
 
-    if count > 0:
-        _write_state(new_sessions_map, count)
-
     if count == 0:
-        return json_error({"error": "Nothing to export", "since": since}, 422)
+        return error_response(
+            ErrorCode.EXPORT_NOTHING_TO_EXPORT,
+            "Nothing to export",
+            422,
+            since=since,
+        )
+
+    _write_state(new_sessions_map, count)
 
     buf.seek(0)
     date_tag = datetime.now().strftime("%Y-%m-%d")
@@ -253,7 +266,6 @@ def bulk_export() -> FlaskReturn:
 
 @export_bp.route("/api/export/session/<path:project_name>/<session_id>")
 def export_session(project_name: str, session_id: str) -> FlaskReturn:
-    import os
     from utils.session_path import safe_join
 
     base = (
@@ -263,42 +275,67 @@ def export_session(project_name: str, session_id: str) -> FlaskReturn:
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return json_error("Invalid path", 400)
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return json_error("Session not found", 404)
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            "Session not found",
+            404,
+        )
 
     fmt = request.args.get("format", "md")
     try:
         session = parse_session(filepath)
-        rules = current_app.config.get("EXCLUSION_RULES") or []
-        if is_session_excluded(rules, session, project_name):
-            return json_error("Session not found", 404)
+    except Exception:
+        current_app.logger.exception(
+            "Failed to parse session %s for export", session_id
+        )
+        return error_response(
+            ErrorCode.PARSE_ERROR,
+            "Failed to parse session",
+            500,
+        )
+
+    rules = current_app.config.get("EXCLUSION_RULES") or []
+    if is_session_excluded(rules, session, project_name):
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            "Session not found",
+            404,
+        )
+
+    try:
         stats = compute_stats(session)
-        title_slug = slugify(session["title"], default="session")
-
-        if fmt == "json":
-            content = session_to_json(session, stats)
-            buf = io.BytesIO(content.encode("utf-8"))
-            buf.seek(0)
-            return send_file(
-                buf,
-                mimetype="application/json",
-                as_attachment=True,
-                download_name=f"{title_slug}.json",  # type: ignore[call-arg]
-            )
+    except Exception:
+        current_app.logger.exception(
+            "Failed to compute stats for export %s", session_id
+        )
+        return error_response(
+            ErrorCode.INTERNAL_ERROR,
+            "Failed to compute session stats",
+            500,
+        )
+
+    title_slug = slugify(session["title"], default="session")
 
-        md = session_to_markdown(session, stats)
-        buf = io.BytesIO(md.encode("utf-8"))
+    if fmt == "json":
+        content = session_to_json(session, stats)
+        buf = io.BytesIO(content.encode("utf-8"))
         buf.seek(0)
         return send_file(
             buf,
-            mimetype="text/markdown",
+            mimetype="application/json",
             as_attachment=True,
-            download_name=f"{title_slug}.md",  # type: ignore[call-arg]
+            download_name=f"{title_slug}.json",  # type: ignore[call-arg]
         )
-    except Exception:
-        current_app.logger.exception(
-            "Failed to export session %s/%s", project_name, session_id
-        )
-        return json_error("Internal server error exporting session", 500)
+
+    md = session_to_markdown(session, stats)
+    buf = io.BytesIO(md.encode("utf-8"))
+    buf.seek(0)
+    return send_file(
+        buf,
+        mimetype="text/markdown",
+        as_attachment=True,
+        download_name=f"{title_slug}.md",  # type: ignore[call-arg]
+    )

api/search.py

@@ -2,9 +2,10 @@
 
 import os
 
-from flask import Blueprint, current_app, jsonify, request
+from flask import Blueprint, current_app, request
 
-from api._flask_types import FlaskReturn, json_error, json_response
+from api._flask_types import FlaskReturn, json_response
+from api.error_codes import ErrorCode, error_response
 from models.search import SearchHitDict
 from utils.session_path import get_claude_projects_dir, list_projects, list_sessions
 from utils.jsonl_parser import parse_session
@@ -37,8 +38,13 @@ def search() -> FlaskReturn:
 
     try:
         max_results = _parse_limit(request.args.get("limit"))
-    except ValueError as e:
-        return json_error(str(e), 400)
+    except ValueError:
+        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)
 
@@ -60,7 +66,6 @@ def search() -> FlaskReturn:
             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

@@ -4,8 +4,8 @@
 
 from flask import Blueprint, current_app
 
-from api._flask_types import FlaskReturn, json_error, json_response
-
+from api._flask_types import FlaskReturn, json_response
+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
@@ -20,25 +20,32 @@ def get_session(project_name: str, session_id: str) -> FlaskReturn:
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return json_error("Invalid path", 400)
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return json_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 json_error("Session not found", 404)
+            return error_response(
+                ErrorCode.SESSION_NOT_FOUND,
+                "Session not found",
+                404,
+            )
         return json_response(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 json_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")
@@ -47,20 +54,40 @@ def get_session_stats(project_name: str, session_id: str) -> FlaskReturn:
     try:
         filepath = safe_join(base, project_name, f"{session_id}.jsonl")
     except ValueError:
-        return json_error("Invalid path", 400)
+        return error_response(ErrorCode.INVALID_PATH, "Invalid path", 400)
 
     if not os.path.isfile(filepath):
-        return json_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 json_error("Session not found", 404)
+    except Exception:
+        current_app.logger.exception("Failed to parse session %s", session_id)
+        return error_response(
+            ErrorCode.PARSE_ERROR,
+            "Failed to parse session",
+            500,
+        )
+
+    rules = current_app.config.get("EXCLUSION_RULES") or []
+    if is_session_excluded(rules, session, project_name):
+        return error_response(
+            ErrorCode.SESSION_NOT_FOUND,
+            "Session not found",
+            404,
+        )
+
+    try:
         stats = compute_stats(session)
         return json_response(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 json_error("Failed to compute session stats", 500)
+        return error_response(
+            ErrorCode.INTERNAL_ERROR,
+            "Failed to compute session stats",
+            500,
+        )