epub_tools 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea6ef571bfc4a850094975f5bf56be8d56b4a81b5cf977dc7a6fca295005086a
+  data.tar.gz: 37b32d7759ac7b00f273871558778cfe0c613955e7319dbee8f33e590678eb94
+SHA512:
+  metadata.gz: 9ea5b766003d9595f9d067e4dbfea5a6348102deb29092be235fadb3b511feec1dff20c1bc63683673378e1136e70f026c7a747c54793a329e7a136b9d18b4d3
+  data.tar.gz: 411cf6f8b5e7cde261368076e55ada115df9f8884bf951b0b3ea2a2ab0fa77425ecf2a04e3de63e3c1351f2bd862c0bb7f0296781c1e78ed9d7c4cea73e02e76

data/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4.3'
+          bundler-cache: true
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+/.bundle/
+/coverage/
+vendor/bundle/
+*.gem
+
+text_style_classes.yaml

data/.nova/Configuration.json

@@ -0,0 +1,4 @@
+{
+  "workspace.art_style" : 0,
+  "workspace.name" : "EPub Tools"
+}

data/.ruby-version

@@ -0,0 +1 @@
+3.4.3

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+ruby '3.4.3'
+
+source "https://rubygems.org"
+
+gem "nokogiri", "~> 1.18"
+gem "rake", "~> 13.2"
+gem "rubyzip", "~> 2.4"
+
+group :test do
+  gem "minitest", "~> 5.25"
+  gem "simplecov", require: false
+end

data/Gemfile.lock

