diaryx_core 1.0.0

//! Entry operations module.
//!
//! This module provides functionality for working with individual entries:
//! - Frontmatter manipulation (get, set, remove properties)
//! - Content operations (get, set, append, prepend)
//! - Attachment management
//! - Daily entry creation with index hierarchy
//!
//! # Migration Note
//!
//! `DiaryxAppSync` is deprecated. Use [`DiaryxApp`] with `AsyncFileSystem`
//! for all new code. The sync implementation will be removed in a future version.
//!
//! ```ignore
//! use diaryx_core::entry::DiaryxApp;
//! use diaryx_core::fs::{RealFileSystem, SyncToAsyncFs};
//! use futures_lite::future::block_on;
//!
//! // Use async-first API even in sync contexts
//! let fs = SyncToAsyncFs::new(RealFileSystem);
//! let app = DiaryxApp::new(fs);
//!
//! block_on(app.get_content("note.md"))?;
//! ```

mod helpers;

// Re-export helper functions
pub use helpers::{apply_filename_style, prettify_filename, slugify, slugify_title};

use crate::config::Config;
use crate::date::{date_to_path, parse_date};
use crate::error::{DiaryxError, Result};
use crate::fs::{AsyncFileSystem, FileSystem};
use crate::link_parser;
use crate::template::{Template, TemplateContext, TemplateManager};
use chrono::{NaiveDate, Utc};
use indexmap::IndexMap;
use serde_yaml::Value;
use std::path::{Path, PathBuf};

/// Async-first Diaryx entry operations.
///
/// This is the main entry API going forward.
pub struct DiaryxApp<FS: AsyncFileSystem> {
    fs: FS,
}

/// Legacy synchronous Diaryx entry operations.
///
/// This preserves the prior `FileSystem`-based implementation during the async refactor.
/// Prefer [`DiaryxApp`].
pub struct DiaryxAppSync<FS: FileSystem> {
    fs: FS,
}

impl<FS: AsyncFileSystem> DiaryxApp<FS> {
    /// DiaryxApp constructor
    pub fn new(fs: FS) -> Self {
        Self { fs }
    }

    /// Access the underlying filesystem.
    pub fn fs(&self) -> &FS {
        &self.fs
    }

    /// Create a new entry.
    pub async fn create_entry(&self, path: &str) -> Result<()> {
        let content = format!("---\ntitle: {}\n---\n\n# {}\n\n", path, path);
        self.fs
            .create_new(std::path::Path::new(path), &content)
            .await
            .map_err(|e| DiaryxError::FileWrite {
                path: PathBuf::from(path),
                source: e,
            })?;
        Ok(())
    }

    /// Template-based entry creation is temporarily disabled for the async-first API.
    ///
    /// `TemplateManager` is still `FileSystem`-based. Once it is refactored to `AsyncFileSystem`,
    /// these methods can be re-enabled.
    #[allow(dead_code)]
    pub fn template_manager(&self, _workspace_dir: Option<&Path>) -> TemplateManager<&FS> {
        unimplemented!("TemplateManager is not yet refactored to AsyncFileSystem");
    }

    /// Template-based entry creation is temporarily disabled for the async-first API.
    #[allow(dead_code)]
    pub async fn create_entry_with_template(
        &self,
        _path: &Path,
        _template: &Template,
        _context: &TemplateContext,
    ) -> Result<()> {
        Err(DiaryxError::Unsupported(
            "Template-based entry creation is not yet supported for AsyncFileSystem".to_string(),
        ))
    }

    /// Template-based entry creation is temporarily disabled for the async-first API.
    #[allow(dead_code)]
    pub async fn create_entry_from_template(
        &self,
        _path: &Path,
        _template_name: Option<&str>,
        _title: Option<&str>,
        _workspace_dir: Option<&Path>,
    ) -> Result<()> {
        Err(DiaryxError::Unsupported(
            "Template-based entry creation is not yet supported for AsyncFileSystem".to_string(),
        ))
    }

    /// Parses a markdown file and extracts frontmatter and body.
    /// Returns an error if no frontmatter is found.
    async fn parse_file(&self, path: &str) -> Result<(IndexMap<String, Value>, String)> {
        let path_buf = PathBuf::from(path);
        let content = self
            .fs
            .read_to_string(std::path::Path::new(path))
            .await
            .map_err(|e| DiaryxError::FileRead {
                path: path_buf.clone(),
                source: e,
            })?;

        // Check if content starts with frontmatter delimiter
        if !content.starts_with("---\n") && !content.starts_with("---\r\n") {
            return Err(DiaryxError::NoFrontmatter(path_buf));
        }

        // Find the closing delimiter
        let rest = &content[4..]; // Skip first "---\n"
        let end_idx = rest
            .find("\n---\n")
            .or_else(|| rest.find("\n---\r\n"))
            .ok_or_else(|| DiaryxError::NoFrontmatter(path_buf.clone()))?;

        let frontmatter_str = &rest[..end_idx];
        let body = &rest[end_idx + 5..]; // Skip "\n---\n"

        // Parse YAML frontmatter into IndexMap to preserve order
        let frontmatter: IndexMap<String, Value> = serde_yaml::from_str(frontmatter_str)?;

        Ok((frontmatter, body.to_string()))
    }

    /// Parses a markdown file, creating empty frontmatter if none exists.
    /// Creates the file if it doesn't exist.
    /// Use this for operations that should create frontmatter when missing (like set).
    async fn parse_file_or_create_frontmatter(
        &self,
        path: &str,
    ) -> Result<(IndexMap<String, Value>, String)> {
        let path_buf = PathBuf::from(path);

        // Try to read the file, if it doesn't exist, return empty frontmatter and body
        let content = match self.fs.read_to_string(std::path::Path::new(path)).await {
            Ok(c) => c,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                // File doesn't exist - return empty frontmatter and body
                // The file will be created when reconstruct_file is called
                return Ok((IndexMap::new(), String::new()));
            }
            Err(e) => {
                return Err(DiaryxError::FileRead {
                    path: path_buf,
                    source: e,
                });
            }
        };

        // Check if content starts with frontmatter delimiter
        if !content.starts_with("---\n") && !content.starts_with("---\r\n") {
            // No frontmatter - return empty frontmatter and entire content as body
            return Ok((IndexMap::new(), content));
        }

        // Find the closing delimiter
        let rest = &content[4..]; // Skip first "---\n"
        let end_idx = rest.find("\n---\n").or_else(|| rest.find("\n---\r\n"));

