handoff-mcp-server 0.26.0 → 0.27.0

package/src/storage/memory/model.rs

@@ -1,127 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-/// Current memory schema version. Bump when `MemoryEntry` changes shape in a way
-/// that needs migration handling on read.
-///
-/// v1 → v2: added `keywords` field (defaults to empty on read).
-pub const MEMORY_SCHEMA_VERSION: u32 = 2;
-
-/// Valid `kind` values for a memory. Free-form text is rejected so the field
-/// stays a small, queryable enumeration.
-pub const VALID_MEMORY_KINDS: &[&str] = &["lesson", "rule", "convention", "gotcha"];
-
-/// Returns true if `kind` is one of the accepted memory kinds.
-pub fn is_valid_memory_kind(kind: &str) -> bool {
-    VALID_MEMORY_KINDS.contains(&kind)
-}
-
-/// A single persisted memory: a long-lived, cross-session piece of project
-/// knowledge ("lesson / rule / convention / gotcha"). One file per memory under
-/// `.handoff/memory/`.
-///
-/// Token sets are intentionally **not** stored — they are recomputed from `text`
-/// on every read so the index can never drift from the body.
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MemoryEntry {
-    /// Schema version (= [`MEMORY_SCHEMA_VERSION`]).
-    pub version: u32,
-    /// Stable id: `m-YYYYMMDD-HHMMSS-NNNNNN`.
-    pub id: String,
-    /// The memory body (multilingual).
-    pub text: String,
-    /// One of [`VALID_MEMORY_KINDS`].
-    pub kind: String,
-    /// Free-form tags; also fed into the similarity index.
-    #[serde(default)]
-    pub tags: Vec<String>,
-    /// Subject keywords — nouns, technical terms, proper nouns that identify what
-    /// this memory is *about*. Used for BM25 matching with boosted weight.
-    /// Distinct from `tags` (classification labels) and `scope_paths` (file
-    /// prefixes). Populated by the AI at save time; defaults to empty for v1
-    /// memories.
-    #[serde(default)]
-    pub keywords: Vec<String>,
-    /// Path prefixes this memory applies to (e.g. `src/storage/`). A query whose
-    /// file paths start with one of these gets a relevance boost.
-    #[serde(default)]
-    pub scope_paths: Vec<String>,
-    /// FNV-1a hash of the canonical (tokenized) text. Drives exact-duplicate
-    /// detection and per-session re-injection tracking.
-    pub content_hash: String,
-    /// RFC3339 creation timestamp.
-    pub created_at: String,
-    /// RFC3339 last-update timestamp.
-    pub updated_at: String,
-    /// RFC3339 timestamp of the last time this memory was injected into a
-    /// session, if ever.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub last_referenced_at: Option<String>,
-    /// Number of times this memory has been injected.
-    #[serde(default)]
-    pub hit_count: u64,
-    /// Ids of memories merged into this one (audit trail for AI-driven merges).
-    #[serde(default)]
-    pub superseded_ids: Vec<String>,
-}
-
-impl MemoryEntry {
-    /// Build a new entry with timestamps and content hash filled in. `now` is an
-    /// RFC3339 timestamp supplied by the caller (keeps this module clock-free
-    /// and testable).
-    pub fn new(
-        id: String,
-        text: String,
-        kind: String,
-        tags: Vec<String>,
-        keywords: Vec<String>,
-        scope_paths: Vec<String>,
-        now: String,
-    ) -> Self {
-        let content_hash = lexsim::content_hash(&text);
-        MemoryEntry {
-            version: MEMORY_SCHEMA_VERSION,
-            id,
-            text,
-            kind,
-            tags,
-            keywords,
-            scope_paths,
-            content_hash,
-            created_at: now.clone(),
-            updated_at: now,
-            last_referenced_at: None,
-            hit_count: 0,
-            superseded_ids: Vec::new(),
-        }
-    }
-
-    /// Plain-text index for Jaccard similarity: body + tags + keywords.
-    pub fn index_text(&self) -> String {
-        let mut parts = vec![self.text.clone()];
-        if !self.tags.is_empty() {
-            parts.push(self.tags.join(" "));
-        }
-        if !self.keywords.is_empty() {
-            parts.push(self.keywords.join(" "));
-        }
-        parts.join(" ")
-    }
-
-    /// Weighted tokens for `Corpus::build_weighted_tokens`. Body + tags are
-    /// tokenized at default weight; keywords are added with weight 2.0
-    /// (doc-side TF boost), replacing the old 2x-concatenation hack.
-    pub fn index_weighted_tokens(&self) -> Vec<lexsim::WeightedToken> {
-        let mut base = vec![self.text.clone()];
-        if !self.tags.is_empty() {
-            base.push(self.tags.join(" "));
-        }
-        let mut tokens = lexsim::tokenize_weighted(&base.join(" "));
-        for kw in &self.keywords {
-            for mut wt in lexsim::tokenize_weighted(kw) {
-                wt.weight *= 2.0;
-                tokens.push(wt);
-            }
-        }
-        tokens
-    }
-}

