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

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

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/mistralai/mistral-medium-3.1) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-08-24 23:45:43 -03:00
parent 19e1ae587f
commit a5992fdb38
1 changed files with 125 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
PLAN.md
View File

@@ -1,13 +1,22 @@
# Refactoring Plan to Reduce Code Duplication # Refactoring Plan to Reduce Code Duplication
## 1. Create Core Service Layer with Clear Boundaries ## 1. Create Core Service Layer with Clear Boundaries
**Files:** `src/core/` (new directory) **Files:**
- `src/core/item_service.rs` - Main service for item operations (synchronous) - Add: `src/core/item_service.rs`
- `src/core/async_item_service.rs` - Async wrapper for API use - Add: `src/core/async_item_service.rs`
- `src/core/compression_service.rs` - Compression handling - Add: `src/core/compression_service.rs`
- `src/core/meta_service.rs` - Metadata processing - Add: `src/core/meta_service.rs`
- `src/core/mod.rs` - Module exports - Add: `src/core/mod.rs`
- `src/core/error.rs` - Unified error handling - 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 **Reason:** Extract common business logic from modes and APIs into reusable services
**Implementation:** **Implementation:**
@@ -35,6 +44,16 @@
``` ```
## 2. Thread Safety and Resource Management ## 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 **Reason:** Ensure services can be safely used in both synchronous and asynchronous contexts
**Implementation:** **Implementation:**
- Document thread-safety guarantees for all core services - Document thread-safety guarantees for all core services
@@ -57,7 +76,14 @@
- Benchmark thread pool sizes for CPU-bound tasks (e.g., compression) - Benchmark thread pool sizes for CPU-bound tasks (e.g., compression)
## 3. Create Common Data Structures ## 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 **Reason:** Standardize data structures used across modes and APIs
**Implementation:** **Implementation:**
- Define structs for `Item`, `ItemWithContent`, `ItemWithMeta`, `Response<T>` - Define structs for `Item`, `ItemWithContent`, `ItemWithMeta`, `Response<T>`
@@ -67,6 +93,19 @@
- Use zero-copy patterns where possible (slicing instead of copying) - Use zero-copy patterns where possible (slicing instead of copying)
## 4. Unified Error Handling with Conversions ## 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 **Reason:** Standardize error types across CLI, API, and MCP interfaces
**Implementation:** **Implementation:**
- Define a base error enum (`CoreError`) with conversions to all interface-specific error types - 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 ## 5. Refactor CLI Modes to Use Services
**Files:** **Files:**
- `src/modes/get.rs` - Change: `src/modes/get.rs`
- `src/modes/save.rs` - Change: `src/modes/save.rs`
- `src/modes/list.rs` - Change: `src/modes/list.rs`
- `src/modes/info.rs` - Change: `src/modes/info.rs`
- `src/modes/delete.rs` - Change: `src/modes/delete.rs`
- `src/modes/diff.rs` - Change: `src/modes/diff.rs`
- `src/modes/status.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 **Reason:** Remove direct database and file system access from modes
**Implementation:** **Implementation:**
@@ -114,8 +162,17 @@
## 6. Refactor REST API to Use Async Services ## 6. Refactor REST API to Use Async Services
**Files:** **Files:**
- `src/modes/server/api/item.rs` - Change: `src/modes/server/api/item.rs`
- `src/modes/server/api/status.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 **Reason:** Remove business logic from HTTP handlers
**Implementation:** **Implementation:**
@@ -125,7 +182,15 @@
- Wrap synchronous service calls in `tokio::task::spawn_blocking` - Wrap synchronous service calls in `tokio::task::spawn_blocking`
## 7. Refactor MCP Tools to Use Services ## 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 **Reason:** Remove duplication with REST API and CLI modes
**Implementation:** **Implementation:**
@@ -135,7 +200,15 @@
- Standardize response format to match API/CLI - Standardize response format to match API/CLI
## 8. Create Common Error Handling ## 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 **Reason:** Standardize error types across the application
**Implementation:** **Implementation:**
- Define comprehensive error enum with conversions: - Define comprehensive error enum with conversions:
@@ -151,7 +224,16 @@
- Include error codes for programmatic handling - Include error codes for programmatic handling
## 9. Update Database Layer for Batch Operations ## 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 **Reason:** Support efficient batch operations needed by services
**Implementation:** **Implementation:**
- Add functions to get multiple items with their metadata and tags - Add functions to get multiple items with their metadata and tags
@@ -161,7 +243,18 @@
- Ensure all batch operations are properly documented - Ensure all batch operations are properly documented
## 10. Add Integration Tests ## 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 **Reason:** Ensure refactored code maintains functionality and performance
**Implementation:** **Implementation:**
- Test core services independently - Test core services independently
@@ -172,6 +265,16 @@
- Test both sync and async service implementations - Test both sync and async service implementations
## 11. Performance Optimization Guidelines ## 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 **Reason:** Ensure the refactored version doesn't slow down pipelines
**Implementation:** **Implementation:**
- Use streaming for stdin/stdout processing (chunked I/O) - Use streaming for stdin/stdout processing (chunked I/O)
@@ -179,7 +282,7 @@
- Offload CPU-bound work (compression, plugins) to thread pools - Offload CPU-bound work (compression, plugins) to thread pools
- Provide fast-path options (e.g., `--fast` flag to skip metadata plugins) - Provide fast-path options (e.g., `--fast` flag to skip metadata plugins)
- Benchmark critical operations before/after refactoring - Benchmark critical operations before/after refactoring
- Document performance characteristics - Document performance characteristics and tradeoffs
## Implementation Order: ## Implementation Order:
1. Create core module structure and error types (`core/error.rs`, `core/types.rs`) 1. Create core module structure and error types (`core/error.rs`, `core/types.rs`)