Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript
135 KB
Raw Blame
use std::collections::{BTreeMap, BTreeSet, HashMap, VecDeque};
use std::fs;
use std::hash::{DefaultHasher, Hash, Hasher};
use std::io::{Cursor, Read};
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicU8, AtomicUsize, Ordering};
use std::sync::mpsc::{self, Receiver, SyncSender};
use std::sync::{Arc, Mutex, OnceLock};
use std::thread;
use std::time::{Duration, Instant};

use futures::FutureExt;
use serde::{Deserialize, Serialize};
use serde_json::{json, Map, Value};
use tauri::{AppHandle, Manager};
use tiny_http::{Header, Method, Response, Server, StatusCode};
use uuid::Uuid;
use walkdir::WalkDir;

use crate::cors::{local_cors_headers, request_origin};
use crate::{agent, clip_server, commands, server_bind};

const PORT: u16 = 19828;
const API_PREFIX: &str = "/api/v1";
const MAX_BODY_BYTES: usize = 1024 * 1024;
const MAX_CHAT_BODY_BYTES: usize = 40 * 1024 * 1024;
// JSON may encode one input byte as a six-byte `\u00XX` escape. Keep the
// transport boundary above the authoritative 2 MiB decoded-content limit.
const MAX_PAGE_WRITE_BODY_BYTES: usize = 6 * 2 * 1024 * 1024 + 16 * 1024;
const MAX_FILE_CONTENT_BYTES: u64 = 2 * 1024 * 1024;
const DEFAULT_MAX_FILES: usize = 2_000;
const HARD_MAX_FILES: usize = 10_000;
const DEFAULT_MAX_REVIEWS: usize = 200;
const HARD_MAX_REVIEWS: usize = 1_000;
const MAX_SEARCH_RESULTS: usize = 50;
const BIND_RETRY_DELAY_SECS: u64 = 2;
const MAX_BIND_RETRIES: u32 = 3;
const APP_STATE_CACHE_TTL: Duration = Duration::from_secs(5);
const RATE_LIMIT_WINDOW: Duration = Duration::from_secs(1);
const RATE_LIMIT_MAX_REQUESTS: usize = 120;
const MAX_IN_FLIGHT_REQUESTS: usize = 64;
const MAX_IN_FLIGHT_CHAT_STREAMS: usize = 8;
const MAX_IN_FLIGHT_PAGE_EMBEDS: usize = 4;
const SSE_QUEUE_CAPACITY: usize = 64;
const SSE_HEARTBEAT_INTERVAL: Duration = Duration::from_secs(10);
const GRAPH_CACHE_TTL: Duration = Duration::from_secs(5);
const GRAPH_CACHE_MAX_PROJECTS: usize = 8;

/// API status: 0=starting, 1=running, 2=port_conflict, 3=error
static API_STATUS: AtomicU8 = AtomicU8::new(0);
static IN_FLIGHT_REQUESTS: AtomicUsize = AtomicUsize::new(0);
static IN_FLIGHT_CHAT_STREAMS: AtomicUsize = AtomicUsize::new(0);
static IN_FLIGHT_PAGE_EMBEDS: AtomicUsize = AtomicUsize::new(0);
static APP_STATE_CACHE: OnceLock<Mutex<Option<CachedAppState>>> = OnceLock::new();
static RATE_LIMIT: OnceLock<Mutex<VecDeque<Instant>>> = OnceLock::new();
static GRAPH_CACHE: OnceLock<Mutex<HashMap<String, Arc<CachedGraph>>>> = OnceLock::new();

#[derive(Clone)]
struct CachedAppState {
    loaded_at: Instant,
    value: Option<Value>,
}

#[derive(Clone)]
struct CachedGraph {
    loaded_at: Instant,
    fingerprint: u64,
    nodes: Vec<ApiGraphNode>,
    edges: Vec<ApiGraphEdge>,
}

pub fn get_api_status() -> &'static str {
    match API_STATUS.load(Ordering::Relaxed) {
        0 => "starting",
        1 => "running",
        2 => "port_conflict",
        _ => "error",
    }
}

pub fn invalidate_config_cache() {
    if let Some(lock) = APP_STATE_CACHE.get() {
        if let Ok(mut cache) = lock.lock() {
            *cache = None;
        }
    }
}

pub fn start_api_server(app: AppHandle) {
    thread::spawn(move || loop {
        API_STATUS.store(0, Ordering::Relaxed);
        let (server, addr) = match bind_server_with_retry(&app) {
            Some(bound) => bound,
            None => {
                API_STATUS.store(2, Ordering::Relaxed);
                thread::sleep(Duration::from_secs(BIND_RETRY_DELAY_SECS));
                continue;
            }
        };

        API_STATUS.store(1, Ordering::Relaxed);
        eprintln!("[API Server] Listening on http://{addr}{API_PREFIX}");

        for request in server.incoming_requests() {
            let method = request.method().clone();
            let url = request.url().to_string();
            let origin = request_origin(&request);
            if should_rate_limit(&method, &url) && !allow_request() {
                respond_error(request, 429, "Too many requests", origin.as_deref());
                continue;
            }
            let Some(slot) = try_acquire_request_slot() else {
                respond_error(request, 503, "API server is busy", origin.as_deref());
                continue;
            };
            let app = app.clone();
            thread::spawn(move || {
                let _slot = slot;
                let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
                    process_request(app, request);
                }));
                if let Err(payload) = result {
                    eprintln!("[API Server] request handler panicked: {payload:?}");
                }
            });
        }

        API_STATUS.store(3, Ordering::Relaxed);
        eprintln!("[API Server] server loop exited; restarting");
        thread::sleep(Duration::from_secs(BIND_RETRY_DELAY_SECS));
    });
}

fn bind_server_with_retry(app: &AppHandle) -> Option<(Server, String)> {
    let host = server_bind::configured_bind_host(app);
    let addr = server_bind::bind_addr(&host, PORT);
    for attempt in 1..=MAX_BIND_RETRIES {
        match Server::http(&addr) {
            Ok(server) => return Some((server, addr)),
            Err(err) => {
                eprintln!(
                    "[API Server] Failed to bind {addr} (attempt {attempt}/{MAX_BIND_RETRIES}): {err}"
                );
                if attempt < MAX_BIND_RETRIES {
                    thread::sleep(Duration::from_secs(BIND_RETRY_DELAY_SECS));
                }
            }
        }
    }
    None
}

struct RequestSlot;

impl Drop for RequestSlot {
    fn drop(&mut self) {
        IN_FLIGHT_REQUESTS.fetch_sub(1, Ordering::Relaxed);
    }
}

struct ChatStreamSlot;

impl Drop for ChatStreamSlot {
    fn drop(&mut self) {
        IN_FLIGHT_CHAT_STREAMS.fetch_sub(1, Ordering::Relaxed);
    }
}

fn try_acquire_chat_stream_slot() -> Option<ChatStreamSlot> {
    let mut current = IN_FLIGHT_CHAT_STREAMS.load(Ordering::Relaxed);
    loop {
        if current >= MAX_IN_FLIGHT_CHAT_STREAMS {
            return None;
        }
        match IN_FLIGHT_CHAT_STREAMS.compare_exchange_weak(
            current,
            current + 1,
            Ordering::Relaxed,
            Ordering::Relaxed,
        ) {
            Ok(_) => return Some(ChatStreamSlot),
            Err(next) => current = next,
        }
    }
}

fn try_acquire_request_slot() -> Option<RequestSlot> {
    let mut current = IN_FLIGHT_REQUESTS.load(Ordering::Relaxed);
    loop {
        if current >= MAX_IN_FLIGHT_REQUESTS {
            return None;
        }
        match IN_FLIGHT_REQUESTS.compare_exchange_weak(
            current,
            current + 1,
            Ordering::Relaxed,
            Ordering::Relaxed,
        ) {
            Ok(_) => return Some(RequestSlot),
            Err(next) => current = next,
        }
    }
}

fn process_request(app: AppHandle, mut request: tiny_http::Request) {
    let method = request.method().clone();
    let url = request.url().to_string();
    let origin = request_origin(&request);
    if method == Method::Options {
        respond_options(request, origin.as_deref());
        return;
    }

    let headers: Vec<(String, String)> = request
        .headers()
        .iter()
        .map(|header| {
            (
                header.field.as_str().to_ascii_lowercase().to_string(),
                header.value.as_str().to_string(),
            )
        })
        .collect();

    let body = match read_body(&mut request, body_limit_for_request(&method, &url)) {
        Ok(body) => body,
        Err(err) => {
            respond_error(request, 400, &err, origin.as_deref());
            return;
        }
    };

    let (path, query) = split_url(&url);
    if wants_streaming_chat(&method, &path, &body, &headers) {
        if !api_enabled(&app) {
            respond_error(
                request,
                503,
                "API server is disabled in Settings → API Server",
                origin.as_deref(),
            );
            return;
        }
        // Agent chat remains token-protected even when read-oriented API
        // endpoints are configured for unauthenticated local access.
        if !is_token_authorized(&app, query, &headers) {
            respond_error(request, 401, "Unauthorized", origin.as_deref());
            return;
        }
        let Some(project_id) = chat_project_id(&method, &path) else {
            respond_error(request, 404, "Not found", origin.as_deref());
            return;
        };
        let Some(stream_slot) = try_acquire_chat_stream_slot() else {
            respond_error(
                request,
                503,
                "Too many concurrent Agent chat streams",
                origin.as_deref(),
            );
            return;
        };
        respond_chat_sse(
            request,
            app,
            project_id,
            &body,
            origin.as_deref(),
            stream_slot,
        );
        return;
    }

    let response = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        handle_request(&app, &method, &url, &body, &headers)
    }))
    .unwrap_or_else(|payload| {
        eprintln!("[API Server] request panicked: {payload:?}");
        err(500, "Internal API server error")
    });
    respond_json(request, response.status, response.body, origin.as_deref());
}

struct ApiResponse {
    status: u16,
    body: Value,
}

fn ok(body: Value) -> ApiResponse {
    ApiResponse { status: 200, body }
}

fn err(status: u16, message: impl Into<String>) -> ApiResponse {
    ApiResponse {
        status,
        body: json!({ "ok": false, "error": message.into() }),
    }
}

fn handle_request(
    app: &AppHandle,
    method: &Method,
    url: &str,
    body: &str,
    headers: &[(String, String)],
) -> ApiResponse {
    let (path, query) = split_url(url);
    if path == "/health" || path == format!("{API_PREFIX}/health") {
        // /health stays reachable even when the user has disabled the
        // API in Settings — the desktop UI uses it to render the
        // "Enabled / disabled / port_conflict" line, and curl-from-
        // terminal users need a way to confirm the server is alive
        // before they go hunting for why other endpoints 503.
        return ok(json!({
            "ok": true,
            "status": get_api_status(),
            "version": env!("CARGO_PKG_VERSION"),
            "authRequired": api_auth_required(app),
            "authConfigured": api_token(app).is_some(),
            "tokenSource": api_token_source(app),
            "enabled": api_enabled(app),
            "mcpEnabled": api_mcp_enabled(app),
            "allowUnauthenticated": api_allow_unauthenticated(app),
            "allowLanAccess": api_allow_lan_access(app),
            "agent": {
                "chat": true,
                "streaming": true,
                "streamProtocol": "sse",
            },
        }));
    }
    if !path.starts_with(API_PREFIX) {
        return err(404, "Not found");
    }
    if !api_enabled(app) {
        // Kill-switch path: token may be configured and valid, but the
        // user toggled the API off in Settings → API Server. 503 is
        // the right code semantically ("temporarily unavailable")
        // and tells well-behaved clients to back off rather than
        // retry instantly the way 401 would.
        return err(503, "API server is disabled in Settings → API Server");
    }
    if is_token_required_request(&method, &path) && !is_token_authorized(app, query, headers) {
        return err(401, "Unauthorized");
    }
    if !is_authorized(app, query, headers) {
        return err(401, "Unauthorized");
    }
    if !matches!(
        method,
        &Method::Get | &Method::Post | &Method::Patch | &Method::Delete
    ) {
        return err(405, "Method not allowed");
    }

    let Some(parts) = api_path_parts(&path) else {
        return err(404, "Not found");
    };

    match (method, parts.as_slice()) {
        (&Method::Get, ["projects"]) => handle_projects(app),
        (&Method::Get, ["projects", project_id, "files"]) => handle_files(app, project_id, query),
        (&Method::Get, ["projects", project_id, "files", "content"]) => {
            handle_file_content(app, project_id, query)
        }
        (&Method::Get, ["projects", project_id, "reviews"]) => {
            handle_reviews(app, project_id, query)
        }
        (&Method::Post, ["projects", project_id, "reviews", "resolve"]) => {
            handle_bulk_resolve_reviews(app, project_id, body)
        }
        (&Method::Patch, ["projects", project_id, "reviews", review_id]) => {
            handle_patch_review(app, project_id, review_id, body)
        }
        (&Method::Delete, ["projects", project_id, "reviews", review_id]) => {
            handle_delete_review(app, project_id, review_id)
        }
        (&Method::Post, ["projects", project_id, "search"]) => handle_search(app, project_id, body),
        (&Method::Get, ["projects", project_id, "graph"]) => handle_graph(app, project_id, query),
        (&Method::Post, ["projects", project_id, "sources", "rescan"]) => {
            handle_rescan(app, project_id)
        }
        (&Method::Post, ["projects", project_id, "pages", "embed"]) => {
            handle_embed_page(app, project_id, body)
        }
        (&Method::Post, ["projects", project_id, "pages", "write"]) => {
            handle_write_page(app, project_id, body)
        }
        (&Method::Post, ["projects", project_id, "chat"]) => handle_chat(app, project_id, body),
        (&Method::Post, ["projects", project_id, "chat", session_id, "cancel"]) => {
            handle_cancel_chat(app, project_id, session_id)
        }
        _ => err(404, "Not found"),
    }
}

fn should_rate_limit(method: &Method, url: &str) -> bool {
    if method == &Method::Options {
        return false;
    }
    let (path, _) = split_url(url);
    !(path == "/health" || path == format!("{API_PREFIX}/health"))
}

fn allow_request() -> bool {
    let now = Instant::now();
    let window_start = now - RATE_LIMIT_WINDOW;
    let lock = RATE_LIMIT.get_or_init(|| Mutex::new(VecDeque::new()));
    let Ok(mut hits) = lock.lock() else {
        return false;
    };
    while hits.front().map(|t| *t < window_start).unwrap_or(false) {
        hits.pop_front();
    }
    if hits.len() >= RATE_LIMIT_MAX_REQUESTS {
        return false;
    }
    hits.push_back(now);
    true
}

fn is_agent_chat_request(method: &Method, path: &str) -> bool {
    let Some(parts) = api_path_parts(path) else {
        return false;
    };
    method == &Method::Post
        && matches!(
            parts.as_slice(),
            ["projects", _, "chat"] | ["projects", _, "chat", _, "cancel"]
        )
}

fn is_token_required_request(method: &Method, path: &str) -> bool {
    if is_agent_chat_request(method, path) {
        return true;
    }
    let Some(parts) = api_path_parts(path) else {
        return false;
    };
    method == &Method::Post
        && matches!(
            parts.as_slice(),
            ["projects", _, "pages", "embed"] | ["projects", _, "pages", "write"]
        )
}

fn chat_project_id<'a>(method: &Method, path: &'a str) -> Option<&'a str> {
    if method != &Method::Post {
        return None;
    }
    let parts = api_path_parts(path)?;
    match parts.as_slice() {
        ["projects", project_id, "chat"] => Some(*project_id),
        _ => None,
    }
}

