dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,225 @@
+#!/usr/bin/env python
+"""Escape hatch for WordprocessingML features python-docx does not expose.
+
+One invocation may combine several patches, which is what makes it useful for
+finishing a document in one pass:
+
+  --enable-track                 switch on revisions
+  --tracked-replace-ins-id ID    turn an insertion into delete + insert
+  --add-comment --comment-text   attach a comment to the first matching paragraph
+  --header-date TEXT             set a right-aligned first-header line
+  --add-page-numbers             centered PAGE field in the footer
+  --hyperlink-first URL          wrap the first text paragraph in a hyperlink
+
+Exit codes: 0 success, 1 requested target not found, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+PKG_REL = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+REL_HYPERLINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
+
+
+def stamp(args) -> str:
+    return args.date or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def enable_track(doc: kit.Docx) -> str:
+    settings = doc.xml("word/settings.xml")
+    if settings.find(kit.q("trackRevisions")) is None:
+        settings.append(settings.makeelement(kit.q("trackRevisions"), {}))
+    return "trackRevisions enabled"
+
+
+def tracked_replace(doc: kit.Docx, ins_id: str, new_text: str, author: str, date: str) -> str:
+    for part in doc.text_parts():
+        for node in doc.xml(part).iter(kit.q("ins")):
+            if (node.get(kit.q("id")) or "") != str(ins_id):
+                continue
+            parent = node.getparent()
+            ident = doc.next_id()
+            deletion = etree.Element(kit.q("del"))
+            deletion.set(kit.q("id"), str(ident))
+            deletion.set(kit.q("author"), author)
+            deletion.set(kit.q("date"), date)
+            for child in list(node):
+                clone = etree.fromstring(etree.tostring(child))
+                for text in clone.iter(kit.q("t")):
+                    text.tag = kit.q("delText")
+                deletion.append(clone)
+            insertion = etree.Element(kit.q("ins"))
+            insertion.set(kit.q("id"), str(ident + 1))
+            insertion.set(kit.q("author"), author)
+            insertion.set(kit.q("date"), date)
+            insertion.append(kit.make_run(new_text))
+            position = parent.index(node)
+            parent.remove(node)
+            parent.insert(position, deletion)
+            parent.insert(position + 1, insertion)
+            return "converted ins %s to del+ins in %s" % (ins_id, part)
+    return ""
+
+
+def find_paragraph(doc: kit.Docx, contains: str | None, indent: int | None):
+    for paragraph in doc.paragraphs():
+        props = paragraph.find(kit.q("pPr"))
+        if contains is not None and contains not in kit.paragraph_text(paragraph):
+            continue
+        if indent is not None:
+            ind = props.find(kit.q("ind")) if props is not None else None
+            if ind is None or (ind.get(kit.q("left")) or "") != str(indent):
+                continue
+        return paragraph
+    return None
+
+
+def add_comment(doc: kit.Docx, paragraph, text: str, author: str, date: str, explicit_id: str | None) -> str:
+    if not doc.exists("word/comments.xml"):
+        root = etree.Element(kit.q("comments"), nsmap={"w": kit.W, "r": kit.R})
+        doc.set_xml("word/comments.xml", root)
+        doc.ensure_override("word/comments.xml", kit.CT_BY_REL[kit.REL_COMMENTS])
+        doc.ensure_rel("word/document.xml", kit.REL_COMMENTS, "comments.xml")
+    root = doc.xml("word/comments.xml")
+    ident = int(explicit_id) if explicit_id and explicit_id.isdigit() else doc.next_id()
+    comment = etree.SubElement(root, kit.q("comment"))
+    comment.set(kit.q("id"), str(ident))
+    comment.set(kit.q("author"), author)
+    comment.set(kit.q("initials"), author[:2].upper())
+    comment.set(kit.q("date"), date)
+    body = etree.SubElement(comment, kit.q("p"))
+    run = etree.SubElement(body, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space"), kit.XML)
+
+    start = etree.Element(kit.q("commentRangeStart"))
+    start.set(kit.q("id"), str(ident))
+    position = 1 if paragraph.find(kit.q("pPr")) is not None else 0
+    paragraph.insert(position, start)
+    end = etree.SubElement(paragraph, kit.q("commentRangeEnd"))
+    end.set(kit.q("id"), str(ident))
+    ref_run = etree.SubElement(paragraph, kit.q("r"))
+    etree.SubElement(ref_run, kit.q("commentReference")).set(kit.q("id"), str(ident))
+    return "comment %d anchored" % ident
+
+
+def header_date(doc: kit.Docx, text: str) -> str:
+    part = doc.ensure_header_footer("header")
+    paragraph = doc.xml(part).find(".//" + kit.q("p"))
+    if paragraph is None:
+        paragraph = etree.SubElement(doc.xml(part), kit.q("p"))
+    props = paragraph.find(kit.q("pPr"))
+    if props is None:
+        props = etree.Element(kit.q("pPr"))
+        paragraph.insert(0, props)
+    for existing in props.findall(kit.q("jc")):
+        props.remove(existing)
+    etree.SubElement(props, kit.q("jc")).set(kit.q("val"), "right")
+    kit.set_paragraph_text(paragraph, text)
+    return "header set in %s" % part
+
+
+def page_numbers(doc: kit.Docx) -> str:
+    part = doc.ensure_header_footer("footer")
+    paragraph = doc.xml(part).find(".//" + kit.q("p"))
+    if paragraph is None:
+        paragraph = etree.SubElement(doc.xml(part), kit.q("p"))
+    props = paragraph.find(kit.q("pPr"))
+    if props is None:
+        props = etree.Element(kit.q("pPr"))
+        paragraph.insert(0, props)
+    etree.SubElement(props, kit.q("jc")).set(kit.q("val"), "center")
+    for run in kit.field_runs("PAGE", "1"):
+        paragraph.append(run)
+    return "PAGE field added to %s" % part
+
+
+def hyperlink_first(doc: kit.Docx, url: str) -> str:
+    for paragraph in doc.paragraphs():
+        runs = [child for child in paragraph if child.tag == kit.q("r") and kit.text_of(child).strip()]
+        if not runs:
+            continue
+        rid = doc.ensure_rel("word/document.xml", REL_HYPERLINK, url, external=True)
+        link = etree.Element(kit.q("hyperlink"))
+        link.set(kit.q("id", kit.R), rid)
+        position = paragraph.index(runs[0])
+        for run in runs:
+            paragraph.remove(run)
+            link.append(run)
+        paragraph.insert(position, link)
+        return "wrapped %d run(s) in hyperlink %s" % (len(runs), url)
+    return ""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Apply targeted OOXML patches that python-docx cannot express.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--out", default=None, help="Output .docx (default: overwrite the input)")
+    parser.add_argument("--enable-track", action="store_true")
+    parser.add_argument("--author", default="dsh-office")
+    parser.add_argument("--date", default=None, help="ISO timestamp for revisions and comments")
+    parser.add_argument("--tracked-replace-ins-id", default=None)
+    parser.add_argument("--new-text", default="")
+    parser.add_argument("--add-comment", action="store_true")
+    parser.add_argument("--comment-text", default="")
+    parser.add_argument("--contains", default=None, help="Target paragraph containing this text")
+    parser.add_argument("--indent-left-twips", type=int, default=None, help="Target paragraph with this left indent")
+    parser.add_argument("--comment-id", default=None)
+    parser.add_argument("--header-date", nargs="?", const="auto", default=None, help="Right-aligned header line; omit the value to use today's date")
+    parser.add_argument("--add-page-numbers", action="store_true")
+    parser.add_argument("--hyperlink-first", default=None)
+    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
+
+    actions = []
+    missing = []
+    when = stamp(args)
+
+    if args.enable_track:
+        actions.append(enable_track(doc))
+    if args.tracked_replace_ins_id is not None:
+        result = tracked_replace(doc, args.tracked_replace_ins_id, args.new_text, args.author, when)
+        actions.append(result) if result else missing.append("ins id %s" % args.tracked_replace_ins_id)
+    if args.add_comment:
+        paragraph = find_paragraph(doc, args.contains, args.indent_left_twips)
+        if paragraph is None:
+            missing.append("paragraph for --add-comment")
+        else:
+            actions.append(add_comment(doc, paragraph, args.comment_text, args.author, when, args.comment_id))
+    if args.header_date is not None:
+        from datetime import date
+
+        stamp_text = date.today().isoformat() if args.header_date == "auto" else args.header_date
+        actions.append(header_date(doc, stamp_text))
+    if args.add_page_numbers:
+        actions.append(page_numbers(doc))
+    if args.hyperlink_first:
+        result = hyperlink_first(doc, args.hyperlink_first)
+        actions.append(result) if result else missing.append("paragraph for --hyperlink-first")
+
+    if not actions and not missing:
+        parser.error("no patch requested")
+
+    out = args.out or args.docx
+    doc.save(out)
+    kit.emit({"ok": not missing, "output": str(Path(out)), "actions": actions, "missing": missing})
+    return 1 if missing else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+"""Export one table from a .docx to CSV.
+
+Merged cells are expanded so the CSV has a rectangular shape: a horizontally
+merged cell repeats its text across the spanned columns and a vertically merged
+cell inherits the value from the row above.  That keeps downstream spreadsheets
+aligned instead of silently shifting columns.
+
+Exit codes: 0 success, 1 table index out of range, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+
+def cell_span(cell) -> int:
+    props = cell.find(kit.q("tcPr"))
+    if props is None:
+        return 1
+    span = props.find(kit.q("gridSpan"))
+    if span is None:
+        return 1
+    try:
+        return max(1, int(span.get(kit.q("val")) or 1))
+    except ValueError:
+        return 1
+
+
+def vertical_merge(cell) -> str:
+    props = cell.find(kit.q("tcPr"))
+    if props is None:
+        return ""
+    merge = props.find(kit.q("vMerge"))
+    if merge is None:
+        return ""
+    return merge.get(kit.q("val")) or "continue"
+
+
+def table_rows(table) -> list[list[str]]:
+    rows: list[list[str]] = []
+    grid_width = 0
+    for row in table.findall(kit.q("tr")):
+        values: list[str] = []
+        for cell in row.findall(kit.q("tc")):
+            text = " ".join(" ".join(kit.text_of(paragraph).split()) for paragraph in cell.findall(kit.q("p"))).strip()
+            span = cell_span(cell)
+            merge = vertical_merge(cell)
+            if merge == "continue":
+                column = len(values)
+                inherited = ""
+                if rows and column < len(rows[-1]):
+                    inherited = rows[-1][column]
+                text = inherited
+            values.extend([text] * span)
+        grid_width = max(grid_width, len(values))
+        rows.append(values)
+    for row in rows:
+        while len(row) < grid_width:
+            row.append("")
+    return rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Export a table from a .docx to CSV, expanding merged cells.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--table_index", type=int, default=0, help="Zero-based table index")
+    parser.add_argument("--out", required=True, help="Output .csv 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
+
+    tables = list(doc.xml("word/document.xml").iter(kit.q("tbl")))
+    if args.table_index < 0 or args.table_index >= len(tables):
+        print("error: table_index %d out of range (document has %d)" % (args.table_index, len(tables)), file=sys.stderr)
+        return 1
+
+    rows = table_rows(tables[args.table_index])
+    out = Path(args.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with out.open("w", encoding="utf-8", newline="") as handle:
+        csv.writer(handle).writerows(rows)
+
+    kit.emit({"ok": True, "output": str(out), "tables": len(tables), "table_index": args.table_index, "rows": len(rows), "columns": len(rows[0]) if rows else 0})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+"""Freeze SEQ/REF field results into plain text so renders match Word.
+
+Headless renderers do not always evaluate fields, so a caption may show "Table"
+with no number.  The cached result is already inside the document; this script
+throws away the field machinery and keeps that result as ordinary runs.
+
+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
+
+
+def freeze(doc: kit.Docx, allowed: set[str]) -> int:
+    flattened = 0
+    for part in doc.text_parts():
+        for paragraph in doc.paragraphs(part):
+            for field in reversed(kit.paragraph_fields(paragraph)):
+                if field["type"] not in allowed:
+                    continue
+                span = field["span"]
+                if not span:
+                    continue
+                first = span[0]
+                rpr = first.find(kit.q("rPr")) if first.tag == kit.q("r") else None
+                position = paragraph.index(first)
+                for node in span:
+                    if node.getparent() is paragraph:
+                        paragraph.remove(node)
+                if field["result"]:
+                    run = kit.make_run(field["result"], etree.fromstring(etree.tostring(rpr)) if rpr is not None else None)
+                    paragraph.insert(position, run)
+                flattened += 1
+    return flattened
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Replace SEQ/REF fields with their cached result text.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--only", nargs="+", default=["SEQ", "REF"], choices=["SEQ", "REF"], help="Field types to freeze")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    flattened = freeze(doc, set(args.only))
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "only": args.only, "fields_frozen": flattened})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+"""List the Word fields in a .docx and show what each one asks for.
+
+Fields are the dynamic bits Word fills at layout time: ``TOC``, ``SEQ``, ``REF``,
+``PAGEREF``, ``HYPERLINK``, ``DATE`` and friends.  Each is reported once with its
+instruction, cached result, and the part it lives in, so a headless workflow can
+tell whether a document depends on a refresh before rendering.
+
+Exit codes: 0 success (also when there are no fields), 2 bad input or missing part.
+"""
+
+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
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report Word fields (TOC, SEQ, REF, PAGEREF, HYPERLINK, ...) in a .docx.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--max_examples", type=int, default=8, help="How many sample instructions to keep per field type")
+    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
+
+    counts: dict[str, int] = {}
+    examples: dict[str, list[dict]] = {}
+    kinds: dict[str, int] = {}
+    for part, paragraph, field in kit.iter_fields(doc):
+        name = field["type"] or "UNKNOWN"
+        counts[name] = counts.get(name, 0) + 1
+        kinds[field["kind"]] = kinds.get(field["kind"], 0) + 1
+        bucket = examples.setdefault(name, [])
+        if len(bucket) < args.max_examples:
+            bucket.append({"part": part, "instr": field["instr"], "result": field["result"][:80]})
+
+    kit.emit(
+        {
+            "ok": True,
+            "input": str(Path(args.docx)),
+            "total": sum(counts.values()),
+            "counts": counts,
+            "kinds": kinds,
+            "examples": examples,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+"""Replace REF and PAGEREF fields with the text they resolve to.
+
+A focused subset of field freezing: cross-reference fields are the ones that
+most often render blank outside Word, so this script rewrites only those and
+leaves TOC, SEQ and date fields untouched.
+
+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
+
+TARGETS = {"REF", "PAGEREF"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Flatten REF/PAGEREF cross-reference fields to literal text.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.in_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    flattened = 0
+    for part in doc.text_parts():
+        for paragraph in doc.paragraphs(part):
+            for field in reversed(kit.paragraph_fields(paragraph)):
+                if field["type"] not in TARGETS or not field["span"]:
+                    continue
+                first = field["span"][0]
+                rpr = first.find(kit.q("rPr")) if first.tag == kit.q("r") else None
+                position = paragraph.index(first)
+                for node in field["span"]:
+                    if node.getparent() is paragraph:
+                        paragraph.remove(node)
+                if field["result"]:
+                    paragraph.insert(
+                        position,
+                        kit.make_run(field["result"], etree.fromstring(etree.tostring(rpr)) if rpr is not None else None),
+                    )
+                flattened += 1
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "flattened": flattened})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+"""Report footnotes and endnotes stored in a .docx.
+
+Real notes are not footer text: they live in word/footnotes.xml or
+word/endnotes.xml, and the body only carries a reference run.  This script
+prints every note with its id, kind and text, plus how many references the body
+makes, which is how you catch notes that were orphaned by an edit.
+
+Exit codes: 0 success, 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
+
+PARTS = {"footnote": "word/footnotes.xml", "endnote": "word/endnotes.xml"}
+SEPARATOR_TYPES = {"separator", "continuationSeparator", "continuationNotice"}
+
+
+def collect(doc: kit.Docx, kind: str) -> list[dict]:
+    part = PARTS[kind]
+    if not doc.exists(part):
+        return []
+    notes = []
+    for node in doc.xml(part).iter(kit.q(kind)):
+        note_type = node.get(kit.q("type")) or "normal"
+        if note_type in SEPARATOR_TYPES:
+            continue
+        paragraphs = [kit.text_of(paragraph).strip() for paragraph in node.iter(kit.q("p"))]
+        notes.append(
+            {
+                "kind": kind,
+                "id": node.get(kit.q("id")),
+                "text": " ".join(text for text in paragraphs if text),
+                "empty": not any(text for text in paragraphs),
+            }
+        )
+    return notes
+
+
+def references(doc: kit.Docx, kind: str) -> list[str]:
+    return [node.get(kit.q("id")) for node in doc.xml("word/document.xml").iter(kit.q(kind + "Reference"))]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report footnote/endnote content and reference counts in a .docx.")
+    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
+
+    payload = {"ok": True, "input": str(Path(args.docx)), "notes": {}, "references": {}, "orphans": {}}
+    for kind in ("footnote", "endnote"):
+        notes = collect(doc, kind)
+        refs = references(doc, kind)
+        ids = {note["id"] for note in notes}
+        payload["notes"][kind] = notes
+        payload["references"][kind] = {"count": len(refs), "ids": refs}
+        payload["orphans"][kind] = {
+            "unreferenced_notes": sorted(ids - set(refs), key=lambda value: int(value) if (value or "").lstrip("-").isdigit() else 0),
+            "dangling_references": [value for value in refs if value not in ids],
+        }
+    kit.emit(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,96 @@
+#!/usr/bin/env python
+"""Undo the heading damage left by importing a document from a web editor.
+
+Imports commonly arrive with a run of empty paragraphs before the body starts and
+with the document title duplicated as a level-1 heading, which makes the outline
+read "My Doc" twice and pushes the real first section down.  The cleanup only
+touches the leading region, so a deliberate title page further in is untouched.
+
+Exit codes: 0 changed or nothing to change, 1 --check found problems, 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
+
+
+def leading_region(body, limit: int) -> list:
+    seen = 0
+    region = []
+    for child in body:
+        if child.tag == kit.q("p") and kit.paragraph_text(child).strip():
+            seen += 1
+            if seen >= limit:
+                region.append(child)
+                break
+        region.append(child)
+    return region
+
+
+def sanitize(body, limit: int) -> dict:
+    removed_empty = 0
+    removed_duplicate = 0
+    region = leading_region(body, limit)
+    for paragraph in list(region):
+        if paragraph.tag != kit.q("p") or kit.paragraph_text(paragraph).strip():
+            continue
+        parent = paragraph.getparent()
+        if parent is not None:
+            parent.remove(paragraph)
+            removed_empty += 1
+
+    region = leading_region(body, limit)
+    for index, paragraph in enumerate(region):
+        if paragraph.tag != kit.q("p") or kit.paragraph_style(paragraph) != "Title":
+            continue
+        title = kit.paragraph_text(paragraph).strip()
+        for follower in region[index + 1 :]:
+            if follower.tag != kit.q("p"):
+                continue
+            text = kit.paragraph_text(follower).strip()
+            if not text:
+                continue
+            if text == title and kit.heading_level(follower) == 1:
+                body.remove(follower)
+                removed_duplicate += 1
+            break
+    return {"removed_empty": removed_empty, "removed_duplicate_heading": removed_duplicate}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Remove leading empty paragraphs and a duplicated title heading after import.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", default=None, help="Output .docx")
+    parser.add_argument("--in-place", action="store_true", help="Rewrite the input file")
+    parser.add_argument("--check", action="store_true", help="Report only; exit 1 when cleanup is needed")
+    parser.add_argument("--leading-nonempty-paragraphs", type=int, default=3, help="How far into the document to look")
+    args = parser.parse_args(argv)
+
+    if not (args.out or args.in_place or args.check):
+        parser.error("choose --out, --in-place or --check")
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    result = sanitize(doc.body(), max(1, args.leading_nonempty_paragraphs))
+    changed = bool(result["removed_empty"] or result["removed_duplicate_heading"])
+
+    output = None
+    if args.in_place or args.out:
+        output = args.out or args.input_docx
+        doc.save(output)
+
+    kit.emit({"ok": not (args.check and changed), "changed": changed, "check": args.check, "output": str(Path(output)) if output else None, **result})
+    return 1 if (args.check and changed) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())