bindery-cli 0.27.0__tar.gz

bindery_cli-0.27.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      # html5lib is the project's declared optional `reserialize` extra (core stays
+      # stdlib-only); installing it here lets CI exercise the --reserialize tests
+      # instead of skipping them. ruff is a dev-only linter.
+      - run: pip install . html5lib ruff==0.16.2
+      # The rule set lives in pyproject.toml, so these mean the same thing locally.
+      # Checking `.` rather than named directories keeps a new top-level script from
+      # silently escaping lint.
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: PYTHONPATH=src python -m unittest discover -s tests

bindery_cli-0.27.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Run test suite
+        run: |
+          pip install .[reserialize]
+          PYTHONPATH=src python -m unittest discover -s tests
+
+  build-and-publish:
+    name: Build distribution and publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bindery-cli
+    permissions:
+      id-token: write # Required for OIDC authentication with PyPI
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install build
+        run: python -m pip install --upgrade build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bindery_cli-0.27.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.ruff_cache/
+.pytest_cache/
+
+# Ignore actual books used for testing to prevent IP leaks
+testing_facility/books_to_fix/*
+!testing_facility/books_to_fix/.gitkeep

bindery_cli-0.27.0/AGENTS.md

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

bindery_cli-0.27.0/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md (Bindery)
+
+Per-project guidance. Overrides the global file where they conflict.
+
+## What this is
+
+A focused EPUB repair and diagnostic tool: deterministic well-formedness fixes, gated by epubcheck,
+with atomic in-place replacement in a Calibre library. Absorbed the retired oceanstrip at
+v0.12.0 (2026-08-22) as the lossy `--strip-watermarks` flag; the standalone repo is gone from
+the workspace (2026-08-26), and any instruction that runs `python -m oceanstrip` is dead.
+Born from the 2026 library audit (see the user memory `calibre-library-epubcheck-audit`).
+
+## Hard constraints
+
+- **Minimal Dependencies.** Runtime deps are exactly: `tqdm` (progress/output),
+  `vir-tui` (shared TUI rendering) and `cquarry` (read-only Calibre `metadata.db` access,
+  adopted in v0.16.0). `vir-tui` is PINNED to an exact commit in pyproject.toml
+  (bump deliberately); `cquarry` deliberately tracks `@main` since v0.19.0 so CI always
+  exercises the current library. `html5lib` remains the one approved
+  heavy-parsing exception (used only for the `--reserialize` fix, imported lazily so every
+  other mode runs without it). Tests use the standard `unittest` framework. epubcheck is an
+  external CLI dependency, and `calibredb` is required for the `--install-to-calibre`
+  feature. Before adding any further Python package, stop and ask.
+- **Semantics-preserving transforms by default, everything else fenced behind a flag.**
+  The always-on core is exactly five well-formedness fixes (prolog junk, duplicate
+  `xmlns`, bare `&`, named entities, void self-closing) plus the NCX pipeline; every core
+  fix must render identically to the author's intent: never add, remove, or reorder
+  visible content. Two kinds of exceptions exist, both opt-in and off unless requested:
+  * **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`;
+    transforms.py, threaded through epub.py): they alter markup structure or fabricate
+    minimal content. v0.14–v0.16 ran these unconditionally, which broke this rule;
+    v0.17.0 restored it. `--unwrap-illegal-tags` additionally protects any illegal-tag
+    name that an EPUB stylesheet styles as an element selector (`css_protected_tags`,
+    book-wide, inline `<style>` blocks included).
+  * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`;
+    pagination.py, watermark.py): remove only what a converter injected (page numbers,
+    running headers, leaked tags, watermarks), fenced behind character conservation, tag
+    balance, and the epubcheck no-regression bar.
+  Do not let any NEW fix touch content without its own flag; if a candidate repair cannot
+  be made deterministically safe, it does not belong here — report it for manual repair
+  instead.
+- **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
+  Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
+  error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
+  `--strip-watermarks`) are accepted by `validate.no_worse` instead (their gain is
+  invisible to epubcheck, so it only forbids a regression, never demands a measured
+  improvement). The structural opt-ins go through the normal `gate`: their gain IS
+  visible (they clear errors), so a run with no measurable improvement is a noop and
+  nothing is applied. Changing either bar means re-running the library dry run.
+- **Library writes are sacred.** Replacement must stay atomic (temp in same dir, then
+  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default. Calibre integrations should seamlessly swap formats using `calibredb add_format -replace`.
+  Never write to the library without `-apply`. Test every change on `/tmp` copies first.
+
+## Layout
+
+- `src/bindery/transforms.py`: pure `str -> (str, int)` text transforms (including `strip_broken_tags`).
+- `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
+- `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
+- `src/bindery/reserialize.py`: structural repair via `html5lib`.
+- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, and `monolithic` since v0.21.0, `--max-doc-chars N`) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again.
+- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan).
+- `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` (remove+add in one `batch()`; `add_format` refuses duplicates); the external `calibredb` CLI is gone. Never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, and the version pin.
+
+## Conventions
+
+- Type hints, `from __future__ import annotations`, ruff for lint and format.
+- `VERSION` lives in `src/bindery/__init__.py`, mirrored in `pyproject.toml`. Bump both.
+- Run tests with `./run_tests.sh`.
+
+## Validation workflow
+
+The library is real data. The loop is always: dry run on `/tmp` copies, inspect the
+report, then apply with backups. epubcheck is the oracle; a repaired book that still has
+fatals is `partial` and must be left for manual work, never auto-applied.

bindery_cli-0.27.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vrnvctss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bindery_cli-0.27.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: bindery-cli
+Version: 0.27.0
+Summary: High-speed EPUB repair surgeon with a persistent Java validation daemon, safe HTML unwrapping, and native Calibre integration.
+Author: vrnvctss
+License: MIT
+License-File: LICENSE
+Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Requires-Python: >=3.14
+Requires-Dist: cquarry>=1.9.0
+Requires-Dist: tqdm
+Requires-Dist: vir-tui>=2.2.0
+Provides-Extra: reserialize
+Requires-Dist: html5lib>=1.1; extra == 'reserialize'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="logo.svg" width="96" height="96" alt="Bindery logo"/>
+  <h1>Bindery</h1>
+  <p>Audit EPUB body text and repair broken EPUBs with safe, deterministic fixes, validated by epubcheck, with optional in-place replacement in a Calibre library.</p>
+</div>
+
+<p align="center">
+  <img src="docs/screenshots/library-sweep.png" alt="Bindery's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
+</p>
+
+## What it fixes
+
+Bindery makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
+
+- **Unclosed void elements** (`<link>`, `<br>`, `<img>`, ...) get self-closed.
+- **Undeclared named entities** (`&nbsp;`, `&deg;`, `&eacute;`, ...) become numeric character references that every XML parser understands.
+- **Bare `&`** (common in `toc.ncx`) is escaped to `&amp;`.
+- **Junk before the XML prolog** (BOM, stray bytes) is stripped.
+- **Duplicate `xmlns`** on the root `<html>` is collapsed to one.
+- **NCX-001**: `toc.ncx` `dtb:uid` is synced to the OPF unique identifier; duplicated NCX `playOrder` values are resequenced whenever the NCX is processed (part of the always-on NCX pipeline, not a flag).
+- **mimetype** is rewritten first and stored, fixing the common ordering defect; a missing entry is added and wrong or whitespace-padded content is normalized to the OCF constant.
+
+### Opt-in repairs
+
+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.
+- **`--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.
+- **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
+- **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
+- **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
+- **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
+- **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
+
+
+Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
+
+- **`--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 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.
+
+All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
+
+## The safety contract
+
+Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acceptance rule is two-mode, because a fatal parse error makes epubcheck stop reading a file and hides every downstream error:
+
+- If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
+- If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
+
+Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
+
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+
+## Install
+
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the pinned VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+
+```sh
+uv tool install bindery-cli                            # core tools
+uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
+```
+
+## Usage
+
+Three verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, and `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place).
+The sections below take each in turn.
+
+## Auditing
+
+Bindery includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
+
+Scan a Calibre library for specific issues:
+
+```sh
+# Detect non-English content (e.g., Cyrillic or CJK in an English library)
+cd ~/docs/Calibre\ Library && bindery audit content
+
+# Find books with hardcoded print page numbers interrupting the text
+bindery audit pagenumbers ~/docs/Calibre\ Library
+
+# Find books that are empty or severely truncated
+bindery audit emptytext ~/docs/Calibre\ Library
+
+# Find books with severe OCR damage (garbage characters, excessive hyphenation)
+bindery audit ocr ~/docs/Calibre\ Library
+
+# Flag books where a single content document is too large for readers to render
+bindery audit monolithic ~/docs/Calibre\ Library
+
+# Run all audits and generate a comprehensive CSV
+cd ~/docs/Calibre\ Library && bindery audit all
+```
+
+Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
+```sh
+bindery audit pagenumbers /path/to/loose/epubs
+```
+
+Or on one or more library books by Calibre id (comma-separated) — fetched through cquarry's single-entity `get_book()` (no library-wide scan), with the EPUB resolved via cquarry's own path logic:
+```sh
+cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
+```
+`--id` composes with `--tag`: the book is tagged only if the audit flags it.
+
+**Spine-integrity reporting:** Both `audit` and `library` reports now classify manifest/NCX references that point to absent files. A `convention` verdict means the ToC is bloated but the present documents form a consecutive chapter span (e.g., the Wandering Inn official-build pattern, safe). A `fragment` verdict means the span itself is broken.
+
+**Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT — with the first broken entry named — instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
+
+### Tagging flagged books (opt-in)
+
+By default an audit writes nothing. With `--tag TAG` (library mode only), every book the audit
+flags is tagged in `metadata.db` through cquarry's trigger-safe write module — useful for piping
+flagged books back into Calibre views:
+
+```sh
+cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
+```
+
+The audit itself stays read-only; only the final tagging pass writes, it skips books that already
+carry the tag, and THIN emptytext advisories are never tagged. Close Calibre first so the write
+does not fight its lock. Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
+desktop app regenerates their sidecar `.opf`s (and re-pushes metadata to wireless readers) on its
+next startup — no manual resync needed.
+
+
+Repair one book to a new file (gated; writes only if it is an improvement):
+
+```sh
+bindery repair broken.epub                 # -> "broken (repaired).epub"
+bindery repair broken.epub fixed.epub
+bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
+```
+
+Scan a Calibre library and see what would be fixed, writing nothing:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only fatals --audit epub_audit.csv
+```
+
+Apply accepted repairs in place, atomically, with backups:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only fatals --apply --backup ~/bindery-backups
+```
+
+Apply all safe and lossy repairs directly into the Calibre database natively:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-calibre
+```
+
+- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
+- `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
+- `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. Bindery launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
+- `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
+- `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
+- Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
+- A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.
+- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
+- `repair` refuses to overwrite an existing output file unless `--force` is given.
+
+## Companion scripts
+
+`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside Bindery's repair contract (fixing what they find would be a content change, which Bindery makes only via the opt-in `--strip-pagination`):
+
+- `find_missing_images.py`: scans a library tree and reports every book whose `<img>` tags point at files that do not exist inside the archive (a common defect in converted EPUBs). Reads the archives in place; nothing is unpacked or written. The library path is set at the bottom of the script.
+
+## Development
+
+```sh
+./run_tests.sh        # unittest suite
+```
+
+See [spec.md](spec.md) for the full contract and [roadmap.md](roadmap.md) for what is planned.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Support
+
+If Bindery's useful to you and you'd like to chip in:
+
+- liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
+- bitcoin
+  ```
+  bc1qkge6zr45tzqfwfmvma2ylumt6mg7wlwmhr05yv
+  ```

bindery_cli-0.27.0/README.md

@@ -0,0 +1,202 @@
+<div align="center">
+  <img src="logo.svg" width="96" height="96" alt="Bindery logo"/>
+  <h1>Bindery</h1>
+  <p>Audit EPUB body text and repair broken EPUBs with safe, deterministic fixes, validated by epubcheck, with optional in-place replacement in a Calibre library.</p>
+</div>
+
+<p align="center">
+  <img src="docs/screenshots/library-sweep.png" alt="Bindery's dry-run library sweep: per-book epubcheck results and a summary table ending in 'no files written'">
+</p>
+
+## What it fixes
+
+Bindery makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
+
+- **Unclosed void elements** (`<link>`, `<br>`, `<img>`, ...) get self-closed.
+- **Undeclared named entities** (`&nbsp;`, `&deg;`, `&eacute;`, ...) become numeric character references that every XML parser understands.
+- **Bare `&`** (common in `toc.ncx`) is escaped to `&amp;`.
+- **Junk before the XML prolog** (BOM, stray bytes) is stripped.
+- **Duplicate `xmlns`** on the root `<html>` is collapsed to one.
+- **NCX-001**: `toc.ncx` `dtb:uid` is synced to the OPF unique identifier; duplicated NCX `playOrder` values are resequenced whenever the NCX is processed (part of the always-on NCX pipeline, not a flag).
+- **mimetype** is rewritten first and stored, fixing the common ordering defect; a missing entry is added and wrong or whitespace-padded content is normalized to the OCF constant.
+
+### Opt-in repairs
+
+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.
+- **`--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.
+- **`--escape-unknown-entities`**: escape entity names that are not in the HTML5 table (`&foo;` becomes `&amp;foo;`), which renders exactly as browsers already render an unknown entity. Documents whose DOCTYPE carries an internal subset are skipped wholesale, since a subset can declare custom entities.
+- **`--fix-id-colons`**: translates illegal colons in `id="X:Y"` and their matching `#X:Y` fragment references to valid underscores.
+- **`--fix-empty-body`**: appends a non-breaking space `&nbsp;` to strictly empty body tags to satisfy parser requirements.
+- **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
+- **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
+- **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
+- **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
+- **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package — `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive).
+- **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents — `figure`/`section` to `div`, `figcaption` to `p` — keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed.
+- **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
+
+
+Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
+
+- **`--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 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.
+
+All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
+
+## The safety contract
+
+Every repair is gated by [epubcheck](https://github.com/w3c/epubcheck). The acceptance rule is two-mode, because a fatal parse error makes epubcheck stop reading a file and hides every downstream error:
+
+- If a book **had fatals**, success means **fewer fatals**. The error count may rise as previously-hidden schema warnings become visible once the file parses; that is the book going from "won't open" to "opens with nits," not a regression.
+- If a book had **no fatals**, an error increase is a real regression, so a strict error decrease is required.
+
+Introducing a net-new fatal is always rejected. If epubcheck itself fails to run (crash, timeout, unparsable output), the book is reported as an error and never applied; only an explicit `--no-validate` skips the gate. Originals are never modified except by an explicit, atomic in-place replace (see below), and even then only after the gate accepts the result.
+
+The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-watermarks`) are the exception to the "must improve" rule. Since they remove visible markup rather than correcting XML schema violations, epubcheck counts often remain unchanged. They are accepted when the result is **no worse** (no net-new fatals or errors), relying on strict programmatic safety nets instead.
+
+## Install
+
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the pinned VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+
+```sh
+uv tool install bindery-cli                            # core tools
+uv tool install "bindery-cli[reserialize]"             # incl. --reserialize
+```
+
+## Usage
+
+Three verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, and `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place).
+The sections below take each in turn.
+
+## Auditing
+
+Bindery includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
+
+Scan a Calibre library for specific issues:
+
+```sh
+# Detect non-English content (e.g., Cyrillic or CJK in an English library)
+cd ~/docs/Calibre\ Library && bindery audit content
+
+# Find books with hardcoded print page numbers interrupting the text
+bindery audit pagenumbers ~/docs/Calibre\ Library
+
+# Find books that are empty or severely truncated
+bindery audit emptytext ~/docs/Calibre\ Library
+
+# Find books with severe OCR damage (garbage characters, excessive hyphenation)
+bindery audit ocr ~/docs/Calibre\ Library
+
+# Flag books where a single content document is too large for readers to render
+bindery audit monolithic ~/docs/Calibre\ Library
+
+# Run all audits and generate a comprehensive CSV
+cd ~/docs/Calibre\ Library && bindery audit all
+```
+
+Audits can also be run on a directory of loose `.epub` files by passing the path as the second argument:
+```sh
+bindery audit pagenumbers /path/to/loose/epubs
+```
+
+Or on one or more library books by Calibre id (comma-separated) — fetched through cquarry's single-entity `get_book()` (no library-wide scan), with the EPUB resolved via cquarry's own path logic:
+```sh
+cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
+```
+`--id` composes with `--tag`: the book is tagged only if the audit flags it.
+
+**Spine-integrity reporting:** Both `audit` and `library` reports now classify manifest/NCX references that point to absent files. A `convention` verdict means the ToC is bloated but the present documents form a consecutive chapter span (e.g., the Wandering Inn official-build pattern, safe). A `fragment` verdict means the span itself is broken.
+
+**Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT — with the first broken entry named — instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
+
+### Tagging flagged books (opt-in)
+
+By default an audit writes nothing. With `--tag TAG` (library mode only), every book the audit
+flags is tagged in `metadata.db` through cquarry's trigger-safe write module — useful for piping
+flagged books back into Calibre views:
+
+```sh
+cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
+```
+
+The audit itself stays read-only; only the final tagging pass writes, it skips books that already
+carry the tag, and THIN emptytext advisories are never tagged. Close Calibre first so the write
+does not fight its lock. Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
+desktop app regenerates their sidecar `.opf`s (and re-pushes metadata to wireless readers) on its
+next startup — no manual resync needed.
+
+
+Repair one book to a new file (gated; writes only if it is an improvement):
+
+```sh
+bindery repair broken.epub                 # -> "broken (repaired).epub"
+bindery repair broken.epub fixed.epub
+bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
+```
+
+Scan a Calibre library and see what would be fixed, writing nothing:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only fatals --audit epub_audit.csv
+```
+
+Apply accepted repairs in place, atomically, with backups:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only fatals --apply --backup ~/bindery-backups
+```
+
+Apply all safe and lossy repairs directly into the Calibre database natively:
+
+```sh
+bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-calibre
+```
+
+- `--only {fatals,ncx,all}` restricts the candidate set. `ncx` targets NCX-001 mismatches (detected without epubcheck); `fatals` needs `--audit`.
+- `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
+- `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
+- `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. Bindery launches a transparent, persistent Java daemon (`EpubcheckDaemon`) to evaluate candidates in the background, eliminating the JVM startup penalty. This reduces validation time from ~5 seconds per book down to ~0.05 seconds, allowing `--sweep` to scan a 5,000-book library in just 10 minutes. Combine with `--only fatals` for a self-contained, lightning-fast "find and fix the broken books" run.
+- `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
+- `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
+- `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
+- `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied` — Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning.
+- `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
+- Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
+- A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.
+- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron).
+- `repair` refuses to overwrite an existing output file unless `--force` is given.
+
+## Companion scripts
+
+`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside Bindery's repair contract (fixing what they find would be a content change, which Bindery makes only via the opt-in `--strip-pagination`):
+
+- `find_missing_images.py`: scans a library tree and reports every book whose `<img>` tags point at files that do not exist inside the archive (a common defect in converted EPUBs). Reads the archives in place; nothing is unpacked or written. The library path is set at the bottom of the script.
+
+## Development
+
+```sh
+./run_tests.sh        # unittest suite
+```
+
+See [spec.md](spec.md) for the full contract and [roadmap.md](roadmap.md) for what is planned.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Support
+
+If Bindery's useful to you and you'd like to chip in:
+
+- liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
+- bitcoin
+  ```
+  bc1qkge6zr45tzqfwfmvma2ylumt6mg7wlwmhr05yv
+  ```