dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/shared/check_runtime.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Validate the Office runtime that the format skills promise.
+
+Imports every distribution listed in python/requirements.txt, then asks the
+helper CLI for its own `status` report (packages and renderers) and fails with
+a readable message when anything the skills depend on is missing.
+
+Exit codes:
+  0  all required packages import and the helper CLI answered
+  1  one or more required packages is missing or fails to import
+  2  helper CLI missing, crashed, or did not return a status report
+  3  bad path or argument
+  4  --require-renderer was given and no document renderer was found
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.metadata
+import json
+import re
+import subprocess
+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
+
+DEFAULT_ROOT = Path(__file__).resolve().parents[3]
+RENDERER_HINT = (
+    "docx/pptx/xlsx rendering needs LibreOffice, Microsoft Office, or WPS Office; "
+    "pdf rendering works without any of them (PyMuPDF)"
+)
+
+
+def canonical(name: str) -> str:
+    """Normalise a distribution name the way packaging does."""
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def parse_requirements(path: Path) -> list[str]:
+    """Return distribution names from a requirements file, one per line."""
+    names: list[str] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.split("#", 1)[0].strip()
+        if not line or line.startswith("-"):
+            continue
+        line = line.split(";", 1)[0].strip()
+        name = re.split(r"[<>=!~\[( ]", line, maxsplit=1)[0].strip()
+        if name and canonical(name) not in {canonical(n) for n in names}:
+            names.append(name)
+    return names
+
+
+def module_map() -> dict[str, list[str]]:
+    """Map canonical distribution name -> its top-level import modules."""
+    mapping: dict[str, list[str]] = {}
+    for module, dists in importlib.metadata.packages_distributions().items():
+        for dist in dists:
+            mapping.setdefault(canonical(dist), []).append(module)
+    return mapping
+
+
+def check_packages(requirements: list[str]) -> list[dict]:
+    """Import each distribution's modules and report per-package state."""
+    mapping = module_map()
+    results = []
+    for name in requirements:
+        key = canonical(name)
+        modules = sorted(mapping.get(key, []))
+        if "pymupdf" in modules:
+            # PyMuPDF ships a legacy `fitz` alias that prints a deprecation warning.
+            modules = [m for m in modules if m != "fitz"]
+        entry: dict = {"distribution": name, "modules": modules}
+        try:
+            entry["version"] = importlib.metadata.version(name)
+        except importlib.metadata.PackageNotFoundError:
+            entry.update(ok=False, error="not installed for this interpreter")
+            results.append(entry)
+            continue
+        failures = []
+        for module in modules:
+            try:
+                importlib.import_module(module)
+            except Exception as exc:  # noqa: BLE001 - report any import failure verbatim
+                failures.append(f"{module}: {type(exc).__name__}: {exc}")
+        if failures:
+            entry.update(ok=False, error="; ".join(failures))
+        else:
+            entry.update(ok=True)
+        results.append(entry)
+    return results
+
+
+def cli_status(python: Path, cli: Path, timeout: float) -> dict:
+    """Run `<python> <cli> status` and return the parsed JSON report."""
+    proc = subprocess.run(
+        [str(python), str(cli), "status"],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=timeout,
+        cwd=str(cli.parent),
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"status exited {proc.returncode}: "
+            f"{(proc.stderr or proc.stdout).strip()[:800]}"
+        )
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"status did not print JSON: {exc}") from exc
+
+
+def renderer_summary(report: dict) -> dict:
+    """Reduce the CLI renderer block to a simple availability answer."""
+    renderers = report.get("renderers") or {}
+    office = renderers.get("microsoft_office") or {}
+    wps = renderers.get("kingsoft_wps") or {}
+    available = {
+        "libreoffice": renderers.get("libreoffice") or None,
+        "microsoft_office": {k: office.get(k) or None for k in ("word", "powerpoint", "excel")},
+        "kingsoft_wps": {k: wps.get(k) or None for k in ("writer", "presentation", "spreadsheet")},
+    }
+    available["any"] = (
+        bool(available["libreoffice"])
+        or any(available["microsoft_office"].values())
+        or any(available["kingsoft_wps"].values())
+    )
+    return available
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate the Office runtime the skills promise (packages + renderer status).",
+    )
+    parser.add_argument("--python", default=sys.executable, help="interpreter to validate (default: this one)")
+    parser.add_argument(
+        "--requirements",
+        default=str(DEFAULT_ROOT / "python" / "requirements.txt"),
+        help="requirements file (default: <plugin>/python/requirements.txt)",
+    )
+    parser.add_argument(
+        "--cli",
+        default=str(DEFAULT_ROOT / "python" / "office_cli.py"),
+        help="helper CLI path (default: <plugin>/python/office_cli.py)",
+    )
+    parser.add_argument("--require-renderer", action="store_true", help="exit 4 when no document renderer is installed")
+    parser.add_argument("--timeout", type=float, default=180.0, help="seconds allowed for the status call")
+    parser.add_argument("--json", action="store_true", help="print one JSON object instead of prose")
+    args = parser.parse_args(argv)
+
+    python = Path(args.python)
+    requirements_path = Path(args.requirements)
+    cli = Path(args.cli)
+    for label, path in (("requirements", requirements_path), ("cli", cli)):
+        if not path.is_file():
+            print(f"error: {label} file not found: {path}", file=sys.stderr)
+            return 3
+    if not python.exists():
+        print(f"error: interpreter not found: {python}", file=sys.stderr)
+        return 3
+
+    requirements = parse_requirements(requirements_path)
+    if not requirements:
+        print(f"error: no packages listed in {requirements_path}", file=sys.stderr)
+        return 3
+
+    packages = check_packages(requirements)
+    missing = [p["distribution"] for p in packages if not p["ok"]]
+
+    report: dict = {
+        "ok": False,
+        "python": {"executable": str(python), "version": sys.version.split()[0] if python == Path(sys.executable) else None},
+        "requirements": {"path": str(requirements_path), "distributions": requirements},
+        "cli": {"path": str(cli)},
+        "packages": packages,
+        "missing": missing,
+        "warnings": [],
+    }
+
+    if missing:
+        report["error"] = f"{len(missing)} of {len(requirements)} required package(s) missing: {', '.join(missing)}"
+        report["remedy"] = f'"{python}" -m pip install -r "{requirements_path}"'
+        emit(args, report)
+        return 1
+
+    try:
+        status = cli_status(python, cli, args.timeout)
+    except (OSError, subprocess.SubprocessError, RuntimeError) as exc:
+        report["error"] = f"helper CLI status failed: {exc}"
+        emit(args, report)
+        return 2
+
+    if status.get("command") != "status":
+        report["error"] = "helper CLI did not identify itself as the status command"
+        emit(args, report)
+        return 2
+
+    cli_python = (status.get("python") or {}).get("executable")
+    report["python"]["version"] = (status.get("python") or {}).get("version") or report["python"]["version"]
+    if cli_python and Path(cli_python).resolve() != python.resolve():
+        report["warnings"].append(f"status reported a different interpreter: {cli_python}")
+
+    cli_missing = [p.get("package") for p in status.get("packages") or [] if not p.get("installed")]
+    if cli_missing:
+        report["error"] = f"status disagrees with direct imports; still missing: {', '.join(str(p) for p in cli_missing)}"
+        emit(args, report)
+        return 2
+
+    renderers = renderer_summary(status)
+    report["renderers"] = renderers
+    if not renderers["any"]:
+        report["warnings"].append(f"no document renderer found: {RENDERER_HINT}")
+        if args.require_renderer:
+            report["error"] = "no document renderer found (--require-renderer)"
+            emit(args, report)
+            return 4
+
+    report["ok"] = True
+    emit(args, report)
+    return 0
+
+
+def emit(args: argparse.Namespace, report: dict) -> None:
+    """Print the machine report or a short human summary."""
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        return
+
+    print(f"interpreter  {report['python']['executable']}  (python {report['python']['version'] or '?'})")
+    print(f"requirements {report['requirements']['path']}  ({len(report['requirements']['distributions'])} distributions)")
+    for item in report["packages"]:
+        mark = "ok  " if item["ok"] else "FAIL"
+        detail = item.get("version") or item.get("error", "")
+        modules = f"  ({', '.join(item['modules'])})" if item["modules"] else ""
+        print(f"  [{mark}] {item['distribution']:<16} {detail}{modules}")
+    if "renderers" in report:
+        r = report["renderers"]
+        print(f"renderer     libreoffice={r['libreoffice'] or 'none'}; "
+              f"office={r['microsoft_office']}; wps={r['kingsoft_wps']}")
+    for warning in report["warnings"]:
+        print(f"warning      {warning}")
+    if report.get("error"):
+        print(f"FAILED       {report['error']}", file=sys.stderr)
+        if report.get("remedy"):
+            print(f"remedy       {report['remedy']}", file=sys.stderr)
+        return
+    print(f"OK           {len(report['packages'])}/{len(report['packages'])} packages import; helper CLI status matches")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/assets/skills/shared/common-workflow.md

