microsoft-word 0.0.0-stage → 0.1.4

package/scripts/requirements.txt

@@ -0,0 +1 @@
+lxml>=4.9

package/scripts/wordpkg.py

@@ -0,0 +1,328 @@
+"""Shared, dependency-light helpers for the microsoft-word scripts.
+
+Not a public API. Imported by inspect_docx.py, docx_replace.py and docx_sanitize.py,
+which sit in the same folder (Python puts the script folder on sys.path).
+
+Safety rules implemented here:
+  - XML is parsed with lxml, entity resolution off, DTD loading off, no network, no huge
+    trees. Those parser flags are the real control against entity attacks; the DOCTYPE
+    check (first 4096 bytes) and ENTITY check only turn an attempt into a clean refusal,
+    since OOXML parts never need either.
+  - Duplicate zip member names, and names that differ only by case, are refused: different
+    readers pick different copies, so the part we inspect might not be the part Word loads.
+  - Archives are refused above a total uncompressed size and member count, before parsing.
+  - Writes go to a temp file next to the output and are linked into place only if the
+    output does not exist yet, so an existing file is never replaced.
+  - lxml is used rather than xml.etree because ElementTree renames namespace prefixes
+    (ns0, ns1) and drops unused declarations, which leaves mc:Ignorable naming prefixes
+    that are no longer declared.
+"""
+import os
+import re
+import sys
+import tempfile
+import zipfile
+from posixpath import dirname, join, normpath
+
+try:
+    from lxml import etree
+except ImportError:  # pragma: no cover
+    sys.stderr.write("error: lxml is required (pip install -r scripts/requirements.txt)\n")
+    sys.exit(3)
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PR = "http://schemas.openxmlformats.org/package/2006/relationships"
+CT = "http://schemas.openxmlformats.org/package/2006/content-types"
+NS = {"w": W, "r": R, "pr": PR, "ct": CT}
+
+MAIN_TYPES = {
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml": "docx",
+    "application/vnd.ms-word.document.macroEnabled.main+xml": "docm",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml": "dotx",
+    "application/vnd.ms-word.template.macroEnabledTemplate.main+xml": "dotm",
+}
+STORY_RELS = {"header", "footer", "footnotes", "endnotes", "comments"}
+
+# C0, DEL, C1 (includes \x9b CSI), Arabic letter mark, zero-width, bidi embeddings,
+# overrides and isolates, word joiner and BOM: they can hide or reorder injected text.
+CTRL = re.compile("[\x00-\x08\x0b-\x1f\x7f-\x9f\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]")
+
+
+class Refusal(Exception):
+    """Safety refusal: exit code 3."""
+
+
+class Unsupported(Exception):
+    """Unsupported or unreadable input: exit code 2."""
+
+
+def w(tag):
+    return f"{{{W}}}{tag}"
+
+
+def clean(v, maxlen=200):
+    if v is None or isinstance(v, (int, float, bool)):
+        return v
+    s = CTRL.sub(" ", str(v))
+    return s if len(s) <= maxlen else s[:maxlen] + "...[truncated]"
+
+
+def sniff(path):
+    """Return 'zip', 'doc' (legacy binary), 'encrypted' (OOXML inside OLE2), 'ole2', 'rtf' or 'other'."""
+    with open(path, "rb") as f:
+        head = f.read(8)
+        if head.startswith(b"PK\x03\x04"):
+            return "zip"
+        if head.startswith(b"{\\rtf"):
+            return "rtf"
+        if head.startswith(b"\xd0\xcf\x11\xe0"):
+            f.seek(0)
+            blob = f.read(4 * 1024 * 1024)  # directory entries are near the start in practice
+            if "EncryptionInfo".encode("utf-16-le") in blob:
+                return "encrypted"
+            if "WordDocument".encode("utf-16-le") in blob:
+                return "doc"
+            return "ole2"
+    return "other"
+
+
+_PARSER = etree.XMLParser(resolve_entities=False, no_network=True, huge_tree=False,
+                          load_dtd=False, remove_blank_text=False)
+
+
+def parse_xml(data):
+    if re.search(rb"<!DOCTYPE", data[:4096], re.I) or b"<!ENTITY" in data:
+        raise Refusal("XML part contains a DOCTYPE or ENTITY declaration (not valid in OOXML)")
+    try:
+        return etree.fromstring(data, _PARSER)
+    except etree.XMLSyntaxError as e:
+        raise Unsupported(f"malformed XML: {e}") from None
+
+
+def serialize(root):
+    return etree.tostring(root, xml_declaration=True, encoding="UTF-8", standalone=True)
+
+
+class Package:
+    """Read-only view of an OOXML Word package."""
+
+    def __init__(self, path, max_mb=200, max_members=5000):
+        kind = sniff(path)
+        if kind == "encrypted":
+            raise Unsupported("encrypted (password-protected) document: decrypt a copy with "
+                              "msoffcrypto-tool using the password the user gives you")
+        if kind == "doc":
+            raise Unsupported("legacy binary .doc: convert a copy to .docx first (references/conversion.md)")
+        if kind == "rtf":
+            raise Unsupported("RTF: convert a copy to .docx first (references/conversion.md)")
+        if kind != "zip":
+            raise Unsupported("not an OOXML zip package")
+        try:
+            self.zip = zipfile.ZipFile(path)
+        except zipfile.BadZipFile as e:
+            raise Unsupported(f"corrupt zip: {e}") from None
+        infos = self.zip.infolist()
+        if len(infos) > max_members:
+            raise Refusal(f"{len(infos)} zip members exceeds the cap of {max_members}")
+        total = sum(i.file_size for i in infos)
+        if total > max_mb * 1024 * 1024:
+            raise Refusal(f"uncompressed size {total // (1024 * 1024)} MB exceeds --max-mb {max_mb}")
+        self.names = [i.filename for i in infos]
+        seen = {}
+        for n in self.names:
+            k = n.lower()
+            if k in seen:
+                what = "duplicate" if seen[k] == n else "case-colliding"
+                raise Refusal(f"{what} zip member names {seen[k]!r} and {n!r}: readers disagree on "
+                              "which one is the real part, refusing")
+            seen[k] = n
+        self._cache = {}
+        if "[Content_Types].xml" not in self.names:
+            raise Unsupported("missing [Content_Types].xml: not an OOXML package")
+        self.overrides = {}
+        self.defaults = {}
+        ct = self.xml("[Content_Types].xml")
+        for o in ct.findall("ct:Override", NS):
+            self.overrides[o.get("PartName", "").lstrip("/")] = o.get("ContentType", "")
+        for d in ct.findall("ct:Default", NS):
+            self.defaults[d.get("Extension", "").lower()] = d.get("ContentType", "")
+        main = [r for r in self.rels("") if r["type"] == "officeDocument" and not r["external"]]
+        if not main:
+            raise Unsupported("no officeDocument relationship in _rels/.rels")
+        self.main = main[0]["target"]
+        if self.main not in self.names:
+            raise Unsupported(f"main part {self.main} is missing")
+        self.content_type = self.content_type_of(self.main)
+        self.kind = MAIN_TYPES.get(self.content_type)
+        if self.kind is None:
+            raise Unsupported(f"not a Word document (main content type {self.content_type!r})")
+
+    def content_type_of(self, name):
+        if name in self.overrides:
+            return self.overrides[name]
+        return self.defaults.get(name.rsplit(".", 1)[-1].lower(), "")
+
+    def read(self, name):
+        return self.zip.read(name)
+
+    def xml(self, name):
+        if name not in self._cache:
+            self._cache[name] = parse_xml(self.zip.read(name))
+        return self._cache[name]
+
+    def rels_name(self, part):
+        return join(dirname(part), "_rels", part.rsplit("/", 1)[-1] + ".rels") if part else "_rels/.rels"
+
+    def rels(self, part):
+        """Relationships of a part: list of dicts with id, type (short), target (resolved), external."""
+        rn = self.rels_name(part)
+        if rn not in self.names:
+            return []
+        out = []
+        for r in self.xml(rn).findall("pr:Relationship", NS):
+            ext = r.get("TargetMode") == "External"
+            tgt = r.get("Target", "")
+            if not ext:
+                tgt = normpath(join(dirname(part), tgt)).lstrip("/") if not tgt.startswith("/") else tgt.lstrip("/")
+            out.append({"id": r.get("Id"), "type": r.get("Type", "").rsplit("/", 1)[-1],
+                        "full_type": r.get("Type", ""), "target": tgt, "external": ext})
+        return out
+
+    def story_parts(self, include_comments=False):
+        """Main document plus headers, footers, footnotes, endnotes (and comments if asked)."""
+        parts = [self.main]
+        for r in self.rels(self.main):
+            if r["external"] or r["target"] not in self.names:
+                continue
+            if r["type"] in STORY_RELS and (include_comments or r["type"] != "comments"):
+                if r["target"] not in parts:
+                    parts.append(r["target"])
+        return parts
+
+    def glossary_parts(self):
+        """The glossary document (building blocks, AutoText) and its own headers, footers, notes.
+        Word never shows it in the body, but its text travels with the file."""
+        g = [r["target"] for r in self.rels(self.main)
+             if r["type"] == "glossaryDocument" and not r["external"] and r["target"] in self.names]
+        out = []
+        for gp in g:
+            out.append(gp)
+            for r in self.rels(gp):
+                if not r["external"] and r["target"] in self.names and r["type"] in STORY_RELS \
+                        and r["target"] not in out:
+                    out.append(r["target"])
+        return out
+
+
+OFF = {"0", "false", "off"}
+HIDE_TAGS = ("vanish", "specVanish", "webHidden")
+
+
+def toggle(rpr, tag):
+    """True, False, or None (not set) for a toggle property such as w:vanish in an rPr."""
+    if rpr is None:
+        return None
+    x = rpr.find(f"w:{tag}", NS)
+    if x is None:
+        return None
+    return x.get(w("val"), "true").lower() not in OFF
+
+
+class Hidden:
+    """Decides whether a run is hidden: direct w:vanish, w:specVanish or w:webHidden, else the
+    character style chain (rStyle, basedOn), else the paragraph style chain (pStyle or the
+    default paragraph style), else docDefaults. An explicit val="0" at a closer level wins.
+    Simplification: Word XORs toggle properties between style levels; this treats the
+    closest explicit setting as final, which errs toward reporting text as hidden."""
+
+    def __init__(self, pkg):
+        self.styles, self.default_para, self.doc_default = {}, None, {}
+        if "word/styles.xml" in pkg.names:
+            sx = pkg.xml("word/styles.xml")
+            dd = sx.find("w:docDefaults/w:rPrDefault/w:rPr", NS)
+            self.doc_default = {t: toggle(dd, t) for t in HIDE_TAGS}
+            for s in sx.findall("w:style", NS):
+                b = s.find("w:basedOn", NS)
+                self.styles[s.get(w("styleId"))] = (
+                    b.get(w("val")) if b is not None else None,
+                    {t: toggle(s.find("w:rPr", NS), t) for t in HIDE_TAGS})
+                if s.get(w("type")) == "paragraph" and s.get(w("default")) in ("1", "true", "on"):
+                    self.default_para = s.get(w("styleId"))
+
+    def _chain(self, sid, tag):
+        seen = set()
+        while sid and sid in self.styles and sid not in seen:
+            seen.add(sid)
+            based, props = self.styles[sid]
+            if props[tag] is not None:
+                return props[tag]
+            sid = based
+        return None
+
+    def run_hidden(self, r):
+        rpr = r.find("w:rPr", NS)
+        st = rpr.find("w:rStyle", NS) if rpr is not None else None
+        p = next((a for a in r.iterancestors(w("p"))), None)
+        ps = p.find("w:pPr/w:pStyle", NS) if p is not None else None
+        pid = ps.get(w("val")) if ps is not None else self.default_para
+        for tag in HIDE_TAGS:
+            for v in (toggle(rpr, tag),
+                      self._chain(st.get(w("val")), tag) if st is not None else None,
+                      self._chain(pid, tag),
+                      self.doc_default.get(tag)):
+                if v is not None:
+                    if v:
+                        return tag
+                    break
+        return None
+
+
+def write_package(src_zip, out_path, replaced, removed=()):
+    """Copy every member of src_zip to out_path, replacing the bytes of members in `replaced`
+    and dropping members in `removed`. Untouched members keep their bytes and order.
+    Refuses (Refusal) if out_path already exists; never replaces it."""
+    out_path = os.path.abspath(out_path)
+    if os.path.lexists(out_path):
+        raise Refusal(f"output exists, refusing to overwrite: {out_path}")
+    fd, tmp = tempfile.mkstemp(prefix=".tmp-", suffix=".docx", dir=os.path.dirname(out_path))
+    os.close(fd)
+    try:
+        with zipfile.ZipFile(tmp, "w") as dst:
+            for info in src_zip.infolist():
+                if info.filename in removed:
+                    continue
+                data = replaced.get(info.filename)
+                if data is None:
+                    data = src_zip.read(info.filename)
+                zi = zipfile.ZipInfo(info.filename, date_time=info.date_time)
+                zi.compress_type = zipfile.ZIP_DEFLATED if info.compress_type != zipfile.ZIP_STORED else zipfile.ZIP_STORED
+                # regular file, rw-r--r--: never copy symlink or setuid bits from the source
+                zi.external_attr = 0o100644 << 16
+                dst.writestr(zi, data)
+        try:
+            os.link(tmp, out_path)  # atomic: fails if out_path appeared meanwhile
+        except FileExistsError:
+            raise Refusal(f"output exists, refusing to overwrite: {out_path}") from None
+        except OSError:
+            # filesystem without hard links: create the output exclusively, then copy into it
+            try:
+                fd = os.open(out_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+            except FileExistsError:
+                raise Refusal(f"output exists, refusing to overwrite: {out_path}") from None
+            with os.fdopen(fd, "wb") as dst_f, open(tmp, "rb") as src_f:
+                while True:
+                    chunk = src_f.read(1 << 20)
+                    if not chunk:
+                        break
+                    dst_f.write(chunk)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def same_file(a, b):
+    try:
+        return os.path.samefile(a, b)
+    except FileNotFoundError:
+        return os.path.abspath(a) == os.path.abspath(b)

package/skill.json

@@ -0,0 +1,55 @@
+{
+  "name": "microsoft-word",
+  "version": "0.1.4",
+  "description": "Use when reading, creating, editing, converting, comparing, redacting or automating Microsoft Word documents (.docx, .docm, .dotx, .dotm, .doc, .rtf): find and replace that misses text split across runs, python-docx, docx.js (docx npm), docxtpl, mammoth or pandoc output that loses text or formatting, stale TOC or REF fields, tracked changes and comments, headers and footers, numbering, content controls, mail merge, LibreOffice headless PDF export, Office.js, VBA or Microsoft Graph automation, SharePoint or OneDrive files, and safe handling of untrusted documents (macros, remote templates, DDE fields, hidden text and metadata before sharing). Not needed for plain text or Markdown files that never become a Word document.",
+  "entry": "SKILL.md",
+  "skill_md_url": "https://raw.githubusercontent.com/skillsaas/microsoft-word/main/SKILL.md",
+  "repository": "https://github.com/skillsaas/microsoft-word",
+  "license": "MIT",
+  "platforms": {
+    "scripts": "any OS with Python 3.9+ and lxml",
+    "docx_refresh.py": "Linux only (bubblewrap or unshare); refuses on macOS/Windows by design"
+  },
+  "requires": {
+    "python": ">=3.9",
+    "pip": [
+      "lxml"
+    ],
+    "pip_optional": [
+      "python-docx",
+      "mammoth"
+    ],
+    "system_optional": [
+      "pandoc",
+      "libreoffice-writer",
+      "bubblewrap"
+    ]
+  },
+  "published": {
+    "npm": true,
+    "github": true
+  },
+  "verification": {
+    "tested_on_box": [
+      "scripts/*.py (tests/smoke_test.py)",
+      "references/extraction.md matrix",
+      "LibreOffice 25.2.3.2 with bwrap"
+    ],
+    "documented_not_executed": [
+      "references/automation.md (Office.js type-checked with tsc and a mock, Graph checked against msgraph-metadata, VBA against docs; no live Word or tenant run)",
+      "references/word-ui.md (Word menus and keys)"
+    ]
+  },
+  "third_party_licenses": {
+    "lxml": "BSD-3-Clause",
+    "python-docx": "MIT",
+    "mammoth": "BSD-2-Clause",
+    "pandoc": "GPL-2.0-or-later",
+    "libreoffice-writer": "MPL-2.0",
+    "bubblewrap": "LGPL-2.0-or-later",
+    "docxtpl": "LGPL-2.1",
+    "docx (npm)": "MIT",
+    "msoffcrypto-tool": "MIT",
+    "openpyxl": "MIT"
+  }
+}