bindery-cli 0.38.0__tar.gz → 0.40.0__tar.gz

bindery_cli-0.40.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      # ruff is a dev-only linter; the rule set lives in pyproject.toml, so
+      # these mean the same thing locally. Checking `.` rather than named
+      # directories keeps a new top-level script from silently escaping lint.
+      - run: pip install ruff==0.16.2
+      - run: ruff check .
+      - run: ruff format --check .
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      # html5lib is the project's declared optional `reserialize` extra (core
+      # stays stdlib-only); installing it here lets CI exercise the
+      # --reserialize tests instead of skipping them.
+      - run: pip install . html5lib
+      - run: PYTHONPATH=src python -m unittest discover -s tests
+  core-compat:
+    name: Run the stack-free suite on the 3.12/3.13 floor
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The install floor (decision 63): vir-tui/cquarry are marker-gated
+        # to 3.14 there, so these legs install the core (tqdm only) and run
+        # exactly the test modules that never touch the gated stack: the
+        # repair core, the plugin under calibre stubs, validate, and the
+        # version/grammar pins. audit/library/CLI-stack tests stay on the
+        # 3.14 leg above.
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install . html5lib
+      - run: >
+          PYTHONPATH=src python -m unittest
+          tests.test_transforms tests.test_epub tests.test_pagination
+          tests.test_watermark tests.test_reserialize tests.test_version
+          tests.test_plugin tests.test_validate
+  plugin-compat:
+    name: Parse-check the plugin zip under the interpreters Calibre embeds
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # v0.39.0 shipped 3.14-only syntax and the plugin failed to load with
+        # a bare SyntaxError on every released Calibre. The embedded
+        # interpreters are 3.11 (7.x and the whole 8.x series) and 3.14
+        # (9.0+); 3.12/3.13 bracket the gap and match the CLI's grammar
+        # floor (tests/test_version.py). The plugin cannot be imported
+        # without Calibre, but the shipped zip can be extracted and
+        # byte-compiled, which catches exactly this class.
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Build the plugin zip from this tree
+        run: python scripts/build_plugin.py
+      - name: Byte-compile the zip contents and the CLI sources
+        run: |
+          python -m zipfile -e dist/BinderyRepair-*.zip plugin_pkg
+          python -m compileall -q plugin_pkg src

{bindery_cli-0.38.0 → bindery_cli-0.40.0}/CLAUDE.md

@@ -15,7 +15,11 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - **Minimal Dependencies.** Runtime deps are exactly: `tqdm` (progress/output),
   `vir-tui` (shared TUI rendering) and `cquarry` (read-only Calibre `metadata.db` access,
   adopted in v0.16.0), pinned as PyPI ranges in pyproject.toml (`vir-tui>=2.2.0`,
-  `cquarry>=1.9.0`); `uv.lock` records the resolved versions. `html5lib` remains the one approved
+  `cquarry>=1.19.0`); `uv.lock` records the resolved versions. Since v0.40.0 both
+  VirInvictus pins carry `; python_version >= '3.14'` markers (every release they
+  ship declares requires-python >=3.14) and the package floor is 3.12: a 3.12/3.13
+  install runs the stack-free repair core, and the audit/library surfaces degrade
+  through cli.py's dispatch guard instead of failing resolution. `html5lib` remains the one approved
   heavy-parsing exception (used only for the `--reserialize` fix, imported lazily so every
   other mode runs without it). Tests use the standard `unittest` framework. epubcheck is an
   external CLI dependency expected on PATH; `--install-to-calibre` needs no external
@@ -30,7 +34,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
     `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
     `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
-    `--fix-container`, `--fix-media-types`; transforms.py, threaded through epub.py):
+    `--fix-container`, `--fix-media-types`, `--fix-cover`; transforms.py, threaded
+    through epub.py):
     they alter markup structure or fabricate minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
     v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
     name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
@@ -57,8 +62,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   `--escape-unknown-entities`) plus `--encode-url-spaces`, which repair without
   altering visible markup; the "twelve structural repairs and three lossy strips"
   phrasing elsewhere in these docs was never the complete inventory, and the
