shoko 0.1.0

data/lib/shoko/adapters/storage/json_cache_store/resources.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Resource persistence helpers for `JsonCacheStore`.
+    class JsonCacheStore
+      private
+
+      def resources_dir(sha)
+        File.join(@cache_root, 'resources', normalize_sha!(sha))
+      end
+
+      def resource_blob_path(sha, blob_key)
+        File.join(resources_dir(sha), "#{blob_key}.bin")
+      end
+
+      def hydrate_resources(sha, index_rows)
+        Array(index_rows).filter_map { |row| hydrate_resource_row(sha, row) }
+      end
+
+      def hydrate_resource_row(sha, row)
+        path, blob_key = resource_index_row_fields(row)
+        path_string = path.to_s
+        blob_key_string = blob_key.to_s
+        return nil if path_string.empty? || blob_key_string.empty?
+
+        data = File.binread(resource_blob_path(sha, blob_key_string))
+        data.force_encoding(Encoding::BINARY)
+        { path: path_string, data: data }
+      rescue StandardError
+        nil
+      end
+
+      def resource_index_row_fields(row)
+        return [nil, nil] unless row.is_a?(Hash)
+
+        [row['path'] || row[:path], row['blob'] || row[:blob]]
+      end
+
+      def persist_resources(sha, resources_rows)
+        resources_rows = Array(resources_rows)
+        return [[], 0] if resources_rows.empty?
+
+        FileUtils.mkdir_p(resources_dir(sha))
+
+        rows = []
+        total_bytes = 0
+        resources_rows.each do |row|
+          persisted = persist_resource_row(sha, row)
+          next unless persisted
+
+          rows << persisted[:index_row]
+          total_bytes += persisted[:bytesize]
+        end
+
+        [rows, total_bytes]
+      end
+
+      def persist_resource_row(sha, row)
+        path, data = resource_row_fields(row)
+        path_string = path.to_s
+        return nil if path_string.empty?
+
+        bytes = String(data).dup
+        bytes.force_encoding(Encoding::BINARY)
+        blob_key = Digest::SHA256.hexdigest(path_string)
+
+        AtomicFileWriter.write(resource_blob_path(sha, blob_key), bytes, binary: true)
+
+        bytesize = bytes.bytesize
+        {
+          bytesize: bytesize,
+          index_row: { 'path' => path_string, 'blob' => blob_key, 'bytesize' => bytesize },
+        }
+      end
+
+      def resource_row_fields(row)
+        return [nil, nil] unless row.is_a?(Hash)
+
+        [row[:path] || row['path'], row[:data] || row['data']]
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/json_cache_store.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+require 'securerandom'
+
+require_relative 'atomic_file_writer'
+require_relative 'cache_paths'
+require_relative '../monitoring/logger.rb'
+require_relative '../book_sources/source_fingerprint.rb'
+
+module Shoko
+  module Adapters::Storage
+    # JSON-backed cache store for EPUB payloads + layouts.
+    #
+    # This store persists only primitive JSON data and keeps binary resources
+    # as separate blobs on disk (referenced from the JSON payload).
+    class JsonCacheStore
+      ENGINE = 'json'
+      FORMAT = 'shoko-cache-payload'
+      FORMAT_VERSION = 2
+
+      # Raw payload read from disk (metadata + chapter/resource indexes + layouts).
+      Payload = Struct.new(:metadata_row, :chapters, :resources, :layouts, keyword_init: true)
+
+      MANIFEST_FILENAME = 'cache_manifest.json'
+
+      SHA256_HEX_PATTERN = /\A[0-9a-f]{64}\z/i
+
+      MAX_LAYOUT_KEY_BYTES = 200
+      LAYOUT_KEY_PATTERN = /\A[a-zA-Z0-9][a-zA-Z0-9._-]*\z/
+
+      CHAPTERS_DIRNAME = 'chapters'
+      CHAPTERS_RAW_DIRNAME = 'raw'
+      CHAPTERS_GENERATION_BYTES = 8
+      CHAPTERS_GENERATION_PATTERN = /\A[0-9a-f]{16}\z/i
+      CHAPTER_FILENAME_DIGITS = 6
+      MAX_CHAPTER_COUNT = 20_000
+
+      def initialize(cache_root: CachePaths.cache_root)
+        @cache_root = cache_root
+        FileUtils.mkdir_p(@cache_root)
+      end
+
+      def engine
+        ENGINE
+      end
+
+      def fetch_payload(sha, include_resources: false)
+        data = load_payload_data(sha)
+        return nil unless data
+
+        Payload.new(
+          metadata_row: data.fetch('metadata_row', {}),
+          chapters: data.fetch('chapters', []),
+          resources: include_resources ? hydrate_resources(sha, data.fetch('resources', [])) : [],
+          layouts: fetch_layouts(sha)
+        )
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: fetch failed', sha: sha.to_s, error: e.message)
+        nil
+      end
+
+      def write_payload(sha:, source_path:, source_mtime:, generated_at:, serialized_book:, serialized_chapters:,
+                        serialized_resources:, serialized_layouts:)
+        normalized_sha = normalize_sha!(sha)
+
+        metadata_row = build_metadata_row(serialized_book, normalized_sha, source_path:, source_mtime:, generated_at:)
+        chapters_index, chapter_generation, chapter_bytes = persist_chapters(normalized_sha, serialized_chapters)
+        resources_index, resource_bytes = persist_resources(normalized_sha, serialized_resources)
+        size_bytes = chapter_bytes.to_i + resource_bytes.to_i
+        indexes = { chapters: chapters_index, resources: resources_index }
+        payload = payload_hash(metadata_row, chapter_generation, indexes)
+        write_payload_file(normalized_sha, payload)
+        post_write_housekeeping(normalized_sha, metadata_row, chapter_generation, size_bytes, serialized_layouts:)
+        true
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: write failed', sha: sha.to_s, error: e.message)
+        cleanup_failed_chapter_generation(normalized_sha, chapter_generation) if normalized_sha && chapter_generation
+        false
+      end
+
+      def load_layout(sha, key)
+        file = layout_file(sha, key)
+        return nil unless File.file?(file)
+
+        JSON.parse(File.read(file))
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: layout load failed', sha: sha.to_s, key: key.to_s, error: e.message)
+        nil
+      end
+
+      def fetch_layouts(sha)
+        dir = layouts_dir(sha)
+        return {} unless Dir.exist?(dir)
+
+        Dir.children(dir).each_with_object({}) do |entry, layouts|
+          key = layout_key_for_entry(entry)
+          next unless key
+
+          payload = read_layout_payload(dir, entry, sha: sha, key: key)
+          layouts[key] = payload if payload
+        end
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: layouts fetch failed', sha: sha.to_s, error: e.message)
+        {}
+      end
+
+      def chapters_complete?(sha, generation, expected_count:)
+        normalized_sha = normalize_sha!(sha)
+        gen = normalize_chapter_generation(generation)
+        count = normalize_expected_chapter_count(expected_count)
+        return false unless gen && count
+        return true if count.zero?
+
+        chapter_files_complete?(normalized_sha, gen, count)
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: chapters completeness check failed',
+                     sha: sha.to_s, generation: generation.to_s, expected: expected_count.to_i,
+                     error: e.message)
+        false
+      end
+
+      def mutate_layouts(sha)
+        layouts = fetch_layouts(sha)
+        yield layouts
+        write_layouts(sha, layouts)
+        true
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: mutate layouts failed', sha: sha.to_s, error: e.message)
+        false
+      end
+
+      def delete_payload(sha)
+        normalized_sha = normalize_sha!(sha)
+        FileUtils.rm_f(payload_path(normalized_sha))
+        FileUtils.rm_rf(layouts_dir(normalized_sha))
+        FileUtils.rm_rf(resources_dir(normalized_sha))
+        FileUtils.rm_rf(chapters_dir(normalized_sha))
+        remove_from_manifest(normalized_sha)
+        true
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: delete failed', sha: sha.to_s, error: e.message)
+        false
+      end
+
+      def list_books
+        self.class.manifest_rows(@cache_root)
+      rescue StandardError
+        []
+      end
+
+      def self.manifest_rows(cache_root)
+        read_manifest_file(File.join(cache_root, MANIFEST_FILENAME))
+      rescue StandardError
+        []
+      end
+    end
+  end
+end
+
+require_relative 'json_cache_store/payload_helpers'
+require_relative 'json_cache_store/chapters'
+require_relative 'json_cache_store/layouts'
+require_relative 'json_cache_store/resources'
+require_relative 'json_cache_store/manifest'

