aster/tools/file/

read.rs

//! Read Tool Implementation
//!
//! This module implements the `ReadTool` for reading files with:
//! - Text file reading with line numbers
//! - Image reading with base64 encoding
//! - PDF reading (optional)
//! - Jupyter notebook reading
//! - File read history tracking
//!
//! Requirements: 4.1, 4.2, 4.3, 4.4, 4.5

use std::fs;
use std::path::{Path, PathBuf};

use async_trait::async_trait;
use base64::{engine::general_purpose::STANDARD as BASE64, Engine};
use serde::{Deserialize, Serialize};
use tracing::debug;

use super::{compute_content_hash, FileReadRecord, SharedFileReadHistory};
use crate::tools::base::{PermissionCheckResult, Tool};
use crate::tools::context::{ToolContext, ToolOptions, ToolResult};
use crate::tools::error::ToolError;

/// Maximum file size for text files (10MB)
pub const MAX_TEXT_FILE_SIZE: u64 = 10 * 1024 * 1024;

/// Maximum file size for images (50MB)
pub const MAX_IMAGE_FILE_SIZE: u64 = 50 * 1024 * 1024;

/// Supported image extensions
const IMAGE_EXTENSIONS: &[&str] = &["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "svg"];

/// Supported text extensions (non-exhaustive, used for hints)
const TEXT_EXTENSIONS: &[&str] = &[
    "txt",
    "md",
    "rs",
    "py",
    "js",
    "ts",
    "jsx",
    "tsx",
    "json",
    "yaml",
    "yml",
    "toml",
    "xml",
    "html",
    "css",
    "scss",
    "less",
    "sql",
    "sh",
    "bash",
    "zsh",
    "c",
    "cpp",
    "h",
    "hpp",
    "java",
    "go",
    "rb",
    "php",
    "swift",
    "kt",
    "scala",
    "r",
    "lua",
    "pl",
    "pm",
    "ex",
    "exs",
    "erl",
    "hrl",
    "hs",
    "ml",
    "mli",
    "fs",
    "fsx",
    "clj",
    "cljs",
    "lisp",
    "el",
    "vim",
    "conf",
    "ini",
    "cfg",
    "env",
    "gitignore",
    "dockerignore",
    "makefile",
    "cmake",
    "gradle",
];

/// Line range for partial file reading
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct LineRange {
    /// Start line (1-indexed, inclusive)
    pub start: usize,
    /// End line (1-indexed, inclusive, None means to end of file)
    pub end: Option<usize>,
}

impl LineRange {
    /// Create a new line range
    pub fn new(start: usize, end: Option<usize>) -> Self {
        Self { start, end }
    }

    /// Create a range from start to end of file
    pub fn from_start(start: usize) -> Self {
        Self { start, end: None }
    }

    /// Create a range for a specific number of lines from start
    pub fn lines(start: usize, count: usize) -> Self {
        Self {
            start,
            end: Some(start + count - 1),
        }
    }
}

/// Read Tool for reading files
///
/// Supports reading:
/// - Text files with line numbers
/// - Images as base64
/// - PDF files (optional)
/// - Jupyter notebooks
///
/// Requirements: 4.1, 4.2, 4.3, 4.4, 4.5
/// File analysis information for enhanced text reading
#[derive(Debug)]
struct TextFileInfo {
    path: PathBuf,
    extension: String,
    language: Option<String>,
    file_category: String,
    size_bytes: u64,
    total_lines: usize,
}

#[derive(Debug)]
pub struct ReadTool {
    /// Shared file read history
    read_history: SharedFileReadHistory,
    /// Whether PDF reading is enabled
    pdf_enabled: bool,
}

impl ReadTool {
    /// Create a new ReadTool with shared history
    pub fn new(read_history: SharedFileReadHistory) -> Self {
        Self {
            read_history,
            pdf_enabled: false,
        }
    }

    /// Enable PDF reading
    pub fn with_pdf_enabled(mut self, enabled: bool) -> Self {
        self.pdf_enabled = enabled;
        self
    }

    /// Get the shared read history
    pub fn read_history(&self) -> &SharedFileReadHistory {
        &self.read_history
    }
}

// =============================================================================
// Text File Reading (Requirements: 4.1)
// =============================================================================

impl ReadTool {
    /// Read a text file with line numbers
    ///
    /// Returns the file content with line numbers prefixed.
    /// Optionally reads only a specific line range.
    ///
    /// Requirements: 4.1
    pub async fn read_text(
        &self,
        path: &Path,
        range: Option<LineRange>,
        context: &ToolContext,
    ) -> Result<String, ToolError> {
        let full_path = self.resolve_path(path, context);

        // Check file exists
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "File not found: {}",
                full_path.display()
            )));
        }

        // Check file size
        let metadata = fs::metadata(&full_path)?;
        if metadata.len() > MAX_TEXT_FILE_SIZE {
            return Err(ToolError::execution_failed(format!(
                "File too large: {} bytes (max: {} bytes)",
                metadata.len(),
                MAX_TEXT_FILE_SIZE
            )));
        }

        // Read file content
        let content = fs::read(&full_path)?;
        let text = String::from_utf8_lossy(&content);

        // Record the read
        self.record_file_read(&full_path, &content, &metadata)?;

        // Format with line numbers
        let lines: Vec<&str> = text.lines().collect();
        let total_lines = lines.len();

        let (start, end) = match range {
            Some(r) => {
                let start = r.start.saturating_sub(1).min(total_lines);
                let end = r.end.map(|e| e.min(total_lines)).unwrap_or(total_lines);
                (start, end)
            }
            None => (0, total_lines),
        };

        // Calculate line number width for formatting
        let line_width = (end.max(1)).to_string().len();

        let formatted: Vec<String> = lines[start..end]
            .iter()
            .enumerate()
            .map(|(i, line)| {
                let line_num = start + i + 1;
                format!("{:>width$} | {}", line_num, line, width = line_width)
            })
            .collect();

        debug!(
            "Read text file: {} ({} lines, showing {}-{})",
            full_path.display(),
            total_lines,
            start + 1,
            end
        );

        Ok(formatted.join("\n"))
    }

    /// Record a file read in the history
    fn record_file_read(
        &self,
        path: &Path,
        content: &[u8],
        metadata: &fs::Metadata,
    ) -> Result<(), ToolError> {
        let hash = compute_content_hash(content);
        let mtime = metadata.modified().ok();
        let line_count = String::from_utf8_lossy(content).lines().count();

        let mut record = FileReadRecord::new(path.to_path_buf(), hash, metadata.len())
            .with_line_count(line_count);

        if let Some(mt) = mtime {
            record = record.with_mtime(mt);
        }

        self.read_history.write().unwrap().record_read(record);
        Ok(())
    }

    /// Resolve a path relative to the working directory
    fn resolve_path(&self, path: &Path, context: &ToolContext) -> PathBuf {
        if path.is_absolute() {
            path.to_path_buf()
        } else {
            context.working_directory.join(path)
        }
    }
}