-  Phase 16 package repairs (`--fix-container`, `--fix-media-types`) took the
-  structural count to fourteen (v0.38.0).
+  Phase 16 package repairs (`--fix-container`, `--fix-media-types`, `--fix-cover`)
+  took the structural count to fifteen (v0.38.0 + v0.39.0).
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
@@ -79,17 +84,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
-- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED).
-- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.38.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them — spine@toc, media-overlay, fallback, EPUB2 cover meta — are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only).
+- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
+- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them — spine@toc, media-overlay, fallback, EPUB2 cover meta — are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched — never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
-- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape.
-- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin, and the Calibre plugin (build drift + run behavior under calibre stubs).
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
+- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs).
 
 ## Conventions
 
 - Type hints, `from __future__ import annotations`, ruff for lint and format.
+- `./run_tests.sh` runs the suite in the project venv. Since the 3.12 floor, `uv run --python X` REBUILDS `.venv` for interpreter X, and the `python_version >= '3.14'` markers then gate vir-tui/cquarry OUT of it below 3.14 (the suite goes red with ModuleNotFoundError: cquarry). After interpreter experiments, rebuild with `uv run --python 3.14` before running the suite again.
 - `VERSION` lives in `src/bindery/__init__.py`, mirrored in `pyproject.toml`. Bump both.
 - Run tests with `./run_tests.sh`.
 

bindery_cli-0.38.0/README.md → bindery_cli-0.40.0/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.5
+Name: bindery-cli
+Version: 0.40.0
+Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
+Author: vrnvctss
+License: MIT
+License-File: LICENSE
+Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: cquarry>=1.19.0; python_version >= '3.14'
+Requires-Dist: tqdm
+Requires-Dist: vir-tui>=2.2.0; python_version >= '3.14'
+Provides-Extra: reserialize
+Requires-Dist: html5lib>=1.1; extra == 'reserialize'
+Description-Content-Type: text/markdown
+
 <div align="center">
   <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
   <h1>bindery-cli</h1>
@@ -43,6 +67,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
 - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so an honestly-declared misnamed file is never made worse.
+- **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -68,7 +93,19 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## Install
 
-Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+Python 3.12+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for
+progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and
+`cquarry` (read-only Calibre database access), which install on Python 3.14+
+only; `html5lib` remains an optional extra, needed only for `--reserialize`.
+
+The floor is two-tier by those markers: on Python 3.14 everything runs. On
+3.12/3.13 the install carries the repair core only, which is the tool's core
+job: `bindery repair` on a single EPUB works in full, while `bindery audit`,
+`bindery library` and `bindery run` print a one-line note that the command
+needs the Python 3.14 stack instead of dying in a traceback. (Every vir-tui
+and cquarry release on PyPI currently declares `requires-python >=3.14`, so
+the stack itself cannot follow the floor down until they move.) CI runs the
+stack-free test modules on real 3.12 and 3.13 interpreters.
 
 ```sh
 uv tool install bindery-cli                            # core tools
@@ -85,6 +122,18 @@ well-formedness fixes plus the NCX pipeline. The structural repairs and lossy
 strips stay CLI-only, because their acceptance is the epubcheck gate and
 epubcheck cannot run inside Calibre; nothing runs ungated in the plugin, ever.
 
+Compatibility: the plugin declares a minimum Calibre of **7.0** and
+`supported_platforms` is Linux. Both are honest floors, not boastful ones:
+released Calibre embeds Python 3.11 through the whole 8.x series and 3.14 from
+9.0 on, and CI byte-compiles the shipped plugin zip under Python 3.11, 3.12,
+3.13 and 3.14, so the plugin parses on every current Calibre series; 7.x is
+the oldest whose interpreter CI covers, 2.x-6.x embed interpreters nothing
+verifies. The Calibre API surface the plugin uses is the long-stable
+`FileTypePlugin` shape, exercised against test stubs only; the plugin is
+developed and tested on Linux (v0.39.0 shipped the 3.14-only except syntax
+and silently failed to load on every released Calibre, which is the failure
+this floor and CI now guard against).
+
 Behavior and guarantees:
 
 - `run()` never raises and never touches the original file or `metadata.db`: a

bindery_cli-0.38.0/PKG-INFO → bindery_cli-0.40.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.5
-Name: bindery-cli
-Version: 0.38.0
-Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
-Author: vrnvctss
-License: MIT
-License-File: LICENSE
-Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Utilities
-Requires-Python: >=3.14
-Requires-Dist: cquarry>=1.19.0
-Requires-Dist: tqdm
-Requires-Dist: vir-tui>=2.2.0
-Provides-Extra: reserialize
-Requires-Dist: html5lib>=1.1; extra == 'reserialize'
-Description-Content-Type: text/markdown
-
 <div align="center">
   <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
   <h1>bindery-cli</h1>
@@ -65,6 +43,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
 - **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so an honestly-declared misnamed file is never made worse.
+- **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -90,7 +69,19 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## Install
 
-Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+Python 3.12+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for
+progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and
+`cquarry` (read-only Calibre database access), which install on Python 3.14+
+only; `html5lib` remains an optional extra, needed only for `--reserialize`.
+
+The floor is two-tier by those markers: on Python 3.14 everything runs. On
+3.12/3.13 the install carries the repair core only, which is the tool's core
+job: `bindery repair` on a single EPUB works in full, while `bindery audit`,
+`bindery library` and `bindery run` print a one-line note that the command
+needs the Python 3.14 stack instead of dying in a traceback. (Every vir-tui
+and cquarry release on PyPI currently declares `requires-python >=3.14`, so
+the stack itself cannot follow the floor down until they move.) CI runs the
+stack-free test modules on real 3.12 and 3.13 interpreters.
 
 ```sh
 uv tool install bindery-cli                            # core tools
