@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/scripts/figma-subcomponent-graph.py

@@ -0,0 +1,391 @@
+#!/usr/bin/env python3
+"""
+Figma Sub-Component Graph Generator
+
+Queries the Figma REST API to discover which components use other components
+as instances (sub-components). Produces sub-component-graph.json.
+
+Data flow:
+    1. Read component-catalog.json (source of truth for component list)
+    2. For each Figma file, batch-fetch node trees via REST API
+    3. Walk each node tree for INSTANCE children
+    4. Resolve INSTANCE.componentId → catalog component via response metadata
+    5. Write sub-component-graph.json
+
+Usage:
+    python3 figma-subcomponent-graph.py [--dry-run] [--output path] [--skip-assets]
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+import urllib.parse
+import urllib.request
+
+FIGMA_API = "https://api.figma.com/v1"
+BATCH_SIZE = 25
+RATE_DELAY = 1.0  # seconds between API calls (respect rate limits)
+
+
+def get_token():
+    """Retrieve Figma API token from macOS Keychain."""
+    r = subprocess.run(
+        ["security", "find-generic-password", "-a", os.environ["USER"],
+         "-s", "FIGMA_ACCESS_TOKEN", "-w"],
+        capture_output=True, text=True, check=True
+    )
+    return r.stdout.strip()
+
+
+def api_get(token, path):
+    """GET request to Figma REST API."""
+    url = f"{FIGMA_API}{path}"
+    req = urllib.request.Request(url)
+    req.add_header("X-Figma-Token", token)
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", errors="replace")[:300]
+        raise RuntimeError(f"Figma API {e.code}: {body}")
+
+
+def extract_file_key(figma_url):
+    """Extract fileKey from a Figma design URL."""
+    m = re.search(r'/design/([^/]+)/', figma_url)
+    return m.group(1) if m else None
+
+
+def sanitize_type_name(name):
+    """
+    Replicate FigmaRegistryUtility.sanitizeTypeName() in Python.
+    Splits on non-alphanumeric, PascalCases each part, joins.
+    """
+    parts = re.split(r'[^a-zA-Z0-9]+', name)
+    result = []
+    for part in parts:
+        if not part:
+            continue
+        has_upper = any(c.isupper() for c in part)
+        has_lower = any(c.islower() for c in part)
+        if has_upper and has_lower:
+            result.append(part[0].upper() + part[1:])
+        else:
+            result.append(part[0].upper() + part[1:].lower())
+    return "".join(result)
+
+
+def find_instances(node):
+    """Recursively find all INSTANCE componentIds in a node subtree."""
+    found = set()
+    if not isinstance(node, dict):
+        return found
+    if node.get("type") == "INSTANCE":
+        cid = node.get("componentId")
+        if cid:
+            found.add(cid)
+    for child in node.get("children", []):
+        found |= find_instances(child)
+    return found
+
+
+def find_catalog(script_dir):
+    """Locate component-catalog.json from various possible working directories."""
+    candidates = [
+        os.path.join(script_dir, "..", "..", "..", "..",
+                     "{repos.packagesContainer}/Packages/"
+                     "{project.slug}-common/"
+                     "Shared/Figma/Generated/component-catalog.json"),
+        "{repos.packagesContainer}/Packages/"
+        "{project.slug}-common/"
+        "Shared/Figma/Generated/component-catalog.json",
+        "Shared/Figma/Generated/component-catalog.json",
+    ]
+    for c in candidates:
+        p = os.path.normpath(c)
+        if os.path.isfile(p):
+            return p
+    return None
+
+
+def find_output_dir(script_dir):
+    """Locate Shared/Figma/ directory for output."""
+    candidates = [
+        os.path.join(script_dir, "..", "..", "..", "..",
+                     "{repos.packagesContainer}/Packages/"
+                     "{project.slug}-common/Shared/Figma"),
+        "{repos.packagesContainer}/Packages/"
+        "{project.slug}-common/Shared/Figma",
+        "Shared/Figma",
+    ]
+    for c in candidates:
+        p = os.path.normpath(c)
+        if os.path.isdir(p):
+            return p
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate sub-component dependency graph from Figma REST API")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Preview API calls without executing")
+    parser.add_argument("--output", help="Override output file path")
+    parser.add_argument("--skip-assets", action="store_true",
+                        help="Skip Visual Assets file (icons/flags rarely have sub-components)")
+    parser.add_argument("--verbose", action="store_true",
+                        help="Print detailed progress")
+    args = parser.parse_args()
+
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+
+    # --- 1. Load catalog ---
+    cat_path = find_catalog(script_dir)
+    if not cat_path:
+        print("ERROR: component-catalog.json not found")
+        print("Run: FigmaRegistryUtility catalog")
+        sys.exit(1)
+
+    with open(cat_path) as f:
+        catalog = json.load(f)
+
+    print(f"Catalog: {cat_path}")
+    print(f"Total:   {catalog['summary']['totalComponents']} components")
+
+    # --- 2. Build lookup tables ---
+    # catalog_by_node: nodeId → {name, figmaName, fileKey}
+    # catalog_by_name: sanitizedName → nodeId
+    # file_groups: fileKey → [(nodeId, name, fileLabel), ...]
+    catalog_by_node = {}
+    catalog_by_name = {}
+    file_groups = {}
+
+    for file_entry in catalog["files"]:
+        file_label = file_entry["fileLabel"]
+        for page in file_entry["pages"]:
+            for comp in page["components"]:
+                name = comp["name"]
+                node_id = comp["nodeId"]
+                figma_url = comp.get("figmaUrl", "")
+                file_key = extract_file_key(figma_url)
+
+                catalog_by_node[node_id] = {
+                    "name": name,
+                    "figmaName": comp.get("figmaName", ""),
+                    "fileKey": file_key,
+                    "fileLabel": file_label,
+                }
+                catalog_by_name[name] = node_id
+
+                if file_key:
+                    if args.skip_assets and file_label == "Visual Assets":
+                        continue
+                    file_groups.setdefault(file_key, {
+                        "label": file_label,
+                        "components": []
+                    })["components"].append((node_id, name))
+
+    print(f"Files:   {len(file_groups)}")
+    for fk, fg in file_groups.items():
+        print(f"  {fg['label']}: {len(fg['components'])} components ({fk[:8]}...)")
+
+    if args.dry_run:
+        total_batches = sum(
+            (len(fg["components"]) + BATCH_SIZE - 1) // BATCH_SIZE
+            for fg in file_groups.values()
+        )
+        print(f"\n[DRY RUN] Would make ~{total_batches} API requests")
+        print(f"[DRY RUN] Rate: {RATE_DELAY}s delay → ~{total_batches * RATE_DELAY:.0f}s total")
+        return
+
+    # --- 3. Fetch from Figma REST API ---
+    token = get_token()
+    graph = {}  # nodeId → {name, subComponents: [{nodeId, name}], instanceCount}
+    errors = []
+    api_calls = 0
+
+    for file_key, fg in file_groups.items():
+        file_label = fg["label"]
+        components = fg["components"]
+        print(f"\n{'='*60}")
+        print(f"File: {file_label} ({len(components)} components)")
+        print(f"{'='*60}")
+
+        node_ids = [nid for nid, _ in components]
+
+        for i in range(0, len(node_ids), BATCH_SIZE):
+            batch = node_ids[i:i + BATCH_SIZE]
+            batch_num = i // BATCH_SIZE + 1
+            total_batches = (len(node_ids) + BATCH_SIZE - 1) // BATCH_SIZE
+
+            ids_param = urllib.parse.quote(",".join(batch))
+            path = f"/files/{file_key}/nodes?ids={ids_param}"
+
+            print(f"  Batch {batch_num}/{total_batches} ({len(batch)} nodes)...", end=" ", flush=True)
+
+            try:
+                data = api_get(token, path)
+                api_calls += 1
+            except Exception as e:
+                print(f"ERROR: {e}")
+                errors.append({"batch": batch, "error": str(e)})
+                time.sleep(RATE_DELAY)
+                continue
+
+            nodes_data = data.get("nodes", {})
+            batch_subs = 0
+
+            for nid in batch:
+                node_result = nodes_data.get(nid)
+                if not node_result:
+                    graph[nid] = {
+                        "name": catalog_by_node[nid]["name"],
+                        "subComponents": [],
+                        "instanceCount": 0,
+                        "error": "node not returned"
+                    }
+                    continue
+
+                doc = node_result.get("document", {})
+                components_map = node_result.get("components", {})
+                component_sets_map = node_result.get("componentSets", {})
+
+                # Find all INSTANCE componentIds in this subtree
+                instance_ids = find_instances(doc)
+
+                # Resolve each instance to a catalog component
+                sub_components = []
+                seen = set()
+
+                for cid in instance_ids:
+                    # Look up in response components map
+                    comp_meta = components_map.get(cid, {})
+                    comp_set_id = comp_meta.get("componentSetId")
+
+                    # The "real" component is the COMPONENT_SET if it exists,
+                    # otherwise the COMPONENT itself
+                    resolved_id = comp_set_id if comp_set_id else cid
+
+                    # Check if resolved ID is in our catalog
+                    if resolved_id in catalog_by_node and resolved_id != nid:
+                        if resolved_id not in seen:
+                            seen.add(resolved_id)
+                            sub_components.append({
+                                "nodeId": resolved_id,
+                                "name": catalog_by_node[resolved_id]["name"]
+                            })
+                        continue
+
+                    # Fallback: try matching by sanitized name
+                    raw_name = comp_meta.get("name", "")
+                    if not raw_name and comp_set_id and comp_set_id in component_sets_map:
+                        raw_name = component_sets_map[comp_set_id].get("name", "")
+
+                    if raw_name:
+                        sanitized = sanitize_type_name(raw_name)
+                        matched_nid = catalog_by_name.get(sanitized)
+                        if matched_nid and matched_nid != nid and matched_nid not in seen:
+                            seen.add(matched_nid)
+                            sub_components.append({
+                                "nodeId": matched_nid,
+                                "name": sanitized
+                            })
+
+                sub_components.sort(key=lambda x: x["name"])
+                comp_name = catalog_by_node[nid]["name"]
+
+                graph[nid] = {
+                    "name": comp_name,
+                    "subComponents": sub_components,
+                    "instanceCount": len(instance_ids),
+                }
+
+                if sub_components:
+                    batch_subs += 1
+                    if args.verbose:
+                        names = [s["name"] for s in sub_components]
+                        print(f"\n    {comp_name} → {names}")
+
+            print(f"OK ({batch_subs} with subs)")
+            time.sleep(RATE_DELAY)
+
+    # --- 4. Compute reverse map (usedBy) ---
+    used_by = {}  # nodeId → [nodeId, ...]
+    for nid, entry in graph.items():
+        for sub in entry["subComponents"]:
+            used_by.setdefault(sub["nodeId"], []).append(nid)
+
+    for nid in used_by:
+        used_by[nid] = sorted(
+            used_by[nid],
+            key=lambda x: graph.get(x, {}).get("name", "")
+        )
+
+    # --- 5. Build output ---
+    with_subs = sum(1 for v in graph.values() if v["subComponents"])
+    used_as_sub = len(used_by)
+
+    output = {
+        "version": "1.0",
+        "generatedAt": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "source": "Figma REST API /files/:key/nodes — INSTANCE child inspection",
+        "stats": {
+            "totalComponents": len(graph),
+            "componentsWithSubComponents": with_subs,
+            "componentsUsedAsSub": used_as_sub,
+            "apiCalls": api_calls,
+            "errors": len(errors),
+        },
+        "graph": {},
+    }
+
+    for nid, entry in sorted(graph.items(), key=lambda x: x[1]["name"]):
+        node_entry = {
+            "name": entry["name"],
+            "subComponents": [s["name"] for s in entry["subComponents"]],
+        }
+        # Add usedBy if this component is used by others
+        if nid in used_by:
+            node_entry["usedBy"] = [
+                graph[uid]["name"] for uid in used_by[nid] if uid in graph
+            ]
+        # Only include instanceCount if there are unresolved instances
+        unresolved = entry["instanceCount"] - len(entry["subComponents"])
+        if unresolved > 0:
+            node_entry["unresolvedInstances"] = unresolved
+        if entry.get("error"):
+            node_entry["error"] = entry["error"]
+
+        output["graph"][nid] = node_entry
+
+    # --- 6. Write output ---
+    out_path = args.output
+    if not out_path:
+        out_dir = find_output_dir(script_dir)
+        if out_dir:
+            out_path = os.path.join(out_dir, "sub-component-graph.json")
+        else:
+            out_path = "sub-component-graph.json"
+
+    with open(out_path, "w") as f:
+        json.dump(output, f, indent=2, sort_keys=False, ensure_ascii=False)
+        f.write("\n")
+
+    print(f"\n{'='*60}")
+    print(f"Written: {out_path}")
+    print(f"Components:        {len(graph)}")
+    print(f"With sub-comps:    {with_subs}")
+    print(f"Used as sub-comp:  {used_as_sub}")
+    print(f"API calls:         {api_calls}")
+    if errors:
+        print(f"Errors:            {len(errors)}")
+        for err in errors[:5]:
+            print(f"  {err['error'][:100]}")
+
+
+if __name__ == "__main__":
+    main()

package/pipeline/skills/figma-ios/figma-to-component/scripts/figma-update.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""figma-update.py — detect Figma-side changes and mark components stale.
+
+Fetches the file-level `lastModified` timestamp from the Figma REST API
+(`GET /v1/files/:key`) and compares it to the `figmaUpdatedAt` stored in
+each component registry entry. If Figma has newer data, the script calls
+`lib.registry_writer.mark_stale()` for every registry entry that belongs
+to that file — setting `status.<platform>.stale = true` on any platform
+that has been implemented.
+
+This is a FILE-LEVEL check. Any change anywhere in the Figma file will
+mark all components in that file as stale. Conservative but correct:
+never misses a real change, only produces false positives that a
+developer can acknowledge by re-running Phase 4 (which clears stale via
+`set_implemented`'s side effect).
+
+Usage:
+    # Check one file explicitly
+    python3 figma-update.py --file-key ps4xrJzhn7WNbfkZs895Bi
+
+    # Scan every unique fileKey across the registry
+    python3 figma-update.py --all
+
+    # Dry-run (no writes, prints what would change)
+    python3 figma-update.py --all --dry-run
+
+    # Limit the number of registry entries touched (for smoke tests)
+    python3 figma-update.py --all --limit 10
+
+Token: FIGMA_ACCESS_TOKEN env var, or macOS Keychain FIGMA_ACCESS_TOKEN.
+
+Exit codes:
+    0 — Success
+    1 — Error (network, auth, bad registry files, etc.)
+"""
+
+import argparse
+import http.client
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional
+
+sys.path.insert(0, str(Path(__file__).parent))
+from lib.registry_writer import mark_stale  # noqa: E402
+
+
+FIGMA_API_HOST = "api.figma.com"
+
+
+# --------------------------------------------------------------------
+# Repo layout helpers
+# --------------------------------------------------------------------
+
+def find_repo_root() -> Path:
+    p = Path.cwd()
+    while p != p.parent:
+        if (p / ".git").exists():
+            return p
+        p = p.parent
+    return Path.cwd()
+
+
+def default_registry_dir() -> Path:
+    return (
+        find_repo_root()
+        / "{repos.packagesContainer}"
+        / "Packages"
+        / "{project.slug}-common"
+        / "Shared"
+        / "Figma"
+        / "Components"
+    )
+
+
+# --------------------------------------------------------------------
+# Figma API (injectable for tests)
+# --------------------------------------------------------------------
+
+def load_figma_token() -> Optional[str]:
+    """FIGMA_ACCESS_TOKEN env var first, then macOS Keychain."""
+    env_token = os.environ.get("FIGMA_ACCESS_TOKEN")
+    if env_token:
+        return env_token
+
+    try:
+        result = subprocess.run(
+            [
+                "security", "find-generic-password",
+                "-a", os.environ.get("USER", ""),
+                "-s", "FIGMA_ACCESS_TOKEN",
+                "-w",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except (subprocess.SubprocessError, FileNotFoundError):
+        pass
+    return None
+
+
+def fetch_file_last_modified(file_key: str, token: str) -> str:
+    """Call Figma REST API and return the file's lastModified timestamp.
+
+    Uses the `depth=1` parameter to minimize payload — we only need the
+    top-level metadata, not the full node tree. Figma returns a JSON
+    object with a top-level `lastModified` ISO 8601 string.
+
+    Raises:
+        RuntimeError on HTTP error, missing field, or auth failure.
+    """
+    conn = http.client.HTTPSConnection(FIGMA_API_HOST, timeout=30)
+    try:
+        conn.request(
+            "GET",
+            f"/v1/files/{file_key}?depth=1",
+            headers={"X-Figma-Token": token},
+        )
+        response = conn.getresponse()
+        body = response.read().decode("utf-8")
+        if response.status != 200:
+            raise RuntimeError(
+                f"Figma API returned {response.status}: {body[:200]}"
+            )
+        data = json.loads(body)
+        last_modified = data.get("lastModified")
+        if not last_modified:
+            raise RuntimeError("Figma response missing lastModified field")
+        return last_modified
+    finally:
+        conn.close()
+
+
+# --------------------------------------------------------------------
+# Core logic (pure, no network)
+# --------------------------------------------------------------------
+
+def scan_registry_for_file_keys(registry_dir: Path) -> dict[str, list[str]]:
+    """Walk the registry directory and return { fileKey: [node_id, ...] }.
+
+    Skips files that are not valid JSON or lack nodeId/fileKey.
+    """
+    by_file: dict[str, list[str]] = {}
+    if not registry_dir.exists():
+        return by_file
+
+    for path in sorted(registry_dir.glob("*.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        node_id = data.get("nodeId")
+        file_key = data.get("fileKey")
+        if not node_id or not file_key:
+            continue
+        by_file.setdefault(file_key, []).append(node_id)
+    return by_file
+
+
+def update_file_components(
+    registry_dir: Path,
+    file_key: str,
+    node_ids: list[str],
+    new_last_modified: str,
+    dry_run: bool,
+    limit: Optional[int] = None,
+) -> dict:
+    """For every node in `node_ids`, call mark_stale if not a dry run.
+
+    Returns a summary dict: { updated: [node_id...], skipped: [node_id...] }.
+    """
+    updated: list[str] = []
+    skipped: list[str] = []
+
+    to_process = node_ids if limit is None else node_ids[:limit]
+
+    for node_id in to_process:
+        node_id_dash = node_id.replace(":", "-")
+        path = registry_dir / f"{node_id_dash}.json"
+        if not path.exists():
+            skipped.append(node_id)
+            continue
+
+        if dry_run:
+            # Read and compare without writing
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                skipped.append(node_id)
+                continue
+            prev = data.get("figmaUpdatedAt")
+            if prev and prev >= new_last_modified:
+                skipped.append(node_id)
+            else:
+                updated.append(node_id)
+        else:
+            changed = mark_stale(registry_dir, node_id, new_last_modified)
+            if changed:
+                updated.append(node_id)
+            else:
+                skipped.append(node_id)
+
+    return {
+        "fileKey": file_key,
+        "lastModified": new_last_modified,
+        "updated": updated,
+        "skipped": skipped,
+        "limit_applied": limit,
+    }
+
+
+# --------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Scan registry and mark components stale when Figma has newer data",
+    )
+    scope = parser.add_mutually_exclusive_group(required=True)
+    scope.add_argument("--file-key", help="Check one specific Figma file")
+    scope.add_argument("--all", action="store_true", help="Check every unique fileKey in the registry")
+
+    parser.add_argument("--registry-dir", help="Override registry directory path")
+    parser.add_argument("--dry-run", action="store_true", help="Print changes without writing")
+    parser.add_argument("--limit", type=int, help="Max nodes to touch per file (smoke-test safety)")
+    parser.add_argument("--token", help="Figma API token (overrides env var and keychain)")
+    args = parser.parse_args()
+
+    registry_dir = Path(args.registry_dir) if args.registry_dir else default_registry_dir()
+    if not registry_dir.exists():
+        print(f"ERROR: registry directory does not exist: {registry_dir}", file=sys.stderr)
+        return 1
+
+    token = args.token or load_figma_token()
+    if not token:
+        print("ERROR: no Figma token found (set FIGMA_ACCESS_TOKEN or use --token)", file=sys.stderr)
+        return 1
+
+    if args.file_key:
+        by_file: dict[str, list[str]] = scan_registry_for_file_keys(registry_dir)
+        nodes_in_file = by_file.get(args.file_key, [])
+        if not nodes_in_file:
+            print(
+                json.dumps({"status": "ok", "message": f"no registry entries for {args.file_key}"}),
+            )
+            return 0
+        file_keys = {args.file_key: nodes_in_file}
+    else:
+        file_keys = scan_registry_for_file_keys(registry_dir)
+
+    summary: list[dict] = []
+    total_updated = 0
+    total_skipped = 0
+
+    for fk, nodes in file_keys.items():
+        try:
+            last_modified = fetch_file_last_modified(fk, token)
+        except RuntimeError as e:
+            print(f"ERROR fetching {fk}: {e}", file=sys.stderr)
+            return 1
+
+        file_summary = update_file_components(
+            registry_dir=registry_dir,
+            file_key=fk,
+            node_ids=nodes,
+            new_last_modified=last_modified,
+            dry_run=args.dry_run,
+            limit=args.limit,
+        )
+        summary.append(file_summary)
+        total_updated += len(file_summary["updated"])
+        total_skipped += len(file_summary["skipped"])
+
+    print(json.dumps({
+        "status": "ok",
+        "dry_run": args.dry_run,
+        "total_files": len(summary),
+        "total_updated": total_updated,
+        "total_skipped": total_skipped,
+        "files": summary,
+    }, indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/pipeline/skills/figma-ios/figma-to-component/scripts/lib/__init__.py

@@ -0,0 +1 @@
+"""Shared helpers for figma-to-swiftui pipeline scripts."""