// =============================================================================
// Image Reading (Requirements: 4.2)
// =============================================================================

impl ReadTool {
    /// Read an image file with enhanced analysis capabilities
    ///
    /// Enhanced version inspired by Claude Agent SDK:
    /// - Provides detailed image metadata
    /// - Estimates token consumption
    /// - Supports intelligent image analysis
    /// - Returns structured information for AI processing
    ///
    /// Requirements: 4.2
    pub async fn read_image(
        &self,
        path: &Path,
        context: &ToolContext,
    ) -> Result<String, ToolError> {
        let full_path = self.resolve_path(path, context);

        // Check file exists
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "Image not found: {}",
                full_path.display()
            )));
        }

        // Check file size
        let metadata = fs::metadata(&full_path)?;
        if metadata.len() > MAX_IMAGE_FILE_SIZE {
            return Err(ToolError::execution_failed(format!(
                "Image too large: {} bytes (max: {} bytes)",
                metadata.len(),
                MAX_IMAGE_FILE_SIZE
            )));
        }

        // Use enhanced image processing from media module
        let image_result = crate::media::read_image_file_enhanced(&full_path)
            .map_err(|e| ToolError::execution_failed(format!("Failed to read image: {}", e)))?;

        // Record the read
        let content = fs::read(&full_path)?;
        self.record_file_read(&full_path, &content, &metadata)?;

        // Calculate enhanced metadata
        let size_kb = (image_result.original_size as f64 / 1024.0).round() as u64;
        let token_estimate = crate::media::estimate_image_tokens(&image_result.base64);

        // Build enhanced output with analysis information
        let mut output = Vec::new();
        output.push(format!(
            "[Enhanced Image Analysis: {}]",
            full_path.display()
        ));
        output.push(format!("Format: {}", image_result.mime_type));
        output.push(format!(
            "Size: {} KB ({} bytes)",
            size_kb, image_result.original_size
        ));

        if let Some(dims) = &image_result.dimensions {
            if let (Some(w), Some(h)) = (dims.original_width, dims.original_height) {
                output.push(format!("Original dimensions: {}x{}", w, h));
                if let (Some(dw), Some(dh)) = (dims.display_width, dims.display_height) {
                    if dw != w || dh != h {
                        output.push(format!("Display dimensions: {}x{} (resized)", dw, dh));
                    }
                }
            }
        }

        output.push(format!("Estimated tokens: {}", token_estimate));

        // Add analysis hints for AI processing
        output.push(String::new());
        output.push("AI Analysis Capabilities:".to_string());
        output.push("- Content recognition and description".to_string());
        output.push("- Text extraction (OCR)".to_string());
        output.push("- Object and scene detection".to_string());
        output.push("- Color analysis and composition".to_string());
        output.push("- Technical diagram interpretation".to_string());
        output.push("- Screenshot analysis and UI element identification".to_string());

        debug!(
            "Enhanced image read: {} ({} KB, {} tokens, {})",
            full_path.display(),
            size_kb,
            token_estimate,
            image_result.mime_type
        );

        // Return formatted analysis with base64 data
        Ok(format!(
            "{}\n\nBase64 Data: data:{};base64,{}",
            output.join("\n"),
            image_result.mime_type,
            image_result.base64
        ))
    }

    /// Check if a file is an image based on extension (uses media module)
    pub fn is_image_file(path: &Path) -> bool {
        let ext = path
            .extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase();
        crate::media::is_supported_image_format(&ext)
    }
}

// =============================================================================
// PDF Reading (Requirements: 4.3)
// =============================================================================