@@ -0,0 +1,53 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    docile (1.4.1)
+    minitest (5.25.5)
+    nokogiri (1.18.8-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-musl)
+      racc (~> 1.4)
+    racc (1.8.1)
+    rake (13.2.1)
+    rubyzip (2.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  minitest (~> 5.25)
+  nokogiri (~> 1.18)
+  rake (~> 13.2)
+  rubyzip (~> 2.4)
+  simplecov
+
+RUBY VERSION
+   ruby 3.4.3p32
+
+BUNDLED WITH
+   2.6.7

data/README.md

@@ -0,0 +1,118 @@
+ # EPUB Tools
+
+ **TL;DR:** A Ruby gem and CLI for working with EPUB files: extract, split, initialize, add chapters, pack, and unpack EPUB books.
+
+## Installation
+Install the gem via RubyGems:
+```bash
+gem install epub_tools
+```
+
+Or build and install locally:
+```bash
+bundle install
+gem build epub_tools.gemspec
+gem install ./epub_tools-*.gem
+```
+
+## CLI Usage
+After installation, use the `epub-tools` executable:
+
+```bash
+Usage: epub-tools COMMAND [options]
+```
+
+Commands:
+- `init`      Initialize a new EPUB directory structure
+- `extract`   Extract XHTML files from EPUB archives
+- `split`     Split an XHTML file into separate chapter 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
+
+Run `epub-tools COMMAND --help` for details on options.
+
+### Example
+```bash
+# Extract XHTMLs
+epub-tools extract -s source_epubs -t xhtml_output
+
+# Split chapters
+epub-tools split -i xhtml_output/chapter1.xhtml -t "My Book" -o chapters
+
+# Initialize EPUB
+epub-tools init -t "My Book" -a "Author Name" -o epub_dir -c cover.jpg
+
+# Add chapters to EPUB
+epub-tools add -c chapters -e epub_dir/OEBPS
+
+# Package EPUB (Ruby)
+epub-tools pack -i epub_dir -o MyBook.epub
+
+# Unpack EPUB
+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)
+
+## Library Usage
+Use the library directly in Ruby:
+```ruby
+require 'epub_tools'
+
+# Extract XHTML
+EpubTools::XHTMLExtractor.new(
+  source_dir: 'source_epubs',
+  target_dir: 'xhtml_output',
+  verbose: true
+).extract_all
+
+# Split chapters
+EpubTools::SplitChapters.new(
+  'xhtml_output/chapter1.xhtml',
+  'My Book',
+  'chapters',
+  'chapter'
+).run
+
+# Initialize EPUB
+EpubTools::EpubInitializer.new(
+  'My Book',
+  'Author Name',
+  'epub_dir',
+  'cover.jpg'
+).run
+
+# Add chapters
+EpubTools::AddChaptersToEpub.new('chapters', 'epub_dir/OEBPS').run
+
+# Pack EPUB
+EpubTools::PackEbook.new('epub_dir', 'MyBook.epub').run
+
+# Unpack EPUB
+EpubTools::UnpackEbook.new('MyBook.epub', 'unpacked_dir').run
+```
+## Development & Testing
+Clone the repo and install dependencies:
+```bash
+git clone <repo-url>
+cd epub_tools
+bundle install
+```
+
+Run tests:
+```bash
+bundle exec rake test
+```
+
+Enable coverage reporting:
+```bash
+COVERAGE=true bundle exec rake test
+```
+
+## Contributing
+Pull requests welcome! Please open an issue for major changes.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'rake/testtask'
+
+desc 'Run all tests'
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test

data/bin/epub-tools

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+require_relative '../lib/epub_tools'
+
+prog = File.basename($PROGRAM_NAME)
+script_dir = File.expand_path(File.join(__dir__, '..'))
+commands = %w[add extract init split pack unpack compile]
+
+if ARGV.empty? || !commands.include?(ARGV[0])
+  puts <<~USAGE
+    Usage: #{prog} COMMAND [options]
+    Commands:
+      init      Initialize a bare-bones EPUB
+      extract   Extract XHTML files from EPUBs
+      split     Split XHTML into separate XHTMLs per chapter
+      add       Add chapter XHTML files into an EPUB
+      pack      Package an EPUB directory into a .epub file
+      unpack    Unpack an EPUB file into a directory
+      compile   Takes EPUBs in a dir and splits, cleans, and compiles into a single EPUB.
+  USAGE
+  exit 1
+end
+
+cmd = ARGV.shift
+
+case cmd
+when 'add'
+options = {}
+EpubTools::CLIHelper.parse(options, [:chapters_dir, :epub_oebps_dir]) do |opts, o|
+  opts.banner = "Usage: #{prog} add [options]"
+  opts.on('-c DIR', '--chapters-dir DIR', 'Chapters directory (required)') { |v| o[:chapters_dir] = v }
+  opts.on('-e DIR', '--epub-oebps-dir DIR', 'EPUB OEBPS directory (required)') { |v| o[:epub_oebps_dir] = v }
+end
+
+EpubTools::AddChaptersToEpub.new(options[:chapters_dir], options[:epub_oebps_dir]).run
+
+when 'extract'
+  options = { verbose: true }
+  EpubTools::CLIHelper.parse(options, [:source_dir, :target_dir]) do |opts, o|
+    opts.banner = "Usage: #{prog} extract [options]"
+    opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') { |v| o[:source_dir] = v }
+    opts.on('-t DIR', '--target-dir DIR', 'Directory where the XHTML files will be extracted to (required)') { |v| o[:target_dir] = v }
+    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
+  end
+  EpubTools::XHTMLExtractor.new(
+    source_dir: options[:source_dir],
+    target_dir: options[:target_dir],
+    verbose: options[:verbose]
+  ).extract_all
+
+when 'split'
+  options = { output_dir: './chapters', prefix: 'chapter', verbose: true }
+  EpubTools::CLIHelper.parse(options, [:input_file, :book_title]) do |opts, o|
+    opts.banner = "Usage: #{prog} split [options]"
+    opts.on('-i FILE', '--input FILE', 'Source XHTML file (required)') { |v| options[:input_file] = v }
+    opts.on('-t TITLE', '--title TITLE', 'Book title for HTML <title> tags (required)') { |v| options[:book_title] = v }
+    opts.on('-o DIR', '--output-dir DIR', "Output directory for chapter files (default: #{options[:output_dir]})") { |v| options[:output_dir] = v }
+    opts.on('-p PREFIX', '--prefix PREFIX', "Filename prefix for chapters (default: #{options[:prefix]})") { |v| options[:prefix] = v }
+    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
+  end
+  EpubTools::SplitChapters.new(options[:input_file], options[:book_title], options[:output_dir], options[:prefix], options[:verbose]).run
+
+when 'init'
+  options = {}
+  EpubTools::CLIHelper.parse(options, [:title, :author, :destination]) do |opts, o|
+    opts.banner = "Usage: #{prog} init [options]"
+    opts.on('-t TITLE', '--title TITLE', 'Book title (required)') { |v| o[:title] = v }
+    opts.on('-a AUTHOR', '--author AUTHOR', 'Author name (required)') { |v| o[:author] = v }
+    opts.on('-o DIR', '--output-dir DIR', 'Destination EPUB directory (required)') { |v| o[:destination] = v }
+    opts.on('-c PATH', '--cover PATH', 'Cover image file path (optional)') { |v| o[:cover_image] = v }
+  end
+
+  EpubTools::EpubInitializer.new(options[:title], options[:author], options[:destination], options[:cover_image]).run
+
+when 'pack'
+  options = {verbose: true}
+  EpubTools::CLIHelper.parse(options, [:input_dir, :output_file]) do |opts, o|
+    opts.banner = "Usage: #{prog} pack [options]"
+    opts.on('-i DIR', '--input-dir DIR', 'EPUB directory to package (required)') { |v| o[:input_dir] = v }
+    opts.on('-o FILE', '--output-file FILE', 'Output EPUB file path (required)') { |v| o[:output_file] = v }
+    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
+  end
+
+  EpubTools::PackEbook.new(options[:input_dir], options[:output_file], verbose: options[:verbose]).run
+
+when 'unpack'
+  options = {verbose: true}
+  EpubTools::CLIHelper.parse(options, [:epub_file]) do |opts, o|
+    opts.banner = "Usage: #{prog} unpack [options]"
+    opts.on('-i FILE', '--input-file FILE', 'EPUB file to unpack (required)') { |v| o[:epub_file] = v }
+    opts.on('-o DIR', '--output-dir DIR', 'Output directory to extract into (default: basename of epub)') { |v| o[:output_dir] = v }
+    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
+  end
+  EpubTools::UnpackEbook.new(options[:epub_file], verbose: options[:verbose]).run
+
+when 'compile'
+  options = {verbose: true}
+  EpubTools::CLIHelper.parse(options, %i(title author source_dir)) do |opts, o|
+    opts.banner = "Usage: #{prog} compile [options]"
+    opts.on('-t TITLE', '--title TITLE', 'Book title (required)') { |v| o[:title] = v }
+    opts.on('-a AUTHOR', '--author AUTHOR', 'Author name (required)') { |v| o[:author] = v }
+    opts.on('-s DIR', '--source-dir DIR', 'Directory with EPUBs to extract XHTMLs from (required)') { |v| o[:source_dir] = v }
+    opts.on('-o FILE', '--output FILE', 'EPUB to create (default: book title in source dir)') { |v| o[:output_file] = v }
+    opts.on('-c PATH', '--cover PATH', 'Cover image file path (optional)') { |v| o[:cover_image] = v }
+    opts.on('-q', '--quiet', 'Run quietly (default: verbose)') { |v| o[:verbose] = !v }
+  end
+  EpubTools::CompileBook.new(*options).run
+end

data/epub_tools.gemspec

@@ -0,0 +1,21 @@
+require_relative 'lib/epub_tools/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'epub_tools'
+  spec.version       = EpubTools::VERSION
+  spec.summary       = 'Tools to extract, split, and compile EPUB books'
+  spec.authors       = ['Jaime Rodas']
+  spec.email         = ['rodas@hey.com']
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files`.split("\n")
+  spec.require_paths = ['lib']
+  spec.executables   = ['epub-tools']
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.add_dependency 'nokogiri', '~> 1.18'
+  spec.add_dependency 'rubyzip', '~> 2.4'
+  spec.add_dependency 'rake', '~> 13.2'
+
+  spec.add_development_dependency 'minitest', '~> 5.25'
+  spec.add_development_dependency 'simplecov', '~> 0'
+end

data/lib/epub_tools/add_chapters_to_epub.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+require 'nokogiri'
+require 'fileutils'
+
+module EpubTools
+  class AddChaptersToEpub
+    def initialize(chapters_dir = './chapters', epub_dir = './epub/OEBPS', verbose = false)
+      @chapters_dir = chapters_dir
+      @epub_dir = epub_dir
+      @opf_file = File.join(@epub_dir, 'package.opf')
+      @nav_file = File.join(@epub_dir, 'nav.xhtml')
+      @verbose = verbose
+    end
+
+    def run
+      moved_files = move_chapters
+      update_package_opf(moved_files)
+      update_nav_xhtml(moved_files)
+      @verbose ? moved_files.each {|f| puts "Moved: #{f}"} : moved_files
+    end
+
+    private
+
+    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
+      end
+      chapter_files.each do |file|
+        FileUtils.mv(file, @epub_dir)
+      end
+      chapter_files.map { |f| File.basename(f) }
+    end
+
+    def chapter_id(filename)
+      match = filename.match(/chapter_(\d+)\.xhtml/)
+      match ? "chap#{match[1]}" : File.basename(filename, '.xhtml')
+    end
+
+    def update_package_opf(filenames)
+      doc = Nokogiri::XML(File.read(@opf_file)) { |config| config.default_xml.noblanks }
+      manifest = doc.at_xpath('//xmlns:manifest')
+      spine = doc.at_xpath('//xmlns:spine')
+
+      filenames.each do |filename|
+        id = chapter_id(filename)
+        # Add <item> to the manifest if missing
+        unless doc.at_xpath("//xmlns:item[@href='#{filename}']")
+          item = Nokogiri::XML::Node.new('item', doc)
+          item['id'] = id
+          item['href'] = filename
+          item['media-type'] = 'application/xhtml+xml'
+          manifest.add_child(item)
+        end
+
+        # Add <itemref> to the spine if missing
+        unless doc.at_xpath("//xmlns:itemref[@idref='#{id}']")
+          itemref = Nokogiri::XML::Node.new('itemref', doc)
+          itemref['idref'] = id
+          spine.add_child(itemref)
+        end
+      end
+
+      File.write(@opf_file, doc.to_xml(indent: 2))
+    end
+
+    def update_nav_xhtml(filenames)
+      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 do |filename|
+        # Create a new <li><a href="...">Label</a></li> element
+        label = File.basename(filename, '.xhtml').gsub('_', ' ').capitalize
+        label = "Prologue" if label == "Chapter 0"
+        li = Nokogiri::XML::Node.new('li', doc)
+        a  = Nokogiri::XML::Node.new('a', doc)
+        a['href'] = filename
+        a.content = label
+        li.add_child(a)
+        nav.add_child(li)
+      end
+
+      File.write(@nav_file, doc.to_xml(indent: 2))
+    end
+  end
+end

data/lib/epub_tools/cli_helper.rb

@@ -0,0 +1,31 @@
+require 'optparse'
+
+module EpubTools
+  # A simple helper to DRY CLI OptionParser usage across commands
+  class CLIHelper
+    # Parses ARGV into options hash, enforces required keys, and displays help/errors.
+    # options: hash of defaults; required_keys: array of symbols required
+    def self.parse(options = {}, required_keys = [], &block)
+      parser = OptionParser.new do |opts|
+        block.call(opts, options)
+        opts.on('-h', '--help', 'Prints this help') { puts opts; exit }
+      end
+      begin
+        parser.parse!
+        unless required_keys.empty?
+          missing = required_keys.select { |k| options[k].nil? }
+          unless missing.empty?
+            STDERR.puts "Missing required options: #{missing.map { |k| "--#{k.to_s.gsub('_','-')}" }.join(', ')}"
+            STDERR.puts parser
+            exit 1
+          end
+        end
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+        STDERR.puts e.message
+        STDERR.puts parser
+        exit 1
+      end
+      options
+    end
+  end
+end

data/lib/epub_tools/compile_book.rb

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+$LOAD_PATH.unshift File.expand_path('../../', __FILE__)
+require 'epub_tools'
+
+module EpubTools
+  # Orchestrates extraction, splitting, validation, and packaging of book EPUBs
+  class CompileBook
+    attr_reader :title, :author, :source_dir, :cover_image, :output_file, :build_dir, :verbose
+
+    # title: String, author: String, source_dir: path to input epubs
+    # cover_image: optional path to cover image, output_file: filename for final epub
+    # build_dir: optional working directory for intermediate files
+    def initialize(title:, author:, source_dir:, cover_image: nil, output_file: nil, build_dir: nil, verbose: false)
+      @title       = title
+      @author      = author
+      @source_dir  = source_dir
+      @cover_image = cover_image
+      @output_file = output_file || default_output_file
+      @build_dir   = build_dir || File.join(Dir.pwd, '.epub_tools_build')
+      @verbose     = verbose
+    end
+
+    # Run the full compile workflow
+    def run
+      clean_build_dir
+      prepare_dirs
+      extract_xhtmls
+      split_xhtmls
+      validate_sequence
+      initialize_epub
+      add_chapters
+      pack_epub
+      log "Done. Output EPUB: #{File.expand_path(output_file)}"
+      clean_build_dir
+    end
+
+    private
+
+    def log(message)
+      puts message if verbose
+    end
+
+    def default_output_file
+      "#{title.gsub(' ', '_')}.epub"
+    end
+
+    def clean_build_dir
+      log "Cleaning build directory #{build_dir}..."
+      FileUtils.rm_rf(build_dir)
+    end
+
+    def prepare_dirs
+      log "Preparing build directories..."
+      FileUtils.mkdir_p(xhtml_dir)
+      FileUtils.mkdir_p(chapters_dir)
+    end
+
+    def xhtml_dir
+      @xhtml_dir ||= File.join(build_dir, 'xhtml')
+    end
+
+    def chapters_dir
+      @chapters_dir ||= File.join(build_dir, 'chapters')
+    end
+
+    def epub_dir
+      @epub_dir ||= File.join(build_dir, 'epub')
+    end
+
+    def extract_xhtmls
+      log "Extracting XHTML files from epubs in '#{source_dir}'..."
+      XHTMLExtractor.new(source_dir: source_dir, target_dir: xhtml_dir, verbose: verbose).extract_all
+    end
+
+    def split_xhtmls
+      log "Splitting XHTML files into chapters..."
+      Dir.glob(File.join(xhtml_dir, '*.xhtml')).each do |xhtml_file|
+        base = File.basename(xhtml_file, '.xhtml')
+        log "Splitting '#{base}'..."
+        SplitChapters.new(xhtml_file, title, chapters_dir, 'chapter', verbose).run
+      end
+    end
+
+    def validate_sequence
+      log "Validating chapter sequence..."
+      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
+      raise "No chapter files found in #{chapters_dir}" if nums.empty?
+      sorted = nums.sort.uniq
+      missing = (sorted.first..sorted.last).to_a - sorted
+      if missing.any?
+        raise "Missing chapter numbers: #{missing.join(' ')}"
+      else
+        log "Chapter sequence is complete: #{sorted.first} to #{sorted.last}."
+      end
+    end
+
+    def initialize_epub
+      log "Initializing new EPUB..."
+      if cover_image
+        EpubInitializer.new(title, author, epub_dir, cover_image).run
+      else
+        EpubInitializer.new(title, author, epub_dir).run
+      end
+    end
+
+    def add_chapters
+      log "Adding chapters to EPUB..."
+      AddChaptersToEpub.new(chapters_dir, File.join(epub_dir, 'OEBPS'), verbose).run
+    end
+
+    def pack_epub
+      log "Building final EPUB '#{output_file}'..."
+      PackEbook.new(epub_dir, output_file, verbose: verbose).run
+    end
+  end
+end