handoff-mcp-server 0.26.0 → 0.28.0

package/src/context/injection.rs

@@ -1,276 +0,0 @@
-//! Shared BM25 + scope-path ranking used by `memory_query` and (from t96.3)
-//! `doc_query`.
-//!
-//! Extracted from the original `memory_query` implementation
-//! (`src/mcp/handlers/memory.rs`) so both features rank candidates the same
-//! way: BM25 relevance over a `lexsim::Corpus`, a fixed bonus when a
-//! candidate's `scope_paths` prefix-matches one of the query's `file_paths`,
-//! a `min_score` floor, then a stable sort + `limit` truncation.
-
-/// One ranked candidate: the index into the caller's original slice, plus its
-/// final score (BM25 + scope bonus).
-#[derive(Debug, Clone, Copy, PartialEq)]
-pub struct RankItem {
-    pub index: usize,
-    pub score: f64,
-}
-
-/// Tuning knobs for [`rank_by_bm25_and_scope`].
-#[derive(Debug, Clone, Copy)]
-pub struct RankConfig {
-    /// Candidates scoring below this are dropped before sorting.
-    pub min_score: f64,
-    /// Relative threshold (0.0–1.0): after ranking, a candidate is dropped
-    /// unless `score >= top_score * relative_threshold`. 0.0 disables.
-    pub relative_threshold: f64,
-    /// Added to a candidate's BM25 score when [`scope_matches`] is true.
-    pub scope_path_bonus: f64,
-    /// Max number of items returned (applied after sort, before session diff).
-    pub limit: usize,
-}
-
-/// True if any `scope` prefix matches any `file` path (substring match on the
-/// path, not a strict prefix — mirrors the original `memory_query` behavior).
-pub fn scope_matches(scopes: &[String], files: &[String]) -> bool {
-    if scopes.is_empty() || files.is_empty() {
-        return false;
-    }
-    scopes
-        .iter()
-        .any(|scope| files.iter().any(|f| f.contains(scope.as_str())))
-}
-
-/// Rank every document in `corpus` against `query_tokens` via weighted BM25,
-/// add `config.scope_path_bonus` when `scope_paths[i]` matches `file_paths`,
-/// drop anything below `config.min_score`, sort descending by score, and
-/// truncate to `config.limit`.
-///
-/// `scope_paths` and the corpus must be index-aligned (one entry per
-/// document); `corpus.len()` and `scope_paths.len()` are expected to match —
-/// a mismatch simply means the extra `scope_paths` entries are never
-/// consulted (indices beyond `corpus.len()` are not produced).
-pub fn rank_by_bm25_and_scope(
-    corpus: &lexsim::Corpus,
-    query_tokens: &[lexsim::WeightedToken],
-    scope_paths: &[Vec<String>],
-    file_paths: &[String],
-    config: &RankConfig,
-) -> Vec<RankItem> {
-    let scores = corpus.bm25_scores_weighted_tokens(query_tokens);
-
-    let mut ranked: Vec<RankItem> = scores
-        .into_iter()
-        .enumerate()
-        .map(|(index, mut score)| {
-            if let Some(scopes) = scope_paths.get(index) {
-                if scope_matches(scopes, file_paths) {
-                    score += config.scope_path_bonus;
-                }
-            }
-            RankItem { index, score }
-        })
-        .filter(|item| item.score > 0.0 && item.score >= config.min_score)
-        .collect();
-
-    ranked.sort_by(|a, b| {
-        b.score
-            .partial_cmp(&a.score)
-            .unwrap_or(std::cmp::Ordering::Equal)
-    });
-
-    // Relative threshold: drop candidates whose score is below a fraction of
-    // the top hit. Applied after sorting so `ranked[0]` is the best match.
-    if config.relative_threshold > 0.0 {
-        if let Some(top) = ranked.first() {
-            let floor = top.score * config.relative_threshold;
-            ranked.retain(|item| item.score >= floor);
-        }
-    }
-
-    ranked.truncate(config.limit);
-    ranked
-}
-
-/// Drop already-injected candidates (per the caller's session sidecar) from
-/// `ranked`, then truncate the survivors to `limit`.
-///
-/// `already_injected(index)` receives the original document index (as stored
-/// on [`RankItem::index`]) and returns true when that document was already
-/// injected into the current session at its current content hash.
-pub fn filter_already_injected<F>(
-    ranked: Vec<RankItem>,
-    already_injected: F,
-    limit: usize,
-) -> Vec<RankItem>
-where
-    F: Fn(usize) -> bool,
-{
-    ranked
-        .into_iter()
-        .filter(|item| !already_injected(item.index))
-        .take(limit)
-        .collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn docs() -> Vec<String> {
-        vec![
-            "rust error handling with Result and anyhow".to_string(),
-            "javascript promises and async await".to_string(),
-            "rust ownership borrow checker ownership".to_string(),
-        ]
-    }
-
-    fn default_config() -> RankConfig {
-        RankConfig {
-            min_score: 0.0,
-            relative_threshold: 0.0,
-            scope_path_bonus: 2.0,
-            limit: 10,
-        }
-    }
-
-    #[test]
-    fn scope_matches_prefix() {
-        let scopes = vec!["src/storage/".to_string()];
-        let files = vec!["/repo/src/storage/mod.rs".to_string()];
-        assert!(scope_matches(&scopes, &files));
-        let files2 = vec!["/repo/src/mcp/mod.rs".to_string()];
-        assert!(!scope_matches(&scopes, &files2));
-    }
-
-    #[test]
-    fn scope_matches_empty_inputs_false() {
-        assert!(!scope_matches(&[], &["a".to_string()]));
-        assert!(!scope_matches(&["a".to_string()], &[]));
-    }
-
-    #[test]
-    fn rank_by_bm25_orders_relevant_docs_first() {
-        let corpus = lexsim::Corpus::build_weighted(&docs());
-        let query_tokens = lexsim::tokenize_weighted("rust ownership");
-        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
-        let ranked =
-            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &default_config());
-
-        assert!(!ranked.is_empty());
-        assert_eq!(ranked[0].index, 2);
-    }
-
-    #[test]
-    fn rank_by_bm25_applies_scope_path_bonus() {
-        let corpus = lexsim::Corpus::build_weighted(&docs());
-        let query_tokens = lexsim::tokenize_weighted("javascript");
-        let scope_paths: Vec<Vec<String>> = vec![vec![], vec!["src/web/".to_string()], vec![]];
-        let file_paths = vec!["/repo/src/web/app.js".to_string()];
-        let config = RankConfig {
-            min_score: 0.0,
-            relative_threshold: 0.0,
-            scope_path_bonus: 2.0,
-            limit: 10,
-        };
-        let ranked =
-            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &file_paths, &config);
-        assert_eq!(ranked[0].index, 1);
-        assert!(ranked[0].score >= 2.0);
-    }
-
-    #[test]
-    fn rank_by_bm25_filters_below_min_score() {
-        let corpus = lexsim::Corpus::build_weighted(&docs());
-        let query_tokens = lexsim::tokenize_weighted("completely unrelated gibberish zzz");
-        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
-        let config = RankConfig {
-            min_score: 0.01,
-            relative_threshold: 0.0,
-            scope_path_bonus: 2.0,
-            limit: 10,
-        };
-        let ranked = rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config);
-        assert!(ranked.is_empty());
-    }
-
-    #[test]
-    fn rank_by_bm25_respects_limit() {
-        let corpus = lexsim::Corpus::build_weighted(&docs());
-        let query_tokens = lexsim::tokenize_weighted("rust javascript");
-        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
-        let config = RankConfig {
-            min_score: 0.0,
-            relative_threshold: 0.0,
-            scope_path_bonus: 2.0,
-            limit: 1,
-        };
-        let ranked = rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config);
-        assert_eq!(ranked.len(), 1);
-    }
-
-    #[test]
-    fn rank_by_bm25_applies_relative_threshold() {
-        let corpus = lexsim::Corpus::build_weighted(&docs());
-        let query_tokens = lexsim::tokenize_weighted("rust ownership");
-        let scope_paths: Vec<Vec<String>> = vec![vec![], vec![], vec![]];
-        let all =
-            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &default_config());
-        assert!(all.len() >= 2, "need at least 2 results to test relative");
-        let config_rel = RankConfig {
-            min_score: 0.0,
-            relative_threshold: 0.95,
-            scope_path_bonus: 0.0,
-            limit: 10,
-        };
-        let filtered =
-            rank_by_bm25_and_scope(&corpus, &query_tokens, &scope_paths, &[], &config_rel);
-        assert!(
-            filtered.len() < all.len(),
-            "relative threshold should drop low-scoring tail"
-        );
-        assert_eq!(filtered[0].index, all[0].index, "top hit must survive");
-    }
-
-    #[test]
-    fn filter_already_injected_drops_marked_and_respects_limit() {
-        let ranked = vec![
-            RankItem {
-                index: 0,
-                score: 5.0,
-            },
-            RankItem {
-                index: 1,
-                score: 4.0,
-            },
-            RankItem {
-                index: 2,
-                score: 3.0,
-            },
-        ];
-        let already = |i: usize| i == 1;
-        let out = filter_already_injected(ranked, already, 10);
-        assert_eq!(out.iter().map(|i| i.index).collect::<Vec<_>>(), vec![0, 2]);
-    }
-
-    #[test]
-    fn filter_already_injected_applies_limit_after_filtering() {
-        let ranked = vec![
-            RankItem {
-                index: 0,
-                score: 5.0,
-            },
-            RankItem {
-                index: 1,
-                score: 4.0,
-            },
-            RankItem {
-                index: 2,
-                score: 3.0,
-            },
-        ];
-        let out = filter_already_injected(ranked, |_| false, 2);
-        assert_eq!(out.len(), 2);
-        assert_eq!(out[0].index, 0);
-        assert_eq!(out[1].index, 1);
-    }
-}