fn api_path_parts(path: &str) -> Option<Vec<&str>> {
    let remainder = path.strip_prefix(API_PREFIX)?;
    if !remainder.is_empty() && !remainder.starts_with('/') {
        return None;
    }
    Some(
        remainder
            .trim_start_matches('/')
            .split('/')
            .filter(|part| !part.is_empty())
            .collect(),
    )
}

fn wants_streaming_chat(
    method: &Method,
    path: &str,
    body: &str,
    headers: &[(String, String)],
) -> bool {
    if chat_project_id(method, path).is_none() {
        return false;
    }
    let accepts_sse = headers.iter().any(|(key, value)| {
        key == "accept"
            && value
                .split(',')
                .filter_map(|part| part.trim().split(';').next())
                .any(|media_type| media_type.trim().eq_ignore_ascii_case("text/event-stream"))
    });
    match serde_json::from_str::<Value>(body)
        .ok()
        .and_then(|value| value.get("stream").and_then(Value::as_bool))
    {
        Some(stream) => stream,
        None => accepts_sse,
    }
}

fn body_limit_for_request(method: &Method, url: &str) -> usize {
    let (path, _) = split_url(url);
    let parts = api_path_parts(&path);
    if method != &Method::Post {
        return MAX_BODY_BYTES;
    }
    match parts.as_deref() {
        Some(["projects", _, "chat"]) => MAX_CHAT_BODY_BYTES,
        Some(["projects", _, "pages", "write"]) => MAX_PAGE_WRITE_BODY_BYTES,
        _ => MAX_BODY_BYTES,
    }
}

fn read_body(request: &mut tiny_http::Request, max_body_bytes: usize) -> Result<String, String> {
    let mut limited = request.as_reader().take(max_body_bytes as u64 + 1);
    let mut bytes = Vec::new();
    limited
        .read_to_end(&mut bytes)
        .map_err(|e| format!("Failed to read body: {e}"))?;
    if bytes.len() > max_body_bytes {
        return Err("Request body too large".to_string());
    }
    String::from_utf8(bytes).map_err(|_| "Request body must be UTF-8".to_string())
}

fn respond_error(request: tiny_http::Request, status: u16, message: &str, origin: Option<&str>) {
    respond_json(
        request,
        status,
        json!({ "ok": false, "error": message }),
        origin,
    );
}

fn respond_options(request: tiny_http::Request, origin: Option<&str>) {
    let mut response = Response::empty(StatusCode(204));
    for header in cors_headers(origin) {
        response.add_header(header);
    }
    response.add_header(Header::from_bytes("Access-Control-Max-Age", "600").unwrap());
    let _ = request.respond(response);
}

fn respond_json(request: tiny_http::Request, status: u16, body: Value, origin: Option<&str>) {
    let mut response = Response::from_string(body.to_string()).with_status_code(StatusCode(status));
    for header in cors_headers(origin) {
        response.add_header(header);
    }
    let _ = request.respond(response);
}

fn cors_headers(origin: Option<&str>) -> Vec<Header> {
    local_cors_headers(origin, "Content-Type, Authorization, X-LLM-Wiki-Token")
}

fn split_url(url: &str) -> (String, &str) {
    match url.split_once('?') {
        Some((path, query)) => (path.to_string(), query),
        None => (url.to_string(), ""),
    }
}

fn parse_query(query: &str) -> BTreeMap<String, String> {
    let mut out = BTreeMap::new();
    for pair in query.split('&').filter(|s| !s.is_empty()) {
        let (k, v) = pair.split_once('=').unwrap_or((pair, ""));
        out.insert(percent_decode(k), percent_decode(v));
    }
    out
}

fn percent_decode(input: &str) -> String {
    let bytes = input.as_bytes();
    let mut out = Vec::with_capacity(bytes.len());
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] == b'%' && i + 2 < bytes.len() {
            if let Ok(v) = u8::from_str_radix(&input[i + 1..i + 3], 16) {
                out.push(v);
                i += 3;
                continue;
            }
        }
        out.push(if bytes[i] == b'+' { b' ' } else { bytes[i] });
        i += 1;
    }
    String::from_utf8_lossy(&out).into_owned()
}

fn is_authorized(app: &AppHandle, query: &str, headers: &[(String, String)]) -> bool {
    if !api_auth_required(app) {
        return true;
    }
    is_token_authorized(app, query, headers)
}

pub(crate) fn is_token_authorized(
    app: &AppHandle,
    query: &str,
    headers: &[(String, String)],
) -> bool {
    let Some(token) = api_token(app) else {
        return false;
    };
    let params = parse_query(query);
    if params
        .get("token")
        .map(|v| constant_time_eq(v.as_bytes(), token.as_bytes()))
        .unwrap_or(false)
    {
        return true;
    }
    headers.iter().any(|(key, value)| {
        if key == "x-llm-wiki-token" {
            return constant_time_eq(value.as_bytes(), token.as_bytes());
        }
        if key == "authorization" {
            return value
                .strip_prefix("Bearer ")
                .map(|v| constant_time_eq(v.as_bytes(), token.as_bytes()))
                .unwrap_or(false);
        }
        false
    })
}

fn api_token(app: &AppHandle) -> Option<String> {
    if let Ok(token) = std::env::var("LLM_WIKI_API_TOKEN") {
        let trimmed = token.trim();
        if !trimmed.is_empty() {
            return Some(trimmed.to_string());
        }
    }
    let parsed = load_app_state(app)?;
    parsed
        .get("apiConfig")
        .and_then(|v| v.get("token"))
        .and_then(Value::as_str)
        .filter(|s| !s.is_empty())
        .map(ToOwned::to_owned)
}

fn api_token_source(app: &AppHandle) -> &'static str {
    if let Ok(token) = std::env::var("LLM_WIKI_API_TOKEN") {
        if !token.trim().is_empty() {
            return "env";
        }
    }
    if load_app_state(app)
        .and_then(|parsed| {
            parsed
                .get("apiConfig")
                .and_then(|v| v.get("token"))
                .and_then(Value::as_str)
                .filter(|s| !s.is_empty())
                .map(|_| ())
        })
        .is_some()
    {
        return "store";
    }
    "none"
}

fn api_auth_required(app: &AppHandle) -> bool {
    !api_allow_unauthenticated(app)
}

fn api_allow_unauthenticated(app: &AppHandle) -> bool {
    let Some(parsed) = load_app_state(app) else {
        return false;
    };
    parsed
        .get("apiConfig")
        .and_then(|v| v.get("allowUnauthenticated"))
        .and_then(Value::as_bool)
        .unwrap_or(false)
}

fn api_allow_lan_access(app: &AppHandle) -> bool {
    let Some(parsed) = load_app_state(app) else {
        return false;
    };
    parsed
        .get("apiConfig")
        .and_then(|v| v.get("allowLanAccess"))
        .and_then(Value::as_bool)
        .unwrap_or(false)
}

/// Whether the API server should accept non-/health requests.
///
/// Defaults to `true` when no config has been written yet — keeps
/// existing setups (env-token-only, hand-edited app-state.json) working
/// after the kill-switch was introduced. New users still land in
/// "enabled + no token = 401" which is fail-closed by virtue of the
/// missing token, not the enable flag.
fn api_enabled(app: &AppHandle) -> bool {
    let Some(parsed) = load_app_state(app) else {
        return true;
    };
    parsed
        .get("apiConfig")
        .and_then(|v| v.get("enabled"))
        .and_then(Value::as_bool)
        .unwrap_or(true)
}

fn api_mcp_enabled(app: &AppHandle) -> bool {
    let Some(parsed) = load_app_state(app) else {
        return false;
    };
    parsed
        .get("apiConfig")
        .and_then(|v| v.get("mcpEnabled"))
        .and_then(Value::as_bool)
        .unwrap_or(false)
}

fn constant_time_eq(left: &[u8], right: &[u8]) -> bool {
    let max_len = left.len().max(right.len());
    let mut diff = left.len() ^ right.len();
    for i in 0..max_len {
        let a = left.get(i).copied().unwrap_or(0);
        let b = right.get(i).copied().unwrap_or(0);
        diff |= (a ^ b) as usize;
    }
    diff == 0
}

fn load_app_state(app: &AppHandle) -> Option<Value> {
    let now = Instant::now();
    let lock = APP_STATE_CACHE.get_or_init(|| Mutex::new(None));
    let mut previous = None;
    if let Ok(cache) = lock.lock() {
        if let Some(cached) = cache.as_ref() {
            if now.duration_since(cached.loaded_at) < APP_STATE_CACHE_TTL {
                return cached.value.clone();
            }
            previous = cached.value.clone();
        }
    }

    let path = app.path().app_data_dir().ok()?.join("app-state.json");
    let loaded = fs::read_to_string(path)
        .ok()
        .and_then(|raw| serde_json::from_str::<Value>(&raw).ok());
    let value = loaded.or(previous);

    if let Ok(mut cache) = lock.lock() {
        *cache = Some(CachedAppState {
            loaded_at: now,
            value: value.clone(),
        });
    }
    value
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ProjectEntry {
    id: String,
    name: String,
    path: String,
    current: bool,
}

fn handle_projects(app: &AppHandle) -> ApiResponse {
    let projects = load_projects(app);
    let current_project = projects.iter().find(|project| project.current).cloned();
    ok(json!({
        "ok": true,
        "projects": projects,
        "currentProject": current_project,
    }))
}

fn load_projects(app: &AppHandle) -> Vec<ProjectEntry> {
    let current = normalize_path(&clip_server::current_project_path());
    let mut by_path: BTreeMap<String, ProjectEntry> = BTreeMap::new();

    if let Some(parsed) = load_app_state(app) {
        if let Some(registry) = parsed.get("projectRegistry").and_then(Value::as_object) {
            for (id, value) in registry {
                let path = value.get("path").and_then(Value::as_str).unwrap_or("");
                if path.is_empty() {
                    continue;
                }
                let path = normalize_path(path);
                let name = value
                    .get("name")
                    .and_then(Value::as_str)
                    .map(ToOwned::to_owned)
                    .unwrap_or_else(|| project_name_from_path(&path));
                by_path.insert(
                    path.clone(),
                    ProjectEntry {
                        id: id.clone(),
                        name,
                        current: path == current,
                        path,
                    },
                );
            }
        }
        if let Some(recents) = parsed.get("recentProjects").and_then(Value::as_array) {
            for value in recents {
                let path = value.get("path").and_then(Value::as_str).unwrap_or("");
                if path.is_empty() {
                    continue;
                }
                let path = normalize_path(path);
                by_path.entry(path.clone()).or_insert_with(|| {
                    let id = read_project_id(&path).unwrap_or_else(|| path.clone());
                    let name = value
                        .get("name")
                        .and_then(Value::as_str)
                        .map(ToOwned::to_owned)
                        .unwrap_or_else(|| project_name_from_path(&path));
                    ProjectEntry {
                        id,
                        name,
                        current: path == current,
                        path,
                    }
                });
            }
        }
    }

    for (name, path) in clip_server::all_projects() {
        let path = normalize_path(&path);
        by_path.entry(path.clone()).or_insert_with(|| ProjectEntry {
            id: read_project_id(&path).unwrap_or_else(|| path.clone()),
            name: if name.is_empty() {
                project_name_from_path(&path)
            } else {
                name
            },
            current: path == current,
            path,
        });
    }

    if !current.is_empty() {
        by_path
            .entry(current.clone())
            .or_insert_with(|| ProjectEntry {
                id: read_project_id(&current).unwrap_or_else(|| current.clone()),
                name: project_name_from_path(&current),
                current: true,
                path: current.clone(),
            });
    }

    by_path.into_values().collect()
}

fn resolve_project(app: &AppHandle, project_id: &str) -> Result<ProjectEntry, String> {
    let project_id = percent_decode(project_id);
    let wants_current = project_id.eq_ignore_ascii_case("current");
    load_projects(app)
        .into_iter()
        .find(|p| {
            p.id == project_id
                || project_path_matches(&p.path, &project_id)
                || (wants_current && p.current)
        })
        .ok_or_else(|| format!("Unknown project: {project_id}"))
}

fn project_path_matches(stored_path: &str, candidate: &str) -> bool {
    let stored = normalize_path(stored_path);
    let candidate = normalize_path(candidate);
    if cfg!(windows) {
        stored.eq_ignore_ascii_case(&candidate)
    } else {
        stored == candidate
    }
}

fn read_project_id(path: &str) -> Option<String> {
    let raw = fs::read_to_string(Path::new(path).join(".llm-wiki/project.json")).ok()?;
    let parsed: Value = serde_json::from_str(&raw).ok()?;
    parsed
        .get("id")
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
}

fn project_name_from_path(path: &str) -> String {
    Path::new(path)
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("Project")
        .to_string()
}

fn normalize_path(path: &str) -> String {
    path.replace('\\', "/").trim_end_matches('/').to_string()
}

fn handle_files(app: &AppHandle, project_id: &str, query: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let params = parse_query(query);
    let root = params.get("root").map(String::as_str).unwrap_or("wiki");
    let recursive = params
        .get("recursive")
        .map(|v| v != "false")
        .unwrap_or(true);
    let max_files = params
        .get("maxFiles")
        .and_then(|v| v.parse::<usize>().ok())
        .unwrap_or(DEFAULT_MAX_FILES)
        .clamp(1, HARD_MAX_FILES);
    let rel = match root {
        "wiki" => "wiki",
        "sources" | "raw" | "raw/sources" => "raw/sources",
        "all" | "" => "",
        _ => return err(400, "root must be wiki, sources, or all"),
    };
    if rel.is_empty() {
        return match list_public_roots(&project.path, recursive, max_files) {
            Ok(files) => ok(json!({
                "ok": true,
                "projectId": project.id,
                "root": "all",
                "files": files,
                "truncated": false,
            })),
            Err(e) => err(if e.contains("exceeds") { 413 } else { 500 }, e),
        };
    }
    let dir = match safe_join(&project.path, rel) {
        Ok(path) => path,
        Err(e) => return err(400, e),
    };
    let mut count = 0;
    match list_tree(&project.path, &dir, recursive, max_files, &mut count) {
        Ok(files) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "root": rel,
            "files": files,
            "truncated": false,
        })),
        Err(e) => err(if e.contains("exceeds") { 413 } else { 500 }, e),
    }
}

fn handle_file_content(app: &AppHandle, project_id: &str, query: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let params = parse_query(query);
    let Some(rel) = params.get("path") else {
        return err(400, "Missing path query parameter");
    };
    if !is_public_project_rel(rel) {
        return err(403, "Path is not exposed by the local API");
    }
    if !is_text_content_rel(rel) {
        return err(
            415,
            "Only text-like project files can be read via this endpoint",
        );
    }
    let path = match safe_join(&project.path, rel) {
        Ok(path) => path,
        Err(e) => return err(400, e),
    };
    let meta = match fs::metadata(&path) {
        Ok(meta) => meta,
        Err(e) => return err(404, format!("File not found: {e}")),
    };
    if meta.len() > MAX_FILE_CONTENT_BYTES {
        return err(413, "File is too large to return via API");
    }
    match fs::read_to_string(&path) {
        Ok(content) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "path": rel,
            "content": content,
        })),
        Err(_) => err(415, "File is not valid UTF-8 text"),
    }
}

