shoko 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7a36fd324fdba1eed316344cfab543f5fef1bfa863c1b25fc3e644502978054
-  data.tar.gz: 5fc5820176929bd037c545901cdc0c611e98b593a90fc8da7a54d4a01b0cc359
+  metadata.gz: a52dba22d1ec1059543f62821ab8e1bf7236def9a0cb8ef2376b13434faf2f03
+  data.tar.gz: 2da5e4f6c6b7a31702f7b9c9fe1786b02895f1588415a215ab0130068eebfb33
 SHA512:
-  metadata.gz: e29b072b4f0dc64eb6a18f36d3fcc1bf37fa9efa904b1827cccbe85c4c37860073e04c3eddc87fdab827b9d02e03958f54bd1714d58644cdff026caaacf93bfe
-  data.tar.gz: 0ffb950539fe1440f26149b1d75755811f2aaf541f900f6ab89051dc9e4e2550c1a07a9de32d83a3d6bac5a5f25a1184f7830cf3b39866eed458b71081fe9248
+  metadata.gz: acbbf2c9f160186d0cf41a3a8ed41efeb60be2f261398f80d2e9318eb0573f9c1ef47bb6f01851c9cdec6a42f8409b99b4b789d36e9d0af36491c3000cfbaa88
+  data.tar.gz: 6756ad75a6ffcfe850b99958f30440f35800a602d910115b1e79a59bfdb0afc3d06d4558c5f8f114eac15a3281acccfd8948b10a508c22b1aee952c66c41d4c8

data/Gemfile

@@ -17,4 +17,5 @@ group :test do
   gem 'fakefs', require: 'fakefs/spec_helpers'
   gem 'rspec'
   gem 'simplecov', require: false
+  gem 'webmock', require: false
 end

data/README.md

@@ -15,10 +15,42 @@ Terminal ebook reader for EPUB files.
 ## How it works
 
 - `bin/start` runs the CLI and enters menu mode or opens a file directly.
+- `bootstrap` is the only runtime wiring boundary (`Bootstrap::ContainerFactory`).
 - 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.
 
+## Architecture boundaries
+
+- Hexagonal layering is enforced.
+- `core` contains domain models/services and the single ports root.
+- Ports are split by direction only:
+- `Core::Ports::Inbound::*` (driving boundary into application use cases).
+- `Core::Ports::Outbound::*` (driven dependencies implemented by adapters).
+- `application` contains use-case/workflow/service orchestration only.
+- `adapters` contains all input, UI, output, runtime, monitoring, and storage implementations.
+- `bootstrap` is the only composition root and the only layer that mutates/resolves the container.
+- Reader runtime controller graph composition is bootstrap-only (`ContainerFactory::ControllerComposition::ReaderBuilder`).
+
+Canonical runtime layout:
+
+```text
+lib/shoko/
+  core/ports/{inbound,outbound}
+  application/{use_cases,services,workflows}
+  adapters/{input,ui,output,runtime,storage,monitoring}
+  bootstrap/{container_factory,dependencies}
+  shared/
+```
+
+Inbound command boundary:
+
+- `Core::Ports::Inbound::CommandBus`
+- `Core::Ports::Inbound::ReaderIntentHandler`
+- `Core::Ports::Inbound::MenuIntentHandler`
+- Implemented by `Application::UseCases::CommandBus`
+- Input symbols are dispatched through `ReaderIntentCommand`, `MenuIntentCommand`, and `SharedIntentCommand`
+
 ## Usage
 
 From source:
@@ -34,12 +66,27 @@ Open a file directly:
 bin/start /path/to/book.epub
 ```
 
+Import a folder of ebooks from CLI:
+
+```bash
+bin/start /path/to/books-directory
+```
+
+This scans the directory recursively (skipping hidden files/folders), shows counts by format, and lets you:
+
+- import all discovered files
+- import only one file type
+- exit without importing
+
+After import, Shoko opens menu mode by default.
+
 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.
+- `-v`, `--version` Show version.
 - `-h`, `--help` Show help.
 
 ## Controls (basics)
@@ -69,7 +116,6 @@ Reader:
   - `config.json`
   - `annotations.json`, `bookmarks.json`, `progress.json`, `recent.json`
   - `downloads/` (Gutendex downloads)
-  - `epub_cache.json` (scan cache)
 - Cache: `~/.cache/shoko/`
 
 ## Logging and profiling
@@ -80,3 +126,56 @@ You can also configure logging with environment variables:
 - `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.
+
+## Testing
+
+Required guardrails lane:
+
+```bash
+bundle exec rake test:guardrails
+```
+
+Required non-fixture lane (runs 3 fixed seeds):
+
+```bash
+bundle exec rake test:required
+```
+
+Real-book fixture lane:
+
+```bash
+SHOKO_BOOK_FIXTURES=1 SHOKO_FIXTURES_DIR=/path/to/book-fixtures bundle exec rake test:fixtures
+```
+
+Full suite sanity:
+
+```bash
+bundle exec rspec
+```
+
+## Benchmarking
+
+Run the built-in snappiness benchmark:
+
+```bash
+bundle exec ruby script/bench/snappiness_benchmark.rb
+```
+
+The benchmark prints baseline vs optimized timings for:
+
+- `TextMetrics.visible_length` cache impact
+- `TextMetrics.visible_length` ASCII fast-path impact
+- `TextMetrics.truncate_to` ASCII fast-path impact
+- `TextMetrics.wrap_plain_text` cache impact
+- `TextMetrics.wrap_plain_text` result-cache impact
+- `LineAssembler.build` cache impact
+- `LineAssembler::Tokenizer.tokenize` cache impact
+- `LineAssembler.build` tokenize-cache impact
+- `LineAssembler.build` token-width-hints impact
+- `LineAssembler.build` token-pipeline combined impact
+- `WrappingService.wrap_window` prefetch-range reuse impact
+- `LineGeometryBuilder.build` repeated-line cell cache impact
+- `TerminalBuffer::Frame.write` ASCII fast-path impact
+- `LineContentComposer.compose` repeated-line cache impact
+- `ManifestShaFinder.sha` large-manifest lookup impact
+- `JsonCacheStore.manifest_rows` repeated-read cache impact

data/Rakefile

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
+require 'json'
+require 'English'
+require 'fileutils'
+require 'shellwords'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 
@@ -13,9 +17,84 @@ task quality: %i[spec rubocop]
 task default: :quality
 
 namespace :test do