package/src/context/mod.rs

@@ -1,129 +0,0 @@
-//! Shared ranking + corpus-cache infrastructure for full-text search across
-//! features (`memory_query` today, `doc_query` from t96.3).
-//!
-//! See `wiki/130-document-management.md` §3.1 for the design rationale: a
-//! single BM25 corpus cache, invalidated by a generation counter bumped on
-//! every mutating call (`doc_save`/`doc_delete`/`doc_import`), avoids
-//! rebuilding the corpus on every query once fragment counts reach the
-//! thousands. `memory_query` stays on the un-cached path (memory counts are
-//! small enough that a per-call rebuild is cheap) and only adopts the shared
-//! ranking function from [`injection`].
-
-pub mod injection;
-
-use std::sync::{Mutex, OnceLock};
-
-/// Process-wide cache of the document-fragment BM25 corpus, invalidated by a
-/// monotonically increasing generation counter.
-///
-/// `doc_save`/`doc_delete`/`doc_import` call [`CorpusCache::increment_generation`]
-/// on every mutation; the next [`CorpusCache::get_or_build_corpus`] call
-/// notices its cached generation is stale and rebuilds. The MCP server is
-/// single-threaded stdio today, so the `Mutex` is uncontended in practice —
-/// it exists for forward compatibility with a future multi-session server.
-pub struct CorpusCache {
-    generation: u64,
-    built_generation: Option<u64>,
-    corpus: Option<lexsim::Corpus>,
-    doc_texts: Vec<String>,
-}
-
-impl CorpusCache {
-    fn new() -> Self {
-        CorpusCache {
-            generation: 0,
-            built_generation: None,
-            corpus: None,
-            doc_texts: Vec::new(),
-        }
-    }
-
-    /// Invalidate the cached corpus. Called after any mutation to the
-    /// underlying fragment store (`doc_save`, `doc_delete`, `doc_import`).
-    pub fn increment_generation(&mut self) {
-        self.generation += 1;
-    }
-
-    /// Return the cached corpus if it is still current for `doc_texts`,
-    /// otherwise rebuild it from `doc_texts` and cache the result.
-    ///
-    /// `doc_texts` is the caller's current full set of fragment index texts,
-    /// supplied fresh on every call (the cache does not own fragment
-    /// storage) — only the expensive `lexsim::Corpus::build` step is skipped
-    /// when the generation hasn't moved since the last build.
-    pub fn get_or_build_corpus(&mut self, doc_texts: &[String]) -> &lexsim::Corpus {
-        let stale = self.built_generation != Some(self.generation) || self.doc_texts != doc_texts;
-        if stale {
-            self.corpus = Some(lexsim::Corpus::build_weighted(doc_texts));
-            self.doc_texts = doc_texts.to_vec();
-            self.built_generation = Some(self.generation);
-        }
-        self.corpus
-            .as_ref()
-            .expect("corpus is always populated by the stale branch above")
-    }
-
-    /// Current generation counter (test/inspection hook).
-    pub fn generation(&self) -> u64 {
-        self.generation
-    }
-}
-
-impl Default for CorpusCache {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-static DOC_CORPUS_CACHE: OnceLock<Mutex<CorpusCache>> = OnceLock::new();
-
-/// The process-wide document corpus cache, created lazily on first access.
-pub fn doc_corpus_cache() -> &'static Mutex<CorpusCache> {
-    DOC_CORPUS_CACHE.get_or_init(|| Mutex::new(CorpusCache::new()))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn get_or_build_corpus_reuses_cache_when_generation_unchanged() {
-        let mut cache = CorpusCache::new();
-        let texts = vec!["alpha beta".to_string(), "gamma delta".to_string()];
-        {
-            let corpus = cache.get_or_build_corpus(&texts);
-            assert_eq!(corpus.len(), 2);
-        }
-        assert_eq!(cache.built_generation, Some(0));
-        // Second call with identical inputs and generation should not rebuild
-        // (rebuild is observable only via built_generation staying put).
-        let _ = cache.get_or_build_corpus(&texts);
-        assert_eq!(cache.built_generation, Some(0));
-    }
-
-    #[test]
-    fn increment_generation_forces_rebuild() {
-        let mut cache = CorpusCache::new();
-        let texts = vec!["alpha".to_string()];
-        let _ = cache.get_or_build_corpus(&texts);
-        assert_eq!(cache.built_generation, Some(0));
-
-        cache.increment_generation();
-        assert_eq!(cache.generation(), 1);
-
-        let texts2 = vec!["alpha".to_string(), "beta".to_string()];
-        let corpus = cache.get_or_build_corpus(&texts2);
-        assert_eq!(corpus.len(), 2);
-        assert_eq!(cache.built_generation, Some(1));
-    }
-
-    #[test]
-    fn doc_corpus_cache_is_a_shared_singleton() {
-        {
-            let mut guard = doc_corpus_cache().lock().expect("cache mutex poisoned");
-            guard.increment_generation();
-        }
-        let guard = doc_corpus_cache().lock().expect("cache mutex poisoned");
-        assert!(guard.generation() >= 1);
-    }
-}

