vtcode_indexer/

markdown_store.rs

#![expect(
    clippy::string_slice,
    clippy::let_underscore_must_use,
    unused_results,
    reason = "Markdown extraction uses validated ASCII fences and best-effort lock/storage cleanup."
)]

//! Markdown-backed storage utilities extracted from VT Code.
//!
//! This module provides lightweight persistence helpers that serialize
//! structured data into Markdown files with embedded JSON and YAML blocks.
//! It also exposes simple project and cache managers built on top of the
//! markdown storage abstraction so command-line tools can persist
//! human-readable state without requiring a database.

use std::fs::{self, OpenOptions};
use std::io::Read;
use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use fs2::FileExt;
use indexmap::IndexMap;
use serde::{Deserialize, Serialize};

use crate::atomic_write::{
    canonical_existing_storage_dir, canonical_storage_dir, contained_existing_record_path, contained_record_path,
    reject_symlink_destination, validate_record_key, write_atomic,
};

/// Simple markdown storage manager
#[derive(Clone)]
pub struct MarkdownStorage {
    storage_dir: PathBuf,
}

impl MarkdownStorage {
    /// Create a new markdown storage instance rooted at `storage_dir`.
    fn new(storage_dir: PathBuf) -> Self {
        Self { storage_dir }
    }

    /// Initialize storage directory
    fn init(&self) -> Result<()> {
        canonical_storage_dir(&self.storage_dir)?;
        Ok(())
    }

    /// Store data as markdown
    fn store<T: Serialize>(&self, key: &str, data: &T, title: &str) -> Result<()> {
        let file_path = self.storage_path(key)?;
        let markdown = self.serialize_to_markdown(data, title)?;
        write_with_lock(&file_path, markdown.as_bytes())
    }

    /// Resolve `key` to the record path inside the canonical storage dir.
    ///
    /// Keys must be single file names: separators, parent components, and
    /// absolute paths fail closed so record operations cannot escape the
    /// store when names arrive from workspaces or CLI input.
    fn storage_path(&self, key: &str) -> Result<PathBuf> {
        contained_record_path(&self.storage_dir, key, "md")
    }

    /// Resolve `key` without creating anything, for read and delete paths.
    fn existing_storage_path(&self, key: &str) -> Result<PathBuf> {
        contained_existing_record_path(&self.storage_dir, key, "md")
    }

    /// Load data from markdown
    pub fn load<T: for<'de> Deserialize<'de>>(&self, key: &str) -> Result<T> {
        let file_path = self.existing_storage_path(key)?;
        let content = read_with_shared_lock(&file_path)?;
        self.deserialize_from_markdown(&content)
    }

    /// List all stored items
    pub fn list(&self) -> Result<Vec<String>> {
        let mut items = Vec::new();

        let dir = canonical_existing_storage_dir(&self.storage_dir)?;
        for entry in fs::read_dir(&dir)? {
            let entry = entry?;
            if let Some(name) = entry.path().file_stem().and_then(|file_name| file_name.to_str()) {
                items.push(name.to_string());
            }
        }

        Ok(items)
    }

    /// Delete stored item
    pub fn delete(&self, key: &str) -> Result<()> {
        validate_record_key(key)?;
        if !self.storage_dir.join(format!("{key}.md")).exists() {
            return Ok(());
        }
        let file_path = self.existing_storage_path(key)?;
        if file_path.exists() {
            // Try to obtain an exclusive lock before removing the file so
            // concurrent readers or writers can finish gracefully.
            if let Ok(file) = OpenOptions::new().read(true).write(true).open(&file_path) {
                let _ = file.lock_exclusive();
                // Explicit drop to release the lock prior to removal.
                drop(file);
            }

            // Removing a file that was concurrently deleted is not an error -
            // treat it as best-effort cleanup.
            match fs::remove_file(&file_path) {
                Ok(_) => {}
                Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
                Err(err) => {
                    return Err(err)
                        .with_context(|| format!("Failed to delete markdown file at {}", file_path.display()));
                }
            }
        }
        Ok(())
    }

    /// Check if item exists
    ///
    /// Key validation keeps the probe inside the store without creating
    /// anything; only mutating and loading operations canonicalize.
    pub fn exists(&self, key: &str) -> bool {
        if validate_record_key(key).is_err() {
            return false;
        }
        self.storage_dir.join(format!("{key}.md")).exists()
    }

