agpm_cli/templating/

mod.rs

//! Markdown templating engine for AGPM resources.
//!
//! This module provides Tera-based templating functionality for Markdown resources,
//! enabling dynamic content generation during installation. It supports safe, sandboxed
//! template rendering with a rich context containing installation metadata.
//!
//! # Overview
//!
//! The templating system allows resource authors to:
//! - Reference other resources by name and type
//! - Access resolved installation paths and versions
//! - Use conditional logic and loops in templates
//! - Read and embed project-specific files (style guides, best practices, etc.)
//!
//! # Template Context
//!
//! Templates are rendered with a structured context containing:
//! - `agpm.resource`: Current resource information (name, type, install path, etc.)
//! - `agpm.deps`: Nested dependency information by resource type and name
//!
//! # Custom Filters
//!
//! - `content`: Read project-specific files (e.g., `{{ 'docs/guide.md' | content }}`)
//!
//! # Syntax Restrictions
//!
//! For security and safety, the following Tera features are disabled:
//! - `{% include %}` tags (no file system access)
//! - `{% extends %}` tags (no template inheritance)
//! - `{% import %}` tags (no external template imports)
//! - Custom functions that access the file system or network (except content filter)
//!
//! # Supported Features
//!
//! - Variable substitution: `{{ agpm.resource.install_path }}`
//! - Conditional logic: `{% if agpm.resource.source %}...{% endif %}`
//! - Loops: `{% for name, dep in agpm.deps.agents %}...{% endfor %}`
//! - Standard Tera filters (string manipulation, formatting)
//! - Project file embedding: `{{ 'path/to/file.md' | content }}`
//! - Literal blocks: Protect template syntax from rendering for documentation
//!
//! # Literal Blocks (Documentation Mode)
//!
//! When writing documentation that includes template syntax examples, you can use
//! `literal` fenced code blocks to protect the content from being rendered:
//!
//! ````markdown
//! # Template Documentation
//!
//! Here's how to use template variables:
//!
//! ```literal
//! {{ agpm.deps.snippets.example.content }}
//! ```
//!
//! The above syntax will be displayed literally, not rendered.
//! ````
//!
//! This is particularly useful for:
//! - Documentation snippets that show template syntax examples
//! - Tutorial content that explains how to use templates
//! - Example code that should not be executed during rendering
//!
//! The content inside `literal` blocks will be:
//! 1. Protected from template rendering (preserved as-is)
//! 2. Wrapped in standard markdown code fences in the output
//! 3. Displayed literally to the end user
//!
//! # Examples
//!
//! ## Basic Variable Substitution
//!
//! ```markdown
//! # {{ agpm.resource.name }}
//!
//! This agent is installed at: `{{ agpm.resource.install_path }}`
//! Version: {{ agpm.resource.version }}
//! ```
//!
//! ## Dependency Content Embedding (v0.4.7+)
//!
//! All dependencies automatically have `.content` field with processed content:
//!
//! ```markdown
//! ---
//! agpm.templating: true
//! dependencies:
//!   snippets:
//!     - path: snippets/best-practices.md
//!       name: best_practices
//! ---
//! # Code Reviewer
//!
//! ## Best Practices
//! {{ agpm.deps.snippets.best_practices.content }}
//! ```
//!
//! ## Project File Filter (v0.4.8+)
//!
//! Read project-specific files using the `content` filter:
//!
//! ```markdown
//! ---
//! agpm.templating: true
//! ---
//! # Team Agent
//!
//! ## Project Style Guide
//! {{ 'project/styleguide.md' | content }}
//!
//! ## Team Conventions
//! {{ 'docs/conventions.txt' | content }}
//! ```
//!
//! ## Combining Dependency Content + Project Files
//!
//! Use both features together for maximum flexibility:
//!
//! ```markdown
//! ---
//! agpm.templating: true
//! dependencies:
//!   snippets:
//!     - path: snippets/rust-patterns.md
//!       name: rust_patterns
//!     - path: snippets/error-handling.md
//!       name: error_handling
//! ---
//! # Rust Code Reviewer
//!
//! ## Shared Patterns (from AGPM repository)
//! {{ agpm.deps.snippets.rust_patterns.content }}
//!
//! ## Project-Specific Style Guide
//! {{ 'project/rust-style.md' | content }}
//!
//! ## Error Handling Best Practices
//! {{ agpm.deps.snippets.error_handling.content }}
//!
//! ## Team Conventions
//! {{ 'docs/team-conventions.txt' | content }}
//! ```
//!
//! **When to use each**:
//! - **Dependency content**: Versioned, shared resources from AGPM repos
//! - **Project files**: Team-specific, project-local documentation
//!
//! ## Literal Blocks for Documentation
//!
//! When creating documentation snippets that explain template syntax, use
//! `literal` blocks to prevent the examples from being rendered:
//!
//! ````markdown
//! ---
//! agpm.templating: true
//! ---
//! # AGPM Template Guide
//!
//! ## How to Embed Snippet Content
//!
//! To embed a snippet's content in your template, use this syntax:
//!
//! ```literal
//! {{ agpm.deps.snippets.best_practices.content }}
//! ```
//!
//! This will render the **current agent name**: {{ agpm.resource.name }}
//!
//! ## How to Loop Over Dependencies
//!
//! ```literal
//! {% for name, dep in agpm.deps.agents %}
//! - {{ name }}: {{ dep.version }}
//! {% endfor %}
//! ```
//!
//! The syntax examples above are displayed literally, while the agent name
//! below is dynamically rendered based on the context.
//! ````
//!
//! In this example:
//! - The `literal` blocks show template syntax examples without rendering them
//! - Regular template variables like `{{ agpm.resource.name }}` are still rendered
//! - This allows documentation to demonstrate template features while using them
//!
//! ## Recursive Project Files
//!
//! Project files can reference other project files (up to 10 levels):
//!
//! **Main agent** (`.claude/agents/reviewer.md`):
//! ```markdown
//! ---
//! agpm.templating: true
//! ---
//! # Code Reviewer
//!
//! {{ 'project/styleguide.md' | content }}
//! ```
//!
//! **Style guide** (`project/styleguide.md`):
//! ```markdown
//! # Coding Standards
//!
//! ## Rust-Specific Rules
//! {{ 'project/rust-style.md' | content }}
//! ```
//!
//! ## Dependency References
//!
//! Dependencies are accessible by name in the template context. The name is determined by:
//! 1. For manifest deps: the key in `[agents]`, `[snippets]`, etc.
//! 2. For transitive deps: the `name` field if specified, otherwise derived from path
//!
//! ```markdown
//! ## Dependencies
//!
//! This agent uses the following helper:
//! - {{ agpm.deps.snippets.helper.install_path }}
//!
//! {% if agpm.deps.agents %}
//! ## Related Agents
//! {% for agent in agpm.deps.agents %}
//! - {{ agent.name }} ({{ agent.version }})
//! {% endfor %}
//! {% endif %}
//! ```
//!
//! ### Custom Names for Transitive Dependencies
//!
//! ```yaml
//! ---
//! dependencies:
//!   agents:
//!     - path: "../shared/complex-path/helper.md"
//!       name: "helper"  # Use "helper" instead of deriving from path
//! ---
//! ```
//!
//! ## Conditional Content
//!
//! ```markdown
//! {% if agpm.resource.source == "community" %}
//! This resource is from the community repository.
//! {% elif agpm.resource.source %}
//! This resource is from the {{ agpm.resource.source }} source.
//! {% else %}
//! This is a local resource.
//! {% endif %}
//! ```

pub mod filters;

use anyhow::{Context, Result, bail};
use serde::{Deserialize, Serialize};
use serde_json::{Map, to_string, to_value};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use tera::{Context as TeraContext, Tera};

use crate::core::ResourceType;
use crate::lockfile::LockFile;

