shoko 0.1.0

data/lib/shoko/application/use_cases/catalog_service.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative '../../core/services/base_service.rb'
+require_relative '../../adapters/book_sources/epub/parsers/metadata_extractor.rb'
+require_relative '../../adapters/storage/recent_files'
+require_relative '../../adapters/storage/repositories/cached_library_repository'
+
+module Shoko
+  module Application::UseCases
+      # Facade providing catalog data (cached books, scan status, metadata) to higher layers.
+      # Wraps the infrastructure scanner/metadata helpers so presentation never touches them directly.
+      class CatalogService < BaseService
+        def initialize(dependencies)
+          super
+          @scanner = resolve(:library_scanner)
+          @cached_library_repository = resolve(:cached_library_repository) if registered?(:cached_library_repository)
+          @metadata_cache = {}
+        end
+
+        def required_dependencies
+          [:library_scanner]
+        end
+
+        def load_cached
+          @scanner.load_cached
+        end
+
+        def cached_library_entries
+          return [] unless @cached_library_repository
+
+          entries = @cached_library_repository.list_entries
+          return [] if entries.empty?
+
+          recent_index = index_recent_by_path
+          entries.each do |entry|
+            path = entry[:epub_path] || entry['epub_path']
+            entry[:last_accessed] = recent_index[path] if path
+          end
+          entries
+        rescue StandardError
+          []
+        end
+
+        def start_scan(force: false)
+          @scanner.start_scan(force: force)
+        end
+
+        def process_results
+          results = @scanner.process_results
+          update_entries(results) if results
+          results
+        end
+
+        def entries
+          @scanner.epubs || []
+        end
+
+        def update_entries(entries)
+          @scanner.epubs = entries
+          clear_metadata_cache
+        end
+
+        def scan_status
+          @scanner.scan_status
+        end
+
+        def scan_status=(value)
+          @scanner.scan_status = value
+        end
+
+        def scan_message
+          @scanner.scan_message
+        end
+
+        def scan_message=(value)
+          @scanner.scan_message = value
+        end
+
+        def cleanup
+          @scanner.cleanup if @scanner.respond_to?(:cleanup)
+        end
+
+        def metadata_for(path)
+          return {} unless path
+
+          @metadata_cache[path] ||= begin
+            Adapters::BookSources::Epub::Parsers::MetadataExtractor.from_epub(path)
+          rescue StandardError
+            {}
+          end
+        end
+
+        def size_for(path)
+          return 0 unless path
+
+          File.size(path)
+        rescue StandardError
+          0
+        end
+
+        def clear_metadata_cache
+          @metadata_cache.clear
+        end
+
+        private
+
+        def index_recent_by_path
+          items = Adapters::Storage::RecentFiles.load
+          Array(items).each_with_object({}) do |recent_item, acc|
+            path = recent_item['path'] || recent_item[:path]
+            accessed = recent_item['accessed'] || recent_item[:accessed]
+            acc[path] = accessed if path && accessed
+          end
+        end
+      end
+  end
+end

data/lib/shoko/application/use_cases/commands/annotation_editor_commands.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Shoko
+  module Application
+    module Commands
+      # Commands for driving the Annotation Editor screen via a clean, public API.
+      class AnnotationEditorCommand < BaseCommand
+        def initialize(action, name: nil, description: nil)
+          @action = action
+          super(
+            name: name || "annotation_editor_#{action}",
+            description: description || "Annotation editor #{action.to_s.tr('_', ' ')}"
+          )
+        end
+
+        protected
+
+        def perform(context, params = {})
+          ui = context.dependencies.resolve(:ui_controller) if context.respond_to?(:dependencies)
+          # Prefer a context-provided editor component (menu or reader), else fall back to UI current_mode
+          mode = if context.respond_to?(:current_editor_component)
+                   context.current_editor_component
+                 else
+                   ui&.current_mode
+                 end
+
+          case @action
+          when :save
+            return :handled if dispatched_to_mode?(mode, :save_annotation)
+          when :cancel
+            # Reader: cleanup + back to read; Menu: back to annotations
+            if dispatched_to_mode?(mode, :cancel_annotation)
+              # Mode handled the cancel path completely
+            elsif ui
+              begin
+                ui.cleanup_popup_state
+              rescue StandardError
+                # no-op (menu has no popup state)
+              end
+              begin
+                ui.switch_mode(:read)
+              rescue StandardError
+                # fall through to menu path
+              end
+            else
+              # Menu context: switch to annotations screen
+              begin
+                context.state.dispatch(Shoko::Application::Actions::UpdateMenuAction.new(mode: :annotations))
+              rescue StandardError
+                # best-effort
+              end
+            end
+          when :backspace
+            return :handled if dispatched_to_mode?(mode, :handle_backspace)
+          when :enter
+            return :handled if dispatched_to_mode?(mode, :handle_enter)
+          when :insert_char
+            ch = (params[:key] || '').to_s
+            return :pass if ch.empty?
+
+            return :handled if dispatched_to_mode?(mode, :handle_character, ch)
+          else
+            return :pass
+          end
+
+          :handled
+        end
+
+        private
+
+        def dispatched_to_mode?(mode, method_name, *)
+          return false unless mode.respond_to?(method_name)
+
+          mode.public_send(method_name, *)
+          true
+        end
+      end
+
+      # Factory methods for building AnnotationEditor commands.
+      module AnnotationEditorCommandFactory
+        def self.save
+          AnnotationEditorCommand.new(:save)
+        end
+
+        def self.cancel
+          AnnotationEditorCommand.new(:cancel)
+        end
+
+        def self.backspace
+          AnnotationEditorCommand.new(:backspace)
+        end
+
+        def self.enter
+          AnnotationEditorCommand.new(:enter)
+        end
+
+        def self.insert_char
+          AnnotationEditorCommand.new(:insert_char)
+        end
+      end
+    end
+  end
+end

