@ebowwa/large-output 1.1.0 → 1.2.0

package/rust/src/lib.rs

@@ -0,0 +1,596 @@
+//! # large-output
+//!
+//! Shared utility for handling large outputs with automatic file fallback
+//! and actionable LLM prompts.
+//!
+//! When output size exceeds the threshold, automatically writes to a temp file
+//! and returns a structured response with file path and preview.
+//!
+//! ## Example
+//!
+//! ```rust
+//! use large_output::{handle_output, handle_mcp_output, OutputResponse};
+//!
+//! // Basic usage
+//! let content = "very large content...".repeat(1000);
+//! let response = handle_output(&content, None);
+//!
+//! match response {
+//!     OutputResponse::Inline { content, .. } => println!("{}", content),
+//!     OutputResponse::File { path, size, .. } => {
+//!         println!("Written {} bytes to {:?}", size, path);
+//!     }
+//! }
+//!
+//! // MCP convenience function
+//! let mcp_text = handle_mcp_output(&content, None);
+//! println!("{}", mcp_text);
+//! ```
+
+use chrono::Local;
+use serde::{Deserialize, Serialize};
+use std::fs;
+use std::path::PathBuf;
+use uuid::Uuid;
+
+/// Configuration options for the output handler
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LargeOutputOptions {
+    /// Character threshold for file fallback
+    /// Default: 15000 (safety margin under Claude's ~20K limit)
+    #[serde(default = "default_threshold")]
+    pub threshold: usize,
+
+    /// Number of characters to include in preview when writing to file
+    /// Default: 500
+    #[serde(default = "default_preview_length")]
+    pub preview_length: usize,
+
+    /// Custom temp directory for output files
+    /// Default: OS temp directory
+    pub temp_dir: Option<PathBuf>,
+
+    /// Custom filename prefix
+    /// Default: "mcp_output"
+    #[serde(default = "default_filename_prefix")]
+    pub filename_prefix: String,
+
+    /// Whether to include a size indicator in the response
+    /// Default: true
+    #[serde(default = "default_true")]
+    pub include_size: bool,
+
+    /// Whether to include a preview in the file response
+    /// Default: true
+    #[serde(default = "default_true")]
+    pub include_preview: bool,
+
+    /// Response format for file outputs
+    /// - "actionable" (default): Returns actionable text prompting LLM to read the file
+    /// - "json": Returns structured JSON object
+    #[serde(default = "default_response_format")]
+    pub response_format: ResponseFormat,
+}
+
+fn default_threshold() -> usize { 15000 }
+fn default_preview_length() -> usize { 500 }
+fn default_filename_prefix() -> String { "mcp_output".to_string() }
+fn default_true() -> bool { true }
+fn default_response_format() -> ResponseFormat { ResponseFormat::Actionable }
+
+impl Default for LargeOutputOptions {
+    fn default() -> Self {
+        Self {
+            threshold: default_threshold(),
+            preview_length: default_preview_length(),
+            temp_dir: None,
+            filename_prefix: default_filename_prefix(),
+            include_size: default_true(),
+            include_preview: default_true(),
+            response_format: default_response_format(),
+        }
+    }
+}
+
+/// Response format for file outputs
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum ResponseFormat {
+    /// Returns actionable text prompting LLM to read the file
+    Actionable,
+    /// Returns structured JSON object
+    Json,
+}
+
+impl Default for ResponseFormat {
+    fn default() -> Self {
+        Self::Actionable
+    }
+}
+
+/// Response when output is returned inline (under threshold)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct InlineResponse {
+    #[serde(rename = "type")]
+    pub response_type: String,
+    pub content: String,
+}
+
+/// Response when output is written to file (over threshold)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FileResponse {
+    #[serde(rename = "type")]
+    pub response_type: String,
+    pub path: PathBuf,
+    pub size: usize,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub size_formatted: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub preview: Option<String>,
+}
+
+/// Union type for all possible responses
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(untagged)]
+pub enum OutputResponse {
+    Inline {
+        #[serde(rename = "type")]
+        response_type: String,
+        content: String,
+    },
+    File {
+        #[serde(rename = "type")]
+        response_type: String,
+        path: PathBuf,
+        size: usize,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        size_formatted: Option<String>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        preview: Option<String>,
+    },
+}
+
+impl OutputResponse {
+    /// Check if response is inline
+    pub fn is_inline(&self) -> bool {
+        matches!(self, OutputResponse::Inline { .. })
+    }
+
+    /// Check if response is file
+    pub fn is_file(&self) -> bool {
+        matches!(self, OutputResponse::File { .. })
+    }
+
+    /// Get the content if inline
+    pub fn content(&self) -> Option<&str> {
+        match self {
+            OutputResponse::Inline { content, .. } => Some(content),
+            _ => None,
+        }
+    }
+
+    /// Get the file path if file
+    pub fn path(&self) -> Option<&PathBuf> {
+        match self {
+            OutputResponse::File { path, .. } => Some(path),
+            _ => None,
+        }
+    }
+}
+
+/// Format bytes to human-readable string
+fn format_size(bytes: usize) -> String {
+    if bytes < 1024 {
+        format!("{} B", bytes)
+    } else if bytes < 1024 * 1024 {
+        format!("{:.1} KB", bytes as f64 / 1024.0)
+    } else {
+        format!("{:.1} MB", bytes as f64 / (1024.0 * 1024.0))
+    }
+}
+
+/// Generate a unique filename with timestamp
+fn generate_filename(prefix: &str) -> String {
+    let timestamp = Local::now().format("%Y-%m-%dT%H-%M-%S");
+    let random: String = Uuid::new_v4()
+        .to_string()
+        .split('-')
+        .next()
+        .unwrap_or("unknown")
+        .to_string();
+    format!("{}_{}_{}.txt", prefix, timestamp, random)
+}
+
+/// Ensure directory exists, create if not
+fn ensure_dir(dir: &PathBuf) -> std::io::Result<()> {
+    if !dir.exists() {
+        fs::create_dir_all(dir)?;
+    }
+    Ok(())
+}
+
+/// Handle output with automatic file fallback
+///
+/// # Arguments
+///
+/// * `content` - The content to return
+/// * `options` - Configuration options (None for defaults)
+///
+/// # Returns
+///
+/// `OutputResponse` with inline content or file reference
+///
+/// # Example
+///
+/// ```rust
+/// use large_output::{handle_output, OutputResponse};
+///
+/// let content = "very large content...".repeat(1000);
+/// let response = handle_output(&content, None);
+///
+/// match response {
+///     OutputResponse::Inline { content, .. } => println!("{}", content),
+///     OutputResponse::File { path, size, .. } => {
+///         println!("Written {} bytes to {:?}", size, path);
+///     }
+/// }
+/// ```
+pub fn handle_output(content: &str, options: Option<LargeOutputOptions>) -> OutputResponse {
+    let opts = options.unwrap_or_default();
+    let content_length = content.len();
+
+    // Return inline if under threshold
+    if content_length <= opts.threshold {
+        return OutputResponse::Inline {
+            response_type: "inline".to_string(),
+            content: content.to_string(),
+        };
+    }
+
+    // Write to file if over threshold
+    let temp_dir = opts.temp_dir.unwrap_or_else(std::env::temp_dir);
+    let filename_prefix = if opts.filename_prefix.is_empty() {
+        "mcp_output".to_string()
+    } else {
+        opts.filename_prefix
+    };
+
+    // Ensure temp directory exists
+    if let Err(e) = ensure_dir(&temp_dir) {
+        eprintln!("Warning: Could not create temp directory: {}", e);
+    }
+
+    let filename = generate_filename(&filename_prefix);
+    let filepath = temp_dir.join(&filename);
+
+    // Write file
+    if let Err(e) = fs::write(&filepath, content) {
+        eprintln!("Warning: Could not write to file: {}", e);
+    }
+
+    let size_formatted = if opts.include_size {
+        Some(format_size(content_length))
+    } else {
+        None
+    };
+
+    let preview = if opts.include_preview {
+        let preview = if content_length > opts.preview_length {
+            format!("{}...", &content[..opts.preview_length])
+        } else {
+            content.to_string()
+        };
+        Some(preview)
+    } else {
+        None
+    };
+
+    OutputResponse::File {
+        response_type: "file".to_string(),
+        path: filepath,
+        size: content_length,
+        size_formatted,
+        preview,
+    }
+}
+
+/// Convert an OutputResponse to a string for MCP tool return
+///
+/// # Arguments
+///
+/// * `response` - The response from handle_output()
+/// * `format` - Response format: "actionable" (default) or "json"
+///
+/// # Returns
+///
+/// Text or JSON string suitable for MCP tool return value
+///
+/// # Example
+///
+/// ```rust
+/// use large_output::{handle_output, to_mcp_response, ResponseFormat};
+///
+/// let response = handle_output("content", None);
+/// let text = to_mcp_response(&response, ResponseFormat::Actionable);
+/// println!("{}", text);
+/// ```
+pub fn to_mcp_response(response: &OutputResponse, format: ResponseFormat) -> String {
+    match response {
+        OutputResponse::Inline { content, .. } => content.clone(),
+
+        OutputResponse::File {
+            path,
+            size,
+            size_formatted,
+            preview,
+            ..
+        } => {
+            // JSON format for programmatic consumers
+            if format == ResponseFormat::Json {
+                let mut result = serde_json::Map::new();
+                result.insert("type".to_string(), serde_json::json!("file"));
+                result.insert("path".to_string(), serde_json::json!(path.to_string_lossy()));
+                result.insert("size".to_string(), serde_json::json!(size));
+
+                if let Some(sf) = size_formatted {
+                    result.insert("sizeFormatted".to_string(), serde_json::json!(sf));
+                }
+
+                if let Some(p) = preview {
+                    result.insert("preview".to_string(), serde_json::json!(p));
+                }
+
+                return serde_json::to_string_pretty(&result).unwrap_or_default();
+            }
+
+            // Actionable format - prompts LLM to read the file (DEFAULT)
+            let size_display = size_formatted
+                .clone()
+                .unwrap_or_else(|| format_size(*size));
+
+            let mut lines = vec![
+                format!("Large output ({}) saved to file.", size_display),
+                String::new(),
+                "ACTION REQUIRED: Use the Read tool to read this file:".to_string(),
+                String::new(),
+                format!("   {}", path.to_string_lossy()),
+                String::new(),
+            ];
+
+            if let Some(p) = preview {
+                lines.push("--- PREVIEW (first 500 chars) ---".to_string());
+                lines.push(p.clone());
+                lines.push("--- END PREVIEW ---".to_string());
+                lines.push(String::new());
+            }
+
+            lines.push("File contains the complete data. Read it to proceed.".to_string());
+
+            lines.join("\n")
+        }
+    }
+}
+
+/// Convenience function: handle output and return MCP-formatted string
+///
+/// # Arguments
+///
+/// * `content` - The content to return
+/// * `options` - Configuration options (including response_format)
+///
+/// # Returns
+///
+/// Text string with actionable instructions (default) or JSON
+///
+/// # Example
+///
+/// ```rust
+/// use large_output::handle_mcp_output;
+///
+/// let content = "very large content...".repeat(1000);
+/// let text = handle_mcp_output(&content, None);
+/// println!("{}", text);
+/// ```
+pub fn handle_mcp_output(content: &str, options: Option<LargeOutputOptions>) -> String {
+    let opts = options.clone().unwrap_or_default();
+    let response = handle_output(content, options);
+    to_mcp_response(&response, opts.response_format)
+}
+
+/// Batch handler for multiple outputs
+///
+/// # Arguments
+///
+/// * `contents` - Slice of content strings
+/// * `options` - Configuration options (applied to all)
+///
+/// # Returns
+///
+/// Vector of OutputResponse
+///
+/// # Example
+///
+/// ```rust
+/// use large_output::handle_batch;
+///
+/// let contents = vec!["data1", "data2", "data3"];
+/// let outputs = handle_batch(&contents, None);
+/// for output in outputs {
+///     println!("{:?}", output);
+/// }
+/// ```
+pub fn handle_batch(contents: &[&str], options: Option<LargeOutputOptions>) -> Vec<OutputResponse> {
+    contents
+        .iter()
+        .map(|content| handle_output(content, options.clone()))
+        .collect()
+}
+
+/// Builder for LargeOutputOptions
+///
+/// # Example
+///
+/// ```rust
+/// use large_output::OptionsBuilder;
+///
+/// let options = OptionsBuilder::new()
+///     .threshold(20000)
+///     .preview_length(1000)
+///     .filename_prefix("github_search")
+///     .build();
+/// ```
+#[derive(Debug, Clone, Default)]
+pub struct OptionsBuilder {
+    options: LargeOutputOptions,
+}
+
+impl OptionsBuilder {
+    /// Create a new OptionsBuilder with defaults
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Set character threshold for file fallback
+    pub fn threshold(mut self, threshold: usize) -> Self {
+        self.options.threshold = threshold;
+        self
+    }
+
+    /// Set number of characters to include in preview
+    pub fn preview_length(mut self, length: usize) -> Self {
+        self.options.preview_length = length;
+        self
+    }
+
+    /// Set custom temp directory
+    pub fn temp_dir(mut self, dir: PathBuf) -> Self {
+        self.options.temp_dir = Some(dir);
+        self
+    }
+
+    /// Set filename prefix
+    pub fn filename_prefix(mut self, prefix: impl Into<String>) -> Self {
+        self.options.filename_prefix = prefix.into();
+        self
+    }
+
+    /// Set whether to include size in response
+    pub fn include_size(mut self, include: bool) -> Self {
+        self.options.include_size = include;
+        self
+    }
+
+    /// Set whether to include preview in response
+    pub fn include_preview(mut self, include: bool) -> Self {
+        self.options.include_preview = include;
+        self
+    }
+
+    /// Set response format
+    pub fn response_format(mut self, format: ResponseFormat) -> Self {
+        self.options.response_format = format;
+        self
+    }
+
+    /// Build the options
+    pub fn build(self) -> LargeOutputOptions {
+        self.options
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_inline_output() {
+        let content = "small content";
+        let response = handle_output(content, None);
+        assert!(response.is_inline());
+        assert_eq!(response.content(), Some(content));
+    }
+
+    #[test]
+    fn test_file_output() {
+        let content = "x".repeat(20000);
+        let response = handle_output(&content, None);
+        assert!(response.is_file());
+
+        if let OutputResponse::File { path, size, .. } = response {
+            assert_eq!(size, 20000);
+            assert!(path.exists());
+            let file_content = fs::read_to_string(&path).unwrap();
+            assert_eq!(file_content, content);
+            // Cleanup
+            let _ = fs::remove_file(&path);
+        }
+    }
+
+    #[test]
+    fn test_format_size() {
+        assert_eq!(format_size(500), "500 B");
+        assert_eq!(format_size(1024), "1.0 KB");
+        assert_eq!(format_size(1536), "1.5 KB");
+        assert_eq!(format_size(1048576), "1.0 MB");
+    }
+
+    #[test]
+    fn test_options_builder() {
+        let options = OptionsBuilder::new()
+            .threshold(20000)
+            .preview_length(1000)
+            .filename_prefix("test")
+            .response_format(ResponseFormat::Json)
+            .build();
+
+        assert_eq!(options.threshold, 20000);
+        assert_eq!(options.preview_length, 1000);
+        assert_eq!(options.filename_prefix, "test");
+        assert_eq!(options.response_format, ResponseFormat::Json);
+    }
+
+    #[test]
+    fn test_to_mcp_response_actionable() {
+        let content = "x".repeat(20000);
+        let response = handle_output(&content, None);
+        let text = to_mcp_response(&response, ResponseFormat::Actionable);
+
+        assert!(text.contains("Large output"));
+        assert!(text.contains("ACTION REQUIRED"));
+        assert!(text.contains("Read tool"));
+    }
+
+    #[test]
+    fn test_to_mcp_response_json() {
+        let content = "x".repeat(20000);
+        let response = handle_output(&content, None);
+        let text = to_mcp_response(&response, ResponseFormat::Json);
+
+        assert!(text.contains("\"type\": \"file\""));
+        assert!(text.contains("\"size\": 20000"));
+
+        // Cleanup
+        if let OutputResponse::File { path, .. } = response {
+            let _ = fs::remove_file(&path);
+        }
+    }
+
+    #[test]
+    fn test_handle_batch() {
+        let large = "x".repeat(20000);
+        let contents: Vec<&str> = vec!["small", &large, "tiny"];
+        let responses = handle_batch(&contents, None);
+
+        assert_eq!(responses.len(), 3);
+        assert!(responses[0].is_inline());
+        assert!(responses[1].is_file());
+        assert!(responses[2].is_inline());
+
+        // Cleanup
+        for response in responses {
+            if let OutputResponse::File { path, .. } = response {
+                let _ = fs::remove_file(&path);
+            }
+        }
+    }
+}