bindery-cli 0.48.2__tar.gz → 0.49.0__tar.gz

bindery_cli-0.48.2/CLAUDE.md → bindery_cli-0.49.0/AGENTS.md

@@ -1,4 +1,4 @@
-# CLAUDE.md (bindery-cli)
+# AGENTS.md (bindery-cli)
 
 Per-project guidance. Overrides the global file where they conflict.
 
@@ -120,13 +120,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
 - `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); 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; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs 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. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
   custom-rendered and colors itself with the CPython 3.14 argparse theme,
-  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1). `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.
+  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 probed/written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1); since v0.49.0 the single-file verb's no-output form is a probe (the gate runs, the record's `output` is null and `applied` false, nothing is written anywhere; the old implicit `(repaired).epub` sibling was issue #7's import litter in a vetted tree, and writing now needs an explicit DST). `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, `max_log_mb` rotation cap default 2, `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). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
 
 ## Conventions
 
-- Type hints, `from __future__ import annotations`, ruff for lint and format.
+- Python style follows the global conventions (type hints, `from __future__ import annotations`, ruff for lint and format; `~/.zcode/AGENTS.md`).
 - `./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`.
@@ -136,3 +136,12 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 The library is real data. The loop is always: dry run on `/tmp` copies, inspect the
 report, then apply with backups. epubcheck is the oracle; a repaired book that still has
 fatals is `partial` and must be left for manual work, never auto-applied.
+
+## Release flow
+
+Commit and push verified work (the standing push grant in the global file; force-pushes
+still need approval), wait for CI to go green, then tag: annotated `vX.Y.Z` at the release
+commit, message = that release's patchnotes entry verbatim (`--cleanup=verbatim`; the full
+tag procedure lives in `~/.zcode/AGENTS.md`). The tag drives `publish.yml`: the PyPI push
+plus the Bindery Repair plugin zip attached to the GitHub release. Version carriers:
+`src/bindery/__init__.py`'s VERSION and `pyproject.toml`; bump both.

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.48.2
+Version: 0.49.0
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -290,11 +290,15 @@ next startup: no manual resync needed.
 
 ## Repairing a book
 
