shoko 0.1.0

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage::Repositories
+      # Base class for all repository implementations in the domain layer.
+      #
+      # Repositories provide an abstraction layer between domain services and
+      # infrastructure storage mechanisms, following the Repository pattern from
+      # Domain-Driven Design.
+      #
+      # All repositories should:
+      # - Provide domain-focused methods (not storage-focused)
+      # - Return domain objects or primitives
+      # - Handle storage-specific errors and convert to domain errors
+      # - Use dependency injection for storage implementations
+      #
+      # @example Implementing a repository
+      #   class MyRepository < BaseRepository
+      #     def find_by_id(id)
+      #       storage_result = @storage.find(id)
+      #       convert_to_domain_object(storage_result)
+      #     rescue Storage::NotFoundError => e
+      #       raise EntityNotFoundError, e.message
+      #     end
+      #   end
+      class BaseRepository
+        # Repository-specific errors
+        class RepositoryError < StandardError; end
+        class EntityNotFoundError < RepositoryError; end
+        class ValidationError < RepositoryError; end
+        class PersistenceError < RepositoryError; end
+
+        def initialize(dependencies)
+          @dependencies = dependencies
+          @logger = dependencies.resolve(:logger)
+          setup_repository_dependencies
+        end
+
+        protected
+
+        attr_reader :dependencies, :logger
+
+        # Template method for subclasses to set up their specific dependencies
+        def setup_repository_dependencies
+          # Override in subclasses to resolve storage dependencies
+        end
+
+        # Helper to handle common storage errors
+        def handle_storage_error(error, context = nil)
+          msg = error.message
+          message = context ? "#{context}: #{msg}" : msg
+          logger.error("Repository error - #{message}")
+
+          case error
+          when NoMethodError, ArgumentError
+            raise ValidationError, message
+          else
+            raise PersistenceError, message
+          end
+        end
+
+        # Helper to validate required parameters
+        def validate_required_params(params, required_keys)
+          missing_keys = required_keys.select do |key|
+            val = params[key]
+            !params.key?(key) || val.nil? || (val.respond_to?(:empty?) && val.empty?)
+          end
+          return if missing_keys.empty?
+
+          raise ValidationError, "Missing required parameters: #{missing_keys.join(', ')}"
+        end
+
+        # Helper to ensure entity exists before operations
+        def ensure_entity_exists(entity, entity_name = 'Entity')
+          return if entity
+
+          raise EntityNotFoundError, "#{entity_name} not found"
+        end
+      end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative 'base_repository'
+require_relative '../../../core/models/bookmark_data.rb'
+require_relative 'storage/bookmark_file_store'
+
+module Shoko
+  module Adapters::Storage::Repositories
+      # Repository for bookmark persistence, abstracting the underlying storage mechanism.
+      #
+      # This repository provides a clean domain interface for bookmark operations,
+      # hiding the file-based persistence details from domain services.
+      #
+      # @example Adding a bookmark
+      #   repo = BookmarkRepository.new(dependencies)
+      #   repo.add_for_book('/path/to/book.epub', chapter: 2, line: 50, text: 'Important quote')
+      #
+      # @example Getting bookmarks for a book
+      #   bookmarks = repo.find_by_book_path('/path/to/book.epub')
+      class BookmarkRepository < BaseRepository
+        def initialize(dependencies)
+          super
+          file_writer = dependencies.resolve(:file_writer)
+          @storage = Storage::BookmarkFileStore.new(file_writer:)
+        end
+
+        # Add a bookmark for a specific book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param chapter_index [Integer] Chapter index (0-based)
+        # @param line_offset [Integer] Line offset within the chapter
+        # @param text_snippet [String] Text snippet for the bookmark
+        # @return [Models::Bookmark] The created bookmark
+        def add_for_book(book_path, chapter_index:, line_offset:, text_snippet:)
+          validate_required_params(
+            { book_path: book_path, chapter_index: chapter_index, line_offset: line_offset },
+            %i[book_path chapter_index line_offset]
+          )
+
+          bookmark_data = Core::Models::BookmarkData.new(
+            path: book_path,
+            chapter: chapter_index,
+            line_offset: line_offset,
+            text: text_snippet || ''
+          )
+
+          begin
+            @storage.add(bookmark_data)
+
+            # Return the bookmark object that was created
+            bookmarks = find_by_book_path(book_path)
+            # Find the most recently added bookmark (by timestamp)
+            bookmarks.max_by(&:created_at)
+          rescue StandardError => e
+            handle_storage_error(e, "adding bookmark for #{book_path}")
+          end
+        end
+
+        # Find all bookmarks for a specific book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @return [Array<Models::Bookmark>] Array of bookmarks 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 bookmarks for #{book_path}")
+          end
+        end
+
+        # Delete a specific bookmark
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param bookmark [Models::Bookmark] The bookmark to delete
+        # @return [Boolean] True if deleted successfully
+        def delete_for_book(book_path, bookmark)
+          # Ensure entity existence takes precedence for clearer error semantics
+          ensure_entity_exists(bookmark, 'Bookmark')
+          validate_required_params({ book_path: book_path }, %i[book_path])
+
+          begin
+            @storage.delete(book_path, bookmark)
+            true
+          rescue StandardError => e
+            handle_storage_error(e, "deleting bookmark for #{book_path}")
+          end
+        end
+
+        # Check if a bookmark exists at the given position
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param chapter_index [Integer] Chapter index
+        # @param line_offset [Integer] Line offset within the chapter
+        # @return [Boolean] True if a bookmark exists at this position
+        def exists_at_position?(book_path, chapter_index, line_offset)
+          bookmarks = find_by_book_path(book_path)
+          bookmarks.any? do |bookmark|
+            bookmark.chapter_index == chapter_index && bookmark.line_offset == line_offset
+          end
+        rescue StandardError => e
+          handle_storage_error(e, "checking bookmark existence for #{book_path}")
+        end
+
+        # Get bookmark count for a book
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @return [Integer] Number of bookmarks for the book
+        def count_for_book(book_path)
+          find_by_book_path(book_path).size
+        rescue StandardError => e
+          handle_storage_error(e, "counting bookmarks for #{book_path}")
+        end
+
+        # Find bookmark at a specific position
+        #
+        # @param book_path [String] Path to the EPUB file
+        # @param chapter_index [Integer] Chapter index
+        # @param line_offset [Integer] Line offset within the chapter
+        # @return [Models::Bookmark, nil] The bookmark at this position, or nil
+        def find_at_position(book_path, chapter_index, line_offset)
+          bookmarks = find_by_book_path(book_path)
+          bookmarks.find do |bookmark|
+            bookmark.chapter_index == chapter_index && bookmark.line_offset == line_offset
+          end
+        rescue StandardError => e
+          handle_storage_error(e, "finding bookmark at position for #{book_path}")
+        end
+      end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+require_relative '../cache_paths'
+require_relative '../json_cache_store'
+require_relative '../cache_pointer_manager'
+require_relative '../epub_cache'
+require_relative '../../output/terminal/terminal_sanitizer.rb'
+
+module Shoko
+  module Adapters::Storage::Repositories
+      # Provides read-only access to cached library metadata on disk.
+      class CachedLibraryRepository
+        def initialize(cache_root: Adapters::Storage::CachePaths.cache_root, store: nil)
+          @cache_root = cache_root
+          @cache_store = store || Adapters::Storage::JsonCacheStore.new(cache_root:)
+        end
+
+        def list_entries
+          rows = fetch_manifest_rows
+          rows = fetch_rows if rows.empty?
+          return [] if rows.empty?
+
+          rows.filter_map { |row| build_entry_from_row(row) }
+        end
+
+        private
+
+        def fetch_rows
+          @cache_store.list_books
+        end
+
+        def fetch_manifest_rows
+          Adapters::Storage::JsonCacheStore.manifest_rows(@cache_root)
+        end
+
+        def build_entry_from_row(row)
+          sha = row.is_a?(Hash) ? (row['source_sha'] || row[:source_sha]) : nil
+          pointer_path = Adapters::Storage::EpubCache.cache_path_for_sha(sha, cache_root: @cache_root)
+          return nil unless pointer_path
+
+          ensure_pointer_file(row, pointer_path)
+
+          metadata = parse_json_object(row['metadata_json'])
+          authors = parse_json_array(row['authors_json']).map { |name| sanitize_display(name.to_s) }
+
+          {
+            title: sanitize_display(present_or_default(row['title'], 'Unknown')),
+            authors: authors.join(', '),
+            year: extract_year(metadata),
+            size_bytes: (row['cache_size_bytes'] || safe_file_size(pointer_path)).to_i,
+            open_path: pointer_path,
+            epub_path: row['source_path'].to_s,
+          }
+        end
+
+        def ensure_pointer_file(row, path)
+          return path if File.exist?(path) || row['source_sha'].to_s.empty?
+
+          generated_at = begin
+            raw = row['generated_at']
+            raw ? Time.at(raw.to_f).utc.iso8601 : Time.now.utc.iso8601
+          rescue StandardError
+            Time.now.utc.iso8601
+          end
+
+          metadata = {
+            'format' => Adapters::Storage::CachePointerManager::POINTER_FORMAT,
+            'version' => Adapters::Storage::CachePointerManager::POINTER_VERSION,
+            'sha256' => row['source_sha'],
+            'source_path' => row['source_path'],
+            'generated_at' => generated_at,
+            'engine' => Adapters::Storage::JsonCacheStore::ENGINE,
+          }
+
+          Adapters::Storage::CachePointerManager.new(path).write(metadata)
+          path
+        rescue StandardError
+          path
+        end
+
+        def parse_json_object(value)
+          return {} unless value
+          return value if value.is_a?(Hash)
+
+          parsed = JSON.parse(value)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError, TypeError
+          {}
+        end
+
+        def parse_json_array(value)
+          return [] unless value
+          return value if value.is_a?(Array)
+
+          parsed = JSON.parse(value)
+          parsed.is_a?(Array) ? parsed : []
+        rescue JSON::ParserError, TypeError
+          []
+        end
+
+        def extract_year(metadata)
+          return '' unless metadata.respond_to?(:[])
+
+          year = metadata['year'] || metadata[:year]
+          year ? year.to_s : ''
+        end
+
+        def present_or_default(value, fallback)
+          str = value.to_s.strip
+          str.empty? ? fallback : value
+        end
+
+        def safe_file_size(path)
+          File.size(path)
+        rescue StandardError
+          0
+        end
+
+        def sanitize_display(text)
+          Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(text.to_s, preserve_newlines: false, preserve_tabs: false)
+        rescue StandardError
+          text.to_s
+        end
+      end
+  end
+end

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

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require_relative 'base_repository'
+
+module Shoko
+  module Adapters::Storage::Repositories
+      # Repository for configuration persistence, abstracting the underlying storage mechanism.
+      #
+      # This repository provides a clean domain interface for configuration operations,
+      # using the StateStore as the single source of truth for all configuration data.
+      #
+      # @example Getting configuration
+      #   repo = ConfigRepository.new(dependencies)
+      #   view_mode = repo.view_mode
+      #   line_spacing = repo.line_spacing
+      #
+      # @example Updating configuration
+      #   repo.update_view_mode(:split)
+      #   repo.update_line_spacing(:relaxed)
+      class ConfigRepository < BaseRepository
+        LINE_SPACING_ALIASES = {
+          tight: :compact,
+          wide: :relaxed,
+        }.freeze
+
+        LINE_SPACING_ALLOWED = %i[compact normal relaxed].freeze
+
+        # Default configuration values
+        DEFAULT_CONFIG = {
+          view_mode: :split,
+          page_numbering_mode: :dynamic,
+          show_page_numbers: true,
+          line_spacing: :compact,
+          highlight_quotes: true,
+          input_debounce_ms: 100,
+          search_highlight_timeout: 2000,
+          auto_save_interval: 30,
+          theme: :default,
+        }.freeze
+
+        def initialize(dependencies)
+          super
+          @state_store = dependencies.resolve(:global_state)
+        end
+
+        # Get the current view mode
+        #
+        # @return [Symbol] Current view mode (:split or :single)
+        def view_mode
+          get_config_value(:view_mode, DEFAULT_CONFIG[:view_mode])
+        end
+
+        # Update the view mode
+        #
+        # @param mode [Symbol] New view mode (:split or :single)
+        # @return [Boolean] True if updated successfully
+        def update_view_mode(mode)
+          validate_enum_value(:view_mode, mode, %i[split single])
+          update_config_value(:view_mode, mode)
+        end
+
+        # Get the current page numbering mode
+        #
+        # @return [Symbol] Current page numbering mode (:absolute or :dynamic)
+        def page_numbering_mode
+          get_config_value(:page_numbering_mode, DEFAULT_CONFIG[:page_numbering_mode])
+        end
+
+        # Update the page numbering mode
+        #
+        # @param mode [Symbol] New page numbering mode (:absolute or :dynamic)
+        # @return [Boolean] True if updated successfully
+        def update_page_numbering_mode(mode)
+          validate_enum_value(:page_numbering_mode, mode, %i[absolute dynamic])
+          update_config_value(:page_numbering_mode, mode)
+        end
+
+        # Get whether page numbers are shown
+        #
+        # @return [Boolean] True if page numbers should be shown
+        def show_page_numbers?
+          get_config_value(:show_page_numbers, DEFAULT_CONFIG[:show_page_numbers])
+        end
+
+        # Update whether to show page numbers
+        #
+        # @param show [Boolean] Whether to show page numbers
+        # @return [Boolean] True if updated successfully
+        def update_show_page_numbers(show)
+          validate_boolean_value(:show_page_numbers, show)
+          update_config_value(:show_page_numbers, show)
+        end
+
+        # Get the current line spacing
+        #
+        # @return [Symbol] Current line spacing (:compact, :normal, or :relaxed)
+        def line_spacing
+          raw = get_config_value(:line_spacing, DEFAULT_CONFIG[:line_spacing])
+          normalized = normalize_line_spacing(raw)
+          update_config_value(:line_spacing, normalized) if raw != normalized
+          normalized
+        end
+
+        # Update the line spacing
+        #
+        # @param spacing [Symbol] New line spacing (:compact, :normal, or :relaxed)
+        # @return [Boolean] True if updated successfully
+        def update_line_spacing(spacing)
+          normalized = normalize_line_spacing(spacing)
+          validate_enum_value(:line_spacing, normalized, LINE_SPACING_ALLOWED)
+          update_config_value(:line_spacing, normalized)
+        end
+
+        # Get the input debounce time in milliseconds
+        #
+        # @return [Integer] Input debounce time in milliseconds
+        def input_debounce_ms
+          get_config_value(:input_debounce_ms, DEFAULT_CONFIG[:input_debounce_ms])
+        end
+
+        # Update the input debounce time
+        #
+        # @param ms [Integer] New debounce time in milliseconds
+        # @return [Boolean] True if updated successfully
+        def update_input_debounce_ms(milliseconds)
+          validate_positive_integer(:input_debounce_ms, milliseconds)
+          update_config_value(:input_debounce_ms, milliseconds)
+        end
+
+        # Get all configuration as a hash
+        #
+        # @return [Hash] All configuration values
+        def all_config
+          config_state = @state_store.get(%i[config]) || {}
+          DEFAULT_CONFIG.merge(config_state)
+        end
+
+        # Update multiple configuration values at once
+        #
+        # @param config_hash [Hash] Hash of configuration key-value pairs
+        # @return [Boolean] True if updated successfully
+        def update_multiple(config_hash)
+          validate_required_params({ config_hash: config_hash }, [:config_hash])
+
+          begin
+            # Validate each value before applying any updates
+            normalized = {}
+            config_hash.each do |key, value|
+              coerced = key == :line_spacing ? normalize_line_spacing(value) : value
+              validate_config_key_value(key, coerced)
+              normalized[key] = coerced
+            end
+
+            # Apply updates as a single state transaction
+            @state_store.update(normalized.transform_keys { |k| [:config, k] })
+            true
+          rescue StandardError => e
+            # Bubble up validation errors directly; wrap others
+            raise e if e.is_a?(BaseRepository::ValidationError)
+
+            handle_storage_error(e, 'updating multiple config values')
+          end
+        end
+
+        # Reset configuration to defaults
+        #
+        # @return [Boolean] True if reset successfully
+        def reset_to_defaults
+          @state_store.update(DEFAULT_CONFIG.transform_keys { |k| [:config, k] })
+          true
+        rescue StandardError => e
+          handle_storage_error(e, 'resetting configuration to defaults')
+        end
+
+        # Check if a configuration key has been customized from default
+        #
+        # @param key [Symbol] Configuration key to check
+        # @return [Boolean] True if the value differs from default
+        def customized?(key)
+          current_value = get_config_value(key, nil)
+          default_value = DEFAULT_CONFIG[key]
+          current_value != default_value
+        end
+
+        private
+
+        # Get a configuration value with fallback to default
+        def get_config_value(key, default_value)
+          value = @state_store.get([:config, key])
+          value.nil? ? default_value : value
+        rescue StandardError => e
+          handle_storage_error(e, "getting config value #{key}")
+        end
+
+        # Update a single configuration value
+        def update_config_value(key, value)
+          stored_value = key == :line_spacing ? normalize_line_spacing(value) : value
+          @state_store.update({ [:config, key] => stored_value })
+          true
+        rescue StandardError => e
+          handle_storage_error(e, "updating config value #{key}")
+        end
+
+        # Validate that a value is one of the allowed enum values
+        def validate_enum_value(key, value, allowed_values)
+          return if allowed_values.include?(value)
+
+          raise ValidationError,
+                "Invalid #{key}: #{value}. Must be one of: #{allowed_values.join(', ')}"
+        end
+
+        # Validate that a value is a boolean
+        def validate_boolean_value(key, value)
+          return if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+
+          raise ValidationError, "Invalid #{key}: #{value}. Must be true or false"
+        end
+
+        # Validate that a value is a positive integer
+        def validate_positive_integer(key, value)
+          return if value.is_a?(Integer) && value.positive?
+
+          raise ValidationError, "Invalid #{key}: #{value}. Must be a positive integer"
+        end
+
+        # Validate a specific config key-value pair
+        def validate_config_key_value(key, value)
+          case key
+          when :view_mode
+            validate_enum_value(key, value, %i[split single])
+          when :page_numbering_mode
+            validate_enum_value(key, value, %i[absolute dynamic])
+          when :line_spacing
+            normalized = normalize_line_spacing(value)
+            validate_enum_value(key, normalized, LINE_SPACING_ALLOWED)
+          when :show_page_numbers
+            validate_boolean_value(key, value)
+          when :input_debounce_ms, :search_highlight_timeout, :auto_save_interval
+            validate_positive_integer(key, value)
+          when :theme
+            # Allow any symbol for theme for extensibility
+            unless value.is_a?(Symbol)
+              raise ValidationError,
+                    "Invalid #{key}: #{value}. Must be a symbol"
+            end
+          else
+            # Unknown keys are allowed for forward compatibility
+            logger.debug("Unknown config key: #{key}")
+          end
+        end
+
+        def normalize_line_spacing(value)
+          sym = begin
+            value.is_a?(String) ? value.downcase.to_sym : value&.to_sym
+          rescue StandardError
+            nil
+          end
+          LINE_SPACING_ALIASES.fetch(sym, sym || DEFAULT_CONFIG[:line_spacing])
+        end
+      end
+  end
+end