epub_tools 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 830a3d6d88e106980c19f5c19ea5e0365e39499cc90c0c32ff5c204b7cf24abd
-  data.tar.gz: 7898e152850e5e390842e04a56947e2e88623bd1e5b65525561423da7a5ec744
+  metadata.gz: a379e3e740873230fa8c4f71261006ac79654e74f1fa5ba299aee8742f9aa3c3
+  data.tar.gz: c9d83418c1f585a43e3650e3b5189fd74a4f3374a4835b818bc15379f19ede05
 SHA512:
-  metadata.gz: 7b852a22e630ad9177c5adc692326dac517b904c687e6cbe3874b7e1f43347a53cfdd381cb5b66b7feaf6faafae75129510aac6a23f84f4b3e82734ae84dc8ac
-  data.tar.gz: 4602e5922dbdf257436445546b14501a0064861af84fea854feb0a10ed2ef651d6eefb8009ce459c7463c50c3383eabe3220a10d856271ad38c49cc768b8da5f
+  metadata.gz: 27bf72687e57c4998831d5e94098ddbeb76f953d99b09d2798e2087b4ce147353df2673e5d1996124047ae3c09741604b80483a79aea471180cdd9769f76a28f
+  data.tar.gz: b06cce574ef93ab03769d7734bffd0947453bc4353f50c17edda34943a075e151a44e04916bc4c08890ff51b9f8a7f6d4fde7ba05d591507ba5be0bb6d49a65e

data/CLAUDE.md

@@ -71,10 +71,14 @@ gem install ./epub_tools-*.gem
   - `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)
+- **Workflow Classes**: Orchestrators built on a shared base class
+  - `BookBuilder`: Base class with template method pattern (extract → split → 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**: SOLID-designed helper classes
-  - `CompileWorkspace`: Manages build directories for CompileBook
+  - `CompileWorkspace`: Manages build directories for book-building workflows
   - `ChapterValidator`: Validates chapter sequence completeness
+  - `ChapterMarkerDetector`: Detects chapter boundary markers (Chapter N, Chapter N (continued), Prologue)
   - `EpubConfiguration`: Configuration object for EPUB initialization
   - `XhtmlGenerator`: Generates XHTML templates for EPUB content
   - `EpubMetadataBuilder`: Builds OPF metadata content

data/Gemfile.lock

@@ -6,7 +6,7 @@ GEM
     docile (1.4.1)
     drb (2.2.3)
     erb (6.0.2)
-    json (2.18.1)
+    json (2.19.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     minitest (6.0.2)

data/README.md

@@ -2,7 +2,7 @@
 
 [![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
 
@@ -36,6 +36,7 @@ Commands:
 - `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
+- `append`    Extracts and splits EPUBs from a dir and appends them to an existing EPUB
 
 Run `epub-tools COMMAND --help` for details on options.
 
@@ -61,46 +62,58 @@ epub-tools unpack -i MyBook.epub -o unpacked_dir
 
 # 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
