@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_meta.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Document metadata and file attachments for PDFs (pypdf).
+
+Modes (one required):
+  --set-meta            set metadata keys given via --title/--author/...
+  --clear-meta          drop all document info metadata
+  --attach FILE         embed a file attachment
+  --list-attachments    list embedded attachment names
+  --extract-attachments DIR  write all attachments into DIR
+
+Metadata note: values are stored in the classic DocInfo dictionary
+(Title/Author/Subject/Keywords). XMP metadata, if present, is not
+rewritten and may disagree in sophisticated viewers.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Set/clear PDF metadata; manage attachments.")
+    parser.add_argument("pdf", help="Input PDF path")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--set-meta", action="store_true", help="Set metadata fields")
+    mode.add_argument("--clear-meta", action="store_true", help="Remove all DocInfo metadata")
+    mode.add_argument("--attach", metavar="FILE", help="Embed FILE as an attachment")
+    mode.add_argument("--list-attachments", action="store_true", help="List attachment names")
+    mode.add_argument("--extract-attachments", metavar="DIR", help="Extract attachments into DIR")
+    parser.add_argument("-o", "--output", help="Output PDF (required for write modes)")
+    parser.add_argument("--title")
+    parser.add_argument("--author")
+    parser.add_argument("--subject")
+    parser.add_argument("--keywords")
+    parser.add_argument("--password", help="Password if the input is encrypted")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("Error: input is encrypted; pass --password", file=sys.stderr)
+            return 3
+
+    if args.list_attachments:
+        names = list(reader.attachments.keys())
+        json.dump({"attachment_count": len(names), "attachments": names}, sys.stdout,
+                  ensure_ascii=False, indent=2)
+        print()
+        return 0
+
+    if args.extract_attachments:
+        out_dir = Path(args.extract_attachments)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        written = []
+        for name, contents in reader.attachments.items():
+            safe = os.path.basename(name.replace('\\', '/'))
+            if safe in ('', '.', '..'):
+                safe = 'attachment.bin'
+            for data in (contents if isinstance(contents, list) else [contents]):
+                suffix = 0
+                while True:
+                    target = out_dir / (safe if not suffix else f'{Path(safe).stem}-{suffix}{Path(safe).suffix}')
+                    try:
+                        with open(target, 'xb') as fh:
+                            fh.write(bytes(data))
+                        break
+                    except FileExistsError:
+                        suffix += 1
+                written.append(str(target))
+        json.dump({"extracted": written}, sys.stdout, ensure_ascii=False, indent=2)
+        print()
+        return 0
+
+    if not args.output:
+        print("Error: -o/--output is required for write modes", file=sys.stderr)
+        return 4
+
+    writer = PdfWriter()
+    writer.append(reader)
+
+    if args.set_meta:
+        meta = {}
+        for key, value in ((f"/{k.capitalize()}", getattr(args, k))
+                           for k in ("title", "author", "subject", "keywords")):
+            if value is not None:
+                meta[key] = value
+        if not meta:
+            print("Error: --set-meta needs at least one of --title/--author/--subject/--keywords",
+                  file=sys.stderr)
+            return 4
+        writer.add_metadata(meta)
+        result = {"output": args.output, "set": {k.lstrip("/"): v for k, v in meta.items()}}
+    elif args.clear_meta:
+        writer.metadata = None
+        result = {"output": args.output, "cleared": True}
+    else:  # --attach
+        attach_path = Path(args.attach)
+        with open(attach_path, "rb") as fh:
+            writer.add_attachment(attach_path.name, fh.read())
+        result = {"output": args.output, "attached": attach_path.name}
+
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_page_image.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Export PDF pages as PNG images at a chosen DPI.
+
+Rasterizer fallback chain: pypdfium2 (pip) -> pdftoppm (poppler-utils).
+When neither is available, exits 0 with {"rendered": false, "missing": [...]}
+so callers can branch instead of crashing.
+
+Typical uses: visual verification with a vision model, and exporting
+image-only (scanned) pages for hand-off to the references/ocr-extraction.md in this skill.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def parse_pages(spec: str, page_count: int) -> list[int]:
+    """'1-3,5,9-' (1-based, inclusive) -> sorted page list."""
+    pages: set[int] = set()
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            start_s, _, end_s = part.partition("-")
+            start = int(start_s) if start_s else 1
+            end = int(end_s) if end_s else page_count
+            if end < start:
+                raise ValueError('reversed page range')
+            pages.update(range(start, end + 1))
+        else:
+            pages.add(int(part))
+    bad = [p for p in pages if not 1 <= p <= page_count]
+    if not pages or bad:
+        raise ValueError(f"pages out of range 1-{page_count}: {sorted(bad)}")
+    return sorted(pages)
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Export PDF pages as PNG images.")
+    parser.add_argument("pdf", help="Input PDF path")
+    parser.add_argument("--pages", default="1-", help="1-based ranges, e.g. '1-3,5' (default: all)")
+    parser.add_argument("--dpi", type=int, default=150, help="Render DPI (default 150)")
+    parser.add_argument("--out-dir", required=True, help="Directory for PNG files")
+    parser.add_argument("--prefix", default="page", help="Output filename prefix (default 'page')")
+    parser.add_argument("--password", help="Password for encrypted PDFs")
+    args = parser.parse_args()
+
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+    import _raster
+
+    if not _raster.available_backends():
+        json.dump({"rendered": False, "missing": _raster.missing_hints()}, sys.stdout)
+        print()
+        return 0
+
+    try:
+        from pypdf import PdfReader
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("File is encrypted; pass --password.", file=sys.stderr)
+            return 3
+    page_count = len(reader.pages)
+
+    try:
+        pages = parse_pages(args.pages, page_count)
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 4
+
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    files = []
+    for pageno in pages:
+        img = _raster.rasterize_page(args.pdf, pageno, dpi=args.dpi, password=args.password)
+        if img is None:
+            json.dump({"rendered": False, "missing": _raster.missing_hints()}, sys.stdout)
+            print()
+            return 0
+        out_path = out_dir / f"{args.prefix}{pageno:03d}.png"
+        img.save(out_path)
+        files.append(str(out_path))
+    json.dump({"rendered": True, "dpi": args.dpi, "page_count": page_count,
+               "files": files}, sys.stdout, ensure_ascii=False, indent=2)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_read.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Read a PDF: per-page text, tables, metadata, or form fields. JSON to stdout."""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+
+
+def _reconfigure_stdio() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+
+def _need(module: str, package: str):
+    try:
+        return __import__(module)
+    except ImportError:
+        print(f"Missing dependency: install with 'python3 -m pip install {package}'", file=sys.stderr)
+        raise SystemExit(2)
+
+
+def read_text(path: str, password: str | None) -> dict:
+    pdfplumber = _need("pdfplumber", "pdfplumber")
+    pages = []
+    with pdfplumber.open(path, password=password) as pdf:
+        for page in pdf.pages:
+            pages.append(page.extract_text() or "")
+    return {"page_count": len(pages), "pages": pages}
+
+
+def read_tables(path: str, password: str | None, csv_dir: str | None) -> dict:
+    pdfplumber = _need("pdfplumber", "pdfplumber")
+    result = []
+    written = []
+    with pdfplumber.open(path, password=password) as pdf:
+        for pageno, page in enumerate(pdf.pages, start=1):
+            for tidx, table in enumerate(page.extract_tables()):
+                result.append({"page": pageno, "index": tidx, "rows": table})
+                if csv_dir:
+                    os.makedirs(csv_dir, exist_ok=True)
+                    csv_path = os.path.join(csv_dir, f"page{pageno}_table{tidx}.csv")
+                    with open(csv_path, "w", encoding="utf-8", newline="") as fh:
+                        csv.writer(fh).writerows([[c if c is not None else "" for c in row] for row in table])
+                    written.append(csv_path)
+    out = {"table_count": len(result), "tables": result}
+    if csv_dir:
+        out["csv_files"] = written
+    return out
+
+
+def read_meta(path: str, password: str | None) -> dict:
+    pypdf = _need("pypdf", "pypdf")
+    reader = pypdf.PdfReader(path)
+    encrypted = reader.is_encrypted
+    if encrypted:
+        if password is None or not reader.decrypt(password):
+            return {"encrypted": True, "note": "Provide --password to read metadata of an encrypted file."}
+    meta = {}
+    if reader.metadata:
+        for key, value in reader.metadata.items():
+            meta[str(key).lstrip("/")] = str(value)
+    pages = []
+    for idx, page in enumerate(reader.pages, start=1):
+        box = page.mediabox
+        pages.append({
+            "page": idx,
+            "width": float(box.width),
+            "height": float(box.height),
+            "rotation": int(page.get("/Rotate", 0)),
+        })
+    # scanned-page heuristic: no extractable text but page has images
+    likely_scanned = []
+    try:
+        pdfplumber = _need("pdfplumber", "pdfplumber")
+        with pdfplumber.open(path, password=password) as pdf:
+            for pageno, page in enumerate(pdf.pages, start=1):
+                text = (page.extract_text() or "").strip()
+                if not text and page.images:
+                    likely_scanned.append(pageno)
+    except SystemExit:
+        raise
+    except Exception as exc:  # pragma: no cover - heuristic only
+        print(f"Warning: scanned-page check failed: {exc}", file=sys.stderr)
+    out = {
+        "encrypted": encrypted,
+        "page_count": len(reader.pages),
+        "metadata": meta,
+        "pages": pages,
+        "likely_scanned_pages": likely_scanned,
+    }
+    if likely_scanned:
+        out["note"] = ("Image-only pages detected: no text layer to extract. "
+                       "Use the references/ocr-extraction.md in this skill for OCR.")
+    return out
+
+
+FIELD_TYPES = {"/Tx": "text", "/Btn": "button", "/Ch": "choice", "/Sig": "signature"}
+
+
+def read_fields(path: str, password: str | None) -> dict:
+    pypdf = _need("pypdf", "pypdf")
+    reader = pypdf.PdfReader(path)
+    if reader.is_encrypted:
+        if password is None or not reader.decrypt(password):
+            print("File is encrypted; pass --password.", file=sys.stderr)
+            raise SystemExit(3)
+    fields = reader.get_fields() or {}
+    out = {}
+    for name, field in fields.items():
+        ftype = FIELD_TYPES.get(str(field.get("/FT")), str(field.get("/FT")))
+        value = field.get("/V")
+        states = field.get("/_States_")
+        entry = {"type": ftype, "value": None if value is None else str(value)}
+        if states:
+            entry["options"] = [str(s) for s in states]
+        out[name] = entry
+    return {"field_count": len(out), "fields": out}
+
+
+def main() -> int:
+    _reconfigure_stdio()
+    parser = argparse.ArgumentParser(description="Extract text, tables, metadata, or form fields from a PDF.")
+    parser.add_argument("pdf", help="Input PDF path")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--text", action="store_true", help="Per-page text as JSON")
+    mode.add_argument("--tables", action="store_true", help="Tables as JSON (optionally CSV via --csv-dir)")
+    mode.add_argument("--meta", action="store_true", help="Metadata, page sizes, encrypted/scanned flags")
+    mode.add_argument("--fields", action="store_true", help="AcroForm fields with types and values")
+    parser.add_argument("--csv-dir", help="Also write each table as a CSV file into this directory")
+    parser.add_argument("--password", help="Password for encrypted PDFs")
+    args = parser.parse_args()
+
+    if args.text:
+        result = read_text(args.pdf, args.password)
+    elif args.tables:
+        result = read_tables(args.pdf, args.password, args.csv_dir)
+    elif args.meta:
+        result = read_meta(args.pdf, args.password)
+    else:
+        result = read_fields(args.pdf, args.password)
+    json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_secure.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Encrypt or decrypt a PDF with passwords (AES-256 via pypdf).
+
+Note: permission flags set at encryption time are advisory — viewers may honor
+them, but any PDF library can strip them. Only the user password gates content.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Encrypt/decrypt PDFs (pypdf, AES-256).")
+    parser.add_argument("pdf", help="Input PDF path")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--encrypt", action="store_true", help="Encrypt the PDF")
+    mode.add_argument("--decrypt", action="store_true", help="Remove encryption (password required)")
+    parser.add_argument("--user-password", help="User (open) password for --encrypt")
+    parser.add_argument("--owner-password", help="Owner password for --encrypt (defaults to user password)")
+    parser.add_argument("--password", help="Known password for --decrypt")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+
+    reader = PdfReader(args.pdf)
+    if args.encrypt:
+        if not args.user_password:
+            print("Error: --encrypt requires --user-password", file=sys.stderr)
+            return 2
+        if reader.is_encrypted:
+            print("Error: input already encrypted; decrypt first", file=sys.stderr)
+            return 3
+        writer = PdfWriter()
+        writer.append(reader)
+        writer.encrypt(
+            user_password=args.user_password,
+            owner_password=args.owner_password or args.user_password,
+            algorithm="AES-256",
+        )
+        action = "encrypted"
+    else:
+        if not reader.is_encrypted:
+            print("Error: input is not encrypted", file=sys.stderr)
+            return 3
+        if args.password is None or not reader.decrypt(args.password):
+            print("Error: wrong or missing --password", file=sys.stderr)
+            return 4
+        writer = PdfWriter()
+        writer.append(reader)
+        action = "decrypted"
+
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps({"output": args.output, "action": action, "page_count": len(reader.pages)}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_split.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Extract page ranges from a PDF, optionally rotating and/or compressing pages."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def parse_pages(spec: str, page_count: int) -> list[int]:
+    """Parse a 1-based page spec like '1-3,5,9-' into 0-based indices."""
+    indices: list[int] = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            start_s, _, end_s = part.partition("-")
+            start = int(start_s) if start_s else 1
+            end = int(end_s) if end_s else page_count
+        else:
+            start = end = int(part)
+        if start < 1 or end > page_count or start > end:
+            raise ValueError(f"Page range {part!r} out of bounds (1-{page_count})")
+        indices.extend(range(start - 1, end))
+    if not indices:
+        raise ValueError('Page selection must not be empty')
+    return indices
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(
+        description="Split/extract pages from a PDF (pypdf). Pages are 1-based: '1-3,5,9-'.")
+    parser.add_argument("pdf", help="Input PDF path")
+    parser.add_argument("--pages", required=True, help="1-based page spec, e.g. '1-3,5,9-'")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    parser.add_argument("--rotate", type=int, default=0,
+                        help="Rotate extracted pages clockwise (multiple of 90)")
+    parser.add_argument("--compress", action="store_true",
+                        help="Deflate content streams (modest savings; does not recompress images)")
+    parser.add_argument("--password", help="Password if the input is encrypted")
+    args = parser.parse_args()
+
+    if args.rotate % 90 != 0:
+        print("Error: --rotate must be a multiple of 90", file=sys.stderr)
+        return 2
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf'", file=sys.stderr)
+        return 2
+
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("Error: input is encrypted; pass --password", file=sys.stderr)
+            return 3
+    try:
+        indices = parse_pages(args.pages, len(reader.pages))
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    writer = PdfWriter()
+    for idx in indices:
+        page = reader.pages[idx]
+        if args.rotate:
+            page.rotate(args.rotate)
+        writer.add_page(page)
+    if args.compress:
+        for page in writer.pages:
+            page.compress_content_streams()
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps({"output": args.output, "page_count": len(indices), "rotated": args.rotate}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/built-in-skills/office-artifacts/references/pdf/scripts/pdf_stamp.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Stamp text or an image at coordinates onto selected PDF pages.
+
+Builds an in-memory single-page overlay with reportlab, then merges it
+onto each selected page with pypdf. Coordinates are PDF points, origin
+bottom-left. Covers 'sign here' arrows, diagonal DRAFT banners, and
+page-corner labels.
+
+Examples:
+  pdf_stamp.py in.pdf -o out.pdf --text "DRAFT" --x 200 --y 400 \
+      --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000"
+  pdf_stamp.py in.pdf -o out.pdf --image sig.png --x 400 --y 60 \
+      --width 120 --pages 3
+"""
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import sys
+
+
+def parse_pages(spec: str, page_count: int) -> list[int]:
+    pages: set[int] = set()
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            start_s, _, end_s = part.partition("-")
+            start = int(start_s) if start_s else 1
+            end = int(end_s) if end_s else page_count
+            if end < start:
+                raise ValueError('reversed page range')
+            pages.update(range(start, end + 1))
+        else:
+            pages.add(int(part))
+    bad = [p for p in pages if not 1 <= p <= page_count]
+    if not pages or bad:
+        raise ValueError(f"pages out of range 1-{page_count}: {sorted(bad)}")
+    return sorted(pages)
+
+
+def build_overlay(args, page_width: float, page_height: float) -> bytes:
+    from reportlab.lib.colors import HexColor
+    from reportlab.pdfgen import canvas
+    buf = io.BytesIO()
+    c = canvas.Canvas(buf, pagesize=(page_width, page_height))
+    c.saveState()
+    try:
+        c.setFillAlpha(float(args.opacity))
+        c.setStrokeAlpha(float(args.opacity))
+    except Exception:
+        pass  # very old reportlab: no alpha support
+    c.translate(float(args.x), float(args.y))
+    if args.rotation:
+        c.rotate(float(args.rotation))
+    if args.text:
+        c.setFont(args.font, float(args.font_size))
+        c.setFillColor(HexColor(args.color))
+        c.drawString(0, 0, args.text)
+    else:
+        kwargs = {}
+        if args.width:
+            kwargs["width"] = float(args.width)
+        if args.height:
+            kwargs["height"] = float(args.height)
+        if "width" in kwargs and "height" not in kwargs:
+            from PIL import Image as PILImage
+            with PILImage.open(args.image) as im:
+                kwargs["height"] = kwargs["width"] * im.height / im.width
+        c.drawImage(args.image, 0, 0, mask="auto", **kwargs)
+    c.restoreState()
+    c.save()
+    return buf.getvalue()
+
+
+def main() -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+    parser = argparse.ArgumentParser(description="Stamp text or an image onto PDF pages.")
+    parser.add_argument("pdf", help="Input PDF path")
+    parser.add_argument("-o", "--output", required=True, help="Output PDF path")
+    what = parser.add_mutually_exclusive_group(required=True)
+    what.add_argument("--text", help="Text to stamp")
+    what.add_argument("--image", help="Image file to stamp (PNG/JPEG)")
+    parser.add_argument("--x", type=float, required=True, help="X in points (origin bottom-left)")
+    parser.add_argument("--y", type=float, required=True, help="Y in points")
+    parser.add_argument("--pages", default="1-", help="1-based ranges, e.g. '1-3,5' (default: all)")
+    parser.add_argument("--font", default="Helvetica", help="Font name (default Helvetica)")
+    parser.add_argument("--font-size", type=float, default=24, help="Font size in points")
+    parser.add_argument("--color", default="#000000", help="Text color as #RRGGBB")
+    parser.add_argument("--rotation", type=float, default=0, help="Degrees counterclockwise")
+    parser.add_argument("--opacity", type=float, default=1.0, help="0.0-1.0 (default 1.0)")
+    parser.add_argument("--width", type=float, help="Image width in points")
+    parser.add_argument("--height", type=float, help="Image height in points")
+    parser.add_argument("--under", action="store_true",
+                        help="Place the stamp under existing content instead of over it")
+    parser.add_argument("--password", help="Password if the input is encrypted")
+    args = parser.parse_args()
+
+    try:
+        from pypdf import PdfReader, PdfWriter
+    except ImportError:
+        print("Missing dependency: install with 'python3 -m pip install pypdf reportlab'",
+              file=sys.stderr)
+        return 2
+
+    reader = PdfReader(args.pdf)
+    if reader.is_encrypted:
+        if args.password is None or not reader.decrypt(args.password):
+            print("Error: input is encrypted; pass --password", file=sys.stderr)
+            return 3
+    try:
+        pages = set(parse_pages(args.pages, len(reader.pages)))
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 4
+
+    writer = PdfWriter()
+    overlay_cache: dict[tuple[float, float], object] = {}
+    for idx, page in enumerate(reader.pages, start=1):
+        if idx in pages:
+            size = (float(page.mediabox.width), float(page.mediabox.height))
+            if size not in overlay_cache:
+                overlay_pdf = PdfReader(io.BytesIO(build_overlay(args, *size)))
+                overlay_cache[size] = overlay_pdf.pages[0]
+            stamp = overlay_cache[size]
+            if args.under:
+                page.merge_page(stamp, over=False)
+            else:
+                page.merge_page(stamp)
+        writer.add_page(page)
+    with open(args.output, "wb") as fh:
+        writer.write(fh)
+    print(json.dumps({"output": args.output, "stamped_pages": sorted(pages),
+                      "kind": "text" if args.text else "image"}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())