@mmmbuto/nexuscrew 0.8.32 → 0.8.34

package/skills/fill-forms/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: fill-forms
+description: Use for inspecting, filling and visually validating local PDF or DOCX forms, including AcroForm fields, coordinate-based overlays, checkboxes, character boxes and an explicitly authorised signature image. Trigger when the user asks to fill in a PDF, complete a form, prepare paperwork for signature, populate a DOCX template or inspect a form before completion. Keep processing local, preserve the original, never invent personal data, and never sign or submit a document without explicit authorisation.
+---
+
+# Fill Forms
+
+Fill PDF and DOCX forms locally with the bundled scripts. Prefer named PDF
+fields when they exist; use coordinate overlays only for flat forms or scans.
+Always preserve the blank source and visually verify a new output file.
+
+## Select the response language
+
+Choose the language for questions, progress updates and explanations in this
+order:
+
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+
+Do not translate field values, names, identifiers, legal wording or document
+text merely to match the response language. Preserve the document's language
+unless the user explicitly requests a translation.
+
+## Apply the safety boundary
+
+- Work on local copies. Do not upload a form or its contents to an external
+  service unless the user explicitly requests and authorises that transfer.
+- Never invent a name, address, identifier, account number, date, selection or
+  legal answer. Ask for missing data or leave the field visibly unresolved.
+- Treat signatures as sensitive assets. Insert a signature image only when the
+  authorised signer supplies it and explicitly asks for insertion into the
+  identified document. Never keep signature images in source control.
+- Filling is not signing, sending or submitting. Obtain separate explicit
+  authorisation before any consequential external action.
+- Never overwrite the blank source. The scripts reject identical source and
+  output paths and require `--overwrite` before replacing an existing output.
+- Generated documents, prepared signatures and preview images are written as
+  owner-only files; generated preview/grid directories are owner-only.
+- Keep configuration files containing personal data out of source control and
+  remove temporary previews when the user no longer needs them.
+
+## Prepare dependencies
+
+Resolve every script relative to this `SKILL.md`. The scripts require Python 3
+and do not install packages automatically. Check the environment first:
+
+```bash
+python3 --version
+python3 -c "import fitz"
+```
+
+For PDF image/signature handling and DOCX support, the complete dependency set
+is listed in `requirements.txt`. If dependencies are missing, explain what is
+needed and ask before creating a virtual environment or installing packages.
+Never modify the system Python implicitly.
+
+## Inspect first
+
+Run the inspector before filling a PDF:
+
+```bash
+python3 <skill-dir>/scripts/inspect_pdf.py form.pdf
+```
+
+It reports AcroForm fields and produces coordinate-grid PNG files next to the
+source. Review those images rather than guessing positions. Replacing an
+existing grid requires an intentional `--overwrite`.
+
+- If named fields exist, prefer `mode: "acroform"`.
+- For a flat PDF or scan, use `mode: "overlay"`.
+- Use `mode: "both"` only when the document genuinely mixes both forms.
+
+For precise checkboxes and signature lines, anchor coordinates to nearby PDF
+text rather than estimating from a full-page image. Read
+[`references/overlay-technique.md`](references/overlay-technique.md) before a
+non-trivial overlay.
+
+## Fill a PDF
+
+Create a JSON configuration beside the working copy:
+
+```json
+{
+  "src": "blank-form.pdf",
+  "out": "completed-form.pdf",
+  "mode": "overlay",
+  "font_size": 9,
+  "overlay": [
+    {"page": 0, "x": 220, "y": 190, "text": "Example Person"},
+    {"page": 0, "x": 62, "y": 332, "check": true},
+    {
+      "page": 1,
+      "x": 70,
+      "y": 410,
+      "text": "XX00EXAMPLE0000000000000000",
+      "spread": {"step": 17.5}
+    }
+  ]
+}
+```
+
+Relative paths are resolved from the configuration file. Run:
+
+```bash
+python3 <skill-dir>/scripts/fill_pdf.py form-data.json
+```
+
+The script creates the output and a `<output>_preview/` directory. Use
+`--overwrite` only for an intentional revision of that output.
+
+Supported overlay items:
+
+- `text`, `x`, `y`, optional `size`;
+- `check: true`, `x`, `y`, optional `size`;
+- `text` plus `spread.step` and optional `spread.skip` for character boxes;
+- `image` plus `rect: [x0, y0, x1, y1]` for an explicitly authorised local
+  image;
+- optional top-level `font_file` for a user-provided TTF/OTF when the built-in
+  PDF font cannot represent the required text.
+
+For AcroForm mode, provide `"acroform": {"field-name": "value"}` and booleans
+for checkboxes. Unknown requested field names fail closed instead of silently
+producing an incomplete form.
+
+## Fill a DOCX template
+
+Inspect its paragraphs and tables:
+
+```bash
+python3 <skill-dir>/scripts/dump_docx.py template.docx
+```
+
+Use explicit `{{placeholder}}` tokens whenever possible, then run:
+
+```bash
+python3 <skill-dir>/scripts/fill_docx.py template.docx completed.docx \
+  --data form-data.json
+```
+
+Plain-text key replacement is available only with `--literal-keys` because it
+can otherwise replace unintended text. Unused data keys fail closed unless the
+user deliberately chooses `--allow-unused`.
+
+## Verify before handoff
+
+1. Review every generated preview page at full size.
+2. Zoom critical regions such as checkboxes, character boxes and signatures.
+3. Compare every populated value with the user's authoritative source.
+4. Confirm that the original file is unchanged and the output has a distinct
+   name.
+5. Show the final preview or document to the user before calling it ready.
+6. State clearly which fields remain empty, uncertain, unsigned or unsubmitted.