/// Sentinel markers used to guard non-templated dependency content.
/// Content enclosed between these markers should be treated as literal text
/// and never passed through the templating engine.
const NON_TEMPLATED_LITERAL_GUARD_START: &str = "__AGPM_LITERAL_RAW_START__";
const NON_TEMPLATED_LITERAL_GUARD_END: &str = "__AGPM_LITERAL_RAW_END__";

/// Convert Unix-style path (from lockfile) to platform-native format for display in templates.
///
/// Lockfiles always use Unix-style forward slashes for cross-platform compatibility,
/// but when rendering templates, we want to show paths in the platform's native format
/// so users see `.claude\agents\helper.md` on Windows and `.claude/agents/helper.md` on Unix.
///
/// # Arguments
///
/// * `unix_path` - Path string with forward slashes (from lockfile)
///
/// # Returns
///
/// Platform-native path string (backslashes on Windows, forward slashes on Unix)
///
/// # Examples
///
/// ```
/// # use agpm_cli::templating::to_native_path_display;
/// #[cfg(windows)]
/// assert_eq!(to_native_path_display(".claude/agents/test.md"), ".claude\\agents\\test.md");
///
/// #[cfg(not(windows))]
/// assert_eq!(to_native_path_display(".claude/agents/test.md"), ".claude/agents/test.md");
/// ```
pub fn to_native_path_display(unix_path: &str) -> String {
    #[cfg(windows)]
    {
        unix_path.replace('/', "\\")
    }
    #[cfg(not(windows))]
    {
        unix_path.to_string()
    }
}

/// Template context builder for AGPM resource installation.
///
/// This struct is responsible for building the template context that will be
/// available to Markdown templates during rendering. It collects data from
/// the manifest, lockfile, and current resource being processed.
///
/// # Context Structure
///
/// The built context follows this structure:
/// ```json
/// {
///   "agpm": {
///     "resource": {
///       "type": "agent",
///       "name": "example-agent",
///       "install_path": ".claude/agents/example.md",
///       "source": "community",
///       "version": "v1.0.0",
///       "resolved_commit": "abc123...",
///       "checksum": "sha256:...",
///       "path": "agents/example.md"
///     },
///     "deps": {
///       "agents": {
///         "helper": {
///           "install_path": ".claude/agents/helper.md",
///           "version": "v1.0.0",
///           "resolved_commit": "def456...",
///           "checksum": "sha256:...",
///           "source": "community",
///           "path": "agents/helper.md"
///         }
///       },
///       "snippets": { ... },
///       "commands": { ... }
///     }
///   }
/// }
/// ```
pub struct TemplateContextBuilder {
    /// The lockfile containing resolved resource information
    /// Shared via Arc to avoid expensive clones when building contexts for multiple resources
    lockfile: Arc<LockFile>,
    /// Project-specific template variables from the manifest
    project_config: Option<crate::manifest::ProjectConfig>,
    /// Cache instance for reading source files during content extraction
    /// Shared via Arc to avoid expensive clones
    cache: Arc<crate::cache::Cache>,
    /// Project root directory for resolving local file paths
    project_dir: PathBuf,
}

/// Template renderer with Tera engine and custom functions.
///
/// This struct wraps a Tera instance with AGPM-specific configuration,
/// custom functions, and filters. It provides a safe, sandboxed environment
/// for rendering Markdown templates.
///
/// # Security
///
/// The renderer is configured with security restrictions:
/// - No file system access via includes/extends (except content filter)
/// - No network access
/// - Sandboxed template execution
/// - Custom functions are carefully vetted
/// - Project file access restricted to project directory with validation
pub struct TemplateRenderer {
    /// The underlying Tera template engine
    tera: Tera,
    /// Whether templating is enabled globally
    enabled: bool,
}

/// Metadata about a resource for template context.
///
/// This struct represents the information available about a resource
/// in the template context. It includes both the resource's own metadata
/// and its resolved installation information.
#[derive(Clone, Serialize, Deserialize)]
pub struct ResourceTemplateData {
    /// Resource type (agent, snippet, command, etc.)
    #[serde(rename = "type")]
    pub resource_type: String,
    /// Logical resource name from manifest
    pub name: String,
    /// Resolved installation path
    pub install_path: String,
    /// Source identifier (if applicable)
    pub source: Option<String>,
    /// Resolved version (if applicable)
    pub version: Option<String>,
    /// Git commit SHA (if applicable)
    pub resolved_commit: Option<String>,
    /// SHA256 checksum of the content
    pub checksum: String,
    /// Source-relative path in repository
    pub path: String,
    /// Processed content of the resource file.
    ///
    /// Contains the file content with metadata stripped:
    /// - For Markdown: Content without YAML frontmatter
    /// - For JSON: Content without metadata fields
    ///
    /// This field is available for all dependencies, enabling template
    /// embedding via `{{ agpm.deps.<type>.<name>.content }}`.
    ///
    /// Note: This field is large and should not be printed in debug output.
    /// Use the Debug impl which shows only the content length.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
}

impl std::fmt::Debug for ResourceTemplateData {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ResourceTemplateData")
            .field("resource_type", &self.resource_type)
            .field("name", &self.name)
            .field("install_path", &self.install_path)
            .field("source", &self.source)
            .field("version", &self.version)
            .field("resolved_commit", &self.resolved_commit)
            .field("checksum", &self.checksum)
            .field("path", &self.path)
            .field("content", &self.content.as_ref().map(|c| format!("<{} bytes>", c.len())))
            .finish()
    }
}

impl TemplateContextBuilder {
    /// Create a new template context builder.
    ///
    /// # Arguments
    ///
    /// * `lockfile` - The resolved lockfile, wrapped in Arc for efficient sharing
    /// * `project_config` - Optional project-specific template variables from the manifest
    /// * `cache` - Cache instance for reading source files during content extraction
    /// * `project_dir` - Project root directory for resolving local file paths
    pub fn new(
        lockfile: Arc<LockFile>,
        project_config: Option<crate::manifest::ProjectConfig>,
        cache: Arc<crate::cache::Cache>,
        project_dir: PathBuf,
    ) -> Self {
        Self {
            lockfile,
            project_config,
            cache,
            project_dir,
        }
    }

    /// Build the complete template context for a specific resource.
    ///
    /// # Arguments
    ///
    /// * `resource_name` - Name of the resource being rendered
    /// * `resource_type` - Type of the resource (agents, snippets, etc.)
    ///
    /// # Returns
    ///
    /// Returns a Tera `Context` containing all available template variables.
    pub async fn build_context(
        &self,
        resource_name: &str,
        resource_type: ResourceType,
    ) -> Result<TeraContext> {
        let mut context = TeraContext::new();

        // Build the nested agpm structure
        let mut agpm = Map::new();

        // Build current resource data
        let resource_data = self.build_resource_data(resource_name, resource_type)?;
        agpm.insert("resource".to_string(), to_value(resource_data)?);

        // Build dependency data
        let deps_data = self.build_dependencies_data().await?;
        agpm.insert("deps".to_string(), to_value(deps_data)?);

        // Add project variables if available
        if let Some(ref project_config) = self.project_config {
            let project_json = project_config.to_json_value();
            agpm.insert("project".to_string(), project_json);
        }

        // Insert the complete agpm object
        context.insert("agpm", &agpm);

        Ok(context)
    }

    /// Build resource metadata for the template context.
    ///
    /// # Arguments
    ///
    /// * `resource_name` - Name of the resource
    /// * `resource_type` - Type of the resource
    fn build_resource_data(
        &self,
        resource_name: &str,
        resource_type: ResourceType,
    ) -> Result<ResourceTemplateData> {
        let entry =
            self.lockfile.find_resource(resource_name, resource_type).with_context(|| {
                format!(
                    "Resource '{}' of type {:?} not found in lockfile",
                    resource_name, resource_type
                )
            })?;

        Ok(ResourceTemplateData {
            resource_type: resource_type.to_string(),
            name: resource_name.to_string(),
            install_path: to_native_path_display(&entry.installed_at),
            source: entry.source.clone(),
            version: entry.version.clone(),
            resolved_commit: entry.resolved_commit.clone(),
            checksum: entry.checksum.clone(),
            path: entry.path.clone(),
            content: None, // Will be populated when content extraction is implemented
        })
    }

