epub_tools 0.5.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830a3d6d88e106980c19f5c19ea5e0365e39499cc90c0c32ff5c204b7cf24abd
-  data.tar.gz: 7898e152850e5e390842e04a56947e2e88623bd1e5b65525561423da7a5ec744
+  metadata.gz: 79e280c3b4dd2f362ee8c013e98f6ac44a9ea5c18535bd0b6dba67c1a5a49f52
+  data.tar.gz: 1c6a8eac67cced477f7312eb5ec50091048c5bf5932264b5de9f1396c8bd6879
 SHA512:
-  metadata.gz: 7b852a22e630ad9177c5adc692326dac517b904c687e6cbe3874b7e1f43347a53cfdd381cb5b66b7feaf6faafae75129510aac6a23f84f4b3e82734ae84dc8ac
-  data.tar.gz: 4602e5922dbdf257436445546b14501a0064861af84fea854feb0a10ed2ef651d6eefb8009ce459c7463c50c3383eabe3220a10d856271ad38c49cc768b8da5f
+  metadata.gz: fe396cf56d97ee602ad326f50614f21edc31b0af9ef0ed82656826f567e5dc5ad7df92620e1ba6b79203dbabac75ee03cff2c2ec597cb8763b35ac601ee72a79
+  data.tar.gz: 6a293f1075e4ff4b2ee26a2e11c2aedc5ec39b56d638dacb0c8feae916eb405024be0006b7fa4310afa333b871429130c6ec2265f236b9b7e998591103066ba4

data/.github/workflows/ci.yml

@@ -12,14 +12,9 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        ruby: ['3.2', '3.3', '3.4']
     steps:
-      - uses: actions/checkout@v3
-      - uses: ruby/setup-ruby@v1
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1 # Ruby version from .tool-versions
         with:
-          ruby-version: ${{ matrix.ruby }}
-      - run: gem install bundler
-      - run: bundle install --jobs 4 --retry 3
+          bundler-cache: true
       - run: bundle exec rake test

data/.gitignore

@@ -6,6 +6,5 @@
 vendor/bundle/
 *.gem
 
-text_style_classes.yaml
 
 **/.claude/

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.5
+ruby 4.0.9

data/CLAUDE.md

@@ -59,40 +59,38 @@ gem install ./epub_tools-*.gem
 ### Core Components
 
 - **Main Module** (`lib/epub_tools.rb`): Entry point that requires all components
-- **CLI System** (`lib/epub_tools/cli/`): Object-oriented command-line interface
-  - `Runner`: Main CLI runner that handles command dispatch
-  - `CommandRegistry`: Manages available commands and their configurations
-  - `OptionBuilder`: Builds command-line option parsers
-  - `CommandOptionsConfigurator`: Handles command-specific option configuration
+- **CLI** (`lib/epub_tools/cli.rb`): `CLI::COMMANDS` maps each command to its class, summary and flags
 - **Core Classes**: Individual operation classes for EPUB manipulation
   - `XHTMLExtractor`: Extracts XHTML files from EPUB archives
-  - `SplitChapters`: Splits XHTML files into separate chapters
-  - `EpubInitializer`: Creates new EPUB directory structure (uses configuration pattern)
+  - `PDFConverter`: Converts chapter PDFs (named `12a Title.pdf`) into chapter XHTMLs via poppler's `pdftohtml -xml`
+  - `SplitChapters`: Splits XHTML files into separate chapters at Chapter N / Chapter N (continued) / Prologue markers
+  - `EpubInitializer`: Creates new EPUB directory structure
   - `AddChapters`: Adds chapter files to existing EPUB
   - `PackEbook`: Packages EPUB directories into .epub files
   - `UnpackEbook`: Unpacks .epub files into directories
-  - `CompileBook`: Full workflow combining multiple operations (uses workspace pattern)
-- **Supporting Classes**: SOLID-designed helper classes
-  - `CompileWorkspace`: Manages build directories for CompileBook
+  - `SetCover`: Adds or replaces a cover, in a packed EPUB (`cover` command) or an unpacked one (used by `EpubInitializer`)
+- **Workflow Classes**: Orchestrators built on a shared base class
+  - `BookBuilder`: Base class with template method pattern (extract → split → convert PDFs → validate → add → pack)
+  - `CompileBook`: Creates a new EPUB from source EPUBs (inherits BookBuilder)
+  - `AppendBook`: Appends chapters from source EPUBs to an existing EPUB (inherits BookBuilder)
+- **Supporting Classes**
   - `ChapterValidator`: Validates chapter sequence completeness