        match end_idx {
            Some(idx) => {
                let frontmatter_str = &rest[..idx];
                let body = &rest[idx + 5..]; // Skip "\n---\n"

                // Parse YAML frontmatter into IndexMap to preserve order
                let frontmatter: IndexMap<String, Value> = serde_yaml::from_str(frontmatter_str)?;

                Ok((frontmatter, body.to_string()))
            }
            None => {
                // Malformed frontmatter (no closing delimiter) - treat as no frontmatter
                Ok((IndexMap::new(), content))
            }
        }
    }

    /// Reconstructs a markdown file with updated frontmatter.
    async fn reconstruct_file(
        &self,
        path: &str,
        frontmatter: &IndexMap<String, Value>,
        body: &str,
    ) -> Result<()> {
        let yaml_str = serde_yaml::to_string(frontmatter)?;
        let content = format!("---\n{}---\n{}", yaml_str, body);
        self.fs
            .write_file(std::path::Path::new(path), &content)
            .await
            .map_err(|e| DiaryxError::FileWrite {
                path: PathBuf::from(path),
                source: e,
            })?;
        Ok(())
    }

    // ==================== Frontmatter Methods ====================

    /// Adds or updates a frontmatter property.
    /// Creates frontmatter if none exists.
    pub async fn set_frontmatter_property(
        &self,
        path: &str,
        key: &str,
        value: Value,
    ) -> Result<()> {
        let (mut frontmatter, body) = self.parse_file_or_create_frontmatter(path).await?;
        frontmatter.insert(key.to_string(), value);
        self.reconstruct_file(path, &frontmatter, &body).await
    }

    /// Removes a frontmatter property.
    /// Does nothing if no frontmatter exists or key is not found.
    pub async fn remove_frontmatter_property(&self, path: &str, key: &str) -> Result<()> {
        match self.parse_file(path).await {
            Ok((mut frontmatter, body)) => {
                frontmatter.shift_remove(key);
                self.reconstruct_file(path, &frontmatter, &body).await
            }
            Err(DiaryxError::NoFrontmatter(_)) => Ok(()), // No frontmatter, nothing to remove
            Err(e) => Err(e),
        }
    }

    /// Renames a frontmatter property key.
    /// Returns Ok(true) if the key was found and renamed, Ok(false) if key was not found or no frontmatter.
    pub async fn rename_frontmatter_property(
        &self,
        path: &str,
        old_key: &str,
        new_key: &str,
    ) -> Result<bool> {
        let (frontmatter, body) = match self.parse_file(path).await {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(false), // No frontmatter, key not found
            Err(e) => return Err(e),
        };

        if !frontmatter.contains_key(old_key) {
            return Ok(false);
        }

        // Rebuild the map, replacing old_key with new_key at the same position
        let mut result: IndexMap<String, Value> = IndexMap::new();
        for (k, v) in frontmatter {
            if k == old_key {
                result.insert(new_key.to_string(), v);
            } else {
                result.insert(k, v);
            }
        }

        self.reconstruct_file(path, &result, &body).await?;
        Ok(true)
    }

    /// Gets a frontmatter property value.
    /// Returns Ok(None) if no frontmatter exists or key is not found.
    pub async fn get_frontmatter_property(&self, path: &str, key: &str) -> Result<Option<Value>> {
        match self.parse_file(path).await {
            Ok((frontmatter, _)) => Ok(frontmatter.get(key).cloned()),
            Err(DiaryxError::NoFrontmatter(_)) => Ok(None), // No frontmatter, key not found
            Err(e) => Err(e),
        }
    }

    /// Gets all frontmatter properties.
    /// Returns empty map if no frontmatter exists.
    pub async fn get_all_frontmatter(&self, path: &str) -> Result<IndexMap<String, Value>> {
        match self.parse_file(path).await {
            Ok((frontmatter, _)) => Ok(frontmatter),
            Err(DiaryxError::NoFrontmatter(_)) => Ok(IndexMap::new()), // No frontmatter, return empty
            Err(e) => Err(e),
        }
    }

    // ==================== Content Methods ====================

    /// Get the content (body) of a file, excluding frontmatter.
    pub async fn get_content(&self, path: &str) -> Result<String> {
        let (_, body) = self.parse_file_or_create_frontmatter(path).await?;
        Ok(body)
    }

    /// Set the content (body) of a file, preserving frontmatter.
    /// Creates frontmatter if none exists.
    pub async fn set_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, _) = self.parse_file_or_create_frontmatter(path).await?;
        self.reconstruct_file(path, &frontmatter, content).await
    }

    /// Clear the content (body) of a file, preserving frontmatter.
    pub async fn clear_content(&self, path: &str) -> Result<()> {
        self.set_content(path, "").await
    }

    /// Update the 'updated' frontmatter property with the current timestamp (RFC 3339 format).
    /// Creates frontmatter if none exists.
    pub async fn touch_updated(&self, path: &str) -> Result<()> {
        let timestamp = Utc::now().format("%Y-%m-%dT%H:%M:%SZ").to_string();
        self.set_frontmatter_property(path, "updated", Value::String(timestamp))
            .await
    }

    /// Save content and optionally update the 'updated' timestamp.
    /// When `auto_update_timestamp` is true (the default), this combines set_content and touch_updated.
    pub async fn save_content(&self, path: &str, content: &str) -> Result<()> {
        self.save_content_with_options(path, content, true).await
    }

    /// Save content with explicit control over timestamp updating.
    pub async fn save_content_with_options(
        &self,
        path: &str,
        content: &str,
        auto_update_timestamp: bool,
    ) -> Result<()> {
        self.set_content(path, content).await?;
        if auto_update_timestamp {
            self.touch_updated(path).await?;
        }
        Ok(())
    }

    /// Append content to the end of a file's body.
    pub async fn append_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, body) = self.parse_file_or_create_frontmatter(path).await?;
        let new_body = if body.is_empty() {
            content.to_string()
        } else if body.ends_with('\n') {
            format!("{}{}", body, content)
        } else {
            format!("{}\n{}", body, content)
        };
        self.reconstruct_file(path, &frontmatter, &new_body).await
    }

    /// Prepend content to the beginning of a file's body.
    pub async fn prepend_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, body) = self.parse_file_or_create_frontmatter(path).await?;
        let new_body = if body.is_empty() {
            content.to_string()
        } else if content.ends_with('\n') {
            format!("{}{}", content, body)
        } else {
            format!("{}\n{}", content, body)
        };
        self.reconstruct_file(path, &frontmatter, &new_body).await
    }

    // ==================== Attachment Methods ====================

    /// Add an attachment path to the entry's attachments list.
    /// Creates the attachments property if it doesn't exist.
    pub async fn add_attachment(&self, path: &str, attachment_path: &str) -> Result<()> {
        let (mut frontmatter, body) = self.parse_file_or_create_frontmatter(path).await?;

        let attachments = frontmatter
            .entry("attachments".to_string())
            .or_insert(Value::Sequence(vec![]));

        if let Value::Sequence(list) = attachments {
            let new_attachment = Value::String(attachment_path.to_string());
            if !list.contains(&new_attachment) {
                list.push(new_attachment);
            }
        }

        self.reconstruct_file(path, &frontmatter, &body).await
    }

    /// Remove an attachment path from the entry's attachments list.
    /// Does nothing if the attachment isn't found.
    pub async fn remove_attachment(&self, path: &str, attachment_path: &str) -> Result<()> {
        let (mut frontmatter, body) = match self.parse_file(path).await {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(()),
            Err(e) => return Err(e),
        };

        if let Some(Value::Sequence(list)) = frontmatter.get_mut("attachments") {
            list.retain(|item| {
                if let Value::String(s) = item {
                    s != attachment_path
                } else {
                    true
                }
            });

            // Remove empty attachments array
            if list.is_empty() {
                frontmatter.shift_remove("attachments");
            }
        }

        self.reconstruct_file(path, &frontmatter, &body).await
    }

    /// Get the list of attachments directly declared in this entry.
    pub async fn get_attachments(&self, path: &str) -> Result<Vec<String>> {
        let (frontmatter, _) = match self.parse_file(path).await {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(vec![]),
            Err(e) => return Err(e),
        };

        match frontmatter.get("attachments") {
            Some(Value::Sequence(list)) => Ok(list
                .iter()
                .filter_map(|v| {
                    if let Value::String(s) = v {
                        Some(s.clone())
                    } else {
                        None
                    }
                })
                .collect()),
            _ => Ok(vec![]),
        }
    }
}

