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

{bindery_cli-0.47.1 → bindery_cli-0.48.0}/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.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.47.1
+Version: 0.48.0
 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.48.0}/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.48.0}/patchnotes.md

@@ -1,5 +1,61 @@
 # bindery-cli Patch Notes
 
+## v0.48.0 (2026-10-06)
+
+### The closed-Calibre guard, stated contracts, and --help-json
+
+The AI-grokability probe (a fresh agent learning the CLI from help
+alone, the same method CalibreQuarry ran) confirmed the repair-semantics
+help is complete and found the cross-cutting contracts missing. Three
+fixes:
+
+- **The closed-Calibre gate is enforced, not just stated.** audit
+  --tag and library --apply --install-to-calibre both write
+  metadata.db, and nothing stopped that write under a live Calibre
+  (WritableCalibreDB waits on the sqlite lock and proceeds; a running
+  Calibre holds no persistent exclusive lock). Both doors now share a
+  fail-closed pgrep refusal (exit 1: an environment condition, not a
+  usage error), and --install-to-calibre's help says so.
+- **The help states the contracts** the probe could not find: exit
+  codes on the repair, library, and run-slice pages (0 clean, 2
+  trouble, 1 invocation problem); neither mode ever prompts (--apply is
+  the only confirmation); an existing output without --force is exit 1;
+  NCX-001 defined (toc.ncx dtb:uid != the OPF unique-identifier); --id
+  works without --sweep; the repair and library --json envelopes name
+  their keys.
+- **--help-json**: the complete surface (subcommands with every flag,
+  the run slices, the full repair reference, the exit contract, the
+  Calibre gates) as deterministic JSON, generated from the live parser
+  and _REPAIR_FLAG_TABLE, never colored.
+
+15 new tests (639 total).
+
+## 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.48.0}/pyproject.toml

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

@@ -41,6 +41,7 @@ The plugin vendors the core and never gates (the epubcheck latency ruling).
 | 0.45 | Structured fix records (`fixes`, `ncx_uid_synced`, `watermark_refusals`) in every JSON payload; CalibreQuarry consumes them with the 0.45.0 floor | v0.45.0 |
 | 0.46 | RSC-016 `--fix-comment-double-hyphen` (the last open repair class) and the RepairFlags dataclass | v0.46.0 |
 | 0.47 | The intake-wave batch (five open issues): the stub classifier's body-pool + image-carrier exemption, the NCName-complete `--fix-ids`, and `--fix-svg-dup-ids`, `--fix-cdata-terminator`, `--fix-misnested-inline`, `--fix-stray-close`, `--fix-unterminated-attr` | v0.47.0 |
+| 0.48 | The AI-probe batch: the enforced closed-Calibre gate on both metadata.db doors (`audit --tag`, `library --apply --install-to-calibre`), the stated contracts (exit codes, no-prompt, NCX-001, --id scoping, json envelope keys), and `--help-json` | v0.48.0 |
 
 ## Open work
 

{bindery_cli-0.47.1 → bindery_cli-0.48.0}/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.48.0"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

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

@@ -395,8 +395,155 @@ def _epubs_for_ids(root: Path, id_csv: str) -> list[Path] | None:
     return epubs
 
 