@@ -107,6 +98,18 @@ well-formedness fixes plus the NCX pipeline. The structural repairs and lossy
 strips stay CLI-only, because their acceptance is the epubcheck gate and
 epubcheck cannot run inside Calibre; nothing runs ungated in the plugin, ever.
 
+Compatibility: the plugin declares a minimum Calibre of **7.0** and
+`supported_platforms` is Linux. Both are honest floors, not boastful ones:
+released Calibre embeds Python 3.11 through the whole 8.x series and 3.14 from
+9.0 on, and CI byte-compiles the shipped plugin zip under Python 3.11, 3.12,
+3.13 and 3.14, so the plugin parses on every current Calibre series; 7.x is
+the oldest whose interpreter CI covers, 2.x-6.x embed interpreters nothing
+verifies. The Calibre API surface the plugin uses is the long-stable
+`FileTypePlugin` shape, exercised against test stubs only; the plugin is
+developed and tested on Linux (v0.39.0 shipped the 3.14-only except syntax
+and silently failed to load on every released Calibre, which is the failure
+this floor and CI now guard against).
+
 Behavior and guarantees:
 
 - `run()` never raises and never touches the original file or `metadata.db`: a

{bindery_cli-0.38.0 → bindery_cli-0.40.0}/patchnotes.md

@@ -1,4 +1,90 @@
 # bindery-cli Patch Notes