impl<FS: FileSystem> DiaryxAppSync<FS> {
    /// DiaryxAppSync constructor
    pub fn new(fs: FS) -> Self {
        Self { fs }
    }

    /// Access the underlying filesystem.
    pub fn fs(&self) -> &FS {
        &self.fs
    }

    /// Create a new entry
    pub fn create_entry(&self, path: &str) -> Result<()> {
        let content = format!("---\ntitle: {}\n---\n\n# {}\n\n", path, path);
        self.fs.create_new(std::path::Path::new(path), &content)?;
        Ok(())
    }

    /// Create a new entry using a template
    ///
    /// # Arguments
    /// * `path` - Path where the entry will be created
    /// * `template` - The template to use
    /// * `context` - Context for variable substitution
    pub fn create_entry_with_template(
        &self,
        path: &Path,
        template: &Template,
        context: &TemplateContext,
    ) -> Result<()> {
        let content = template.render(context);
        self.fs.create_new(path, &content)?;
        Ok(())
    }

    /// Create a new entry, optionally using a template
    ///
    /// If template_name is provided, looks up the template and uses it.
    /// Falls back to the "note" built-in template if not found.
    ///
    /// # Arguments
    /// * `path` - Path where the entry will be created
    /// * `template_name` - Optional template name to use
    /// * `title` - Optional title for the entry
    /// * `workspace_dir` - Optional workspace directory for template lookup
    pub fn create_entry_from_template(
        &self,
        path: &Path,
        template_name: Option<&str>,
        title: Option<&str>,
        workspace_dir: Option<&Path>,
    ) -> Result<()> {
        let manager = self.template_manager(workspace_dir);

        // Get template (use "note" as default)
        let template_name = template_name.unwrap_or("note");
        let template = manager
            .get(template_name)
            .ok_or_else(|| DiaryxError::TemplateNotFound(template_name.to_string()))?;

        // Build context
        let filename = path
            .file_stem()
            .and_then(|s| s.to_str())
            .unwrap_or("Untitled");

        let mut context = TemplateContext::new().with_filename(filename);

        if let Some(t) = title {
            context = context.with_title(t);
        } else {
            // Use filename as title, but prettified
            context = context.with_title(prettify_filename(filename));
        }

        self.create_entry_with_template(path, &template, &context)
    }

    /// Get a template manager configured for this app
    pub fn template_manager(&self, workspace_dir: Option<&Path>) -> TemplateManager<&FS> {
        let mut manager = TemplateManager::new(&self.fs);
        if let Some(dir) = workspace_dir {
            manager = manager.with_workspace_dir(dir);
        }
        manager
    }

    /// Parses a markdown file and extracts frontmatter and body
    /// Returns an error if no frontmatter is found
    fn parse_file(&self, path: &str) -> Result<(IndexMap<String, Value>, String)> {
        let path_buf = PathBuf::from(path);
        let content = self
            .fs
            .read_to_string(std::path::Path::new(path))
            .map_err(|e| DiaryxError::FileRead {
                path: path_buf.clone(),
                source: e,
            })?;

        // Check if content starts with frontmatter delimiter
        if !content.starts_with("---\n") && !content.starts_with("---\r\n") {
            return Err(DiaryxError::NoFrontmatter(path_buf));
        }

        // Find the closing delimiter
        let rest = &content[4..]; // Skip first "---\n"
        let end_idx = rest
            .find("\n---\n")
            .or_else(|| rest.find("\n---\r\n"))
            .ok_or_else(|| DiaryxError::NoFrontmatter(path_buf.clone()))?;

        let frontmatter_str = &rest[..end_idx];
        let body = &rest[end_idx + 5..]; // Skip "\n---\n"

        // Parse YAML frontmatter into IndexMap to preserve order
        let frontmatter: IndexMap<String, Value> = serde_yaml::from_str(frontmatter_str)?;

        Ok((frontmatter, body.to_string()))
    }

    /// Parses a markdown file, creating empty frontmatter if none exists.
    /// Creates the file if it doesn't exist.
    /// Use this for operations that should create frontmatter when missing (like set).
    fn parse_file_or_create_frontmatter(
        &self,
        path: &str,
    ) -> Result<(IndexMap<String, Value>, String)> {
        let path_buf = PathBuf::from(path);

        // Try to read the file, if it doesn't exist, return empty frontmatter and body
        let content = match self.fs.read_to_string(std::path::Path::new(path)) {
            Ok(c) => c,
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
                // File doesn't exist - return empty frontmatter and body
                // The file will be created when reconstruct_file is called
                return Ok((IndexMap::new(), String::new()));
            }
            Err(e) => {
                return Err(DiaryxError::FileRead {
                    path: path_buf,
                    source: e,
                });
            }
        };

        // Check if content starts with frontmatter delimiter
        if !content.starts_with("---\n") && !content.starts_with("---\r\n") {
            // No frontmatter - return empty frontmatter and entire content as body
            return Ok((IndexMap::new(), content));
        }

        // Find the closing delimiter
        let rest = &content[4..]; // Skip first "---\n"
        let end_idx = rest.find("\n---\n").or_else(|| rest.find("\n---\r\n"));

