dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-presentations/container_tools/core_properties.py

@@ -0,0 +1,127 @@
+"""Read or set the document properties of a deck.
+
+Title, author, subject, keywords and comments live in `docProps/core.xml`. They
+show up in file listings, in the presenter's title bar and in search, which is
+why a deck titled "PowerPoint Presentation" is a small embarrassment.
+
+Passing no property flag prints the current values and changes nothing.
+
+Usage
+-----
+    <python> core_properties.py --input deck.pptx
+    <python> core_properties.py --input deck.pptx --title "Automation Review" --author "Ops"
+    <python> core_properties.py --input deck.pptx --keywords "warehouse, automation" --out tagged.pptx
+
+Exit codes
+----------
+0  properties read or written
+2  bad arguments or unreadable input
+3  the output file could not be written
+
+The JSON report on stdout is `{ok, input, output, before{}, after{}, changed[]}`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+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
+
+FIELDS = ("title", "author", "subject", "keywords", "comments", "category", "last_modified_by")
+
+
+def _emit(payload: dict, code: int = 0) -> int:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return code
+
+
+def _snapshot(properties) -> dict:
+    return {field: getattr(properties, field, None) for field in FIELDS}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Read or set .pptx core properties (title, author, subject, keywords, comments).",
+        epilog="Exit codes: 0 ok, 2 bad input, 3 write failure.",
+    )
+    parser.add_argument("--input", required=True, help="source deck")
+    parser.add_argument("--title")
+    parser.add_argument("--author")
+    parser.add_argument("--subject")
+    parser.add_argument("--keywords")
+    parser.add_argument("--comments")
+    parser.add_argument("--category")
+    parser.add_argument("--last-modified-by")
+    parser.add_argument("--out", help="output deck (default: <input>-edited.pptx when writing)")
+    args = parser.parse_args()
+
+    source = Path(args.input)
+    if not source.is_file():
+        return _emit({"ok": False, "error": f"no such file: {source}"}, 2)
+
+    from pptx import Presentation  # noqa: PLC0415
+
+    try:
+        prs = Presentation(str(source))
+    except Exception as error:  # noqa: BLE001
+        return _emit({"ok": False, "error": f"cannot open {source}: {error}"}, 2)
+
+    before = _snapshot(prs.core_properties)
+    updates = {
+        field: (getattr(args, field) if getattr(args, field) is not None else None)
+        for field in FIELDS
+        if field != "last_modified_by"
+    }
+    if args.last_modified_by is not None:
+        updates["last_modified_by"] = args.last_modified_by
+    requested = {key: value for key, value in updates.items() if value is not None}
+
+    if not requested:
+        return _emit(
+            {
+                "schema": "core_properties/1",
+                "ok": True,
+                "input": str(source),
+                "output": None,
+                "before": before,
+                "after": before,
+                "changed": [],
+                "note": "read-only: no property flag was passed",
+            }
+        )
+
+    for field, value in requested.items():
+        setattr(prs.core_properties, field, value)
+    prs.core_properties.modified = datetime.now(timezone.utc).replace(tzinfo=None)
+    after = _snapshot(prs.core_properties)
+
+    output = Path(args.out) if args.out else source.with_name(f"{source.stem}-edited{source.suffix}")
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        prs.save(str(output))
+    except Exception as error:  # noqa: BLE001
+        return _emit({"ok": False, "error": f"cannot write {output}: {error}"}, 3)
+
+    return _emit(
+        {
+            "schema": "core_properties/1",
+            "ok": True,
+            "input": str(source),
+            "output": str(output),
+            "before": before,
+            "after": after,
+            "changed": [key for key, value in requested.items() if before.get(key) != value],
+        }
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/skills/office-presentations/container_tools/create_montage.py

@@ -0,0 +1,133 @@
+"""Assemble slide PNGs into one labelled contact sheet.
+
+Purpose: eyeballing twenty renders one file at a time wastes context; a single
+grid image lets you spot collisions, empty slides and stray template text at a
+glance, then zoom into the slide that looks wrong.
+
+Exit codes: 0 sheet written, 2 no readable input, 3 Pillow unavailable.
+"""
+
+from __future__ import annotations
+
+import json
+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
+
+try:
+    from PIL import Image, ImageDraw, ImageFont
+except ImportError:  # pragma: no cover - whitelist dependency, but fail clearly
+    print(json.dumps({"ok": False, "error": {"code": "pillow_missing", "message": "Pillow is required"}}))
+    raise SystemExit(3)
+
+
+def _collect(paths: list[str], directory: str | None) -> list[Path]:
+    found: list[Path] = [Path(item) for item in paths]
+    if directory:
+        found.extend(sorted(Path(directory).glob("*.png")))
+    ordered: list[Path] = []
+    seen: set[str] = set()
+    for path in found:
+        key = str(path.resolve())
+        if key in seen or not path.is_file() or path.name in {"contact-sheet.png", "montage.png"}:
+            continue
+        seen.add(key)
+        ordered.append(path)
+    return ordered
+
+
+def _label(draw, box, text: str, size: int, colour) -> None:
+    try:
+        font = ImageFont.truetype("arial.ttf", size)
+    except OSError:
+        try:
+            font = ImageFont.load_default(size=size)
+        except TypeError:  # very old Pillow
+            font = ImageFont.load_default()
+    draw.text((box[0], box[1]), text, fill=colour, font=font)
+
+
+def make_montage(
+    paths: list[str],
+    output: str | Path,
+    directory: str | None = None,
+    columns: int = 3,
+    cell_width: int = 480,
+    padding: int = 16,
+    background: tuple[int, int, int] = (245, 246, 248),
+) -> dict:
+    images = _collect(paths, directory)
+    if not images:
+        return {"ok": False, "error": {"code": "no_images", "message": "no PNG inputs found"}}
+
+    loaded: list[tuple[Path, Image.Image]] = []
+    for path in images:
+        try:
+            with Image.open(path) as handle:
+                loaded.append((path, handle.convert("RGB")))
+        except Exception as exc:  # noqa: BLE001 - one bad file must not kill the sheet
+            loaded.append((path, Image.new("RGB", (cell_width, int(cell_width * 0.5625)), (220, 60, 60))))
+    columns = max(1, min(columns, len(loaded)))
+    cell_height = max(1, int(round(cell_width * loaded[0][1].height / max(loaded[0][1].width, 1))))
+    rows = (len(loaded) + columns - 1) // columns
+    label_height = 22
+    sheet = Image.new(
+        "RGB",
+        (
+            columns * cell_width + (columns + 1) * padding,
+            rows * (cell_height + label_height) + (rows + 1) * padding,
+        ),
+        background,
+    )
+    draw = ImageDraw.Draw(sheet)
+    for index, (path, image) in enumerate(loaded):
+        column = index % columns
+        row = index // columns
+        x = padding + column * (cell_width + padding)
+        y = padding + row * (cell_height + label_height + padding)
+        draw.rectangle([x - 1, y - 1, x + cell_width, y + cell_height], outline=(205, 210, 218))
+        thumb = image.copy()
+        thumb.thumbnail((cell_width, cell_height), Image.LANCZOS)
+        sheet.paste(thumb, (x + (cell_width - thumb.width) // 2, y + (cell_height - thumb.height) // 2))
+        _label(draw, (x, y + cell_height + 4), path.stem, 13, (70, 76, 86))
+
+    target = Path(output)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(target)
+    return {
+        "ok": True,
+        "output": str(target.resolve()),
+        "cells": len(loaded),
+        "columns": columns,
+        "size": list(sheet.size),
+        "cells_in_order": [path.name for path, _ in loaded],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Combine slide PNGs into one labelled grid image.")
+    parser.add_argument("images", nargs="*", help="PNG files (order is preserved)")
+    parser.add_argument("--dir", help="also include every .png in this directory, sorted")
+    parser.add_argument("--out", required=True, help="path of the contact sheet to write")
+    parser.add_argument("--columns", type=int, default=3, help="grid columns (default 3)")
+    parser.add_argument("--cell-width", type=int, default=480, help="width of one cell in pixels (default 480)")
+    args = parser.parse_args(argv)
+
+    report = make_montage(args.images, args.out, args.dir, args.columns, args.cell_width)
+    json.dump(report, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    if report.get("ok"):
+        return 0
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-presentations/container_tools/inspect_presentation_layout_geometry.py

@@ -0,0 +1,292 @@
+"""Inspect slide geometry for the mistakes a render catches late.
+
+Purpose: before spending a round trip on a render, read the shapes and answer
+the questions that actually break a deck — does anything leave the slide, is
+text dropped out of its own box, do two blocks of text sit on top of each
+other, is a chart buried under a table, is the smallest type too small, is an
+opens-in-place placeholder still empty, does a heading end in a full stop.
+
+Severity split (ported behaviour): `fail` findings are structural and block
+delivery; `review` findings are judgement calls the author should look at.
+
+Exit codes: 0 no blocking finding, 1 blocking finding, 2 unreadable input.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from ooxml_helpers import (  # noqa: E402
+    box,
+    emit,
+    default_size_pt,
+    estimated_text_height_in,
+    finding,
+    has_visible_text,
+    is_chart,
+    is_connector,
+    is_picture,
+    is_table,
+    iter_shapes,
+    label,
+    open_presentation,
+    overlap_ratio,
+    placeholder_kind,
+    rects_intersect,
+    run_size_pt,
+    slide_size_in,
+    text_of,
+)
+
+# 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
+
+TITLE_OUTSIDE_MARGIN_IN = 0.0
+DEFAULT_TITLE_FLOOR_PT = 28.0
+DEFAULT_BODY_FLOOR_PT = 14.0
+OVERLAP_HINT_RATIO = 0.35
+TEXT_OVERFLOW_SLACK_IN = 0.08
+
+
+def inspect(pptx_path: str | Path, title_floor: float = DEFAULT_TITLE_FLOOR_PT, body_floor: float = DEFAULT_BODY_FLOOR_PT) -> dict:
+    presentation = open_presentation(pptx_path)
+    slide_w, slide_h = slide_size_in(presentation)
+    findings: list[dict] = []
+    slides_report: list[dict] = []
+    title_sizes: list[tuple[int, int]] = []
+
+    for slide_no, slide in enumerate(presentation.slides, start=1):
+        shapes = [shape for shape in iter_shapes(slide.shapes)]
+        slide_findings: list[dict] = []
+        text_boxes: list[tuple[str, tuple[float, float, float, float], str]] = []
+
+        for shape in shapes:
+            geometry = box(shape)
+            name = label(shape)
+            if geometry is None:
+                slide_findings.append(finding("shape_without_frame", "review", f"'{name}' has no position or size", shape=name))
+                continue
+            left, top, width, height = geometry
+
+            if left < -TITLE_OUTSIDE_MARGIN_IN or top < -TITLE_OUTSIDE_MARGIN_IN or left + width > slide_w + 0.01 or top + height > slide_h + 0.01:
+                slide_findings.append(
+                    finding(
+                        "outside_slide",
+                        "fail",
+                        f"'{name}' extends past the slide edge",
+                        shape=name,
+                        bbox=[round(left, 2), round(top, 2), round(width, 2), round(height, 2)],
+                        bleed={
+                            "right": round(max(0.0, left + width - slide_w), 2),
+                            "bottom": round(max(0.0, top + height - slide_h), 2),
+                            "left": round(max(0.0, -left), 2),
+                            "top": round(max(0.0, -top), 2),
+                        },
+                    )
+                )
+
+            if width <= 0 or height <= 0:
+                slide_findings.append(finding("degenerate_size", "fail", f"'{name}' has zero width or height", shape=name))
+
+            needed = estimated_text_height_in(shape)
+            if needed is not None and needed > height + TEXT_OVERFLOW_SLACK_IN:
+                slide_findings.append(
+                    finding(
+                        "text_overflow",
+                        "fail",
+                        f"'{name}' needs about {needed:.2f} in of text height but its frame is {height:.2f} in",
+                        shape=name,
+                        neededIn=round(needed, 2),
+                        frameIn=round(height, 2),
+                    )
+                )
+
+            kind = (placeholder_kind(shape) or "").upper()
+            if kind and not has_visible_text(shape) and not is_picture(shape):
+                slide_findings.append(finding("empty_placeholder", "review", f"empty {kind} placeholder is still on the slide", shape=name))
+
+            if has_visible_text(shape):
+                text_boxes.append((name, geometry, text_of(shape)))
+                size = run_size_pt(shape) or 0.0
+                if "TITLE" in kind or name.lower().startswith("title"):
+                    if 0 < size < title_floor:
+                        slide_findings.append(finding("small_title", "review", f"title '{name}' is {size:.0f} pt", shape=name, fontPt=size))
+                    if text_of(shape).rstrip().endswith("."):
+                        slide_findings.append(finding("heading_full_stop", "review", f"heading '{name}' ends with a full stop", shape=name))
+                elif 0 < size < body_floor:
+                    slide_findings.append(finding("small_body_text", "review", f"'{name}' is {size:.0f} pt", shape=name, fontPt=size))
+
+            if is_table(shape):
+                table_bottom = top + height
+                if table_bottom > slide_h:
+                    slide_findings.append(finding("table_outside_slide", "fail", f"table '{name}' runs {table_bottom - slide_h:.2f} in past the bottom edge", shape=name))
+
+        # text block collisions
+        for first in range(len(text_boxes)):
+            for second in range(first + 1, len(text_boxes)):
+                name_a, box_a, text_a = text_boxes[first]
+                name_b, box_b, text_b = text_boxes[second]
+                if not rects_intersect(box_a, box_b):
+                    continue
+                ratio = overlap_ratio(box_a, box_b)
+                if ratio >= OVERLAP_HINT_RATIO:
+                    slide_findings.append(
+                        finding(
+                            "text_overlap",
+                            "review",
+                            f"'{name_a}' and '{name_b}' overlap by {ratio * 100:.0f}% of the smaller box",
+                            shapes=[name_a, name_b],
+                            overlap=round(ratio, 2),
+                            excerpt=[text_a[:60], text_b[:60]],
+                        )
+                    )
+
+        # a chart or table hidden under a picture/other block
+        heavy = [(label(shape), box(shape)) for shape in shapes if (is_chart(shape) or is_table(shape)) and box(shape)]
+        for name, geometry in heavy:
+            for other in shapes:
+                if label(other) == name:
+                    continue
+                other_box = box(other)
+                if other_box is None or is_connector(other) or (is_chart(other) or is_table(other)):
+                    continue
+                if not has_visible_text(other) and not is_picture(other):
+                    continue
+                ratio = overlap_ratio(geometry, other_box)
+                if ratio >= 0.5:
+                    slide_findings.append(
+                        finding(
+                            "evidence_covered",
+                            "fail",
+                            f"'{label(other)}' covers {ratio * 100:.0f}% of '{name}'",
+                            shapes=[name, label(other)],
+                            overlap=round(ratio, 2),
+                        )
+                    )
+
+        # connectors crossing text
+        for shape in shapes:
+            if not is_connector(shape) or box(shape) is None:
+                continue
+            for name, text_box, _ in text_boxes:
+                if rects_intersect(box(shape), text_box) and overlap_ratio(box(shape), text_box) > 0.15:
+                    slide_findings.append(finding("connector_over_text", "review", f"connector '{label(shape)}' crosses '{name}'", shapes=[label(shape), name]))
+
+        # chart and table repeating the same numbers on one slide
+        if any(is_chart(shape) for shape in shapes) and any(is_table(shape) for shape in shapes):
+            chart_labels = {
+                str(category).strip()
+                for shape in shapes
+                if is_chart(shape)
+                for category in _chart_categories(shape)
+            }
+            table_labels = {
+                str(cell.text).strip()
+                for shape in shapes
+                if is_table(shape)
+                for row in shape.table.rows
+                for cell in row.cells
+            }
+            shared = {value for value in chart_labels & table_labels if value and not value.replace(".", "").isdigit()}
+            if len(shared) >= 2:
+                slide_findings.append(
+                    finding(
+                        "duplicate_evidence",
+                        "review",
+                        "the chart and the table restate the same categories",
+                        shared=sorted(shared)[:6],
+                    )
+                )
+
+        findings.extend({**item, "slide": slide_no} for item in slide_findings)
+        slides_report.append(
+            {
+                "slide": slide_no,
+                "shapes": len(shapes),
+                "charts": sum(1 for shape in shapes if is_chart(shape)),
+                "tables": sum(1 for shape in shapes if is_table(shape)),
+                "pictures": sum(1 for shape in shapes if is_picture(shape)),
+                "findings": len(slide_findings),
+            }
+        )
+
+        for shape in shapes:
+            kind = (placeholder_kind(shape) or "").upper()
+            # A cover is meant to run larger than the body slides, so it is excluded.
+            if "CENTER_TITLE" in kind or not has_visible_text(shape):
+                continue
+            if "TITLE" in kind or label(shape).lower().startswith("title"):
+                # Inherited sizes only resolve at render time; approximate them with the
+                # pack's placeholder defaults so drift between slides is still visible.
+                size = run_size_pt(shape) or default_size_pt(shape)
+                if size:
+                    title_sizes.append((slide_no, round(size)))
+
+    if len({size for _, size in title_sizes}) > 1:
+        findings.append(
+            finding(
+                "inconsistent_title_size",
+                "review",
+                "slide titles are set at different sizes; pick one size for the deck",
+                sizes=sorted({size for _, size in title_sizes}),
+                slides=[slide_no for slide_no, _ in title_sizes],
+            )
+        )
+    blocking = [item for item in findings if item["severity"] == "fail"]
+    return {
+        "gate": "layout-geometry",
+        "presentation": str(Path(pptx_path).resolve()),
+        "slideSizeIn": [round(slide_w, 3), round(slide_h, 3)],
+        "slides": slides_report,
+        "findings": findings,
+        "summary": {
+            "slides": len(slides_report),
+            "fail": len(blocking),
+            "review": len(findings) - len(blocking),
+        },
+        "passed": not blocking,
+    }
+
+
+def _chart_categories(shape) -> list[str]:
+    try:
+        return [str(category) for category in shape.chart.plots[0].categories]
+    except Exception:  # noqa: BLE001 - charts without a cache simply contribute nothing
+        return []
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Report slide-geometry problems (out-of-bounds shapes, text overflow, overlaps).")
+    parser.add_argument("presentation", nargs="?", help="path to the .pptx")
+    parser.add_argument("--input", dest="input_path", help="path to the .pptx (same as the positional)")
+    parser.add_argument("--title-floor", type=float, default=DEFAULT_TITLE_FLOOR_PT, help="minimum title size in pt (default 28)")
+    parser.add_argument("--body-floor", type=float, default=DEFAULT_BODY_FLOOR_PT, help="minimum body size in pt (default 14)")
+    parser.add_argument("--strict", action="store_true", help="treat review findings as blocking too")
+    parser.add_argument("--json-out", help="also write the report here")
+    args = parser.parse_args(argv)
+    path = args.input_path or args.presentation
+    if not path:
+        parser.error("a .pptx path is required (positional or --input)")
+
+    report = inspect(path, args.title_floor, args.body_floor)
+    if args.strict:
+        report["strict"] = True
+        report["passed"] = not report["findings"]
+    if args.json_out:
+        Path(args.json_out).write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    emit(report)
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())