+  module RSpecLane
+    module_function
+
+    RESULT_DIR = File.expand_path('tmp/rspec-results', __dir__)
+
+    def run!(name:, args:, env: {})
+      FileUtils.mkdir_p(RESULT_DIR)
+      output_path = File.join(RESULT_DIR, "#{name}.json")
+      command = ['bundle', 'exec', 'rspec', *args, '--format', 'json', '--out', output_path]
+
+      puts "==> #{name}: #{Shellwords.join(command)}"
+      success = system(env, *command)
+      pending = pending_count(output_path)
+
+      raise "Pending examples detected in #{name}: #{pending}" if pending.positive?
+      raise "RSpec failed in #{name} (exit #{$CHILD_STATUS.exitstatus})" unless success
+    end
+
+    def pending_count(path)
+      return 0 unless File.exist?(path)
+
+      payload = JSON.parse(File.read(path))
+      payload.dig('summary', 'pending_count').to_i
+    rescue JSON::ParserError => e
+      raise "Unable to parse RSpec JSON report at #{path}: #{e.message}"
+    end
+  end
+
+  desc 'Run architecture and wiring guardrail specs only'
+  task :guardrails do
+    FileUtils.mkdir_p(RSpecLane::RESULT_DIR)
+    fallback_report_path = File.join(RSpecLane::RESULT_DIR, 'fallback-report.json')
+    fallback_command = ['ruby', File.expand_path('script/architecture/fallback_report.rb', __dir__)]
+    puts "==> fallback-report: #{Shellwords.join(fallback_command)}"
+    fallback_payload = IO.popen(fallback_command, &:read)
+    File.write(fallback_report_path, fallback_payload)
+    raise 'Fallback report detected guardrail offenders' unless $CHILD_STATUS.success?
+
+    guardrail_targets = [
+      'spec/core/architecture',
+      'spec/adapters/input/command_bus_only_bindings_spec.rb',
+      'spec/adapters/input/command_binding_completeness_spec.rb',
+      'spec/bootstrap/dependencies/bundle_guardrails_spec.rb',
+    ]
+
+    RSpecLane.run!(
+      name: 'guardrails',
+      args: [*guardrail_targets, '--seed', '10101']
+    )
+  end
+
+  desc 'Run required non-fixture specs across fixed deterministic seeds'
+  task :required do
+    %w[10101 20202 30303].each do |seed|
+      RSpecLane.run!(
+        name: "required-seed-#{seed}",
+        args: ['--tag', '~requires_book_fixtures', '--seed', seed]
+      )
+    end
+  end
+
+  desc 'Run fixture-dependent specs only'
+  task :fixtures do
+    env = {
+      'SHOKO_BOOK_FIXTURES' => '1',
+    }
+    env['SHOKO_FIXTURES_DIR'] = ENV['SHOKO_FIXTURES_DIR'] if ENV.key?('SHOKO_FIXTURES_DIR')
+
+    RSpecLane.run!(
+      name: 'fixtures',
+      env: env,
+      args: ['--tag', 'requires_book_fixtures', '--seed', '30303']
+    )
+  end
+
   desc 'Run tests with coverage'
   task :coverage do
-    ENV['COVERAGE'] = 'true'
+    ENV['COVERAGE'] = '1'
     Rake::Task['spec'].invoke
   end
 end

data/bin/shoko

@@ -7,13 +7,19 @@ $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
 begin
   # Only activate Bundler when explicitly running under it (e.g. bundle exec).
-  if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
-    require 'bundler/setup'
-  end
+  require 'bundler/setup' if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
 rescue LoadError
   # Running without Bundler (e.g., installed gem).
 end
 
 require 'shoko'
 
-Shoko::CLI.run
+Shoko::Adapters::Input::CLI.run(
+  ARGV,
+  app_factory: lambda do |epub_path:, log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_unified_application(epub_path: epub_path, log_config: log_config)
+  end,
+  folder_import_factory: lambda do |log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_cli_folder_import_context(log_config: log_config)
+  end
+)

data/bin/start

@@ -7,13 +7,19 @@ $LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
 begin
   # Only activate Bundler when explicitly running under it (e.g. bundle exec).
-  if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
-    require 'bundler/setup'
-  end
+  require 'bundler/setup' if ENV['BUNDLE_GEMFILE'] || ENV['BUNDLE_BIN_PATH']
 rescue LoadError
   # Running without Bundler (e.g., installed gem).
 end
 
 require 'shoko'
 
-Shoko::CLI.run
+Shoko::Adapters::Input::CLI.run(
+  ARGV,
+  app_factory: lambda do |epub_path:, log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_unified_application(epub_path: epub_path, log_config: log_config)
+  end,
+  folder_import_factory: lambda do |log_config:|
+    Shoko::Bootstrap::ContainerFactory.build_cli_folder_import_context(log_config: log_config)
+  end
+)

data/docs/architecture/hexagonal-adherence-checklist.md