    fn serialize_to_markdown<T: Serialize>(&self, data: &T, title: &str) -> Result<String> {
        let json = serde_json::to_string_pretty(data)?;
        let yaml = serde_saphyr::to_string(data)?;

        let markdown = format!(
            "# {}\n\n\
            ## JSON\n\n\
            ```json\n\
            {}\n\
            ```\n\n\
            ## YAML\n\n\
            ```yaml\n\
            {}\n\
            ```\n\n\
            ## Raw Data\n\n\
            {}\n",
            title,
            json,
            yaml,
            self.format_raw_data(data)
        );

        Ok(markdown)
    }

    fn deserialize_from_markdown<T: for<'de> Deserialize<'de>>(&self, content: &str) -> Result<T> {
        if let Some(json_block) = self.extract_code_block(content, "json") {
            return serde_json::from_str(json_block).context("Failed to parse JSON from markdown");
        }

        if let Some(yaml_block) = self.extract_code_block(content, "yaml") {
            return serde_saphyr::from_str(yaml_block).context("Failed to parse YAML from markdown");
        }

        Err(anyhow::anyhow!("No valid JSON or YAML found in markdown"))
    }

    fn extract_code_block<'a>(&self, content: &'a str, language: &str) -> Option<&'a str> {
        let start_pattern = format!("```{language}");
        let end_pattern = "```";

        if let Some(start_idx) = content.find(&start_pattern) {
            let code_start = start_idx + start_pattern.len();
            if let Some(end_idx) = content[code_start..].find(end_pattern) {
                let code_end = code_start + end_idx;
                return Some(content[code_start..code_end].trim());
            }
        }

        None
    }

    fn format_raw_data<T: Serialize>(&self, data: &T) -> String {
        match serde_json::to_value(data) {
            Ok(serde_json::Value::Object(map)) => {
                let mut lines = Vec::with_capacity(map.len());
                for (key, value) in map {
                    lines.push(format!("- **{}**: {}", key, self.format_value(&value)));
                }
                lines.join("\n")
            }
            _ => "Complex data structure".to_string(),
        }
    }

    fn format_value(&self, value: &serde_json::Value) -> String {
        match value {
            serde_json::Value::String(s) => format!("\"{s}\""),
            serde_json::Value::Number(n) => n.to_string(),
            serde_json::Value::Bool(b) => b.to_string(),
            serde_json::Value::Array(arr) => format!("[{} items]", arr.len()),
            serde_json::Value::Object(obj) => format!("{{{} fields}}", obj.len()),
            serde_json::Value::Null => "null".to_string(),
        }
    }
}

fn write_with_lock(path: &Path, data: &[u8]) -> Result<()> {
    let parent = path
        .parent()
        .ok_or_else(|| anyhow::anyhow!("storage path {} has no parent", path.display()))?;
    let file_name = path
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| anyhow::anyhow!("storage path {} has no file name", path.display()))?;
    reject_symlink_destination(path)?;

    // Lock the destination inode itself while the bytes land atomically:
    // the destination is never truncated in place, so readers observe the
    // old or the new record but never a mix, and a failed write keeps the
    // last committed record instead of a torn one. A writer that opens the
    // path after our rename locks the new inode instead, so overlapping
    // writes resolve as last-writer-wins between complete files.
    let lock = OpenOptions::new()
        .create(true)
        .read(true)
        .write(true)
        .truncate(false)
        .open(path)
        .with_context(|| format!("Failed to open file at {}", path.display()))?;

    FileExt::lock_exclusive(&lock)
        .with_context(|| format!("Failed to acquire exclusive lock for {}", path.display()))?;

    let result = write_atomic(parent, file_name, data);

    FileExt::unlock(&lock).with_context(|| format!("Failed to release exclusive lock for {}", path.display()))?;
    result
}

fn read_with_shared_lock(path: &Path) -> Result<String> {
    reject_symlink_destination(path)?;
    let mut file = OpenOptions::new()
        .read(true)
        .open(path)
        .with_context(|| format!("Failed to open file at {}", path.display()))?;

    FileExt::lock_shared(&file).with_context(|| format!("Failed to acquire shared lock for {}", path.display()))?;

    let mut content = String::new();
    file.read_to_string(&mut content)
        .with_context(|| format!("Failed to read file content from {} while holding shared lock", path.display()))?;

    FileExt::unlock(&file).with_context(|| format!("Failed to release shared lock for {}", path.display()))?;

    Ok(content)
}