fn safe_join(project_path: &str, rel: &str) -> Result<PathBuf, String> {
    let root = PathBuf::from(project_path);
    let rel = rel.trim_start_matches('/');
    let rel_path = Path::new(rel);
    if rel_path.is_absolute() {
        return Err("Absolute paths are not allowed".to_string());
    }
    for component in rel_path.components() {
        if matches!(
            component,
            Component::ParentDir | Component::Prefix(_) | Component::RootDir
        ) {
            return Err("Path traversal is not allowed".to_string());
        }
    }
    let joined = root.join(rel_path);
    let root_canon = root
        .canonicalize()
        .map_err(|e| format!("Failed to resolve project path: {e}"))?;
    if joined.exists() {
        let joined_canon = joined
            .canonicalize()
            .map_err(|e| format!("Failed to resolve path: {e}"))?;
        if !joined_canon.starts_with(&root_canon) {
            return Err("Resolved path escapes the project directory".to_string());
        }
        return Ok(joined_canon);
    }
    let parent = joined
        .parent()
        .ok_or_else(|| "Path has no parent directory".to_string())?;
    if parent.exists() {
        let parent_canon = parent
            .canonicalize()
            .map_err(|e| format!("Failed to resolve parent path: {e}"))?;
        if !parent_canon.starts_with(&root_canon) {
            return Err("Resolved parent escapes the project directory".to_string());
        }
    }
    Ok(joined)
}

fn is_public_project_rel(rel: &str) -> bool {
    let rel = normalize_path(rel).trim_start_matches('/').to_string();
    if rel
        .split('/')
        .any(|part| part.is_empty() || part.starts_with('.'))
    {
        return false;
    }
    let lower = rel.to_lowercase();
    lower == "purpose.md"
        || lower == "schema.md"
        || lower.starts_with("wiki/")
        || lower.starts_with("raw/sources/")
}

fn is_text_content_rel(rel: &str) -> bool {
    let rel = normalize_path(rel).to_lowercase();
    let ext = Path::new(&rel)
        .extension()
        .and_then(|s| s.to_str())
        .unwrap_or("");
    matches!(
        ext,
        "md" | "mdx" | "txt" | "csv" | "json" | "yaml" | "yml" | "xml" | "html" | "htm" | "log"
    )
}

#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
struct ApiFileNode {
    name: String,
    path: String,
    is_dir: bool,
    size: Option<u64>,
    children: Option<Vec<ApiFileNode>>,
}

fn list_public_roots(
    project_path: &str,
    recursive: bool,
    max_files: usize,
) -> Result<Vec<ApiFileNode>, String> {
    let mut count = 0;
    let mut roots = Vec::new();
    for rel in ["purpose.md", "schema.md", "wiki", "raw/sources"] {
        let path = safe_join(project_path, rel)?;
        if !path.exists() {
            continue;
        }
        push_file_node(
            project_path,
            &path,
            recursive,
            max_files,
            &mut count,
            &mut roots,
        )?;
    }
    Ok(roots)
}

fn list_tree(
    project_path: &str,
    path: &Path,
    recursive: bool,
    max_files: usize,
    count: &mut usize,
) -> Result<Vec<ApiFileNode>, String> {
    let mut out = Vec::new();
    let entries = fs::read_dir(path).map_err(|e| format!("Failed to list directory: {e}"))?;
    for entry in entries {
        let entry = entry.map_err(|e| format!("Failed to read directory entry: {e}"))?;
        push_file_node(
            project_path,
            &entry.path(),
            recursive,
            max_files,
            count,
            &mut out,
        )?;
    }
    out.sort_by(|a, b| b.is_dir.cmp(&a.is_dir).then_with(|| a.name.cmp(&b.name)));
    Ok(out)
}

fn push_file_node(
    project_path: &str,
    path: &Path,
    recursive: bool,
    max_files: usize,
    count: &mut usize,
    out: &mut Vec<ApiFileNode>,
) -> Result<(), String> {
    let name = path
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("")
        .to_string();
    if name.starts_with('.') {
        return Ok(());
    }
    let meta = fs::symlink_metadata(path).map_err(|e| format!("Failed to read metadata: {e}"))?;
    let file_type = meta.file_type();
    if file_type.is_symlink() {
        return Ok(());
    }
    *count += 1;
    if *count > max_files {
        return Err(format!("File listing exceeds maxFiles limit ({max_files})"));
    }
    let is_dir = file_type.is_dir();
    let children = if recursive && is_dir {
        Some(list_tree(project_path, path, true, max_files, count)?)
    } else {
        None
    };
    out.push(ApiFileNode {
        name,
        path: relative_to_project(project_path, path),
        is_dir,
        size: if is_dir { None } else { Some(meta.len()) },
        children,
    });
    Ok(())
}

fn relative_to_project(project_path: &str, path: &Path) -> String {
    let root = Path::new(project_path);
    path.strip_prefix(root)
        .map(|p| p.to_string_lossy().replace('\\', "/"))
        .unwrap_or_else(|_| path.to_string_lossy().replace('\\', "/"))
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ReviewStatus {
    Unresolved,
    Resolved,
    All,
}

impl ReviewStatus {
    fn as_str(self) -> &'static str {
        match self {
            ReviewStatus::Unresolved => "unresolved",
            ReviewStatus::Resolved => "resolved",
            ReviewStatus::All => "all",
        }
    }

    fn matches(self, resolved: bool) -> bool {
        match self {
            ReviewStatus::Unresolved => !resolved,
            ReviewStatus::Resolved => resolved,
            ReviewStatus::All => true,
        }
    }
}

#[derive(Debug, Clone)]
struct ReviewQuery {
    status: ReviewStatus,
    item_type: Option<String>,
    limit: usize,
}

fn parse_review_query(query: &str) -> Result<ReviewQuery, String> {
    let params = parse_query(query);
    let status = match params
        .get("status")
        .map(|s| s.as_str())
        .unwrap_or("unresolved")
    {
        "unresolved" | "pending" => ReviewStatus::Unresolved,
        "resolved" => ReviewStatus::Resolved,
        "all" => ReviewStatus::All,
        value => {
            return Err(format!(
                "Invalid review status '{value}'. Expected unresolved, resolved, or all"
            ))
        }
    };
    let item_type = params
        .get("type")
        .map(|s| s.trim().to_string())
        .filter(|s| !s.is_empty());
    let limit = params
        .get("limit")
        .and_then(|s| s.parse::<usize>().ok())
        .unwrap_or(DEFAULT_MAX_REVIEWS)
        .clamp(1, HARD_MAX_REVIEWS);

    Ok(ReviewQuery {
        status,
        item_type,
        limit,
    })
}

fn normalize_review_title(title: &str) -> String {
    let trimmed = title.trim_start();
    let lower = trimmed.to_lowercase();
    let mut rest = trimmed;
    for prefix in [
        "missing page",
        "missing-page",
        "missingpage",
        "duplicate page",
        "duplicate-page",
        "duplicatepage",
        "possible duplicate",
        "possible-duplicate",
        "possibleduplicate",
        "缺失页面",
        "缺少页面",
        "重复页面",
        "疑似重复",
    ] {
        if !lower.starts_with(prefix) {
            continue;
        }
        let suffix = &trimmed[prefix.len()..];
        let Some(delimiter) = suffix.chars().next() else {
            continue;
        };
        if delimiter == ':' || delimiter == ':' {
            rest = suffix[delimiter.len_utf8()..].trim_start();
            break;
        }
    }
    rest.split_whitespace()
        .collect::<Vec<_>>()
        .join(" ")
        .to_lowercase()
}

fn review_id_for_parts(item_type: &str, title: &str) -> String {
    let key = format!("{item_type}::{}", normalize_review_title(title));
    let mut h: u32 = 0x811c9dc5;
    for unit in key.encode_utf16() {
        h ^= u32::from(unit);
        h = h.wrapping_mul(0x01000193);
    }
    format!("review-{h:08x}")
}

fn stable_review_id(item: &Value) -> Option<String> {
    let item_type = item.get("type").and_then(Value::as_str)?;
    let title = item.get("title").and_then(Value::as_str)?;
    Some(review_id_for_parts(item_type, title))
}

fn review_id_matches(item: &Value, requested_id: &str) -> bool {
    item.get("id").and_then(Value::as_str) == Some(requested_id)
        || stable_review_id(item).as_deref() == Some(requested_id)
}

fn load_review_items(project_path: &str, query: &ReviewQuery) -> Result<Vec<Value>, String> {
    let path = Path::new(project_path).join(".llm-wiki/review.json");
    let raw = match fs::read_to_string(&path) {
        Ok(raw) => raw,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(err) => return Err(format!("Failed to read review state: {err}")),
    };
    let parsed: Value =
        serde_json::from_str(&raw).map_err(|err| format!("Invalid review state JSON: {err}"))?;
    let items = parsed
        .as_array()
        .ok_or_else(|| "Invalid review state JSON: expected an array".to_string())?;

    let mut normalized: Vec<Value> = Vec::new();
    let mut index_by_id: BTreeMap<String, usize> = BTreeMap::new();
    for item in items {
        let sanitized = sanitize_review_item(item);
        let id = sanitized
            .get("id")
            .and_then(Value::as_str)
            .map(str::to_string);
        if let Some(id) = id {
            if let Some(existing_idx) = index_by_id.get(&id).copied() {
                merge_sanitized_review(&mut normalized[existing_idx], &sanitized);
                continue;
            }
            index_by_id.insert(id, normalized.len());
        }
        normalized.push(sanitized);
    }

    let mut reviews: Vec<Value> = Vec::new();
    for item in normalized {
        let resolved = item
            .get("resolved")
            .and_then(Value::as_bool)
            .unwrap_or(false);
        if !query.status.matches(resolved) {
            continue;
        }
        if let Some(item_type) = &query.item_type {
            if item.get("type").and_then(Value::as_str) != Some(item_type.as_str()) {
                continue;
            }
        }
        if reviews.len() >= query.limit {
            break;
        }
        reviews.push(item);
    }

    Ok(reviews)
}

fn sanitize_review_item(item: &Value) -> Value {
    let mut out = Map::new();
    if let Some(id) = stable_review_id(item) {
        out.insert("id".to_string(), Value::String(id));
    } else {
        copy_string_field(item, &mut out, "id");
    }
    copy_string_field(item, &mut out, "type");
    copy_string_field(item, &mut out, "title");
    copy_string_field(item, &mut out, "description");
    copy_string_field(item, &mut out, "sourcePath");
    copy_string_array_field(item, &mut out, "affectedPages");
    copy_string_array_field(item, &mut out, "searchQueries");
    copy_review_options(item, &mut out);
    copy_bool_field(item, &mut out, "resolved");
    copy_string_field(item, &mut out, "resolvedAction");
    copy_number_field(item, &mut out, "createdAt");
    Value::Object(out)
}

fn merge_sanitized_review(existing: &mut Value, incoming: &Value) {
    let Some(existing) = existing.as_object_mut() else {
        return;
    };
    let Some(incoming) = incoming.as_object() else {
        return;
    };

    let resolved = existing
        .get("resolved")
        .and_then(Value::as_bool)
        .unwrap_or(false)
        || incoming
            .get("resolved")
            .and_then(Value::as_bool)
            .unwrap_or(false);
    existing.insert("resolved".to_string(), Value::Bool(resolved));

    if resolved && !existing.contains_key("resolvedAction") {
        if let Some(action) = incoming.get("resolvedAction").and_then(Value::as_str) {
            existing.insert(
                "resolvedAction".to_string(),
                Value::String(action.to_string()),
            );
        }
    }

    for key in ["description", "sourcePath"] {
        let existing_empty = existing
            .get(key)
            .and_then(Value::as_str)
            .map(str::is_empty)
            .unwrap_or(true);
        if existing_empty {
            if let Some(value) = incoming.get(key).and_then(Value::as_str) {
                existing.insert(key.to_string(), Value::String(value.to_string()));
            }
        }
    }

    merge_string_array_field(existing, incoming, "affectedPages");
    merge_string_array_field(existing, incoming, "searchQueries");
    merge_review_options_field(existing, incoming);

    if let Some(incoming_created) = incoming.get("createdAt").and_then(Value::as_f64) {
        let existing_created = existing
            .get("createdAt")
            .and_then(Value::as_f64)
            .unwrap_or(incoming_created);
        existing.insert(
            "createdAt".to_string(),
            json!(existing_created.min(incoming_created)),
        );
    }
}

fn merge_string_array_field(
    existing: &mut Map<String, Value>,
    incoming: &Map<String, Value>,
    key: &str,
) {
    let mut values = existing
        .get(key)
        .and_then(Value::as_array)
        .map(|values| {
            values
                .iter()
                .filter_map(Value::as_str)
                .map(str::to_string)
                .collect::<Vec<_>>()
        })
        .unwrap_or_default();
    for value in incoming
        .get(key)
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(Value::as_str)
    {
        if !values.iter().any(|existing| existing == value) {
            values.push(value.to_string());
        }
    }
    if !values.is_empty() {
        existing.insert(
            key.to_string(),
            Value::Array(values.into_iter().map(Value::String).collect()),
        );
    }
}

fn merge_review_options_field(existing: &mut Map<String, Value>, incoming: &Map<String, Value>) {
    let mut options = existing
        .get("options")
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    for option in incoming
        .get("options")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        let action = option.get("action").and_then(Value::as_str);
        let already_present = action.is_some_and(|action| {
            options
                .iter()
                .any(|existing| existing.get("action").and_then(Value::as_str) == Some(action))
        });
        if !already_present {
            options.push(option.clone());
        }
    }
    if !options.is_empty() {
        existing.insert("options".to_string(), Value::Array(options));
    }
}

fn copy_string_field(item: &Value, out: &mut Map<String, Value>, key: &str) {
    if let Some(value) = item.get(key).and_then(Value::as_str) {
        out.insert(key.to_string(), Value::String(value.to_string()));
    }
}

fn copy_bool_field(item: &Value, out: &mut Map<String, Value>, key: &str) {
    if let Some(value) = item.get(key).and_then(Value::as_bool) {
        out.insert(key.to_string(), Value::Bool(value));
    }
}

fn copy_number_field(item: &Value, out: &mut Map<String, Value>, key: &str) {
    if let Some(value) = item.get(key).and_then(Value::as_f64) {
        if value.is_finite() {
            out.insert(key.to_string(), json!(value));
        }
    }
}

fn copy_string_array_field(item: &Value, out: &mut Map<String, Value>, key: &str) {
    let Some(values) = item.get(key).and_then(Value::as_array) else {
        return;
    };
    let strings = values
        .iter()
        .filter_map(Value::as_str)
        .map(|value| Value::String(value.to_string()))
        .collect::<Vec<_>>();
    out.insert(key.to_string(), Value::Array(strings));
}

fn copy_review_options(item: &Value, out: &mut Map<String, Value>) {
    let Some(values) = item.get("options").and_then(Value::as_array) else {
        return;
    };
    let options = values
        .iter()
        .filter_map(|option| {
            let option = option.as_object()?;
            let mut sanitized = Map::new();
            if let Some(label) = option.get("label").and_then(Value::as_str) {
                sanitized.insert("label".to_string(), Value::String(label.to_string()));
            }
            if let Some(action) = option.get("action").and_then(Value::as_str) {
                sanitized.insert("action".to_string(), Value::String(action.to_string()));
            }
            if sanitized.is_empty() {
                None
            } else {
                Some(Value::Object(sanitized))
            }
        })
        .collect::<Vec<_>>();
    out.insert("options".to_string(), Value::Array(options));
}

fn handle_reviews(app: &AppHandle, project_id: &str, query: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let query = match parse_review_query(query) {
        Ok(query) => query,
        Err(e) => return err(400, e),
    };
    match load_review_items(&project.path, &query) {
        Ok(reviews) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "status": query.status.as_str(),
            "count": reviews.len(),
            "reviews": reviews,
        })),
        Err(e) => err(500, e),
    }
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct PatchReviewRequest {
    /// Target resolved state. Defaults to `true` (the common case:
    /// resolve). Pass `false` to reopen a resolved item.
    resolved: Option<bool>,
    /// Optional human-readable action label stored on the item
    /// (e.g. "Skip", "Created page"). Mark-only — the API never
    /// replicates the WebView's side effects (page creation, etc).
    action: Option<String>,
}

