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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.47.2
+Version: 0.48.1
 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

{bindery_cli-0.47.2 → bindery_cli-0.48.1}/patchnotes.md

@@ -1,5 +1,71 @@
 # bindery-cli Patch Notes
 
+## v0.48.1 (2026-10-06)
+
+### The 12-agent audit: the exit contracts tell the truth
+
+Three waves of four lenses audited this help surface. The flag
+inventory verified perfect (30/30 repair flags, zero misses, zero
+fabrications); the defects were the exit contracts and the safety
+silences:
+
+- **repair --help stated an exit contract the verb has never honored**
+  (trouble returns 1, not 2; a PARTIAL repair writes its output and
+  returns 0). The page and --help-json now tell the code's truth, per
+  verb: repair 0/written + 1, audit's deliberate inverse contract
+  (0 clean; 1 findings; 2 usage/environment; 3 findings plus a failed
+  report write), library and the run slices on the unified 0/2/1.
+  calibre_gates names the third metadata.db door (run phase3, guarded
+  transitively), and the contract admits the missing-stack exit-2 and
+  the exit-3 class.
+- **The library page states the no-backup default**: --apply without
+  --backup/--backup-inplace replaces in place and keeps no copy of the
+  original. --no-validate says the write still happens (status
+  unvalidated). --backup names the outside-the-library refusal.
+  --only fatals names its --audit/--sweep precondition.
+- audit and doctor got real descriptions (the eight analyzers, the CWD
+  library resolution, the one-id --json rule; doctor's always-exit-0
+  contract); the --help-repairs preamble names the five always-on
+  fixes, defines the gate metric, enumerates the status vocabulary,
+  and states the no-worse classes; phase1's exit list gains
+  audit-flagged books; repair's positionals, default output name, and
+  never-modifies-the-input are stated; the --json envelopes name all
+  keys including books; the root help points at doctor/README/spec.
+- One code fix: the no-backup lossy warning now covers
+  --strip-stub-docs (it warned for its three siblings only).
+
+15 pins updated/added (639 total).
+
+## 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.47.2"
+version = "0.48.1"
 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.2 → bindery_cli-0.48.1}/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.2 → bindery_cli-0.48.1}/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.2"
+VERSION = "0.48.1"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

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

