@prismer/runtime 2.2.55 → 2.2.64

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

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Edit an existing .docx in place (or to a new file).
+
+Subcommands:
+  replace   find-and-replace text, preserving run formatting
+  set-cell  set the text of a table cell
+  insert    insert a paragraph before a given body paragraph index
+  delete    delete a body paragraph by index
+  style     apply a paragraph style to a body paragraph by index
+  normalize merge adjacent runs with identical formatting
+  toc       insert a Table of Contents field at a body paragraph index
+  page-numbers  add "Page X of Y" (PAGE/NUMPAGES fields) to the footer
+
+Examples:
+  docx_edit.py replace in.docx --find old --replace new -o out.docx
+  docx_edit.py set-cell in.docx --table 0 --row 1 --col 2 --text "42"
+  docx_edit.py insert in.docx --index 3 --text "New para" --style Normal
+  docx_edit.py delete in.docx --index 3
+  docx_edit.py style in.docx --index 0 --style "Heading 1"
+  docx_edit.py normalize in.docx -o out.docx
+  docx_edit.py toc in.docx --index 1 -o out.docx
+  docx_edit.py page-numbers in.docx -o out.docx
+
+Field results (TOC entries, page numbers) are computed by Word or
+LibreOffice when the document is opened, not by python-docx; until then
+the fields show placeholder text.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from docx import Document
+
+from docx_common import iter_all_paragraphs, replace_in_paragraph
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def _q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+def cmd_replace(doc, args) -> dict:
+    n = 0
+    for para in iter_all_paragraphs(doc):
+        n += replace_in_paragraph(para, args.find, args.replace)
+    return {"replacements": n}
+
+
+def cmd_set_cell(doc, args) -> dict:
+    cell = doc.tables[args.table].cell(args.row, args.col)
+    cell.text = args.text
+    return {"table": args.table, "row": args.row, "col": args.col}
+
+
+def cmd_insert(doc, args) -> dict:
+    paras = doc.paragraphs
+    if args.index < len(paras):
+        anchor = paras[args.index]
+        new_para = anchor.insert_paragraph_before(args.text, style=args.style)
+    else:
+        new_para = doc.add_paragraph(args.text, style=args.style)
+    return {"inserted_at": args.index, "text": new_para.text}
+
+
+def cmd_delete(doc, args) -> dict:
+    para = doc.paragraphs[args.index]
+    el = para._element
+    el.getparent().remove(el)
+    return {"deleted_index": args.index}
+
+
+def cmd_style(doc, args) -> dict:
+    doc.paragraphs[args.index].style = doc.styles[args.style]
+    return {"index": args.index, "style": args.style}
+
+
+def _run_format_key(r_el) -> str:
+    """Canonical string for a run's w:rPr (None when absent)."""
+    from lxml import etree
+    rpr = r_el.find(_q("rPr"))
+    return "" if rpr is None else etree.tostring(rpr).decode("utf-8")
+
+
+def cmd_normalize(doc) -> dict:
+    """Merge adjacent sibling runs with identical formatting."""
+    merged = 0
+    for para in iter_all_paragraphs(doc):
+        prev = None
+        for r_el in list(para._p):
+            if r_el.tag != _q("r"):
+                prev = None
+                continue
+            # only merge plain-text runs (no breaks, tabs, drawings...)
+            kids = {c.tag for c in r_el} - {_q("rPr"), _q("t")}
+            if kids:
+                prev = None
+                continue
+            if (prev is not None
+                    and _run_format_key(prev) == _run_format_key(r_el)):
+                pt = prev.find(_q("t"))
+                ct = r_el.find(_q("t"))
+                if pt is None:
+                    pt = prev.makeelement(_q("t"), {})
+                    prev.append(pt)
+                pt.text = (pt.text or "") + ((ct.text or "")
+                                             if ct is not None else "")
+                pt.set("{http://www.w3.org/XML/1998/namespace}space",
+                       "preserve")
+                r_el.getparent().remove(r_el)
+                merged += 1
+            else:
+                prev = r_el
+    return {"runs_merged": merged}
+
+
+def _add_field(para, instr: str, placeholder: str) -> None:
+    """Append a complex field (begin/instrText/separate/result/end)."""
+    p = para._p
+    for ftype, extra in (("begin", None), (None, instr),
+                         ("separate", None), (None, placeholder),
+                         ("end", None)):
+        r = p.makeelement(_q("r"), {})
+        p.append(r)
+        if ftype is not None:
+            fld = r.makeelement(_q("fldChar"), {_q("fldCharType"): ftype})
+            r.append(fld)
+        elif extra is instr:
+            it = r.makeelement(_q("instrText"), {})
+            it.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+            it.text = instr
+            r.append(it)
+        else:
+            t = r.makeelement(_q("t"), {})
+            t.text = extra
+            r.append(t)
+
+
+def cmd_toc(doc, args) -> dict:
+    paras = doc.paragraphs
+    if args.index < len(paras):
+        para = paras[args.index].insert_paragraph_before("")
+    else:
+        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.")
+    return {"toc_inserted_at": args.index}
+
+
+def cmd_page_numbers(doc, args) -> dict:
+    footer = doc.sections[0].footer
+    para = footer.paragraphs[0] if footer.paragraphs \
+        else footer.add_paragraph()
+    para.add_run("Page ")
+    _add_field(para, " PAGE ", "1")
+    para.add_run(" of ")
+    _add_field(para, " NUMPAGES ", "1")
+    return {"footer_fields": ["PAGE", "NUMPAGES"]}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Edit a .docx file.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def common(p):
+        p.add_argument("path", help="input .docx")
+        p.add_argument("-o", "--output",
+                       help="output path (default: overwrite input)")
+
+    p = sub.add_parser("replace", help="find-and-replace text")
+    common(p)
+    p.add_argument("--find", required=True)
+    p.add_argument("--replace", required=True)
+    p.add_argument("--body-only", action="store_true",
+                   help="skip headers/footers")
+
+    p = sub.add_parser("set-cell", help="set table cell text")
+    common(p)
+    p.add_argument("--table", type=int, required=True, help="table index")
+    p.add_argument("--row", type=int, required=True)
+    p.add_argument("--col", type=int, required=True)
+    p.add_argument("--text", required=True)
+
+    p = sub.add_parser("insert", help="insert paragraph at body index")
+    common(p)
+    p.add_argument("--index", type=int, required=True)
+    p.add_argument("--text", required=True)
+    p.add_argument("--style", default=None)
+
+    p = sub.add_parser("delete", help="delete body paragraph by index")
+    common(p)
+    p.add_argument("--index", type=int, required=True)
+
+    p = sub.add_parser("style", help="apply style to body paragraph")
+    common(p)
+    p.add_argument("--index", type=int, required=True)
+    p.add_argument("--style", required=True)
+
+    p = sub.add_parser("normalize",
+                       help="merge adjacent runs with identical formatting")
+    common(p)
+
+    p = sub.add_parser("toc", help="insert a TOC field (Word computes it)")
+    common(p)
+    p.add_argument("--index", type=int, default=0,
+                   help="body paragraph index to insert before (default 0)")
+
+    p = sub.add_parser("page-numbers",
+                       help="add PAGE/NUMPAGES fields to the footer")
+    common(p)
+
+    args = ap.parse_args()
+    doc = Document(args.path)
+
+    if args.cmd == "replace":
+        if args.body_only:
+            n = 0
+            for para in iter_all_paragraphs(doc, include_headers_footers=False):
+                n += replace_in_paragraph(para, args.find, args.replace)
+            result = {"replacements": n}
+        else:
+            result = cmd_replace(doc, args)
+    elif args.cmd == "set-cell":
+        result = cmd_set_cell(doc, args)
+    elif args.cmd == "insert":
+        result = cmd_insert(doc, args)
+    elif args.cmd == "delete":
+        result = cmd_delete(doc, args)
+    elif args.cmd == "normalize":
+        result = cmd_normalize(doc)
+    elif args.cmd == "toc":
+        result = cmd_toc(doc, args)
+    elif args.cmd == "page-numbers":
+        result = cmd_page_numbers(doc, args)
+    else:
+        result = cmd_style(doc, args)
+
+    out = args.output or args.path
+    doc.save(out)
+    result.update({"ok": True, "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_read.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Read a .docx: text, structure outline, styles, images, revision detection.
+
+Usage:
+  docx_read.py file.docx --text        # full text incl. tables + headers/footers
+  docx_read.py file.docx --structure   # JSON outline (headings, tables, counts)
+  docx_read.py file.docx --styles      # JSON list of styles actually used
+  docx_read.py file.docx --images DIR  # extract embedded images into DIR
+  docx_read.py file.docx --revisions   # JSON: tracked changes / comments present?
+
+Text output is JSON: {"body": [...], "tables": [[...rows]], "headers": [...],
+"footers": [...]}. The XML text walker includes insertions and excludes
+deletions/moveFrom without modifying or accepting revisions in the input.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import zipfile
+
+from docx import Document
+from lxml import etree
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def accepted_text(element):
+    """Read visible run text, including insertions, without mutating revisions."""
+    if element.tag in (f"{{{W}}}del", f"{{{W}}}moveFrom"):
+        return ""
+    if element.tag == f"{{{W}}}t":
+        return element.text or ""
+    if element.tag == f"{{{W}}}tab":
+        return "\t"
+    if element.tag in (f"{{{W}}}br", f"{{{W}}}cr"):
+        return "\n"
+    return "".join(accepted_text(child) for child in element)
+
+
+def table_to_rows(table) -> list:
+    return [["\n".join(accepted_text(p._p) for p in cell.paragraphs)
+             for cell in row.cells] for row in table.rows]
+
+
+def extract_text(doc) -> dict:
+    out = {"body": [accepted_text(p._p) for p in doc.paragraphs],
+           "tables": [table_to_rows(t) for t in doc.tables],
+           "headers": [], "footers": []}
+    for section in doc.sections:
+        out["headers"].extend(accepted_text(p._p) for p in section.header.paragraphs)
+        out["footers"].extend(accepted_text(p._p) for p in section.footer.paragraphs)
+        for t in section.header.tables:
+            out["headers"].append(json.dumps(table_to_rows(t), ensure_ascii=False))
+        for t in section.footer.tables:
+            out["footers"].append(json.dumps(table_to_rows(t), ensure_ascii=False))
+    return out
+
+
+def extract_structure(doc) -> dict:
+    outline = []
+    for i, para in enumerate(doc.paragraphs):
+        style = para.style.name if para.style else ""
+        if style.startswith("Heading"):
+            try:
+                level = int(style.split()[-1])
+            except ValueError:
+                level = 1
+            outline.append({"index": i, "level": level, "text": accepted_text(para._p)})
+    return {
+        "outline": outline,
+        "paragraph_count": len(doc.paragraphs),
+        "table_count": len(doc.tables),
+        "tables": [{"rows": len(t.rows), "cols": len(t.columns)}
+                   for t in doc.tables],
+        "section_count": len(doc.sections),
+    }
+
+
+def styles_used(doc) -> list:
+    used = set()
+    for para in doc.paragraphs:
+        if para.style:
+            used.add(para.style.name)
+        for run in para.runs:
+            if run.style:
+                used.add(run.style.name)
+    for table in doc.tables:
+        if table.style:
+            used.add(table.style.name)
+        for row in table.rows:
+            for cell in row.cells:
+                for para in cell.paragraphs:
+                    if para.style:
+                        used.add(para.style.name)
+    return sorted(used)
+
+
+def extract_images(path: str, outdir: str) -> list:
+    os.makedirs(outdir, exist_ok=True)
+    written = []
+    with zipfile.ZipFile(path) as zf:
+        for name in zf.namelist():
+            if name.startswith("word/media/"):
+                target = os.path.join(outdir, os.path.basename(name))
+                with open(target, "wb") as f:
+                    f.write(zf.read(name))
+                written.append(target)
+    return written
+
+
+def detect_revisions(path: str) -> dict:
+    """Detect tracked changes and comments by scanning the raw XML parts."""
+    markers = {"insertions": {"ins", "moveTo", "moveToRangeStart"},
+               "deletions": {"del", "moveFrom", "moveFromRangeStart"},
+               "format_changes": {"rPrChange", "pPrChange", "tblPrChange", "trPrChange",
+                                  "tcPrChange", "sectPrChange", "tblGridChange", "numberingChange"}}
+    result = {k: False for k in markers}
+    result["comments"] = False
+    with zipfile.ZipFile(path) as zf:
+        names = zf.namelist()
+        result["comments"] = any(n.startswith("word/comments") for n in names)
+        for name in names:
+            if name.startswith("word/") and name.endswith(".xml"):
+                root = etree.fromstring(zf.read(name))
+                tags = {el.tag for el in root.iter()}
+                for key, marker in markers.items():
+                    if tags & {f"{{{W}}}{tag}" for tag in marker}:
+                        result[key] = True
+    result["has_tracked_changes"] = any(
+        result[k] for k in ("insertions", "deletions", "format_changes"))
+    return result
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Read/inspect a .docx file.")
+    ap.add_argument("path", help=".docx file to read")
+    g = ap.add_mutually_exclusive_group(required=True)
+    g.add_argument("--text", action="store_true", help="extract all text as JSON")
+    g.add_argument("--structure", action="store_true", help="outline JSON")
+    g.add_argument("--styles", action="store_true", help="styles used, JSON")
+    g.add_argument("--images", metavar="DIR", help="extract images to DIR")
+    g.add_argument("--revisions", action="store_true",
+                   help="detect tracked changes / comments")
+    args = ap.parse_args()
+
+    if args.images:
+        print(json.dumps({"images": extract_images(args.path, args.images)},
+                         ensure_ascii=False))
+        return 0
+    if args.revisions:
+        print(json.dumps(detect_revisions(args.path), ensure_ascii=False))
+        return 0
+
+    doc = Document(args.path)
+    if args.text:
+        out = extract_text(doc)
+    elif args.structure:
+        out = extract_structure(doc)
+    else:
+        out = {"styles": styles_used(doc)}
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Inspect and resolve tracked changes (w:ins / w:del) in a .docx.
+
+Subcommands:
+  list        JSON list of revisions: id, author, date, type, text
+  accept-all  accept every insertion and deletion
+  reject-all  reject every insertion and deletion
+  accept      accept one revision by --id
+  reject      reject one revision by --id
+
+Examples:
+  docx_revisions.py list report.docx
+  docx_revisions.py accept-all report.docx -o accepted.docx
+  docx_revisions.py reject report.docx --id 3 -o out.docx
+
+Semantics (direct XML manipulation, python-docx oxml layer):
+  accept w:ins -> unwrap (keep inserted runs)   reject w:ins -> remove
+  accept w:del -> remove                        reject w:del -> restore
+  (restore = w:delText tags renamed to w:t, wrapper unwrapped)
+
+Covers run-level insertions/deletions anywhere in body, tables (nested
+included), headers and footers. Row/paragraph-mark revisions and format
+changes (w:rPrChange etc.) are reported by docx_read.py --revisions but
+not resolved here.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from docx import Document
+
+from docx_common import iter_part_roots
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+
+
+def q(tag: str) -> str:
+    return f"{{{W}}}{tag}"
+
+
+INS, DEL = q("ins"), q("del")
+
+
+def _iter_revision_elements(doc):
+    """Yield every w:ins / w:del element across body, headers, footers."""
+    for root in iter_part_roots(doc):
+        for el in root.iter(INS, DEL):
+            # Property/row/paragraph-mark revisions are not run wrappers.
+            if el.getparent().tag in {q('p'), INS, DEL, q('hyperlink'), q('sdtContent')}:
+                yield el
+
+
+def _rev_text(el) -> str:
+    tag = q("delText") if el.tag == DEL else q("t")
+    return "".join(t.text or "" for t in el.iter(tag))
+
+
+def _rev_record(el) -> dict:
+    return {
+        "id": el.get(q("id")),
+        "author": el.get(q("author")),
+        "date": el.get(q("date")),
+        "type": "insertion" if el.tag == INS else "deletion",
+        "text": _rev_text(el),
+    }
+
+
+def _unwrap(el) -> None:
+    """Replace `el` with its children, keeping document order."""
+    parent = el.getparent()
+    idx = list(parent).index(el)
+    for child in list(el):
+        parent.insert(idx, child)
+        idx += 1
+    parent.remove(el)
+
+
+def _apply(el, accept: bool) -> None:
+    if el.getparent() is None:  # already detached via an outer wrapper
+        return
+    if el.tag == INS:
+        if accept:
+            _unwrap(el)
+        else:
+            el.getparent().remove(el)
+    else:  # w:del
+        if accept:
+            el.getparent().remove(el)
+        else:
+            for dt in list(el.iter(q("delText"))):
+                dt.tag = q("t")
+            _unwrap(el)
+
+
+def resolve(doc, accept: bool, rev_id: str | None = None) -> int:
+    targets = [el for el in _iter_revision_elements(doc)
+               if rev_id is None or el.get(q("id")) == rev_id]
+    for el in targets:
+        _apply(el, accept)
+    return len(targets)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="List, accept, or reject tracked changes in a .docx.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    def common(p, out=True):
+        p.add_argument("path", help="input .docx")
+        if out:
+            p.add_argument("-o", "--output",
+                           help="output path (default: overwrite input)")
+
+    common(sub.add_parser("list", help="list revisions as JSON"), out=False)
+    common(sub.add_parser("accept-all", help="accept every revision"))
+    common(sub.add_parser("reject-all", help="reject every revision"))
+    for name in ("accept", "reject"):
+        p = sub.add_parser(name, help=f"{name} one revision by id")
+        common(p)
+        p.add_argument("--id", required=True, help="revision id (w:id)")
+
+    args = ap.parse_args()
+    doc = Document(args.path)
+
+    if args.cmd == "list":
+        revs = [_rev_record(el) for el in _iter_revision_elements(doc)]
+        print(json.dumps({"ok": True, "revisions": revs}, ensure_ascii=False))
+        return 0
+
+    accept = args.cmd in ("accept-all", "accept")
+    rev_id = getattr(args, "id", None)
+    n = resolve(doc, accept, rev_id)
+    if rev_id is not None and n == 0:
+        print(json.dumps({"ok": False,
+                          "error": f"no revision with id {rev_id}"}))
+        return 1
+    out = args.output or args.path
+    doc.save(out)
+    print(json.dumps({"ok": True, "output": out, "resolved": n,
+                      "action": "accept" if accept else "reject"},
+                     ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Fill {{placeholder}} tokens in a .docx from a JSON mapping.
+
+Tokens are replaced everywhere: body paragraphs, tables (including nested
+tables), headers and footers. Run formatting is preserved; tokens split
+across runs are handled.
+
+Usage:
+  docx_template.py template.docx values.json output.docx
+  docx_template.py template.docx values.json output.docx --strict
+
+values.json: {"name": "Ada", "date": "2026-01-01"}  fills {{name}}, {{date}}.
+With --strict, exits 1 if any {{token}} remains unfilled after processing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+from docx import Document
+
+from docx_common import iter_all_paragraphs, replace_in_paragraph
+
+TOKEN_RE = re.compile(r"\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Fill {{token}} placeholders in a .docx from JSON.")
+    ap.add_argument("template", help="input .docx with {{tokens}}")
+    ap.add_argument("values", help="JSON file of token -> value")
+    ap.add_argument("output", help="output .docx path")
+    ap.add_argument("--strict", action="store_true",
+                    help="fail if any token remains unfilled")
+    args = ap.parse_args()
+
+    with open(args.values, encoding="utf-8") as f:
+        values = json.load(f)
+
+    doc = Document(args.template)
+    filled = {}
+    for para in iter_all_paragraphs(doc):
+        # Normalize whitespace variants like {{ name }} first.
+        for m in set(TOKEN_RE.findall(para.text)):
+            if m in values:
+                # Replace any spacing variant with canonical token, then fill.
+                for variant in set(
+                        t.group(0) for t in TOKEN_RE.finditer(para.text)
+                        if t.group(1) == m):
+                    n = replace_in_paragraph(para, variant, str(values[m]))
+                    filled[m] = filled.get(m, 0) + n
+
+    remaining = sorted({m for para in iter_all_paragraphs(doc)
+                        for m in TOKEN_RE.findall(para.text)})
+    result = {"ok": True, "output": args.output, "filled": filled,
+              "unfilled_tokens": remaining}
+    if args.strict and remaining:
+        result["ok"] = False
+        print(json.dumps(result, ensure_ascii=False))
+        return 1
+    doc.save(args.output)
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())