shoko 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4da504e314b4ccf14caada8bcdb128ea1e128c3eb391e51ee85ef41529003fb5
+  data.tar.gz: 356baf7e71baf08181a92eb4d582c3e21e248ce121414c6ea1313c881f54ca9c
+SHA512:
+  metadata.gz: c31d6dac31624b683b5bb672174f5d47c1943d63bd8f2677806e42cd48943f9bd2ac83c73d72f9d4b4ace1416423d4361b00d688b23649b9a80edd7c4c839a27
+  data.tar.gz: 52f71139fc47843e8d078ad5fc23a874d8b0807002275781f6bbb99ac01f58b73ca216f2af3218f8905a3070ee5d6726108355d902cc276b760e141e7d4644a7

data/.bundle/config

@@ -0,0 +1,4 @@
+---
+BUNDLE_BIN: "bin"
+BUNDLE_PATH: "vendor/bundle"
+BUNDLE_WITHOUT: "development:test"

data/.bundle/config.bak

@@ -0,0 +1,3 @@
+---
+BUNDLE_BIN: "bin"
+BUNDLE_PATH: "vendor/bundle"

data/.rspec_status

@@ -0,0 +1,42 @@
+example_id                                      | status | run_time        |
+----------------------------------------------- | ------ | --------------- |
+./spec/comprehensive_coverage_spec.rb[1:1:1:1]  | passed | 0.0089 seconds  |
+./spec/comprehensive_coverage_spec.rb[1:1:1:2]  | passed | 0.00391 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:3]  | passed | 0.00181 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:4]  | passed | 0.00271 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:5]  | failed | 0.00894 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:6]  | passed | 0.00246 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:7]  | failed | 0.00194 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:8]  | passed | 0.00167 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:9]  | passed | 0.00327 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:10] | passed | 0.00172 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:1:11] | passed | 0.22362 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:2:1]  | failed | 0.00262 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:2:2]  | passed | 0.00312 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:2:3]  | passed | 0.0047 seconds  |
+./spec/comprehensive_coverage_spec.rb[1:1:3:1]  | passed | 0.0022 seconds  |
+./spec/comprehensive_coverage_spec.rb[1:1:3:2]  | failed | 0.00193 seconds |
+./spec/comprehensive_coverage_spec.rb[1:1:3:3]  | passed | 0.00264 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:1:1]  | passed | 0.00124 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:1:2]  | passed | 0.00094 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:1:3]  | passed | 0.00128 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:1:4]  | passed | 0.0018 seconds  |
+./spec/comprehensive_coverage_spec.rb[1:2:2:1]  | passed | 0.00142 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:2:2]  | passed | 0.00105 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:3:1]  | passed | 0.00189 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:3:2]  | passed | 0.00288 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:4:1]  | passed | 0.00163 seconds |
+./spec/comprehensive_coverage_spec.rb[1:2:4:2]  | passed | 0.00181 seconds |
+./spec/comprehensive_coverage_spec.rb[1:3:1:1]  | passed | 0.0228 seconds  |
+./spec/comprehensive_coverage_spec.rb[1:3:1:2]  | passed | 0.00391 seconds |
+./spec/comprehensive_coverage_spec.rb[1:4:1:1]  | passed | 0.00306 seconds |
+./spec/comprehensive_coverage_spec.rb[1:4:1:2]  | passed | 0.00191 seconds |
+./spec/comprehensive_coverage_spec.rb[1:4:1:3]  | passed | 0.00109 seconds |
+./spec/comprehensive_coverage_spec.rb[1:5:1:1]  | passed | 0.00094 seconds |
+./spec/comprehensive_coverage_spec.rb[1:5:1:2]  | passed | 0.00254 seconds |
+./spec/comprehensive_coverage_spec.rb[1:6:1:1]  | passed | 0.00089 seconds |
+./spec/comprehensive_coverage_spec.rb[1:6:1:2]  | passed | 0.00071 seconds |
+./spec/comprehensive_coverage_spec.rb[1:6:1:3]  | passed | 0.0591 seconds  |
+./spec/infrastructure_validator_spec.rb[1:1]    | passed | 0.00546 seconds |
+./spec/infrastructure_validator_spec.rb[1:2]    | passed | 0.00201 seconds |
+./spec/infrastructure_validator_spec.rb[1:3]    | passed | 0.00107 seconds |

data/.rubocop.yml