+class _HelpJsonAction(argparse.Action):
+    """The machine surface: dump the complete CLI surface as JSON and exit.
+    Like _HelpRepairsAction, deliberately not a store_true dest, and never
+    colored: the output must stay valid JSON under any environment."""
+
+    def __init__(
+        self,
+        option_strings,
+        dest=argparse.SUPPRESS,
+        default=argparse.SUPPRESS,
+        help=None,
+    ):
+        super().__init__(
+            option_strings=option_strings,
+            dest=dest,
+            default=default,
+            nargs=0,
+            help=help,
+        )
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        payload = {
+            "tool": "bindery",
+            "version": __version__,
+            "exit_contract": {
+                "0": "clean",
+                "1": "invocation problem (bad args; repair: existing output "
+                "without --force); lock-class refusals (Calibre open at a "
+                "metadata.db door)",
+                "2": "trouble found (rejected/error/unreadable/partial "
+                "books; unscoped phase3 sweep); argparse usage errors",
+                "130": "interrupted",
+            },
+            "calibre_gates": [
+                "audit --tag",
+                "library --apply --install-to-calibre",
+            ],
+            "subcommands": [],
+            "repair_reference": [
+                {
+                    "group": title,
+                    "flags": [
+                        {"dest": dest, "summary": summary, "reference": long}
+                        for dest, summary, long in rows
+                    ],
+                }
+                for title, rows in _REPAIR_FLAG_TABLE.items()
+            ],
+        }
+        subparsers = next(
+            (a for a in parser._actions if isinstance(a, argparse._SubParsersAction)),
+            None,
+        )
+        sub_helps = (
+            {pa.dest: pa.help for pa in subparsers._choices_actions}
+            if subparsers
+            else {}
+        )
+        for name, sub in subparsers.choices.items() if subparsers else []:
+
+            def sub_flags(subparser):
+                out = []
+                for group in subparser._action_groups:
+                    for action in group._group_actions:
+                        if action.dest in ("help",):
+                            continue
+                        entry = {
+                            "flags": list(action.option_strings) or [action.dest],
+                            "dest": action.dest,
+                            "help": " ".join((action.help or "").split()),
+                        }
+                        if action.metavar:
+                            met = action.metavar
+                            entry["metavar"] = (
+                                " ".join(met) if isinstance(met, tuple) else met
+                            )
+                        if action.choices:
+                            entry["choices"] = [str(c) for c in action.choices]
+                        out.append(entry)
+                return out
+
+            payload["subcommands"].append(
+                {
+                    "name": name,
+                    "help": " ".join((sub_helps.get(name) or "").split()),
+                    "description": " ".join((sub.description or "").split()),
+                    "flags": sub_flags(sub),
+                    "flag_groups": [
+                        {
+                            "title": group.title,
+                            "flags": [
+                                " ".join((a.help or "").split())
+                                for a in group._group_actions
+                                if a.dest != "help"
+                            ],
+                        }
+                        for group in sub._action_groups
+                        if group.title
+                    ],
+                }
+            )
+        # the run slices are one level deeper
+        run_choice = subparsers.choices.get("run") if subparsers else None
+        if run_choice is not None:
+            run_subs = next(
+                (
+                    a
+                    for a in run_choice._actions
+                    if isinstance(a, argparse._SubParsersAction)
+                ),
+                None,
+            )
+            run_entry = next(
+                (s for s in payload["subcommands"] if s["name"] == "run"),
+                None,
+            )
+            if (
+                run_choice is not None
+                and run_subs is not None
+                and run_entry is not None
+            ):
+                slice_helps = {pa.dest: pa.help for pa in run_subs._choices_actions}
+                run_entry["slices"] = [
+                    {
+                        "name": name,
+                        "help": " ".join((slice_helps.get(name) or "").split()),
+                        "flags": [
+                            {
+                                "flags": list(a.option_strings) or [a.dest],
+                                "dest": a.dest,
+                                "help": " ".join((a.help or "").split()),
+                            }
+                            for group in sub._action_groups
+                            for a in group._group_actions
+                            if a.dest != "help"
+                        ],
+                    }
+                    for name, sub in run_subs.choices.items()
+                ]
+        print(json.dumps(payload, indent=1, sort_keys=True))
+        raise SystemExit(0)
+
+
 def run_library(args) -> int:
     root = Path(args.path).expanduser()
+    if args.apply and args.install_to_calibre:
+        rc = _require_closed_calibre("--apply --install-to-calibre")
+        if rc:
+            return rc
     # cquarry-backed id resolution for --install-to-calibre: one lazy map
     # build per run, read-only against metadata.db.
     id_resolver = CalibreIdResolver(root)
