docs: update PLAN.md with file and function change details

Co-authored-by: aider (openai/andrew/openrouter/mistralai/mistral-medium-3.1) <aider@aider.chat>

PLAN.md

@@ -1,13 +1,22 @@
 # Refactoring Plan to Reduce Code Duplication
 
 ## 1. Create Core Service Layer with Clear Boundaries
-**Files:** `src/core/` (new directory)
-- `src/core/item_service.rs` - Main service for item operations (synchronous)
-- `src/core/async_item_service.rs` - Async wrapper for API use
-- `src/core/compression_service.rs` - Compression handling
-- `src/core/meta_service.rs` - Metadata processing
-- `src/core/mod.rs` - Module exports
-- `src/core/error.rs` - Unified error handling
+**Files:**
+- Add: `src/core/item_service.rs`
+- Add: `src/core/async_item_service.rs`
+- Add: `src/core/compression_service.rs`
+- Add: `src/core/meta_service.rs`
+- Add: `src/core/mod.rs`
+- Add: `src/core/error.rs`
+
+**Functions:**
+- Add: `get_item_full` in `item_service.rs`
+- Add: `save_item` in `item_service.rs`
+- Add: `list_items` in `item_service.rs`
+- Add: `delete_item` in `item_service.rs`
+- Add: `get_compressed_content` in `compression_service.rs`
+- Add: `process_metadata` in `meta_service.rs`
+- Add: Async wrappers for all core functions in `async_item_service.rs`
 
 **Reason:** Extract common business logic from modes and APIs into reusable services
 **Implementation:**