@@ -0,0 +1,124 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rails
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+# Layout
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+# Metrics
+Metrics/ClassLength:
+  Max: 200
+  CountComments: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/ModuleLength:
+  Max: 200
+  CountComments: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/MethodLength:
+  Max: 15
+  CountComments: false
+  AllowedMethods:
+    - 'initialize'
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 8
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/PerceivedComplexity:
+  Max: 9
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/ParameterLists:
+  Max: 4
+  CountKeywordArgs: false
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+
+# Style
+Style/Documentation:
+  Enabled: true
+  Exclude:
+    - 'spec/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+  ConsistentQuotesInMultiline: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/GuardClause:
+  Enabled: true
+  MinBodyLength: 1
+
+Style/ModuleFunction:
+  Enabled: true
+  EnforcedStyle: module_function
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+# Security
+Security/Eval:
+  Enabled: true
+
+Security/Open:
+  Enabled: true
+
+# Performance
+Performance/Count:
+  Enabled: true
+
+Performance/Detect:
+  Enabled: true
+
+# Additional cops
+Lint/UselessAssignment:
+  Enabled: true
+
+Lint/DuplicateMethods:
+  Enabled: true
+
+Rails:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'reek'
+  gem 'rubocop', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rails', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+group :test do
+  gem 'fakefs', require: 'fakefs/spec_helpers'
+  gem 'rspec'
+  gem 'simplecov', require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shayan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# Shoko
+
+Terminal ebook reader for EPUB files.
+
+## What it does
+
+- Scans common folders for EPUB files and shows them in a menu.
+- Opens a specific file directly when a path is provided.
+- Reads in split or single view with adjustable line spacing and themes.
+- Provides a TOC sidebar, bookmarks, and annotations.
+- Supports mouse selection for highlighting and annotation editing.
+- Can download public-domain EPUBs from Gutendex.
+- Optional Kitty inline image rendering (when supported).
+
+## How it works
+
+- `bin/start` runs the CLI and enters menu mode or opens a file directly.
+- State lives in a single store; actions update state and selectors read it.
+- Rendering is component-based and drawn through a terminal buffer with diff updates.
+- Selection/highlighting uses recorded line geometry from the render pass.
+
+## Usage
+
+From source:
+
+```bash
+bundle install
+bin/start
+```
+
+Open a file directly:
+
+```bash
+bin/start /path/to/book.epub
+```
+
+Options:
+
+- `-d`, `--debug` Enable debug logging.
+- `--log PATH` Write JSON logs to PATH.
+- `--log-level LEVEL` Set log level (`debug`, `info`, `warn`, `error`, `fatal`).
+- `--profile PATH` Write a concise performance profile to PATH.
+- `-h`, `--help` Show help.
+
+## Controls (basics)
+
+Menu:
+
+- `j`/`k` or arrow keys to move
+- `Enter` to select
+- `Esc` to go back
+- `/` to search in browse mode
+- `q` to quit
+
+Reader:
+
+- `h`/`l` or arrow keys to change pages
+- `j`/`k` to scroll
+- `Space` for next page
+- `t` for TOC
+- `b` to add bookmark, `B` to open bookmarks
+- `A` to open annotations
+- `?` for help
+- `q` to return to menu, `Q` to quit
+
+## Data locations
+
+- Config and data: `~/.config/shoko/`
+  - `config.json`
+  - `annotations.json`, `bookmarks.json`, `progress.json`, `recent.json`
+  - `downloads/` (Gutendex downloads)
+  - `epub_cache.json` (scan cache)
+- Cache: `~/.cache/shoko/`
+
+## Logging and profiling
+
+You can also configure logging with environment variables:
+
+- `DEBUG=1` Enable debug logging.
+- `SHOKO_LOG_PATH=/path/to/log` Write JSON logs to a file.
+- `SHOKO_LOG_LEVEL=info` Set log level.
+- `SHOKO_PROFILE_PATH=/path/to/profile` Write a performance profile.

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+desc 'Run all quality checks'
+task quality: %i[spec rubocop]
+
+task default: :quality
+
+namespace :test do
+  desc 'Run tests with coverage'
+  task :coverage do
+    ENV['COVERAGE'] = 'true'
+    Rake::Task['spec'].invoke
+  end
+end
+
+desc 'Console with library loaded'
+task :console do
+  require 'irb'
+  require 'shoko'
+  ARGV.clear
+  IRB.start
+end

data/bin/start

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+begin
+  require "bundler/setup"
+rescue LoadError
+  # Bundler isn't required when running from a packaged gem.
+end
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "shoko"
+
+Shoko::CLI.run(ARGV)