        match end_idx {
            Some(idx) => {
                let frontmatter_str = &rest[..idx];
                let body = &rest[idx + 5..]; // Skip "\n---\n"

                // Parse YAML frontmatter into IndexMap to preserve order
                let frontmatter: IndexMap<String, Value> = serde_yaml::from_str(frontmatter_str)?;

                Ok((frontmatter, body.to_string()))
            }
            None => {
                // Malformed frontmatter (no closing delimiter) - treat as no frontmatter
                Ok((IndexMap::new(), content))
            }
        }
    }

    /// Reconstructs a markdown file with updated frontmatter.
    fn reconstruct_file(
        &self,
        path: &str,
        frontmatter: &IndexMap<String, Value>,
        body: &str,
    ) -> Result<()> {
        let yaml_str = serde_yaml::to_string(frontmatter)?;
        let content = format!("---\n{}---\n{}", yaml_str, body);
        self.fs
            .write_file(std::path::Path::new(path), &content)
            .map_err(|e| DiaryxError::FileWrite {
                path: PathBuf::from(path),
                source: e,
            })?;
        Ok(())
    }

    /// Adds or updates a frontmatter property.
    /// Creates frontmatter if none exists.
    pub fn set_frontmatter_property(&self, path: &str, key: &str, value: Value) -> Result<()> {
        let (mut frontmatter, body) = self.parse_file_or_create_frontmatter(path)?;
        frontmatter.insert(key.to_string(), value);
        self.reconstruct_file(path, &frontmatter, &body)
    }

    /// Removes a frontmatter property.
    /// Does nothing if no frontmatter exists or key is not found.
    pub fn remove_frontmatter_property(&self, path: &str, key: &str) -> Result<()> {
        match self.parse_file(path) {
            Ok((mut frontmatter, body)) => {
                frontmatter.shift_remove(key);
                self.reconstruct_file(path, &frontmatter, &body)
            }
            Err(DiaryxError::NoFrontmatter(_)) => Ok(()), // No frontmatter, nothing to remove
            Err(e) => Err(e),
        }
    }

    /// Renames a frontmatter property key.
    /// Returns Ok(true) if the key was found and renamed, Ok(false) if key was not found or no frontmatter.
    pub fn rename_frontmatter_property(
        &self,
        path: &str,
        old_key: &str,
        new_key: &str,
    ) -> Result<bool> {
        let (frontmatter, body) = match self.parse_file(path) {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(false), // No frontmatter, key not found
            Err(e) => return Err(e),
        };

        if !frontmatter.contains_key(old_key) {
            return Ok(false);
        }

        // Rebuild the map, replacing old_key with new_key at the same position
        let mut result: IndexMap<String, Value> = IndexMap::new();
        for (k, v) in frontmatter {
            if k == old_key {
                result.insert(new_key.to_string(), v);
            } else {
                result.insert(k, v);
            }
        }

        self.reconstruct_file(path, &result, &body)?;
        Ok(true)
    }

    /// Get body content (excluding frontmatter). If no frontmatter exists, returns entire file.
    pub fn get_content(&self, path: &str) -> Result<String> {
        match self.parse_file_or_create_frontmatter(path) {
            Ok((_frontmatter, body)) => Ok(body),
            Err(e) => Err(e),
        }
    }

    /// Set body content, preserving (or creating) frontmatter.
    pub fn set_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, _old_body) = self.parse_file_or_create_frontmatter(path)?;
        self.reconstruct_file(path, &frontmatter, content)
    }

    /// Clear file body content.
    pub fn clear_content(&self, path: &str) -> Result<()> {
        self.set_content(path, "")
    }

    /// Append content to end of body.
    pub fn append_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, mut body) = self.parse_file_or_create_frontmatter(path)?;

        if body.is_empty() {
            body = content.to_string();
        } else if body.ends_with('\n') {
            body.push_str(content);
        } else {
            body.push('\n');
            body.push_str(content);
        }

        self.reconstruct_file(path, &frontmatter, &body)
    }

    /// Prepend content to start of body.
    pub fn prepend_content(&self, path: &str, content: &str) -> Result<()> {
        let (frontmatter, body) = self.parse_file_or_create_frontmatter(path)?;
        let new_body = if body.is_empty() {
            content.to_string()
        } else if content.ends_with('\n') {
            format!("{}{}", content, body)
        } else {
            format!("{}\n{}", content, body)
        };
        self.reconstruct_file(path, &frontmatter, &new_body)
    }

    /// Gets a frontmatter property value.
    /// Returns Ok(None) if no frontmatter exists or key is not found.
    pub fn get_frontmatter_property(&self, path: &str, key: &str) -> Result<Option<Value>> {
        match self.parse_file(path) {
            Ok((frontmatter, _)) => Ok(frontmatter.get(key).cloned()),
            Err(DiaryxError::NoFrontmatter(_)) => Ok(None), // No frontmatter, key not found
            Err(e) => Err(e),
        }
    }

    /// Gets all frontmatter properties.
    /// Returns empty map if no frontmatter exists.
    pub fn get_all_frontmatter(&self, path: &str) -> Result<IndexMap<String, Value>> {
        match self.parse_file(path) {
            Ok((frontmatter, _)) => Ok(frontmatter),
            Err(DiaryxError::NoFrontmatter(_)) => Ok(IndexMap::new()), // No frontmatter, return empty
            Err(e) => Err(e),
        }
    }

    // ==================== Attachment Methods ====================

    /// Add an attachment path to the entry's attachments list.
    /// Creates the attachments property if it doesn't exist.
    pub fn add_attachment(&self, path: &str, attachment_path: &str) -> Result<()> {
        let (mut frontmatter, body) = self.parse_file_or_create_frontmatter(path)?;

        let attachments = frontmatter
            .entry("attachments".to_string())
            .or_insert(Value::Sequence(vec![]));

        if let Value::Sequence(list) = attachments {
            let new_attachment = Value::String(attachment_path.to_string());
            if !list.contains(&new_attachment) {
                list.push(new_attachment);
            }
        }

        self.reconstruct_file(path, &frontmatter, &body)
    }

    /// Remove an attachment path from the entry's attachments list.
    /// Does nothing if the attachment isn't found.
    pub fn remove_attachment(&self, path: &str, attachment_path: &str) -> Result<()> {
        let (mut frontmatter, body) = match self.parse_file(path) {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(()),
            Err(e) => return Err(e),
        };

        if let Some(Value::Sequence(list)) = frontmatter.get_mut("attachments") {
            list.retain(|item| {
                if let Value::String(s) = item {
                    s != attachment_path
                } else {
                    true
                }
            });

            // Remove empty attachments array
            if list.is_empty() {
                frontmatter.shift_remove("attachments");
            }
        }

        self.reconstruct_file(path, &frontmatter, &body)
    }

    /// Get the list of attachments directly declared in this entry.
    pub fn get_attachments(&self, path: &str) -> Result<Vec<String>> {
        let (frontmatter, _) = match self.parse_file(path) {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(vec![]),
            Err(e) => return Err(e),
        };

        match frontmatter.get("attachments") {
            Some(Value::Sequence(list)) => Ok(list
                .iter()
                .filter_map(|v| {
                    if let Value::String(s) = v {
                        Some(s.clone())
                    } else {
                        None
                    }
                })
                .collect()),
            _ => Ok(vec![]),
        }
    }

    /// Resolve an attachment by traversing up the index hierarchy via part_of.
    /// Returns the absolute path to the attachment if found, or None.
    pub fn resolve_attachment(
        &self,
        entry_path: &str,
        attachment_name: &str,
    ) -> Result<Option<PathBuf>> {
        use crate::workspace::IndexFrontmatter;

        let entry_path = Path::new(entry_path);
        let entry_dir = entry_path.parent().unwrap_or(Path::new("."));

        // Parse the file's frontmatter inline (to avoid async Workspace dependency)
        let content = match self.fs.read_to_string(entry_path) {
            Ok(c) => c,
            Err(_) => return Ok(None),
        };

        // Parse frontmatter
        if !content.starts_with("---\n") && !content.starts_with("---\r\n") {
            return Ok(None);
        }

        let rest = &content[4..];
        let end_idx = match rest.find("\n---\n").or_else(|| rest.find("\n---\r\n")) {
            Some(idx) => idx,
            None => return Ok(None),
        };

        let frontmatter_str = &rest[..end_idx];
        let frontmatter: IndexFrontmatter = match serde_yaml::from_str(frontmatter_str) {
            Ok(fm) => fm,
            Err(_) => return Ok(None),
        };

        // First, check attachments directly on this entry
        for att_path in frontmatter.attachments_list() {
            // Parse through link_parser to handle markdown links and different path formats
            let parsed = link_parser::parse_link(att_path);
            let resolved = entry_dir.join(&parsed.path);
            if resolved.file_name().map(|n| n.to_string_lossy()) == Some(attachment_name.into())
                && self.fs.exists(&resolved)
            {
                return Ok(Some(resolved));
            }
            // Also check if the path itself matches
            if parsed.path == attachment_name
                || parsed.path.ends_with(&format!("/{}", attachment_name))
            {
                let resolved = entry_dir.join(&parsed.path);
                if self.fs.exists(&resolved) {
                    return Ok(Some(resolved));
                }
            }
        }

        // Traverse up via part_of
        if let Some(ref parent_rel) = frontmatter.part_of {
            let parsed_parent = link_parser::parse_link(parent_rel);
            let canonical_parent = link_parser::to_canonical(&parsed_parent, entry_path);
            let parent_path = PathBuf::from(canonical_parent);
            if self.fs.exists(&parent_path) {
                return self.resolve_attachment(&parent_path.to_string_lossy(), attachment_name);
            }
        }

        Ok(None)
    }

    // ==================== Frontmatter Sorting ====================

    /// Sort frontmatter keys according to a pattern.
    /// Pattern is comma-separated keys, with "*" meaning "rest alphabetically".
    /// Example: "title,description,*" puts title first, description second, rest alphabetically
    /// Does nothing if no frontmatter exists (won't add empty frontmatter).
    pub fn sort_frontmatter(&self, path: &str, pattern: Option<&str>) -> Result<()> {
        let (frontmatter, body) = match self.parse_file(path) {
            Ok(result) => result,
            Err(DiaryxError::NoFrontmatter(_)) => return Ok(()), // No frontmatter, nothing to sort
            Err(e) => return Err(e),
        };

        let sorted = match pattern {
            Some(p) => self.sort_by_pattern(frontmatter, p),
            None => self.sort_alphabetically(frontmatter),
        };

        self.reconstruct_file(path, &sorted, &body)
    }

    fn sort_alphabetically(&self, frontmatter: IndexMap<String, Value>) -> IndexMap<String, Value> {
        let mut pairs: Vec<_> = frontmatter.into_iter().collect();
        pairs.sort_by(|a, b| a.0.cmp(&b.0));
        pairs.into_iter().collect()
    }

    fn sort_by_pattern(
        &self,
        frontmatter: IndexMap<String, Value>,
        pattern: &str,
    ) -> IndexMap<String, Value> {
        let priority_keys: Vec<&str> = pattern.split(',').map(|s| s.trim()).collect();

        let mut result = IndexMap::new();
        let mut remaining: IndexMap<String, Value> = frontmatter;

        for key in &priority_keys {
            if *key == "*" {
                // Insert remaining keys alphabetically
                let mut rest: Vec<_> = remaining.drain(..).collect();
                rest.sort_by(|a, b| a.0.cmp(&b.0));
                for (k, v) in rest {
                    result.insert(k, v);
                }
                break;
            } else if let Some(value) = remaining.shift_remove(*key) {
                result.insert(key.to_string(), value);
            }
        }

        // If no "*" was in pattern, append any remaining keys alphabetically.
        if !remaining.is_empty() {
            let mut rest: Vec<_> = remaining.drain(..).collect();
            rest.sort_by(|a, b| a.0.cmp(&b.0));
            for (k, v) in rest {
                result.insert(k, v);
            }
        }

        result
    }

    /// Get the full path for a date-based entry.
    pub fn get_dated_entry_path(&self, date_str: &str, config: &Config) -> Result<PathBuf> {
        let date = parse_date(date_str)?;
        Ok(date_to_path(&config.daily_entry_dir(), &date))
    }

    /// Resolve a path string - either a date string ("today", "2024-01-15") or a literal path.
    /// If it parses as a date, returns the dated entry path. Otherwise, treats it as a literal path.
    pub fn resolve_path(&self, path_str: &str, config: &Config) -> PathBuf {
        // Try to parse as a date first
        if let Ok(date) = parse_date(path_str) {
            date_to_path(&config.daily_entry_dir(), &date)
        } else {
            // Treat as literal path
            PathBuf::from(path_str)
        }
    }

    /// Create a dated entry with proper frontmatter and index hierarchy.
    pub fn create_dated_entry(&self, date: &NaiveDate, config: &Config) -> Result<PathBuf> {
        self.create_dated_entry_with_template(date, config, None)
    }

    /// Create a dated entry with an optional template.
    ///
    /// If template_name is provided, uses that template.
    /// Otherwise uses `daily_template` from config, or falls back to built-in "daily" template.
    pub fn create_dated_entry_with_template(
        &self,
        date: &NaiveDate,
        config: &Config,
        template_name: Option<&str>,
    ) -> Result<PathBuf> {
        let daily_dir = config.daily_entry_dir();
        let path = date_to_path(&daily_dir, date);

        // Create parent directories if they don't exist
        if let Some(parent) = path.parent() {
            self.fs.create_dir_all(parent)?;
        }

        // Ensure the index hierarchy exists
        self.ensure_daily_index_hierarchy(date, config)?;

        // Get template
        let manager = self.template_manager(Some(&config.default_workspace));

        // Priority: explicit template_name > "daily" built-in
        let effective_template_name = template_name.unwrap_or("daily");

        let template = manager
            .get(effective_template_name)
            .ok_or_else(|| DiaryxError::TemplateNotFound(effective_template_name.to_string()))?;

        // Build context
        let title = date.format("%B %d, %Y").to_string(); // e.g., "January 15, 2024"
        let month_index_name = Self::month_index_filename(date);

        // Compute canonical paths for proper linking (workspace-relative)
        let daily_prefix = config.daily_entry_folder.clone().unwrap_or_default();
        let daily_prefix = daily_prefix.trim_start_matches('/').to_string(); // canonical has no leading slash

        // Helper to join paths with slash, avoiding double slashes or empty segments
        let join_path = |base: &str, part: &str| -> String {
            if base.is_empty() {
                part.to_string()
            } else {
                format!("{}/{}", base, part)
            }
        };

        let year = date.format("%Y").to_string();
        let month = date.format("%m").to_string();
        let month_index_canonical = join_path(
            &daily_prefix,
            &format!("{}/{}/{}", year, month, month_index_name),
        );

        let entry_filename = format!("{}.md", date.format("%Y-%m-%d"));
        let entry_canonical = join_path(
            &daily_prefix,
            &format!("{}/{}/{}", year, month, entry_filename),
        );

        let context = TemplateContext::new()
            .with_title(&title)
            .with_date(*date)
            // Use configured link format for frontmatter links
            .with_part_of(link_parser::format_link_with_format(
                &month_index_canonical,
                &link_parser::path_to_title(&month_index_name),
                config.link_format,
                &entry_canonical,
            ));

        let content = template.render(&context);
        self.fs.create_new(&path, &content)?;

        // Add entry to month index contents
        let month_index_path = path.parent().unwrap().join(&month_index_name);

        // Format the link according to config
        let link = link_parser::format_link_with_format(
            &entry_canonical,
            &link_parser::path_to_title(&entry_filename),
            config.link_format,
            &month_index_canonical,
        );

        self.add_to_index_contents(&month_index_path, &link)?;

        Ok(path)
    }

    /// Ensure a dated entry exists, creating it if necessary.
    /// This will NEVER overwrite an existing file.
    pub fn ensure_dated_entry(&self, date: &NaiveDate, config: &Config) -> Result<PathBuf> {
        self.ensure_dated_entry_with_template(date, config, None)
    }

    /// Ensure a dated entry exists with an optional template.
    /// This will NEVER overwrite an existing file.
    pub fn ensure_dated_entry_with_template(
        &self,
        date: &NaiveDate,
        config: &Config,
        template_name: Option<&str>,
    ) -> Result<PathBuf> {
        let path = date_to_path(&config.daily_entry_dir(), date);

        // Check if file already exists using filesystem trait
        if self.fs.exists(&path) {
            return Ok(path);
        }

        // Create the entry (create_new will fail if file exists)
        // Check for duplicates before creating
        if let Err(_e) = self.validate_daily_hierarchy(date, config) {
            // Note: We just log validation errors for now during creation,
            // as we want creation to succeed even if there are warnings.
            // In the future this could be more aggressive.
            // We use standard error output or logging mechanism.
            // For now, since this returns Result, we won't fail here.
        }

        // Always ensure hierarchy exists and is correct
        self.ensure_daily_index_hierarchy(date, config)?;

        self.create_dated_entry_with_template(date, config, template_name)
    }

    /// Validates the daily hierarchy for a given date.
    /// Returns a list of strings (warnings) for any detached nodes or duplicates.
    pub fn validate_daily_hierarchy(
        &self,
        date: &NaiveDate,
        config: &Config,
    ) -> Result<Vec<String>> {
        let mut warnings = Vec::new();
        let daily_dir = config.daily_entry_dir();

        // 1. Check for duplicates
        let duplicates = self.detect_duplicates(date, config)?;
        for dup in duplicates {
            warnings.push(format!("Duplicate folder found: {}", dup));
        }

        // 2. Check connections
        let year = date.format("%Y").to_string();
        let month = date.format("%m").to_string();

        let daily_index_path = daily_dir.join("daily_index.md");
        let year_dir = daily_dir.join(&year);
        let year_index_path = year_dir.join(Self::year_index_filename(date));
        let month_dir = year_dir.join(&month);
        let _month_index_path = month_dir.join(Self::month_index_filename(date));

        // Check daily index <-> year link
        if self.fs.exists(&year_index_path) {
            let year_index_name = Self::year_index_filename(date);
            if self.fs.exists(&daily_index_path) {
                let year_index_rel = format!("{}/{}", year, year_index_name);
                let daily_content =
                    self.get_frontmatter_property(&daily_index_path.to_string_lossy(), "contents")?;

                let is_linked = match daily_content {
                    Some(Value::Sequence(seq)) => {
                        seq.iter().any(|v| v.as_str() == Some(&year_index_rel))
                    }
                    _ => false,
                };

                if !is_linked {
                    warnings.push(format!(
                        "Year index {} is not listed in daily_index.md contents",
                        year
                    ));
                }
            }
        }

        Ok(warnings)
    }

    /// Detects duplicate month/year folders.
    /// Returns a list of paths that are duplicates of the canonical paths.
    pub fn detect_duplicates(&self, date: &NaiveDate, config: &Config) -> Result<Vec<String>> {
        let mut duplicates = Vec::new();
        let daily_dir = config.daily_entry_dir();

        // Check Year duplicates (e.g. "2024" vs "2024 (1)") - unlikely for year numbers but good to have
        // Actually, more common is names vs numbers for months.

        let year = date.format("%Y").to_string();
        let month = date.format("%m").to_string(); // "01", "02"
        let month_name = date.format("%B").to_string(); // "January"

        // Canonical structure is daily_dir/YYYY/MM
        let year_dir = daily_dir.join(&year);

        // Check for month duplicates in year directory
        if self.fs.exists(&year_dir) {
            // Check if "January" exists alongside "01"
            let named_month_path = year_dir.join(&month_name);
            let _numbered_month_path = year_dir.join(&month);

            // If we are using numbered months (default), check if named month exists
            if self.fs.exists(&named_month_path) && month_name != month {
                duplicates.push(named_month_path.to_string_lossy().to_string());
            }
        }

        Ok(duplicates)
    }

    /// Merges duplicates into the canonical path.
    /// Moves files from source to dest, then deletes source.
    pub fn merge_duplicates(&self, from_path: &Path, to_path: &Path) -> Result<()> {
        if !self.fs.exists(from_path) {
            return Ok(());
        }

        self.fs.create_dir_all(to_path)?;

        // Move all files
        // Since list_all_files_recursive is async and we are in sync shim,
        // we might need to rely on the underlying fs being efficient or implementation details.
        // But wait, we are in DiaryxAppSync which holds FS: FileSystem (sync trait).
        // The sync FileSystem trait has `list_files`.

        // Basic merge strategy:
        // 1. List files in from_path
        // 2. Move each to to_path
        // 3. Remove from_path

        let entries = self.fs.list_files(from_path)?;
        for entry in entries {
            let file_name = entry.file_name().unwrap_or_default();
            let dest = to_path.join(file_name);

            if self.fs.is_dir(&entry) {
                // Recursive merge
                self.merge_duplicates(&entry, &dest)?;
            } else {
                // Move file
                // If dest exists, we might overwrite or rename. For now, let's assume valid merge and overwrite or skip?
                // Safest is to not overwrite if exists? But then we leave duplicates.
                // Let's try to move.
                if self.fs.exists(&dest) {
                    // Conflict. Append timestamp?
                    // Or just skip for now to be safe.
                } else {
                    self.fs.move_file(&entry, &dest)?;
                }
            }
        }

        // If directory is empty, remove it
        let remaining = self.fs.list_files(from_path)?;
        if remaining.is_empty() {
            self.fs.delete_file(from_path)?;
        }

        Ok(())
    }

    /// Ensure the daily index hierarchy exists for a given date.
    /// Creates: daily_index.md -> YYYY_index.md -> YYYY_month.md
    /// Also connects daily_index.md to workspace root if daily_entry_folder is configured.
    fn ensure_daily_index_hierarchy(&self, date: &NaiveDate, config: &Config) -> Result<()> {
        let daily_dir = config.daily_entry_dir();
        let year = date.format("%Y").to_string();
        let month = date.format("%m").to_string();

        // Compute canonical paths for properly formatted linking (workspace-relative)
        let daily_prefix = config.daily_entry_folder.clone().unwrap_or_default();
        let daily_prefix = daily_prefix.trim_start_matches('/').to_string(); // canonical has no leading slash

        // Helper to join paths with slash, avoiding double slashes or empty segments
        // We use forward slashes for canonical paths even on Windows
        let join_path = |base: &str, part: &str| -> String {
            if base.is_empty() {
                part.to_string()
            } else {
                format!("{}/{}", base, part)
            }
        };

        let daily_index_filename = "daily_index.md";
        let daily_index_canonical = join_path(&daily_prefix, daily_index_filename);
        let daily_index_path = daily_dir.join(daily_index_filename);

        let year_index_filename = Self::year_index_filename(date);
        let year_index_canonical =
            join_path(&daily_prefix, &format!("{}/{}", year, year_index_filename));
        let year_dir = daily_dir.join(&year);
        let year_index_path = year_dir.join(&year_index_filename);

        let month_index_filename = Self::month_index_filename(date);
        let month_index_canonical = join_path(
            &daily_prefix,
            &format!("{}/{}/{}", year, month, month_index_filename),
        );
        let month_dir = year_dir.join(&month);
        let month_index_path = month_dir.join(&month_index_filename);

        // Create directories
        self.fs.create_dir_all(&month_dir)?;

        // 1. Ensure daily_index.md exists
        let daily_index_created = !self.fs.exists(&daily_index_path);
        if daily_index_created {
            // Determine if we should link to workspace root
            let part_of = if config.daily_entry_folder.is_some() {
                // Daily folder is configured, try to link to workspace root
                self.find_workspace_root_relative(&daily_dir)
            } else {
                None
            };
            self.create_daily_index(&daily_index_path, part_of.as_deref())?;

            // If we have a workspace root, add daily_index to its contents
            if let Some(ref root_rel) = part_of {
                // Determine workspace root absolute path
                let workspace_root = daily_dir.join(root_rel);

                // We need canonical path of workspace root (which is empty string if it's root)
                // or we rely on the fact that daily_index_canonical is already correct relative to it.
                // format_link_with_format for linking TO daily_index FROM root.
                // From root: current path is "" (or root index name).

                // Let's deduce root canonical path.
                // If daily_prefix is "Daily", then root is "".
                let root_canonical = "";

                if self.fs.exists(&workspace_root) {
                    let link = link_parser::format_link_with_format(
                        &daily_index_canonical,
                        "Daily Index",
                        config.link_format,
                        root_canonical,
                    );

                    self.add_to_index_contents(&workspace_root, &link)?;
                }
            }
        }

        // 2. Ensure year index exists
        if !self.fs.exists(&year_index_path) {
            // Create link from Year Index TO Daily Index (part_of)
            let part_of_link = link_parser::format_link_with_format(
                &daily_index_canonical,
                "Daily Index",
                config.link_format,
                &year_index_canonical,
            );
            self.create_year_index(&year_index_path, date, &part_of_link)?;
        }

        // Ensure year index is in daily index contents
        // Link from Daily Index TO Year Index
        let link = link_parser::format_link_with_format(
            &year_index_canonical,
            &year,
            config.link_format,
            &daily_index_canonical,
        );
        self.add_to_index_contents(&daily_index_path, &link)?;

        // 3. Ensure month index exists
        if !self.fs.exists(&month_index_path) {
            // Create link from Month Index TO Year Index (part_of)
            let part_of_link = link_parser::format_link_with_format(
                &year_index_canonical,
                &year,
                config.link_format,
                &month_index_canonical,
            );
            self.create_month_index(&month_index_path, date, &part_of_link)?;
        }

        // Ensure month index is in year index contents
        // Link from Year Index TO Month Index
        let link = link_parser::format_link_with_format(
            &month_index_canonical,
            &date.format("%B").to_string(), // Month name
            config.link_format,
            &year_index_canonical,
        );
        self.add_to_index_contents(&year_index_path, &link)?;

        Ok(())
    }

    /// Find the workspace root index relative to a directory.
    fn find_workspace_root_relative(&self, from_dir: &Path) -> Option<String> {
        // Look for any index file in parent directory (workspace root)
        let parent = from_dir.parent()?;

        // Try common index file patterns
        let candidates = [
            // New naming convention: {dirname}.md
            parent
                .file_name()
                .and_then(|n| n.to_str())
                .map(|name| format!("{}.md", name)),
            // Legacy README.md
            Some("README.md".to_string()),
            // Legacy index.md
            Some("index.md".to_string()),
        ];

        for candidate in candidates.iter().flatten() {
            let index_path = parent.join(candidate);
            if self.fs.exists(&index_path) {
                // Check if it's actually an index (has contents property)
                let index_str = index_path.to_string_lossy();
                if let Ok(Some(_)) = self.get_frontmatter_property(&index_str, "contents") {
                    return Some(format!("../{}", candidate));
                }
            }
        }

        None
    }

    /// Create the root daily index file.
    fn create_daily_index(&self, path: &Path, part_of: Option<&str>) -> Result<()> {
        let part_of_line = match part_of {
            Some(p) => format!("part_of: \"{}\"\n", p),
            None => String::new(),
        };

        let content = format!(
            "---\n\
            title: Daily Entries\n\
            {}contents: []\n\
            ---\n\n\
            # Daily Entries\n\n\
            This index contains all daily journal entries organized by year and month.\n",
            part_of_line
        );

        self.fs.write_file(path, &content)?;
        Ok(())
    }

    /// Create a year index file.
    fn create_year_index(&self, path: &Path, date: &NaiveDate, part_of: &str) -> Result<()> {
        let year = date.format("%Y").to_string();
        let content = format!(
            "---\n\
            title: {year}\n\
            part_of: \"{part_of}\"\n\
            contents: []\n\
            ---\n\n\
            # {year}\n\n\
            Daily entries for {year}.\n"
        );

        self.fs.write_file(path, &content)?;
        Ok(())
    }

    /// Create a month index file.
    fn create_month_index(&self, path: &Path, date: &NaiveDate, part_of: &str) -> Result<()> {
        let year = date.format("%Y").to_string();
        let month_name = date.format("%B").to_string(); // e.g., "January"
        let title = format!("{} {}", month_name, year);

        let content = format!(
            "---\n\
            title: {title}\n\
            part_of: \"{part_of}\"\n\
            contents: []\n\
            ---\n\n\
            # {title}\n\n\
            Daily entries for {title}.\n"
        );

        self.fs.write_file(path, &content)?;
        Ok(())
    }

    /// Add an entry to an index's contents list.
    ///
    /// Does nothing if the entry is already present.
    /// Returns `Ok(true)` if the entry was added, `Ok(false)` if already present or skipped.
    pub fn add_to_index_contents(&self, index_path: &Path, entry: &str) -> Result<bool> {
        let index_str = index_path.to_string_lossy();

        match self.get_frontmatter_property(&index_str, "contents") {
            Ok(Some(Value::Sequence(mut items))) => {
                let entry_value = Value::String(entry.to_string());
                if !items.contains(&entry_value) {
                    items.push(entry_value);
                    // Sort contents for consistent ordering
                    items.sort_by(|a, b| {
                        let a_str = a.as_str().unwrap_or("");
                        let b_str = b.as_str().unwrap_or("");
                        a_str.cmp(b_str)
                    });
                    self.set_frontmatter_property(&index_str, "contents", Value::Sequence(items))?;
                    return Ok(true);
                }
                Ok(false)
            }
            Ok(None) => {
                // Create contents with just this entry
                let items = vec![Value::String(entry.to_string())];
                self.set_frontmatter_property(&index_str, "contents", Value::Sequence(items))?;
                Ok(true)
            }
            _ => {
                // Contents exists but isn't a sequence, or error reading - skip
                Ok(false)
            }
        }
    }

    /// Remove an entry from an index's contents list.
    ///
    /// Returns `Ok(true)` if the entry was found and removed, `Ok(false)` if not found or skipped.
    pub fn remove_from_index_contents(&self, index_path: &Path, entry: &str) -> Result<bool> {
        let index_str = index_path.to_string_lossy();

        match self.get_frontmatter_property(&index_str, "contents") {
            Ok(Some(Value::Sequence(mut items))) => {
                let before_len = items.len();
                items.retain(|item| item.as_str() != Some(entry));

                if items.len() != before_len {
                    // Sort contents for consistent ordering
                    items.sort_by(|a, b| {
                        let a_str = a.as_str().unwrap_or("");
                        let b_str = b.as_str().unwrap_or("");
                        a_str.cmp(b_str)
                    });
                    self.set_frontmatter_property(&index_str, "contents", Value::Sequence(items))?;
                    return Ok(true);
                }
                Ok(false)
            }
            Ok(None) | Ok(Some(_)) => {
                // No contents property or not a sequence - nothing to remove
                Ok(false)
            }
            Err(_) => {
                // Error reading - skip
                Ok(false)
            }
        }
    }

    /// Generate the year index filename (e.g., "2025_index.md")
    fn year_index_filename(date: &NaiveDate) -> String {
        format!("{}_index.md", date.format("%Y"))
    }

    /// Generate the month index filename (e.g., "2025_january.md")
    fn month_index_filename(date: &NaiveDate) -> String {
        format!(
            "{}_{}.md",
            date.format("%Y"),
            date.format("%B").to_string().to_lowercase()
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::fs::SyncToAsyncFs;
    use crate::test_utils::MockFileSystem;

    #[test]
    fn test_get_content() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nHello, world!");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs));

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert_eq!(content, "Hello, world!");
    }

    #[test]
    fn test_get_content_empty_body() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\n");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs));

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert_eq!(content, "");
    }

    #[test]
    fn test_get_content_no_frontmatter() {
        let fs = MockFileSystem::new().with_file("test.md", "Just plain content");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs));

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert_eq!(content, "Just plain content");
    }

    #[test]
    fn test_set_content() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nOld content");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.set_content("test.md", "New content")).unwrap();

        let result = fs.get_content("test.md").unwrap();
        assert!(result.contains("title: Test"));
        assert!(result.contains("New content"));
        assert!(!result.contains("Old content"));
    }

    #[test]
    fn test_set_content_preserves_frontmatter() {
        let fs = MockFileSystem::new().with_file(
            "test.md",
            "---\ntitle: My Title\ndescription: A description\n---\nOld",
        );
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.set_content("test.md", "New body")).unwrap();

        let result = fs.get_content("test.md").unwrap();
        assert!(result.contains("title: My Title"));
        assert!(result.contains("description: A description"));
        assert!(result.contains("New body"));
    }

    #[test]
    fn test_clear_content() {
        let fs =
            MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nSome content here");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.clear_content("test.md")).unwrap();

        let result = fs.get_content("test.md").unwrap();
        assert!(result.contains("title: Test"));
        // Content should be empty after the frontmatter closing
        assert!(result.ends_with("---\n"));
    }

    #[test]
    fn test_append_content() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nFirst line");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.append_content("test.md", "Second line")).unwrap();

        let result = fs.get_content("test.md").unwrap();
        assert!(result.contains("First line"));
        assert!(result.contains("Second line"));
        // Second line should come after first
        let first_pos = result.find("First line").unwrap();
        let second_pos = result.find("Second line").unwrap();
        assert!(second_pos > first_pos);
    }

    #[test]
    fn test_append_content_adds_newline() {
        let fs = MockFileSystem::new()
            .with_file("test.md", "---\ntitle: Test\n---\nNo trailing newline");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.append_content("test.md", "Appended")).unwrap();

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert!(content.contains("No trailing newline\nAppended"));
    }

    #[test]
    fn test_append_content_to_empty_body() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\n");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.append_content("test.md", "New content")).unwrap();

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert_eq!(content, "New content");
    }

    #[test]
    fn test_prepend_content() {
        let fs =
            MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nExisting content");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.prepend_content("test.md", "# Header")).unwrap();

        let result = fs.get_content("test.md").unwrap();
        assert!(result.contains("# Header"));
        assert!(result.contains("Existing content"));
        // Header should come before existing content
        let header_pos = result.find("# Header").unwrap();
        let existing_pos = result.find("Existing content").unwrap();
        assert!(header_pos < existing_pos);
    }

    #[test]
    fn test_prepend_content_adds_newline() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\nExisting");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.prepend_content("test.md", "Prepended")).unwrap();

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert!(content.contains("Prepended\nExisting"));
    }

    #[test]
    fn test_prepend_content_to_empty_body() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\n");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.prepend_content("test.md", "New content")).unwrap();

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert_eq!(content, "New content");
    }

    #[test]
    fn test_content_operations_on_nonexistent_file() {
        let fs = MockFileSystem::new();
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        // set_content should create the file
        crate::fs::block_on_test(app.set_content("new.md", "Content")).unwrap();

        let result = fs.get_content("new.md").unwrap();
        assert!(result.contains("Content"));
    }

    #[test]
    fn test_multiple_content_operations() {
        let fs = MockFileSystem::new().with_file("test.md", "---\ntitle: Test\n---\n");
        let app = DiaryxApp::new(SyncToAsyncFs::new(fs.clone()));

        crate::fs::block_on_test(app.append_content("test.md", "Line 1")).unwrap();
        crate::fs::block_on_test(app.append_content("test.md", "Line 2")).unwrap();
        crate::fs::block_on_test(app.prepend_content("test.md", "# Title")).unwrap();

        let content = crate::fs::block_on_test(app.get_content("test.md")).unwrap();
        assert!(content.starts_with("# Title"));
        assert!(content.contains("Line 1"));
        assert!(content.contains("Line 2"));
    }

    #[test]
    fn test_ensure_daily_index_hierarchy_repairs_links() {
        let fs = MockFileSystem::new();
        // Use DiaryxAppSync since the method is on it
        let app = DiaryxAppSync::new(fs.clone());
        let config = Config::default();
        let date = NaiveDate::from_ymd_opt(2025, 1, 15).unwrap();

        // 1. Create partial hierarchy: Year index exists but NOT linked in Daily Index
        let daily_dir = config.daily_entry_dir();
        fs.create_dir_all(&daily_dir).unwrap();
        app.create_daily_index(&daily_dir.join("daily_index.md"), None)
            .unwrap();

        let year_dir = daily_dir.join("2025");
        fs.create_dir_all(&year_dir).unwrap();
        app.create_year_index(&year_dir.join("2025_index.md"), &date, "../daily_index.md")
            .unwrap();

        // ensure_daily_index_hierarchy should fix the link
        app.ensure_daily_index_hierarchy(&date, &config).unwrap();

        // Verify link established
        let daily_index_path = daily_dir.join("daily_index.md");
        let daily_content_after = app
            .get_frontmatter_property(daily_index_path.to_str().unwrap(), "contents")
            .unwrap();
        if let Some(Value::Sequence(seq)) = daily_content_after {
            assert!(!seq.is_empty());
            assert_eq!(seq[0].as_str(), Some("[2025](/2025/2025_index.md)"));
        } else {
            panic!("Contents should be a sequence");
        }
    }

    #[test]
    fn test_detect_duplicates() {
        let fs = MockFileSystem::new();
        let app = DiaryxAppSync::new(fs.clone());
        let config = Config::default();
        let date = NaiveDate::from_ymd_opt(2025, 1, 15).unwrap(); // January

        // Create canonical hierarchy
        let daily_dir = config.daily_entry_dir();
        let year_dir = daily_dir.join("2025");
        fs.create_dir_all(&year_dir).unwrap();

        // Create duplicate "January" folder
        let duplicate_dir = year_dir.join("January");
        fs.create_dir_all(&duplicate_dir).unwrap();

        // Run detection
        let duplicates = app.detect_duplicates(&date, &config).unwrap();

        assert_eq!(duplicates.len(), 1);
        assert!(duplicates[0].ends_with("January"));
    }

    #[test]
    fn test_merge_duplicates() {
        let fs = MockFileSystem::new();
        let app = DiaryxAppSync::new(fs.clone());

        // Setup scenarios
        let from_dir = Path::new("from_dir");
        let to_dir = Path::new("to_dir");
        fs.create_dir_all(from_dir).unwrap();

        // Create file in from_dir
        fs.write_file(&from_dir.join("note.md"), "content").unwrap();

        // Run merge
        app.merge_duplicates(from_dir, to_dir).unwrap();

        // Verify
        assert!(!fs.exists(from_dir));
        assert!(fs.exists(to_dir));
        assert!(fs.exists(&to_dir.join("note.md")));
        assert_eq!(
            fs.get_content(to_dir.join("note.md").to_str().unwrap())
                .unwrap(),
            "content"
        );
    }
}