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

package/skills/docx/scripts/docx_create.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+# MIT License. Part of the Hermes docx skill.
+"""Create a .docx document from a JSON spec.
+
+Usage: docx_create.py spec.json output.docx
+Run with --help for the spec format summary.
+
+Spec (JSON object):
+{
+  "page": {"width_mm": 210, "height_mm": 297,
+           "margins_mm": {"top": 25, "bottom": 25, "left": 20, "right": 20}},
+  "header": "text shown in page header",
+  "footer": "text shown in page footer",
+  "styles": [{"name": "MyStyle", "base": "Normal", "font": "Arial",
+              "size_pt": 12, "bold": true, "color": "1F4E79"}],
+  "blocks": [
+    {"type": "heading", "text": "Title", "level": 1},
+    {"type": "paragraph", "style": "MyStyle", "runs": [
+        {"text": "plain "}, {"text": "bold", "bold": true},
+        {"text": " italic", "italic": true},
+        {"text": " under", "underline": true}]},
+    {"type": "paragraph", "text": "shortcut: single plain run"},
+    {"type": "bullet_list", "items": ["a", "b"]},
+    {"type": "numbered_list", "items": ["one", "two"]},
+    {"type": "table", "header": ["Col1", "Col2"],
+     "rows": [["1", "2"]], "style": "Light Grid Accent 1",
+     "header_bold": true},
+    {"type": "image", "path": "pic.png", "width_mm": 60},
+    {"type": "page_break"},
+    {"type": "toc"}
+  ]
+}
+
+Paragraph extras: "align": "center"|"right"|"justify", "first_line_chars": 0 to cancel the indent.
+Chinese defaults (spec contains Chinese): body paragraphs get a 2-character first-line indent
+(top-level "first_line_chars" to change), line spacing 1.5 (top-level "line_spacing"),
+and A4 paper with 25 mm margins unless "page" sets width_mm. Tables: cells vertically
+centered, numbers right-aligned, header row repeats across pages.
+CJK: when the spec contains Chinese/Japanese/Korean text, East Asian fonts are set
+automatically (body SimSun, headings SimHei). Override with
+`"cjk_fonts": {"body": "FangSong_GB2312", "heading": "SimHei"}` or disable with `"cjk_fonts": false`.
+
+Extras: `"footer_page_numbers": true` at the top level adds a
+"Page X of Y" footer built from PAGE/NUMPAGES fields, and a `toc` block
+inserts a Table of Contents field. Field results are computed by
+Word/LibreOffice when the file is opened, not by python-docx.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from docx import Document
+from docx.enum.style import WD_STYLE_TYPE
+from docx.enum.text import WD_BREAK
+from docx.shared import Mm, Pt, RGBColor
+from docx.oxml.ns import qn
+
+_NUMERIC = re.compile(r"^[\s¥$€£+\-−]*[\d,.]+\s*(%|万|亿|元|万元|k|K|M)?\s*$")
+
+
+def _tidy_table(table, has_header: bool) -> None:
+    """Cells: vertically centered, no inherited first-line indent / spacing,
+    numeric cells right-aligned, header row repeated on page breaks."""
+    from docx.enum.table import WD_ALIGN_VERTICAL
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.oxml import OxmlElement
+    for r, row in enumerate(table.rows):
+        for cell in row.cells:
+            cell.vertical_alignment = WD_ALIGN_VERTICAL.CENTER
+            for para in cell.paragraphs:
+                pf = para.paragraph_format
+                pf.first_line_indent = Pt(0)
+                pf.space_before = Pt(2)
+                pf.space_after = Pt(2)
+                pf.line_spacing = 1.0
+                ind = para._p.get_or_add_pPr().find(qn("w:ind"))
+                if ind is not None and ind.get(qn("w:firstLineChars")) is not None:
+                    ind.set(qn("w:firstLineChars"), "0")
+                if has_header and r == 0:
+                    para.alignment = WD_ALIGN_PARAGRAPH.CENTER
+                elif _NUMERIC.match(cell.text or ""):
+                    para.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    if has_header and table.rows:
+        tr_pr = table.rows[0]._tr.get_or_add_trPr()
+        if tr_pr.find(qn("w:tblHeader")) is None:
+            tr_pr.append(OxmlElement("w:tblHeader"))
+
+
+def apply_page(doc, page: dict) -> None:
+    section = doc.sections[0]
+    if "width_mm" in page:
+        section.page_width = Mm(page["width_mm"])
+    if "height_mm" in page:
+        section.page_height = Mm(page["height_mm"])
+    m = page.get("margins_mm", {})
+    for side in ("top", "bottom", "left", "right"):
+        if side in m:
+            setattr(section, f"{side}_margin", Mm(m[side]))
+
+
+def add_styles(doc, styles: list) -> None:
+    for s in styles:
+        style = doc.styles.add_style(s["name"], WD_STYLE_TYPE.PARAGRAPH)
+        if s.get("base"):
+            style.base_style = doc.styles[s["base"]]
+        font = style.font
+        if s.get("font"):
+            font.name = s["font"]
+        if s.get("size_pt"):
+            font.size = Pt(s["size_pt"])
+        if s.get("bold") is not None:
+            font.bold = s["bold"]
+        if s.get("italic") is not None:
+            font.italic = s["italic"]
+        if s.get("color"):
+            font.color.rgb = RGBColor.from_string(s["color"])
+
+
+def add_runs(para, block: dict) -> None:
+    runs = block.get("runs")
+    if runs is None:
+        runs = [{"text": block.get("text", "")}]
+    for r in runs:
+        run = para.add_run(r.get("text", ""))
+        if r.get("bold"):
+            run.bold = True
+        if r.get("italic"):
+            run.italic = True
+        if r.get("underline"):
+            run.underline = True
+
+
+CJK_INDENT = 0  # set to 2 by main() for Chinese documents unless the spec says otherwise
+
+
+def add_block(doc, block: dict) -> None:
+    btype = block["type"]
+    if btype == "heading":
+        doc.add_heading(block.get("text", ""), level=block.get("level", 1))
+    elif btype == "paragraph":
+        para = doc.add_paragraph(style=block.get("style"))
+        add_runs(para, block)
+        indent = block.get("first_line_chars", CJK_INDENT)
+        if indent:  # Chinese body text: first-line indent in characters, scales with font size
+            from docx.oxml.ns import qn
+            from docx.oxml import OxmlElement
+            ind = OxmlElement("w:ind")
+            ind.set(qn("w:firstLineChars"), str(int(indent * 100)))
+            para._p.get_or_add_pPr().append(ind)
+        if block.get("align"):
+            from docx.enum.text import WD_ALIGN_PARAGRAPH
+            para.alignment = getattr(WD_ALIGN_PARAGRAPH, block["align"].upper())
+    elif btype == "bullet_list":
+        for item in block.get("items", []):
+            doc.add_paragraph(item, style="List Bullet")
+    elif btype == "numbered_list":
+        for item in block.get("items", []):
+            doc.add_paragraph(item, style="List Number")
+    elif btype == "table":
+        header = block.get("header", [])
+        rows = block.get("rows", [])
+        ncols = len(header) if header else (len(rows[0]) if rows else 1)
+        table = doc.add_table(rows=0, cols=ncols)
+        table.style = block.get("style", "Table Grid")
+        if header:
+            cells = table.add_row().cells
+            for i, text in enumerate(header):
+                cells[i].text = str(text)
+                if block.get("header_bold", True):
+                    for para in cells[i].paragraphs:
+                        for run in para.runs:
+                            run.bold = True
+        for row in rows:
+            cells = table.add_row().cells
+            for i, text in enumerate(row):
+                cells[i].text = str(text)
+        _tidy_table(table, has_header=bool(header))
+    elif btype == "image":
+        width = Mm(block["width_mm"]) if block.get("width_mm") else None
+        doc.add_picture(block["path"], width=width)
+    elif btype == "page_break":
+        doc.add_paragraph().add_run().add_break(WD_BREAK.PAGE)
+    elif btype == "toc":
+        from docx_edit import _add_field
+        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.")
+    else:
+        raise ValueError(f"unknown block type: {btype}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="Create a .docx from a JSON spec.",
+        epilog="See the module docstring (top of this file) for the spec format.")
+    ap.add_argument("spec", help="path to JSON spec file")
+    ap.add_argument("output", help="path of .docx to write")
+    args = ap.parse_args()
+
+    with open(args.spec, encoding="utf-8") as f:
+        spec = json.load(f)
+
+    doc = Document()
+    global CJK_INDENT
+    has_cjk = bool(re.search(r"[\u3400-\u9fff]", json.dumps(spec, ensure_ascii=False)))
+    CJK_INDENT = spec.get("first_line_chars", 2 if has_cjk else 0)
+    if has_cjk and spec.get("line_spacing", 1.5):
+        normal = doc.styles["Normal"].paragraph_format
+        normal.line_spacing = spec.get("line_spacing", 1.5)
+    if has_cjk and not (spec.get("page") or {}).get("width_mm"):
+        # python-docx's default template is US Letter; Chinese documents are A4.
+        section = doc.sections[0]
+        section.page_width, section.page_height = Mm(210), Mm(297)
+        for side in ("top", "bottom", "left", "right"):
+            setattr(section, f"{side}_margin", Mm(25))
+    if spec.get("page"):
+        apply_page(doc, spec["page"])
+    if spec.get("styles"):
+        add_styles(doc, spec["styles"])
+    if spec.get("header"):
+        doc.sections[0].header.paragraphs[0].text = spec["header"]
+    if spec.get("footer"):
+        doc.sections[0].footer.paragraphs[0].text = spec["footer"]
+    for block in spec.get("blocks", []):
+        add_block(doc, block)
+    if spec.get("footer_page_numbers"):
+        from docx_edit import _add_field
+        para = doc.sections[0].footer.paragraphs[0]
+        zh = bool(re.search(r"[\u3400-\u9fff]", json.dumps(spec, ensure_ascii=False)))
+        from docx.enum.text import WD_ALIGN_PARAGRAPH
+        para.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        para.add_run("第 " if zh else "Page ")
+        _add_field(para, " PAGE ", "1")
+        para.add_run(" 页 共 " if zh else " of ")
+        _add_field(para, " NUMPAGES ", "1")
+        if zh:
+            para.add_run(" 页")
+    doc.save(args.output)
+    cjk = None
+    if spec.get("cjk_fonts", "auto") and re.search(r"[\u3040-\u30ff\u3400-\u9fff\uac00-\ud7af\uff00-\uffef]",
+                                                 json.dumps(spec, ensure_ascii=False)):
+        from cjk_fonts import process as set_cjk
+        f = spec.get("cjk_fonts") if isinstance(spec.get("cjk_fonts"), dict) else {}
+        cjk = set_cjk(args.output, args.output, f.get("body"), f.get("heading"), f.get("lang", "zh-CN"))
+    print(json.dumps({"ok": True, "output": args.output,
+                      "blocks": len(spec.get("blocks", [])),
+                      "cjk_fonts": cjk and {"body": cjk["body"], "heading": cjk["heading"]}}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/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/skills/docx/scripts/docx_read.py

@@ -0,0 +1,149 @@
+#!/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": [...]}. Body text is the accepted/as-is text (python-docx ignores
+deleted-in-revision text and shows inserted text).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import zipfile
+
+from docx import Document
+
+
+def table_to_rows(table) -> list:
+    return [[cell.text for cell in row.cells] for row in table.rows]
+
+
+def extract_text(doc) -> dict:
+    out = {"body": [p.text 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(p.text for p in section.header.paragraphs)
+        out["footers"].extend(p.text 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": para.text})
+    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": b"<w:ins ", "deletions": b"<w:del ",
+               "format_changes": b"<w:rPrChange"}
+    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"):
+                data = zf.read(name)
+                for key, marker in markers.items():
+                    if marker in data:
+                        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())