@@ -1642,6 +1789,115 @@ _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)
+
+
+def _calibre_running() -> bool:
+    """pgrep -x calibre. Fail-closed: this gates a metadata.db write, and
+    an unrunnable or timed-out pgrep means "can't tell", so the safe
+    answer is running (refusing costs a closed-Calibre re-run; guessing
+    wrong writes underneath a live Calibre)."""
+    try:
+        return (
+            subprocess.run(
+                ["pgrep", "-x", "calibre"], capture_output=True, timeout=10
+            ).returncode
+            == 0
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return True
+
+
+def _require_closed_calibre(door: str) -> int:
+    """The lock-class refusal shared by the metadata.db write doors
+    (`audit --tag`, `library --apply --install-to-calibre`). Exit 1, not
+    a usage error: an open Calibre is an environment condition, exactly
+    like the companion tools' convention (usage problems exit 2)."""
+    if _calibre_running():
+        print(
+            f"ERROR: Calibre is running; close it before {door} "
+            "(the write goes through metadata.db).",
+            file=sys.stderr,
+        )
+        return 1
+    return 0
+
+
 class _HelpRepairsAction(argparse.Action):
     """The second help level: print the full repair-flag reference and exit.
 
@@ -1665,35 +1921,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)
 
 
@@ -1731,6 +1959,10 @@ def _add_repair_flags(p: argparse.ArgumentParser) -> None:
 
 
 def run_audit_cmd(args: argparse.Namespace) -> int:
+    if getattr(args, "tag", None):
+        rc = _require_closed_calibre("audit --tag")
+        if rc:
+            return rc
     selected = list(ALL) if args.mode == "all" else [args.mode]
     max_doc = args.max_doc_chars
     if args.min_chars > args.thin_chars:
@@ -1803,6 +2035,12 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     ap.add_argument("--version", action="version", version=f"bindery {__version__}")
+    ap.add_argument(
+        "--help-json",
+        action=_HelpJsonAction,
+        help="dump the complete CLI surface (subcommands, flags, the "
+        "repair reference, the exit contract) as JSON and exit",
+    )
     sub = ap.add_subparsers(dest="cmd", required=True)
 
     r = sub.add_parser(
@@ -1812,7 +2050,10 @@ def build_parser() -> argparse.ArgumentParser:
         description="Repair one EPUB into a new file with the epubcheck-gated "
         "core pass: the five well-formedness fixes, the NCX pipeline, and the "
         "mimetype fix run always; every other repair is opt-in (grouped "
-        "below) and applied only when epubcheck confirms the result improved.",
+        "below) and applied only when epubcheck confirms the result improved. "
+        "Never prompts. Exit codes: 0 clean, 2 trouble found (repairs refused "
+        "or failed; --json carries the records), 1 invocation problem (bad "
+        "args, or an existing output without --force).",
         epilog="examples:\n"
         "  bindery repair book.epub out.epub\n"
         "  bindery repair book.epub out.epub --all\n"
@@ -1832,8 +2073,9 @@ def build_parser() -> argparse.ArgumentParser:
         "--json",
         dest="json_path",
         metavar="FILE",
-        help="write a machine-readable report (status, before/after counts, "
-        "fix summary) in the library --json per-book shape",
+        help="write a machine-readable report: one record per file with "
+        "mode, path, output, status, before, after, and the per-fix "
+        "summary (the library --json per-book shape)",
     )
     _add_repair_flags(r)
     r.set_defaults(func=run_repair)
@@ -1920,7 +2162,11 @@ def build_parser() -> argparse.ArgumentParser:
         description="Scan a Calibre library tree for repair candidates and "
         "repair them in place. Dry run by default; --apply atomically "
         "replaces accepted books. Shares the repair-flag set with `bindery "
-        "repair` (--all enables every opt-in).",
+        "repair` (--all enables every opt-in). Never prompts: --apply is "
+        "the only confirmation. Exit codes: 0 all clean, 2 any "
+        "flagged/rejected/error/partial book, 1 invocation problem. "
+        "--apply --install-to-calibre writes metadata.db and demands a "
+        "closed Calibre (refused, exit 1, while it runs).",
         epilog="examples:\n"
         "  bindery library ~/docs/Calibre\\ Library --sweep\n"
         "  bindery library ~/docs/Calibre\\ Library --id 1234 --apply "
@@ -1938,7 +2184,8 @@ def build_parser() -> argparse.ArgumentParser:
         "--only",
         choices=("fatals", "ncx", "all"),
         default="all",
-        help="restrict to books with fatals, NCX-001 mismatch, or all (default)",
+        help="restrict to books with fatals, the NCX-001 mismatch "
+        "(toc.ncx dtb:uid != the OPF unique-identifier), or all (default)",
     )
     rc.add_argument(
         "--limit", type=int, help="process at most N candidates (for sampling)"
@@ -1971,9 +2218,9 @@ def build_parser() -> argparse.ArgumentParser:
         "--id",
         default="",
         metavar="IDS",
-        help="comma-separated Calibre book ids to scope the sweep to "
-        "(resolved via cquarry's get_format_path; mutually exclusive with "
-        "--audit)",
+        help="comma-separated Calibre book ids to scope the run to "
+        "(resolved via cquarry's get_format_path; works without --sweep, "
+        "since ids replace the tree walk; mutually exclusive with --audit)",
     )
     bk = lib.add_argument_group("backups")
     bk.add_argument("--backup", help="directory to mirror backups into before --apply")
@@ -1994,7 +2241,7 @@ def build_parser() -> argparse.ArgumentParser:
     out.add_argument(
         "--json",
         metavar="FILE",
-        help="write a machine-readable JSON report of the run to FILE",
+        help="write a machine-readable JSON report of the run to FILE Top-level envelope keys: mode (apply|dry-run), root, only, validate, candidates, summary",
     )
     out.add_argument(
         "--manual-list",
@@ -2005,7 +2252,7 @@ def build_parser() -> argparse.ArgumentParser:
     out.add_argument(
         "--install-to-calibre",
         action="store_true",
-        help="with --apply, re-register the format natively in metadata.db "
+        help="Calibre must be closed for this door (the row write goes through metadata.db; refused with exit 1 while it runs). with --apply, re-register the format natively in metadata.db "
         "through cquarry's write module (remove + add in one transaction) "
         "instead of a bare filesystem replace",
     )
@@ -2024,7 +2271,9 @@ def build_parser() -> argparse.ArgumentParser:
         "phase1",
         help="the EPUB pre-import vetting slice over a directory of loose "
         "files: corruption sweep, epubcheck, content battery, monolithic, "
-        "watermark detection, repairability. Read-only without --apply-lossy",
+        "watermark detection, repairability. Read-only without --apply-lossy. "
+        "Exit codes: 0 clean, 2 trouble (reject/partial/error/unreadable "
+        "books; decisions_needed in --json), 1 invocation problem",
     )
     p1.add_argument("path")
     p1.add_argument(
@@ -2060,7 +2309,8 @@ def build_parser() -> argparse.ArgumentParser:
         help="the post-import scoped repair sweep: library --id <ids> --sweep "
         "--only all --apply --all --install-to-calibre with a pre/post "
         "summary. Refuses unscoped library-wide sweeps (exit 2); run from "
-        "the library directory",
+        "the library directory. Exit codes follow library's: 0 clean, "
+        "2 trouble, 1 invocation problem",
     )
     p3.add_argument(
         "--ids",

{bindery_cli-0.47.1 → bindery_cli-0.48.0}/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.48.0/tests/test_help.py

@@ -0,0 +1,198 @@
+"""Tests for the help-surface truth set and the machine surface: the
+fail-closed Calibre guard on the metadata.db write doors, the contracts
+the AI-grokability probe found missing from help (exit codes, the gate,
+NCX-001, --id scoping, the json envelopes), and --help-json."""
+
+import argparse
+import contextlib
+import io
+import json
+import unittest
+from types import SimpleNamespace
+from unittest import mock
+
+from bindery import __version__, cli
+
+
+class TestCalibreGuard(unittest.TestCase):
+    """The lock-class refusal on audit --tag and library --apply
+    --install-to-calibre: fail-closed pgrep, exit 1, before any work."""
+
+    def test_refuses_when_calibre_runs(self):
+        with mock.patch.object(cli, "_calibre_running", return_value=True):
+            rc = cli._require_closed_calibre("the door")
+        self.assertEqual(rc, 1)
+
+    def test_passes_when_calibre_closed(self):
+        with mock.patch.object(cli, "_calibre_running", return_value=False):
+            rc = cli._require_closed_calibre("the door")
+        self.assertEqual(rc, 0)
+
+    def test_pgrep_failure_is_fail_closed(self):
+        # an unrunnable pgrep means "can't tell": refuse
+        with mock.patch.object(
+            cli.subprocess,
+            "run",
+            side_effect=OSError("no pgrep"),
+        ):
+            self.assertTrue(cli._calibre_running())
+        with mock.patch.object(
+            cli.subprocess,
+            "run",
+            side_effect=cli.subprocess.TimeoutExpired(cmd="pgrep", timeout=10),
+        ):
+            self.assertTrue(cli._calibre_running())
+
+    def test_library_guard_fires_before_anything_else(self):
+        # a nonexistent path would fail "not a directory" (exit 1) anyway;
+        # the stderr message proves the guard spoke first
+        args = SimpleNamespace(
+            apply=True,
+            install_to_calibre=True,
+            path="/nonexistent/library",
+        )
+        err = io.StringIO()
+        with (
+            mock.patch.object(cli, "_calibre_running", return_value=True),
+            contextlib.redirect_stderr(err),
+        ):
+            rc = cli.run_library(args)
+        self.assertEqual(rc, 1)
+        self.assertIn("Calibre is running", err.getvalue())
+
+    def test_library_without_install_door_is_not_gated(self):
+        # a plain --apply (in-place) or dry run never consults the guard
+        args = SimpleNamespace(
+            apply=True,
+            install_to_calibre=False,
+            path="/nonexistent/library",
+        )
+        err = io.StringIO()
+        with (
+            mock.patch.object(cli, "_calibre_running", return_value=True),
+            contextlib.redirect_stderr(err),
+        ):
+            rc = cli.run_library(args)
+        self.assertEqual(rc, 1)
+        self.assertIn("not a directory", err.getvalue())
+
+    def test_audit_tag_guard_fires_first(self):
+        args = SimpleNamespace(tag="Flagged")
+        err = io.StringIO()
+        with (
+            mock.patch.object(cli, "_calibre_running", return_value=True),
+            contextlib.redirect_stderr(err),
+        ):
+            rc = cli.run_audit_cmd(args)
+        self.assertEqual(rc, 1)
+        self.assertIn("audit --tag", err.getvalue())
+
+
+class TestHelpTruth(unittest.TestCase):
+    """The contracts the probe found missing, now stated where users and
+    agents read them."""
+
+    def _parser(self):
+        return cli.build_parser()
+
+    def _sub(self, parser, name):
+        subparsers = next(
+            a for a in parser._actions if isinstance(a, argparse._SubParsersAction)
+        )
+        return subparsers.choices[name]
+
+    def test_repair_page_states_the_contract(self):
+        text = self._sub(self._parser(), "repair").description
+        self.assertIn("Never prompts", text)
+        self.assertIn("0 clean, 2 trouble", text)
+        self.assertIn("without --force", text)
+
+    def test_library_page_states_gate_and_codes(self):
+        text = self._sub(self._parser(), "library").description
+        self.assertIn("Never prompts", text)
+        self.assertIn("closed Calibre", text)
+        self.assertIn("0 all clean, 2 any", text)
+
+    def test_install_to_calibre_names_the_gate(self):
+        parser = self._parser()
+        lib = self._sub(parser, "library")
+        helps = " ".join(
+            a.help or "" for g in lib._action_groups for a in g._group_actions
+        )
+        self.assertIn("Calibre must be closed", helps)
+
+    def test_ncx001_is_defined(self):
+        parser = self._parser()
+        lib = self._sub(parser, "library")
+        helps = " ".join(
+            a.help or "" for g in lib._action_groups for a in g._group_actions
+        )
+        self.assertIn("dtb:uid", helps)
+
+    def test_library_id_works_without_sweep(self):
+        parser = self._parser()
+        lib = self._sub(parser, "library")
+        helps = " ".join(
+            a.help or "" for g in lib._action_groups for a in g._group_actions
+        )
+        self.assertIn("works without --sweep", helps)
+
+    def test_run_pages_carry_exit_codes(self):
+        run = self._sub(self._parser(), "run")
+        run_subs = next(
+            a for a in run._actions if isinstance(a, argparse._SubParsersAction)
+        )
+        helps = {pa.dest: pa.help for pa in run_subs._choices_actions}
+        for name in ("phase1", "phase3"):
+            text = helps[name]
+            self.assertIn("Exit codes", text, name)
+
+
+class TestHelpJson(unittest.TestCase):
+    def test_valid_complete_deterministic(self):
+        payload_text = self._dump()
+        data = json.loads(payload_text)
+        self.assertEqual(data["tool"], "bindery")
+        self.assertEqual(data["version"], __version__)
+        self.assertEqual(
+            [s["name"] for s in data["subcommands"]],
+            ["repair", "doctor", "audit", "library", "run"],
+        )
+        run = next(s for s in data["subcommands"] if s["name"] == "run")
+        self.assertEqual([s["name"] for s in run["slices"]], ["phase1", "phase3"])
+        self.assertEqual(
+            [g["group"] for g in data["repair_reference"]],
+            list(cli._REPAIR_FLAG_TABLE),
+        )
+        self.assertEqual(
+            data["calibre_gates"],
+            ["audit --tag", "library --apply --install-to-calibre"],
+        )
+        self.assertEqual(payload_text, self._dump())
+
+    def _dump(self):
+        out = io.StringIO()
+        with contextlib.redirect_stdout(out):
+            with self.assertRaises(SystemExit) as caught:
+                cli.main(["--help-json"])
+        self.assertEqual(caught.exception.code, 0)
+        return out.getvalue()
+
+    def test_covers_every_subcommand_flag_dest(self):
+        payload_text = self._dump()
+        parser = cli.build_parser()
+        subparsers = next(
+            a for a in parser._actions if isinstance(a, argparse._SubParsersAction)
+        )
+        for _name, sub in subparsers.choices.items():
+            for group in sub._action_groups:
+                for action in group._group_actions:
+                    if action.dest == "help":
+                        continue
+                    for opt in action.option_strings:
+                        self.assertIn(f'"{opt}"', payload_text, opt)
+
+    def test_exit_contract_present(self):
+        data = json.loads(self._dump())
+        self.assertIn("0", data["exit_contract"])
+        self.assertIn("2", data["exit_contract"])

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

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