    /// Extract and process content from a resource file.
    ///
    /// Reads the source file and processes it based on file type:
    /// - Markdown (.md): Strips YAML frontmatter, returns content only
    /// - JSON (.json): Removes metadata fields like `dependencies`
    /// - Other files: Returns raw content
    ///
    /// # Arguments
    ///
    /// * `resource` - The locked resource to extract content from
    ///
    /// # Returns
    ///
    /// Returns `Some(content)` if extraction succeeded, `None` on error (with warning logged)
    async fn extract_content(&self, resource: &crate::lockfile::LockedResource) -> Option<String> {
        tracing::debug!(
            "Attempting to extract content for resource '{}' (type: {:?})",
            resource.name,
            resource.resource_type
        );

        // Determine source path
        let source_path = if let Some(source_name) = &resource.source {
            let url = resource.url.as_ref()?;

            // Check if this is a local directory source
            let is_local_source = resource.resolved_commit.as_deref().is_none_or(str::is_empty);

            tracing::debug!(
                "Resource '{}': source='{}', url='{}', is_local={}",
                resource.name,
                source_name,
                url,
                is_local_source
            );

            if is_local_source {
                // Local directory source - use URL as path directly
                let path = std::path::PathBuf::from(url).join(&resource.path);
                tracing::debug!("Using local source path: {}", path.display());
                path
            } else {
                // Git-based source - get worktree path
                let sha = resource.resolved_commit.as_deref()?;

                tracing::debug!(
                    "Resource '{}': Getting worktree for SHA {}...",
                    resource.name,
                    &sha[..8.min(sha.len())]
                );

                // Use centralized worktree path construction
                let worktree_dir = match self.cache.get_worktree_path(url, sha) {
                    Ok(path) => {
                        tracing::debug!("Worktree path: {}", path.display());
                        path
                    }
                    Err(e) => {
                        tracing::warn!(
                            "Failed to construct worktree path for resource '{}': {}",
                            resource.name,
                            e
                        );
                        return None;
                    }
                };

                let full_path = worktree_dir.join(&resource.path);
                tracing::debug!(
                    "Full source path for '{}': {} (worktree exists: {})",
                    resource.name,
                    full_path.display(),
                    worktree_dir.exists()
                );
                full_path
            }
        } else {
            // Local file - path is relative to project or absolute
            let local_path = std::path::Path::new(&resource.path);
            let resolved_path = if local_path.is_absolute() {
                local_path.to_path_buf()
            } else {
                self.project_dir.join(local_path)
            };

            tracing::debug!(
                "Resource '{}': Using local file path: {}",
                resource.name,
                resolved_path.display()
            );

            resolved_path
        };

        // Read file content
        let content = match tokio::fs::read_to_string(&source_path).await {
            Ok(c) => c,
            Err(e) => {
                tracing::warn!(
                    "Failed to read content for resource '{}' from {}: {}",
                    resource.name,
                    source_path.display(),
                    e
                );
                return None;
            }
        };

        // Process based on file type
        let processed_content = if resource.path.ends_with(".md") {
            // Markdown: strip frontmatter and guard non-templated content that contains template syntax
            match crate::markdown::MarkdownDocument::parse(&content) {
                Ok(doc) => {
                    let templating_enabled =
                        Self::is_markdown_templating_enabled(doc.metadata.as_ref());
                    let mut stripped_content = doc.content;

                    if !templating_enabled
                        && Self::content_contains_template_syntax(&stripped_content)
                    {
                        tracing::debug!(
                            "Protecting non-templated markdown content for '{}'",
                            resource.name
                        );
                        stripped_content = Self::wrap_content_in_literal_guard(stripped_content);
                    }

                    stripped_content
                }
                Err(e) => {
                    tracing::warn!(
                        "Failed to parse markdown for resource '{}': {}. Using raw content.",
                        resource.name,
                        e
                    );
                    content
                }
            }
        } else if resource.path.ends_with(".json") {
            // JSON: parse and remove metadata fields
            match serde_json::from_str::<serde_json::Value>(&content) {
                Ok(mut json) => {
                    if let Some(obj) = json.as_object_mut() {
                        // Remove metadata fields that shouldn't be in embedded content
                        obj.remove("dependencies");
                    }
                    serde_json::to_string_pretty(&json).unwrap_or(content)
                }
                Err(e) => {
                    tracing::warn!(
                        "Failed to parse JSON for resource '{}': {}. Using raw content.",
                        resource.name,
                        e
                    );
                    content
                }
            }
        } else {
            // Other files: use raw content
            content
        };

        Some(processed_content)
    }

    /// Determine whether templating is explicitly enabled in Markdown frontmatter.
    fn is_markdown_templating_enabled(
        metadata: Option<&crate::markdown::MarkdownMetadata>,
    ) -> bool {
        metadata
            .and_then(|md| md.extra.get("agpm"))
            .and_then(|agpm| agpm.as_object())
            .and_then(|agpm_obj| agpm_obj.get("templating"))
            .and_then(|value| value.as_bool())
            .unwrap_or(false)
    }

    /// Detect if content contains Tera template syntax markers.
    fn content_contains_template_syntax(content: &str) -> bool {
        content.contains("{{") || content.contains("{%") || content.contains("{#")
    }

    /// Wrap non-templated content in a literal fence so it renders safely without being evaluated.
    fn wrap_content_in_literal_guard(content: String) -> String {
        let mut wrapped = String::with_capacity(
            content.len()
                + NON_TEMPLATED_LITERAL_GUARD_START.len()
                + NON_TEMPLATED_LITERAL_GUARD_END.len()
                + 2, // newline separators
        );

        wrapped.push_str(NON_TEMPLATED_LITERAL_GUARD_START);
        wrapped.push('\n');
        wrapped.push_str(&content);
        if !content.ends_with('\n') {
            wrapped.push('\n');
        }
        wrapped.push_str(NON_TEMPLATED_LITERAL_GUARD_END);

        wrapped
    }

    /// Build dependency data for the template context.
    ///
    /// This creates a nested structure of all dependencies by resource type and name.
    async fn build_dependencies_data(
        &self,
    ) -> Result<HashMap<String, HashMap<String, ResourceTemplateData>>> {
        let mut deps = HashMap::new();

        // Process each resource type
        for resource_type in [
            ResourceType::Agent,
            ResourceType::Snippet,
            ResourceType::Command,
            ResourceType::Script,
            ResourceType::Hook,
            ResourceType::McpServer,
        ] {
            let type_str_plural = resource_type.to_plural().to_string();
            let type_str_singular = resource_type.to_string();
            let mut type_deps = HashMap::new();

            let resources = self.lockfile.get_resources_by_type(resource_type);
            for resource in resources {
                // Extract content from source file
                let content = self.extract_content(resource).await;

                let template_data = ResourceTemplateData {
                    resource_type: type_str_singular.clone(),
                    name: resource.name.clone(),
                    install_path: to_native_path_display(&resource.installed_at),
                    source: resource.source.clone(),
                    version: resource.version.clone(),
                    resolved_commit: resource.resolved_commit.clone(),
                    checksum: resource.checksum.clone(),
                    path: resource.path.clone(),
                    content,
                };

                // Use manifest_alias if available, otherwise use resource name
                // For path-like names (containing / or \), extract just the basename
                // This ensures clean keys like "ai_attribution" instead of full paths
                let key_name = if let Some(alias) = &resource.manifest_alias {
                    alias.clone()
                } else if resource.name.contains('/') || resource.name.contains('\\') {
                    // Name looks like a path - extract basename without extension
                    std::path::Path::new(&resource.name)
                        .file_stem()
                        .and_then(|s| s.to_str())
                        .unwrap_or(&resource.name)
                        .to_string()
                } else {
                    // Use name as-is
                    resource.name.clone()
                };

                // Sanitize the key name by replacing hyphens with underscores
                // to avoid Tera interpreting them as minus operators
                let sanitized_key = key_name.replace('-', "_");
                type_deps.insert(sanitized_key, template_data);
            }

            if !type_deps.is_empty() {
                deps.insert(type_str_plural, type_deps);
            }
        }

        // Debug: Print what we're building
        tracing::debug!("Built dependencies data with {} resource types", deps.len());
        for (resource_type, resources) in &deps {
            tracing::debug!("  Type {}: {} resources", resource_type, resources.len());
            for name in resources.keys() {
                tracing::debug!("    - {}", name);
            }
        }

        Ok(deps)
    }

