winter-super-cli 2026.5.15

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/scripts/insert_note.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Insert a true footnote or endnote into a DOCX by patching OOXML.
+
+Why
+---
+python-docx does not currently offer a stable high-level API for true footnotes
+and endnotes. In OOXML, notes live in separate parts (footnotes.xml/endnotes.xml)
+with references embedded in the main body.
+
+This helper performs a minimal, high-ROI insertion:
+- ensures word/footnotes.xml or word/endnotes.xml exists (with separators)
+- inserts w:footnoteReference / w:endnoteReference at a marker in document.xml
+- adds a new note entry in the part
+- ensures document relationships and [Content_Types].xml overrides exist
+
+Usage
+-----
+# Insert a footnote at marker [[FN]] in the doc
+python scripts/insert_note.py in.docx --kind footnote --text "hello" --marker "[[FN]]" --out out.docx
+
+# Insert an endnote
+python scripts/insert_note.py in.docx --kind endnote --text "source" --marker "[[EN]]" --out out.docx
+
+Always render and inspect PNGs after insertion.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import zipfile
+
+from lxml import etree
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PKGREL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+CT_NS = "http://schemas.openxmlformats.org/package/2006/content-types"
+
+NS = {"w": W_NS, "r": R_NS, "rel": PKGREL_NS, "ct": CT_NS}
+
+REL_TYPE_FOOTNOTES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes"
+REL_TYPE_ENDNOTES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes"
+
+CT_FOOTNOTES = "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml"
+CT_ENDNOTES = "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml"
+
+
+def _xml_bytes(root: etree._Element) -> bytes:
+    return etree.tostring(root, xml_declaration=True, encoding="UTF-8", standalone="yes")
+
+
+def _read_xml(z: zipfile.ZipFile, name: str) -> etree._Element:
+    return etree.fromstring(z.read(name))
+
+
+def _next_rid(rels_root: etree._Element) -> str:
+    max_n = 0
+    for rel in rels_root.findall(f"{{{PKGREL_NS}}}Relationship"):
+        rid = rel.get("Id") or ""
+        m = re.match(r"rId(\d+)$", rid)
+        if m:
+            max_n = max(max_n, int(m.group(1)))
+    return f"rId{max_n + 1}"
+
+
+def _ensure_note_relationship(rels_root: etree._Element, kind: str) -> bool:
+    target = "footnotes.xml" if kind == "footnote" else "endnotes.xml"
+    rel_type = REL_TYPE_FOOTNOTES if kind == "footnote" else REL_TYPE_ENDNOTES
+
+    for rel in rels_root.findall(f"{{{PKGREL_NS}}}Relationship"):
+        if rel.get("Type") == rel_type:
+            return False
+
+    rel = etree.SubElement(rels_root, f"{{{PKGREL_NS}}}Relationship")
+    rel.set("Id", _next_rid(rels_root))
+    rel.set("Type", rel_type)
+    rel.set("Target", target)
+    return True
+
+
+def _ensure_override(ct_root: etree._Element, part_name: str, content_type: str) -> bool:
+    if not part_name.startswith("/"):
+        part_name = "/" + part_name
+
+    for ov in ct_root.findall(f"{{{CT_NS}}}Override"):
+        if ov.get("PartName") == part_name:
+            if ov.get("ContentType") != content_type:
+                ov.set("ContentType", content_type)
+                return True
+            return False
+
+    ov = etree.SubElement(ct_root, f"{{{CT_NS}}}Override")
+    ov.set("PartName", part_name)
+    ov.set("ContentType", content_type)
+    return True
+
+
+def _make_empty_notes_part(kind: str) -> etree._Element:
+    root = etree.Element(f"{{{W_NS}}}{kind}s", nsmap={"w": W_NS, "r": R_NS})
+
+    # separators (-1 and 0) are expected by Word/LO
+    def _sep(note_id: str, sep_type: str) -> None:
+        note = etree.SubElement(root, f"{{{W_NS}}}{kind}")
+        note.set(f"{{{W_NS}}}id", note_id)
+        p = etree.SubElement(note, f"{{{W_NS}}}p")
+        r = etree.SubElement(p, f"{{{W_NS}}}r")
+        sep = etree.SubElement(r, f"{{{W_NS}}}{sep_type}")
+        _ = sep
+
+    _sep("-1", "separator")
+    _sep("0", "continuationSeparator")
+    return root
+
+
+def _next_note_id(notes_root: etree._Element, kind: str) -> int:
+    ids = []
+    for n in notes_root.findall(f"{{{W_NS}}}{kind}"):
+        v = n.get(f"{{{W_NS}}}id")
+        try:
+            iv = int(v) if v is not None else None
+        except ValueError:
+            iv = None
+        if iv is not None and iv >= 1:
+            ids.append(iv)
+    return (max(ids) + 1) if ids else 1
+
+
+def _append_note(notes_root: etree._Element, kind: str, note_id: int, text: str) -> None:
+    note = etree.SubElement(notes_root, f"{{{W_NS}}}{kind}")
+    note.set(f"{{{W_NS}}}id", str(note_id))
+
+    p = etree.SubElement(note, f"{{{W_NS}}}p")
+    r1 = etree.SubElement(p, f"{{{W_NS}}}r")
+    tag = "endnoteRef" if kind == "endnote" else "footnoteRef"
+    etree.SubElement(r1, f"{{{W_NS}}}{tag}")
+    # Word often inserts a space after the reference
+    r2 = etree.SubElement(p, f"{{{W_NS}}}r")
+    t = etree.SubElement(r2, f"{{{W_NS}}}t")
+    t.text = " " + text
+
+
+def _insert_reference(doc_root: etree._Element, kind: str, marker: str, note_id: int) -> bool:
+    ref_tag = "footnoteReference" if kind == "footnote" else "endnoteReference"
+
+    for t in doc_root.xpath(".//w:t", namespaces=NS):
+        if t.text and marker in t.text:
+            # Remove marker text from this run
+            t.text = t.text.replace(marker, "")
+            # Insert reference run immediately after this run's parent <w:r>
+            r = t.getparent()
+            while r is not None and r.tag != f"{{{W_NS}}}r":
+                r = r.getparent()
+            if r is None:
+                continue
+            parent = r.getparent()
+            idx = parent.index(r)
+            new_r = etree.Element(f"{{{W_NS}}}r")
+            ref = etree.SubElement(new_r, f"{{{W_NS}}}{ref_tag}")
+            ref.set(f"{{{W_NS}}}id", str(note_id))
+            parent.insert(idx + 1, new_r)
+            return True
+
+    return False
+
+
+def insert_note(in_docx: str, out_docx: str, kind: str, marker: str, text: str) -> None:
+    if kind not in ("footnote", "endnote"):
+        raise ValueError("kind must be footnote or endnote")
+
+    part_name = "word/footnotes.xml" if kind == "footnote" else "word/endnotes.xml"
+    ct = CT_FOOTNOTES if kind == "footnote" else CT_ENDNOTES
+
+    with zipfile.ZipFile(in_docx, "r") as zin:
+        doc_root = _read_xml(zin, "word/document.xml")
+
+        # notes part
+        if part_name in zin.namelist():
+            notes_root = _read_xml(zin, part_name)
+        else:
+            notes_root = _make_empty_notes_part(kind)
+
+        new_id = _next_note_id(notes_root, kind)
+        _append_note(notes_root, kind, new_id, text)
+
+        inserted = _insert_reference(doc_root, kind, marker, new_id)
+        if not inserted:
+            # Append at end of document body if marker missing
+            body = doc_root.find("w:body", namespaces=NS)
+            if body is None:
+                raise RuntimeError("No w:body in document.xml")
+            p = etree.SubElement(body, f"{{{W_NS}}}p")
+            r = etree.SubElement(p, f"{{{W_NS}}}r")
+            ref = etree.SubElement(
+                r,
+                f"{{{W_NS}}}{'footnoteReference' if kind == 'footnote' else 'endnoteReference'}",
+            )
+            ref.set(f"{{{W_NS}}}id", str(new_id))
+
+        # relationships
+        rels_root = _read_xml(zin, "word/_rels/document.xml.rels")
+        rels_changed = _ensure_note_relationship(rels_root, kind)
+
+        # content types
+        ct_root = _read_xml(zin, "[Content_Types].xml")
+        ct_changed = _ensure_override(ct_root, part_name, ct)
+
+        overrides: dict[str, bytes] = {
+            "word/document.xml": _xml_bytes(doc_root),
+            part_name: _xml_bytes(notes_root),
+        }
+        if rels_changed:
+            overrides["word/_rels/document.xml.rels"] = _xml_bytes(rels_root)
+        if ct_changed:
+            overrides["[Content_Types].xml"] = _xml_bytes(ct_root)
+
+        with zipfile.ZipFile(out_docx, "w", zipfile.ZIP_DEFLATED) as zout:
+            for info in zin.infolist():
+                name = info.filename
+                if name in overrides:
+                    zout.writestr(name, overrides[name])
+                else:
+                    zout.writestr(name, zin.read(name))
+            # Add new parts not present in original
+            for name, data in overrides.items():
+                if name not in {i.filename for i in zin.infolist()}:
+                    zout.writestr(name, data)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("in_docx")
+    ap.add_argument("--kind", choices=["footnote", "endnote"], required=True)
+    ap.add_argument("--text", required=True)
+    ap.add_argument("--marker", default="[[NOTE]]")
+    ap.add_argument("--out", required=True)
+    args = ap.parse_args()
+
+    insert_note(args.in_docx, args.out, args.kind, args.marker, args.text)
+    print(f"[OK] inserted {args.kind} and wrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/scripts/insert_ref_fields.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Insert Word cross-references (REF fields) by replacing lightweight markers.
+
+Why this exists
+--------------
+Word cross-references are implemented as `REF` fields that point at a bookmark.
+`python-docx` does not expose a first-class API for these fields.
+
+This helper lets you author docs with simple markers like:
+
+  "See [[REF:tbl1]] for details."
+
+…and then replace those markers with real `REF` fields in OOXML.
+
+Design goals
+------------
+- Minimal, deterministic, container-friendly.
+- Works on document.xml + headers/footers.
+- Keeps implementation small and easy to reuse/import.
+
+Limitations
+-----------
+- The marker must be fully contained in a single `<w:t>` node.
+  (If Word splits it across runs, retype the marker as a single contiguous token.)
+- This does *not* create bookmarks. Pair with `captions_and_crossrefs.py --bookmarks`.
+- For stable headless QA, run `fields_materialize.py` afterwards.
+
+Example
+-------
+1) Add captions + bookmarks:
+   python scripts/captions_and_crossrefs.py in.docx out_caps.docx --tables --bookmarks
+2) Replace markers with REF fields:
+   python scripts/insert_ref_fields.py out_caps.docx out_refs.docx
+3) Materialize:
+   python scripts/fields_materialize.py out_refs.docx --out out_refs_mat.docx
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import tempfile
+from pathlib import Path
+
+from lxml import etree
+
+try:
+    from docx_ooxml_patch import unzip_docx, zip_docx
+except Exception:
+    # Fallback minimal zip helpers (keeps this script standalone).
+    import os
+    import shutil
+    import zipfile
+
+    def unzip_docx(docx_path: Path, out_dir: Path) -> None:
+        if out_dir.exists():
+            shutil.rmtree(out_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        with zipfile.ZipFile(docx_path, "r") as z:
+            z.extractall(out_dir)
+
+    def zip_docx(in_dir: Path, out_docx_path: Path) -> None:
+        if out_docx_path.exists():
+            out_docx_path.unlink()
+        with zipfile.ZipFile(out_docx_path, "w", compression=zipfile.ZIP_DEFLATED) as z:
+            for root, _dirs, files in os.walk(in_dir):
+                for f in files:
+                    abs_path = Path(root) / f
+                    rel_path = abs_path.relative_to(in_dir)
+                    z.write(abs_path, rel_path.as_posix())
+
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+NS = {
+    "w": W_NS,
+}
+
+
+def qn(local: str) -> str:
+    return f"{{{W_NS}}}{local}"
+
+
+def w_attr(local: str) -> str:
+    return f"{{{W_NS}}}{local}"
+
+
+def _xml_space_preserve(t_el: etree._Element) -> None:
+    if t_el.text and (t_el.text.startswith(" ") or t_el.text.endswith(" ")):
+        t_el.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+
+
+def _load_tree(path: Path) -> etree._ElementTree:
+    parser = etree.XMLParser(remove_blank_text=False)
+    return etree.parse(str(path), parser)
+
+
+def _save_tree(tree: etree._ElementTree, path: Path) -> None:
+    tree.write(str(path), xml_declaration=True, encoding="UTF-8", standalone="yes")
+
+
+def _iter_word_parts(unzipped: Path) -> list[Path]:
+    parts = [unzipped / "word" / "document.xml"]
+    for pat in ("header*.xml", "footer*.xml"):
+        parts.extend(sorted((unzipped / "word").glob(pat)))
+    return [p for p in parts if p.exists()]
+
+
+def _make_run_text(txt: str) -> etree._Element:
+    r = etree.Element(qn("r"))
+    t = etree.SubElement(r, qn("t"))
+    t.text = txt
+    _xml_space_preserve(t)
+    return r
+
+
+def _make_ref_field_runs(bookmark: str) -> list[etree._Element]:
+    """Create runs implementing a REF field (begin/instr/separate/result/end)."""
+    runs: list[etree._Element] = []
+
+    r_begin = etree.Element(qn("r"))
+    fld_begin = etree.SubElement(r_begin, qn("fldChar"))
+    fld_begin.set(w_attr("fldCharType"), "begin")
+    runs.append(r_begin)
+
+    r_instr = etree.Element(qn("r"))
+    instr = etree.SubElement(r_instr, qn("instrText"))
+    instr.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    instr.text = f" REF {bookmark} \\h "
+    runs.append(r_instr)
+
+    r_sep = etree.Element(qn("r"))
+    fld_sep = etree.SubElement(r_sep, qn("fldChar"))
+    fld_sep.set(w_attr("fldCharType"), "separate")
+    runs.append(r_sep)
+
+    r_res = etree.Element(qn("r"))
+    t_res = etree.SubElement(r_res, qn("t"))
+    t_res.text = "0"  # placeholder; can be materialized later
+    runs.append(r_res)
+
+    r_end = etree.Element(qn("r"))
+    fld_end = etree.SubElement(r_end, qn("fldChar"))
+    fld_end.set(w_attr("fldCharType"), "end")
+    runs.append(r_end)
+
+    return runs
+
+
+def replace_markers_in_part(
+    tree: etree._ElementTree,
+    marker_re: re.Pattern[str],
+    prefix: str,
+) -> int:
+    """Replace markers in <w:t> nodes. Marker must be fully inside one node."""
+    root = tree.getroot()
+    changed = 0
+
+    for t in root.findall(".//w:t", namespaces=NS):
+        if t.text is None:
+            continue
+        matches = list(marker_re.finditer(t.text))
+        if not matches:
+            continue
+
+        # Find the run containing this <w:t>
+        r = t.getparent()
+        if r is None or r.tag != qn("r"):
+            continue
+        p = r.getparent()
+        if p is None:
+            continue
+
+        idx = p.index(r)
+
+        # Remove original run
+        p.remove(r)
+
+        # Replace all markers inside this one <w:t>.
+        insert_runs: list[etree._Element] = []
+        pos = 0
+        for m in matches:
+            before = t.text[pos : m.start()]
+            if before:
+                insert_runs.append(_make_run_text(before))
+            if prefix:
+                insert_runs.append(_make_run_text(prefix))
+            insert_runs.extend(_make_ref_field_runs(m.group("bookmark")))
+            pos = m.end()
+
+        after = t.text[pos:]
+        if after:
+            insert_runs.append(_make_run_text(after))
+
+        for j, rr in enumerate(insert_runs):
+            p.insert(idx + j, rr)
+
+        changed += len(matches)
+
+    return changed
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("input_docx", type=Path)
+    ap.add_argument("output_docx", type=Path)
+    ap.add_argument(
+        "--pattern",
+        default=r"\[\[REF:(?P<bookmark>[A-Za-z0-9_:\-]+)\]\]",
+        help=(
+            "Regex for markers. Must contain a named group 'bookmark'. "
+            "Default matches [[REF:tbl1]]."
+        ),
+    )
+    ap.add_argument(
+        "--prefix",
+        default="",
+        help="Optional text inserted immediately before the REF field.",
+    )
+    args = ap.parse_args()
+
+    marker_re = re.compile(args.pattern)
+
+    with tempfile.TemporaryDirectory(prefix="docx_unz_") as td:
+        unz = Path(td) / "unz"
+        unzip_docx(args.input_docx, unz)
+
+        total = 0
+        for part in _iter_word_parts(unz):
+            tree = _load_tree(part)
+            total += replace_markers_in_part(tree, marker_re, args.prefix)
+            _save_tree(tree, part)
+
+        zip_docx(unz, args.output_docx)
+
+    print(f"[OK] wrote {args.output_docx} | markers_replaced={total}")
+
+
+if __name__ == "__main__":
+    main()

package/resources/local/codex/plugins/cache/openai-primary-runtime/documents/26.505.10851/skills/documents/scripts/insert_toc.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Insert a Table of Contents (TOC) field at a placeholder paragraph.
+
+Default behavior
+----------------
+- Finds a paragraph whose full text equals the placeholder token (default: "[[TOC]]").
+- Replaces it with a Word TOC field code (complex field with fldChar begin/separate/end).
+- Sets the document setting "updateFields on open" so Word refreshes TOC/page/refs when opened.
+
+Why this exists
+---------------
+TOCs are extremely common in reports, and "TOC looks wrong" is often because:
+- headings aren't using Heading 1/2/3 styles, or
+- fields were not updated before rendering/export.
+
+This script doesn't *compute* the TOC. Word (or a GUI editor) still needs to update fields.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from lxml import etree
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+NS = {"w": W_NS}
+
+
+def _set_update_fields_on_open(docx_path: Path) -> None:
+    """Ensure word/settings.xml contains <w:updateFields w:val="true"/>."""
+
+    tmp = Path(tempfile.mkdtemp(prefix="docx_toc_patch_"))
+    try:
+        with zipfile.ZipFile(docx_path, "r") as z:
+            z.extractall(tmp)
+
+        settings = tmp / "word" / "settings.xml"
+        settings.parent.mkdir(parents=True, exist_ok=True)
+
+        parser = etree.XMLParser(remove_blank_text=False)
+        if settings.exists():
+            tree = etree.parse(str(settings), parser)
+            root = tree.getroot()
+        else:
+            root = etree.Element(f"{{{W_NS}}}settings", nsmap={"w": W_NS})
+            tree = etree.ElementTree(root)
+
+        uf = root.find("w:updateFields", namespaces=NS)
+        if uf is None:
+            uf = etree.Element(f"{{{W_NS}}}updateFields")
+            root.insert(0, uf)
+        uf.set(f"{{{W_NS}}}val", "true")
+
+        tree.write(str(settings), xml_declaration=True, encoding="UTF-8", standalone="yes")
+
+        # Repack
+        out = docx_path
+        with zipfile.ZipFile(out, "w", compression=zipfile.ZIP_DEFLATED) as z:
+            for p in tmp.rglob("*"):
+                if p.is_dir():
+                    continue
+                z.write(p, p.relative_to(tmp).as_posix())
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _clear_paragraph(p) -> None:
+    for r in list(p.runs)[::-1]:
+        p._p.remove(r._r)
+
+
+def _add_toc_field(paragraph, levels: str = "1-3") -> None:
+    """Insert a TOC field into an existing paragraph."""
+
+    r = paragraph.add_run()
+    fld_begin = OxmlElement("w:fldChar")
+    fld_begin.set(qn("w:fldCharType"), "begin")
+
+    instr = OxmlElement("w:instrText")
+    instr.set(qn("xml:space"), "preserve")
+    # Typical field switches: \o = levels, \h = hyperlinks, \z = hide page numbers in web layout, \u = use applied outline levels
+    instr.text = f' TOC \\o "{levels}" \\h \\z \\u '
+
+    fld_sep = OxmlElement("w:fldChar")
+    fld_sep.set(qn("w:fldCharType"), "separate")
+
+    # Placeholder display text before update
+    t = OxmlElement("w:t")
+    t.text = "(TOC will populate after updating fields)"
+
+    fld_end = OxmlElement("w:fldChar")
+    fld_end.set(qn("w:fldCharType"), "end")
+
+    r._r.append(fld_begin)
+    r._r.append(instr)
+    r._r.append(fld_sep)
+    r._r.append(t)
+    r._r.append(fld_end)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Insert a Word TOC field at a placeholder paragraph.")
+    ap.add_argument("docx", type=Path)
+    ap.add_argument("--out", type=Path, default=None, help="Output DOCX path (default: in-place)")
+    ap.add_argument("--placeholder", default="[[TOC]]", help="Paragraph text token to replace")
+    ap.add_argument("--levels", default="1-3", help='Heading levels range, e.g. "1-3"')
+    args = ap.parse_args()
+
+    in_path = args.docx
+    if not in_path.exists():
+        raise FileNotFoundError(in_path)
+    out_path = args.out or in_path
+    if out_path != in_path:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(in_path, out_path)
+
+    doc = Document(str(out_path))
+    target = None
+    for p in doc.paragraphs:
+        if (p.text or "").strip() == args.placeholder:
+            target = p
+            break
+    if target is None:
+        raise RuntimeError(
+            f"Could not find a paragraph whose text == placeholder {args.placeholder!r}. "
+            "Tip: add a single paragraph containing that token."
+        )
+
+    _clear_paragraph(target)
+    _add_toc_field(target, levels=args.levels)
+    doc.save(str(out_path))
+
+    _set_update_fields_on_open(out_path)
+    print(f"[OK] Inserted TOC field at placeholder {args.placeholder!r} → {out_path}")
+    print("Next: open in Word → Ctrl+A → F9 (Update Fields) → save → re-render.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        if os.environ.get("DOCS_DEBUG") == "1":
+            raise
+        print(f"[ERROR] {e}", file=sys.stderr)
+        raise SystemExit(2)