impl ReadTool {
    /// Read a PDF file with enhanced processing capabilities
    ///
    /// Enhanced version inspired by Claude Agent SDK:
    /// - Provides detailed PDF metadata
    /// - Supports document block processing for AI analysis
    /// - Returns structured information for multimodal AI processing
    /// - Includes content extraction hints
    ///
    /// Note: PDF reading requires external dependencies and is disabled by default.
    /// When enabled, extracts text content from PDF files and prepares them
    /// for AI analysis with document blocks.
    ///
    /// Requirements: 4.3
    pub async fn read_pdf(&self, path: &Path, context: &ToolContext) -> Result<String, ToolError> {
        if !self.pdf_enabled {
            return Err(ToolError::execution_failed(
                "PDF reading is not enabled. Enable it with ReadTool::with_pdf_enabled(true)",
            ));
        }

        let full_path = self.resolve_path(path, context);

        // Check file exists
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "PDF not found: {}",
                full_path.display()
            )));
        }

        // Read file content for history tracking and analysis
        let content = fs::read(&full_path)?;
        let metadata = fs::metadata(&full_path)?;
        self.record_file_read(&full_path, &content, &metadata)?;

        // Calculate enhanced metadata
        let size_mb = (metadata.len() as f64 / 1_048_576.0 * 100.0).round() / 100.0;
        let base64_content = BASE64.encode(&content);
        let base64_length = base64_content.len();

        // Build enhanced output with analysis information
        let mut output = Vec::new();
        output.push(format!("[Enhanced PDF Analysis: {}]", full_path.display()));
        output.push(format!("Size: {} MB ({} bytes)", size_mb, metadata.len()));
        output.push(format!("Base64 length: {} chars", base64_length));
        output.push(String::new());

        // Add analysis capabilities information
        output.push("AI Analysis Capabilities:".to_string());
        output.push("- Document structure analysis".to_string());
        output.push("- Text extraction and content analysis".to_string());
        output.push("- Table and form recognition".to_string());
        output.push("- Image and diagram extraction".to_string());
        output.push("- Layout and formatting analysis".to_string());
        output.push("- Multi-page document processing".to_string());
        output.push(String::new());

        // Add processing hints
        output.push("Processing Notes:".to_string());
        output
            .push("- PDF content will be processed as document blocks for AI analysis".to_string());
        output.push("- Large PDFs may be processed in chunks for optimal performance".to_string());
        output.push("- Text and visual elements will be analyzed together".to_string());

        debug!(
            "Enhanced PDF read: {} ({} MB, {} base64 chars)",
            full_path.display(),
            size_mb,
            base64_length
        );

        // Return enhanced analysis information
        // Note: In a full implementation, this would include the actual PDF processing
        // and document block creation for AI analysis
        Ok(format!("{}\n\nDocument ready for AI analysis.\nBase64 data available for multimodal processing.", 
                   output.join("\n")))
    }

    /// Check if a file is a PDF (uses media module)
    pub fn is_pdf_file(path: &Path) -> bool {
        let ext = path
            .extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase();
        crate::media::is_pdf_extension(&ext)
    }
}

// =============================================================================
// Jupyter Notebook Reading (Requirements: 4.4)
// =============================================================================