    /// Compute a stable digest of the template context data.
    ///
    /// This method creates a deterministic hash of all lockfile metadata that could
    /// affect template rendering. The digest is used as part of the cache key to ensure
    /// that changes to dependency versions or metadata properly invalidate the cache.
    ///
    /// # Returns
    ///
    /// Returns a hex-encoded string containing the first 16 characters of the SHA-256
    /// hash of the serialized template context data. This is sufficient to uniquely
    /// identify context changes while keeping the digest compact.
    ///
    /// # What's Included
    ///
    /// The digest includes all lockfile metadata that affects rendering:
    /// - Resource names, types, and installation paths
    /// - Dependency versions and resolved commits
    /// - Checksums and source information
    ///
    /// # Determinism
    ///
    /// The hash is stable across runs because:
    /// - Resources are sorted by type and name before hashing
    /// - JSON serialization uses consistent ordering (BTreeMap)
    /// - Only metadata fields that affect rendering are included
    ///
    /// # Examples
    ///
    /// ```rust,no_run
    /// use agpm_cli::templating::TemplateContextBuilder;
    /// use agpm_cli::lockfile::LockFile;
    /// use std::path::{Path, PathBuf};
    /// use std::sync::Arc;
    ///
    /// # fn example() -> anyhow::Result<()> {
    /// let lockfile = LockFile::load(Path::new("agpm.lock"))?;
    /// let cache = Arc::new(agpm_cli::cache::Cache::new()?);
    /// let project_dir = std::env::current_dir()?;
    /// let builder = TemplateContextBuilder::new(
    ///     Arc::new(lockfile),
    ///     None,
    ///     cache,
    ///     project_dir
    /// );
    ///
    /// let digest = builder.compute_context_digest()?;
    /// println!("Template context digest: {}", digest);
    /// # Ok(())
    /// # }
    /// ```
    pub fn compute_context_digest(&self) -> Result<String> {
        use sha2::{Digest, Sha256};
        use std::collections::BTreeMap;

        // Build a deterministic representation of the lockfile data
        // Use BTreeMap for consistent ordering
        let mut digest_data: BTreeMap<String, BTreeMap<String, BTreeMap<&str, String>>> =
            BTreeMap::new();

        // Process each resource type in a consistent order
        for resource_type in [
            ResourceType::Agent,
            ResourceType::Snippet,
            ResourceType::Command,
            ResourceType::Script,
            ResourceType::Hook,
            ResourceType::McpServer,
        ] {
            let resources = self.lockfile.get_resources_by_type(resource_type);
            if resources.is_empty() {
                continue;
            }

            let type_str = resource_type.to_plural().to_string();
            let mut sorted_resources: Vec<_> = resources.iter().collect();
            // Sort by name for deterministic ordering
            sorted_resources.sort_by(|a, b| a.name.cmp(&b.name));

            let mut type_data = BTreeMap::new();
            for resource in sorted_resources {
                // Include only the fields that can affect template rendering
                let mut resource_data: BTreeMap<&str, String> = BTreeMap::new();
                resource_data.insert("name", resource.name.clone());
                resource_data.insert("install_path", resource.installed_at.clone());
                resource_data.insert("path", resource.path.clone());
                resource_data.insert("checksum", resource.checksum.clone());

                // Optional fields - only include if present
                if let Some(ref source) = resource.source {
                    resource_data.insert("source", source.to_string());
                }
                if let Some(ref version) = resource.version {
                    resource_data.insert("version", version.to_string());
                }
                if let Some(ref commit) = resource.resolved_commit {
                    resource_data.insert("resolved_commit", commit.to_string());
                }

                type_data.insert(resource.name.clone(), resource_data);
            }

            digest_data.insert(type_str, type_data);
        }

        // Serialize to JSON for stable representation
        let json_str =
            to_string(&digest_data).context("Failed to serialize template context for digest")?;

        // Compute SHA-256 hash
        let mut hasher = Sha256::new();
        hasher.update(json_str.as_bytes());
        let hash = hasher.finalize();

        // Return first 16 hex characters (64 bits) - sufficient for uniqueness
        Ok(hex::encode(&hash[..8]))
    }
}

impl TemplateRenderer {
    /// Create a new template renderer with AGPM-specific configuration.
    ///
    /// # Arguments
    ///
    /// * `enabled` - Whether templating is enabled globally
    /// * `project_dir` - Project root directory for content filter validation
    /// * `max_content_file_size` - Maximum file size in bytes for content filter (None for no limit)
    ///
    /// # Returns
    ///
    /// Returns a configured `TemplateRenderer` instance with custom filters registered.
    ///
    /// # Filters
    ///
    /// The following custom filters are registered:
    /// - `content`: Read project-specific files with path validation and size limits
    pub fn new(
        enabled: bool,
        project_dir: PathBuf,
        max_content_file_size: Option<u64>,
    ) -> Result<Self> {
        let mut tera = Tera::default();

        // Register custom filters
        tera.register_filter(
            "content",
            filters::create_content_filter(project_dir.clone(), max_content_file_size),
        );

        Ok(Self {
            tera,
            enabled,
        })
    }

    /// Protect literal blocks from template rendering by replacing them with placeholders.
    ///
    /// This method scans for ```literal fenced code blocks and replaces them with
    /// unique placeholders that won't be affected by template rendering. The original
    /// content is stored in a HashMap that can be used to restore the blocks later.
    ///
    /// # Arguments
    ///
    /// * `content` - The content to process
    ///
    /// # Returns
    ///
    /// Returns a tuple of:
    /// - Modified content with placeholders instead of literal blocks
    /// - HashMap mapping placeholder IDs to original content
    ///
    /// # Examples
    ///
    /// ````markdown
    /// # Documentation Example
    ///
    /// Use this syntax in templates:
    ///
    /// ```literal
    /// {{ agpm.deps.snippets.example.content }}
    /// ```
    /// ````
    ///
    /// The content inside the literal block will be protected from rendering.
    fn protect_literal_blocks(&self, content: &str) -> (String, HashMap<String, String>) {
        let mut placeholders = HashMap::new();
        let mut counter = 0;
        let mut result = String::with_capacity(content.len());

        // Split content by triple backticks to find code blocks
        let mut in_literal_block = false;
        let mut current_block = String::new();
        let lines = content.lines();

        for line in lines {
            if line.trim().starts_with("```literal") {
                // Start of literal block
                in_literal_block = true;
                current_block.clear();
                tracing::debug!("Found start of literal block");
                continue; // Skip the fence line
            } else if in_literal_block && line.trim().starts_with("```") {
                // End of literal block
                in_literal_block = false;

                // Generate unique placeholder
                let placeholder_id = format!("__AGPM_LITERAL_BLOCK_{}__", counter);
                counter += 1;

                // Store original content
                placeholders.insert(placeholder_id.clone(), current_block.clone());

                // Insert placeholder
                result.push_str(&placeholder_id);
                result.push('\n');

                tracing::debug!(
                    "Protected literal block with placeholder {} ({} bytes)",
                    placeholder_id,
                    current_block.len()
                );

                current_block.clear();
                continue; // Skip the fence line
            } else if in_literal_block {
                // Inside literal block - accumulate content
                if !current_block.is_empty() {
                    current_block.push('\n');
                }
                current_block.push_str(line);
            } else {
                // Regular content - pass through
                result.push_str(line);
                result.push('\n');
            }
        }

        // Handle unclosed literal block (add back as-is)
        if in_literal_block {
            tracing::warn!("Unclosed literal block found - treating as regular content");
            result.push_str("```literal\n");
            result.push_str(&current_block);
        }

        // Remove trailing newline if original didn't have one
        if !content.ends_with('\n') && result.ends_with('\n') {
            result.pop();
        }

        tracing::debug!("Protected {} literal block(s)", placeholders.len());
        (result, placeholders)
    }