/// `PATCH /projects/{id}/reviews/{reviewId}` — partial update of a
/// single review item's resolved state. Body `{ resolved?, action? }`;
/// an empty body resolves the item (resolved defaults to true).
fn handle_patch_review(
    app: &AppHandle,
    project_id: &str,
    review_id: &str,
    body: &str,
) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let req = if body.trim().is_empty() {
        PatchReviewRequest {
            resolved: None,
            action: None,
        }
    } else {
        match serde_json::from_str::<PatchReviewRequest>(body) {
            Ok(req) => req,
            Err(e) => return err(400, format!("Invalid request body: {e}")),
        }
    };
    let resolved = req.resolved.unwrap_or(true);
    match patch_review_item(&project.path, review_id, resolved, req.action.as_deref()) {
        Ok(true) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "reviewId": review_id,
            "resolved": resolved,
        })),
        Ok(false) => err(404, format!("Review item '{review_id}' not found")),
        Err(e) => err(500, e),
    }
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct BulkResolveRequest {
    /// Review item ids to resolve. Required, non-empty.
    #[serde(alias = "reviewIds")]
    ids: Vec<String>,
    /// Optional label applied to every resolved item.
    action: Option<String>,
}

fn handle_delete_review(app: &AppHandle, project_id: &str, review_id: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    match delete_review_item(&project.path, review_id) {
        Ok(true) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "reviewId": review_id,
            "deleted": true,
        })),
        Ok(false) => err(404, format!("Review item '{review_id}' not found")),
        Err(e) => err(500, e),
    }
}

fn delete_review_item(project_path: &str, review_id: &str) -> Result<bool, String> {
    let path = Path::new(project_path).join(".llm-wiki/review.json");
    let mut parsed = match read_raw_review_array(&path)? {
        Some(parsed) => parsed,
        None => return Ok(false),
    };
    let items = parsed
        .as_array_mut()
        .ok_or_else(|| "Invalid review state JSON: expected an array".to_string())?;
    let original_len = items.len();
    items.retain(|item| !review_id_matches(item, review_id));
    if items.len() == original_len {
        return Ok(false);
    }
    write_raw_review_array(&path, &parsed)?;
    Ok(true)
}

/// `POST /projects/{id}/reviews/resolve` — bulk-resolve many review
/// items in one request. Body `{ ids, action? }`. Partial success is
/// normal, so this returns 200 with `{ resolved, notFound, count }`
/// rather than 404 — 404 is reserved for the single-item PATCH where
/// one unknown id is the entire request.
fn handle_bulk_resolve_reviews(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let req = match serde_json::from_str::<BulkResolveRequest>(body) {
        Ok(req) => req,
        Err(e) => return err(400, format!("Invalid request body: {e}")),
    };
    if req.ids.is_empty() {
        return err(400, "ids must be a non-empty array".to_string());
    }
    match resolve_review_items(&project.path, &req.ids, req.action.as_deref()) {
        Ok((resolved, not_found)) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "resolved": resolved,
            "notFound": not_found,
            "count": resolved.len(),
        })),
        Err(e) => err(500, e),
    }
}

/// Set one review item's resolved state in `.llm-wiki/review.json`.
///
/// Operates on the RAW parsed array (not `load_review_items`, which
/// sanitizes — reusing it would strip fields like `internalSecret` and
/// silently corrupt the file on write-back). Sets `resolved` and, when
/// provided, `resolvedAction`. Returns Ok(false) if no item with the
/// given id exists (caller maps to 404).
fn patch_review_item(
    project_path: &str,
    review_id: &str,
    resolved: bool,
    action: Option<&str>,
) -> Result<bool, String> {
    let path = Path::new(project_path).join(".llm-wiki/review.json");
    let mut parsed = match read_raw_review_array(&path)? {
        Some(parsed) => parsed,
        None => return Ok(false),
    };
    let items = parsed
        .as_array_mut()
        .ok_or_else(|| "Invalid review state JSON: expected an array".to_string())?;

    let mut found = false;
    for item in items.iter_mut() {
        if !review_id_matches(item, review_id) {
            continue;
        }
        apply_resolution(item, resolved, action);
        if let Some(stable_id) = stable_review_id(item) {
            if let Some(obj) = item.as_object_mut() {
                obj.insert("id".to_string(), Value::String(stable_id));
            }
        }
        found = true;
    }

    if !found {
        return Ok(false);
    }
    write_raw_review_array(&path, &parsed)?;
    Ok(true)
}

/// Bulk version of `patch_review_item`: reads `review.json` ONCE,
/// resolves every matching id in the raw array, writes ONCE. Looping
/// the single-item helper would be N read-parse-write cycles with a
/// race window per write. Returns `(resolved_ids, not_found_ids)`,
/// both in the caller's input order.
fn resolve_review_items(
    project_path: &str,
    ids: &[String],
    action: Option<&str>,
) -> Result<(Vec<String>, Vec<String>), String> {
    let path = Path::new(project_path).join(".llm-wiki/review.json");
    let mut parsed = match read_raw_review_array(&path)? {
        Some(parsed) => parsed,
        // No review file → nothing exists, so every id is "not found".
        None => return Ok((Vec::new(), ids.to_vec())),
    };
    let items = parsed
        .as_array_mut()
        .ok_or_else(|| "Invalid review state JSON: expected an array".to_string())?;

    let mut found: BTreeSet<String> = BTreeSet::new();
    for item in items.iter_mut() {
        let raw_id = item.get("id").and_then(Value::as_str);
        let stable_id = stable_review_id(item);
        let matched_request = ids
            .iter()
            .find(|id| raw_id == Some(id.as_str()) || stable_id.as_deref() == Some(id.as_str()));
        let Some(requested_id) = matched_request else {
            continue;
        };
        apply_resolution(item, true, action);
        if let Some(stable_id) = stable_id {
            if let Some(obj) = item.as_object_mut() {
                obj.insert("id".to_string(), Value::String(stable_id));
            }
        }
        found.insert(requested_id.clone());
    }

    if !found.is_empty() {
        write_raw_review_array(&path, &parsed)?;
    }

    // Preserve the caller's input order; dedupe is implicit via `found`.
    let resolved: Vec<String> = ids
        .iter()
        .filter(|id| found.contains(*id))
        .cloned()
        .collect();
    let not_found: Vec<String> = ids
        .iter()
        .filter(|id| !found.contains(*id))
        .cloned()
        .collect();
    Ok((resolved, not_found))
}

/// Set `resolved` / `resolvedAction` on a raw review item value.
fn apply_resolution(item: &mut Value, resolved: bool, action: Option<&str>) {
    if let Some(obj) = item.as_object_mut() {
        obj.insert("resolved".to_string(), Value::Bool(resolved));
        if !resolved {
            obj.remove("resolvedAction");
        } else if let Some(action) = action {
            obj.insert(
                "resolvedAction".to_string(),
                Value::String(action.to_string()),
            );
        }
    }
}

/// Read `.llm-wiki/review.json` as a raw JSON value. Returns Ok(None)
/// when the file doesn't exist (callers treat that as "no items").
fn read_raw_review_array(path: &Path) -> Result<Option<Value>, String> {
    let raw = match fs::read_to_string(path) {
        Ok(raw) => raw,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(err) => return Err(format!("Failed to read review state: {err}")),
    };
    let parsed: Value =
        serde_json::from_str(&raw).map_err(|err| format!("Invalid review state JSON: {err}"))?;
    Ok(Some(parsed))
}

fn write_raw_review_array(path: &Path, parsed: &Value) -> Result<(), String> {
    let serialized = serde_json::to_string_pretty(parsed)
        .map_err(|err| format!("Failed to serialize review state: {err}"))?;
    fs::write(path, serialized).map_err(|err| format!("Failed to write review state: {err}"))
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct SearchRequest {
    query: String,
    top_k: Option<usize>,
    include_content: Option<bool>,
    query_embedding: Option<Vec<f32>>,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct EmbedPageRequest {
    path: String,
    #[serde(default)]
    force: bool,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
struct WritePageRequest {
    path: String,
    content: String,
    #[serde(default)]
    allow_overwrite: bool,
}

fn handle_write_page(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let req: WritePageRequest = match serde_json::from_str(body) {
        Ok(req) => req,
        Err(e) => return err(400, format!("Invalid JSON: {e}")),
    };
    if req.path.trim().is_empty() {
        return err(400, "path is required");
    }
    match agent::tools::write_wiki_page_verified(
        &project.path,
        &req.path,
        &req.content,
        req.allow_overwrite,
    ) {
        Ok(result) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "result": result,
        })),
        Err(error) => {
            let lower = error.to_ascii_lowercase();
            let status = if lower.contains("without allowoverwrite") {
                409
            } else if lower.contains("path")
                || lower.contains("markdown file")
                || lower.contains("too large")
            {
                400
            } else {
                500
            };
            err(status, error)
        }
    }
}

struct PageEmbedSlot;

impl Drop for PageEmbedSlot {
    fn drop(&mut self) {
        IN_FLIGHT_PAGE_EMBEDS.fetch_sub(1, Ordering::Relaxed);
    }
}

fn try_acquire_page_embed_slot() -> Option<PageEmbedSlot> {
    IN_FLIGHT_PAGE_EMBEDS
        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
            (current < MAX_IN_FLIGHT_PAGE_EMBEDS).then_some(current + 1)
        })
        .ok()
        .map(|_| PageEmbedSlot)
}

fn handle_embed_page(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let req: EmbedPageRequest = match serde_json::from_str(body) {
        Ok(req) => req,
        Err(e) => return err(400, format!("Invalid JSON: {e}")),
    };
    if req.path.trim().is_empty() {
        return err(400, "path is required");
    }
    let Some(config) = load_embedding_config(app) else {
        return err(400, "Embedding is not configured");
    };
    let Some(_slot) = try_acquire_page_embed_slot() else {
        return err(503, "Too many page indexing requests are already running");
    };
    let result = tauri::async_runtime::block_on(commands::page_embedding::embed_wiki_page(
        &project.path,
        &req.path,
        config,
        req.force,
    ));
    match result {
        Ok(result) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "result": result,
        })),
        Err(error) => {
            let status = match error.kind {
                commands::page_embedding::PageEmbeddingErrorKind::InvalidRequest => 400,
                commands::page_embedding::PageEmbeddingErrorKind::NotFound => 404,
                commands::page_embedding::PageEmbeddingErrorKind::Provider => 502,
                commands::page_embedding::PageEmbeddingErrorKind::Storage => 500,
                commands::page_embedding::PageEmbeddingErrorKind::Timeout => 504,
            };
            err(status, error.message)
        }
    }
}

fn handle_search(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let req: SearchRequest = match serde_json::from_str(body) {
        Ok(req) => req,
        Err(e) => return err(400, format!("Invalid JSON: {e}")),
    };
    if req.query.trim().is_empty() {
        return err(400, "query is required");
    }
    let top_k = req.top_k.unwrap_or(10).clamp(1, MAX_SEARCH_RESULTS);
    let query = req.query;
    let query_embedding =
        match tauri::async_runtime::block_on(commands::search::resolve_query_embedding(
            &query,
            req.query_embedding,
            load_embedding_config(app),
        )) {
            Ok(embedding) => embedding,
            Err(e) => return err(400, e),
        };
    match tauri::async_runtime::block_on(commands::search::search_project_inner(
        project.path.clone(),
        query,
        top_k,
        req.include_content.unwrap_or(false),
        query_embedding,
    )) {
        Ok(search) => ok(json!({
            "ok": true,
            "projectId": project.id,
            "mode": search.mode,
            "note": "Search uses the shared backend hybrid retrieval service, combining keyword, vector, and one-hop knowledge-graph candidates. When embeddingConfig is enabled, the API automatically includes LanceDB vector results; clients may also pass queryEmbedding explicitly.",
            "tokenHits": search.token_hits,
            "vectorHits": search.vector_hits,
            "graphHits": search.graph_hits,
            "results": search.results,
        })),
        Err(e) => err(500, e),
    }
}

struct PreparedChat {
    project: ProjectEntry,
    request: agent::AgentChatRequest,
    runtime: agent::AgentRuntime,
    user_message: String,
    persist_session: bool,
    session_id: String,
    run_id: String,
    cancellation: Option<agent::cancel::AgentCancellationToken>,
}

fn prepare_chat(
    app: &AppHandle,
    project_id: &str,
    body: &str,
) -> Result<PreparedChat, ApiResponse> {
    let project = resolve_project(app, project_id).map_err(|e| err(404, e))?;
    let mut req: agent::AgentChatRequest =
        serde_json::from_str(body).map_err(|e| err(400, format!("Invalid JSON: {e}")))?;
    // This is an internal desktop preflight escape hatch for CLI-backed chat.
    // The public API must retain its actionable generator-configuration error.
    req.allow_empty_retrieval = false;
    if req.message.trim().is_empty() {
        return Err(err(400, "message is required"));
    }
    if req
        .session_id
        .as_deref()
        .map(str::trim)
        .unwrap_or("")
        .is_empty()
    {
        req.session_id = Some(format!("api_{}", Uuid::new_v4()));
    }
    if req
        .run_id
        .as_deref()
        .map(str::trim)
        .unwrap_or("")
        .is_empty()
    {
        req.run_id = Some(format!("run_{}", Uuid::new_v4()));
    }
    let requested_session_id = req.session_id.clone();
    if let Some(session_id) = requested_session_id.as_deref() {
        if req.history.is_empty() && !req.history_explicit {
            req.history = app
                .state::<agent::session::AgentSessionStore>()
                .recent_messages(&project.path, session_id, 12)
                .into_iter()
                .map(|message| agent::types::AgentConversationMessage {
                    role: message.role,
                    content: message.content,
                })
                .collect();
        }
    }
    let runtime_config = load_agent_runtime_config(app, Some(&project.id));
    let runtime = agent::AgentRuntime::new(
        project.id.clone(),
        project.path.clone(),
        runtime_config.embedding,
        runtime_config.llm,
        runtime_config.web_search,
        runtime_config.anytxt,
    );
    let user_message_for_session = req.message.clone();
    let persist_session = req.persist_session;
    let session_id = req.session_id.clone().unwrap_or_default();
    let run_id = req.run_id.clone().unwrap_or_default();
    let cancellation = app
        .state::<agent::cancel::AgentCancellationRegistry>()
        .start(&project.id, &session_id, &run_id);
    Ok(PreparedChat {
        project,
        request: req,
        runtime,
        user_message: user_message_for_session,
        persist_session,
        session_id,
        run_id,
        cancellation: Some(cancellation),
    })
}

fn persist_chat_response(
    app: &AppHandle,
    prepared: &PreparedChat,
    response: &agent::types::AgentChatResponse,
) {
    if prepared.persist_session {
        app.state::<agent::session::AgentSessionStore>()
            .append_turn(
                &prepared.project.path,
                &prepared.project.id,
                &response.session_id,
                &prepared.user_message,
                &response.message,
            );
    }
}

fn external_chat_response(mut response: agent::types::AgentChatResponse) -> Value {
    for event in &mut response.events {
        event.redact_for_external_api();
    }
    json!({
        "ok": true,
        "projectId": response.project_id,
        "sessionId": response.session_id,
        "mode": response.mode,
        "message": {
            "role": "assistant",
            "content": response.message,
        },
        "references": response.references,
        "toolEvents": response.tool_events,
        "events": response.events,
        "usage": response.usage,
    })
}

