dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env python
+"""Attach Word comments to the paragraphs that contain given text.
+
+Each ``--add "needle=comment body"`` anchors a comment over the first paragraph
+whose text contains ``needle``: range start, range end and the reference run are
+inserted inline, and the comment body is appended to comments.xml.  Nothing is
+reworded; the body is exactly the text you pass.
+
+Exit codes: 0 all comments placed, 1 a pattern matched nothing (with
+--require_all nothing is written), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+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
+
+
+def comments_root(doc: kit.Docx):
+    if not doc.exists("word/comments.xml"):
+        root = etree.Element(kit.q("comments"), nsmap={"w": kit.W, "r": kit.R})
+        doc.set_xml("word/comments.xml", root)
+        doc.ensure_override("word/comments.xml", kit.CT_BY_REL[kit.REL_COMMENTS])
+        doc.ensure_rel("word/document.xml", kit.REL_COMMENTS, "comments.xml")
+    return doc.xml("word/comments.xml")
+
+
+def initials(name: str) -> str:
+    parts = [piece for piece in name.replace(".", " ").split() if piece]
+    return "".join(piece[0] for piece in parts)[:3].upper() or "OR"
+
+
+def append_comment(root, text: str, author: str, stamp: str, ident: int) -> None:
+    comment = etree.SubElement(root, kit.q("comment"))
+    comment.set(kit.q("id"), str(ident))
+    comment.set(kit.q("author"), author)
+    comment.set(kit.q("initials"), initials(author))
+    comment.set(kit.q("date"), stamp)
+    paragraph = etree.SubElement(comment, kit.q("p"))
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space", kit.XML), "preserve")
+
+
+def anchor(paragraph, ident: int) -> None:
+    start = etree.Element(kit.q("commentRangeStart"))
+    start.set(kit.q("id"), str(ident))
+    position = 1 if paragraph.find(kit.q("pPr")) is not None else 0
+    paragraph.insert(position, start)
+    end = etree.SubElement(paragraph, kit.q("commentRangeEnd"))
+    end.set(kit.q("id"), str(ident))
+    run = etree.SubElement(paragraph, kit.q("r"))
+    ref = etree.SubElement(run, kit.q("commentReference"))
+    ref.set(kit.q("id"), str(ident))
+
+
+def parse_add(raw: str) -> tuple[str, str]:
+    if "=" not in raw:
+        raise ValueError("--add expects NEEDLE=COMMENT, got %r" % raw)
+    needle, body = raw.split("=", 1)
+    if not needle or not body:
+        raise ValueError("--add needs a non-empty needle and comment")
+    return needle, body
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add Word comments over paragraphs matched by substring.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--author", default="dsh-office", help="Comment author")
+    parser.add_argument("--add", action="append", default=[], help="NEEDLE=COMMENT (repeatable)")
+    parser.add_argument("--ignore_case", action="store_true", help="Match needle case-insensitively")
+    parser.add_argument("--require_all", action="store_true", help="Fail without writing if any needle is absent")
+    parser.add_argument("--date", default=None, help="ISO timestamp for the comments (default: now, UTC)")
+    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
+    if not args.add:
+        parser.error("at least one --add NEEDLE=COMMENT is required")
+
+    paragraphs = doc.paragraphs()
+    requests = []
+    for raw in args.add:
+        try:
+            needle, body = parse_add(raw)
+        except ValueError as exc:
+            print("error: %s" % exc, file=sys.stderr)
+            return 2
+        target = None
+        for paragraph in paragraphs:
+            haystack = kit.paragraph_text(paragraph)
+            if (needle.lower() in haystack.lower()) if args.ignore_case else (needle in haystack):
+                target = paragraph
+                break
+        requests.append({"needle": needle, "body": body, "paragraph": target})
+
+    missing = [item["needle"] for item in requests if item["paragraph"] is None]
+    if missing and args.require_all:
+        kit.emit({"ok": False, "output": None, "matched": 0, "missing": missing})
+        return 1
+
+    stamp = args.date or datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    root = comments_root(doc)
+    ident = doc.next_id()
+    placed = []
+    for item in requests:
+        if item["paragraph"] is None:
+            continue
+        append_comment(root, item["body"], args.author, stamp, ident)
+        anchor(item["paragraph"], ident)
+        placed.append({"id": ident, "needle": item["needle"], "body": item["body"]})
+        ident += 1
+
+    if not placed:
+        kit.emit({"ok": False, "output": None, "matched": 0, "missing": missing})
+        return 1
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "author": args.author, "placed": placed, "missing": missing})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,121 @@
+#!/usr/bin/env python
+"""Edit existing comments in place from a JSON patch file.
+
+The patch is a JSON list (or an object with an ``ops`` list) of operations keyed
+by comment id:
+
+    [{"id": 1, "append": "Also check 2024."},
+     {"id": 2, "replace": "Rewritten note."},
+     {"id": 3, "resolved": true}]
+
+``append`` adds a paragraph, ``replace`` rewrites the body, and ``resolved``
+marks the comment done (the threading metadata Word uses for "Resolve").
+
+Exit codes: 0 all operations applied, 1 some ids were missing, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+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
+
+
+def set_body(comment, text: str) -> None:
+    paragraphs = comment.findall(kit.q("p"))
+    if not paragraphs:
+        paragraph = etree.SubElement(comment, kit.q("p"))
+    else:
+        paragraph = paragraphs[0]
+        for extra in paragraphs[1:]:
+            comment.remove(extra)
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space", kit.XML), "preserve")
+
+
+def append_body(comment, text: str) -> None:
+    paragraph = etree.SubElement(comment, kit.q("p"))
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = text
+    node.set(kit.q("space", kit.XML), "preserve")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Apply append/replace/resolve operations to existing Word comments.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("patch_json", help="JSON patch file")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    args = parser.parse_args(argv)
+
+    try:
+        patch = json.loads(Path(args.patch_json).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print("error: cannot read patch: %s" % exc, file=sys.stderr)
+        return 2
+    ops = patch.get("ops") if isinstance(patch, dict) else patch
+    if not isinstance(ops, list):
+        print("error: patch must be a list or an object with an 'ops' list", file=sys.stderr)
+        return 2
+
+    try:
+        doc = kit.Docx(args.in_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+    if not doc.exists("word/comments.xml"):
+        print("error: document has no comments", file=sys.stderr)
+        return 1
+
+    by_id = {node.get(kit.q("id")): node for node in doc.xml("word/comments.xml").findall(kit.q("comment"))}
+    applied, missing = [], []
+    for op in ops:
+        if not isinstance(op, dict):
+            print("error: each operation must be an object", file=sys.stderr)
+            return 2
+        ident = str(op.get("id"))
+        comment = by_id.get(ident)
+        if comment is None:
+            missing.append(ident)
+            continue
+        changed = []
+        if "replace" in op:
+            set_body(comment, str(op["replace"]))
+            changed.append("replace")
+        if "append" in op:
+            append_body(comment, str(op["append"]))
+            changed.append("append")
+        if "resolved" in op:
+            if op["resolved"]:
+                comment.set(kit.q("done", kit.W15), "1")
+            else:
+                comment.attrib.pop(kit.q("done", kit.W15), None)
+            changed.append("resolved")
+        applied.append({"id": ident, "changes": changed})
+
+    doc.save(args.out)
+    kit.emit({"ok": not missing, "output": str(Path(args.out)), "applied": applied, "missing_ids": missing})
+    return 1 if missing else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+"""Extract Word comments to JSON, including the text each comment is anchored to.
+
+The anchor is recovered by walking the marked-up parts in document order and
+collecting the text between ``commentRangeStart`` and ``commentRangeEnd`` for
+the same id.  Comments whose range was lost still appear, with an empty anchor.
+
+Exit codes: 0 success (an empty list when the file has no comments), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+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
+
+
+def anchor_map(doc: kit.Docx) -> dict[str, dict]:
+    found: dict[str, dict] = {}
+    hf = [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    parts = ["word/document.xml"] + hf + [part for part in doc.text_parts() if part != "word/document.xml"]
+    for part in parts:
+        active = None
+        for node in doc.xml(part).iter():
+            if not isinstance(node.tag, str):
+                continue
+            local = node.tag.split("}", 1)[1] if node.tag.startswith("{%s}" % kit.W) else ""
+            if local == "commentRangeStart":
+                ident = node.get(kit.q("id")) or ""
+                active = ident
+                found.setdefault(ident, {"part": part, "anchored_text": ""})
+            elif local == "commentRangeEnd":
+                if active is not None and (node.get(kit.q("id")) or "") == active:
+                    active = None
+            elif local == "commentReference" and active is None:
+                ident = node.get(kit.q("id")) or ""
+                found.setdefault(ident, {"part": part, "anchored_text": ""})
+            elif active is not None and local in ("t", "delText"):
+                found.setdefault(active, {"part": part, "anchored_text": ""})["anchored_text"] += node.text or ""
+    return found
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Extract comments (author, date, body, anchored text) from a .docx.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Write the JSON report here")
+    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
+    if not doc.exists("word/comments.xml"):
+        kit.emit({"ok": True, "input": str(Path(args.in_docx)), "count": 0, "comments": []}, args.out)
+        return 0
+
+    anchors = anchor_map(doc)
+    comments = []
+    for node in doc.xml("word/comments.xml").findall(kit.q("comment")):
+        ident = node.get(kit.q("id")) or ""
+        paragraphs = [kit.text_of(paragraph) for paragraph in node.iter(kit.q("p"))]
+        info = anchors.get(ident, {})
+        comments.append(
+            {
+                "id": int(ident) if ident.lstrip("-").isdigit() else ident,
+                "author": node.get(kit.q("author")) or "",
+                "initials": node.get(kit.q("initials")) or "",
+                "date": node.get(kit.q("date")) or "",
+                "text": "\n".join(text for text in paragraphs if text),
+                "anchored_text": info.get("anchored_text", "").strip(),
+                "part": info.get("part"),
+                "resolved": node.get(kit.q("done", kit.W15)) in ("1", "true"),
+            }
+        )
+    comments.sort(key=lambda item: item["id"] if isinstance(item["id"], int) else 0)
+    kit.emit({"ok": True, "input": str(Path(args.in_docx)), "count": len(comments), "comments": comments}, args.out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+"""Remove every comment from a .docx: markers, bodies, relationships, part.
+
+Word needs all four removed together.  Leaving a stray ``commentReference``
+behind makes Word report a corrupt package, and leaving comments.xml in the zip
+re-adds metadata you thought you deleted, so each is handled here.
+
+Exit codes: 0 success (also when there was nothing to strip), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+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
+
+MARKERS = ("commentRangeStart", "commentRangeEnd", "commentReference")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Strip all comments and comment markers from a .docx.")
+    parser.add_argument("in_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    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
+
+    hf = [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    removed_markers = 0
+    for part in ["word/document.xml"] + hf + doc.text_parts():
+        if not doc.exists(part):
+            continue
+        root = doc.xml(part)
+        for local in MARKERS:
+            for node in list(root.iter(kit.q(local))):
+                parent = node.getparent()
+                if parent is None:
+                    continue
+                if local == "commentReference" and parent.tag == kit.q("r") and len(parent) <= 1:
+                    grand = parent.getparent()
+                    if grand is not None:
+                        grand.remove(parent)
+                else:
+                    parent.remove(node)
+                removed_markers += 1
+
+    had_part = doc.exists("word/comments.xml")
+    if had_part:
+        doc.drop("word/comments.xml")
+        doc.drop_rel_target("word/document.xml", "word/comments.xml")
+        doc.drop_override("word/comments.xml")
+
+    doc.save(args.out)
+    kit.emit(
+        {
+            "ok": True,
+            "input": str(Path(args.in_docx)),
+            "output": str(Path(args.out)),
+            "comments_part_removed": had_part,
+            "markers_removed": removed_markers,
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,199 @@
+#!/usr/bin/env python
+"""Read or edit Word content controls (structured document tags / SDT).
+
+python-docx has no API for content controls, so this works directly on the
+``w:sdt`` elements: list them, wrap a paragraph into a typed control, or replace
+the text of controls matched by tag.  Tags are the stable key — they survive
+copying between documents better than the numeric ids.
+
+Exit codes: 0 success, 1 a tag was not found, 2 bad input or bad subcommand.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+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
+
+TYPE_TAGS = ("text", "richText", "date", "dropDownList", "comboBox", "picture", "checkbox")
+CONTAINER_TAGS = ("docPartObj", "group", "citation", "bibliography")
+
+
+def part_list(doc: kit.Docx, include_headers: bool) -> list[str]:
+    parts = ["word/document.xml"]
+    if include_headers:
+        parts += [name for name in doc.names("word/header") + doc.names("word/footer") if name.endswith(".xml") and "_rels" not in name]
+    return [part for part in parts if doc.exists(part)]
+
+
+def controls(doc: kit.Docx, part: str):
+    return [node for node in doc.xml(part).iter(kit.q("sdt")) if node.find(kit.q("sdtPr")) is not None]
+
+
+def describe(doc: kit.Docx, part: str, sdt) -> dict:
+    props = sdt.find(kit.q("sdtPr"))
+    tag = props.find(kit.q("tag")) if props is not None else None
+    alias = props.find(kit.q("alias")) if props is not None else None
+    ident = props.find(kit.q("id")) if props is not None else None
+    kind = "unknown"
+    if props is not None:
+        for name in TYPE_TAGS:
+            if props.find(kit.q(name)) is not None:
+                kind = name
+                break
+        if kind == "unknown" and any(props.find(kit.q(name)) is not None for name in CONTAINER_TAGS):
+            kind = "container"
+    content = sdt.find(kit.q("sdtContent"))
+    text = kit.text_of(content) if content is not None else ""
+    return {
+        "part": part,
+        "tag": tag.get(kit.q("val")) if tag is not None else "",
+        "alias": alias.get(kit.q("val")) if alias is not None else "",
+        "id": ident.get(kit.q("val")) if ident is not None else "",
+        "type": kind,
+        "text": text,
+    }
+
+
+def build_control(tag: str, alias: str, text: str, ident: int, content) -> etree._Element:
+    sdt = etree.Element(kit.q("sdt"))
+    props = etree.SubElement(sdt, kit.q("sdtPr"))
+    if tag:
+        etree.SubElement(props, kit.q("tag")).set(kit.q("val"), tag)
+    if alias:
+        etree.SubElement(props, kit.q("alias")).set(kit.q("val"), alias)
+    etree.SubElement(props, kit.q("id")).set(kit.q("val"), str(ident))
+    etree.SubElement(props, kit.q("text"))
+    body = etree.SubElement(sdt, kit.q("sdtContent"))
+    if content is not None:
+        body.append(content)
+    else:
+        paragraph = etree.SubElement(body, kit.q("p"))
+        run = etree.SubElement(paragraph, kit.q("r"))
+        node = etree.SubElement(run, kit.q("t"))
+        node.text = text
+    return sdt
+
+
+def replace_text(sdt, value: str) -> bool:
+    content = sdt.find(kit.q("sdtContent"))
+    if content is None:
+        return False
+    paragraphs = list(content.iter(kit.q("p")))
+    if not paragraphs:
+        return False
+    paragraph = paragraphs[0]
+    for extra in paragraphs[1:]:
+        parent = extra.getparent()
+        if parent is not None:
+            parent.remove(extra)
+    ppr = paragraph.find(kit.q("pPr"))
+    for child in list(paragraph):
+        if child is not ppr:
+            paragraph.remove(child)
+    run = etree.SubElement(paragraph, kit.q("r"))
+    node = etree.SubElement(run, kit.q("t"))
+    node.text = value
+    node.set(kit.q("space"), kit.XML)
+    return True
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="List, create, or fill Word content controls (SDTs).")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    listing = sub.add_parser("list", help="list content controls")
+    listing.add_argument("docx")
+    listing.add_argument("--json", action="store_true", help="emit JSON (always on; kept for scripts)")
+    listing.add_argument("--no_headers_footers", action="store_true")
+
+    create = sub.add_parser("create", help="wrap a paragraph or add a new control")
+    create.add_argument("docx")
+    create.add_argument("--tag", default="", help="Stable tag used by later edits")
+    create.add_argument("--alias", default="", help="Display name shown in Word")
+    create.add_argument("--text", default="", help="Initial value for a new control")
+    create.add_argument("--placeholder", default="", help="Wrap the paragraph containing this text instead of adding a new control")
+    create.add_argument("--output", required=True)
+    create.add_argument("--no_headers_footers", action="store_true")
+
+    update = sub.add_parser("set", help="fill controls by tag")
+    update.add_argument("docx")
+    update.add_argument("--set", action="append", default=[], help="TAG=VALUE (repeatable)")
+    update.add_argument("--output", required=True)
+    update.add_argument("--no_headers_footers", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    if args.command == "list":
+        rows = []
+        for part in part_list(doc, not args.no_headers_footers):
+            for sdt in controls(doc, part):
+                rows.append(describe(doc, part, sdt))
+        kit.emit({"ok": True, "input": str(Path(args.docx)), "count": len(rows), "controls": rows})
+        return 0
+
+    if args.command == "set":
+        if not args.set:
+            parser.error("at least one --set TAG=VALUE is required")
+        wanted = {}
+        for raw in args.set:
+            if "=" not in raw:
+                parser.error("--set expects TAG=VALUE, got %r" % raw)
+            tag, value = raw.split("=", 1)
+            wanted[tag] = value
+        filled, missing = [], []
+        for part in part_list(doc, not args.no_headers_footers):
+            for sdt in controls(doc, part):
+                info = describe(doc, part, sdt)
+                if info["tag"] in wanted and replace_text(sdt, wanted[info["tag"]]):
+                    filled.append({"tag": info["tag"], "value": wanted[info["tag"]], "part": part})
+                    wanted.pop(info["tag"], None)
+        missing = sorted(wanted)
+        doc.save(args.output)
+        kit.emit({"ok": not missing, "output": str(Path(args.output)), "filled": filled, "missing_tags": missing})
+        return 1 if missing else 0
+
+    ident = doc.next_id()
+    if args.placeholder:
+        target = None
+        for paragraph in doc.paragraphs():
+            if args.placeholder in kit.paragraph_text(paragraph):
+                target = paragraph
+                break
+        if target is None:
+            print("error: placeholder %r not found" % args.placeholder, file=sys.stderr)
+            return 1
+        parent = target.getparent()
+        index = list(parent).index(target)
+        sdt = build_control(args.tag, args.alias, args.text, ident, target)
+        parent.insert(index, sdt)
+        where = "wrapped"
+    else:
+        sdt = build_control(args.tag, args.alias, args.text, ident, None)
+        doc.body().append(sdt)
+        where = "appended"
+    doc.save(args.output)
+    kit.emit({"ok": True, "output": str(Path(args.output)), "mode": where, "tag": args.tag, "id": ident})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())