@mmmbuto/nexuscrew 0.8.33 → 0.8.34

package/skills/fill-forms/scripts/inspect_pdf.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Inspect a PDF form and render coordinate-grid previews."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="List AcroForm fields and render a coordinate grid for each PDF page."
+    )
+    parser.add_argument("pdf", type=Path)
+    parser.add_argument("--dpi", type=int, default=150)
+    parser.add_argument("--step", type=int, default=25, help="grid step in PDF points")
+    parser.add_argument("--output-dir", type=Path)
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="replace an existing generated page grid",
+    )
+    return parser.parse_args()
+
+
+def load_fitz():
+    try:
+        import fitz
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: PyMuPDF. With user consent, install the "
+            "packages listed in the skill's requirements.txt."
+        ) from exc
+    return fitz
+
+
+def validate_args(args: argparse.Namespace) -> None:
+    if args.dpi < 72 or args.dpi > 600:
+        raise SystemExit("--dpi must be between 72 and 600.")
+    if args.step < 5 or args.step > 200:
+        raise SystemExit("--step must be between 5 and 200 PDF points.")
+    if not args.pdf.is_file():
+        raise SystemExit(f"PDF not found or not a regular file: {args.pdf}")
+
+
+def list_fields(document) -> list[tuple[int, str, str, tuple[float, ...]]]:
+    fields = []
+    for page_number in range(document.page_count):
+        for widget in document[page_number].widgets() or []:
+            fields.append(
+                (
+                    page_number,
+                    widget.field_name or "",
+                    widget.field_type_string or "unknown",
+                    tuple(round(value, 1) for value in widget.rect),
+                )
+            )
+    return fields
+
+
+def draw_grid(fitz, document, step: int):
+    grid = fitz.open()
+    grid.insert_pdf(document)
+    grey = (0.7, 0.7, 0.85)
+    red = (0.9, 0.1, 0.1)
+
+    for page_number in range(grid.page_count):
+        page = grid[page_number]
+        width, height = page.rect.width, page.rect.height
+
+        x = 0
+        while x <= width:
+            major = int(x) % 100 == 0
+            page.draw_line(
+                (x, 0),
+                (x, height),
+                color=red if major else grey,
+                width=0.5 if major else 0.25,
+            )
+            if major and x > 0:
+                page.insert_text((x + 1, 9), str(int(x)), fontsize=6, color=red)
+            x += step
+
+        y = 0
+        while y <= height:
+            major = int(y) % 100 == 0
+            page.draw_line(
+                (0, y),
+                (width, y),
+                color=red if major else grey,
+                width=0.5 if major else 0.25,
+            )
+            if major and y > 0:
+                page.insert_text((2, y - 1), str(int(y)), fontsize=6, color=red)
+            y += step
+
+    return grid
+
+
+def main() -> None:
+    args = parse_args()
+    validate_args(args)
+    fitz = load_fitz()
+
+    try:
+        document = fitz.open(args.pdf)
+    except Exception as exc:
+        raise SystemExit(f"Could not open PDF: {exc}") from exc
+
+    try:
+        if document.page_count < 1:
+            raise SystemExit("The PDF has no pages.")
+        if document.needs_pass:
+            raise SystemExit("The PDF is encrypted. Decrypt an authorised working copy first.")
+
+        first = document[0].rect
+        print(f"PDF: {args.pdf}")
+        print(
+            f"Pages: {document.page_count} | first page: "
+            f"{first.width:.0f} x {first.height:.0f} pt"
+        )
+
+        fields = list_fields(document)
+        if fields:
+            print(f"\nFillable PDF: {len(fields)} AcroForm fields")
+            print(f"{'page':>4}  {'type':<14} name")
+            for page_number, name, field_type, rect in fields:
+                print(
+                    f"{page_number:>4}  {field_type:<14} "
+                    f"{name!r} rect={rect}"
+                )
+        else:
+            print("\nFlat PDF: no AcroForm fields. Use coordinate overlays.")
+
+        output_unresolved = (
+            args.output_dir.expanduser()
+            if args.output_dir
+            else args.pdf.resolve().with_suffix("").with_name(
+                f"{args.pdf.stem}_grid"
+            )
+        )
+        if output_unresolved.is_symlink():
+            raise SystemExit("Grid output directory must not be a symbolic link.")
+        output_dir = output_unresolved.resolve()
+        if output_dir.exists() and not output_dir.is_dir():
+            raise SystemExit(f"Grid output target is not a directory: {output_dir}")
+        if output_dir.exists():
+            safe = re.compile(r"^page-[1-9][0-9]*\.png$")
+            entries = list(output_dir.iterdir())
+            if any(
+                entry.is_symlink()
+                or not entry.is_file()
+                or safe.fullmatch(entry.name) is None
+                for entry in entries
+            ):
+                raise SystemExit(
+                    "Grid output directory contains unexpected files; "
+                    "choose another --output-dir."
+                )
+            if entries and not args.overwrite:
+                raise SystemExit(
+                    "Grid output already exists. Use --overwrite for an "
+                    "intentional revision."
+                )
+            for entry in entries:
+                entry.unlink()
+        output_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        os.chmod(output_dir, 0o700)
+
+        grid = draw_grid(fitz, document, args.step)
+        try:
+            for page_number in range(grid.page_count):
+                target = output_dir / f"page-{page_number + 1}.png"
+                grid[page_number].get_pixmap(dpi=args.dpi).save(target)
+                os.chmod(target, 0o600)
+        finally:
+            grid.close()
+
+        print(f"\nCoordinate grids: {output_dir}/page-*.png")
+        print("Review the PNG files before choosing overlay coordinates.")
+    finally:
+        document.close()
+
+
+if __name__ == "__main__":
+    main()

