fix: distinct /api/search error codes and search UX polish

Author: clean6378-max-it

api/search.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import os
 from datetime import datetime, timezone
 from typing import Any
 
@@ -31,9 +32,14 @@
 
 _DEFAULT_LIMIT = 50
 _MAX_LIMIT = 500
+_MAX_QUERY_LEN = 500
 _MAX_SEARCH_SINCE_DAYS = 36_500
 
 
+class _SearchIndexUnavailable(Exception):
+    """Raised when the FTS index exists but is locked during rebuild."""
+
+
 def _parse_limit(raw: str | None, default: int = _DEFAULT_LIMIT) -> int:
     """Parse a positive integer limit from a query string value."""
     if raw is None or raw.strip() == "":
@@ -52,13 +58,23 @@ def _parse_since_days(raw: str | None) -> int | None:
         return None
     try:
         days = int(str(raw).strip())
-    except ValueError:
-        return None
+    except ValueError as exc:
+        raise ValueError("Invalid since_days: must be a positive integer") from exc
     if days <= 0:
-        return None
+        raise ValueError("Invalid since_days: must be a positive integer")
     return min(days, _MAX_SEARCH_SINCE_DAYS)
 
 
+def _projects_dir_available(projects_dir: str) -> bool:
+    try:
+        if not os.path.isdir(projects_dir):
+            return False
+        os.listdir(projects_dir)
+        return True
+    except OSError:
+        return False
+
+
 def _message_searchable_text(msg: MessageDict) -> str:
     text = msg.get("text", "") or msg.get("content", "")
     if not isinstance(text, str):
@@ -119,6 +135,8 @@ def _search_via_index(
             max_results=need,
             sql_offset=sql_offset,
         )
+        if indexed["index_locked"]:
+            raise _SearchIndexUnavailable()
         if not indexed["query_ok"]:
             return None
         if indexed["sql_rows_fetched"] == 0:
@@ -209,9 +227,20 @@ def _search_live_scan(
 
 @search_bp.route("/api/search")
 def search() -> FlaskReturn:
-    query = request.args.get("q", "").strip()
+    raw_query = request.args.get("q", "")
+    query = raw_query.strip()
     if not query:
-        return json_response([])
+        return error_response(
+            ErrorCode.SEARCH_EMPTY_QUERY,
+            "Search query is required",
+            400,
+        )
+    if len(query) > _MAX_QUERY_LEN:
+        return error_response(
+            ErrorCode.SEARCH_QUERY_TOO_LONG,
+            f"Search query must be at most {_MAX_QUERY_LEN} characters",
+            400,
+        )
 
     try:
         max_results = _parse_limit(request.args.get("limit"))
@@ -222,35 +251,66 @@ def search() -> FlaskReturn:
             400,
         )
 
+    since_days_raw = request.args.get("since_days")
+    try:
+        since_days = _parse_since_days(since_days_raw)
+    except ValueError:
+        return error_response(
+            ErrorCode.SEARCH_INVALID_SINCE_DAYS,
+            "Invalid since_days: must be a positive integer",
+            400,
+        )
+
     query_lower = query.lower()
     all_history = request.args.get("all_history") in ("1", "true")
     since_ms = resolve_search_since_ms(
         all_history=all_history,
-        since_days=_parse_since_days(request.args.get("since_days")),
+        since_days=since_days,
         now=datetime.now(timezone.utc),
     )
 
     base = current_app.config.get("CLAUDE_PROJECTS_DIR") or get_claude_projects_dir()
-    rules = current_app.config.get("EXCLUSION_RULES") or []
+    if not _projects_dir_available(base):
+        return error_response(
+            ErrorCode.SEARCH_PROJECTS_UNAVAILABLE,
+            "Claude projects directory is not accessible",
+            503,
+        )
 
-    indexed = _search_via_index(
-        base,
-        rules,
-        query,
-        query_lower,
-        since_ms=since_ms,
-        max_results=max_results,
-    )
-    if indexed is not None:
-        return json_response(indexed)
+    rules = current_app.config.get("EXCLUSION_RULES") or []
 
