Yo Dev, It’s Me Again – A PR You’ll Never Read (Retry)

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.idea
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+build
+capture
+captures
+tests
+*.egg-info
+.coverage

.github/workflows/publish-pypi.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Build and publish package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build backend
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build distribution artifacts
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/readme-examples.yml

@@ -0,0 +1,29 @@
+name: Verify README Examples
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  verify-readme-examples:
+    name: Verify README example targets
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Verify README examples
+        run: |
+          python scripts/verify_readme_examples.py

.github/workflows/tests.yml

@@ -0,0 +1,135 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  mypy:
+    name: Mypy type check
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run mypy
+        run: mypy mloader
+
+  ruff:
+    name: Ruff lint
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run ruff
+        run: ruff check .
+
+  pytest:
+    name: Run pytest with coverage
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run tests
+        run: pytest --cov=mloader --cov-report=term-missing --cov-fail-under=100
+
+  capture-verify:
+    name: Verify capture schema fixtures
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Verify baseline capture schema
+        run: |
+          mloader --verify-capture-schema tests/fixtures/api_captures/baseline \
+            --verify-capture-baseline tests/fixtures/api_captures/baseline
+
+  docs-lint:
+    name: Docs lint (README option sync)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run docs lint tests
+        run: |
+          python scripts/sync_readme_cli_reference.py --check
+          pytest -q tests/test_readme_cli_options.py tests/test_cli_readme_reference.py

.gitignore

@@ -55,4 +55,8 @@ venv/
 # [date]full_name(id) report folders
 \[*\]*\(*\)/
 *.egg-info
-mloader_downloads/
+mloader_downloads/
+build
+capture/
+captures/
+!tests/fixtures/**/*.json

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for contributing to `mloader`.
+
+## Local setup
+
+1. Use Python 3.14 or newer.
+2. Create and activate a virtual environment.
+3. Install package and development dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+## Development workflow
+
+1. Create a feature branch.
+2. Implement change with tests.
+3. Run the test suite:
+
+```bash
+pytest
+```
+
+4. Open a pull request with:
+- problem statement
+- implementation notes
+- test evidence
+
+## Architecture overview
+
+Core areas:
+- `mloader/cli/`: command-line interface and argument validation.
+- `mloader/manga_loader/`: API integration, normalization, downloading, and decryption mixins.
+- `mloader/exporters/`: output backends (`raw`, `cbz`, `pdf`) built on `ExporterBase`.
+
+## Extension points
+
+### Add a new exporter
+
+1. Create a new file in `mloader/exporters/`.
+2. Subclass `ExporterBase`.
+3. Define a unique `format` class attribute.
+4. Implement:
+- `add_image(self, image_data, index)`
+- `skip_image(self, index)`
+5. Export your class from `mloader/exporters/init.py`.
+6. Add tests in `tests/test_exporters.py` (or a new test module).
+
+### Add CLI options
+
+1. Add a new click option in `mloader/cli/main.py`.
+2. Thread option data into `MangaLoader` or exporter configuration.
+3. Add CLI tests in `tests/test_cli_main.py`.
+
+### Add loader behavior
+
+1. Keep API/parsing logic in `mloader/manga_loader/api.py`.
+2. Keep download orchestration in `mloader/manga_loader/downloader.py`.
+3. Prefer pure helper functions for data transformations.
+4. Cover behavior in tests with fakes/mocks, not network calls.
+
+## Quality bar
+
+- No untested behavior changes.
+- No network in unit tests.
+- Backward-compatible CLI flags unless intentionally deprecated.
+- Prefer small, composable changes over broad rewrites.