package/src/storage/mod.rs

@@ -1,96 +0,0 @@
-pub mod config;
-pub mod docs;
-pub mod git;
-pub mod memory;
-pub mod referrals;
-pub mod sessions;
-pub mod tasks;
-
-use std::path::{Path, PathBuf};
-
-use anyhow::{Context, Result};
-
-/// Write `content` to `path` atomically: write to a sibling temp file, fsync,
-/// then rename over the target. A rename within the same directory is atomic on
-/// POSIX, so a concurrent reader never observes a partially-written file.
-///
-/// Used by every handoff write path (tasks, config, sessions, referrals) so that
-/// the VSCode extension — which writes the same files — never reads torn data.
-pub fn atomic_write(path: impl AsRef<Path>, content: &[u8]) -> Result<()> {
-    use std::io::Write;
-
-    let path = path.as_ref();
-    let dir = path.parent().ok_or_else(|| {
-        anyhow::anyhow!("Cannot determine parent directory for {}", path.display())
-    })?;
-    let file_name = path
-        .file_name()
-        .and_then(|n| n.to_str())
-        .ok_or_else(|| anyhow::anyhow!("Invalid file name for {}", path.display()))?;
-
-    // Unique-per-process temp name in the same directory (so rename is atomic).
-    let tmp_name = format!(".{file_name}.tmp.{}", std::process::id());
-    let tmp_path = dir.join(tmp_name);
-
-    let mut f = std::fs::File::create(&tmp_path)
-        .with_context(|| format!("Failed to create temp file {}", tmp_path.display()))?;
-    f.write_all(content)
-        .with_context(|| format!("Failed to write temp file {}", tmp_path.display()))?;
-    f.sync_all()
-        .with_context(|| format!("Failed to sync temp file {}", tmp_path.display()))?;
-    drop(f);
-
-    std::fs::rename(&tmp_path, path).with_context(|| {
-        // Best-effort cleanup so a failed rename doesn't leave a stray temp file.
-        let _ = std::fs::remove_file(&tmp_path);
-        format!(
-            "Failed to rename {} -> {}",
-            tmp_path.display(),
-            path.display()
-        )
-    })?;
-    Ok(())
-}
-
-pub fn expand_tilde(path: &str) -> String {
-    if let Some(rest) = path.strip_prefix("~/") {
-        if let Ok(home) = std::env::var("HOME") {
-            return format!("{home}/{rest}");
-        }
-    }
-    path.to_string()
-}
-
-pub fn handoff_dir(project_dir: &Path) -> PathBuf {
-    project_dir.join(".handoff")
-}
-
-pub fn ensure_handoff_exists(project_dir: &Path) -> Result<PathBuf> {
-    let dir = handoff_dir(project_dir);
-    if !dir.exists() {
-        anyhow::bail!(
-            ".handoff/ directory not found in {}. Run handoff_init first.",
-            project_dir.display()
-        );
-    }
-    Ok(dir)
-}
-
-pub fn init_handoff(project_dir: &Path, project_name: &str, description: &str) -> Result<()> {
-    let dir = handoff_dir(project_dir);
-    if dir.exists() {
-        anyhow::bail!(
-            ".handoff/ already exists in {}. Project is already initialized.",
-            project_dir.display()
-        );
-    }
-
-    std::fs::create_dir_all(dir.join("sessions")).context("Failed to create .handoff/sessions/")?;
-    std::fs::create_dir_all(dir.join("tasks")).context("Failed to create .handoff/tasks/")?;
-    std::fs::create_dir_all(dir.join("memory")).context("Failed to create .handoff/memory/")?;
-
-    let config = config::Config::new(project_name, description);
-    config::write_config(&dir.join("config.toml"), &config)?;
-
-    Ok(())
-}

