coverart-cli 0.4.0__tar.gz

coverart_cli-0.4.0/.coderabbit.yaml

@@ -0,0 +1,38 @@
+# CodeRabbit configuration for coverart-cli
+# Docs: https://docs.coderabbit.ai/getting-started/configure-coderabbit
+
+language: en-US
+early_access: false
+
+reviews:
+  profile: chill           # less nitpicky; chill | assertive
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  collapse_walkthrough: true
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches: [main]
+  path_filters:
+    - "!docs/screenshots/**"      # don't review screenshots
+    - "!**/*.md"                  # docs don't need code review
+    - "!CHANGELOG.md"
+    - "!.release-please-manifest.json"
+  path_instructions:
+    - path: "src/coverart_cli/providers/**"
+      instructions: >
+        Providers must inherit CoverProvider and call _http_get with retries.
+        Reject placeholder images. Respect MIN_COVER_BYTES.
+    - path: "src/coverart_cli/templates/**"
+      instructions: >
+        HTML templates must use safe DOM construction
+        (createElement / textContent / replaceChildren),
+        never innerHTML with non-escaped JSON.
+    - path: "tests/**"
+      instructions: >
+        Tests should be deterministic — use the FakeProvider, no real network.
+
+chat:
+  auto_reply: true

coverart_cli-0.4.0/.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.py]
+indent_size = 4
+
+[*.{json,toml,yml,yaml,html,css,js}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

coverart_cli-0.4.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewer for everything.
+* @WildDragonKing

coverart_cli-0.4.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      gh-actions:
+        patterns: ["*"]
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-deps:
+        patterns: ["*"]

coverart_cli-0.4.0/.github/workflows/auto-enable-automerge.yml

@@ -0,0 +1,23 @@
+# Auto-enable squash auto-merge on every non-draft PR.
+# Branch protection still gates the merge — it only fires once all required
+# checks (test matrix, CodeQL, smoke, CodeRabbit) pass.
+name: Enable auto-merge
+
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  enable:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Enable squash auto-merge
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: gh pr merge --auto --squash "$PR_URL"

coverart_cli-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Unit + integration tests
+        run: pytest --cov=coverart_cli --cov-report=term-missing
+
+  smoke:
+    name: smoke (install wheel + run end-to-end)
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - name: Build wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+      - name: Install wheel into a fresh venv
+        run: |
+          python -m venv /tmp/smoke-venv
+          /tmp/smoke-venv/bin/pip install --upgrade pip
+          /tmp/smoke-venv/bin/pip install dist/*.whl
+      - name: Verify CLI is installed
+        run: |
+          /tmp/smoke-venv/bin/coverart --version
+          /tmp/smoke-venv/bin/coverart --help > /dev/null
+      - name: Build a fixture library
+        # Use the smoke-venv python so we can import mutagen (installed as a dep of coverart-cli).
+        run: |
+          /tmp/smoke-venv/bin/python <<'PY'
+          from pathlib import Path
+          from mutagen.id3 import ID3, TPE1, TPE2, TALB, TIT2
+          p = Path("/tmp/fixture-lib/Pink Floyd/The Wall/01.mp3")
+          p.parent.mkdir(parents=True, exist_ok=True)
+          p.write_bytes(b"\xff\xfb\x90\x00" + b"\x00" * 1000)
+          tags = ID3()
+          tags.add(TPE1(encoding=3, text=["Pink Floyd"]))
+          tags.add(TPE2(encoding=3, text=["Pink Floyd"]))
+          tags.add(TALB(encoding=3, text=["The Wall"]))
+          tags.add(TIT2(encoding=3, text=["Mother"]))
+          tags.save(str(p))
+          PY
+      - name: Run end-to-end
+        run: |
+          /tmp/smoke-venv/bin/coverart /tmp/fixture-lib -v
+          test -f "/tmp/fixture-lib/Pink Floyd/The Wall/cover.jpg" && echo "✓ cover.jpg written"
+      - name: Generate HTML report against fixture
+        run: |
+          /tmp/smoke-venv/bin/coverart /tmp/fixture-lib --report-only --report-html /tmp/report.html
+          test -s /tmp/report.html && echo "✓ report written ($(wc -c </tmp/report.html) bytes)"

coverart_cli-0.4.0/.github/workflows/codeql.yml

@@ -0,0 +1,33 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly extra scan to catch newly disclosed CVEs in dependencies.
+    - cron: "13 7 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+          queries: security-extended,security-and-quality
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+      - name: Perform analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:python"

coverart_cli-0.4.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,28 @@
+# Auto-merge Dependabot PRs once all required checks pass.
+# Branch protection requires the status checks (test matrix + CodeQL + smoke);
+# this workflow just flips the auto-merge bit, GitHub does the rest.
+name: Dependabot auto-merge
+
+on:
+  pull_request_target:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  automerge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch Dependabot metadata
+        id: meta
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Enable auto-merge (squash)
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+        run: gh pr merge --auto --squash "$PR_URL"

coverart_cli-0.4.0/.github/workflows/release-please.yml

@@ -0,0 +1,20 @@
+name: Release-please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

coverart_cli-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,61 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write  # PyPI Trusted Publishing (OIDC)
+
+jobs:
+  # Gate: must pass tests before we ever build a release artifact.
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/coverart-cli
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      # Pinned to a release tag; bump deliberately, signed by maintainer.
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

coverart_cli-0.4.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# venv
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local
+*.local
+.env
+.envrc
+
+# Project output
+missing-covers.csv
+*.log
+docs/screenshots/demo-report.html
+docs/screenshots/*.tmp

coverart_cli-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: [--maxkb=2048]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

coverart_cli-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

coverart_cli-0.4.0/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0](https://github.com/WildDragonKing/coverart-cli/compare/v0.3.0...v0.4.0) (2026-05-17)
+
+
+### Features
+
+* add release-please for merge-driven version bumps ([#9](https://github.com/WildDragonKing/coverart-cli/issues/9)) ([28ec876](https://github.com/WildDragonKing/coverart-cli/commit/28ec8768d70e22c50ebd58e6ca170fb65393eb6c))
+* auto-enable squash auto-merge + CodeRabbit config ([#11](https://github.com/WildDragonKing/coverart-cli/issues/11)) ([3756926](https://github.com/WildDragonKing/coverart-cli/commit/37569263e397e61d34d3cd865f4935c94432e3a9))
+
+
+### Bug Fixes
+
+* drop failing approve step from Dependabot auto-merge ([#12](https://github.com/WildDragonKing/coverart-cli/issues/12)) ([c2f984d](https://github.com/WildDragonKing/coverart-cli/commit/c2f984d7417ee811bc80e90ec9b3d2f587ffddb2))
+
+## [0.3.0] - 2026-05-17
+
+### Added
+
+- **TOML config file** support — `~/.config/coverart-cli/config.toml`,
+  `./coverart.toml`, or `--config PATH`. CLI flags still override the config.
+- **`py.typed`** marker file for PEP 561 — type checkers can now see our types.
+- **Public library API** explicitly defined via `__all__` in
+  `coverart_cli/__init__.py`. You can now do
+  `from coverart_cli import RunOptions, run, ITunesProvider`.
+- **`.editorconfig`** for cross-IDE consistency.
+- **`.pre-commit-config.yaml`** with ruff + ruff-format + standard checks.
+- **`SECURITY.md`** with private vulnerability reporting link.
+- **PyPI release workflow** (`.github/workflows/release.yml`) — push a
+  `v*` tag and the package is built and uploaded via PyPI Trusted Publishing.
+  Includes a **`needs: test`** gate so a red main can't ship a release.
+- **Dependabot** monthly checks for GitHub Actions and pip.
+
+### Changed
+
+- Minimum Python is now **3.11** (was 3.10) — needed for stdlib `tomllib`.
+- Metadata now uses **PEP 639 SPDX** (`license = "MIT"` + `license-files`),
+  no more deprecated `License ::` classifier.
+- Description and CLI help text now reflect the actual provider and format
+  coverage (4 providers, 5 formats).
+- All providers share a single `_default_user_agent()` derived from
+  `__version__` — no more stale `0.1.0` strings hard-coded in defaults.
+- `iTunesProvider` and `DeezerProvider` correctly accept `user_agent=`
+  (was silently ignored, broke library usage).
+- `MusicBrainzProvider` dead `release` fallback branch removed.
+- Size threshold for accepted covers unified across providers via
+  `tagging.MIN_COVER_BYTES`.
+- `scan_library` path-traversal logic simplified to `relative_to` +
+  `ValueError` guard.
+
+## [0.2.0] - 2026-05-17
+
+### Added
+
+- **iTunes provider** (Apple Music public search) — no API key required.
+- **Deezer provider** — no API key required.
+- **FLAC, Ogg Vorbis, and Opus** file format support (read + embed).
+- HTML report shows iTunes / Deezer / Embedded filter chips and badges.
+- Demo report generator (`docs/make_demo_report.py`).
+- **`--min-bytes N`**: upgrade existing covers smaller than N bytes. Default 0
+  (keep all existing). Setting e.g. `--min-bytes 50000` causes the tool to
+  re-fetch covers for any album whose current artwork is below 50 KB.
+- **`--replace-smaller`**: when the freshly fetched cover is larger than the
+  existing one, replace it. Default is to keep the larger existing cover when
+  both qualify.
+- `existing_embedded_size()` helper in `coverart_cli.tagging` for inspecting
+  in-tag artwork sizes across all five formats.
+
+### Changed
+
+- Last.fm is now optional — if no key is supplied, the tool runs with the three
+  free providers instead of failing.
+- README rewritten — significantly shorter, with screenshots and an
+  alternatives table.
+
+## [0.1.0] - 2026-05-17
+
+### Added
+
+- Initial release.
+- Tag-first album metadata reading via `mutagen`, directory-name fallback.
+- Last.fm `album.getinfo` provider with placeholder-image rejection.
+- MusicBrainz + Cover Art Archive fallback provider with rate limiting.
+- Embed into MP3 (`ID3 APIC`) and M4A (`covr` atom).
+- Sidecar `cover.jpg` / `cover.png` writing with magic-byte MIME detection.
+- CLI: `--lastfm-key`, `--no-lastfm`, `--no-musicbrainz`, `--no-embed`,
+  `--no-sidecar`, `--dry-run`, `--missing-csv`, `-v`/`-vv`.
+- **HTML coverage report**: `--report-html PATH`, `--report-only`, `--no-thumbs`.
+  Self-contained single-file output with embedded thumbnails, dark/light theme,
+  searchable + filterable album grid. Editorial/liner-notes aesthetic with
+  Fraunces, Geist, and JetBrains Mono typography.
+- Pytest smoke suite (25 tests) for tagging, provider helpers, and report module.
+- GitHub Actions CI for lint + tests on Python 3.10–3.13.

coverart_cli-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WildDragonKing
+
+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.