-Repair one book to a new file (gated; writes only if it is an improvement):
+Repair one book to a new file (gated; writes only if it is an improvement). Without an
+output path the verb is a probe: the gate runs and the report says what would change,
+and nothing is written anywhere, so probing a file can never litter the directory
+under vetting:
 
 ```sh
-bindery repair broken.epub                 # -> "broken (repaired).epub"
-bindery repair broken.epub fixed.epub
+bindery repair broken.epub                 # probe: report only, nothing written
+bindery repair broken.epub --all --json report.json   # probe with a machine-readable record
+bindery repair broken.epub fixed.epub      # rescue form: write the repaired file
 bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
 bindery repair stubs.epub --strip-stub-docs      # drop repeated placeholder chapters
 bindery repair broken.epub fixed.epub --json report.json  # machine-readable record
@@ -303,7 +307,9 @@ bindery repair broken.epub fixed.epub --json report.json  # machine-readable rec
 `repair --json FILE` writes one record in the `library --json` per-book
 vocabulary (`status`, `applied`, `before`/`after` counts, the fix `summary`),
 on every processing outcome including nochange and reject: a calling agent
-gets the same facts the console lines carry.
+gets the same facts the console lines carry. On a probe the record's
+`output` is null and `applied` stays false; the counts and the fix
+breakdown still describe the gate-accepted projection.
 
 ## Sweeping a library
 
@@ -338,7 +344,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.
-- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean OR written (a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`) — it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean, probed, OR written (a probe writes nothing and exits 0; a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`); it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/README.md

@@ -263,11 +263,15 @@ next startup: no manual resync needed.
 
 ## Repairing a book
 
-Repair one book to a new file (gated; writes only if it is an improvement):
+Repair one book to a new file (gated; writes only if it is an improvement). Without an
+output path the verb is a probe: the gate runs and the report says what would change,
+and nothing is written anywhere, so probing a file can never litter the directory
+under vetting:
 
 ```sh
-bindery repair broken.epub                 # -> "broken (repaired).epub"
-bindery repair broken.epub fixed.epub
+bindery repair broken.epub                 # probe: report only, nothing written
+bindery repair broken.epub --all --json report.json   # probe with a machine-readable record
+bindery repair broken.epub fixed.epub      # rescue form: write the repaired file
 bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
 bindery repair stubs.epub --strip-stub-docs      # drop repeated placeholder chapters
 bindery repair broken.epub fixed.epub --json report.json  # machine-readable record
@@ -276,7 +280,9 @@ bindery repair broken.epub fixed.epub --json report.json  # machine-readable rec
 `repair --json FILE` writes one record in the `library --json` per-book
 vocabulary (`status`, `applied`, `before`/`after` counts, the fix `summary`),
 on every processing outcome including nochange and reject: a calling agent
-gets the same facts the console lines carry.
+gets the same facts the console lines carry. On a probe the record's
+`output` is null and `applied` stays false; the counts and the fix
+breakdown still describe the gate-accepted projection.
 
 ## Sweeping a library
 
@@ -311,7 +317,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.
-- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean OR written (a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`) — it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean, probed, OR written (a probe writes nothing and exits 0; a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`); it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/patchnotes.md

@@ -1,5 +1,42 @@
 # bindery-cli Patch Notes
 
+## v0.49.0 (2026-10-13)
+
+### The single-file repair probe writes nothing (issue #7)
+
+Found live in a phase-1 vetting run: `bindery repair <file> --all --json
+report.json`, the acquisition pipeline's documented single-candidate
+probe, wrote its full repaired output as an 11MB `...(repaired).epub`
+sibling inside the vetted tree, where anything beside the files gets
+inventoried: import litter by the pipeline's own rule, carrying a name
+only the `(repaired)` suffix apart from the original, so a later driver
+pointed at the pre-probe filename list either missed it or
+double-handled it.
+
+- **No output path is now a probe**: the epubcheck gate runs, the
+  console lines and the `--json` record carry the full projection
+  (status, before/after counts, the structured fix breakdown), and
+  nothing is written anywhere; the repaired bytes stay in the scratch
+  workdir and vanish. On a probe the record's `output` is null and
+  `applied` stays false.
+- **Writing needs an explicit destination** (`bindery repair book.epub
+  out.epub`), and that rescue form is byte-for-byte what it was: same
+  gate, same copy-the-accepted-bytes rule, same `--force` and
+  refuse-to-overwrite-the-input guards.
+- The probe's console verdict is the record's own status vocabulary
+  (`accept:`/`equal:`/`unvalidated:`; partial keeps its established
+  PARTIAL phrasing), followed by an explicit "probe: nothing written"
+  line; a probe that would be partial still exits 0 with the record's
+  status carrying the verdict.
+- The repair `--help` text (new probe example, the output positional's
+  no-write meaning) and `--help-json`'s exit contract tell the new
+  truth; README and spec.md document both forms. The exit contract
+  itself is unchanged: 0 clean/probed/written including partial, 1
+  trouble, never 2.
+- Three pins added (643 total): the probe writes nothing on the accept
+  and partial paths, and the `equal` noop verdict is carried honestly
+  rather than dressed up as repairable.
+
 ## v0.48.2 (2026-10-06)
 
 ### The 12-agent docs audit: README/spec/CLAUDE tell the v0.48 truth

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.48.2"
+version = "0.49.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.48.2 → bindery_cli-0.49.0}/roadmap.md

@@ -42,6 +42,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | 0.46 | RSC-016 `--fix-comment-double-hyphen` (the last open repair class) and the RepairFlags dataclass | v0.46.0 |
 | 0.47 | The intake-wave batch (five open issues): the stub classifier's body-pool + image-carrier exemption, the NCName-complete `--fix-ids`, and `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr` | v0.47.0 |
 | 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
+| 0.49 | The probe form (issue #7): single-file repair without an output path runs the gate and writes nothing; writing needs an explicit DST | v0.49.0 |
 
 ## Open work
 

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/spec.md

@@ -559,6 +559,16 @@ half of the same information: consumers narrow lossy consent by fix class
 as data, never by substring-matching the rendered summary (v0.45.0; the
 phase1 payload inherits them through its per-book repair records).
 
+DST is optional, and the two forms have different write contracts. With a
+DST the verb is the rescue form: the gate-accepted bytes are written there
+(the input is never overwritten; an existing DST needs `--force`). Without
+a DST the verb is a probe: the gate runs and the record carries the
+projection (`output` null, `applied` false), and nothing is written
+anywhere, so probing a file in a vetted tree cannot litter it with a
+`(repaired).epub` sibling (the v0.48.2-and-before default, retired in
+v0.49.0; a probe that would be partial still exits 0 with `status`
+carrying the verdict).
+
 ## The Calibre plugin (Bindery Repair)
 
 Each release vendors the repair core into a Calibre plugin zip,

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/src/bindery/__init__.py

@@ -11,7 +11,7 @@ Calibre plugin built from this core.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.48.2"
+VERSION = "0.49.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/src/bindery/cli.py

@@ -420,7 +420,7 @@ class _HelpJsonAction(argparse.Action):
             "tool": "bindery",
             "version": __version__,
             "exit_contract": {
-                "0": "clean (repair: also written, including partial)",
+                "0": "clean (repair: also probed or written, including partial)",
                 "1": "library/run slices: trouble found; repair: trouble "
                 "(refused/failed/unreadable) or invocation problem; audit: "
                 "FINDINGS (the inverse contract, per spec.md); "
@@ -432,7 +432,8 @@ class _HelpJsonAction(argparse.Action):
                 "3": "audit: findings PLUS a failed --json/--tag write",
                 "130": "interrupted",
                 "per_verb": {
-                    "repair": "0 clean/written (partial writes, exit 0); "
+                    "repair": "0 clean/probed/written (a probe writes "
+                    "nothing, not even the sibling; partial writes, exit 0); "
                     "1 trouble or invocation problem; never 2",
                     "audit": "0 clean; 1 findings; 2 usage/environment; "
                     "3 findings + failed report write",
@@ -938,20 +939,21 @@ def run_repair(args) -> int:
     if not src.is_file():
         print(f"error: no such file: {src}", file=sys.stderr)
         return 1
-    dst = (
-        Path(args.output).expanduser()
-        if args.output
-        else src.with_name(f"{src.stem} (repaired).epub")
-    )
-    if dst.resolve() == src.resolve():
-        print("error: refusing to overwrite the input in place", file=sys.stderr)
-        return 1
-    if dst.exists() and not args.force:
-        print(
-            f"error: output exists: {dst} (pass --force to overwrite)",
-            file=sys.stderr,
-        )
-        return 1
+    # No output path is the probe form (issue #7): the gate runs and the
+    # report carries the projection, but nothing is written; the old
+    # implicit "(repaired).epub" sibling was import litter in a vetted tree.
+    # Writing needs an explicit destination.
+    dst = Path(args.output).expanduser() if args.output else None
+    if dst is not None:
+        if dst.resolve() == src.resolve():
+            print("error: refusing to overwrite the input in place", file=sys.stderr)
+            return 1
+        if dst.exists() and not args.force:
+            print(
+                f"error: output exists: {dst} (pass --force to overwrite)",
+                file=sys.stderr,
+            )
+            return 1
 
     def emit(record: dict) -> None:
         if getattr(args, "json_path", None):
@@ -974,7 +976,7 @@ def run_repair(args) -> int:
                 {
                     "mode": "repair",
                     "path": str(src),
-                    "output": str(dst),
+                    "output": str(dst) if dst else None,
                     "status": "error",
                     "applied": False,
                     "before": None,
@@ -990,7 +992,7 @@ def run_repair(args) -> int:
         base_record = {
             "mode": "repair",
             "path": str(src),
-            "output": str(dst),
+            "output": str(dst) if dst else None,
             "status": o.status,
             "applied": False,
             "before": _counts_dict(o.before),
@@ -1017,13 +1019,28 @@ def run_repair(args) -> int:
             )
             emit(base_record)
             return 1
+        ba = f"{o.before} -> {o.after}  " if o.before else ""
+        if dst is None:
+            # Probe: the accepted bytes stay in the scratch workdir; the JSON
+            # record and these console lines are the whole deliverable. The
+            # verdict word is the record's own status vocabulary.
+            verdict = (
+                "PARTIAL (still has fatals; needs manual work)"
+                if o.status == "partial"
+                else o.status
+            )
+            print(
+                f"{verdict}: {ba}{o.summary}\n"
+                "probe: nothing written (pass an output path to write the repaired file)"
+            )
+            emit(base_record)
+            return 0
         # Copy the exact bytes the gate accepted. Re-repairing src here would silently
         # drop the opt-in flags (--fix-ids, --reserialize, --strip-bad-attrs) and write
         # a file that differs from the one epubcheck validated.
         shutil.copyfile(work / "repaired.epub", dst)
         base_record["applied"] = True
         emit(base_record)
-        ba = f"{o.before} -> {o.after}  " if o.before else ""
         if o.status == "partial":
             # The file is a real improvement and worth writing, but calling it
             # "repaired" would read as fixed; it still will not open.
@@ -2078,13 +2095,15 @@ def build_parser() -> argparse.ArgumentParser:
 
     r = sub.add_parser(
         "repair",
-        help="repair a single EPUB to a new file",
+        help="repair a single EPUB (a probe when no output path is given)",
         usage="bindery repair [options] path [output]",
-        description="Repair one EPUB into a new file with the epubcheck-gated "
-        "core pass: the five well-formedness fixes, the NCX pipeline, and the "
-        "mimetype fix run always; every other repair is opt-in (grouped "
-        "below) and applied only when epubcheck confirms the result improved. "
-        "Never prompts. Exit codes: 0 clean or written (a PARTIAL repair "
+        description="Repair one EPUB with the epubcheck-gated core pass: the "
+        "five well-formedness fixes, the NCX pipeline, and the mimetype fix "
+        "run always; every other repair is opt-in (grouped below) and "
+        "applied only when epubcheck confirms the result improved. Without "
+        "an output path the verb is a probe: the gate runs and the report "
+        "says what would change, and nothing is written anywhere. Never "
+        "prompts. Exit codes: 0 clean, probed, or written (a PARTIAL repair "
         "writes its best output and exits 0; the --json record's status "
         "says so), 1 trouble (repair refused by the gate, epubcheck "
         "failure, or unreadable input) or invocation problem (bad args, "
@@ -2093,12 +2112,19 @@ def build_parser() -> argparse.ArgumentParser:
         epilog="examples:\n"
         "  bindery repair book.epub out.epub\n"
         "  bindery repair book.epub out.epub --all\n"
+        "  bindery repair book.epub --all --json report.json   "
+        "# probe: report only, nothing written\n"
         "  bindery repair book.epub out.epub --fix-svg-dup-ids "
         "--fix-cdata-terminator\n",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     r.add_argument("path")
-    r.add_argument("output", nargs="?")
+    r.add_argument(
+        "output",
+        nargs="?",
+        help="destination for the repaired file; omit it to probe "
+        "(report only, nothing written)",
+    )
     rc = r.add_argument_group("run control")
     rc.add_argument(
         "--force",

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/tests/test_cli.py

@@ -184,6 +184,79 @@ class TestRepairRefusesOverwrite(unittest.TestCase):
             self.assertNotEqual(dst.read_bytes(), b"precious")
 
 
+class TestRepairProbeForm(unittest.TestCase):
+    """repair without an output path is a probe (issue #7): the gate runs,
+    the record carries the projection, and nothing is written anywhere; the
+    old implicit "(repaired).epub" sibling was import litter in a vetted
+    tree."""
+
+    def test_accept_probe_writes_nothing(self):
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            jout = Path(td) / "probe.json"
+            results = [CheckResult(1, 0, 0), CheckResult(0, 0, 0)]
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.run_epubcheck", side_effect=results),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src), "--json", str(jout)])
+            data = json.loads(jout.read_text())
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub", "probe.json"])
+        self.assertEqual(data["status"], "accept")
+        self.assertFalse(data["applied"])
+        self.assertIsNone(data["output"])
+        self.assertEqual(data["after"]["fatals"], 0)
+        self.assertIn("accept:", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+    def test_equal_probe_reports_the_noop_and_writes_nothing(self):
+        # 'equal' is the gate's noop verdict (accepted, no measurable gain);
+        # the probe must carry that status, not dress it up as repairable.
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            report = RepairReport(fixes={"fix_named_entities": 1})
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.repair_epub", return_value=report),
+                mock.patch(
+                    "bindery.cli.run_epubcheck",
+                    side_effect=[CheckResult(0, 0, 0), CheckResult(0, 0, 0)],
+                ),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src)])
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub"])
+        self.assertIn("equal:", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+    def test_partial_probe_reports_and_writes_nothing(self):
+        # A probe that would be partial is still exit 0 (the verb's own
+        # contract: partial is the record's status, not a failure); the
+        # point here is that the "best output" is NOT written.
+        with tempfile.TemporaryDirectory() as td:
+            src = Path(td) / "in.epub"
+            build(src)
+            results = [CheckResult(3, 0, 0), CheckResult(1, 0, 0)]
+            out = io.StringIO()
+            with (
+                mock.patch("bindery.cli.run_epubcheck", side_effect=results),
+                redirect_stdout(out),
+            ):
+                rc = main(["repair", str(src)])
+            leftovers = sorted(p.name for p in Path(td).iterdir())
+        self.assertEqual(rc, 0)
+        self.assertEqual(leftovers, ["in.epub"])
+        self.assertIn("PARTIAL", out.getvalue())
+        self.assertIn("probe: nothing written", out.getvalue())
+
+
 class TestRepairWritesGatedBytes(unittest.TestCase):
     @unittest.skipUnless(HAVE_HTML5LIB, "html5lib not installed")
     def test_opt_in_flags_reach_the_output_file(self):

{bindery_cli-0.48.2 → bindery_cli-0.49.0}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "bindery-cli"
-version = "0.48.2"
+version = "0.49.0"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry", marker = "python_full_version >= '3.14'" },

bindery_cli-0.48.2/AGENTS.md

@@ -1 +0,0 @@
-CLAUDE.md