@@ -0,0 +1,173 @@
+# Hexagonal Architecture Adherence Checklist (Zero-Fallback Cutover)
+
+Date: 2026-03-03  
+Scope: `lib/shoko/**` runtime + architecture guardrails/spec gates
+
+## Completed
+
+- [x] Removed optional DI resolution usage:
+  - zero `resolve_optional(` occurrences in `lib/shoko`.
+  - `DependencyContainer` exposes mandatory `resolve` only.
+- [x] Removed two-phase reader runtime wiring from public API:
+  - no `defer_runtime_setup`.
+  - no `attach_runtime_components!`.
+  - reader runtime graph is single-phase via constructor-time runtime factory.
+- [x] Completed inbound boundary ownership migration:
+  - adapters no longer include inbound intent handler ports.
+  - adapter-owned intent handler classes removed.
+  - application intent handlers added under `application/use_cases/intents`.
+- [x] Removed reflection-style probing/dispatch globally in runtime code:
+  - zero `respond_to?(` occurrences.
+  - zero `public_send` occurrences.
+  - zero dynamic `send(` occurrences.
+- [x] Removed collaborator-probing rescues:
+  - zero `rescue NoMethodError` collaborator probing occurrences.
+- [x] Removed known swallow/fallback runtime behaviors in strict paths:
+  - reader quit/save progress now fails fast.
+  - event bus subscriber failures are logged then re-raised.
+  - render state writer failures are logged then re-raised.
+  - document path resolver no longer masks resolver failures.
+  - kitty image line renderer no longer suppresses renderer exceptions.
+- [x] Removed known mechanical migration violations:
+  - bare `rescue =>` patterns removed (runtime code).
+  - inline `... rescue ...` expressions removed from runtime code.
+- [x] Boundary translation hardened:
+  - document load failures are translated to `Shoko::BookParseError`.
+  - dictionary catalog boundary uses typed `CatalogError < Shoko::Error`.
+  - cache import boundary propagates typed malformed-book failures (`BookParseError` / `MalformedBookInputError`) with no adapter shim fallback.
+- [x] Completed inbound handler decoupling from adapter controllers:
+  - application intent handlers now depend on typed executors (`ReaderIntentExecutor` / `MenuIntentExecutor`).
+  - adapter controller dispatch moved to adapter bridges.
+  - no `@reader_controller.` / `@menu_controller.` loopback remains in app intent handlers.
+- [x] Replaced bootstrap session contexts with launch-state ports/adapters:
+  - added `Core::Ports::Outbound::ReaderLaunchState` and `MenuLaunchState`.
+  - runtime adapters added in `adapters/runtime/session_state`.
+  - `ReaderSessionContext` / `MenuSessionContext` removed from bootstrap.
+  - application workflows and unified app now use launch-state ports.
+- [x] Enforced symbol-only input command execution contract:
+  - `Adapters::Input::Commands.execute` now rejects non-symbol commands.
+  - legacy proc/object/array execution paths removed.
+- [x] Optional dependency hard-error path introduced for sqlite execution:
+  - added `Shared::OptionalDependency.require_gem!`.
+  - added `DependencyUnavailableError` and used it in sqlite runtime load path.
+  - dictionary repository now remains wired in auto mode; missing sqlite fails explicitly on invocation.
+- [x] Fixed reader relaunch crash after closing/opening another book:
+  - reader launch state now clears background worker on reader exit (`RuntimeExecution#run_reader` ensure block), preventing reuse of stopped workers.
+- [x] Added canonical zero-fallback architecture guardrails:
+  - `spec/core/architecture/no_rescue_literal_default_spec.rb`
+  - `spec/core/architecture/no_overlapping_rescue_chains_spec.rb`
+  - `spec/core/architecture/no_stale_optional_resolution_spec.rb`
+  - `spec/core/architecture/no_standard_error_rescue_spec.rb`
+- [x] Removed duplicate/overlapping rescue chains that created unreachable branches.
+  - importer translation chains fixed (`fb2`, `kindle`, `pdf`, `rtf`).
+  - cache/string translation chain fixed (`lazy_file_string`).
+  - CLI contract coercion rescue overlaps fixed.
+  - bootstrap background worker fallback contract rescue overlap fixed.
+- [x] Removed stale optional-resolution scaffolding in reader composition.
+  - `ReaderBuilder#resolve_many` now has a single deterministic resolve path.
+- [x] Eliminated explicit `rescue StandardError` usage in `lib/shoko/**`.
+  - fail-fast boundaries now use explicit/translated rescue flows without `rescue StandardError`.
+- [x] Completed hard-cutover removal of legacy callable factories.
+  - removed DI keys/usages of `:document_service_factory` and `:background_worker_factory`.
+  - replaced with typed outbound ports `DocumentLoader` and `BackgroundWorkerBuilder`.
+- [x] Added typed progress boundary and removed adapter-to-adapter coupling in the progress path.
+  - new port `Core::Ports::Outbound::ProgressRepository`.
+  - new core value `Core::Models::ReadingProgress`.
+  - input adapter progress actions now consume typed core progress data only.
+- [x] Removed Proc-type migration fallbacks from runtime paths.
+  - zero `is_a?(Proc)` checks remain in `lib/shoko`.
+- [x] Removed implicit `NullRuntimeConfig` fallback expressions from runtime code.
+  - runtime config is now explicit at composition boundaries and test builders.
+- [x] Removed `rescue Exception` and bare string raises from `lib/shoko`.
+  - `rescue Exception`: `0`
+  - `raise '...'` / `raise "..."`: `0`
+- [x] Added permanent guardrails for zero-fallback constraints.
+  - `spec/core/architecture/no_rescue_exception_spec.rb`
+  - `spec/core/architecture/no_bare_string_raise_spec.rb`
+  - `spec/core/architecture/no_implicit_null_runtime_config_spec.rb`
+  - `spec/core/architecture/no_legacy_factory_keys_spec.rb`
+  - `spec/core/architecture/no_proc_type_fallbacks_spec.rb`
+- [x] Fixed post-cutover runtime regressions in browse/menu flow.
+  - directory scanner recursion now works (books populate in Browse).
+  - scanner roots narrowed to explicit book directories by default, with opt-in overrides via `SHOKO_BOOK_SCAN_DIRS`.
+  - metadata extraction wiring includes required `path_ops` / `file_probe`.
+  - terminal and menu styling normalize binary-encoded text safely for UTF-8 rendering.
+  - annotation editor session/controller event handling now enforces hash payloads; non-event return values (e.g. cursor timestamp floats) are ignored safely.
+- [x] Completed fatal external-input hard-break semantics across runtime boundaries.
+  - added `FatalExternalInputError` hierarchy with typed subclasses (`MalformedBookInputError`, `MalformedMetadataInputError`, `MalformedDictionaryInputError`).
+  - top boundaries now terminate with exit code `2` on fatal external input (`CLI`, menu lifecycle, reader lifecycle).
+  - fatal logs use stable event IDs (`fatal.external_input.book|metadata|dictionary`).
+- [x] Removed rescue-fallback defaults and hardened guardrails to enforce zero fallback.
+  - AST-based analyzer now detects literal defaults (`[]`, `{}`, `''`, `""`, booleans, symbols, numeric literals) and variable passthrough.
+  - added guardrails:
+    - `no_rescue_numeric_default_spec.rb`
+    - `no_swallowing_rescue_spec.rb`
+    - `no_noop_reraise_rescue_spec.rb`
+    - `no_mixed_symbol_string_key_reads_in_application_spec.rb`
+    - `no_cross_adapter_runtime_coupling_spec.rb`
+  - added deterministic report: `script/architecture/fallback_report.rb` (wired into `test:guardrails`).
+- [x] Completed typed boundary migration for key menu/runtime flows.
+  - introduced typed models used across workflow boundaries:
+    - `MenuBook`
+    - `AnnotationSelection`
+    - `PendingJumpPayload`
+    - `DictionaryCatalogEntry`
+  - removed mixed symbol/string dual-key normalization from `application/**` (`x[:k] || x['k']`).
+- [x] Removed cross-adapter runtime coupling in flagged paths.
+  - `DocumentLoaderAdapter` now depends on outbound `BookCachePipelineFactory` port.
+  - output terminal runtime config no longer depends on runtime-adapter null type directly.
+- [x] Hard-deleted legacy command/fallback APIs.
+  - removed unused bookmark command factory methods (`remove_bookmark`, `toggle_bookmark`, `jump_to_bookmark`).
+  - removed cache-import compatibility wrapper error type (`CacheImportAdapter::ImportError`).
+
+## Open Items
+
+- [ ] Persist benchmark baselines and enforce CI threshold checks.
+- [ ] Fixture lane is blocked locally by missing required books (see verification snapshot).
+- [ ] Extend optional dependency hard-error semantics to remaining optional capability execution paths (not only sqlite).
+
+## Verification Checklist
+
+- [x] `bundle exec rspec spec/core/architecture spec/bootstrap/dependencies`
+- [x] `bundle exec rake test:guardrails`
+- [x] `bundle exec rake test:required`
+- [x] `bundle exec rspec` (fixtures excluded by default tag filter)
+- [ ] `bundle exec rake test:fixtures` (blocked locally)
+
+## Verification Snapshot
+
+- `bundle exec rspec spec/core/architecture spec/bootstrap/dependencies`:
+  - 101 examples, 0 failures.
+- `bundle exec rake test:guardrails`:
+  - pass (`fallback_report` summary all zero).
+- `bundle exec rake test:required`:
+  - pass for seeds `10101`, `20202`, `30303` (973 examples/seed, 0 failures).
+- `bundle exec rspec`:
+  - 973 examples, 0 failures (with `requires_book_fixtures` excluded by default).
+- `bundle exec rake test:fixtures`:
+  - blocked by missing files:
+    - `Persuasion (Jane Austen).mobi`
+    - `Pride Prejudice (Jane Austen).azw`
+    - `Emma (Jane Austen).azw3`
+    - `Pride And Prejudice (Austen Jane).rtf`
+- Artifact sweeps (`lib/shoko`):
+  - `resolve_optional(`: `0`
+  - `rescue StandardError`: `0`
+  - `rescue Exception`: `0`
+  - bare `rescue =>`: `0`
+  - bare string raise (`raise '...'` / `raise "..."`): `0`
+  - duplicate `rescue ArgumentError, ArgumentError`: `0`
+  - duplicate/overlapping same-class rescue chains with unreachable fallback branches: `0`
+  - stale optional resolution ternary (`optional ? resolve : resolve`): `0`
+  - inline `... rescue ...` expressions: `0`
+  - `rescue NoMethodError` probing: `0`
+  - `respond_to?` / `public_send` / dynamic `send(`: `0`
+  - `fallback_report` zero-fallback summary:
+    - `fallback_literal_defaults`: `0`
+    - `numeric_rescue_defaults`: `0`
+    - `no_op_reraise_rescues`: `0`
+    - `fatal_input_swallow_rescues`: `0`
+    - `mixed_key_reads_application`: `0`
+  - legacy factory keys/usages (`document_service_factory|background_worker_factory`): `0`
+  - proc-type fallbacks (`is_a?(Proc)`): `0`
+  - implicit null runtime fallback expression (`|| ...NullRuntimeConfig.instance`): `0`

