bindery-cli 0.33.0__tar.gz → 0.34.0__tar.gz

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.33.0
+Version: 0.34.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
@@ -209,7 +209,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - 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). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1.
-- A `partial` book (improved but still unable to open) is reported for manual follow-up and does not fail a `library` run; `run phase1` counts it as trouble and exits 2.
+- A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
 ## Run slices

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/README.md

@@ -187,7 +187,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - 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). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1.
-- A `partial` book (improved but still unable to open) is reported for manual follow-up and does not fail a `library` run; `run phase1` counts it as trouble and exits 2.
+- A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
 ## Run slices

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/patchnotes.md

@@ -1,4 +1,40 @@
 # bindery-cli Patch Notes
+## v0.34.0 (2026-09-10)
+
+### Brandon's three calls: partial books are trouble, the contract reconciled, the daemon decision informed
+
+- **Partial books now fail every layer (exit-code decision, option A).**
+  A `partial` book (repaired, improved, but still unable to open) used to
+  exit 0 from `library` and `run phase3` while `run phase1` counted it
+  as trouble. All three layers now exit 2 on it: the run succeeded, but
+  a book still needs a human. README and spec updated to match, and a
+  regression test pins a 3f-to-1f book exiting 2 with `applied: 0`.
+- **spec.md reconciled with the shipped opt-ins** (applied on Brandon's
+  go, from the draft filed in v0.33.0's roadmap box). The non-goals no
+  longer prohibit what ships: "fixing RSC-005 in bulk" now names the
+  scoped, version-gated repairs as the shipped exception, and "repairing
+  genuinely mangled structure" now describes `--reserialize`'s actual
+  bounds (html root required, non-HTML XML sidecars refused). The
+  missing `--fix-ids` OPF section is written (manifest item ids, spine
+  idref/toc, fallback, media-overlay, EPUB 2 cover meta, both quote
+  styles), the garbled NCX sentence is rewritten, and "the OPF is left
+  untouched" now reads "by the default pass", naming the five opt-ins
+  that edit it on request.
+- **The daemon decision, informed:** Brandon asked whether upgrading
+  java to 27 fixes the epubcheck daemon. Investigated and answered: his
+  javac is Fedora's `java-latest-openjdk-devel` 27-ea while `java` is
+  `java-25-openjdk` (both official Fedora packages, no COPR involved),
+  but the version skew is not the real blocker. epubcheck's own JSON
+  output is deduplicated (it reports 4 errors for a book whose CLI
+  summary says 243), the daemon counts everything, and bindery's gate
+  has always measured with JSON-style counts, so a working daemon would
+  change what the gate measures. The skew itself is fixable in code
+  (Java's single-file source launcher needs no javac at all), but the
+  daemon should stay off until its counting matches the JSON oracle; it
+  already self-disables safely, and `--workers` parallelism works via
+  subprocesses. Retire-or-reconcile remains the open decision; recorded
+  in the roadmap's `:958` box.
+
 ## v0.33.0 (2026-09-10)
 
 ### Phase 14 hardening: the apply path, the audit, and the safety contract's tests
@@ -24,14 +60,14 @@ regression test.
   bounded pool sized by `--workers` (default 1: the old behavior), a
   busy pool falls back to subprocesses instead of blocking, every
   roundtrip is bounded by the caller's timeout, and a daemon that dies
-  or wedges is torn down and never retried — one failed attempt exhausts
-  the pool so the sweep degrades to pure subprocess checks instead of
+  or wedges is torn down and never retried; one failed attempt exhausts
+  the pool, so the sweep degrades to pure subprocess checks instead of
   respawning a JVM per book. Measured: 8 books, 4 workers, two ~10s
   waves. The evidence for the recorded daemon-classpath decision grew:
   this machine's javac (27-ea) and java (25) cannot load each other's
   classes, so the daemon has never served a count here, and when forced
   to run its counts diverge from the CLI JSON oracle (243 vs 4 on one
-  book) — enabling it would change gate outcomes.
+  book): enabling it would change gate outcomes.
 - **Smaller apply papercuts:** `--limit < 1` and a missing `--audit`
   file are usage errors, not tracebacks; the fresh-format install
   registers the catalogued file's own name instead of `repaired`; and

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/pyproject.toml

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

@@ -1068,7 +1068,7 @@ can be net-neutral and ships silently.*
       and JSON with exit 2; the resumable run journal is deliberately not
       built, since isolation plus `--json` already preserves the record
       and the journal is a second write surface next to the library.)*
-- [ ] **Drive the exit code from partial books.** The documented contract
+- [x] **Drive the exit code from partial books.** The documented contract
       says exit 2 means "ran fine but some books are in trouble", but
       partial books land in `still_fatal` and return 0, in both `library`
       and phase3, while phase1 maps partial to problem/exit 2; the layers
@@ -1089,6 +1089,11 @@ can be net-neutral and ships silently.*
       cost: scripts that care must parse the report, and the contract's
       exit-2 sentence stays subtly incomplete.
       Either way the exit-code documentation lands with the decision.
