dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-documents/ooxml/tracked_changes.md

@@ -0,0 +1,53 @@
+# Tracked changes
+
+Tracked changes are markup, not a diff. The file contains both the old and the new text, wrapped in elements that say which is which, plus enough metadata for Word to show reviewer names and accept or reject each edit.
+
+## The elements
+
+| Element | Meaning |
+|---|---|
+| `w:ins` | Text inserted (contains runs) |
+| `w:del` | Text deleted (contains runs whose text is `w:delText`) |
+| `w:moveFrom` / `w:moveTo` | Moved text, paired by `w:name` |
+| `w:rPrChange` / `w:pPrChange` | Formatting change, with the previous properties inside |
+| `w:delText` | The deleted characters — not `w:t` |
+| `w:delInstrText` | A deleted field instruction |
+
+Each carries `w:id`, `w:author`, `w:date`. Ids must be unique within the document; reusing one makes Word show the wrong reviewer.
+
+A deletion is a `w:del` containing runs with `w:delText`, not a run with a strikethrough:
+
+```xml
+<w:del w:id="101" w:author="dsh-office" w:date="2026-10-21T00:00:00Z">
+  <w:r><w:delText>Revenue grew</w:delText></w:r>
+</w:del>
+<w:ins w:id="102" w:author="dsh-office" w:date="2026-10-21T00:00:00Z">
+  <w:r><w:t>Revenue climbed</w:t></w:r>
+</w:ins>
+```
+
+## Tracking has to be on
+
+`<w:trackRevisions/>` in `word/settings.xml` makes *Word* track subsequent edits. It does not affect markup already in the file. Write the markup directly when you are generating the change; turn tracking on when the user will continue editing.
+
+## Accepting and rejecting
+
+- **Accept** — keep `w:ins` content and unwrap it; delete `w:del` entirely; for moves keep `w:moveTo`.
+- **Reject** — delete `w:ins` content; keep `w:del` content and convert `w:delText` back to `w:t` (unwrap the `w:del`).
+- Either way, remove the revision containers afterwards; leaving an empty `w:ins` shows a stray marker.
+- Format-change elements have no accept/reject choice in the content sense: accepted means the new properties stay, rejected means the old ones are restored.
+
+## Where tracking hides
+
+- Inside headers, footers, footnotes, endnotes, table cells, text boxes.
+- Table-level changes: `w:trPr/w:ins` for an inserted row, `w:tcPr/w:cellIns` for a cell.
+- Paragraph-level: a paragraph mark inserted or deleted uses `w:rPr/w:ins` in `w:pPr`, so "delete this paragraph" is not a `w:del` around the paragraph.
+- Comments are separate markup; a comment can survive its being accepted.
+
+## Reading markup without a renderer
+
+```bash
+"<python>" "<skill>/scripts/accept_tracked_changes.py" "<file.docx>" --mode report
+```
+
+The report lists insertions and deletions with authors and the text on each side. That is the honest way to answer "what changed" when there is no rendered view, and it is also how you confirm a generated change landed as markup rather than as plain text.

package/assets/skills/office-documents/references/docx-structure.md