data/lib/shoko/adapters/storage/lazy_file_string.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative '../../shared/errors.rb'
+
+module Shoko
+  module Adapters::Storage
+    # Lazily reads a file into a String on first use.
+    #
+    # Used to avoid loading large chapter XHTML payloads until they are needed.
+    # Optionally sanitizes the loaded content before memoizing it.
+    class LazyFileString
+      def initialize(path, sanitizer: nil, encoding: Encoding::UTF_8)
+        @path = path.to_s
+        @sanitizer = sanitizer
+        @encoding = encoding
+        @loaded = nil
+      end
+
+      attr_reader :path
+
+      def to_s
+        load_string
+      end
+
+      def to_str
+        load_string
+      end
+
+      def inspect
+        "#<#{self.class.name} path=#{path.inspect} loaded=#{!@loaded.nil?}>"
+      end
+
+      def method_missing(name, *, &)
+        value = load_string
+        return super unless value.respond_to?(name)
+
+        value.public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        ''.respond_to?(name, include_private) || super
+      end
+
+      private
+
+      def load_string
+        return @loaded if @loaded
+
+        bytes = File.binread(path)
+        bytes.force_encoding(@encoding)
+        text = @sanitizer ? @sanitizer.call(bytes) : bytes
+        text = text.to_s
+        unless text.encoding == Encoding::UTF_8
+          text = text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace,
+                                              replace: "\uFFFD")
+        end
+        @loaded = text
+      rescue Shoko::Error
+        raise
+      rescue StandardError => e
+        raise Shoko::CacheLoadError.new(path, e.message)
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/pagination_cache.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'epub_cache'
+require_relative '../monitoring/perf_tracer.rb'
+
+module Shoko
+  module Adapters::Storage
+    # Persists dynamic pagination layouts inside the on-disk cache for a book.
+    module PaginationCache
+      module_function
+
+      SCHEMA_VERSION = 3
+
+      def layout_key(width, height, view_mode, line_spacing, kitty_images: false)
+        suffix = kitty_images ? 'img1' : 'img0'
+        "#{width}x#{height}_#{view_mode}_#{line_spacing}_#{suffix}"
+      end
+
+      def parse_layout_key(key)
+        return nil unless key
+
+        dims, view_mode, line_spacing, image_mode = key.to_s.split('_', 4)
+        width_str, height_str = dims.to_s.split('x', 2)
+        return nil unless width_str && height_str && view_mode && line_spacing
+
+        {
+          width: width_str.to_i,
+          height: height_str.to_i,
+          view_mode: view_mode.to_sym,
+          line_spacing: line_spacing.to_sym,
+          kitty_images: image_mode.to_s == 'img1',
+        }
+      rescue StandardError
+        nil
+      end
+
+      def load_for_document(doc, key)
+        cache = cache_for(doc)
+        return nil unless cache
+
+        data = Adapters::Monitoring::PerfTracer.measure('cache.lookup') { cache.load_layout(key) }
+        extract_pages(data)
+      rescue StandardError
+        nil
+      end
+
+      def save_for_document(doc, key, pages_compact)
+        cache = cache_for(doc)
+        return false unless cache
+
+        payload = {
+          'version' => SCHEMA_VERSION,
+          'pages' => pages_compact,
+        }
+        cache.mutate_layouts! { |layouts| layouts[key] = payload }
+      end
+
+      def delete_for_document(doc, key)
+        cache = cache_for(doc)
+        return false unless cache
+
+        cache.mutate_layouts! { |layouts| layouts.delete(key) }
+      end
+
+      def exists_for_document?(doc, key)
+        cache = cache_for(doc)
+        return false unless cache
+
+        !!cache.load_layout(key)
+      rescue StandardError
+        false
+      end
+
+      def layout_keys_for_document(doc)
+        cache = cache_for(doc)
+        return [] unless cache
+
+        cache.layout_keys
+      rescue StandardError
+        []
+      end
+
+      def extract_pages(data)
+        return nil unless data.is_a?(Hash)
+
+        version = data['version'] || data[:version]
+        pages = data['pages'] || data[:pages]
+        return nil unless pages.is_a?(Array)
+        return nil if version && version.to_i != SCHEMA_VERSION
+
+        pages.map do |entry|
+          {
+            chapter_index: entry[:chapter_index] || entry['chapter_index'],
+            page_in_chapter: entry[:page_in_chapter] || entry['page_in_chapter'],
+            total_pages_in_chapter: entry[:total_pages_in_chapter] || entry['total_pages_in_chapter'],
+            start_line: entry[:start_line] || entry['start_line'],
+            end_line: entry[:end_line] || entry['end_line'],
+          }
+        end
+      end
+
+      def cache_for(doc)
+        path = resolve_cache_path(doc)
+        return nil unless path && File.exist?(path)
+
+        Shoko::Adapters::Storage::EpubCache.new(path)
+      rescue Shoko::Error, StandardError
+        nil
+      end
+      private_class_method :cache_for
+
+      def resolve_cache_path(doc)
+        return doc.cache_path if doc.respond_to?(:cache_path) && doc.cache_path && !doc.cache_path.to_s.empty?
+
+        if doc.respond_to?(:canonical_path) && doc.canonical_path && File.exist?(doc.canonical_path)
+          cache = Shoko::Adapters::Storage::EpubCache.new(doc.canonical_path)
+          return cache.cache_path if File.exist?(cache.cache_path)
+        end
+
+        nil
+      rescue Shoko::Error, StandardError
+        nil
+      end
+      private_class_method :resolve_cache_path
+    end
+  end
+end