/// Simple key-value storage using markdown
pub struct SimpleKVStorage {
    storage: MarkdownStorage,
}

impl SimpleKVStorage {
    pub fn new(storage_dir: PathBuf) -> Self {
        Self { storage: MarkdownStorage::new(storage_dir) }
    }

    pub fn init(&self) -> Result<()> {
        self.storage.init()
    }

    pub fn put(&self, key: &str, value: &str) -> Result<()> {
        let data = IndexMap::from([("value".to_string(), value.to_string())]);
        self.storage.store(key, &data, &format!("Key-Value: {key}"))
    }

    pub fn get(&self, key: &str) -> Result<String> {
        let data: IndexMap<String, String> = self.storage.load(key)?;
        data.get("value")
            .cloned()
            .ok_or_else(|| anyhow::anyhow!("Value not found for key: {key}"))
    }

    pub fn delete(&self, key: &str) -> Result<()> {
        self.storage.delete(key)
    }

    pub fn list_keys(&self) -> Result<Vec<String>> {
        self.storage.list()
    }
}

/// Simple project metadata storage
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProjectData {
    name: String,
    pub description: Option<String>,
    version: String,
    tags: Vec<String>,
    metadata: IndexMap<String, String>,
}

impl ProjectData {
    pub fn new(name: &str) -> Self {
        Self {
            name: name.to_string(),
            description: None,
            version: "1.0.0".to_string(),
            tags: vec![],
            metadata: IndexMap::new(),
        }
    }
}

/// Project storage using markdown
#[derive(Clone)]
pub struct ProjectStorage {
    storage: MarkdownStorage,
}

impl ProjectStorage {
    fn new(storage_dir: PathBuf) -> Self {
        Self { storage: MarkdownStorage::new(storage_dir) }
    }

    fn init(&self) -> Result<()> {
        self.storage.init()
    }

    fn save_project(&self, project: &ProjectData) -> Result<()> {
        self.storage
            .store(&project.name, project, &format!("Project: {}", project.name))
    }

    pub fn load_project(&self, name: &str) -> Result<ProjectData> {
        self.storage.load(name)
    }

    pub fn list_projects(&self) -> Result<Vec<String>> {
        self.storage.list()
    }

    pub fn delete_project(&self, name: &str) -> Result<()> {
        self.storage.delete(name)
    }

    pub fn storage_dir(&self) -> &Path {
        &self.storage.storage_dir
    }
}

/// Simple project manager that orchestrates project metadata persistence.
#[derive(Clone)]
pub struct SimpleProjectManager {
    storage: ProjectStorage,
    workspace_root: PathBuf,
    project_root: PathBuf,
}

impl SimpleProjectManager {
    /// Construct a project manager that stores metadata under
    /// `<workspace_root>/.vtcode/projects`.
    pub fn new(workspace_root: PathBuf) -> Self {
        let project_root = workspace_root.join(".vtcode").join("projects");
        Self::with_project_root(workspace_root, project_root)
    }

    /// Construct a manager with a caller-supplied project storage root.
    fn with_project_root(workspace_root: PathBuf, project_root: PathBuf) -> Self {
        let storage = ProjectStorage::new(project_root.clone());
        Self { storage, workspace_root, project_root }
    }

    /// Initialize the project manager
    pub fn init(&self) -> Result<()> {
        self.storage.init()
    }

    /// Create a new project
    pub fn create_project(&self, name: &str, description: Option<&str>) -> Result<()> {
        let mut project = ProjectData::new(name);
        project.description = description.map(|s| s.to_string());

        self.storage.save_project(&project)?;
        Ok(())
    }

    /// Load a project by name
    pub fn load_project(&self, name: &str) -> Result<ProjectData> {
        self.storage.load_project(name)
    }

    /// List all projects
    pub fn list_projects(&self) -> Result<Vec<String>> {
        self.storage.list_projects()
    }

    /// Delete a project
    pub fn delete_project(&self, name: &str) -> Result<()> {
        self.storage.delete_project(name)
    }

    /// Update project metadata
    pub fn update_project(&self, project: &ProjectData) -> Result<()> {
        self.storage.save_project(project)
    }

    /// Get project data directory
    pub fn project_data_dir(&self, project_name: &str) -> PathBuf {
        self.project_root.join(project_name)
    }

