asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add Rustdoc comments for info and mcp modules and grep plugin

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 14:30:54 -03:00
parent 7ee8ef6ce6
commit f3a4894699
4 changed files with 207 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
src/modes/info.rs
View File

@@ -13,20 +13,32 @@ use comfy_table::{Cell, Attribute};
/// Displays detailed information about an item or the last item if no ID/tags specified.
///
/// Supports table, JSON, or YAML output formats.
/// Supports table, JSON, or YAML output formats. Validates input (at most one ID, no mixing IDs/tags).
/// Uses ItemService to fetch the item and displays via helpers.
///
/// # Arguments
///
/// * `cmd` - Mutable Clap command for error handling.
/// * `settings` - Application settings.
/// * `ids` - Mutable vector of item IDs (at most one).
/// * `cmd` - Mutable Clap command for error handling and exiting on invalid args.
/// * `settings` - Application settings for output formatting and human-readable sizes.
/// * `ids` - Mutable vector of item IDs (at most one; cleared if tags used).
/// * `tags` - Mutable vector of tags (mutually exclusive with IDs).
/// * `conn` - Mutable database connection.
/// * `data_path` - Path to data directory.
/// * `conn` - Mutable database connection for querying items.
/// * `data_path` - Path to data directory for file metadata.
///
/// # Returns
///
/// `Ok(())` on success, or Result with error.
/// `Ok(())` on success, or `Err(anyhow::Error)` if item not found or DB query fails.
///
/// # Errors
///
/// * Clap errors if invalid args (e.g., multiple IDs).
/// * Anyhow error if no matching item found.
///
/// # Examples
///
/// ```
/// mode_info(&mut cmd, &settings, &mut vec![123], &mut vec![], &mut conn, data_path)?;
/// ```
pub fn mode_info(
cmd: &mut Command,
settings: &config::Settings,
@@ -54,6 +66,22 @@ pub fn mode_info(
#[derive(Debug, Serialize, Deserialize)]
/// Structured representation of item information for JSON/YAML output.
///
/// This struct serializes item details including ID, timestamp, sizes, compression, tags, and metadata
/// for non-table output formats.
///
/// # Fields
///
/// * `id` - The unique item ID.
/// * `timestamp` - Formatted timestamp string.
/// * `path` - Full file path to the item.
/// * `stream_size` - Original uncompressed size in bytes (optional).
/// * `stream_size_formatted` - Human-readable stream size.
/// * `compression` - Compression type used.
/// * `file_size` - Compressed file size in bytes (optional).
/// * `file_size_formatted` - Human-readable file size.
/// * `tags` - List of associated tags.
/// * `meta` - Metadata key-value pairs.
pub struct ItemInfo {
id: i64,
timestamp: String,
@@ -67,22 +95,35 @@ pub struct ItemInfo {
meta: std::collections::HashMap<String, String>,
}
/// Displays item information in table format or delegates to structured output.
///
/// Builds a comfy-table for tabular display or calls structured helper for JSON/YAML.
/// Handles file size via metadata and formats tags/meta accordingly.
///
/// # Arguments
///
/// * `item_with_meta` - Item with associated metadata and tags.
/// * `settings` - Application settings for formatting (e.g., human-readable sizes).
/// * `data_path` - Path to data directory for calculating compressed file size.
///
/// # Returns
///
/// `Ok(())` on success, or `Err(anyhow::Error)` if path resolution fails.
///
/// # Errors
///
/// * Anyhow error if item path cannot be stringified.
///
/// # Examples
///
/// ```
/// show_item(item_with_meta, &settings, data_path)?;
/// ```
fn show_item(
item_with_meta: ItemWithMeta,
settings: &config::Settings,
data_path: PathBuf,
) -> Result<()> {
/// Displays item information in table format or delegates to structured output.
///
/// # Arguments
///
/// * `item_with_meta` - Item with associated metadata and tags.
/// * `settings` - Application settings for formatting.
/// * `data_path` - Path to data directory for file size calculation.
///
/// # Returns
///
/// `Ok(())` on success.
let output_format = crate::modes::common::settings_output_format(settings);
if output_format != OutputFormat::Table {
@@ -157,24 +198,37 @@ fn show_item(
Ok(())
}
/// Displays item information in structured JSON or YAML format.
///
/// Serializes ItemInfo and prints pretty-formatted output. Handles file metadata for sizes.
///
/// # Arguments
///
/// * `item_with_meta` - Item with metadata and tags.
/// * `settings` - Settings for size formatting (human-readable).
/// * `data_path` - Data path for compressed file size calculation.
/// * `output_format` - JSON or YAML (Table is unreachable here).
///
/// # Returns
///
/// `Ok(())` on success, or `Err(anyhow::Error)` if serialization or path fails.
///
/// # Errors
///
/// * Serde errors during JSON/YAML serialization.
/// * Anyhow error if file metadata unavailable.
///
/// # Examples
///
/// ```
/// show_item_structured(item_with_meta, &settings, data_path, OutputFormat::Json)?;
/// ```
fn show_item_structured(
item_with_meta: ItemWithMeta,
settings: &config::Settings,
data_path: PathBuf,
output_format: OutputFormat,
) -> Result<()> {
/// Displays item information in structured JSON or YAML format.
///
/// # Arguments
///
/// * `item_with_meta` - Item with metadata and tags.
/// * `settings` - Settings for size formatting.
/// * `data_path` - Data path for file size.
/// * `output_format` - JSON or YAML.
///
/// # Returns
///
/// `Ok(())` on success.
let item_tags: Vec<String> = item_with_meta.tags.iter().map(|t| t.name.clone()).collect();
let meta_map = item_with_meta.meta_as_map();
let item = item_with_meta.item;

71
src/modes/server/mcp/server.rs
View File

@@ -4,44 +4,61 @@ use serde_json::Value;
use crate::modes::server::common::AppState;
use super::tools::{KeepTools, ToolError};
#[derive(Clone)]
/// Server handler for MCP (Model Context Protocol) requests.
///
/// Routes requests to appropriate tools and handles responses.
/// Routes requests to appropriate tools and handles responses. Clones AppState for tool usage.
///
/// # Fields
///
/// * `state` - The shared application state (DB, config, etc.).
#[derive(Clone)]
pub struct KeepMcpServer {
state: AppState,
}
/// Creates a new `KeepMcpServer` instance.
///
/// # Arguments
///
/// * `state` - The application state containing DB, config, and services.
///
/// # Returns
///
/// A new `KeepMcpServer` instance.
///
/// # Examples
///
/// ```
/// let server = KeepMcpServer::new(app_state);
/// ```
impl KeepMcpServer {
/// Creates a new `KeepMcpServer` instance.
///
/// # Arguments
///
/// * `state` - The application state containing DB and config.
///
/// # Returns
///
/// A new `KeepMcpServer`.
pub fn new(state: AppState) -> Self {
Self { state }
}
/// Handles an MCP request by routing to the appropriate tool.
///
/// Supports methods like save_item, get_item, etc.
///
/// # Arguments
///
/// * `method` - The MCP method name.
/// * `params` - Optional JSON parameters.
///
/// # Returns
///
/// JSON string response on success, or ToolError.
///
/// # Errors
///
/// Returns ToolError::UnknownTool for unsupported methods.
/// Handles an MCP request by routing to the appropriate tool.
///
/// Supports methods like "save_item", "get_item", "list_items". Logs the request and delegates to KeepTools.
///
/// # Arguments
///
/// * `method` - The MCP method name (string).
/// * `params` - Optional JSON parameters as serde_json::Value.
///
/// # Returns
///
/// `Ok(String)` with JSON-serialized response on success, or `Err(ToolError)` on failure.
///
/// # Errors
///
/// * ToolError::UnknownTool if method unsupported.
/// * Propagates tool-specific errors (e.g., invalid args, DB failures).
///
/// # Examples
///
/// ```
/// let result = server.handle_request("save_item", Some(params)).await?;
/// ```
pub async fn handle_request(&self, method: &str, params: Option<Value>) -> Result<String, ToolError> {
debug!("MCP: Handling request '{}' with params: {:?}", method, params);