@@ -0,0 +1,83 @@
+# DOCX structure reference
+
+## The package
+
+```
+[Content_Types].xml          extensions and per-part overrides
+_rels/.rels                  package relationships (document, core props)
+docProps/core.xml            author, title, subject, keywords, revision
+docProps/app.xml             application, company, manager
+word/document.xml            the body: paragraphs, tables, sections
+word/styles.xml             paragraph/character/table style definitions
+word/numbering.xml           abstract lists and their num instances
+word/settings.xml            protection, tracking, updateFields
+word/theme/theme1.xml        fonts and colour scheme
+word/header1.xml, footer1.xml
+word/media/*                 images
+word/comments.xml, footnotes.xml, endnotes.xml   optional
+```
+
+## The body
+
+`word/document.xml` is a sequence of block-level elements: `w:p` (paragraph), `w:tbl` (table), `w:sdt` (content control), and finally one `w:sectPr` per section (the last one sits in the body, earlier ones inside a paragraph's `pPr`).
+
+A paragraph is:
+
+```xml
+<w:p>
+  <w:pPr>                     <!-- paragraph properties -->
+    <w:pStyle w:val="Heading1"/>
+    <w:spacing w:before="240" w:after="80"/>
+    <w:keepNext/>
+    <w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr>
+    <w:jc w:val="center"/>
+  </w:pPr>
+  <w:r>                       <!-- run -->
+    <w:rPr><w:b/><w:sz w:val="24"/></w:rPr>   <!-- sz is half-points: 24 = 12pt -->
+    <w:t xml:space="preserve">text</w:t>
+  </w:r>
+</w:p>
+```
+
+Everything a reader sees is a run inside a paragraph; everything that makes it look different from its style is direct formatting in `pPr`/`rPr`. Direct formatting is why `style_normalize.py` exists.
+
+A table is `w:tbl` > `w:tblPr` (style, width, layout) + `w:tblGrid` (column widths) + `w:tr` > `w:tc` > `w:p`. A cell always contains at least one paragraph.
+
+## Units
+
+| Unit | Where | Conversion |
+|---|---|---|
+| twip (1/1440 in) | margins, widths, indents, cell widths | 1440 per inch |
+| half-point | `w:sz` | 2 per point |
+| eighth-point | border widths (`w:sz` on borders) | 8 per point |
+| EMU (914400/in) | drawing extents | 914400 per inch |
+
+A Letter page is 12240×15840 twips. Text width = page width − left − right margins (default 9360 twips with 1in margins).
+
+## Styles
+
+`w:style` with `w:type` of `paragraph`, `character`, `table` or `numbering`. Attributes: `w:styleId` (the internal name), `w:name` (the UI name), `w:basedOn`, `w:next`, `w:link`, plus `w:pPr`/`w:rPr`.
+
+- `Normal` is the root; `Heading1`..`Heading9` drive the outline level and the TOC.
+- Outline level can also be set explicitly with `w:outlineLvl` (0-based) in `pPr`; a paragraph can look like a heading without being one, and the TOC will not see it.
+- Latent styles do not exist in the file until used; a document may reference `Heading3` while `styles.xml` has no definition for it.
+
+## Numbering
+
+`word/numbering.xml` holds `w:abstractNum` (the list definition, per level: format, text, indentation) and `w:num` (`w:numId` → `w:abstractNumId`, optionally overridden). A paragraph joins a list with `w:numPr` referencing a `numId`. Two paragraphs with the same `numId` share a counter.
+
+## Sections
+
+`w:sectPr` carries page size (`w:pgSz`), margins (`w:pgMar`), orientation (implied by width vs height, or `w:orient`), columns, and the header/footer references. A document with one section has one `sectPr`; a new section is a paragraph whose `pPr` contains the *previous* section's `sectPr`.
+
+## Fields
+
+Simple (`w:fldSimple`) and complex (`fldChar` begin/separate/end with `w:instrText`). The visible text is a cache. `w:updateFields` in `settings.xml` asks the editor to refresh on open. See `ooxml/hyperlinks_and_fields.md`.
+
+## Revision markup
+
+`w:ins`, `w:del` (with `w:delText`), `w:moveFrom`/`w:moveTo`, `w:rPrChange`/`w:pPrChange`, each with author and date. See `ooxml/tracked_changes.md`.
+
+## Minimum valid package
+
+`[Content_Types].xml`, `_rels/.rels`, `word/document.xml`, `word/_rels/document.xml.rels`. Word accepts a document without styles or settings; most libraries add them. When hand-building, write `[Content_Types].xml` first in the zip.

package/assets/skills/office-documents/references/template-elicitation.md

@@ -0,0 +1,49 @@
+# Eliciting a template
+
+A user who says "use our house style" has a file somewhere. Getting it is worth one question; guessing produces a document that has to be redone.
+
+## Ask for the artefact, not the description
+
+Description ("blue headings, maybe 11pt") produces a different document every time. The artefact (`house-template.dotx`, an old `.docx` of the same kind, a PDF of the last report) carries the actual styles, margins and fonts.
+
+One sentence is enough:
+
+> Is there an existing document in this style I should match? Send the file (`.dotx`, or any `.docx` in that style) and I will follow it exactly.
+
+If they have no file, ask for two or three specifics that cannot be guessed and choose the rest from `SKILL.md` defaults:
+
+- page size and margins, if their organisation is not US Letter,
+- the heading/body typeface and sizes,
+- anything required by policy (logo in the header, classification mark in the footer).
+
+## Read the template before using it
+
+```bash
+"<python>" "<cli>" docx read --input "<template.docx>"
+"<python>" "<skill>/scripts/docx_kit.py" xml '<template.docx>' word/styles.xml
+"<python>" "<skill>/scripts/section_audit.py" "<template.docx>"
+```
+
+From `styles.xml`, note the `styleId` of what will be used: `Heading1`..`Heading3`, `Title`, `Caption`, `Quote`, `ListParagraph`. From the section audit, record page size, margins, header/footer text and whether the first page is different.
+
+## Apply it
+
+```bash
+"<python>" "<skill>/scripts/apply_template_styles.py" --template "<template.docx>" --target "<draft.docx>" --out "<styled.docx>"
+```
+
+This merges style definitions (and numbering) by id — the body content is untouched, so anything written with direct formatting keeps it. Follow with:
+
+```bash
+"<python>" "<skill>/scripts/style_normalize.py" "<styled.docx>" --out "<styled-final.docx>" --clear_paragraph_format --enforce_heading_spacing
+```
+
+Now the text picks up the template's look instead of the draft's.
+
+## When the template is a PDF or an image
+
+Extract structure, not styles: heading hierarchy, section order, table layout, caption convention, margin proportions. Then reproduce them with named styles in a generated document. Say which parts were matched approximately — a PDF does not tell you the font size of a heading, only how it looks.
+
+## When there is no template and no details
+
+Fall back to the defaults in `SKILL.md` (Letter, 1in margins, 11–12pt body, black headings, `#D9D9D9` table borders) and state the assumption in one line with the delivered file. Do not stall on a question the user may not care about.

package/assets/skills/office-documents/references/writing-quality.md

@@ -0,0 +1,49 @@
+# Writing quality
+
+Content quality is the part of a document the format cannot fix. These are the rules to apply while drafting, before any rendering.
+
+## Structure before prose
+
+- Every heading states a claim the reader can disagree with ("Services carried the quarter", not "Services"). A heading that only names a topic is a missed opportunity to be clear.
+- A section that cannot be summarised in one sentence is two sections.
+- Three levels of heading is the practical maximum; a fourth usually means the content should be a table or an appendix.
+- Nothing between a heading and its first paragraph. No label line, no restated title.
+
+## Paragraphs
+
+- One idea per paragraph, first sentence carries it.
+- 3–6 sentences is the comfortable range; a 1600-word paragraph is a formatting defect even if the prose is good.
+- No em-dash pile-ups, no "furthermore/moreover" chains, no sentence that only announces the next sentence.
+- The last paragraph of a section says what it meant, not that it is finished.
+
+## Lists and tables
+
+- Bullets for parallel items of equal weight; never for a sequence (that is a numbered list).
+- If items have two attributes, a table beats a bulleted list with parentheticals.
+- Table headers are nouns, units in the header ("Revenue ($m)"), numbers right-aligned.
+- Every table earns its caption; a table without a purpose is a screenshot of data.
+
+## Voice
+
+- Active unless the actor is unknown or unimportant; "We found", not "It was found".
+- Present tense for findings, past for actions taken.
+- No unsupported superlatives. "18% growth" beats "strong growth"; if a number is unknown, say so rather than adding an adverb.
+- Define an acronym once, then use it. Never define it twice in different places.
+
+## Numbers
+
+- Consistent precision. Do not mix "12.4%" and "8%" in one table unless the source did.
+- Percentages below 1 take a leading zero (0.4%, not .4%).
+- State the period and the currency in the table or its caption, not in the surrounding prose.
+- A number in prose must match the number in the table; rendering does not catch this, re-reading does.
+
+## What to cut
+
+- Opening paragraphs that explain that the document will explain something.
+- Closing paragraphs that thank the reader.
+- Bold on every second phrase: emphasis used everywhere is emphasis used nowhere.
+- Sentences that begin "It is important to note that".
+
+## Where this connects
+
+`references/docx-structure.md` covers how the structure is expressed in Word — styles, captions, table layout. `tasks/verify_render.md` covers checking the result on a page. Neither replaces reading the text once with the question "would a busy reader get the point from the headings alone?"

package/assets/skills/office-documents/render_docx.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python
+"""Render a .docx to page images through the helper CLI's render verb.
+
+Rendering is the only honest check that a document looks right: XML can be valid
+and still overlap, clip or reflow badly.  This script keeps the plumbing in one
+place so tasks can say "render it, look at the images" and mean a single command.
+
+The render verb needs a real Word engine (Microsoft Word, WPS Writer, or
+LibreOffice).  When none is installed the script reports exactly that and exits 3,
+because a placeholder image would be worse than no image.
+
+Exit codes: 0 rendered, 1 render failed, 3 no renderer installed, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "scripts"))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def resize(path: Path, width: int | None, height: int | None) -> None:
+    try:
+        from PIL import Image
+    except ImportError:
+        return
+    if not (width or height):
+        return
+    with Image.open(path) as image:
+        size = (width or image.width, height or image.height)
+        image.resize(size).save(path)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Render a .docx to PNG page images (and optionally keep the PDF).")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--output_dir", default=None, help="Directory for page images (default: next to the input)")
+    parser.add_argument("--dpi", type=int, default=150)
+    parser.add_argument("--width", type=int, default=None, help="Resize page images to this width")
+    parser.add_argument("--height", type=int, default=None, help="Resize page images to this height")
+    parser.add_argument("--emit_pdf", action="store_true", help="Keep the intermediate PDF and report its path")
+    parser.add_argument("--verbose", action="store_true", help="Include the CLI's raw output")
+    args = parser.parse_args(argv)
+
+    source = Path(args.input_docx).expanduser().resolve()
+    if not source.is_file():
+        print("error: %s not found" % source, file=sys.stderr)
+        return 2
+    out_dir = Path(args.output_dir).expanduser().resolve() if args.output_dir else source.parent / (source.stem + "-render")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    command = ["docx", "render", "--input", str(source), "--out-dir", str(out_dir)]
+    if args.dpi:
+        command += ["--dpi", str(args.dpi)]
+    code, stdout, stderr = kit.run_office_cli(command)
+    payload = kit.cli_json(stdout) or kit.cli_json(stderr) or {}
+    pages = payload.get("pages") or []
+
+    if code != 0 or not pages:
+        detail = payload.get("error") or payload.get("reason") or ""
+        if not detail:
+            lines = [line for line in (stderr or stdout or "").splitlines() if line.strip() not in ("", "{", "}")]
+            detail = lines[-1].strip() if lines else "render failed"
+        if "renderer" in detail.lower() or "libreoffice" in detail.lower():
+            kit.emit({"ok": False, "reason": "no_renderer", "detail": detail, "remedy": "Install Microsoft Office, WPS Office, or LibreOffice, then re-run this command."})
+            return 3
+        kit.emit({"ok": False, "reason": "render_failed", "detail": detail})
+        return 1
+
+    for page in pages:
+        resize(Path(page), args.width, args.height)
+
+    result = {
+        "ok": True,
+        "input": str(source),
+        "pages": pages,
+        "page_count": len(pages),
+        "renderer": payload.get("renderer"),
+    }
+    if args.emit_pdf and payload.get("pdf"):
+        result["pdf"] = payload["pdf"]
+    if args.verbose:
+        result["stdout"] = stdout.strip()
+    kit.emit(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/a11y_audit.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python
+"""Accessibility audit for a .docx, with two safe repair switches.
+
+Checks images for missing alternative text, tables for a repeating header row,
+heading runs for skipped levels, links for vague link text, and the package for
+a document title.  Repairs are opt-in and never guess at meaning: alt text is
+derived from the image file name and table headers come from the first row.
+
+Exit codes: 0 clean (or all findings repaired), 1 findings remain, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import posixpath
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+GENERIC_LINK_TEXT = {"click here", "here", "link", "this link", "read more"}
+DETAIL_PARTS = ("word/document.xml", "word/header1.xml", "word/footer1.xml")
+
+
+def header_footer_parts(doc: kit.Docx) -> list[str]:
+    names = doc.names("word/header") + doc.names("word/footer")
+    return [name for name in names if name.endswith(".xml") and "_rels" not in name]
+
+
+def scan_images(doc: kit.Docx) -> list[dict]:
+    findings = []
+    for part in ["word/document.xml"] + header_footer_parts(doc):
+        if not doc.exists(part):
+            continue
+        rels = {rel["id"]: rel for rel in doc.relationships(part)}
+        for docpr in doc.xml(part).iter(kit.q("docPr", kit.WP)):
+            blip = docpr.getparent().find(".//" + kit.q("blip", kit.A))
+            rid = blip.get(kit.q("embed", kit.R)) if blip is not None else None
+            target = rels.get(rid, {}).get("resolved", "")
+            alt = (docpr.get("descr") or docpr.get("title") or "").strip()
+            findings.append(
+                {
+                    "code": "image_missing_alt",
+                    "part": part,
+                    "name": docpr.get("name"),
+                    "target": target,
+                    "ok": bool(alt),
+                }
+            )
+    return findings
+
+
+def scan_tables(doc: kit.Docx) -> list[dict]:
+    findings = []
+    for index, table in enumerate(doc.xml("word/document.xml").iter(kit.q("tbl"))):
+        rows = table.findall(kit.q("tr"))
+        if not rows:
+            continue
+        props = rows[0].find(kit.q("trPr"))
+        repeat = props is not None and props.find(kit.q("tblHeader")) is not None
+        findings.append(
+            {
+                "code": "table_missing_header_row",
+                "table_index": index,
+                "rows": len(rows),
+                "ok": repeat,
+                "style": (table.find(kit.q("tblPr")).find(kit.q("tblStyle")).get(kit.q("val")) if table.find(kit.q("tblPr")) is not None and table.find(kit.q("tblPr")).find(kit.q("tblStyle")) is not None else ""),
+            }
+        )
+    return findings
+
+
+def scan_headings(doc: kit.Docx) -> list[dict]:
+    findings = []
+    previous = 0
+    for index, paragraph in enumerate(doc.paragraphs()):
+        level = kit.heading_level(paragraph)
+        if not level:
+            continue
+        text = kit.paragraph_text(paragraph).strip()
+        if previous and level > previous + 1:
+            findings.append({"code": "heading_level_jump", "paragraph": index, "from": previous, "to": level, "text": text, "ok": False})
+        if not text:
+            findings.append({"code": "empty_heading", "paragraph": index, "level": level, "ok": False})
+        previous = level
+    return findings
+
+
+def scan_links(doc: kit.Docx) -> list[dict]:
+    findings = []
+    for part in ["word/document.xml"] + header_footer_parts(doc):
+        if not doc.exists(part):
+            continue
+        for link in doc.xml(part).iter(kit.q("hyperlink")):
+            text = kit.text_of(link).strip().lower()
+            if not text:
+                findings.append({"code": "empty_link", "part": part, "ok": False})
+            elif text in GENERIC_LINK_TEXT:
+                findings.append({"code": "vague_link_text", "part": part, "text": text, "ok": False})
+    return findings
+
+
+def scan_title(doc: kit.Docx) -> list[dict]:
+    if not doc.exists("docProps/core.xml"):
+        return [{"code": "missing_document_title", "ok": False}]
+    core = doc.xml("docProps/core.xml")
+    title = core.find("{http://purl.org/dc/elements/1.1/}title")
+    text = (title.text or "").strip() if title is not None else ""
+    return [{"code": "missing_document_title", "ok": bool(text)}] if not text else []
+
+
+def fix_alt_text(doc: kit.Docx) -> int:
+    changed = 0
+    for part in ["word/document.xml"] + header_footer_parts(doc):
+        if not doc.exists(part):
+            continue
+        rels = {rel["id"]: rel for rel in doc.relationships(part)}
+        for docpr in doc.xml(part).iter(kit.q("docPr", kit.WP)):
+            if (docpr.get("descr") or "").strip():
+                continue
+            blip = docpr.getparent().find(".//" + kit.q("blip", kit.A))
+            rid = blip.get(kit.q("embed", kit.R)) if blip is not None else None
+            target = rels.get(rid, {}).get("resolved", "")
+            stem = posixpath.splitext(posixpath.basename(target))[0]
+            label = (stem or docpr.get("name") or "image").replace("_", " ").replace("-", " ").strip()
+            docpr.set("descr", label.title() or "Image")
+            changed += 1
+    return changed
+
+
+def fix_table_headers(doc: kit.Docx) -> int:
+    changed = 0
+    for table in doc.xml("word/document.xml").iter(kit.q("tbl")):
+        rows = table.findall(kit.q("tr"))
+        if not rows:
+            continue
+        props = rows[0].find(kit.q("trPr"))
+        if props is None:
+            props = rows[0].makeelement(kit.q("trPr"), {})
+            rows[0].insert(0, props)
+        if props.find(kit.q("tblHeader")) is None:
+            props.append(props.makeelement(kit.q("tblHeader"), {}))
+            changed += 1
+    return changed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Audit a .docx for accessibility blockers, optionally repairing the two safe cases.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--fix_image_alt", choices=["from_filename"], help="Derive missing alt text from the image file name")
+    parser.add_argument("--fix_table_headers", choices=["first_row"], help="Mark the first row as a repeating header")
+    parser.add_argument("--out", help="Write the repaired .docx here (required with any --fix)")
+    parser.add_argument("--out_json", help="Write the full report JSON here instead of stdout")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.in_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    findings = scan_images(doc) + scan_tables(doc) + scan_headings(doc) + scan_links(doc) + scan_title(doc)
+    issues = [item for item in findings if not item["ok"]]
+
+    repairs = {}
+    if args.fix_image_alt or args.fix_table_headers:
+        if not args.out:
+            parser.error("--out is required when applying fixes")
+    if args.fix_image_alt:
+        repairs["image_alt"] = fix_alt_text(doc)
+    if args.fix_table_headers:
+        repairs["table_headers"] = fix_table_headers(doc)
+    if repairs and args.out:
+        doc.save(args.out)
+        issues = [item for item in (scan_images(doc) + scan_tables(doc) + scan_headings(doc) + scan_links(doc) + scan_title(doc)) if not item["ok"]]
+
+    counts: dict[str, int] = {}
+    for item in issues:
+        counts[item["code"]] = counts.get(item["code"], 0) + 1
+    report = {
+        "ok": not issues,
+        "input": str(Path(args.in_docx)),
+        "output": str(Path(args.out)) if args.out and repairs else None,
+        "repairs": repairs,
+        "counts": counts,
+        "findings": issues,
+    }
+    kit.emit(report, args.out_json)
+    return 1 if issues else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())