    /// Restore literal blocks by replacing placeholders with original content.
    ///
    /// This method takes rendered content and restores any literal blocks that were
    /// protected during the rendering process.
    ///
    /// # Arguments
    ///
    /// * `content` - The rendered content containing placeholders
    /// * `placeholders` - HashMap mapping placeholder IDs to original content
    ///
    /// # Returns
    ///
    /// Returns the content with placeholders replaced by original literal blocks,
    /// wrapped in markdown code fences for proper display.
    fn restore_literal_blocks(
        &self,
        content: &str,
        placeholders: HashMap<String, String>,
    ) -> String {
        let mut result = content.to_string();

        for (placeholder_id, original_content) in placeholders {
            if original_content.starts_with(NON_TEMPLATED_LITERAL_GUARD_START) {
                result = result.replace(&placeholder_id, &original_content);
            } else {
                // Wrap in markdown code fence for display
                let replacement = format!("```\n{}\n```", original_content);
                result = result.replace(&placeholder_id, &replacement);
            }

            tracing::debug!(
                "Restored literal block {} ({} bytes)",
                placeholder_id,
                original_content.len()
            );
        }

        result
    }

    /// Collapse literal fences that were injected to protect non-templated dependency content.
    ///
    /// Any block that starts with ```literal, contains the sentinel marker on its first line,
    /// and ends with ``` will be replaced by the inner content without the sentinel or fences.
    fn collapse_non_templated_literal_guards(content: String) -> String {
        let mut result = String::with_capacity(content.len());
        let mut in_guard = false;

        for chunk in content.split_inclusive('\n') {
            let trimmed = chunk.trim_end_matches(['\r', '\n']);

            if !in_guard {
                if trimmed == NON_TEMPLATED_LITERAL_GUARD_START {
                    in_guard = true;
                } else {
                    result.push_str(chunk);
                }
            } else if trimmed == NON_TEMPLATED_LITERAL_GUARD_END {
                in_guard = false;
            } else {
                result.push_str(chunk);
            }
        }

        // If guard never closed, re-append the start marker and captured content to avoid dropping data.
        if in_guard {
            result.push_str(NON_TEMPLATED_LITERAL_GUARD_START);
        }

        result
    }

    /// Render a Markdown template with the given context.
    ///
    /// This method supports recursive template rendering where project files
    /// can reference other project files using the `content` filter.
    /// Rendering continues up to [`filters::MAX_RENDER_DEPTH`] levels deep.
    ///
    /// # Arguments
    ///
    /// * `template_content` - The raw Markdown template content
    /// * `context` - The template context containing variables
    ///
    /// # Returns
    ///
    /// Returns the rendered Markdown content.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Template syntax is invalid
    /// - Context variables are missing
    /// - Custom functions/filters fail
    /// - Recursive rendering exceeds maximum depth (10 levels)
    ///
    /// # Literal Blocks
    ///
    /// Content wrapped in ```literal fences will be protected from
    /// template rendering and displayed literally:
    ///
    /// ````markdown
    /// ```literal
    /// {{ agpm.deps.snippets.example.content }}
    /// ```
    /// ````
    ///
    /// This is useful for documentation that shows template syntax examples.
    ///
    /// # Recursive Rendering
    ///
    /// When a template contains `content` filter references, those files
    /// may themselves contain template syntax. The renderer automatically
    /// detects this and performs multiple rendering passes until either:
    /// - No template syntax remains in the output
    /// - Maximum depth is reached (error)
    ///
    /// Example recursive template chain:
    /// ```markdown
    /// # Main Agent
    /// {{ 'docs/guide.md' | content }}
    /// ```
    ///
    /// Where `docs/guide.md` contains:
    /// ```markdown
    /// # Guide
    /// {{ 'docs/common.md' | content }}
    /// ```
    ///
    /// This will render up to 10 levels deep.
    pub fn render_template(
        &mut self,
        template_content: &str,
        context: &TeraContext,
    ) -> Result<String> {
        tracing::debug!("render_template called, enabled={}", self.enabled);

        if !self.enabled {
            // If templating is disabled, return content as-is
            tracing::debug!("Templating disabled, returning content as-is");
            return Ok(template_content.to_string());
        }

        // Step 1: Protect literal blocks before any rendering
        let (protected_content, placeholders) = self.protect_literal_blocks(template_content);

        // Check if content contains template syntax (after protecting literals)
        if !self.contains_template_syntax(&protected_content) {
            // No template syntax found, restore literals and return
            tracing::debug!(
                "No template syntax found after protecting literals, returning content"
            );
            return Ok(self.restore_literal_blocks(&protected_content, placeholders));
        }

        // Log the template context for debugging
        tracing::debug!("Rendering template with context");
        Self::log_context_as_kv(context);

        // Step 2: Multi-pass rendering for recursive templates
        // This allows project files to reference other project files
        let mut current_content = protected_content;
        let mut depth = 0;
        let max_depth = filters::MAX_RENDER_DEPTH;

        let rendered = loop {
            depth += 1;

            // Check depth limit
            if depth > max_depth {
                bail!(
                    "Template rendering exceeded maximum recursion depth of {}. \
                     This usually indicates circular dependencies between project files. \
                     Please check your content filter references for cycles.",
                    max_depth
                );
            }

            tracing::debug!("Rendering pass {} of max {}", depth, max_depth);

            // Render the current content
            let rendered = self.tera.render_str(&current_content, context).map_err(|e| {
                // Extract detailed error information from Tera error
                let error_msg = Self::format_tera_error(&e);

                // Output the detailed error to stderr for immediate visibility
                eprintln!("Template rendering error:\n{}", error_msg);

                // Include the context in the error message for user visibility
                let context_str = Self::format_context_as_string(context);
                anyhow::Error::new(e).context(format!(
                    "Template rendering failed at depth {}:\n{}\n\nTemplate context:\n{}",
                    depth, error_msg, context_str
                ))
            })?;

            // Check if the rendered output still contains template syntax OUTSIDE code fences
            // This prevents re-rendering template syntax that was embedded as code examples
            if !self.contains_template_syntax_outside_fences(&rendered) {
                // No more template syntax outside fences - we're done with rendering
                tracing::debug!("Template rendering complete after {} pass(es)", depth);
                break rendered;
            }

            // More template syntax found outside fences - prepare for next iteration
            tracing::debug!("Template syntax detected in output, continuing to pass {}", depth + 1);
            current_content = rendered;
        };

        // Step 3: Restore literal blocks after all rendering is complete
        let restored = self.restore_literal_blocks(&rendered, placeholders);

        // Step 4: Collapse any literal guards that were added for non-templated dependencies
        Ok(Self::collapse_non_templated_literal_guards(restored))
    }

