v1.1.0-beta.033 - feat(metadata/profile): add Mylar-spec series.json, activity heatmap, KOReader sync, and refactor PDF/bytes
Implement Mylar-spec series.json metadata generation, introduce a GitHub-style activity heatmap tracking per-day issue reading detail with KOReader integration, drop unsupported PDF smart-matching, and unify system-wide byte formatting.
📚 Mylar-Spec series.json Metadata
- Replace the Komga-API-shaped series.json payload with the industry-standard Mylar v1.0.2 schema consumed by Komga, Kavita, and Mylar.
- Source comicid strictly from the ComicVine volume ID (Metron-sourced series write null to prevent ID leaking).
- Derive publication_run dynamically from the earliest and latest issue release dates (e.g., March 1999 - December 2001 or - Present).
- Ensure HTML is stripped from description_text and description_formatted, defaulting untracked fields to schema-valid nulls and booktype to Print.
🔥 Activity Heatmap & Analytics
- Introduce a new DailyIssueRead database table to record daily granular reading history (user, issue, date, pages read), managed automatically via Prisma migrations on container start.
- Update /api/user/analytics to return heatmapDetails per date, seamlessly backfilling legacy data from ReadProgress.updatedAt.
- Rebuild the frontend profile heatmap as a GitHub-style week-aligned grid complete with month/weekday labels, color legend, and current/best streak badges.
- Add a responsive detail panel that opens on-click to show covers, series names, issue numbers, and pages read, linking back to their respective series pages.
📖 KOReader Integration & Syncing
- Update the KOReader sync route to convert percentage advances into page increments using the issue's real pageCount (falling back to percentage points if missing).
- Isolate stats recording so failure cannot break progress synchronization, and protect against backwards/stale device syncs.
- Centralize execution paths using a shared recordDailyReading helper to ensure web reader and KOReader behaviors remain identical.
- recordDailyReading swallows and logs stats failures so heatmap bookkeeping can never break a progress save (web reader or KOReader)
📄 PDF & Filesystem Refactoring
- Remove the unsupported .pdf exception from smart match—PDFs previously created unreadable library entries lacking scanner, cover, reader, or OPDS support, and will now remain cleanly in UNMATCHED.
- Unify file size presentation by introducing formatBytes() in utils/format.ts, replacing three divergent local copies.
- Fix a bug where interactive search displayed 0 MB for releases under 1 MB, ensuring consistent storage text across the storage page and search modals.
🗜️ CB7 Comic Archive Support
- Accept .cb7 in convertCbrToCbz, relying on unar's native 7z extraction fallback path.
- Wire up .cb7 files for conversion during watched-folder ingest, post-import, and smart-match.
- Update the CBR Auto-Converter job's library query to include .cb7/.CB7.
- Handle .cb7 gracefully in the Reader by showing the waiting to be converted message instead of failing out.
📦 File-Format Centralization & Drift Fixes
- Create src/lib/utils/formats.ts as the single source of truth for comic and image extensions.
- Replace 17 scattered extension lists and regexes across 14 files to fix system-wide behavior drift:
- Library scanner now ingests .rar, .cb7, and .epub (previously restricted to cbz/cbr/zip).
- Diagnostics deep-scan now audits all six supported formats.
- Ghost-series cleanup no longer accidentally deletes folders containing only .rar/.epub files.
- Reader and OPDS can now display preserved GIF/BMP pages; importer page counts now include .bmp.
- Smart-match now properly accepts and queues .rar files instead of silently skipping them.
- Explicitly separated intentionally narrow lists (Hoster link-detection/cover picker) and appended PDF exceptions with intent comments.
📁 Filesystem Paths Centralization & Drift Fixes
- Create src/lib/utils/paths.ts to act as the single source of truth for all system paths (CONFIG_DIR, CACHE_DIR, LOGS_DIR, BACKUPS_DIR, WATCHED_DIR, UNMATCHED_DIR).
- Replace 16 inline process.env fallbacks scattered across 14 files with these new shared constants.
- Standardize system fallbacks to fix critical data-retention drift:
- Logs fallback moved from the ephemeral container path (/app/config/logs) to the persistent volume (/config/logs), ensuring consistency across logger, download, and reporting routes.
- Backups fallback standardized to /config/backups (was /backups).
- Fixed a missed repackArchive cache-path edit in converter.ts.
- Add environment validation to ensure watched and unmatched directories exist and are writable, logging proactive warnings to prevent silent data loss in the container's ephemeral layer.
🧰 Utility Deduplication & Code Cleanup
- Centralized shared helpers into single-source utility modules, removing 12+ redundant copies:
- utils/defaults.ts: Consolidates release-scoring defaults for the engine and settings UI.
- utils/search-terms.ts: Unifies stop words and keywords for download providers.
- utils/xml.ts: Shares escapeXml between OPDS feeds and ComicInfo writing.
- utils/safe-parse.ts: Centralizes JSON array parsing for library API routes.
- utils/sanitize.ts: Shares sanitizeFilename to ensure imports and renames build identical paths.
- metadata/providers/metron-cover.ts: Deduplicates the Metron fallback cover lookup.
✅ Verification
- Pass clean compilation via tsc clean.
- All 173/173 tests passing via vitest across 58 files, including new tests for Mylar series.json edge cases, daily progress tracking hooks, and KOReader delta math.
Addresses #163