+      *(DECIDED 2026-09-10: option A, "unify on trouble". `run_library`
+      now folds `partials` into its trouble exit, and phase3 propagates
+      that rc, so all three layers exit 2 on a partial book. README and
+      spec updated to match; regression test pins a 3f->1f book exiting
+      2 with applied=0. Shipped in v0.34.0.)*
 - [x] **Give backups overwrite protection and keep them out of the
       candidate set.** `make_backup` clobbers an existing backup, so a
       second `--apply` destroys the only copy of the author original
@@ -1137,7 +1142,21 @@ can be net-neutral and ships silently.*
       `--only ncx` encrypted-archive crash is also fixed here:
       `ncx_uid_mismatch` now catches the RuntimeError that `z.read`
       raises on zip-encrypted entries, so a DRM'd book is not a candidate
-      rather than a crash.)*
+      rather than a crash.)
+      *(DECISION NOTE 2026-09-10: Brandon asked whether upgrading his
+      java to 27 would fix the daemon. Answered no: his javac is Fedora's
+      java-latest-openjdk-devel 27-ea while java is java-25-openjdk (both
+      official Fedora packages, no COPR involved), but the version skew
+      is not the real blocker: epubcheck's own JSON output is
+      deduplicated (it reports 4 errors for a book its CLI summary calls
+      243), the daemon counts everything, and bindery's gate has always
+      measured with JSON-style counts. Upgrading java would make the
+      daemon boot and start feeding different numbers into the gate. The
+      skew itself is fixable in code (single-file source launcher, no
+      javac at all), but the daemon should stay off until its counting
+      matches the JSON oracle; retire-or-reconcile remains the open
+      decision. The daemon already self-disables safely, and --workers
+      parallelism works via subprocesses.)**
 - [x] **Smaller apply papercuts:** `--limit -1` and a missing
       `--audit` file raise tracebacks instead of usage errors
       (`cli.py:434`, `373`); the fresh-format branch of `install_format`

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/spec.md

@@ -50,7 +50,11 @@ Applied to content documents (`.xhtml`, `.html`, `.htm`, `.xml`), in order:
    change what renders. Removed end tags are counted in the fix total.
 
 Applied to the NCX sidecar (`.ncx`): strip_prolog_junk, escape_bare_amp,
-fix_named_entities, plus **dtb:uid sync**, **fix_ncx_playorder** (sequentially rewrites duplicate playOrder attributes)  to the OPF unique identifier (NCX-001).
+fix_named_entities, plus **dtb:uid sync** (rewriting the NCX's `dtb:uid`
+meta to match the OPF's unique identifier when they drift, NCX-001) and
+**fix_ncx_playorder** (resequencing `playOrder` attributes on
+`<navPoint>` start tags so they are strictly sequential; nav-label text
+is never touched).
 With `--fix-ids`, ids in the NCX that are not valid XML names (digit-led, as when a
 converter stamps navPoint ids from UUIDs; colon-bearing) are renamed with the same
 `id_` scheme as OPF manifest ids. NCX ids are internal to the NCX (nothing in the
@@ -58,7 +62,10 @@ OPF or content documents references them), so the rename needs no cross-file
 bookkeeping.
 
 The OPF is located via `META-INF/container.xml` (falling back to the first `.opf`
-in the archive) and is left untouched, to keep Calibre's embedded metadata pristine.
+in the archive). The default pass leaves it untouched, to keep Calibre's embedded
+metadata pristine; the opt-in `--fix-ids`, `--strip-epub3-attrs`, `--fix-page-map`,
+`--prune-missing-resources`, and `--encode-url-spaces` each edit it when requested,
+and the human-facing `dc:` metadata is never altered by any of them.
 
 ### Opt-in: escape unknown entities (`--escape-unknown-entities`)
 
@@ -97,6 +104,12 @@ part of the default pipeline:
   external URL names a position in that other document and survives verbatim, and the
   NCX's `content src` fragments follow the rename (`fix_ncx_src_fragments`), so a ToC
   never dangles against the ids it references.
+- **`--fix-ids`**: renames manifest `item` ids that are not valid XML names
+  (digit-led, colon-bearing) with the deterministic `id_` scheme, and updates
+  every reference to them: spine `idref` and `toc`, item `fallback` and
+  `media-overlay`, and the EPUB 2 cover meta, in both quote styles. NCX ids are
+  renamed by the same pass (`fix_ncx_ids`); colon-bearing fragments follow the
+  rename via `--fix-id-colons`' NCX half. Href paths and filenames are untouched.
 - **`--unwrap-block-in-inline`**: drop a `<span>` that illegally wraps a
   `<div>/<p>/<blockquote>`, keeping the block element and its text.
 - **`--strip-invalid-value`**: remove misplaced `value="..."` attributes from non-form
