docs: add refactoring plan to reduce code duplication

Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>

PLAN.md

@@ -1 +1,97 @@
 
+# Refactoring Plan to Reduce Code Duplication
+
+## 1. Create Core Service Layer
+**Files:** `src/core/` (new directory)
+- `src/core/item_service.rs` - Main service for item operations
+- `src/core/compression_service.rs` - Compression handling
+- `src/core/meta_service.rs` - Metadata processing
+- `src/core/mod.rs` - Module exports
+
+**Reason:** Extract common business logic from modes and APIs into reusable services
+**Implementation:** 
+- Move logic from modes (get, save, list, info) and API handlers into service functions
+- Services should return structured data, not format output
+- Handle compression, metadata, and database operations
+
+## 2. Create Common Data Structures
+**Files:** `src/core/types.rs`
+**Reason:** Standardize data structures used across modes and APIs
+**Implementation:**
+- Define structs for Item, ItemContent, ItemWithMeta, etc.
+- Include conversion functions from database types
+- Add serialization/deserialization support
+
+## 3. 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`
+
+**Reason:** Remove direct database and file system access from modes
+**Implementation:**
+- Replace current implementations with calls to core services
+- Keep only CLI-specific formatting and output logic
+- Handle command-line argument parsing and validation
+
+## 4. Refactor REST API to Use Services
+**Files:**
+- `src/modes/server/api/item.rs`
+- `src/modes/server/api/status.rs`
+
+**Reason:** Remove business logic from HTTP handlers
+**Implementation:**
+- Convert handlers to call core services
+- Keep only HTTP-specific code (status codes, headers, etc.)
+- Use common error handling
+
+## 5. Refactor MCP Tools to Use Services
+**Files:**
+- `src/modes/server/mcp/tools.rs`
+
+**Reason:** Remove duplication with REST API and CLI modes
+**Implementation:**
+- Replace current implementation with calls to core services
+- Keep only MCP protocol-specific logic
+
+## 6. Create Common Error Handling
+**Files:** `src/core/error.rs`
+**Reason:** Standardize error types across the application
+**Implementation:**
+- Define comprehensive error enum with conversions
+- Implement proper error formatting for different outputs (CLI, JSON, HTTP)
+
+## 7. Update Database Layer for Batch Operations
+**Files:** `src/db.rs`
+**Reason:** Support efficient batch operations needed by services
+**Implementation:**
+- Add functions to get multiple items with their metadata and tags
+- Optimize queries for common access patterns
+
+## 8. Add Integration Tests
+**Files:** `tests/integration/` (new directory)
+**Reason:** Ensure refactored code maintains functionality
+**Implementation:**
+- Test core services independently
+- Test CLI modes and APIs through their public interfaces
+- Verify compression, metadata, and database operations
+
+## Implementation Order:
+1. Create core module structure and error types
+2. Implement core services with basic functionality
+3. Refactor one mode (e.g., get) to use services
+4. Refactor corresponding API endpoints
+5. Repeat for other modes and APIs
+6. Add comprehensive tests
+7. Clean up removed code from original files
+
+## Benefits:
+- Reduced code duplication
+- Easier maintenance
+- Consistent behavior across interfaces
+- Better testability
+- Clear separation of concerns