data/lib/shoko/application/use_cases/commands/application_commands.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Shoko
+  module Application
+    module Commands
+      # Application-level commands for mode switching and system control.
+      class ApplicationCommand < BaseCommand
+        def initialize(action, name: nil, description: nil)
+          @action = action
+          super(
+            name: name || "app_#{action}",
+            description: description || "Application #{action.to_s.tr('_', ' ')}"
+          )
+        end
+
+        protected
+
+        def perform(context, _params = {})
+          deps = dependencies_from(context)
+
+          case @action
+          when :quit_to_menu
+            handle_quit_to_menu(deps)
+          when :quit_application
+            handle_quit_application(deps)
+          when :toggle_view_mode
+            handle_toggle_view_mode(deps)
+          when :show_help
+            handle_show_help(deps)
+          when :show_toc
+            handle_show_toc(deps)
+          when :show_bookmarks
+            handle_show_bookmarks(deps)
+          when :show_annotations
+            handle_show_annotations(deps)
+          else
+            raise ExecutionError.new("Unknown application action: #{@action}", command_name: name)
+          end
+
+          @action
+        end
+
+        private
+
+        def handle_quit_to_menu(deps)
+          controller = resolve_optional(deps, :state_controller)
+          if controller.respond_to?(:quit_to_menu)
+            controller.quit_to_menu
+          else
+            dispatch_action(deps, Application::Actions::QuitToMenuAction.new)
+          end
+        end
+
+        def handle_quit_application(deps)
+          controller = resolve_optional(deps, :state_controller)
+          if controller.respond_to?(:quit_application)
+            controller.quit_application
+            return
+          end
+
+          handle_quit_to_menu(deps)
+          force_cleanup(deps)
+          Kernel.exit(0)
+        end
+
+        def handle_toggle_view_mode(deps)
+          controller = resolve_optional(deps, :ui_controller)
+          if controller.respond_to?(:toggle_view_mode)
+            controller.toggle_view_mode
+          else
+            dispatch_action(deps, Application::Actions::ToggleViewModeAction.new)
+          end
+        end
+
+        def handle_show_help(deps)
+          controller = resolve_optional(deps, :ui_controller)
+          if controller.respond_to?(:show_help)
+            controller.show_help
+          else
+            state_store = resolve_state_store(deps)
+            state_store&.set(%i[reader mode], :help)
+          end
+        end
+
+        def handle_show_toc(deps)
+          controller = resolve_optional(deps, :ui_controller)
+          return unless controller.respond_to?(:open_toc)
+
+          controller.open_toc
+        end
+
+        def handle_show_bookmarks(deps)
+          controller = resolve_optional(deps, :ui_controller)
+          return unless controller.respond_to?(:open_bookmarks)
+
+          controller.open_bookmarks
+        end
+
+        def handle_show_annotations(deps)
+          controller = resolve_optional(deps, :ui_controller)
+          return unless controller.respond_to?(:open_annotations)
+
+          controller.open_annotations
+        end
+
+        def dependencies_from(context)
+          return context.dependencies if context.respond_to?(:dependencies)
+
+          raise ExecutionError.new('Command context must expose dependencies', command_name: name)
+        end
+
+        def resolve_optional(deps, key)
+          return nil if deps.respond_to?(:registered?) && !deps.registered?(key)
+
+          deps.resolve(key)
+        rescue StandardError
+          nil
+        end
+
+        def resolve_state_store(deps)
+          resolve_optional(deps, :state_store) || resolve_optional(deps, :global_state)
+        end
+
+        def dispatch_action(deps, action)
+          state_store = resolve_state_store(deps)
+          state_store&.dispatch(action)
+        end
+
+        def force_cleanup(deps)
+          terminal = resolve_optional(deps, :terminal_service)
+          return unless terminal
+
+          if terminal.respond_to?(:force_cleanup)
+            terminal.force_cleanup
+          elsif terminal.respond_to?(:cleanup)
+            terminal.cleanup
+          end
+        end
+      end
+
+      # Command that switches the reader into a specific UI mode.
+      class ModeCommand < BaseCommand
+        def initialize(mode, name: nil, description: nil)
+          @mode = mode
+          super(
+            name: name || "mode_#{mode}",
+            description: description || "Switch to #{mode} mode"
+          )
+        end
+
+        def validate_parameters(params)
+          super
+
+          valid_modes = %i[read help search]
+          return if valid_modes.include?(@mode)
+
+          raise ValidationError.new("Mode must be one of #{valid_modes}", command_name: name)
+        end
+
+        protected
+
+        def perform(context, _params = {})
+          state_store = context.dependencies.resolve(:state_store)
+          state_store.set(%i[reader mode], @mode)
+
+          @mode
+        end
+      end
+
+      # Factory methods for common application commands
+      module ApplicationCommandFactory
+        def self.quit_to_menu
+          ApplicationCommand.new(:quit_to_menu)
+        end
+
+        def self.quit_application
+          ApplicationCommand.new(:quit_application)
+        end
+
+        def self.toggle_view_mode
+          ApplicationCommand.new(:toggle_view_mode)
+        end
+
+        def self.show_help
+          ApplicationCommand.new(:show_help)
+        end
+
+        def self.show_toc
+          ApplicationCommand.new(:show_toc)
+        end
+
+        def self.show_bookmarks
+          ApplicationCommand.new(:show_bookmarks)
+        end
+
+        def self.show_annotations
+          ApplicationCommand.new(:show_annotations)
+        end
+
+        def self.switch_to_mode(mode)
+          ModeCommand.new(mode)
+        end
+      end
+    end
+  end
+end

