@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -1,391 +0,0 @@
-#!/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

@@ -1,292 +0,0 @@
-#!/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

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