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

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

@@ -30,15 +30,27 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
   mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
   fix must render identically to the author's intent: never add, remove, or reorder
-  visible content. The canonical opt-in inventory lives in spec.md: sixteen structural
+  visible content. The canonical opt-in inventory lives in spec.md: twenty-one structural
   repairs, four lossy strips, four safe opt-ins, plus `--reserialize`.
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
     `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
     `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
     `--fix-container`, `--fix-media-types`, `--fix-cover`,
-    `--fix-comment-double-hyphen`; transforms.py, threaded
-    through epub.py). `--fix-comment-double-hyphen` (v0.46.0, the RSC-016 fatal)
+    `--fix-comment-double-hyphen`, `--fix-svg-dup-ids`, `--fix-cdata-terminator`,
+    `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr`;
+    transforms.py, threaded through epub.py). The v0.47.0 five (the 2026-10-06
+    issue batch): `--fix-svg-dup-ids` renames duplicate glyph ids inside
+    standalone `.svg` entries (first keeps its name, references resolve to the
+    first definition so they are never rewritten); `--fix-cdata-terminator`
+    completes a truncated `/*]]>` CDATA-terminator comment inside inline
+    `<style>` blocks (CSS-008); `--fix-misnested-inline` normalizes the
+    Mobipocket drop-cap mis-nest `<i><b>X</i></b>` (punctuation between the
+    reversed closers survives outside both spans; a letter run is refused);
+    `--fix-stray-close` removes an end tag with no open start frame (a merely
+    mis-nested pair is never touched); `--fix-unterminated-attr` closes an
+    attribute value open to the tag's own `>` (bare-word values, no quote
+    before the next `<`); all normal `gate`. `--fix-comment-double-hyphen` (v0.46.0, the RSC-016 fatal)
     replaces `--` inside XML comments with an en-dash: comment bodies only (text
     nodes and CDATA never touched, the one deliberate exception to the
     never-rewrite-comments invariant), in content documents, the NCX, and the OPF
@@ -71,7 +83,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     in `RepairReport.watermark_refusals`, and surfaced as a `manual_watermark_repair`
     decision by `run phase1` on both the read-only and apply paths. `--strip-stub-docs`
     (2026-09-15) mirrors emptytext's placeholder signals: identical short text across
-    >= 3 spine docs and >= 30% of the spine; the whole-spine-stubs book is refused
+    >= 3 spine docs and >= 30% of the spine; since v0.47.0 the pool is the `<body>`
+    span and image-carrier pages (empty body text, an `<img>` present) are exempt, so
+    identical head `<title>`s can never weld illustrated divider pages into a fake
+    stub class (the Great Change misfire); the whole-spine-stubs book is refused
     (EMPTY, re-source), and the drop cascades to archive entries, manifest, spine,
     NCX navPoints, and nav toc entries.
   Do not let any NEW fix touch content without its own flag; if a candidate repair cannot
@@ -103,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.46.1 → bindery_cli-0.47.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.46.1
+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
@@ -51,7 +51,7 @@ bindery-cli makes accidentally broken markup well-formed again. It does not rewr
 
 Everything below is off until its flag is passed (or all at once via `--all`). They go further than well-formedness (altering structure or adding minimal content), so they never run by default:
 
-- **`--fix-ids`**: rewrite ids that are not valid XML names (start with a digit, contain a colon) in the OPF manifest, updating every reference to them (spine, fallback, media-overlay, the EPUB 2 cover meta), and in the NCX (where old conversions stamp navPoint ids from UUIDs). Touches the OPF, so it is off by default; the dc: metadata is never altered.
+- **`--fix-ids`**: rewrite ids that are not valid XML names (start with a digit, contain a colon, or carry any character outside the XML NameChar set, like the apostrophes calibre copies from filenames) in the OPF manifest, updating every reference to them (spine, fallback, media-overlay, the EPUB 2 cover meta), and in the NCX (where old conversions stamp navPoint ids from UUIDs). Touches the OPF, so it is off by default; the dc: metadata is never altered.
 - **`--add-img-alt`**: add `alt=""` to `<img>` elements missing the required attribute. Renders identically, but it adds markup the author never wrote, and an empty alt tells a screen reader the image is decorative; hence opt-in.
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
@@ -72,6 +72,11 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--fix-media-types`**: normalizes 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 (a PNG renamed .jpg) is never made worse.
 - **`--fix-cover`**: repairs 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`**: replaces `--` 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.