impl ReadTool {
    /// Read an SVG file with enhanced rendering capabilities
    ///
    /// Enhanced version inspired by Claude Agent SDK:
    /// - Supports SVG content analysis
    /// - Provides rendering information
    /// - Includes vector graphics analysis capabilities
    /// - Returns structured information for AI processing
    ///
    /// Requirements: 4.2 (extended)
    pub async fn read_svg(&self, path: &Path, context: &ToolContext) -> Result<String, ToolError> {
        let full_path = self.resolve_path(path, context);

        // Check file exists
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "SVG not found: {}",
                full_path.display()
            )));
        }

        // Read file content
        let content = fs::read(&full_path)?;
        let metadata = fs::metadata(&full_path)?;
        let svg_text = String::from_utf8_lossy(&content);

        // Record the read
        self.record_file_read(&full_path, &content, &metadata)?;

        // Calculate metadata
        let size_kb = (metadata.len() as f64 / 1024.0).round() as u64;

        // Build enhanced output with analysis information
        let mut output = Vec::new();
        output.push(format!("[Enhanced SVG Analysis: {}]", full_path.display()));
        output.push(format!("Size: {} KB ({} bytes)", size_kb, metadata.len()));
        output.push("Content type: Scalable Vector Graphics".to_string());
        output.push(String::new());

        // Add analysis capabilities information
        output.push("AI Analysis Capabilities:".to_string());
        output.push("- Vector graphics structure analysis".to_string());
        output.push("- Shape and path recognition".to_string());
        output.push("- Text content extraction".to_string());
        output.push("- Color scheme analysis".to_string());
        output.push("- Diagram and flowchart interpretation".to_string());
        output.push("- Icon and symbol recognition".to_string());
        output.push(String::new());

        // Add SVG content preview (first few lines)
        output.push("SVG Content Preview:".to_string());
        let lines: Vec<&str> = svg_text.lines().take(10).collect();
        for (i, line) in lines.iter().enumerate() {
            let trimmed = line.trim();
            if !trimmed.is_empty() {
                output.push(format!("  {}: {}", i + 1, trimmed));
            }
        }

        if svg_text.lines().count() > 10 {
            output.push("  ... (content truncated)".to_string());
        }

        debug!(
            "Enhanced SVG read: {} ({} KB)",
            full_path.display(),
            size_kb
        );

        // Return enhanced analysis with full SVG content
        Ok(format!(
            "{}\n\nFull SVG Content:\n{}",
            output.join("\n"),
            svg_text
        ))
    }

    /// Read a Jupyter notebook file with enhanced analysis
    ///
    /// Enhanced version inspired by Claude Agent SDK:
    /// - Extracts and formats code cells and markdown cells
    /// - Provides execution output analysis
    /// - Includes data visualization detection
    /// - Returns structured information for AI processing
    ///
    /// Requirements: 4.4
    pub async fn read_notebook(
        &self,
        path: &Path,
        context: &ToolContext,
    ) -> Result<String, ToolError> {
        let full_path = self.resolve_path(path, context);

        // Check file exists and read content
        let (content, metadata, notebook) = self.load_notebook_file(&full_path)?;

        // Record the read
        self.record_file_read(&full_path, &content, &metadata)?;

        // Extract cells and build output
        let cells = self.extract_notebook_cells(&notebook)?;
        let output = self.build_notebook_output(&full_path, &metadata, cells);

        debug!(
            "Enhanced notebook read: {} ({} cells)",
            full_path.display(),
            cells.len()
        );

        Ok(output.join("\n"))
    }

    /// Add notebook header and statistics
    fn add_notebook_header(
        &self,
        output: &mut Vec<String>,
        full_path: &Path,
        metadata: &fs::Metadata,
        cells: &[serde_json::Value],
    ) {
        output.push(format!(
            "[Enhanced Notebook Analysis: {}]",
            full_path.display()
        ));
        output.push(format!(
            "Size: {} KB",
            (metadata.len() as f64 / 1024.0).round() as u64
        ));
        output.push(format!("Total cells: {}", cells.len()));

        // Analyze cell types
        let (code_cells, markdown_cells, other_cells) = self.analyze_cell_types(cells);
        output.push(format!(
            "Code cells: {}, Markdown cells: {}, Other: {}",
            code_cells, markdown_cells, other_cells
        ));
        output.push(String::new());
    }

    /// Load and parse notebook file
    fn load_notebook_file(
        &self,
        full_path: &Path,
    ) -> Result<(Vec<u8>, fs::Metadata, serde_json::Value), ToolError> {
        // Check file exists
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "Notebook not found: {}",
                full_path.display()
            )));
        }

        // Read and parse JSON
        let content = fs::read(full_path)?;
        let metadata = fs::metadata(full_path)?;

        let notebook: serde_json::Value = serde_json::from_slice(&content).map_err(|e| {
            ToolError::execution_failed(format!("Failed to parse notebook JSON: {}", e))
        })?;

        Ok((content, metadata, notebook))
    }

    /// Extract cells from notebook JSON
    fn extract_notebook_cells<'a>(
        &self,
        notebook: &'a serde_json::Value,
    ) -> Result<&'a Vec<serde_json::Value>, ToolError> {
        notebook
            .get("cells")
            .and_then(|c| c.as_array())
            .ok_or_else(|| ToolError::execution_failed("Invalid notebook format: missing cells"))
    }

    /// Build complete notebook output
    fn build_notebook_output(
        &self,
        full_path: &Path,
        metadata: &fs::Metadata,
        cells: &[serde_json::Value],
    ) -> Vec<String> {
        let mut output = Vec::new();

        // Add header and statistics
        self.add_notebook_header(&mut output, full_path, metadata, cells);

        // Add analysis capabilities
        self.add_analysis_capabilities(&mut output);

        // Process each cell
        self.process_notebook_cells(&mut output, cells);

        output
    }

    /// Analyze cell types and return counts
    fn analyze_cell_types(&self, cells: &[serde_json::Value]) -> (usize, usize, usize) {
        let mut code_cells = 0;
        let mut markdown_cells = 0;
        let mut other_cells = 0;

        for cell in cells {
            match cell
                .get("cell_type")
                .and_then(|t| t.as_str())
                .unwrap_or("unknown")
            {
                "code" => code_cells += 1,
                "markdown" => markdown_cells += 1,
                _ => other_cells += 1,
            }
        }

        (code_cells, markdown_cells, other_cells)
    }

    /// Add analysis capabilities description
    fn add_analysis_capabilities(&self, output: &mut Vec<String>) {
        output.push("AI Analysis Capabilities:".to_string());
        output.push("- Code execution flow analysis".to_string());
        output.push("- Data visualization interpretation".to_string());
        output.push("- Scientific computation analysis".to_string());
        output.push("- Documentation and markdown processing".to_string());
        output.push("- Output and result interpretation".to_string());
        output.push("- Machine learning workflow analysis".to_string());
        output.push(String::new());
    }

    /// Process all notebook cells
    fn process_notebook_cells(&self, output: &mut Vec<String>, cells: &[serde_json::Value]) {
        for (i, cell) in cells.iter().enumerate() {
            self.process_single_cell(output, cell, i + 1);
            output.push(String::new());
        }
    }

    /// Process a single notebook cell
    fn process_single_cell(
        &self,
        output: &mut Vec<String>,
        cell: &serde_json::Value,
        cell_num: usize,
    ) {
        let cell_type = cell
            .get("cell_type")
            .and_then(|t| t.as_str())
            .unwrap_or("unknown");

        let source = cell
            .get("source")
            .map(|s| self.extract_cell_source(s))
            .unwrap_or_default();

        match cell_type {
            "code" => {
                output.push(format!("## Cell {} [Code Cell] 🐍", cell_num));
                output.push("```python".to_string());
                output.push(source);
                output.push("```".to_string());

                // Include outputs if present
                self.process_cell_outputs(output, cell);
            }
            "markdown" => {
                output.push(format!("## Cell {} [Markdown Cell] 📝", cell_num));
                output.push(source);
            }
            _ => {
                output.push(format!("## Cell {} [{}] ❓", cell_num, cell_type));
                output.push(source);
            }
        }
    }

    /// Process cell outputs
    fn process_cell_outputs(&self, output: &mut Vec<String>, cell: &serde_json::Value) {
        if let Some(outputs) = cell.get("outputs").and_then(|o| o.as_array()) {
            if !outputs.is_empty() {
                output.push("### Execution Output:".to_string());
                for (out_idx, out) in outputs.iter().enumerate() {
                    if let Some(text) = self.extract_output_text(out) {
                        output.push(format!(
                            "#### Output {} [{}]:",
                            out_idx + 1,
                            out.get("output_type")
                                .and_then(|t| t.as_str())
                                .unwrap_or("result")
                        ));
                        output.push("```".to_string());
                        output.push(text);
                        output.push("```".to_string());
                    }
                }
            }
        }
    }

    /// Extract source from a cell (handles both string and array formats)
    fn extract_cell_source(&self, source: &serde_json::Value) -> String {
        match source {
            serde_json::Value::String(s) => s.clone(),
            serde_json::Value::Array(arr) => arr
                .iter()
                .filter_map(|v| v.as_str())
                .collect::<Vec<_>>()
                .join(""),
            _ => String::new(),
        }
    }

    /// Extract text from cell output
    fn extract_output_text(&self, output: &serde_json::Value) -> Option<String> {
        // Try "text" field first (stream output)
        if let Some(text) = output.get("text") {
            return Some(self.extract_cell_source(text));
        }

        // Try "data" -> "text/plain" (execute_result)
        if let Some(data) = output.get("data") {
            if let Some(text) = data.get("text/plain") {
                return Some(self.extract_cell_source(text));
            }
        }

        None
    }

    /// Check if a file is a Jupyter notebook
    pub fn is_notebook_file(path: &Path) -> bool {
        path.extension()
            .and_then(|e| e.to_str())
            .map(|e| e.to_lowercase() == "ipynb")
            .unwrap_or(false)
    }
}

