@mmerterden/multi-agent-pipeline 14.2.1 → 14.2.2

package/pipeline/skills/shared/external/localization-reuse-map/scripts/build-spreadsheet.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Build the content-team Excel (CMS import) sheet from a mapping JSON.
+
+One row per localization key, in the columns the content team's CMS import expects:
+
+  Channel | Property Group | Property Module | Key | EN Value | TR Value | AR Value | Anotation EN | Anotation TR
+
+- Channel  -  the delivery channel these strings belong to ("Mobile" by default; --channel).
+- Property Group  -  deduced from the key namespace; describe your CMS buckets with --taxonomy, or let a
+                   row override it outright with a "propertyGroup" field.
+- Property Module  -  deduced too (Fields / Validation / Common / <domain>); overridable with "propertyModule".
+- Key  -  our NEW (redesign) key, verbatim (row.newKey). "(owned by ...)" component tags are stripped.
+- EN/TR/AR Value  -  our SUGGESTED values (row.new.en / .tr / .ar  -  resolve-new-values.py output).
+- Anotation EN/TR  -  the content team's ACTUAL copy, the Figma CMS annotations (row.cms.en / .tr).
+
+Writes a real `.xlsx` (an OOXML zip built with the Python stdlib only  -  no pip, no network, same trick
+build-artifact.py uses for .docx). `--csv` also emits a UTF-8 CSV alongside it (a terminal-friendly fallback
+when Excel is not needed). `--csv-only` skips the xlsx.
+
+Usage:
+  python3 build-spreadsheet.py <mapping>.json --out <dir> [--slug <slug>] [--channel Mobile]
+      [--taxonomy cms-taxonomy.json] [--csv|--csv-only]
+"""
+import argparse
+import csv
+import html
+import io
+import json
+import os
+import sys
+import zipfile
+
+COLUMNS = ["Channel", "Property Group", "Property Module", "Key",
+           "EN Value", "TR Value", "AR Value", "Anotation EN", "Anotation TR"]
+
+# Approx display widths (chars) per column, for the xlsx.
+COL_WIDTHS = [10, 22, 20, 40, 26, 26, 26, 26, 26]
+
+
+def _text(v):
+    return "" if v in (None, "") else str(v)
+
+
+def slugify(name):
+    slug = "".join(ch if ch.isalnum() else "-" for ch in _text(name).lower()).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    return slug or "screen"
+
+
+def clean_key(row):
+    """The Key column = our new key, without a trailing '(owned by ...)' component tag."""
+    k = _text(row.get("newKey"))
+    i = k.find("(owned by")
+    return (k[:i].strip() if i >= 0 else k).strip()
+
+
+# --- Property Group / Module deduction ------------------------------------------------
+# A CMS typically files keys into a group (shared building blocks vs feature areas) and a
+# module inside it. The deduction below is a neutral default; every CMS names its buckets
+# differently, so point --taxonomy at a JSON file to describe yours:
+#
+#   {
+#     "errors":     {"group": "Common-Errors",  "module": ""},
+#     "lookups":    {"group": "Common-Lookup",  "module": ""},
+#     "validation": {"group": "Core",           "module": "Validation"},
+#     "fields":     {"group": "Core",           "module": "Fields"},
+#     "fallback":   {"group": "Core",           "module": "Common"},
+#     "domainGroup": "Domains",
+#     "domains": {"auth": ["login", "signup", "otp"], "billing": ["invoice", "card"]}
+#   }
+#
+# Any subset may be given; unspecified parts keep the defaults. A mapping row always wins
+# over deduction via explicit "propertyGroup" / "propertyModule".
+
+DEFAULT_TAXONOMY = {
+    "errors": {"group": "Errors", "module": ""},
+    "lookups": {"group": "Lookups", "module": ""},
+    "validation": {"group": "Core", "module": "Validation"},
+    "fields": {"group": "Core", "module": "Fields"},
+    "fallback": {"group": "Core", "module": "Common"},
+    "domainGroup": "Domains",
+    "domains": {
+        "auth": ["auth", "login", "signin", "sign-in", "register", "signup", "otp", "password"],
+        "account": ["account", "profile", "settings", "preferences"],
+        "checkout": ["checkout", "cart", "payment", "billing", "order"],
+        "search": ["search", "filter", "results"],
+    },
+}
+
+_TAXONOMY = DEFAULT_TAXONOMY
+
+
+def load_taxonomy(path):
+    """Merge a user taxonomy file over the neutral defaults (one level deep)."""
+    if not path:
+        return dict(DEFAULT_TAXONOMY)
+    with open(path, encoding="utf-8") as fh:
+        user = json.load(fh)
+    if not isinstance(user, dict):
+        raise SystemExit(f"--taxonomy must be a JSON object, got {type(user).__name__}")
+    merged = dict(DEFAULT_TAXONOMY)
+    for k, v in user.items():
+        if isinstance(v, dict) and isinstance(merged.get(k), dict):
+            merged[k] = {**merged[k], **v}
+        else:
+            merged[k] = v
+    return merged
+
+
+def _bucket(name, group, module):
+    b = _TAXONOMY.get(name) or {}
+    return (group or _text(b.get("group")), module or _text(b.get("module")))
+
+
+def _first_segment(key):
+    for sep in (".", "-", "_", "/"):
+        if sep in key:
+            return key.split(sep, 1)[0]
+    return key
+
+
+def deduce_group_module(row):
+    """Return (group, module) for a row, honoring explicit overrides first."""
+    group = _text(row.get("propertyGroup"))
+    module = _text(row.get("propertyModule"))
+    if group and module:
+        return group, module
+
+    key = clean_key(row)
+    low = key.lower()
+
+    # Cross-cutting pools first.
+    if "error" in low or "errormessage" in low:
+        return _bucket("errors", group, module)
+    if "lookup" in low:
+        return _bucket("lookups", group, module)
+
+    # Core building blocks.
+    if "validation" in low or "invalid" in low or low.endswith(".valid"):
+        return _bucket("validation", group, module)
+    if any(w in low for w in ("field", "placeholder", "hint", "label")):
+        return _bucket("fields", group, module)
+
+    # Feature domains, matched on the first namespace segment then anywhere in the key.
+    first = _first_segment(low)
+    for dom, hints in (_TAXONOMY.get("domains") or {}).items():
+        if first in hints or any(h in low for h in hints):
+            return (group or _text(_TAXONOMY.get("domainGroup")), module or dom)
+
+    return _bucket("fallback", group, module)
+
+
+def row_to_record(row, channel):
+    group, module = deduce_group_module(row)
+    new = row.get("new") or {}
+    cms = row.get("cms") or {}
+    return [
+        channel,
+        group,
+        module,
+        clean_key(row),
+        _text(new.get("en")),
+        _text(new.get("tr")),
+        _text(new.get("ar")),
+        _text(cms.get("en")),
+        _text(cms.get("tr")),
+    ]
+
+
+def build_records(mapping, channel):
+    return [row_to_record(r, channel) for r in mapping.get("rows", [])]
+
+
+# --- xlsx writer (stdlib only: an .xlsx is a zip of OOXML parts) -----------------------
+
+def _xesc(s):
+    return html.escape(_text(s), quote=True)
+
+
+def _col_letter(idx):  # 0-based -> A, B, ... Z, AA, ...
+    idx += 1
+    out = ""
+    while idx:
+        idx, rem = divmod(idx - 1, 26)
+        out = chr(65 + rem) + out
+    return out
+
+
+def _sheet_xml(records):
+    cols = "".join(
+        f'<col min="{i+1}" max="{i+1}" width="{w}" customWidth="1"/>'
+        for i, w in enumerate(COL_WIDTHS)
+    )
+
+    def cell(col_idx, row_idx, value, style):
+        ref = f"{_col_letter(col_idx)}{row_idx}"
+        return (f'<c r="{ref}" t="inlineStr" s="{style}">'
+                f'<is><t xml:space="preserve">{_xesc(value)}</t></is></c>')
+
+    rows_xml = []
+    header = "".join(cell(i, 1, COLUMNS[i], 1) for i in range(len(COLUMNS)))
+    rows_xml.append(f'<row r="1">{header}</row>')
+    for ri, rec in enumerate(records, start=2):
+        cells = "".join(cell(i, ri, rec[i], 0) for i in range(len(COLUMNS)))
+        rows_xml.append(f'<row r="{ri}">{cells}</row>')
+
+    last = f"{_col_letter(len(COLUMNS)-1)}{max(1, len(records)+1)}"
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+        f'<dimension ref="A1:{last}"/>'
+        '<sheetViews><sheetView workbookViewId="0">'
+        '<pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/>'
+        '</sheetView></sheetViews>'
+        '<sheetFormatPr defaultRowHeight="15"/>'
+        f'<cols>{cols}</cols>'
+        f'<sheetData>{"".join(rows_xml)}</sheetData>'
+        f'<autoFilter ref="A1:{_col_letter(len(COLUMNS)-1)}1"/>'
+        '</worksheet>'
+    )
+
+
+_STYLES_XML = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<styleSheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">'
+    '<fonts count="2">'
+    '<font><sz val="11"/><name val="Calibri"/></font>'
+    '<font><b/><sz val="11"/><color rgb="FFFFFFFF"/><name val="Calibri"/></font>'
+    '</fonts>'
+    '<fills count="3">'
+    '<fill><patternFill patternType="none"/></fill>'
+    '<fill><patternFill patternType="gray125"/></fill>'
+    '<fill><patternFill patternType="solid"><fgColor rgb="FF4472C4"/><bgColor indexed="64"/></patternFill></fill>'
+    '</fills>'
+    '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>'
+    '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>'
+    '<cellXfs count="2">'
+    '<xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0" applyAlignment="1">'
+    '<alignment vertical="top" wrapText="1"/></xf>'
+    '<xf numFmtId="0" fontId="1" fillId="2" borderId="0" xfId="0" applyAlignment="1">'
+    '<alignment vertical="center" wrapText="1"/></xf>'
+    '</cellXfs>'
+    '<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>'
+    '</styleSheet>'
+)
+
+
+def write_xlsx(records, out_path, sheet_name="Localization"):
+    safe = "".join(c for c in sheet_name if c not in r'[]:*?/\\')[:31] or "Sheet1"
+    parts = {
+        "[Content_Types].xml":
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+            '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+            '<Default Extension="xml" ContentType="application/xml"/>'
+            '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>'
+            '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>'
+            '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>'
+            '</Types>',
+        "_rels/.rels":
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+            '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>'
+            '</Relationships>',
+        "xl/workbook.xml":
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" '
+            'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">'
+            f'<sheets><sheet name="{_xesc(safe)}" sheetId="1" r:id="rId1"/></sheets></workbook>',
+        "xl/_rels/workbook.xml.rels":
+            '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+            '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>'
+            '<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>'
+            '</Relationships>',
+        "xl/styles.xml": _STYLES_XML,
+        "xl/worksheets/sheet1.xml": _sheet_xml(records),
+    }
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as z:
+        for name, data in parts.items():
+            z.writestr(name, data)
+
+
+def write_csv(records, out_path):
+    with open(out_path, "w", newline="", encoding="utf-8-sig") as f:
+        w = csv.writer(f)
+        w.writerow(COLUMNS)
+        w.writerows(records)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("mapping", help="path to the mapping JSON (- for stdin)")
+    ap.add_argument("--out", default=".", help="output directory")
+    ap.add_argument("--slug", help="output basename (default: slug of mapping.screen)")
+    ap.add_argument("--channel", default="Mobile", help="Channel column value (default: Mobile)")
+    ap.add_argument("--taxonomy", help="JSON file describing your CMS group/module buckets "
+                                      "(merged over the neutral defaults; see the module docstring)")
+    ap.add_argument("--csv", action="store_true", help="also write a <slug>.localization.csv")
+    ap.add_argument("--csv-only", action="store_true", help="write only the CSV, skip the xlsx")
+    args = ap.parse_args()
+
+    global _TAXONOMY
+    _TAXONOMY = load_taxonomy(args.taxonomy)
+
+    raw = sys.stdin.read() if args.mapping == "-" else open(args.mapping, encoding="utf-8").read()
+    mapping = json.loads(raw)
+
+    slug = args.slug or slugify(mapping.get("screen"))
+    os.makedirs(args.out, exist_ok=True)
+    records = build_records(mapping, args.channel)
+
+    written = []
+    if not args.csv_only:
+        xlsx_path = os.path.join(args.out, f"{slug}.localization.xlsx")
+        write_xlsx(records, xlsx_path)
+        written.append(xlsx_path)
+    if args.csv or args.csv_only:
+        csv_path = os.path.join(args.out, f"{slug}.localization.csv")
+        write_csv(records, csv_path)
+        written.append(csv_path)
+
+    print(json.dumps({
+        "slug": slug,
+        "rows": len(records),
+        "columns": COLUMNS,
+        "channel": args.channel,
+        "written": [os.path.basename(p) for p in written],
+    }, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/pipeline/skills/shared/external/localization-reuse-map/scripts/fetch-annotations.py

@@ -0,0 +1,344 @@
+#!/usr/bin/env python3
+"""Fetch the content team's Final UX Writing annotations off the screen's Figma nodes.
+
+The CMS / content team writes the **final bilingual copy** as Figma Dev Mode
+annotations (category "Final UX Writing") directly on the text nodes, in the form
+`TR: <türkçe>\nEN: <english>`. The design text itself is usually a *placeholder*
+("Giriniz", "Lorem ipsum", "Ahmet Abdullah"), so the annotation  -  not the design
+text  -  is the content team's *actual* value. This script harvests them so the map
+can show an `İçerik (CMS)` column beside the new (resources) and legacy values.
+
+Three sources, in priority order (Figma changes constantly → live is primary):
+  1. REST  -  `GET https://api.figma.com/v1/files/<key>/nodes?ids=...`, header
+            `X-Figma-Token` (from --token, env FIGMA_ACCESS_TOKEN/FIGMA_TOKEN, or
+            the macOS keychain item `FIGMA_ACCESS_TOKEN`). Default.
+  2. MCP  -  `--from-mcp <raw.json>`: an already-captured Dev Mode dump (the host's
+            Figma plugin/`use_figma` output). No network, no rate limit  -  use it
+            for big runs or when REST is 429-throttled.
+  3. local  -  `--local <design-export-screen-dir>`: best-effort read of the in-repo
+            snapshot's `tree.json` (only if it carries `annotations`). The safety
+            net when neither API nor MCP is reachable; usually yields nothing, in
+            which case the CMS column is simply left blank (blank beats a guess).
+
+Why a script: parsing `TR:/EN:` labels out of a node tree across many nodes is
+pure IO + string work  -  slow and error-prone by hand. Read-only; touches no repo.
+
+Emits the `_annotations.json` contract (to --out or stdout):
+  { generatedAt, source, files[], auditedNodes[], count, withTr, withEn,
+    annotations: [ {nodeId, name, type, designText, raw, tr, en, mode} ] }
+
+The label→{tr,en} parser (`split_lang`) is a faithful port of the web skill's
+`lib/split-lang.mjs`, so iOS/Android and web stay byte-compatible on the rules.
+"""
+import argparse
+import datetime
+import json
+import os
+import re
+import ssl
+import subprocess
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+FIGMA_API = "https://api.figma.com/v1"
+CHUNK = 4  # Figma /nodes batches; mirrors the web extractor
+
+# --- label → {tr, en, mode}  -  verbatim port of lib/split-lang.mjs ----------
+# Annotation authors separate label from value with a colon, a hyphen, or the
+# en-dash their editor auto-inserts. Built from the codepoint so this file
+# carries no literal dash variant of its own.
+_DASHES = ':\\-' + chr(0x2013)
+RE_TR = re.compile(rf"^(?:tr|tr[kc]e|t[üu]rk[çc]e)\s*[{_DASHES}]\s*(.+)$", re.I)
+RE_EN = re.compile(rf"^(?:en|eng|ing|[iİ]ngilizce)\s*[{_DASHES}]\s*(.+)$", re.I)
+
+
+def split_lang(raw):
+    """Parse a Dev Mode annotation label into {tr, en, mode}.
+
+    Prefixed `TR:`/`EN:` lines win over position; otherwise line1=TR, line2=EN.
+    """
+    if not raw:
+        return {"tr": None, "en": None, "mode": "empty"}
+    lines = [ln.strip() for ln in re.split(r"\r?\n", raw)]
+    lines = [ln for ln in lines if ln]
+    tr = en = None
+    bare = []
+    for ln in lines:
+        m = RE_TR.match(ln)
+        if m and tr is None:
+            tr = m.group(1).strip()
+            continue
+        m = RE_EN.match(ln)
+        if m and en is None:
+            en = m.group(1).strip()
+            continue
+        bare.append(ln)
+    if tr is not None or en is not None:
+        bi = 0
+        if tr is None and bi < len(bare):
+            tr = bare[bi]
+            bi += 1
+        if en is None and bi < len(bare):
+            en = bare[bi]
+            bi += 1
+        return {"tr": tr, "en": en, "mode": "prefixed"}
+    if len(bare) >= 2:
+        return {"tr": bare[0], "en": bare[1], "mode": "two-line"}
+    if len(bare) == 1:
+        return {"tr": bare[0], "en": None, "mode": "single"}
+    return {"tr": None, "en": None, "mode": "empty"}
+
+
+def canon_id(s):
+    """`1234-56` (URL form) → `1234:56` (node-id form); trims."""
+    return re.sub(r"^(\d+)-(\d+)$", r"\1:\2", (s or "").strip())
+
+
+# --- annotation parsing ----------------------------------------------------
+def labels_of(node):
+    """The annotation label strings on a node (each `label` ?? `labelMarkdown`)."""
+    anns = node.get("annotations")
+    if not isinstance(anns, list):
+        return []
+    out = []
+    for a in anns:
+        if not isinstance(a, dict):
+            continue
+        lbl = a.get("label") or a.get("labelMarkdown") or ""
+        if lbl:
+            out.append(lbl)
+    return out
+
+
+def design_text(node):
+    if node.get("type") == "TEXT" and isinstance(node.get("characters"), str):
+        return node["characters"]
+    return node.get("name")
+
+
+def parse_item(node_id, name, ntype, dtext, labels):
+    """Run split_lang over each label; keep the first that yields tr or en."""
+    best = {"tr": None, "en": None, "mode": "empty"}
+    raw = ""
+    for lbl in (labels or []):
+        parsed = split_lang(lbl)
+        if parsed["tr"] is not None or parsed["en"] is not None:
+            best = parsed
+            raw = lbl
+            break
+        if not raw:
+            raw = lbl
+    return {
+        "nodeId": node_id,
+        "name": name,
+        "type": ntype,
+        "designText": dtext,
+        "raw": raw,
+        "tr": best["tr"],
+        "en": best["en"],
+        "mode": best["mode"],
+    }
+
+
+def walk_collect(node, out):
+    """Recurse a Figma node tree, collecting every node that carries annotations."""
+    labels = labels_of(node)
+    if labels:
+        out.append(parse_item(node.get("id"), node.get("name"),
+                              node.get("type"), design_text(node), labels))
+    for child in node.get("children", []) or []:
+        walk_collect(child, out)
+
+
+# --- sources ---------------------------------------------------------------
+def figma_token(args):
+    if args.token:
+        return args.token
+    for env in ("FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN"):
+        v = os.environ.get(env)
+        if v:
+            return v.strip()
+    try:
+        r = subprocess.run(
+            ["security", "find-generic-password", "-s", "FIGMA_ACCESS_TOKEN", "-w"],
+            capture_output=True, text=True)
+        if r.returncode == 0 and r.stdout.strip():
+            return r.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def http_get_json(url, headers, ca_file):
+    ctx = ssl.create_default_context(cafile=ca_file) if ca_file else ssl.create_default_context()
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(req, context=ctx, timeout=60) as r:
+            return json.load(r)
+    except urllib.error.HTTPError as e:
+        if e.code == 429:
+            sys.exit("Figma 429 (rate-limited)  -  re-run with the MCP dump instead: "
+                     "--from-mcp <raw.json>.")
+        body = e.read()[:200]
+        sys.exit(f"Figma HTTP {e.code} for {url}: {body!r}")
+    except urllib.error.URLError as e:
+        msg = str(getattr(e, "reason", e))
+        if re.search(r"CERTIFICATE|ISSUER|SELF.SIGNED|UNABLE_TO|CERT", msg, re.I):
+            sys.exit(
+                "TLS verification failed. Behind a corporate proxy, export the system "
+                "roots and pass --ca-file:\n"
+                "  security find-certificate -a -p /System/Library/Keychains/"
+                "SystemRootCertificates.keychain > /tmp/ca.pem\n"
+                "  security find-certificate -a -p /Library/Keychains/System.keychain "
+                ">> /tmp/ca.pem\n"
+                "  ... --ca-file /tmp/ca.pem")
+        sys.exit(f"Figma request failed: {msg}")
+
+
+def from_rest(file_key, node_ids, token, ca_file):
+    if not token:
+        sys.exit("No Figma token  -  pass --token, set FIGMA_ACCESS_TOKEN, or add the "
+                 "keychain item FIGMA_ACCESS_TOKEN (or use --from-mcp / --local).")
+    headers = {"X-Figma-Token": token}
+    collected = []
+    ids = [canon_id(n) for n in node_ids]
+    for i in range(0, len(ids), CHUNK):
+        batch = ids[i:i + CHUNK]
+        q = ",".join(urllib.parse.quote(n, safe="") for n in batch)
+        data = http_get_json(f"{FIGMA_API}/files/{file_key}/nodes?ids={q}", headers, ca_file)
+        for nid in batch:
+            entry = (data.get("nodes") or {}).get(nid)
+            doc = entry.get("document") if isinstance(entry, dict) else None
+            if doc:
+                walk_collect(doc, collected)
+    return collected, "rest"
+
+
+def from_mcp(path):
+    with open(path, encoding="utf-8") as fh:
+        dump = json.load(fh)
+    items = dump if isinstance(dump, list) else (dump.get("annotations") or dump.get("items") or [])
+    collected = []
+    files = []
+    for it in items:
+        fk = it.get("fileKey")
+        if fk and fk not in files:
+            files.append(fk)
+        labels = it.get("labels")
+        if labels is None and it.get("raw") is not None:
+            labels = [it["raw"]]
+        collected.append(parse_item(it.get("nodeId"), it.get("name"), it.get("type"),
+                                    it.get("designText"), labels or []))
+    return collected, "mcp", files
+
+
+def from_local(screen_dir):
+    """Best-effort: read annotations from a design-export tree.json if it has any."""
+    tree = os.path.join(screen_dir, "tree.json")
+    if not os.path.isfile(tree):
+        return [], "local"
+    with open(tree, encoding="utf-8") as fh:
+        data = json.load(fh)
+    roots = data if isinstance(data, list) else [data]
+    collected = []
+    for root in roots:
+        if isinstance(root, dict):
+            walk_collect(root, collected)
+    return collected, "local"
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--file", help="Figma fileKey (REST)")
+    ap.add_argument("--nodes", help="comma-separated node-ids (REST), e.g. '10065:56313,10065:56329'")
+    ap.add_argument("--mapping", help="a mapping JSON to read figmaFileKey + figmaNodes from")
+    ap.add_argument("--from-mcp", dest="from_mcp", help="captured Dev Mode dump (MCP path)")
+    ap.add_argument("--local", help="design-export screen dir (fallback; reads tree.json)")
+    ap.add_argument("--source", choices=["auto", "rest", "mcp", "local"], default="auto",
+                    help="force a source; 'auto' tries REST then --local (default)")
+    ap.add_argument("--token", help="Figma token (else env / keychain)")
+    ap.add_argument("--ca-file", help="CA bundle for TLS behind a corporate proxy")
+    ap.add_argument("--out", help="write _annotations.json here (default: stdout)")
+    args = ap.parse_args()
+
+    file_key = args.file
+    node_ids = [n.strip() for n in (args.nodes or "").split(",") if n.strip()]
+    if args.mapping:
+        with open(args.mapping, encoding="utf-8") as fh:
+            m = json.load(fh)
+        file_key = file_key or m.get("figmaFileKey")
+        if not node_ids:
+            node_ids = [str(n) for n in (m.get("figmaNodes") or [])]
+
+    files = [file_key] if file_key else []
+    source = args.source
+
+    if args.from_mcp or source == "mcp":
+        if not args.from_mcp:
+            ap.error("--source mcp needs --from-mcp <raw.json>")
+        collected, source, mcp_files = from_mcp(args.from_mcp)
+        files = mcp_files or files
+    elif source == "local":
+        if not args.local:
+            ap.error("--source local needs --local <dir>")
+        collected, source = from_local(args.local)
+    elif source == "rest":
+        if not (file_key and node_ids):
+            ap.error("REST needs --file and --nodes (or --mapping)")
+        collected, source = from_rest(file_key, node_ids, figma_token(args), args.ca_file)
+    else:  # auto: REST first, fall back to --local
+        if file_key and node_ids and figma_token(args):
+            try:
+                collected, source = from_rest(file_key, node_ids, figma_token(args), args.ca_file)
+            except SystemExit:
+                if not args.local:
+                    raise
+                sys.stderr.write("# REST failed  -  falling back to --local\n")
+                collected, source = from_local(args.local)
+        elif args.local:
+            collected, source = from_local(args.local)
+        else:
+            ap.error("nothing to do  -  supply --file/--nodes (or --mapping) for REST, "
+                     "--from-mcp for MCP, or --local for the snapshot fallback")
+
+    # de-dup by nodeId, keep first (REST returns each requested node once anyway)
+    seen = set()
+    deduped = []
+    for a in collected:
+        nid = a.get("nodeId")
+        if nid in seen:
+            continue
+        seen.add(nid)
+        deduped.append(a)
+
+    out = {
+        "generatedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "source": source,
+        "files": files,
+        "auditedNodes": [canon_id(n) for n in node_ids],
+        "count": len(deduped),
+        "withTr": sum(1 for a in deduped if a.get("tr") is not None),
+        "withEn": sum(1 for a in deduped if a.get("en") is not None),
+        "annotations": deduped,
+    }
+
+    text = json.dumps(out, ensure_ascii=False, indent=2)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+        sys.stderr.write(f"# {out['count']} annotated node(s) "
+                         f"(tr={out['withTr']} en={out['withEn']}, source={source}) → {args.out}\n")
+    else:
+        sys.stdout.write(text + "\n")
+
+    only_tr = [a["nodeId"] for a in deduped if a.get("tr") and not a.get("en")]
+    if only_tr:
+        sys.stderr.write(f"# {len(only_tr)} annotation(s) have TR but no EN "
+                         "(flag back to the content team): " + ", ".join(only_tr) + "\n")
+
+
+if __name__ == "__main__":
+    main()