@@ -0,0 +1,139 @@
+# Shared workflow
+
+Every format pack follows this loop. The helper CLI is an accelerator for common
+operations, not the boundary of what is possible: it shortens the common path,
+and the skill teaches the rest. The format router adds the spec keys and the
+commands; the order, the checks and the failure handling are the same.
+
+## 0. Read the runtime block first
+
+Call the `office_status` tool, then read the `## Office runtime` section that is
+appended to the end of the active `SKILL.md`. It is a fenced JSON block:
+
+```json
+{ "python": "...\\python.exe", "cli": "...\\python\\office_cli.py", "skill": "...\\assets\\skills\\office-documents", "shared": "...\\assets\\skills\\shared", "version": "3.13.12" }
+```
+
+- `python` and `cli` are verified absolute paths. Use them verbatim and quote
+  them in commands. Never call a bare `python`, `py`, `soffice` or `pdftoppm`.
+- `skill` is the directory of the format pack; its scripts live under
+  `<skill>/scripts/`.
+- `shared` is this directory (workflow and annotation recipes).
+- If the block is missing entirely and the skill body instead says *No working
+  Python runtime is available*, stop: do not run any helper command and do not
+  fabricate a document.
+
+`office_status` returns the same facts as JSON with `runtime.state`, the package
+list and `renderers`. Use it when a command fails and you need to know why.
+
+## 1. Decide: create or edit
+
+- No existing file → create. Write the output into the user's workspace, not a
+  temp directory, unless the user names a location.
+- Existing file to change → edit. **Never write back over the original.** The
+  output is `<original>-edited.<ext>` next to the original (or the name the user
+  asked for): `report.docx` → `report-edited.docx`. State both paths in the
+  final summary.
+- "Improve this document" means read it first (`read` verb) and edit the real
+  content; do not rebuild it from scratch and drop its formatting.
+
+## 2. Understand the file, choose the route, then change it
+
+Read or inspect the file before changing it (`read` verb first), then pick the
+cheapest route that actually does the job:
+
+1. **CLI verb** — the common case. The helper CLI is spec-driven and prints
+   exactly one JSON object on stdout. Failures print
+   `{ "ok": false, "error": "..." }` on stderr and exit non-zero.
+
+   ```bash
+   "<python>" "<cli>" docx|pptx|xlsx|pdf create --spec "<spec.json>" --out "<file>"
+   "<python>" "<cli>" docx|pptx|xlsx|pdf read   --input "<file>"
+   "<python>" "<cli>" docx|pptx|xlsx|pdf edit   --input "<file>" --spec "<spec.json>" --out "<file-edited>"
+   "<python>" "<cli>" docx|pptx|xlsx|pdf render --input "<file>" --out-dir "<dir>"
+   "<python>" "<cli>" xlsx recalc --input "<file>" --out "<file>"
+   ```
+
+   Write the spec as a JSON file in the workspace; quote absolute paths.
+   `xlsx read` accepts `--data-only`; every command accepts `--json-out <path>`
+   when you want the report on disk instead of stdout.
+
+2. **Pack script** — a specialised job the CLI has no verb for. Use the script
+   listed in the format router (`<skill>/scripts/`, or `container_tools/` for
+   pptx/xlsx). Scripts are argparse-based, support `--help`, and take absolute
+   paths; run them with the same `"<python>"`.
+
+3. **Library snippet** — the long tail. When neither the CLI nor a pack script
+   covers the change, write a short runnable script in the workspace using the
+   installed libraries (`python-docx`, `openpyxl`, `python-pptx`, `pypdf`,
+   `PyMuPDF`, `reportlab`, `pdfplumber`), run it with `"<python>"`, then verify
+   the file through the same render step. Keep it small and keep the user's
+   original untouched.
+
+Never answer "the CLI does not support this, so it cannot be done". A missing
+verb is a missing shortcut, not a missing capability: give the library-level
+route, run it, and verify the result like any other change.
+
+`check_runtime.py` in this directory validates the interpreter: it imports every
+package from `python/requirements.txt` and runs `<cli> status`. A non-zero exit
+means the environment is broken, not the spec.
+
+## 3. Render and look at the result
+
+```bash
+"<python>" "<cli>" docx render --input "<file>" --out-dir "<dir>"
+```
+
+Output: `<dir>/page-1.png`, `page-2.png`, ... (rasterised at `--dpi`, default
+110). For docx/pptx/xlsx the intermediate PDF is kept at `<dir>/<stem>.pdf` —
+use it for annotation geometry. `pdf render` rasterises with PyMuPDF and needs
+no external renderer.
+
+Open each page with `read_image`. Look for: text overflowing or clipped at
+margins, overlapping shapes, unexplained blank pages, tables spilling past the
+page, fonts replaced by boxes, missing chart/table content, and numbers that do
+not match what the user asked for.
+
+Only after the pages look right do you present the file.
+
+## 4. Fix, re-render, present
+
+Edit the spec (or the edit spec), re-run the same command, re-render, look
+again. Two or three passes is normal; if a problem survives three passes, say
+what still looks wrong instead of pretending it is fixed.
+
+Then call `present` with the final file and reply with one sentence about what
+changed. For an edit, mention the original path and the edited path.
+
+## Rasterizing art
+
+Decks, workbooks and documents embed raster images only, so an SVG or a chosen
+PDF page has to become a PNG first; the same call downscales an oversized raster.
+
+```bash
+"<python>" "<shared>/scripts/ensure_raster_image.py" --input "<art.svg>" --dpi 300 --out "<art.png>"
+"<python>" "<shared>/scripts/ensure_raster_image.py" --input "<deck.pdf>" --page 2 --width 1600 --out "<slide-2.png>"
+```
+
+It prints one JSON object with the PNG's `width`/`height` and never overwrites
+the input. Open that PNG with `read_image` and look at it before embedding it:
+a blank, clipped or miscoloured raster is invisible inside the host file.
+
+## Failure ladder
+
+| Symptom | Meaning | What you do and say |
+| --- | --- | --- |
+| No `## Office runtime` JSON; skill says *No working Python runtime is available* | The plugin cannot install or find a compatible interpreter | Do not run helper commands, do not write a document by hand. Give the user the remedy command from the skill body, ask them to run it, then call `office_status` again. |
+| `office_status` shows `cli.exists: false`, or `python`/`cli` file not found | The bundled helper or its install is incomplete | Report the missing path. Do not substitute another tool that produces a different file. |
+| `render` fails: `no document renderer found: install LibreOffice, Microsoft Office, or WPS Office` | Create/read/edit work, but docx/pptx/xlsx cannot be rasterised here | Do not claim you inspected it. Say the file was built and validated structurally (read verb), but this machine has no renderer so you could not check its appearance; the preview stays unavailable until Microsoft Office, WPS Office, or LibreOffice is installed. `pdf render` still works. If the user needs visual confidence now, offer to rebuild from a spec or to present the unverified file explicitly labelled as such. |
+| Annotation region does not land on anything, or the payload says `unmapped: true` | The drawn region cannot be tied to an object in the file | Do not silently shift the region or guess a cell/shape. Say what you could identify (preview page, text, resolved cells) and which item you could not locate, then ask the user for the text or cell. |
+| `{"ok": false, "error": "..."}` and non-zero exit | The spec was rejected (unknown key, bad type, missing file) | Read the error text, fix the spec key it names, re-run the same command. Never strip a failing block to make the command pass — that silently deletes user content. |
+| `xlsx recalc` fails with *requires Microsoft Excel or WPS Spreadsheets* | openpyxl cannot evaluate formulas | Report formula cells as uncalculated; do not invent computed values. |
+| The helper has no verb for what the requirement needs | The common path is short; the capability is not limited to it | Take the pack script route, or write a short snippet against `python-docx` / `openpyxl` / `python-pptx` / `pypdf` / `PyMuPDF` / `reportlab`, run it with `<python>`, then `read` the file back and render. Never refuse a job because a verb is missing. |
+| `read` returns an empty structure for a file the user supplied | Unsupported or corrupt input | Say what failed and stop; do not overwrite the user's file with an empty one. |
+
+## Naming rule for edits (restated)
+
+`<original>-edited.<ext>`, in the same directory as the original, unless the
+user asked for a different name. Never overwrite the original, never delete it,
+never "clean up" a temp copy over it. Deliver both paths, original first.

