dsh-office-kit 0.2.0 → 0.3.1

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

@@ -0,0 +1,183 @@
+"""Catch the traces an authoring pass leaves in a template-based deck.
+
+Purpose: a deck can keep the template's layouts and still be wrong — a
+"Click to add title" prompt left in place, the template's instruction text
+still sitting in a body, or an opaque panel dropped exactly over the artwork
+the design relies on. None of those are visible in a plan; all of them are
+cheap to detect afterwards.
+
+Exit codes: 0 clean, 1 findings, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "container_tools"))
+
+from ooxml_helpers import box, has_visible_text, is_picture, overlap_ratio, text_of  # noqa: E402
+
+# 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
+
+PLACEHOLDER_PATTERNS = [
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"^slide number$",
+        r"^date$",
+        r"^footer$",
+        r"^click to add (title|subtitle|text|body)",
+        r"^(title|subtitle|name|text|body) goes here$",
+        r"^lorem ipsum\b",
+        r"\btemplate instruction\b",
+        r"^\[.*\]$",
+    )
+]
+ART_COVER_MIN_RATIO = 0.9
+
+
+def _has_solid_fill(shape) -> bool:
+    try:
+        from pptx.enum.dml import MSO_FILL
+
+        return shape.fill.type == MSO_FILL.SOLID
+    except Exception:  # noqa: BLE001 - shapes without a fill API are never opaque panels
+        return False
+
+
+def _slide_size_in(slide) -> tuple[float, float]:
+    presentation = slide.part.package.presentation_part.presentation
+    return presentation.slide_width / 914400, presentation.slide_height / 914400
+
+
+def check(template_path: str | Path, final_path: str | Path, plan_path: str | Path | None = None) -> dict:
+    from pptx import Presentation
+
+    template_file = Path(template_path)
+    final_file = Path(final_path)
+    for candidate in (template_file, final_file):
+        if not candidate.is_file():
+            return {"gate": "template-authoring-fidelity", "passed": False, "findings": [{"kind": "missing_file", "detail": str(candidate)}]}
+
+    template = Presentation(str(template_file))
+    final = Presentation(str(final_file))
+    template_slides = list(template.slides)
+    final_slides = list(final.slides)
+    plan = {}
+    if plan_path and Path(plan_path).is_file():
+        plan = json.loads(Path(plan_path).read_text(encoding="utf-8"))
+
+    findings: list[dict] = []
+    mapping: list[tuple[int, int]] = []
+    for entry in plan.get("outputSlides") or []:
+        mapping.append((int(entry.get("slide", len(mapping) + 1)), int(entry.get("sourceSlide", 0))))
+    if not mapping:
+        mapping = [(index, index) for index in range(1, min(len(template_slides), len(final_slides)) + 1)]
+
+    for output_index, source_index in mapping:
+        if not (1 <= output_index <= len(final_slides) and 1 <= source_index <= len(template_slides)):
+            findings.append({"kind": "mapping_out_of_range", "severity": "fail", "message": f"mapping {output_index}->{source_index} is outside the deck"})
+            continue
+        output_slide = final_slides[output_index - 1]
+        source_slide = template_slides[source_index - 1]
+
+        if output_slide.slide_layout.name != source_slide.slide_layout.name:
+            findings.append(
+                {
+                    "kind": "layout_drift",
+                    "severity": "review",
+                    "slide": output_index,
+                    "message": f"layout is '{output_slide.slide_layout.name}', template slide used '{source_slide.slide_layout.name}'",
+                }
+            )
+
+        for shape in output_slide.shapes:
+            if not has_visible_text(shape):
+                continue
+            text = text_of(shape).strip()
+            for pattern in PLACEHOLDER_PATTERNS:
+                if pattern.search(text):
+                    findings.append(
+                        {
+                            "kind": "leftover_placeholder_text",
+                            "severity": "fail",
+                            "slide": output_index,
+                            "shape": shape.name,
+                            "text": text[:80],
+                            "message": "template prompt text is still on the slide",
+                        }
+                    )
+                    break
+            if not text and shape.is_placeholder:
+                findings.append({"kind": "empty_placeholder", "severity": "review", "slide": output_index, "shape": shape.name, "message": "placeholder was left empty"})
+
+        inherited_art = [box(shape) for shape in source_slide.shapes if is_picture(shape) and box(shape)]
+        slide_w, slide_h = _slide_size_in(source_slide)
+        full_bleed = {
+            index
+            for index, art in enumerate(inherited_art)
+            if art[0] <= 0.02 and art[1] <= 0.02 and art[2] >= slide_w * 0.98 and art[3] >= slide_h * 0.98
+        }
+        for shape in output_slide.shapes:
+            # only an opaque panel is a problem: text over a background image is the template working
+            if is_picture(shape) or not _has_solid_fill(shape):
+                continue
+            geometry = box(shape)
+            if geometry is None:
+                continue
+            for art_index, art in enumerate(inherited_art):
+                if art_index in full_bleed:
+                    continue
+                ratio = overlap_ratio(geometry, art)
+                if ratio >= ART_COVER_MIN_RATIO:
+                    findings.append(
+                        {
+                            "kind": "template_art_covered",
+                            "severity": "fail",
+                            "slide": output_index,
+                            "shape": shape.name,
+                            "overlap": round(ratio, 2),
+                            "message": "a text or table block sits on top of the template artwork",
+                        }
+                    )
+                    break
+
+    blocking = [item for item in findings if item["severity"] == "fail"]
+    return {
+        "gate": "template-authoring-fidelity",
+        "template": str(template_file.resolve()),
+        "final": str(final_file.resolve()),
+        "plan": str(plan_path) if plan_path else None,
+        "mappedSlides": len(mapping),
+        "findings": findings,
+        "passed": not blocking,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Find leftover template prompts, layout drift and covered artwork.")
+    parser.add_argument("--template", required=True, help="the template .pptx")
+    parser.add_argument("--final", required=True, help="the finished .pptx")
+    parser.add_argument("--plan", help="optional template-frame-map.json for the slide mapping")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+
+    report = check(args.template, args.final, args.plan)
+    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())

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

@@ -0,0 +1,161 @@
+"""Read a template deck into records an author can plan against.
+
+Purpose: matching a supplied deck starts with knowing what it actually is —
+slide size, which layouts exist, what each slide inherits, where the title and
+body sit, which elements repeat on every slide, what type and colours the theme
+carries. Guessing from memory of "a normal 16:9 deck" is how a template gets
+flattened.
+
+Writes:
+  <out-dir>/template-inspect.ndjson    one JSON record per slide
+  <out-dir>/template-manifest.json     deck level summary
+
+Exit codes: 0 written, 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, has_visible_text, is_chart, is_picture, is_table, placeholder_kind, slide_size_in, text_of  # noqa: E402
+
+# 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 _theme(presentation) -> dict:
+    fonts: set[str] = set()
+    fills: set[str] = set()
+    for master in presentation.slide_masters:
+        for layout in master.slide_layouts:
+            for shape in layout.shapes:
+                if has_visible_text(shape):
+                    for paragraph in shape.text_frame.paragraphs:
+                        for run in paragraph.runs:
+                            if run.font.name:
+                                fonts.add(run.font.name)
+    for slide in presentation.slides:
+        for shape in slide.shapes:
+            if has_visible_text(shape):
+                for paragraph in shape.text_frame.paragraphs:
+                    for run in paragraph.runs:
+                        if run.font.name:
+                            fonts.add(run.font.name)
+    return {"fontsSeen": sorted(fonts), "colourSourcesNote": "check layouts and masters in PowerPoint for exact theme colours"}
+
+
+def inspect_template(template_path: str | Path, out_dir: str | Path) -> dict:
+    from pptx import Presentation
+
+    source = Path(template_path)
+    if not source.is_file():
+        return {"ok": False, "error": {"code": "input_missing", "message": f"no such file: {source}"}}
+    presentation = Presentation(str(source))
+    slide_w, slide_h = slide_size_in(presentation)
+    destination = Path(out_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+
+    records: list[dict] = []
+    for index, slide in enumerate(presentation.slides, start=1):
+        layout = slide.slide_layout
+        placeholders = []
+        for shape in slide.shapes:
+            if not shape.is_placeholder:
+                continue
+            placeholders.append(
+                {
+                    "idx": shape.placeholder_format.idx,
+                    "kind": placeholder_kind(shape) or "",
+                    "type": int(shape.placeholder_format.type) if shape.placeholder_format.type is not None else None,
+                    "bboxIn": [round(value, 3) for value in (box(shape) or (0, 0, 0, 0))],
+                    "text": text_of(shape)[:120],
+                }
+            )
+        layout_placeholders = [
+            {
+                "idx": shape.placeholder_format.idx,
+                "kind": placeholder_kind(shape) or "",
+                "bboxIn": [round(value, 3) for value in (box(shape) or (0, 0, 0, 0))],
+            }
+            for shape in layout.shapes
+            if shape.is_placeholder
+        ]
+        records.append(
+            {
+                "slide": index,
+                "layout": layout.name,
+                "layoutIndex": list(presentation.slide_layouts).index(layout) if layout in list(presentation.slide_layouts) else None,
+                "layoutPlaceholders": layout_placeholders,
+                "placeholders": placeholders,
+                "shapes": len(slide.shapes),
+                "pictures": sum(1 for shape in slide.shapes if is_picture(shape)),
+                "charts": sum(1 for shape in slide.shapes if is_chart(shape)),
+                "tables": sum(1 for shape in slide.shapes if is_table(shape)),
+                "textExcerpt": " | ".join(text_of(shape)[:80] for shape in slide.shapes if has_visible_text(shape))[:240],
+                "backgroundPicture": any(
+                    is_picture(shape) and box(shape) and box(shape)[2] >= slide_w * 0.95 and box(shape)[3] >= slide_h * 0.95
+                    for shape in slide.shapes
+                ),
+            }
+        )
+
+    manifest = {
+        "template": str(source.resolve()),
+        "slideSizeIn": [round(slide_w, 3), round(slide_h, 3)],
+        "aspect": "16:9" if abs(slide_w / slide_h - 16 / 9) < 0.02 else "4:3" if abs(slide_w / slide_h - 4 / 3) < 0.02 else "custom",
+        "slideCount": len(presentation.slides),
+        "layouts": [layout.name for layout in presentation.slide_layouts],
+        "masters": len(presentation.slide_masters),
+        "slides": [{key: record[key] for key in ("slide", "layout", "shapes", "backgroundPicture")} for record in records],
+        "theme": _theme(presentation),
+    }
+
+    ndjson = destination / "template-inspect.ndjson"
+    ndjson.write_text("\n".join(json.dumps(record, ensure_ascii=False) for record in records) + "\n", encoding="utf-8")
+    manifest_path = destination / "template-manifest.json"
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    return {
+        "ok": True,
+        "template": str(source.resolve()),
+        "records": len(records),
+        "ndjson": str(ndjson.resolve()),
+        "manifest": str(manifest_path.resolve()),
+        "summary": {
+            "slideCount": manifest["slideCount"],
+            "slideSizeIn": manifest["slideSizeIn"],
+            "aspect": manifest["aspect"],
+            "layouts": manifest["layouts"],
+            "backgroundArtSlides": [record["slide"] for record in records if record["backgroundPicture"]],
+        },
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Summarise a template deck: layouts, placeholders, geometry, theme.")
+    parser.add_argument("template", nargs="?", help="path to the template .pptx")
+    parser.add_argument("--template", dest="template_opt", help="path to the template .pptx (same as the positional)")
+    parser.add_argument("--out-dir", required=True, help="directory for template-inspect.ndjson and template-manifest.json")
+    args = parser.parse_args(argv)
+    template = args.template_opt or args.template
+    if not template:
+        parser.error("a template .pptx path is required (positional or --template)")
+
+    report = inspect_template(template, args.out_dir)
+    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/make_contact_sheet.py

@@ -0,0 +1,118 @@
+"""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
+
+# 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
+
+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())