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

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

@@ -118,7 +118,9 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.46.0 the opt-in selection is the `RepairFlags` dataclass (one field per flag, all off by default; the all-off instance IS the default pass): `repair_epub(src, dst, flags)` and `process_book(..., flags)` take one object instead of a ~25-kwarg signature, the EPUB2-targeted fixes' version gate swaps in a `dataclasses.replace` copy (never mutating the caller's instance), and the plugin's bare `repair_epub(src, dst)` call constructs exactly the all-off default pass. Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
 - `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15; since v0.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
+  custom-rendered and colors itself with the CPython 3.14 argparse theme,
+  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
 - `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `max_log_mb` rotation cap default 2, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
 - `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
 

{bindery_cli-0.47.1 → bindery_cli-0.47.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.47.1
+Version: 0.47.2
 Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
 Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
 Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
@@ -203,6 +203,14 @@ vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery do
 checks the installation (see Install).
 The sections below take each in turn.
 
+Help is two-level: `bindery repair --help` (or `library --help`) lists the
+shared repair flags grouped with one-line descriptions, and
+`bindery repair --help-repairs` prints the full reference carrying every
+flag's long rationale. On a terminal both are ANSI-colored with the same
+theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
+`FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
+them.
+
 ## Auditing
 
 bindery-cli's auditing tool inspects 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-0.47.1 → bindery_cli-0.47.2}/README.md

@@ -176,6 +176,14 @@ vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery do
 checks the installation (see Install).
 The sections below take each in turn.
 