data/lib/{zip.rb → shoko/adapters/book_sources/archive/zip_reader.rb}

@@ -5,6 +5,7 @@
 #
 # Public API:
 #   Zip::File.open(path) { |zip| ... }
+#   zip.entries -> Array<Zip::Entry>
 #   zip.read(entry_path) -> String (binary)
 #   zip.find_entry(entry_path) -> entry or nil
 #   zip.close ; zip.closed?
@@ -269,21 +270,9 @@ module Zip
     attr_reader :max_entry_compressed, :max_entry_uncompressed, :max_total_uncompressed
 
     def initialize(max_entry_uncompressed:, max_entry_compressed:, max_total_uncompressed:)
-      @max_entry_uncompressed = LimitResolver.resolve(
-        max_entry_uncompressed,
-        env: 'SHOKO_ZIP_MAX_ENTRY_BYTES',
-        default: Limits::MAX_ENTRY_UNCOMPRESSED
-      )
-      @max_entry_compressed = LimitResolver.resolve(
-        max_entry_compressed,
-        env: 'SHOKO_ZIP_MAX_ENTRY_COMPRESSED_BYTES',
-        default: Limits::MAX_ENTRY_COMPRESSED
-      )
-      @max_total_uncompressed = LimitResolver.resolve(
-        max_total_uncompressed,
-        env: 'SHOKO_ZIP_MAX_TOTAL_BYTES',
-        default: Limits::MAX_TOTAL_UNCOMPRESSED
-      )
+      @max_entry_uncompressed = LimitResolver.resolve(max_entry_uncompressed, default: Limits::MAX_ENTRY_UNCOMPRESSED)
+      @max_entry_compressed = LimitResolver.resolve(max_entry_compressed, default: Limits::MAX_ENTRY_COMPRESSED)
+      @max_total_uncompressed = LimitResolver.resolve(max_total_uncompressed, default: Limits::MAX_TOTAL_UNCOMPRESSED)
       @total_uncompressed_bytes = 0
     end
 