@@ -395,8 +395,171 @@ 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 (repair: also written, including partial)",
+                "1": "library/run slices: trouble found; repair: trouble "
+                "(refused/failed/unreadable) or invocation problem; audit: "
+                "FINDINGS (the inverse contract, per spec.md); "
+                "lock-class refusals (Calibre open at a metadata.db door)",
+                "2": "library/run slices: trouble found (rejected/error/"
+                "unreadable/partial books; unscoped phase3 sweep); audit: "
+                "usage/environment errors; argparse usage errors; missing "
+                "vir_tui/cquarry on Python < 3.14",
+                "3": "audit: findings PLUS a failed --json/--tag write",
+                "130": "interrupted",
+                "per_verb": {
+                    "repair": "0 clean/written (partial writes, exit 0); "
+                    "1 trouble or invocation problem; never 2",
+                    "audit": "0 clean; 1 findings; 2 usage/environment; "
+                    "3 findings + failed report write",
+                    "library": "0 clean; 2 trouble (rejected/error/"
+                    "unreadable/partial); 1 invocation problem",
+                    "run phase1": "0 clean; 2 trouble (audit-flagged, "
+                    "rejected, partial, error, unreadable); 1 invocation",
+                },
+            },
+            "calibre_gates": [
+                "audit --tag",
+                "library --apply --install-to-calibre",
+                "run phase3 (transitively: it wraps 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)
@@ -485,7 +648,12 @@ def run_library(args) -> int:
     if (
         args.apply
         and not wants_backup
-        and (args.strip_pagination or args.strip_broken_tags or args.strip_watermarks)
+        and (
+            args.strip_pagination
+            or args.strip_broken_tags
+            or args.strip_watermarks
+            or args.strip_stub_docs
+        )
     ):
         print(
             "WARNING: the --strip-* modes are lossy; strongly consider --backup DIR "
@@ -1694,12 +1862,21 @@ def _repair_flag_reference(color: bool | None = None) -> str:
         + " 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.",
+        "The always-on core pass is exactly five well-formedness fixes",
+        "(strip prolog junk, drop duplicate xmlns, escape bare ampersands,",
+        "fix named entities, self-close void tags), 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",
+        "(strictly fewer findings than before); the lossy strips, the",
+        "cover wiring repairs, and the space-entry renames are held to the",
+        "weaker no-worse bar (not more findings). Library mode is dry-run",
+        "by default; `--all` enables every flag below at once. Statuses a",
+        "record can carry: accept (gate-applied), partial (written but",
+        "still failing epubcheck), reject (the gate refused), error,",
+        "unreadable, nochange (nothing to do), equal (already as good as",
+        "the result), unvalidated (applied under --no-validate, never",
+        "gate-checked). The README and spec.md carry the full rationale",
+        "for each repair.",
     ]
     for title, rows in _REPAIR_FLAG_TABLE.items():
         lines.append("")
@@ -1720,6 +1897,37 @@ def _repair_flag_reference(color: bool | None = None) -> str:
     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.
 
@@ -1765,12 +1973,15 @@ def _add_repair_flags(p: argparse.ArgumentParser) -> None:
     g.add_argument(
         "--all",
         action="store_true",
-        help="enable every opt-in fix flag (safe, structural, and lossy)",
+        help="enable every opt-in fix flag (safe, structural, and lossy); "
+        "this IS the lossy consent here (run phase1's separate "
+        "--apply-lossy door is the phase1 equivalent)",
     )
     g.add_argument(
         "--no-validate",
         action="store_true",
-        help="skip the epubcheck gate",
+        help="skip the epubcheck gate: the repair still writes/appends "
+        "with status unvalidated (no gate check runs)",
     )
     p.add_argument(
         "--help-repairs",
@@ -1781,6 +1992,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:
@@ -1853,6 +2068,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(
@@ -1862,7 +2083,13 @@ 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 or written (a PARTIAL repair "
+        "writes its best output and exits 0; the --json record's status "
+        "says so), 1 trouble (repair refused by the gate, epubcheck "
+        "failure, or unreadable input) or invocation problem (bad args, "
+        "or an existing output without --force). This verb does not use "
+        "the tool-wide trouble=2 contract; library and the run slices do.",
         epilog="examples:\n"
         "  bindery repair book.epub out.epub\n"
         "  bindery repair book.epub out.epub --all\n"
@@ -1882,8 +2109,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)
@@ -1892,12 +2120,25 @@ def build_parser() -> argparse.ArgumentParser:
         "doctor",
         help="check the environment: Python stack tier, epubcheck, Java, "
         "html5lib, and Calibre-library discovery",
+        description="Check the environment and exit 0 ALWAYS: the output "
+        "is the diagnosis, never a failure (run this first). Checks: the "
+        "Python stack tier, epubcheck, Java, html5lib, and Calibre-library "
+        "discovery.",
     )
     doc.set_defaults(func=run_doctor)
 
     audit = sub.add_parser(
         "audit",
         help="audit EPUB body text to detect non-schema content flaws (OCR damage, hardcoded page numbers, empty books, non-English text)",
+        description="Read-only content audit (eight analyzers: monolithic "
+        "scans, completeness, cover wiring, toc drift, and the body-text "
+        "battery over OCR damage, hardcoded page numbers, empty/thin "
+        "books, and non-English text). Library mode resolves the Calibre "
+        "library from the CURRENT DIRECTORY's metadata.db, or pass a "
+        "directory, or --id for specific books (--id plus --json takes "
+        "exactly one id). Exit codes are the audit inverse: 0 clean, "
+        "1 FINDINGS (flagged books), 2 usage or environment errors, "
+        "3 findings plus a failed --json/--tag write. Never prompts.",
     )
     audit.add_argument(
         "mode",
@@ -1949,7 +2190,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--id",
         metavar="BOOK_IDS",
         default=None,
-        help="audit library book(s) by Calibre id — one id or a comma-separated "
+        help="audit library book(s) by Calibre id: one id or a comma-separated "
         "list (fetched via cquarry's single-entity get_book; cannot be "
         "combined with a directory)",
     )
@@ -1970,7 +2211,13 @@ 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. --apply WITHOUT --backup or --backup-inplace "
+        "replaces in place and keeps NO copy of the original. Exit codes: "
+        "0 all clean, 2 any flagged/rejected/error/unreadable/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 "
@@ -1988,7 +2235,9 @@ 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); "
+        "fatals requires --audit CSV or --sweep",
     )
     rc.add_argument(
         "--limit", type=int, help="process at most N candidates (for sampling)"
@@ -2021,9 +2270,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")
@@ -2044,7 +2293,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, books (one record per candidate)",
     )
     out.add_argument(
         "--manual-list",
@@ -2055,7 +2304,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",
     )
@@ -2074,7 +2323,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(
@@ -2110,7 +2361,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.48.1/tests/test_help.py

@@ -0,0 +1,208 @@
+"""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("PARTIAL repair writes its best output and exits 0", text)
+        self.assertIn("does not use", 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 flagged/rejected/error/unreadable/partial", text
+        )
+        self.assertIn("keeps NO copy of the original", 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"][0:2],
+            ["audit --tag", "library --apply --install-to-calibre"],
+        )
+        # the third door is phase3, guarded transitively through library
+        self.assertIn("run phase3", data["calibre_gates"][2])
+        # the contract now carries the per-verb truth
+        self.assertEqual(data["exit_contract"]["per_verb"]["repair"][-7:], "never 2")
+        self.assertIn("1 findings", data["exit_contract"]["per_verb"]["audit"])
+        self.assertIn("3", data["exit_contract"])
+        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.2 → bindery_cli-0.48.1}/uv.lock

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