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

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

@@ -118,7 +118,7 @@ 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 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.47.0
+Version: 0.47.1
 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

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

@@ -1,5 +1,39 @@
 # bindery-cli Patch Notes
 
+## 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.1}/pyproject.toml

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

{bindery_cli-0.47.0 → bindery_cli-0.47.1}/src/bindery/cli.py

@@ -10,6 +10,7 @@ import shutil
 import subprocess
 import sys
 import tempfile
+import textwrap
 import zipfile
 from dataclasses import dataclass, field
 from itertools import islice
@@ -1345,228 +1346,388 @@ def run_phase3(args) -> int:
     return 2 if repair_rc != 0 else 0
 
 
+# The repair-flag inventory, one table, two renderings: `_add_repair_flags`
+# registers the short one-liners into argparse argument groups (the compact
+# `--help`), and `--help-repairs` renders the long descriptions as the full
+# reference. Adding a flag means adding a row here; the dests below are the
+# contract tests/test_flags_wiring.py pins.
+# Row shape: (dest, short one-liner, long reference text).
+_REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
+    "safe opt-ins (markup-neutral)": [
+        (
+            "fix_ids",
+            "rewrite invalid OPF/NCX ids (RSC-005), every reference in sync",
+            "rewrite ids that are not valid XML names (digit-led, colon-bearing, "
+            "or carrying any character outside the XML NameChar set, like the "
+            "apostrophes calibre copies from filenames) in the OPF manifest and "
+            "the NCX, updating every reference to them (spine idref, spine toc, "
+            "item fallback, media-overlay, the EPUB 2 cover meta). The dc: "
+            "metadata is never altered.",
+        ),
+        (
+            "add_img_alt",
+            'add alt="" to <img> elements missing the required attribute',
+            'add alt="" to <img> elements missing the required attribute. '
+            "Renders identically, but it adds markup the author never wrote, and "
+            'an empty alt asserts "decorative" to a screen reader where a '
+            "missing alt did not; hence opt-in.",
+        ),
+        (
+            "reserialize",
+            "rebuild still-malformed documents via html5lib",
+            "rebuild content documents that are still malformed by re-parsing "
+            "them with html5lib and re-emitting XHTML, closing unclosed non-void "
+            "elements the regex transforms cannot. Runs only on documents that "
+            "are not already well-formed, so good files are untouched.",
+        ),
+        (
+            "strip_bad_attrs",
+            "drop invalid attributes (digit-led names, unbound prefixes)",
+            "drop attributes that make the XML unparseable: a name starting "
+            'with a digit (a mangled 31="") or a namespaced name whose prefix '
+            "is not declared anywhere in the document (Office VML v:shapes). "
+            "Surgical and a no-op on well-formed files.",
+        ),
+        (
+            "escape_unknown_entities",
+            "&foo; -> &amp;foo; for names outside the HTML5 table",
+            "escape entity names outside the HTML5 table, which renders exactly "
+            "as browsers already render an unknown entity. Documents whose "
+            "DOCTYPE carries an internal subset (which can declare custom "
+            "entities) are skipped wholesale.",
+        ),
+    ],
+    "structural repairs: markup and nesting": [
+        (
+            "fix_empty_body",
+            "append &nbsp; to a strictly empty <body></body>",
+            "append &nbsp; inside a strictly empty <body></body> (the 'body "
+            "incomplete' error). Adds visible content the author never wrote; "
+            "hence opt-in.",
+        ),
+        (
+            "fix_missing_title",
+            "inject <title>Unknown</title> when the head has none",
+            "inject a <title>Unknown</title> fallback when the head has no "
+            "usable title: an empty <title/> is filled in, an absent tag is "
+            "added to the head.",
+        ),
+        (
+            "fix_id_colons",
+            'id="X:Y" colons and matching #X:Y fragments become underscores',
+            'translate illegal colons in id="X:Y" and their matching internal '
+            "#X:Y fragment references to underscores, so a ToC never dangles "
+            "against the ids it references (the NCX's content src fragments "
+            "follow the rename). Only the bare id attribute is in scope; the "
+            "fragment of an external URL names a position in that other "
+            "document and survives verbatim.",
+        ),
+        (
+            "unwrap_block_in_inline",
+            "unwrap a <span> illegally wrapping a block element",
+            "unwrap a <span> that illegally wraps a block element "
+            "(<div>/<p>/<blockquote>), keeping the block element and its text.",
+        ),
+        (
+            "strip_invalid_value",
+            "strip misplaced value= attributes from non-form elements",
+            'strip misplaced value="..." attributes from elements like <div>, '
+            "<span>, <p> where they are schema violations.",
+        ),
+        (
+            "unwrap_illegal_tags",
+            "delete illegal tags (<st>, <w>...) keeping text; styled names safe",
+            "delete illegal/deprecated tags (<st>, <sentence>, <o>, <w>, "
+            "<pagebreak>) while keeping their inner text. Any of those names a "
+            "stylesheet styles as an element selector (class/id selectors do "
+            "not count) is protected book-wide, so styled formatting is never "
+            "destroyed.",
+        ),
+        (
+            "strip_epub3_attrs",
+            "scrub EPUB3-only attributes an EPUB2 package rejects (fixed set)",
+            "scrub the EPUB3-only attributes epubcheck rejects on an EPUB2 "
+            "package: page-progression-direction, epub:type, aria-label (a "
+            "fixed, documented set; rendering is unchanged). Gated on the "
+            "package version: inert on EPUB 3 books.",
+        ),
+        (
+            "downgrade_epub3_tags",
+            "figure/section to div, figcaption to p; semantic name kept as class",
+            "downgrade EPUB3/HTML5 semantic elements to EPUB2 equivalents "
+            "(figure/section to div, figcaption to p), keeping existing classes "
+            "and appending the semantic name as the styling hook. Names a "
+            "stylesheet styles as an element selector are protected book-wide. "
+            "Gated on the package version: inert on EPUB 3 books.",
+        ),
+        (
+            "fix_misnested_inline",
+            "rewrite the drop-cap mis-nest <i><b>X</i></b> to <i><b>X</b></i>",
+            "rewrite the Mobipocket drop-cap mis-nest <i><b>X</i></b> to "
+            "<i><b>X</b></i> (em/strong variants, either tag order): the unique "
+            "well-formed form of the same two spans. A punctuation run caught "
+            "between the reversed closers (<i><b>xile</i>,</b>) survives "
+            "outside both spans; a letter run there is refused (which span "
+            "keeps the letters has no deterministic answer).",
+        ),
+        (
+            "fix_stray_close",
+            "remove end tags whose element has no open start (stray </div>)",
+            "remove an end tag whose element has no open start tag anywhere "
+            "above it (the stray extra </div> on a shell page, which cascades "
+            "into 'body must be terminated by the matching end-tag'). A merely "
+            "mis-nested pair (<div><span></div></span>) is never touched: a "
+            "close is removed only when nothing by that name is open.",
+        ),
+        (
+            "fix_unterminated_attr",
+            "close attribute values open to the tag's own '>' (RSC-016)",
+            "close an attribute value left open to the tag's own '>' "
+            '(<p class="footnote> -> <p class="footnote">): the parser '
+            "swallows prose into the value until the next quote and dies on the "
+            "first '<' it meets. Guards keep it off legal >-bearing values: "
+            "bare-word values only, and no quote may close before the next '<'.",
+        ),
+        (
+            "fix_cdata_terminator",
+            "complete truncated /*]]> closers in inline <style> blocks (CSS-008)",
+            "complete a truncated CDATA-terminator comment in an inline <style> "
+            "block: /*]]> becomes /*]]>*/. A comment-wrapped CDATA block whose "
+            "closing */ the converter dropped leaves the CSS parser inside an "
+            "unterminated comment: one CSS-008 'Premature end of file' per "
+            "affected document. Only the malformed-terminator token class; "
+            "invalid CSS stays unfixed, and stylesheet files are not touched.",
+        ),
+    ],
+    "structural repairs: references and resources": [
+        (
+            "fix_page_map",
+            'drop the OPF page-map attribute; class="pages" on NCX pageLists',
+            "normalize legacy page-map markup: drop the non-standard page-map "
+            'attribute from the OPF <spine> and add class="pages" to classless '
+            "NCX <pageList> elements (epubcheck rejects both on older "
+            "HarperCollins / Anna's Archive conversions).",
+        ),
+        (
+            "prune_missing_resources",
+            "remove references to files the archive does not contain (RSC-007)",
+            "remove references to files the archive does not contain "
+            "(RSC-007/PKG-010): dead <link> elements, anchors' href to absent "
+            "files (anchor text preserved), absent <img> sources (replaced by "
+            "their alt text when they carry one), and orphaned non-spine OPF "
+            "manifest items, with every package edge that pointed at them "
+            "rewritten. Spine documents are never pruned: a missing spine "
+            "document is reported as a damaged fragment, not silently dropped.",
+        ),
+        (
+            "strip_broken_anchors",
+            "strip hrefs that cannot resolve; anchor text always preserved",
+            "strip href attributes that cannot resolve, keeping the anchor text "
+            "byte-for-byte: a #fragment the target document does not define "
+            "(RSC-020/RSC-012; NCX navTargets keep the document target, so "
+            "chapter navigation survives) and unresolvable URI schemes "
+            "(kindle:, file:).",
+        ),
+        (
+            "encode_url_spaces",
+            "encode raw spaces in URLs; rename space-bearing entries (PKG-010)",
+            "repair raw-space URLs two ways: percent-encode raw spaces in "
+            "src/href attribute values across the package (a literal space is "
+            "not a valid URL, RSC-020), and rename the archive entries whose "
+            "names carry raw spaces to their underscore spellings, rewriting "
+            "every reference to them (underscore, never percent-encoding: "
+            "epubcheck decodes references before entry lookup). Accepted under "
+            "the no-worse bar: the rename half's gain sits on the warning axis.",
+        ),
+        (
+            "fix_svg_dup_ids",
+            "rename duplicate glyph ids in .svg entries (first keeps its name)",
+            "rename duplicate id values inside standalone .svg entries (old "
+            "calibre SVG page renders repeat glyph ids within one document; the "
+            "intake wave that found this carried 445 to 1,339 'Duplicate "
+            '"glNNNN"\' errors per book). The first occurrence keeps its name, '
+            "later ones gain _2/_3, and internal references are deliberately "
+            "untouched: they already resolve to the first definition under "
+            "every reader's first-match lookup. Content-document ids are styled "
+            "by CSS selectors and targeted by anchors; they stay out of scope.",
+        ),
+    ],
+    "structural repairs: package wiring": [
+        (
+            "fix_container",
+            "generate container.xml when missing or stale (the gateway defect)",
+            "generate META-INF/container.xml at the located OPF when the "
+            "container is missing or names a file the archive does not contain. "
+            "This is the gateway defect: epubcheck stays fatal while the OPF is "
+            "unfindable, so no repair can be gate-accepted on such a book until "
+            "the container exists.",
+        ),
+        (
+            "fix_media_types",
+            "normalize wrong manifest media-types (magic-byte confirmed)",
+            "normalize wrong manifest media-type declarations (OPF-029, e.g. a "
+            "jpg stamped image/png by an aggregator). Attribute-only and "
+            "quote-preserving; it fires only when the file's magic bytes "
+            "confirm the extension, so a misnamed-but-consistent file is never "
+            "made worse.",
+        ),
+        (
+            "fix_cover",
+            "re-point or remove a dangling EPUB2 cover meta (no-worse bar)",
+            'repair dangling EPUB2 cover wiring: a <meta name="cover"> whose '
+            "content names no manifest item is re-pointed when the OPF guide's "
+            "own cover reference names an existing item, and removed when "
+            'nothing identifies it. EPUB3 properties="cover-image" is '
+            "deliberately audit-only (guessing which image is the cover is not "
+            "deterministic). Cover wiring is invisible to epubcheck, so "
+            "cover-only repairs are accepted under the same no-worse bar the "
+            "lossy strips use.",
+        ),
+        (
+            "fix_comment_double_hyphen",
+            "replace -- inside XML comments with an en-dash (RSC-016)",
+            "replace -- sequences inside XML comments with en-dashes. -- is "
+            "illegal inside an XML comment (epubcheck fatal RSC-016: the book "
+            "opens in lenient readers but never passes epubcheck). The edit "
+            "stays inside the comment bodies: text nodes and CDATA sections are "
+            "never touched, and each comment's terminator is left intact.",
+        ),
+    ],
+    "lossy strips (these delete converter-injected content; accepted on a no-worse bar)": [
+        (
+            "strip_pagination",
+            "LOSSY: page numbers/running heads baked into the body text",
+            "remove print page numbers and running headers that a PDF/OCR "
+            "conversion baked into the body text as literal paragraphs (so they "
+            "reflow into the middle of a sentence). It removes only that "
+            "injected furniture, never the author's prose: where a number split "
+            "a sentence it rejoins the two paragraphs, and it preserves roman "
+            "chapter numbers, page-list nav anchors, and years. Three safety "
+            "nets guard every edit (character conservation, tag balance, and "
+            "the epubcheck no-regression check); any failure leaves the "
+            "document untouched.",
+        ),
+        (
+            "strip_broken_tags",
+            "LOSSY: leaked close tags rendered as text (</p> without <)",
+            "remove leaked HTML closing tags missing their open brackets (e.g. "
+            "</p> rendered as raw text in the reader).",
+        ),
+        (
+            "strip_watermarks",
+            "LOSSY: producer stamps (OceanofPDF ...) and marker files",
+            "remove known producer and distributor watermarks and stray marker "
+            "files. It locates the stamp and deletes the outermost wrapper "
+            "whose entire visible text is the watermark, so prose that merely "
+            "mentions the URL is preserved. An inline stamp link is deleted "
+            "only when it holds nothing but the stamp; a match too large to be "
+            "safe is refused and reported for manual repair rather than "
+            "deleted.",
+        ),
+        (
+            "strip_stub_docs",
+            "LOSSY: repeated placeholder spine docs, full manifest/NCX cascade",
+            "drop spine documents whose entire visible body text is one "
+            "identical short placeholder repeated across the spine: the "
+            "Bookmate-style export whose chapters are all the same 'content "
+            "unavailable' notice. The drop cascades (archive entries, manifest "
+            "items, spine order, NCX navPoints, nav toc entries), so the book "
+            "opens straight into its real chapters. Deliberately conservative "
+            "(the pool is the <body> span, image-carrier divider pages are "
+            "exempt) and a book whose every spine doc is the stub is refused "
+            "outright: that book is empty and needs a re-source, never a "
+            "repair.",
+        ),
+    ],
+}
+
+
+class _HelpRepairsAction(argparse.Action):
+    """The second help level: print the full repair-flag reference and exit.
+
+    Deliberately NOT a store_true action: tests/test_flags_wiring.py counts
+    every store_true dest in _add_repair_flags as a repair selection, and
+    this is a help affordance like -h, not a selection."""
+
+    def __init__(
+        self,
+        option_strings,
+        dest=argparse.SUPPRESS,
+        default=argparse.SUPPRESS,
+        help=None,
+    ):
+        super().__init__(
+            option_strings=option_strings,
+            dest=dest,
+            default=default,
+            nargs=0,
+            help=help,
+        )
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        lines = [
+            "bindery repair-flag reference (shared by `bindery repair` and "
+            "`bindery library`)",
+            "",
+            "The always-on core pass is exactly five well-formedness fixes, the NCX",
+            "pipeline, and the mimetype fix. Everything below is opt-in, and every",
+            "repair is epubcheck-gated: applied only when the measured result improved",
+            "(lossy strips: only when it did not get worse). Library mode is dry-run",
+            "by default; `--all` enables every flag below at once. The README and",
+            "spec.md carry the full rationale for each repair.",
+        ]
+        for title, rows in _REPAIR_FLAG_TABLE.items():
+            lines.append("")
+            lines.append(title)
+            lines.append("")
+            for dest, _short, long_help in rows:
+                option = "--" + dest.replace("_", "-")
+                lines.append(f"  {option}")
+                for para in long_help.split("\n"):
+                    lines.extend(
+                        textwrap.wrap(
+                            para,
+                            width=88,
+                            initial_indent="      ",
+                            subsequent_indent="      ",
+                        )
+                        or ["     "]
+                    )
+        print("\n".join(lines))
+        parser.exit(0)
+
+
 def _add_repair_flags(p: argparse.ArgumentParser) -> None:
-    """The fix-selection and gate flags shared by both subcommands."""
-    p.add_argument(
-        "--fix-ids",
-        action="store_true",
-        help="also rewrite invalid ids in the OPF manifest and the NCX (RSC-005)",
-    )
-    p.add_argument(
-        "--add-img-alt",
-        action="store_true",
-        help='add alt="" to <img> elements missing the required attribute '
-        "(renders identically; asserts 'decorative' to screen readers)",
-    )
-    p.add_argument(
-        "--reserialize",
-        action="store_true",
-        help="rebuild still-malformed documents via html5lib (closes unclosed elements)",
-    )
-    p.add_argument(
-        "--strip-bad-attrs",
-        action="store_true",
-        help="drop invalid attributes (digit-led names, unbound namespace prefixes)",
-    )
-    p.add_argument(
-        "--escape-unknown-entities",
-        action="store_true",
-        help="escape entity names outside the HTML5 table (&foo; -> &amp;foo;), "
-        "rendering as browsers already render them; documents with a DOCTYPE "
-        "internal subset (which can declare custom entities) are skipped",
-    )
-    p.add_argument(
-        "--fix-empty-body",
-        action="store_true",
-        help="append &nbsp; to a strictly empty <body></body> (adds visible "
-        "content; hence opt-in)",
-    )
-    p.add_argument(
-        "--fix-missing-title",
-        action="store_true",
-        help="inject a <title>Unknown</title> fallback when the head has none",
-    )
-    p.add_argument(
-        "--fix-id-colons",
-        action="store_true",
-        help='translate illegal colons in id="X:Y" and their matching #X:Y '
-        "fragment references to underscores",
-    )
-    p.add_argument(
-        "--unwrap-block-in-inline",
-        action="store_true",
-        help="unwrap a <span> that illegally wraps a block element (<div>/<p>/"
-        "<blockquote>), keeping the block and its text",
-    )
-    p.add_argument(
-        "--strip-invalid-value",
-        action="store_true",
-        help='strip misplaced value="..." attributes from non-form elements',
-    )
-    p.add_argument(
-        "--unwrap-illegal-tags",
-        action="store_true",
-        help="delete illegal/deprecated tags (<st>, <sentence>, <o>, <w>, "
-        "<pagebreak>) keeping inner text; any tag a stylesheet styles as an "
-        "element selector is protected book-wide",
-    )
-    p.add_argument(
-        "--fix-page-map",
-        dest="fix_page_map",
-        action="store_true",
-        help="normalize legacy page-map markup: drop the non-standard page-map "
-        'attribute from the OPF spine and add class="pages" to classless NCX '
-        "<pageList> elements (epubcheck rejects both)",
-    )
-    p.add_argument(
-        "--strip-epub3-attrs",
-        dest="strip_epub3_attrs",
-        action="store_true",
-        help="scrub the EPUB3-only attributes epubcheck rejects on an EPUB2 "
-        "package (page-progression-direction, epub:type, aria-label; fixed set)",
-    )
-    p.add_argument(
-        "--downgrade-epub3-tags",
-        dest="downgrade_epub3_tags",
-        action="store_true",
-        help="downgrade EPUB3/HTML5 semantic elements to EPUB2 equivalents "
-        "(figure/section to div, figcaption to p; semantic name kept as a "
-        "class; names a stylesheet styles as an element selector are "
-        "protected book-wide)",
-    )
-    p.add_argument(
-        "--prune-missing-resources",
-        dest="prune_missing_resources",
-        action="store_true",
-        help="remove references to files the archive does not contain "
-        "(RSC-007/PKG-010): dead <link> elements, anchors' href to absent "
-        "files, absent <img> sources (replaced by their alt text when they "
-        "carry one), and orphaned non-spine OPF manifest items; spine "
-        "documents are never pruned",
-    )
-    p.add_argument(
-        "--strip-broken-anchors",
-        dest="strip_broken_anchors",
-        action="store_true",
-        help="strip href attributes that cannot resolve: a #fragment the "
-        "target document does not define (RSC-020/RSC-012; NCX navTargets "
-        "keep the document target) and non-resolvable URI schemes (kindle:, "
-        "file:); anchor text is always preserved",
-    )
-    p.add_argument(
-        "--encode-url-spaces",
-        dest="encode_url_spaces",
-        action="store_true",
-        help="percent-encode raw spaces in src/href attribute values across "
-        "the package (OPF href, NCX src, content docs): a literal space is "
-        "not a valid URL (RSC-020)",
-    )
-    p.add_argument(
-        "--fix-container",
-        dest="fix_container",
-        action="store_true",
-        help="generate META-INF/container.xml at the located OPF when the "
-        "container is missing or names a file the archive does not contain "
-        "(the gateway defect: epubcheck stays fatal while the OPF is "
-        "unfindable)",
-    )
-    p.add_argument(
-        "--fix-media-types",
-        dest="fix_media_types",
-        action="store_true",
-        help="normalize wrong manifest media-type declarations (OPF-029): "
-        "attribute-only, fired only when the file's magic bytes confirm the "
-        "extension (jpg/png/gif)",
-    )
-    p.add_argument(
-        "--fix-cover",
-        dest="fix_cover",
-        action="store_true",
-        help='repair dangling EPUB2 cover wiring: re-point <meta name="cover"> '
-        "from the guide's cover reference when that names an existing manifest "
-        "item, remove the dead meta when nothing does; EPUB3 "
-        'properties="cover-image" is audit-only by ruling',
-    )
-    p.add_argument(
-        "--fix-comment-double-hyphen",
-        dest="fix_comment_double_hyphen",
-        action="store_true",
-        help="replace `--` inside XML comments with an en-dash (RSC-016: "
-        "`--` is not permitted within comments); comment bodies only, "
-        "CDATA never touched",
-    )
-    p.add_argument(
-        "--fix-svg-dup-ids",
-        dest="fix_svg_dup_ids",
-        action="store_true",
-        help="rename duplicate id values inside standalone .svg entries "
-        "(old calibre SVG page renders, RSC-005 'Duplicate \"glNNNN\"'): "
-        "first occurrence keeps its name, later ones gain _2/_3; "
-        "references need no rewrite (they resolve to the first definition)",
-    )
-    p.add_argument(
-        "--fix-cdata-terminator",
-        dest="fix_cdata_terminator",
-        action="store_true",
-        help="complete a truncated CDATA-terminator comment in an inline "
-        "<style> block (/*]]> -> /*]]>*/; the CSS-008 'Premature end of "
-        "file' class, one error per affected document)",
-    )
-    p.add_argument(
-        "--fix-misnested-inline",
-        dest="fix_misnested_inline",
-        action="store_true",
-        help="rewrite the drop-cap mis-nest <i><b>X</i></b> to "
-        "<i><b>X</b></i> (em/strong variants, either tag order): the "
-        "unique well-formed form of the same two spans",
-    )
-    p.add_argument(
-        "--fix-stray-close",
-        dest="fix_stray_close",
-        action="store_true",
-        help="remove an end tag whose element has no open start tag (the "
-        "stray extra </div> that cascades into 'body must be terminated "
-        "by the matching end-tag'); mis-nested-but-open pairs never touched",
-    )
-    p.add_argument(
-        "--fix-unterminated-attr",
-        dest="fix_unterminated_attr",
-        action="store_true",
-        help="close an attribute value left open to the tag's own '>' "
-        '(<p class="footnote> -> <p class="footnote">; the RSC-016 '
-        "'must not contain the < character' fatal)",
-    )
-    p.add_argument(
-        "--strip-pagination",
-        action="store_true",
-        help="LOSSY: remove print page numbers/running headers baked into the body "
-        "text by a bad conversion, rejoining sentences they split (epubcheck-gated, "
-        "accepted when no worse)",
-    )
-    p.add_argument(
-        "--strip-broken-tags",
-        action="store_true",
-        help="LOSSY: remove leaked HTML closing tags missing their open bracket (e.g. </p> rendered as text) (epubcheck-gated)",
-    )
-    p.add_argument(
-        "--strip-watermarks",
+    """The fix-selection and gate flags shared by both subcommands,
+    registered from _REPAIR_FLAG_TABLE into titled groups (the compact
+    --help); --help-repairs prints the same inventory with the long
+    descriptions."""
+    for title, rows in _REPAIR_FLAG_TABLE.items():
+        g = p.add_argument_group(title)
+        for dest, short, _long in rows:
+            g.add_argument(
+                "--" + dest.replace("_", "-"),
+                dest=dest,
+                action="store_true",
+                help=short,
+            )
+    g = p.add_argument_group("gate and selection")
+    g.add_argument(
+        "--all",
         action="store_true",
-        help="remove known producer/distributor watermarks and stray marker files",
+        help="enable every opt-in fix flag (safe, structural, and lossy)",
     )
-    p.add_argument(
-        "--strip-stub-docs",
+    g.add_argument(
+        "--no-validate",
         action="store_true",
-        help="drop spine docs whose entire text is one identical short "
-        "placeholder repeated across the spine (Bookmate/DRM-sample exports); "
-        "manifest/NCX/nav cascade; refuses a book whose whole spine is stubs",
+        help="skip the epubcheck gate",
     )
     p.add_argument(
-        "--all",
-        action="store_true",
-        help="enable every opt-in fix flag (the safe structural repairs above "
-        "and all lossy strips)",
+        "--help-repairs",
+        action=_HelpRepairsAction,
+        help="print the full repair-flag reference (every flag's long "
+        "description, grouped) and exit",
     )
-    p.add_argument("--no-validate", action="store_true", help="skip the epubcheck gate")
 
 
 def run_audit_cmd(args: argparse.Namespace) -> int:
@@ -1632,38 +1793,42 @@ def run_audit_cmd(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    # Generate an attractive, perfectly aligned help block for the shared flags
-    dummy = argparse.ArgumentParser(add_help=False, usage=argparse.SUPPRESS)
-    group = dummy.add_argument_group(
-        "shared fix flags (can be passed to either repair or library)"
-    )
-    _add_repair_flags(group)
-    lib_group = dummy.add_argument_group("library-specific integration")
-    lib_group.add_argument(
-        "--install-to-calibre",
-        action="store_true",
-        help="with --apply, re-register the format natively in metadata.db through cquarry's write module (remove + add in one transaction) instead of a bare filesystem replace",
-    )
-    shared_help = dummy.format_help().strip()
-
     ap = argparse.ArgumentParser(
         prog="bindery",
         description="Repair EPUBs, epubcheck-gated.",
-        epilog=shared_help,
+        epilog="both `repair` and `library` accept the same opt-in repair-flag\n"
+        "set (--all enables every one): `bindery repair --help` lists them\n"
+        "grouped, and `bindery repair --help-repairs` prints the full\n"
+        "reference.",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     ap.add_argument("--version", action="version", version=f"bindery {__version__}")
     sub = ap.add_subparsers(dest="cmd", required=True)
 
-    r = sub.add_parser("repair", help="repair a single EPUB to a new file")
+    r = sub.add_parser(
+        "repair",
+        help="repair a single EPUB to a new file",
+        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.",
+        epilog="examples:\n"
+        "  bindery repair book.epub out.epub\n"
+        "  bindery repair book.epub out.epub --all\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(
+    rc = r.add_argument_group("run control")
+    rc.add_argument(
         "--force",
         action="store_true",
         help="overwrite the output file if it already exists",
     )
-    r.add_argument(
+    rc.add_argument(
         "--json",
         dest="json_path",
         metavar="FILE",
@@ -1748,58 +1913,76 @@ def build_parser() -> argparse.ArgumentParser:
     )
     audit.set_defaults(func=run_audit_cmd)
 
-    lib = sub.add_parser("library", help="scan/repair a Calibre library tree")
+    lib = sub.add_parser(
+        "library",
+        help="scan/repair a Calibre library tree",
+        usage="bindery library [options] path",
+        description="Scan a Calibre library tree for repair candidates and "
+        "repair them in place. Dry run by default; --apply atomically "
+        "replaces accepted books. Shares the repair-flag set with `bindery "
+        "repair` (--all enables every opt-in).",
+        epilog="examples:\n"
+        "  bindery library ~/docs/Calibre\\ Library --sweep\n"
+        "  bindery library ~/docs/Calibre\\ Library --id 1234 --apply "
+        "--backup /tmp/bindery-backups --install-to-calibre\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     lib.add_argument("path")
-    lib.add_argument(
+    rc = lib.add_argument_group("run control")
+    rc.add_argument(
         "--apply",
         action="store_true",
         help="atomically replace accepted books in place (default: dry run)",
     )
-    lib.add_argument(
+    rc.add_argument(
         "--only",
         choices=("fatals", "ncx", "all"),
         default="all",
         help="restrict to books with fatals, NCX-001 mismatch, or all (default)",
     )
-    lib.add_argument(
-        "--audit", help="audit CSV (fatals,errors,warnings,path) to filter candidates"
-    )
-    lib.add_argument(
-        "--sweep",
-        action="store_true",
-        help="select candidates via a live epubcheck sweep instead of an --audit CSV "
-        "(each sweep result doubles as that book's 'before' measurement)",
+    rc.add_argument(
+        "--limit", type=int, help="process at most N candidates (for sampling)"
     )
-    lib.add_argument(
-        "--json",
-        metavar="FILE",
-        help="write a machine-readable JSON report of the run to FILE",
+    rc.add_argument(
+        "--workers",
+        type=int,
+        default=1,
+        metavar="N",
+        help="concurrent epubcheck workers for the --sweep candidate pass "
+        "(default 1: serial, unchanged). The repair phase stays serial",
     )
-    lib.add_argument(
-        "--manual-list",
-        metavar="FILE",
-        help="write the paths of books that were not auto-repaired "
-        "(nochange/equal/partial/reject/error/unreadable), one per line",
+    rc.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress the per-book progress line on stderr",
     )
-    lib.add_argument(
-        "--install-to-calibre",
+    cs = lib.add_argument_group("candidate selection")
+    cs.add_argument(
+        "--sweep",
         action="store_true",
-        help="with --apply, re-register the format natively in metadata.db through cquarry's write module (remove + add in one transaction) instead of a bare filesystem replace",
+        help="select candidates via a live epubcheck sweep instead of an "
+        "--audit CSV (each sweep result doubles as that book's 'before' "
+        "measurement)",
     )
-    lib.add_argument(
+    cs.add_argument(
+        "--audit", help="audit CSV (fatals,errors,warnings,path) to filter candidates"
+    )
+    cs.add_argument(
         "--id",
         default="",
         metavar="IDS",
         help="comma-separated Calibre book ids to scope the sweep to "
-        "(resolved via cquarry's get_format_path; mutually exclusive with --audit)",
+        "(resolved via cquarry's get_format_path; mutually exclusive with "
+        "--audit)",
     )
-    lib.add_argument("--backup", help="directory to mirror backups into before --apply")
-    lib.add_argument(
+    bk = lib.add_argument_group("backups")
+    bk.add_argument("--backup", help="directory to mirror backups into before --apply")
+    bk.add_argument(
         "--backup-inplace",
         action="store_true",
         help="with --apply, write a .epub.bak beside each replaced file",
     )
-    lib.add_argument(
+    bk.add_argument(
         "--backup-keep",
         type=int,
         metavar="N",
@@ -1807,21 +1990,24 @@ def build_parser() -> argparse.ArgumentParser:
         "(minimum 2; the author original .bak is never deleted). Opt-in: "
         "without it the rotation grows unbounded",
     )
-    lib.add_argument(
-        "--limit", type=int, help="process at most N candidates (for sampling)"
+    out = lib.add_argument_group("output and library integration")
+    out.add_argument(
+        "--json",
+        metavar="FILE",
+        help="write a machine-readable JSON report of the run to FILE",
     )
-    lib.add_argument(
-        "--workers",
-        type=int,
-        default=1,
-        metavar="N",
-        help="concurrent epubcheck workers for the --sweep candidate pass "
-        "(default 1: serial, unchanged). The repair phase stays serial",
+    out.add_argument(
+        "--manual-list",
+        metavar="FILE",
+        help="write the paths of books that were not auto-repaired "
+        "(nochange/equal/partial/reject/error/unreadable), one per line",
     )
-    lib.add_argument(
-        "--quiet",
+    out.add_argument(
+        "--install-to-calibre",
         action="store_true",
-        help="suppress the per-book progress line on stderr",
+        help="with --apply, re-register the format natively in metadata.db "
+        "through cquarry's write module (remove + add in one transaction) "
+        "instead of a bare filesystem replace",
     )
     _add_repair_flags(lib)
     lib.set_defaults(func=run_library)

{bindery_cli-0.47.0 → bindery_cli-0.47.1}/tests/test_cli.py

@@ -4,6 +4,7 @@ the single-file repair must write the exact bytes the gate accepted (flags inclu
 and label partial output honestly, and candidate selection must refuse --only fatals
 without an audit."""
 
+import argparse
 import contextlib
 import io
 import json
@@ -1792,3 +1793,84 @@ class TestStripStubDocsGate(unittest.TestCase):
     def test_regression_rejects(self) -> None:
         o = self._strip_verdict(CheckResult(0, 1, 0), CheckResult(0, 2, 0))
         self.assertEqual(o.status, "reject")
+
+
+class TestHelpLayout(unittest.TestCase):
+    """The two-level help contract (the 2026-10-06 restructure): the compact
+    --help is grouped with one-line flags and a short usage line, and
+    --help-repairs prints the full reference carrying every flag's long
+    description. The flag surface itself is pinned by test_flags_wiring; this
+    module pins the presentation."""
+
+    def _subparser(self, name):
+        parser = build_parser()
+        for a in parser._actions:
+            if isinstance(a, argparse._SubParsersAction):
+                return a.choices[name]
+        self.fail("no subparsers on build_parser()")
+
+    def _format(self, name):
+        return self._subparser(name).format_help()
+
+    def test_usage_line_is_short(self):
+        for verb, tail_ in (
+            ("repair", "[options] path [output]"),
+            ("library", "[options] path"),
+        ):
+            usage = self._format(verb).splitlines()[0]
+            self.assertEqual(usage, f"usage: bindery {verb} {tail_}", verb)
+
+    def test_compact_help_groups_every_flag_once(self):
+        from bindery.cli import _REPAIR_FLAG_TABLE
+
+        for verb in ("repair", "library"):
+            text = self._format(verb)
+            self.assertIn(
+                "lossy strips (these delete converter-injected content; "
+                "accepted on a no-worse bar)",
+                text,
+                verb,
+            )
+            for rows in _REPAIR_FLAG_TABLE.values():
+                for dest, _short, _long in rows:
+                    option = "--" + dest.replace("_", "-")
+                    self.assertIn(option, text, f"{verb}: {option}")
+
+    def test_lossy_flags_carry_the_prefix(self):
+        from bindery.cli import _REPAIR_FLAG_TABLE
+
+        text = self._format("repair")
+        for dest, short, _long in _REPAIR_FLAG_TABLE[
+            "lossy strips (these delete converter-injected content; "
+            "accepted on a no-worse bar)"
+        ]:
+            self.assertTrue(short.startswith("LOSSY:"), dest)
+            # the one-liner must survive into the rendered help intact
+            self.assertIn(short.split(":")[0] + ":", text)
+
+    def test_help_repairs_prints_the_full_reference(self):
+        from bindery.cli import _REPAIR_FLAG_TABLE
+
+        for verb in ("repair", "library"):
+            buf = io.StringIO()
+            with self.assertRaises(SystemExit) as cm, contextlib.redirect_stdout(buf):
+                main([verb, "--help-repairs"])
+            self.assertEqual(cm.exception.code, 0, verb)
+            text = buf.getvalue()
+            for rows in _REPAIR_FLAG_TABLE.values():
+                for dest, _short, _long in rows:
+                    self.assertIn(
+                        "--" + dest.replace("_", "-"), text, f"{verb}: {dest}"
+                    )
+            # long-text sentinels from two different groups
+            self.assertIn("XML NameChar set", text, verb)
+            self.assertIn("no-worse", text, verb)
+
+    def test_help_repairs_is_not_a_selection_flag(self):
+        # _HelpRepairsAction is deliberately not a store_true: the wiring
+        # test counts store_true dests as repair selections
+        from argparse import _StoreTrueAction
+
+        p = self._subparser("repair")
+        dests = {a.dest for a in p._actions if isinstance(a, _StoreTrueAction)}
+        self.assertNotIn("help_repairs", dests)

{bindery_cli-0.47.0 → bindery_cli-0.47.1}/uv.lock

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