dsh-office-kit 0.2.0 → 0.3.0

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

@@ -0,0 +1,148 @@
+#!/usr/bin/env python
+"""Turn find/replace edits into tracked revisions (delete + insert).
+
+Each ``--replace OLD=NEW`` finds the literal text inside a paragraph and
+rewrites just the runs it covers: the old characters become a ``w:del`` and the
+new characters a ``w:ins``, both attributed to ``--author``.  Word then shows
+the edit as a suggestion instead of an opaque rewrite.  Tracking is switched on
+in settings.xml so follow-up edits are recorded too.
+
+Exit codes: 0 success (replacements may still be zero), 1 no replacement matched,
+2 bad input or malformed --replace.
+"""
+
+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
+
+
+def split_pair(raw: str) -> tuple[str, str]:
+    if "=" not in raw:
+        raise argparse.ArgumentTypeError("--replace expects OLD=NEW, got %r" % raw)
+    old, new = raw.split("=", 1)
+    if not old:
+        raise argparse.ArgumentTypeError("--replace needs a non-empty OLD value")
+    return old, new
+
+
+def run_text(run) -> str:
+    return kit.text_of(run)
+
+
+def tracked_replace(paragraph, old: str, new: str, author: str, stamp: str, counter: list[int]) -> bool:
+    full = kit.paragraph_text(paragraph)
+    start = full.find(old)
+    if start < 0:
+        return False
+    end = start + len(old)
+    runs = [child for child in paragraph if child.tag == kit.q("r")]
+    if not runs:
+        return False
+
+    out: list = []
+    deleted: list = []
+    insert_at: int | None = None
+    cursor = 0
+    for run in runs:
+        text = run_text(run)
+        rpr = run.find(kit.q("rPr"))
+        left_end = start
+        right_start = end
+        run_start, run_end = cursor, cursor + len(text)
+        cursor = run_end
+        if run_end <= left_end or run_start >= right_start:
+            out.append(run)
+            continue
+        left = text[: max(0, left_end - run_start)]
+        middle = text[max(0, left_end - run_start) : min(len(text), right_start - run_start)]
+        right = text[min(len(text), right_start - run_start) :]
+        if left:
+            out.append(kit.make_run(left, rpr))
+        if middle:
+            if insert_at is None:
+                insert_at = len(out)
+            deleted.append(kit.make_run(middle, rpr, tag="delText"))
+        if right:
+            out.append(kit.make_run(right, rpr))
+
+    if not deleted:
+        return False
+
+    ident = counter[0]
+    counter[0] += 2
+    deletion = etree.Element(kit.q("del"))
+    deletion.set(kit.q("id"), str(ident))
+    deletion.set(kit.q("author"), author)
+    deletion.set(kit.q("date"), stamp)
+    for node in deleted:
+        deletion.append(node)
+    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"), stamp)
+    insertion.append(kit.make_run(new))
+
+    position = insert_at if insert_at is not None else len(out)
+    out.insert(position, deletion)
+    out.insert(position + 1, insertion)
+
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    for child in out:
+        paragraph.append(child)
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Record find/replace edits as tracked deletions and insertions.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--author", default="dsh-office", help="Revision author shown in Word")
+    parser.add_argument("--replace", action="append", default=[], help="Replacement formatted as OLD=NEW (repeatable)")
+    parser.add_argument("--date", default=None, help="ISO timestamp for the revisions (default: now, UTC)")
+    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 args.replace:
+        parser.error("at least one --replace OLD=NEW is required")
+
+    stamp = args.date or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    counter = [doc.next_id()]
+    applied = []
+    for raw in args.replace:
+        try:
+            old, new = split_pair(raw)
+        except argparse.ArgumentTypeError as exc:
+            print("error: %s" % exc, file=sys.stderr)
+            return 2
+        hits = 0
+        for paragraph in doc.paragraphs():
+            if tracked_replace(paragraph, old, new, args.author, stamp, counter):
+                hits += 1
+        applied.append({"old": old, "new": new, "paragraphs": hits})
+
+    settings = doc.xml("word/settings.xml")
+    if settings.find(kit.q("trackRevisions")) is None:
+        settings.append(settings.makeelement(kit.q("trackRevisions"), {}))
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "author": args.author, "replacements": applied})
+    return 0 if any(item["paragraphs"] for item in applied) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Append blocks to the end of an existing Word document.
+
+The block builder (headings, paragraphs, bullets, numbered lists, tables,
+images, equations, quotes, page breaks, spacers) is the helper CLI's own
+`_docx_add_blocks`, imported rather than re-implemented so a spec that works
+with `docx create` works here too.
+
+Usage:
+  append_blocks.py --input IN.docx [--out OUT.docx] --blocks blocks.json
+  append_blocks.py --input IN.docx [--out OUT.docx] --spec spec.json
+
+`--blocks` takes a JSON list of blocks or {"blocks": [...]}; `--spec` takes a
+document spec whose `blocks` (or `sections`) array is appended.
+
+Exit codes: 0 appended, 1 the document or a block could not be handled, 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
+
+COUNTER_KEYS = ("headings", "paragraphs", "list_items", "tables", "images", "equations", "equation_fallbacks")
+
+
+def fail(payload: dict, code: int = 1) -> int:
+    kit.emit({"ok": False, **payload})
+    return code
+
+
+def load_builder():
+    cli = kit.office_cli_path()
+    if cli is None:
+        raise FileNotFoundError("helper CLI not found; set DSH_OFFICE_CLI to python/office_cli.py")
+    sys.path.insert(0, str(cli.parent))
+    import office_cli
+
+    return office_cli
+
+
+def load_blocks(args) -> list[dict]:
+    raw = args.blocks or args.spec
+    text = raw.strip()
+    if text.startswith(("[", "{")):
+        payload = json.loads(text)
+    else:
+        payload = json.loads(Path(text).expanduser().read_text(encoding="utf-8"))
+    if isinstance(payload, list):
+        blocks = payload
+    else:
+        blocks = payload.get("blocks", payload.get("sections", []))
+    if not isinstance(blocks, list):
+        raise ValueError("blocks must be a JSON array")
+    return [block for block in blocks if isinstance(block, dict)]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Append content blocks to a .docx copy.")
+    parser.add_argument("--input", required=True, help="source .docx (never modified)")
+    parser.add_argument("--out", help="output path; default <name>-edited.docx")
+    parser.add_argument("--blocks", help="JSON file holding an array of blocks")
+    parser.add_argument("--spec", help="JSON document spec; its blocks array is appended")
+    args = parser.parse_args()
+
+    if not (args.blocks or args.spec):
+        return fail({"error": "pass --blocks or --spec"}, 2)
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        return fail({"error": f"input not found: {args.input}"})
+    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"})
+
+    try:
+        blocks = load_blocks(args)
+    except (OSError, ValueError) as exc:
+        return fail({"error": f"cannot read blocks: {exc}"}, 2)
+
+    try:
+        office_cli = load_builder()
+    except FileNotFoundError as exc:
+        return fail({"error": str(exc)})
+
+    from docx import Document
+
+    document = Document(str(source))
+    counters = {key: 0 for key in COUNTER_KEYS}
+    try:
+        office_cli._docx_add_blocks(document, blocks, counters)
+    except SystemExit as exc:  # the builder reports bad blocks through the CLI
+        return fail({"error": f"a block was rejected: {exc}", "counts": counters})
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    document.save(str(out))
+    kit.emit({"ok": True, "input": str(source), "output": str(out), "appended": len(blocks), "counts": counters})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+"""Merge a style pack (another .docx/.dotx) into a target .docx.
+
+Only the formatting layer is transplanted: styles, and the numbering
+definitions the styles point at.  Body content, media, headers and section
+geometry stay exactly as they are in the target.  Styles that share an id are
+replaced, target-only styles survive, and template-only styles are appended so
+named styles referenced by the pack resolve.
+
+Exit codes: 0 success, 1 template has no styles part, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import zipfile
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+
+def load_xml(path: Path, part: str):
+    with zipfile.ZipFile(path) as zf:
+        if part not in zf.namelist():
+            return None
+        return etree.fromstring(zf.read(part))
+
+
+def merge_styles(doc: kit.Docx, template_styles) -> dict:
+    target = doc.xml("word/styles.xml")
+    incoming = {node.get(kit.q("styleId")): node for node in template_styles.findall(kit.q("style")) if node.get(kit.q("styleId"))}
+    existing = {node.get(kit.q("styleId")): node for node in target.findall(kit.q("style")) if node.get(kit.q("styleId"))}
+    replaced = added = 0
+    for style_id, node in incoming.items():
+        clone = etree.fromstring(etree.tostring(node))
+        if style_id in existing:
+            target.replace(existing[style_id], clone)
+            existing[style_id] = clone
+            replaced += 1
+        else:
+            target.append(clone)
+            existing[style_id] = clone
+            added += 1
+    template_defaults = template_styles.find(kit.q("docDefaults"))
+    if template_defaults is not None:
+        clone = etree.fromstring(etree.tostring(template_defaults))
+        current = target.find(kit.q("docDefaults"))
+        if current is not None:
+            target.replace(current, clone)
+        else:
+            target.insert(0, clone)
+    return {"replaced": replaced, "added": added, "total": len(existing)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Apply the styles and numbering of a template .docx/.dotx to a target .docx.")
+    parser.add_argument("--template", required=True, help="Template or style-pack .docx/.dotx")
+    parser.add_argument("--target", required=True, help="Document whose styles should be updated")
+    parser.add_argument("--out", required=True, help="Output .docx (never overwrite the target)")
+    args = parser.parse_args(argv)
+
+    template_path = Path(args.template)
+    if template_path.suffix.lower() == ".dotx":
+        # A .dotx is a .docx package with a different content type; reading the
+        # zip directly works the same, so no conversion is needed.
+        pass
+    try:
+        template_styles = load_xml(template_path, "word/styles.xml")
+    except OSError as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+    if template_styles is None:
+        print("error: template has no word/styles.xml", file=sys.stderr)
+        return 1
+
+    try:
+        doc = kit.Docx(args.target)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    stats = merge_styles(doc, template_styles)
+    template_numbering = None
+    try:
+        template_numbering = load_xml(template_path, "word/numbering.xml")
+    except OSError:
+        template_numbering = None
+    if template_numbering is not None:
+        doc.set_xml("word/numbering.xml", etree.fromstring(etree.tostring(template_numbering)))
+        doc.ensure_override("word/numbering.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml")
+        doc.ensure_rel("word/document.xml", kit.REL_NUMBERING, "numbering.xml")
+        stats["numbering"] = "copied"
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "template": str(template_path), "target": str(Path(args.target)), "output": str(Path(args.out)), "styles": stats})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+"""Add numbered captions under tables and figures, with optional bookmarks.
+
+The number is written as a ``SEQ`` field by default so Word renumbers when
+captions move, with the current value cached as the field result so a renderer
+that skips fields still shows a number.  ``--bookmarks`` adds stable bookmark
+names (tbl1, fig1, ...) which ``insert_ref_fields.py`` can then reference.
+
+Exit codes: 0 success, 2 bad input, 3 --materialize requested alongside a field
+mode conflict (never raised: materialize simply writes literal numbers).
+"""
+
+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
+
+CAPTION_LABEL = {"table": "Table", "figure": "Figure"}
+
+
+def caption_paragraph(label: str, number: int, text: str, bookmark: str | None, ident: int, materialize: bool):
+    paragraph = etree.Element(kit.q("p"))
+    props = etree.SubElement(paragraph, kit.q("pPr"))
+    etree.SubElement(props, kit.q("pStyle")).set(kit.q("val"), "Caption")
+    paragraph.append(kit.make_run("%s " % label))
+    if bookmark:
+        start = etree.SubElement(paragraph, kit.q("bookmarkStart"))
+        start.set(kit.q("id"), str(ident))
+        start.set(kit.q("name"), bookmark)
+    if materialize:
+        paragraph.append(kit.make_run(str(number)))
+    else:
+        for run in kit.field_runs("SEQ %s \\* ARABIC" % label, str(number)):
+            paragraph.append(run)
+    if bookmark:
+        end = etree.SubElement(paragraph, kit.q("bookmarkEnd"))
+        end.set(kit.q("id"), str(ident))
+    if text:
+        paragraph.append(kit.make_run(". " + text))
+    return paragraph
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Insert numbered table/figure captions, optionally bookmarking them.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("output_docx", help="Output .docx")
+    parser.add_argument("--tables", action="store_true", help="Caption tables")
+    parser.add_argument("--figures", action="store_true", help="Caption figures (paragraphs containing a drawing)")
+    parser.add_argument("--caption_text", default="", help="Text placed after the number")
+    parser.add_argument("--bookmarks", action="store_true", help="Add tblN/figN bookmarks around the number")
+    parser.add_argument("--materialize", action="store_true", help="Write literal numbers instead of SEQ fields")
+    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
+
+    do_tables = args.tables or args.figures
+    want_tables = args.tables or not do_tables
+    want_figures = args.figures or not do_tables
+
+    body = doc.body()
+    tables = list(body.iter(kit.q("tbl"))) if want_tables else []
+    figures = []
+    if want_figures:
+        for paragraph in body.iter(kit.q("p")):
+            if paragraph.find(".//" + kit.q("drawing")) is not None or paragraph.find(".//" + kit.q("pict", kit.V)) is not None:
+                figures.append(paragraph)
+
+    ident = doc.next_id()
+    added = []
+    for index, table in enumerate(tables, start=1):
+        bookmark = "tbl%d" % index if args.bookmarks else None
+        paragraph = caption_paragraph(CAPTION_LABEL["table"], index, args.caption_text, bookmark, ident, args.materialize)
+        table.addnext(paragraph)
+        added.append({"kind": "table", "number": index, "bookmark": bookmark})
+        ident += 1
+    for index, figure in enumerate(figures, start=1):
+        bookmark = "fig%d" % index if args.bookmarks else None
+        paragraph = caption_paragraph(CAPTION_LABEL["figure"], index, args.caption_text, bookmark, ident, args.materialize)
+        figure.addnext(paragraph)
+        added.append({"kind": "figure", "number": index, "bookmark": bookmark})
+        ident += 1
+
+    if not added:
+        print("error: no tables or figures found to caption", file=sys.stderr)
+        return 2
+    doc.save(args.output_docx)
+    kit.emit({"ok": True, "output": str(Path(args.output_docx)), "captions": added})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,136 @@
+#!/usr/bin/env python
+"""Attach Word comments to the paragraphs that contain given text.
+
+Each ``--add "needle=comment body"`` anchors a comment over the first paragraph
+whose text contains ``needle``: range start, range end and the reference run are
+inserted inline, and the comment body is appended to comments.xml.  Nothing is
+reworded; the body is exactly the text you pass.
+
+Exit codes: 0 all comments placed, 1 a pattern matched nothing (with
+--require_all nothing is written), 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
+
+
+def comments_root(doc: kit.Docx):
+    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")
+    return doc.xml("word/comments.xml")
+
+
+def initials(name: str) -> str:
+    parts = [piece for piece in name.replace(".", " ").split() if piece]
+    return "".join(piece[0] for piece in parts)[:3].upper() or "OR"
+
+
+def append_comment(root, text: str, author: str, stamp: str, ident: int) -> None:
+    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"), initials(author))
+    comment.set(kit.q("date"), stamp)
+    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 anchor(paragraph, ident: int) -> None:
+    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))
+    run = etree.SubElement(paragraph, kit.q("r"))
+    ref = etree.SubElement(run, kit.q("commentReference"))
+    ref.set(kit.q("id"), str(ident))
+
+
+def parse_add(raw: str) -> tuple[str, str]:
+    if "=" not in raw:
+        raise ValueError("--add expects NEEDLE=COMMENT, got %r" % raw)
+    needle, body = raw.split("=", 1)
+    if not needle or not body:
+        raise ValueError("--add needs a non-empty needle and comment")
+    return needle, body
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add Word comments over paragraphs matched by substring.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--author", default="dsh-office", help="Comment author")
+    parser.add_argument("--add", action="append", default=[], help="NEEDLE=COMMENT (repeatable)")
+    parser.add_argument("--ignore_case", action="store_true", help="Match needle case-insensitively")
+    parser.add_argument("--require_all", action="store_true", help="Fail without writing if any needle is absent")
+    parser.add_argument("--date", default=None, help="ISO timestamp for the comments (default: now, UTC)")
+    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 args.add:
+        parser.error("at least one --add NEEDLE=COMMENT is required")
+
+    paragraphs = doc.paragraphs()
+    requests = []
+    for raw in args.add:
+        try:
+            needle, body = parse_add(raw)
+        except ValueError as exc:
+            print("error: %s" % exc, file=sys.stderr)
+            return 2
+        target = None
+        for paragraph in paragraphs:
+            haystack = kit.paragraph_text(paragraph)
+            if (needle.lower() in haystack.lower()) if args.ignore_case else (needle in haystack):
+                target = paragraph
+                break
+        requests.append({"needle": needle, "body": body, "paragraph": target})
+
+    missing = [item["needle"] for item in requests if item["paragraph"] is None]
+    if missing and args.require_all:
+        kit.emit({"ok": False, "output": None, "matched": 0, "missing": missing})
+        return 1
+
+    stamp = args.date or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    root = comments_root(doc)
+    ident = doc.next_id()
+    placed = []
+    for item in requests:
+        if item["paragraph"] is None:
+            continue
+        append_comment(root, item["body"], args.author, stamp, ident)
+        anchor(item["paragraph"], ident)
+        placed.append({"id": ident, "needle": item["needle"], "body": item["body"]})
+        ident += 1
+
+    if not placed:
+        kit.emit({"ok": False, "output": None, "matched": 0, "missing": missing})
+        return 1
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "author": args.author, "placed": placed, "missing": missing})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())