@@ -351,34 +340,28 @@ module Zip
     end
   end
 
-  # Resolves limit values from arguments, environment, or defaults
+  # Resolves limit values from explicit arguments or defaults.
   class LimitResolver
-    def self.resolve(value, env:, default:)
-      new(value, env, default).resolve
+    def self.resolve(value, default:)
+      new(value, default).resolve
     end
 
-    def initialize(value, env, default)
+    def initialize(value, default)
       @value = value
-      @env = env
       @default = default
     end
 
     def resolve
-      candidate = value_or_env
-      parsed = parse_integer(candidate)
+      parsed = parse_integer(@value)
       valid_positive_or_default(parsed)
     end
 
     private
 
-    def value_or_env
-      @value || ENV.fetch(@env, nil)
-    end
-
     def parse_integer(candidate)
+      return nil if candidate.nil?
+
       Integer(candidate)
-    rescue StandardError
-      nil
     end
 
     def valid_positive_or_default(parsed)
@@ -479,8 +462,8 @@ module Zip
 
     def close_inflater(inflater)
       inflater&.close
-    rescue StandardError
-      nil
+    rescue Shoko::Error
+      raise
     end
 
     def decompress_all(inflater, entry, remaining_bytes)
@@ -657,7 +640,7 @@ module Zip
 
     def self.close_safely(zip_file)
       zip_file.close