package/skills/fill-forms/scripts/prepare_signature.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Prepare an explicitly authorised local signature image for PDF overlay."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Remove paper background, crop and export a signature as transparent PNG. "
+            "Use only with the signer's explicit authorisation."
+        )
+    )
+    parser.add_argument("src", type=Path)
+    parser.add_argument("out", type=Path)
+    parser.add_argument("--dark", type=int, default=90)
+    parser.add_argument("--light", type=int, default=185)
+    parser.add_argument("--margin", type=int, default=12)
+    parser.add_argument(
+        "--min-alpha",
+        type=int,
+        default=60,
+        help="discard low-opacity background pixels; 0 disables",
+    )
+    parser.add_argument(
+        "--max-width",
+        type=int,
+        default=0,
+        help="downsize to this pixel width; 0 preserves the cropped width",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="replace an existing output file, never the source",
+    )
+    return parser.parse_args()
+
+
+def load_dependencies():
+    try:
+        import numpy
+        from PIL import Image
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: numpy and Pillow are required. With user "
+            "consent, install the packages listed in requirements.txt."
+        ) from exc
+    return numpy, Image
+
+
+def validate_args(args: argparse.Namespace) -> tuple[Path, Path]:
+    source = args.src.resolve()
+    output_unresolved = args.out.expanduser()
+    if output_unresolved.is_symlink():
+        raise SystemExit("Output must not be a symbolic link.")
+    output = output_unresolved.resolve()
+
+    if not source.is_file():
+        raise SystemExit(f"Input image not found or not a regular file: {source}")
+    if source == output:
+        raise SystemExit("Source and output must be different files.")
+    if output.exists() and not args.overwrite:
+        raise SystemExit("Output already exists. Use --overwrite for an intentional revision.")
+    if output.suffix.lower() != ".png":
+        raise SystemExit("Output must use the .png extension.")
+    if not 0 <= args.dark < args.light <= 255:
+        raise SystemExit("Require 0 <= --dark < --light <= 255.")
+    if args.margin < 0 or args.margin > 1000:
+        raise SystemExit("--margin must be between 0 and 1000 pixels.")
+    if not 0 <= args.min_alpha <= 255:
+        raise SystemExit("--min-alpha must be between 0 and 255.")
+    if args.max_width < 0 or args.max_width > 20_000:
+        raise SystemExit("--max-width must be between 0 and 20000 pixels.")
+    return source, output
+
+
+def flatten_to_greyscale(Image, source):
+    if source.mode in ("RGBA", "LA") or (
+        source.mode == "P" and "transparency" in source.info
+    ):
+        rgba = source.convert("RGBA")
+        flattened = Image.new("RGB", rgba.size, (255, 255, 255))
+        flattened.paste(rgba, mask=rgba.getchannel("A"))
+        return flattened.convert("L")
+    return source.convert("L")
+
+
+def main() -> None:
+    args = parse_args()
+    source_path, output_path = validate_args(args)
+    np, Image = load_dependencies()
+
+    try:
+        with Image.open(source_path) as source:
+            source.load()
+            grey = np.asarray(flatten_to_greyscale(Image, source), dtype=np.float32)
+    except Exception as exc:
+        raise SystemExit(f"Could not read input image: {exc}") from exc
+
+    dark = float(args.dark)
+    light = float(args.light)
+    alpha = np.clip((light - grey) / (light - dark), 0.0, 1.0)
+
+    ink = alpha > 0.35
+    height, width = ink.shape
+    column_ink = ink.sum(axis=0)
+    row_ink = ink.sum(axis=1)
+    minimum_column = max(3, int(0.004 * height))
+    minimum_row = max(3, int(0.004 * width))
+    columns = np.where(column_ink >= minimum_column)[0]
+    rows = np.where(row_ink >= minimum_row)[0]
+    if columns.size == 0 or rows.size == 0:
+        raise SystemExit(
+            "No consistent ink stroke detected. Adjust --dark/--light and inspect the source."
+        )
+
+    margin = args.margin
+    x0 = max(0, int(columns[0]) - margin)
+    x1 = min(width, int(columns[-1]) + 1 + margin)
+    y0 = max(0, int(rows[0]) - margin)
+    y1 = min(height, int(rows[-1]) + 1 + margin)
+
+    cropped_alpha = (alpha[y0:y1, x0:x1] * 255).astype(np.uint8)
+    if args.min_alpha:
+        cropped_alpha[cropped_alpha < args.min_alpha] = 0
+
+    crop_height, crop_width = cropped_alpha.shape
+    pixels = np.zeros((crop_height, crop_width, 4), dtype=np.uint8)
+    pixels[..., 3] = cropped_alpha
+    prepared = Image.fromarray(pixels, "RGBA")
+
+    if args.max_width and crop_width > args.max_width:
+        new_height = max(1, round(crop_height * args.max_width / crop_width))
+        prepared = prepared.resize(
+            (args.max_width, new_height),
+            Image.Resampling.LANCZOS,
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        prefix=f".{output_path.name}.",
+        suffix=".tmp",
+        dir=output_path.parent,
+        delete=False,
+    )
+    temporary = Path(handle.name)
+    handle.close()
+    try:
+        prepared.save(temporary, format="PNG")
+        os.replace(temporary, output_path)
+        os.chmod(output_path, 0o600)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+    print(
+        f"Saved: {output_path} | crop {prepared.width}x{prepared.height}px "
+        f"from {width}x{height}px"
+    )
+    print(
+        "Verify the PNG on a pure white background. Keep it private and use it "
+        "only for the specifically authorised document."
+    )
+
+
+if __name__ == "__main__":
+    main()