// =============================================================================
// Tool Trait Implementation
// =============================================================================

#[async_trait]
impl Tool for ReadTool {
    fn name(&self) -> &str {
        "read"
    }

    fn description(&self) -> &str {
        "Enhanced multimodal file reader with intelligent analysis capabilities. \
         Supports text files (with syntax highlighting and language detection), \
         images (with metadata and AI analysis hints), PDF files (with document processing), \
         SVG files (with vector graphics analysis), and Jupyter notebooks (with computational analysis). \
         Automatically detects file type and provides structured information optimized for AI processing. \
         Inspired by Claude Agent SDK for comprehensive file understanding and analysis."
    }

    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Path to the file to read (relative to working directory or absolute)"
                },
                "start_line": {
                    "type": "integer",
                    "description": "Start line number (1-indexed, for text files only)",
                    "minimum": 1
                },
                "end_line": {
                    "type": "integer",
                    "description": "End line number (1-indexed, inclusive, for text files only)",
                    "minimum": 1
                }
            },
            "required": ["path"]
        })
    }

    async fn execute(
        &self,
        params: serde_json::Value,
        context: &ToolContext,
    ) -> Result<ToolResult, ToolError> {
        // Check for cancellation
        if context.is_cancelled() {
            return Err(ToolError::Cancelled);
        }

        // Extract path parameter
        let path_str = params
            .get("path")
            .and_then(|v| v.as_str())
            .ok_or_else(|| ToolError::invalid_params("Missing required parameter: path"))?;

        let path = Path::new(path_str);

        // Determine file type and read accordingly with enhanced analysis
        if Self::is_image_file(path) {
            let content = self.read_image(path, context).await?;
            return Ok(ToolResult::success(content)
                .with_metadata("file_type", serde_json::json!("image"))
                .with_metadata("analysis_type", serde_json::json!("enhanced_multimodal")));
        }

        if Self::is_pdf_file(path) {
            let content = self.read_pdf(path, context).await?;
            return Ok(ToolResult::success(content)
                .with_metadata("file_type", serde_json::json!("pdf"))
                .with_metadata("analysis_type", serde_json::json!("enhanced_document")));
        }

        if Self::is_svg_file(path) {
            let content = self.read_svg(path, context).await?;
            return Ok(ToolResult::success(content)
                .with_metadata("file_type", serde_json::json!("svg"))
                .with_metadata("analysis_type", serde_json::json!("enhanced_vector")));
        }

        if Self::is_notebook_file(path) {
            let content = self.read_notebook(path, context).await?;
            return Ok(ToolResult::success(content)
                .with_metadata("file_type", serde_json::json!("notebook"))
                .with_metadata("analysis_type", serde_json::json!("enhanced_computational")));
        }

        // Enhanced text file reading with intelligent analysis
        let range = self.extract_line_range(&params);
        let content = self.read_text_enhanced(path, range, context).await?;

        Ok(ToolResult::success(content)
            .with_metadata("file_type", serde_json::json!("text"))
            .with_metadata("analysis_type", serde_json::json!("enhanced_textual")))
    }

    async fn check_permissions(
        &self,
        params: &serde_json::Value,
        context: &ToolContext,
    ) -> PermissionCheckResult {
        // Extract path for permission check
        let path_str = match params.get("path").and_then(|v| v.as_str()) {
            Some(p) => p,
            None => return PermissionCheckResult::deny("Missing path parameter"),
        };

        let path = Path::new(path_str);
        let full_path = self.resolve_path(path, context);

        // Check if path is within allowed directories
        // For now, allow all reads (permission manager handles restrictions)
        debug!("Permission check for read: {}", full_path.display());

        PermissionCheckResult::allow()
    }

    fn options(&self) -> ToolOptions {
        ToolOptions::new()
            .with_max_retries(1)
            .with_base_timeout(std::time::Duration::from_secs(30))
    }
}

impl ReadTool {
    /// Extract line range from parameters
    fn extract_line_range(&self, params: &serde_json::Value) -> Option<LineRange> {
        let start = params
            .get("start_line")
            .and_then(|v| v.as_u64())
            .map(|v| v as usize);
        let end = params
            .get("end_line")
            .and_then(|v| v.as_u64())
            .map(|v| v as usize);

        match (start, end) {
            (Some(s), e) => Some(LineRange::new(s, e)),
            (None, Some(e)) => Some(LineRange::new(1, Some(e))),
            (None, None) => None,
        }
    }

    /// Read a text file with enhanced analysis capabilities
    ///
    /// Enhanced version inspired by Claude Agent SDK:
    /// - Provides intelligent content analysis
    /// - Detects programming languages and file types
    /// - Includes syntax highlighting hints
    /// - Returns structured information for AI processing
    ///
    /// Requirements: 4.1
    pub async fn read_text_enhanced(
        &self,
        path: &Path,
        range: Option<LineRange>,
        context: &ToolContext,
    ) -> Result<String, ToolError> {
        let full_path = self.resolve_path(path, context);

        // Load and validate file
        let (content, metadata, text) = self.load_text_file(&full_path)?;

        // Record the read
        self.record_file_read(&full_path, &content, &metadata)?;

        // Analyze and format content
        let file_info = self.analyze_text_file(&full_path, &text, &metadata);
        let formatted_content = self.format_text_with_lines(&text, range);
        let output = self.build_text_analysis_output(&file_info, &formatted_content, range);

        debug!(
            "Enhanced text read: {} ({} lines, {}, {})",
            full_path.display(),
            file_info.total_lines,
            file_info.file_category,
            file_info.language.unwrap_or_else(|| "unknown".to_string())
        );

        Ok(output.join("\n"))
    }

