@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/office-artifacts/references/docx/scripts/docx_comments.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""List, add, and delete comments in a .docx.
+
+Subcommands:
+  list    JSON per comment: id, author, initials, date, text, anchored_text
+  add     add a comment anchored to the first occurrence of --target
+  delete  remove a comment (and its range markers) by --id
+
+Examples:
+  docx_comments.py list report.docx
+  docx_comments.py add report.docx --target "Q3 revenue" \
+      --text "Needs a source" --author "Reviewer" -o out.docx
+  docx_comments.py delete report.docx --id 0 -o out.docx
+
+Uses the native python-docx comments API (>= 1.2) when available; falls
+back to building word/comments.xml and the range markers directly for
+older versions (or when --xml is passed). Listing and deletion always
+work at the XML level so they handle documents from any producer.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import sys
+from copy import deepcopy
+
+from docx import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from lxml import etree
+
+from docx_common import iter_part_roots
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+COMMENTS_CT = ("application/vnd.openxmlformats-officedocument"
+               ".wordprocessingml.comments+xml")
+
+
+def q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+# ---------------------------------------------------------------- reading
+
+def _comments_root(doc):
+    """Return the XML root of the comments part, or None."""
+    for rel in doc.part.rels.values():
+        if rel.reltype == RT.COMMENTS:
+            part = rel.target_part
+            el = getattr(part, "_element", None)
+            if el is not None:
+                return el
+            from docx.opc.part import XmlPart
+            part._element = etree.fromstring(part.blob)
+            part.__class__ = XmlPart
+            return part._element
+    return None
+
+
+def _anchored_texts(doc) -> dict:
+    """Map comment id -> document text between its range markers."""
+    anchored: dict[str, list[str]] = {}
+    for root in iter_part_roots(doc):
+        active: set[str] = set()
+        for el in root.iter():
+            if el.tag == q("commentRangeStart"):
+                cid = el.get(q("id"))
+                active.add(cid)
+                anchored.setdefault(cid, [])
+            elif el.tag == q("commentRangeEnd"):
+                active.discard(el.get(q("id")))
+            elif el.tag == q("t") and active:
+                for cid in active:
+                    anchored[cid].append(el.text or "")
+    return {cid: "".join(parts) for cid, parts in anchored.items()}
+
+
+def list_comments(doc) -> list:
+    root = _comments_root(doc)
+    if root is None:
+        return []
+    anchored = _anchored_texts(doc)
+    out = []
+    for c in root.iter(q("comment")):
+        cid = c.get(q("id"))
+        text = "\n".join(
+            "".join(t.text or "" for t in p.iter(q("t")))
+            for p in c.iter(q("p")))
+        out.append({"id": cid, "author": c.get(q("author")),
+                    "initials": c.get(q("initials")),
+                    "date": c.get(q("date")), "text": text,
+                    "anchored_text": anchored.get(cid, "")})
+    return out
+
+
+# ---------------------------------------------------------------- anchoring
+
+def _split_run(para, run_el, offset: int):
+    """Split a run element at text offset; return the new right-hand run."""
+    text = "".join(t.text or "" for t in run_el.iter(q("t")))
+    right = deepcopy(run_el)
+    run_el.addnext(right)
+    for el, s in ((run_el, text[:offset]), (right, text[offset:])):
+        for t in list(el.iter(q("t"))):
+            el.remove(t)
+        t = etree.SubElement(el, q("t"))
+        t.text = s
+        t.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    return right
+
+
+def find_anchor_runs(doc, target: str):
+    """Isolate `target`'s first occurrence into whole runs; return them."""
+    from docx_common import iter_all_paragraphs
+    for para in iter_all_paragraphs(doc):
+        full = para.text
+        start = full.find(target)
+        if start < 0:
+            continue
+        end = start + len(target)
+        pos = 0
+        covered = []
+        for run_el in para._p.iter(q("r")):
+            rtext = "".join(t.text or "" for t in run_el.iter(q("t")))
+            r_start, r_end = pos, pos + len(rtext)
+            pos = r_end
+            if r_end <= start or r_start >= end:
+                continue
+            if r_start < start:  # split off the left part
+                run_el = _split_run(para, run_el, start - r_start)
+                r_start = start
+            if r_end > end:      # split off the right part
+                _split_run(para, run_el, end - r_start)
+            covered.append(run_el)
+        return para, covered
+    return None, []
+
+
+# ---------------------------------------------------------------- adding
+
+def _next_id(doc) -> int:
+    root = _comments_root(doc)
+    if root is None:
+        return 0
+    ids = [int(c.get(q("id"), "0")) for c in root.iter(q("comment"))
+           if c.get(q("id"), "").isdigit()]
+    return max(ids) + 1 if ids else 0
+
+
+def add_comment_native(doc, runs, text, author, initials):
+    from docx.text.run import Run
+    run_objs = [Run(r, None) for r in runs]
+    comment = doc.add_comment(run_objs, text=text, author=author,
+                              initials=initials or "")
+    return str(comment.comment_id)
+
+
+def add_comment_xml(doc, runs, text, author, initials) -> str:
+    cid = str(_next_id(doc))
+    root = _comments_root(doc)
+    if root is None:
+        root = etree.fromstring(
+            f'<w:comments xmlns:w="{W}"/>'.encode("utf-8"))
+        from docx.opc.packuri import PackURI
+        from docx.opc.part import Part
+        blob = etree.tostring(root, xml_declaration=True,
+                              encoding="UTF-8", standalone=True)
+        part = Part(PackURI("/word/comments.xml"), COMMENTS_CT, blob,
+                    doc.part.package)
+        doc.part.relate_to(part, RT.COMMENTS)
+        # keep a live element on the part so edits reach save()
+        part._element = root
+        part.blob_ = None
+
+        def _blob(self=part):
+            return etree.tostring(self._element, xml_declaration=True,
+                                  encoding="UTF-8", standalone=True)
+        part.__class__ = type("CommentsXmlPart", (Part,),
+                              {"blob": property(lambda self: _blob(self))})
+    now = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    comment = etree.SubElement(root, q("comment"))
+    comment.set(q("id"), cid)
+    comment.set(q("author"), author)
+    if initials:
+        comment.set(q("initials"), initials)
+    comment.set(q("date"), now)
+    p = etree.SubElement(comment, q("p"))
+    r = etree.SubElement(p, q("r"))
+    t = etree.SubElement(r, q("t"))
+    t.text = text
+    # range markers around the anchor runs + reference run after them
+    first, last = runs[0], runs[-1]
+    start = first.makeelement(q("commentRangeStart"), {q("id"): cid})
+    first.addprevious(start)
+    end = last.makeelement(q("commentRangeEnd"), {q("id"): cid})
+    last.addnext(end)
+    ref_run = last.makeelement(q("r"), {})
+    ref = etree.SubElement(ref_run, q("commentReference"))
+    ref.set(q("id"), cid)
+    end.addnext(ref_run)
+    return cid
+
+
+# ---------------------------------------------------------------- deleting
+
+def delete_comment(doc, cid: str) -> bool:
+    root = _comments_root(doc)
+    found = False
+    if root is not None:
+        for c in list(root.iter(q("comment"))):
+            if c.get(q("id")) == cid:
+                c.getparent().remove(c)
+                found = True
+    for part_root in iter_part_roots(doc):
+        for tag in ("commentRangeStart", "commentRangeEnd",
+                    "commentReference"):
+            for el in list(part_root.iter(q(tag))):
+                if el.get(q("id")) == cid:
+                    parent = el.getparent()
+                    # remove the wrapping run for reference marks
+                    if tag == "commentReference" and parent.tag == q("r"):
+                        parent.getparent().remove(parent)
+                    else:
+                        parent.remove(el)
+                    found = True
+    return found
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="List, add, or delete comments in a .docx.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("list", help="list comments as JSON")
+    p.add_argument("path", help="input .docx")
+
+    p = sub.add_parser("add", help="add a comment anchored to text")
+    p.add_argument("path", help="input .docx")
+    p.add_argument("-o", "--output", help="output path (default: in place)")
+    p.add_argument("--target", required=True,
+                   help="anchor: first occurrence of this text")
+    p.add_argument("--text", required=True, help="comment body")
+    p.add_argument("--author", default="Hermes")
+    p.add_argument("--initials", default="")
+    p.add_argument("--xml", action="store_true",
+                   help="force the XML fallback (skip native API)")
+
+    p = sub.add_parser("delete", help="delete a comment by id")
+    p.add_argument("path", help="input .docx")
+    p.add_argument("-o", "--output", help="output path (default: in place)")
+    p.add_argument("--id", required=True, help="comment id")
+
+    args = ap.parse_args()
+    doc = Document(args.path)
+
+    if args.cmd == "list":
+        print(json.dumps({"ok": True, "comments": list_comments(doc)},
+                         ensure_ascii=False))
+        return 0
+
+    if args.cmd == "add":
+        para, runs = find_anchor_runs(doc, args.target)
+        if not runs:
+            print(json.dumps({"ok": False,
+                              "error": f"target not found: {args.target}"}))
+            return 1
+        native = hasattr(doc, "add_comment") and not args.xml
+        if native:
+            cid = add_comment_native(doc, runs, args.text, args.author,
+                                     args.initials)
+        else:
+            cid = add_comment_xml(doc, runs, args.text, args.author,
+                                  args.initials)
+        result = {"ok": True, "comment_id": cid,
+                  "native_api": native, "anchored_to": args.target}
+    else:  # delete
+        if not delete_comment(doc, args.id):
+            print(json.dumps({"ok": False,
+                              "error": f"no comment with id {args.id}"}))
+            return 1
+        result = {"ok": True, "deleted_id": args.id}
+
+    out = args.output or args.path
+    doc.save(out)
+    result["output"] = out
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/docx/scripts/docx_common.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+# MIT License. Shared helpers for the docx skill scripts.
+"""Shared helpers: paragraph iteration and run-preserving text replacement."""
+from __future__ import annotations
+
+
+def iter_all_paragraphs(doc, include_headers_footers: bool = True):
+    """Yield every paragraph in body, tables (recursively), headers, footers."""
+    seen = set()
+    def unique(container):
+        for para in _iter_container(container):
+            if para._p not in seen:
+                seen.add(para._p)
+                yield para
+    yield from unique(doc)
+    if include_headers_footers:
+        for section in doc.sections:
+            for part in (
+                section.header, section.footer,
+                section.first_page_header, section.first_page_footer,
+                section.even_page_header, section.even_page_footer,
+            ):
+                if part is not None:
+                    yield from unique(part)
+
+
+def _iter_container(container):
+    for para in container.paragraphs:
+        yield para
+    for table in container.tables:
+        yield from _iter_table(table)
+
+
+def _iter_table(table):
+    for row in table.rows:
+        for cell in row.cells:
+            for para in cell.paragraphs:
+                yield para
+            for nested in cell.tables:
+                yield from _iter_table(nested)
+
+
+def iter_part_roots(doc):
+    """Yield the XML root of the body plus every header/footer part."""
+    yield doc.element.body
+    seen = set()
+    for section in doc.sections:
+        for part in (
+            section.header, section.footer,
+            section.first_page_header, section.first_page_footer,
+            section.even_page_header, section.even_page_footer,
+        ):
+            if part is not None and id(part._element) not in seen:
+                seen.add(id(part._element))
+                yield part._element
+
+
+def replace_in_paragraph(para, old: str, new: str) -> int:
+    """Replace `old` with `new` in a paragraph, preserving run formatting.
+
+    Strategy: first replace occurrences fully contained in a single run
+    (formatting fully preserved). If the needle spans multiple runs, the
+    matched runs are collapsed: the replacement inherits the formatting of
+    the run where the match starts. Returns number of replacements made.
+    """
+    if not old or old not in para.text:
+        return 0
+    runs = list(para.runs)
+    full = "".join(r.text for r in runs)
+    matches, cursor = [], 0
+    while (start := full.find(old, cursor)) >= 0:
+        matches.append(start)
+        cursor = start + len(old)
+    # Work backwards against original offsets; inserted text is never scanned.
+    for start in reversed(matches):
+        end = start + len(old)
+        pos = 0
+        spans = []  # (run_idx, cut_start, cut_end) portions inside the match
+        for i, r in enumerate(runs):
+            r_start, r_end = pos, pos + len(r.text)
+            if r_end > start and r_start < end:
+                spans.append((i, max(start, r_start) - r_start,
+                              min(end, r_end) - r_start))
+            pos = r_end
+        first = True
+        for i, cs, ce in spans:
+            t = runs[i].text
+            if first:
+                runs[i].text = t[:cs] + new + t[ce:]
+                first = False
+            else:
+                runs[i].text = t[:cs] + t[ce:]
+    return len(matches)

