bindery-cli 0.36.0__tar.gz → 0.37.0__tar.gz

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/.github/workflows/publish.yml

@@ -43,3 +43,26 @@ jobs:
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
+
+  plugin-zip:
+    name: Build the Bindery Repair Calibre plugin zip
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Run the suite
+        run: |
+          pip install .[reserialize]
+          PYTHONPATH=src python -m unittest discover -s tests
+
+      - name: Build the plugin zip from the tagged tree
+        run: python scripts/build_plugin.py
+
+      - name: Attach BinderyRepair zip to the release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/BinderyRepair-*.zip

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/CLAUDE.md

@@ -73,7 +73,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 ## Layout
 
-- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms.
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`). Since v0.32.0: `strip_attrs_in_start_tags` anchors attribute edits on the quote-aware start-tag matcher, `_outside_protected` forwards arguments (context-carrying transforms can be decorated), `fix_id_colons` matches only the bare `id` attribute and only internal fragments (`fix_ncx_src_fragments` carries renames into the NCX), `fix_ncx_playorder` is anchored to `<navPoint>` start tags, and the css selector boundary covers namespaced and functional selector forms. Since v0.37.0: `fix_ncx_playorder` strips quotes before its already-correct comparison (regex groups carry quote characters; comparing quoted values against bare numbers counted phantom fixes on every sequential NCX and rewrote single-quoted correct attributes to double quotes).
 - `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`.
@@ -82,7 +82,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-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).
-- `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, and the version pin.
+- `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).
 
 ## Conventions
 

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.36.0
+Version: 0.37.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
@@ -95,6 +95,41 @@ uv tool install bindery-cli                            # core tools
 uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
 ```
 