    /// Analyze text file and extract metadata
    fn analyze_text_file(&self, path: &Path, text: &str, metadata: &fs::Metadata) -> TextFileInfo {
        let extension = path
            .extension()
            .and_then(|e| e.to_str())
            .unwrap_or("")
            .to_lowercase();

        let language = self.detect_programming_language(&extension, text);
        let file_category = self.categorize_file_type(&extension);
        let total_lines = text.lines().count();

        TextFileInfo {
            path: path.to_path_buf(),
            extension,
            language,
            file_category,
            size_bytes: metadata.len(),
            total_lines,
        }
    }

    /// Load and validate text file
    fn load_text_file(
        &self,
        full_path: &Path,
    ) -> Result<(Vec<u8>, fs::Metadata, String), ToolError> {
        // Check file exists and size
        if !full_path.exists() {
            return Err(ToolError::execution_failed(format!(
                "File not found: {}",
                full_path.display()
            )));
        }

        let metadata = fs::metadata(full_path)?;
        if metadata.len() > MAX_TEXT_FILE_SIZE {
            return Err(ToolError::execution_failed(format!(
                "File too large: {} bytes (max: {} bytes)",
                metadata.len(),
                MAX_TEXT_FILE_SIZE
            )));
        }

        // Read and process file
        let content = fs::read(full_path)?;
        let text = String::from_utf8_lossy(&content).to_string();

        Ok((content, metadata, text))
    }

    /// Format text content with line numbers
    fn format_text_with_lines(&self, text: &str, range: Option<LineRange>) -> Vec<String> {
        let lines: Vec<&str> = text.lines().collect();
        let total_lines = lines.len();

        let (start, end) = match range {
            Some(r) => {
                let start = r.start.saturating_sub(1).min(total_lines);
                let end = r.end.map(|e| e.min(total_lines)).unwrap_or(total_lines);
                (start, end)
            }
            None => (0, total_lines),
        };

        let line_width = (end.max(1)).to_string().len();

        lines[start..end]
            .iter()
            .enumerate()
            .map(|(i, line)| {
                let line_num = start + i + 1;
                format!("{:>width$} | {}", line_num, line, width = line_width)
            })
            .collect()
    }

    /// Build enhanced text analysis output
    fn build_text_analysis_output(
        &self,
        file_info: &TextFileInfo,
        formatted_content: &[String],
        range: Option<LineRange>,
    ) -> Vec<String> {
        let mut output = Vec::new();

        // Add header information
        output.push(format!(
            "[Enhanced Text Analysis: {}]",
            file_info.path.display()
        ));
        output.push(format!(
            "File type: {} ({})",
            file_info.file_category, file_info.extension
        ));
        if let Some(lang) = &file_info.language {
            output.push(format!("Programming language: {}", lang));
        }
        output.push(format!(
            "Size: {} KB ({} bytes)",
            (file_info.size_bytes as f64 / 1024.0).round() as u64,
            file_info.size_bytes
        ));

        // Add line information
        let (start, end) = self.get_display_range(file_info.total_lines, range);
        output.push(format!(
            "Lines: {} total, showing {}-{}",
            file_info.total_lines, start, end
        ));
        output.push(String::new());

        // Add analysis capabilities
        self.add_text_analysis_capabilities(&mut output, &file_info.file_category);

        // Add formatted content
        output.push("File Content:".to_string());
        output.extend_from_slice(formatted_content);

        output
    }

    /// Get display range for line information
    fn get_display_range(&self, total_lines: usize, range: Option<LineRange>) -> (usize, usize) {
        match range {
            Some(r) => {
                let start = r.start.min(total_lines + 1);
                let end = r.end.map(|e| e.min(total_lines)).unwrap_or(total_lines);
                (start, end)
            }
            None => (1, total_lines),
        }
    }

    /// Add analysis capabilities based on file type
    fn add_text_analysis_capabilities(&self, output: &mut Vec<String>, file_category: &str) {
        output.push("AI Analysis Capabilities:".to_string());
        match file_category {
            "Source Code" => {
                output.push("- Code structure and syntax analysis".to_string());
                output.push("- Function and class identification".to_string());
                output.push("- Code quality and best practices review".to_string());
                output.push("- Bug detection and security analysis".to_string());
                output.push("- Documentation and comment analysis".to_string());
            }
            "Configuration" => {
                output.push("- Configuration structure analysis".to_string());
                output.push("- Setting validation and optimization".to_string());
                output.push("- Dependency and version management".to_string());
                output.push("- Security configuration review".to_string());
            }
            "Documentation" => {
                output.push("- Content structure and organization".to_string());
                output.push("- Writing quality and clarity analysis".to_string());
                output.push("- Link and reference validation".to_string());
                output.push("- Documentation completeness review".to_string());
            }
            _ => {
                output.push("- Content analysis and understanding".to_string());
                output.push("- Structure and format recognition".to_string());
                output.push("- Data extraction and processing".to_string());
                output.push("- Pattern recognition and insights".to_string());
            }
        }
        output.push(String::new());
    }

    /// Detect programming language from extension and content
    fn detect_programming_language(&self, extension: &str, content: &str) -> Option<String> {
        match extension {
            "rs" => Some("Rust".to_string()),
            "py" => Some("Python".to_string()),
            "js" => Some("JavaScript".to_string()),
            "ts" => Some("TypeScript".to_string()),
            "jsx" => Some("React JSX".to_string()),
            "tsx" => Some("React TSX".to_string()),
            "java" => Some("Java".to_string()),
            "c" => Some("C".to_string()),
            "cpp" | "cc" | "cxx" => Some("C++".to_string()),
            "h" | "hpp" => Some("C/C++ Header".to_string()),
            "go" => Some("Go".to_string()),
            "rb" => Some("Ruby".to_string()),
            "php" => Some("PHP".to_string()),
            "swift" => Some("Swift".to_string()),
            "kt" => Some("Kotlin".to_string()),
            "scala" => Some("Scala".to_string()),
            "sh" | "bash" | "zsh" => Some("Shell Script".to_string()),
            "sql" => Some("SQL".to_string()),
            "html" => Some("HTML".to_string()),
            "css" => Some("CSS".to_string()),
            "scss" | "sass" => Some("SCSS/Sass".to_string()),
            "xml" => Some("XML".to_string()),
            "json" => Some("JSON".to_string()),
            "yaml" | "yml" => Some("YAML".to_string()),
            "toml" => Some("TOML".to_string()),
            "md" => Some("Markdown".to_string()),
            _ => {
                // Try to detect from content
                if content.starts_with("#!/bin/bash") || content.starts_with("#!/bin/sh") {
                    Some("Shell Script".to_string())
                } else if content.starts_with("#!/usr/bin/env python") {
                    Some("Python".to_string())
                } else if content.starts_with("#!/usr/bin/env node") {
                    Some("JavaScript".to_string())
                } else {
                    None
                }
            }
        }
    }

