From a5992fdb386156cb1c7f209f23954e3f8ea786ce Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Sun, 24 Aug 2025 23:45:43 -0300 Subject: [PATCH] docs: update PLAN.md with file and function change details Co-authored-by: aider (openai/andrew/openrouter/mistralai/mistral-medium-3.1) --- PLAN.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 125 insertions(+), 22 deletions(-) diff --git a/PLAN.md b/PLAN.md index 518b5e9..fc338e1 100644 --- a/PLAN.md +++ b/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` for `ItemWithMeta` +- Add: `From` 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` @@ -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` for `StatusCode` +- Add: `From` for `ToolError` +- Add: `From` 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`)