goatchain-cli-darwin-x64 0.0.73-beta.9 → 0.1.1

package/bin/skills-assets/pdf/scripts/fill_inspect.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+fill_inspect.py — Inspect form fields in an existing PDF.
+
+Usage:
+    python3 fill_inspect.py --input form.pdf
+    python3 fill_inspect.py --input form.pdf --out fields.json
+
+Outputs a JSON summary of every fillable field: name, type, current value,
+allowed values (for checkboxes / dropdowns), and page number.
+
+Exit codes: 0 success, 1 bad args / file not found, 2 dep missing, 3 read error
+"""
+
+import argparse
+import json
+import sys
+import importlib.util
+import os
+
+
+
+
+def ensure_deps():
+    if importlib.util.find_spec("pypdf") is None:
+        import subprocess
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--break-system-packages", "-q", "pypdf"]
+        )
+
+
+ensure_deps()
+from pypdf import PdfReader
+from pypdf.generic import ArrayObject, DictionaryObject, NameObject, TextStringObject
+
+
+# ── Field type resolution ──────────────────────────────────────────────────────
+def _field_type(field) -> str:
+    ft = field.get("/FT")
+    if ft is None:
+        return "unknown"
+    ft = str(ft)
+    if ft == "/Tx":
+        return "text"
+    if ft == "/Btn":
+        ff = int(field.get("/Ff", 0))
+        return "radio" if ff & (1 << 15) else "checkbox"
+    if ft == "/Ch":
+        ff = int(field.get("/Ff", 0))
+        return "dropdown" if ff & (1 << 17) else "listbox"
+    if ft == "/Sig":
+        return "signature"
+    return "unknown"
+
+
+def _field_value(field) -> str | None:
+    v = field.get("/V")
+    return str(v) if v is not None else None
+
+
+def _field_options(field, ftype: str) -> dict:
+    extra = {}
+    if ftype in ("checkbox",):
+        ap = field.get("/AP")
+        if ap and "/N" in ap:
+            states = [str(k) for k in ap["/N"]]
+            extra["states"] = states
+            checked = next((s for s in states if s != "/Off"), None)
+            if checked:
+                extra["checked_value"] = checked
+    if ftype in ("dropdown", "listbox"):
+        opt = field.get("/Opt")
+        if opt:
+            choices = []
+            for item in opt:
+                if isinstance(item, (list, ArrayObject)) and len(item) >= 2:
+                    choices.append({"value": str(item[0]), "label": str(item[1])})
+                else:
+                    choices.append({"value": str(item), "label": str(item)})
+            extra["choices"] = choices
+    if ftype == "radio":
+        kids = field.get("/Kids")
+        if kids:
+            values = []
+            for kid in kids:
+                ap = kid.get("/AP")
+                if ap and "/N" in ap:
+                    for k in ap["/N"]:
+                        if str(k) != "/Off":
+                            values.append(str(k))
+            extra["radio_values"] = values
+    return extra
+
+
+def _walk_fields(fields, page_map: dict, parent_name: str = "") -> list:
+    """Recursively collect all leaf fields."""
+    result = []
+    for field in fields:
+        name = str(field.get("/T", ""))
+        full = f"{parent_name}.{name}" if parent_name else name
+
+        kids = field.get("/Kids")
+        # Kids that have /T are sub-fields (groups), not widget annotations
+        if kids:
+            named_kids = [k for k in kids if "/T" in k]
+            if named_kids:
+                result.extend(_walk_fields(named_kids, page_map, full))
+                continue
+
+        ftype = _field_type(field)
+        if ftype == "unknown":
+            continue
+
+        entry = {
+            "name":  full,
+            "type":  ftype,
+            "value": _field_value(field),
+        }
+        entry.update(_field_options(field, ftype))
+
+        # Page lookup via /P indirect reference
+        p_ref = field.get("/P")
+        if p_ref and hasattr(p_ref, "idnum"):
+            entry["page"] = page_map.get(p_ref.idnum, "?")
+
+        result.append(entry)
+    return result
+
+
+def inspect(pdf_path: str) -> dict:
+    try:
+        reader = PdfReader(pdf_path)
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+    # Build page-number lookup: {object_id: 1-based page number}
+    page_map = {}
+    for i, page in enumerate(reader.pages):
+        if hasattr(page, "indirect_reference") and page.indirect_reference:
+            page_map[page.indirect_reference.idnum] = i + 1
+
+    acroform = reader.trailer.get("/Root", {}).get("/AcroForm")
+    if acroform is None or "/Fields" not in acroform:
+        return {
+            "status":     "ok",
+            "has_fields": False,
+            "field_count": 0,
+            "fields":     [],
+            "note":       "This PDF has no fillable form fields.",
+        }
+
+    fields = _walk_fields(list(acroform["/Fields"]), page_map)
+
+    return {
+        "status":      "ok",
+        "has_fields":  bool(fields),
+        "field_count": len(fields),
+        "fields":      fields,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Inspect PDF form fields")
+    parser.add_argument("--input", required=True, help="PDF file to inspect")
+    parser.add_argument("--out",   default="",    help="Write JSON to file (optional)")
+    args = parser.parse_args()
+
+    if not os.path.exists(args.input):
+        print(json.dumps({"status": "error", "error": f"File not found: {args.input}"}),
+              file=sys.stderr)
+        sys.exit(1)
+
+    result = inspect(args.input)
+
+    output = json.dumps(result, indent=2, ensure_ascii=False)
+
+    if args.out:
+        with open(args.out, "w") as f:
+            f.write(output)
+
+    print(output)
+
+    # Human-readable summary
+    if result["status"] == "ok" and result["has_fields"]:
+        print(f"\n── Fields in {args.input} ──────────────────────────────",
+              file=sys.stderr)
+        for f in result["fields"]:
+            pg  = f"  p.{f['page']}" if "page" in f else ""
+            val = f"  = {f['value']}" if f.get("value") else ""
+            extra = ""
+            if "choices" in f:
+                extra = f"  [{', '.join(c['value'] for c in f['choices'][:4])}{'…' if len(f['choices'])>4 else ''}]"
+            elif "states" in f:
+                extra = f"  {f['states']}"
+            print(f"  {f['type']:12}  {f['name']}{pg}{val}{extra}", file=sys.stderr)
+        print("", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/bin/skills-assets/pdf/scripts/fill_write.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+fill_write.py — Write values into PDF form fields.
+
+Usage:
+    # From a JSON data file
+    python3 fill_write.py --input form.pdf --data values.json --out filled.pdf
+
+    # Inline JSON
+    python3 fill_write.py --input form.pdf --out filled.pdf \
+        --values '{"FirstName": "Jane", "Agree": "true"}'
+
+values format:
+    {
+      "FieldName":  "text value",          # text field
+      "CheckBox1":  "true",                # checkbox  (true / false)
+      "Dropdown1":  "OptionValue",         # dropdown  (must match an existing choice value)
+      "Radio1":     "/Choice2"             # radio     (must match a radio value)
+    }
+
+Exit codes: 0 success, 1 bad args, 2 dep missing, 3 read/write error, 4 validation error
+"""
+
+import argparse
+import json
+import os
+import sys
+import importlib.util
+
+
+
+
+def ensure_deps():
+    if importlib.util.find_spec("pypdf") is None:
+        import subprocess
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--break-system-packages", "-q", "pypdf"]
+        )
+
+
+ensure_deps()
+from pypdf import PdfReader, PdfWriter
+from pypdf.generic import NameObject, TextStringObject, BooleanObject
+
+
+# ── Field helpers ─────────────────────────────────────────────────────────────
+def _field_type(field) -> str:
+    ft = str(field.get("/FT", ""))
+    if ft == "/Tx":  return "text"
+    if ft == "/Btn":
+        ff = int(field.get("/Ff", 0))
+        return "radio" if ff & (1 << 15) else "checkbox"
+    if ft == "/Ch":
+        ff = int(field.get("/Ff", 0))
+        return "dropdown" if ff & (1 << 17) else "listbox"
+    return "unknown"
+
+
+def _get_checkbox_on_value(field) -> str:
+    """Return the /AP /N key that means 'checked' (anything except /Off)."""
+    ap = field.get("/AP")
+    if ap and "/N" in ap:
+        for k in ap["/N"]:
+            if str(k) != "/Off":
+                return str(k)
+    return "/Yes"
+
+
+def _get_dropdown_values(field) -> list[str]:
+    opt = field.get("/Opt")
+    if not opt:
+        return []
+    values = []
+    for item in opt:
+        try:
+            from pypdf.generic import ArrayObject
+            if isinstance(item, (list, ArrayObject)) and len(item) >= 1:
+                values.append(str(item[0]))
+            else:
+                values.append(str(item))
+        except Exception:
+            values.append(str(item))
+    return values
+
+
+# ── Walk + fill ───────────────────────────────────────────────────────────────
+def _walk_and_fill(fields, data: dict, filled: list, errors: list, parent: str = ""):
+    for field in fields:
+        name = str(field.get("/T", ""))
+        full = f"{parent}.{name}" if parent else name
+
+        # Recurse into named groups
+        kids = field.get("/Kids")
+        if kids:
+            named = [k for k in kids if "/T" in k]
+            if named:
+                _walk_and_fill(named, data, filled, errors, full)
+                continue
+
+        if full not in data:
+            continue
+
+        value   = data[full]
+        ftype   = _field_type(field)
+
+        if ftype == "text":
+            field.update({
+                NameObject("/V"):  TextStringObject(str(value)),
+                NameObject("/DV"): TextStringObject(str(value)),
+            })
+            filled.append(full)
+
+        elif ftype == "checkbox":
+            truthy = str(value).lower() in ("true", "1", "yes", "on")
+            on_val = _get_checkbox_on_value(field)
+            pdf_val = on_val if truthy else "/Off"
+            field.update({
+                NameObject("/V"):  NameObject(pdf_val),
+                NameObject("/AS"): NameObject(pdf_val),
+            })
+            filled.append(full)
+
+        elif ftype in ("dropdown", "listbox"):
+            allowed = _get_dropdown_values(field)
+            if allowed and str(value) not in allowed:
+                errors.append({
+                    "field": full,
+                    "error": f"Value '{value}' not in allowed choices: {allowed}"
+                })
+                continue
+            field.update({NameObject("/V"): TextStringObject(str(value))})
+            filled.append(full)
+
+        elif ftype == "radio":
+            # Radio value must start with /
+            pdf_val = str(value) if str(value).startswith("/") else f"/{value}"
+            field.update({
+                NameObject("/V"):  NameObject(pdf_val),
+                NameObject("/AS"): NameObject(pdf_val),
+            })
+            filled.append(full)
+
+        else:
+            errors.append({"field": full, "error": f"Unsupported field type: {ftype}"})
+
+
+def fill(pdf_path: str, out_path: str, data: dict) -> dict:
+    try:
+        reader = PdfReader(pdf_path)
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+    writer = PdfWriter()
+    writer.clone_document_from_reader(reader)
+
+    acroform = writer._root_object.get("/AcroForm")  # type: ignore[attr-defined]
+    if acroform is None or "/Fields" not in acroform:
+        return {
+            "status": "error",
+            "error":  "This PDF has no fillable form fields.",
+            "hint":   "Run fill_inspect.py first to confirm the PDF has fields.",
+        }
+
+    # Enable appearance regeneration so viewers show the new values
+    acroform.update({NameObject("/NeedAppearances"): BooleanObject(True)})
+
+    filled: list[str] = []
+    errors: list[dict] = []
+    _walk_and_fill(list(acroform["/Fields"]), data, filled, errors)
+
+    # Warn about requested fields that were never found
+    not_found = [k for k in data if k not in filled and not any(e["field"] == k for e in errors)]
+
+    try:
+        os.makedirs(os.path.dirname(os.path.abspath(out_path)), exist_ok=True)
+        with open(out_path, "wb") as f:
+            writer.write(f)
+    except Exception as e:
+        return {"status": "error", "error": f"Write failed: {e}"}
+
+    result = {
+        "status":        "ok",
+        "out":           out_path,
+        "filled_count":  len(filled),
+        "filled_fields": filled,
+        "size_kb":       os.path.getsize(out_path) // 1024,
+    }
+    if errors:
+        result["validation_errors"] = errors
+    if not_found:
+        result["not_found"] = not_found
+        result["hint"] = "Run fill_inspect.py to see all available field names."
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fill PDF form fields")
+    parser.add_argument("--input",  required=True, help="Input PDF with form fields")
+    parser.add_argument("--out",    required=True, help="Output PDF path")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--data",   help="Path to JSON file with field values")
+    group.add_argument("--values", help="Inline JSON string with field values")
+    args = parser.parse_args()
+
+    if not os.path.exists(args.input):
+        print(json.dumps({"status": "error", "error": f"File not found: {args.input}"}),
+              file=sys.stderr)
+        sys.exit(1)
+
+    # Load data
+    try:
+        if args.data:
+            with open(args.data) as f:
+                data = json.load(f)
+        else:
+            data = json.loads(args.values)
+    except Exception as e:
+        print(json.dumps({"status": "error", "error": f"JSON parse error: {e}"}),
+              file=sys.stderr)
+        sys.exit(1)
+
+    result = fill(args.input, args.out, data)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["status"] == "ok":
+        print(f"\n── Fill complete ───────────────────────────────────────",
+              file=sys.stderr)
+        print(f"  Output : {result['out']}", file=sys.stderr)
+        print(f"  Filled : {result['filled_count']} field(s)", file=sys.stderr)
+        if result.get("validation_errors"):
+            print(f"  Errors :", file=sys.stderr)
+            for e in result["validation_errors"]:
+                print(f"    • {e['field']}: {e['error']}", file=sys.stderr)
+        if result.get("not_found"):
+            print(f"  Not found: {result['not_found']}", file=sys.stderr)
+        print("", file=sys.stderr)
+    else:
+        sys.exit(3)
+
+
+if __name__ == "__main__":
+    main()