package/src/storage/referrals.rs

@@ -1,248 +0,0 @@
-use std::path::{Path, PathBuf};
-
-use anyhow::{Context, Result};
-use serde::{Deserialize, Serialize};
-use serde_json::Value;
-
-const VALID_REFERRAL_TYPES: &[&str] = &["improvement", "bug", "request", "info"];
-const VALID_REFERRAL_STATUSES: &[&str] = &["open", "acknowledged", "resolved"];
-
-pub fn is_valid_referral_type(t: &str) -> bool {
-    VALID_REFERRAL_TYPES.contains(&t)
-}
-
-pub fn is_valid_referral_status(s: &str) -> bool {
-    VALID_REFERRAL_STATUSES.contains(&s)
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ReferralData {
-    pub id: String,
-    pub source_project: String,
-    pub source_project_dir: String,
-    pub created_at: String,
-    pub referral_type: String,
-    pub summary: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub details: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub priority: Option<String>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub tasks: Vec<Value>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub context: Option<Value>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ReferralSummary {
-    pub id: String,
-    pub source_project: String,
-    pub referral_type: String,
-    pub summary: String,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub priority: Option<String>,
-    pub status: String,
-    pub created_at: String,
-}
-
-pub fn write_referral(referrals_dir: &Path, data: &ReferralData) -> Result<PathBuf> {
-    std::fs::create_dir_all(referrals_dir).with_context(|| {
-        format!(
-            "Failed to create referrals dir: {}",
-            referrals_dir.display()
-        )
-    })?;
-
-    let slug = source_to_slug(&data.source_project);
-    let id_suffix = data.id.replace("ref-", "");
-    let filename = format!("{id_suffix}-{slug}.open.json");
-    let file_path = referrals_dir.join(&filename);
-
-    let content = serde_json::to_string_pretty(data).context("Failed to serialize referral")?;
-    crate::storage::atomic_write(&file_path, content.as_bytes())
-        .with_context(|| format!("Failed to write referral: {}", file_path.display()))?;
-
-    Ok(file_path)
-}
-
-pub fn read_referrals(
-    referrals_dir: &Path,
-    status_filter: Option<&str>,
-) -> Result<Vec<(ReferralData, String)>> {
-    let mut results = Vec::new();
-
-    if !referrals_dir.exists() {
-        return Ok(results);
-    }
-
-    let mut entries: Vec<_> = std::fs::read_dir(referrals_dir)?
-        .filter_map(|e| e.ok())
-        .collect();
-    entries.sort_by_key(|e| e.file_name());
-
-    for entry in entries {
-        let name = entry.file_name().to_string_lossy().to_string();
-        if let Some(status) = parse_referral_status(&name) {
-            if let Some(filter) = status_filter {
-                if status != filter {
-                    continue;
-                }
-            }
-            let content = std::fs::read_to_string(entry.path())
-                .with_context(|| format!("Failed to read referral: {}", entry.path().display()))?;
-            let data: ReferralData = serde_json::from_str(&content)
-                .with_context(|| format!("Failed to parse referral: {}", entry.path().display()))?;
-            results.push((data, status));
-        }
-    }
-
-    Ok(results)
-}
-
-pub fn read_referral_summaries(
-    referrals_dir: &Path,
-    status_filter: Option<&str>,
-) -> Result<Vec<ReferralSummary>> {
-    let referrals = read_referrals(referrals_dir, status_filter)?;
-    Ok(referrals
-        .into_iter()
-        .map(|(data, status)| ReferralSummary {
-            id: data.id,
-            source_project: data.source_project,
-            referral_type: data.referral_type,
-            summary: data.summary,
-            priority: data.priority,
-            status,
-            created_at: data.created_at,
-        })
-        .collect())
-}
-
-pub fn change_referral_status(
-    referrals_dir: &Path,
-    referral_id: &str,
-    new_status: &str,
-) -> Result<()> {
-    if !is_valid_referral_status(new_status) {
-        anyhow::bail!(
-            "Invalid referral status: '{new_status}'. Must be one of: {}",
-            VALID_REFERRAL_STATUSES.join(", ")
-        );
-    }
-
-    let (old_path, old_status) = find_referral_file(referrals_dir, referral_id)?
-        .ok_or_else(|| anyhow::anyhow!("Referral not found: {referral_id}"))?;
-
-    if old_status == new_status {
-        return Ok(());
-    }
-
-    let old_name = old_path
-        .file_name()
-        .ok_or_else(|| anyhow::anyhow!("Invalid referral path"))?
-        .to_string_lossy()
-        .to_string();
-
-    let new_name = old_name.replace(
-        &format!(".{old_status}.json"),
-        &format!(".{new_status}.json"),
-    );
-    let new_path = referrals_dir.join(&new_name);
-
-    std::fs::rename(&old_path, &new_path).with_context(|| {
-        format!(
-            "Failed to rename {} -> {}",
-            old_path.display(),
-            new_path.display()
-        )
-    })?;
-
-    Ok(())
-}
-
-/// Read a single referral's full data by ID, returning the data and its status.
-/// Searches every status (open / acknowledged / resolved). Matches by exact ID
-/// first, then falls back to a unique prefix match for convenience.
-pub fn read_referral_by_id(
-    referrals_dir: &Path,
-    referral_id: &str,
-) -> Result<Option<(ReferralData, String)>> {
-    if !referrals_dir.exists() {
-        return Ok(None);
-    }
-
-    let mut prefix_matches: Vec<(ReferralData, String)> = Vec::new();
-
-    for entry in std::fs::read_dir(referrals_dir)? {
-        let entry = entry?;
-        let name = entry.file_name().to_string_lossy().to_string();
-        if let Some(status) = parse_referral_status(&name) {
-            let content = std::fs::read_to_string(entry.path())?;
-            if let Ok(data) = serde_json::from_str::<ReferralData>(&content) {
-                if data.id == referral_id {
-                    return Ok(Some((data, status)));
-                }
-                if data.id.starts_with(referral_id) {
-                    prefix_matches.push((data, status));
-                }
-            }
-        }
-    }
-
-    match prefix_matches.len() {
-        0 => Ok(None),
-        1 => Ok(Some(prefix_matches.into_iter().next().unwrap())),
-        n => anyhow::bail!(
-            "Ambiguous referral id prefix '{referral_id}' matches {n} referrals; use the full id"
-        ),
-    }
-}
-
-pub fn find_referral_file(
-    referrals_dir: &Path,
-    referral_id: &str,
-) -> Result<Option<(PathBuf, String)>> {
-    if !referrals_dir.exists() {
-        return Ok(None);
-    }
-
-    for entry in std::fs::read_dir(referrals_dir)? {
-        let entry = entry?;
-        let name = entry.file_name().to_string_lossy().to_string();
-        if let Some(status) = parse_referral_status(&name) {
-            let content = std::fs::read_to_string(entry.path())?;
-            if let Ok(data) = serde_json::from_str::<ReferralData>(&content) {
-                if data.id == referral_id {
-                    return Ok(Some((entry.path(), status)));
-                }
-            }
-        }
-    }
-
-    Ok(None)
-}
-
-fn parse_referral_status(filename: &str) -> Option<String> {
-    let name = filename.strip_suffix(".json")?;
-    for status in VALID_REFERRAL_STATUSES {
-        if name.ends_with(&format!(".{status}")) {
-            return Some(status.to_string());
-        }
-    }
-    None
-}
-
-fn source_to_slug(source: &str) -> String {
-    let slug: String = source
-        .chars()
-        .take(30)
-        .map(|c| {
-            if c.is_ascii_alphanumeric() {
-                c.to_ascii_lowercase()
-            } else {
-                '-'
-            }
-        })
-        .collect();
-    slug.trim_matches('-').to_string()
-}