dsh-office-kit 0.2.0 → 0.3.0

package/assets/skills/office-documents/scripts/render_and_diff.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python
+"""Render two documents and report which pages changed, pixel by pixel.
+
+This is how you prove an edit did what you meant without opening Word: render
+both versions, diff the page images, then look at the pages that moved.  The diff
+image marks changed pixels in colour so a one-line change is obvious.
+
+Exit codes: 0 compared, 1 render failed, 3 no renderer installed, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+THRESHOLD = 8
+
+
+def render(path: Path, out_dir: Path, dpi: int) -> tuple[int, list[str], str]:
+    code, stdout, stderr = kit.run_office_cli(["docx", "render", "--input", str(path), "--out-dir", str(out_dir), "--dpi", str(dpi)])
+    payload = kit.cli_json(stdout) or kit.cli_json(stderr) or {}
+    detail = payload.get("error") or payload.get("reason") or ""
+    if not detail:
+        lines = [line.strip() for line in (stderr or stdout).splitlines() if line.strip() not in ("", "{", "}")]
+        detail = lines[-1] if lines else "render failed"
+    return code, payload.get("pages") or [], detail
+
+
+def diff_pages(first: Path, second: Path, out_path: Path) -> dict:
+    from PIL import Image, ImageChops, ImageOps
+
+    with Image.open(first) as a, Image.open(second) as b:
+        left = a.convert("RGB")
+        right = b.convert("RGB")
+        if left.size != right.size:
+            right = right.resize(left.size)
+        difference = ImageChops.difference(left, right)
+        grey = difference.convert("L").point(lambda value: 255 if value > THRESHOLD else 0)
+        changed = sum(1 for value in grey.getdata() if value)
+        box = difference.getbbox()
+        ImageOps.autocontrast(difference).save(out_path)
+        return {
+            "changed_pixels": changed,
+            "total_pixels": left.width * left.height,
+            "ratio": round(changed / float(left.width * left.height), 6),
+            "bbox": list(box) if box else None,
+            "size": list(left.size),
+            "diff_image": str(out_path),
+        }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Render two .docx files and report per-page pixel differences.")
+    parser.add_argument("first", help="Original .docx")
+    parser.add_argument("second", help="Changed .docx")
+    parser.add_argument("--outdir", required=True, help="Directory for rendered pages and diff images")
+    parser.add_argument("--dpi", type=int, default=120)
+    parser.add_argument("--threshold", type=int, default=THRESHOLD, help="Per-pixel channel difference that counts as a change")
+    args = parser.parse_args(argv)
+
+    root = Path(args.outdir).expanduser().resolve()
+    first = Path(args.first).expanduser().resolve()
+    second = Path(args.second).expanduser().resolve()
+    for path in (first, second):
+        if not path.is_file():
+            print("error: %s not found" % path, file=sys.stderr)
+            return 2
+
+    code_a, pages_a, detail_a = render(first, root / "a", args.dpi)
+    code_b, pages_b, detail_b = render(second, root / "b", args.dpi)
+    if code_a != 0 or code_b != 0 or not pages_a or not pages_b:
+        detail = detail_a or detail_b or "render failed"
+        reason = "no_renderer" if ("renderer" in detail.lower() or "libreoffice" in detail.lower()) else "render_failed"
+        kit.emit({"ok": False, "reason": reason, "detail": detail, "remedy": "Install Microsoft Office, WPS Office, or LibreOffice, then re-run."})
+        return 3 if reason == "no_renderer" else 1
+
+    pairs = list(zip(pages_a, pages_b))
+    results = []
+    for index, (left, right) in enumerate(pairs, start=1):
+        results.append(diff_pages(Path(left), Path(right), root / ("diff-%02d.png" % index)))
+
+    changed_pages = [index for index, item in enumerate(results, start=1) if item["changed_pixels"]]
+    kit.emit(
+        {
+            "ok": True,
+            "pages_first": len(pages_a),
+            "pages_second": len(pages_b),
+            "changed_pages": changed_pages,
+            "page_count_delta": len(pages_b) - len(pages_a),
+            "diffs": results,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/replace_text.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Replace text in a Word document without touching the original.
+
+Pairs run inside single runs first; when a match straddles runs the paragraph
+text is rewritten into its first run, so ordinary prose survives intact and a
+paragraph that mixes formats collapses. Body, tables, and every section header
+and footer are covered.
+
+Usage:
+  replace_text.py --input IN.docx [--out OUT.docx] --find OLD --replace NEW [--find ...]
+  replace_text.py --input IN.docx [--out OUT.docx] --spec edits.json
+
+The spec file is {"replace": [{"find": "18%", "replace": "21%"}]} or a bare list
+of those objects.
+
+Exit codes: 0 replaced, 1 nothing replaced (with --require-all) or invalid
+input, 2 argparse usage error.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import docx_kit as kit  # noqa: E402
+
+
+def paragraph_text_nodes(paragraph) -> list:
+    """Every w:t below a paragraph, including runs inside hyperlinks."""
+    return paragraph._p.xpath(".//w:t")
+
+
+def replace_in_paragraph(paragraph, find: str, replacement: str) -> int:
+    nodes = paragraph_text_nodes(paragraph)
+    if not nodes:
+        return 0
+    count = 0
+    for node in nodes:
+        text = node.text or ""
+        if find in text:
+            hits = text.count(find)
+            node.text = text.replace(find, replacement)
+            count += hits
+    if count:
+        return count
+    joined = "".join(node.text or "" for node in nodes)
+    if find not in joined:
+        return 0
+    hits = joined.count(find)
+    nodes[0].text = joined.replace(find, replacement)
+    for node in nodes[1:]:
+        node.text = ""
+    return hits
+
+
+def iter_paragraphs(document):
+    def walk_tables(tables):
+        for table in tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    yield from cell.paragraphs
+                    yield from walk_tables(cell.tables)
+
+    yield from document.paragraphs
+    yield from walk_tables(document.tables)
+    for section in document.sections:
+        for part in (section.header, section.footer, section.first_page_header,
+                     section.first_page_footer, section.even_page_header,
+                     section.even_page_footer):
+            try:
+                yield from part.paragraphs
+            except Exception:  # a header/footer that is not linked or not present
+                continue
+
+
+def fail(payload: dict, code: int = 1) -> int:
+    kit.emit({"ok": False, **payload})
+    return code
+
+
+def load_spec(path: str) -> list[tuple[str, str]]:
+    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    items = payload.get("replace", []) if isinstance(payload, dict) else payload
+    pairs: list[tuple[str, str]] = []
+    for item in items:
+        find = str(item.get("find", ""))
+        if find:
+            pairs.append((find, str(item.get("replace", ""))))
+    return pairs
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Replace text in a .docx copy.")
+    parser.add_argument("--input", required=True, help="source .docx (never modified)")
+    parser.add_argument("--out", help="output path; default <name>-edited.docx")
+    parser.add_argument("--find", action="append", default=[], help="text to find; pair with --replace")
+    parser.add_argument("--replace", action="append", default=[], help="replacement for the matching --find")
+    parser.add_argument("--spec", help="JSON file with replace pairs")
+    parser.add_argument("--require-all", action="store_true", help="exit 1 when a pair matches nothing")
+    args = parser.parse_args()
+
+    if args.find and len(args.find) != len(args.replace):
+        return fail({"error": "--find and --replace must be given in pairs"}, 2)
+    pairs = list(zip(args.find, args.replace))
+    if args.spec:
+        try:
+            pairs.extend(load_spec(args.spec))
+        except (OSError, ValueError) as exc:
+            return fail({"error": f"cannot read spec: {exc}"}, 2)
+    if not pairs:
+        return fail({"error": "no replacements requested"}, 2)
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        return fail({"error": f"input not found: {args.input}"}, 1)
+    out = Path(args.out).expanduser() if args.out else source.with_name(f"{source.stem}-edited.docx")
+    if out.resolve() == source.resolve():
+        return fail({"error": "refusing to overwrite the input; pass a different --out"}, 1)
+
+    from docx import Document
+
+    document = Document(str(source))
+    per_pair: list[dict] = []
+    total = 0
+    for find, replacement in pairs:
+        hits = 0
+        for paragraph in iter_paragraphs(document):
+            hits += replace_in_paragraph(paragraph, find, replacement)
+        total += hits
+        per_pair.append({"find": find, "replace": replacement, "count": hits})
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    document.save(str(out))
+    misses = [item["find"] for item in per_pair if not item["count"]]
+    payload = {
+        "ok": not (args.require_all and misses),
+        "input": str(source),
+        "output": str(out),
+        "replacements": total,
+        "pairs": per_pair,
+        "misses": misses,
+    }
+    if args.require_all and misses:
+        payload["error"] = "patterns matched nothing: " + ", ".join(misses)
+        return fail(payload, 1)
+    kit.emit(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/section_audit.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python
+"""Report section geometry in inches so layout problems are visible as numbers.
+
+Every ``sectPr`` is one page-layout decision: page size, orientation (portrait is
+a page size where width < height, not a flag), margins, columns, header/footer
+links, and the section start type.  Mixed page sizes in one file are the most
+common cause of "why did page 4 shrink" reports, so a summary flag calls it out.
+
+Exit codes: 0 clean, 1 suspicious geometry, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+TWIPS_PER_INCH = 1440
+
+
+def inches(value: str | None) -> float | None:
+    return round(int(value) / TWIPS_PER_INCH, 3) if value and value.lstrip("-").isdigit() else None
+
+
+def describe(part: str, sect, index: int, doc: kit.Docx) -> dict:
+    page = sect.find(kit.q("pgSz"))
+    margins = sect.find(kit.q("pgMar"))
+    columns = sect.find(kit.q("cols"))
+    kind = sect.find(kit.q("type"))
+    info = {
+        "index": index,
+        "part": part,
+        "width_in": inches(page.get(kit.q("w"))) if page is not None else None,
+        "height_in": inches(page.get(kit.q("h"))) if page is not None else None,
+        "orientation": None,
+        "margin_in": {},
+        "columns": int(columns.get(kit.q("num"))) if columns is not None and columns.get(kit.q("num")) else 1,
+        "start": kind.get(kit.q("val")) if kind is not None else "nextPage",
+        "headers": [],
+        "footers": [],
+        "title_page": sect.find(kit.q("titlePg")) is not None,
+        "page_number_start": None,
+    }
+    if info["width_in"] and info["height_in"]:
+        info["orientation"] = "portrait" if info["width_in"] < info["height_in"] else "landscape"
+    if margins is not None:
+        for side in ("top", "bottom", "left", "right", "header", "footer", "gutter"):
+            info["margin_in"][side] = inches(margins.get(kit.q(side)))
+    numbering = sect.find(kit.q("pgNumType"))
+    if numbering is not None and numbering.get(kit.q("start")):
+        info["page_number_start"] = int(numbering.get(kit.q("start")))
+    rels = {entry["id"]: entry for entry in doc.relationships(part)}
+    for tag, key in (("headerReference", "headers"), ("footerReference", "footers")):
+        for ref in sect.findall(kit.q(tag)):
+            rid = ref.get(kit.q("id", kit.R))
+            info[key].append({"type": ref.get(kit.q("type")), "part": rels[rid]["resolved"] if rid in rels else None})
+    return info
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report page size, orientation, margins and columns per section.")
+    parser.add_argument("docx", help="Input .docx")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    sections = [describe("word/document.xml", sect, index, doc) for index, sect in enumerate(doc.sections(), start=1)]
+    findings = []
+    sizes = {(item["width_in"], item["height_in"]) for item in sections}
+    if len(sizes) > 1:
+        findings.append({"kind": "mixed_page_sizes", "sizes": sorted(sizes, key=lambda pair: (pair[0] or 0, pair[1] or 0))})
+    for item in sections:
+        margins = item["margin_in"]
+        if margins.get("left") is not None and margins.get("right") is not None and margins["left"] + margins["right"] >= (item["width_in"] or 8.5) - 1:
+            findings.append({"kind": "narrow_text_column", "section": item["index"], "left": margins["left"], "right": margins["right"]})
+        if item["width_in"] and item["width_in"] > 8.5 and item["orientation"] == "portrait":
+            findings.append({"kind": "portrait_wider_than_letter", "section": item["index"]})
+
+    kit.emit({"ok": not findings, "sections": sections, "findings": findings})
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/set_protection.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+"""Set or clear Word's document-protection editing restriction.
+
+Protection is a workplace guardrail, not encryption: without a password hash the
+restriction can be removed by anyone who knows the settings part, which is often
+exactly what is wanted for review copies.  Supply a precomputed ``--hash`` if the
+file must resist casual removal.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+MODES = {
+    "off": None,
+    "none": None,
+    "readonly": "readOnly",
+    "read_only": "readOnly",
+    "read-only": "readOnly",
+    "comments": "comments",
+    "comment": "comments",
+    "trackedchanges": "trackedChanges",
+    "tracked_changes": "trackedChanges",
+    "tracked-changes": "trackedChanges",
+    "forms": "forms",
+    "form": "forms",
+}
+HASH_ALGORITHM_SID = "4"  # SHA-512, the modern Word default
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Apply or remove the editing restriction stored in settings.xml.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--mode", required=True, help="off, readOnly, comments, trackedChanges, forms")
+    parser.add_argument("--out", default=None, help="Output .docx (default: overwrite the input)")
+    parser.add_argument("--no_enforce", action="store_true", help="Write the mode but leave enforcement off")
+    parser.add_argument("--hash", default=None, help="Precomputed password hash (skip to leave protection password-free)")
+    parser.add_argument("--salt", default=None, help="Salt value that belongs with --hash")
+    parser.add_argument("--spin_count", default="100000")
+    args = parser.parse_args(argv)
+
+    mode = MODES.get(args.mode.strip().lower())
+    if mode is None and args.mode.strip().lower() not in ("off", "none"):
+        print("error: unknown --mode %r (use off, readOnly, comments, trackedChanges, forms)" % args.mode, file=sys.stderr)
+        return 2
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    settings = doc.xml("word/settings.xml")
+    for existing in settings.findall(kit.q("documentProtection")):
+        settings.remove(existing)
+
+    if mode is not None:
+        node = etree.Element(kit.q("documentProtection"))
+        node.set(kit.q("edit"), mode)
+        node.set(kit.q("enforcement"), "0" if args.no_enforce else "1")
+        if args.hash:
+            node.set(kit.q("cryptProviderType"), "rsaFull")
+            node.set(kit.q("cryptAlgorithmClass"), "hash")
+            node.set(kit.q("cryptAlgorithmType"), "typeAny")
+            node.set(kit.q("cryptAlgorithmSid"), HASH_ALGORITHM_SID)
+            node.set(kit.q("cryptSpinCount"), args.spin_count)
+            node.set(kit.q("hash"), args.hash)
+            if args.salt:
+                node.set(kit.q("salt"), args.salt)
+        anchor = settings.find(kit.q("writeProtection"))
+        if anchor is None:
+            settings.insert(0, node)
+        else:
+            anchor.addnext(node)
+
+    out = args.out or args.docx
+    doc.save(out)
+    kit.emit({"ok": True, "output": str(Path(out)), "mode": mode or "off", "enforced": bool(mode) and not args.no_enforce, "password_hash": bool(args.hash)})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/style_lint.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python
+"""Lint a document for formatting that fights its own styles.
+
+The report answers "can Word restyle this document?"  Direct run formatting,
+undefined style ids, hand-typed bullets and one-off font sizes are the usual
+reasons a restyle pass does nothing.  Findings are advisory: a few are legitimate.
+
+Exit codes: 0 clean, 1 findings, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+MAX_FINDINGS = 50
+BULLET_TEXT = ("\u2022", "- ", "* ")
+
+
+def known_styles(doc: kit.Docx) -> dict[str, str]:
+    styles = {}
+    root = doc.xml("word/styles.xml")
+    for node in root.findall(kit.q("style")):
+        ident = node.get(kit.q("styleId"))
+        name = node.find(kit.q("name"))
+        styles[ident] = name.get(kit.q("val")) if name is not None else ident
+    return styles
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report direct formatting, undefined styles and other style conflicts.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--json", default=None, help="Also write the report to this path")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    styles = known_styles(doc)
+    findings = []
+    sizes = Counter()
+    direct = 0
+
+    for index, paragraph in enumerate(doc.paragraphs(), start=1):
+        text = kit.paragraph_text(paragraph).strip()
+        style_id = kit.paragraph_style(paragraph)
+        level = kit.heading_level(paragraph)
+        if style_id and style_id not in styles:
+            findings.append({"kind": "undefined_style", "index": index, "style": style_id})
+        if level and paragraph.find(kit.q("pPr") + "/" + kit.q("rPr")) is not None:
+            findings.append({"kind": "heading_paragraph_formatting", "index": index, "text": text[:80]})
+        for run in paragraph.iter(kit.q("r")):
+            props = run.find(kit.q("rPr"))
+            if props is None or len(props) == 0:
+                continue
+            direct += 1
+            if level and any(props.find(kit.q(tag)) is not None for tag in ("b", "i", "color", "sz")):
+                findings.append({"kind": "heading_direct_formatting", "index": index, "text": text[:80]})
+                break
+            size = props.find(kit.q("sz"))
+            if size is not None and not level and (size.get(kit.q("val")) or "").isdigit():
+                sizes[int(size.get(kit.q("val")))] += 1
+            if not kit.text_of(run):
+                findings.append({"kind": "empty_run", "index": index})
+                break
+        if text.startswith(BULLET_TEXT) and paragraph.find(kit.q("pPr") + "/" + kit.q("numPr")) is None:
+            findings.append({"kind": "manual_bullet", "index": index, "text": text[:80]})
+        if "  " in text:
+            findings.append({"kind": "double_space", "index": index, "text": text[:80]})
+        if text != text.rstrip():
+            findings.append({"kind": "trailing_space", "index": index})
+
+    if sizes:
+        common, _ = sizes.most_common(1)[0]
+        for size, count in sizes.items():
+            if size != common and count <= 3:
+                findings.append({"kind": "body_size_outlier", "half_points": size, "count": count, "common_half_points": common})
+
+    for table in doc.body().iter(kit.q("tbl")):
+        if table.find(kit.q("tblPr") + "/" + kit.q("tblStyle")) is None:
+            findings.append({"kind": "table_without_style"})
+
+    counts = {}
+    for finding in findings:
+        counts[finding["kind"]] = counts.get(finding["kind"], 0) + 1
+
+    report = {
+        "ok": not findings,
+        "styles_defined": len(styles),
+        "directly_formatted_runs": direct,
+        "counts": counts,
+        "findings": findings[:MAX_FINDINGS],
+        "truncated": max(0, len(findings) - MAX_FINDINGS),
+    }
+    if args.json:
+        Path(args.json).write_text(json.dumps(report, indent=2), encoding="utf-8")
+    kit.emit(report)
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/style_normalize.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+"""Push formatting back onto styles so the document can be restyled again.
+
+Two passes, both opt-in:
+
+``--clear_paragraph_format``
+    delete paragraph-mark direct formatting and stray run formatting, keeping
+    character styles, so the paragraph style governs again.
+``--enforce_heading_spacing``
+    give headings consistent spacing and "keep with next" so a page break cannot
+    strand a heading at the bottom of a page.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+HEADING_SPACING = {1: (320, 120), 2: (240, 80), 3: (200, 60)}
+KEEP_RUN_PROPS = {kit.q("rStyle"), kit.q("rtl"), kit.q("lang")}
+
+
+def strip_run_formatting(paragraph) -> int:
+    removed = 0
+    for run in paragraph.iter(kit.q("r")):
+        props = run.find(kit.q("rPr"))
+        if props is None:
+            continue
+        for child in list(props):
+            if child.tag not in KEEP_RUN_PROPS:
+                props.remove(child)
+                removed += 1
+        if len(props) == 0:
+            run.remove(props)
+    return removed
+
+
+def enforce_spacing(paragraph, level: int) -> None:
+    props = paragraph.find(kit.q("pPr"))
+    if props is None:
+        props = etree.Element(kit.q("pPr"))
+        paragraph.insert(0, props)
+    for tag in ("spacing", "keepNext"):
+        for existing in props.findall(kit.q(tag)):
+            props.remove(existing)
+    before, after = HEADING_SPACING.get(level, (240, 120))
+    spacing = etree.SubElement(props, kit.q("spacing"))
+    spacing.set(kit.q("before"), str(before))
+    spacing.set(kit.q("after"), str(after))
+    etree.SubElement(props, kit.q("keepNext"))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Remove direct formatting and normalize heading spacing.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("output_docx", nargs="?", default=None, help="Output .docx")
+    parser.add_argument("--out", default=None, help="Output .docx (alternative to the positional argument)")
+    parser.add_argument("--clear_paragraph_format", action="store_true", help="Strip direct run and paragraph-mark formatting")
+    parser.add_argument("--enforce_heading_spacing", action="store_true", help="Apply consistent heading spacing and keep-with-next")
+    args = parser.parse_args(argv)
+
+    out = args.out or args.output_docx
+    if not out:
+        parser.error("provide an output path (positional or --out)")
+    if not (args.clear_paragraph_format or args.enforce_heading_spacing):
+        parser.error("choose --clear_paragraph_format and/or --enforce_heading_spacing")
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    runs_cleaned = 0
+    headings_spaced = 0
+    for paragraph in doc.paragraphs():
+        if args.clear_paragraph_format:
+            props = paragraph.find(kit.q("pPr"))
+            if props is not None:
+                for mark in props.findall(kit.q("rPr")):
+                    props.remove(mark)
+            runs_cleaned += strip_run_formatting(paragraph)
+        if args.enforce_heading_spacing:
+            level = kit.heading_level(paragraph)
+            if level:
+                enforce_spacing(paragraph, level)
+                headings_spaced += 1
+
+    doc.save(out)
+    kit.emit({"ok": True, "output": str(Path(out)), "runs_cleaned": runs_cleaned, "headings_spaced": headings_spaced})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())