bindery-cli 0.27.0__tar.gz → 0.29.0__tar.gz

bindery_cli-0.29.0/.gitignore

@@ -0,0 +1,21 @@
+__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
+testing_facility/top500candidates/*.epub
+
+# Compiled Java scratch (FastSweep harness)
+*.class
+
+# Local virtualenvs (each carries its own auto-generated inner .gitignore,
+# which is the only reason they were invisible until now)
+venv/
+.venv_ci/

{bindery_cli-0.27.0 → bindery_cli-0.29.0}/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md (Bindery)
+# CLAUDE.md (bindery-cli)
 
 Per-project guidance. Overrides the global file where they conflict.
 
@@ -14,13 +14,13 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 
 - **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
+  adopted in v0.16.0), pinned as PyPI ranges in pyproject.toml (`vir-tui>=2.2.0`,
+  `cquarry>=1.9.0`); `uv.lock` records the resolved versions. `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.
+  external CLI dependency expected on PATH; `--install-to-calibre` needs no external
+  binary, it re-registers the format through cquarry's write module (the calibredb
+  subprocess was retired in v0.24.0). 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
@@ -28,7 +28,8 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   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`;
+    `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
+    `--prune-missing-resources`, `--strip-broken-anchors`, `--encode-url-spaces`;
     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
@@ -50,8 +51,10 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   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.
+  `os.replace`), touch only the `.epub`, preserve mode, and be dry-run by default.
+  Calibre format installation goes through cquarry's write module (`--install-to-calibre`;
+  the calibredb subprocess was retired in v0.24.0). Never write to the library without
+  `--apply`. Test every change on `/tmp` copies first.
 
 ## Layout
 
@@ -59,11 +62,11 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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/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. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story).
 - `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`.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; 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). Both 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.
 - `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

bindery_cli-0.27.0/README.md → bindery_cli-0.29.0/PKG-INFO

@@ -1,16 +1,38 @@
+Metadata-Version: 2.5
+Name: bindery-cli
+Version: 0.29.0
+Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
+Author: vrnvctss
+License: MIT
+License-File: LICENSE
+Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+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>
+  <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
+  <h1>bindery-cli</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'">
+  <img src="docs/screenshots/library-sweep.png" alt="bindery-cli'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:
+bindery-cli 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.
@@ -38,6 +60,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
+- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
+- **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
+- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -61,7 +86,7 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## 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`.
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the 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
@@ -70,14 +95,16 @@ 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).
+Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place),
+and `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
+vetting, phase-3 scoped post-import repair) for a calling agent.
 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`.
+bindery-cli 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:
 
@@ -112,6 +139,12 @@ cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
 ```
 `--id` composes with `--tag`: the book is tagged only if the audit flags it.
 
+**Machine-readable reports:** `--json FILE` writes the run's verdicts in the same shape `library --json` uses: one record per book with a `status` (`clean`/`problem`/`error`) and per-analyzer verdicts (`problem`, `status`, `details`), plus the always-on archive/spine verdicts (OK when they were silent). This is the contract downstream consumers of the pre-import vetting slice read.
+```sh
+bindery audit all ~/Downloads/epubs --json vetting-report.json
+```
+With `--id`, `--json` accepts exactly one book id (each single-book run writes the file wholesale).
+
 **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.
@@ -162,7 +195,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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.
+- `--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-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "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.
@@ -173,11 +206,47 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - 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.
 
+## Run slices
+
+`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
+repair classes of their own: they compose the shipped audit and library runners
+in the documented order, and both speak `--json` for a calling agent.
+
+**`run phase1 DIR`** is the pre-import vetting slice for a directory of loose
+files: the audit battery (corruption sweep, content battery, monolithic) in one
+decompression pass per book, then the gated repair sweep (epubcheck, watermark
+detection, repairability) over the same directory. The verb is read-only until
+`--apply-lossy` is passed, and that flag IS the recorded lossy-strip consent;
+`--backup DIR` mirrors originals first (keep backups outside the vetted
+directory). Consent questions never block the verb: a read-only run that finds
+repairable books records an `apply_lossy` entry in the JSON's
+`decisions_needed` instead of prompting, and `--non-interactive` declares that
+contract for callers. Exit codes per the `library` contract: 0 clean, 1 usage,
+2 when any book is flagged, rejected, unreadable, or failed epubcheck (a
+consent question alone is not trouble).
+
+```sh
+bindery run phase1 ~/Downloads --json phase1-report.json               # read-only
+bindery run phase1 ~/Downloads --apply-lossy --backup /tmp/phase1-backups
+```
+
+**`run phase3 --ids IDS`** (from the library directory) is the post-import
+scoped repair sweep: exactly `library --id IDS --sweep --only all --apply --all
+--install-to-calibre` plus a pre/post epubcheck summary. It mechanically
+refuses an unscoped library-wide sweep with exit 2 (a full-library sweep is a
+dedicated hours-long task, never a verb call), and books left partial or
+unreadable surface as `decisions_needed` in the JSON.
+
+```sh
+cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-report.json
+```
+
 ## 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`):
+`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli 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.
+- `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
 
 ## Development
 
@@ -193,7 +262,7 @@ MIT. See [LICENSE](LICENSE).
 
 ## Support
 
-If Bindery's useful to you and you'd like to chip in:
+If bindery-cli's useful to you and you'd like to chip in:
 
 - liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
 - bitcoin

bindery_cli-0.27.0/PKG-INFO → bindery_cli-0.29.0/README.md

@@ -1,32 +1,16 @@
-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>
+  <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
+  <h1>bindery-cli</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'">
+  <img src="docs/screenshots/library-sweep.png" alt="bindery-cli'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:
+bindery-cli 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.
@@ -54,6 +38,9 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--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.
+- **`--prune-missing-resources`**: removes references to files the archive does not contain (RSC-007/PKG-010): dead `<link>` elements, anchors' `href` to absent files (anchor text preserved), absent `<img>` sources (replaced by their alt text when they carry one), and orphaned non-spine OPF manifest items. Spine documents are never pruned: a missing spine document is reported as a damaged fragment, not silently dropped.
+- **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
+- **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 
 
 Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
@@ -77,7 +64,7 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## 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`.
+Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the 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
@@ -86,14 +73,16 @@ 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).
+Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+reports content flaws without touching anything, `bindery library` sweeps a Calibre
+library tree (dry run by default; `--apply` replaces accepted books atomically in place),
+and `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
+vetting, phase-3 scoped post-import repair) for a calling agent.
 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`.
+bindery-cli 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:
 
@@ -128,6 +117,12 @@ cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
 ```
 `--id` composes with `--tag`: the book is tagged only if the audit flags it.
 
+**Machine-readable reports:** `--json FILE` writes the run's verdicts in the same shape `library --json` uses: one record per book with a `status` (`clean`/`problem`/`error`) and per-analyzer verdicts (`problem`, `status`, `details`), plus the always-on archive/spine verdicts (OK when they were silent). This is the contract downstream consumers of the pre-import vetting slice read.
+```sh
+bindery audit all ~/Downloads/epubs --json vetting-report.json
+```
+With `--id`, `--json` accepts exactly one book id (each single-book run writes the file wholesale).
+
 **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.
@@ -178,7 +173,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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.
+- `--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-cli first tries a persistent Java daemon (`EpubcheckDaemon`) to eliminate the per-book JVM startup; in practice the daemon cannot boot on most installs (its classpath carries only epubcheck's launcher jar, not the `lib/` dependencies epubcheck itself puts on the classpath), and the run silently falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Budget accordingly. Fixing the classpath is a recorded decision (it would also change the counts the gate measures), not a shipped behavior. Combine with `--only fatals` for a self-contained "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.
@@ -189,11 +184,47 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - 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.
 
+## Run slices
+
+`bindery run` wraps the acquisition pathway's EPUB steps as verbs. They add no
+repair classes of their own: they compose the shipped audit and library runners
+in the documented order, and both speak `--json` for a calling agent.
+
+**`run phase1 DIR`** is the pre-import vetting slice for a directory of loose
+files: the audit battery (corruption sweep, content battery, monolithic) in one
+decompression pass per book, then the gated repair sweep (epubcheck, watermark
+detection, repairability) over the same directory. The verb is read-only until
+`--apply-lossy` is passed, and that flag IS the recorded lossy-strip consent;
+`--backup DIR` mirrors originals first (keep backups outside the vetted
+directory). Consent questions never block the verb: a read-only run that finds
+repairable books records an `apply_lossy` entry in the JSON's
+`decisions_needed` instead of prompting, and `--non-interactive` declares that
+contract for callers. Exit codes per the `library` contract: 0 clean, 1 usage,
+2 when any book is flagged, rejected, unreadable, or failed epubcheck (a
+consent question alone is not trouble).
+
+```sh
+bindery run phase1 ~/Downloads --json phase1-report.json               # read-only
+bindery run phase1 ~/Downloads --apply-lossy --backup /tmp/phase1-backups
+```
+
+**`run phase3 --ids IDS`** (from the library directory) is the post-import
+scoped repair sweep: exactly `library --id IDS --sweep --only all --apply --all
+--install-to-calibre` plus a pre/post epubcheck summary. It mechanically
+refuses an unscoped library-wide sweep with exit 2 (a full-library sweep is a
+dedicated hours-long task, never a verb call), and books left partial or
+unreadable surface as `decisions_needed` in the JSON.
+
+```sh
+cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-report.json
+```
+
 ## 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`):
+`scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli 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.
+- `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
 
 ## Development
 
@@ -209,7 +240,7 @@ MIT. See [LICENSE](LICENSE).
 
 ## Support
 
-If Bindery's useful to you and you'd like to chip in:
+If bindery-cli's useful to you and you'd like to chip in:
 
 - liberapay · [liberapay.com/bdkl](https://liberapay.com/bdkl/)
 - bitcoin

{bindery_cli-0.27.0 → bindery_cli-0.29.0}/logo.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="Bindery logo">
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="bindery-cli logo">
   <rect width="128" height="128" rx="24" fill="#181616"/>
   <!-- book spine / cover being rebound -->
   <rect x="30" y="26" width="68" height="76" rx="5" fill="none" stroke="#c5c9c5" stroke-width="5"/>