    /// Format a Tera error with detailed information about what went wrong.
    ///
    /// Tera errors can contain various types of issues:
    /// - Missing variables (e.g., "Variable `foo` not found")
    /// - Syntax errors (e.g., "Unexpected end of template")
    /// - Filter/function errors (e.g., "Filter `unknown` not found")
    ///
    /// This function extracts the root cause and formats it in a user-friendly way,
    /// filtering out unhelpful internal template names like '__tera_one_off'.
    ///
    /// # Arguments
    ///
    /// * `error` - The Tera error to format
    fn format_tera_error(error: &tera::Error) -> String {
        use std::error::Error;

        let mut messages = Vec::new();

        // Walk the entire error chain and collect all messages
        let mut all_messages = vec![error.to_string()];
        let mut current_error: Option<&dyn Error> = error.source();
        while let Some(err) = current_error {
            all_messages.push(err.to_string());
            current_error = err.source();
        }

        // Process messages to extract useful information
        for msg in all_messages {
            // Clean up the message by removing internal template names
            let cleaned = msg
                .replace("while rendering '__tera_one_off'", "")
                .replace("Failed to render '__tera_one_off'", "Template rendering failed")
                .replace("Failed to parse '__tera_one_off'", "Template syntax error")
                .replace("'__tera_one_off'", "template")
                .trim()
                .to_string();

            // Only keep non-empty, useful messages
            if !cleaned.is_empty()
                && cleaned != "Template rendering failed"
                && cleaned != "Template syntax error"
            {
                messages.push(cleaned);
            }
        }

        // If we got useful messages, return them
        if !messages.is_empty() {
            messages.join("\n  → ")
        } else {
            // Fallback: extract just the error kind
            "Template syntax error (see details above)".to_string()
        }
    }

    /// Format the template context as a string for error messages.
    ///
    /// # Arguments
    ///
    /// * `context` - The Tera context to format
    fn format_context_as_string(context: &TeraContext) -> String {
        let context_clone = context.clone();
        let json_value = context_clone.into_json();
        let mut output = String::new();

        // Recursively format the JSON structure with indentation
        fn format_value(key: &str, value: &serde_json::Value, indent: usize) -> Vec<String> {
            let prefix = "  ".repeat(indent);
            let mut lines = Vec::new();

            match value {
                serde_json::Value::Object(map) => {
                    lines.push(format!("{}{}:", prefix, key));
                    for (k, v) in map {
                        lines.extend(format_value(k, v, indent + 1));
                    }
                }
                serde_json::Value::Array(arr) => {
                    lines.push(format!("{}{}: [{} items]", prefix, key, arr.len()));
                    // Only show first few items to avoid spam
                    for (i, item) in arr.iter().take(3).enumerate() {
                        lines.extend(format_value(&format!("[{}]", i), item, indent + 1));
                    }
                    if arr.len() > 3 {
                        lines.push(format!("{}  ... {} more items", prefix, arr.len() - 3));
                    }
                }
                serde_json::Value::String(s) => {
                    // Truncate long strings
                    if s.len() > 100 {
                        lines.push(format!(
                            "{}{}: \"{}...\" ({} chars)",
                            prefix,
                            key,
                            &s[..97],
                            s.len()
                        ));
                    } else {
                        lines.push(format!("{}{}: \"{}\"", prefix, key, s));
                    }
                }
                serde_json::Value::Number(n) => {
                    lines.push(format!("{}{}: {}", prefix, key, n));
                }
                serde_json::Value::Bool(b) => {
                    lines.push(format!("{}{}: {}", prefix, key, b));
                }
                serde_json::Value::Null => {
                    lines.push(format!("{}{}: null", prefix, key));
                }
            }
            lines
        }

        if let serde_json::Value::Object(map) = &json_value {
            for (key, value) in map {
                output.push_str(&format_value(key, value, 1).join("\n"));
                output.push('\n');
            }
        }

        output
    }

    /// Log the template context as key-value pairs at debug level.
    ///
    /// # Arguments
    ///
    /// * `context` - The Tera context to log
    fn log_context_as_kv(context: &TeraContext) {
        let formatted = Self::format_context_as_string(context);
        for line in formatted.lines() {
            tracing::debug!("{}", line);
        }
    }

    /// Check if content contains Tera template syntax.
    ///
    /// # Arguments
    ///
    /// * `content` - The content to check
    ///
    /// # Returns
    ///
    /// Returns `true` if the content contains template delimiters.
    fn contains_template_syntax(&self, content: &str) -> bool {
        let has_vars = content.contains("{{");
        let has_tags = content.contains("{%");
        let has_comments = content.contains("{#");
        let result = has_vars || has_tags || has_comments;
        tracing::debug!(
            "Template syntax check: vars={}, tags={}, comments={}, result={}",
            has_vars,
            has_tags,
            has_comments,
            result
        );
        result
    }

    /// Check if content contains template syntax outside of code fences.
    ///
    /// This is used after rendering to determine if another pass is needed.
    /// It ignores template syntax inside code fences to prevent re-rendering
    /// content that has already been processed (like embedded dependency content).
    fn contains_template_syntax_outside_fences(&self, content: &str) -> bool {
        let mut in_code_fence = false;
        let mut in_guard = 0usize;

        for line in content.lines() {
            let trimmed = line.trim();

            if trimmed == NON_TEMPLATED_LITERAL_GUARD_START {
                in_guard = in_guard.saturating_add(1);
                continue;
            } else if trimmed == NON_TEMPLATED_LITERAL_GUARD_END {
                in_guard = in_guard.saturating_sub(1);
                continue;
            }

            if in_guard > 0 {
                continue;
            }

            // Track code fence boundaries
            if trimmed.starts_with("```") {
                in_code_fence = !in_code_fence;
                continue;
            }

            // Skip lines inside code fences
            if in_code_fence {
                continue;
            }

            // Check for template syntax in non-fenced content
            if line.contains("{{") || line.contains("{%") || line.contains("{#") {
                tracing::debug!(
                    "Template syntax found outside code fences: {:?}",
                    &line[..line.len().min(80)]
                );
                return true;
            }
        }

        tracing::debug!("No template syntax found outside code fences");
        false
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::lockfile::{LockFile, LockedResource};

    fn create_test_lockfile() -> LockFile {
        let mut lockfile = LockFile::default();

        // Add a test agent
        lockfile.agents.push(LockedResource {
            name: "test-agent".to_string(),
            source: Some("community".to_string()),
            url: Some("https://github.com/example/community.git".to_string()),
            path: "agents/test-agent.md".to_string(),
            version: Some("v1.0.0".to_string()),
            resolved_commit: Some("abc123def456".to_string()),
            checksum: "sha256:testchecksum".to_string(),
            installed_at: ".claude/agents/test-agent.md".to_string(),
            dependencies: vec![],
            resource_type: ResourceType::Agent,
            tool: Some("claude-code".to_string()),
            manifest_alias: None,
            applied_patches: std::collections::HashMap::new(),
            install: None,
        });

        lockfile
    }

    #[tokio::test]
    async fn test_template_context_builder() {
        let lockfile = create_test_lockfile();

        let cache = crate::cache::Cache::new().unwrap();
        let project_dir = std::env::current_dir().unwrap();
        let builder =
            TemplateContextBuilder::new(Arc::new(lockfile), None, Arc::new(cache), project_dir);

        let _context = builder.build_context("test-agent", ResourceType::Agent).await.unwrap();

        // If we got here without panicking, context building succeeded
        // The actual context structure is tested implicitly by the renderer tests
    }

    #[test]
    fn test_template_renderer() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        // Test rendering without template syntax
        let result = renderer.render_template("# Plain Markdown", &TeraContext::new()).unwrap();
        assert_eq!(result, "# Plain Markdown");

        // Test rendering with template syntax
        let mut context = TeraContext::new();
        context.insert("test_var", "test_value");

        let result = renderer.render_template("# {{ test_var }}", &context).unwrap();
        assert_eq!(result, "# test_value");
    }

    #[test]
    fn test_template_renderer_disabled() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(false, project_dir, None).unwrap();

        let mut context = TeraContext::new();
        context.insert("test_var", "test_value");