fn handle_chat(app: &AppHandle, project_id: &str, body: &str) -> ApiResponse {
    let mut prepared = match prepare_chat(app, project_id, body) {
        Ok(prepared) => prepared,
        Err(response) => return response,
    };
    let result = tauri::async_runtime::block_on(prepared.runtime.run_once_with_cancel(
        std::mem::take(&mut prepared.request),
        prepared.cancellation.take(),
    ));
    app.state::<agent::cancel::AgentCancellationRegistry>()
        .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);
    match result {
        Ok(response) => {
            persist_chat_response(app, &prepared, &response);
            ok(external_chat_response(response))
        }
        Err(e) if e == "message is required" => err(400, e),
        Err(e) if e == "Agent turn cancelled" => err(499, e),
        Err(e) => err(502, e),
    }
}

struct SseReader {
    receiver: Receiver<Vec<u8>>,
    current: Cursor<Vec<u8>>,
}

impl SseReader {
    fn new(receiver: Receiver<Vec<u8>>) -> Self {
        Self {
            receiver,
            current: Cursor::new(Vec::new()),
        }
    }
}

impl Read for SseReader {
    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
        if buffer.is_empty() {
            return Ok(0);
        }
        loop {
            let read = self.current.read(buffer)?;
            if read > 0 {
                return Ok(read);
            }
            match self.receiver.recv() {
                Ok(chunk) => self.current = Cursor::new(chunk),
                Err(_) => return Ok(0),
            }
        }
    }
}

fn sse_frame(event: &str, data: &Value) -> Vec<u8> {
    format!("event: {event}\ndata: {}\n\n", data).into_bytes()
}

enum SseSendResult {
    Sent,
    Full,
    Disconnected,
}

fn try_send_sse(sender: &SyncSender<Vec<u8>>, frame: Vec<u8>) -> SseSendResult {
    match sender.try_send(frame) {
        Ok(()) => SseSendResult::Sent,
        Err(mpsc::TrySendError::Full(_)) => SseSendResult::Full,
        Err(mpsc::TrySendError::Disconnected(_)) => SseSendResult::Disconnected,
    }
}

fn send_terminal_sse(sender: SyncSender<Vec<u8>>, frame: Vec<u8>) {
    // A terminal frame must not be dropped when the bounded queue is briefly
    // full, but blocking a Tokio worker would stall unrelated app work. Use a
    // short-lived writer thread; send unblocks when the socket drains or the
    // request reader is dropped after a disconnect.
    thread::spawn(move || {
        let _ = sender.send(frame);
    });
}

fn respond_chat_sse(
    request: tiny_http::Request,
    app: AppHandle,
    project_id: &str,
    body: &str,
    origin: Option<&str>,
    _stream_slot: ChatStreamSlot,
) {
    let prepared = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        prepare_chat(&app, project_id, body)
    }));
    let mut prepared = match prepared {
        Ok(Ok(prepared)) => prepared,
        Ok(Err(response)) => {
            respond_json(request, response.status, response.body, origin);
            return;
        }
        Err(_) => {
            respond_error(request, 500, "Internal API server error", origin);
            return;
        }
    };
    let (sender, receiver) = mpsc::sync_channel::<Vec<u8>>(SSE_QUEUE_CAPACITY);
    let _ = try_send_sse(
        &sender,
        sse_frame(
            "meta",
            &json!({
                "projectId": prepared.project.id,
                "sessionId": prepared.session_id,
                "runId": prepared.run_id,
            }),
        ),
    );

    let (heartbeat_stop, heartbeat_done) = mpsc::channel::<()>();
    let heartbeat_sender = sender.clone();
    let heartbeat_registry = app
        .state::<agent::cancel::AgentCancellationRegistry>()
        .inner()
        .clone();
    let heartbeat_project = prepared.project.id.clone();
    let heartbeat_session = prepared.session_id.clone();
    let heartbeat_run = prepared.run_id.clone();
    thread::spawn(move || loop {
        match heartbeat_done.recv_timeout(SSE_HEARTBEAT_INTERVAL) {
            Ok(_) | Err(mpsc::RecvTimeoutError::Disconnected) => break,
            Err(mpsc::RecvTimeoutError::Timeout) => {
                match try_send_sse(&heartbeat_sender, b": keepalive\n\n".to_vec()) {
                    SseSendResult::Disconnected => {
                        heartbeat_registry.cancel(
                            &heartbeat_project,
                            &heartbeat_session,
                            Some(&heartbeat_run),
                        );
                        break;
                    }
                    SseSendResult::Sent | SseSendResult::Full => {}
                }
            }
        }
    });

    let task_app = app.clone();
    tauri::async_runtime::spawn(async move {
        let event_sender = sender.clone();
        let registry = task_app
            .state::<agent::cancel::AgentCancellationRegistry>()
            .inner()
            .clone();
        let cancel_project = prepared.project.id.clone();
        let cancel_session = prepared.session_id.clone();
        let cancel_run = prepared.run_id.clone();
        let sink: agent::runtime::AgentEventSink = std::sync::Arc::new(move |mut event| {
            event.redact_for_external_api();
            let payload = serde_json::to_value(event)
                .unwrap_or_else(|err| json!({ "type": "error", "message": err.to_string() }));
            match try_send_sse(&event_sender, sse_frame("agent", &payload)) {
                SseSendResult::Disconnected => {
                    registry.cancel(&cancel_project, &cancel_session, Some(&cancel_run));
                }
                // Intermediate events may be dropped for a temporarily slow
                // client. The terminal `done` frame still carries the complete
                // aggregate response, so correctness is preserved.
                SseSendResult::Sent | SseSendResult::Full => {}
            }
        });
        let result =
            std::panic::AssertUnwindSafe(prepared.runtime.run_once_with_cancel_and_events(
                std::mem::take(&mut prepared.request),
                prepared.cancellation.take(),
                Some(sink),
            ))
            .catch_unwind()
            .await;
        task_app
            .state::<agent::cancel::AgentCancellationRegistry>()
            .finish(&prepared.project.id, &prepared.session_id, &prepared.run_id);
        match result {
            Ok(Ok(response)) => {
                persist_chat_response(&task_app, &prepared, &response);
                send_terminal_sse(
                    sender.clone(),
                    sse_frame("done", &external_chat_response(response)),
                );
            }
            Ok(Err(message)) => {
                let event = if message == "Agent turn cancelled" {
                    "cancelled"
                } else {
                    "error"
                };
                send_terminal_sse(
                    sender.clone(),
                    sse_frame(event, &json!({ "ok": false, "error": message })),
                );
            }
            Err(_) => {
                send_terminal_sse(
                    sender.clone(),
                    sse_frame(
                        "error",
                        &json!({ "ok": false, "error": "Agent chat task panicked" }),
                    ),
                );
            }
        }
        let _ = heartbeat_stop.send(());
    });

    let mut response = Response::new(
        StatusCode(200),
        vec![
            Header::from_bytes("Content-Type", "text/event-stream; charset=utf-8").unwrap(),
            Header::from_bytes("Cache-Control", "no-cache, no-transform").unwrap(),
            Header::from_bytes("X-Accel-Buffering", "no").unwrap(),
        ],
        SseReader::new(receiver),
        None,
        None,
    );
    for header in cors_headers(origin) {
        response.add_header(header);
    }
    let _ = request.respond(response);
}

fn handle_cancel_chat(app: &AppHandle, project_id: &str, session_id: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    ok(json!({
        "ok": true,
        "cancelled": app
            .state::<agent::cancel::AgentCancellationRegistry>()
            .cancel(&project.id, session_id, None),
        "sessionId": session_id,
    }))
}

fn load_embedding_config(app: &AppHandle) -> Option<commands::search::SearchEmbeddingConfig> {
    let parsed = load_app_state(app)?;
    let value = parsed.get("embeddingConfig")?.clone();
    serde_json::from_value::<commands::search::SearchEmbeddingConfig>(value).ok()
}

#[derive(Debug, Clone, Default)]
struct AgentRuntimeConfig {
    embedding: Option<commands::search::SearchEmbeddingConfig>,
    llm: Option<agent::provider::LlmConfig>,
    web_search: Option<agent::tools::WebSearchConfig>,
    anytxt: Option<agent::tools::AnyTxtConfig>,
}

fn project_llm_config(parsed: &Value, project_id: &str) -> Option<agent::provider::LlmConfig> {
    let global = parsed.get("llmConfig").cloned();
    let Some(project) = parsed
        .get("projectLlmOverrides")
        .and_then(|value| value.get(project_id))
    else {
        return global.and_then(|value| serde_json::from_value(value).ok());
    };
    if project.get("enabled").and_then(Value::as_bool) != Some(true) {
        return global.and_then(|value| serde_json::from_value(value).ok());
    }

    // The frontend persists a resolved, non-secret profile. Merge the current
    // provider override here so credential rotation and endpoint edits apply to
    // native API calls without duplicating API keys in every project record.
    let mut profile = project.get("profile")?.clone();
    let profile_object = profile.as_object_mut()?;
    let preset_id = project.get("presetId").and_then(Value::as_str)?;
    let provider = parsed
        .get("providerConfigs")
        .and_then(|value| value.get(preset_id))
        .and_then(Value::as_object);
    // `customLlmPresets` is the authoritative registry. A stale providerConfigs
    // entry may survive an interrupted multi-key settings save, so credentials
    // alone must not resurrect a deleted custom preset.
    let custom_preset_exists = parsed
        .get("customLlmPresets")
        .and_then(Value::as_array)
        .map(|presets| {
            presets
                .iter()
                .any(|preset| preset.get("id").and_then(Value::as_str) == Some(preset_id))
        })
        .unwrap_or(false);
    // Match resolveProjectLlmConfig in src/lib/llm-task-routing.ts: deleting a
    // custom preset must make every project that referenced it fall back to
    // the global config, including projects that are not currently open.
    if preset_id.starts_with("custom-") && !custom_preset_exists {
        return global.and_then(|value| serde_json::from_value(value).ok());
    }
    if let Some(provider) = provider {
        for key in [
            "apiKey",
            "apiMode",
            "azureApiVersion",
            "maxContextSize",
            "reasoning",
            "streamingEnabled",
            "customHeaders",
            "extraRequestBody",
        ] {
            if let Some(value) = provider.get(key) {
                profile_object.insert(key.to_string(), value.clone());
            }
        }
        if project
            .get("model")
            .and_then(Value::as_str)
            .map(str::trim)
            .unwrap_or("")
            .is_empty()
        {
            if let Some(value) = provider.get("model") {
                profile_object.insert("model".to_string(), value.clone());
            }
        }
        if let Some(value) = provider.get("baseUrl") {
            let endpoint_key =
                if profile_object.get("provider").and_then(Value::as_str) == Some("ollama") {
                    "ollamaUrl"
                } else {
                    "customEndpoint"
                };
            profile_object.insert(endpoint_key.to_string(), value.clone());
        }
    }
    serde_json::from_value(profile).ok()
}

fn load_agent_runtime_config(app: &AppHandle, project_id: Option<&str>) -> AgentRuntimeConfig {
    let Some(parsed) = load_app_state(app) else {
        return AgentRuntimeConfig::default();
    };
    AgentRuntimeConfig {
        embedding: parsed
            .get("embeddingConfig")
            .cloned()
            .and_then(|value| serde_json::from_value(value).ok()),
        llm: project_id
            .and_then(|id| project_llm_config(&parsed, id))
            .or_else(|| {
                parsed
                    .get("llmConfig")
                    .cloned()
                    .and_then(|value| serde_json::from_value(value).ok())
            }),
        web_search: parsed
            .get("searchApiConfig")
            .cloned()
            .and_then(|value| serde_json::from_value(value).ok()),
        anytxt: parsed
            .get("searchApiConfig")
            .and_then(|value| value.get("anyTxt"))
            .cloned()
            .and_then(|value| serde_json::from_value(value).ok()),
    }
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct ApiGraphNode {
    id: String,
    label: String,
    node_type: String,
    path: String,
    link_count: usize,
}

#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct ApiGraphEdge {
    source: String,
    target: String,
    weight: f64,
}

struct GraphPage {
    nodes: Vec<ApiGraphNode>,
    edges: Vec<ApiGraphEdge>,
    total_count: usize,
    has_more: bool,
}

fn handle_graph(app: &AppHandle, project_id: &str, query: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    let params = parse_query(query);
    let q = params.get("q").map(|s| s.to_lowercase());
    let node_type = params.get("nodeType").map(|s| s.to_lowercase());
    let paged_edges = match params.get("edgeScope").map(String::as_str) {
        Some("filtered") => true,
        Some("page") | None => false,
        Some(_) => return err(400, "edgeScope must be 'page' or 'filtered'"),
    };
    let offset = match params.get("offset") {
        Some(value) => match value.parse::<usize>() {
            Ok(value) => value,
            Err(_) => return err(400, "offset must be a non-negative integer"),
        },
        None => 0,
    };
    let limit = match params.get("limit") {
        Some(value) => match value.parse::<usize>() {
            Ok(value) if value > 0 => value.clamp(1, 1000),
            _ => return err(400, "limit must be a positive integer"),
        },
        None => 200,
    };

    match load_graph(&project.path) {
        Ok(graph) => {
            let page = select_graph_page(
                &graph.nodes,
                &graph.edges,
                q.as_deref(),
                node_type.as_deref(),
                offset,
                limit,
                paged_edges,
            );
            ok(json!({
                "ok": true,
                "projectId": project.id,
                "nodes": page.nodes,
                "edges": page.edges,
                "offset": offset,
                "limit": limit,
                "totalCount": page.total_count,
                "hasMore": page.has_more,
            }))
        }
        Err(e) => err(500, e),
    }
}

fn select_graph_page(
    nodes: &[ApiGraphNode],
    edges: &[ApiGraphEdge],
    q: Option<&str>,
    node_type: Option<&str>,
    offset: usize,
    limit: usize,
    paged_edges: bool,
) -> GraphPage {
    let matches = |node: &&ApiGraphNode| {
        q.is_none_or(|q| {
            node.id.to_lowercase().contains(q) || node.label.to_lowercase().contains(q)
        }) && node_type.is_none_or(|node_type| node.node_type == node_type)
    };
    let total_count = nodes.iter().filter(matches).count();
    let filtered_ids = paged_edges.then(|| {
        nodes
            .iter()
            .filter(matches)
            .map(|node| node.id.clone())
            .collect::<BTreeSet<_>>()
    });
    let nodes: Vec<ApiGraphNode> = nodes
        .iter()
        .filter(matches)
        .skip(offset)
        .take(limit)
        .cloned()
        .collect();
    let page_ids: BTreeSet<String> = nodes.iter().map(|node| node.id.clone()).collect();
    let edges = edges
        .iter()
        .filter(|edge| {
            if paged_edges {
                page_ids.contains(&edge.source)
                    && filtered_ids
                        .as_ref()
                        .is_some_and(|ids| ids.contains(&edge.target))
            } else {
                page_ids.contains(&edge.source) && page_ids.contains(&edge.target)
            }
        })
        .cloned()
        .collect();
    let has_more = offset.saturating_add(nodes.len()) < total_count;
    GraphPage {
        nodes,
        edges,
        total_count,
        has_more,
    }
}