    /// Categorize file type for analysis
    fn categorize_file_type(&self, extension: &str) -> String {
        match extension {
            "rs" | "py" | "js" | "ts" | "jsx" | "tsx" | "java" | "c" | "cpp" | "cc" | "cxx"
            | "h" | "hpp" | "go" | "rb" | "php" | "swift" | "kt" | "scala" | "sh" | "bash"
            | "zsh" | "sql" => "Source Code".to_string(),

            "json" | "yaml" | "yml" | "toml" | "xml" | "ini" | "cfg" | "conf" | "env" => {
                "Configuration".to_string()
            }

            "md" | "txt" | "rst" | "adoc" => "Documentation".to_string(),

            "html" | "css" | "scss" | "sass" | "less" => "Web Content".to_string(),

            "csv" | "tsv" | "log" => "Data File".to_string(),

            _ => "Text File".to_string(),
        }
    }

    /// Check if a file is likely a text file based on extension (enhanced version)
    pub fn is_text_file(path: &Path) -> bool {
        match path.extension().and_then(|e| e.to_str()) {
            Some(ext) => {
                let ext_lower = ext.to_lowercase();
                // If it's a known text extension, return true
                // If it's a known non-text extension (image, pdf, notebook, svg), return false
                // Otherwise, default to true (assume text)
                if TEXT_EXTENSIONS.contains(&ext_lower.as_str()) {
                    true
                } else if IMAGE_EXTENSIONS.contains(&ext_lower.as_str())
                    || ext_lower == "pdf"
                    || ext_lower == "ipynb"
                    || ext_lower == "svg"
                {
                    false
                } else {
                    true // Unknown extensions default to text
                }
            }
            None => true, // No extension defaults to text
        }
    }

    /// Check if a file is an SVG
    pub fn is_svg_file(path: &Path) -> bool {
        path.extension()
            .and_then(|e| e.to_str())
            .map(|e| e.to_lowercase() == "svg")
            .unwrap_or(false)
    }
}