package/src/lib.rs

@@ -1,5 +0,0 @@
-pub mod cli;
-pub mod context;
-pub mod mcp;
-pub mod setup;
-pub mod storage;

package/src/main.rs

@@ -1,157 +0,0 @@
-use std::io::{self, BufRead, Write};
-use std::sync::mpsc;
-use std::thread;
-use std::time::Duration;
-
-use handoff_mcp::mcp::protocol::process_line;
-
-/// Maximum time a single JSON-RPC request may take before the server gives
-/// up waiting and returns a fail-safe error response. Processing continues
-/// on the worker thread in the background; the timeout only bounds how long
-/// the main loop blocks waiting for a reply. Override for tests via
-/// `HANDOFF_MCP_REQUEST_TIMEOUT_SECS` (parsed once at startup; falls back to
-/// the 30s default on missing/invalid values).
-const DEFAULT_REQUEST_TIMEOUT_SECS: u64 = 30;
-
-fn request_timeout() -> Duration {
-    let secs = std::env::var("HANDOFF_MCP_REQUEST_TIMEOUT_SECS")
-        .ok()
-        .and_then(|v| v.parse::<u64>().ok())
-        .unwrap_or(DEFAULT_REQUEST_TIMEOUT_SECS);
-    Duration::from_secs(secs)
-}
-
-fn main() {
-    let args: Vec<String> = std::env::args().collect();
-
-    if args.len() >= 2 {
-        match args[1].as_str() {
-            "setup" => {
-                let check = args.iter().any(|a| a == "--check");
-                let uninstall = args.iter().any(|a| a == "--uninstall");
-                let mcp_json = args.iter().any(|a| a == "--mcp-json");
-                let yes = args.iter().any(|a| a == "-y" || a == "--yes");
-                let global = args.iter().any(|a| a == "--global");
-                let force = args.iter().any(|a| a == "--force");
-                if let Err(e) = handoff_mcp::setup::run_setup_with_opts(
-                    check, uninstall, mcp_json, yes, global, force,
-                ) {
-                    eprintln!("Error: {e:#}");
-                    std::process::exit(1);
-                }
-                return;
-            }
-            "--version" | "-V" => {
-                println!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
-                return;
-            }
-            "--help" | "-h" => {
-                print_help();
-                return;
-            }
-            other => {
-                if handoff_mcp::cli::is_cli_command(other) {
-                    let cli_args: Vec<String> = args[1..].to_vec();
-                    // Handle --help for group
-                    if cli_args.len() >= 2 && (cli_args[1] == "--help" || cli_args[1] == "-h") {
-                        handoff_mcp::cli::print_group_help(&cli_args[0]);
-                        return;
-                    }
-                    let code = handoff_mcp::cli::run(&cli_args);
-                    std::process::exit(code);
-                }
-                eprintln!("Unknown command: {other}");
-                eprintln!("Run `handoff-mcp --help` for usage.");
-                std::process::exit(1);
-            }
-        }
-    }
-
-    eprintln!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
-
-    let stdin = io::stdin();
-    let mut stdout = io::stdout();
-    let timeout = request_timeout();
-
-    for line in stdin.lock().lines() {
-        let line = match line {
-            Ok(l) => l,
-            Err(e) => {
-                eprintln!("stdin read error: {e}");
-                break;
-            }
-        };
-
-        // Run this request on a dedicated worker thread so a slow handler
-        // can't block the main loop forever: `recv_timeout` below bounds how
-        // long we wait for a reply. The next line is only read after this
-        // request's worker completes (or times out) — sequential processing
-        // order is preserved; this is a fail-safe timeout, not parallelism.
-        let (tx, rx) = mpsc::channel();
-        let line_for_worker = line.clone();
-        thread::spawn(move || {
-            let result = process_line(&line_for_worker);
-            let _ = tx.send(result);
-        });
-
-        match rx.recv_timeout(timeout) {
-            Ok(Some(response)) => {
-                if writeln!(stdout, "{response}").is_err() {
-                    break;
-                }
-                if stdout.flush().is_err() {
-                    break;
-                }
-            }
-            Ok(None) => {
-                // Notification: no response expected.
-            }
-            Err(mpsc::RecvTimeoutError::Timeout) => {
-                eprintln!("Request timed out after {}s", timeout.as_secs());
-                let id = serde_json::from_str::<serde_json::Value>(&line)
-                    .ok()
-                    .and_then(|req| req.get("id").cloned())
-                    .unwrap_or(serde_json::Value::Null);
-                let error_response = serde_json::json!({
-                    "jsonrpc": "2.0",
-                    "id": id,
-                    "error": {
-                        "code": -32603,
-                        "message": format!("Request timed out after {}s", timeout.as_secs())
-                    }
-                });
-                if writeln!(stdout, "{error_response}").is_err() {
-                    break;
-                }
-                if stdout.flush().is_err() {
-                    break;
-                }
-            }
-            Err(mpsc::RecvTimeoutError::Disconnected) => {
-                eprintln!("Worker thread disconnected without a response");
-            }
-        }
-    }
-}
-
-fn print_help() {
-    handoff_mcp::cli::print_cli_help();
-    println!(
-        "
-SERVER MODE:
-    handoff-mcp              Start the MCP server (stdio transport)
-
-SETUP:
-    handoff-mcp setup              Install hooks + MCP server + CLAUDE.md template
-    handoff-mcp setup --global     Use ~/.claude/settings.json mcpServers (not .mcp.json)
-    handoff-mcp setup --check      Check if hooks, MCP, and CLAUDE.md are configured
-    handoff-mcp setup --uninstall  Remove handoff hooks and MCP entry
-    handoff-mcp setup --mcp-json   Add handoff MCP server entry only (non-interactive)
-    handoff-mcp setup --force      Replace existing CLAUDE.md handoff section with latest
-    handoff-mcp setup -y           Skip all confirmation prompts
-
-OPTIONS:
-    -h, --help       Print this help message
-    -V, --version    Print version"
-    );
-}