fn load_graph(project_path: &str) -> Result<Arc<CachedGraph>, String> {
    let cache = GRAPH_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
    let cached = cache.lock().ok().and_then(|cache| {
        cache
            .get(project_path)
            .filter(|entry| entry.loaded_at.elapsed() < GRAPH_CACHE_TTL)
            .cloned()
    });
    if let Some(entry) = cached {
        return Ok(entry);
    }

    let (fingerprint, files) = graph_files(project_path)?;
    let cached = cache.lock().ok().and_then(|cache| {
        cache
            .get(project_path)
            .filter(|entry| entry.fingerprint == fingerprint)
            .cloned()
    });
    if let Some(entry) = cached {
        return Ok(entry);
    }

    let (nodes, edges) = build_graph_from_files(project_path, &files)?;
    let graph = Arc::new(CachedGraph {
        loaded_at: Instant::now(),
        fingerprint,
        nodes,
        edges,
    });
    if let Ok(mut cache) = cache.lock() {
        cache.retain(|_, entry| entry.loaded_at.elapsed() < GRAPH_CACHE_TTL);
        if cache.len() >= GRAPH_CACHE_MAX_PROJECTS && !cache.contains_key(project_path) {
            if let Some(oldest) = cache
                .iter()
                .min_by_key(|(_, entry)| entry.loaded_at)
                .map(|(path, _)| path.clone())
            {
                cache.remove(&oldest);
            }
        }
        cache.insert(project_path.to_string(), Arc::clone(&graph));
    }
    Ok(graph)
}

fn graph_files(project_path: &str) -> Result<(u64, Vec<PathBuf>), String> {
    let wiki_root = Path::new(project_path).join("wiki");
    let mut files = Vec::new();
    for entry in WalkDir::new(&wiki_root).into_iter().filter_map(Result::ok) {
        if entry.file_type().is_file()
            && entry
                .path()
                .extension()
                .and_then(|value| value.to_str())
                .is_some_and(|value| value.eq_ignore_ascii_case("md"))
        {
            files.push(entry.into_path());
        }
    }
    files.sort();

    let mut hasher = DefaultHasher::new();
    for path in &files {
        path.hash(&mut hasher);
        if let Ok(metadata) = fs::metadata(path) {
            metadata.len().hash(&mut hasher);
            metadata.modified().ok().hash(&mut hasher);
        }
    }
    Ok((hasher.finish(), files))
}

#[cfg(test)]
fn build_graph(project_path: &str) -> Result<(Vec<ApiGraphNode>, Vec<ApiGraphEdge>), String> {
    let (_, files) = graph_files(project_path)?;
    build_graph_from_files(project_path, &files)
}

fn build_graph_from_files(
    project_path: &str,
    files: &[PathBuf],
) -> Result<(Vec<ApiGraphNode>, Vec<ApiGraphEdge>), String> {
    let wiki_root = Path::new(project_path).join("wiki");
    let mut stem_counts = HashMap::new();
    for path in files {
        if let Some(stem) = path.file_stem().and_then(|value| value.to_str()) {
            *stem_counts.entry(stem.to_string()).or_insert(0usize) += 1;
        }
    }
    let mut raw: BTreeMap<String, (String, String, String, Vec<String>)> = BTreeMap::new();
    for path in files {
        let content = match fs::read_to_string(path) {
            Ok(content) => content,
            Err(_) => continue,
        };
        let relative_id = wiki_page_id(&wiki_root, path);
        let stem = path
            .file_stem()
            .and_then(|value| value.to_str())
            .unwrap_or("");
        let id = if stem_counts.get(stem) == Some(&1) {
            stem.to_string()
        } else {
            relative_id
        };
        if id.is_empty() {
            continue;
        }
        let fallback_name = path
            .file_name()
            .and_then(|value| value.to_str())
            .unwrap_or("");
        let title = commands::search::extract_title(&content, fallback_name);
        let node_type = extract_type(&content);
        let relative_path = relative_to_project(project_path, path);
        let links = commands::search::extract_graph_links(&content);
        raw.insert(id, (title, node_type, relative_path, links));
    }
    // Query pages are intermediate artifacts rather than graph nodes. Remove
    // them before link resolution so the API cannot emit edges whose source
    // or target is absent from the returned node set.
    raw.retain(|_, (_, node_type, _, _)| node_type != "query");
    let aliases = graph_aliases(&raw);
    let mut link_count: BTreeMap<String, usize> = raw.keys().map(|id| (id.clone(), 0)).collect();
    let mut seen = BTreeSet::new();
    let mut edges = Vec::new();
    for (source, (_, _, _, links)) in &raw {
        for link in links {
            let Some(target) = resolve_link(link, &aliases) else {
                continue;
            };
            if &target == source {
                continue;
            }
            let key = if source < &target {
                format!("{source}::{target}")
            } else {
                format!("{target}::{source}")
            };
            if seen.insert(key) {
                *link_count.entry(source.clone()).or_default() += 1;
                *link_count.entry(target.clone()).or_default() += 1;
                edges.push(ApiGraphEdge {
                    source: source.clone(),
                    target,
                    weight: 1.0,
                });
            }
        }
    }
    let nodes = raw
        .into_iter()
        .map(|(id, (label, node_type, path, _))| ApiGraphNode {
            link_count: *link_count.get(&id).unwrap_or(&0),
            id,
            label,
            node_type,
            path,
        })
        .collect();
    Ok((nodes, edges))
}

fn wiki_page_id(wiki_root: &Path, path: &Path) -> String {
    path.strip_prefix(wiki_root)
        .unwrap_or(path)
        .with_extension("")
        .to_string_lossy()
        .replace('\\', "/")
}

struct GraphAliases {
    exact_ids: HashMap<String, String>,
    ids: HashMap<String, Option<String>>,
    stems: HashMap<String, Option<String>>,
    titles: HashMap<String, Option<String>>,
}

fn graph_aliases(raw: &BTreeMap<String, (String, String, String, Vec<String>)>) -> GraphAliases {
    let mut aliases = GraphAliases {
        exact_ids: HashMap::new(),
        ids: HashMap::new(),
        stems: HashMap::new(),
        titles: HashMap::new(),
    };
    for (id, (title, _, path, _)) in raw {
        aliases.exact_ids.insert(id.clone(), id.clone());
        insert_graph_alias(&mut aliases.ids, name_alias_keys(id), id);
        let canonical_path = path
            .strip_prefix("wiki/")
            .unwrap_or(path)
            .trim_end_matches(".md");
        insert_graph_alias(&mut aliases.ids, name_alias_keys(canonical_path), id);
        if let Some(stem) = id.rsplit('/').next() {
            insert_graph_alias(&mut aliases.stems, name_alias_keys(stem), id);
        }
        insert_graph_alias(&mut aliases.titles, name_alias_keys(title), id);
    }
    aliases
}

fn insert_graph_alias(aliases: &mut HashMap<String, Option<String>>, keys: Vec<String>, id: &str) {
    for key in keys {
        match aliases.get(&key) {
            None => {
                aliases.insert(key, Some(id.to_string()));
            }
            Some(Some(existing)) if existing != id => {
                aliases.insert(key, None);
            }
            _ => {}
        }
    }
}

fn link_alias_keys(raw: &str) -> Vec<String> {
    let target = raw
        .split('|')
        .next()
        .unwrap_or("")
        .split('#')
        .next()
        .unwrap_or("")
        .trim();
    name_alias_keys(target)
}

fn name_alias_keys(raw: &str) -> Vec<String> {
    let normalized = raw.trim().replace('\\', "/").to_lowercase();
    let normalized = normalized.trim_matches('/');
    let normalized = normalized.strip_prefix("./").unwrap_or(normalized);
    let normalized = normalized.strip_prefix("wiki/").unwrap_or(normalized);
    let normalized = if normalized.ends_with(".md") {
        &normalized[..normalized.len() - 3]
    } else {
        normalized
    };
    if normalized.is_empty() {
        return Vec::new();
    }
    let slugged = normalized.replace(' ', "-");
    if slugged == normalized {
        vec![normalized.to_string()]
    } else {
        vec![normalized.to_string(), slugged]
    }
}

fn extract_type(content: &str) -> String {
    for line in content.lines() {
        if let Some(value) = line.trim().strip_prefix("type:") {
            return value
                .trim()
                .trim_matches('"')
                .trim_matches('\'')
                .to_lowercase();
        }
    }
    "other".to_string()
}

fn resolve_link(raw: &str, aliases: &GraphAliases) -> Option<String> {
    let exact = raw
        .split('|')
        .next()
        .unwrap_or("")
        .split('#')
        .next()
        .unwrap_or("")
        .trim();
    if let Some(id) = aliases.exact_ids.get(exact) {
        return Some(id.clone());
    }
    let keys = link_alias_keys(raw);
    for tier in [&aliases.ids, &aliases.stems, &aliases.titles] {
        for key in &keys {
            if let Some(resolved) = tier.get(key) {
                return resolved.clone();
            }
        }
    }
    None
}

fn invalidate_graph_cache(project_path: &str) {
    if let Some(cache) = GRAPH_CACHE.get() {
        if let Ok(mut cache) = cache.lock() {
            cache.remove(project_path);
        }
    }
}

fn handle_rescan(app: &AppHandle, project_id: &str) -> ApiResponse {
    let project = match resolve_project(app, project_id) {
        Ok(project) => project,
        Err(e) => return err(404, e),
    };
    invalidate_graph_cache(&project.path);
    let source_watch_config = load_source_watch_config(app, &project.id);
    match commands::file_sync::rescan_project_files(
        app.clone(),
        project.id.clone(),
        project.path.clone(),
        source_watch_config,
        None,
    ) {
        Ok(result) => ok(json!({ "ok": true, "projectId": project.id, "result": result })),
        Err(e) => err(500, e),
    }
}

