winter-super-cli 2026.5.15

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

@@ -0,0 +1,365 @@
+#!/usr/bin/env python3
+"""Add internal navigation aids to a DOCX (bookmarks + internal hyperlinks).
+
+This is an OOXML-level helper for deterministic navigation in headless flows.
+
+What it does
+------------
+- Adds Top / Bottom / TOC bookmarks.
+- Adds bookmarks on heading paragraphs (Heading1/2/3 by default).
+- Builds a *static* Table of Contents section with internal hyperlinks.
+- Adds a "Back to TOC" link on each heading paragraph.
+- Optionally adds a quick-links bar including Top/Bottom + figN/tblN bookmarks.
+
+Why static TOC?
+--------------
+Word's TOC is a field and typically requires Word to update. In automation
+pipelines, a deterministic static TOC is easier to QA and reason about.
+
+Usage
+-----
+python scripts/internal_nav.py in.docx --out out.docx
+python scripts/internal_nav.py in.docx --out out.docx --levels 1 2
+python scripts/internal_nav.py in.docx --out out.docx --no_quicklinks
+
+Notes
+-----
+- Internal links use <w:hyperlink w:anchor="bookmarkName">.
+- This script patches only word/document.xml.
+"""
+
+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:
+    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"
+R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+NS = {"w": W_NS, "r": R_NS}
+XML_NS = "http://www.w3.org/XML/1998/namespace"
+
+
+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(f"{{{XML_NS}}}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 _max_bookmark_id(root: etree._Element) -> int:
+    mx = 0
+    for b in root.findall(".//w:bookmarkStart", namespaces=NS):
+        v = b.get(w_attr("id"))
+        if v and v.isdigit():
+            mx = max(mx, int(v))
+    for b in root.findall(".//w:bookmarkEnd", namespaces=NS):
+        v = b.get(w_attr("id"))
+        if v and v.isdigit():
+            mx = max(mx, int(v))
+    return mx
+
+
+def _p_text(p: etree._Element) -> str:
+    return "".join(p.xpath(".//w:t/text()", namespaces=NS)).strip()
+
+
+def _p_style(p: etree._Element) -> str | None:
+    st = p.find("w:pPr/w:pStyle", namespaces=NS)
+    if st is None:
+        return None
+    return st.get(w_attr("val"))
+
+
+def _outline_level(p: etree._Element) -> int | None:
+    """Return Word outline level (0-based) if present, else None."""
+    ol = p.find("w:pPr/w:outlineLvl", namespaces=NS)
+    if ol is None:
+        return None
+    v = ol.get(w_attr("val"))
+    if v is None or not v.isdigit():
+        return None
+    return int(v)
+
+
+def _make_paragraph(text: str, style: str | None = None) -> etree._Element:
+    p = etree.Element(qn("p"))
+    if style is not None:
+        pPr = etree.SubElement(p, qn("pPr"))
+        pStyle = etree.SubElement(pPr, qn("pStyle"))
+        pStyle.set(w_attr("val"), style)
+    r = etree.SubElement(p, qn("r"))
+    t = etree.SubElement(r, qn("t"))
+    t.text = text
+    _xml_space_preserve(t)
+    return p
+
+
+def _make_internal_hyperlink(anchor: str, text: str) -> etree._Element:
+    hl = etree.Element(qn("hyperlink"))
+    hl.set(w_attr("anchor"), anchor)
+
+    r = etree.SubElement(hl, qn("r"))
+    rPr = etree.SubElement(r, qn("rPr"))
+    rStyle = etree.SubElement(rPr, qn("rStyle"))
+    rStyle.set(w_attr("val"), "Hyperlink")
+
+    t = etree.SubElement(r, qn("t"))
+    t.text = text
+    _xml_space_preserve(t)
+    return hl
+
+
+def _insert_bookmark_in_paragraph(p: etree._Element, name: str, bm_id: int) -> None:
+    # Avoid duplicates: if bookmarkStart with same name exists in paragraph, skip
+    for b in p.findall(".//w:bookmarkStart", namespaces=NS):
+        if b.get(w_attr("name")) == name:
+            return
+
+    b_start = etree.Element(qn("bookmarkStart"))
+    b_start.set(w_attr("id"), str(bm_id))
+    b_start.set(w_attr("name"), name)
+    b_end = etree.Element(qn("bookmarkEnd"))
+    b_end.set(w_attr("id"), str(bm_id))
+
+    # Put start at the beginning of paragraph content.
+    p.insert(0, b_start)
+    p.append(b_end)
+
+
+def _bookmark_names(root: etree._Element) -> set[str]:
+    out: set[str] = set()
+    for b in root.findall(".//w:bookmarkStart", namespaces=NS):
+        nm = b.get(w_attr("name"))
+        if nm:
+            out.add(nm)
+    return out
+
+
+def _find_fig_tbl_bookmarks(root: etree._Element) -> tuple[list[str], list[str]]:
+    names = sorted(_bookmark_names(root))
+    fig = [n for n in names if re.fullmatch(r"fig\d+", n)]
+    tbl = [n for n in names if re.fullmatch(r"tbl\d+", n)]
+    return fig, tbl
+
+
+def patch_document(
+    docx_in: Path,
+    docx_out: Path,
+    levels: list[int],
+    toc_title: str,
+    add_quicklinks: bool,
+    add_back_to_toc: bool,
+    add_top_bottom: bool,
+) -> None:
+    with tempfile.TemporaryDirectory(prefix="docx_nav_") as td:
+        unz = Path(td) / "unz"
+        unzip_docx(docx_in, unz)
+
+        doc_xml = unz / "word" / "document.xml"
+        tree = _load_tree(doc_xml)
+        root = tree.getroot()
+        body = root.find("w:body", namespaces=NS)
+        if body is None:
+            raise RuntimeError("word/document.xml missing w:body")
+
+        paras = body.findall("w:p", namespaces=NS)
+        if not paras:
+            raise RuntimeError("No paragraphs found in document body")
+
+        bm_id = _max_bookmark_id(root) + 1
+
+        # Add Top / Bottom bookmarks (best-effort).
+        if add_top_bottom:
+            _insert_bookmark_in_paragraph(paras[0], "Top", bm_id)
+            bm_id += 1
+            _insert_bookmark_in_paragraph(paras[-1], "Bottom", bm_id)
+            bm_id += 1
+
+        # Identify headings and bookmark them.
+        heading_infos: list[tuple[int, str, str, etree._Element]] = []
+        sec_idx = 0
+
+        for p in body.findall("w:p", namespaces=NS):
+            # Prefer outline level if present (works even when the doc lacks Heading styles).
+            ol = _outline_level(p)
+            level = None
+            if ol is not None:
+                level = ol + 1
+            else:
+                st = _p_style(p) or ""
+                m = re.fullmatch(r"Heading\s*(\d+)", st)
+                if m is None:
+                    # Common styleId is Heading1/Heading2
+                    m = re.fullmatch(r"Heading(\d+)", st)
+                if m is not None:
+                    level = int(m.group(1))
+
+            if level is None:
+                continue
+            if level not in levels:
+                continue
+            title = _p_text(p)
+            if not title:
+                continue
+            sec_idx += 1
+            bname = f"sec{sec_idx:03d}"
+            _insert_bookmark_in_paragraph(p, bname, bm_id)
+            bm_id += 1
+            heading_infos.append((level, title, bname, p))
+
+        # Insert TOC section at the start of the document.
+        # Place it before the first paragraph.
+        toc_heading = _make_paragraph(toc_title, style="Heading1")
+        _insert_bookmark_in_paragraph(toc_heading, "TOC", bm_id)
+        bm_id += 1
+
+        insert_at = 0
+        body.insert(insert_at, toc_heading)
+        insert_at += 1
+
+        # Build TOC entries
+        for level, title, bname, _p in heading_infos:
+            indent = "  " * (max(1, level) - 1)
+            p_ent = etree.Element(qn("p"))
+            if indent:
+                r = etree.SubElement(p_ent, qn("r"))
+                t = etree.SubElement(r, qn("t"))
+                t.text = indent
+                _xml_space_preserve(t)
+            p_ent.append(_make_internal_hyperlink(bname, title))
+            body.insert(insert_at, p_ent)
+            insert_at += 1
+
+        # Add a blank line after TOC
+        body.insert(insert_at, _make_paragraph(""))
+        insert_at += 1
+
+        # Add quick links bar after TOC (implemented here to avoid placeholder run)
+        if add_quicklinks:
+            fig_bm, tbl_bm = _find_fig_tbl_bookmarks(root)
+            p_links = etree.Element(qn("p"))
+            p_links.append(_make_internal_hyperlink("Top", "Top"))
+
+            # separator runs
+            def _sep(txt: str) -> etree._Element:
+                r = etree.Element(qn("r"))
+                t = etree.SubElement(r, qn("t"))
+                t.text = txt
+                _xml_space_preserve(t)
+                return r
+
+            p_links.append(_sep(" | "))
+            p_links.append(_make_internal_hyperlink("Bottom", "Bottom"))
+            p_links.append(_sep(" | "))
+            p_links.append(_make_internal_hyperlink("TOC", "TOC"))
+
+            # Link to each table/figure bookmark (caption-number bookmarks)
+            for b in tbl_bm:
+                num = b.replace("tbl", "")
+                p_links.append(_sep(" | "))
+                p_links.append(_make_internal_hyperlink(b, f"Table {num}"))
+            for b in fig_bm:
+                num = b.replace("fig", "")
+                p_links.append(_sep(" | "))
+                p_links.append(_make_internal_hyperlink(b, f"Figure {num}"))
+
+            body.insert(insert_at, p_links)
+            insert_at += 1
+            body.insert(insert_at, _make_paragraph(""))
+            insert_at += 1
+
+        # Add "Back to TOC" on headings
+        if add_back_to_toc:
+            for _level, _title, _bname, p in heading_infos:
+                # Add a space run then hyperlink
+                r = etree.SubElement(p, qn("r"))
+                t = etree.SubElement(r, qn("t"))
+                t.text = " "
+                _xml_space_preserve(t)
+                p.append(_make_internal_hyperlink("TOC", "Back to TOC"))
+
+        _save_tree(tree, doc_xml)
+        zip_docx(unz, docx_out)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        description="Add internal navigation links/bookmarks and a static TOC"
+    )
+    ap.add_argument("input_docx")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--toc_title", default="Table of Contents")
+    ap.add_argument(
+        "--levels",
+        nargs="+",
+        type=int,
+        default=[1, 2, 3],
+        help="Heading levels to include",
+    )
+    ap.add_argument("--no_quicklinks", action="store_true", help="Disable quick links bar")
+    ap.add_argument(
+        "--no_back_to_toc",
+        action="store_true",
+        help="Do not add back-to-TOC links on headings",
+    )
+    ap.add_argument("--no_top_bottom", action="store_true", help="Do not add Top/Bottom bookmarks")
+    args = ap.parse_args()
+
+    patch_document(
+        docx_in=Path(args.input_docx),
+        docx_out=Path(args.out),
+        levels=list(args.levels),
+        toc_title=args.toc_title,
+        add_quicklinks=not args.no_quicklinks,
+        add_back_to_toc=not args.no_back_to_toc,
+        add_top_bottom=not args.no_top_bottom,
+    )
+    print(f"[OK] wrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Create reproducible DOCX fixtures for edge-case testing.
+
+Why
+---
+Some DOCX edge cases (tracked changes, VML watermarks) are painful to reproduce
+manually. This script generates small DOCX files and then injects minimal OOXML
+so downstream skills can be tested deterministically.
+
+This is intentionally *not* a general-purpose DOCX generator; it emits a tiny
+set of fixtures with well-known markers.
+
+Outputs
+-------
+- tracked_changes_fixture.docx
+- watermark_fixture.docx
+
+Usage
+-----
+python scripts/make_fixtures.py --outdir /mnt/data/fixtures
+python scripts/make_fixtures.py --outdir /mnt/data/fixtures --only tracked
+
+Notes
+-----
+- Tracked changes are represented by w:ins / w:del wrappers in document.xml.
+- Watermarks are commonly VML in headers (w:pict + v:shape + v:textpath).
+  LibreOffice headless may not render all VML variants; the watermark fixture is
+  primarily for OOXML auditing/removal testing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import zipfile
+from datetime import datetime, timezone
+
+from docx import Document
+from lxml import etree
+
+W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+V_NS = "urn:schemas-microsoft-com:vml"
+O_NS = "urn:schemas-microsoft-com:office:office"
+R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+
+NS = {"w": W_NS, "v": V_NS, "o": O_NS, "r": R_NS}
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _read_zip_xml(z: zipfile.ZipFile, name: str) -> etree._Element:
+    data = z.read(name)
+    return etree.fromstring(data)
+
+
+def _write_zip_xml(zout: zipfile.ZipFile, name: str, root: etree._Element) -> None:
+    xml = etree.tostring(root, xml_declaration=True, encoding="UTF-8", standalone="yes")
+    zout.writestr(name, xml)
+
+
+def _copy_zip_with_overrides(src_path: str, dst_path: str, overrides: dict[str, bytes]) -> None:
+    """Copy all files from src zip to dst zip, overriding specific names."""
+    with (
+        zipfile.ZipFile(src_path, "r") as zin,
+        zipfile.ZipFile(dst_path, "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 any new files not present in src
+        for name, data in overrides.items():
+            if name not in {i.filename for i in zin.infolist()}:
+                zout.writestr(name, data)
+
+
+def make_tracked_changes_fixture(out_path: str) -> None:
+    """Create a minimal tracked-changes DOCX."""
+    tmp_base = out_path + ".base.docx"
+
+    doc = Document()
+    doc.add_heading("Tracked Changes Fixture", level=1)
+    p = doc.add_paragraph("Sentence with a pending edit: ")
+    p.add_run("REPLACE_ME")
+    doc.add_paragraph("End of fixture.")
+    doc.save(tmp_base)
+
+    with zipfile.ZipFile(tmp_base, "r") as z:
+        doc_xml = _read_zip_xml(z, "word/document.xml")
+
+    # Find the run containing 'REPLACE_ME'
+    runs = doc_xml.xpath(".//w:r[w:t='REPLACE_ME']", namespaces=NS)
+    if not runs:
+        raise RuntimeError("Could not find marker text REPLACE_ME in generated document.xml")
+
+    r = runs[0]
+    parent = r.getparent()
+    idx = parent.index(r)
+
+    # Build <w:del> wrapper containing old text
+    del_el = etree.Element(f"{{{W_NS}}}del", nsmap={"w": W_NS, "r": R_NS})
+    del_el.set(f"{{{W_NS}}}id", "1")
+    del_el.set(f"{{{W_NS}}}author", "FixtureMaker")
+    del_el.set(f"{{{W_NS}}}date", _utc_now())
+    del_r = etree.SubElement(del_el, f"{{{W_NS}}}r")
+    del_t = etree.SubElement(del_r, f"{{{W_NS}}}delText")
+    del_t.text = "REPLACE_ME"
+
+    # Build <w:ins> wrapper containing new text
+    ins_el = etree.Element(f"{{{W_NS}}}ins", nsmap={"w": W_NS, "r": R_NS})
+    ins_el.set(f"{{{W_NS}}}id", "2")
+    ins_el.set(f"{{{W_NS}}}author", "FixtureMaker")
+    ins_el.set(f"{{{W_NS}}}date", _utc_now())
+    ins_r = etree.SubElement(ins_el, f"{{{W_NS}}}r")
+    ins_t = etree.SubElement(ins_r, f"{{{W_NS}}}t")
+    ins_t.text = "INSERTED_TEXT"
+
+    # Replace original run with del+ins
+    parent.remove(r)
+    parent.insert(idx, del_el)
+    parent.insert(idx + 1, ins_el)
+
+    # Enable trackRevisions in settings.xml
+    with zipfile.ZipFile(tmp_base, "r") as z:
+        settings = _read_zip_xml(z, "word/settings.xml")
+
+    # Remove existing trackRevisions if present, then add
+    for el in settings.xpath(".//w:trackRevisions", namespaces=NS):
+        el.getparent().remove(el)
+    settings.append(etree.Element(f"{{{W_NS}}}trackRevisions"))
+
+    # Write overridden parts
+    doc_xml_bytes = etree.tostring(
+        doc_xml, xml_declaration=True, encoding="UTF-8", standalone="yes"
+    )
+    settings_bytes = etree.tostring(
+        settings, xml_declaration=True, encoding="UTF-8", standalone="yes"
+    )
+
+    _copy_zip_with_overrides(
+        tmp_base,
+        out_path,
+        {
+            "word/document.xml": doc_xml_bytes,
+            "word/settings.xml": settings_bytes,
+        },
+    )
+
+    os.remove(tmp_base)
+
+
+def _inject_vml_watermark_into_header(header_xml: etree._Element, text: str) -> None:
+    """Inject a simple VML textpath watermark-like shape into the first header."""
+    body = header_xml.find("w:body", namespaces=NS)
+    if body is None:
+        body = header_xml
+
+    p = etree.Element(f"{{{W_NS}}}p")
+    r = etree.SubElement(p, f"{{{W_NS}}}r")
+    pict = etree.SubElement(r, f"{{{W_NS}}}pict")
+
+    # <v:shape> with <v:textpath string="...">
+    shape = etree.SubElement(pict, f"{{{V_NS}}}shape")
+    shape.set("id", "PowerPlusWaterMarkObject1")
+    shape.set(f"{{{O_NS}}}spid", "_x0000_s1025")
+    shape.set("type", "#_x0000_t136")
+    shape.set(
+        "style",
+        "position:absolute;margin-left:0;margin-top:0;width:468pt;height:234pt;rotation:315",
+    )
+    shape.set("fillcolor", "#d0d0d0")
+    shape.set("stroked", "f")
+
+    fill = etree.SubElement(shape, f"{{{V_NS}}}fill")
+    fill.set("opacity", ".25")
+
+    textpath = etree.SubElement(shape, f"{{{V_NS}}}textpath")
+    textpath.set("style", "font-family:'Calibri';font-size:1pt")
+    textpath.set("string", text)
+
+    # Ensure the header has at least one paragraph; insert first.
+    children = list(body)
+    if children:
+        body.insert(0, p)
+    else:
+        body.append(p)
+
+
+def make_watermark_fixture(out_path: str) -> None:
+    """Create a DOCX with a VML watermark-like shape in the header."""
+    tmp_base = out_path + ".base.docx"
+
+    doc = Document()
+    # Force a header part to exist in the generated DOCX
+    section = doc.sections[0]
+    header = section.header
+    if header.paragraphs:
+        header.paragraphs[0].text = ""
+    else:
+        header.add_paragraph("")
+
+    doc.add_heading("Watermark Fixture", level=1)
+    doc.add_paragraph("This file contains a VML watermark-like header shape with text DRAFT.")
+    doc.add_paragraph("LibreOffice headless may not render it; use OOXML audit/removal.")
+    doc.save(tmp_base)
+
+    with zipfile.ZipFile(tmp_base, "r") as z:
+        # Find a header part to patch; prefer header1.xml
+        header_name = None
+        for name in z.namelist():
+            if re.fullmatch(r"word/header\d+\.xml", name):
+                header_name = name
+                break
+        if header_name is None:
+            # Some docs might not have explicit headers; create header1.xml is non-trivial.
+            raise RuntimeError("No header part found in generated DOCX; cannot inject watermark")
+        header_xml = _read_zip_xml(z, header_name)
+
+    _inject_vml_watermark_into_header(header_xml, text="DRAFT")
+    header_bytes = etree.tostring(
+        header_xml, xml_declaration=True, encoding="UTF-8", standalone="yes"
+    )
+
+    _copy_zip_with_overrides(tmp_base, out_path, {header_name: header_bytes})
+    os.remove(tmp_base)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--outdir", required=True, help="Directory to write fixtures")
+    ap.add_argument(
+        "--only",
+        choices=["tracked", "watermark", "all"],
+        default="all",
+        help="Which fixtures to generate",
+    )
+    args = ap.parse_args()
+
+    os.makedirs(args.outdir, exist_ok=True)
+
+    if args.only in ("tracked", "all"):
+        out = os.path.join(args.outdir, "tracked_changes_fixture.docx")
+        make_tracked_changes_fixture(out)
+        print(f"[OK] wrote {out}")
+
+    if args.only in ("watermark", "all"):
+        out = os.path.join(args.outdir, "watermark_fixture.docx")
+        make_watermark_fixture(out)
+        print(f"[OK] wrote {out}")
+
+
+if __name__ == "__main__":
+    main()