// =============================================================================
// Unit Tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use std::io::Write;
    use tempfile::TempDir;

    fn create_test_context(dir: &Path) -> ToolContext {
        ToolContext::new(dir.to_path_buf())
            .with_session_id("test-session")
            .with_user("test-user")
    }

    fn create_read_tool() -> ReadTool {
        ReadTool::new(super::super::create_shared_history())
    }

    #[test]
    fn test_line_range_new() {
        let range = LineRange::new(5, Some(10));
        assert_eq!(range.start, 5);
        assert_eq!(range.end, Some(10));
    }

    #[test]
    fn test_line_range_from_start() {
        let range = LineRange::from_start(5);
        assert_eq!(range.start, 5);
        assert_eq!(range.end, None);
    }

    #[test]
    fn test_line_range_lines() {
        let range = LineRange::lines(5, 10);
        assert_eq!(range.start, 5);
        assert_eq!(range.end, Some(14));
    }

    #[test]
    fn test_is_image_file() {
        assert!(ReadTool::is_image_file(Path::new("test.png")));
        assert!(ReadTool::is_image_file(Path::new("test.jpg")));
        assert!(ReadTool::is_image_file(Path::new("test.JPEG")));
        assert!(ReadTool::is_image_file(Path::new("test.gif")));
        assert!(!ReadTool::is_image_file(Path::new("test.txt")));
        assert!(!ReadTool::is_image_file(Path::new("test.rs")));
    }

    #[test]
    fn test_is_pdf_file() {
        assert!(ReadTool::is_pdf_file(Path::new("test.pdf")));
        assert!(ReadTool::is_pdf_file(Path::new("test.PDF")));
        assert!(!ReadTool::is_pdf_file(Path::new("test.txt")));
    }

    #[test]
    fn test_is_notebook_file() {
        assert!(ReadTool::is_notebook_file(Path::new("test.ipynb")));
        assert!(ReadTool::is_notebook_file(Path::new("test.IPYNB")));
        assert!(!ReadTool::is_notebook_file(Path::new("test.py")));
    }

    #[test]
    fn test_is_text_file() {
        assert!(ReadTool::is_text_file(Path::new("test.txt")));
        assert!(ReadTool::is_text_file(Path::new("test.rs")));
        assert!(ReadTool::is_text_file(Path::new("test.py")));
        assert!(ReadTool::is_text_file(Path::new("test.json")));
        // Unknown extensions default to text
        assert!(ReadTool::is_text_file(Path::new("test.unknown")));
    }

    #[tokio::test]
    async fn test_read_text_file() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.txt");

        // Create test file
        let mut file = fs::File::create(&file_path).unwrap();
        writeln!(file, "Line 1").unwrap();
        writeln!(file, "Line 2").unwrap();
        writeln!(file, "Line 3").unwrap();

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());

        let result = tool.read_text(&file_path, None, &context).await.unwrap();

        assert!(result.contains("1 | Line 1"));
        assert!(result.contains("2 | Line 2"));
        assert!(result.contains("3 | Line 3"));

        // Check history was recorded
        assert!(tool.read_history.read().unwrap().has_read(&file_path));
    }

    #[tokio::test]
    async fn test_read_text_file_with_range() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.txt");

        // Create test file with 10 lines
        let mut file = fs::File::create(&file_path).unwrap();
        for i in 1..=10 {
            writeln!(file, "Line {}", i).unwrap();
        }

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());

        let range = LineRange::new(3, Some(5));
        let result = tool
            .read_text(&file_path, Some(range), &context)
            .await
            .unwrap();

        assert!(result.contains("3 | Line 3"));
        assert!(result.contains("4 | Line 4"));
        assert!(result.contains("5 | Line 5"));
        assert!(!result.contains("Line 1"));
        assert!(!result.contains("Line 6"));
    }

    #[tokio::test]
    async fn test_read_nonexistent_file() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("nonexistent.txt");

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());

        let result = tool.read_text(&file_path, None, &context).await;
        assert!(result.is_err());
    }

    #[tokio::test]
    async fn test_read_image_file() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.png");

        // Create a minimal PNG file (1x1 transparent pixel)
        let png_data: Vec<u8> = vec![
            0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
            0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, // IHDR chunk
            0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x06, 0x00, 0x00, 0x00, 0x1F,
            0x15, 0xC4, 0x89, 0x00, 0x00, 0x00, 0x0A, 0x49, 0x44, 0x41, // IDAT chunk
            0x54, 0x78, 0x9C, 0x63, 0x00, 0x01, 0x00, 0x00, 0x05, 0x00, 0x01, 0x0D, 0x0A, 0x2D,
            0xB4, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE, // IEND chunk
            0x42, 0x60, 0x82,
        ];
        fs::write(&file_path, &png_data).unwrap();

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());

        let result = tool.read_image(&file_path, &context).await.unwrap();

        // Updated assertion for enhanced image output format
        assert!(result.contains("[Enhanced Image Analysis:"));
        assert!(result.contains("Base64 Data: data:image/png;base64,"));
        assert!(tool.read_history.read().unwrap().has_read(&file_path));
    }

    #[tokio::test]
    async fn test_read_notebook_file() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.ipynb");

        // Create a minimal notebook
        let notebook = serde_json::json!({
            "cells": [
                {
                    "cell_type": "code",
                    "source": ["print('Hello')"],
                    "outputs": []
                },
                {
                    "cell_type": "markdown",
                    "source": ["# Title"]
                }
            ],
            "metadata": {},
            "nbformat": 4,
            "nbformat_minor": 2
        });
        fs::write(&file_path, serde_json::to_string(&notebook).unwrap()).unwrap();

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());

        let result = tool.read_notebook(&file_path, &context).await.unwrap();

        // Updated assertions for enhanced notebook output format
        assert!(result.contains("[Enhanced Notebook Analysis:"));
        assert!(result.contains("Cell 1 [Code Cell]"));
        assert!(result.contains("print('Hello')"));
        assert!(result.contains("Cell 2 [Markdown Cell]"));
        assert!(result.contains("# Title"));
    }

    #[tokio::test]
    async fn test_tool_execute_text() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.txt");
        fs::write(&file_path, "Hello, World!").unwrap();

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());
        let params = serde_json::json!({
            "path": file_path.to_str().unwrap()
        });

        let result = tool.execute(params, &context).await.unwrap();

        assert!(result.is_success());
        assert!(result.output.unwrap().contains("Hello, World!"));
        assert_eq!(
            result.metadata.get("file_type"),
            Some(&serde_json::json!("text"))
        );
    }

    #[tokio::test]
    async fn test_tool_execute_with_line_range() {
        let temp_dir = TempDir::new().unwrap();
        let file_path = temp_dir.path().join("test.txt");

        let mut file = fs::File::create(&file_path).unwrap();
        for i in 1..=10 {
            writeln!(file, "Line {}", i).unwrap();
        }

        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());
        let params = serde_json::json!({
            "path": file_path.to_str().unwrap(),
            "start_line": 2,
            "end_line": 4
        });

        let result = tool.execute(params, &context).await.unwrap();

        assert!(result.is_success());
        let output = result.output.unwrap();
        assert!(output.contains("Line 2"));
        assert!(output.contains("Line 3"));
        assert!(output.contains("Line 4"));
        assert!(!output.contains("Line 1"));
        assert!(!output.contains("Line 5"));
    }

    #[tokio::test]
    async fn test_tool_execute_missing_path() {
        let temp_dir = TempDir::new().unwrap();
        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());
        let params = serde_json::json!({});

        let result = tool.execute(params, &context).await;
        assert!(result.is_err());
        assert!(matches!(result.unwrap_err(), ToolError::InvalidParams(_)));
    }

    #[test]
    fn test_tool_name() {
        let tool = create_read_tool();
        assert_eq!(tool.name(), "read");
    }

    #[test]
    fn test_tool_description() {
        let tool = create_read_tool();
        assert!(!tool.description().is_empty());
        assert!(
            tool.description().contains("Enhanced") || tool.description().contains("multimodal")
        );
    }

    #[test]
    fn test_tool_input_schema() {
        let tool = create_read_tool();
        let schema = tool.input_schema();
        assert_eq!(schema["type"], "object");
        assert!(schema["properties"]["path"].is_object());
        assert!(schema["properties"]["start_line"].is_object());
        assert!(schema["properties"]["end_line"].is_object());
    }

    #[tokio::test]
    async fn test_check_permissions() {
        let temp_dir = TempDir::new().unwrap();
        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());
        let params = serde_json::json!({
            "path": "test.txt"
        });

        let result = tool.check_permissions(&params, &context).await;
        assert!(result.is_allowed());
    }

    #[tokio::test]
    async fn test_check_permissions_missing_path() {
        let temp_dir = TempDir::new().unwrap();
        let tool = create_read_tool();
        let context = create_test_context(temp_dir.path());
        let params = serde_json::json!({});

        let result = tool.check_permissions(&params, &context).await;
        assert!(result.is_denied());
    }
}