+- **`--fix-svg-dup-ids`**: renames 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.
+- **`--fix-cdata-terminator`**: completes 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 is rewritten; invalid CSS stays unfixed, and stylesheet files are not touched.
+- **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
+- **`--fix-stray-close`**: removes 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'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
+- **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<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 `<`.
 
 
 Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -79,7 +84,7 @@ Four opt-in fixes are **lossy** and stand apart from the semantics-preserving re
 - **`--strip-pagination`**: 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: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
 - **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring 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 (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
-- **`--strip-stub-docs`**: drop spine documents whose entire visible text is one identical short placeholder repeated across the spine: the Bookmate-style export whose chapters are all the same "content unavailable" notice, passing epubcheck because the placeholder is valid XHTML. The drop cascades (archive entries, manifest items, spine order, NCX navPoints, nav toc entries), so the book opens straight into its real chapters. The identity rule is deliberately conservative (same text, at least 3 docs, at least 30% of the spine, each doc short but not blank) 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.
+- **`--strip-stub-docs`**: 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, passing epubcheck because the placeholder is valid XHTML. The drop cascades (archive entries, manifest items, spine order, NCX navPoints, nav toc entries), so the book opens straight into its real chapters. The identity rule is deliberately conservative (same body text, at least 3 docs, at least 30% of the spine, each doc short but not blank; the pool is the `<body>` span, and image-carrier pages with no body text are exempt, so illustrated part-divider pages are never candidates) 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.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 

{bindery_cli-0.46.1 → bindery_cli-0.47.1}/README.md

@@ -24,7 +24,7 @@ bindery-cli makes accidentally broken markup well-formed again. It does not rewr
 
 Everything below is off until its flag is passed (or all at once via `--all`). They go further than well-formedness (altering structure or adding minimal content), so they never run by default:
 
-- **`--fix-ids`**: rewrite ids that are not valid XML names (start with a digit, contain a colon) in the OPF manifest, updating every reference to them (spine, fallback, media-overlay, the EPUB 2 cover meta), and in the NCX (where old conversions stamp navPoint ids from UUIDs). Touches the OPF, so it is off by default; the dc: metadata is never altered.
+- **`--fix-ids`**: rewrite ids that are not valid XML names (start with a digit, contain a colon, or carry any character outside the XML NameChar set, like the apostrophes calibre copies from filenames) in the OPF manifest, updating every reference to them (spine, fallback, media-overlay, the EPUB 2 cover meta), and in the NCX (where old conversions stamp navPoint ids from UUIDs). Touches the OPF, so it is off by default; the dc: metadata is never altered.
 - **`--add-img-alt`**: add `alt=""` to `<img>` elements missing the required attribute. Renders identically, but it adds markup the author never wrote, and an empty alt tells a screen reader the image is decorative; hence opt-in.
 - **`--reserialize`**: rebuild content documents that are still malformed by re-parsing them with html5lib and re-emitting XHTML, closing unclosed `<p>`/`<div>`/`<span>`/`<blockquote>` that the regex transforms cannot. Runs only on documents that are not already well-formed, so good files are untouched.
 - **`--strip-bad-attrs`**: drop attributes that are invalid XML (a name starting with a digit, or a namespaced name whose prefix is never declared, like Office VML `v:shapes`). Surgical and a no-op on well-formed files.
@@ -45,6 +45,11 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--fix-media-types`**: normalizes 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 (a PNG renamed .jpg) is never made worse.
 - **`--fix-cover`**: repairs 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`**: replaces `--` 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.
+- **`--fix-svg-dup-ids`**: renames 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.
+- **`--fix-cdata-terminator`**: completes 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 is rewritten; invalid CSS stays unfixed, and stylesheet files are not touched.
+- **`--fix-misnested-inline`**: rewrites the Mobipocket drop-cap mis-nest `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order). Only the both-open-then-reversed-close shape is touched; a punctuation run caught between the reversed closers (`<i><b>xile</i>,</b>`) survives outside both spans, and a letter run there is refused (which span keeps the letters has no deterministic answer).
+- **`--fix-stray-close`**: removes 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'). Merely mis-nested pairs are never touched: a close is removed only when nothing by that name is open.
+- **`--fix-unterminated-attr`**: closes an attribute value left open to the tag's own `>` (`<p class="footnote>` becomes `<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 `<`.
 
 
 Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -52,7 +57,7 @@ Four opt-in fixes are **lossy** and stand apart from the semantics-preserving re
 - **`--strip-pagination`**: 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: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
 - **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring 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 (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
-- **`--strip-stub-docs`**: drop spine documents whose entire visible text is one identical short placeholder repeated across the spine: the Bookmate-style export whose chapters are all the same "content unavailable" notice, passing epubcheck because the placeholder is valid XHTML. The drop cascades (archive entries, manifest items, spine order, NCX navPoints, nav toc entries), so the book opens straight into its real chapters. The identity rule is deliberately conservative (same text, at least 3 docs, at least 30% of the spine, each doc short but not blank) 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.
+- **`--strip-stub-docs`**: 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, passing epubcheck because the placeholder is valid XHTML. The drop cascades (archive entries, manifest items, spine order, NCX navPoints, nav toc entries), so the book opens straight into its real chapters. The identity rule is deliberately conservative (same body text, at least 3 docs, at least 30% of the spine, each doc short but not blank; the pool is the `<body>` span, and image-carrier pages with no body text are exempt, so illustrated part-divider pages are never candidates) 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.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 

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

@@ -1,4 +1,105 @@
 # 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
+
+The 2026-10-05/06 acquisition wave filed five issues against real books; all
+five land here. Two are classifier and validity corrections to existing
+surfaces, three are new opt-in structural repairs, and each was verified
+epubcheck-gated against its own fixture before shipping.
+
+* The stub classifier pools BODY text and exempts image carriers (issue #1).
+  The four Kobo part-divider pages of the Great Change carry only a
+  full-bleed `<img>` each, and their identical head `<title>` welded them,
+  with the title page, into a fake five-doc stub class: emptytext answered
+  PARTIAL and `--strip-stub-docs` offered a strip that deleted real
+  illustrations (the apply-time gate caught the deletion, but the offer was
+  wrong). Both the analyzer and the repair twin now pool the `<body>` span,
+  and a doc with no body text that carries an image is furniture, never a
+  candidate; identical titles alone are never a stub class.
+* `--fix-ids` sees every invalid character, not just colons and digit leads
+  (issue #3). The Lisey's Story OPF carries ids like
+  `Stephen_King_-_Lisey's_story22` (apostrophes copied from filenames),
+  which passed the original empty/colon/leading-char NCName check
+  wholesale, so a full `--all` sweep left the RSC-005 id errors standing
+  (epubcheck's message says "without colons"; the defect was never colons).
+  The check now enforces the XML NameChar set at every position, and the
+  rename sanitizes every invalid character to `_`, references in sync as
+  before. Fixture: 22 ids renamed, the OPF id error class cleared; the
+  errors that remain on that book are unrelated classes (deprecated body
+  attributes, stray GeoXML elements).
+* `--fix-svg-dup-ids` (issue #2): old calibre 0.8.x SVG page renders repeat
+  glyph ids within one document. The first occurrence keeps its name, later
+  ones gain `_2`/`_3`, and references are deliberately untouched: they
+  resolve to the first definition under every reader's first-match lookup,
+  so first-keeps-id preserves exactly what rendered. Standalone `.svg`
+  entries only; content-document ids are styled and anchor-targeted and
+  stay out of scope. Fixture: 346 ids rewritten, 80 aggregated errors to
+  zero.
+* `--fix-cdata-terminator` (issue #4): completes the truncated `/*]]>`
+  CDATA-terminator comment inside inline `<style>` blocks (the 2002-era
+  conversion lineage whose 19 content docs each died with CSS-008
+  "Premature end of file"; the aggregated gate saw one message). Only the
+  malformed-terminator token class: invalid CSS stays unfixed, stylesheet
+  files are not touched, and an intact closer (even space-separated) is
+  left alone.
+* The markup-fatal trio (issue #5): `--fix-misnested-inline` normalizes the
+  Mobipocket drop-cap mis-nest `<i><b>X</i></b>` (em/strong variants and
+  either order; punctuation between the reversed closers survives outside
+  both spans; a letter run is refused as ambiguous),
+  `--fix-stray-close` removes an end tag whose element has no open start
+  frame (a merely mis-nested pair is never touched; script/style text is
+  skipped to its end tag and an unclosed comment stops the walk), and
+  `--fix-unterminated-attr` closes an
+  attribute value open to the tag's own `>` (`<p class="footnote>`;
+  bare-word values only, and only when no quote closes before the next
+  `<`). Life (Keith Richards): 3 fatals to zero, gate-accepted with the
+  unterminated-attr repair running before the tag-shape readers an open
+  value would otherwise lie to.
+
+Tests: 615 (up from 575), including a real-core row per new flag, the
+wiring-table pins for the five new dests, classifier regressions for both
+sides of the stub fix, and a version-sync pin for uv.lock's root entry
+(the pre-release audit found v0.46.1 shipped with the lock one patch
+stale, a class the pyproject pin cannot see). The plugin ships the default pass only; it
+vendors the changed modules byte-identically and CI byte-compiles it under
+3.11 through 3.14.
+
 ## v0.46.1 (2026-10-02)
 
 ### The closing sweep: documentation truth after the 0.46 line

{bindery_cli-0.46.1 → bindery_cli-0.47.1}/pyproject.toml

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

@@ -40,6 +40,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | Waves 15 + blitz | The plugin PEP-758 HIGH + the 3.11-3.14 interpreter matrix, analyzer robustness, the per-matcher census (possessive bounding; cited by tests/test_matcher_hardening.py), stdlib XML hardening, FastDaemon v2 (reconcile-not-retire), `--strip-stub-docs`, `bindery doctor` + `repair --json`, `--encode-url-spaces` entry renames, the cover + tocdrift analyzers, the privacy/GitHub/docs/comment/hygiene batches, requires-python 3.12 with markers, the em-dash sweep | v0.40.0-v0.44.0 |
 | 0.45 | Structured fix records (`fixes`, `ncx_uid_synced`, `watermark_refusals`) in every JSON payload; CalibreQuarry consumes them with the 0.45.0 floor | v0.45.0 |
 | 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 |
 
 ## Open work
 

{bindery_cli-0.46.1 → bindery_cli-0.47.1}/spec.md

@@ -13,13 +13,14 @@ restyle, re-compress, or restructure content, and it does not attempt to fix arb
 schema (RSC-005) violations, which are usually harmless to readers and not safely
 mechanizable.
 
-The deliberate exceptions to "semantics-preserving" come in opt-in groups. The sixteen
+The deliberate exceptions to "semantics-preserving" come in opt-in groups. The twenty-one
 **structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
 `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
 `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
 `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`,
-`--fix-container`, `--fix-media-types`, `--fix-cover`,
-`--fix-comment-double-hyphen`) alter
+`--fix-container`, `--fix-media-types`, `--fix-cover`, `--fix-comment-double-hyphen`,
+`--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`,
+`--fix-stray-close`, `--fix-unterminated-attr`) alter
 markup structure or fabricate minimal content; the four
 **lossy modes** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`,
 `--strip-stub-docs`) remove
@@ -124,7 +125,7 @@ byte-for-byte. The normal gate applies.
 
 ### Opt-in: structural repairs
 
-Sixteen repairs go past well-formedness and therefore require their own flag; none is ever
+Twenty-one repairs go past well-formedness and therefore require their own flag; none is ever
 part of the default pipeline:
 
 - **`--fix-empty-body`**: `&nbsp;` inside a strictly empty `<body></body>` ("body
@@ -233,8 +234,54 @@ use, with the `partial` rule intact.
   never touched, and each comment's `-->` terminator stays intact. An unclosed comment is a
   different fatal class and is left alone. It applies to content documents, the NCX, and
   the OPF alike, and every replaced sequence is counted.
-
-Fourteen of the sixteen are evaluated by the normal `gate`: unlike the lossy strips,
+- **`--fix-svg-dup-ids`**: rename duplicate `id` values inside standalone `.svg`
+  entries (old calibre 0.8.x SVG page renders repeat glyph ids within one document;
+  four books from one intake wave carried 445 to 1,339 'Duplicate "glNNNN"' RSC-005s
+  each). The first occurrence keeps its name; every later one gains `_2`, `_3`, ... in
+  document order (prefixed with `_` until the name is free). Internal
+  `xlink:href="#x"` / `url(#x)` references are deliberately never rewritten: they
+  already resolve to the first definition under every reader's first-match lookup, so
+  first-keeps-id preserves exactly what rendered. Scope is standalone `.svg` entries
+  only: content-document ids are styled by CSS selectors and targeted by anchors, and
+  renaming those needs a reference graph this repair does not build.
+- **`--fix-cdata-terminator`**: complete a truncated CDATA-terminator comment in an
+  inline `<style>` block: `/*]]>` becomes `/*]]>*/` (a comment-wrapped CDATA block
+  whose closing `*/` the converter dropped; epubcheck's CSS parser reads the dangling
+  `/*` as an unterminated comment and answers CSS-008 'Premature end of file' once per
+  affected document, 19 identical errors on the 2002-era fixture). Deliberately narrow:
+  only the malformed-terminator token class, inside `<style>` blocks only; invalid CSS
+  properties and selectors stay unfixed (renderers degrade gracefully), stylesheet FILE
+  entries are not touched, and a closer that already sits intact (possibly after
+  whitespace) is left alone.
+- **`--fix-misnested-inline`**: rewrite the Mobipocket drop-cap mis-nest
+  `<i><b>X</i></b>` to `<i><b>X</b></i>` (em/strong variants and either tag order
+  included). Only the both-open-then-reversed-close shape is rewritten: any match is
+  XML fatal, and swapping the closers is the unique well-formed form carrying the same
+  two spans over the same text. The Exile variant, where a short punctuation run sits
+  between the reversed closers (`<i><b>xile</i>,</b>`), is covered: the punctuation
+  survives outside both spans, byte-preserved. A letter run between the closers
+  (`<i><b>S</i>ome</b>`, where `<b>` spans `Some` and `<i>` only `S`) is refused: which
+  span keeps the letters has no deterministic answer. Same-tag pairs, attribute-bearing
+  starts, and markup crossing the run are untouched.
+- **`--fix-stray-close`**: 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'). The rule is deliberately narrower
+  than a nesting repair: a close is removed only when NOTHING by that name is open, so
+  a merely mis-nested pair (`<div><span></div></span>`) is left exactly as written
+  (its `</span>` still has an open frame and is never misread as stray). Self-closed
+  and void starts open no frame; raw-text elements (`script`, `style`) are skipped to
+  their end tag so JS/CSS text is never read as markup; the walk stops at an unclosed
+  comment or CDATA opener, where the parser stops reading markup too.
+- **`--fix-unterminated-attr`**: 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, meets a `<`, and dies with the RSC-016 fatal "the
+  value of attribute ... must not contain the '<' character"). Three guards keep it off
+  legal `>`-bearing values: the value is one bare word, the `>` must be followed by no
+  quote before the next `<` (a real multi-line value closes quote-first), and only
+  double-quoted values are judged. It runs before the other tag-shape readers, which an
+  open value otherwise lies to.
+
+Nineteen of the twenty-one are evaluated by the normal `gate`: unlike the lossy strips,
 their benefit is visible to epubcheck (they clear errors), so a run with no measurable
 improvement is a noop and nothing is applied. The two exceptions are `--fix-cover` and
 `--encode-url-spaces`, whose gains sit on axes epubcheck does not measure (cover
@@ -267,7 +314,7 @@ Since this removes visible text from the reading experience, it is lossy by desi
 Strips known producer and redistributor watermarks out of EPUBs (e.g. OceanofPDF.com, ABC Amber LIT Converter). The removal is a balanced-element surgery rather than regex slicing: it locates the stamp and deletes the outermost wrapper whose *entire visible text* is the watermark, ensuring prose that merely mentions the URL is preserved. Also drops known zero-byte marker files. Like other lossy operations, this is verified via `no_worse`.
 
 ### Opt-in, lossy: stub-document strip (`--strip-stub-docs`)
-Drops spine documents whose entire visible text is one identical short placeholder repeated across the spine: the Bookmate/DRM-sample export whose chapters are all the same "content unavailable" notice, valid XHTML that epubcheck passes. The identity rule mirrors the emptytext analyzer's placeholder signals and is deliberately conservative: a candidate doc's visible text is 12-600 characters (short, not blank) and IDENTICAL to the text of at least two other spine docs, and the class covers at least 30% of the spine; only the single most common repeated class qualifies.
+Drops spine documents whose entire visible BODY text is one identical short placeholder repeated across the spine: the Bookmate/DRM-sample export whose chapters are all the same "content unavailable" notice, valid XHTML that epubcheck passes. The identity rule mirrors the emptytext analyzer's placeholder signals and is deliberately conservative: a candidate doc's visible body text is 12-600 characters (short, not blank) and IDENTICAL to the text of at least two other spine docs, and the class covers at least 30% of the spine; only the single most common repeated class qualifies. The pool is the `<body>` span, not the whole document (whole document when a doc has none; a converter stamps the same head `<title>` on every shell page, which used to weld unrelated docs into a fake stub class), and an image-carrier page (empty body text, an `<img>`/`<image>` present) is exempt outright: those are illustrated part-divider pages, furniture the strip must never delete (the Great Change misfire, 2026-10-05).
 
 The drop cascades fully: the placeholder archive entries, their manifest items and spine itemrefs (with every package edge rewritten), their NCX navPoints (the always-on playOrder resequencing heals the sequence afterward), and their nav toc `<li>` entries. Refusals, each reported as a no-op: no repeated class, the class under the fraction bar, and the class covering the whole spine (a book whose every spine doc is the same stub is EMPTY; it needs a re-source, never a repair). Accepted under the `no_worse` bar with the partial rule intact.
 

{bindery_cli-0.46.1 → 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.46.1"
+VERSION = "0.47.1"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.46.1 → bindery_cli-0.47.1}/src/bindery/audit.py

@@ -1224,6 +1224,28 @@ def _visible_chars(html: str) -> int:
     return len(_visible_text(html))
 
 
+# Stub identity pools BODY text (the image-carrier fix, 2026-10-06): a
+# converter stamps the same head <title> on every shell page, so
+# whole-document text welded unrelated docs into a fake stub class (the Great
+# Change divider-page misfire, issue #1). An image-carrier rule (empty body
+# text, an <img>/<image> present) marks divider pages: furniture, never
+# stubs. Mirrored by epub._stub_body_text / epub._stub_is_image_carrier.
+_BODY_SPAN_RE = re.compile(r"<body\b[^>]*>(.*)</body>", re.IGNORECASE | re.DOTALL)
+_IMAGE_CARRIER_RE = re.compile(r"<(?:img|image)\b", re.IGNORECASE)
+
+
+def _body_visible_text(html: str) -> str:
+    """Visible text of the <body> span (whole document when there is none)."""
+    m = _BODY_SPAN_RE.search(html)
+    return _visible_text(m.group(1)) if m else _visible_text(html)
+
+
+def _is_image_carrier(html: str, body_text: str) -> bool:
+    """True for a doc with no body text that carries an image element: a
+    divider page (furniture), never a stub."""
+    return body_text == "" and bool(_IMAGE_CARRIER_RE.search(html))
+
+
 def analyze_emptytext(book: Book) -> dict:
     """Count visible text across the (pre-read) spine and gather triage signals."""
     texts = book.visible_texts()
@@ -1235,10 +1257,23 @@ def analyze_emptytext(book: Book) -> dict:
     # short stub repeated across a large fraction of the spine (most chapters
     # replaced by an identical "content unavailable" notice). Blank docs are
     # excluded by PLACEHOLDER_STUB_MIN so well-made books full of small section
-    # dividers (each with distinct text) do not trip it.
+    # dividers (each with distinct text) do not trip it. The pool is the BODY
+    # text, and image-carrier pages are excluded outright: the four Kobo
+    # divider pages of the Great Change carry only a full-bleed <img>, and
+    # their identical head <title> used to be the "stub" every one of them
+    # matched (offering a --strip-stub-docs that deleted real illustrations).
     sig = any(_PLACEHOLDER_SIG.search(t) for t in texts)
+    body_texts = []
+    carriers = []
+    for d in book.spine:
+        doc_html = book.docs.get(d, "")
+        body = _body_visible_text(doc_html)
+        body_texts.append(body)
+        carriers.append(_is_image_carrier(doc_html, body))
     stubs = Counter(
-        t for t in texts if PLACEHOLDER_STUB_MIN <= len(t) <= PLACEHOLDER_STUB_MAX
+        t
+        for t, carrier in zip(body_texts, carriers, strict=True)
+        if not carrier and PLACEHOLDER_STUB_MIN <= len(t) <= PLACEHOLDER_STUB_MAX
     )
     stub_n = stubs.most_common(1)[0][1] if stubs else 0
     spine_n = max(1, len(book.spine))