bindery-cli 0.39.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.39.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
@@ -80,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/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.39.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>
@@ -69,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
@@ -86,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.39.0/PKG-INFO → bindery_cli-0.40.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.5
-Name: bindery-cli
-Version: 0.39.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>
@@ -91,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
@@ -108,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.39.0 → bindery_cli-0.40.0}/patchnotes.md

@@ -1,4 +1,52 @@
 # 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

{bindery_cli-0.39.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.39.0 → bindery_cli-0.40.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.39.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

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/roadmap.md

@@ -1408,7 +1408,7 @@ everything else is backlog, not danger.*
 
 *(SHIPPED 2026-09-12 as v0.36.0: `audit completeness` rides the existing
 single decompression pass; the Redwall-shaped regression tests landed
-first (4021ce7), the analyzer second (e6156c0). Verified against the
+first (ed2589d), the analyzer second (da0d2c7). Verified against the
 real fixtures: Lord Brocktree's trailing ToC is caught with the Epilogue
 sampled as the last prose doc, The Long Patrol reads exactly 55/57
 prose docs through its percent-encoded hrefs, and Mattimeo's split doc
@@ -1486,7 +1486,7 @@ an opt-in structural repair under the existing gate contract.
 - [x] **`--fix-container`**: generate META-INF/container.xml at the
   located OPF (model: upstream calibre's initialize_container).
   Gateway repair, effort S, HIGH value.
-  *(shipped v0.38.0, dac7835: fires when the container is missing,
+  *(shipped v0.38.0, fa65c3a: fires when the container is missing,
   unparseable, or names a file the archive does not contain; the
   generated entry carries the constant epoch so repairs stay
   byte-deterministic. Prevalence: 0 books in-library (5,228/5,228 have
@@ -1506,7 +1506,7 @@ an opt-in structural repair under the existing gate contract.
 - [x] **Audit distinction: OBFUSCATED vs DRM** in audit.py (today the
   ENCRYPTED verdict keys on unreadable entries and implies DRM where
   publisher obfuscation is benign). S, rides the box above.
-  *(shipped v0.38.0, dac7835: readable obfuscation entries are the
+  *(shipped v0.38.0, fa65c3a: readable obfuscation entries are the
   OBFUSCATED advisory (problem-False, exit-neutral; 86 library books);
   an unreadable obfuscation entry is CORRUPT (broken font, re-source),
   and only non-obfuscation algorithms give the ENCRYPTED skip.)*
@@ -1514,13 +1514,13 @@ an opt-in structural repair under the existing gate contract.
   rewrite `spine@toc`, `item@media-overlay`, `item@fallback`, and EPUB2
   cover-meta edges when their targets are pruned (machinery exists in
   fix_manifest_ids). Prevents manufacturing gate regressions. S/M.
-  *(shipped v0.38.0, dac7835: prune_missing_manifest_items returns the
+  *(shipped v0.38.0, fa65c3a: prune_missing_manifest_items returns the
   pruned ids; prune_dangling_edges removes the optional attributes and
   a cover meta whose payload died. RSC-007 backs it at 14,156
   occurrences in 600 books.)*
 - [x] **Manifest media-type normalization**: sniff magic bytes /
   extension map; attribute-only. S.
-  *(shipped v0.38.0, dac7835 as `--fix-media-types`: OPF-029 class,
+  *(shipped v0.38.0, fa65c3a as `--fix-media-types`: OPF-029 class,
   275 occurrences in 15 books; jpg/png/gif only, fired only when the
   magic bytes confirm the extension. Oracle-verified on the real
   Arthur sample: nochange without the flag, accept with 9 normalized.)*
@@ -1610,3 +1610,75 @@ The release-tag backlog is settled, forward-only:
   files) are stripped from all history via git filter-repo, main and
   all 14 tags force-pushed. The tags' verbatim messages survived the
   rewrite; PyPI was untouched throughout.
+
+## New findings 2026-09-12 late (six-lens full audit; detail: audit/FULL-AUDIT-2026-09-12.md, Wave 15)
+
+Lane 2026-09-13 shipped v0.40.0 from this section. Correction to the Wave 15
+text: 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 bypy sources.json checked against the upstream clone; the
+"Calibre 9.x embeds 3.13" line was imprecise, and no released Calibre embeds
+3.12 or 3.13 at all. CI now byte-compiles the shipped plugin zip under all
+four interpreter families.
+
+- [x] **HIGH: the Calibre plugin cannot load on mainstream Calibre**
+      (SHIPPED v0.40.0: bab3bdc + bb31308). plugin/__init__.py:218/228 and
+      the vendored epub.py:948/1286 used PEP 758 unparenthesized except
+      tuples - SyntaxError on every released Calibre (see the correction
+      above); validate.py:75/398 carried the same syntax for the CLI. All
+      six sites parenthesized; ruff's `target-version = "py312"` pin keeps
+      `ruff format` from re-stripping the parens (inference from a 3.14
+      requires-python rewrote them); CI gained the `plugin-compat` job
+      (build the zip, extract, `compileall` the zip + src under
+      3.11/3.12/3.13/3.14); `tests/test_version.py` gained the
+      syntax-floor grammar guard so the class fails a test, not a Calibre
+      install. Honest metadata: `minimum_calibre_version` is (7, 0, 0)
+      (the oldest series whose embedded interpreter CI covers; the hollow
+      (2, 0, 0) is gone) and the README plugin section documents platforms
+      (Linux-tested) and the verification story.
+- [ ] **Analyzer robustness on untrusted input:** spine_integrity
+      IndexErrors on a spineless EPUB (nums[0] with an empty list) and
+      the call sites sit OUTSIDE the per-book try - one malformed book
+      aborts a whole run; load_book raises NameError (encrypted_names
+      used before assignment) on a corrupt container.xml; DRM books get
+      an EMPTY re-source verdict alongside the ENCRYPTED skip (extend the
+      emptytext gate to encrypted_drm_n). (Not in the 09-13 lane; still
+      open.)
+- [x] **Repair-edge fixes** (SHIPPED v0.40.0: 2473bf8).
+      generate_container XML-escapes the book-controlled OPF path into its
+      double-quoted attribute and BOTH regex readers unescape before
+      comparing against zip names (the round trip is regression-tested
+      with a "Tom & Jerry.opf" fixture, including the second-repair
+      idempotence the staleness check depends on); the two remaining
+      FRAGMENT em-dash verdict lines match the colon style; fix_cover_meta's
+      dead `present` parameter is removed (the function deliberately
+      consults only OPF text, never archive membership).
+- [x] **Docs sweep, plugin-platforms half** (SHIPPED v0.40.0: bb31308):
+      the plugin is no longer undocumented; the README states supported
+      platforms and the minimum Calibre version. The rest stays open:
+      README's audit CSV claim, the repair_epub docstring's three missing
+      flags, the audit.py module-docstring contradictions, the
+      roman-numeral duplication, the sys.path.insert pollution.
+- [ ] **Blitz candidates:** the audit-refresh deep-dive (per-class deltas
+      vs the 09-12 baselines; first-time counts for the two C-ruled
+      classes); a cover advisory analyzer completing the hybrid ruling;
+      --encode-url-spaces entry rename + reference rewrite (PKG-010, 280
+      books); plugin log rotation.
+- [ ] **GitHub presentation (workspace batch):** description rewrite
+      (leads with deterministic epubcheck-gated repair); 7 topics swapped
+      (add epub3/calibre-plugin/python-cli/ebook-audit); codex page still
+      says calibredb; wiki off.
+
+- [x] **DECIDED 2026-09-13: requires-python drops to ~3.12** (decision
+      63) - EXECUTED v0.40.0 the same day with one refinement Brandon
+      ruled on live: every cquarry (1.9.0-1.21.0) and vir-tui (2.2.0/2.3.0)
+      on PyPI declares requires-python >=3.14, so a bare floor drop would
+      have failed pip resolution for exactly the strangers it invites.
+      Decided shape (asked, markers + guard): the VirInvictus pins carry
+      `; python_version >= '3.14'` markers (3.14 installs byte-identical
+      to v0.39.0), 3.12/3.13 installs run the stack-free repair core,
+      audit.py loads its renderer through the `_LazyUI` proxy, cli.py's
+      dispatch guard turns the missing stack into one stderr line + exit
+      2, and CI's `core-compat` job runs the stack-free test modules on
+      real 3.12/3.13 (258 tests per leg, verified locally under
+      3.12.14/3.13.15). Suite 445, ruff 0.16.2 clean.

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/src/bindery/__init__.py

@@ -4,7 +4,7 @@ strip), epubcheck-gated.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.39.0"
+VERSION = "0.40.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/src/bindery/audit.py

@@ -71,7 +71,22 @@ from pathlib import Path
 from xml.etree import ElementTree as ET
 
 sys.path.insert(0, str(Path(__file__).parent))
-import vir_tui as ui
+
+
+class _LazyUI:
+    # vir_tui rides the Python 3.14 VirInvictus stack, marker-gated out of
+    # 3.12/3.13 installs since the v0.40.0 floor drop. A module-level import
+    # would make the whole package unimportable there (and LOAD_GLOBAL never
+    # consults module __getattr__), so this proxy defers the import to the
+    # first render call, where cli.py's dispatch guard can answer cleanly.
+    def __getattr__(self, name: str):
+        import vir_tui
+
+        return getattr(vir_tui, name)
+
+
+ui = _LazyUI()
+
 
 # ----------------------------------------------------------------------------
 # Shared scaffolding
@@ -1349,18 +1364,18 @@ def _corrupt_verdict(r: dict) -> tuple[bool, str, list[str]]:
             "CORRUPT",
             [
                 f"unreadable obfuscated font(s): {r['encrypted_n']} "
-                f"(first: {r['encrypted_first']}) — broken, not DRM; re-source"
+                f"(first: {r['encrypted_first']}): broken, not DRM; re-source"
             ],
         )
     if r.get("encrypted_n"):
         lines = []
         if r.get("n"):
             lines.append(
-                f"corrupt:{r['n']} (first: {r['first']}) — damaged archive; re-source"
+                f"corrupt:{r['n']} (first: {r['first']}): damaged archive; re-source"
             )
         lines.append(
             f"encrypted:{r['encrypted_drm_n']} (first: {r['encrypted_first']})"
-            " — DRM-protected; not repairable, skip"
+            ": DRM-protected; not repairable, skip"
         )
         return (
             True,
@@ -1368,7 +1383,7 @@ def _corrupt_verdict(r: dict) -> tuple[bool, str, list[str]]:
             lines,
         )
     if r.get("n"):
-        lines = [f"corrupt:{r['n']} (first: {r['first']}) — damaged archive; re-source"]
+        lines = [f"corrupt:{r['n']} (first: {r['first']}): damaged archive; re-source"]
         if r.get("dup_entries"):
             lines.append(
                 f"duplicate entries: {r['dup_entries']} (zip resolves last-wins; "
@@ -1385,7 +1400,7 @@ def _corrupt_verdict(r: dict) -> tuple[bool, str, list[str]]:
             "OBFUSCATED",
             [
                 f"obfuscated font(s): {r['obfuscated_n']} "
-                f"(first: {r['obfuscated_first']}) — publisher embedding, "
+                f"(first: {r['obfuscated_first']}): publisher embedding, "
                 "readable; benign"
             ],
         )
@@ -1432,7 +1447,7 @@ def _spine_verdict(r: dict) -> tuple[bool, str, list[str]]:
         return (
             True,
             "FRAGMENT",
-            [f"toc {r['refs']} refs, {r['absent']} absent — span broken"],
+            [f"toc {r['refs']} refs, {r['absent']} absent: span broken"],
         )
     if r["class"] == "convention":
         return (
@@ -1852,7 +1867,7 @@ def _corrupt_sections(hits) -> int:
         print(f"{RED}{BOLD}CORRUPT ARCHIVES ({len(hits)}){RESET}")
         for book_id, title, tag, n, first in sorted(hits):
             print(f"  {RED}#{book_id}{RESET} [{tag}] {title}")
-            print(f"    corrupt:{n} (first: {first}) — damaged archive; re-source")
+            print(f"    corrupt:{n} (first: {first}): damaged archive; re-source")
         print()
         print(
             f"{RED}{BOLD}archive FOUND{RESET}: {len(hits)} file(s) need re-sourcing "
@@ -1876,7 +1891,7 @@ def _spine_sections(hits, advisory) -> int:
         print(f"{RED}{BOLD}SPINE FRAGMENTS ({len(hits)}){RESET}")
         for book_id, title, tag, r in sorted(hits):
             print(f"  {RED}#{book_id}{RESET} [{tag}] {title}")
-            print(f"    toc {r['refs']} refs, {r['absent']} absent — span broken")
+            print(f"    toc {r['refs']} refs, {r['absent']} absent: span broken")
         print()
         print(
             f"{RED}{BOLD}spine FOUND{RESET}: {len(hits)} file(s) are fragments "
@@ -1921,7 +1936,7 @@ def _obfuscated_sections(hits) -> int:
             print(f"  {YELLOW}#{book_id}{RESET} [{tag}] {title}")
             print(
                 f"    obfuscated font(s): {r['obfuscated_n']} "
-                f"(first: {r['obfuscated_first']}) — readable; benign"
+                f"(first: {r['obfuscated_first']}): readable; benign"
             )
         print()
     return 0

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/src/bindery/cli.py

@@ -1623,6 +1623,20 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
         return args.func(args)
+    except ModuleNotFoundError as e:
+        # The VirInvictus stack (vir-tui, cquarry) is marker-gated to Python
+        # 3.14+ since the v0.40.0 floor drop: a 3.12/3.13 install runs the
+        # single-book repair core, and the audit/library surfaces say what
+        # they need instead of dying with a traceback. Anything else missing
+        # is a real bug and still raises.
+        if e.name not in ("vir_tui", "cquarry"):
+            raise
+        print(
+            f"this command needs the {e.name} library, which currently "
+            "installs only on Python 3.14+; run it under Python 3.14",
+            file=sys.stderr,
+        )
+        return 2
     except KeyboardInterrupt:
         # A library run can take a long time; end a Ctrl-C cleanly instead of with a
         # traceback. In-flight work is safe: the original is only ever touched by the

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/src/bindery/epub.py

@@ -15,6 +15,8 @@ import zipfile
 from dataclasses import dataclass, field
 from pathlib import Path
 from urllib.parse import unquote
+from xml.sax.saxutils import escape as _xml_escape
+from xml.sax.saxutils import unescape as _xml_unescape
 
 from .pagination import collect_runheads, detect_page_layer, strip_pagination_doc
 from .reserialize import reserialize_if_broken
@@ -63,6 +65,12 @@ _ITEM_ID_RE = re.compile(
 )
 _ROOTFILE_RE = re.compile(r"full-path=([\"'])((?:(?!\1).)+)\1")
 
+# The inverse pair for the container.xml rootfile attribute: generate_container
+# escapes the book-controlled OPF path into its double-quoted attribute, and
+# every regex-based reader of that attribute unescapes before comparing against
+# zip names (which are raw). Default entities plus the quote forms.
+_XML_ATTR_ENTITIES = {""": '"', "'": "'"}
+
 
 def _locate_opf(z: zipfile.ZipFile) -> str | None:
     """The package document path, from META-INF/container.xml when possible.
@@ -76,8 +84,8 @@ def _locate_opf(z: zipfile.ZipFile) -> str | None:
     except KeyError:
         container = ""
     m = _ROOTFILE_RE.search(container)
-    if m and m.group(2) in z.namelist():
-        return m.group(2)
+    if m and _xml_unescape(m.group(2), _XML_ATTR_ENTITIES) in z.namelist():
+        return _xml_unescape(m.group(2), _XML_ATTR_ENTITIES)
     return next((n for n in z.namelist() if n.lower().endswith(".opf")), None)
 
 
@@ -275,14 +283,18 @@ def generate_container(opf_path: str) -> str:
     Byte-deterministic: the same OPF path always yields the same bytes (the
     model is upstream calibre's initialize_container). The entry itself is
     written with the constant epoch timestamp, so repairing one book twice
-    is byte-identical.
+    is byte-identical. The path is book-controlled (it is a zip entry name)
+    and lands in a double-quoted XML attribute, so it is escaped: without
+    this, an OPF named like ``Tom & Jerry.opf`` would install a fresh
+    fatal into a book the repair just fixed.
     """
+    safe_path = _xml_escape(opf_path, {'"': """})
     return (
         '<?xml version="1.0" encoding="UTF-8"?>\n'
         '<container version="1.0" '
         'xmlns="urn:oasis:names:tc:opendocument:xmlns:container">\n'
         "  <rootfiles>\n"
-        f'    <rootfile full-path="{opf_path}" '
+        f'    <rootfile full-path="{safe_path}" '
         'media-type="application/oebps-package+xml"/>\n'
         "  </rootfiles>\n"
         "</container>\n"
@@ -309,9 +321,7 @@ _GUIDE_REF_RE = re.compile(
 )
 
 
-def fix_cover_meta(
-    opf_text: str, opf_dir: str, present: frozenset[str]
-) -> tuple[str, dict[str, int]]:
+def fix_cover_meta(opf_text: str, opf_dir: str) -> tuple[str, dict[str, int]]:
     """Repair the EPUB2 cover-meta wiring (the cover-wiring ruling's
     deterministic half; hybrid scope, 2026-09-12).
 
@@ -945,7 +955,7 @@ def ncx_uid_mismatch(src: Path) -> bool:
             text = z.read(ncx).decode("utf-8", "replace")
             m = _DTB_UID_RE.search(text) or _DTB_UID_RE_REV.search(text)
             return bool(m and m.group(3) != uid)
-    except zipfile.BadZipFile, OSError, RuntimeError:
+    except (zipfile.BadZipFile, OSError, RuntimeError):
         # RuntimeError covers zip-encrypted entries, which raise out of
         # z.read: a DRM'd book is not a candidate, not a crash.
         return False
@@ -1154,7 +1164,8 @@ def repair_epub(
                 cm = _ROOTFILE_RE.search(
                     zin.read("META-INF/container.xml").decode("utf-8", "replace")
                 )
-            if not (cm and cm.group(2) in zin.namelist()):
+            rootfile = _xml_unescape(cm.group(2), _XML_ATTR_ENTITIES) if cm else None
+            if not (rootfile and rootfile in zin.namelist()):
                 container_bytes = generate_container(opf).encode("utf-8")
         if container_bytes is not None and "META-INF/container.xml" not in (
             zin.namelist()
@@ -1283,7 +1294,7 @@ def repair_epub(
                         try:
                             with zin.open(resolved) as f:
                                 return f.read(8)
-                        except KeyError, OSError, RuntimeError:
+                        except (KeyError, OSError, RuntimeError):
                             return None
 
                     text, n = fix_manifest_media_types(text, opf_dir, peek)
@@ -1291,7 +1302,7 @@ def repair_epub(
                         report.add({"media_types_normalized": n})
                         opf_changed = True
                 if fix_cover:
-                    text, ccounts = fix_cover_meta(text, opf_dir, present)
+                    text, ccounts = fix_cover_meta(text, opf_dir)
                     if ccounts:
                         report.add(ccounts)
                         opf_changed = True

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/src/bindery/validate.py

@@ -72,7 +72,7 @@ def _counts_from_json(stdout: str) -> CheckResult | None:
         return CheckResult(
             int(checker["nFatal"]), int(checker["nError"]), int(checker["nWarning"])
         )
-    except KeyError, TypeError, ValueError:
+    except (KeyError, TypeError, ValueError):
         return None
 
 
@@ -395,7 +395,7 @@ def run_epubcheck(path: Path, timeout: int = 300) -> CheckResult | None:
             env=_english_locale_env(),
             check=False,
         )
-    except FileNotFoundError, subprocess.TimeoutExpired:
+    except (FileNotFoundError, subprocess.TimeoutExpired):
         return None
     result = _counts_from_json(out.stdout)
     if result is not None:

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/tests/test_cli.py

@@ -1385,3 +1385,24 @@ class TestCoverGate(unittest.TestCase):
     def test_regression_rejects(self):
         o = self._cover_verdict(CheckResult(0, 0, 0), CheckResult(0, 1, 0))
         self.assertEqual(o.status, "reject")
+
+
+class TestStackFreeFloorGuard(unittest.TestCase):
+    """Since the v0.40.0 floor drop the VirInvictus stack (vir-tui, cquarry)
+    is marker-gated out of 3.12/3.13 installs; the audit/library surfaces
+    must say so cleanly (trouble exit, one stderr line) instead of dying
+    with a traceback. Poisoning sys.modules stands in for the absent
+    library whatever the dev machine has installed."""
+
+    def test_missing_stack_is_a_clean_trouble_exit(self):
+        with tempfile.TemporaryDirectory() as td:
+            # any .epub name reaches the audit scan's first ui render, which
+            # is the first point the gated library would load
+            (Path(td) / "x.epub").write_bytes(b"not a zip")
+            out, err = io.StringIO(), io.StringIO()
+            with mock.patch.dict(sys.modules, {"vir_tui": None}):
+                with redirect_stdout(out), redirect_stderr(err):
+                    rc = main(["audit", "content", td])
+            self.assertEqual(rc, 2)
+            self.assertIn("installs only on Python 3.14+", err.getvalue())
+            self.assertIn("vir_tui", err.getvalue())

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/tests/test_epub.py

@@ -6,12 +6,15 @@ import unittest
 import warnings
 import zipfile
 from pathlib import Path
+from xml.etree import ElementTree as ET
 
 from bindery.epub import (
+    _locate_opf,
     downgrade_epub3_tags,
     fix_manifest_ids,
     fix_ncx_ids,
     fix_pagelist_class,
+    generate_container,
     ncx_uid_mismatch,
     opf_unique_id,
     package_version,
@@ -1325,6 +1328,49 @@ class TestFixContainer(unittest.TestCase):
             report = repair_epub(once, twice, fix_container=True)
             self.assertNotIn("container_generated", report.fixes)
 
+    def test_generate_container_escapes_xml_specials(self):
+        """An OPF entry name is book-controlled and lands in a double-quoted
+        XML attribute; an unescaped '&' or quote would install a fresh fatal
+        into a book the repair just fixed (six-lens audit, 2026-09-12)."""
+        for name in ("Tom & Jerry.opf", 'weird"name.opf', "a<b>c.opf", "plain.opf"):
+            container = generate_container(name)
+            root = ET.fromstring(container)
+            rootfile = root.find(
+                ".//{urn:oasis:names:tc:opendocument:xmlns:container}rootfile"
+            )
+            self.assertEqual(rootfile.get("full-path"), name)
+
+    def test_ampersand_opf_name_round_trips_through_the_generated_container(self):
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            once, twice = Path(td) / "a.epub", Path(td) / "b.epub"
+            opf_name = "OEBPS/Tom & Jerry.opf"
+            self._build(
+                src,
+                {
+                    "mimetype": "application/epub+zip",
+                    opf_name: self.OPF,
+                    "OEBPS/c1.xhtml": CONTENT,
+                },
+            )
+            report = repair_epub(src, once, fix_container=True)
+            self.assertEqual(report.fixes.get("container_generated"), 1)
+            with zipfile.ZipFile(once) as z:
+                self.assertIsNone(z.testzip())
+                container = z.read("META-INF/container.xml").decode("utf-8")
+                root = ET.fromstring(container)
+                rootfile = root.find(
+                    ".//{urn:oasis:names:tc:opendocument:xmlns:container}rootfile"
+                )
+                self.assertEqual(rootfile.get("full-path"), opf_name)
+                # the escaping reader: the locator resolves the escaped
+                # attribute back to the raw zip entry, not the first-.opf
+                # fallback (which a stray duplicate .opf could poison)
+                self.assertEqual(_locate_opf(z), opf_name)
+            # and the escaped container reads back as healthy, not stale
+            report = repair_epub(once, twice, fix_container=True)
+            self.assertNotIn("container_generated", report.fixes)
+
 
 class TestPruneDanglingEdges(unittest.TestCase):
     """Phase 16 B2: pruning an item must rewrite the edges that point at it

bindery_cli-0.40.0/tests/test_version.py

@@ -0,0 +1,78 @@
+"""Tests to ensure version numbers are synchronized across the repository.
+
+v0.19.1 exists because `__init__.py` drifted to 0.18.0 while pyproject said
+0.19.0; this pin is the Phase 7 guard so that class of drift fails a test
+instead of shipping.
+"""
+
+import ast
+import unittest
+from pathlib import Path
+
+from bindery import VERSION as CODE_VERSION
+
+
+class TestVersionSync(unittest.TestCase):
+    def test_versions_match(self):
+        """Ensure pyproject.toml's version mirrors the code's VERSION.
+
+        `__init__.py` is the declared single source (there is no VERSION
+        file by design); pyproject.toml must repeat it exactly.
+        """
+        root_dir = Path(__file__).parent.parent
+
+        pyproject_path = root_dir / "pyproject.toml"
+        pyproject_version = None
+        if pyproject_path.exists():
+            with open(pyproject_path, encoding="utf-8") as f:
+                for line in f:
+                    if line.startswith("version = "):
+                        pyproject_version = line.split("=")[1].strip().strip('"')
+                        break
+
+        self.assertIsNotNone(
+            pyproject_version, "Could not find version in pyproject.toml"
+        )
+        self.assertEqual(
+            pyproject_version,
+            CODE_VERSION,
+            f"pyproject.toml ({pyproject_version}) does not match code VERSION ({CODE_VERSION})",
+        )
+
+
+class TestSyntaxFloor(unittest.TestCase):
+    """The Python floor is a package contract, enforced by parse, not trust.
+
+    v0.39.0 shipped the PEP 758 unparenthesized except form; the Calibre
+    plugin vendors those modules, so the plugin failed to load with a bare
+    SyntaxError on every released Calibre (7.x/8.x embed Python 3.11, 9.x
+    embeds 3.14) and CI could not see it because the suite only ever ran
+    under 3.14. This guard parses every module in the repo's Python roots
+    under a pinned grammar level, so interpreter-only syntax fails a test
+    instead of shipping. The pinned level is a deliberate contract point:
+    update it together with pyproject's requires-python and the CI
+    interpreter legs.
+    """
+
+    GRAMMAR_FLOOR = (3, 12)
+    ROOTS = ("src", "plugin", "tests", "scripts")
+
+    def test_tree_parses_under_the_declared_grammar(self):
+        repo = Path(__file__).parent.parent
+        checked = 0
+        for root in self.ROOTS:
+            for path in sorted((repo / root).rglob("*.py")):
+                if "__pycache__" in path.parts:
+                    continue
+                try:
+                    ast.parse(
+                        path.read_text(encoding="utf-8"),
+                        filename=str(path),
+                        feature_version=self.GRAMMAR_FLOOR,
+                    )
+                except SyntaxError as e:
+                    self.fail(f"{path.relative_to(repo)}: {e}")
+                checked += 1
+        # the tree has dozens of modules; a broken path glob must not
+        # let the guard pass vacuously
+        self.assertGreaterEqual(checked, 20)

{bindery_cli-0.39.0 → bindery_cli-0.40.0}/uv.lock

@@ -1,15 +1,19 @@
 version = 1
 revision = 3
-requires-python = ">=3.14"
+requires-python = ">=3.12"
+resolution-markers = [
+    "python_full_version >= '3.14'",
+    "python_full_version < '3.14'",
+]
 
 [[package]]
 name = "bindery-cli"
-version = "0.39.0"
+version = "0.40.0"
 source = { editable = "." }
 dependencies = [
-    { name = "cquarry" },
+    { name = "cquarry", marker = "python_full_version >= '3.14'" },
     { name = "tqdm" },
-    { name = "vir-tui" },
+    { name = "vir-tui", marker = "python_full_version >= '3.14'" },
 ]
 
 [package.optional-dependencies]
@@ -19,10 +23,10 @@ reserialize = [
 
 [package.metadata]
 requires-dist = [
-    { name = "cquarry", specifier = ">=1.19.0" },
+    { name = "cquarry", marker = "python_full_version >= '3.14'", specifier = ">=1.19.0" },
     { name = "html5lib", marker = "extra == 'reserialize'", specifier = ">=1.1" },
     { name = "tqdm" },
-    { name = "vir-tui", specifier = ">=2.2.0" },
+    { name = "vir-tui", marker = "python_full_version >= '3.14'", specifier = ">=2.2.0" },
 ]
 provides-extras = ["reserialize"]
 

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

@@ -1,25 +0,0 @@
-name: CI
-on:
-  push:
-    branches: [main]
-  pull_request:
-permissions:
-  contents: read
-jobs:
-  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. ruff is a dev-only linter.
-      - run: pip install . html5lib ruff==0.16.2
-      # 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: ruff check .
-      - run: ruff format --check .
-      - run: PYTHONPATH=src python -m unittest discover -s tests

bindery_cli-0.39.0/tests/test_version.py

@@ -1,39 +0,0 @@
-"""Tests to ensure version numbers are synchronized across the repository.
-
-v0.19.1 exists because `__init__.py` drifted to 0.18.0 while pyproject said
-0.19.0; this pin is the Phase 7 guard so that class of drift fails a test
-instead of shipping.
-"""
-
-import unittest
-from pathlib import Path
-
-from bindery import VERSION as CODE_VERSION
-
-
-class TestVersionSync(unittest.TestCase):
-    def test_versions_match(self):
-        """Ensure pyproject.toml's version mirrors the code's VERSION.
-
-        `__init__.py` is the declared single source (there is no VERSION
-        file by design); pyproject.toml must repeat it exactly.
-        """
-        root_dir = Path(__file__).parent.parent
-
-        pyproject_path = root_dir / "pyproject.toml"
-        pyproject_version = None
-        if pyproject_path.exists():
-            with open(pyproject_path, encoding="utf-8") as f:
-                for line in f:
-                    if line.startswith("version = "):
-                        pyproject_version = line.split("=")[1].strip().strip('"')
-                        break
-
-        self.assertIsNotNone(
-            pyproject_version, "Could not find version in pyproject.toml"
-        )
-        self.assertEqual(
-            pyproject_version,
-            CODE_VERSION,
-            f"pyproject.toml ({pyproject_version}) does not match code VERSION ({CODE_VERSION})",
-        )