package/skills/fill-forms/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fill Forms"
+  short_description: "Safely fill and verify local PDF and DOCX forms"
+  default_prompt: "Use fill-forms to inspect and safely complete this local form."

package/skills/fill-forms/references/overlay-technique.md

@@ -0,0 +1,99 @@
+# Coordinate Overlay Technique
+
+Read this reference before filling a non-trivial flat PDF. For ordinary
+AcroForm documents, named fields are safer and this guide is unnecessary.
+
+## Coordinate system
+
+PyMuPDF uses PDF points (1 point is 1/72 inch), with the origin at the top-left.
+The x axis increases to the right and the y axis increases downward.
+`insert_text((x, y), ...)` places the text baseline at `(x, y)`.
+
+The PNG grids produced by `inspect_pdf.py` use the same coordinates. No manual
+pixel-to-point conversion is needed.
+
+## Anchor to existing text
+
+For a checkbox, signature line or narrow field, locate a nearby printed label
+and derive an offset from its exact PDF word bounds:
+
+```python
+import fitz
+
+doc = fitz.open("form.pdf")
+for word in doc[0].get_text("words"):
+    if word[4] == "Consent":
+        print(word[:5])
+```
+
+A word tuple starts with `(x0, y0, x1, y1, text)`. Position the field relative
+to those bounds and verify the result in a high-resolution clipped preview.
+Do not treat an estimated offset as final evidence.
+
+## Text baselines and boxes
+
+Use the line on which the text should sit as the initial y coordinate. If the
+text falls below the line, decrease y; if it floats too high, increase y.
+Adjust in small steps.
+
+For a checkbox, place the X near the horizontal centre and use the lower part
+of the box as the initial baseline. Verify at high zoom.
+
+## Character-by-character fields
+
+Use `spread.step` for account numbers, dates or identifiers printed as separate
+boxes:
+
+```json
+{
+  "page": 0,
+  "x": 70,
+  "y": 410,
+  "text": "XX00EXAMPLE0000000000000000",
+  "spread": {"step": 17.5}
+}
+```
+
+Measure `step` from two adjacent boxes on the coordinate grid. `spread.skip`
+accepts zero-based character indexes that should not be drawn while retaining
+their spacing.
+
+## Long text and fonts
+
+The overlay script does not wrap text automatically. Reduce the per-item
+`size`, split the content into explicitly positioned lines, or leave the field
+for manual completion rather than allowing text to overlap legal wording.
+
+The built-in PDF font is suitable for common Latin text. For another script or
+missing glyph, use a locally available, appropriately licensed TTF/OTF through
+the top-level `font_file` configuration. Do not bundle private or unlicensed
+fonts.
+
+## Signature images
+
+Insert a signature only after explicit authorisation from the signer for the
+specific document. Prepare the image locally with `prepare_signature.py` and
+keep the original and prepared image outside source control.
+
+Use a transparent PNG and a rectangle whose proportions are close to the
+signature. Avoid stretching it unnaturally. Place it so the visible stroke
+rests on the intended line, then inspect the result on a pure white background
+and in a clipped high-resolution preview.
+
+The fill script downsizes very large inserted images to the resolution needed
+for the target rectangle. This avoids embedding a multi-megapixel source into
+a small signature area.
+
+## Focused verification
+
+Render a critical region rather than relying only on a full-page preview:
+
+```python
+clip = fitz.Rect(x0, y0, x1, y1)
+pix = doc[page_number].get_pixmap(clip=clip, dpi=240)
+pix.save("verification-region.png")
+```
+
+Check every populated field, not only representative examples. Treat the
+completed file as a draft until the user has reviewed it. Filling a form does
+not authorise signing, sending or submission.

