chore(deps): update anchore/sbom-action action to v0.21.1 (#155)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.github/copilot-instructions.md

@@ -0,0 +1,309 @@
+# CBZOptimizer - GitHub Copilot Instructions
+
+## Project Overview
+
+CBZOptimizer is a Go-based command-line tool designed to optimize CBZ (Comic Book Zip) and CBR (Comic Book RAR) files by converting images to modern formats (primarily WebP) with configurable quality settings. The tool reduces the size of comic book archives while maintaining acceptable image quality.
+
+**Key Features:**
+- Convert CBZ/CBR files to optimized CBZ format
+- WebP image encoding with quality control
+- Parallel chapter processing
+- File watching for automatic optimization
+- Optional page splitting for large images
+- Timeout handling for problematic files
+
+## Technology Stack
+
+- **Language:** Go 1.25+
+- **CLI Framework:** Cobra + Viper
+- **Logging:** zerolog (structured logging)
+- **Image Processing:** go-webpbin/v2 for WebP encoding
+- **Archive Handling:** mholt/archives for CBZ/CBR processing
+- **Testing:** testify + gotestsum
+
+## Project Structure
+
+```
+.
+├── cmd/
+│   ├── cbzoptimizer/         # Main CLI application
+│   │   ├── commands/         # Cobra commands (optimize, watch)
+│   │   └── main.go          # Entry point
+│   └── encoder-setup/        # WebP encoder setup utility
+│       └── main.go          # Encoder initialization (build tag: encoder_setup)
+├── internal/
+│   ├── cbz/                 # CBZ/CBR file operations
+│   │   ├── cbz_loader.go   # Load and parse comic archives
+│   │   └── cbz_creator.go  # Create optimized archives
+│   ├── manga/              # Domain models
+│   │   ├── chapter.go      # Chapter representation
+│   │   ├── page.go         # Page image handling
+│   │   └── page_container.go # Page collection management
+│   └── utils/              # Utility functions
+│       ├── optimize.go     # Core optimization logic
+│       └── errs/           # Error handling utilities
+└── pkg/
+    └── converter/          # Image conversion abstractions
+        ├── converter.go    # Converter interface
+        ├── webp/          # WebP implementation
+        │   ├── webp_converter.go    # WebP conversion logic
+        │   └── webp_provider.go     # WebP encoder provider
+        ├── errors/        # Conversion error types
+        └── constant/      # Shared constants
+```
+
+## Building and Testing
+
+### Prerequisites
+
+Before building or testing, the WebP encoder must be set up:
+
+```bash
+# Build the encoder-setup utility
+go build -tags encoder_setup -o encoder-setup ./cmd/encoder-setup
+
+# Run encoder setup (downloads and configures libwebp 1.6.0)
+./encoder-setup
+```
+
+This step is **required** before running tests or building the main application.
+
+### Build Commands
+
+```bash
+# Build the main application
+go build -o cbzconverter ./cmd/cbzoptimizer
+
+# Build with version information
+go build -ldflags "-s -w -X main.version=1.0.0 -X main.commit=abc123 -X main.date=2024-01-01" -o cbzconverter ./cmd/cbzoptimizer
+```
+
+### Testing
+
+```bash
+# Install test runner
+go install gotest.tools/gotestsum@latest
+
+# Run all tests with coverage
+gotestsum --format testname -- -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+# Run specific package tests
+go test -v ./internal/cbz/...
+go test -v ./pkg/converter/...
+
+# Run integration tests
+go test -v ./internal/utils/...
+```
+
+### Linting
+
+```bash
+# Install golangci-lint if not available
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+# Run linter
+golangci-lint run
+```
+
+## Code Conventions
+
+### Go Style
+
+- **Follow standard Go conventions:** Use `gofmt` and `goimports`
+- **Package naming:** Short, lowercase, single-word names
+- **Error handling:** Always check errors explicitly; use structured error wrapping with `fmt.Errorf("context: %w", err)`
+- **Context usage:** Pass `context.Context` as first parameter for operations that may be cancelled
+
+### Logging
+
+Use **zerolog** for all logging:
+
+```go
+import "github.com/rs/zerolog/log"
+
+// Info level with structured fields
+log.Info().Str("file", path).Int("pages", count).Msg("Processing file")
+
+// Debug level for detailed diagnostics
+log.Debug().Str("file", path).Uint8("quality", quality).Msg("Optimization parameters")
+
+// Error level with error wrapping
+log.Error().Str("file", path).Err(err).Msg("Failed to load chapter")
+```
+
+**Log Levels (in order of verbosity):**
+- `panic` - System panic conditions
+- `fatal` - Fatal errors requiring exit
+- `error` - Error conditions
+- `warn` - Warning conditions
+- `info` - General information (default)
+- `debug` - Debug-level messages
+- `trace` - Trace-level messages
+
+### Error Handling
+
+- Use the custom `errs` package for deferred error handling:
+  ```go
+  import "github.com/belphemur/CBZOptimizer/v2/internal/utils/errs"
+  
+  func processFile() (err error) {
+      defer errs.Wrap(&err, "failed to process file")
+      // ... implementation
+  }
+  ```
+
+- Define custom error types in `pkg/converter/errors/` for specific error conditions
+- Always provide context when wrapping errors
+
+### Testing
+
+- Use **testify** for assertions:
+  ```go
+  import "github.com/stretchr/testify/assert"
+  
+  func TestSomething(t *testing.T) {
+      result, err := DoSomething()
+      assert.NoError(t, err)
+      assert.Equal(t, expected, result)
+  }
+  ```
+
+- Use table-driven tests for multiple scenarios:
+  ```go
+  testCases := []struct {
+      name        string
+      input       string
+      expected    string
+      expectError bool
+  }{
+      {"case1", "input1", "output1", false},
+      {"case2", "input2", "output2", true},
+  }
+  
+  for _, tc := range testCases {
+      t.Run(tc.name, func(t *testing.T) {
+          // test implementation
+      })
+  }
+  ```
+
+- Integration tests should be in `*_integration_test.go` files
+- Use temporary directories for file operations in tests
+
+### Command Structure (Cobra)
+
+- Commands are in `cmd/cbzoptimizer/commands/`
+- Each command is in its own file (e.g., `optimize_command.go`, `watch_command.go`)
+- Use Cobra's persistent flags for global options
+- Use Viper for configuration management
+
+### Dependencies
+
+**Key external packages:**
+- `github.com/belphemur/go-webpbin/v2` - WebP encoding (libwebp wrapper)
+- `github.com/mholt/archives` - Archive format handling
+- `github.com/spf13/cobra` - CLI framework
+- `github.com/spf13/viper` - Configuration management
+- `github.com/rs/zerolog` - Structured logging
+- `github.com/oliamb/cutter` - Image cropping for page splitting
+- `golang.org/x/image` - Extended image format support
+
+## Docker Considerations
+
+The Dockerfile uses a multi-stage build and requires:
+1. The compiled `CBZOptimizer` binary (from goreleaser)
+2. The `encoder-setup` binary (built with `-tags encoder_setup`)
+3. The encoder-setup is run during image build to configure WebP encoder
+
+The encoder must be set up in the container before the application runs.
+
+## Common Tasks
+
+### Adding a New Command
+
+1. Create `cmd/cbzoptimizer/commands/newcommand_command.go`
+2. Define the command using Cobra:
+   ```go
+   var newCmd = &cobra.Command{
+       Use:   "new",
+       Short: "Description",
+       RunE: func(cmd *cobra.Command, args []string) error {
+           // implementation
+       },
+   }
+   
+   func init() {
+       rootCmd.AddCommand(newCmd)
+   }
+   ```
+3. Add tests in `newcommand_command_test.go`
+
+### Adding a New Image Format Converter
+
+1. Create a new package under `pkg/converter/` (e.g., `avif/`)
+2. Implement the `Converter` interface from `pkg/converter/converter.go`
+3. Add tests following existing patterns in `pkg/converter/webp/`
+4. Update command flags to support the new format
+
+### Modifying Optimization Logic
+
+The core optimization logic is in `internal/utils/optimize.go`:
+- Uses the `OptimizeOptions` struct for parameters
+- Handles chapter loading, conversion, and saving
+- Implements timeout handling with context
+- Provides structured logging at each step
+
+## CI/CD
+
+### GitHub Actions Workflows
+
+1. **test.yml** - Runs on every push/PR
+   - Sets up Go environment
+   - Runs encoder-setup
+   - Executes tests with coverage
+   - Uploads results to Codecov
+
+2. **release.yml** - Runs on version tags
+   - Uses goreleaser for multi-platform builds
+   - Builds Docker images for linux/amd64 and linux/arm64
+   - Signs releases with cosign
+   - Generates SBOMs with syft
+
+3. **qodana.yml** - Code quality analysis
+
+### Release Process
+
+Releases are automated via goreleaser:
+- Tag format: `v*` (e.g., `v2.1.0`)
+- Builds for: linux, darwin, windows (amd64, arm64)
+- Creates Docker images and pushes to ghcr.io
+- Generates checksums and SBOMs
+
+## Performance Considerations
+
+- **Parallelism:** Use `--parallelism` flag to control concurrent chapter processing
+- **Memory:** Large images are processed in-memory; consider system RAM when setting parallelism
+- **Timeouts:** Use `--timeout` flag to prevent hanging on problematic files
+- **WebP Quality:** Balance quality (0-100) vs file size; default is 85
+
+## Security
+
+- No credentials or secrets should be committed
+- Archive extraction includes path traversal protection
+- File permissions are preserved during operations
+- Docker images run as non-root user (`abc`, UID 99)
+
+## Additional Notes
+
+- CBR files are always converted to CBZ format (RAR is read-only)
+- The `--override` flag deletes the original file after successful conversion
+- Page splitting is useful for double-page spreads or very tall images
+- Watch mode uses inotify on Linux for efficient file monitoring
+- Bash completion is available via `cbzconverter completion bash`
+
+## Getting Help
+
+- Use `--help` flag for command documentation
+- Use `--log debug` for detailed diagnostic output
+- Check GitHub Issues for known problems
+- Review test files for usage examples

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,69 @@
+name: Copilot Setup Steps
+permissions:
+  contents: read
+
+on:
+  workflow_dispatch:
+
+jobs:
+  copilot-setup-steps:
+    name: Setup Go and gopls
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Verify Go installation
+        run: |
+          go version
+          go env
+
+      - name: Install gopls
+        run: |
+          go install golang.org/x/tools/gopls@latest
+
+      - name: Verify gopls installation
+        run: |
+          gopls version
+
+      - name: Install golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: latest
+
+      - name: Download Go dependencies
+        run: |
+          go mod download
+          go mod verify
+
+      - name: Build encoder-setup utility
+        run: |
+          go build -tags encoder_setup -o encoder-setup ./cmd/encoder-setup
+          ls -lh encoder-setup
+
+      - name: Run encoder-setup
+        run: |
+          ./encoder-setup
+
+      - name: Install gotestsum
+        run: |
+          go install gotest.tools/gotestsum@latest
+
+      - name: Verify gotestsum installation
+        run: |
+          gotestsum --version
+
+      - name: Setup complete
+        run: |
+          echo "✅ Go environment setup complete"
+          echo "✅ gopls (Go language server) installed"
+          echo "✅ golangci-lint installed"
+          echo "✅ Dependencies downloaded and verified"
+          echo "✅ WebP encoder configured (libwebp 1.6.0)"
+          echo "✅ gotestsum (test runner) installed"

.github/workflows/qodana.yml

@@ -13,7 +13,7 @@ jobs:
       pull-requests: write
       checks: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}  # to check out the actual pull request commit, not the merge commit
           fetch-depth: 0  # a full history is required for pull request analysis

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0 # this is important, otherwise it won't checkout the full tree (i.e. no previous tags)
       - name: Set up Go