data/lib/shoko/adapters/storage/recent_files.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'time'
+require_relative 'atomic_file_writer'
+require_relative 'config_paths'
+require_relative '../output/terminal/terminal_sanitizer.rb'
+
+module Shoko
+  module Adapters::Storage
+    # Manages a list of recently opened files.
+    class RecentFiles
+      CONFIG_DIR = Adapters::Storage::ConfigPaths.config_root
+      RECENT_FILE = File.join(CONFIG_DIR, 'recent.json')
+      MAX_RECENT_FILES = 10
+
+      class << self
+        # Adds a file path to the top of the recent files list.
+        #
+        # @param path [String] The path to the file to add.
+        def add(path)
+          recent_files = load.reject { |file| file['path'] == path }
+
+          raw_label = File.basename(path, File.extname(path)).tr('_-', ' ')
+          label = Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(raw_label, preserve_newlines: false, preserve_tabs: false)
+
+          new_entry = {
+            'path' => path,
+            'name' => label,
+            'accessed' => Time.now.iso8601,
+          }
+
+          save([new_entry, *recent_files].first(MAX_RECENT_FILES))
+        end
+
+        # Loads the list of recent files from disk.
+        #
+        # @return [Array<Hash>] An array of recent file entries.
+        def load
+          return [] unless File.exist?(RECENT_FILE)
+
+          entries = JSON.parse(File.read(RECENT_FILE))
+          Array(entries).map do |row|
+            next row unless row.is_a?(Hash)
+
+            safe = row.dup
+            safe['name'] =
+              Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(safe['name'].to_s, preserve_newlines: false, preserve_tabs: false)
+            safe
+          end
+        rescue JSON::ParserError, Errno::ENOENT
+          []
+        end
+
+        # Clears the recent files list by removing the recent file.
+        def clear
+          FileUtils.rm_f(RECENT_FILE)
+        rescue Errno::EACCES, Errno::ENOENT
+          # Ignore errors
+        end
+
+        private
+
+        # Saves the list of recent files to disk.
+        #
+        # @param recent [Array<Hash>] The list of recent files to save.
+        def save(recent)
+          FileUtils.mkdir_p(File.dirname(RECENT_FILE))
+          payload = JSON.pretty_generate(recent)
+          Shoko::Adapters::Storage::AtomicFileWriter.write(RECENT_FILE, payload)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/repositories/annotation_repository.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative 'base_repository'
+require_relative 'storage/annotation_file_store'
+
+module Shoko
+  module Adapters::Storage::Repositories
+      # Repository for annotation persistence, abstracting the underlying storage mechanism.
+      #
+      # This repository provides a clean domain interface for annotation operations,
+      # hiding the file-based persistence details from domain services.
+      #
+      # @example Adding an annotation
+      #   repo = AnnotationRepository.new(dependencies)
+      #   annotation = repo.add_for_book(
+      #     '/path/to/book.epub',
+      #     text: 'Selected text',
+      #     note: 'My note',
+      #     range: { start: 100, end: 120 },
+      #     chapter_index: 2
+      #   )
+      #
+      # @example Getting annotations for a book
+      #   annotations = repo.find_by_book_path('/path/to/book.epub')
+      class AnnotationRepository < BaseRepository
+        def initialize(dependencies)
+          super
+          file_writer = dependencies.resolve(:file_writer)
+          @storage = Storage::AnnotationFileStore.new(file_writer:)
+        end
+
+        # Add a new annotation for a specific book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param text [String] The selected text being annotated
+        # @param note [String] The annotation note
+        # @param range [Hash] Text selection range with :start and :end
+        # @param chapter_index [Integer] Chapter index (0-based)
+        # @param page_meta [Hash, nil] Optional page metadata
+        # @return [Hash] The created annotation data
+        def add_for_book(book_path, text:, note:, range:, chapter_index:, page_meta: nil)
+          validate_required_params(
+            { book_path: book_path, text: text, note: note, range: range,
+              chapter_index: chapter_index },
+            %i[book_path text note range chapter_index]
+          )
+
+          begin
+            @storage.add(book_path, text, note, range, chapter_index, page_meta)
+
+            # Return the most recently created annotation
+            annotations = find_by_book_path(book_path)
+            annotations.max_by do |a|
+              Time.parse(a['created_at'] || a['updated_at'] || Time.now.iso8601)
+            end
+          rescue StandardError => e
+            handle_storage_error(e, "adding annotation for #{book_path}")
+          end
+        end
+
+        # Find all annotations for a specific book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @return [Array<Hash>] Array of annotation hashes for the book
+        def find_by_book_path(book_path)
+          validate_required_params({ book_path: book_path }, [:book_path])
+
+          begin
+            @storage.get(book_path) || []
+          rescue StandardError => e
+            handle_storage_error(e, "loading annotations for #{book_path}")
+          end
+        end
+
+        # Find all annotations across all books
+        #
+        # @return [Hash] Hash mapping book paths to annotation arrays
+        def find_all
+          @storage.all || {}
+        rescue StandardError => e
+          handle_storage_error(e, 'loading all annotations')
+        end
+
+        # Update an existing annotation's note
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param annotation_id [String] ID of the annotation to update
+        # @param note [String] New note content
+        # @return [Boolean] True if updated successfully
+        def update_note(book_path, annotation_id, note)
+          validate_required_params(
+            { book_path: book_path, annotation_id: annotation_id, note: note },
+            %i[book_path annotation_id note]
+          )
+
+          begin
+            @storage.update(book_path, annotation_id, note)
+            true
+          rescue StandardError => e
+            handle_storage_error(e, "updating annotation #{annotation_id} for #{book_path}")
+          end
+        end
+
+        # Delete a specific annotation
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param annotation_id [String] ID of the annotation to delete
+        # @return [Boolean] True if deleted successfully
+        def delete_by_id(book_path, annotation_id)
+          validate_required_params(
+            { book_path: book_path, annotation_id: annotation_id },
+            %i[book_path annotation_id]
+          )
+
+          begin
+            @storage.delete(book_path, annotation_id)
+            true
+          rescue StandardError => e
+            handle_storage_error(e, "deleting annotation #{annotation_id} for #{book_path}")
+          end
+        end
+
+        # Find a specific annotation by ID
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param annotation_id [String] ID of the annotation to find
+        # @return [Hash, nil] The annotation hash, or nil if not found
+        def find_by_id(book_path, annotation_id)
+          annotations = find_by_book_path(book_path)
+          annotations.find { |a| a['id'] == annotation_id }
+        rescue StandardError => e
+          handle_storage_error(e, "finding annotation #{annotation_id} for #{book_path}")
+        end
+
+        # Get annotation count for a book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @return [Integer] Number of annotations for the book
+        def count_for_book(book_path)
+          find_by_book_path(book_path).size
+        rescue StandardError => e
+          handle_storage_error(e, "counting annotations for #{book_path}")
+        end
+
+        # Find annotations by chapter
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param chapter_index [Integer] Chapter index to filter by
+        # @return [Array<Hash>] Annotations in the specified chapter
+        def find_by_chapter(book_path, chapter_index)
+          annotations = find_by_book_path(book_path)
+          annotations.select { |a| a['chapter_index'] == chapter_index }
+        rescue StandardError => e
+          handle_storage_error(e, "finding annotations by chapter for #{book_path}")
+        end
+
+        # Check if any annotations exist at a text range
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param chapter_index [Integer] Chapter index
+        # @param range [Hash] Text range with :start and :end
+        # @return [Boolean] True if annotations exist in this range
+        def exists_in_range?(book_path, chapter_index, range)
+          annotations = find_by_chapter(book_path, chapter_index)
+          annotations.any? do |annotation|
+            annotation_range = annotation['range']
+            next false unless annotation_range
+
+            # Check for overlap
+            annotation_start = annotation_range['start'] || annotation_range[:start]
+            annotation_end = annotation_range['end'] || annotation_range[:end]
+            range_start = range['start'] || range[:start]
+            range_end = range['end'] || range[:end]
+
+            annotation_start < range_end && range_start < annotation_end
+          end
+        rescue StandardError => e
+          handle_storage_error(e, "checking annotation range for #{book_path}")
+        end
+      end
+  end
+end