@mmerterden/multi-agent-pipeline 14.2.1 → 14.2.2

package/pipeline/skills/shared/external/localization-reuse-map/scripts/render-key-shots.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+"""Render a PER-KEY "screenpiece" for every mapping row: a cropped band of the screen
+with a RED BOX around exactly that element, so the table's "Ekran Görüntüsü" cell shows
+the content team where each key lives on screen (ported from the web skill's
+render-key-shots.mjs). No AI image generation  -  pure geometry + HTML + headless Chrome.
+
+Input modes (same split as render-overlay.py):
+  * REST (default)  -  Figma token (--token / env / keychain FIGMA_ACCESS_TOKEN):
+      geometry  GET /v1/files/<key>/nodes?ids=<frame>  → per-text absoluteBoundingBox,
+                with ANCESTOR VISIBILITY (`visible!=false`) + cumulative opacity tracked,
+                so hidden component variants with stale bboxes are never boxed;
+      image     GET /v1/images/<key>?ids=<frame>&format=png&scale=<n> → one render,
+                cropped per key.
+  * --spec <file> (repeatable; MCP / offline)  -  the SAME spec shape render-overlay.py
+      takes: { fileKey?, pages:[{nodeId, image, frame:{w,h}, nodes:[{id, characters,
+      x,y,w,h}]}] }. `image` may be a data URL **or a file path** (resolved relative to
+      the spec file)  -  a committed example spec can reference screenshot.png instead of
+      inlining base64. Several --spec files = several screen states; each row is boxed
+      on the FIRST spec/page where its node matches.
+
+Rows are matched to nodes exactly like the overlay: by `cmsNodeId` first, else by
+normalized value (new/cms/legacy tr+en, element label). Every matched row gets a shot;
+unmatched rows are listed in the manifest's `missing` (blank cell in the table  -  never
+a guessed crop).
+
+Output, into --out:
+  keyshots/keyshot__<NN>__<key>.png   one per matched row; NN = the row's 1-based
+                                      position in mapping.rows  -  the SAME number the
+                                      table and the overlay cards use.
+  <slug>.keyshots.manifest.json       {shots:[{row,key,element,file,...}], missing:[...]}
+                                      build-artifact.py reads this (mapping top-level
+                                      `keyshots`) to fill the table cells;
+                                      publish-confluence.py --keyshots attaches the PNGs.
+No headless Chrome → per-shot `.html` files are written instead (open/print manually);
+the manifest marks them `"fallback": "html"`. Read-only against every source.
+"""
+import argparse
+import base64
+import importlib.util
+import json
+import os
+import re
+import sys
+import tempfile
+
+sys.dont_write_bytecode = True
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, _HERE)
+
+# Shared with the overlay renderer on purpose: SAME matching = the shot, the
+# overlay card and the table row can never disagree about which node a key is.
+# The filename is not a valid identifier, so it loads by path rather than by
+# `import`: spec_from_file_location yields a real module object, and no source
+# text is evaluated at runtime.
+_RO_PATH = os.path.join(_HERE, "render-overlay.py")
+_spec = importlib.util.spec_from_file_location("render_overlay", _RO_PATH)
+if _spec is None or _spec.loader is None:
+    sys.exit(f"render-key-shots: cannot load {_RO_PATH}")
+_ro = importlib.util.module_from_spec(_spec)
+sys.modules["render_overlay"] = _ro
+_spec.loader.exec_module(_ro)
+
+canon_id = _ro.canon_id
+slug = _ro.slug
+build_index = _ro.build_index
+match_row = _ro.match_row
+figma_token = _ro.figma_token
+http_get_json = _ro.http_get_json
+http_get_bytes = _ro.http_get_bytes
+find_chrome = _ro.find_chrome
+FIGMA_API = _ro.FIGMA_API
+
+RED = "#E81932"
+
+
+def key_file(num, key):
+    # Drop a trailing "(owned by ...)" marker first: it is provenance, not identity, so
+    # letting it into the filename churns every PNG (and orphans the old ones) whenever
+    # a component is renamed or the tag is added. Matches build-spreadsheet's clean_key.
+    bare = re.sub(r"\s*\(.*\)\s*$", "", key or "").strip()
+    safe = re.sub(r'[/\\:*?"<>|\s]+', "-", bare or "key").strip("-")
+    return f"keyshot__{num:02d}__{safe}.png"
+
+
+def build_shot_html(img_src, fw, fh, box, pad):
+    """Full-frame-width band: `pad` px of context above/below the element, red box on it."""
+    cy0 = max(0, box["y"] - pad)
+    cy1 = min(fh, box["y"] + box["h"] + pad)
+    crop_w, crop_h = fw, cy1 - cy0
+    bx = max(0, box["x"] - 6)
+    by = box["y"] - cy0 - 6
+    bw, bh = box["w"] + 12, box["h"] + 12
+    html = f"""<!doctype html><html><head><meta charset="utf-8"><style>
+*{{margin:0;padding:0;box-sizing:border-box}}
+body{{width:{crop_w}px;height:{crop_h}px;overflow:hidden;position:relative;background:#fff}}
+img{{position:absolute;left:0;top:{-cy0}px;width:{fw}px;height:{fh}px}}
+.box{{position:absolute;left:{bx}px;top:{by}px;width:{bw}px;height:{bh}px;
+ border:3px solid {RED};border-radius:6px;box-shadow:0 0 0 2px rgba(232,25,50,.15)}}
+</style></head><body><img src="{img_src.replace('"', '&quot;')}"/><div class="box"></div></body></html>"""
+    return html, crop_w, crop_h
+
+
+def render_shot_png(chrome, html, w, h, out_path, scale):
+    """One headless-Chrome screenshot. Returns None on success, else an error string."""
+    import subprocess
+    with tempfile.NamedTemporaryFile("w", suffix=".html", delete=False, encoding="utf-8") as tf:
+        tf.write(html)
+        tmp = tf.name
+    try:
+        r = subprocess.run(
+            [chrome, "--headless", "--disable-gpu", "--hide-scrollbars",
+             f"--force-device-scale-factor={scale}",
+             f"--window-size={w},{int(h)}",
+             f"--screenshot={out_path}", tmp],
+            capture_output=True, text=True, timeout=120)
+        if not os.path.isfile(out_path):
+            return (r.stderr or "no output")[:200]
+        return None
+    except Exception as exc:  # timeout / spawn failure  -  fall back per shot, not per run
+        return str(exc)[:200]
+    finally:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+
+
+def spec_image_src(page, spec_path):
+    """`image` as a browser src: pass a data URL through; inline a file path (relative
+    to the spec file) as base64 so the crop HTML stays self-contained for Chrome."""
+    img = page.get("image") or ""
+    if img.startswith("data:"):
+        return img
+    cand = img if os.path.isabs(img) else os.path.join(os.path.dirname(os.path.abspath(spec_path)), img)
+    if not os.path.isfile(cand):
+        sys.exit(f"spec image not found: {cand}")
+    with open(cand, "rb") as fh:
+        return "data:image/png;base64," + base64.b64encode(fh.read()).decode("ascii")
+
+
+def collect_rest_pages(file_key, node_ids, token, ca_file, scale):
+    """Fetch each frame's VISIBLE text nodes (+ image render)  -  visibility is ancestor
+    `visible` AND cumulative opacity, exactly the web port's rule, because a node tree
+    carries text that is not rendered in this state and its stale bbox would land the
+    red box on the wrong content."""
+    headers = {"X-Figma-Token": token}
+    import urllib.parse
+    pages = []
+    for nid in node_ids:
+        data = http_get_json(f"{FIGMA_API}/files/{file_key}/nodes?ids={urllib.parse.quote(nid, safe='')}",
+                             headers, ca_file)
+        doc = ((data.get("nodes") or {}).get(nid) or {}).get("document")
+        if not doc:
+            sys.stderr.write(f"# warning: node {nid} not found  -  skipped\n")
+            continue
+        fb = doc.get("absoluteBoundingBox") or {"x": 0, "y": 0, "width": 0, "height": 0}
+        nodes = []
+
+        def walk(n, anc_visible, opacity):
+            vis = anc_visible and n.get("visible") is not False
+            op = opacity * (n.get("opacity") if isinstance(n.get("opacity"), (int, float)) else 1)
+            b = n.get("absoluteBoundingBox")
+            is_text = n.get("type") == "TEXT" and isinstance(n.get("characters"), str) and n["characters"].strip()
+            if is_text and b and vis and op > 0:
+                nodes.append({"id": n.get("id"), "characters": n["characters"],
+                              "x": round(b["x"] - fb["x"]), "y": round(b["y"] - fb["y"]),
+                              "w": round(b["width"]), "h": round(b["height"])})
+            for c in n.get("children") or []:
+                walk(c, vis, op)
+
+        walk(doc, True, 1)
+        img = http_get_json(
+            f"{FIGMA_API}/images/{file_key}?ids={urllib.parse.quote(nid, safe='')}&format=png&scale={scale}",
+            headers, ca_file)
+        url = (img.get("images") or {}).get(nid)
+        if not url:
+            sys.stderr.write(f"# warning: no image render for {nid}  -  skipped\n")
+            continue
+        raw = http_get_bytes(url, ca_file)
+        pages.append({"nodeId": nid,
+                      "image": "data:image/png;base64," + base64.b64encode(raw).decode("ascii"),
+                      "frame": {"w": round(fb.get("width", 0)), "h": round(fb.get("height", 0))},
+                      "nodes": nodes, "_src": "rest"})
+    return pages
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--mapping", required=True, help="mapping JSON (rows + figmaFileKey/figmaNodes + screen)")
+    ap.add_argument("--spec", action="append", default=[],
+                    help="spec JSON (repeatable  -  one per screen state; overlay-compatible shape; "
+                         "image may be a data URL or a file path relative to the spec)")
+    ap.add_argument("--file", help="Figma fileKey (REST; else mapping figmaFileKey)")
+    ap.add_argument("--nodes", help="comma-separated frame node-ids (REST; else mapping figmaNodes)")
+    ap.add_argument("--pad", type=int, default=150, help="context band above/below the element (px)")
+    ap.add_argument("--scale", type=int, default=2)
+    ap.add_argument("--token")
+    ap.add_argument("--ca-file")
+    ap.add_argument("--out", default=".", help="output dir (shots go under <out>/keyshots/)")
+    ap.add_argument("--slug", help="override slug (default from screen name)")
+    args = ap.parse_args()
+
+    with open(args.mapping, encoding="utf-8") as fh:
+        m = json.load(fh)
+    rows = m.get("rows") or []
+    screen = m.get("screen") or "screen"
+    sl = args.slug or slug(screen)
+    shots_dir = os.path.join(args.out, "keyshots")
+    os.makedirs(shots_dir, exist_ok=True)
+
+    # ---- geometry pages, in precedence order (first match wins per row) ----
+    if args.spec:
+        pages = []
+        for sp in args.spec:
+            with open(sp, encoding="utf-8") as fh:
+                spec = json.load(fh)
+            for page in spec.get("pages") or []:
+                page["_img_src"] = spec_image_src(page, sp)
+                pages.append(page)
+        if not pages:
+            sys.exit("--spec files carry no pages")
+    else:
+        file_key = args.file or m.get("figmaFileKey")
+        node_ids = [canon_id(n) for n in (args.nodes or "").split(",") if n.strip()] or \
+            [canon_id(str(n)) for n in (m.get("figmaNodes") or [])]
+        if not (file_key and node_ids):
+            ap.error("REST needs a fileKey + node-ids (via --file/--nodes or the mapping). "
+                     "Or pass --spec for the offline path.")
+        token = figma_token(args)
+        if not token:
+            sys.exit("No Figma token  -  pass --token, set FIGMA_ACCESS_TOKEN, or add the "
+                     "keychain item FIGMA_ACCESS_TOKEN (or use --spec).")
+        pages = collect_rest_pages(file_key, node_ids, token, args.ca_file, args.scale)
+        for page in pages:
+            page["_img_src"] = page["image"]
+        if not pages:
+            sys.exit("no renderable frames")
+
+    # ---- choose one node per row: first page (in order) whose nodes match it ----
+    by = [build_index([r]) for r in rows]  # per-row index → exact same matcher as overlay
+    chosen = {}   # row idx (0-based) → {page, node}
+    for page in pages:
+        for n in sorted(page["nodes"], key=lambda x: x.get("y", 0)):
+            for i, r in enumerate(rows):
+                if i in chosen or not r.get("newKey"):
+                    continue
+                if match_row(n, *by[i]) is r:
+                    chosen[i] = {"page": page, "node": n}
+    missing = [{"row": i + 1, "key": r.get("newKey"),
+                "reason": "no visible node matched (cmsNodeId/value)"}
+               for i, r in enumerate(rows) if r.get("newKey") and i not in chosen]
+
+    chrome = find_chrome()
+    if not chrome:
+        sys.stderr.write("# no headless Chrome  -  writing per-shot .html fallbacks\n")
+
+    manifest = {"screen": screen, "slug": sl, "pad": args.pad, "scale": args.scale,
+                "dir": "keyshots", "shots": [], "missing": missing}
+    ok = fail = 0
+    for i in sorted(chosen):
+        r, c = rows[i], chosen[i]
+        page, n = c["page"], c["node"]
+        num = i + 1
+        html, w, h = build_shot_html(page["_img_src"], page["frame"]["w"], page["frame"]["h"],
+                                     {"x": n["x"], "y": n["y"], "w": n["w"], "h": n["h"]}, args.pad)
+        fname = key_file(num, r["newKey"])
+        out_png = os.path.join(shots_dir, fname)
+        entry = {"row": num, "key": r["newKey"], "element": r.get("element"),
+                 "file": f"keyshots/{fname}", "pageNode": page.get("nodeId"),
+                 "cropW": w, "cropH": h}
+        if chrome:
+            err = render_shot_png(chrome, html, w, h, out_png, args.scale)
+            if err:
+                fail += 1
+                sys.stderr.write(f"# ✗ row {num} {r['newKey']}: {err}\n")
+                continue
+        else:
+            alt = out_png[:-4] + ".html"
+            with open(alt, "w", encoding="utf-8") as fh:
+                fh.write(html)
+            entry["file"] = f"keyshots/{os.path.basename(alt)}"
+            entry["fallback"] = "html"
+        ok += 1
+        manifest["shots"].append(entry)
+
+    mpath = os.path.join(args.out, sl + ".keyshots.manifest.json")
+    with open(mpath, "w", encoding="utf-8") as fh:
+        json.dump(manifest, fh, ensure_ascii=False, indent=2)
+        fh.write("\n")
+    sys.stderr.write(f"# keyshots: {ok} written, {len(missing)} unmatched, {fail} failed → "
+                     f"{shots_dir}/ · manifest: {mpath}\n")
+    sys.stderr.write(f'# set the mapping\'s top-level "keyshots": "{os.path.basename(mpath)}" '
+                     "so build-artifact.py fills the table cells\n")
+
+
+if __name__ == "__main__":
+    main()