Documentation updates:
- Update README.md title and all references
- Update PROJECT_GUIDELINES.md title and guidelines
- Update all documentation files in docs/ directory
- Update device setup guides (Kobo, KOReader)
- Update API and architecture documentation
- Update completion summaries and progress reports
This is part 5 of the project rename to Bookhoard.
Bruno API test updates:
- Update test assertions: X-Bookmann-* → X-Bookhoard-*
- Update variable names and references in test scripts
- Update documentation and comments in API tests
This is part 4 of the project rename to Bookhoard.
Template changes:
- Update page titles: "Bookmann" → "Bookhoard"
- Update header branding and navigation text
- Regenerate compiled .go templates from .templ sources
- Update all UI references in HTML templates
This is part 3 of the project rename to Bookhoard.
Added 110 lines of safety guidelines to prevent future bugs:
New CRITICAL PROHIBITIONS:
- NEVER delete code without reading full context (20 lines before/after)
- NEVER make cascading fix-up edits without git diff review
- NEVER skip post-edit verification
New MANDATORY REQUIREMENTS:
- Post-Edit Verification (mandatory for all file modifications)
- Backup Before Large Changes
- Large Deletion Safety Pattern
New ERROR RECOVERY PROTOCOL:
- Immediate actions when mistakes occur
- Recovery examples with git commands
- Prevention learning points
New WORKFLOW CHECKLISTS:
- Error Recovery Protocol
- Phase Completion Verification
These guidelines address the critical bug where auth functions were
accidentally deleted during cleanup, preventing recurrence.
Added comprehensive documentation of Phases 1-3:
- Phase 1: Documentation cleanup details
- Phase 2: Dead code removal summary
- Phase 3: Test suite cleanup details
- Complete statistics and verification results
This document serves as a record of the legacy code cleanup
work completed in this session.
New test file with 5 test suites:
- TestMediaItemISBNNormalization (8 test cases)
- TestMediaItemISBNEdgeCases (3 test cases)
- TestMediaItemsPagination (5 test cases)
- TestMediaItemLibraryRequirement (2 test cases)
- TestUpdateMediaItemISBN (1 test case)
Features:
- Tests use /api/media-items endpoint (not deprecated /api/ebooks)
- Real API calls (not mock handlers)
- Comprehensive ISBN-10/ISBN-13 normalization coverage
- Pagination validation with limit/offset edge cases
- Library requirement validation
This replaces the functionality lost from isbn_and_library_test.go
with modern, working tests using current API endpoints.
Phase 3: Test Suite Cleanup - Replacement Tests
- Deleted isbn_and_library_test.go (507 lines)
- All tests used deprecated /api/ebooks endpoint
- Tests were mock-based, not real API calls
- Functionality will be replaced with modern tests
This is part of legacy code cleanup Phase 3.
Phase 3: Test Suite Cleanup
- Removed TestPaginationAndFiltering function
- Deleted 4 test cases using deprecated /api/ebooks endpoint
- Tests for pagination already exist in library_test.go using /api/media-items
This is part of legacy code cleanup Phase 3.
Phase 3: Test Suite Cleanup
- Removed comment about 'Ebook notes handlers (backward compatibility using views)'
- Removed comment references to non-existent GetEbookNotes and GetEbookHighlights
- Cleaned up misleading legacy documentation
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Removed comment about user_ebook_folders table replacement
- Removed comment about library system transition
- Historical migration documentation removed
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Removed 'Ebook Compatibility (Backward Compatible)' section
- Removed 'Backward Compatibility Views' from database docs
- Removed backward compatibility bullet point from Database Schema section
- Cleaned up legacy API references from README
This is part of legacy code cleanup Phase 1.
Phase 1: Documentation Cleanup
- Analytics API endpoints (reading stats, device usage, popular books)
- Bulk operations for conflicts, books, and collections
- Book matching and auto-linking endpoints
- Unlinked book management
- OPDS on-the-fly conversion
- Request/response examples for all endpoints
- Authentication requirements and error handling
Sync-Kobo:
- Auto link books endpoint tests
- Bulk link books endpoint tests
- Get unlinked book suggestions endpoint tests
OPDS:
- Download book with on-the-fly KEPUB conversion tests
All tests cover no user, user, and admin contexts
- Display paginated list of unresolved unlinked books
- Show match suggestions with confidence scores
- Bulk linking interface
- Auto-link with configurable threshold
- Device and file metadata display
- Integrate conversion service with OPDS handler
- Convert EPUB to KEPUB format on download request
- Cache converted files to reduce processing time
- Support per-device catalog with format availability
- Maintain backward compatibility with existing downloads
- BulkLinkBooks: manually link multiple unlinked books to media items
- AutoLinkBooks: automatically link books above confidence threshold
- GetUnlinkedBookSuggestions: get match suggestions for specific unlinked book
- Support batch operations with individual result tracking
- Configurable confidence thresholds and limits
- Add reading stats endpoint with daily/monthly history
- Add device usage statistics (sync count, time spent)
- Add popular books view with completion rates
- Server-side rendered analytics page with HTMX
- Date range filtering for reading history
Add analytics queries:
- GetUserReadingHistory: detailed reading history with device info
- GetUserDeviceUsage: device usage statistics (sync count, time spent)
- GetPopularBooks: most read books with completion rates
Add book matching queries:
- GetUnlinkedBookByID: fetch single unlinked book
- DeleteUnlinkedBook: remove resolved unlinked book
- ListUnresolvedUnlinkedBooks: paginated list of unresolved books
- Install kepubify binary in Dockerfile for on-the-fly conversion
- Add conversion service with caching layer (24hr TTL)
- Support KEPUB downloads through OPDS endpoint
- Cache converted files to reduce processing overhead
- Add environment configuration for cache directory and tool path
This plan implements the remaining features from the original implementation plan:
- Phase 1: File Conversion Pipeline (EPUB→KEPUB with dual hash storage)
- Phase 2: Advanced Unlinked Book Resolution (bulk operations)
- Phase 3: Conflict Resolution UI & API
- Phase 4: Analytics & Reporting Dashboard
- Phase 5: Bulk Operations API
- Phase 6: WebSocket Real-time Updates
Each phase is atomic, independently testable, and includes:
- Complete implementation code
- Database queries
- Frontend templates
- Bruno API tests
- Unit tests
The plan is designed to be implemented by any AI with knowledge of
Go, Echo framework, PostgreSQL, and HTMX.
Remove exception for htmx.min.js so all compiled JavaScript in
web/static/ is ignored and generated during Docker build.
The Dockerfile already handles downloading HTMX via:
- npm postinstall script
- Downloads from unpkg.com during container build
This keeps the repository clean and lets the container build
process generate all static assets consistently.
Add extensive unit tests for collection rule matching logic:
Test Coverage (30+ tests):
1. Rule Evaluation Tests:
- Equals operator (match and no match)
- Not equals operator (match and no match)
- Contains operator (case-insensitive)
- Not contains operator
- Starts with operator
- Ends with operator
- Greater than operator (numeric)
- Less than operator (numeric)
- NULL field handling
2. Comparison Function Tests:
- Case-insensitive string matching
- Empty string edge cases
- Numeric edge cases (0, negative, large numbers)
- Type conversion validation
3. Multi-Rule Tests:
- Matches first rule
- Matches second rule (first fails)
- No matches across all rules
- Empty rules array
4. Complex Rule Scenarios:
- Multiple conditions on same book
- Different field types (genre, author, year, series)
- Various operators tested
- Table-driven test for 8 scenarios
5. Edge Cases and Error Handling:
- Invalid operator returns false
- Non-existent field returns false
- Invalid numeric strings handled
- Type conversion failures
Test Structure:
- Clear test names explaining what's being tested
- Assertion messages explain expected vs actual
- Uses testify/assert for better error messages
- Table-driven tests for multiple scenarios
- Comprehensive edge case coverage
Code Coverage:
- evaluateRule() function
- compareValues() function
- checkRulesAgainstBook() function
- All operators: equals, not_equals, contains, not_contains,
starts_with, ends_with, greater_than, less_than
- All field types: genre, author, series, copyright_year
Test Results:
- All 30+ tests passing
- Coverage of critical collection rule logic
- Prevents regressions in rule matching
- Validates edge case handling
This test suite ensures the collection auto-assignment
feature works correctly for all supported rule types and operators.
Add comprehensive Bruno tests for Phase 9 limitations features:
Test Collection Rules.bru:
- Test rule: genre equals "Science Fiction"
- Test rule: author contains "Asimov"
- Test rule: copyright_year greater than 2000
- Test rule: non-existent genre (expects 0 matches)
- Test validation: empty rules array (expects 400)
Bulk Remove Books.bru:
- Setup: Create test collection
- Add multiple books to collection
- Test 1: Bulk remove all books
- Test 2: Bulk remove with some invalid IDs
- Test 3: Empty list validation
- Test 4: Single book removal (bulk should work for 1 too)
- Cleanup: Delete test collection
Test Coverage:
- Rule evaluation API endpoint
- Bulk remove API endpoint
- Request validation
- Response structure verification
- Edge cases and error handling
Bruno Test Format:
- JSON request bodies
- Status code assertions
- Response structure validation
- Setup/teardown for integration tests
These tests ensure the new Phase 9 API endpoints work correctly
and maintain backward compatibility.
Update both Kobo and KOReader setup guides with OPDS workflow:
KOBO_SETUP.md Updates:
- New OPDS Wireless Book Delivery section
- Step-by-step OPDS configuration (automatic and manual)
- Browse and download books from Bookmann catalog
- Collection-based downloads
- Format support (EPUB, KEPUB, PDF)
- Automatic EPUB to KEPUB conversion
- Progress sync integration
- Collection to shelf mapping
- Troubleshooting section for OPDS issues
- OPDS vs USB transfer comparison table
- Advanced OPDS configuration options
KOREADER_SETUP.md Updates:
- OPDS catalog addition in KOReader
- Browse entire library wirelessly
- Download books and collections
- Automatic book matching
- Collection integration
- KOReader-specific OPDS settings
- Auto-download features
- Comprehensive troubleshooting
- OPDS tips and tricks
- Comparison table (OPDS vs USB)
Key Features Documented:
- Wireless book delivery (no USB cable needed)
- On-demand library browsing
- Collection-based organization
- Automatic progress sync for downloaded books
- Format conversion and optimization
- Device-specific configuration
Both guides now provide complete instructions for:
1. Setting up OPDS catalog on device
2. Browsing and downloading books
3. Troubleshooting common OPDS issues
4. Comparing wireless vs USB transfer methods
5. Advanced configuration options
This completes the OPDS documentation requirement for Phase 10.
Document the completion of all 5 Phase 9 limitations:
- Rule Testing Preview (Limitation #1)
- Bulk Operations (Limitation #2)
- Collection-Specific Search (Limitation #3)
- Real-time Collection Updates (Limitation #4)
- Bulk Remove (Limitation #5)
Includes:
- Implementation details for each limitation
- API endpoints and WebSocket events
- Code statistics and git commits
- User experience improvements
- Quality assurance status
- Deployment information
- Next steps and future enhancements
All 5 limitations are now COMPLETE and production-ready.
Implement real-time collection updates when books are added/removed:
Backend Changes:
- Added connManager to CollectionHandler struct
- Updated constructor to accept ConnectionManager
- Updated all NewCollectionHandler() calls in ebook.go and main.go
- Added WebSocket broadcasts in AddBooks() handler
- Added WebSocket broadcasts in BulkRemoveBooks() handler
- Broadcasts collection_updated events with:
- collection_id: Which collection changed
- action: books_added or books_removed
- book_ids: Array of affected book IDs
- count: Number of books changed
Frontend Changes:
- Added WebSocket connection in collections UI
- connectWebSocket() establishes connection to /ws/sync
- Listens for collection_updated events
- Shows toast notification on collection change
- Auto-reloads page after 1 second to show updated book list
- Auto-reconnect on disconnect (5s delay)
- Error handling for WebSocket failures
WebSocket Event Format:
{
"type": "collection_updated",
"timestamp": "2026-02-01T12:00:00Z",
"data": {
"collection_id": "uuid",
"action": "books_added",
"book_ids": ["uuid1", "uuid2"],
"count": 2
}
}
User Experience:
- When another user adds books to a collection, all connected clients see:
1. Toast notification: "Collection updated: books_added (2 books)"
2. Page auto-refreshes after 1 second
3. Updated book list displays
- Same for book removal
- Works across multiple browser tabs/devices
- No manual refresh needed
Technical Notes:
- Broadcasts to ALL connected WebSocket clients
- Client-side filtering by collection_id
- Existing progress/conflict broadcasts continue to work
- Connection manager handles broadcast distribution
Resolves Limitation #4: Real-time Collection Updates
Add search and filter within a collection:
Frontend Implementation:
- Search input box in collection detail toolbar
- filterCollectionBooks() JavaScript function
- Real-time filtering of books by title and author
- Case-insensitive search
- Hides non-matching book cards
- Shows all books when search is cleared
How It Works:
- AllBooks array contains book data from server render
- On keyup, filters books by title and author
- Toggles display property on book cards
- Empty state has ID and is not hidden
- Pure client-side filtering (no server round-trips)
User Experience:
- Instant search results as user types
- No page reload required
- Works with existing multi-select for bulk operations
- Search box always visible in toolbar
Resolves Limitation #3: Collection-Specific Search
Complete bulk operations for collections management:
BULK ADD BOOKS:
- Implemented searchBooks() with real API integration
- Multi-select checkboxes for book selection
- SelectedBooks Set tracks chosen books
- AddSelectedBooks() sends array to existing endpoint
- Uses existing POST /api/collections/:id/books endpoint
BULK REMOVE BOOKS:
- New endpoint: POST /api/collections/:id/books/bulk-remove
- Checkboxes on each book card for selection
- BooksToRemove Set tracks selections
- Live counter showing selected count
- BulkRemoveBooks() handler removes all in one API call
- More efficient than N individual DELETE requests
Frontend Changes:
- Selected counter badge shows number selected
- Bulk remove button (enabled when books selected)
- Checkboxes on all books for multi-select
- Confirmation dialog for bulk operations
- Toast notifications with counts
Backend Changes:
- BulkRemoveBooks() handler in collections.go
- Accepts book_ids array, returns removed/total counts
- Iterates and removes, counting successes
- Route: POST /api/collections/:id/books/bulk-remove
API Request:
{
"book_ids": ["uuid1", "uuid2", "uuid3"]
}
API Response:
{
"removed": 3,
"total": 3
}
Tests Added:
- TestCompareValues_* (existing)
- TestEvaluateRule_* (existing)
Resolves Limitations #2 (Bulk Operations) and #5 (Bulk Remove)
john-okeefe