fn load_source_watch_config(
    app: &AppHandle,
    project_id: &str,
) -> Option<commands::file_sync::SourceWatchConfig> {
    let parsed = load_app_state(app)?;
    let settings = parsed.get("sourceWatchConfig").and_then(Value::as_object);
    if let Some(value) = settings
        .and_then(|s| s.get(project_id).or_else(|| s.get("default")))
        .cloned()
    {
        if let Ok(config) = serde_json::from_value::<commands::file_sync::SourceWatchConfig>(value)
        {
            return Some(config);
        }
    }
    let legacy_enabled = parsed
        .get("projectFileSyncEnabled")
        .and_then(Value::as_object)
        .and_then(|settings| {
            settings
                .get(project_id)
                .or_else(|| settings.get("default"))
                .and_then(Value::as_bool)
        });
    legacy_enabled.and_then(|enabled| {
        serde_json::from_value::<commands::file_sync::SourceWatchConfig>(
            json!({ "enabled": enabled }),
        )
        .ok()
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::time::{SystemTime, UNIX_EPOCH};

    fn test_project_dir() -> PathBuf {
        // Per-process atomic sequence appended to the timestamp so two
        // tests calling this concurrently can't collide on the same dir
        // (nanos alone are not unique enough under parallel `cargo test`,
        // which would let one test's remove_dir_all delete another's files).
        use std::sync::atomic::{AtomicU64, Ordering};
        static COUNTER: AtomicU64 = AtomicU64::new(0);
        let id = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_nanos();
        let seq = COUNTER.fetch_add(1, Ordering::Relaxed);
        let path = std::env::temp_dir().join(format!("llm-wiki-api-test-{id}-{seq}"));
        fs::create_dir_all(path.join("wiki")).unwrap();
        path
    }

    #[test]
    fn safe_join_rejects_traversal() {
        let root = test_project_dir();
        let root_str = root.to_string_lossy();
        assert!(safe_join(&root_str, "../secret.md").is_err());
        assert!(safe_join(&root_str, "wiki/../../secret.md").is_err());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn safe_join_accepts_project_relative_paths() {
        let root = test_project_dir();
        let root_str = root.to_string_lossy();
        let joined = safe_join(&root_str, "wiki/index.md").unwrap();
        assert_eq!(joined, root.join("wiki/index.md"));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_uses_relative_slugs_and_resolves_path_links() {
        let root = test_project_dir();
        fs::create_dir_all(root.join("wiki/topic")).unwrap();
        fs::write(
            root.join("wiki/index.md"),
            "---\ntype: overview\n---\n# Index\n[[topic/Detail Page.md#section|Detail]]",
        )
        .unwrap();
        fs::write(
            root.join("wiki/topic/Detail Page.md"),
            "---\ntype: entity\n---\n# Detail Page",
        )
        .unwrap();

        let (nodes, edges) = build_graph(root.to_string_lossy().as_ref()).unwrap();
        assert!(nodes.iter().any(|node| node.id == "Detail Page"));
        assert!(edges
            .iter()
            .any(|edge| { edge.source == "index" && edge.target == "Detail Page" }));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_includes_frontmatter_related_links() {
        let root = test_project_dir();
        fs::write(
            root.join("wiki/source.md"),
            "---\nrelated: [target]\n---\n# Source",
        )
        .unwrap();
        fs::write(root.join("wiki/target.md"), "# Target").unwrap();

        let (_, edges) = build_graph(root.to_string_lossy().as_ref()).unwrap();
        assert!(edges
            .iter()
            .any(|edge| edge.source == "source" && edge.target == "target"));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_drops_edges_to_hidden_query_pages() {
        let root = test_project_dir();
        fs::write(
            root.join("wiki/source.md"),
            "---\nrelated: [hidden]\n---\n# Source",
        )
        .unwrap();
        fs::write(
            root.join("wiki/hidden.md"),
            "---\ntype: query\n---\n# Hidden\n[[source]]",
        )
        .unwrap();

        let (nodes, edges) = build_graph(root.to_string_lossy().as_ref()).unwrap();
        assert!(nodes.iter().all(|node| node.id != "hidden"));
        assert!(edges.is_empty());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_does_not_resolve_ambiguous_bare_stems() {
        let root = test_project_dir();
        fs::create_dir_all(root.join("wiki/a")).unwrap();
        fs::create_dir_all(root.join("wiki/b")).unwrap();
        fs::write(root.join("wiki/index.md"), "# Index\n[[same]]").unwrap();
        fs::write(root.join("wiki/a/same.md"), "# A").unwrap();
        fs::write(root.join("wiki/b/same.md"), "# B").unwrap();

        let (nodes, edges) = build_graph(root.to_string_lossy().as_ref()).unwrap();
        assert_eq!(nodes.len(), 3);
        assert!(nodes.iter().any(|node| node.id == "a/same"));
        assert!(nodes.iter().any(|node| node.id == "b/same"));
        assert!(edges.is_empty());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_exact_id_wins_over_a_colliding_title() {
        let root = test_project_dir();
        fs::write(root.join("wiki/index.md"), "# Home").unwrap();
        fs::write(root.join("wiki/glossary.md"), "# Index\n[[index]]").unwrap();

        let (_, edges) = build_graph(root.to_string_lossy().as_ref()).unwrap();
        assert_eq!(edges.len(), 1);
        assert_eq!(edges[0].target, "index");
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn graph_exact_id_wins_over_a_normalized_id_collision() {
        let mut raw = BTreeMap::new();
        for id in ["Machine Learning", "machine-learning"] {
            raw.insert(
                id.to_string(),
                (
                    id.to_string(),
                    "entity".to_string(),
                    format!("wiki/{id}.md"),
                    vec![],
                ),
            );
        }
        let aliases = graph_aliases(&raw);
        assert_eq!(
            resolve_link("Machine Learning", &aliases).as_deref(),
            Some("Machine Learning")
        );
        assert_eq!(
            resolve_link("machine-learning", &aliases).as_deref(),
            Some("machine-learning")
        );
    }

    #[test]
    fn graph_link_normalization_accepts_common_path_forms() {
        let mut raw = BTreeMap::new();
        raw.insert(
            "Page".to_string(),
            (
                "Display Title".to_string(),
                "entity".to_string(),
                "wiki/Page.md".to_string(),
                vec![],
            ),
        );
        let aliases = graph_aliases(&raw);
        for link in [
            "./Page",
            "wiki/Page",
            "/wiki/Page",
            "Page.MD",
            "Display Title",
        ] {
            assert_eq!(
                resolve_link(link, &aliases).as_deref(),
                Some("Page"),
                "{link}"
            );
        }
    }

    #[test]
    fn graph_pagination_can_be_merged_without_losing_edges() {
        let nodes = ["a", "b", "c"]
            .into_iter()
            .map(|id| ApiGraphNode {
                id: id.to_string(),
                label: id.to_string(),
                node_type: "entity".to_string(),
                path: format!("wiki/{id}.md"),
                link_count: 1,
            })
            .collect::<Vec<_>>();
        let edges = vec![
            ApiGraphEdge {
                source: "a".to_string(),
                target: "c".to_string(),
                weight: 1.0,
            },
            ApiGraphEdge {
                source: "b".to_string(),
                target: "c".to_string(),
                weight: 1.0,
            },
        ];

        let first = select_graph_page(&nodes, &edges, None, None, 0, 2, true);
        let second = select_graph_page(&nodes, &edges, None, None, 2, 2, true);
        assert_eq!(first.nodes.len(), 2);
        assert_eq!(first.total_count, 3);
        assert!(first.has_more);
        assert_eq!(second.nodes.len(), 1);
        assert!(!second.has_more);
        assert_eq!(first.edges.len() + second.edges.len(), 2);
    }

    #[test]
    fn graph_legacy_response_keeps_edge_endpoints_in_the_node_page() {
        let nodes = ["a", "b", "c"]
            .into_iter()
            .map(|id| ApiGraphNode {
                id: id.to_string(),
                label: id.to_string(),
                node_type: "entity".to_string(),
                path: format!("wiki/{id}.md"),
                link_count: 1,
            })
            .collect::<Vec<_>>();
        let edges = vec![ApiGraphEdge {
            source: "a".to_string(),
            target: "c".to_string(),
            weight: 1.0,
        }];
        let page = select_graph_page(&nodes, &edges, None, None, 0, 2, false);
        assert!(page.edges.is_empty());
    }

    #[test]
    fn graph_cache_invalidates_when_a_page_changes() {
        let root = test_project_dir();
        let page = root.join("wiki/page.md");
        fs::write(&page, "# Before").unwrap();
        let before = load_graph(root.to_string_lossy().as_ref()).unwrap();
        assert_eq!(before.nodes[0].label, "Before");
        let cached = load_graph(root.to_string_lossy().as_ref()).unwrap();
        assert!(Arc::ptr_eq(&before, &cached));

        fs::write(&page, "# After with a different length").unwrap();
        invalidate_graph_cache(root.to_string_lossy().as_ref());
        let after = load_graph(root.to_string_lossy().as_ref()).unwrap();
        assert_eq!(after.nodes[0].label, "After with a different length");
        assert!(!Arc::ptr_eq(&before, &after));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn query_parser_decodes_percent_and_plus() {
        let parsed = parse_query("path=wiki%2Fhello+world.md&token=a%2Bb");
        assert_eq!(parsed.get("path").unwrap(), "wiki/hello world.md");
        assert_eq!(parsed.get("token").unwrap(), "a+b");
    }

    #[test]
    fn snippet_handles_unicode_boundaries() {
        let content = "前言。这里是关于知识图谱过滤的中文内容。后续说明。";
        let snippet = commands::search::build_snippet(content, "知识图谱");
        assert!(snippet.contains("知识图谱"));
    }

    #[test]
    fn public_api_paths_exclude_internal_state() {
        assert!(is_public_project_rel("wiki/index.md"));
        assert!(is_public_project_rel("Wiki/index.md"));
        assert!(is_public_project_rel("raw/sources/source.md"));
        assert!(is_public_project_rel("Raw/Sources/source.md"));
        assert!(!is_public_project_rel(".llm-wiki/file-change-queue.json"));
        assert!(!is_public_project_rel("wiki/.draft.md"));
    }

    #[test]
    fn review_query_defaults_to_unresolved_items() {
        let root = test_project_dir();
        let state_dir = root.join(".llm-wiki");
        fs::create_dir_all(&state_dir).unwrap();
        fs::write(
            state_dir.join("review.json"),
            json!([
                {
                    "id": "r1",
                    "type": "missing-page",
                    "title": "Missing page: Attention",
                    "description": "Add Attention",
                    "options": [],
                    "resolved": false,
                    "createdAt": 1,
                    "internalSecret": "do-not-expose"
                },
                {
                    "id": "r2",
                    "type": "duplicate",
                    "title": "Duplicate: LLM",
                    "description": "Merge pages",
                    "options": [],
                    "resolved": true,
                    "createdAt": 2
                }
            ])
            .to_string(),
        )
        .unwrap();

        let query = parse_review_query("").unwrap();
        let reviews = load_review_items(root.to_str().unwrap(), &query).unwrap();

        assert_eq!(query.status.as_str(), "unresolved");
        assert_eq!(reviews.len(), 1);
        assert_eq!(
            reviews[0].get("id").and_then(Value::as_str),
            Some(review_id_for_parts("missing-page", "Missing page: Attention").as_str())
        );
        assert!(reviews[0].get("internalSecret").is_none());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn review_title_normalization_requires_a_prefix_delimiter() {
        assert_eq!(
            normalize_review_title("Missing page: Attention"),
            "attention"
        );
        assert_eq!(
            normalize_review_title(" Missing page: Attention"),
            "attention"
        );
        assert_eq!(
            normalize_review_title("Missing page Attention"),
            "missing page attention"
        );
        assert_eq!(normalize_review_title("疑似重复 注意力"), "疑似重复 注意力");
        assert_ne!(
            review_id_for_parts("missing-page", "Missing page: Attention"),
            review_id_for_parts("missing-page", "Missing page Attention")
        );
        assert_eq!(
            review_id_for_parts("missing-page", "Missing page: Attention"),
            "review-dbdcf949"
        );
        assert_eq!(
            review_id_for_parts("missing-page", " Missing page: Attention"),
            "review-dbdcf949"
        );
        assert_eq!(
            review_id_for_parts("missing-page", "Missing page Attention"),
            "review-fa5d9960"
        );
        assert_eq!(
            review_id_for_parts("missing-page", "疑似重复 注意力"),
            "review-d2dacda0"
        );
    }

    #[test]
    fn review_query_filters_by_type_status_and_limit() {
        let root = test_project_dir();
        let state_dir = root.join(".llm-wiki");
        fs::create_dir_all(&state_dir).unwrap();
        fs::write(
            state_dir.join("review.json"),
            json!([
                { "id": "r1", "type": "missing-page", "title": "r1", "resolved": false, "createdAt": 1 },
                { "id": "r2", "type": "missing-page", "title": "r2", "resolved": false, "createdAt": 2 },
                { "id": "r3", "type": "duplicate", "resolved": false, "createdAt": 3 },
                { "id": "r4", "type": "missing-page", "resolved": true, "createdAt": 4 }
            ])
            .to_string(),
        )
        .unwrap();

        let query = parse_review_query("status=all&type=missing-page&limit=2").unwrap();
        let reviews = load_review_items(root.to_str().unwrap(), &query).unwrap();

        assert_eq!(query.status.as_str(), "all");
        assert_eq!(
            reviews
                .iter()
                .filter_map(|r| r.get("id").and_then(Value::as_str))
                .map(str::to_string)
                .collect::<Vec<_>>(),
            vec![
                review_id_for_parts("missing-page", "r1"),
                review_id_for_parts("missing-page", "r2"),
            ]
        );
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn review_query_collapses_legacy_duplicate_ids_to_stable_id() {
        let root = test_project_dir();
        let state_dir = root.join(".llm-wiki");
        fs::create_dir_all(&state_dir).unwrap();
        fs::write(
            state_dir.join("review.json"),
            json!([
                {
                    "id": "review-1",
                    "type": "missing-page",
                    "title": "Attention",
                    "description": "",
                    "affectedPages": ["a.md"],
                    "resolved": false,
                    "createdAt": 5
                },
                {
                    "id": "review-2",
                    "type": "missing-page",
                    "title": "Missing page: Attention",
                    "description": "resolved copy",
                    "affectedPages": ["b.md"],
                    "resolved": true,
                    "resolvedAction": "user-resolved",
                    "createdAt": 2
                }
            ])
            .to_string(),
        )
        .unwrap();

        let query = parse_review_query("status=all").unwrap();
        let reviews = load_review_items(root.to_str().unwrap(), &query).unwrap();

        assert_eq!(reviews.len(), 1);
        assert_eq!(
            reviews[0].get("id").and_then(Value::as_str),
            Some(review_id_for_parts("missing-page", "Attention").as_str())
        );
        assert_eq!(
            reviews[0].get("resolved").and_then(Value::as_bool),
            Some(true)
        );
        assert_eq!(
            reviews[0].get("resolvedAction").and_then(Value::as_str),
            Some("user-resolved")
        );
        assert_eq!(
            reviews[0]
                .get("affectedPages")
                .and_then(Value::as_array)
                .map(|pages| pages.iter().filter_map(Value::as_str).collect::<Vec<_>>()),
            Some(vec!["a.md", "b.md"])
        );
        assert_eq!(
            reviews[0].get("createdAt").and_then(Value::as_f64),
            Some(2.0)
        );
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn review_query_filters_status_after_stable_id_merge() {
        let root = test_project_dir();
        let state_dir = root.join(".llm-wiki");
        fs::create_dir_all(&state_dir).unwrap();
        fs::write(
            state_dir.join("review.json"),
            json!([
                {
                    "id": "review-old-unresolved",
                    "type": "missing-page",
                    "title": "Attention",
                    "resolved": false,
                    "createdAt": 5
                },
                {
                    "id": "review-old-resolved",
                    "type": "missing-page",
                    "title": "Missing page: Attention",
                    "resolved": true,
                    "resolvedAction": "Done",
                    "createdAt": 6
                }
            ])
            .to_string(),
        )
        .unwrap();

        let unresolved = parse_review_query("status=unresolved").unwrap();
        let unresolved_reviews = load_review_items(root.to_str().unwrap(), &unresolved).unwrap();
        assert!(unresolved_reviews.is_empty());

        let all = parse_review_query("status=all").unwrap();
        let all_reviews = load_review_items(root.to_str().unwrap(), &all).unwrap();
        assert_eq!(all_reviews.len(), 1);
        assert_eq!(
            all_reviews[0].get("resolved").and_then(Value::as_bool),
            Some(true)
        );
        let _ = fs::remove_dir_all(root);
    }

    fn write_reviews(root: &Path, value: Value) {
        let state_dir = root.join(".llm-wiki");
        fs::create_dir_all(&state_dir).unwrap();
        fs::write(state_dir.join("review.json"), value.to_string()).unwrap();
    }

    fn read_reviews(root: &Path) -> Value {
        let raw = fs::read_to_string(root.join(".llm-wiki/review.json")).unwrap();
        serde_json::from_str(&raw).unwrap()
    }

    #[test]
    fn patch_review_item_marks_resolved_and_preserves_unsanitized_fields() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([
                {
                    "id": "r1",
                    "type": "missing-page",
                    "resolved": false,
                    "createdAt": 1,
                    "internalSecret": "keep-me"
                },
                { "id": "r2", "type": "duplicate", "resolved": false, "createdAt": 2 }
            ]),
        );

        let found = patch_review_item(root.to_str().unwrap(), "r1", true, Some("Skip")).unwrap();
        assert!(found);

        // Re-read the RAW file: r1 must be resolved with the action label,
        // its non-sanitized `internalSecret` preserved (the write path must
        // not go through the sanitizing reader), and r2 left untouched.
        let parsed = read_reviews(&root);
        let items = parsed.as_array().unwrap();
        let r1 = items
            .iter()
            .find(|i| i.get("id").and_then(Value::as_str) == Some("r1"))
            .unwrap();
        assert_eq!(r1.get("resolved").and_then(Value::as_bool), Some(true));
        assert_eq!(
            r1.get("resolvedAction").and_then(Value::as_str),
            Some("Skip")
        );
        assert_eq!(
            r1.get("internalSecret").and_then(Value::as_str),
            Some("keep-me")
        );
        let r2 = items
            .iter()
            .find(|i| i.get("id").and_then(Value::as_str) == Some("r2"))
            .unwrap();
        assert_eq!(r2.get("resolved").and_then(Value::as_bool), Some(false));
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn patch_review_item_accepts_stable_id_for_legacy_counter_item() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([
                {
                    "id": "review-1",
                    "type": "missing-page",
                    "title": "Missing page: Attention",
                    "resolved": false
                }
            ]),
        );

        let stable_id = review_id_for_parts("missing-page", "Attention");
        let found =
            patch_review_item(root.to_str().unwrap(), &stable_id, true, Some("API")).unwrap();
        assert!(found);

        let parsed = read_reviews(&root);
        let item = &parsed.as_array().unwrap()[0];
        assert_eq!(
            item.get("id").and_then(Value::as_str),
            Some(stable_id.as_str())
        );
        assert_eq!(item.get("resolved").and_then(Value::as_bool), Some(true));
        assert_eq!(
            item.get("resolvedAction").and_then(Value::as_str),
            Some("API")
        );
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn patch_review_item_can_reopen_with_resolved_false() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([{ "id": "r1", "resolved": true, "resolvedAction": "Skip" }]),
        );

        let found = patch_review_item(root.to_str().unwrap(), "r1", false, None).unwrap();
        assert!(found);

        let parsed = read_reviews(&root);
        let r1 = &parsed.as_array().unwrap()[0];
        assert_eq!(r1.get("resolved").and_then(Value::as_bool), Some(false));
        assert!(r1.get("resolvedAction").is_none());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn patch_review_item_returns_false_for_unknown_id() {
        let root = test_project_dir();
        write_reviews(&root, json!([{ "id": "r1", "resolved": false }]));

        let found = patch_review_item(root.to_str().unwrap(), "nope", true, None).unwrap();
        assert!(!found);
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn patch_review_item_missing_file_returns_false() {
        let root = test_project_dir();
        let found = patch_review_item(root.to_str().unwrap(), "r1", true, None).unwrap();
        assert!(!found);
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn delete_review_item_removes_match_and_preserves_other_fields() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([
                { "id": "r1", "resolved": false, "internalSecret": "remove" },
                { "id": "r2", "resolved": false, "internalSecret": "keep" }
            ]),
        );

        assert!(delete_review_item(root.to_str().unwrap(), "r1").unwrap());
        let parsed = read_reviews(&root);
        let items = parsed.as_array().unwrap();
        assert_eq!(items.len(), 1);
        assert_eq!(items[0].get("id").and_then(Value::as_str), Some("r2"));
        assert_eq!(
            items[0].get("internalSecret").and_then(Value::as_str),
            Some("keep")
        );
        assert!(!delete_review_item(root.to_str().unwrap(), "missing").unwrap());
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn bulk_resolve_request_accepts_documented_review_ids_alias() {
        let request: BulkResolveRequest = serde_json::from_value(json!({
            "reviewIds": ["r1", "r2"],
            "action": "API"
        }))
        .unwrap();
        assert_eq!(request.ids, vec!["r1", "r2"]);
        assert_eq!(request.action.as_deref(), Some("API"));
    }

    #[test]
    fn resolve_review_items_bulk_resolves_matching_and_reports_not_found() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([
                { "id": "r1", "resolved": false, "internalSecret": "a" },
                { "id": "r2", "resolved": false },
                { "id": "r3", "resolved": false }
            ]),
        );

        let ids = vec!["r1".to_string(), "r3".to_string(), "missing".to_string()];
        let (resolved, not_found) =
            resolve_review_items(root.to_str().unwrap(), &ids, Some("Bulk")).unwrap();

        // Input order preserved; missing id reported, not 404'd.
        assert_eq!(resolved, vec!["r1".to_string(), "r3".to_string()]);
        assert_eq!(not_found, vec!["missing".to_string()]);

        let parsed = read_reviews(&root);
        let items = parsed.as_array().unwrap();
        let by_id = |id: &str| {
            items
                .iter()
                .find(|i| i.get("id").and_then(Value::as_str) == Some(id))
                .unwrap()
        };
        assert_eq!(
            by_id("r1").get("resolved").and_then(Value::as_bool),
            Some(true)
        );
        assert_eq!(
            by_id("r1").get("resolvedAction").and_then(Value::as_str),
            Some("Bulk")
        );
        // Unsanitized field survives the bulk write-back too.
        assert_eq!(
            by_id("r1").get("internalSecret").and_then(Value::as_str),
            Some("a")
        );
        assert_eq!(
            by_id("r3").get("resolved").and_then(Value::as_bool),
            Some(true)
        );
        // r2 was not in the request — untouched.
        assert_eq!(
            by_id("r2").get("resolved").and_then(Value::as_bool),
            Some(false)
        );
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn resolve_review_items_accepts_stable_ids_for_legacy_counter_items() {
        let root = test_project_dir();
        write_reviews(
            &root,
            json!([
                {
                    "id": "review-1",
                    "type": "missing-page",
                    "title": "Missing page: Attention",
                    "resolved": false
                },
                {
                    "id": "review-2",
                    "type": "duplicate",
                    "title": "Duplicate page: Transformer",
                    "resolved": false
                }
            ]),
        );

        let ids = vec![
            review_id_for_parts("missing-page", "Attention"),
            "missing".to_string(),
        ];
        let (resolved, not_found) =
            resolve_review_items(root.to_str().unwrap(), &ids, Some("Bulk")).unwrap();

        assert_eq!(resolved, vec![ids[0].clone()]);
        assert_eq!(not_found, vec!["missing".to_string()]);
        let parsed = read_reviews(&root);
        let items = parsed.as_array().unwrap();
        assert_eq!(
            items[0].get("id").and_then(Value::as_str),
            Some(ids[0].as_str())
        );
        assert_eq!(
            items[0].get("resolved").and_then(Value::as_bool),
            Some(true)
        );
        assert_eq!(items[1].get("id").and_then(Value::as_str), Some("review-2"));
        assert_eq!(
            items[1].get("resolved").and_then(Value::as_bool),
            Some(false)
        );
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn resolve_review_items_missing_file_reports_all_not_found() {
        let root = test_project_dir();
        let ids = vec!["r1".to_string(), "r2".to_string()];
        let (resolved, not_found) =
            resolve_review_items(root.to_str().unwrap(), &ids, None).unwrap();
        assert!(resolved.is_empty());
        assert_eq!(not_found, ids);
        let _ = fs::remove_dir_all(root);
    }

    #[test]
    fn project_path_match_normalizes_separators() {
        assert!(project_path_matches(
            "C:/Users/me/wiki",
            "C:\\Users\\me\\wiki"
        ));
        if cfg!(windows) {
            assert!(project_path_matches("C:/Users/me/wiki", "c:/users/me/wiki"));
        } else {
            assert!(!project_path_matches(
                "C:/Users/me/wiki",
                "c:/users/me/wiki"
            ));
        }
    }

    #[test]
    fn tokenize_keeps_single_cjk_character() {
        assert_eq!(
            crate::commands::search::tokenize_query("图"),
            Vec::<String>::new()
        );
        let tokens = crate::commands::search::tokenize_query("知识图谱");
        assert!(tokens.contains(&"知识".to_string()));
    }

    #[test]
    fn text_content_filter_rejects_binary_extensions() {
        assert!(is_text_content_rel("wiki/index.md"));
        assert!(!is_text_content_rel("wiki/media/image.png"));
        assert!(!is_text_content_rel("raw/sources/book.pdf"));
        assert!(!is_text_content_rel("raw/sources/notes.rtf"));
    }

    #[test]
    fn constant_time_eq_matches_equal_bytes_only() {
        assert!(constant_time_eq(b"token", b"token"));
        assert!(constant_time_eq(b"", b""));
        assert!(!constant_time_eq(b"token", b"tokeN"));
        assert!(!constant_time_eq(b"token", b"token-longer"));
    }

    #[test]
    fn rate_limit_skips_health_and_options_only() {
        assert!(!should_rate_limit(&Method::Get, "/api/v1/health"));
        assert!(!should_rate_limit(&Method::Options, "/api/v1/projects"));
        assert!(should_rate_limit(&Method::Get, "/wp-login"));
        assert!(should_rate_limit(
            &Method::Post,
            "/api/v1/projects/current/search"
        ));
    }

    #[test]
    fn chat_endpoint_allows_larger_multimodal_bodies() {
        assert_eq!(
            body_limit_for_request(&Method::Post, "/api/v1/projects/current/chat"),
            MAX_CHAT_BODY_BYTES
        );
        assert_eq!(
            body_limit_for_request(&Method::Post, "/api/v1/projects/current/search"),
            MAX_BODY_BYTES
        );
        assert_eq!(
            body_limit_for_request(&Method::Post, "/api/v1/projects/current/pages/write"),
            MAX_PAGE_WRITE_BODY_BYTES
        );
    }

    #[test]
    fn chat_routes_are_recognized_as_agent_requests() {
        assert!(is_agent_chat_request(
            &Method::Post,
            "/api/v1/projects/current/chat"
        ));
        assert!(is_agent_chat_request(
            &Method::Post,
            "/api/v1/projects/current/chat/session-1/cancel"
        ));
        assert!(!is_agent_chat_request(
            &Method::Post,
            "/api/v1/projects/current/search"
        ));
        assert!(!is_agent_chat_request(
            &Method::Get,
            "/api/v1/projects/current/chat"
        ));
    }

    #[test]
    fn paid_or_mutating_agent_routes_always_require_a_token() {
        assert!(is_token_required_request(
            &Method::Post,
            "/api/v1/projects/current/pages/embed"
        ));
        assert!(is_token_required_request(
            &Method::Post,
            "/api/v1/projects/current/pages/write"
        ));
        assert!(is_token_required_request(
            &Method::Post,
            "/api/v1/projects/current/chat"
        ));
        assert!(!is_token_required_request(
            &Method::Post,
            "/api/v1/projects/current/search"
        ));
        assert!(!is_token_required_request(
            &Method::Get,
            "/api/v1/projects/current/pages/embed"
        ));
    }

    #[test]
    fn chat_streaming_is_enabled_by_body_or_accept_header() {
        let path = "/api/v1/projects/current/chat";
        assert!(wants_streaming_chat(
            &Method::Post,
            path,
            r#"{"message":"hello","stream":true}"#,
            &[],
        ));
        assert!(wants_streaming_chat(
            &Method::Post,
            path,
            r#"{"message":"hello"}"#,
            &[(
                "accept".to_string(),
                "application/json, text/event-stream; q=0.9".to_string(),
            )],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            path,
            r#"{"message":"hello","stream":false}"#,
            &[],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            path,
            r#"{"message":"hello","stream":false}"#,
            &[("accept".to_string(), "text/event-stream".to_string())],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            "/api/v1/projects/current/search",
            r#"{"stream":true}"#,
            &[],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            "/api/v1/projects/current/chat/s1/cancel",
            r#"{"stream":true}"#,
            &[],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            "/projects/current/chat",
            r#"{"stream":true}"#,
            &[],
        ));
        assert!(!wants_streaming_chat(
            &Method::Post,
            "/api/v1/api/v1/projects/current/chat",
            r#"{"stream":true}"#,
            &[],
        ));
    }

    #[test]
    fn sse_reader_preserves_event_frames_until_sender_closes() {
        let (sender, receiver) = mpsc::sync_channel(4);
        sender
            .send(sse_frame("meta", &json!({ "sessionId": "s1" })))
            .unwrap();
        sender
            .send(sse_frame(
                "agent",
                &json!({ "type": "messageDelta", "text": "Hi" }),
            ))
            .unwrap();
        drop(sender);

        let mut body = String::new();
        let mut reader = SseReader::new(receiver);
        assert_eq!(reader.read(&mut []).unwrap(), 0);
        reader.read_to_string(&mut body).unwrap();
        assert!(body.contains("event: meta\n"));
        assert!(body.contains(r#"data: {"sessionId":"s1"}"#));
        assert!(body.contains("event: agent\n"));
        assert!(body.contains(r#""type":"messageDelta""#));
    }

    #[test]
    fn sse_queue_rejects_backpressure_without_blocking_runtime_threads() {
        let (sender, _receiver) = mpsc::sync_channel(1);
        assert!(matches!(
            try_send_sse(&sender, b"first".to_vec()),
            SseSendResult::Sent
        ));
        assert!(matches!(
            try_send_sse(&sender, b"second".to_vec()),
            SseSendResult::Full
        ));
    }

    #[test]
    fn sse_queue_reports_disconnected_clients() {
        let (sender, receiver) = mpsc::sync_channel(1);
        drop(receiver);
        assert!(matches!(
            try_send_sse(&sender, b"event".to_vec()),
            SseSendResult::Disconnected
        ));
    }

    #[test]
    fn terminal_sse_waits_for_queue_capacity() {
        let (sender, receiver) = mpsc::sync_channel(1);
        sender.send(b"agent".to_vec()).unwrap();
        send_terminal_sse(sender, b"done".to_vec());

        assert_eq!(receiver.recv().unwrap(), b"agent");
        assert_eq!(receiver.recv().unwrap(), b"done");
    }

    #[test]
    fn api_config_shape_parses_enabled_and_unauthenticated_access() {
        // Standalone pure-function check to mirror what `api_enabled`
        // reads off `load_app_state`. Mirrors the JS-side shape
        // emitted by `saveApiConfig` so any rename on either side
        // surfaces here before users hit it as a 503 in production.
        let payload = json!({
            "apiConfig": {
                "enabled": false,
                "allowUnauthenticated": true,
                "allowLanAccess": true,
                "mcpEnabled": true,
                "token": "abc"
            }
        });
        let enabled = payload
            .get("apiConfig")
            .and_then(|v| v.get("enabled"))
            .and_then(Value::as_bool)
            .unwrap_or(true);
        assert!(!enabled);
        let allow_unauthenticated = payload
            .get("apiConfig")
            .and_then(|v| v.get("allowUnauthenticated"))
            .and_then(Value::as_bool)
            .unwrap_or(false);
        assert!(allow_unauthenticated);
        let allow_lan_access = payload
            .get("apiConfig")
            .and_then(|v| v.get("allowLanAccess"))
            .and_then(Value::as_bool)
            .unwrap_or(false);
        assert!(allow_lan_access);
        let mcp_enabled = payload
            .get("apiConfig")
            .and_then(|v| v.get("mcpEnabled"))
            .and_then(Value::as_bool)
            .unwrap_or(false);
        assert!(mcp_enabled);
        let token_source = payload
            .get("apiConfig")
            .and_then(|v| v.get("token"))
            .and_then(Value::as_str)
            .filter(|s| !s.is_empty())
            .map(|_| "store")
            .unwrap_or("none");
        assert_eq!(token_source, "store");

        let missing = json!({});
        let enabled_missing = missing
            .get("apiConfig")
            .and_then(|v| v.get("enabled"))
            .and_then(Value::as_bool)
            .unwrap_or(true);
        // Fail-open by design — see `api_enabled` doc comment.
        assert!(enabled_missing);
        let mcp_enabled_missing = missing
            .get("apiConfig")
            .and_then(|v| v.get("mcpEnabled"))
            .and_then(Value::as_bool)
            .unwrap_or(false);
        assert!(!mcp_enabled_missing);
        let allow_lan_access_missing = missing
            .get("apiConfig")
            .and_then(|v| v.get("allowLanAccess"))
            .and_then(Value::as_bool)
            .unwrap_or(false);
        assert!(!allow_lan_access_missing);
    }

    #[test]
    fn project_llm_config_uses_profile_with_current_provider_credentials() {
        let state = json!({
            "llmConfig": { "provider": "openai", "apiKey": "global", "model": "gpt-global", "ollamaUrl": "", "customEndpoint": "", "maxContextSize": 1000 },
            "providerConfigs": {
                "deepseek": { "apiKey": "rotated", "model": "provider-model", "baseUrl": "https://new.example/v1", "apiMode": "chat_completions", "streamingEnabled": false, "customHeaders": { "X-Tenant-ID": "team-a" } }
            },
            "projectLlmOverrides": {
                "project-a": {
                    "enabled": true,
                    "presetId": "deepseek",
                    "model": "project-model",
                    "profile": { "provider": "custom", "model": "project-model", "ollamaUrl": "", "customEndpoint": "https://old.example/v1", "maxContextSize": 64000, "apiMode": "chat_completions" }
                }
            }
        });
        let config = project_llm_config(&state, "project-a").expect("project config");
        assert_eq!(config.provider, "custom");
        assert_eq!(config.api_key, "rotated");
        assert_eq!(config.model, "project-model");
        assert_eq!(config.custom_endpoint, "https://new.example/v1");
        assert_eq!(config.streaming_enabled, Some(false));
        assert_eq!(
            config.custom_headers.get("X-Tenant-ID").map(String::as_str),
            Some("team-a")
        );
    }

    #[test]
    fn project_llm_config_falls_back_for_disabled_or_legacy_override() {
        let state = json!({
            "llmConfig": { "provider": "openai", "apiKey": "global", "model": "gpt-global", "ollamaUrl": "", "customEndpoint": "", "maxContextSize": 1000 },
            "projectLlmOverrides": {
                "disabled": { "enabled": false, "presetId": "anthropic", "model": "claude" },
                "legacy": { "enabled": true, "presetId": "anthropic", "model": "claude" }
            }
        });
        assert_eq!(
            project_llm_config(&state, "disabled").unwrap().model,
            "gpt-global"
        );
        assert!(project_llm_config(&state, "legacy").is_none());
    }

    #[test]
    fn project_llm_config_falls_back_after_custom_preset_is_deleted() {
        let state = json!({
            "llmConfig": { "provider": "openai", "apiKey": "global", "model": "gpt-global", "ollamaUrl": "", "customEndpoint": "", "maxContextSize": 1000 },
            "providerConfigs": {
                "custom-deleted": { "apiKey": "stale-secret", "model": "stale-model", "baseUrl": "https://old.example/v1" }
            },
            "customLlmPresets": [],
            "projectLlmOverrides": {
                "project-b": {
                    "enabled": true,
                    "presetId": "custom-deleted",
                    "model": "stale-model",
                    "profile": { "provider": "custom", "model": "stale-model", "ollamaUrl": "", "customEndpoint": "https://old.example/v1", "maxContextSize": 64000 }
                }
            }
        });
        let config = project_llm_config(&state, "project-b").expect("global fallback");
        assert_eq!(config.model, "gpt-global");
        assert_eq!(config.api_key, "global");
    }

    #[test]
    fn project_llm_config_uses_registered_custom_preset() {
        let state = json!({
            "llmConfig": { "provider": "openai", "apiKey": "global", "model": "gpt-global", "ollamaUrl": "", "customEndpoint": "", "maxContextSize": 1000 },
            "customLlmPresets": [{ "id": "custom-live", "label": "Live" }],
            "providerConfigs": {
                "custom-live": { "apiKey": "live-secret", "model": "live-model", "baseUrl": "https://live.example/v1" }
            },
            "projectLlmOverrides": {
                "project-c": {
                    "enabled": true,
                    "presetId": "custom-live",
                    "model": "",
                    "profile": { "provider": "custom", "model": "old-model", "ollamaUrl": "", "customEndpoint": "https://old.example/v1", "maxContextSize": 64000 }
                }
            }
        });
        let config = project_llm_config(&state, "project-c").expect("custom config");
        assert_eq!(config.model, "live-model");
        assert_eq!(config.api_key, "live-secret");
        assert_eq!(config.custom_endpoint, "https://live.example/v1");
    }
}