+## The Calibre plugin (Bindery Repair)
+
+Each release also ships **BinderyRepair-v<VERSION>.zip**, a Calibre plugin that
+repairs EPUBs as they are imported: it is attached to the GitHub release beside
+the PyPI wheel (install it via Calibre's Preferences, Plugins, "Load plugin
+from file"). The plugin is the CLI's always-on core pass only: the five
+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.
+
+Behavior and guarantees:
+
+- `run()` never raises and never touches the original file or `metadata.db`: a
+  repaired copy is built in a persistent temp file and handed back for import;
+  any trouble returns the original path and logs one line.
+- Byte-idempotent: an already-clean book yields zero fixes and the original
+  path, so re-adding a format re-runs the plugin harmlessly.
+- The rewritten archive is `testzip()`-verified before it is handed back.
+- One log line per book (fixed / no fixes / refused / errored), appended to
+  `bindery_repair.log` in Calibre's config directory by default.
+- Files over the size cap are refused (default 150MB) rather than stalling an
+  import.
+
+Configuration is the plugin's customization string, parsed as JSON:
+
+```json
+{"log": true, "log_path": "/path/bindery_repair.log", "max_size_mb": 150,
+ "epubcheck_path": null}
+```
+
+`epubcheck_path` opts into the experimental on-PATH validation mode: the
+repaired copy is re-measured with your epubcheck binary and refused unless it
+is no worse than the original. It defaults to off; the default pass is safe
+without a gate, and the mode costs two epubcheck runs per imported book.
+
 ## Usage
 
 Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/README.md

@@ -73,6 +73,41 @@ uv tool install bindery-cli                            # core tools
 uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
 ```
 
+## The Calibre plugin (Bindery Repair)
+
+Each release also ships **BinderyRepair-v<VERSION>.zip**, a Calibre plugin that
+repairs EPUBs as they are imported: it is attached to the GitHub release beside
+the PyPI wheel (install it via Calibre's Preferences, Plugins, "Load plugin
+from file"). The plugin is the CLI's always-on core pass only: the five
+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.
+
+Behavior and guarantees:
+
+- `run()` never raises and never touches the original file or `metadata.db`: a
+  repaired copy is built in a persistent temp file and handed back for import;
+  any trouble returns the original path and logs one line.
+- Byte-idempotent: an already-clean book yields zero fixes and the original
+  path, so re-adding a format re-runs the plugin harmlessly.
+- The rewritten archive is `testzip()`-verified before it is handed back.
+- One log line per book (fixed / no fixes / refused / errored), appended to
+  `bindery_repair.log` in Calibre's config directory by default.
+- Files over the size cap are refused (default 150MB) rather than stalling an
+  import.
+
+Configuration is the plugin's customization string, parsed as JSON:
+
+```json
+{"log": true, "log_path": "/path/bindery_repair.log", "max_size_mb": 150,
+ "epubcheck_path": null}
+```
+
+`epubcheck_path` opts into the experimental on-PATH validation mode: the
+repaired copy is re-measured with your epubcheck binary and refused unless it
+is no worse than the original. It defaults to off; the default pass is safe
+without a gate, and the mode costs two epubcheck runs per imported book.
+
 ## Usage
 
 Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/patchnotes.md

@@ -1,4 +1,50 @@
 # bindery-cli Patch Notes
+## v0.37.0 (2026-09-12)
+
+### The Bindery Repair Calibre plugin (Phase 3)
+
+- **Books are repaired as they are imported.** Each release now attaches
+  BinderyRepair-v<VERSION>.zip to the GitHub release: a Calibre
+  FileTypePlugin (on_import) that runs the CLI's always-on core pass, the
+  five well-formedness fixes plus the NCX pipeline, on *.epub files as they
+  are added. run() never raises and never touches the original file or
+  metadata.db: a repaired copy is built in a persistent temp file,
+  testzip()-verified, and handed back for import; any trouble returns the
+  original path and logs one line. The plugin is byte-idempotent, so
+  re-adding a format re-runs it harmlessly.
+- **The vendor slice is byte-identical to the repo.** The zip carries
+  transforms.py, epub.py, pagination.py, watermark.py, and reserialize.py
+  unchanged (the zip root is a package, so their relative imports resolve);
+  a suite drift test pins the equality, and publish.yml regenerates the zip
+  from the tag and attaches it to the release.
+- **Nothing runs ungated, ever.** The structural repairs and the lossy
+  strips stay CLI-only because their acceptance is the epubcheck gate,
+  which cannot run inside Calibre. Identity: Bindery Repair /
+  bindery_repair. Config via the plugin's customization string as JSON:
+  log, log_path (default <config dir>/bindery_repair.log), max_size_mb
+  (recorded default 150MB), and epubcheck_path, the experimental on-PATH
+  validation mode, default OFF (the three open questions, answered
+  2026-09-11).
+
+### Fixed: fix_ncx_playorder counted phantom fixes (found by the plugin)
+
+- The already-correct comparison read the attribute value with its
+  quotes, so every sequential navPoint counted as a fix on every pass
+  while the rewritten bytes stayed identical. The Long Patrol reported
+  fix_ncx_playorder=59 on every run of a repaired book; a book whose
+  only fix was phantom was rewritten instead of reported as nochange;
+  and a single-quoted sequential attribute was rewritten to double
+  quotes, touching already-correct markup. Quotes are now stripped
+  before the comparison and an already-correct attribute is returned
+  untouched: honest counts, single quotes survive, and the plugin's
+  zero-fixes contract holds end to end.
+
+### Repo records
+
+- Phase 16's FastSweep prevalence study (5,228 books) and the obfuscation
+  magic-byte validation are recorded in the roadmap with real counts for
+  every Phase 16 repair box.
+
 ## v0.36.0 (2026-09-12)
 
 ### The completeness spot-check: `audit completeness` (Phase 15)

bindery_cli-0.37.0/plugin/__init__.py

@@ -0,0 +1,239 @@
+"""Bindery Repair: repair EPUBs on import with bindery-cli's gate-safe pass.
+
+A Calibre FileTypePlugin running bindery-cli's always-on core pass (the five
+well-formedness transforms plus the NCX pipeline) on *.epub files as they are
+imported. The structural repairs and the lossy strips stay CLI-only: their
+acceptance IS the epubcheck gate, which cannot run inside Calibre (no jar, no
+JVM, and seconds-per-book latency), so their flags are never enabled here and
+nothing runs ungated, ever.
+
+The on_import contract: run(path) returns the path to a repaired copy built
+with the plugin's own temporary_file(), and Calibre imports that instead. The
+original on disk is never touched and nothing writes to metadata.db. No
+exception ever escapes run(): a raising plugin cannot abort an import (Calibre
+falls back to the original silently), so every failure returns the original
+path and logs one line. The plugin is byte-idempotent: an already-clean book
+yields zero fixes and the original path, which db.add_format's
+run_hooks=True re-entry requires.
+
+Configuration is the plain site_customization string, parsed as JSON::
+
+    {"log": true, "log_path": "/path/bindery_repair.log",
+     "max_size_mb": 150, "epubcheck_path": null}
+
+log_path defaults to <calibre config dir>/bindery_repair.log. The size cap
+refuses absurd files rather than stalling an import; 150MB is the recorded
+default. epubcheck_path opts into the experimental on-PATH validation mode:
+the repaired copy is re-measured with the epubcheck binary and refused unless
+it is no worse than the original (the CLI's no_worse bar). It defaults to
+off, keeping the import fast; the default pass is safe without a gate.
+
+The vendored bindery modules ride in this zip as submodules of the plugin
+package (their relative imports resolve unchanged), so the zip's module bytes
+are identical to the repo's src/bindery/ sources; scripts/build_plugin.py
+generates the zip at release and the suite's drift test pins the equality.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import zipfile
+from collections import namedtuple
+from pathlib import Path
+
+__PLUGIN_VERSION__ = (0, 0, 0)  # substituted by scripts/build_plugin.py
+
+# The vendored bindery modules load as submodules of this plugin package
+# (calibre_plugins.bindery_repair.epub and siblings), so their own relative
+# imports resolve unchanged.
+from calibre.customize import FileTypePlugin
+
+from . import epub as _bindery_epub
+
+DEFAULT_MAX_SIZE_MB = 150
+_EPUB_SUFFIXES = (".epub",)
+# the slice of validate.CheckResult the experimental mode needs
+_EcCounts = namedtuple("_EcCounts", "fatals errors warnings")
+
+
+class BinderyRepair(FileTypePlugin):
+    name = "Bindery Repair"
+    description = (
+        "Repair well-formedness defects in EPUB files as they are imported, "
+        "running bindery-cli's epubcheck-safe default pass"
+    )
+    author = "Brandon LaRocque"
+    version = __PLUGIN_VERSION__
+    minimum_calibre_version = (2, 0, 0)
+    supported_platforms = ["linux"]
+    type = "File type"
+    file_types = {"epub"}
+    on_import = True
+    priority = 1
+
+    # ---- run() never raises: the contract is the original path on trouble
+
+    def run(self, path_to_ebook):
+        try:
+            return self._run(path_to_ebook)
+        except Exception as e:
+            # the last-resort sink re-reads the config, whose parsing is
+            # itself exception-safe; run() must never raise
+            self._log(
+                f"errored: {path_to_ebook}: {type(e).__name__}: {e}",
+                self._resolve_log_path(self._config()),
+            )
+            return path_to_ebook
+
+    def _run(self, path_to_ebook: str) -> str:
+        src = Path(path_to_ebook)
+        if src.suffix.lower() not in _EPUB_SUFFIXES:
+            return path_to_ebook
+        cfg = self._config()
+        log_path = self._resolve_log_path(cfg)
+        try:
+            size_mb = src.stat().st_size / (1024 * 1024)
+        except OSError as e:
+            self._log(f"errored: {src}: {e}", log_path)
+            return path_to_ebook
+        cap = cfg.get("max_size_mb", DEFAULT_MAX_SIZE_MB)
+        if isinstance(cap, (int, float)) and cap > 0 and size_mb > cap:
+            self._log(
+                f"refused: {src.name}: {size_mb:.0f}MB over the {cap:g}MB cap",
+                log_path,
+            )
+            return path_to_ebook
+
+        with self.temporary_file(".epub") as tf:
+            dst = Path(tf.name)
+            try:
+                report = _bindery_epub.repair_epub(src, dst)
+            except Exception as e:
+                self._log(
+                    f"errored: {src.name}: repair failed: {type(e).__name__}: {e}",
+                    log_path,
+                )
+                return path_to_ebook
+            if not report:
+                # zero fixes: hand back the original byte-for-byte (the
+                # add_format(run_hooks=True) re-entry depends on this)
+                dst.unlink(missing_ok=True)
+                self._log(f"no fixes: {src.name}", log_path)
+                return path_to_ebook
+            with zipfile.ZipFile(dst) as z:
+                damaged = z.testzip()
+            if damaged is not None:
+                dst.unlink(missing_ok=True)
+                self._log(
+                    f"refused: {src.name}: rewritten archive failed testzip() "
+                    f"at {damaged}",
+                    log_path,
+                )
+                return path_to_ebook
+            if "epubcheck_path" in cfg and cfg["epubcheck_path"]:
+                verdict = self._epubcheck_no_worse(src, dst, cfg["epubcheck_path"])
+                if verdict is False:
+                    dst.unlink(missing_ok=True)
+                    self._log(
+                        f"refused: {src.name}: epubcheck measured the repair "
+                        "no better or worse; keeping the original",
+                        log_path,
+                    )
+                    return path_to_ebook
+            detail = ", ".join(f"{k}={v}" for k, v in sorted(report.fixes.items()))
+            if report.ncx_uid_synced:
+                detail = (detail + ", " if detail else "") + "ncx_uid_synced"
+            self._log(f"fixed: {src.name}: {detail}", log_path)
+            return str(dst)
+
+    # ---- configuration and logging
+
+    def _config(self) -> dict:
+        raw = getattr(self, "site_customization", None)
+        if not raw:
+            return {}
+        try:
+            cfg = json.loads(raw)
+        except ValueError:
+            # a broken config lands one line in the default log and the run
+            # proceeds on the defaults; an import must never be lost to config
+            self._log(
+                "config: site_customization is not valid JSON; using defaults",
+                self._default_log_path(),
+            )
+            return {}
+        return cfg if isinstance(cfg, dict) else {}
+
+    def _resolve_log_path(self, cfg: dict) -> str | None:
+        if not cfg.get("log", True):
+            return None
+        path = cfg.get("log_path") or self._default_log_path()
+        return path if isinstance(path, str) else None
+
+    def _default_log_path(self) -> str | None:
+        try:
+            from calibre.constants import config_dir
+
+            return os.path.join(config_dir, "bindery_repair.log")
+        except Exception:
+            return None
+
+    def _log(self, line: str, log_path: str | None) -> None:
+        """One line per book, appended; logging must never break an import."""
+        if not log_path:
+            return
+        try:
+            with open(log_path, "a", encoding="utf-8") as f:
+                f.write(line.rstrip() + "\n")
+        except OSError:
+            pass
+
+    # ---- experimental epubcheck-on-PATH validation (default off)
+
+    def _epubcheck_no_worse(self, src: Path, dst: Path, epubcheck: str) -> bool | None:
+        """Measure both files with the epubcheck binary; True when the repair
+        is no worse (no net-new fatals, no new errors unless fatals masked
+        them), False when it regressed, None when the binary cannot answer
+        (an unanswered check never refuses the repair; the pass is safe)."""
+        before = self._epubcheck_counts(src, epubcheck)
+        after = self._epubcheck_counts(dst, epubcheck)
+        if before is None or after is None:
+            return None
+        if after.fatals > before.fatals:
+            return False
+        if before.fatals == 0 and after.errors > before.errors:
+            return False
+        return True
+
+    def _epubcheck_counts(self, path: Path, epubcheck: str):
+        try:
+            proc = subprocess.run(
+                [epubcheck, "--json", "-", str(path)],
+                capture_output=True,
+                text=True,
+                timeout=300,
+            )
+        except OSError, subprocess.TimeoutExpired:
+            return None
+        try:
+            data = json.loads(proc.stdout)
+            checker = data["checker"]
+            return _EcCounts(
+                int(checker["nFatal"]),
+                int(checker["nError"]),
+                int(checker["nWarning"]),
+            )
+        except json.JSONDecodeError, KeyError, TypeError, ValueError:
+            return None
+
+    # ---- plugin housekeeping
+
+    def customization_help(self, gui=False):
+        return (
+            'Enter a JSON object: {"log": true, "log_path": ..., '
+            '"max_size_mb": 150, "epubcheck_path": null}. '
+            "epubcheck_path enables the experimental post-repair validation "
+            "with the epubcheck binary (slow; off by default)."
+        )

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/pyproject.toml

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

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/roadmap.md

@@ -278,8 +278,16 @@ locale hardening (5.2), in v0.10.0. Phase 5 is closed.*
 
 ## Phase 3: integration (maybe)
 
-- [ ] Calibre plugin so books are repaired on add, as a `FileTypePlugin` with
-      `on_import = True`.
+- [x] Calibre plugin so books are repaired on add, as a `FileTypePlugin` with
+      `on_import = True`. *(SHIPPED 2026-09-12 as v0.37.0: "Bindery Repair" /
+      `bindery_repair`, built to the scoped spec below. Vendor slice byte-
+      identical with a suite drift test; default pass only; testzip()
+      verification; byte-idempotent; one log line per book; site_customization
+      JSON config with the size cap at the recorded default 150MB and the
+      epubcheck-on-PATH experimental mode default OFF; publish.yml attaches
+      BinderyRepair-v<VERSION>.zip to each release. The plugin's smoke test
+      found the fix_ncx_playorder phantom-count bug (Bug Reports), which the
+      same release fixes.)*
 - [x] ~~Optional metadata.db nudge so Calibre notices the new file size~~
       **Dropped 2026-08-09: unnecessary under `on_import`.** See the decision below.
 
@@ -370,6 +378,12 @@ Open questions (Brandon): epubcheck-on-PATH experimental mode (default no, the
 latency ruling stands); plugin identity `Bindery Repair` / `bindery_repair`;
 size-cap default.
 
+*(ANSWERED 2026-09-11 and SHIPPED 2026-09-12 as v0.37.0: epubcheck-on-PATH
+mode exists behind the `epubcheck_path` config key and defaults OFF; identity
+is `Bindery Repair` / `bindery_repair`; the size cap keeps the documented
+default, now recorded as 150MB in README and spec. See the plugin box above
+and the spec's "The Calibre plugin" section.)*
+
 
 ## Supplementary Phase (Based on Library Audit)
 Following a comprehensive epubcheck sweep of a 5,043-book Calibre library on 2026-08-22 (~3,228 candidates for repair), several recurring error schemas were identified; all have since shipped. (This section absorbs the one-off `BINDERY_REPORT.md`, retired in v0.17.0 — its performance notes live in the v0.13.0 patchnotes, and its findings are the checked items below.)
@@ -696,6 +710,26 @@ driven alternative was rejected because it would still silently mutate legal
 markup whenever an unrelated finding existed; the gate keeps EPUB3 books
 byte-identical.)*
 
+### fix_ncx_playorder counts phantom fixes on already-sequential NCXs (2026-09-12, plugin work)
+**Bug in the default pass's `fix_ncx_playorder`:** the already-correct
+comparison read the captured attribute value WITH its quotes
+(`m.group(2) != str(playorder)`), so every navPoint counted as a fix on
+every pass. The rewritten bytes stayed identical (which is why the
+deterministic-output tests and every gate run never caught it), but the
+fix counts were phantom: The Long Patrol reported `fix_ncx_playorder=59`
+on every run of an already-repaired book, and a book whose only "fix"
+was phantom was rewritten instead of being reported as nochange. A
+single-quoted sequential attribute was also rewritten to double quotes,
+touching already-correct markup. Found by the Calibre plugin's smoke
+test: the plugin's zero-fixes contract (return the original path) broke
+on real books. `transforms.py` `fix_ncx_playorder`.
+**Fix:** strip the quotes before comparing; an already-correct attribute
+is returned untouched (its quote style preserved) and not counted.
+*(Fixed in v0.37.0: honest counts on every NCX, single quotes survive,
+and the plugin's byte-idempotence holds end to end. The sweep's
+apply-path behavior changes only in that a phantom-only repair is now
+correctly a noop.)*
+
 ## Phase 11: Migrate install-to-calibre to native cquarry API (proposed 2026-08-31)
 
 *Context: `bindery library --install-to-calibre` currently shells out to the external `calibredb add_format` CLI binary. This is fragile (it crashed on 2026-08-31 due to a non-existent `--replace` flag) and bypasses the transaction and trigger-safety guarantees built into the `cquarry` library. Since bindery-cli already imports `cquarry` for path resolution, it should adopt the native write module.*
@@ -1418,14 +1452,34 @@ an opt-in structural repair under the existing gate contract.
 
 ### A. Research first (boxes cannot be honestly sized without these)
 
-- [ ] **FastSweep prevalence study**: run `fast_sweep.py
+- [x] **FastSweep prevalence study**: run `fast_sweep.py
   --mode=extract` aggregation over the full library for the new
   classes — container.xml presence/validity, encryption.xml
   algorithms, manifest media-type warnings, case-mismatch RSC-007s.
   Each Phase 16 repair box gets its real count before it opens.
-- [ ] **Obfuscation magic-byte validation**: confirm the IDPF
+  *(done 2026-09-12: 5,228 books through epubcheck extract (664s) plus
+  a direct zip-level pass. Real counts: container.xml valid on
+  5,228/5,228 (zero gateway-defect books in-library); OPF-029
+  media-type mismatches 275 occurrences in 15 books; RSC-007 14,156
+  occurrences in 600 books and PKG-010 in 280 (the prune surface,
+  1,538 truly-absent manifest hrefs); case-mismatch hrefs exactly 1 in
+  1 book; backslash hrefs 0; duplicate zip entries 0 books; encryption.xml
+  in 86 books carrying 429 entries (426 Adobe `ns.adobe.com/pdf/enc#RC`
+  obfuscation + 3 IDPF `2008/embedding`), and NO real-DRM algorithm
+  anywhere in the library.)*
+- [x] **Obfuscation magic-byte validation**: confirm the IDPF
   (`2008/embedding`) and Adobe (`pdf/enc#RC`) font prefixes at offset 0
   against real samples before the encryption-repair box opens.
+  *(done 2026-09-12, same pass: all 424 readable obfuscation-declared
+  fonts carry scrambled, non-font bytes at offset 0 (no OTTO/ttf/ttc/
+  woff magic anywhere) — every in-library obfuscated font is genuinely
+  obfuscated, so the "decrypted in place" stale-entry class has ZERO
+  prevalence here; the valid-magic-at-offset-0 test is validated as the
+  right discriminator for the repair's precondition. Two CipherReference
+  targets are absent from their archives. Real-sample correction: the
+  Adobe algorithm URI in the wild is `http://ns.adobe.com/pdf/enc#RC`,
+  not the spec-text `http://www.adobe.com/2005/pdf/enc#RC`; recognition
+  must carry both.)*
 
 ### B. The repairs (each: opt-in flag, dry-run default, gate-accepted)
 

bindery_cli-0.37.0/scripts/build_plugin.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Build the Bindery Repair Calibre plugin zip from the repo tree.
+
+The plugin vendors bindery-cli's gate-safe repair core: transforms.py,
+epub.py, pagination.py, watermark.py, reserialize.py (byte-identical copies;
+the zip root is a package, so their relative imports resolve unchanged) plus
+plugin/__init__.py with the version tuple substituted from
+src/bindery/__init__.py. A `plugin-import-name-bindery_repair.txt` marker
+names the import package calibre_plugins.bindery_repair.
+
+stdlib only; a release-time tool (publish.yml runs it against the tag), not
+part of the repair contract.
+
+Example:
+  python scripts/build_plugin.py --out dist/BinderyRepair-v0.36.0.zip
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+import zipfile
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+PLUGIN_ENTRY = REPO / "plugin" / "__init__.py"
+VENDOR_MODULES = (
+    "transforms.py",
+    "epub.py",
+    "pagination.py",
+    "watermark.py",
+    "reserialize.py",
+)
+IMPORT_NAME_MARKER = "plugin-import-name-bindery_repair.txt"
+
+# Keep in sync with __PLUGIN_VERSION__ in plugin/__init__.py.
+_VERSION_LINE = re.compile(r"^__PLUGIN_VERSION__ = .*$", re.MULTILINE)
+
+
+def repo_version() -> tuple[int, int, int]:
+    """The single source of truth: src/bindery/__init__.py's VERSION."""
+    text = (REPO / "src" / "bindery" / "__init__.py").read_text(encoding="utf-8")
+    match = re.search(r'^VERSION = "(\d+)\.(\d+)\.(\d+)"$', text, re.MULTILINE)
+    if not match:
+        sys.exit('error: no VERSION = "X.Y.Z" line in src/bindery/__init__.py')
+    return tuple(int(part) for part in match.groups())
+
+
+def plugin_entry_bytes(version: tuple[int, int, int]) -> bytes:
+    text = PLUGIN_ENTRY.read_text(encoding="utf-8")
+    if "__PLUGIN_VERSION__ = " not in text:
+        sys.exit("error: plugin/__init__.py carries no __PLUGIN_VERSION__ line")
+    substituted = _VERSION_LINE.sub(f"__PLUGIN_VERSION__ = {version!r}", text, count=1)
+    return substituted.encode("utf-8")
+
+
+def build(out: Path) -> Path:
+    version = repo_version()
+    with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr(IMPORT_NAME_MARKER, "bindery_repair\n")
+        z.writestr("__init__.py", plugin_entry_bytes(version))
+        for name in VENDOR_MODULES:
+            src = REPO / "src" / "bindery" / name
+            z.writestr(name, src.read_bytes())
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument(
+        "--out",
+        type=Path,
+        default=None,
+        help="output zip path (default: dist/BinderyRepair-v<VERSION>.zip)",
+    )
+    args = ap.parse_args()
+    version = repo_version()
+    out = (
+        args.out or REPO / "dist" / f"BinderyRepair-v{'.'.join(map(str, version))}.zip"
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    build(out)
+    print(f"wrote {out} (Bindery Repair v{'.'.join(map(str, version))})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/spec.md

@@ -405,6 +405,52 @@ replacement contract is untouched. The scope refusal is mechanical: no `--ids`,
 no sweep, exit 2 (a library-wide sweep is a dedicated hours-long task, never a
 verb call). Books left partial or unreadable surface as `decisions_needed`.
 
+## The Calibre plugin (Bindery Repair)
+
+Each release vendors the repair core into a Calibre plugin zip,
+`BinderyRepair-v<VERSION>.zip`, generated from the tagged tree by
+`scripts/build_plugin.py` and attached to the GitHub release. The zip carries
+`transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, and
+`reserialize.py` byte-identical to `src/bindery/` (the zip root is a package,
+so their relative imports resolve unchanged; a suite drift test pins the
+equality) plus the plugin entry `plugin/__init__.py` with the version tuple
+substituted from the single-source `VERSION`.
+
+Identity and shape: the plugin is `Bindery Repair` (import name
+`bindery_repair`, via the `plugin-import-name-` marker), a
+`FileTypePlugin` with `on_import = True`, `supported_platforms = ['linux']`
+(the loader rejects an empty platform list, which also makes other OSes an
+enforced non-goal).
+
+The active fix set is exactly the CLI's default pass: the five
+well-formedness transforms plus the NCX pipeline. All structural repairs and
+the three lossy strips stay CLI-only: their acceptance IS the epubcheck gate,
+which cannot run inside Calibre. Opt-in flags are never enabled by the
+plugin; nothing runs ungated.
+
+Behavior contract:
+
+- `run(path)` never raises. It returns the path of a repaired copy built with
+  the plugin's `temporary_file()` (Calibre imports that instead; the original
+  on disk is untouched, `metadata.db` is never written, there is no
+  `postimport` hook), or the original path on any trouble: non-`.epub`
+  suffix, over the size cap, zero fixes, a failed `testzip()` verification of
+  the rewritten archive, or an exception (each logged, never raised).
+- Byte-idempotence: an already-clean book yields zero fixes and the original
+  path, because the format-add path (`db.add_format(..., run_hooks=True)`)
+  re-enters the plugin on repaired files.
+- One log line per book (fixed / no fixes / refused / errored), appended
+  under a lock-free best-effort policy: logging failures never break an
+  import.
+- Configuration is the `site_customization` string parsed as JSON: `log`
+  (default true), `log_path` (default `<config_dir>/bindery_repair.log`),
+  `max_size_mb` (default 150: refuse absurd files rather than stall an
+  import), and `epubcheck_path` (default null). `epubcheck_path` enables the
+  experimental on-PATH validation mode: the repaired copy is re-measured with
+  the user's epubcheck binary under the `no_worse` bar and refused on a
+  regression; an unanswered measurement never refuses. The mode is off by
+  default (the latency ruling stands; the default pass is safe ungated).
+
 ## Out of scope (non-goals)
 
 - Fixing RSC-005 schema/content-model violations *in bulk*: the scoped, opt-in

{bindery_cli-0.36.0 → bindery_cli-0.37.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.36.0"
+VERSION = "0.37.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/src/bindery/transforms.py

@@ -333,9 +333,16 @@ def fix_ncx_playorder(s: str) -> tuple[str, int]:
 
     def repl(m: re.Match) -> str:
         nonlocal count, playorder
-        if m.group(2) != str(playorder):
+        # the captured value carries its quotes; strip them before comparing,
+        # or every already-correct navPoint counts as a fix on every pass
+        # (identical output bytes, phantom counts; found by the plugin work,
+        # 2026-09-12). A correct value is returned untouched, so a
+        # single-quoted correct attribute keeps its quote style.
+        if m.group(2).strip("\"'") == str(playorder):
+            res = m.group(0)
+        else:
             count += 1
-        res = f'{m.group(1)} playOrder="{playorder}"'
+            res = f'{m.group(1)} playOrder="{playorder}"'
         playorder += 1
         return res
 

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/tests/test_cli.py

@@ -536,8 +536,8 @@ class TestApplyFailureIsolation(unittest.TestCase):
     def test_apply_oserror_is_recorded_and_run_continues(self):
         with tempfile.TemporaryDirectory() as td:
             root = Path(td)
-            _phase1_book(root / "a.epub", broken=False)
-            _phase1_book(root / "b.epub", broken=False)
+            _phase1_book(root / "a.epub", broken=False, real_fix=True)
+            _phase1_book(root / "b.epub", broken=False, real_fix=True)
             jout = root / "lib.json"
             out, err = io.StringIO(), io.StringIO()
             with (
@@ -902,10 +902,13 @@ class TestAuditJsonWiring(unittest.TestCase):
         run.assert_not_called()
 
 
-def _phase1_book(path: Path, broken: bool) -> None:
+def _phase1_book(path: Path, broken: bool, real_fix: bool = False) -> None:
     """A realistic loose EPUB: proper container/OPF/NCX, >2000 chars of body
     text so the audit battery stays silent on it. `broken` leaves an unclosed
-    <p> that only --reserialize can repair (epubcheck fatal, audit-clean)."""
+    <p> that only --reserialize can repair (epubcheck fatal, audit-clean).
+    `real_fix` writes a genuinely unordered NCX playOrder so the default pass
+    reports a real fix (the 2026-09-12 playOrder counter fix made a clean
+    book a true noop, so tests exercising the apply path need this)."""
     container = (
         '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
         '<rootfiles><rootfile full-path="content.opf" '
@@ -921,11 +924,12 @@ def _phase1_book(path: Path, broken: bool) -> None:
         '<item id="ncx" href="t.ncx" media-type="application/x-dtbncx+xml"/>'
         '</manifest><spine toc="ncx"><itemref idref="c1"/></spine></package>'
     )
+    playorder_attr = 'playOrder="7"' if real_fix else 'playOrder="1"'
     ncx = (
         '<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">'
         '<head><meta name="dtb:uid" content="x"/></head>'
         "<docTitle><text>T</text></docTitle><navMap>"
-        '<navPoint id="n1" playOrder="1"><navLabel><text>C1</text></navLabel>'
+        f'<navPoint id="n1" {playorder_attr}><navLabel><text>C1</text></navLabel>'
         '<content src="t.xhtml"/></navPoint></navMap></ncx>'
     )
     if broken:

bindery_cli-0.37.0/tests/test_plugin.py

@@ -0,0 +1,360 @@
+"""The Bindery Repair Calibre plugin: zip build drift, import shape, and
+run() behavior under a stubbed calibre namespace.
+
+The plugin vendors the repair core's five modules byte-identically; the
+loader (calibre/customize/zipplugin.py) imports every zip-root .py as a
+submodule of the plugin package, which is exactly the import shape these
+tests install, so behavior tested here is behavior that ships."""
+
+import importlib.util
+import json
+import pathlib
+import sys
+import tempfile
+import types
+import unittest
+import zipfile
+from collections import namedtuple
+
+REPO = pathlib.Path(__file__).resolve().parents[1]
+PLUGIN_DIR = REPO / "plugin"
+_Counts = namedtuple("_Counts", "fatals errors warnings")
+
+VENDOR_MODULES = (
+    "transforms.py",
+    "epub.py",
+    "pagination.py",
+    "watermark.py",
+    "reserialize.py",
+)
+
+
+def _repo_version() -> tuple[int, int, int]:
+    text = (REPO / "src" / "bindery" / "__init__.py").read_text(encoding="utf-8")
+    prefix = 'VERSION = "'
+    start = text.index(prefix) + len(prefix)
+    end = text.index('"', start)
+    return tuple(int(part) for part in text[start:end].split("."))
+
+
+_PTF_DIR: tempfile.TemporaryDirectory | None = None
+
+
+class _StubPersistentTemporaryFile:
+    """The slice of calibre.ptempfile.PersistentTemporaryFile the plugin
+    uses: a context manager handing out a real path that survives close()
+    and the with-block (run() returns the path for Calibre to import; only
+    interpreter shutdown cleans it)."""
+
+    def __init__(self, suffix):
+        fd = tempfile.NamedTemporaryFile(suffix=suffix, delete=False, dir=_ptf_dir())
+        self.name = fd.name
+        fd.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass
+
+
+def _ptf_dir() -> str:
+    return _PTF_DIR.name if _PTF_DIR is not None else tempfile.gettempdir()
+
+
+def _install_calibre_stubs(config_dir: str) -> None:
+    cal = types.ModuleType("calibre")
+    customize = types.ModuleType("calibre.customize")
+    constants = types.ModuleType("calibre.constants")
+    ptemp = types.ModuleType("calibre.ptempfile")
+
+    class FileTypePlugin:
+        def __init__(self, plugin_path):
+            self.plugin_path = plugin_path
+            self.site_customization = None
+
+        def temporary_file(self, suffix):
+            return _StubPersistentTemporaryFile(suffix)
+
+    customize.FileTypePlugin = FileTypePlugin
+    constants.config_dir = config_dir
+    ptemp.PersistentTemporaryFile = _StubPersistentTemporaryFile
+    cal.customize = customize
+    cal.constants = constants
+    cal.ptempfile = ptemp
+    for name, mod in (
+        ("calibre", cal),
+        ("calibre.customize", customize),
+        ("calibre.constants", constants),
+        ("calibre.ptempfile", ptemp),
+    ):
+        sys.modules.setdefault(name, mod)
+
+
+def _load_plugin_package():
+    """Import plugin/__init__.py exactly the way calibre's loader does: as
+    the package calibre_plugins.bindery_repair, with the vendored modules
+    resolvable as its submodules (plugin dir first, then src/bindery)."""
+    _install_calibre_stubs(tempfile.gettempdir())
+    pkg = types.ModuleType("calibre_plugins")
+    sys.modules.setdefault("calibre_plugins", pkg)
+    spec = importlib.util.spec_from_file_location(
+        "calibre_plugins.bindery_repair",
+        PLUGIN_DIR / "__init__.py",
+        submodule_search_locations=[str(PLUGIN_DIR), str(REPO / "src" / "bindery")],
+    )
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["calibre_plugins.bindery_repair"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestPluginBuild(unittest.TestCase):
+    """The zip the release attaches is a pure function of the repo tree."""
+
+    @classmethod
+    def setUpClass(cls):
+        sys.path.insert(0, str(REPO / "scripts"))
+        import build_plugin
+
+        cls.build_plugin = build_plugin
+        cls.tmp = tempfile.TemporaryDirectory(prefix="bindery_plugin_")
+        cls.zip_path = pathlib.Path(cls.tmp.name) / "test-plugin.zip"
+        build_plugin.build(cls.zip_path)
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.tmp.cleanup()
+        sys.path.remove(str(REPO / "scripts"))
+
+    def _entry(self, name: str) -> bytes:
+        with zipfile.ZipFile(self.zip_path) as z:
+            return z.read(name)
+
+    def test_vendor_modules_are_byte_identical(self):
+        for name in VENDOR_MODULES:
+            self.assertEqual(
+                self._entry(name),
+                (REPO / "src" / "bindery" / name).read_bytes(),
+                name,
+            )
+
+    def test_entry_is_the_plugin_source_with_the_repo_version(self):
+        raw = self._entry("__init__.py").decode("utf-8")
+        version = _repo_version()
+        self.assertIn(f"__PLUGIN_VERSION__ = {version!r}", raw)
+        committed = (PLUGIN_DIR / "__init__.py").read_text(encoding="utf-8")
+        # the only permitted difference is the substituted version line
+        self.assertEqual(
+            raw,
+            self.build_plugin._VERSION_LINE.sub(
+                f"__PLUGIN_VERSION__ = {version!r}", committed, count=1
+            ),
+        )
+
+    def test_import_name_marker_and_zip_layout(self):
+        self.assertEqual(
+            self._entry("plugin-import-name-bindery_repair.txt"),
+            b"bindery_repair\n",
+        )
+        with zipfile.ZipFile(self.zip_path) as z:
+            names = set(z.namelist())
+        self.assertIn("__init__.py", names)
+        self.assertTrue(set(VENDOR_MODULES) <= names)
+
+    def test_default_output_name_carries_the_version(self):
+        version = ".".join(str(part) for part in _repo_version())
+        self.assertEqual(self.build_plugin.repo_version(), _repo_version())
+        out = self.build_plugin.REPO / "dist" / f"BinderyRepair-v{version}.zip"
+        self.assertEqual(out.parent, self.build_plugin.REPO / "dist")
+        self.assertTrue(out.name.startswith("BinderyRepair-v"))
+
+
+class TestPluginRun(unittest.TestCase):
+    """run() behavior against synthetic EPUBs, under the calibre stubs."""
+
+    CONTAINER = (
+        '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
+        '<rootfiles><rootfile full-path="content.opf" '
+        'media-type="application/oebps-package+xml"/></rootfiles></container>'
+    )
+    OPF = (
+        '<package xmlns="http://www.idpf.org/2007/opf">'
+        "<manifest>"
+        '<item id="c1" href="text.xhtml" media-type="application/xhtml+xml"/>'
+        "</manifest>"
+        '<spine><itemref idref="c1"/></spine></package>'
+    )
+
+    @classmethod
+    def setUpClass(cls):
+        global _PTF_DIR
+        _PTF_DIR = tempfile.TemporaryDirectory(prefix="bindery_plugin_tmp_")
+        cls._ptf_dir = _PTF_DIR
+        cls.plugin_module = _load_plugin_package()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls._ptf_dir.cleanup()
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory(prefix="bindery_plugin_run_")
+        self.addCleanup(self.tmp.cleanup)
+        self.plugin = self.plugin_module.BinderyRepair("/tmp/not-a-real-plugin.zip")
+        self.plugin.site_customization = json.dumps(
+            {"log_path": str(pathlib.Path(self.tmp.name) / "plugin.log")}
+        )
+
+    def _epub(self, name="t.epub", doc=None, pad=0):
+        # doc is the FULL content-document text; None builds a clean doc
+        if doc is None:
+            doc = "<html><body><p>ordinary prose</p></body></html>"
+        p = pathlib.Path(self.tmp.name) / name
+        with zipfile.ZipFile(p, "w") as z:
+            z.writestr("mimetype", "application/epub+zip")
+            z.writestr("META-INF/container.xml", self.CONTAINER)
+            z.writestr("content.opf", self.OPF)
+            z.writestr("text.xhtml", doc)
+            if pad:
+                z.writestr("filler.bin", b"\0" * pad)
+        return p
+
+    def _log(self) -> str:
+        f = pathlib.Path(self.tmp.name) / "plugin.log"
+        return f.read_text() if f.exists() else ""
+
+    def test_damaged_book_is_repaired_and_original_untouched(self):
+        # a BOM before the first < is prolog junk: one default-pass fix
+        p = pathlib.Path(self.tmp.name) / "d.epub"
+        with zipfile.ZipFile(p, "w") as z:
+            z.writestr("mimetype", "application/epub+zip")
+            z.writestr("META-INF/container.xml", self.CONTAINER)
+            z.writestr("content.opf", self.OPF)
+            z.writestr(
+                "text.xhtml",
+                "\ufeff<html><body><p>prolog junk here</p></body></html>",
+            )
+        before = p.read_bytes()
+        out = self.plugin.run(str(p))
+        self.assertNotEqual(out, str(p))
+        self.assertTrue(pathlib.Path(out).exists())
+        self.assertEqual(p.read_bytes(), before)  # the original is never touched
+        with zipfile.ZipFile(out) as z:
+            self.assertIsNone(z.testzip())
+            self.assertIn("prolog junk here", z.read("text.xhtml").decode("utf-8"))
+        self.assertIn("fixed:", self._log())
+
+    def test_clean_book_returns_original_byte_for_byte(self):
+        p = self._epub()
+        out = self.plugin.run(str(p))
+        self.assertEqual(out, str(p))
+        self.assertIn("no fixes:", self._log())
+
+    def test_idempotent_second_run_reports_no_fixes(self):
+        p = self._epub(doc="\ufeff<html><body><p>junk</p></body></html>")
+        first = self.plugin.run(str(p))
+        repaired = pathlib.Path(first).read_bytes()
+        second = self.plugin.run(first)
+        self.assertEqual(second, first)
+        self.assertIn("no fixes:", self._log())
+        # and the repaired file the first run produced is stable
+        self.assertEqual(pathlib.Path(first).read_bytes(), repaired)
+
+    def test_size_cap_refuses_and_returns_original(self):
+        self.plugin.site_customization = json.dumps(
+            {
+                "log_path": str(pathlib.Path(self.tmp.name) / "plugin.log"),
+                "max_size_mb": 0.01,  # ~10KB: the padded book exceeds it
+            }
+        )
+        p = self._epub(pad=64 * 1024)
+        out = self.plugin.run(str(p))
+        self.assertEqual(out, str(p))
+        self.assertIn("refused:", self._log())
+        self.assertIn("cap", self._log())
+
+    def test_broken_json_config_falls_back_to_defaults(self):
+        self.plugin.site_customization = "{not json"
+        p = self._epub(doc="\ufeff<html><body><p>junk</p></body></html>")
+        out = self.plugin.run(str(p))
+        # defaults still repair (log goes to the calibre config dir, which
+        # the stub points into a read-safe scratch dir)
+        self.assertNotEqual(out, str(p))
+
+    def test_non_epub_suffix_passes_through(self):
+        p = pathlib.Path(self.tmp.name) / "cover.jpg"
+        p.write_bytes(b"not an epub at all")
+        out = self.plugin.run(str(p))
+        self.assertEqual(out, str(p))
+        self.assertEqual(self._log(), "")
+
+    def test_unreadable_zip_errors_and_returns_original(self):
+        p = pathlib.Path(self.tmp.name) / "broken.epub"
+        p.write_bytes(b"PK\x03\x04 this is not really a zip")
+        out = self.plugin.run(str(p))
+        self.assertEqual(out, str(p))
+        self.assertIn("errored:", self._log())
+
+    def test_experimental_epubcheck_mode_refuses_a_regression(self):
+        p = self._epub(doc="\ufeff<html><body><p>junk</p></body></html>")
+        self.plugin.site_customization = json.dumps(
+            {
+                "log_path": str(pathlib.Path(self.tmp.name) / "plugin.log"),
+                "epubcheck_path": "/usr/bin/false",
+            }
+        )
+
+        def fake_counts(plugin, path, cmd):
+            # the original measures clean, the repaired copy "regresses"
+            return _Counts(0, 0, 0) if path == p else _Counts(1, 0, 0)
+
+        self.plugin_module.BinderyRepair._epubcheck_counts = fake_counts
+        self.addCleanup(
+            delattr,
+            self.plugin_module.BinderyRepair,
+            "_epubcheck_counts",
+        )
+        out = self.plugin.run(str(p))
+        self.assertEqual(out, str(p))
+        self.assertIn("refused:", self._log())
+
+    def test_experimental_epubcheck_mode_accepts_no_worse(self):
+        p = self._epub(doc="\ufeff<html><body><p>junk</p></body></html>")
+        self.plugin.site_customization = json.dumps(
+            {
+                "log_path": str(pathlib.Path(self.tmp.name) / "plugin.log"),
+                "epubcheck_path": "/usr/bin/false",
+            }
+        )
+        self.plugin_module.BinderyRepair._epubcheck_counts = lambda plugin, path, cmd: (
+            _Counts(1, 0, 0)
+        )
+        self.addCleanup(
+            delattr,
+            self.plugin_module.BinderyRepair,
+            "_epubcheck_counts",
+        )
+        out = self.plugin.run(str(p))
+        self.assertNotEqual(out, str(p))
+        self.assertIn("fixed:", self._log())
+
+    def test_experimental_epubcheck_mode_unanswered_check_accepts(self):
+        p = self._epub(doc="\ufeff<html><body><p>junk</p></body></html>")
+        self.plugin.site_customization = json.dumps(
+            {
+                "log_path": str(pathlib.Path(self.tmp.name) / "plugin.log"),
+                "epubcheck_path": "/usr/bin/false",
+            }
+        )
+        self.plugin_module.BinderyRepair._epubcheck_counts = lambda plugin, path, cmd: (
+            None
+        )
+        self.addCleanup(
+            delattr,
+            self.plugin_module.BinderyRepair,
+            "_epubcheck_counts",
+        )
+        out = self.plugin.run(str(p))
+        # an unanswered measurement never refuses the (safe) default pass
+        self.assertNotEqual(out, str(p))
+        self.assertIn("fixed:", self._log())

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/tests/test_transforms.py

@@ -462,6 +462,33 @@ class TestFixNcxPlayorder(unittest.TestCase):
         self.assertEqual(out.count('playOrder="1"'), 1)
         self.assertIn("Chapter playOrder=", out)
 
+    def test_already_sequential_playorder_is_not_counted_as_fixes(self):
+        # found by the plugin work (2026-09-12): the already-correct
+        # comparison read the attribute value WITH its quotes, so every
+        # sequential navPoint counted as a fix on every pass. The rewritten
+        # bytes were identical, which is why the deterministic-output tests
+        # never caught it; only the fix counts were phantom (59 on a real
+        # book, every run), and the plugin's zero-fixes contract broke.
+        ncx = "".join(f'<navPoint id="p{i}" playOrder="{i}"/>' for i in range(1, 5))
+        out, n = fix_ncx_playorder(ncx)
+        self.assertEqual(n, 0)
+        self.assertEqual(out, ncx)
+
+    def test_single_quoted_sequential_playorder_is_untouched(self):
+        # the same bug's second face: already-correct markup must stay
+        # untouched (single quotes preserved), not be rewritten to doubles
+        ncx = "".join(f"<navPoint id='p{i}' playOrder='{i}'/>" for i in range(1, 5))
+        out, n = fix_ncx_playorder(ncx)
+        self.assertEqual(n, 0)
+        self.assertEqual(out, ncx)
+
+    def test_resequence_count_still_counts_real_changes(self):
+        ncx = '<navPoint playOrder="2"/><navPoint playOrder="2"/>'
+        out, n = fix_ncx_playorder(ncx)
+        self.assertEqual(n, 1)  # the first moves 2->1; the second is right
+        self.assertIn('playOrder="1"', out)
+        self.assertIn('playOrder="2"', out)
+
 
 class TestStripInvalidValue(unittest.TestCase):
     def test_misplaced_value_is_stripped(self):

{bindery_cli-0.36.0 → bindery_cli-0.37.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.14"
 
 [[package]]
 name = "bindery-cli"
-version = "0.35.0"
+version = "0.37.0"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry" },