comicbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a990cb3f4650a5a8efb0de5f872f7242c6a3e9f7028f137022d003f92f401f4b
+  data.tar.gz: b10b662cfd46bbe3126b4c834b2e5c057a227d18bed5d0a97d4bc899af843192
+SHA512:
+  metadata.gz: 4d7e88350b4c8f9c111d68579509bdc90f8dbee09abf326a5255b9f2c4065255c1d6d863ff57df3cb42279565aee09ed67873bce779f3d734537b57c03745330
+  data.tar.gz: '0059293bd6b56943810b2fd5bb7ed730dfc1ad214371a5467e2ab73cd7fd8604b4ca66b822ca74051beb10187c15d193d589f58b6bfa02e7ed0d64d81cb3571c'

data/.ruby-version

@@ -0,0 +1 @@
+3.4.7

data/AGENT.md

@@ -0,0 +1,110 @@
+# AGENT.md - Development Rules
+
+## Core Principles
+
+- **Be terse, not verbose in responses** - Say as little as possible
+- **One small move at a time** - No large changes
+- **Always write tests first** - RSpec required
+- **Easy to read code** - Clarity over cleverness
+- **Follow existing patterns** - No new approaches
+
+## Architecture Rules
+
+### Adapter Pattern
+```
+Format (e.g., CBR)
+├── cbr.rb - inherits from Adapter
+├── archiver.rb - creates archives
+└── extractor.rb - extracts archives
+```
+
+### TmpDir Testing
+- All file I/O uses `Dir.mktmpdir`
+- Never create files in repo root
+- Clean up in `after` blocks
+
+### Output Paths
+- Use `determine_output_path` method
+- Place files in source directory (temp)
+- Never use current working directory
+
+## Workflow Rules
+
+### Before Coding
+- Read existing code first
+- Use `grep`/`find_path` to understand patterns
+- Don't guess - investigate
+
+### Development
+- **Never commit without confirmation**
+- Run tests - must pass
+- Run RuboCop - must pass
+- Provide one-line commit message
+
+### Testing Requirements
+- Match existing coverage
+- Use `load_fixture().copy_to()` pattern for all test data
+- Use RSpec matchers over raw Ruby (e.g., `expect(file).to exist` not `File.exist?`)
+- Include: basic, edge cases, options, errors
+- Follow existing spec structure exactly
+
+## Quality Gates
+
+### Definition of Done
+- [ ] All existing tests pass
+- [ ] New tests pass
+- [ ] RuboCop clean
+- [ ] No repo root pollution
+- [ ] Documentation updated
+- [ ] Approved for commit
+
+### Test Structure
+```ruby
+describe 'Component' do
+  let(:temp_dir) { Dir.mktmpdir }
+  after { FileUtils.rm_rf temp_dir }
+
+  before do
+    load_fixture('format/simple.ext').copy_to(test_file)
+  end
+
+  it 'uses RSpec matchers' do
+    expect(File).to exist output_path
+    expect(pages).to be_an Array
+    expect(pages).to be_all ComicBook::Page
+  end
+end
+```
+
+## Adding New Formats
+
+1. Create fixtures (same structure as others)
+2. Main adapter (inherit from Adapter)
+3. Extractor class
+4. Archiver class (if possible)
+5. Tests matching existing patterns
+6. Update main ComicBook class detection
+7. Update documentation
+
+## Vendored Tools
+
+- Use `lib/comic_book/vendor/platform/tool`
+- Detect platform: macos/linux/windows
+- Handle command errors gracefully
+- Parse output appropriately
+
+## Anti-Patterns
+
+- Files in repo root
+- Breaking existing interfaces
+- New patterns when existing ones work
+- Skipping quality gates
+- Verbose communication
+
+## Success Criteria
+
+- All tests pass
+- RuboCop clean
+- Same patterns as CB7/CBT/CBZ
+- No repo pollution
+- Documentation current

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-26
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+veganstraightedge@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.md

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

data/README.md