package/built-in-skills/office-artifacts/references/docx/scripts/docx_create.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Create a .docx document from a JSON spec.
+
+Usage: docx_create.py spec.json output.docx
+Run with --help for the spec format summary.
+
+Spec (JSON object):
+{
+  "page": {"width_mm": 210, "height_mm": 297,
+           "margins_mm": {"top": 25, "bottom": 25, "left": 20, "right": 20}},
+  "header": "text shown in page header",
+  "footer": "text shown in page footer",
+  "styles": [{"name": "MyStyle", "base": "Normal", "font": "Arial",
+              "size_pt": 12, "bold": true, "color": "1F4E79"}],
+  "blocks": [
+    {"type": "heading", "text": "Title", "level": 1},
+    {"type": "paragraph", "style": "MyStyle", "runs": [
+        {"text": "plain "}, {"text": "bold", "bold": true},
+        {"text": " italic", "italic": true},
+        {"text": " under", "underline": true}]},
+    {"type": "paragraph", "text": "shortcut: single plain run"},
+    {"type": "bullet_list", "items": ["a", "b"]},
+    {"type": "numbered_list", "items": ["one", "two"]},
+    {"type": "table", "header": ["Col1", "Col2"],
+     "rows": [["1", "2"]], "style": "Light Grid Accent 1",
+     "header_bold": true},
+    {"type": "image", "path": "pic.png", "width_mm": 60},
+    {"type": "page_break"},
+    {"type": "toc"}
+  ]
+}
+
+Extras: `"footer_page_numbers": true` at the top level adds a
+"Page X of Y" footer built from PAGE/NUMPAGES fields, and a `toc` block
+inserts a Table of Contents field. Field results are computed by
+Word/LibreOffice when the file is opened, not by python-docx.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from docx import Document
+from docx.enum.style import WD_STYLE_TYPE
+from docx.enum.text import WD_BREAK
+from docx.shared import Mm, Pt, RGBColor
+
+
+def apply_page(doc, page: dict) -> None:
+    section = doc.sections[0]
+    if "width_mm" in page:
+        section.page_width = Mm(page["width_mm"])
+    if "height_mm" in page:
+        section.page_height = Mm(page["height_mm"])
+    m = page.get("margins_mm", {})
+    for side in ("top", "bottom", "left", "right"):
+        if side in m:
+            setattr(section, f"{side}_margin", Mm(m[side]))
+
+
+def add_styles(doc, styles: list) -> None:
+    for s in styles:
+        style = doc.styles.add_style(s["name"], WD_STYLE_TYPE.PARAGRAPH)
+        if s.get("base"):
+            style.base_style = doc.styles[s["base"]]
+        font = style.font
+        if s.get("font"):
+            font.name = s["font"]
+        if s.get("size_pt"):
+            font.size = Pt(s["size_pt"])
+        if s.get("bold") is not None:
+            font.bold = s["bold"]
+        if s.get("italic") is not None:
+            font.italic = s["italic"]
+        if s.get("color"):
+            font.color.rgb = RGBColor.from_string(s["color"])
+
+
+def add_runs(para, block: dict) -> None:
+    runs = block.get("runs")
+    if runs is None:
+        runs = [{"text": block.get("text", "")}]
+    for r in runs:
+        run = para.add_run(r.get("text", ""))
+        if r.get("bold"):
+            run.bold = True
+        if r.get("italic"):
+            run.italic = True
+        if r.get("underline"):
+            run.underline = True
+
+
+def add_block(doc, block: dict) -> None:
+    btype = block["type"]
+    if btype == "heading":
+        doc.add_heading(block.get("text", ""), level=block.get("level", 1))
+    elif btype == "paragraph":
+        para = doc.add_paragraph(style=block.get("style"))
+        add_runs(para, block)
+    elif btype == "bullet_list":
+        for item in block.get("items", []):
+            doc.add_paragraph(item, style="List Bullet")
+    elif btype == "numbered_list":
+        for item in block.get("items", []):
+            doc.add_paragraph(item, style="List Number")
+    elif btype == "table":
+        header = block.get("header", [])
+        rows = block.get("rows", [])
+        ncols = len(header) if header else (len(rows[0]) if rows else 1)
+        table = doc.add_table(rows=0, cols=ncols)
+        table.style = block.get("style", "Table Grid")
+        if header:
+            cells = table.add_row().cells
+            for i, text in enumerate(header):
+                cells[i].text = str(text)
+                if block.get("header_bold", True):
+                    for para in cells[i].paragraphs:
+                        for run in para.runs:
+                            run.bold = True
+        for row in rows:
+            cells = table.add_row().cells
+            for i, text in enumerate(row):
+                cells[i].text = str(text)
+    elif btype == "image":
+        width = Mm(block["width_mm"]) if block.get("width_mm") else None
+        doc.add_picture(block["path"], width=width)
+    elif btype == "page_break":
+        doc.add_paragraph().add_run().add_break(WD_BREAK.PAGE)
+    elif btype == "toc":
+        from docx_edit import _add_field
+        para = doc.add_paragraph()
+        _add_field(para, r' TOC \o "1-3" \h \z \u ',
+                   "Table of contents - open in Word/LibreOffice and "
+                   "update fields to populate.")
+    else:
+        raise ValueError(f"unknown block type: {btype}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Create a .docx from a JSON spec.",
+        epilog="See the module docstring (top of this file) for the spec format.")
+    ap.add_argument("spec", help="path to JSON spec file")
+    ap.add_argument("output", help="path of .docx to write")
+    args = ap.parse_args()
+
+    with open(args.spec, encoding="utf-8") as f:
+        spec = json.load(f)
+
+    doc = Document()
+    if spec.get("page"):
+        apply_page(doc, spec["page"])
+    if spec.get("styles"):
+        add_styles(doc, spec["styles"])
+    if spec.get("header"):
+        doc.sections[0].header.paragraphs[0].text = spec["header"]
+    if spec.get("footer"):
+        doc.sections[0].footer.paragraphs[0].text = spec["footer"]
+    for block in spec.get("blocks", []):
+        add_block(doc, block)
+    if spec.get("footer_page_numbers"):
+        from docx_edit import _add_field
+        para = doc.sections[0].footer.paragraphs[0]
+        para.add_run("Page ")
+        _add_field(para, " PAGE ", "1")
+        para.add_run(" of ")
+        _add_field(para, " NUMPAGES ", "1")
+    doc.save(args.output)
+    print(json.dumps({"ok": True, "output": args.output,
+                      "blocks": len(spec.get("blocks", []))}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())