@@ -35,6 +44,16 @@
   ```
 
 ## 2. Thread Safety and Resource Management
+**Files:**
+- Change: `src/modes/server/api/item.rs`
+- Change: `src/modes/server/api/status.rs`
+- Change: `src/modes/server/mcp/tools.rs`
+
+**Functions:**
+- Add: `get_item_async` in `async_item_service.rs`
+- Add: `save_item_async` in `async_item_service.rs`
+- Change: All API handlers to use async services
+
 **Reason:** Ensure services can be safely used in both synchronous and asynchronous contexts
 **Implementation:**
 - Document thread-safety guarantees for all core services
@@ -57,7 +76,14 @@
 - Benchmark thread pool sizes for CPU-bound tasks (e.g., compression)
 
 ## 3. Create Common Data Structures
-**Files:** `src/core/types.rs`
+**Files:**
+- Add: `src/core/types.rs`
+
+**Functions:**
+- Add: `From<db::Item>` for `ItemWithMeta`
+- Add: `From<ItemWithMeta>` for `ItemInfo` (API response)
+- Add: Serialization/deserialization implementations
+
 **Reason:** Standardize data structures used across modes and APIs
 **Implementation:**
 - Define structs for `Item`, `ItemWithContent`, `ItemWithMeta`, `Response<T>`
@@ -67,6 +93,19 @@
 - Use zero-copy patterns where possible (slicing instead of copying)
 
 ## 4. Unified Error Handling with Conversions
+**Files:**
+- Add: `src/core/error.rs`
+- Change: `src/modes/server/api/item.rs`
+- Change: `src/modes/server/mcp/tools.rs`
+- Change: All mode files (`get.rs`, `save.rs`, etc.)
+
+**Functions:**
+- Add: `CoreError` enum with comprehensive variants
+- Add: `From<CoreError>` for `StatusCode`
+- Add: `From<CoreError>` for `ToolError`
+- Add: `From<CoreError>` for `anyhow::Error`
+- Change: All error handling to use `CoreError`
+
 **Reason:** Standardize error types across CLI, API, and MCP interfaces
 **Implementation:**
 - Define a base error enum (`CoreError`) with conversions to all interface-specific error types
@@ -96,13 +135,22 @@
 
 ## 5. Refactor CLI Modes to Use Services
 **Files:**
-- `src/modes/get.rs`
-- `src/modes/save.rs`
-- `src/modes/list.rs`
-- `src/modes/info.rs`
-- `src/modes/delete.rs`
-- `src/modes/diff.rs`
-- `src/modes/status.rs`
+- Change: `src/modes/get.rs`
+- Change: `src/modes/save.rs`
+- Change: `src/modes/list.rs`
+- Change: `src/modes/info.rs`
+- Change: `src/modes/delete.rs`
+- Change: `src/modes/diff.rs`
+- Change: `src/modes/status.rs`
+
+**Functions:**
+- Change: `mode_get` to use `item_service::get_item_full`
+- Change: `mode_save` to use `item_service::save_item`
+- Change: `mode_list` to use `item_service::list_items`
+- Change: `mode_info` to use `item_service::get_item_full`
+- Change: `mode_delete` to use `item_service::delete_item`
+- Change: `mode_diff` to use `item_service::get_item_full` for both items
+- Change: `mode_status` to use new status service functions
 
 **Reason:** Remove direct database and file system access from modes
 **Implementation:**
@@ -114,8 +162,17 @@
 
 ## 6. Refactor REST API to Use Async Services
 **Files:**
-- `src/modes/server/api/item.rs`
-- `src/modes/server/api/status.rs`
+- Change: `src/modes/server/api/item.rs`
+- Change: `src/modes/server/api/status.rs`
+
+**Functions:**
+- Change: `handle_get_item` to use `async_item_service::get_item_async`
+- Change: `handle_get_item_latest` to use `async_item_service::get_item_async`
+- Change: `handle_list_items` to use `async_item_service::list_items_async`
+- Change: `handle_post_item` to use `async_item_service::save_item_async`
+- Change: `handle_get_item_content` to use `async_item_service::get_item_content_async`
+- Change: `handle_get_item_meta` to use `async_item_service::get_item_meta_async`
+- Change: `handle_status` to use `async_item_service::get_status_async`
 
 **Reason:** Remove business logic from HTTP handlers
 **Implementation:**
@@ -125,7 +182,15 @@
 - Wrap synchronous service calls in `tokio::task::spawn_blocking`
 
 ## 7. Refactor MCP Tools to Use Services
-**Files:** `src/modes/server/mcp/tools.rs`
+**Files:**
+- Change: `src/modes/server/mcp/tools.rs`
+
+**Functions:**
+- Change: `save_item` to use `item_service::save_item`
+- Change: `get_item` to use `item_service::get_item_full`
+- Change: `get_latest_item` to use `item_service::get_latest_item`
+- Change: `list_items` to use `item_service::list_items`
+- Change: `search_items` to use `item_service::search_items`
 
 **Reason:** Remove duplication with REST API and CLI modes
 **Implementation:**
@@ -135,7 +200,15 @@
 - Standardize response format to match API/CLI
 
 ## 8. Create Common Error Handling
-**Files:** `src/core/error.rs`
+**Files:**
+- Add: `src/core/error.rs`
+- Change: All files that handle errors
+
+**Functions:**
+- Add: Comprehensive error handling in `core/error.rs`
+- Add: Conversion traits for all error types
+- Change: All error handling to use new error system
+
 **Reason:** Standardize error types across the application
 **Implementation:**
 - Define comprehensive error enum with conversions:
@@ -151,7 +224,16 @@
 - Include error codes for programmatic handling
 
 ## 9. Update Database Layer for Batch Operations
-**Files:** `src/db.rs`
+**Files:**
+- Change: `src/db.rs`
+
+**Functions:**
+- Add: `get_items_with_meta_batch`
+- Add: `get_items_with_tags_batch`
+- Add: `insert_item_with_meta_transaction`
+- Add: `delete_item_with_meta_transaction`
+- Change: Optimize existing queries for batch operations
+
 **Reason:** Support efficient batch operations needed by services
 **Implementation:**
 - Add functions to get multiple items with their metadata and tags
@@ -161,7 +243,18 @@
 - Ensure all batch operations are properly documented
 
 ## 10. Add Integration Tests
-**Files:** `tests/integration/` (new directory)
+**Files:**
+- Add: `tests/integration/core_tests.rs`
+- Add: `tests/integration/cli_tests.rs`
+- Add: `tests/integration/api_tests.rs`
+- Add: `tests/integration/performance_tests.rs`
+
+**Functions:**
+- Add: Test cases for all core service functions
+- Add: Test cases for CLI modes
+- Add: Test cases for API endpoints
+- Add: Performance benchmarks
+
 **Reason:** Ensure refactored code maintains functionality and performance
 **Implementation:**
 - Test core services independently
@@ -172,6 +265,16 @@
 - Test both sync and async service implementations
 
 ## 11. Performance Optimization Guidelines
+**Files:**
+- Change: All core service files
+- Change: All mode files
+- Change: All API handler files
+
+**Functions:**
+- Add: Streaming implementations for I/O operations
+- Add: Benchmark functions for critical paths
+- Change: Buffer management to minimize copies
+
 **Reason:** Ensure the refactored version doesn't slow down pipelines
 **Implementation:**
 - Use streaming for stdin/stdout processing (chunked I/O)
@@ -179,7 +282,7 @@
 - Offload CPU-bound work (compression, plugins) to thread pools
 - Provide fast-path options (e.g., `--fast` flag to skip metadata plugins)
 - Benchmark critical operations before/after refactoring
-- Document performance characteristics
+- Document performance characteristics and tradeoffs
 
 ## Implementation Order:
 1. Create core module structure and error types (`core/error.rs`, `core/types.rs`)