    /// Get project config directory
    pub fn config_dir(&self, project_name: &str) -> PathBuf {
        self.project_data_dir(project_name).join("config")
    }

    /// Get project cache directory
    pub fn cache_dir(&self, project_name: &str) -> PathBuf {
        self.project_data_dir(project_name).join("cache")
    }

    /// Get workspace root
    pub fn workspace_root(&self) -> &Path {
        &self.workspace_root
    }

    /// Return the root directory backing project metadata.
    pub fn project_root(&self) -> &Path {
        &self.project_root
    }

    /// Check if project exists
    pub fn project_exists(&self, name: &str) -> bool {
        self.storage
            .list_projects()
            .map(|projects| projects.contains(&name.to_string()))
            .unwrap_or(false)
    }

    /// Get project info as simple text
    pub fn get_project_info(&self, name: &str) -> Result<String> {
        let project = self.load_project(name)?;

        let mut info = format!("Project: {}\n", project.name);
        if let Some(desc) = &project.description {
            info.push_str(&format!("Description: {desc}\n"));
        }
        info.push_str(&format!("Version: {}\n", project.version));
        info.push_str(&format!("Tags: {}\n", project.tags.join(", ")));

        if !project.metadata.is_empty() {
            info.push_str("\nMetadata:\n");
            for (key, value) in &project.metadata {
                info.push_str(&format!("  {key}: {value}\n"));
            }
        }

        Ok(info)
    }

    /// Simple project identification from current directory
    pub fn identify_current_project(&self) -> Result<String> {
        let project_file = self.workspace_root.join(".vtcode-project");
        if project_file.exists() {
            let content = fs::read_to_string(&project_file)?;
            return Ok(content.trim().to_string());
        }

        self.workspace_root
            .file_name()
            .and_then(|name| name.to_str())
            .map(|name| name.to_string())
            .ok_or_else(|| anyhow::anyhow!("Could not determine project name from directory"))
    }

    /// Set current project
    pub fn set_current_project(&self, name: &str) -> Result<()> {
        let project_file = self.workspace_root.join(".vtcode-project");
        fs::write(project_file, name)?;
        Ok(())
    }
}

/// Simple cache using file system
pub struct SimpleCache {
    cache_dir: PathBuf,
}

impl SimpleCache {
    /// Create a new simple cache
    pub fn new(cache_dir: PathBuf) -> Self {
        Self { cache_dir }
    }

    /// Initialize cache directory
    pub fn init(&self) -> Result<()> {
        canonical_storage_dir(&self.cache_dir)?;
        Ok(())
    }

    /// Store data in cache
    pub fn store(&self, key: &str, data: &str) -> Result<()> {
        let file_path = contained_record_path(&self.cache_dir, key, "txt")?;
        write_with_lock(&file_path, data.as_bytes())
    }

    /// Load data from cache
    pub fn load(&self, key: &str) -> Result<String> {
        let file_path = contained_existing_record_path(&self.cache_dir, key, "txt")?;
        read_with_shared_lock(&file_path).map_err(|err| {
            if err
                .downcast_ref::<std::io::Error>()
                .is_some_and(|io_err| io_err.kind() == std::io::ErrorKind::NotFound)
            {
                anyhow::anyhow!("Cache key '{key}' not found")
            } else {
                err
            }
        })
    }

    /// Check if cache entry exists
    pub fn exists(&self, key: &str) -> bool {
        if validate_record_key(key).is_err() {
            return false;
        }
        self.cache_dir.join(format!("{key}.txt")).exists()
    }

    /// Clear cache
    pub fn clear(&self) -> Result<()> {
        let dir = canonical_existing_storage_dir(&self.cache_dir)?;
        for entry in fs::read_dir(&dir)? {
            let entry = entry?;
            if vtcode_commons::walk::entry_is_file(&entry) {
                fs::remove_file(entry.path())?;
            }
        }
        Ok(())
    }

    /// List cache entries
    pub fn list(&self) -> Result<Vec<String>> {
        let mut entries = Vec::new();
        let dir = canonical_existing_storage_dir(&self.cache_dir)?;
        for entry in fs::read_dir(&dir)? {
            let entry = entry?;
            if let Some(name) = entry.path().file_stem().and_then(|file_name| file_name.to_str()) {
                entries.push(name.to_string());
            }
        }
        Ok(entries)
    }
}