dsh-office-kit 0.1.0 → 0.3.0

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

@@ -0,0 +1,169 @@
+#!/usr/bin/env python
+"""Generate small documents that exercise the awkward parts of the format.
+
+Reviewing comments, tracked changes or watermarks is impossible without files
+that contain them, and hand-building those by clicking in Word is not repeatable.
+Each fixture targets one feature so a script's report can be judged against a
+known-clean or known-broken input.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+from docx import Document
+from docx.shared import Inches
+
+
+def base_document(title: str, paragraphs: list[str]) -> Document:
+    document = Document()
+    document.add_heading(title, level=1)
+    for text in paragraphs:
+        document.add_paragraph(text)
+    return document
+
+
+def mark_paragraph(paragraph, before: str, deleted: str, inserted: str, after: str, author: str, date: str) -> None:
+    rpr = kit.first_rpr(paragraph)
+    kit.clear_paragraph_content(paragraph)
+    paragraph.append(kit.make_run(before, etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+    deletion = etree.SubElement(paragraph, kit.q("del"))
+    deletion.set(kit.q("id"), "101")
+    deletion.set(kit.q("author"), author)
+    deletion.set(kit.q("date"), date)
+    deletion.append(kit.make_run(deleted, tag="delText"))
+    insertion = etree.SubElement(paragraph, kit.q("ins"))
+    insertion.set(kit.q("id"), "102")
+    insertion.set(kit.q("author"), author)
+    insertion.set(kit.q("date"), date)
+    insertion.append(kit.make_run(inserted))
+    paragraph.append(kit.make_run(after))
+
+
+def make_tracked(target: Path) -> dict:
+    document = base_document("Revisions demo", ["Regional revenue grew by 12% in the quarter.", "Hardware sales stayed flat."])
+    document.save(target)
+    doc = kit.Docx(target)
+    paragraphs = doc.paragraphs()
+    mark_paragraph(paragraphs[1], "Regional revenue grew by ", "12%", "14%", " in the quarter.", "Reviewer", "2024-05-01T09:00:00Z")
+    mark_paragraph(paragraphs[2], "Hardware sales ", "stayed", "remained", " flat.", "Reviewer", "2024-05-01T09:01:00Z")
+    settings = doc.xml("word/settings.xml")
+    if settings.find(kit.q("trackRevisions")) is None:
+        settings.append(settings.makeelement(kit.q("trackRevisions"), {}))
+    doc.save(target)
+    return {"path": str(target), "tracked_changes": 4}
+
+
+def make_watermark(target: Path) -> dict:
+    document = base_document("Watermark demo", ["This copy is for internal review."])
+    document.save(target)
+    doc = kit.Docx(target)
+    part = doc.ensure_header_footer("header")
+    doc.xml(part).append(kit.watermark_paragraph("DRAFT", doc.next_id()))
+    doc.save(target)
+    return {"path": str(target), "watermark": "DRAFT"}
+
+
+def make_comments(target: Path) -> dict:
+    document = base_document("Comments demo", ["The first paragraph carries a question.", "The second paragraph is clean."])
+    document.save(target)
+    doc = kit.Docx(target)
+    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")
+    comment = etree.SubElement(root, kit.q("comment"))
+    comment.set(kit.q("id"), "1")
+    comment.set(kit.q("author"), "Reviewer")
+    comment.set(kit.q("initials"), "RV")
+    comment.set(kit.q("date"), "2024-05-02T10:00:00Z")
+    body = etree.SubElement(comment, kit.q("p"))
+    etree.SubElement(etree.SubElement(body, kit.q("r")), kit.q("t")).text = "Is this number current?"
+
+    paragraph = doc.paragraphs()[1]
+    start = etree.Element(kit.q("commentRangeStart"))
+    start.set(kit.q("id"), "1")
+    paragraph.insert(1, start)
+    end = etree.SubElement(paragraph, kit.q("commentRangeEnd"))
+    end.set(kit.q("id"), "1")
+    run = etree.SubElement(paragraph, kit.q("r"))
+    etree.SubElement(run, kit.q("commentReference")).set(kit.q("id"), "1")
+    doc.save(target)
+    return {"path": str(target), "comments": 1}
+
+
+def make_edge_cases(target: Path, image_dir: Path) -> dict:
+    image_path = image_dir / "sample.png"
+    try:
+        from PIL import Image
+
+        Image.new("RGB", (320, 200), "#4472c4").save(image_path)
+    except ImportError:
+        image_path = None
+
+    document = Document()
+    document.add_heading("Edge cases", level=1)
+    document.add_paragraph("")
+    document.add_heading("A level three heading after a level one", level=3)
+    document.add_paragraph("A very long paragraph " * 40)
+    document.add_paragraph("Contact: writer@example.org or +1 555 010 9999.")
+    table = document.add_table(rows=2, cols=10)
+    for row_index in range(2):
+        for column_index in range(10):
+            table.cell(row_index, column_index).text = "R%dC%d" % (row_index + 1, column_index + 1)
+    if image_path is not None:
+        document.add_picture(str(image_path), width=Inches(4))
+    document.save(target)
+    return {"path": str(target), "fixtures": ["empty_paragraph", "skipped_heading_level", "wide_table", "image_without_alt", "contact_details"]}
+
+
+BUILDERS = {
+    "tracked": make_tracked,
+    "watermark": make_watermark,
+    "comments": make_comments,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create sample .docx files for tracked changes, watermarks, comments and edge cases.")
+    parser.add_argument("--outdir", required=True, help="Directory for the generated files")
+    parser.add_argument("--only", default="all", help="tracked, watermark, comments, edge, or all")
+    args = parser.parse_args(argv)
+
+    out_dir = Path(args.outdir).expanduser().resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    wanted = [name.strip() for name in args.only.split(",") if name.strip()]
+    if "all" in wanted:
+        wanted = ["tracked", "watermark", "comments", "edge"]
+    unknown = [name for name in wanted if name not in BUILDERS and name != "edge"]
+    if unknown:
+        print("error: unknown fixture %s" % ", ".join(unknown), file=sys.stderr)
+        return 2
+
+    results = []
+    try:
+        for name in wanted:
+            if name == "edge":
+                results.append(make_edge_cases(out_dir / "edge_cases.docx", out_dir))
+            else:
+                results.append(BUILDERS[name](out_dir / ("%s.docx" % name)))
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    kit.emit({"ok": True, "outdir": str(out_dir), "fixtures": results})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,239 @@
+#!/usr/bin/env python
+"""Append one document's body to another, carrying its parts across.
+
+Merging by pasting XML is the easy half; the hard half is that the second file's
+relationships point at its own media, numbering and styles.  This script copies
+those parts into the base under free names, remaps relationship ids and
+numbering ids, and brings over any style the appended content needs.
+
+Drawings are refused by default: a nested drawing can carry its own rel chain and
+silently break a merge, so it has to be asked for explicitly.
+
+Exit codes: 0 success, 1 refused (drawings present, incompatible input), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import posixpath
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+CT = "{http://schemas.openxmlformats.org/package/2006/content-types}"
+W_NS = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+REL_NUMBERING = kit.REL_NUMBERING
+
+
+def free_part_name(base: kit.Docx, source: str) -> str:
+    folder = posixpath.dirname(source) or "word/media"
+    stem, extension = posixpath.splitext(posixpath.basename(source))
+    candidate = posixpath.join(folder, stem + extension)
+    counter = 1
+    while base.exists(candidate):
+        candidate = posixpath.join(folder, "%s_copy%d%s" % (stem, counter, extension))
+        counter += 1
+    return candidate
+
+
+def copy_part(base: kit.Docx, append: kit.Docx, source: str) -> str:
+    target = free_part_name(base, source)
+    base.parts[target] = append.parts[source]
+    base.order.append(target)
+    base._cache.pop(target, None)
+    for node in append.content_types().findall(CT + "Override"):
+        if node.get("PartName") == "/" + source:
+            base.ensure_override(target, node.get("ContentType"))
+            break
+    return target
+
+
+def copy_defaults(base: kit.Docx, append: kit.Docx) -> None:
+    existing = {(node.get("Extension") or "").lower() for node in base.content_types().findall(CT + "Default")}
+    for node in append.content_types().findall(CT + "Default"):
+        extension = (node.get("Extension") or "").lower()
+        if extension and extension not in existing:
+            clone = etree.SubElement(base.content_types(), CT + "Default")
+            clone.set("Extension", node.get("Extension"))
+            clone.set("ContentType", node.get("ContentType"))
+            existing.add(extension)
+
+
+def ensure_style(base: kit.Docx, append: kit.Docx, wanted: str) -> bool:
+    if not append.exists("word/styles.xml") or not wanted:
+        return False
+    base_styles = base.xml("word/styles.xml")
+    present = {node.get(kit.q("styleId")) for node in base_styles.findall(kit.q("style"))}
+    if wanted in present:
+        return False
+    source_styles = {node.get(kit.q("styleId")): node for node in append.xml("word/styles.xml").findall(kit.q("style"))}
+    pending = [wanted]
+    copied = False
+    while pending:
+        style_id = pending.pop()
+        node = source_styles.get(style_id)
+        if node is None or style_id in present:
+            continue
+        clone = etree.fromstring(etree.tostring(node))
+        base_styles.append(clone)
+        present.add(style_id)
+        copied = True
+        for link_tag in ("basedOn", "next", "link"):
+            ref = node.find(kit.q(link_tag))
+            if ref is not None and ref.get(kit.q("val")):
+                pending.append(ref.get(kit.q("val")))
+    return copied
+
+
+def remap_numbering(base: kit.Docx, append: kit.Docx, nodes: list) -> dict[str, str]:
+    used = set()
+    for node in nodes:
+        for num_pr in node.iter(kit.q("numPr")):
+            num_id = num_pr.find(kit.q("numId"))
+            if num_id is not None and num_id.get(kit.q("val")):
+                used.add(num_id.get(kit.q("val")))
+    if not used or not append.exists("word/numbering.xml"):
+        return {}
+    if not base.exists("word/numbering.xml"):
+        base.parts["word/numbering.xml"] = append.parts["word/numbering.xml"]
+        base.order.append("word/numbering.xml")
+        base.ensure_override("word/numbering.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml")
+        base.ensure_rel("word/document.xml", kit.REL_NUMBERING, "numbering.xml")
+        return {}
+
+    base_root = base.xml("word/numbering.xml")
+    source_root = append.xml("word/numbering.xml")
+    base_nums = {node.get(kit.q("numId")): node for node in base_root.findall(kit.q("num"))}
+    base_abstract = {node.get(kit.q("abstractNumId")): node for node in base_root.findall(kit.q("abstractNum"))}
+    next_num = max([int(value) for value in base_nums if (value or "").isdigit()], default=0) + 1
+    next_abstract = max([int(value) for value in base_abstract if (value or "").isdigit()], default=0) + 1
+    source_nums = {node.get(kit.q("numId")): node for node in source_root.findall(kit.q("num"))}
+    source_abstract = {node.get(kit.q("abstractNumId")): node for node in source_root.findall(kit.q("abstractNum"))}
+    mapping = {}
+    for old in used:
+        node = source_nums.get(old)
+        if node is None:
+            continue
+        clone = etree.fromstring(etree.tostring(node))
+        reference = clone.find(kit.q("abstractNumId"))
+        abstract_old = reference.get(kit.q("val")) if reference is not None else None
+        if abstract_old in source_abstract and abstract_old not in base_abstract:
+            abstract_clone = etree.fromstring(etree.tostring(source_abstract[abstract_old]))
+            abstract_clone.set(kit.q("abstractNumId"), str(next_abstract))
+            base_root.insert(0, abstract_clone)
+            base_abstract[str(next_abstract)] = abstract_clone
+            next_abstract += 1
+            if reference is not None:
+                reference.set(kit.q("val"), abstract_clone.get(kit.q("abstractNumId")))
+        clone.set(kit.q("numId"), str(next_num))
+        mapping[old] = str(next_num)
+        base_root.append(clone)
+        base_nums[str(next_num)] = clone
+        next_num += 1
+    return mapping
+
+
+def remap_relationships(base: kit.Docx, append: kit.Docx, nodes: list) -> int:
+    mapping = {}
+    copied = 0
+    source_rels = {entry["id"]: entry for entry in append.relationships("word/document.xml")}
+    attributes = (kit.q("embed", kit.R), kit.q("id", kit.R), kit.q("link", kit.R))
+    for node in nodes:
+        for element in node.iter():
+            for attribute in attributes:
+                rid = element.get(attribute)
+                if not rid:
+                    continue
+                if rid not in mapping:
+                    rel = source_rels.get(rid)
+                    if rel is None:
+                        mapping[rid] = rid
+                        continue
+                    if rel["mode"] == "External":
+                        mapping[rid] = base.ensure_rel("word/document.xml", rel["type"], rel["target"], external=True)
+                    elif append.exists(rel["resolved"]):
+                        target = copy_part(base, append, rel["resolved"])
+                        relative = posixpath.relpath(target, "word")
+                        mapping[rid] = base.ensure_rel("word/document.xml", rel["type"], relative)
+                        copied += 1
+                    else:
+                        mapping[rid] = rid
+                element.set(attribute, mapping[rid])
+    return copied
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Append one .docx body to another, copying media, numbering and styles.")
+    parser.add_argument("base", help="Document to append to")
+    parser.add_argument("append", help="Document whose body is copied in")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--allow_drawings", action="store_true", help="Copy drawings and their relationships")
+    args = parser.parse_args(argv)
+
+    try:
+        base = kit.Docx(args.base)
+        append = kit.Docx(args.append)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    append_body = append.body()
+    incoming = [child for child in append_body if child.tag != kit.q("sectPr")]
+    if not incoming:
+        print("error: %s has an empty body" % args.append, file=sys.stderr)
+        return 2
+
+    has_drawings = any(child.find(".//" + tag) is not None for child in incoming for tag in (kit.q("drawing"), kit.q("pict")))
+    if has_drawings and not args.allow_drawings:
+        print("error: appended body contains drawings; re-run with --allow_drawings", file=sys.stderr)
+        return 1
+
+    style_ids = set()
+    numbering_nodes = []
+    for child in incoming:
+        for node in child.iter():
+            for tag in ("pStyle", "rStyle", "tblStyle"):
+                if node.tag == kit.q(tag) and node.get(kit.q("val")):
+                    style_ids.add(node.get(kit.q("val")))
+        if child.find(".//" + kit.q("numPr")) is not None:
+            numbering_nodes.append(child)
+
+    styles_copied = sum(1 for style_id in sorted(style_ids) if ensure_style(base, append, style_id))
+    number_map = remap_numbering(base, append, numbering_nodes)
+
+    clones = [etree.fromstring(etree.tostring(child)) for child in incoming]
+    if number_map:
+        for clone in clones:
+            for num_pr in clone.iter(kit.q("numPr")):
+                num_id = num_pr.find(kit.q("numId"))
+                if num_id is not None and num_id.get(kit.q("val")) in number_map:
+                    num_id.set(kit.q("val"), number_map[num_id.get(kit.q("val"))])
+    media_copied = remap_relationships(base, append, clones)
+    copy_defaults(base, append)
+
+    body = base.body()
+    sect = body.find(kit.q("sectPr"))
+    anchor = body.index(sect) if sect is not None else len(body)
+    for offset, clone in enumerate(clones):
+        body.insert(anchor + offset, clone)
+
+    base.save(args.out)
+    kit.emit(
+        {
+            "ok": True,
+            "output": str(Path(args.out)),
+            "appended_elements": len(clones),
+            "styles_copied": styles_copied,
+            "media_copied": media_copied,
+            "numbering_remapped": len(number_map),
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env python
+"""Remove metadata that identifies the author or the machine that edited a file.
+
+Word leaves a trail: core properties, the company and manager fields, custom
+properties, revision-save identifiers (``w:rsid*``) and spell-check markers.  None
+of it is visible in the document, all of it travels with the file.
+
+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
+
+DC = "http://purl.org/dc/elements/1.1/"
+CP = "http://schemas.openxmlformats.org/package/2006/metadata/core-properties"
+DCTERMS = "http://purl.org/dc/terms/"
+EP = "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"
+REL_CUSTOM = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties"
+
+CORE_CLEAR = ["{%s}creator" % DC, "{%s}lastModifiedBy" % CP, "{%s}keywords" % CP, "{%s}description" % DC, "{%s}subject" % DC, "{%s}title" % DC, "{%s}category" % CP]
+APP_CLEAR = ["{%s}Company" % EP, "{%s}Manager" % EP, "{%s}Application" % EP]
+
+
+def clear_core(doc: kit.Docx) -> list[str]:
+    cleared = []
+    if not doc.exists("docProps/core.xml"):
+        return cleared
+    root = doc.xml("docProps/core.xml")
+    for tag in CORE_CLEAR:
+        for node in root.findall(tag):
+            node.text = ""
+            cleared.append(tag.rsplit("}", 1)[-1])
+    for node in root.findall("{%s}revision" % CP):
+        node.text = "1"
+    return cleared
+
+
+def clear_app(doc: kit.Docx) -> list[str]:
+    cleared = []
+    if not doc.exists("docProps/app.xml"):
+        return cleared
+    root = doc.xml("docProps/app.xml")
+    for tag in APP_CLEAR:
+        for node in root.findall(tag):
+            node.text = ""
+            cleared.append(tag.rsplit("}", 1)[-1])
+    return cleared
+
+
+def drop_custom(doc: kit.Docx) -> bool:
+    dropped = False
+    if doc.exists("docProps/custom.xml"):
+        doc.drop("docProps/custom.xml")
+        doc.drop_override("docProps/custom.xml")
+        dropped = True
+    ns = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+    for name in [part for part in doc.parts if part.endswith(".rels")]:
+        root = doc.xml(name)
+        changed = False
+        for node in list(root.findall(ns + "Relationship")):
+            if node.get("Type") == REL_CUSTOM:
+                root.remove(node)
+                changed = True
+                dropped = True
+        if changed:
+            doc.set_xml(name, root)
+    return dropped
+
+
+def scrub_document(doc: kit.Docx) -> dict:
+    stats = {"rsid_attributes": 0, "proof_error_markers": 0, "render_breaks": 0}
+    for name in [part for part in doc.parts if part.endswith(".xml") and (part.startswith("word/") or part == "word/document.xml")]:
+        root = doc.xml(name)
+        changed = False
+        for node in root.iter():
+            for key in list(node.attrib):
+                if key.startswith(kit.q("rsid")) or key.startswith("{%s}rsid" % kit.W):
+                    del node.attrib[key]
+                    stats["rsid_attributes"] += 1
+                    changed = True
+        for tag, key in ((kit.q("proofErr"), "proof_error_markers"), (kit.q("lastRenderedPageBreak"), "render_breaks")):
+            for node in list(root.iter(tag)):
+                node.getparent().remove(node)
+                stats[key] += 1
+                changed = True
+        if changed:
+            doc.set_xml(name, root)
+    return stats
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Strip author, company, custom properties and revision identifiers.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--keep_title", action="store_true", help="Keep dc:title and dc:subject")
+    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
+
+    cleared = clear_core(doc) + clear_app(doc)
+    if args.keep_title:
+        cleared = [name for name in cleared if name not in ("title", "subject")]
+        root = doc.xml("docProps/core.xml")
+        original = kit.Docx(args.input_docx).xml("docProps/core.xml")
+        for tag in ("{%s}title" % DC, "{%s}subject" % DC):
+            source = original.find(tag)
+            target = root.find(tag)
+            if source is not None and target is not None:
+                target.text = source.text
+
+    custom_dropped = drop_custom(doc)
+    stats = scrub_document(doc)
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "cleared": cleared, "custom_properties_dropped": custom_dropped, **stats})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env python
+"""Mask emails, phone numbers and custom patterns in a document's text.
+
+The replacement happens inside individual text runs, so a match split across
+formatted runs is not found; that trade keeps the surrounding formatting (bold,
+italics, links) untouched.  Length-preserving masking keeps a redacted table
+aligned, which is usually why the number of characters matters.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+EMAIL = re.compile(r"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}")
+PHONE = re.compile(r"(?<!\d)(?:\+\d{1,3}[\s.\-]?)?(?:\(\d{2,4}\)[\s.\-]?)?\d{2,4}[\s.\-]\d{3,4}(?:[\s.\-]\d{3,4})?(?!\d)")
+
+
+def redact_text(text: str, patterns: list[re.Pattern], mask: str, preserve: bool) -> tuple[str, int]:
+    total = 0
+    for pattern in patterns:
+        def replace(match: re.Match) -> str:
+            nonlocal total
+            total += 1
+            return (mask * len(match.group(0))) if preserve else mask
+
+        text = pattern.sub(replace, text)
+    return text, total
+
+
+def collect_parts(doc: kit.Docx, include_comments: bool) -> list[str]:
+    parts = ["word/document.xml"] + doc.names("word/header") + doc.names("word/footer")
+    for note in ("word/footnotes.xml", "word/endnotes.xml"):
+        if doc.exists(note):
+            parts.append(note)
+    if include_comments and doc.exists("word/comments.xml"):
+        parts.append("word/comments.xml")
+    return parts
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Mask emails, phone numbers or custom regex matches in text runs.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("output_docx", help="Output .docx")
+    parser.add_argument("--emails", action="store_true", help="Redact email addresses (default when no pattern is given)")
+    parser.add_argument("--phones", action="store_true", help="Redact phone numbers (default when no pattern is given)")
+    parser.add_argument("--pattern", action="append", default=[], help="Extra regex to redact (repeatable)")
+    parser.add_argument("--mask_char", default="*", help="Masking character")
+    parser.add_argument("--replacement", default="[redacted]", help="Replacement text when length is not preserved")
+    parser.add_argument("--no_preserve_length", action="store_true", help="Use --replacement instead of a per-character mask")
+    parser.add_argument("--include_comments", action="store_true", help="Also redact comment text")
+    args = parser.parse_args(argv)
+
+    patterns: list[re.Pattern] = []
+    if args.emails or not (args.emails or args.phones or args.pattern):
+        patterns.append(EMAIL)
+    if args.phones or not (args.emails or args.phones or args.pattern):
+        patterns.append(PHONE)
+    for raw in args.pattern:
+        try:
+            patterns.append(re.compile(raw))
+        except re.error as exc:
+            print("error: bad --pattern %r: %s" % (raw, exc), file=sys.stderr)
+            return 2
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    mask = args.replacement if args.no_preserve_length else (args.mask_char or "*")[:1]
+    preserve = not args.no_preserve_length
+    matches = 0
+    touched_parts = []
+    for part in collect_parts(doc, args.include_comments):
+        if not doc.exists(part):
+            continue
+        root = doc.xml(part)
+        part_matches = 0
+        for node in root.iter(kit.q("t")):
+            if not node.text:
+                continue
+            updated, count = redact_text(node.text, patterns, mask, preserve)
+            if count:
+                node.text = updated
+                part_matches += count
+        for node in root.iter(kit.q("delText")):
+            if not node.text:
+                continue
+            updated, count = redact_text(node.text, patterns, mask, preserve)
+            if count:
+                node.text = updated
+                part_matches += count
+        if part_matches:
+            doc.set_xml(part, root)
+            matches += part_matches
+            touched_parts.append({"part": part, "matches": part_matches})
+
+    doc.save(args.output_docx)
+    kit.emit({"ok": True, "output": str(Path(args.output_docx)), "matches": matches, "patterns": len(patterns), "parts": touched_parts})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())