package/assets/skills/shared/scripts/ensure_raster_image.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Rasterise SVG artwork, one PDF page, or a raster image to a PNG.
+
+Decks, workbooks and documents can only embed raster images, so vector art has
+to become pixels before it can go in, and an oversized raster has to be scaled
+down before it makes a file huge. SVG and PDF go through PyMuPDF in-process;
+raster inputs go through Pillow (first frame, alpha kept or flattened).
+
+Success prints exactly one JSON object on stdout. Failures print a JSON error
+object on stderr and exit non-zero. The input file is never overwritten.
+
+Exit codes: 0 success, 1 bad arguments, 2 unreadable input or write failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import pymupdf
+except ImportError:  # pragma: no cover - PyMuPDF is a required dependency
+    import fitz as pymupdf  # type: ignore[no-redef]
+
+from PIL import Image, ImageColor
+
+VECTOR_SUFFIXES = {".svg", ".pdf"}
+RASTER_SUFFIXES = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".tif", ".tiff", ".gif"}
+
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def fail(message, code=1):
+    print(json.dumps({"ok": False, "error": message}, ensure_ascii=False), file=sys.stderr)
+    raise SystemExit(code)
+
+
+def background_color(spec):
+    """Return an RGB tuple, or None for a transparent background."""
+    if spec.strip().lower() == "transparent":
+        return None
+    try:
+        return ImageColor.getrgb(spec.strip())[:3]
+    except ValueError:
+        fail(f"--background must be 'transparent' or a colour such as #ffffff, got {spec!r}")
+
+
+def fit_size(width, height, target_width, target_height):
+    """Scale a native pixel size toward the requested box, keeping the aspect ratio.
+
+    One requested axis sizes the other; with both, the image fits inside the box.
+    """
+    if not target_width and not target_height:
+        return round(width), round(height)
+    scales = [t / n for t, n in ((target_width, width), (target_height, height)) if t]
+    scale = min(scales)
+    return max(1, round(width * scale)), max(1, round(height * scale))
+
+
+def flatten(image, color):
+    """Composite an RGBA image over a solid colour and drop the alpha channel."""
+    canvas = Image.new("RGB", image.size, color)
+    canvas.paste(image, (0, 0), image)
+    return canvas
+
+
+def vector_page(source, args, background):
+    """Rasterise one SVG/PDF page at --dpi, optionally scaled or flattened."""
+    try:
+        document = pymupdf.open(str(source))
+    except Exception as exc:  # noqa: BLE001 - surface the library message verbatim
+        fail(f"cannot open input: {exc}", code=2)
+    if not 1 <= args.page <= document.page_count:
+        fail(f"--page {args.page} is outside 1-{document.page_count} for {source.name}")
+    page = document[args.page - 1]
+    if page.rect.width <= 0 or page.rect.height <= 0:
+        fail(f"{source.name} page {args.page} has no drawable area", code=2)
+
+    base = args.dpi / 72.0
+    natural_width = page.rect.width * base
+    natural_height = page.rect.height * base
+    out_width, out_height = fit_size(natural_width, natural_height, args.width, args.height)
+    zoom = base * (out_width / natural_width)
+    try:
+        pixmap = page.get_pixmap(
+            matrix=pymupdf.Matrix(zoom, zoom),
+            colorspace=pymupdf.csRGB,
+            alpha=True,
+        )
+    except Exception as exc:  # noqa: BLE001 - rasterisation failure is an input problem
+        fail(f"cannot rasterize page {args.page}: {exc}", code=2)
+    image = Image.frombytes("RGBA", (pixmap.width, pixmap.height), pixmap.samples)
+    return flatten(image, background) if background is not None else image
+
+
+def raster_image(source, args, background):
+    """Convert the first frame of a raster input to RGBA, then resize/flatten."""
+    try:
+        with Image.open(source) as raw:
+            raw.seek(0)
+            image = raw.convert("RGBA")
+    except (OSError, ValueError) as exc:
+        fail(f"cannot read raster input: {exc}", code=2)
+    if args.width or args.height:
+        image = image.resize(fit_size(*image.size, args.width, args.height), Image.Resampling.LANCZOS)
+    return flatten(image, background) if background is not None else image
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Rasterise an SVG file, one PDF page, or a raster image to PNG.",
+        epilog='Example: ensure_raster_image.py --input logo.svg --dpi 300 --out logo.png',
+    )
+    parser.add_argument("--input", required=True, help="SVG, PDF, or raster image (.png/.jpg/.webp/.bmp/.tif/.gif)")
+    parser.add_argument("--out", help="PNG output path (default: <input>-p<page>.png beside the input)")
+    parser.add_argument("--dpi", type=int, default=150, help="resolution for SVG/PDF input (default: 150)")
+    parser.add_argument("--page", type=int, default=1, help="1-based page for PDF/SVG input (default: 1)")
+    parser.add_argument("--width", type=int, help="target width in pixels; the height follows the aspect ratio")
+    parser.add_argument("--height", type=int, help="target height in pixels; the width follows the aspect ratio")
+    parser.add_argument(
+        "--background",
+        default="#ffffff",
+        help="colour behind transparent pixels, or 'transparent' to keep alpha (default: #ffffff)",
+    )
+    args = parser.parse_args()
+
+    source = Path(args.input).expanduser()
+    suffix = source.suffix.lower()
+    if not source.is_file():
+        fail(f"input not found: {source}", code=2)
+    if suffix in VECTOR_SUFFIXES:
+        kind = suffix.lstrip(".")
+    elif suffix in RASTER_SUFFIXES:
+        kind = "raster"
+    else:
+        fail(f"unsupported input extension {suffix or '(none)'}; expected .svg, .pdf, or a raster image")
+    if args.dpi <= 0:
+        fail("--dpi must be a positive integer")
+    if args.page < 1:
+        fail("--page must be 1 or greater")
+    for label, value in (("--width", args.width), ("--height", args.height)):
+        if value is not None and value <= 0:
+            fail(f"{label} must be a positive integer")
+    if kind == "raster" and args.page != 1:
+        fail("raster inputs have one frame; use --page 1")
+    background = background_color(args.background)
+
+    out = Path(args.out).expanduser() if args.out else source.with_name(f"{source.stem}-p{args.page}.png")
+    if out.resolve() == source.resolve():
+        fail("--out points at the input file; refusing to overwrite it")
+    try:
+        out.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        fail(f"cannot create output directory {out.parent}: {exc}", code=2)
+
+    image = raster_image(source, args, background) if kind == "raster" else vector_page(source, args, background)
+    try:
+        image.save(str(out), "PNG")
+    except OSError as exc:
+        fail(f"cannot write {out}: {exc}", code=2)
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "input": str(source),
+                "out": str(out),
+                "source_kind": kind,
+                "page": args.page,
+                "width": image.width,
+                "height": image.height,
+                "dpi": args.dpi if kind != "raster" else None,
+                "bytes": out.stat().st_size,
+            },
+            ensure_ascii=False,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()