@@ -28,28 +28,32 @@ jobs:
         with:
           go-version-file: go.mod
           cache: true
-      - uses: sigstore/cosign-installer@v3.9.2 # installs cosign
-      - uses: anchore/sbom-action/download-syft@v0.20.5 # installs syft
+      - name: Install Syft
+        uses: anchore/sbom-action/download-syft@v0.21.1 # installs syft
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
-      - uses: docker/login-action@v3 # login to ghcr
+      - name: Log in to GHCR
+        uses: docker/login-action@v3 # login to ghcr
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
-      - uses: goreleaser/goreleaser-action@v6 # run goreleaser
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6 # run goreleaser
         with:
           version: nightly
           args: release --clean --verbose
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       # After GoReleaser runs, attest all the files in ./dist/checksums.txt:
-      - uses: actions/attest-build-provenance@v3
+      - name: Attest Build Provenance for Archives
+        uses: actions/attest-build-provenance@v3
         with:
           subject-checksums: ./dist/checksums.txt
       # After GoReleaser runs, attest all the images in ./dist/digests.txt:
-      - uses: actions/attest-build-provenance@v3
+      - name: Attest Build Provenance for Docker Images
+        uses: actions/attest-build-provenance@v3
         with:
           subject-checksums: ./dist/digests.txt

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
     name: Test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Set up Go
         uses: actions/setup-go@v6
@@ -31,7 +31,7 @@ jobs:
 
       - name: Upload test result artifact
         if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: test-results
           path: |

.goreleaser.yml

@@ -1,10 +1,20 @@
 # .goreleaser.yml
 version: 2
 project_name: CBZOptimizer
+
+# Configures the release process on GitHub
+# https://goreleaser.com/customization/release/
 release:
   github:
     owner: belphemur
     name: CBZOptimizer
+  include_meta: true
+  # draft: false # Default is false
+  # prerelease: auto # Default is auto
+  # mode: replace # Default is append
+
+# Configures the binary archive generation
+# https://goreleaser.com/customization/archive/
 archives:
   - ids:
       - cbzoptimizer
@@ -14,7 +24,11 @@ archives:
         goos: windows
         formats: ["zip"] # Plural form, multiple formats. Since: v2.6
 
+# Configures the changelog generation
+# https://goreleaser.com/customization/changelog/
 changelog:
+  use: github
+  format: "{{.SHA}}: {{.Message}} (@{{.AuthorUsername}})"
   sort: asc
   filters:
     exclude:
@@ -31,6 +45,16 @@ changelog:
     - title: "Performance"
       regexp: '^.*?perf(\([[:word:]]+\))??!?:.+$'
       order: 2
+
+# Hooks to run before the build process starts
+# https://goreleaser.com/customization/hooks/
+before:
+  hooks:
+    - go mod tidy
+    - go generate ./...
+
+# Configures the Go build process
+# https://goreleaser.com/customization/build/
 builds:
   - id: cbzoptimizer
     main: cmd/cbzoptimizer/main.go
@@ -72,29 +96,37 @@ builds:
       - -s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{ .CommitDate }}
     env:
       - CGO_ENABLED=0
-# config the checksum filename
-# https://goreleaser.com/customization/checksum
+
+# Configures the checksum file generation
+# https://goreleaser.com/customization/checksum/
 checksum:
   name_template: "checksums.txt"
-# Change the digests filename:
+
+# Change the digests filename for attestation
+# https://goreleaser.com/customization/docker_digest/
 docker_digest:
   name_template: "digests.txt"
-# create a source tarball
+
+# Creates a source code archive (tar.gz and zip)
 # https://goreleaser.com/customization/source/
 source:
   enabled: true
-# proxies from the go mod proxy before building
-# https://goreleaser.com/customization/gomod
+
+# Configures Go Modules settings
+# https://goreleaser.com/customization/gomod/
 gomod:
   proxy: true
-# creates SBOMs of all archives and the source tarball using syft
-# https://goreleaser.com/customization/sbom
+
+# Creates SBOMs (Software Bill of Materials)
+# https://goreleaser.com/customization/sbom/
 sboms:
-  - artifacts: archive
-  - id: source # Two different sbom configurations need two different IDs
-    artifacts: source
-# create a docker image
-# https://goreleaser.com/customization/docker
+  - id: archive # Default ID for archive SBOMs
+    artifacts: archive # Generate SBOMs for binary archives using Syft
+  - id: source # Unique ID for source SBOM
+    artifacts: source # Generate SBOM for the source code archive
+
+# Creates Docker images and pushes them to registries using Docker v2 API
+# https://goreleaser.com/customization/docker/
 dockers_v2:
   - id: cbzoptimizer-image
     ids:
@@ -108,6 +140,13 @@ dockers_v2:
     tags:
       - "{{ .Version }}"
       - latest
+    annotations:
+      "org.opencontainers.image.description": "CBZOptimizer is a Go-based tool designed to optimize CBZ (Comic Book Zip) and CBR (Comic Book RAR) files by converting images to a specified format and quality. This tool is useful for reducing the size of comic book archives while maintaining acceptable image quality."
+      "org.opencontainers.image.created": "{{.Date}}"
+      "org.opencontainers.image.name": "{{.ProjectName}}"
+      "org.opencontainers.image.revision": "{{.FullCommit}}"
+      "org.opencontainers.image.version": "{{.Version}}"
+      "org.opencontainers.image.source": "{{.GitURL}}"
     labels:
       "org.opencontainers.image.created": "{{.Date}}"
       "org.opencontainers.image.name": "{{.ProjectName}}"
@@ -115,30 +154,3 @@ dockers_v2:
       "org.opencontainers.image.version": "{{.Version}}"
       "org.opencontainers.image.source": "{{.GitURL}}"
       "org.opencontainers.image.description": "CBZOptimizer is a Go-based tool designed to optimize CBZ (Comic Book Zip) and CBR (Comic Book RAR) files by converting images to a specified format and quality. This tool is useful for reducing the size of comic book archives while maintaining acceptable image quality."
-# signs the checksum file
-# all files (including the sboms) are included in the checksum, so we don't need to sign each one if we don't want to
-# https://goreleaser.com/customization/sign
-signs:
-  - cmd: cosign
-    env:
-      - COSIGN_EXPERIMENTAL=1
-    certificate: "${artifact}.pem"
-    args:
-      - sign-blob
-      - "--output-certificate=${certificate}"
-      - "--output-signature=${signature}"
-      - "${artifact}"
-      - "--yes" # needed on cosign 2.0.0+
-    artifacts: checksum
-    output: true
-# signs our docker image
-# https://goreleaser.com/customization/docker_sign
-docker_signs:
-  - cmd: cosign
-    env:
-      - COSIGN_EXPERIMENTAL=1
-    output: true
-    args:
-      - "sign"
-      - "${artifact}"
-      - "--yes" # needed on cosign 2.0.0+

Dockerfile

@@ -24,7 +24,6 @@ COPY ${TARGETPLATFORM}/CBZOptimizer ${APP_PATH}
 
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    --mount=type=bind,source=${TARGETPLATFORM},target=/tmp/target \
     apt-get update && \
     apt-get full-upgrade -y && \
     apt-get install -y --no-install-recommends \
@@ -32,10 +31,14 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     bash \
     ca-certificates \
     bash-completion && \
-    /tmp/target/encoder-setup && \
     chmod +x ${APP_PATH} && \
     ${APP_PATH} completion bash > /etc/bash_completion.d/CBZOptimizer.bash
 
 
 USER ${USER}
+
+# Need to run as the user to have the right config folder created
+RUN --mount=type=bind,source=${TARGETPLATFORM},target=/tmp/target \
+    /tmp/target/encoder-setup
+
 ENTRYPOINT ["/usr/local/bin/CBZOptimizer"]

README.md

@@ -42,6 +42,22 @@ Optimize all CBZ/CBR files in a folder recursively:
 cbzconverter optimize [folder] --quality 85 --parallelism 2 --override --format webp --split
 ```
 
+The format flag can be specified in multiple ways:
+
+```sh
+# Using space-separated syntax
+cbzconverter optimize [folder] --format webp
+
+# Using short form with space
+cbzconverter optimize [folder] -f webp
+
+# Using equals syntax
+cbzconverter optimize [folder] --format=webp
+
+# Format is case-insensitive
+cbzconverter optimize [folder] --format WEBP
+```
+
 With timeout to avoid hanging on problematic chapters:
 
 ```sh
@@ -74,7 +90,9 @@ docker run -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest watc
 - `--parallelism`, `-n`: Number of chapters to convert in parallel. Default is 2.
 - `--override`, `-o`: Override the original files. For CBZ files, overwrites the original. For CBR files, deletes the original CBR and creates a new CBZ. Default is false.
 - `--split`, `-s`: Split long pages into smaller chunks. Default is false.
-- `--format`, `-f`: Format to convert the images to (e.g., webp). Default is webp.
+- `--format`, `-f`: Format to convert the images to (currently supports: webp). Default is webp.
+  - Can be specified as: `--format webp`, `-f webp`, or `--format=webp`
+  - Case-insensitive: `webp`, `WEBP`, and `WebP` are all valid
 - `--timeout`, `-t`: Maximum time allowed for converting a single chapter (e.g., 30s, 5m, 1h). 0 means no timeout. Default is 0.
 - `--log`, `-l`: Set log level; can be 'panic', 'fatal', 'error', 'warn', 'info', 'debug', or 'trace'. Default is info.
 