@@ -302,8 +315,8 @@ For a Calibre library (`Author/Title (id)/Title - Author.epub`):
   book was rejected, unreadable, or failed epubcheck, so scripts can detect trouble.
   Argparse-level misuse (unknown flag, malformed argument) exits 2 before the tool's
   own validation runs; the tool's own usage validations exit 1. A `partial` book
-  (improved but still fatal) is reported for manual follow-up and does not fail the
-  run; `run phase1` counts it as trouble.
+  (improved but still fatal) is reported for manual follow-up and counts as trouble:
+  `library`, `run phase1`, and `run phase3` all exit 2 on it (unified 2026-09-10).
 - With `--sweep`, `--workers N` runs the candidate-selection epubcheck pass through N
   concurrent workers (default 1: serial, unchanged). Books are checked in windows of N
   consumed in input order, so the candidate set and the before-measurements are identical
@@ -376,7 +389,15 @@ verb call). Books left partial or unreadable surface as `decisions_needed`.
 
 ## Out of scope (non-goals)
 
-- Fixing RSC-005 schema/content-model violations in bulk.
-- Repairing genuinely mangled structure (unclosed non-void elements, corrupted tag
-  names, embedded VML/SVG). These are detected as `partial`/`nochange` and reported.
+- Fixing RSC-005 schema/content-model violations *in bulk*: the scoped, opt-in
+  RSC-005 repairs (`--strip-epub3-attrs`, `--downgrade-epub3-tags`, both gated on
+  the package version) ship and stay, but an indiscriminate RSC-005 sweep remains
+  out of scope.
+- Repairing genuinely mangled structure remains opt-in and bounded:
+  `--reserialize` (the lone html5lib dependency) re-parses malformed documents
+  carrying an `<html>` root and re-emits XHTML, refusing non-HTML XML sidecars;
+  corrupted tag names are covered by `--strip-bad-attrs` and
+  `--unwrap-illegal-tags`. Wholesale structural rewrites without a root to anchor
+  on stay out of scope, and anything the opt-ins cannot make deterministically
+  safe is detected as `partial`/`nochange` and reported.
 - Editing human-facing dc: metadata or creating content.

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/src/bindery/__init__.py

@@ -4,7 +4,7 @@ strip), epubcheck-gated.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.33.0"
+VERSION = "0.34.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/src/bindery/cli.py

@@ -680,7 +680,12 @@ def run_library(args) -> int:
 
     # 2 lets scripts and cron distinguish "ran fine but some books are in trouble"
     # from a clean sweep (0) and a usage error (1).
-    return 2 if (rejected + errors + unreadable) > 0 else 0
+    # Exit codes per the documented contract, unified on "trouble" (Brandon's
+    # option-A call, 2026-09-10): a partial book (improved but still unable
+    # to open) IS trouble -- the run itself succeeded, but a book still needs
+    # a human. phase1 already mapped partial to 2; library and phase3 (which
+    # propagates this rc) now agree with it.
+    return 2 if (rejected + errors + unreadable + partials) > 0 else 0
 
 
 def run_repair(args) -> int:

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/tests/test_cli.py

@@ -1309,3 +1309,46 @@ class TestSweepWorkers(unittest.TestCase):
         self.assertEqual(rc, 0)
         # 1 sweep call + 1 after-validation on the single candidate
         self.assertEqual(len(checked), 2)
+
+
+class TestPartialBooksAreTrouble(unittest.TestCase):
+    """Brandon's option-A call (2026-09-10): a partial book (improved but
+    still unable to open) is trouble -- library and phase3 exit 2 on it,
+    agreeing with phase1's existing mapping."""
+
+    def test_library_exits_2_on_a_partial_book(self):
+        with tempfile.TemporaryDirectory() as td:
+            root = Path(td)
+            _phase1_book(root / "a.epub", broken=True)
+            jout = root / "lib.json"
+            results = [
+                CheckResult(3, 0, 0),  # the sweep's before-measurement
+                CheckResult(1, 0, 0),  # after: fewer fatals, still fatal
+            ]
+            out, err = io.StringIO(), io.StringIO()
+            with (
+                mock.patch("bindery.cli.epubcheck_available", return_value=True),
+                mock.patch("bindery.cli.run_epubcheck", side_effect=results),
+                redirect_stdout(out),
+                redirect_stderr(err),
+            ):
+                rc = cli.run_library(
+                    build_parser().parse_args(
+                        [
+                            "library",
+                            str(root),
+                            "--sweep",
+                            "--only",
+                            "all",
+                            "--all",
+                            "--apply",
+                            "--json",
+                            str(jout),
+                        ]
+                    )
+                )
+            data = json.loads(jout.read_text())
+        self.assertEqual(rc, 2)
+        self.assertEqual(data["summary"]["partial"], 1)
+        # a partial book is never auto-applied
+        self.assertEqual(data["summary"]["applied"], 0)

{bindery_cli-0.33.0 → bindery_cli-0.34.0}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.14"
 
 [[package]]
 name = "bindery-cli"
-version = "0.33.0"
+version = "0.34.0"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry" },