+## v0.40.0 (2026-09-13)
+
+### The plugin loads on Calibre again: the Python floor drops to 3.12
+
+- **The plugin compatibility fix.** v0.39.0 shipped PEP 758
+  unparenthesized except tuples, which are a SyntaxError on every Python
+  before 3.14, and the Bindery Repair plugin failed to load on every
+  released Calibre with a bare SyntaxError, silently. All six sites are
+  parenthesized now (plugin/__init__.py, the vendored epub.py copies,
+  validate.py), which is valid on every Python 3 and what the plugin
+  needed all along.
+- **The compatibility matrix CI actually verifies.** Released Calibre
+  embeds Python 3.11 through the whole 8.x series (7.0.0 = 3.11.5,
+  8.16.2 = 3.11.14) and 3.14 from 9.0 (9.0.0 = 3.14.2), per calibre's own
+  build manifests. CI gained a `plugin-compat` job that builds the plugin
+  zip the way the release does, extracts it, and byte-compiles the zip
+  contents plus the CLI sources under 3.11, 3.12, 3.13 and 3.14, so the
+  class of failure that shipped in v0.39.0 is now a red build instead of
+  a silent plugin. `ruff`'s `target-version = "py312"` pin keeps the
+  formatter from re-stripping the parens, and a new grammar-floor guard
+  in the version tests parses the whole tree under the 3.12 grammar.
+- **Honest plugin metadata.** `minimum_calibre_version` is (7, 0, 0), the
+  oldest series whose embedded interpreter CI actually verifies,
+  replacing the hollow (2, 0, 0). The README plugin section now
+  documents platform support (developed and tested on Linux) and the
+  exact verification level behind the floor.
+- **requires-python drops to >=3.12, with one honest refinement.** Every
+  cquarry (1.9.0-1.21.0) and vir-tui (2.2.0/2.3.0) release on PyPI
+  declares requires-python >=3.14, so a bare floor drop would have made
+  `pip install` fail on 3.12/3.13 in dependency resolution for exactly
+  the strangers the floor is meant to invite. The VirInvictus pins
+  instead carry `; python_version >= '3.14'` markers: Python 3.14
+  installs are byte-identical to v0.39.0, and 3.12/3.13 installs get the
+  stack-free repair core, where `bindery repair` (the one broken EPUB, no
+  Calibre) works in full. `bindery audit`, `bindery library` and
+  `bindery run` print a one-line note that the command needs the Python
+  3.14 stack instead of a traceback (a lazy renderer proxy in the audit
+  module and a dispatch guard in the CLI). CI runs the stack-free test
+  modules on real 3.12 and 3.13 interpreters (258 tests per leg).
+- **Repair-edge riders from the six-lens audit.** `--fix-container`
+  XML-escapes the book-controlled OPF path when it writes
+  container.xml and unescapes at both readers, so a book with an OPF
+  named like `Tom & Jerry.opf` does not gain a fresh fatal while being
+  repaired, and the escaped form round-trips (regression-tested,
+  including second-repair idempotence). The last two FRAGMENT em-dash
+  verdict lines match the colon style. `fix_cover_meta` loses its dead
+  `present` parameter.
+
+## v0.39.0 (2026-09-12)
+
+### The cover-wiring repair (`--fix-cover`) and the executed rulings
+
+- **`--fix-cover` repairs dangling EPUB2 cover wiring.** A
+  `<meta name="cover">` whose content names no manifest item is
+  re-pointed when the OPF guide's own cover reference resolves to
+  exactly one manifest item (the producer's statement, so nothing is
+  guessed), and removed when nothing identifies the item. A meta whose
+  item exists is never touched: an absent cover file belongs to
+  `--prune-missing-resources` and its edge completion.
+- **Gate treatment:** cover wiring is invisible to epubcheck, so a
+  cover-only repair always answered 'equal' from the improvement gate.
+  Cover repairs now ride the same no_worse acceptance the lossy strips
+  use, with the partial rule intact: a regression rejects, a
+  still-fatal book stays partial and is never auto-applied. Verified
+  on a real dangling-meta book from the library: re-pointed 1,
+  accepted.
+- **Scope by ruling (the hybrid):** the EPUB3
+  `properties="cover-image"` slice stays audit-only. Choosing which
+  image is the cover from filenames is exactly the non-determinism the
+  charter forbids, and no library book is fully unwired (measured:
+  21 dangling EPUB2 metas, 3 absent cover files, 103 EPUB3 books
+  without the property, 0 with no wiring at all).
+- **The metadata-validity carve-out is ruled: routed to
+  cquarry/CalibreQuarry.** bindery's side is closed: human-facing dc:
+  metadata stays a non-goal. The cross-repo handoff (a routed box in
+  CalibreQuarry's backlog naming the 51 OPF-085 invalid-UUID warnings
+  and the thin date/language tail) is filed for the next CQ lane.
+- **The tag-policy force-push repairs are executed** on a researched
+  go: the v0.28.0 tag retargeted to the first green commit with its
+  title line restored (the historic `git tag -F` defect had stripped
+  it), the v0.33.0 tag message replaced with the corrected verbatim
+  entry, and the 10 test_facility EPUBs stripped from all history
+  (git filter-repo; main and all 14 tags force-pushed in one
+  publish.yml-disabled session; verbatim tag messages survived; PyPI
+  untouched). The roadmap's Tag policy section records the execution.
+
 ## v0.38.0 (2026-09-12)
 
 ### Phase 16: package-structure repairs