@@ -139,15 +157,81 @@ LOG_LEVEL=warn cbzconverter optimize comics/
 docker run -e LOG_LEVEL=debug -v /path/to/comics:/comics ghcr.io/belphemur/cbzoptimizer:latest optimize /comics
 ```
 
-## Requirements
-
-- For Docker usage: No additional requirements needed
-- For binary usage: Needs `libwebp` installed on the system for WebP conversion
-
 ## Docker Image
 
 The official Docker image is available at: `ghcr.io/belphemur/cbzoptimizer:latest`
 
+### Docker Compose
+
+You can use Docker Compose to run CBZOptimizer with persistent configuration. Create a `docker-compose.yml` file:
+
+```yaml
+version: '3.8'
+
+services:
+  cbzoptimizer:
+    image: ghcr.io/belphemur/cbzoptimizer:latest
+    container_name: cbzoptimizer
+    environment:
+      # Set log level (panic, fatal, error, warn, info, debug, trace)
+      - LOG_LEVEL=info
+      # User and Group ID for file permissions
+      - PUID=99
+      - PGID=100
+    volumes:
+      # Mount your comics directory
+      - /path/to/your/comics:/comics
+      # Optional: Mount a config directory for persistent settings
+      - ./config:/config
+    # Example: Optimize all comics in the /comics directory
+    command: optimize /comics --quality 85 --parallelism 2 --override --format webp --split
+    restart: unless-stopped
+```
+
+For watch mode, you can create a separate service:
+
+```yaml
+  cbzoptimizer-watch:
+    image: ghcr.io/belphemur/cbzoptimizer:latest
+    container_name: cbzoptimizer-watch
+    environment:
+      - LOG_LEVEL=info
+      - PUID=99
+      - PGID=100
+    volumes:
+      - /path/to/watch/directory:/watch
+      - ./config:/config
+    # Watch for new files and automatically optimize them
+    command: watch /watch --quality 85 --override --format webp --split
+    restart: unless-stopped
+```
+
+**Important Notes:**
+- Replace `/path/to/your/comics` and `/path/to/watch/directory` with your actual directory paths
+- The `PUID` and `PGID` environment variables control file permissions (default: 99/100)
+- The `LOG_LEVEL` environment variable sets the logging verbosity
+- For one-time optimization, remove the `restart: unless-stopped` line
+- Watch mode only works on Linux systems
+
+#### Running with Docker Compose
+
+```sh
+# Start the service (one-time optimization)
+docker-compose up cbzoptimizer
+
+# Start in detached mode
+docker-compose up -d cbzoptimizer
+
+# Start watch mode service
+docker-compose up -d cbzoptimizer-watch
+
+# View logs
+docker-compose logs -f cbzoptimizer
+
+# Stop services
+docker-compose down
+```
+
 ## Troubleshooting
 
 If you encounter issues:

cmd/cbzoptimizer/commands/flags.go

@@ -0,0 +1,100 @@
+package commands
+
+import (
+	"fmt"
+
+	"github.com/belphemur/CBZOptimizer/v2/pkg/converter/constant"
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+	"github.com/thediveo/enumflag/v2"
+)
+
+// setupFormatFlag sets up the format flag for a command.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the format flag to
+//   - converterType: Pointer to the ConversionFormat variable that will store the flag value
+//   - bindViper: If true, binds the flag to viper for configuration file support.
+//     Set to true for commands that use viper for configuration (e.g., watch command),
+//     and false for commands that don't (e.g., optimize command).
+func setupFormatFlag(cmd *cobra.Command, converterType *constant.ConversionFormat, bindViper bool) {
+	formatFlag := enumflag.New(converterType, "format", constant.CommandValue, enumflag.EnumCaseInsensitive)
+	_ = formatFlag.RegisterCompletion(cmd, "format", constant.HelpText)
+	
+	cmd.Flags().VarP(
+		formatFlag,
+		"format", "f",
+		fmt.Sprintf("Format to convert the images to: %s", constant.ListAll()))
+	
+	if bindViper {
+		_ = viper.BindPFlag("format", cmd.Flags().Lookup("format"))
+	}
+}
+
+// setupQualityFlag sets up the quality flag for a command.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the quality flag to
+//   - defaultValue: The default quality value (0-100)
+//   - bindViper: If true, binds the flag to viper for configuration file support
+func setupQualityFlag(cmd *cobra.Command, defaultValue uint8, bindViper bool) {
+	cmd.Flags().Uint8P("quality", "q", defaultValue, "Quality for conversion (0-100)")
+	if bindViper {
+		_ = viper.BindPFlag("quality", cmd.Flags().Lookup("quality"))
+	}
+}
+
+// setupOverrideFlag sets up the override flag for a command.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the override flag to
+//   - defaultValue: The default override value
+//   - bindViper: If true, binds the flag to viper for configuration file support
+func setupOverrideFlag(cmd *cobra.Command, defaultValue bool, bindViper bool) {
+	cmd.Flags().BoolP("override", "o", defaultValue, "Override the original CBZ/CBR files")
+	if bindViper {
+		_ = viper.BindPFlag("override", cmd.Flags().Lookup("override"))
+	}
+}
+
+// setupSplitFlag sets up the split flag for a command.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the split flag to
+//   - defaultValue: The default split value
+//   - bindViper: If true, binds the flag to viper for configuration file support
+func setupSplitFlag(cmd *cobra.Command, defaultValue bool, bindViper bool) {
+	cmd.Flags().BoolP("split", "s", defaultValue, "Split long pages into smaller chunks")
+	if bindViper {
+		_ = viper.BindPFlag("split", cmd.Flags().Lookup("split"))
+	}
+}
+
+// setupTimeoutFlag sets up the timeout flag for a command.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the timeout flag to
+//   - bindViper: If true, binds the flag to viper for configuration file support
+func setupTimeoutFlag(cmd *cobra.Command, bindViper bool) {
+	cmd.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter (e.g., 30s, 5m, 1h). 0 means no timeout")
+	if bindViper {
+		_ = viper.BindPFlag("timeout", cmd.Flags().Lookup("timeout"))
+	}
+}
+
+// setupCommonFlags sets up all common flags for optimize and watch commands.
+//
+// Parameters:
+//   - cmd: The Cobra command to add the flags to
+//   - converterType: Pointer to the ConversionFormat variable that will store the format flag value
+//   - qualityDefault: The default quality value (0-100)
+//   - overrideDefault: The default override value
+//   - splitDefault: The default split value
+//   - bindViper: If true, binds all flags to viper for configuration file support
+func setupCommonFlags(cmd *cobra.Command, converterType *constant.ConversionFormat, qualityDefault uint8, overrideDefault bool, splitDefault bool, bindViper bool) {
+	setupFormatFlag(cmd, converterType, bindViper)
+	setupQualityFlag(cmd, qualityDefault, bindViper)
+	setupOverrideFlag(cmd, overrideDefault, bindViper)
+	setupSplitFlag(cmd, splitDefault, bindViper)
+	setupTimeoutFlag(cmd, bindViper)
+}

cmd/cbzoptimizer/commands/optimize_command.go

@@ -12,7 +12,6 @@ import (
 	"github.com/belphemur/CBZOptimizer/v2/pkg/converter/constant"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"github.com/thediveo/enumflag/v2"
 )
 
 var converterType constant.ConversionFormat
@@ -25,19 +24,12 @@ func init() {
 		RunE:  ConvertCbzCommand,
 		Args:  cobra.ExactArgs(1),
 	}
-	formatFlag := enumflag.New(&converterType, "format", constant.CommandValue, enumflag.EnumCaseInsensitive)
-	_ = formatFlag.RegisterCompletion(command, "format", constant.HelpText)
 	
-	command.Flags().Uint8P("quality", "q", 85, "Quality for conversion (0-100)")
+	// Setup common flags (format, quality, override, split, timeout)
+	setupCommonFlags(command, &converterType, 85, false, false, false)
+	
+	// Setup optimize-specific flags
 	command.Flags().IntP("parallelism", "n", 2, "Number of chapters to convert in parallel")
-	command.Flags().BoolP("override", "o", false, "Override the original CBZ/CBR files")
-	command.Flags().BoolP("split", "s", false, "Split long pages into smaller chunks")
-	command.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter (e.g., 30s, 5m, 1h). 0 means no timeout")
-	command.PersistentFlags().VarP(
-		formatFlag,
-		"format", "f",
-		fmt.Sprintf("Format to convert the images to: %s", constant.ListAll()))
-	command.PersistentFlags().Lookup("format").NoOptDefVal = constant.DefaultConversion.String()
 
 	AddCommand(command)
 }

cmd/cbzoptimizer/commands/optimize_command_test.go

@@ -2,6 +2,7 @@ package commands
 
 import (
 	"context"
+	"fmt"
 	"log"
 	"os"
 	"path/filepath"
@@ -172,3 +173,374 @@ func TestConvertCbzCommand(t *testing.T) {
 	// Log summary
 	t.Logf("Found %d converted files", len(convertedFiles))
 }
+
+// setupTestCommand creates a test command with all required flags for testing.
+// It mocks the converter.Get function and sets up a complete command with all flags.
+//
+// Returns:
+//   - *cobra.Command: A configured command ready for testing
+//   - func(): A cleanup function that must be deferred to restore the original converter.Get
+func setupTestCommand(t *testing.T) (*cobra.Command, func()) {
+	t.Helper()
+	// Mock the converter.Get function
+	originalGet := converter.Get
+	converter.Get = func(format constant.ConversionFormat) (converter.Converter, error) {
+		return &MockConverter{}, nil
+	}
+	cleanup := func() { converter.Get = originalGet }
+	
+	// Set up the command
+	cmd := &cobra.Command{
+		Use: "optimize",
+	}
+	cmd.Flags().Uint8P("quality", "q", 85, "Quality for conversion (0-100)")
+	cmd.Flags().IntP("parallelism", "n", 1, "Number of chapters to convert in parallel")
+	cmd.Flags().BoolP("override", "o", false, "Override the original CBZ/CBR files")
+	cmd.Flags().BoolP("split", "s", false, "Split long pages into smaller chunks")
+	cmd.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter")
+	
+	// Reset converterType to default before test for consistency
+	converterType = constant.DefaultConversion
+	setupFormatFlag(cmd, &converterType, false)
+	
+	return cmd, cleanup
+}
+
+// TestFormatFlagWithSpace tests that the format flag works with space-separated values
+func TestFormatFlagWithSpace(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_format_space")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	cmd, cleanup := setupTestCommand(t)
+	defer cleanup()
+
+	// Test with space-separated format flag (--format webp)
+	cmd.ParseFlags([]string{"--format", "webp"})
+	
+	// Execute the command
+	err = ConvertCbzCommand(cmd, []string{tempDir})
+	if err != nil {
+		t.Fatalf("Command execution failed with --format webp: %v", err)
+	}
+
+	// Verify the format was set correctly
+	if converterType != constant.WebP {
+		t.Errorf("Expected format to be WebP, got %v", converterType)
+	}
+}
+
+// TestFormatFlagWithShortForm tests that the short form of format flag works with space-separated values
+func TestFormatFlagWithShortForm(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_format_short")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	cmd, cleanup := setupTestCommand(t)
+	defer cleanup()
+
+	// Test with short form and space (-f webp)
+	cmd.ParseFlags([]string{"-f", "webp"})
+	
+	// Execute the command
+	err = ConvertCbzCommand(cmd, []string{tempDir})
+	if err != nil {
+		t.Fatalf("Command execution failed with -f webp: %v", err)
+	}
+
+	// Verify the format was set correctly
+	if converterType != constant.WebP {
+		t.Errorf("Expected format to be WebP, got %v", converterType)
+	}
+}
+
+// TestFormatFlagWithEquals tests that the format flag works with equals syntax
+func TestFormatFlagWithEquals(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_format_equals")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	cmd, cleanup := setupTestCommand(t)
+	defer cleanup()
+
+	// Test with equals syntax (--format=webp)
+	cmd.ParseFlags([]string{"--format=webp"})
+	
+	// Execute the command
+	err = ConvertCbzCommand(cmd, []string{tempDir})
+	if err != nil {
+		t.Fatalf("Command execution failed with --format=webp: %v", err)
+	}
+
+	// Verify the format was set correctly
+	if converterType != constant.WebP {
+		t.Errorf("Expected format to be WebP, got %v", converterType)
+	}
+}
+
+// TestFormatFlagDefaultValue tests that the default format is used when flag is not provided
+func TestFormatFlagDefaultValue(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_format_default")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	cmd, cleanup := setupTestCommand(t)
+	defer cleanup()
+
+	// Don't set format flag - should use default
+	cmd.ParseFlags([]string{})
+	
+	// Execute the command
+	err = ConvertCbzCommand(cmd, []string{tempDir})
+	if err != nil {
+		t.Fatalf("Command execution failed with default format: %v", err)
+	}
+
+	// Verify the default format is used
+	if converterType != constant.DefaultConversion {
+		t.Errorf("Expected format to be default (%v), got %v", constant.DefaultConversion, converterType)
+	}
+}
+
+// TestFormatFlagCaseInsensitive tests that the format flag is case-insensitive
+func TestFormatFlagCaseInsensitive(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_format_case")
+	if err != nil {
+		t.Fatalf("Failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	testCases := []string{"webp", "WEBP", "WebP", "WeBp"}
+
+	for _, formatValue := range testCases {
+		t.Run(formatValue, func(t *testing.T) {
+			cmd, cleanup := setupTestCommand(t)
+			defer cleanup()
+
+			// Test with different case variations
+			cmd.ParseFlags([]string{"--format", formatValue})
+			
+			// Execute the command
+			err = ConvertCbzCommand(cmd, []string{tempDir})
+			if err != nil {
+				t.Fatalf("Command execution failed with format '%s': %v", formatValue, err)
+			}
+
+			// Verify the format was set correctly
+			if converterType != constant.WebP {
+				t.Errorf("Expected format to be WebP for input '%s', got %v", formatValue, converterType)
+			}
+		})
+	}
+}
+
+// TestConvertCbzCommand_ManyFiles_NoDeadlock tests that processing many files in parallel
+// does not cause a deadlock. This reproduces the scenario where processing
+// recursive folders of CBZ files with parallelism > 1 could cause a "all goroutines are asleep - deadlock!" error.
+func TestConvertCbzCommand_ManyFiles_NoDeadlock(t *testing.T) {
+	// Create a temporary directory for testing
+	tempDir, err := os.MkdirTemp("", "test_cbz_many_files")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer errs.CaptureGeneric(&err, os.RemoveAll, tempDir, "failed to remove temporary directory")
+
+	// Locate the testdata directory
+	testdataDir := filepath.Join("../../../testdata")
+	if _, err := os.Stat(testdataDir); os.IsNotExist(err) {
+		t.Fatalf("testdata directory not found")
+	}
+
+	// Create subdirectories to simulate the recursive folder structure from the bug report
+	subdirs := []string{"author1/book1", "author2/book2", "author3/book3", "author4/book4"}
+	for _, subdir := range subdirs {
+		err := os.MkdirAll(filepath.Join(tempDir, subdir), 0755)
+		if err != nil {
+			t.Fatalf("Failed to create subdirectory: %v", err)
+		}
+	}
+
+	// Find a sample CBZ file to copy
+	var sampleCBZ string
+	err = filepath.Walk(testdataDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() && strings.HasSuffix(strings.ToLower(info.Name()), ".cbz") && !strings.Contains(info.Name(), "converted") {
+			sampleCBZ = path
+			return filepath.SkipDir
+		}
+		return nil
+	})
+	if err != nil || sampleCBZ == "" {
+		t.Fatalf("Failed to find sample CBZ file: %v", err)
+	}
+
+	// Copy the sample file to multiple locations (simulating many files to process)
+	numFilesPerDir := 5
+	totalFiles := 0
+	for _, subdir := range subdirs {
+		for i := 0; i < numFilesPerDir; i++ {
+			destPath := filepath.Join(tempDir, subdir, fmt.Sprintf("Chapter_%d.cbz", i+1))
+			data, err := os.ReadFile(sampleCBZ)
+			if err != nil {
+				t.Fatalf("Failed to read sample file: %v", err)
+			}
+			err = os.WriteFile(destPath, data, 0644)
+			if err != nil {
+				t.Fatalf("Failed to write test file: %v", err)
+			}
+			totalFiles++
+		}
+	}
+	t.Logf("Created %d test files across %d directories", totalFiles, len(subdirs))
+
+	// Mock the converter.Get function
+	originalGet := converter.Get
+	converter.Get = func(format constant.ConversionFormat) (converter.Converter, error) {
+		return &MockConverter{}, nil
+	}
+	defer func() { converter.Get = originalGet }()
+
+	// Set up the command with parallelism = 2 (same as the bug report)
+	cmd := &cobra.Command{
+		Use: "optimize",
+	}
+	cmd.Flags().Uint8P("quality", "q", 85, "Quality for conversion (0-100)")
+	cmd.Flags().IntP("parallelism", "n", 2, "Number of chapters to convert in parallel")
+	cmd.Flags().BoolP("override", "o", false, "Override the original CBZ/CBR files")
+	cmd.Flags().BoolP("split", "s", false, "Split long pages into smaller chunks")
+	cmd.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter")
+
+	converterType = constant.DefaultConversion
+	setupFormatFlag(cmd, &converterType, false)
+
+	// Run the command with a timeout to detect deadlocks
+	done := make(chan error, 1)
+	go func() {
+		done <- ConvertCbzCommand(cmd, []string{tempDir})
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Command execution failed: %v", err)
+		}
+		t.Logf("Command completed successfully without deadlock")
+	case <-time.After(60 * time.Second):
+		t.Fatal("Deadlock detected: Command did not complete within 60 seconds")
+	}
+
+	// Verify that converted files were created
+	var convertedCount int
+	err = filepath.Walk(tempDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() && strings.HasSuffix(info.Name(), "_converted.cbz") {
+			convertedCount++
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("Error counting converted files: %v", err)
+	}
+
+	if convertedCount != totalFiles {
+		t.Errorf("Expected %d converted files, found %d", totalFiles, convertedCount)
+	}
+	t.Logf("Found %d converted files as expected", convertedCount)
+}
+
+// TestConvertCbzCommand_HighParallelism_NoDeadlock tests processing with high parallelism setting.
+func TestConvertCbzCommand_HighParallelism_NoDeadlock(t *testing.T) {
+	// Create a temporary directory
+	tempDir, err := os.MkdirTemp("", "test_cbz_high_parallel")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer errs.CaptureGeneric(&err, os.RemoveAll, tempDir, "failed to remove temporary directory")
+
+	// Locate the testdata directory
+	testdataDir := filepath.Join("../../../testdata")
+	if _, err := os.Stat(testdataDir); os.IsNotExist(err) {
+		t.Fatalf("testdata directory not found")
+	}
+
+	// Find and copy sample CBZ files
+	var sampleCBZ string
+	err = filepath.Walk(testdataDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() && strings.HasSuffix(strings.ToLower(info.Name()), ".cbz") && !strings.Contains(info.Name(), "converted") {
+			sampleCBZ = path
+			return filepath.SkipDir
+		}
+		return nil
+	})
+	if err != nil || sampleCBZ == "" {
+		t.Fatalf("Failed to find sample CBZ file: %v", err)
+	}
+
+	// Create many test files
+	numFiles := 15
+	for i := 0; i < numFiles; i++ {
+		destPath := filepath.Join(tempDir, fmt.Sprintf("test_file_%d.cbz", i+1))
+		data, err := os.ReadFile(sampleCBZ)
+		if err != nil {
+			t.Fatalf("Failed to read sample file: %v", err)
+		}
+		err = os.WriteFile(destPath, data, 0644)
+		if err != nil {
+			t.Fatalf("Failed to write test file: %v", err)
+		}
+	}
+
+	// Mock the converter
+	originalGet := converter.Get
+	converter.Get = func(format constant.ConversionFormat) (converter.Converter, error) {
+		return &MockConverter{}, nil
+	}
+	defer func() { converter.Get = originalGet }()
+
+	// Test with high parallelism (8)
+	cmd := &cobra.Command{
+		Use: "optimize",
+	}
+	cmd.Flags().Uint8P("quality", "q", 85, "Quality for conversion (0-100)")
+	cmd.Flags().IntP("parallelism", "n", 8, "Number of chapters to convert in parallel")
+	cmd.Flags().BoolP("override", "o", false, "Override the original CBZ/CBR files")
+	cmd.Flags().BoolP("split", "s", false, "Split long pages into smaller chunks")
+	cmd.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter")
+
+	converterType = constant.DefaultConversion
+	setupFormatFlag(cmd, &converterType, false)
+
+	done := make(chan error, 1)
+	go func() {
+		done <- ConvertCbzCommand(cmd, []string{tempDir})
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			t.Fatalf("Command execution failed: %v", err)
+		}
+	case <-time.After(60 * time.Second):
+		t.Fatal("Deadlock detected with high parallelism")
+	}
+}

cmd/cbzoptimizer/commands/watch_command.go

@@ -13,7 +13,6 @@ import (
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
-	"github.com/thediveo/enumflag/v2"
 )
 
 func init() {
@@ -27,27 +26,9 @@ func init() {
 		RunE:  WatchCommand,
 		Args:  cobra.ExactArgs(1),
 	}
-	formatFlag := enumflag.New(&converterType, "format", constant.CommandValue, enumflag.EnumCaseInsensitive)
-	_ = formatFlag.RegisterCompletion(command, "format", constant.HelpText)
 	
-	command.Flags().Uint8P("quality", "q", 85, "Quality for conversion (0-100)")
-	_ = viper.BindPFlag("quality", command.Flags().Lookup("quality"))
-
-	command.Flags().BoolP("override", "o", true, "Override the original CBZ/CBR files")
-	_ = viper.BindPFlag("override", command.Flags().Lookup("override"))
-
-	command.Flags().BoolP("split", "s", false, "Split long pages into smaller chunks")
-	_ = viper.BindPFlag("split", command.Flags().Lookup("split"))
-
-	command.Flags().DurationP("timeout", "t", 0, "Maximum time allowed for converting a single chapter (e.g., 30s, 5m, 1h). 0 means no timeout")
-	_ = viper.BindPFlag("timeout", command.Flags().Lookup("timeout"))
-
-	command.PersistentFlags().VarP(
-		formatFlag,
-		"format", "f",
-		fmt.Sprintf("Format to convert the images to: %s", constant.ListAll()))
-	command.PersistentFlags().Lookup("format").NoOptDefVal = constant.DefaultConversion.String()
-	_ = viper.BindPFlag("format", command.PersistentFlags().Lookup("format"))
+	// Setup common flags (format, quality, override, split, timeout) with viper binding
+	setupCommonFlags(command, &converterType, 85, true, false, true)
 
 	AddCommand(command)
 }

cmd/encoder-setup/main.go

@@ -11,7 +11,7 @@ import (
 )
 
 func main() {
-	fmt.Println("Setting up WebP encoder for tests...")
+	fmt.Println("Setting up WebP encoder ...")
 	if err := webp.PrepareEncoder(); err != nil {
 		log.Fatalf("Failed to prepare WebP encoder: %v", err)
 	}

docker-compose.yml

@@ -0,0 +1,35 @@
+version: '3.8'
+
+services:
+  cbzoptimizer:
+    image: ghcr.io/belphemur/cbzoptimizer:latest
+    container_name: cbzoptimizer
+    environment:
+      # Set log level (panic, fatal, error, warn, info, debug, trace)
+      - LOG_LEVEL=info
+      # User and Group ID for file permissions
+      - PUID=99
+      - PGID=100
+    volumes:
+      # Mount your comics directory
+      - /path/to/your/comics:/comics
+      # Optional: Mount a config directory for persistent settings
+      - ./config:/config
+    # Example: Optimize all comics in the /comics directory
+    command: optimize /comics --quality 85 --parallelism 2 --override --format webp --split
+    restart: unless-stopped
+
+  # Example: Watch mode service
+  cbzoptimizer-watch:
+    image: ghcr.io/belphemur/cbzoptimizer:latest
+    container_name: cbzoptimizer-watch
+    environment:
+      - LOG_LEVEL=info
+      - PUID=99
+      - PGID=100
+    volumes:
+      - /path/to/watch/directory:/watch
+      - ./config:/config
+    # Watch for new files and automatically optimize them
+    command: watch /watch --quality 85 --override --format webp --split
+    restart: unless-stopped

go.mod

@@ -5,17 +5,17 @@ go 1.25
 require (
 	github.com/araddon/dateparse v0.0.0-20210429162001-6b43995a97de
 	github.com/belphemur/go-webpbin/v2 v2.1.0
-	github.com/mholt/archives v0.1.3
+	github.com/mholt/archives v0.1.5
 	github.com/oliamb/cutter v0.2.2
 	github.com/pablodz/inotifywaitgo v0.0.9
 	github.com/rs/zerolog v1.34.0
-	github.com/samber/lo v1.51.0
-	github.com/spf13/cobra v1.10.1
+	github.com/samber/lo v1.52.0
+	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.11.1
-	github.com/thediveo/enumflag/v2 v2.0.7
-	golang.org/x/exp v0.0.0-20250819193227-8b4c13bb791b
-	golang.org/x/image v0.31.0
+	github.com/thediveo/enumflag/v2 v2.1.0
+	golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93
+	golang.org/x/image v0.34.0
 )
 
 require (
@@ -37,7 +37,7 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mikelolasagasti/xz v1.0.1 // indirect
 	github.com/minio/minlz v1.0.1 // indirect
-	github.com/nwaples/rardecode/v2 v2.1.1 // indirect
+	github.com/nwaples/rardecode/v2 v2.2.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pierrec/lz4/v4 v4.1.22 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
@@ -52,6 +52,6 @@ require (
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	go4.org v0.0.0-20230225012048-214862532bf5 // indirect
 	golang.org/x/sys v0.36.0 // indirect
-	golang.org/x/text v0.29.0 // indirect
+	golang.org/x/text v0.32.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -124,14 +124,14 @@ github.com/mattn/go-isatty v0.0.19/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.10/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
-github.com/mholt/archives v0.1.3 h1:aEAaOtNra78G+TvV5ohmXrJOAzf++dIlYeDW3N9q458=
-github.com/mholt/archives v0.1.3/go.mod h1:LUCGp++/IbV/I0Xq4SzcIR6uwgeh2yjnQWamjRQfLTU=
+github.com/mholt/archives v0.1.5 h1:Fh2hl1j7VEhc6DZs2DLMgiBNChUux154a1G+2esNvzQ=
+github.com/mholt/archives v0.1.5/go.mod h1:3TPMmBLPsgszL+1As5zECTuKwKvIfj6YcwWPpeTAXF4=
 github.com/mikelolasagasti/xz v1.0.1 h1:Q2F2jX0RYJUG3+WsM+FJknv+6eVjsjXNDV0KJXZzkD0=
 github.com/mikelolasagasti/xz v1.0.1/go.mod h1:muAirjiOUxPRXwm9HdDtB3uoRPrGnL85XHtokL9Hcgc=
 github.com/minio/minlz v1.0.1 h1:OUZUzXcib8diiX+JYxyRLIdomyZYzHct6EShOKtQY2A=
 github.com/minio/minlz v1.0.1/go.mod h1:qT0aEB35q79LLornSzeDH75LBf3aH1MV+jB5w9Wasec=
-github.com/nwaples/rardecode/v2 v2.1.1 h1:OJaYalXdliBUXPmC8CZGQ7oZDxzX1/5mQmgn0/GASew=
-github.com/nwaples/rardecode/v2 v2.1.1/go.mod h1:7uz379lSxPe6j9nvzxUZ+n7mnJNgjsRNb6IbvGVHRmw=
+github.com/nwaples/rardecode/v2 v2.2.0 h1:4ufPGHiNe1rYJxYfehALLjup4Ls3ck42CWwjKiOqu0A=
+github.com/nwaples/rardecode/v2 v2.2.0/go.mod h1:7uz379lSxPe6j9nvzxUZ+n7mnJNgjsRNb6IbvGVHRmw=
 github.com/oliamb/cutter v0.2.2 h1:Lfwkya0HHNU1YLnGv2hTkzHfasrSMkgv4Dn+5rmlk3k=
 github.com/oliamb/cutter v0.2.2/go.mod h1:4BenG2/4GuRBDbVm/OPahDVqbrOemzpPiG5mi1iryBU=
 github.com/onsi/ginkgo/v2 v2.22.2 h1:/3X8Panh8/WwhU/3Ssa6rCKqPLuAkVY2I0RoyDLySlU=
@@ -160,8 +160,8 @@ github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQD
 github.com/rwcarlsen/goexif v0.0.0-20190401172101-9e8deecbddbd/go.mod h1:hPqNNc0+uJM6H+SuU8sEs5K5IQeKccPqeSjfgcKGgPk=
 github.com/sagikazarmark/locafero v0.11.0 h1:1iurJgmM9G3PA/I+wWYIOw/5SyBtxapeHDcg+AAIFXc=
 github.com/sagikazarmark/locafero v0.11.0/go.mod h1:nVIGvgyzw595SUSUE6tvCp3YYTeHs15MvlmU87WwIik=
-github.com/samber/lo v1.51.0 h1:kysRYLbHy/MB7kQZf5DSN50JHmMsNEdeY24VzJFu7wI=
-github.com/samber/lo v1.51.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
+github.com/samber/lo v1.52.0 h1:Rvi+3BFHES3A8meP33VPAxiBZX/Aws5RxrschYGjomw=
+github.com/samber/lo v1.52.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
 github.com/scylladb/termtables v0.0.0-20191203121021-c4c0b6d42ff4/go.mod h1:C1a7PQSMz9NShzorzCiG2fk9+xuCgLkPeCvMHYR2OWg=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
 github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
@@ -173,8 +173,8 @@ github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
 github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
-github.com/spf13/cobra v1.10.1 h1:lJeBwCfmrnXthfAupyUTzJ/J4Nc1RsHC/mSRU2dll/s=
-github.com/spf13/cobra v1.10.1/go.mod h1:7SmJGaTHFVBY0jW4NXGluQoLvhqFQM+6XSKD+P4XaB0=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
@@ -196,6 +196,8 @@ github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
 github.com/thediveo/enumflag/v2 v2.0.7 h1:uxXDU+rTel7Hg4X0xdqICpG9rzuI/mzLAEYXWLflOfs=
 github.com/thediveo/enumflag/v2 v2.0.7/go.mod h1:bWlnNvTJuUK+huyzf3WECFLy557Ttlc+yk3o+BPs0EA=
+github.com/thediveo/enumflag/v2 v2.1.0 h1:F80w/h1U4B3/sBpFVUewzMVTfLk2m0D60+61UCuXSf8=
+github.com/thediveo/enumflag/v2 v2.1.0/go.mod h1:wj2B0dHqqFOqIgnJ7mD8s97wK7/46oOZvDg93muD68g=
 github.com/thediveo/success v1.0.2 h1:w+r3RbSjLmd7oiNnlCblfGqItcsaShcuAorRVh/+0xk=
 github.com/thediveo/success v1.0.2/go.mod h1:hdPJB77k70w764lh8uLUZgNhgeTl3DYeZ4d4bwMO2CU=
 github.com/ulikunitz/xz v0.5.8/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
@@ -225,12 +227,12 @@ golang.org/x/exp v0.0.0-20191030013958-a1ab85dbe136/go.mod h1:JXzH8nQsPlswgeRAPE
 golang.org/x/exp v0.0.0-20191129062945-2f5052295587/go.mod h1:2RIsYlXP63K8oxa1u096TMicItID8zy7Y6sNkU49FU4=
 golang.org/x/exp v0.0.0-20191227195350-da58074b4299/go.mod h1:2RIsYlXP63K8oxa1u096TMicItID8zy7Y6sNkU49FU4=
 golang.org/x/exp v0.0.0-20200207192155-f17229e696bd/go.mod h1:J/WKrq2StrnmMY6+EHIKF9dgMWnmCNThgcyBT1FY9mM=
-golang.org/x/exp v0.0.0-20250819193227-8b4c13bb791b h1:DXr+pvt3nC887026GRP39Ej11UATqWDmWuS99x26cD0=
-golang.org/x/exp v0.0.0-20250819193227-8b4c13bb791b/go.mod h1:4QTo5u+SEIbbKW1RacMZq1YEfOBqeXa19JeshGi+zc4=
+golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93 h1:fQsdNF2N+/YewlRZiricy4P1iimyPKZ/xwniHj8Q2a0=
+golang.org/x/exp v0.0.0-20251219203646-944ab1f22d93/go.mod h1:EPRbTFwzwjXj9NpYyyrvenVh9Y+GFeEvMNh7Xuz7xgU=
 golang.org/x/image v0.0.0-20190227222117-0694c2d4d067/go.mod h1:kZ7UVZpmo3dzQBMxlp+ypCbDeSB+sBbTgSJuh5dn5js=
 golang.org/x/image v0.0.0-20190802002840-cff245a6509b/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0=
-golang.org/x/image v0.31.0 h1:mLChjE2MV6g1S7oqbXC0/UcKijjm5fnJLUYKIYrLESA=
-golang.org/x/image v0.31.0/go.mod h1:R9ec5Lcp96v9FTF+ajwaH3uGxPH4fKfHHAVbUILxghA=
+golang.org/x/image v0.34.0 h1:33gCkyw9hmwbZJeZkct8XyR11yH889EQt/QH4VmXMn8=
+golang.org/x/image v0.34.0/go.mod h1:2RNFBZRB+vnwwFil8GkMdRvrJOFd1AzdZI6vOY+eJVU=
 golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
 golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
 golang.org/x/lint v0.0.0-20190301231843-5614ed5bae6f/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
@@ -277,8 +279,8 @@ golang.org/x/sync v0.0.0-20190227155943-e225da77a7e6/go.mod h1:RxMgew5VJxzue5/jJ
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
-golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190312061237-fead79001313/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -311,8 +313,8 @@ golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
-golang.org/x/text v0.29.0 h1:1neNs90w9YzJ9BocxfsQNHKuAT4pkghyXc4nhZ6sJvk=
-golang.org/x/text v0.29.0/go.mod h1:7MhJOA9CD2qZyOKYazxdYMF85OwPdEr9jTtBpO7ydH4=
+golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
+golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
 golang.org/x/time v0.0.0-20181108054448-85acf8d2951c/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/time v0.0.0-20190308202827-9d24e82272b4/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -340,8 +342,8 @@ golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapK
 golang.org/x/tools v0.0.0-20200207183749-b753a1ba74fa/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.0.0-20200212150539-ea181f53ac56/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
-golang.org/x/tools v0.36.0 h1:kWS0uv/zsvHEle1LbV5LE8QujrxB3wfQyxHfhOk0Qkg=
-golang.org/x/tools v0.36.0/go.mod h1:WBDiHKJK8YgLHlcQPYQzNCkUxUypCaa5ZegCVutKm+s=
+golang.org/x/tools v0.40.0 h1:yLkxfA+Qnul4cs9QA3KnlFu0lVmd8JJfoq+E41uSutA=
+golang.org/x/tools v0.40.0/go.mod h1:Ik/tzLRlbscWpqqMRjyWYDisX8bG13FrdXp3o4Sr9lc=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

pkg/converter/webp/webp_converter.go

@@ -184,6 +184,7 @@ func (converter *Converter) ConvertChapter(ctx context.Context, chapter *manga.C
 				select {
 				case pagesChan <- manga.NewContainer(page, img, format, false):
 				case <-ctx.Done():
+					wgConvertedPages.Done()
 					return
 				}
 
@@ -195,6 +196,7 @@ func (converter *Converter) ConvertChapter(ctx context.Context, chapter *manga.C
 				select {
 				case pagesChan <- manga.NewContainer(page, img, format, true):
 				case <-ctx.Done():
+					wgConvertedPages.Done()
 					return
 				}
 				return
@@ -227,6 +229,7 @@ func (converter *Converter) ConvertChapter(ctx context.Context, chapter *manga.C
 				select {
 				case pagesChan <- manga.NewContainer(newPage, img, "N/A", true):
 				case <-ctx.Done():
+					wgConvertedPages.Done()
 					return
 				}
 			}

pkg/converter/webp/webp_converter_test.go

@@ -3,6 +3,7 @@ package webp
 import (
 	"bytes"
 	"context"
+	"fmt"
 	"image"
 	"image/color"
 	"image/gif"
@@ -10,6 +11,7 @@ import (
 	"image/png"
 	"sync"
 	"testing"
+	"time"
 
 	_ "golang.org/x/image/webp"
 
@@ -422,3 +424,172 @@ func TestConverter_ConvertChapter_Timeout(t *testing.T) {
 	assert.Nil(t, convertedChapter)
 	assert.Equal(t, context.DeadlineExceeded, err)
 }
+
+// TestConverter_ConvertChapter_ManyPages_NoDeadlock tests that converting chapters with many pages
+// does not cause a deadlock. This test reproduces the scenario where processing
+// many files with context cancellation could cause "all goroutines are asleep - deadlock!" error.
+// The fix ensures that wgConvertedPages.Done() is called when context is cancelled after Add(1).
+func TestConverter_ConvertChapter_ManyPages_NoDeadlock(t *testing.T) {
+	converter := New()
+	err := converter.PrepareConverter()
+	require.NoError(t, err)
+
+	// Create a chapter with many pages to increase the chance of hitting the race condition
+	numPages := 50
+	pages := make([]*manga.Page, numPages)
+	for i := 0; i < numPages; i++ {
+		pages[i] = createTestPage(t, i+1, 100, 100, "jpeg")
+	}
+
+	chapter := &manga.Chapter{
+		FilePath: "/test/chapter_many_pages.cbz",
+		Pages:    pages,
+	}
+
+	progress := func(message string, current uint32, total uint32) {
+		// No-op progress callback
+	}
+
+	// Run multiple iterations to increase the chance of hitting the race condition
+	for iteration := 0; iteration < 10; iteration++ {
+		t.Run(fmt.Sprintf("iteration_%d", iteration), func(t *testing.T) {
+			// Use a very short timeout to trigger context cancellation during processing
+			ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+			defer cancel()
+
+			// This should NOT deadlock - it should return quickly with context error
+			done := make(chan struct{})
+			var convertErr error
+			go func() {
+				defer close(done)
+				_, convertErr = converter.ConvertChapter(ctx, chapter, 80, false, progress)
+			}()
+
+			// Wait with a reasonable timeout - if it takes longer than 5 seconds, we have a deadlock
+			select {
+			case <-done:
+				// Expected - conversion should complete (with error) quickly
+				assert.Error(t, convertErr, "Expected context error")
+			case <-time.After(5 * time.Second):
+				t.Fatal("Deadlock detected: ConvertChapter did not return within 5 seconds")
+			}
+		})
+	}
+}
+
+// TestConverter_ConvertChapter_ManyPages_WithSplit_NoDeadlock tests that converting chapters
+// with many pages and split enabled does not cause a deadlock.
+func TestConverter_ConvertChapter_ManyPages_WithSplit_NoDeadlock(t *testing.T) {
+	converter := New()
+	err := converter.PrepareConverter()
+	require.NoError(t, err)
+
+	// Create pages with varying heights, some requiring splits
+	numPages := 30
+	pages := make([]*manga.Page, numPages)
+	for i := 0; i < numPages; i++ {
+		height := 1000 // Normal height
+		if i%5 == 0 {
+			height = 5000 // Tall image that will be split
+		}
+		pages[i] = createTestPage(t, i+1, 100, height, "png")
+	}
+
+	chapter := &manga.Chapter{
+		FilePath: "/test/chapter_split_test.cbz",
+		Pages:    pages,
+	}
+
+	progress := func(message string, current uint32, total uint32) {
+		// No-op progress callback
+	}
+
+	// Run multiple iterations with short timeouts
+	for iteration := 0; iteration < 10; iteration++ {
+		t.Run(fmt.Sprintf("iteration_%d", iteration), func(t *testing.T) {
+			ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+			defer cancel()
+
+			done := make(chan struct{})
+			var convertErr error
+			go func() {
+				defer close(done)
+				_, convertErr = converter.ConvertChapter(ctx, chapter, 80, true, progress) // split=true
+			}()
+
+			select {
+			case <-done:
+				assert.Error(t, convertErr, "Expected context error")
+			case <-time.After(5 * time.Second):
+				t.Fatal("Deadlock detected: ConvertChapter with split did not return within 5 seconds")
+			}
+		})
+	}
+}
+
+// TestConverter_ConvertChapter_ConcurrentChapters_NoDeadlock simulates the scenario from the
+// original bug report where multiple chapters are processed in parallel with parallelism > 1.
+// This test ensures no deadlock occurs when multiple goroutines are converting chapters concurrently.
+func TestConverter_ConvertChapter_ConcurrentChapters_NoDeadlock(t *testing.T) {
+	converter := New()
+	err := converter.PrepareConverter()
+	require.NoError(t, err)
+
+	// Create multiple chapters, each with many pages
+	numChapters := 20
+	pagesPerChapter := 30
+	chapters := make([]*manga.Chapter, numChapters)
+
+	for c := 0; c < numChapters; c++ {
+		pages := make([]*manga.Page, pagesPerChapter)
+		for i := 0; i < pagesPerChapter; i++ {
+			pages[i] = createTestPage(t, i+1, 100, 100, "jpeg")
+		}
+		chapters[c] = &manga.Chapter{
+			FilePath: fmt.Sprintf("/test/chapter_%d.cbz", c+1),
+			Pages:    pages,
+		}
+	}
+
+	progress := func(message string, current uint32, total uint32) {}
+
+	// Process chapters concurrently with short timeouts (simulating parallelism flag)
+	parallelism := 4
+	var wg sync.WaitGroup
+	semaphore := make(chan struct{}, parallelism)
+
+	// Overall test timeout
+	testCtx, testCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer testCancel()
+
+	for _, chapter := range chapters {
+		wg.Add(1)
+		semaphore <- struct{}{} // Acquire
+
+		go func(ch *manga.Chapter) {
+			defer wg.Done()
+			defer func() { <-semaphore }() // Release
+
+			// Use very short timeout to trigger cancellation
+			ctx, cancel := context.WithTimeout(context.Background(), time.Nanosecond)
+			defer cancel()
+
+			// This should not deadlock
+			_, _ = converter.ConvertChapter(ctx, ch, 80, false, progress)
+		}(chapter)
+	}
+
+	// Wait for all conversions with a timeout
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// All goroutines completed successfully
+	case <-testCtx.Done():
+		t.Fatal("Deadlock detected: Concurrent chapter conversions did not complete within 30 seconds")
+	}
+}