        // Should return content as-is when disabled
        let result = renderer.render_template("# {{ test_var }}", &context).unwrap();
        assert_eq!(result, "# {{ test_var }}");
    }

    #[test]
    fn test_template_error_formatting() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();
        let context = TeraContext::new();

        // Test with missing variable - should produce detailed error
        let result = renderer.render_template("# {{ missing_var }}", &context);
        assert!(result.is_err());

        let error = result.unwrap_err();
        let error_msg = format!("{}", error);

        // Error should NOT contain "__tera_one_off"
        assert!(
            !error_msg.contains("__tera_one_off"),
            "Error should not expose internal Tera template names"
        );

        // Error should contain useful information about the missing variable
        assert!(
            error_msg.contains("missing_var") || error_msg.contains("Variable"),
            "Error should mention the problematic variable or that a variable is missing. Got: {}",
            error_msg
        );
    }

    #[test]
    fn test_to_native_path_display() {
        // Test Unix-style path conversion
        let unix_path = ".claude/agents/test.md";
        let native_path = to_native_path_display(unix_path);

        #[cfg(windows)]
        {
            assert_eq!(native_path, ".claude\\agents\\test.md");
        }

        #[cfg(not(windows))]
        {
            assert_eq!(native_path, ".claude/agents/test.md");
        }
    }

    #[test]
    fn test_to_native_path_display_nested() {
        // Test deeply nested path
        let unix_path = ".claude/agents/ai/helpers/test.md";
        let native_path = to_native_path_display(unix_path);

        #[cfg(windows)]
        {
            assert_eq!(native_path, ".claude\\agents\\ai\\helpers\\test.md");
        }

        #[cfg(not(windows))]
        {
            assert_eq!(native_path, ".claude/agents/ai/helpers/test.md");
        }
    }

    #[tokio::test]
    async fn test_template_context_uses_native_paths() {
        let mut lockfile = create_test_lockfile();

        // Add another resource with a nested path
        lockfile.snippets.push(LockedResource {
            name: "test-snippet".to_string(),
            source: Some("community".to_string()),
            url: Some("https://github.com/example/community.git".to_string()),
            path: "snippets/utils/test.md".to_string(),
            version: Some("v1.0.0".to_string()),
            resolved_commit: Some("abc123def456".to_string()),
            checksum: "sha256:testchecksum".to_string(),
            installed_at: ".agpm/snippets/utils/test.md".to_string(),
            dependencies: vec![],
            resource_type: ResourceType::Snippet,
            tool: Some("agpm".to_string()),
            manifest_alias: None,
            applied_patches: std::collections::HashMap::new(),
            install: None,
        });

        let cache = crate::cache::Cache::new().unwrap();
        let project_dir = std::env::current_dir().unwrap();
        let builder =
            TemplateContextBuilder::new(Arc::new(lockfile), None, Arc::new(cache), project_dir);
        let context = builder.build_context("test-agent", ResourceType::Agent).await.unwrap();

        // Extract the agpm.resource.install_path from context
        let agpm_value = context.get("agpm").expect("agpm context should exist");
        let agpm_obj = agpm_value.as_object().expect("agpm should be an object");
        let resource_value = agpm_obj.get("resource").expect("resource should exist");
        let resource_obj = resource_value.as_object().expect("resource should be an object");
        let install_path = resource_obj
            .get("install_path")
            .expect("install_path should exist")
            .as_str()
            .expect("install_path should be a string");

        // Verify the path uses platform-native separators
        #[cfg(windows)]
        {
            assert_eq!(install_path, ".claude\\agents\\test-agent.md");
            assert!(install_path.contains('\\'), "Windows paths should use backslashes");
        }

        #[cfg(not(windows))]
        {
            assert_eq!(install_path, ".claude/agents/test-agent.md");
            assert!(install_path.contains('/'), "Unix paths should use forward slashes");
        }

        // Also verify dependency paths
        let deps_value = agpm_obj.get("deps").expect("deps should exist");
        let deps_obj = deps_value.as_object().expect("deps should be an object");
        let snippets = deps_obj.get("snippets").expect("snippets should exist");
        let snippets_obj = snippets.as_object().expect("snippets should be an object");
        let test_snippet = snippets_obj.get("test_snippet").expect("test_snippet should exist");
        let snippet_obj = test_snippet.as_object().expect("test_snippet should be an object");
        let snippet_path = snippet_obj
            .get("install_path")
            .expect("install_path should exist")
            .as_str()
            .expect("install_path should be a string");

        #[cfg(windows)]
        {
            assert_eq!(snippet_path, ".agpm\\snippets\\utils\\test.md");
        }

        #[cfg(not(windows))]
        {
            assert_eq!(snippet_path, ".agpm/snippets/utils/test.md");
        }
    }

    // Tests for literal block functionality (Phase 1)

    #[test]
    fn test_protect_literal_blocks_basic() {
        let project_dir = std::env::current_dir().unwrap();
        let renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let content = r#"# Documentation

Use this syntax:

```literal
{{ agpm.deps.snippets.example.content }}
```

That's how you embed content."#;

        let (protected, placeholders) = renderer.protect_literal_blocks(content);

        // Should have one placeholder
        assert_eq!(placeholders.len(), 1);

        // Protected content should contain placeholder
        assert!(protected.contains("__AGPM_LITERAL_BLOCK_0__"));

        // Protected content should NOT contain the template syntax
        assert!(!protected.contains("{{ agpm.deps.snippets.example.content }}"));

        // Placeholder should contain the original content
        let placeholder_content = placeholders.get("__AGPM_LITERAL_BLOCK_0__").unwrap();
        assert!(placeholder_content.contains("{{ agpm.deps.snippets.example.content }}"));
    }

    #[test]
    fn test_protect_literal_blocks_multiple() {
        let project_dir = std::env::current_dir().unwrap();
        let renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let content = r#"# First Example

```literal
{{ first.example }}
```

# Second Example

```literal
{{ second.example }}
```"#;

        let (protected, placeholders) = renderer.protect_literal_blocks(content);

        // Should have two placeholders
        assert_eq!(placeholders.len(), 2);

        // Both placeholders should be in the protected content
        assert!(protected.contains("__AGPM_LITERAL_BLOCK_0__"));
        assert!(protected.contains("__AGPM_LITERAL_BLOCK_1__"));

        // Original template syntax should not be in protected content
        assert!(!protected.contains("{{ first.example }}"));
        assert!(!protected.contains("{{ second.example }}"));
    }

    #[test]
    fn test_restore_literal_blocks() {
        let project_dir = std::env::current_dir().unwrap();
        let renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let mut placeholders = HashMap::new();
        placeholders.insert(
            "__AGPM_LITERAL_BLOCK_0__".to_string(),
            "{{ agpm.deps.snippets.example.content }}".to_string(),
        );

        let content = "# Example\n\n__AGPM_LITERAL_BLOCK_0__\n\nDone.";
        let restored = renderer.restore_literal_blocks(content, placeholders);

        // Should contain the original content in a code fence
        assert!(restored.contains("```\n{{ agpm.deps.snippets.example.content }}\n```"));

        // Should NOT contain the placeholder
        assert!(!restored.contains("__AGPM_LITERAL_BLOCK_0__"));
    }

    #[test]
    fn test_literal_blocks_integration_with_rendering() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let template = r#"# Agent: {{ agent_name }}

## Documentation

Here's how to use template syntax:

```literal
{{ agpm.deps.snippets.helper.content }}
```

The agent name is: {{ agent_name }}"#;

        let mut context = TeraContext::new();
        context.insert("agent_name", "test-agent");

        let result = renderer.render_template(template, &context).unwrap();

        // The agent_name variable should be rendered
        assert!(result.contains("# Agent: test-agent"));
        assert!(result.contains("The agent name is: test-agent"));

        // The literal block should be preserved and wrapped in code fence
        assert!(result.contains("```\n{{ agpm.deps.snippets.helper.content }}\n```"));

        // The literal block should NOT be rendered (still has template syntax)
        assert!(result.contains("{{ agpm.deps.snippets.helper.content }}"));
    }

    #[test]
    fn test_literal_blocks_with_complex_template_syntax() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let template = r#"# Documentation