-```
 
- (Legacy script references removed; see CLI Usage above)
+# Append chapters from new EPUBs to an existing book
+epub-tools append -s new_epubs -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', output_prefix: 'chapter'
 ).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/lib/epub_tools/add_chapters.rb

@@ -59,10 +59,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
+        chapter_sort_key(File.basename(path))
       end
 
       raise ArgumentError, "No .xhtml files found in '#{@chapters_dir}'" if chapter_files.empty?
@@ -73,8 +71,17 @@ module EpubTools
       chapter_files.map { |f| File.basename(f) }
     end
 
+    def chapter_sort_key(filename)
+      basename = File.basename(filename, '.xhtml')
+      if (m = basename.match(/_(\d+)_5\z/))
+        m[1].to_f + 0.5
+      else
+        basename[/\d+/].to_f
+      end
+    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
 
@@ -107,8 +114,14 @@ module EpubTools
     end
 
     def format_chapter_label(filename)
-      label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
-      label == 'Chapter 0' ? 'Prologue' : label
+      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)

data/lib/epub_tools/append_book.rb

@@ -0,0 +1,81 @@
+# 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})"
+      @workspace.clean
+      @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: @workspace.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
+      new_numbers = chapter_numbers_in(@workspace.chapters_dir)
+      existing_numbers = chapter_numbers_in(epub_oebps_dir)
+      conflicts = new_numbers & existing_numbers
+      return if conflicts.empty?
+
+      formatted = conflicts.sort.map { |n| n == n.to_i ? n.to_i.to_s : n.to_s }
+      raise ArgumentError,
+            "Chapter number conflict: chapters #{formatted.join(', ')} already exist in the target EPUB. " \
+            'Renumber the source chapters or remove conflicting chapters from the target.'
+    end
+
+    def chapter_numbers_in(dir)
+      Dir.glob(File.join(dir, 'chapter_*.xhtml')).filter_map do |path|
+        basename = File.basename(path, '.xhtml')
+        if (m = basename.match(/_(\d+)_5\z/))
+          m[1].to_f + 0.5
+        elsif (m = basename.match(/_(\d+)\z/))
+          m[1].to_f
+        end
+      end
+    end
+  end
+end

data/lib/epub_tools/book_builder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'loggable'
+require_relative 'xhtml_extractor'
+require_relative 'split_chapters'
+require_relative 'add_chapters'
+require_relative 'pack_ebook'
+require_relative 'compile_workspace'
+require_relative 'chapter_validator'
+
+module EpubTools
+  # Base class for book-building workflows (compile and append).
+  # Uses template method pattern — subclasses override hooks to customize behavior.
+  class BookBuilder
+    include Loggable
+
+    attr_reader :source_dir, :build_dir, :verbose
+
+    def initialize(options = {})
+      @source_dir = options.fetch(:source_dir)
+      @build_dir  = options[:build_dir] || File.join(Dir.pwd, '.epub_tools_build')
+      @verbose    = options[:verbose] || false
+      @workspace  = CompileWorkspace.new(@build_dir)
+    end
+
+    # Run the full build workflow
+    # @return [String] Path to the output EPUB file
+    def run
+      setup_workspace
+      prepare_epub
+      extract_xhtmls
+      split_xhtmls
+      validate_chapters
+      before_add_chapters
+      add_chapters
+      pack_epub
+      finalize_and_cleanup
+    end
+
+    private
+
+    # Hook: called before extract/split to set up the EPUB target
+    def prepare_epub; end
+
+    # Hook: called after validation, before adding chapters
+    def before_add_chapters; end
+
+    # Subclasses must implement: the book title used when splitting chapters
+    def book_title
+      raise NotImplementedError, "#{self.class} must implement #book_title"
+    end
+
+    # Subclasses must implement: the output file path for pack_epub
+    def output_path
+      raise NotImplementedError, "#{self.class} must implement #output_path"
+    end
+
+    def setup_workspace
+      @workspace.clean
+      @workspace.prepare_directories
+      log 'Preparing build directories...'
+    end
+
+    def extract_xhtmls
+      log "Extracting XHTML files from EPUBs in '#{source_dir}'..."
+      XHTMLExtractor.new(source_dir: source_dir, target_dir: @workspace.xhtml_dir, verbose: verbose).run
+    end
+
+    def split_xhtmls
+      Dir.glob(File.join(@workspace.xhtml_dir, '*.xhtml')).each { |f| split_xhtml_file(f) }
+    end
+
+    def split_xhtml_file(xhtml_file)
+      log "Splitting '#{File.basename(xhtml_file, '.xhtml')}'..."
+      SplitChapters.new(
+        input_file: xhtml_file, book_title: book_title,
+        output_dir: @workspace.chapters_dir, output_prefix: 'chapter', verbose: verbose
+      ).run
+    end
+
+    def validate_chapters
+      ChapterValidator.new(chapters_dir: @workspace.chapters_dir, verbose: verbose).validate
+    end
+
+    def add_chapters
+      log 'Adding chapters to EPUB...'
+      AddChapters.new(
+        chapters_dir: @workspace.chapters_dir,
+        oebps_dir: epub_oebps_dir,
+        verbose: verbose
+      ).run
+    end
+
+    def pack_epub
+      log "Building EPUB '#{output_path}'..."
+      PackEbook.new(input_dir: @workspace.epub_dir, output_file: output_path, verbose: verbose).run
+    end
+
+    def finalize_and_cleanup
+      log "Done. Output EPUB: #{File.expand_path(output_path)}"
+      @workspace.clean
+      output_path
+    end
+
+    def epub_oebps_dir = File.join(@workspace.epub_dir, 'OEBPS')
+  end
+end

data/lib/epub_tools/chapter_marker_detector.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module EpubTools
+  # Detects chapter boundary markers in XHTML nodes.
+  # Recognizes: "Chapter N", "Chapter N (continued)", and "Prologue".
+  class ChapterMarkerDetector
+    # Tags that can contain chapter markers
+    MARKER_TAGS = %w[p span h2 h3 h4].freeze
+    # Tags that can contain prologue markers
+    PROLOGUE_TAGS = %w[h3 h4].freeze
+
+    # Detect what type of chapter marker a node represents
+    # @param node [Nokogiri::XML::Node] The XHTML node to check
+    # @return [Symbol, nil] :chapter, :continued, :prologue, or nil
+    def detect(node)
+      if continued_marker?(node)
+        :continued
+      elsif chapter_marker?(node)
+        :chapter
+      elsif prologue_marker?(node)
+        :prologue
+      end
+    end
+
+    # Extract the chapter number from a node's text
+    # @param node [Nokogiri::XML::Node] A node containing "Chapter N" text
+    # @return [Integer] The chapter number
+    def extract_chapter_number(node)
+      node.text.match(/Chapter\s+(\d+)/i)[1].to_i
+    end
+
+    private
+
+    def continued_marker?(node)
+      MARKER_TAGS.include?(node.name) && node.text.match?(/Chapter\s+\d+\s*\(continued\)/i)
+    end
+
+    def chapter_marker?(node)
+      MARKER_TAGS.include?(node.name) && node.text.match?(/Chapter\s+\d+/i) && !continued_marker?(node)
+    end
+
+    def prologue_marker?(node)
+      PROLOGUE_TAGS.include?(node.name) && node.text.strip.match?(/\APrologue\z/i)
+    end
+  end
+end

data/lib/epub_tools/chapter_validator.rb

@@ -12,6 +12,9 @@ module EpubTools
       @verbose = verbose
     end
 
+    # Validates that integer chapter numbers form a complete sequence with no gaps.
+    # Half-chapters (e.g. chapter_5_5.xhtml) are recognized but not required.
+    # @raise [RuntimeError] if no chapter files are found or if integer chapters have gaps
     def validate
       log 'Validating chapter sequence...'
       nums = extract_chapter_numbers
@@ -22,18 +25,25 @@ module EpubTools
     private
 
     def extract_chapter_numbers
-      nums = Dir.glob(File.join(@chapters_dir, '*.xhtml')).map do |file|
-        if (m = File.basename(file, '.xhtml').match(/_(\d+)\z/))
-          m[1].to_i
-        end
-      end.compact
+      nums = Dir.glob(File.join(@chapters_dir, '*.xhtml')).filter_map do |file|
+        extract_chapter_number(File.basename(file, '.xhtml'))
+      end
       raise "No chapter files found in #{@chapters_dir}" if nums.empty?
 
       nums.sort.uniq
     end
 
+    def extract_chapter_number(basename)
+      if (m = basename.match(/_(\d+)_5\z/))
+        m[1].to_i + 0.5
+      elsif (m = basename.match(/_(\d+)\z/))
+        m[1].to_i
+      end
+    end
+
     def check_sequence_completeness(sorted)
-      missing = (sorted.first..sorted.last).to_a - sorted
+      integers = sorted.select { |n| n == n.to_i }.map(&:to_i)
+      missing = (integers.first..integers.last).to_a - integers
       raise "Missing chapter numbers: #{missing.join(' ')}" if missing.any?
     end
   end

data/lib/epub_tools/cli/command_options_configurator.rb

@@ -96,6 +96,19 @@ module EpubTools
         end.with_verbose_option
       end
 
+      # Configure options for the 'append' command
+      # @param builder [OptionBuilder] Option builder instance
+      def configure_append_options(builder)
+        builder.with_custom_options do |opts, options|
+          opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to append (required)') do |v|
+            options[:source_dir] = v
+          end
+          opts.on('-t FILE', '--target-epub FILE', 'Existing EPUB file to append to (required)') do |v|
+            options[:target_epub] = v
+          end
+        end.with_verbose_option
+      end
+
       # Configure options for the 'compile' command
       # @param builder [OptionBuilder] Option builder instance
       def configure_compile_options(builder)

data/lib/epub_tools/cli/runner.rb

@@ -107,6 +107,7 @@ module EpubTools
         puts '  pack      Package an EPUB directory into a .epub file'
         puts '  unpack    Unpack an EPUB file into a directory'
         puts '  compile   Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB.'
+        puts '  append    Extracts and splits EPUBs from a dir and appends them to an existing EPUB.'
       end
     end
   end

data/lib/epub_tools/cli.rb

@@ -27,6 +27,7 @@ module EpubTools
       registry.register('pack', EpubTools::PackEbook, %i[input_dir output_file], { verbose: true })
       registry.register('unpack', EpubTools::UnpackEbook, [:epub_file], { verbose: true })
       registry.register('compile', EpubTools::CompileBook, %i[title author source_dir], { verbose: true })
+      registry.register('append', EpubTools::AppendBook, %i[source_dir target_epub], { verbose: true })
     end
   end
 end

data/lib/epub_tools/compile_book.rb

@@ -1,150 +1,36 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'fileutils'
-require_relative 'loggable'
-require_relative 'xhtml_extractor'
-require_relative 'split_chapters'
+require_relative 'book_builder'
 require_relative 'epub_initializer'
-require_relative 'add_chapters'
-require_relative 'pack_ebook'
-require_relative 'compile_workspace'
-require_relative 'chapter_validator'
 
 module EpubTools
-  # Orchestrates extraction, splitting, validation, and packaging of book EPUBs
-  class CompileBook
-    include Loggable
+  # Compiles a new EPUB from source EPUBs by extracting, splitting, and repackaging
+  class CompileBook < BookBuilder
+    attr_reader :title, :author, :cover_image, :output_file
 
-    # Book title
-    attr_reader :title
-    # Book author
-    attr_reader :author
-    # Path of the input epubs
-    attr_reader :source_dir
-    # Optional path to the cover image
-    attr_reader :cover_image
-    # Filename for the final epub
-    attr_reader :output_file
-    # Optional working directory for intermediate files
-    attr_reader :build_dir
-    # Whether to print progress to STDOUT
-    attr_reader :verbose
-
-    # Initializes the class
-    # @param options [Hash] Configuration options
-    # @option options [String] :title Book title (required)
-    # @option options [String] :author Book author (required)
-    # @option options [String] :source_dir Path of the input epubs (required)
-    # @option options [String] :cover_image Optional path to the cover image
-    # @option options [String] :output_file Filename for the final epub (default: [title].epub)
-    # @option options [String] :build_dir Optional working directory for intermediate files
-    # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
     def initialize(options = {})
+      super
       @title       = options.fetch(:title)
       @author      = options.fetch(:author)
-      @source_dir  = options.fetch(:source_dir)
       @cover_image = options[:cover_image]
       @output_file = options[:output_file] || default_output_file
-      @build_dir   = options[:build_dir] || File.join(Dir.pwd, '.epub_tools_build')
-      @verbose     = options[:verbose] || false
-      @workspace   = CompileWorkspace.new(@build_dir)
-    end
-
-    # Run the full compile workflow
-    def run
-      setup_workspace
-      extract_xhtmls
-      split_xhtmls
-      validate_chapters
-      initialize_epub
-      add_chapters
-      pack_epub
-      finalize_and_cleanup
     end
 
     private
 
-    def setup_workspace
-      @workspace.clean
-      log "Cleaning build directory #{@build_dir}..."
-      @workspace.prepare_directories
-      log 'Preparing build directories...'
-    end
+    def book_title = @title
 
-    def finalize_and_cleanup
-      log "Done. Output EPUB: #{File.expand_path(output_file)}"
-      @workspace.clean
-      output_file
-    end
-
-    def default_output_file
-      "#{title.gsub(' ', '_')}.epub"
-    end
-
-    def extract_xhtmls
-      log "Extracting XHTML files from epubs in '#{source_dir}'..."
-      XHTMLExtractor.new({
-                           source_dir: source_dir,
-                           target_dir: @workspace.xhtml_dir,
-                           verbose: verbose
-                         }).run
-    end
-
-    def split_xhtmls
-      log 'Splitting XHTML files into chapters...'
-      Dir.glob(File.join(@workspace.xhtml_dir, '*.xhtml')).each do |xhtml_file|
-        split_xhtml_file(xhtml_file)
-      end
-    end
+    def output_path = @output_file
 
-    def split_xhtml_file(xhtml_file)
-      base = File.basename(xhtml_file, '.xhtml')
-      log "Splitting '#{base}'..."
-      SplitChapters.new(build_split_options(xhtml_file)).run
-    end
-
-    def build_split_options(xhtml_file)
-      {
-        input_file: xhtml_file,
-        book_title: title,
-        output_dir: @workspace.chapters_dir,
-        output_prefix: 'chapter',
-        verbose: verbose
-      }
-    end
-
-    def validate_chapters
-      ChapterValidator.new(chapters_dir: @workspace.chapters_dir, verbose: verbose).validate
-    end
-
-    def initialize_epub
+    def before_add_chapters
       log 'Initializing new EPUB...'
-      EpubInitializer.new(build_epub_options).run
-    end
-
-    def build_epub_options
       options = { title: title, author: author, destination: @workspace.epub_dir }
       options[:cover_image] = cover_image if cover_image
-      options
-    end
-
-    def add_chapters
-      log 'Adding chapters to EPUB...'
-      AddChapters.new({
-                        chapters_dir: @workspace.chapters_dir,
-                        epub_dir: File.join(@workspace.epub_dir, 'OEBPS'),
-                        verbose: verbose
-                      }).run
+      EpubInitializer.new(options).run
     end
 
-    def pack_epub
-      log "Building final EPUB '#{output_file}'..."
-      PackEbook.new({
-                      input_dir: @workspace.epub_dir,
-                      output_file: output_file,
-                      verbose: verbose
-                    }).run
+    def default_output_file
+      "#{title.gsub(' ', '_')}.epub"
     end
   end
 end

data/lib/epub_tools/split_chapters.rb

@@ -7,48 +7,29 @@ require 'fileutils'
 require_relative 'loggable'
 require_relative 'style_finder'
 require_relative 'xhtml_cleaner'
+require_relative 'chapter_marker_detector'
 
 module EpubTools
-  # Takes a Google Docs generated, already extracted from their EPUB, XHTML files with multiple
-  # chapters and it:
-  # - Extracts classes using {StyleFinder}[rdoc-ref:EpubTools::StyleFinder]
-  # - Looks for tags that say something like Chapter XX or Prologue and splits the text there
-  # - Creates new chapter_XX.xhtml files that are cleaned using
-  #   {XHTMLCleaner}[rdoc-ref:EpubTools::XHTMLCleaner]
-  # - Saves those files to +output_dir+
+  # Splits a multi-chapter XHTML file into individual chapter files.
   class SplitChapters
     include Loggable
 
-    # Initializes the class
-    # @param options [Hash] Configuration options
-    # @option options [String] :input_file Path to the source XHTML (required)
-    # @option options [String] :book_title Title to use in HTML <title> tags (required)
-    # @option options [String] :output_dir Where to write chapter files (default: './chapters')
-    # @option options [String] :output_prefix Filename prefix for chapter files (default: 'chapter')
-    # @option options [Boolean] :verbose Whether to print progress to STDOUT (default: false)
     def initialize(options = {})
       @input_file    = options.fetch(:input_file)
       @book_title    = options.fetch(:book_title)
       @output_dir    = options[:output_dir] || './chapters'
       @output_prefix = options[:output_prefix] || 'chapter'
       @verbose       = options[:verbose] || false
+      @detector      = ChapterMarkerDetector.new
     end
 
     # Runs the splitter
     # @return [Array<String>] List of generated chapter file paths
     def run
-      # Prepare output dir
       FileUtils.mkdir_p(@output_dir)
-
-      # Read the doc
-      raw_content = read_and_strip_problematic_tags
-      doc = Nokogiri::HTML(raw_content)
-
-      # Find Style Classes
+      doc = Nokogiri::HTML(read_and_strip_problematic_tags)
       StyleFinder.new({ file_path: @input_file, verbose: @verbose }).run
-
-      chapters = extract_chapters(doc)
-      write_chapter_files(chapters)
+      extract_chapters(doc).map { |number, content| write_chapter_file(number, content) }
     end
 
     private
@@ -66,53 +47,37 @@ module EpubTools
         current_number, current_fragment = process_node(node, chapters, current_number, current_fragment)
       end
 
-      finalize_chapters(chapters, current_number, current_fragment)
+      chapters[current_number] = current_fragment.to_html if current_number
+      chapters
     end
 
     def process_node(node, chapters, current_number, current_fragment)
-      if chapter_marker?(node)
-        start_new_chapter(chapters, node, current_number, current_fragment)
-      elsif prologue_marker?(node)
-        start_prologue(chapters, current_number, current_fragment)
+      marker = @detector.detect(node)
+      if marker
+        start_chapter(chapters, marker_number(marker, node), current_number, current_fragment)
       else
         current_fragment&.add_child(node.dup)
         [current_number, current_fragment]
       end
     end
 
-    def chapter_marker?(node)
-      node.text.match?(/Chapter\s+\d+/i) && %w[p span h2 h3 h4].include?(node.name)
-    end
-
-    def start_new_chapter(chapters, node, current_number, current_fragment)
-      chapters[current_number] = current_fragment.to_html if current_number
-      chapter_number = node.text.match(/Chapter\s+(\d+)/i)[1].to_i
-      [chapter_number, Nokogiri::HTML::DocumentFragment.parse('')]
-    end
-
-    def start_prologue(chapters, current_number, current_fragment)
-      chapters[current_number] = current_fragment.to_html if current_number
-      [0, Nokogiri::HTML::DocumentFragment.parse('')]
+    def marker_number(marker, node)
+      case marker
+      when :continued then @detector.extract_chapter_number(node) + 0.5
+      when :chapter then @detector.extract_chapter_number(node)
+      when :prologue then 0
+      end
     end
 
-    def finalize_chapters(chapters, current_number, current_fragment)
+    def start_chapter(chapters, number, current_number, current_fragment)
       chapters[current_number] = current_fragment.to_html if current_number
-      chapters
-    end
-
-    def write_chapter_files(chapters)
-      chapter_files = []
-      chapters.each do |number, content|
-        filename = write_chapter_file(number, content)
-        chapter_files << filename
-      end
-      chapter_files
+      [number, Nokogiri::HTML::DocumentFragment.parse('')]
     end
 
     def write_chapter_file(label, content)
-      display_label = display_label(label)
-      filename = File.join(@output_dir, "#{@output_prefix}_#{label}.xhtml")
-      File.write(filename, build_xhtml_template(display_label, content))
+      display = display_label(label)
+      filename = File.join(@output_dir, "#{@output_prefix}_#{file_label(label)}.xhtml")
+      File.write(filename, build_xhtml_template(display, content))
       XHTMLCleaner.new({ filename: filename }).run
       log("Extracted: #{filename}")
       filename
@@ -134,16 +99,14 @@ module EpubTools
       HTML
     end
 
-    def display_label(label)
-      label.positive? ? "Chapter #{label}" : 'Prologue'
+    def file_label(label)
+      label.is_a?(Float) ? label.to_s.gsub('.', '_') : label.to_s
     end
 
-    # Detect a bolded Prologue marker
-    def prologue_marker?(node)
-      return false unless %w[h3 h4].include?(node.name)
-      return false unless node.text.strip =~ /\APrologue\z/i
+    def display_label(label)
+      return 'Prologue' if label.zero?
 
-      true
+      "Chapter #{label}"
     end
   end
 end

data/lib/epub_tools/version.rb

@@ -2,5 +2,5 @@
 
 module EpubTools
   # Ruby Gem version number
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/epub_tools.rb

@@ -5,11 +5,14 @@ require_relative 'epub_tools/loggable'
 require_relative 'epub_tools/add_chapters'
 require_relative 'epub_tools/epub_initializer'
 require_relative 'epub_tools/split_chapters'
+require_relative 'epub_tools/chapter_marker_detector'
 require_relative 'epub_tools/xhtml_cleaner'
 require_relative 'epub_tools/xhtml_extractor'
 require_relative 'epub_tools/pack_ebook'
 require_relative 'epub_tools/unpack_ebook'
+require_relative 'epub_tools/book_builder'
 require_relative 'epub_tools/compile_book'
+require_relative 'epub_tools/append_book'
 require_relative 'epub_tools/cli'
 
 # Wrapper for all the other classes

data/test/add_chapters_test.rb

@@ -121,3 +121,73 @@ class AddChaptersTest < Minitest::Test
     nav_doc.xpath('//nav/ol/li/a')
   end
 end
+
+class AddChaptersHalfChapterTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @chapters_dir = File.join(@tmp, 'chapters')
+    @epub_dir = File.join(@tmp, 'OEBPS')
+    Dir.mkdir(@chapters_dir)
+    Dir.mkdir(@epub_dir)
+    create_chapter_files
+    create_opf_and_nav
+  end
+
+  def teardown
+    FileUtils.remove_entry(@tmp)
+  end
+
+  def test_half_chapter_sorting_and_labels
+    result = EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    assert_equal %w[chapter_1.xhtml chapter_1_5.xhtml chapter_2.xhtml], result
+  end
+
+  def test_half_chapter_nav_label
+    EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    nav_doc = Nokogiri::XML(File.read(File.join(@epub_dir, 'nav.xhtml')))
+    nav_doc.remove_namespaces!
+    links = nav_doc.xpath('//nav/ol/li/a')
+
+    assert_equal 'Chapter 1', links[0].text
+    assert_equal 'Chapter 1.5', links[1].text
+    assert_equal 'Chapter 2', links[2].text
+  end
+
+  def test_half_chapter_opf_id
+    EpubTools::AddChapters.new(chapters_dir: @chapters_dir, oebps_dir: @epub_dir).run
+
+    doc = Nokogiri::XML(File.read(File.join(@epub_dir, 'package.opf')))
+    ids = doc.xpath('//xmlns:manifest/xmlns:item').map { |i| i['id'] }
+
+    assert_includes ids, 'chap1_5'
+  end
+
+  private
+
+  def create_chapter_files
+    File.write(File.join(@chapters_dir, 'chapter_1.xhtml'), '<html><body>Ch1</body></html>')
+    File.write(File.join(@chapters_dir, 'chapter_1_5.xhtml'), '<html><body>Ch1.5</body></html>')
+    File.write(File.join(@chapters_dir, 'chapter_2.xhtml'), '<html><body>Ch2</body></html>')
+  end
+
+  def create_opf_and_nav
+    File.write(File.join(@epub_dir, 'package.opf'), <<~XML)
+      <?xml version="1.0"?>
+      <package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="pub-id" xml:lang="en">
+        <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"></metadata>
+        <manifest></manifest>
+        <spine></spine>
+      </package>
+    XML
+    File.write(File.join(@epub_dir, 'nav.xhtml'), <<~XHTML)
+      <?xml version="1.0" encoding="utf-8"?>
+      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" lang="en">
+        <body>
+          <nav epub:type="toc" id="toc"><ol></ol></nav>
+        </body>
+      </html>
+    XHTML
+  end
+end

data/test/append_book_test.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+require_relative '../lib/epub_tools/append_book'
+
+class AppendBookTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @source = File.join(@tmp, 'src')
+    @target = File.join(@tmp, 'target.epub')
+    FileUtils.mkdir_p(@source)
+    FileUtils.touch(@target)
+  end
+
+  def teardown
+    FileUtils.rm_rf(@tmp)
+  end
+
+  def test_initialize_assigns_attributes
+    ab = build_append_book(verbose: true)
+
+    assert_equal @source, ab.source_dir
+    assert_equal File.expand_path(@target), ab.target_epub
+    assert_equal @tmp, ab.build_dir
+    assert ab.verbose
+  end
+
+  def test_default_build_dir
+    ab = EpubTools::AppendBook.new(source_dir: @source, target_epub: @target)
+
+    assert ab.build_dir.end_with?('.epub_tools_build')
+  end
+
+  def test_log_outputs_when_verbose
+    ab = build_append_book(verbose: true)
+
+    assert_output("hello\n") { ab.send(:log, 'hello') }
+  end
+
+  def test_log_silent_when_not_verbose
+    ab = build_append_book(verbose: false)
+
+    assert_silent { ab.send(:log, 'hello') }
+  end
+
+  def test_detect_conflicts_raises_on_overlap
+    ab = build_append_book
+    setup_conflict_dirs(ab, new_chapters: [1, 2], existing_chapters: [1])
+
+    error = assert_raises(ArgumentError) { ab.send(:detect_conflicts) }
+    assert_match(/chapters 1 already exist/, error.message)
+  end
+
+  def test_detect_conflicts_passes_with_no_overlap
+    ab = build_append_book
+    setup_conflict_dirs(ab, new_chapters: [5], existing_chapters: [1, 2])
+
+    ab.send(:detect_conflicts)
+  end
+
+  def test_detect_conflicts_with_half_chapters
+    ab = build_append_book
+    chapters_dir = File.join(@tmp, 'chapters')
+    oebps_dir = File.join(@tmp, 'epub', 'OEBPS')
+    FileUtils.mkdir_p([chapters_dir, oebps_dir])
+
+    FileUtils.touch(File.join(chapters_dir, 'chapter_3_5.xhtml'))
+    FileUtils.touch(File.join(oebps_dir, 'chapter_3_5.xhtml'))
+
+    workspace = ab.instance_variable_get(:@workspace)
+    workspace.instance_variable_set(:@chapters_dir, chapters_dir)
+    workspace.instance_variable_set(:@epub_dir, File.join(@tmp, 'epub'))
+
+    error = assert_raises(ArgumentError) { ab.send(:detect_conflicts) }
+    assert_match(/3\.5 already exist/, error.message)
+  end
+
+  def test_run_completes_workflow
+    ab = build_append_book
+
+    def ab.prepare_epub; end
+    def ab.extract_xhtmls; end
+    def ab.split_xhtmls; end
+    def ab.validate_chapters; end
+    def ab.before_add_chapters; end
+    def ab.add_chapters; end
+    def ab.pack_epub; end
+
+    result = ab.run
+
+    assert_equal File.expand_path(@target), result
+  end
+
+  def test_backup_creates_bak_file
+    File.write(@target, 'epub content')
+    ab = build_append_book
+
+    ab.send(:backup_target)
+
+    backup_path = "#{File.expand_path(@target)}.bak"
+
+    assert_path_exists backup_path
+    assert_equal 'epub content', File.read(backup_path)
+  end
+
+  private
+
+  def build_append_book(verbose: false)
+    EpubTools::AppendBook.new(
+      source_dir: @source, target_epub: @target,
+      build_dir: @tmp, verbose: verbose
+    )
+  end
+
+  def setup_conflict_dirs(append_book, new_chapters:, existing_chapters:)
+    chapters_dir = File.join(@tmp, 'chapters')
+    oebps_dir = File.join(@tmp, 'epub', 'OEBPS')
+    FileUtils.mkdir_p([chapters_dir, oebps_dir])
+
+    new_chapters.each { |n| FileUtils.touch(File.join(chapters_dir, "chapter_#{n}.xhtml")) }
+    existing_chapters.each { |n| FileUtils.touch(File.join(oebps_dir, "chapter_#{n}.xhtml")) }
+
+    workspace = append_book.instance_variable_get(:@workspace)
+    workspace.instance_variable_set(:@chapters_dir, chapters_dir)
+    workspace.instance_variable_set(:@epub_dir, File.join(@tmp, 'epub'))
+  end
+end

data/test/chapter_validator_test.rb

@@ -37,6 +37,27 @@ class ChapterValidatorTest < Minitest::Test
     assert_silent { @validator.validate }
   end
 
+  def test_validates_sequence_with_half_chapters
+    create_chapter_files([1, 2, 3])
+    create_half_chapter_files([2])
+
+    assert_silent { @validator.validate }
+  end
+
+  def test_validates_sequence_without_half_chapters_present
+    create_chapter_files([1, 2, 3])
+
+    assert_silent { @validator.validate }
+  end
+
+  def test_raises_on_missing_integer_despite_half_chapter
+    create_chapter_files([1, 3]) # Missing 2
+    create_half_chapter_files([1])
+
+    error = assert_raises(RuntimeError) { @validator.validate }
+    assert_match(/Missing chapter numbers: 2/, error.message)
+  end
+
   private
 
   def create_chapter_files(numbers)
@@ -44,4 +65,10 @@ class ChapterValidatorTest < Minitest::Test
       File.write(File.join(@tmp, "chapter_#{num}.xhtml"), '<html></html>')
     end
   end
+
+  def create_half_chapter_files(numbers)
+    numbers.each do |num|
+      File.write(File.join(@tmp, "chapter_#{num}_5.xhtml"), '<html></html>')
+    end
+  end
 end

data/test/cli_commands_test.rb

@@ -22,6 +22,7 @@ class CLICommandsTest < Minitest::Test
     assert_includes output, 'pack'
     assert_includes output, 'unpack'
     assert_includes output, 'compile'
+    assert_includes output, 'append'
   end
 
   def test_show_version
@@ -92,6 +93,14 @@ class CLICommandsTest < Minitest::Test
     assert_includes output, '--output-file FILE'
   end
 
+  def test_append_command
+    output = `#{@bin_path} append --help`
+
+    assert_match(/Usage: epub-tools append \[options\]/, output)
+    assert_includes output, '--source-dir DIR'
+    assert_includes output, '--target-epub FILE'
+  end
+
   def test_unpack_command
     output = `#{@bin_path} unpack --help`
 