{bindery_cli-0.38.0 → bindery_cli-0.40.0}/plugin/__init__.py

@@ -66,7 +66,14 @@ class BinderyRepair(FileTypePlugin):
     )
     author = "Brandon LaRocque"
     version = __PLUGIN_VERSION__
-    minimum_calibre_version = (2, 0, 0)
+    # (7, 0, 0), not (2, 0, 0): the vendored core must at least PARSE under
+    # the interpreter the target Calibre embeds, and CI byte-compiles the
+    # built zip under 3.11/3.12/3.13/3.14. Released Calibre embeds 3.11
+    # through the whole 8.x series and 3.14 from 9.0 (bypy sources.json),
+    # so 7.x is the oldest series the compatibility job actually covers;
+    # 2.x-6.x embed interpreters nothing verifies and the claim was hollow.
+    # The syntax floor is pinned by tests/test_version.py.
+    minimum_calibre_version = (7, 0, 0)
     supported_platforms = ["linux"]
     type = "File type"
     file_types = {"epub"}
@@ -215,7 +222,7 @@ class BinderyRepair(FileTypePlugin):
                 text=True,
                 timeout=300,
             )
-        except OSError, subprocess.TimeoutExpired:
+        except (OSError, subprocess.TimeoutExpired):
             return None
         try:
             data = json.loads(proc.stdout)
@@ -225,7 +232,7 @@ class BinderyRepair(FileTypePlugin):
                 int(checker["nError"]),
                 int(checker["nWarning"]),
             )
-        except json.JSONDecodeError, KeyError, TypeError, ValueError:
+        except (json.JSONDecodeError, KeyError, TypeError, ValueError):
             return None
 
     # ---- plugin housekeeping

{bindery_cli-0.38.0 → bindery_cli-0.40.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.38.0"
+version = "0.40.0"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [
@@ -12,10 +12,12 @@ classifiers = [
     "Environment :: Console",
     "Intended Audience :: End Users/Desktop",
     "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
     "Topic :: Utilities",
 ]
-requires-python = ">=3.14"
+requires-python = ">=3.12"
 keywords = ["epub", "epubcheck", "calibre", "repair", "ebook", "html-repair", "watermarks"]
 license = { text = "MIT" }
 authors = [
@@ -24,10 +26,15 @@ authors = [
 # Core dependencies are minimal. html5lib is needed only for the opt-in --reserialize structural
 # repair; it is imported lazily, so every other mode works without it installed.
 # vir-tui and cquarry are pinned as PyPI ranges; uv.lock records the resolved versions.
+# Both are marker-gated to 3.14+ because every release they ship declares
+# requires-python >=3.14: without the markers a 3.12/3.13 install of this
+# package would die in dependency resolution before `bindery repair` (which
+# needs neither) could run. The audit/library surfaces degrade with a clean
+# message (cli.py's dispatch guard) instead of installing at all.
 dependencies = [
   "tqdm",
-  "vir-tui>=2.2.0",
-  "cquarry>=1.19.0",
+  "vir-tui>=2.2.0; python_version >= '3.14'",
+  "cquarry>=1.19.0; python_version >= '3.14'",
 ]
 
 [project.optional-dependencies]
@@ -39,6 +46,14 @@ bindery = "bindery.cli:main"
 [tool.hatch.build.targets.wheel]
 packages = ["src/bindery"]
 
+[tool.ruff]
+# Pin the rewrite level below the house interpreter on purpose: the Calibre
+# plugin vendors these modules into Calibre's embedded interpreters, so the
+# parenthesized except form must survive `ruff format`. A target inferred
+# from requires-python >=3.14 rewrites it to the PEP 758 bare form, which is
+# a SyntaxError on every released Calibre (see tests/test_version.py).
+target-version = "py312"
+
 [tool.ruff.lint]
 # Pinned explicitly so `ruff check` means the same thing locally and in CI. Without
 # this the result rode on whichever ruff was installed: 0.15 passed clean while 0.16