data/lib/shoko/adapters/book_sources/document_service.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative '../monitoring/performance_monitor.rb'
+require_relative 'epub_document'
+
+module Shoko
+  module Adapters::BookSources
+    # Document service for loading and accessing EPUB content.
+    # Provides clean interface to document operations without coupling to controllers.
+    class DocumentService
+      def initialize(epub_path, wrapping_service = nil, formatting_service: nil, background_worker: nil,
+                     progress_reporter: nil)
+        @epub_path = epub_path
+        @document = nil
+        @content_cache = {}
+        @wrapping_service = wrapping_service
+        @formatting_service = formatting_service
+        @background_worker = background_worker
+        @progress_reporter = progress_reporter
+      end
+
+      # Load the EPUB document
+      #
+      # @return [EPUBDocument] Loaded document
+      def load_document
+        @document ||= Adapters::Monitoring::PerformanceMonitor.time('import.document.load') do
+          EPUBDocument.new(@epub_path,
+                           formatting_service: @formatting_service,
+                           background_worker: @background_worker,
+                           progress_reporter: @progress_reporter)
+        end
+      rescue StandardError => e
+        Adapters::Monitoring::Logger.error('Failed to load document', path: @epub_path, error: e.message)
+        create_error_document(e.message)
+      end
+
+      # Get chapter by index
+      #
+      # @param index [Integer] Chapter index
+      # @return [Chapter] Chapter object or nil
+      def chapter_at(index)
+        return nil unless @document
+
+        @document.get_chapter(index)
+      end
+
+      # Get table of contents
+      #
+      # @return [Array<Hash>] Array of TOC entries
+      def get_table_of_contents
+        return [] unless @document
+
+        @document.chapters.map.with_index do |chapter, index|
+          {
+            index: index,
+            title: chapter.title || "Chapter #{index + 1}",
+            level: 0, # Could be enhanced to support nested TOC
+          }
+        end
+      end
+
+      # Get content for specific page
+      #
+      # @param chapter_index [Integer] Chapter index
+      # @param page_offset [Integer] Page offset within chapter
+      # @param lines_per_page [Integer] Number of lines per page
+      # @return [Array<String>] Array of content lines
+      def get_page_content(chapter_index, page_offset, lines_per_page = 20)
+        cache_key = "#{chapter_index}_#{page_offset}_#{lines_per_page}"
+        cached_fetch(cache_key, default: []) do
+          with_chapter(chapter_index, default: []) do |chapter|
+            lines = chapter.lines || []
+            start_line = page_offset * lines_per_page
+            end_line = start_line + lines_per_page - 1
+            lines[start_line..end_line] || []
+          end
+        end
+      end
+
+      # Get wrapped content for specific page
+      #
+      # @param chapter_index [Integer] Chapter index
+      # @param page_offset [Integer] Page offset within chapter
+      # @param column_width [Integer] Column width for wrapping
+      # @param lines_per_page [Integer] Number of lines per page
+      # @return [Array<String>] Array of wrapped content lines
+      def get_wrapped_page_content(chapter_index, page_offset, column_width, lines_per_page = 20)
+        cache_key = "wrapped_#{chapter_index}_#{page_offset}_#{column_width}_#{lines_per_page}"
+        cached_fetch(cache_key, default: []) do
+          with_chapter(chapter_index, default: []) do |chapter|
+            lines = chapter.lines || []
+            wrapped_lines = wrap_lines(chapter_index, lines, column_width)
+            start_line = page_offset * lines_per_page
+            end_line = start_line + lines_per_page - 1
+            wrapped_lines[start_line..end_line] || []
+          end
+        end
+      end
+
+      # Get total wrapped lines for chapter
+      #
+      # @param chapter_index [Integer] Chapter index
+      # @param column_width [Integer] Column width for wrapping
+      # @return [Integer] Total wrapped lines
+      def get_chapter_wrapped_line_count(chapter_index, column_width)
+        cache_key = "line_count_#{chapter_index}_#{column_width}"
+        cached_fetch(cache_key, default: 0) do
+          with_chapter(chapter_index, default: 0) do |chapter|
+            lines = chapter.lines || []
+            wrapped_lines = wrap_lines(chapter_index, lines, column_width)
+            wrapped_lines.size
+          end
+        end
+      end
+
+      # Clear content cache
+      def clear_cache
+        @content_cache.clear
+      end
+
+      # Clear cache for specific width
+      #
+      # @param width [Integer] Column width
+      def clear_cache_for_width(width)
+        @content_cache.delete_if { |key, _| key.include?("_#{width}_") }
+      end
+
+      private
+
+      def create_error_document(error_message)
+        # Create a simple document with error information
+        ErrorDocument.new(error_message)
+      end
+
+      def wrap_lines(chapter_index, lines, column_width)
+        return lines if column_width <= 0
+        return @wrapping_service.wrap_lines(lines, chapter_index, column_width) if @wrapping_service
+
+        # Minimal fallback for tests/dev without DI
+        lines
+      end
+
+      def cached_fetch(key, default: nil)
+        return @content_cache[key] if @content_cache.key?(key)
+
+        value = yield
+        value = default if value.nil?
+        @content_cache[key] = value
+        value
+      end
+
+      def with_chapter(index, default: nil)
+        chapter = chapter_at(index)
+        return default unless chapter
+
+        yield chapter
+      end
+    end
+
+    # Simple error document for when EPUB loading fails
+    class ErrorDocument
+      attr_reader :error_message
+
+      def initialize(error_message)
+        @error_message = error_message
+      end
+
+      def chapter_count
+        1
+      end
+
+      def get_chapter(index)
+        return nil unless index.zero?
+
+        ErrorChapter.new(@error_message)
+      end
+
+      def chapters
+        [get_chapter(0)]
+      end
+    end
+
+    # Simple error chapter
+    class ErrorChapter
+      attr_reader :title, :lines
+
+      def initialize(error_message)
+        @title = 'Error Loading Book'
+        @lines = [
+          'Failed to load the EPUB file:',
+          '',
+          error_message,
+          '',
+          'Please check that the file exists and is a valid EPUB.',
+          '',
+          "Press 'q' to return to the main menu.",
+        ]
+      end
+    end
+  end
+end

