bindery-cli 0.47.0__tar.gz → 0.47.2__tar.gz

{bindery_cli-0.47.0 → bindery_cli-0.47.2}/CLAUDE.md

@@ -118,7 +118,9 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. 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. `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.
+- `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. `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.
 

{bindery_cli-0.47.0 → bindery_cli-0.47.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.47.0
+Version: 0.47.2
 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
@@ -203,6 +203,14 @@ vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery do
 checks the installation (see Install).
 The sections below take each in turn.
 
+Help is two-level: `bindery repair --help` (or `library --help`) lists the
+shared repair flags grouped with one-line descriptions, and
+`bindery repair --help-repairs` prints the full reference carrying every
+flag's long rationale. On a terminal both are ANSI-colored with the same
+theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
+`FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
+them.
+
 ## Auditing
 
 bindery-cli's auditing tool inspects EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.

{bindery_cli-0.47.0 → bindery_cli-0.47.2}/README.md

@@ -176,6 +176,14 @@ vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery do
 checks the installation (see Install).
 The sections below take each in turn.
 
+Help is two-level: `bindery repair --help` (or `library --help`) lists the
+shared repair flags grouped with one-line descriptions, and
+`bindery repair --help-repairs` prints the full reference carrying every
+flag's long rationale. On a terminal both are ANSI-colored with the same
+theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
+`FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
+them.
+
 ## Auditing
 
 bindery-cli's auditing tool inspects EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.

{bindery_cli-0.47.0 → bindery_cli-0.47.2}/patchnotes.md

@@ -1,5 +1,65 @@
 # bindery-cli Patch Notes
 
+## v0.47.2 (2026-10-06)
+
+### The --help-repairs reference keeps argparse's color
+
+The lattice-music lesson, landed here the same day: Python 3.14's argparse
+colors `-h` on terminals by itself, so the argparse-rendered surfaces (the
+top-level help and `-h` for every verb) kept their theme through the
+v0.47.1 restructure untouched. The one gap was the page v0.47.1 added: the
+custom-rendered `--help-repairs` reference printed plain, silently losing
+the colorization every other surface has (the exact regression
+lattice-music repaired in its 6b88a52).
+
+* The reference now paints with the exact CPython 3.14 default theme
+  (bold blue headings, magenta prog, bold cyan long options; read off real
+  3.14 output, so the page reads like the argparse-rendered `-h` beside
+  it) through a single layout path whose disabled style emits empty codes.
+* The color gate IS argparse's own detection (`_colorize.can_colorize` on
+  3.14+; plain False below 3.14, where argparse has no colorization to
+  match), so the two help levels can never disagree: verified under a pty
+  that `--help-repairs` carries the same code vocabulary as `-h` and that
+  `TERM=dumb` and `NO_COLOR` silence both, and that piped output stays
+  plain for README embedding and tests.
+* Four new tests: the theme codes, the strip invariant (colored, codes
+  stripped == plain, byte for byte), pipe safety, and gate tracking.
+  TestHelpLayout is now nine; suite: 624.
+
+## v0.47.1 (2026-10-06)
+
+### The two-level help: compact grouped --help, full --help-repairs reference
+
+The per-verb help had grown into a wall: a 16-line usage line listing all 27
+repair flags, then roughly 30 paragraph-length descriptions in one flat
+options list with the safe, structural, and lossy classes visually
+undifferentiated, and the shared set printed a third time in the top-level
+help. Flag names, semantics, and the argparse surface are untouched
+(CalibreQuarry's consent mirror drives the shipped parser); this release
+reorganizes how they are presented.
+
+* One inventory, two renderings: the repair flags now live in a single
+  table (dest, one-line short help, long reference text) that registers
+  the compact `--help` into titled argparse groups and renders
+  `--help-repairs` as the full reference with every flag's long
+  description. Structural repairs are grouped by defect class (markup and
+  nesting; references and resources; package wiring), and adding a flag
+  now means adding a table row.
+* Short usage lines replace the flag wall (`bindery repair [options] path
+  [output]`), repair and library carry examples epilogs, and the
+  top-level help becomes a verb list plus a pointer to the two levels.
+* The four lossy strips are consistently `LOSSY:`-prefixed (two of four
+  carried it before) and live in their own warning-titled section ("these
+  delete converter-injected content; accepted on a no-worse bar").
+* library's own 13 flags are grouped (run control, candidate selection,
+  backups, output and library integration) instead of one flat list.
+* `--help-repairs` is a custom argparse action, deliberately not
+  store_true, so the wiring test's repair-selection count ignores it;
+  TestHelpLayout (five tests) pins the usage lines, group titles, LOSSY
+  prefixes, reference content, and that guarantee.
+
+Tests: 620 (up from 615).
+
 ## v0.47.0 (2026-10-06)
 
 ### The intake-wave batch: five repair surfaces from five open issues

{bindery_cli-0.47.0 → bindery_cli-0.47.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.47.0"
+version = "0.47.2"
 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.47.0 → bindery_cli-0.47.2}/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.47.0"
+VERSION = "0.47.2"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402