-  - `EpubConfiguration`: Configuration object for EPUB initialization
-  - `XhtmlGenerator`: Generates XHTML templates for EPUB content
-  - `EpubMetadataBuilder`: Builds OPF metadata content
-  - `EpubFileWriter`: Handles EPUB file writing operations
+  - `PDFLayout`: Rebuilds paragraphs, italics, scene breaks and lists from `pdftohtml -xml` line positions
+  - `ChapterOrder`: Reading order of chapter files (1, 1_5, 1a, 1b, 2); inserts added chapters in place
+  - `StyleFinder` / `XHTMLCleaner`: Find Google Docs' bold/italic classes and clean split chapters with them
 
 ### CLI Architecture
 
-The CLI uses a registry-based system where:
-1. Commands are registered in `cli.rb` with their class, required parameters, and defaults
-2. The `Runner` dispatches to the appropriate command class
-3. The `CommandOptionsConfigurator` handles command-specific option setup
+1. Each command is an entry in `CLI::COMMANDS`: its class, usage summary, and flags as `[short, long, description, option key]`
+2. Flags whose description ends in `(required)` are enforced; commands get `-q/--quiet` unless marked `verbose: false`
+3. `CLI.run` parses the flags and calls `command_class.new(options).run`
 4. Each command class implements a `run` method and uses the `Loggable` mixin for verbose output
 
 ### Dependencies
 
 - **nokogiri**: XML/HTML parsing for EPUB content
 - **rubyzip**: ZIP file manipulation for EPUB packaging
-- **rake**: Build tasks and testing
+- **rake**: Build tasks and testing (development only)
 - **minitest**: Testing framework
 - **rubocop**: Code linting with custom configuration
 - **simplecov**: Test coverage reporting
@@ -111,14 +109,12 @@ The CLI uses a registry-based system where:
 Tests use Minitest with:
 - `test_helper.rb` sets up SimpleCov coverage
 - Tests in `test/` directory follow `*_test.rb` naming
-- CLI tests verify command registration and option parsing
+- CLI tests verify option parsing and dispatch; `cli_commands_test.rb` runs the real executable
 - Individual component tests verify core functionality
 
 ### Code Quality
 
-The codebase follows SOLID principles with:
-- **Single Responsibility**: Classes have focused, well-defined purposes
-- **Open/Closed**: Extensible design through composition and dependency injection
-- **Dependency Inversion**: Configuration objects and factory patterns
+- One class per operation, each with an options hash and a `run` method
+- Prefer plain methods, stdlib and the existing dependencies over new helper classes
 
 RuboCop configuration excludes test files from metrics cops while maintaining strict standards for production code.

data/Gemfile

@@ -1,23 +1,20 @@
 # frozen_string_literal: true
 
-ruby '>= 3.2'
-
 source 'https://rubygems.org'
 
-gem 'nokogiri', '~> 1.18'
-gem 'rake', '~> 13.2'
-gem 'rubyzip', '~> 3.2'
+gemspec
 
 group :test, :development do
   gem 'minitest', '~> 6.0'
+  gem 'rake', '~> 13.2'
   gem 'rubocop', '~> 1.75', require: false
-  gem 'rubocop-minitest', '~> 0.39.0', require: false
+  gem 'rubocop-minitest', '~> 0.41.0', require: false
   gem 'rubocop-rake', '~> 0.7.1', require: false
   gem 'simplecov', require: false
 end
 
 group :doc do
-  gem 'rdoc', '~> 7.2'
+  gem 'rdoc', '~> 8.1'
   gem 'webrick', '~> 1.9'
-  gem 'yard', '~> 0.9.37'
+  gem 'yard', '~> 0.9.44'
 end

data/Gemfile.lock

@@ -1,85 +1,95 @@
+PATH
+  remote: .
+  specs:
+    epub_tools (0.9.0)
+      nokogiri (~> 1.19)
+      rubyzip (~> 3.7)
+
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    date (3.5.1)
-    docile (1.4.1)
     drb (2.2.3)
-    erb (6.0.2)
-    json (2.18.1)
-    language_server-protocol (3.17.0.5)
+    erb (6.0.7)
+    json (3.1.0)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    minitest (6.0.2)
+    logger (1.7.0)
+    minitest (6.1.0)
       drb (~> 2.0)