-    return json_response(
-        _search_live_scan(
+    try:
+        indexed = _search_via_index(
             base,
             rules,
             query,
             query_lower,
             since_ms=since_ms,
             max_results=max_results,
         )
-    )
+        if indexed is not None:
+            return json_response(indexed)
+
+        return json_response(
+            _search_live_scan(
+                base,
+                rules,
+                query,
+                query_lower,
+                since_ms=since_ms,
+                max_results=max_results,
+            )
+        )
+    except _SearchIndexUnavailable:
+        return error_response(
+            ErrorCode.SEARCH_INDEX_UNAVAILABLE,
+            "Search index is temporarily unavailable",
+            503,
+        )
+    except Exception:
+        _logger.exception("Unexpected error during search")
+        return error_response(
+            ErrorCode.INTERNAL_ERROR,
+            "Search failed",
+            500,
+        )

docs/api-reference.md

@@ -56,6 +56,11 @@ Extra fields may appear for specific codes (for example `since` on invalid bulk-
 | `code` | HTTP | Routes | Meaning |
 |--------|------|--------|---------|
 | `SEARCH_INVALID_LIMIT` | 400 | `GET /api/search` | Query param `limit` is not a positive integer |
+| `SEARCH_EMPTY_QUERY` | 400 | `GET /api/search` | Query param `q` is empty or whitespace |
+| `SEARCH_QUERY_TOO_LONG` | 400 | `GET /api/search` | Query param `q` exceeds 500 characters |
+| `SEARCH_INVALID_SINCE_DAYS` | 400 | `GET /api/search` | Query param `since_days` is not a positive integer |
+| `SEARCH_PROJECTS_UNAVAILABLE` | 503 | `GET /api/search` | Claude projects directory is missing or not readable |
+| `SEARCH_INDEX_UNAVAILABLE` | 503 | `GET /api/search` | FTS index is locked during rebuild |
 | `INVALID_PATH` | 400 | Session, stats, export session | Path traversal or rejected URL segment |
 | `SESSION_NOT_FOUND` | 404 | Session, stats, export session | File missing on disk or session excluded by rules |
 | `INVALID_REQUEST_BODY` | 400 | `POST /api/export` | Body is not a JSON object |
@@ -280,14 +285,18 @@ curl -s "http://127.0.0.1:5000/api/sessions/F--boost-capy/session_abc123/stats"
 
 **Source:** [`api/search.py`](../api/search.py)
 
-Case-insensitive substring search across all non-excluded messages in all projects. Linear scan — suitable for local history size, not indexed search.
+Case-insensitive substring search across all non-excluded messages in all projects. Uses a local FTS5 index when available; falls back to a live JSONL scan when the index is missing, stale, or the query cannot be served from SQLite.
 
 #### Query parameters
 
 | Name | Type | Default | Description |
 |------|------|---------|-------------|
-| `q` | string | `""` | Search string; whitespace stripped; empty → `[]` |
+| `q` | string | — | Search string (required); whitespace stripped; max 500 characters |
 | `limit` | integer | `50` | Max results; must be ≥ 1; **capped at 500** |
+| `all_history` | flag | off | When `1` or `true`, search all history (no time window) |
+| `since_days` | integer | `30` | When `all_history` is off, include messages from the last *N* days (positive integer; capped at 36 500) |
+
+By default, messages older than 30 days are excluded. Sessions without a parseable timestamp may still match when windowed.
 
 #### Response — `200 OK`
 
@@ -306,10 +315,17 @@ Case-insensitive substring search across all non-excluded messages in all projec
 
 | Status | `code` | When |
 |--------|--------|------|
+| 400 | `SEARCH_EMPTY_QUERY` | `q` is empty or whitespace |
+| 400 | `SEARCH_QUERY_TOO_LONG` | `q` exceeds 500 characters |
 | 400 | `SEARCH_INVALID_LIMIT` | `limit` not a positive integer (e.g. `abc`, `0`, `1.5`) |
+| 400 | `SEARCH_INVALID_SINCE_DAYS` | `since_days` not a positive integer |
+| 503 | `SEARCH_PROJECTS_UNAVAILABLE` | Projects directory missing or not readable |
+| 503 | `SEARCH_INDEX_UNAVAILABLE` | FTS index locked during rebuild |
+| 500 | `INTERNAL_ERROR` | Unexpected server failure |
 
 ```bash
 curl -s "http://127.0.0.1:5000/api/search?q=parser&limit=10" | jq '.[0]'
+curl -s "http://127.0.0.1:5000/api/search?q="   # → 400 SEARCH_EMPTY_QUERY
 curl -s "http://127.0.0.1:5000/api/search?q=test&limit=abc"   # → 400
 ```
 

models/error_codes.py

@@ -7,6 +7,11 @@
 
 class ErrorCode(StrEnum):
     SEARCH_INVALID_LIMIT = "SEARCH_INVALID_LIMIT"
+    SEARCH_EMPTY_QUERY = "SEARCH_EMPTY_QUERY"
+    SEARCH_QUERY_TOO_LONG = "SEARCH_QUERY_TOO_LONG"
+    SEARCH_INVALID_SINCE_DAYS = "SEARCH_INVALID_SINCE_DAYS"
+    SEARCH_PROJECTS_UNAVAILABLE = "SEARCH_PROJECTS_UNAVAILABLE"
+    SEARCH_INDEX_UNAVAILABLE = "SEARCH_INDEX_UNAVAILABLE"
     INVALID_PATH = "INVALID_PATH"
     SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
     INVALID_REQUEST_BODY = "INVALID_REQUEST_BODY"

static/js/search.js

@@ -6,8 +6,26 @@ import { showProjects } from './projects.js';
 
 // ==================== Search ====================
 
+const SEARCH_LIMIT = 50;
+
 let lastSearchRequestId = 0;
 
+export function highlightSnippet(snippet, query) {
+    if (!snippet) return '';
+    if (!query) return esc(snippet);
+    const hay = snippet.toLowerCase();
+    const needle = query.toLowerCase();
+    const idx = hay.indexOf(needle);
+    if (idx < 0) return esc(snippet);
+    return (
+        esc(snippet.slice(0, idx))
+        + '<mark>'
+        + esc(snippet.slice(idx, idx + query.length))
+        + '</mark>'
+        + esc(snippet.slice(idx + query.length))
+    );
+}
+
 export function showSearchPage() {
     setHamburgerVisible(false);
     setWorkspaceMode(false);
@@ -21,6 +39,14 @@ export function showSearchPage() {
             </a>
             <br><br>
             <h1>Search</h1>
+            <p class="text-muted text-sm search-help">
+                By default, search covers the last 30 days. Chats without a parseable date may still appear.
+                Results are capped at ${SEARCH_LIMIT} (up to 500 via the API). Check
+                <label class="search-all-history-label">
+                    <input type="checkbox" id="search-all-history"> Search all history
+                </label>
+                to include older messages.
+            </p>
             <div class="search-bar">
                 <input class="input" type="text" id="search-input" placeholder="Search conversations..." autofocus>
                 <button type="button" class="btn btn-primary" id="search-submit-btn">Search</button>
@@ -54,36 +80,57 @@ export async function doSearch() {
     const query = input.value.trim();
     if (!query) return;
 
+    const allHistory = document.getElementById('search-all-history')?.checked;
     const container = document.getElementById('search-results');
-    container.innerHTML = '<div class="loading">Searching...</div>';
+    container.innerHTML = '<div class="search-loading">Searching...</div>';
+
+    const params = new URLSearchParams({
+        q: query,
+        limit: String(SEARCH_LIMIT),
+    });
+    if (allHistory) params.set('all_history', '1');
 
     try {
-        const res = await fetch(`/api/search?q=${encodeURIComponent(query)}&limit=50`);
+        const res = await fetch(`/api/search?${params.toString()}`);
         if (localRequestId !== lastSearchRequestId) return;
         if (!res.ok) {
-            let msg = `Search failed (${res.status})`;
-            try { msg = await res.text() || msg; } catch { /* ignore */ }
+            let message = `Search failed (${res.status})`;
+            let code = '';
+            try {
+                const body = await res.json();
+                if (body && typeof body.error === 'string') message = body.error;
+                if (body && typeof body.code === 'string') code = body.code;
+            } catch {
+                try { message = await res.text() || message; } catch { /* ignore */ }
+            }
             if (localRequestId !== lastSearchRequestId) return;
-            throw new Error(msg);
+            const codeAttr = code ? ` data-error-code="${esc(code)}"` : '';
+            container.innerHTML = `<p class="search-error"${codeAttr}>${esc(message)}</p>`;
+            return;
         }
         const results = await res.json();
         if (localRequestId !== lastSearchRequestId) return;
 
-        let html = `<p class="text-muted text-sm">${results.length} result${results.length !== 1 ? 's' : ''}</p><br>`;
+        let html = `<p class="text-muted text-sm">${results.length} result${results.length !== 1 ? 's' : ''}</p>`;
+        if (results.length >= SEARCH_LIMIT) {
+            html += `<p class="text-muted text-sm search-truncation">Showing the first ${SEARCH_LIMIT} matches. Narrow your query or raise <code>limit</code> in the API for more.</p>`;
+        }
         html += '<div class="search-results">';
 
         for (const r of results) {
             html += `<div class="search-result" data-project="${esc(r.project)}" data-session-id="${esc(r.session_id)}">
                 <div><strong>${esc(r.title)}</strong> <span class="text-muted text-sm">${esc(r.project)} &bull; ${esc(r.role)}</span></div>
-                <div class="snippet">...${esc(r.snippet)}...</div>
+                <div class="snippet">...${highlightSnippet(r.snippet, query)}...</div>
             </div>`;
         }
 
-        if (!results.length) html += '<div class="empty-state">No results found.</div>';
+        if (!results.length) {
+            html += '<div class="search-empty">No results found.</div>';
+        }
         html += '</div>';
         smoothSet(container, html);
     } catch (e) {
         if (localRequestId !== lastSearchRequestId) return;
-        container.innerHTML = `<div class="loading">Error: ${esc(e.message)}</div>`;
+        container.innerHTML = `<p class="search-error">${esc(e.message)}</p>`;
     }
 }