data/test/compile_book_test.rb

@@ -101,11 +101,10 @@ class CompileBookTest < Minitest::Test
       output_file: 'test.epub'
     )
 
-    # Mock the workflow methods to avoid complex file setup
     def cb.extract_xhtmls; end
     def cb.split_xhtmls; end
     def cb.validate_chapters; end
-    def cb.initialize_epub; end
+    def cb.before_add_chapters; end
     def cb.add_chapters; end
     def cb.pack_epub; end
 

data/test/split_chapters_test.rb

@@ -92,3 +92,72 @@ class SplitChaptersTest < Minitest::Test
     assert_includes ch2, 'Second paragraph'
   end
 end
+
+class SplitChaptersContinuedTest < Minitest::Test
+  def setup
+    @tmp = Dir.mktmpdir
+    @input = File.join(@tmp, 'input.xhtml')
+    @out = File.join(@tmp, 'out')
+    content = <<~HTML
+      <?xml version="1.0"?>
+      <html xmlns="http://www.w3.org/1999/xhtml">
+        <body>
+          <p>Chapter 1</p>
+          <p>First paragraph</p>
+          <p>Chapter 1 (Continued)</p>
+          <p>Continued text</p>
+          <p>Chapter 2</p>
+          <p>Second paragraph</p>
+        </body>
+      </html>
+    HTML
+    File.write(@input, content)
+  end
+
+  def teardown
+    FileUtils.remove_entry(@tmp)
+  end
+
+  def test_splits_continued_chapters
+    result = EpubTools::SplitChapters.new(
+      input_file: @input, book_title: 'Test', output_dir: @out, output_prefix: 'chapter'
+    ).run
+
+    assert_equal 3, result.size
+    assert_includes result, File.join(@out, 'chapter_1.xhtml')
+    assert_includes result, File.join(@out, 'chapter_1_5.xhtml')
+    assert_includes result, File.join(@out, 'chapter_2.xhtml')
+  end
+
+  def test_continued_chapter_content
+    EpubTools::SplitChapters.new(
+      input_file: @input, book_title: 'Test', output_dir: @out, output_prefix: 'chapter'
+    ).run
+
+    continued = File.read(File.join(@out, 'chapter_1_5.xhtml'))
+
+    assert_includes continued, '<h1>Chapter 1.5</h1>'
+    assert_includes continued, 'Continued text'
+  end
+
+  def test_continued_marker_case_insensitive
+    content = <<~HTML
+      <?xml version="1.0"?>
+      <html xmlns="http://www.w3.org/1999/xhtml">
+        <body>
+          <p>Chapter 5</p>
+          <p>Text</p>
+          <p>Chapter 5 (continued)</p>
+          <p>More text</p>
+        </body>
+      </html>
+    HTML
+    File.write(@input, content)
+
+    result = EpubTools::SplitChapters.new(
+      input_file: @input, book_title: 'Test', output_dir: @out, output_prefix: 'chapter'
+    ).run
+
+    assert_includes result, File.join(@out, 'chapter_5_5.xhtml')
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epub_tools
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Jaime Rodas
@@ -74,6 +74,9 @@ files:
 - epub_tools.gemspec
 - lib/epub_tools.rb
 - lib/epub_tools/add_chapters.rb
+- lib/epub_tools/append_book.rb
+- lib/epub_tools/book_builder.rb
+- lib/epub_tools/chapter_marker_detector.rb
 - lib/epub_tools/chapter_validator.rb
 - lib/epub_tools/cli.rb
 - lib/epub_tools/cli/command_options_configurator.rb
@@ -97,6 +100,7 @@ files:
 - lib/epub_tools/xhtml_generator.rb
 - style.css
 - test/add_chapters_test.rb
+- test/append_book_test.rb
 - test/chapter_validator_test.rb
 - test/cli/command_registry_test.rb
 - test/cli/option_builder_test.rb