-      prism (~> 1.5)
-    nokogiri (1.19.1-aarch64-linux-gnu)
+      prism (>= 1.5, < 3)
+    nokogiri (1.19.7-aarch64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.1-aarch64-linux-musl)
+    nokogiri (1.19.7-aarch64-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.1-arm-linux-gnu)
+    nokogiri (1.19.7-arm-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.1-arm-linux-musl)
+    nokogiri (1.19.7-arm-linux-musl)
       racc (~> 1.4)
-    nokogiri (1.19.1-arm64-darwin)
+    nokogiri (1.19.7-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.1-x86_64-darwin)
+    nokogiri (1.19.7-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.19.1-x86_64-linux-gnu)
+    nokogiri (1.19.7-x86_64-linux-gnu)
       racc (~> 1.4)
-    nokogiri (1.19.1-x86_64-linux-musl)
+    nokogiri (1.19.7-x86_64-linux-musl)
       racc (~> 1.4)
-    parallel (1.27.0)
-    parser (3.3.10.2)
+    parallel (2.3.0)
+    parser (3.3.13.0)
       ast (~> 2.4.1)
       racc
-    prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
+    prism (2.1.0)
+    prism (2.1.0-aarch64-linux-gnu)
+    prism (2.1.0-aarch64-linux-musl)
+    prism (2.1.0-arm-linux-gnu)
+    prism (2.1.0-arm-linux-musl)
+    prism (2.1.0-arm64-darwin)
+    prism (2.1.0-x86_64-darwin)
+    prism (2.1.0-x86_64-linux-gnu)
+    prism (2.1.0-x86_64-linux-musl)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
-    rdoc (7.2.0)
+    rake (13.4.2)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.1.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
-    regexp_parser (2.11.3)
-    rubocop (1.84.2)
-      json (~> 2.3)
+    regexp_parser (2.13.1)
+    rubocop (1.92.2)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 2.9.3, < 3.0)
+      regexp_parser (>= 2.11.3, < 3.0)
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.51.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.7)
-    rubocop-minitest (0.39.1)
+      prism (>= 1.7)
+    rubocop-minitest (0.41.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.75.0, < 2.0)
+      rubocop (>= 1.89.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
-    rubyzip (3.2.2)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    stringio (3.2.0)
+    rubyzip (3.7.0)
+    simplecov (1.3.2)
     tsort (0.2.0)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
     webrick (1.9.2)
-    yard (0.9.38)
+    yard (0.9.45)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -92,20 +102,16 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  epub_tools!
   minitest (~> 6.0)
-  nokogiri (~> 1.18)
   rake (~> 13.2)
-  rdoc (~> 7.2)
+  rdoc (~> 8.1)
   rubocop (~> 1.75)
-  rubocop-minitest (~> 0.39.0)
+  rubocop-minitest (~> 0.41.0)
   rubocop-rake (~> 0.7.1)
-  rubyzip (~> 3.2)
   simplecov
   webrick (~> 1.9)
-  yard (~> 0.9.37)
-
-RUBY VERSION
-   ruby 3.4.5p51
+  yard (~> 0.9.44)
 
 BUNDLED WITH
-   2.7.0
+  4.0.24

data/README.md

@@ -2,12 +2,13 @@
 
 [![Build Status](https://github.com/jaimerodas/epub_tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimerodas/epub_tools/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Gem Version](https://badge.fury.io/rb/epub_tools.svg)](https://badge.fury.io/rb/epub_tools)
 
-**TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
+**TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, unpack, compile, and append to EPUB books.
 
 ## Installation
 
 ### Requirements
-- Ruby 3.2 or higher
+- Ruby 4.0 or higher
+- [poppler](https://poppler.freedesktop.org/) (`brew install poppler`), only for PDF sources
 
 ### Install from RubyGems
 ```bash
@@ -32,10 +33,13 @@ Commands:
 - `init`      Initialize a new EPUB directory structure
 - `extract`   Extract XHTML files from EPUB archives
 - `split`     Split an XHTML file into separate chapter files
+- `pdf`       Convert chapter PDFs into chapter XHTML files
 - `add`       Add chapter XHTML files into an existing EPUB
 - `pack`      Package an EPUB directory into a `.epub` file
 - `unpack`    Unpack a `.epub` file into a directory
-- `compile`   Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB
+- `cover`     Add or replace the cover of a `.epub` file
+- `compile`   Takes EPUBs and/or chapter PDFs in a dir and compiles them into a single EPUB
+- `append`    Takes EPUBs and/or chapter PDFs in a dir and appends them to an existing EPUB
 
 Run `epub-tools COMMAND --help` for details on options.
 
@@ -59,48 +63,84 @@ epub-tools pack -i epub_dir -o MyBook.epub
 # Unpack EPUB
 epub-tools unpack -i MyBook.epub -o unpacked_dir
 
+# Add or replace the cover of an existing EPUB (keeps a MyBook.epub.bak backup)
+epub-tools cover -i MyBook.epub -c cover.jpg
+
 # Full compile workflow: extract, split, initialize, add, and pack into one EPUB
 epub-tools compile -t "My Book" -a "Author Name" -s source_epubs -c cover.jpg -o MyBook.epub
+
+# Append chapters from new EPUBs to an existing book
+epub-tools append -s new_epubs -t MyBook.epub
+```
+
+### Chapter PDFs
+`compile` and `append` also take a directory of chapter PDFs, one chapter per file, named
+`<number><optional letters> <Title>.pdf`:
+
+```
+0 Dramatis Personae.pdf        -> "Dramatis Personae" (chapter 0 is front matter)
+1 First Day.pdf                -> "Chapter 1: First Day"
+1a An Interlude.pdf            -> "Chapter 1a: An Interlude", between 1 and 2
+Epilogue One Month.pdf         -> "Epilogue: One Month", after every chapter
 ```
 
- (Legacy script references removed; see CLI Usage above)
+Paragraphs, italics, bold and scene breaks (`***`) are rebuilt from the PDF layout, and the heading typed
+inside the PDF is replaced by the one from the filename. To add new chapters later, put only the new PDFs
+in a directory and `append` them; chapters are slotted into reading order, even a side chapter like `12a`
+added after chapter 13 is already in the book. Chapters that are already in the book are refused.
+
+```bash
+epub-tools compile -t "My Book" -a "Author Name" -s chapter_pdfs -o MyBook.epub
+epub-tools append -s new_chapter_pdfs -t MyBook.epub
+```
 
 ## Library Usage
 Use the library directly in Ruby:
 ```ruby
 require 'epub_tools'
 
-# Extract XHTML
+# Full compile workflow: extract, split, and compile into a new EPUB
+EpubTools::CompileBook.new(
+  title: 'My Book', author: 'Author Name',
+  source_dir: 'source_epubs', cover_image: 'cover.jpg',
+  output_file: 'MyBook.epub'
+).run
+
+# Append chapters from new EPUBs to an existing book
+EpubTools::AppendBook.new(
+  source_dir: 'new_epubs',
+  target_epub: 'MyBook.epub'
+).run
+
+# Individual steps can also be used standalone:
+
+# Extract XHTML files from EPUBs
 EpubTools::XHTMLExtractor.new(
-  source_dir: 'source_epubs',
-  target_dir: 'xhtml_output',
-  verbose: true
-).extract_all
+  source_dir: 'source_epubs', target_dir: 'xhtml_output'
+).run
 
-# Split chapters
+# Split a multi-chapter XHTML into individual chapter files
 EpubTools::SplitChapters.new(
-  'xhtml_output/chapter1.xhtml',
-  'My Book',
-  'chapters',
-  'chapter'
+  input_file: 'xhtml_output/chapter1.xhtml', book_title: 'My Book',
+  output_dir: 'chapters'
 ).run
 
-# Initialize EPUB
+# Initialize a new EPUB directory structure
 EpubTools::EpubInitializer.new(
-  'My Book',
-  'Author Name',
-  'epub_dir',
-  'cover.jpg'
+  title: 'My Book', author: 'Author Name',
+  destination: 'epub_dir', cover_image: 'cover.jpg'
 ).run
 
-# Add chapters
-EpubTools::AddChapters.new('chapters', 'epub_dir/OEBPS').run
+# Add chapter files into an EPUB
+EpubTools::AddChapters.new(
+  chapters_dir: 'chapters', oebps_dir: 'epub_dir/OEBPS'
+).run
 
-# Pack EPUB
-EpubTools::PackEbook.new('epub_dir', 'MyBook.epub').run
+# Package an EPUB directory into a .epub file
+EpubTools::PackEbook.new(input_dir: 'epub_dir', output_file: 'MyBook.epub').run
 
-# Unpack EPUB
-EpubTools::UnpackEbook.new('MyBook.epub', 'unpacked_dir').run
+# Unpack a .epub file into a directory
+EpubTools::UnpackEbook.new(epub_file: 'MyBook.epub', output_dir: 'unpacked_dir').run
 ```
 ## Development & Testing
 Clone the repo and install dependencies:

data/bin/epub-tools

@@ -3,6 +3,4 @@
 
 require_relative '../lib/epub_tools'
 
-# Use the new object-oriented CLI architecture
-runner = EpubTools::CLI.create_runner
-runner.run(ARGV)
+EpubTools::CLI.run(ARGV)

data/epub_tools.gemspec

@@ -13,14 +13,13 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split("\n")
   spec.require_paths = ['lib']
   spec.executables   = ['epub-tools']
-  spec.required_ruby_version = '>= 3.2'
+  spec.required_ruby_version = '>= 4.0'
   spec.metadata = {
     'source_code_uri' => 'https://github.com/jaimerodas/epub_tools/tree/main',
     'homepage_uri' => 'https://github.com/jaimerodas/epub_tools',
     'rubygems_mfa_required' => 'true'
   }
 
-  spec.add_dependency 'nokogiri', '~> 1.18'
-  spec.add_dependency 'rake', '~> 13.2'
-  spec.add_dependency 'rubyzip', '~> 3.2'
+  spec.add_dependency 'nokogiri', '~> 1.19'
+  spec.add_dependency 'rubyzip', '~> 3.7'
 end

data/lib/epub_tools/add_chapters.rb

@@ -1,9 +1,9 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require 'nokogiri'
 require 'fileutils'
 require_relative 'loggable'
+require_relative 'chapter_order'
 
 module EpubTools
   # Moves new chapters into an unpacked EPUB
@@ -32,9 +32,10 @@ module EpubTools
     # It works like this:
     # - First, the *.xhtml files are moved from +chapters_dir+ over to +epub_dir+
     # - Then, new entries will be added to the manifest and spine of the EPUB's +package.opf+ file.
-    #   It will sort the files by extracting the chapter number.
-    # - Finally, it will update the +nav.xhtml+ file with the new chapters. Note that if there's a
-    #   file named +chapter_0.xhtml+, it will be added to the +nav.xhtml+ as the Prologue.
+    #   Chapters are placed in reading order by their number (+chapter_12a+ goes between 12 and 13),
+    #   even when the book already contains later chapters.
+    # - Finally, it will update the +nav.xhtml+ file with the new chapters, labelled with each chapter's
+    #   <tt><h1></tt>. Without one, the label comes from the filename (+chapter_0.xhtml+ is the Prologue).
     # @return [Array<String>] List of moved chapter filenames
     def run
       moved_files = move_chapters
@@ -59,10 +60,8 @@ module EpubTools
     end
 
     def move_chapters
-      # Sort by chapter number (numeric)
       chapter_files = Dir.glob(File.join(@chapters_dir, '*.xhtml')).sort_by do |path|
-        # extract first integer from filename (e.g. chapter_10.xhtml -> 10)
-        File.basename(path)[/\d+/].to_i
+        ChapterOrder.sort_key(path)
       end
 
       raise ArgumentError, "No .xhtml files found in '#{@chapters_dir}'" if chapter_files.empty?
@@ -74,7 +73,7 @@ module EpubTools
     end
 
     def chapter_id(filename)
-      match = filename.match(/chapter_(\d+)\.xhtml/)
+      match = filename.match(/chapter_(\d+(?:_5)?)\.xhtml/)
       match ? "chap#{match[1]}" : File.basename(filename, '.xhtml')
     end
 
@@ -92,7 +91,9 @@ module EpubTools
       doc = Nokogiri::XML(File.read(@nav_file)) { |config| config.default_xml.noblanks }
       nav = doc.at_xpath('//xmlns:nav[@epub:type="toc"]/xmlns:ol')
 
-      filenames.each { |filename| nav.add_child(create_nav_link(doc, filename)) }
+      filenames.each do |filename|
+        ChapterOrder.insert(nav, create_nav_link(doc, filename), filename) { |li| li.at_xpath('xmlns:a')&.[]('href') }
+      end
 
       File.write(@nav_file, doc.to_xml(indent: 2))
     end
@@ -106,15 +107,25 @@ module EpubTools
       li
     end
 
+    # Uses the chapter's own <h1> when it has one, falling back to a label derived from the filename
     def format_chapter_label(filename)
-      label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
-      label == 'Chapter 0' ? 'Prologue' : label
+      heading = Nokogiri::XML(File.read(File.join(@epub_dir, filename))).at_xpath('//*[local-name()="h1"]')
+      return heading.text.strip unless heading.nil? || heading.text.strip.empty?
+
+      basename = File.basename(filename, '.xhtml')
+      return 'Prologue' if basename == 'chapter_0'
+
+      if (m = basename.match(/chapter_(\d+)_5/))
+        "Chapter #{m[1]}.5"
+      else
+        basename.gsub('_', ' ').capitalize
+      end
     end
 
     def update_opf_for_file(doc, manifest, spine, filename)
       id = chapter_id(filename)
       add_manifest_item(doc, manifest, filename, id) unless manifest_item_exists?(doc, filename)
-      add_spine_itemref(doc, spine, id) unless spine_itemref_exists?(doc, id)
+      add_spine_itemref(doc, spine, id, filename) unless spine_itemref_exists?(doc, id)
     end
 
     def manifest_item_exists?(doc, filename)
@@ -133,10 +144,11 @@ module EpubTools
       manifest.add_child(item)
     end
 
-    def add_spine_itemref(doc, spine, id)
+    def add_spine_itemref(doc, spine, id, filename)
       itemref = Nokogiri::XML::Node.new('itemref', doc)
       itemref['idref'] = id
-      spine.add_child(itemref)
+      hrefs = doc.xpath('//xmlns:manifest/xmlns:item').to_h { |item| [item['id'], item['href']] }
+      ChapterOrder.insert(spine, itemref, filename) { |ref| hrefs[ref['idref']] }
     end
   end
 end

data/lib/epub_tools/append_book.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require_relative 'book_builder'
+require_relative 'unpack_ebook'
+
+module EpubTools
+  # Appends chapters from source EPUBs to an existing target EPUB
+  class AppendBook < BookBuilder
+    attr_reader :target_epub
+
+    def initialize(options = {})
+      super
+      @target_epub = File.expand_path(options.fetch(:target_epub))
+    end
+
+    private
+
+    def book_title
+      @book_title ||= read_target_title
+    end
+
+    def output_path = @target_epub
+
+    def prepare_epub
+      backup_target
+      unpack_target
+    end
+
+    def before_add_chapters
+      detect_conflicts
+    end
+
+    def finalize_and_cleanup
+      log "Done. Updated EPUB: #{@target_epub} (backup: #{@backup_path})"
+      FileUtils.rm_rf(build_dir)
+      @target_epub
+    end
+
+    def backup_target
+      @backup_path = "#{@target_epub}.bak"
+      log "Backing up target to '#{@backup_path}'..."
+      FileUtils.cp(@target_epub, @backup_path)
+    end
+
+    def unpack_target
+      log 'Unpacking target EPUB...'
+      UnpackEbook.new(epub_file: @target_epub, output_dir: epub_dir, verbose: verbose).run
+    end
+
+    def read_target_title
+      opf_path = File.join(epub_oebps_dir, 'package.opf')
+      doc = Nokogiri::XML(File.read(opf_path))
+      doc.remove_namespaces!
+      doc.at_xpath('//title')&.text || 'Untitled'
+    end
+
+    def detect_conflicts
+      conflicts = chapter_numbers_in(chapters_dir) & chapter_numbers_in(epub_oebps_dir)
+      return if conflicts.empty?
+
+      raise ArgumentError,
+            "Chapter number conflict: chapters #{conflicts.sort_by(&:to_f).join(', ')} already exist in the " \
+            'target EPUB. Renumber the source chapters or remove conflicting chapters from the target.'
+    end
+
+    # @return [Array<String>] Chapter numbers as written in filenames: chapter_3_5 is "3.5", chapter_3a is "3a"
+    def chapter_numbers_in(dir)
+      Dir.glob(File.join(dir, 'chapter_*.xhtml')).map do |path|
+        File.basename(path, '.xhtml').delete_prefix('chapter_').tr('_', '.')
+      end
+    end
+  end
+end