@@ -0,0 +1,65 @@
+# ComicBook
+
+⚠️ Under construction. ⚠️
+A Ruby library and CLI tool for managing comic books archives.
+
+**`extract`** — to open a `.cb*` file.
+
+**`archive`** — to create a `.cb*` file (default: `.cbz`).
+
+Currently supported formats, `archive` and `extract`:
+- CB7 — [7zip](https://en.wikipedia.org/wiki/7-Zip)
+- CBT — [Tar](https://en.wikipedia.org/wiki/Tar_(computing))
+- CBZ — [Zip](https://en.wikipedia.org/wiki/ZIP_(file_format))
+
+Planned formats , only `extract`:
+
+- **CBR** — [RAR](https://en.wikipedia.org/wiki/WinRAR) is proprietary without an open source implementation license. People use WinRAR (Windows-only) to create .rar files. Or `unrar` on Linux/macOS to open .rar files. Extracting support is provided because a large number of comic books are archived in .cbr/.rar format, primarily by Windows users. No support for creating `.cbr` files will ever be added until RAR is opensource (or reverse engineered).
+- **CBA** — [ACE](https://en.wikipedia.org/wiki/WinAce) is both proprietary and very old/outdated/unsupported. ACE extracting support is provided for historical posterity and completeness.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```sh
+bundle add comicbook
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```sh
+gem install comicbook
+```
+
+## Usage
+
+In Ruby, you can use the `ComicBook` class to `extract` comic books archives from various formats. You `archive` a folder of images to create a comic book archive.
+
+### Extracting
+
+```ruby
+ComicBook.extract 'path/to/archive.cbz'
+```
+### Archiving
+
+```ruby
+ComicBook.archive 'path/to/archive'
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/veganstraightedge/comicbook. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/veganstraightedge/comicbook/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Comicbook project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/veganstraightedge/comicbook/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new :spec
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/SYSTEM.md

@@ -0,0 +1,235 @@
+# ComicBook Ruby - System Documentation
+
+## Overview
+
+ComicBook Ruby is a Ruby library for reading, writing, and manipulating comic book archive files. It provides a unified interface for working with multiple comic book formats including CBZ (ZIP), CB7 (7-Zip), CBT (TAR), CBR (RAR), and CBA (ACE) archives.
+
+## Project Structure
+
+```
+comicbook-ruby/
+├── lib/
+│   ├── comicbook.rb              # Main entry point and public API
+│   └── comic_book/
+│       ├── adapter.rb            # Base adapter class
+│       ├── page.rb               # Page representation
+│       ├── version.rb            # Version constant
+│       ├── cli_helpers.rb        # CLI utility functions
+│       ├── cb7.rb               # CB7 (7-Zip) adapter
+│       ├── cb7/
+│       │   ├── archiver.rb      # CB7 archive creation
+│       │   └── extractor.rb     # CB7 archive extraction
+│       ├── cbt.rb               # CBT (TAR) adapter
+│       ├── cbt/
+│       │   ├── archiver.rb      # CBT archive creation
+│       │   └── extractor.rb     # CBT archive extraction
+│       ├── cbz.rb               # CBZ (ZIP) adapter
+│       ├── cbz/
+│       │   ├── archiver.rb      # CBZ archive creation
+│       │   └── extractor.rb     # CBZ archive extraction
+│       └── vendor/              # Vendored dependencies
+├── spec/                        # RSpec test suite
+│   ├── fixtures/                # Test fixtures for all formats
+│   └── comic_book/              # Organized test files
+└── bin/                         # Executables and development tools
+```
+
+## Architecture
+
+### Core Design Patterns
+
+#### 1. Adapter Pattern
+The system uses the Adapter pattern to provide a unified interface across different comic book archive formats. Each format (CBZ, CB7, CBT, etc.) implements the same interface defined by `ComicBook::Adapter`.
+
+```ruby
+class ComicBook::Adapter
+  def archive(options = {})      # Create archive from folder (to: destination_path)
+  def extract(options = {})      # Extract archive to folder (to: destination_path)
+  def pages                      # Get array of Page objects
+end
+```
+
+#### 2. Strategy Pattern
+The main `ComicBook` class acts as a context that delegates to the appropriate adapter based on file type detection:
+
+```ruby
+def adapter
+  case type
+  when :cb7 then CB7.new path
+  when :cbt then CBT.new path
+  when :cbz then CBZ.new path
+  # ... other formats
+  end
+end
+```
+
+#### 3. Template Method Pattern
+Each adapter family (CB7, CBT, CBZ) follows a consistent structure with separate Archiver and Extractor classes that implement format-specific operations while sharing common patterns.
+
+### Key Components
+
+#### 1. ComicBook (Main Class)
+- **Location**: `lib/comicbook.rb`
+- **Purpose**: Public API entry point and file type detection
+- **Responsibilities**:
+  - File type detection based on extensions
+  - Path validation
+  - Delegation to appropriate adapters
+  - Unified interface for all operations
+
+#### 2. ComicBook::Adapter (Base Class)
+- **Location**: `lib/comic_book/adapter.rb`
+- **Purpose**: Abstract base class for all format adapters
+- **Pattern**: Template method defining common interface
+- **Key Methods**: `archive`, `extract`, `pages`
+
+#### 3. Format Adapters
+Each format has three components:
+
+**Main Adapter** (`cb7.rb`, `cbt.rb`, `cbz.rb`)
+- Inherits from `ComicBook::Adapter`
+- Delegates to Archiver/Extractor classes
+- Implements `pages` method for reading archive contents
+
+**Archiver Classes** (`*/archiver.rb`)
+- Handles creation of archives from source folders
+- Implements format-specific compression
+- Manages file filtering (images only)
+- Supports options like custom extensions and delete_original
+
+**Extractor Classes** (`*/extractor.rb`)
+- Handles extraction of archives to folders
+- Implements format-specific decompression
+- Filters extracted files (images only)
+- Supports custom destinations and extensions
+
+#### 4. ComicBook::Page
+- **Location**: `lib/comic_book/page.rb`
+- **Purpose**: Represents a single page/image within a comic archive
+- **Attributes**: `path` (file path), `name` (display name)
+
+### File Type Support
+
+| Format | Extension | Status | Compression | Dependencies |
+|--------|-----------|--------|-------------|--------------|
+| CBZ | `.cbz` | ✅ Full | ZIP | `rubyzip` gem |
+| CB7 | `.cb7` | ✅ Full | 7-Zip | `seven-zip` gem |
+| CBT | `.cbt` | ✅ Full | TAR | Ruby stdlib |
+| CBR | `.cbr` | 🚧 Planned | RAR | TBD |
+| CBA | `.cba` | 🚧 Planned | ACE | TBD |
+
+### Data Flow
+
+#### Archive Creation Flow
+1. User calls `ComicBook.new(folder_path).archive()`
+2. Main class detects folder type
+3. Delegates to CBZ adapter (default for folders)
+4. CBZ creates Archiver instance
+5. Archiver scans folder for image files
+6. Creates ZIP archive with filtered content
+7. Returns path to created archive
+
+#### Archive Extraction Flow
+1. User calls `ComicBook.new(archive_path).extract()`
+2. Main class detects file type by extension
+3. Delegates to appropriate adapter (CB7, CBT, CBZ)
+4. Adapter creates Extractor instance
+5. Extractor reads archive contents
+6. Filters for image files only
+7. Extracts to destination folder
+8. Returns path to extracted folder
+
+#### Page Reading Flow
+1. User calls `ComicBook.new(archive_path).pages`
+2. Main class delegates to appropriate adapter
+3. Adapter reads archive contents
+4. Filters for image files
+5. Creates Page objects with path and name
+6. Returns sorted array of Page objects
+
+## Configuration & Constants
+
+### Image File Support
+```ruby
+IMAGE_EXTENSIONS   = %w[.jpg .jpeg .png .gif .bmp .webp].freeze
+IMAGE_GLOB_PATTERN = '*.{jpg,jpeg,png,gif,bmp,webp}'.freeze
+```
+
+The system automatically filters files to include only recognized image formats when creating or extracting archives.
+
+### Options Support
+All archive and extract operations support these options:
+- `extension`: Custom file extension for output
+- `delete_original`: Boolean to remove source after operation
+- `destination`: Custom output path
+
+## Dependencies
+
+### Runtime Dependencies
+- **rubyzip** (>= 3.2.1): ZIP file handling for CBZ format
+- **seven-zip** (~> 1.4): 7-Zip handling for CB7 format
+- Ruby stdlib: TAR handling for CBT format
+
+### Development Dependencies
+- **rspec**: Testing framework
+- **rspec-file_fixtures**: Fixture management for tests
+- **rubocop**: Code linting and style enforcement
+
+## Testing Strategy
+
+### Test Organization
+- **Unit Tests**: Individual component testing
+- **Integration Tests**: End-to-end format operations
+- **Fixture-Based**: Real archive files for accurate testing
+
+### TmpDir Pattern
+All tests use `Dir.mktmpdir` for file I/O operations to ensure:
+- No files created in repository root
+- Proper cleanup after each test
+- Isolation between test runs
+
+### Test Coverage
+- 173 examples across all components
+- Full coverage of archive/extract/pages operations
+- Edge cases: empty archives, non-image files, nested folders
+
+## Performance Considerations
+
+### Memory Usage
+- Streaming operations where possible
+- No full file loading into memory for large archives
+- Lazy page enumeration
+
+### File I/O
+- Temporary directory usage prevents repository pollution
+- Atomic operations with proper cleanup
+- Path normalization for cross-platform compatibility
+
+## Error Handling
+
+### Exception Hierarchy
+```ruby
+ComicBook::Error < StandardError
+```
+
+### Common Error Cases
+- Unsupported file types
+- Missing dependencies for format handlers
+- Invalid or corrupted archive files
+- Permission issues during file operations
+
+## Future Extensibility
+
+### Adding New Formats
+1. Create new adapter class inheriting from `ComicBook::Adapter`
+2. Implement archiver and extractor classes
+3. Add format detection to main `ComicBook` class
+4. Add comprehensive test suite following existing patterns
+
+### Plugin Architecture
+The adapter pattern makes it easy to add new formats or extend existing ones without modifying core functionality.
+
+## Version Information
+- **Current Version**: 0.1.0
+- **Ruby Requirement**: >= 3.4.7
+- **License**: MIT

data/exe/comicbook

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/comicbook'
+require_relative '../lib/comic_book/cli'
+
+ComicBook::CLI.start ARGV

data/lib/comic_book/adapter.rb

@@ -0,0 +1,26 @@
+# NOTE: don't use ComicBook::Adapter.new directly
+#       Inherit from it when making an adapter to formats:
+#       .cb7 .cba .cbr .cbt .cbz
+class ComicBook
+  class Adapter
+    def initialize path
+      @path = File.expand_path path
+    end
+
+    def archive options = {}
+      raise NotImplementedError, "#{self.class} must implement #archive"
+    end
+
+    def extract options = {}
+      raise NotImplementedError, "#{self.class} must implement #extract"
+    end
+
+    def pages
+      raise NotImplementedError, "#{self.class} must implement #pages"
+    end
+
+    private
+
+    attr_reader :path
+  end
+end

data/lib/comic_book/cb7/archiver.rb

@@ -0,0 +1,58 @@
+class ComicBook
+  class CB7 < Adapter
+    class Archiver
+      def initialize source_folder
+        @source_folder = File.expand_path source_folder
+      end
+
+      def archive options = {}
+        extension       = options.fetch :extension, :cb7
+        delete_original = options.fetch :delete_original, false
+
+        output_path = options[:to] || determine_output_path(extension)
+        create_7z_archive output_path
+        cleanup_source_folder if delete_original
+
+        output_path
+      end
+
+      private
+
+      attr_reader :source_folder
+
+      def determine_output_path extension
+        base_name = File.basename source_folder, '.*'
+        dir_name  = File.dirname source_folder
+
+        File.expand_path File.join(dir_name, "#{base_name}.#{extension}")
+      end
+
+      def create_7z_archive output_path
+        File.open(output_path, 'wb') do |file|
+          SevenZipRuby::Writer.open(file) do |szw|
+            find_image_files.each do |image_file|
+              add_file_to_7z szw, image_file
+            end
+          end
+        end
+      end
+
+      def find_image_files
+        pattern = File.join(source_folder, '**', ComicBook::IMAGE_GLOB_PATTERN)
+        Dir.glob(pattern, File::FNM_CASEFOLD).sort
+      end
+
+      def add_file_to_7z szw, file
+        file_path     = Pathname.new file
+        source_path   = Pathname.new source_folder
+        relative_path = file_path.relative_path_from source_path
+
+        szw.add_file file, as: relative_path.to_s
+      end
+
+      def cleanup_source_folder
+        FileUtils.rm_rf source_folder
+      end
+    end
+  end
+end