dsh-office-kit 0.2.0 → 0.3.0

package/assets/skills/office-presentations/template_following_scripts/make_contact_sheet.py

@@ -0,0 +1,111 @@
+"""Tile slide previews into one image so the whole deck can be judged at once.
+
+Purpose: reading ten previews one by one costs ten looks and hides pace,
+repetition and colour drift between slides. One contact sheet shows whether the
+deck has a rhythm: which slides are dense, which are empty, whether the cover
+carries the same accent as the close.
+
+Exit codes: 0 sheet written, 2 nothing readable.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+
+def _natural_key(path: Path) -> list:
+    import re
+
+    return [int(part) if part.isdigit() else part.lower() for part in re.split(r"(\d+)", path.stem)]
+
+
+def build_sheet(images: list[Path], out_path: Path, columns: int = 3, label_height: int = 48, padding: int = 18) -> dict:
+    from PIL import Image, ImageDraw
+
+    columns = max(1, columns)
+    rows = max(1, math.ceil(len(images) / columns))
+    thumbs = []
+    cell_w = 0
+    cell_h = 0
+    for path in images:
+        try:
+            with Image.open(path) as opened:
+                thumb = opened.convert("RGB")
+                thumbs.append((path, thumb.copy(), None))
+                cell_w = max(cell_w, thumb.width)
+                cell_h = max(cell_h, thumb.height)
+        except Exception as exc:  # noqa: BLE001 - unreadable previews become placeholder cells
+            thumbs.append((path, None, str(exc)))
+    if not cell_w or not cell_h:
+        return {"ok": False, "error": {"code": "no_readable_images", "message": "none of the inputs could be opened"}}
+
+    width = columns * cell_w + (columns + 1) * padding
+    height = rows * (cell_h + label_height) + (rows + 1) * padding
+    sheet = Image.new("RGB", (width, height), (246, 246, 246))
+    draw = ImageDraw.Draw(sheet)
+
+    for index, (path, thumb, error) in enumerate(thumbs):
+        row, column = divmod(index, columns)
+        x = padding + column * (cell_w + padding)
+        y = padding + row * (cell_h + label_height + padding)
+        if thumb is None:
+            draw.rectangle([x, y, x + cell_w, y + cell_h], fill=(232, 232, 232), outline=(180, 60, 60), width=3)
+            draw.line([x, y, x + cell_w, y + cell_h], fill=(180, 60, 60), width=3)
+            draw.line([x + cell_w, y, x, y + cell_h], fill=(180, 60, 60), width=3)
+        else:
+            sheet.paste(thumb, (x, y))
+            draw.rectangle([x, y, x + cell_w, y + cell_h], outline=(190, 190, 190), width=1)
+        draw.text((x + 4, y + cell_h + 8), path.stem, fill=(40, 40, 40))
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(out_path)
+    return {
+        "ok": True,
+        "output": str(out_path.resolve()),
+        "cells": len(thumbs),
+        "grid": {"columns": columns, "rows": rows},
+        "size": [width, height],
+        "unreadable": [path.name for path, thumb, _ in thumbs if thumb is None],
+    }
+
+
+def _collect(args) -> list[Path]:
+    found: list[Path] = []
+    for value in [*args.images, *([args.dir] if args.dir else [])]:
+        path = Path(value)
+        if path.is_dir():
+            found.extend(sorted((item for item in path.iterdir() if item.suffix.lower() in {".png", ".jpg", ".jpeg", ".webp"}), key=_natural_key))
+        else:
+            found.append(path)
+    return found
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Build one contact sheet from slide previews.")
+    parser.add_argument("images", nargs="*", help="preview images and/or directories of them")
+    parser.add_argument("--dir", help="a directory of preview images to include (same as passing it positionally)")
+    parser.add_argument("--out", required=True, help="path of the contact sheet to write")
+    parser.add_argument("--columns", type=int, default=3, help="grid width (default 3)")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+    if not args.images and not args.dir:
+        parser.error("give at least one image, one directory, or --dir")
+
+    images = _collect(args)
+    report = build_sheet(images, Path(args.out), args.columns) if images else {"ok": False, "error": {"code": "no_images", "message": "no preview images found"}}
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report.get("ok") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-presentations/template_following_scripts/prepare_template_starter_deck.py

@@ -0,0 +1,239 @@
+"""Build a starter deck out of the slides the plan keeps.
+
+Purpose: the safe way to follow a supplied design is to keep its actual slides,
+not to redraw a lookalike. This copies the template file, keeps the mapped
+source slides in plan order, drops the rest, then applies the element actions
+that only move text: keep, delete, fill-placeholder, rewrite and
+rewrite-and-reposition.
+
+Ceiling: slides are reused, not cloned. Two output slides may not map to the
+same source slide, and 'replace' is left to the author (build the new element
+with a recipe, then run check_template_fidelity). Charts are never rebuilt here.
+
+Exit codes: 0 starter written, 1 plan rejected, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+from ooxml_helpers import box, placeholder_kind, slide_size_in  # noqa: E402
+
+PLACEHOLDER_ALIASES = {
+    "title": ("TITLE", "CENTER_TITLE"),
+    "subtitle": ("SUBTITLE",),
+    "body": ("BODY", "OBJECT"),
+}
+
+
+def _slides(prs) -> list:
+    return list(prs.slides)
+
+
+def _drop_slide(prs, slide) -> None:
+    slide_id = None
+    for element in prs.slides._sldIdLst:
+        if element.rId == slide.part.relate_to(slide.part, "") if False else False:
+            break
+    # find the sldId whose relationship points at this slide part
+    rels = prs.part.rels
+    rId = None
+    for key, relationship in rels.items():
+        if relationship.reltype.endswith("/slide") and relationship.target_part is slide.part:
+            rId = key
+            break
+    if rId is None:
+        return
+    for element in list(prs.slides._sldIdLst):
+        if element.rId == rId:
+            slide_id = element
+            break
+    if slide_id is not None:
+        prs.slides._sldIdLst.remove(slide_id)
+    prs.part.drop_rel(rId)
+
+
+def _keep_only(prs, wanted: list[int]) -> None:
+    ordered = [element for element in prs.slides._sldIdLst]
+    keep_rids = []
+    for position in wanted:
+        keep_rids.append(ordered[position - 1].rId)
+    for slide in list(prs.slides):
+        current = None
+        for key, relationship in prs.part.rels.items():
+            if relationship.reltype.endswith("/slide") and relationship.target_part is slide.part:
+                current = key
+                break
+        if current not in keep_rids:
+            _drop_slide(prs, slide)
+    # reorder what survived to match the plan
+    by_rid = {element.rId: element for element in prs.slides._sldIdLst}
+    for element in list(prs.slides._sldIdLst):
+        prs.slides._sldIdLst.remove(element)
+    for rId in keep_rids:
+        prs.slides._sldIdLst.append(by_rid[rId])
+
+
+def _find_shape(slide, element_id: str):
+    shapes = list(slide.shapes)
+    if element_id.isdigit():
+        index = int(element_id) - 1
+        return shapes[index] if 0 <= index < len(shapes) else None
+    for shape in shapes:
+        if shape.name == element_id:
+            return shape
+    if element_id.lower().startswith("shape-") and element_id[6:].isdigit():
+        index = int(element_id[6:]) - 1
+        return shapes[index] if 0 <= index < len(shapes) else None
+    return None
+
+
+def _find_placeholder(slide, alias: str):
+    wanted = PLACEHOLDER_ALIASES.get(alias.lower())
+    for shape in slide.shapes:
+        if not shape.is_placeholder:
+            continue
+        kind = (placeholder_kind(shape) or "").upper()
+        if alias.isdigit() and shape.placeholder_format.idx == int(alias):
+            return shape
+        if wanted and kind in wanted:
+            return shape
+        if alias.lower() == (placeholder_kind(shape) or "").lower():
+            return shape
+    return None
+
+
+def _set_text(shape, text: str) -> None:
+    frame = shape.text_frame
+    paragraphs = list(frame.paragraphs)
+    first = paragraphs[0]
+    runs = list(first.runs)
+    if runs:
+        runs[0].text = text
+        for run in runs[1:]:
+            run._r.getparent().remove(run._r)
+        for paragraph in paragraphs[1:]:
+            paragraph._p.getparent().remove(paragraph._p)
+    else:
+        frame.text = text
+
+
+def build_starter(template_path: str | Path, plan_path: str | Path, out_path: str | Path) -> dict:
+    from pptx import Presentation
+
+    template = Path(template_path)
+    plan_file = Path(plan_path)
+    if not template.is_file():
+        return {"ok": False, "error": {"code": "template_missing", "message": str(template)}}
+    if not plan_file.is_file():
+        return {"ok": False, "error": {"code": "plan_missing", "message": str(plan_file)}}
+
+    plan = json.loads(plan_file.read_text(encoding="utf-8"))
+    entries = plan.get("outputSlides") or []
+    if not entries:
+        return {"ok": False, "error": {"code": "plan_empty", "message": "outputSlides is empty"}}
+
+    sources = [int(entry.get("sourceSlide", 0)) for entry in entries]
+    duplicates = sorted({value for value in sources if sources.count(value) > 1})
+    if duplicates:
+        return {
+            "ok": False,
+            "error": {
+                "code": "duplicate_source_slide",
+                "message": f"source slides {duplicates} are mapped more than once; this builder reuses slides instead of cloning them",
+            },
+        }
+
+    prs = Presentation(str(template))
+    total = len(prs.slides)
+    out_of_range = [value for value in sources if not 1 <= value <= total]
+    if out_of_range:
+        return {"ok": False, "error": {"code": "source_out_of_range", "message": f"template has {total} slides, plan asks for {out_of_range}"}}
+
+    slide_w, slide_h = slide_size_in(prs)
+    _keep_only(prs, sources)
+    kept = _slides(prs)
+
+    applied: list[dict] = []
+    for position, entry in enumerate(entries):
+        slide = kept[position]
+        for element in entry.get("elements", []):
+            element_id = str(element.get("elementId", ""))
+            action = str(element.get("action", "keep"))
+            target = element.get("target") or {}
+            if action == "keep":
+                continue
+            if action == "fill-placeholder":
+                alias = str(target.get("placeholder") or "")
+                shape = _find_placeholder(slide, alias) if alias else _find_shape(slide, element_id)
+                if shape is None:
+                    applied.append({"slide": position + 1, "element": element_id, "action": action, "status": "not_found"})
+                    continue
+                if target.get("text") is not None:
+                    _set_text(shape, str(target["text"]))
+                applied.append({"slide": position + 1, "element": shape.name, "action": action, "status": "applied"})
+                continue
+            shape = _find_shape(slide, element_id)
+            if shape is None:
+                applied.append({"slide": position + 1, "element": element_id, "action": action, "status": "not_found"})
+                continue
+            if action == "delete":
+                shape._element.getparent().remove(shape._element)
+                applied.append({"slide": position + 1, "element": element_id, "action": action, "status": "applied"})
+                continue
+            if action in {"rewrite", "rewrite-and-reposition"}:
+                _set_text(shape, str(target.get("text", "")))
+                if action == "rewrite-and-reposition" and isinstance(target.get("zone"), list):
+                    x, y, width, height = (float(value) for value in target["zone"])
+                    shape.left = int(x * slide_w * 914400)
+                    shape.top = int(y * slide_h * 914400)
+                    shape.width = int(width * slide_w * 914400)
+                    shape.height = int(height * slide_h * 914400)
+                applied.append({"slide": position + 1, "element": element_id, "action": action, "status": "applied"})
+                continue
+            applied.append({"slide": position + 1, "element": element_id, "action": action, "status": "left_for_author"})
+
+    destination = Path(out_path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    prs.save(str(destination))
+
+    leftovers = []
+    for index, slide in enumerate(kept, start=1):
+        for shape in slide.shapes:
+            if shape.is_placeholder and not (shape.text_frame.text or "").strip():
+                leftovers.append({"slide": index, "placeholder": shape.name, "bboxIn": [round(value, 2) for value in (box(shape) or (0, 0, 0, 0))]})
+
+    return {
+        "ok": True,
+        "starter": str(destination.resolve()),
+        "slides": len(kept),
+        "sourceSlides": sources,
+        "applied": applied,
+        "emptyPlaceholders": leftovers,
+        "note": "empty placeholders still show their prompt in edit view; fill or delete them before delivery",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Build a starter deck from the template slides a plan keeps.")
+    parser.add_argument("--template", required=True, help="path to the template .pptx")
+    parser.add_argument("--plan", required=True, help="path to template-frame-map.json")
+    parser.add_argument("--out", required=True, help="path of the starter .pptx to write")
+    args = parser.parse_args(argv)
+
+    report = build_starter(args.template, args.plan, args.out)
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    if report.get("ok"):
+        return 0
+    return 2 if report["error"]["code"] in {"template_missing", "plan_missing"} else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-presentations/template_following_scripts/validate_template_plan.py

@@ -0,0 +1,185 @@
+"""Check a template plan before any slide is touched.
+
+Purpose: a template plan is a contract between "what the design gives you" and
+"what you intend to write". Validating it first turns a silent redesign into a
+list of violations, because the expensive mistakes (deleting a logo, inventing
+new blocks the brand never had, covering inherited art) are all visible on
+paper before anything is built.
+
+Plan shape (template-frame-map.json):
+  {
+    "template": "path/to/template.pptx",
+    "newPrimitives": {"allowed": false, "justification": ""},
+    "outputSlides": [
+      {"slide": 1, "mode": "duplicate-slide", "sourceSlide": 3,
+       "elements": [{"elementId": "shape-7", "action": "fill-placeholder",
+                     "target": {"placeholder": "title", "text": "Q3 results"}}]}
+    ]
+  }
+
+Exit codes: 0 valid, 1 violations, 2 unreadable plan.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+ALLOWED_ACTIONS = {"rewrite", "rewrite-and-reposition", "replace", "delete", "keep", "fill-placeholder"}
+PRESERVE_ONLY_ROLES = {"brand", "logo", "bumper", "divider", "section", "chrome", "footer"}
+MODES = {"duplicate-slide"}
+
+
+def _violation(code: str, message: str, severity: str = "fail", **extra) -> dict:
+    return {"code": code, "severity": severity, "message": message, **extra}
+
+
+def validate_plan(plan: dict) -> dict:
+    violations: list[dict] = []
+    warnings: list[dict] = []
+
+    output_slides = plan.get("outputSlides")
+    if not isinstance(output_slides, list) or not output_slides:
+        return {"gate": "template-plan", "passed": False, "violations": [_violation("missing_output_slides", "the plan declares no output slides")], "checks": 0}
+
+    indices = []
+    sources: dict[int, int] = {}
+    element_actions = 0
+    for position, entry in enumerate(output_slides, start=1):
+        if not isinstance(entry, dict):
+            violations.append(_violation("malformed_slide", f"output slide #{position} is not an object"))
+            continue
+        slide_no = entry.get("slide", position)
+        indices.append(slide_no)
+        mode = entry.get("mode", "duplicate-slide")
+        if mode not in MODES:
+            violations.append(_violation("unsupported_mode", f"slide {slide_no}: mode '{mode}' is not supported", slide=slide_no))
+        source = entry.get("sourceSlide")
+        if not isinstance(source, int) or source < 1:
+            violations.append(_violation("missing_source_slide", f"slide {slide_no}: sourceSlide must be a positive integer", slide=slide_no))
+        else:
+            if source in sources:
+                warnings.append(
+                    _violation(
+                        "duplicated_source_slide",
+                        f"slides {sources[source]} and {slide_no} both duplicate source slide {source}",
+                        severity="review",
+                        slide=slide_no,
+                    )
+                )
+            sources[source] = slide_no
+        elements = entry.get("elements", [])
+        if not isinstance(elements, list):
+            violations.append(_violation("malformed_elements", f"slide {slide_no}: elements must be a list", slide=slide_no))
+            continue
+        for element in elements:
+            if not isinstance(element, dict) or not element.get("elementId"):
+                violations.append(_violation("missing_element_id", f"slide {slide_no}: an element has no elementId", slide=slide_no))
+                continue
+            element_actions += 1
+            element_id = element["elementId"]
+            action = element.get("action")
+            target = element.get("target") or {}
+            if action not in ALLOWED_ACTIONS:
+                violations.append(
+                    _violation(
+                        "unknown_action",
+                        f"slide {slide_no} element {element_id}: '{action}' is not one of {sorted(ALLOWED_ACTIONS)}",
+                        slide=slide_no,
+                        elementId=element_id,
+                    )
+                )
+                continue
+            role = str(target.get("role") or element.get("role") or "").lower()
+            if role in PRESERVE_ONLY_ROLES and action != "keep":
+                violations.append(
+                    _violation(
+                        "preserve_only_element",
+                        f"slide {slide_no} element {element_id}: role '{role}' must stay untouched, found '{action}'",
+                        slide=slide_no,
+                        elementId=element_id,
+                    )
+                )
+            if action == "fill-placeholder" and not (target.get("placeholder") or target.get("text")):
+                violations.append(
+                    _violation("placeholder_target_missing", f"slide {slide_no} element {element_id}: fill-placeholder needs a placeholder or text target", slide=slide_no, elementId=element_id)
+                )
+            if action in {"rewrite", "rewrite-and-reposition"} and not target.get("text"):
+                violations.append(
+                    _violation("rewrite_text_missing", f"slide {slide_no} element {element_id}: {action} needs target.text", slide=slide_no, elementId=element_id)
+                )
+            if action == "rewrite-and-reposition":
+                zone = target.get("zone")
+                if not (isinstance(zone, list) and len(zone) == 4 and all(isinstance(value, (int, float)) for value in zone)):
+                    violations.append(
+                        _violation("zone_missing", f"slide {slide_no} element {element_id}: rewrite-and-reposition needs a zone [x, y, w, h]", slide=slide_no, elementId=element_id)
+                    )
+                else:
+                    x, y, width, height = zone
+                    if not all(0.0 <= value <= 1.0 for value in zone) or x + width > 1.0001 or y + height > 1.0001:
+                        violations.append(
+                            _violation("zone_out_of_bounds", f"slide {slide_no} element {element_id}: zone {zone} does not fit inside 0-1", slide=slide_no, elementId=element_id)
+                        )
+            if action == "replace":
+                warnings.append(
+                    _violation(
+                        "replace_needs_authoring",
+                        f"slide {slide_no} element {element_id}: 'replace' is applied by the author with a recipe, not by the starter-deck builder",
+                        severity="review",
+                        slide=slide_no,
+                        elementId=element_id,
+                    )
+                )
+
+    if indices != list(range(1, len(output_slides) + 1)):
+        violations.append(_violation("non_sequential_slides", f"output slide numbers must start at 1 and be sequential, found {indices}"))
+
+    primitives = plan.get("newPrimitives") or {}
+    if primitives.get("allowed") is True and not str(primitives.get("justification") or "").strip():
+        violations.append(_violation("new_primitives_unjustified", "newPrimitives.allowed is true but no justification was given"))
+
+    blocking = [item for item in violations if item["severity"] == "fail"]
+    return {
+        "gate": "template-plan",
+        "passed": not blocking,
+        "checks": {"outputSlides": len(output_slides), "elementActions": element_actions},
+        "violations": violations,
+        "warnings": warnings,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Validate a template-frame-map before building the deck.")
+    parser.add_argument("--plan", required=True, help="path to template-frame-map.json")
+    parser.add_argument("--template", help="optionally confirm the plan names an existing template file")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+
+    try:
+        plan = json.loads(Path(args.plan).read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001 - a bad plan is the finding
+        json.dump({"gate": "template-plan", "passed": False, "error": {"code": "unparsable_plan", "message": str(exc)}}, sys.stdout)
+        sys.stdout.write("\n")
+        return 2
+
+    report = validate_plan(plan)
+    if args.template:
+        declared = plan.get("template") or args.template
+        report["template"] = str(declared)
+        if not Path(declared).is_file():
+            report["violations"].append({"code": "template_missing", "severity": "fail", "message": f"template not found: {declared}"})
+            report["passed"] = False
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())