Database changes:
- schema.sql: Update column name bookmann_uuid → bookhoard_uuid
- schema.sql: Update index names and example URLs
- queries.sql: Update all SQL queries to use bookhoard_uuid
- Update example configuration values
Part of project rename to Bookhoard.
Documentation updates:
- All docs/ files: Update project references
- Bruno API collection: Update collection name and tests
- Device setup guides: Update all examples
- Implementation plan: Update database schema examples
- README files: Update project references
Part of project rename to Bookhoard.
Test file updates:
- Update import paths in test files: bookmann/internal → bookhoard/internal
- Update test helper functions and references
- Update test comments and documentation
This is part 6 of the project rename to Bookhoard.
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.
john-okeefe