data/lib/shoko/application/use_cases/commands/base_command.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Application
+    module Commands
+      # Enhanced base command with proper error handling and validation.
+      # Replaces the mixed command patterns with consistent implementation.
+      class BaseCommand
+        # Base error type for command execution and validation failures.
+        class CommandError < StandardError
+          attr_reader :command_name, :context
+
+          def initialize(message, command_name: nil, context: nil)
+            super(message)
+            @command_name = command_name
+            @context = context
+          end
+        end
+
+        class ValidationError < CommandError; end
+        class ExecutionError < CommandError; end
+
+        attr_reader :name, :description
+
+        def initialize(name: nil, description: nil, logger: nil)
+          @name = name || self.class.name.split('::').last
+          @description = description || @name
+          @logger = logger
+        end
+
+        # Execute command with full error handling and validation
+        #
+        # @param context [Object] Execution context (controller, service, etc.)
+        # @param params [Hash] Command parameters
+        # @return [Symbol] :handled, :pass, or :error
+        def execute(context, params = {})
+          validate_context(context)
+          validate_parameters(params)
+
+          return :pass unless can_execute?(context, params)
+
+          begin
+            result = perform(context, params)
+            handle_success(context, result)
+            :handled
+          rescue StandardError => e
+            handle_error(context, e, params)
+            :error
+          end
+        end
+
+        # Check if command can be executed
+        #
+        # @param context [Object] Execution context
+        # @param params [Hash] Command parameters
+        # @return [Boolean]
+        def can_execute?(_context, _params = {})
+          true # Override in subclasses for conditional execution
+        end
+
+        # Validate execution context
+        #
+        # @param context [Object] Execution context
+        # @raise [ValidationError] if context is invalid
+        def validate_context(context)
+          raise ValidationError.new('Context cannot be nil', command_name: name) if context.nil?
+        end
+
+        # Validate command parameters
+        #
+        # @param params [Hash] Command parameters
+        # @raise [ValidationError] if parameters are invalid
+        def validate_parameters(params)
+          # Override in subclasses for parameter validation
+        end
+
+        protected
+
+        # Perform the actual command logic
+        # Must be implemented by subclasses
+        #
+        # @param context [Object] Execution context
+        # @param params [Hash] Command parameters
+        # @return [Object] Command result
+        def perform(context, params = {})
+          raise NotImplementedError, "#{self.class.name} must implement #perform"
+        end
+
+        # Handle successful command execution
+        #
+        # @param context [Object] Execution context
+        # @param result [Object] Command result
+        def handle_success(context, result)
+          log_success(context, result)
+        end
+
+        # Handle command execution errors
+        #
+        # @param context [Object] Execution context
+        # @param error [StandardError] The error that occurred
+        # @param params [Hash] Command parameters
+        def handle_error(context, error, params = {})
+          log_error(context, error, params)
+
+          # Show user-friendly error message if possible
+          return unless context.respond_to?(:show_error_message)
+
+          context.show_error_message(user_friendly_error_message(error))
+        end
+
+        private
+
+        def log_success(context, result)
+          logger = resolve_logger(context)
+          logger&.debug(
+            'Command executed successfully',
+            command: name,
+            context: context.class.name,
+            result: result.inspect
+          )
+        end
+
+        def log_error(context, error, params)
+          logger = resolve_logger(context)
+          logger&.error(
+            'Command execution failed',
+            command: name,
+            context: context.class.name,
+            error: error.message,
+            params: params,
+            backtrace: error.backtrace.first(5)
+          )
+        end
+
+        def resolve_logger(context)
+          return @logger if defined?(@logger) && @logger
+
+          candidate = begin
+            if context.respond_to?(:dependencies)
+              deps = context.dependencies
+              deps.resolve(:logger) if deps.respond_to?(:resolve)
+            elsif context.respond_to?(:logger)
+              context.logger
+            end
+          rescue StandardError
+            nil
+          end
+          @logger = candidate if candidate
+          candidate
+        end
+
+        def user_friendly_error_message(error)
+          msg = error.message
+          case error
+          when ValidationError
+            "Invalid input: #{msg}"
+          when CommandError
+            msg
+          else
+            'An unexpected error occurred'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoko/application/use_cases/commands/bookmark_commands.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module Shoko
+  module Application
+    module Commands
+      # Bookmark management commands using domain services.
+      class BookmarkCommand < BaseCommand
+        def initialize(action, name: nil, description: nil)
+          @action = action
+          super(
+            name: name || "bookmark_#{action}",
+            description: description || "Bookmark #{action.to_s.tr('_', ' ')}"
+          )
+        end
+
+        def can_execute?(context, _params = {})
+          deps = context.dependencies
+          deps.registered?(:bookmark_service) && deps.registered?(:state_store)
+        end
+
+        protected
+
+        def perform(context, params = {})
+          deps = context.dependencies
+          bookmark_service = deps.resolve(:bookmark_service)
+
+          case @action
+          when :add
+            handle_add_bookmark(bookmark_service, params)
+          when :remove
+            handle_remove_bookmark(bookmark_service, params)
+          when :toggle
+            handle_toggle_bookmark(bookmark_service, params)
+          when :jump_to
+            handle_jump_to_bookmark(bookmark_service, params)
+          else
+            raise ExecutionError.new("Unknown bookmark action: #{@action}", command_name: name)
+          end
+
+          @action
+        end
+
+        private
+
+        def handle_add_bookmark(service, params)
+          text_snippet = params[:text_snippet]
+          service.add_bookmark(text_snippet)
+        end
+
+        def handle_remove_bookmark(service, params)
+          bookmark = params[:bookmark]
+
+          raise ValidationError.new('Bookmark required for remove action', command_name: name) unless bookmark
+
+          service.remove_bookmark(bookmark)
+        end
+
+        def handle_toggle_bookmark(service, params)
+          text_snippet = params[:text_snippet]
+          result = service.toggle_bookmark(text_snippet)
+
+          { result: result }
+        end
+
+        def handle_jump_to_bookmark(service, params)
+          bookmark = params[:bookmark]
+
+          raise ValidationError.new('Bookmark required for jump_to action', command_name: name) unless bookmark
+
+          service.jump_to_bookmark(bookmark)
+        end
+      end
+
+      # Factory methods for bookmark commands
+      module BookmarkCommandFactory
+        def self.add_bookmark(text_snippet = nil)
+          command = BookmarkCommand.new(:add)
+
+          # If text_snippet provided, create a wrapper that includes it in params
+          if text_snippet
+            lambda do |context, params = {}|
+              command.execute(context, params.merge(text_snippet: text_snippet))
+            end
+          else
+            command
+          end
+        end
+
+        def self.remove_bookmark(bookmark)
+          command = BookmarkCommand.new(:remove)
+          lambda do |context, params = {}|
+            command.execute(context, params.merge(bookmark: bookmark))
+          end
+        end
+
+        def self.toggle_bookmark(text_snippet = nil)
+          command = BookmarkCommand.new(:toggle)
+          lambda do |context, params = {}|
+            command.execute(context, params.merge(text_snippet: text_snippet))
+          end
+        end
+
+        def self.jump_to_bookmark(bookmark)
+          command = BookmarkCommand.new(:jump_to)
+          lambda do |context, params = {}|
+            command.execute(context, params.merge(bookmark: bookmark))
+          end
+        end
+      end
+    end
+  end
+end