+Help is two-level: `bindery repair --help` (or `library --help`) lists the
+shared repair flags grouped with one-line descriptions, and
+`bindery repair --help-repairs` prints the full reference carrying every
+flag's long rationale. On a terminal both are ANSI-colored with the same
+theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
+`FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
+them.
+
 ## Auditing
 
 bindery-cli's auditing tool inspects 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-0.47.1 → bindery_cli-0.47.2}/patchnotes.md

@@ -1,5 +1,31 @@
 # bindery-cli Patch Notes
 
+## v0.47.2 (2026-10-06)
+
+### The --help-repairs reference keeps argparse's color
+
+The lattice-music lesson, landed here the same day: Python 3.14's argparse
+colors `-h` on terminals by itself, so the argparse-rendered surfaces (the
+top-level help and `-h` for every verb) kept their theme through the
+v0.47.1 restructure untouched. The one gap was the page v0.47.1 added: the
+custom-rendered `--help-repairs` reference printed plain, silently losing
+the colorization every other surface has (the exact regression
+lattice-music repaired in its 6b88a52).
+
+* The reference now paints with the exact CPython 3.14 default theme
+  (bold blue headings, magenta prog, bold cyan long options; read off real
+  3.14 output, so the page reads like the argparse-rendered `-h` beside
+  it) through a single layout path whose disabled style emits empty codes.
+* The color gate IS argparse's own detection (`_colorize.can_colorize` on
+  3.14+; plain False below 3.14, where argparse has no colorization to
+  match), so the two help levels can never disagree: verified under a pty
+  that `--help-repairs` carries the same code vocabulary as `-h` and that
+  `TERM=dumb` and `NO_COLOR` silence both, and that piped output stays
+  plain for README embedding and tests.
+* Four new tests: the theme codes, the strip invariant (colored, codes
+  stripped == plain, byte for byte), pipe safety, and gate tracking.
+  TestHelpLayout is now nine; suite: 624.
+
 ## v0.47.1 (2026-10-06)
 
 ### The two-level help: compact grouped --help, full --help-repairs reference

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.47.1"
+version = "0.47.2"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [

{bindery_cli-0.47.1 → bindery_cli-0.47.2}/src/bindery/__init__.py

@@ -11,7 +11,7 @@ Calibre plugin built from this core.
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.47.1"
+VERSION = "0.47.2"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

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

@@ -1642,6 +1642,84 @@ _REPAIR_FLAG_TABLE: dict[str, list[tuple[str, str, str]]] = {
 }
 
 
+# The --help-repairs page is custom-rendered (not argparse output), so it
+# paints itself with the exact CPython 3.14 argparse default theme
+# (ColorfulTheme: bold blue headings, magenta prog, bold cyan long options
+# -- read off real 3.14 output, so the page reads like the argparse-rendered
+# -h beside it). This is the lattice-music lesson (6b88a52 there): a custom
+# help renderer that prints plain silently loses the colorization argparse
+# gives every other surface.
+_THEME = {
+    "heading": "\x1b[1;34m",
+    "prog": "\x1b[35m",
+    "long_option": "\x1b[1;36m",
+    "reset": "\x1b[0m",
+}
+
+
+def _can_color_help() -> bool:
+    """True exactly when argparse itself would colorize -h here: CPython
+    3.14's own detection (_colorize.can_colorize: PYTHON_COLORS, NO_COLOR,
+    FORCE_COLOR, TERM=dumb, isatty), so the two help levels can never
+    disagree about color. Plain False below 3.14, where argparse has no
+    colorization to match."""
+    if sys.version_info < (3, 14):
+        return False
+    from _colorize import can_colorize
+
+    return can_colorize()
+
+
+def _repair_flag_reference(color: bool | None = None) -> str:
+    """The full repair-flag reference: the _REPAIR_FLAG_TABLE rows with
+    their long descriptions. `color=None` decides by the same gate argparse
+    uses; the disabled style emits empty codes, so one layout path serves
+    both faces and the strip invariant (colored, codes stripped == plain)
+    holds by construction."""
+    if color is None:
+        color = _can_color_help()
+    if color:
+        heading, prog, option, reset = (
+            _THEME["heading"],
+            _THEME["prog"],
+            _THEME["long_option"],
+            _THEME["reset"],
+        )
+    else:
+        heading = prog = option = reset = ""
+    lines = [
+        prog
+        + "bindery"
+        + reset
+        + " repair-flag reference (shared by `bindery repair` and "
+        "`bindery library`)",
+        "",
+        "The always-on core pass is exactly five well-formedness fixes, the NCX",
+        "pipeline, and the mimetype fix. Everything below is opt-in, and every",
+        "repair is epubcheck-gated: applied only when the measured result improved",
+        "(lossy strips: only when it did not get worse). Library mode is dry-run",
+        "by default; `--all` enables every flag below at once. The README and",
+        "spec.md carry the full rationale for each repair.",
+    ]
+    for title, rows in _REPAIR_FLAG_TABLE.items():
+        lines.append("")
+        lines.append(heading + title + reset)
+        lines.append("")
+        for dest, _short, long_help in rows:
+            lines.append("  " + option + "--" + dest.replace("_", "-") + reset)
+            for para in long_help.split("\n"):
+                lines.extend(
+                    textwrap.wrap(
+                        para,
+                        width=88,
+                        initial_indent="      ",
+                        subsequent_indent="      ",
+                    )
+                    or ["     "]
+                )
+    return "\n".join(lines)
+
+
 class _HelpRepairsAction(argparse.Action):
     """The second help level: print the full repair-flag reference and exit.
 
@@ -1665,35 +1743,7 @@ class _HelpRepairsAction(argparse.Action):
         )
 
     def __call__(self, parser, namespace, values, option_string=None):
-        lines = [
-            "bindery repair-flag reference (shared by `bindery repair` and "
-            "`bindery library`)",
-            "",
-            "The always-on core pass is exactly five well-formedness fixes, the NCX",
-            "pipeline, and the mimetype fix. Everything below is opt-in, and every",
-            "repair is epubcheck-gated: applied only when the measured result improved",
-            "(lossy strips: only when it did not get worse). Library mode is dry-run",
-            "by default; `--all` enables every flag below at once. The README and",
-            "spec.md carry the full rationale for each repair.",
-        ]
-        for title, rows in _REPAIR_FLAG_TABLE.items():
-            lines.append("")
-            lines.append(title)
-            lines.append("")
-            for dest, _short, long_help in rows:
-                option = "--" + dest.replace("_", "-")
-                lines.append(f"  {option}")
-                for para in long_help.split("\n"):
-                    lines.extend(
-                        textwrap.wrap(
-                            para,
-                            width=88,
-                            initial_indent="      ",
-                            subsequent_indent="      ",
-                        )
-                        or ["     "]
-                    )
-        print("\n".join(lines))
+        print(_repair_flag_reference())
         parser.exit(0)
 
 

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

@@ -1866,6 +1866,54 @@ class TestHelpLayout(unittest.TestCase):
             self.assertIn("XML NameChar set", text, verb)
             self.assertIn("no-worse", text, verb)
 
+    def test_help_repairs_theme_codes_when_colored(self):
+        from bindery import cli
+
+        text = cli._repair_flag_reference(color=True)
+        # the exact CPython 3.14 argparse theme: heading blue, prog magenta,
+        # long-option cyan
+        self.assertIn("\x1b[1;34m", text)
+        self.assertIn("\x1b[35mbindery\x1b[0m", text)
+        self.assertIn("\x1b[1;36m--fix-ids\x1b[0m", text)
+        self.assertIn("\x1b[1;34mlossy strips", text)
+
+    def test_help_repairs_strip_invariant(self):
+        # colored, codes stripped == plain, byte for byte: one layout path
+        # serves both faces (the lattice-music invariant)
+        import re
+
+        from bindery import cli
+
+        colored = cli._repair_flag_reference(color=True)
+        plain = cli._repair_flag_reference(color=False)
+        self.assertEqual(re.sub(r"\x1b\[[0-9;]*m", "", colored), plain)
+
+    def test_help_repairs_piped_output_is_plain(self):
+        # a pipe (tests, README embedding) never carries codes
+        for verb in ("repair", "library"):
+            buf = io.StringIO()
+            with self.assertRaises(SystemExit), contextlib.redirect_stdout(buf):
+                main([verb, "--help-repairs"])
+            self.assertNotIn("\x1b[", buf.getvalue(), verb)
+
+    def test_help_gate_tracks_argparse(self):
+        # the gate IS argparse's own detection on 3.14+ (so -h and
+        # --help-repairs can never disagree); plain False below, where
+        # argparse has no colorization
+        import os
+
+        from bindery import cli
+
+        if sys.version_info < (3, 14):
+            self.assertFalse(cli._can_color_help())
+            return
+        from _colorize import can_colorize
+
+        self.assertEqual(cli._can_color_help(), can_colorize())
+        # NO_COLOR suppresses on every interpreter
+        with mock.patch.dict(os.environ, {"NO_COLOR": "1"}):
+            self.assertFalse(cli._can_color_help())
+
     def test_help_repairs_is_not_a_selection_flag(self):
         # _HelpRepairsAction is deliberately not a store_true: the wiring
         # test counts store_true dests as repair selections

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

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