```literal
{% for item in agpm.deps.agents %}
{{ item.name }}: {{ item.version }}
{% endfor %}
```"#;

        let context = TeraContext::new();
        let result = renderer.render_template(template, &context).unwrap();

        // Should preserve the for loop syntax
        assert!(result.contains("{% for item in agpm.deps.agents %}"));
        assert!(result.contains("{{ item.name }}"));
        assert!(result.contains("{% endfor %}"));
    }

    #[test]
    fn test_literal_blocks_empty() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let template = r#"# Example

```literal
```

Done."#;

        let context = TeraContext::new();
        let result = renderer.render_template(template, &context).unwrap();

        // Should handle empty literal blocks gracefully
        assert!(result.contains("# Example"));
        assert!(result.contains("Done."));
    }

    #[test]
    fn test_literal_blocks_unclosed() {
        let project_dir = std::env::current_dir().unwrap();
        let renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let content = r#"# Example

```literal
{{ template.syntax }}
This block is not closed"#;

        let (protected, placeholders) = renderer.protect_literal_blocks(content);

        // Should have no placeholders (unclosed block is treated as regular content)
        assert_eq!(placeholders.len(), 0);

        // Content should be preserved as-is
        assert!(protected.contains("```literal"));
        assert!(protected.contains("{{ template.syntax }}"));
    }

    #[test]
    fn test_literal_blocks_with_indentation() {
        let project_dir = std::env::current_dir().unwrap();
        let renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        let content = r#"# Example

    ```literal
    {{ indented.template }}
    ```"#;

        let (_protected, placeholders) = renderer.protect_literal_blocks(content);

        // Should detect indented literal blocks
        assert_eq!(placeholders.len(), 1);

        // Should preserve the indented template syntax
        let placeholder_content = placeholders.get("__AGPM_LITERAL_BLOCK_0__").unwrap();
        assert!(placeholder_content.contains("{{ indented.template }}"));
    }

    #[test]
    fn test_literal_blocks_in_transitive_dependency_content() {
        use std::fs;
        use tempfile::TempDir;

        let temp_dir = TempDir::new().unwrap();
        let project_dir = temp_dir.path().to_path_buf();

        // Create a dependency file with literal blocks containing template syntax
        let dep_content = r#"---
agpm.templating: true
---
# Dependency Documentation

Here's a template example:

```literal
{{ nonexistent_variable }}
{{ agpm.deps.something.else }}
```

This should appear literally."#;

        // Write the dependency file
        let dep_path = project_dir.join("dependency.md");
        fs::write(&dep_path, dep_content).unwrap();

        // First, render the dependency content (simulating what happens when processing a dependency)
        let mut dep_renderer = TemplateRenderer::new(true, project_dir.clone(), None).unwrap();
        let dep_context = TeraContext::new();
        let rendered_dep = dep_renderer.render_template(dep_content, &dep_context).unwrap();

        // The rendered dependency should have the literal block converted to a regular code fence
        assert!(rendered_dep.contains("```\n{{ nonexistent_variable }}"));
        assert!(rendered_dep.contains("{{ agpm.deps.something.else }}\n```"));

        // Now simulate embedding this in a parent resource
        let parent_template = r#"# Parent Resource

## Embedded Documentation

{{ dependency_content }}

## End"#;

        // Create context with the rendered dependency content
        let mut parent_context = TeraContext::new();
        parent_context.insert("dependency_content", &rendered_dep);

        // Render the parent (with templating enabled)
        let mut parent_renderer = TemplateRenderer::new(true, project_dir.clone(), None).unwrap();
        let final_output =
            parent_renderer.render_template(parent_template, &parent_context).unwrap();

        // Verify the final output contains the template syntax literally
        assert!(
            final_output.contains("{{ nonexistent_variable }}"),
            "Template syntax from literal block should appear literally in final output"
        );
        assert!(
            final_output.contains("{{ agpm.deps.something.else }}"),
            "Template syntax from literal block should appear literally in final output"
        );

        // Verify it's in a code fence
        assert!(
            final_output.contains("```\n{{ nonexistent_variable }}"),
            "Literal content should be in a code fence"
        );

        // Verify it doesn't cause rendering errors
        assert!(!final_output.contains("__AGPM_LITERAL_BLOCK_"), "No placeholders should remain");
    }

    #[test]
    fn test_literal_blocks_with_nested_dependencies() {
        let project_dir = std::env::current_dir().unwrap();
        let mut renderer = TemplateRenderer::new(true, project_dir, None).unwrap();

        // Simulate a dependency that was already rendered with literal blocks
        let dep_content = r#"# Helper Snippet

Use this syntax:

```
{{ agpm.deps.snippets.example.content }}
{{ missing.variable }}
```

Done."#;

        // Now embed this in a parent template
        let parent_template = r#"# Main Agent

## Documentation

{{ helper_content }}

The agent uses templating."#;

        let mut context = TeraContext::new();
        context.insert("helper_content", dep_content);

        let result = renderer.render_template(parent_template, &context).unwrap();

        // The template syntax from the dependency should be preserved
        assert!(result.contains("{{ agpm.deps.snippets.example.content }}"));
        assert!(result.contains("{{ missing.variable }}"));

        // It should be in a code fence
        assert!(result.contains("```\n{{ agpm.deps.snippets.example.content }}"));
    }

    #[tokio::test]
    async fn test_non_templated_dependency_content_is_guarded() {
        use tempfile::TempDir;
        use tokio::fs;

        let temp_dir = TempDir::new().unwrap();
        let project_dir = temp_dir.path().to_path_buf();

        let snippets_dir = project_dir.join("snippets");
        fs::create_dir_all(&snippets_dir).await.unwrap();
        let snippet_path = snippets_dir.join("non-templated.md");
        fs::write(
            &snippet_path,
            r#"---
agpm:
  templating: false
---
# Example Snippet

This should show {{ agpm.deps.some.content }} literally.
"#,
        )
        .await
        .unwrap();

        let mut lockfile = LockFile::default();
        lockfile.commands.push(LockedResource {
            name: "test-command".to_string(),
            source: None,
            url: None,
            path: "commands/test.md".to_string(),
            version: None,
            resolved_commit: None,
            checksum: "sha256:test-command".to_string(),
            installed_at: ".claude/commands/test.md".to_string(),
            dependencies: vec![],
            resource_type: ResourceType::Command,
            tool: Some("claude-code".to_string()),
            manifest_alias: None,
            applied_patches: std::collections::HashMap::new(),
            install: None,
        });
        lockfile.snippets.push(LockedResource {
            name: "non_templated".to_string(),
            source: None,
            url: None,
            path: "snippets/non-templated.md".to_string(),
            version: None,
            resolved_commit: None,
            checksum: "sha256:test-snippet".to_string(),
            installed_at: ".agpm/snippets/non-templated.md".to_string(),
            dependencies: vec![],
            resource_type: ResourceType::Snippet,
            tool: Some("agpm".to_string()),
            manifest_alias: None,
            applied_patches: std::collections::HashMap::new(),
            install: None,
        });

        let cache = crate::cache::Cache::new().unwrap();
        let builder = TemplateContextBuilder::new(
            Arc::new(lockfile),
            None,
            Arc::new(cache),
            project_dir.clone(),
        );
        let context = builder.build_context("test-command", ResourceType::Command).await.unwrap();

        let mut renderer = TemplateRenderer::new(true, project_dir.clone(), None).unwrap();
        let template = r#"# Combined Output

{{ agpm.deps.snippets.non_templated.content }}
"#;
        let rendered = renderer.render_template(template, &context).unwrap();

        assert!(
            rendered.contains("# Example Snippet"),
            "Rendered output should include the snippet heading"
        );
        assert!(
            rendered.contains("{{ agpm.deps.some.content }}"),
            "Template syntax inside non-templated dependency should remain literal"
        );
        assert!(
            !rendered.contains(NON_TEMPLATED_LITERAL_GUARD_START)
                && !rendered.contains(NON_TEMPLATED_LITERAL_GUARD_END),
            "Internal literal guard markers should not leak into rendered output"
        );
        assert!(
            !rendered.contains("```literal"),
            "Synthetic literal fences should be removed after rendering"
        );
    }
}