dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,99 @@
+#!/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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+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,118 @@
+#!/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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+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,110 @@
+#!/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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+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())

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env python
+"""Audit table widths in twips, and optionally make every table fit the page.
+
+Word stores table widths three ways (``tblW``, grid columns, cell widths) and they
+disagree often enough that a table overflows the margin after a page-size change.
+``--fix`` makes the table fixed-layout and distributes the text width across the
+grid, writing the same number to each cell so the two can no longer disagree.
+
+Exit codes: 0 clean, 1 problems found (without --fix), 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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def text_width_twips(doc: kit.Docx) -> int:
+    sections = doc.sections()
+    if not sections:
+        return 9360
+    sect = sections[0]
+    page = sect.find(kit.q("pgSz"))
+    margins = sect.find(kit.q("pgMar"))
+    width = int(page.get(kit.q("w")) or 12240) if page is not None else 12240
+    if margins is None:
+        return width - 2880
+    return width - sum(int(margins.get(kit.q(side)) or 0) for side in ("left", "right"))
+
+
+def grid_widths(table) -> list[int]:
+    grid = table.find(kit.q("tblGrid"))
+    if grid is None:
+        return []
+    widths = []
+    for column in grid.findall(kit.q("gridCol")):
+        value = column.get(kit.q("w"))
+        widths.append(int(value) if value and value.lstrip("-").isdigit() else 0)
+    return widths
+
+
+def table_info(table) -> dict:
+    props = table.find(kit.q("tblPr"))
+    width = None
+    layout = None
+    if props is not None:
+        node = props.find(kit.q("tblW"))
+        if node is not None:
+            width = {"type": node.get(kit.q("type")), "value": node.get(kit.q("w"))}
+        node = props.find(kit.q("tblLayout"))
+        if node is not None:
+            layout = node.get(kit.q("type"))
+    widths = grid_widths(table)
+    cells = table.findall(".//" + kit.q("tc"))
+    cell_widths = []
+    for cell in cells:
+        node = cell.find(kit.q("tcPr") + "/" + kit.q("tcW"))
+        if node is not None and (node.get(kit.q("w")) or "").isdigit():
+            cell_widths.append(int(node.get(kit.q("w"))))
+    return {
+        "tblW": width,
+        "layout": layout,
+        "grid_twips": widths,
+        "grid_total": sum(widths),
+        "cells": len(cells),
+        "cell_width_min": min(cell_widths) if cell_widths else None,
+        "cell_width_max": max(cell_widths) if cell_widths else None,
+    }
+
+
+def fix_table(table, target: int) -> None:
+    props = table.find(kit.q("tblPr"))
+    if props is None:
+        props = etree.Element(kit.q("tblPr"))
+        table.insert(0, props)
+    for tag in ("tblW", "tblLayout"):
+        for existing in props.findall(kit.q(tag)):
+            props.remove(existing)
+    width = etree.SubElement(props, kit.q("tblW"))
+    width.set(kit.q("type"), "dxa")
+    width.set(kit.q("w"), str(target))
+    etree.SubElement(props, kit.q("tblLayout")).set(kit.q("type"), "fixed")
+
+    columns = grid_widths(table)
+    if not columns:
+        columns = [1]
+    total = sum(columns) or len(columns)
+    scaled = [max(1, round(target * value / total)) for value in columns]
+    grid = table.find(kit.q("tblGrid"))
+    if grid is None:
+        grid = etree.Element(kit.q("tblGrid"))
+        table.insert(1, grid)
+    for column in list(grid):
+        grid.remove(column)
+    for value in scaled:
+        etree.SubElement(grid, kit.q("gridCol")).set(kit.q("w"), str(value))
+
+    for row in table.findall(kit.q("tr")):
+        position = 0
+        for cell in row.findall(kit.q("tc")):
+            span = 1
+            cell_props = cell.find(kit.q("tcPr"))
+            if cell_props is None:
+                cell_props = etree.Element(kit.q("tcPr"))
+                cell.insert(0, cell_props)
+            node = cell_props.find(kit.q("gridSpan"))
+            if node is not None and (node.get(kit.q("val")) or "").isdigit():
+                span = int(node.get(kit.q("val")))
+            own = sum(scaled[position : position + span]) or scaled[0]
+            for existing in cell_props.findall(kit.q("tcW")):
+                cell_props.remove(existing)
+            tcw = etree.SubElement(cell_props, kit.q("tcW"))
+            tcw.set(kit.q("type"), "dxa")
+            tcw.set(kit.q("w"), str(own))
+            position += span
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Audit table geometry in twips and optionally fit tables to the text width.")
+    parser.add_argument("docx", help="Input .docx")
+    parser.add_argument("--fix", action="store_true", help="Set fixed layout and rewrite grid/cell widths to fit the page")
+    parser.add_argument("--out", default=None, help="Output .docx (required with --fix, defaults to overwriting)")
+    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
+
+    target = text_width_twips(doc)
+    tables = list(doc.body().iter(kit.q("tbl")))
+    rows = [table_info(table) for table in tables]
+    findings = []
+    for index, info in enumerate(rows, start=1):
+        if info["grid_total"] and info["grid_total"] > target:
+            findings.append({"kind": "grid_wider_than_text", "table": index, "grid_total": info["grid_total"], "text_width": target})
+        if info["layout"] != "fixed":
+            findings.append({"kind": "not_fixed_layout", "table": index})
+        if info["cell_width_max"] and info["grid_total"] and info["cell_width_max"] > info["grid_total"]:
+            findings.append({"kind": "cell_wider_than_grid", "table": index})
+        if info["tblW"] and info["tblW"]["type"] == "pct" and not info["grid_total"]:
+            findings.append({"kind": "percent_width_without_grid", "table": index})
+
+    if args.fix:
+        if not tables:
+            print("error: no tables found", file=sys.stderr)
+            return 2
+        for table in tables:
+            fix_table(table, target)
+        out = args.out or args.docx
+        doc.save(out)
+        kit.emit({"ok": True, "fixed": True, "output": str(Path(out)), "tables": len(tables), "text_width": target, "findings": findings})
+        return 0
+
+    kit.emit({"ok": not findings, "text_width": target, "tables": rows, "findings": findings})
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env python
+"""Add a diagonal text watermark to the page background.
+
+The watermark is a VML text shape in the default header, which is how Word has
+stored them since the 2007 file format: it survives conversion, prints on every
+page, and can be removed again by deleting the header shape.
+
+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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add a VML text watermark to the document header.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--text", required=True, help="Watermark text, e.g. CONFIDENTIAL")
+    parser.add_argument("--color", default="#C0C0C0", help="Shape fill colour (hex)")
+    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
+
+    if kit.watermark_texts(doc):
+        print("error: this document already has a watermark; remove it first", file=sys.stderr)
+        return 2
+
+    part = doc.ensure_header_footer("header")
+    root = doc.xml(part)
+    root.append(kit.watermark_paragraph(args.text, doc.next_id(), args.color))
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "text": args.text, "part": part})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env python
+"""Find and remove VML text watermarks from headers.
+
+A watermark that was meant for a draft can end up in a signed document, and it is
+invisible in text extraction because it lives in a shape, not in a paragraph run.
+
+Exit codes: 0 clean, 1 watermarks found (report mode), 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
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report or remove watermarks stored as VML shapes in headers.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--mode", choices=("report", "remove"), default="report")
+    parser.add_argument("--contains", default=None, help="Only match watermarks containing this text")
+    parser.add_argument("--out", default=None, help="Output .docx for --mode remove")
+    args = parser.parse_args(argv)
+
+    if args.mode == "remove" and not args.out:
+        print("error: --mode remove needs --out", 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
+
+    found = kit.watermark_texts(doc)
+    if args.contains:
+        wanted = args.contains.lower()
+        found = [item for item in found if wanted in (item["text"] or "").lower()]
+
+    removed = 0
+    if args.mode == "remove" and found:
+        for item in found:
+            paragraph = item["paragraph"]
+            if paragraph is not None and paragraph.getparent() is not None:
+                paragraph.getparent().remove(paragraph)
+                removed += 1
+        doc.save(args.out)
+    elif args.mode == "remove":
+        doc.save(args.out)
+
+    kit.emit(
+        {
+            "ok": args.mode == "remove" or not found,
+            "mode": args.mode,
+            "watermarks": [{"part": item["part"], "text": item["text"]} for item in found],
+            "removed": removed,
+            "output": str(Path(args.out)) if args.out else None,
+        }
+    )
+    return 0 if (args.mode == "remove" or not found) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())