Initial commit

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Author: jschloman

.env.example

@@ -0,0 +1,17 @@
+# API Keys
+DISCOGS_TOKEN=your_discogs_user_token
+ANTHROPIC_API_KEY=your_key        # if using Claude
+GOOGLE_API_KEY=your_key           # if using Gemini
+
+# Paths
+LIBRARY_ROOT=/path/to/music
+WORKING_DIR=./tagger_workdir
+
+# Tuning
+TAGGER_WORKERS=4
+DISCOGS_FUZZY_THRESHOLD=85        # 0–100; minimum match confidence
+ID3_VERSION=2.3                   # 2.3 or 2.4
+LLM_PROVIDER=claude               # claude | gemini
+
+# Behavior flags
+RETRY_NOT_FOUND=false

.githooks/pre-push

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# pre-push hook — mirrors the CI quality gate.
+# Runs automatically before every `git push`.
+#
+# One-time setup (per clone):
+#   git config core.hooksPath .githooks
+#
+# To skip in an emergency:
+#   git push --no-verify
+
+set -euo pipefail
+
+echo "==> pre-push: running CI checks …"
+
+# Resolve a working Python interpreter.
+# Priority: active venv > py launcher (Windows) > python > python3.
+find_python() {
+    if [[ -n "${VIRTUAL_ENV:-}" ]]; then
+        # Use the venv Python directly
+        if [[ -x "$VIRTUAL_ENV/Scripts/python.exe" ]]; then
+            echo "$VIRTUAL_ENV/Scripts/python.exe"; return
+        fi
+        if [[ -x "$VIRTUAL_ENV/bin/python" ]]; then
+            echo "$VIRTUAL_ENV/bin/python"; return
+        fi
+    fi
+    for candidate in "py -3" python python3; do
+        # shellcheck disable=SC2086
+        if $candidate -c "import sys" 2>/dev/null; then
+            echo $candidate; return
+        fi
+    done
+    echo "ERROR: no working Python interpreter found." >&2
+    exit 1
+}
+
+PYTHON=$(find_python)
+
+run() {
+    echo ""
+    echo "--- $*"
+    # Split PYTHON in case it is "py -3" (two words)
+    # shellcheck disable=SC2086
+    $PYTHON -m "$@"
+}
+
+run ruff check .
+run ruff format --check .
+run mypy tagger/
+run pytest tests/unit tests/integration -m "not slow" -q
+
+echo ""
+echo "==> pre-push: all checks passed."

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [main, feat/*, fix/*, chore/*, refactor/*]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-pr-title:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR title follows conventional commits
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          echo "PR title: $PR_TITLE"
+          if ! echo "$PR_TITLE" | grep -qP '^(feat|fix|perf|refactor|docs|style|test|chore|ci|build)(\(.+\))?(!)?: .+'; then
+            echo "ERROR: PR title must follow Conventional Commits format."
+            echo "Examples: 'feat: add plugin registry', 'fix(writer): handle permission error', 'feat!: breaking api change'"
+            echo "See https://www.conventionalcommits.org"
+            exit 1
+          fi
+
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run ruff check
+        run: ruff check .
+
+      - name: Run ruff format check
+        run: ruff format --check .
+
+      - name: Run mypy
+        run: mypy tagger/
+
+      - name: Run tests with coverage
+        run: pytest tests/unit tests/integration -m "not slow"
+        env:
+          CI: "1"

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  pull_request:
+    branches: [main]
+    types: [closed]
+
+jobs:
+  release:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    concurrency: release
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: main
+
+      - name: Generate timestamp tag
+        id: version
+        run: |
+          BASE="v$(date -u +%Y.%m.%d)"
+          TAG="$BASE"
+          N=1
+          while git ls-remote --tags origin "$TAG" | grep -q "$TAG"; do
+            TAG="${BASE}.${N}"
+            N=$((N + 1))
+          done
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+
+      - name: Create tag and GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ steps.version.outputs.tag }}"
+          git tag "$TAG"
+          git push origin "$TAG"
+          gh release create "$TAG" --title "$TAG" --generate-notes

.gitignore

@@ -0,0 +1,66 @@
+.venv/
+venv/
+.env
+
+*.csv
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Pytest / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nosetests/
+nosetests.xml
+coverage.xml
+*.cover
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.hypothesis/
+
+# Vim
+*~
+*.un~
+.netrwhist
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project — intermediate output files and internal-only scripts
+tagger_workdir/
+scripts/
+*.db
+*.json
+*.txt
+*.ps1
+config.yaml
+recent_folders.py
+
+# Claude Code
+.claude/

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        args: [tagger/]
+        additional_dependencies:
+          - pydantic>=2.7
+          - pydantic-settings>=2.2
+          - types-beautifulsoup4

CHANGELOG.md

@@ -0,0 +1,55 @@
+# 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-24
+
+### Added
+
+- Parallel enrichment pipeline: scans MP3 folders, fetches Discogs / Wikipedia / MusicBrainz
+  metadata, and writes enriched ID3 tags via `mutagen`. Controlled by `--workers`.
+- Five-strategy track-matching algorithm that handles multi-disc albums, non-numeric Discogs
+  positions (vinyl A/B sides, roman numerals), and fuzzy ID3 title matching.
+- ID3 tag writing with full metadata: title, artist, album artist, year, genre, grouping
+  (pipe-delimited `Origin:City | Gender:... | Subgenre:... | Label:... | link:...`),
+  disc number, and embedded album art.
+- Manual-review CSV workflow: albums that cannot be matched automatically are exported to a
+  CSV; after a human supplies Discogs URLs the `process-manual` command applies them.
+- `scan-integrity` command: walks the library and reports ID3 tag / folder-name mismatches
+  (album artist mismatch, inconsistent tags, all-untitled albums, etc.).
+- `retry-not-found` command: re-runs Discogs enrichment on all `not_found` albums without
+  a subprocess round-trip.
+- `prefill-master-urls` command: pre-fills the `user_discogs_url` column in a manual-review
+  CSV using two search passes, reducing reviewer lookup work.
+- `enrich-missing` command: re-scans artist directories for albums referenced in a reviewed
+  CSV that are missing from the database.
+- Claude and Gemini LLM clients for collective / affiliation detection, written as injectable
+  `Protocol` implementations so either backend can be swapped at runtime.
+- SQLite repository layer with versioned migrations and WAL-mode concurrency.
+- Structured logging via `structlog` (JSON in CI, pretty console in development).
+- Pydantic v2 models at every external data boundary (Discogs API, LLM JSON output, DB rows).
+- `tenacity`-based retry decorator with server-provided `Retry-After` awareness and
+  exponential back-off.
+- Token-bucket rate limiter used across all Discogs API calls.
+- Windows SMB share fallback: when `mutagen`'s in-place save fails with `EINVAL`, the writer
+  copies to a local temp file and moves it back to avoid cross-device shutil issues.
+- Four Claude Code skills (`/scan-integrity`, `/retry-not-found`, `/prefill-master-urls`,
+  `/enrich-missing`) matching the four operational CLI commands.
+
+### Fixed
+
+- Apostrophe / contraction handling in title-case normalisation so that "She's Gone" is not
+  upper-cased to "She'S Gone" (#79).
+- Multi-disc track-title shifting: disc-2 files now map directly to Discogs position "N-M"
+  rather than falling through to an incorrect positional index.
+- Artist-name sanity check rejects Discogs matches where folder artist and release artist have
+  < 40% token-set similarity (e.g. Cat Stevens vs. Astrud Gilberto class of false positives).
+- Discogs release artist used as track-artist fallback when per-track artist list is empty.
+
+[Unreleased]: https://github.com/jschloman/mp3-enricher/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jschloman/mp3-enricher/releases/tag/v0.1.0