@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/docx/scripts/docx_revisions.py

@@ -0,0 +1,146 @@
+#!/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):
+        yield from root.iter(INS, DEL)
+
+
+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/skills/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)})
+    doc.save(args.output)
+    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
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/docx/scripts/docx_validate.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Health-check a .docx package and report issues as JSON.
+
+Usage: docx_validate.py file.docx
+
+Checks (health-check tier, NOT full XSD schema validation):
+  - the file is a readable zip and python-docx can open it
+  - required package parts exist ([Content_Types].xml, document.xml)
+  - every relationship in every .rels file resolves to a part in the
+    package (dangling image/hyperlink/etc. rels are reported; external
+    targets such as hyperlinks are skipped)
+  - r:embed / r:id references in document.xml resolve to relationships
+  - embedded images are non-empty and start with known magic bytes
+    (PNG/JPEG/GIF/BMP/TIFF/EMF/WMF/SVG); no PIL required
+  - paragraph and run style ids referenced by the document exist in
+    styles.xml
+
+Output: {"ok": bool, "issues": [{"severity": "error"|"warning", ...}]}
+Exit code 1 when any error-severity issue is found (warnings exit 0).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import posixpath
+import sys
+import zipfile
+
+from lxml import etree
+
+W = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+R = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+PR = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+IMAGE_MAGIC = (
+    b"\x89PNG\r\n\x1a\n", b"\xff\xd8\xff", b"GIF87a", b"GIF89a",
+    b"BM", b"II*\x00", b"MM\x00*",
+    b"\x01\x00\x00\x00",              # EMF
+    b"\xd7\xcd\xc6\x9a", b"\x01\x00\x09\x00",  # WMF variants
+    b"<?xml", b"<svg",
+)
+
+
+def _issue(issues, severity, code, detail):
+    issues.append({"severity": severity, "code": code, "detail": detail})
+
+
+def _rel_target(base_part: str, target: str) -> str:
+    base_dir = posixpath.dirname(base_part)
+    return posixpath.normpath(posixpath.join(base_dir, target)).lstrip("/")
+
+
+def validate(path: str) -> dict:
+    issues: list[dict] = []
+
+    try:
+        zf = zipfile.ZipFile(path)
+    except (OSError, zipfile.BadZipFile) as exc:
+        _issue(issues, "error", "not-a-zip", str(exc))
+        return {"ok": False, "issues": issues}
+
+    names = set(zf.namelist())
+    bad = zf.testzip()
+    if bad is not None:
+        _issue(issues, "error", "corrupt-member", f"CRC check failed: {bad}")
+
+    for required in ("[Content_Types].xml", "word/document.xml"):
+        if required not in names:
+            _issue(issues, "error", "missing-part",
+                   f"required part absent: {required}")
+    if issues and any(i["severity"] == "error" for i in issues):
+        return {"ok": False, "issues": issues}
+
+    # --- relationships resolve ------------------------------------------
+    rel_ids_by_source: dict[str, dict] = {}
+    for rels_name in [n for n in names if n.endswith(".rels")]:
+        try:
+            root = etree.fromstring(zf.read(rels_name))
+        except etree.XMLSyntaxError as exc:
+            _issue(issues, "error", "bad-rels-xml", f"{rels_name}: {exc}")
+            continue
+        source_part = posixpath.normpath(
+            posixpath.join(posixpath.dirname(rels_name), ".."))
+        source_part = "" if source_part == "." else source_part
+        ids = {}
+        for rel in root.iter(f"{{{PR}}}Relationship"):
+            rid, target = rel.get("Id"), rel.get("Target", "")
+            mode = rel.get("TargetMode", "Internal")
+            ids[rid] = target
+            if mode == "External":
+                continue
+            resolved = _rel_target(source_part + "/x" if source_part
+                                   else "x", target)
+            if resolved not in names:
+                _issue(issues, "error", "dangling-rel",
+                       f"{rels_name}: {rid} -> {target} (missing part)")
+        rel_ids_by_source[source_part or "_package"] = ids
+
+    # --- r:id / r:embed references in document.xml -----------------------
+    doc_root = etree.fromstring(zf.read("word/document.xml"))
+    doc_rels = rel_ids_by_source.get("word", {})
+    for el in doc_root.iter():
+        for attr in (f"{{{R}}}id", f"{{{R}}}embed", f"{{{R}}}link"):
+            rid = el.get(attr)
+            if rid and rid not in doc_rels:
+                _issue(issues, "error", "unresolved-reference",
+                       f"document.xml references {rid} with no relationship")
+
+    # --- embedded images decode ------------------------------------------
+    for name in [n for n in names if n.startswith("word/media/")]:
+        data = zf.read(name)
+        if not data:
+            _issue(issues, "error", "empty-image", name)
+        elif not any(data.startswith(m) for m in IMAGE_MAGIC):
+            _issue(issues, "warning", "unknown-image-format",
+                   f"{name}: unrecognized magic bytes")
+
+    # --- styles referenced exist ------------------------------------------
+    defined = set()
+    if "word/styles.xml" in names:
+        styles_root = etree.fromstring(zf.read("word/styles.xml"))
+        defined = {s.get(f"{{{W}}}styleId")
+                   for s in styles_root.iter(f"{{{W}}}style")}
+    for tag, attr in ((f"{{{W}}}pStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}rStyle", f"{{{W}}}val"),
+                      (f"{{{W}}}tblStyle", f"{{{W}}}val")):
+        for el in doc_root.iter(tag):
+            sid = el.get(attr)
+            if sid and sid not in defined:
+                _issue(issues, "error", "missing-style",
+                       f"style id referenced but not defined: {sid}")
+
+    # --- python-docx can open it ------------------------------------------
+    try:
+        from docx import Document
+        Document(path)
+    except Exception as exc:
+        _issue(issues, "error", "python-docx-open-failed", str(exc))
+
+    ok = not any(i["severity"] == "error" for i in issues)
+    return {"ok": ok, "issues": issues}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Health-check a .docx (not XSD schema validation).")
+    ap.add_argument("path", help="the .docx file to check")
+    args = ap.parse_args()
+    report = validate(args.path)
+    print(json.dumps(report, ensure_ascii=False))
+    return 0 if report["ok"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/docx/scripts/render.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""Render an office file (or PDF) to page/slide PNGs so you can LOOK at the result.
+
+Usage:
+  python3 render.py FILE [--outdir DIR] [--dpi 110] [--pages 1-3] [--pdf-only]
+
+FILE may be .docx/.doc/.pptx/.ppt/.xlsx/.xls/.odt/.odp/.ods/.rtf/.csv or .pdf.
+Office files are converted to PDF with LibreOffice (soffice) in an isolated,
+throw-away user profile (so a running LibreOffice or a stale lock never hangs
+the conversion), then split into PNGs with pdftoppm, or pypdfium2 if poppler
+is missing.
+
+Prints JSON:
+  {"rendered": true, "pdf": "DIR/name.pdf", "pages": N, "files": ["DIR/name-01.png", ...]}
+  {"rendered": false, "missing": [...], "install": "..."}   (exit 0, nothing rendered)
+Exit 1 only when a tool was present but the conversion itself failed.
+
+This file is shared verbatim by the docx, pptx, xlsx and pdf skills.
+"""
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tempfile
+
+OFFICE_EXT = {".docx", ".doc", ".dotx", ".pptx", ".ppt", ".potx", ".xlsx", ".xlsm", ".xls",
+              ".odt", ".odp", ".ods", ".rtf", ".csv"}
+
+
+def find_soffice() -> str | None:
+    override = os.environ.get("SOFFICE")
+    if override is not None:  # explicit path, or "" to mean "no LibreOffice"
+        return override if override and os.path.exists(override) else None
+    for name in ("soffice", "libreoffice"):
+        p = shutil.which(name)
+        if p:
+            return p
+    for p in ("/Applications/LibreOffice.app/Contents/MacOS/soffice",
+              r"C:\Program Files\LibreOffice\program\soffice.exe",
+              r"C:\Program Files (x86)\LibreOffice\program\soffice.exe",
+              "/usr/lib/libreoffice/program/soffice", "/opt/libreoffice/program/soffice"):
+        if os.path.exists(p):
+            return p
+    return None
+
+
+def install_hint(missing: list[str]) -> str:
+    sysname = platform.system()
+    tips = []
+    if "soffice" in missing:
+        tips.append({"Darwin": "brew install --cask libreoffice (or download from libreoffice.org)",
+                     "Linux": "sudo apt-get install -y libreoffice-core libreoffice-writer libreoffice-calc libreoffice-impress",
+                     "Windows": "winget install TheDocumentFoundation.LibreOffice"}.get(sysname, "install LibreOffice"))
+    if "pdftoppm" in missing:
+        tips.append({"Darwin": "brew install poppler", "Linux": "sudo apt-get install -y poppler-utils",
+                     "Windows": "pip install pypdfium2"}.get(sysname, "pip install pypdfium2"))
+    return "; ".join(tips)
+
+
+# Windows/Office CJK font names -> fonts that actually exist on this machine, so the
+# preview shows real glyphs with similar metrics instead of empty boxes. Only the
+# throw-away LibreOffice profile used for rendering is changed; the document is not.
+CJK_SUBSTITUTES = {
+    "Darwin": {
+        "SimSun": "Songti SC", "宋体": "Songti SC", "NSimSun": "Songti SC", "SimSun-ExtB": "Songti SC",
+        "SimHei": "Heiti SC", "黑体": "Heiti SC", "Microsoft YaHei": "Hiragino Sans GB",
+        "微软雅黑": "Hiragino Sans GB", "Microsoft JhengHei": "Heiti TC", "PMingLiU": "Songti TC",
+        "FangSong": "STFangsong", "FangSong_GB2312": "STFangsong", "仿宋": "STFangsong", "仿宋_GB2312": "STFangsong",
+        "KaiTi": "Kaiti SC", "KaiTi_GB2312": "Kaiti SC", "楷体": "Kaiti SC", "楷体_GB2312": "Kaiti SC",
+        "DengXian": "Hiragino Sans GB", "等线": "Hiragino Sans GB",
+        "FZXiaoBiaoSong-B05S": "Songti SC", "方正小标宋简体": "Songti SC",
+    },
+    "Linux": {k: v for k, v in (
+        ("SimSun", "Noto Serif CJK SC"), ("宋体", "Noto Serif CJK SC"), ("NSimSun", "Noto Serif CJK SC"),
+        ("SimHei", "Noto Sans CJK SC"), ("黑体", "Noto Sans CJK SC"), ("Microsoft YaHei", "Noto Sans CJK SC"),
+        ("微软雅黑", "Noto Sans CJK SC"), ("FangSong", "Noto Serif CJK SC"), ("FangSong_GB2312", "Noto Serif CJK SC"),
+        ("KaiTi", "Noto Serif CJK SC"), ("KaiTi_GB2312", "Noto Serif CJK SC"), ("DengXian", "Noto Sans CJK SC"),
+        ("FZXiaoBiaoSong-B05S", "Noto Serif CJK SC"))},
+}
+
+
+SYSTEM_CJK_FONT_FILES = [
+    # LibreOffice on macOS does not see these system fonts; link them into the profile so CJK renders.
+    "/System/Library/Fonts/Hiragino Sans GB.ttc", "/System/Library/Fonts/STHeiti Medium.ttc",
+    "/System/Library/Fonts/STHeiti Light.ttc", "/System/Library/Fonts/Supplemental/Songti.ttc",
+    "/System/Library/Fonts/PingFang.ttc", "/System/Library/Fonts/Supplemental/Kaiti.ttc",
+    "/System/Library/Fonts/Supplemental/STFangsong.ttf", "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+]
+
+
+def write_profile(prof: str) -> None:
+    fonts_dir = os.path.join(prof, "user", "fonts")
+    os.makedirs(fonts_dir, exist_ok=True)
+    for f in SYSTEM_CJK_FONT_FILES:
+        if os.path.exists(f):
+            try:
+                os.symlink(f, os.path.join(fonts_dir, os.path.basename(f)))
+            except OSError:
+                shutil.copy(f, fonts_dir)
+    pairs = CJK_SUBSTITUTES.get(platform.system())
+    if not pairs:
+        return  # Windows has the real fonts
+    from xml.sax.saxutils import quoteattr
+    nodes = "".join(
+        f'<item oor:path="/org.openoffice.VCL/FontSubstitutions"><node oor:name={quoteattr("p" + str(i))} oor:op="replace">'
+        f'<prop oor:name="ReplaceFont"><value>{src}</value></prop>'
+        f'<prop oor:name="SubstituteFont"><value>{dst}</value></prop>'
+        f'<prop oor:name="Always"><value>true</value></prop>'
+        f'<prop oor:name="OnScreenOnly"><value>false</value></prop></node></item>'
+        for i, (src, dst) in enumerate(pairs.items()))
+    nodes += ('<item oor:path="/org.openoffice.VCL"><prop oor:name="FontSubstitutionsEnabled" oor:op="fuse">'
+              '<value>true</value></prop></item>'
+              '<item oor:path="/org.openoffice.Office.Common/Font/Substitution"><prop oor:name="Replacement" oor:op="fuse">'
+              '<value>true</value></prop></item>'
+              '<item oor:path="/org.openoffice.Office.Common/Font/Substitution"><prop oor:name="FontPairs" oor:op="fuse">'
+              '<value>' + "".join(
+                  f'<it><prop oor:name="Always"><value>true</value></prop>'
+                  f'<prop oor:name="OnScreenOnly"><value>false</value></prop>'
+                  f'<prop oor:name="ReplaceFont"><value>{s}</value></prop>'
+                  f'<prop oor:name="SubstituteFont"><value>{d}</value></prop></it>'
+                  for s, d in pairs.items()) + '</value></prop></item>')
+    os.makedirs(os.path.join(prof, "user"), exist_ok=True)
+    with open(os.path.join(prof, "user", "registrymodifications.xcu"), "w", encoding="utf-8") as f:
+        f.write('<?xml version="1.0" encoding="UTF-8"?>\n<oor:items xmlns:oor="http://openoffice.org/2001/registry" '
+                'xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">'
+                + nodes + '</oor:items>\n')
+
+
+def to_pdf(src: str, outdir: str, timeout: int) -> str:
+    soffice = find_soffice()
+    if not soffice:
+        raise LookupError("soffice")
+    with tempfile.TemporaryDirectory(prefix="lo-profile-") as prof:
+        write_profile(prof)
+        profile_url = "file:///" + prof.replace("\\", "/").lstrip("/")
+        cmd = [soffice, f"-env:UserInstallation={profile_url}", "--headless", "--norestore",
+               "--nolockcheck", "--convert-to", "pdf", "--outdir", outdir, src]
+        proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8",
+                              errors="replace", timeout=timeout, check=False)
+    pdf = os.path.join(outdir, os.path.splitext(os.path.basename(src))[0] + ".pdf")
+    if proc.returncode != 0 or not os.path.exists(pdf):
+        raise RuntimeError(f"soffice conversion failed (rc={proc.returncode}): {proc.stderr.strip() or proc.stdout.strip()}")
+    return pdf
+
+
+def parse_pages(spec: str | None, n: int) -> list[int]:
+    if not spec:
+        return list(range(1, n + 1))
+    out: list[int] = []
+    for part in spec.split(","):
+        a, _, b = part.partition("-")
+        lo, hi = int(a), int(b or a)
+        out += [p for p in range(lo, hi + 1) if 1 <= p <= n]
+    return out
+
+
+def pdf_pages(pdf: str) -> int:
+    try:
+        from pypdf import PdfReader
+        return len(PdfReader(pdf).pages)
+    except Exception:
+        info = shutil.which("pdfinfo")
+        if info:
+            r = subprocess.run([info, pdf], capture_output=True, text=True, check=False)
+            for line in r.stdout.splitlines():
+                if line.startswith("Pages:"):
+                    return int(line.split()[1])
+    return 0
+
+
+def rasterize(pdf: str, outdir: str, stem: str, dpi: int, pages: list[int]) -> list[str]:
+    width = max(2, len(str(max(pages) if pages else 1)))
+    files = []
+    tool = shutil.which("pdftoppm")
+    if tool:
+        for p in pages:
+            prefix = os.path.join(outdir, f"{stem}-{p:0{width}d}")
+            subprocess.run([tool, "-png", "-r", str(dpi), "-f", str(p), "-l", str(p), "-singlefile", pdf, prefix],
+                           check=True, capture_output=True)
+            files.append(prefix + ".png")
+        return files
+    import pypdfium2 as pdfium  # raises ImportError -> reported as missing
+    doc = pdfium.PdfDocument(pdf)
+    for p in pages:
+        img = doc[p - 1].render(scale=dpi / 72).to_pil()
+        path = os.path.join(outdir, f"{stem}-{p:0{width}d}.png")
+        img.save(path)
+        files.append(path)
+    return files
+
+
+def main(argv=None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0],
+                                 epilog=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("file")
+    ap.add_argument("--outdir", default=None, help="default: <file dir>/render")
+    ap.add_argument("--dpi", type=int, default=110)
+    ap.add_argument("--pages", default=None, help="e.g. 1-3,7 (default: all)")
+    ap.add_argument("--pdf-only", action="store_true", help="convert to PDF, skip PNGs")
+    ap.add_argument("--timeout", type=int, default=240)
+    a = ap.parse_args(argv)
+
+    src = os.path.abspath(a.file)
+    outdir = os.path.abspath(a.outdir or os.path.join(os.path.dirname(src), "render"))
+    os.makedirs(outdir, exist_ok=True)
+    stem = os.path.splitext(os.path.basename(src))[0]
+    ext = os.path.splitext(src)[1].lower()
+    missing: list[str] = []
+    try:
+        if ext == ".pdf":
+            pdf = src
+        elif ext in OFFICE_EXT:
+            pdf = to_pdf(src, outdir, a.timeout)
+        else:
+            print(json.dumps({"rendered": False, "error": f"unsupported file type {ext}"}))
+            return 1
+    except LookupError:
+        missing.append("soffice")
+    except (RuntimeError, subprocess.TimeoutExpired) as e:
+        print(json.dumps({"rendered": False, "error": str(e)}, ensure_ascii=False))
+        return 1
+    if missing:
+        print(json.dumps({"rendered": False, "missing": missing, "install": install_hint(missing)}, ensure_ascii=False))
+        return 0
+    n = pdf_pages(pdf)
+    if a.pdf_only:
+        print(json.dumps({"rendered": True, "pdf": pdf, "pages": n, "files": []}, ensure_ascii=False))
+        return 0
+    try:
+        for old in glob.glob(os.path.join(outdir, f"{stem}-*.png")):
+            os.remove(old)
+        files = rasterize(pdf, outdir, stem, a.dpi, parse_pages(a.pages, n))
+    except ImportError:
+        print(json.dumps({"rendered": False, "pdf": pdf, "missing": ["pdftoppm"],
+                          "install": install_hint(["pdftoppm"])}, ensure_ascii=False))
+        return 0
+    print(json.dumps({"rendered": True, "pdf": pdf, "pages": n, "files": files}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())