fix(#117): address PR #126 review feedback on search UX and errors

Author: clean6378-max-it

api/search.py

@@ -105,11 +105,13 @@ def search() -> tuple[Response, int] | Response:
     Args:
         q: Search query string (required; 400 when empty).
         type: Filter scope — ``all`` (default), ``chat``, or ``composer``.
-        workspace: Optional workspace folder hash; 404 when unknown.
+        workspace: Optional workspace folder hash; 404 when unknown (bonus API
+            filter — not exposed in the search UI).
 
     Returns:
         JSON ``{"results": [...]}`` with optional ``warnings``. Structured
-        ``{"error", "code"}`` bodies for 400/404/503/500 failures.
+        ``{"error", "code"}`` bodies for 400/404/503/500 failures. Error
+        responses omit ``results`` (breaking change vs. legacy 500 bodies).
     """
     query = request.args.get("q", "").strip()
     if not query:
@@ -203,7 +205,13 @@ def search() -> tuple[Response, int] | Response:
             "search_index_unavailable",
             503,
         )
+    except OSError:
+        _logger.exception("Workspace storage unavailable")
+        return _search_error(
+            "Workspace storage is temporarily unavailable",
+            "storage_unavailable",
+            503,
+        )
     except Exception:
         _logger.exception("Search failed")
         return _search_error("Search failed", "internal_error", 500)
-

templates/search.html

@@ -18,6 +18,7 @@ <h1>Search</h1>
         type="button"
         class="search-info-tooltip"
         id="search-window-help"
+        aria-label="Search window help"
         aria-describedby="search-window-help-text"
       >
         <span class="search-info-icon" aria-hidden="true">i</span>
@@ -112,7 +113,10 @@ <h1>Search</h1>
       showIncompleteResultsBanner('parse-warnings-host', []);
       loading.style.display = 'none';
       const message = typeof data.error === 'string' ? data.error : 'Search failed.';
-      container.innerHTML = `<p class="text-danger">${escapeHtml(message)}</p>`;
+      const codeAttr = typeof data.code === 'string'
+        ? ` data-error-code="${escapeHtml(data.code)}"`
+        : '';
+      container.innerHTML = `<p class="text-danger"${codeAttr}>${escapeHtml(message)}</p>`;
       return;
     }
     const results = data.results || [];
@@ -122,7 +126,7 @@ <h1>Search</h1>
     countEl.style.display = 'block';
     const windowNote = data.allHistory
       ? ' (all history)'
-      : ` (last ${data.searchWindowDays || 30} days)`;
+      : ` (last ${data.searchWindowDays || 30} days; undated chats included)`;
     countEl.textContent = `Found ${results.length} results for "${query}"${windowNote}`;
 
     let html = '';

tests/test_api_search.py

@@ -110,14 +110,14 @@ def test_index_lock_returns_503(self, client):
         _assert_error_body(body, code="search_index_unavailable")
         assert "results" not in body
 
-    def test_workspace_path_resolution_failure_returns_structured_500(self, client):
+    def test_workspace_path_resolution_failure_returns_structured_503(self, client):
         with patch(
             "api.search.resolve_workspace_path",
             side_effect=OSError("simulated storage discovery failure"),
         ):
             response = client.get("/api/search?q=sentinel-grep&all_history=1")
-        assert response.status_code == 500
-        _assert_error_body(response.get_json(), code="internal_error")
+        assert response.status_code == 503
+        _assert_error_body(response.get_json(), code="storage_unavailable")
 
 
 class TestSearchEdgeCases: