dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+"""Edit existing comments in place from a JSON patch file.
+
+The patch is a JSON list (or an object with an ``ops`` list) of operations keyed
+by comment id:
+
+    [{"id": 1, "append": "Also check 2024."},
+     {"id": 2, "replace": "Rewritten note."},
+     {"id": 3, "resolved": true}]
+
+``append`` adds a paragraph, ``replace`` rewrites the body, and ``resolved``
+marks the comment done (the threading metadata Word uses for "Resolve").
+
+Exit codes: 0 all operations applied, 1 some ids were missing, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+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 set_body(comment, text: str) -> None:
+    paragraphs = comment.findall(kit.q("p"))
+    if not paragraphs:
+        paragraph = etree.SubElement(comment, kit.q("p"))
+    else:
+        paragraph = paragraphs[0]
+        for extra in paragraphs[1:]:
+            comment.remove(extra)
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space", kit.XML), "preserve")
+
+
+def append_body(comment, text: str) -> None:
+    paragraph = etree.SubElement(comment, kit.q("p"))
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space", kit.XML), "preserve")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Apply append/replace/resolve operations to existing Word comments.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("patch_json", help="JSON patch file")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    args = parser.parse_args(argv)
+
+    try:
+        patch = json.loads(Path(args.patch_json).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print("error: cannot read patch: %s" % exc, file=sys.stderr)
+        return 2
+    ops = patch.get("ops") if isinstance(patch, dict) else patch
+    if not isinstance(ops, list):
+        print("error: patch must be a list or an object with an 'ops' list", file=sys.stderr)
+        return 2
+
+    try:
+        doc = kit.Docx(args.in_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+    if not doc.exists("word/comments.xml"):
+        print("error: document has no comments", file=sys.stderr)
+        return 1
+
+    by_id = {node.get(kit.q("id")): node for node in doc.xml("word/comments.xml").findall(kit.q("comment"))}
+    applied, missing = [], []
+    for op in ops:
+        if not isinstance(op, dict):
+            print("error: each operation must be an object", file=sys.stderr)
+            return 2
+        ident = str(op.get("id"))
+        comment = by_id.get(ident)
+        if comment is None:
+            missing.append(ident)
+            continue
+        changed = []
+        if "replace" in op:
+            set_body(comment, str(op["replace"]))
+            changed.append("replace")
+        if "append" in op:
+            append_body(comment, str(op["append"]))
+            changed.append("append")
+        if "resolved" in op:
+            if op["resolved"]:
+                comment.set(kit.q("done", kit.W15), "1")
+            else:
+                comment.attrib.pop(kit.q("done", kit.W15), None)
+            changed.append("resolved")
+        applied.append({"id": ident, "changes": changed})
+
+    doc.save(args.out)
+    kit.emit({"ok": not missing, "output": str(Path(args.out)), "applied": applied, "missing_ids": missing})
+    return 1 if missing else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,85 @@
+#!/usr/bin/env python
+"""Extract Word comments to JSON, including the text each comment is anchored to.
+
+The anchor is recovered by walking the marked-up parts in document order and
+collecting the text between ``commentRangeStart`` and ``commentRangeEnd`` for
+the same id.  Comments whose range was lost still appear, with an empty anchor.
+
+Exit codes: 0 success (an empty list when the file has no comments), 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 anchor_map(doc: kit.Docx) -> dict[str, dict]:
+    found: dict[str, dict] = {}
+    hf = [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    parts = ["word/document.xml"] + hf + [part for part in doc.text_parts() if part != "word/document.xml"]
+    for part in parts:
+        active = None
+        for node in doc.xml(part).iter():
+            if not isinstance(node.tag, str):
+                continue
+            local = node.tag.split("}", 1)[1] if node.tag.startswith("{%s}" % kit.W) else ""
+            if local == "commentRangeStart":
+                ident = node.get(kit.q("id")) or ""
+                active = ident
+                found.setdefault(ident, {"part": part, "anchored_text": ""})
+            elif local == "commentRangeEnd":
+                if active is not None and (node.get(kit.q("id")) or "") == active:
+                    active = None
+            elif local == "commentReference" and active is None:
+                ident = node.get(kit.q("id")) or ""
+                found.setdefault(ident, {"part": part, "anchored_text": ""})
+            elif active is not None and local in ("t", "delText"):
+                found.setdefault(active, {"part": part, "anchored_text": ""})["anchored_text"] += node.text or ""
+    return found
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Extract comments (author, date, body, anchored text) from a .docx.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Write the JSON report here")
+    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
+    if not doc.exists("word/comments.xml"):
+        kit.emit({"ok": True, "input": str(Path(args.in_docx)), "count": 0, "comments": []}, args.out)
+        return 0
+
+    anchors = anchor_map(doc)
+    comments = []
+    for node in doc.xml("word/comments.xml").findall(kit.q("comment")):
+        ident = node.get(kit.q("id")) or ""
+        paragraphs = [kit.text_of(paragraph) for paragraph in node.iter(kit.q("p"))]
+        info = anchors.get(ident, {})
+        comments.append(
+            {
+                "id": int(ident) if ident.lstrip("-").isdigit() else ident,
+                "author": node.get(kit.q("author")) or "",
+                "initials": node.get(kit.q("initials")) or "",
+                "date": node.get(kit.q("date")) or "",
+                "text": "\n".join(text for text in paragraphs if text),
+                "anchored_text": info.get("anchored_text", "").strip(),
+                "part": info.get("part"),
+                "resolved": node.get(kit.q("done", kit.W15)) in ("1", "true"),
+            }
+        )
+    comments.sort(key=lambda item: item["id"] if isinstance(item["id"], int) else 0)
+    kit.emit({"ok": True, "input": str(Path(args.in_docx)), "count": len(comments), "comments": comments}, args.out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env python
+"""Remove every comment from a .docx: markers, bodies, relationships, part.
+
+Word needs all four removed together.  Leaving a stray ``commentReference``
+behind makes Word report a corrupt package, and leaving comments.xml in the zip
+re-adds metadata you thought you deleted, so each is handled here.
+
+Exit codes: 0 success (also when there was nothing to strip), 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
+
+MARKERS = ("commentRangeStart", "commentRangeEnd", "commentReference")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Strip all comments and comment markers from a .docx.")
+    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
+
+    hf = [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    removed_markers = 0
+    for part in ["word/document.xml"] + hf + doc.text_parts():
+        if not doc.exists(part):
+            continue
+        root = doc.xml(part)
+        for local in MARKERS:
+            for node in list(root.iter(kit.q(local))):
+                parent = node.getparent()
+                if parent is None:
+                    continue
+                if local == "commentReference" and parent.tag == kit.q("r") and len(parent) <= 1:
+                    grand = parent.getparent()
+                    if grand is not None:
+                        grand.remove(parent)
+                else:
+                    parent.remove(node)
+                removed_markers += 1
+
+    had_part = doc.exists("word/comments.xml")
+    if had_part:
+        doc.drop("word/comments.xml")
+        doc.drop_rel_target("word/document.xml", "word/comments.xml")
+        doc.drop_override("word/comments.xml")
+
+    doc.save(args.out)
+    kit.emit(
+        {
+            "ok": True,
+            "input": str(Path(args.in_docx)),
+            "output": str(Path(args.out)),
+            "comments_part_removed": had_part,
+            "markers_removed": removed_markers,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,192 @@
+#!/usr/bin/env python
+"""Read or edit Word content controls (structured document tags / SDT).
+
+python-docx has no API for content controls, so this works directly on the
+``w:sdt`` elements: list them, wrap a paragraph into a typed control, or replace
+the text of controls matched by tag.  Tags are the stable key — they survive
+copying between documents better than the numeric ids.
+
+Exit codes: 0 success, 1 a tag was not found, 2 bad input or bad subcommand.
+"""
+
+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
+
+TYPE_TAGS = ("text", "richText", "date", "dropDownList", "comboBox", "picture", "checkbox")
+CONTAINER_TAGS = ("docPartObj", "group", "citation", "bibliography")
+
+
+def part_list(doc: kit.Docx, include_headers: bool) -> list[str]:
+    parts = ["word/document.xml"]
+    if include_headers:
+        parts += [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    return [part for part in parts if doc.exists(part)]
+
+
+def controls(doc: kit.Docx, part: str):
+    return [node for node in doc.xml(part).iter(kit.q("sdt")) if node.find(kit.q("sdtPr")) is not None]
+
+
+def describe(doc: kit.Docx, part: str, sdt) -> dict:
+    props = sdt.find(kit.q("sdtPr"))
+    tag = props.find(kit.q("tag")) if props is not None else None
+    alias = props.find(kit.q("alias")) if props is not None else None
+    ident = props.find(kit.q("id")) if props is not None else None
+    kind = "unknown"
+    if props is not None:
+        for name in TYPE_TAGS:
+            if props.find(kit.q(name)) is not None:
+                kind = name
+                break
+        if kind == "unknown" and any(props.find(kit.q(name)) is not None for name in CONTAINER_TAGS):
+            kind = "container"
+    content = sdt.find(kit.q("sdtContent"))
+    text = kit.text_of(content) if content is not None else ""
+    return {
+        "part": part,
+        "tag": tag.get(kit.q("val")) if tag is not None else "",
+        "alias": alias.get(kit.q("val")) if alias is not None else "",
+        "id": ident.get(kit.q("val")) if ident is not None else "",
+        "type": kind,
+        "text": text,
+    }
+
+
+def build_control(tag: str, alias: str, text: str, ident: int, content) -> etree._Element:
+    sdt = etree.Element(kit.q("sdt"))
+    props = etree.SubElement(sdt, kit.q("sdtPr"))
+    if tag:
+        etree.SubElement(props, kit.q("tag")).set(kit.q("val"), tag)
+    if alias:
+        etree.SubElement(props, kit.q("alias")).set(kit.q("val"), alias)
+    etree.SubElement(props, kit.q("id")).set(kit.q("val"), str(ident))
+    etree.SubElement(props, kit.q("text"))
+    body = etree.SubElement(sdt, kit.q("sdtContent"))
+    if content is not None:
+        body.append(content)
+    else:
+        paragraph = etree.SubElement(body, kit.q("p"))
+        run = etree.SubElement(paragraph, kit.q("r"))
+        node = etree.SubElement(run, kit.q("t"))
+        node.text = text
+    return sdt
+
+
+def replace_text(sdt, value: str) -> bool:
+    content = sdt.find(kit.q("sdtContent"))
+    if content is None:
+        return False
+    paragraphs = list(content.iter(kit.q("p")))
+    if not paragraphs:
+        return False
+    paragraph = paragraphs[0]
+    for extra in paragraphs[1:]:
+        parent = extra.getparent()
+        if parent is not None:
+            parent.remove(extra)
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = value
+    node.set(kit.q("space"), kit.XML)
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="List, create, or fill Word content controls (SDTs).")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    listing = sub.add_parser("list", help="list content controls")
+    listing.add_argument("docx")
+    listing.add_argument("--json", action="store_true", help="emit JSON (always on; kept for scripts)")
+    listing.add_argument("--no_headers_footers", action="store_true")
+
+    create = sub.add_parser("create", help="wrap a paragraph or add a new control")
+    create.add_argument("docx")
+    create.add_argument("--tag", default="", help="Stable tag used by later edits")
+    create.add_argument("--alias", default="", help="Display name shown in Word")
+    create.add_argument("--text", default="", help="Initial value for a new control")
+    create.add_argument("--placeholder", default="", help="Wrap the paragraph containing this text instead of adding a new control")
+    create.add_argument("--output", required=True)
+    create.add_argument("--no_headers_footers", action="store_true")
+
+    update = sub.add_parser("set", help="fill controls by tag")
+    update.add_argument("docx")
+    update.add_argument("--set", action="append", default=[], help="TAG=VALUE (repeatable)")
+    update.add_argument("--output", required=True)
+    update.add_argument("--no_headers_footers", action="store_true")
+
+    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
+
+    if args.command == "list":
+        rows = []
+        for part in part_list(doc, not args.no_headers_footers):
+            for sdt in controls(doc, part):
+                rows.append(describe(doc, part, sdt))
+        kit.emit({"ok": True, "input": str(Path(args.docx)), "count": len(rows), "controls": rows})
+        return 0
+
+    if args.command == "set":
+        if not args.set:
+            parser.error("at least one --set TAG=VALUE is required")
+        wanted = {}
+        for raw in args.set:
+            if "=" not in raw:
+                parser.error("--set expects TAG=VALUE, got %r" % raw)
+            tag, value = raw.split("=", 1)
+            wanted[tag] = value
+        filled, missing = [], []
+        for part in part_list(doc, not args.no_headers_footers):
+            for sdt in controls(doc, part):
+                info = describe(doc, part, sdt)
+                if info["tag"] in wanted and replace_text(sdt, wanted[info["tag"]]):
+                    filled.append({"tag": info["tag"], "value": wanted[info["tag"]], "part": part})
+                    wanted.pop(info["tag"], None)
+        missing = sorted(wanted)
+        doc.save(args.output)
+        kit.emit({"ok": not missing, "output": str(Path(args.output)), "filled": filled, "missing_tags": missing})
+        return 1 if missing else 0
+
+    ident = doc.next_id()
+    if args.placeholder:
+        target = None
+        for paragraph in doc.paragraphs():
+            if args.placeholder in kit.paragraph_text(paragraph):
+                target = paragraph
+                break
+        if target is None:
+            print("error: placeholder %r not found" % args.placeholder, file=sys.stderr)
+            return 1
+        parent = target.getparent()
+        index = list(parent).index(target)
+        sdt = build_control(args.tag, args.alias, args.text, ident, target)
+        parent.insert(index, sdt)
+        where = "wrapped"
+    else:
+        sdt = build_control(args.tag, args.alias, args.text, ident, None)
+        doc.body().append(sdt)
+        where = "appended"
+    doc.save(args.output)
+    kit.emit({"ok": True, "output": str(Path(args.output)), "mode": where, "tag": args.tag, "id": ident})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Read or set the core properties of a Word document.
+
+Core properties are the metadata a reader sees in File > Info: title, author,
+subject, keywords, comments, category and the last modifier. They live outside
+the body in docProps/core.xml, so changing them never touches the content.
+
+Usage:
+  core_properties.py --input IN.docx [--out OUT.docx] --title "..." --author "..."
+  core_properties.py --input IN.docx [--out OUT.docx] --spec core.json
+  core_properties.py --input IN.docx --show
+
+The spec file is {"core": {"title": "...", "author": "..."}} or a bare object of
+the same names. With no property arguments the command only reports.
+
+Exit codes: 0 success, 1 the document or spec could not be read, 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
+
+TEXT_FIELDS = (
+    "title",
+    "author",
+    "subject",
+    "keywords",
+    "comments",
+    "category",
+    "last_modified_by",
+    "content_status",
+    "identifier",
+    "language",
+    "version",
+)
+INT_FIELDS = ("revision",)
+
+
+def fail(payload: dict, code: int = 1) -> int:
+    kit.emit({"ok": False, **payload})
+    return code
+
+
+def snapshot(document) -> dict:
+    props = document.core_properties
+    data: dict = {}
+    for name in TEXT_FIELDS:
+        value = getattr(props, name, None)
+        data[name] = "" if value is None else str(value)
+    for name in INT_FIELDS:
+        data[name] = getattr(props, name, None)
+    return data
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Read or set .docx core properties.")
+    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("--spec", help="JSON file with a core properties object")
+    parser.add_argument("--show", action="store_true", help="report properties and change nothing")
+    for name in TEXT_FIELDS:
+        parser.add_argument("--" + name.replace("_", "-"), dest=name, help=f"set {name}")
+    parser.add_argument("--revision", type=int, help="set the revision counter")
+    args = parser.parse_args()
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        return fail({"error": f"input not found: {args.input}"})
+
+    updates: dict = {}
+    if args.spec:
+        try:
+            payload = json.loads(Path(args.spec).expanduser().read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            return fail({"error": f"cannot read spec: {exc}"}, 2)
+        updates.update(payload.get("core", payload) if isinstance(payload, dict) else {})
+    for name in TEXT_FIELDS:
+        value = getattr(args, name)
+        if value is not None:
+            updates[name] = value
+    if args.revision is not None:
+        updates["revision"] = args.revision
+
+    unknown = [key for key in updates if key not in TEXT_FIELDS and key not in INT_FIELDS]
+    if unknown:
+        return fail({"error": "unknown properties: " + ", ".join(sorted(unknown)), "known": list(TEXT_FIELDS)}, 2)
+
+    from docx import Document
+
+    document = Document(str(source))
+    before = snapshot(document)
+    if args.show or not updates:
+        kit.emit({"ok": True, "input": str(source), "properties": before})
+        return 0
+
+    for key, value in updates.items():
+        setattr(document.core_properties, key, value)
+    after = snapshot(document)
+
+    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"})
+    out.parent.mkdir(parents=True, exist_ok=True)
+    document.save(str(out))
+    kit.emit({
+        "ok": True,
+        "input": str(source),
+        "output": str(out),
+        "changed": sorted(updates),
+        "before": {key: before[key] for key in updates},
+        "after": {key: after[key] for key in updates},
+    })
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())