-    rescue StandardError
+    rescue Shoko::Error
       # ignore close errors
     end
 
@@ -674,7 +657,7 @@ module Zip
       @io = @state.io
       @entries = @state.entries
       build_index!
-    rescue StandardError
+    rescue Shoko::Error
       close
       raise
     end
@@ -692,6 +675,10 @@ module Zip
       @entries[normalized_path]
     end
 
+    def entries
+      @entries.values
+    end
+
     def read(path)
       entry = find_entry_or_raise(path)
       validate_entry_readable(entry)
@@ -730,3 +717,30 @@ module Zip
     end
   end
 end
+
+module Shoko
+  module Adapters
+    module BookSources
+      module Archive
+        # Adapter-owned archive facade used by book-source importers/loaders.
+        module ZipReader
+          module_function
+
+          def open(path, runtime_config: nil, &block)
+            Zip::File.open(path, **zip_limit_kwargs(runtime_config), &block)
+          end
+
+          def zip_limit_kwargs(runtime_config)
+            return {} unless runtime_config
+
+            {
+              max_entry_uncompressed_bytes: runtime_config.zip_max_entry_uncompressed_bytes,
+              max_entry_compressed_bytes: runtime_config.zip_max_entry_compressed_bytes,
+              max_total_uncompressed_bytes: runtime_config.zip_max_total_uncompressed_bytes
+            }
+          end
+        end
+      end
+    end
+  end
+end