data/lib/shoko/adapters/book_sources/download_service.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative '../../core/services/base_service.rb'
+require_relative '../storage/config_paths'
+
+module Shoko
+  module Adapters::BookSources
+      # Coordinates Gutendex search + download to the local library.
+      class DownloadService < BaseService
+        class DownloadError < StandardError; end
+
+        def search(query:, page_url: nil)
+          payload = client.search(query: query, page_url: page_url)
+          {
+            count: payload['count'].to_i,
+            next: payload['next'],
+            previous: payload['previous'],
+            books: normalize_books(payload['results']),
+          }
+        end
+
+        def download(book)
+          url = pick_download_url(book)
+          raise DownloadError, 'No EPUB format available' unless url
+
+          dest_dir = downloads_root
+          FileUtils.mkdir_p(dest_dir)
+          dest_path = File.join(dest_dir, filename_for(book))
+          return { path: dest_path, existing: true } if File.exist?(dest_path)
+
+          client.download(url, dest_path) { |done, total| yield(done, total) if block_given? }
+          { path: dest_path, existing: false }
+        end
+
+        protected
+
+        def required_dependencies
+          [:gutendex_client]
+        end
+
+        private
+
+        def client
+          @client ||= resolve(:gutendex_client)
+        end
+
+        def downloads_root
+          Adapters::Storage::ConfigPaths.downloads_root
+        end
+
+        def normalize_books(items)
+          Array(items).map do |raw|
+            {
+              id: raw['id'],
+              title: raw['title'],
+              authors: Array(raw['authors']).filter_map { |a| a['name'] },
+              languages: Array(raw['languages']).map(&:to_s),
+              download_count: raw['download_count'],
+              formats: raw['formats'] || {},
+            }
+          end
+        end
+
+        def pick_download_url(book)
+          formats = value_for(book, :formats, 'formats', {})
+          return nil unless formats.respond_to?(:each)
+
+          keys = formats.keys.map(&:to_s)
+          epub_key = keys.find { |k| k.start_with?('application/epub+zip') } ||
+                     keys.find { |k| k.include?('application/epub') } ||
+                     keys.find { |k| k.include?('epub') }
+          return nil unless epub_key
+
+          formats[epub_key] || formats[epub_key.to_sym]
+        end
+
+        def filename_for(book)
+          id = value_for(book, :id, 'id', 'book').to_s
+          title = value_for(book, :title, 'title', 'book').to_s
+          slug = title.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/^-|-$/, '')
+          slug = "book-#{id}" if slug.empty?
+          "#{slug}-#{id}.epub"
+        end
+
+        def value_for(book, key_sym, key_str, default)
+          return book[key_sym] if book.respond_to?(:key?) && book.key?(key_sym)
+          return book[key_str] if book.respond_to?(:key?) && book.key?(key_str)
+
+          default
+        end
+
+      end
+  end
+end