package/skills/fill-forms/requirements.txt

@@ -0,0 +1,4 @@
+PyMuPDF>=1.24,<2
+Pillow>=10,<13
+numpy>=1.26,<3
+python-docx>=1.1,<2

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Print paragraphs, tables, headers and footers from a DOCX template."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Inspect text and table structure in a local DOCX form."
+    )
+    parser.add_argument("docx", type=Path)
+    return parser.parse_args()
+
+
+def load_docx():
+    try:
+        import docx
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: python-docx. With user consent, install the "
+            "packages listed in the skill's requirements.txt."
+        ) from exc
+    return docx
+
+
+def print_paragraphs(paragraphs, heading: str) -> None:
+    print(f"== {heading} ==")
+    for index, paragraph in enumerate(paragraphs):
+        text = paragraph.text.strip()
+        if text:
+            print(f"[{index}] {text}")
+
+
+def print_tables(tables, heading: str) -> None:
+    for table_index, table in enumerate(tables):
+        print(
+            f"\n== {heading} TABLE {table_index} "
+            f"({len(table.rows)}x{len(table.columns)}) =="
+        )
+        for row_index, row in enumerate(table.rows):
+            cells = [cell.text.strip() for cell in row.cells]
+            print(f"  row {row_index}: {cells}")
+
+
+def main() -> None:
+    args = parse_args()
+    if not args.docx.is_file():
+        raise SystemExit(f"DOCX not found or not a regular file: {args.docx}")
+
+    docx = load_docx()
+    try:
+        document = docx.Document(args.docx)
+    except Exception as exc:
+        raise SystemExit(f"Could not open DOCX: {exc}") from exc
+
+    print_paragraphs(document.paragraphs, "BODY PARAGRAPHS")
+    print_tables(document.tables, "BODY")
+
+    for section_index, section in enumerate(document.sections):
+        print_paragraphs(section.header.paragraphs, f"HEADER {section_index}")
+        print_tables(section.header.tables, f"HEADER {section_index}")
+        print_paragraphs(section.footer.paragraphs, f"FOOTER {section_index}")
+        print_tables(section.footer.tables, f"FOOTER {section_index}")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Fill explicit placeholders in a local DOCX template."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import tempfile
+from collections import Counter
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Replace {{placeholders}} in a DOCX form using a JSON mapping."
+    )
+    parser.add_argument("src", type=Path)
+    parser.add_argument("out", type=Path)
+    parser.add_argument("--data", required=True, type=Path)
+    parser.add_argument(
+        "--literal-keys",
+        action="store_true",
+        help="also replace unbraced mapping keys; use only for an inspected template",
+    )
+    parser.add_argument(
+        "--allow-unused",
+        action="store_true",
+        help="allow mapping keys that were not found in the document",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="replace an existing output file, never the source",
+    )
+    return parser.parse_args()
+
+
+def load_docx():
+    try:
+        import docx
+    except ImportError as exc:
+        raise SystemExit(
+            "Missing dependency: python-docx. With user consent, install the "
+            "packages listed in the skill's requirements.txt."
+        ) from exc
+    return docx
+
+
+def load_mapping(path: Path) -> dict[str, str]:
+    if not path.is_file():
+        raise SystemExit(f"Data file not found: {path}")
+    if path.stat().st_size > 2 * 1024 * 1024:
+        raise SystemExit("Data JSON exceeds the 2 MiB safety limit.")
+
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"Could not read data JSON: {exc}") from exc
+
+    if not isinstance(raw, dict) or not raw:
+        raise SystemExit("Data JSON must be a non-empty object.")
+
+    mapping: dict[str, str] = {}
+    for key, value in raw.items():
+        if (
+            not isinstance(key, str)
+            or not key.strip()
+            or len(key) > 128
+            or "{{" in key
+            or "}}" in key
+        ):
+            raise SystemExit("Every placeholder key must be a plain non-empty string.")
+        if value is None:
+            mapping[key] = ""
+        elif isinstance(value, (str, int, float, bool)):
+            mapping[key] = str(value)
+        else:
+            raise SystemExit(f"Placeholder {key!r} has a non-scalar value.")
+    return mapping
+
+
+def token_pattern(mapping: dict[str, str], literal_keys: bool):
+    token_to_key = {}
+    for key in mapping:
+        token_to_key[f"{{{{{key}}}}}"] = key
+        if literal_keys:
+            token_to_key[key] = key
+    ordered = sorted(token_to_key, key=len, reverse=True)
+    return re.compile("|".join(re.escape(token) for token in ordered)), token_to_key
+
+
+def replace_in_paragraph(paragraph, pattern, token_to_key, mapping, counts) -> None:
+    original = "".join(run.text for run in paragraph.runs)
+    if not original:
+        return
+
+    def replacement(match):
+        key = token_to_key[match.group(0)]
+        counts[key] += 1
+        return mapping[key]
+
+    updated = pattern.sub(replacement, original)
+    if updated == original:
+        return
+    if not paragraph.runs:
+        paragraph.add_run(updated)
+        return
+    paragraph.runs[0].text = updated
+    for run in paragraph.runs[1:]:
+        run.text = ""
+
+
+def process_tables(tables, process_paragraph) -> None:
+    for table in tables:
+        for row in table.rows:
+            for cell in row.cells:
+                for paragraph in cell.paragraphs:
+                    process_paragraph(paragraph)
+                process_tables(cell.tables, process_paragraph)
+
+
+def save_atomic(document, output: Path) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        prefix=f".{output.name}.",
+        suffix=".tmp",
+        dir=output.parent,
+        delete=False,
+    )
+    temporary = Path(handle.name)
+    handle.close()
+    try:
+        document.save(temporary)
+        os.replace(temporary, output)
+        os.chmod(output, 0o600)
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def main() -> None:
+    args = parse_args()
+    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()
+    data_path = args.data.resolve()
+
+    if not source.is_file():
+        raise SystemExit(f"DOCX 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.")
+
+    mapping = load_mapping(data_path)
+    pattern, token_to_key = token_pattern(mapping, args.literal_keys)
+    counts = Counter()
+    docx = load_docx()
+
+    try:
+        document = docx.Document(source)
+    except Exception as exc:
+        raise SystemExit(f"Could not open DOCX: {exc}") from exc
+
+    def process(paragraph):
+        replace_in_paragraph(
+            paragraph,
+            pattern,
+            token_to_key,
+            mapping,
+            counts,
+        )
+
+    for paragraph in document.paragraphs:
+        process(paragraph)
+    process_tables(document.tables, process)
+
+    for section in document.sections:
+        for paragraph in section.header.paragraphs:
+            process(paragraph)
+        process_tables(section.header.tables, process)
+        for paragraph in section.footer.paragraphs:
+            process(paragraph)
+        process_tables(section.footer.tables, process)
+
+    unused = sorted(key for key in mapping if counts[key] == 0)
+    if unused and not args.allow_unused:
+        raise SystemExit(
+            "Unused placeholders: "
+            + ", ".join(repr(key) for key in unused)
+            + ". Inspect the template or use --allow-unused deliberately."
+        )
+
+    save_atomic(document, output)
+    print(f"Saved: {output}")
+    print(f"Replacements: {sum(counts.values())}")
+    if unused:
+        print("Unused placeholders allowed: " + ", ".join(repr(key) for key in unused))
+    print("Review the completed DOCX or export a local copy to PDF before handoff.")
+
+
+if __name__ == "__main__":
+    main()