@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/scripts/confluence-component-status-upload.py

@@ -0,0 +1,768 @@
+#!/usr/bin/env python3
+"""
+Generates and uploads a Component Implementation Status page to Confluence.
+
+Step 1: Build a unified component-index.json from:
+    - component-catalog.json (catalog: names, variants, figma URLs, file/page grouping)
+    - Components/{nodeId}.json (registry: codeConnect, confluence links, skip, componentName)
+    - sub-component-graph.json (graph: sub-component dependencies)
+Step 2: Generate XHTML from the index.
+Step 3: Upload to Confluence (delete + recreate, no version bloat).
+
+Usage:
+    python3 .instructions/figma/figma-to-swiftui/scripts/confluence-component-status.py [--dry-run] [--output status.html]
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.parse
+import urllib.request
+
+BASE_URL = "{confluence.baseUrl}"
+SPACE = "DK"
+PAGE_TITLE = "Component Implementation Status"
+
+
+def get_token():
+    r = subprocess.run(
+        ["security", "find-generic-password", "-a", os.environ["USER"],
+         "-s", "CONFLUENCE_TOKEN", "-w"],
+        capture_output=True, text=True, check=True
+    )
+    return r.stdout.strip()
+
+
+def xml_escape(t):
+    return t.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def node_anchor(node_id):
+    """Convert nodeId like '6893:6879' to anchor-safe 'comp-6893-6879'."""
+    return "comp-" + node_id.replace(":", "-")
+
+
+# -------------------------------------------------------------------
+# STEP 1: Build unified component index
+# -------------------------------------------------------------------
+
+def build_component_index(figma_dir):
+    """
+    Merge catalog + registry + graph into one index.
+    Returns: {
+        "components": { nodeId: { ...merged fields... } },
+        "files": [ { fileLabel, pages: [ { pageName, nodeIds: [...] } ] } ],
+        "summary": { ... }
+    }
+    Also builds name → nodeId lookup for sub-component resolution.
+    """
+    catalog_path = os.path.join(figma_dir, "Generated", "component-catalog.json")
+    graph_path = os.path.join(figma_dir, "sub-component-graph.json")
+    components_dir = os.path.join(figma_dir, "Components")
+
+    # --- Load catalog ---
+    with open(catalog_path) as f:
+        catalog = json.load(f)
+
+    # Flat component dict keyed by nodeId
+    components = {}
+    files = []
+    for file_entry in catalog["files"]:
+        file_pages = []
+        for page in file_entry["pages"]:
+            page_node_ids = []
+            for comp in page["components"]:
+                nid = comp["nodeId"]
+                components[nid] = {
+                    "nodeId": nid,
+                    "name": comp["name"],
+                    "figmaName": comp.get("figmaName", ""),
+                    "figmaUrl": comp.get("figmaUrl", ""),
+                    "variantCount": comp.get("variantCount", 0),
+                    "codeConnect": comp.get("codeConnect", {}),
+                    "subComponents": [],
+                    # Registry fields — filled below
+                    "componentName": {},
+                    "skip": False,
+                    "confluence": {},
+                }
+                page_node_ids.append(nid)
+            file_pages.append({
+                "pageName": page["pageName"],
+                "nodeIds": page_node_ids,
+            })
+        files.append({
+            "fileLabel": file_entry["fileLabel"],
+            "totalComponents": file_entry["totalComponents"],
+            "pages": file_pages,
+        })
+
+    # --- Load ALL registry files (source of truth for codeConnect, skip, confluence, componentName) ---
+    registry_count = 0
+    if os.path.isdir(components_dir):
+        for fname in os.listdir(components_dir):
+            if not fname.endswith(".json"):
+                continue
+            fpath = os.path.join(components_dir, fname)
+            try:
+                with open(fpath) as f:
+                    reg = json.load(f)
+            except (json.JSONDecodeError, OSError):
+                continue
+            nid = reg.get("nodeId", fname[:-5].replace("-", ":"))
+            registry_count += 1
+
+            if nid in components:
+                # Merge registry into existing catalog entry
+                c = components[nid]
+                # Registry is source of truth for these fields
+                c["codeConnect"] = reg.get("codeConnect", c["codeConnect"])
+                c["componentName"] = reg.get("componentName", {})
+                c["skip"] = reg.get("skip", False)
+                c["confluence"] = reg.get("confluence", {})
+            else:
+                # Registry-only component (e.g. icons not in catalog)
+                ios_name = reg.get("componentName", {}).get("ios", "")
+                components[nid] = {
+                    "nodeId": nid,
+                    "name": ios_name or nid,
+                    "figmaName": "",
+                    "figmaUrl": "",
+                    "variantCount": 0,
+                    "codeConnect": reg.get("codeConnect", {}),
+                    "subComponents": [],
+                    "componentName": reg.get("componentName", {}),
+                    "skip": reg.get("skip", False),
+                    "confluence": reg.get("confluence", {}),
+                    "registryOnly": True,  # not in catalog
+                }
+
+    # --- Build name → nodeId lookup (multiple aliases per component) ---
+    name_to_nid = {}
+    # Secondary fuzzy lookup keyed by figmaName with separators (`/ _ -`) and
+    # whitespace stripped, lowercased. The Figma sub-component graph emits
+    # plain instance-names like "CardsFareAvailabilityFareTypes" — those won't
+    # match a catalog `figmaName` of "Cards/Fare/Availability/FareTypes" via
+    # the exact-match map below, but they collapse to the same key here.
+    # Used as a fallback when an exact lookup misses.
+    def _strip_key(s):
+        if not s:
+            return ""
+        return re.sub(r"[\s/_\-]+", "", s).lower()
+    fuzzy_to_nid = {}
+    for nid, c in components.items():
+        # Catalog display name
+        if c["name"]:
+            name_to_nid[c["name"]] = nid
+        # Figma name (e.g. "User", "CaretRight")
+        if c["figmaName"] and c["figmaName"] not in name_to_nid:
+            name_to_nid[c["figmaName"]] = nid
+        # iOS component name suffix: "Image.caretRight" → "caretRight"
+        cn = c.get("componentName", {})
+        ios_name = cn.get("ios", "") if isinstance(cn, dict) else cn or ""
+        if ios_name:
+            name_to_nid[ios_name] = nid
+            # Also strip "Image." prefix for matching graph names
+            if "." in ios_name:
+                suffix = ios_name.split(".", 1)[1]
+                if suffix not in name_to_nid:
+                    name_to_nid[suffix] = nid
+                # Case-insensitive: "caretRight" should match "CaretRight"
+                if suffix[0:1].upper() + suffix[1:] not in name_to_nid:
+                    name_to_nid[suffix[0:1].upper() + suffix[1:]] = nid
+        # Populate fuzzy lookup from every alias so collapse-keyed matches work.
+        for alias in (c["name"], c.get("figmaName"), ios_name):
+            k = _strip_key(alias)
+            if k and k not in fuzzy_to_nid:
+                fuzzy_to_nid[k] = nid
+
+    # --- Load sub-component graph and resolve names → nodeIds ---
+    graph_merged = 0
+    fuzzy_resolved = 0
+    if os.path.isfile(graph_path):
+        with open(graph_path) as f:
+            graph_data = json.load(f)
+        graph = graph_data.get("graph", {})
+        for nid, gdata in graph.items():
+            sub_names = gdata.get("subComponents", [])
+            if not sub_names:
+                continue
+            # Resolve sub-component names to nodeIds — exact match first,
+            # then fall back to the stripped/lowercased key. The fuzzy pass
+            # turns the previous {nodeId: null} entries (which silently
+            # bypass the readiness algorithm downstream) into real refs.
+            resolved_subs = []
+            for sname in sub_names:
+                sub_nid = name_to_nid.get(sname)
+                if not sub_nid:
+                    sub_nid = fuzzy_to_nid.get(_strip_key(sname))
+                    if sub_nid:
+                        fuzzy_resolved += 1
+                if sub_nid:
+                    resolved_subs.append({"nodeId": sub_nid, "name": sname})
+                else:
+                    resolved_subs.append({"nodeId": None, "name": sname})
+            if nid in components:
+                components[nid]["subComponents"] = resolved_subs
+                graph_merged += 1
+    if fuzzy_resolved:
+        print(f"  fuzzy-resolved {fuzzy_resolved} sub-component refs that exact-match would have left as null")
+
+    # --- Summary ---
+    total = sum(1 for c in components.values() if not c.get("registryOnly"))
+    total_variants = catalog["summary"].get("totalVariants", 0)
+
+    index = {
+        "components": components,
+        "nameLookup": name_to_nid,
+        "files": files,
+        "summary": {
+            "totalComponents": total,
+            "totalVariants": total_variants,
+            "registryFiles": registry_count,
+            "graphMerged": graph_merged,
+            "resolvedNames": len(name_to_nid),
+        },
+    }
+    return index
+
+
+# -------------------------------------------------------------------
+# STEP 2: Readiness + XHTML generation
+# -------------------------------------------------------------------
+
+READINESS_ICON = {"implemented": "✅", "ready": "🟢", "blocked": "🔴", "skipped": "⏭️"}
+READINESS_COLOR = {
+    "implemented": "#2196F3",  # blue
+    "ready": "#4CAF50",        # green
+    "blocked": "#F44336",      # red
+    "skipped": "#9E9E9E",      # gray
+}
+READINESS_ORDER = {"implemented": 0, "ready": 1, "blocked": 2, "skipped": 3}
+
+
+def compute_readiness(comp, components, platform="ios"):
+    """Readiness from the unified index."""
+    if comp.get("skip"):
+        return "skipped"
+    if comp.get("codeConnect", {}).get(platform, False):
+        return "implemented"
+    subs = comp.get("subComponents", [])
+    if not subs:
+        return "ready"
+    for sub in subs:
+        sub_nid = sub.get("nodeId")
+        if not sub_nid:
+            continue  # Unresolved name (not in catalog or registry) — doesn't block
+        sub_comp = components.get(sub_nid)
+        if not sub_comp:
+            continue
+        if sub_comp.get("skip"):
+            continue
+        if not sub_comp.get("codeConnect", {}).get(platform, False):
+            return "blocked"
+    return "ready"
+
+
+def make_anchor(anchor_id):
+    return (f'<ac:structured-macro ac:name="anchor">'
+            f'<ac:parameter ac:name="">{anchor_id}</ac:parameter>'
+            f'</ac:structured-macro>')
+
+
+def make_anchor_link(anchor_id, text, color=None):
+    """Confluence link-to-anchor on same page."""
+    if color:
+        return (f'<ac:link ac:anchor="{anchor_id}">'
+                f'<ac:link-body>'
+                f'<span style="color:{color}">{xml_escape(text)}</span>'
+                f'</ac:link-body>'
+                f'</ac:link>')
+    return (f'<ac:link ac:anchor="{anchor_id}">'
+            f'<ac:plain-text-link-body>'
+            f'<![CDATA[{text}]]>'
+            f'</ac:plain-text-link-body>'
+            f'</ac:link>')
+
+
+def platform_cell(comp, components, platform):
+    """Build iOS/Android cell: readiness icon + component name if connected."""
+    r = compute_readiness(comp, components, platform)
+    icon = READINESS_ICON.get(r, "⬜")
+    if r == "implemented":
+        display = comp.get("componentName", {}).get(platform) or comp["name"]
+        return f'{icon}&nbsp;&nbsp;<code>{xml_escape(display)}</code>'
+    if r == "skipped":
+        return f'{icon} <span style="color:#9E9E9E"><s>{xml_escape(comp["name"])}</s></span>'
+    return icon
+
+
+def generate_xhtml(index):
+    components = index["components"]
+    files = index["files"]
+    summary = index["summary"]
+    total = summary["totalComponents"]
+    total_variants = summary["totalVariants"]
+
+    # Collect catalog components (not registry-only) for counting
+    catalog_comps = [c for c in components.values() if not c.get("registryOnly")]
+
+    ios_impl = sum(1 for c in catalog_comps if compute_readiness(c, components, "ios") == "implemented")
+    ios_ready = sum(1 for c in catalog_comps if compute_readiness(c, components, "ios") == "ready")
+    ios_blocked = sum(1 for c in catalog_comps if compute_readiness(c, components, "ios") == "blocked")
+    ios_skipped = sum(1 for c in catalog_comps if compute_readiness(c, components, "ios") == "skipped")
+    android_impl = sum(1 for c in catalog_comps if compute_readiness(c, components, "android") == "implemented")
+    android_ready = sum(1 for c in catalog_comps if compute_readiness(c, components, "android") == "ready")
+    android_blocked = sum(1 for c in catalog_comps if compute_readiness(c, components, "android") == "blocked")
+    android_skipped = sum(1 for c in catalog_comps if compute_readiness(c, components, "android") == "skipped")
+
+    p = []
+
+    p.append(f'<p><em>Component implementation status — generated from unified component index '
+             f'({summary["resolvedNames"]} name aliases, {summary["registryFiles"]} registry files).</em></p>')
+    p.append(f'<p><strong>Legend:</strong> '
+             f'✅ Implemented (Code Connected) — shows component name | '
+             f'🟢 Ready for Development | '
+             f'🔴 Blocked (has unconnected sub-components) | '
+             f'⏭️ Skipped (will not be implemented)<br/>'
+             f'<strong>Sub-component colors:</strong> '
+             f'<span style="color:#2196F3">Blue = implemented</span> | '
+             f'<span style="color:#4CAF50">Green = ready</span> | '
+             f'<span style="color:#F44336">Red = blocked</span> | '
+             f'<span style="color:#9E9E9E">Gray = skipped or unresolved</span></p>')
+
+    # Script: find anchor (outside expand), open the nearest expand-container sibling, scroll
+    p.append('<ac:structured-macro ac:name="html">')
+    p.append('<ac:plain-text-body><![CDATA[<script>')
+    p.append("""(function(){
+  function openExpand(container){
+    if(!container||!container.classList.contains('expand-container'))return;
+    var body=container.querySelector('.expand-content');
+    if(body){body.style.display='block';body.classList.remove('expand-hidden');}
+    var ctrl=container.querySelector('.expand-control');
+    if(ctrl)ctrl.classList.add('expanded');
+  }
+  function expandAndScroll(id){
+    var el=document.getElementById(id);
+    if(!el)el=document.querySelector('.confluence-anchor-link[id="'+id+'"]');
+    if(!el)return false;
+    var sib=el;
+    while(sib){
+      if(sib.classList&&sib.classList.contains('expand-container')){openExpand(sib);break;}
+      sib=sib.nextElementSibling;
+    }
+    if(!sib){
+      var parent=el.parentElement;
+      while(parent){
+        var expands=parent.querySelectorAll('.expand-container');
+        if(expands.length>0){for(var i=0;i<expands.length;i++)openExpand(expands[i]);break;}
+        parent=parent.parentElement;
+      }
+    }
+    setTimeout(function(){el.scrollIntoView({behavior:'smooth',block:'start'});},150);
+    return true;
+  }
+  function onHash(){
+    var h=window.location.hash;
+    if(h&&h.length>1)expandAndScroll(decodeURIComponent(h.substring(1)));
+  }
+  window.addEventListener('hashchange',onHash);
+  if(document.readyState==='complete')setTimeout(onHash,500);
+  else window.addEventListener('load',function(){setTimeout(onHash,500);});
+})();""")
+    p.append('</script>]]></ac:plain-text-body>')
+    p.append('</ac:structured-macro>')
+
+    p.append('<hr/>')
+
+    p.append('<ac:structured-macro ac:name="toc">')
+    p.append('<ac:parameter ac:name="printable">true</ac:parameter>')
+    p.append('<ac:parameter ac:name="style">disc</ac:parameter>')
+    p.append('<ac:parameter ac:name="maxLevel">3</ac:parameter>')
+    p.append('<ac:parameter ac:name="minLevel">2</ac:parameter>')
+    p.append('</ac:structured-macro>')
+    p.append('<hr/>')
+
+    # --- Summary table ---
+    p.append('<h2>Summary</h2>')
+    p.append('<table><tbody>')
+    p.append('<tr><th>Metric</th><th>iOS</th><th>Android</th></tr>')
+    p.append(f'<tr><td>Total Components</td><td colspan="2">{total}</td></tr>')
+    p.append(f'<tr><td>✅ Implemented</td><td>{ios_impl}</td><td>{android_impl}</td></tr>')
+    p.append(f'<tr><td>🟢 Ready</td><td>{ios_ready}</td><td>{android_ready}</td></tr>')
+    p.append(f'<tr><td>🔴 Blocked</td><td>{ios_blocked}</td><td>{android_blocked}</td></tr>')
+    p.append(f'<tr><td>⏭️ Skipped</td><td>{ios_skipped}</td><td>{android_skipped}</td></tr>')
+    p.append(f'<tr><td>Total Variants</td><td colspan="2">{total_variants}</td></tr>')
+    effective_total = total - ios_skipped
+    effective_total_android = total - android_skipped
+    ios_pct = (100 * ios_impl // max(effective_total, 1))
+    android_pct = (100 * android_impl // max(effective_total_android, 1))
+    p.append(f'<tr><td>Progress</td><td>{ios_impl}/{effective_total} ({ios_pct}%)</td>'
+             f'<td>{android_impl}/{effective_total_android} ({android_pct}%)</td></tr>')
+    p.append('</tbody></table>')
+    p.append('<hr/>')
+
+    # --- Per file > page > component tables ---
+    for file_entry in files:
+        file_label = file_entry["fileLabel"]
+        file_total = file_entry["totalComponents"]
+
+        file_comps = [components[nid] for pg in file_entry["pages"] for nid in pg["nodeIds"]]
+        file_ios_impl = sum(1 for c in file_comps if compute_readiness(c, components, "ios") == "implemented")
+        file_ios_skipped = sum(1 for c in file_comps if compute_readiness(c, components, "ios") == "skipped")
+        file_ios_eff = file_total - file_ios_skipped
+        file_android_impl = sum(1 for c in file_comps if compute_readiness(c, components, "android") == "implemented")
+        file_android_skipped = sum(1 for c in file_comps if compute_readiness(c, components, "android") == "skipped")
+        file_android_eff = file_total - file_android_skipped
+
+        file_label_esc = xml_escape(file_label)
+        file_stats = f'iOS {file_ios_impl}/{file_ios_eff} / Android {file_android_impl}/{file_android_eff}'
+        if file_ios_eff == 0 and file_android_eff == 0:
+            # All skipped — no TOC entry, just a styled paragraph
+            p.append(f'<p><strong style="font-size:20px"><s>{file_label_esc} ({file_stats})</s></strong></p>')
+        else:
+            p.append(f'<h2>{file_label_esc} ({file_stats})</h2>')
+
+        for page_entry in file_entry["pages"]:
+            page_name = page_entry["pageName"]
+            page_comps = [components[nid] for nid in page_entry["nodeIds"]]
+            pg_ios_impl = sum(1 for c in page_comps if compute_readiness(c, components, "ios") == "implemented")
+            pg_ios_skipped = sum(1 for c in page_comps if compute_readiness(c, components, "ios") == "skipped")
+            pg_ios_eff = len(page_comps) - pg_ios_skipped
+            pg_android_impl = sum(1 for c in page_comps if compute_readiness(c, components, "android") == "implemented")
+            pg_android_skipped = sum(1 for c in page_comps if compute_readiness(c, components, "android") == "skipped")
+            pg_android_eff = len(page_comps) - pg_android_skipped
+
+            page_name_esc = xml_escape(page_name)
+            pg_stats = f'iOS {pg_ios_impl}/{pg_ios_eff} / Android {pg_android_impl}/{pg_android_eff}'
+            if pg_ios_eff == 0 and pg_android_eff == 0:
+                # All skipped — no TOC entry, just a styled paragraph
+                p.append(f'<p><strong style="font-size:16px"><s>{page_name_esc} ({pg_stats})</s></strong></p>')
+            else:
+                p.append(f'<h3>{page_name_esc} ({pg_stats})</h3>')
+
+            sorted_comps = sorted(page_comps, key=lambda c: (
+                READINESS_ORDER.get(compute_readiness(c, components, "ios"), 9), c["name"]))
+
+            # Anchors OUTSIDE expand — Confluence can't resolve anchors inside collapsed expand
+            for c in sorted_comps:
+                p.append(make_anchor(node_anchor(c["nodeId"])))
+
+            p.append('<ac:structured-macro ac:name="expand">')
+            p.append(f'<ac:parameter ac:name="title">{page_name_esc} — '
+                     f'iOS {pg_ios_impl}/{pg_ios_eff} / Android {pg_android_impl}/{pg_android_eff} '
+                     f'({len(page_comps)} components)</ac:parameter>')
+            p.append('<ac:rich-text-body>')
+            p.append('<table><tbody>')
+            p.append('<tr>'
+                     '<th>iOS</th>'
+                     '<th>Android</th>'
+                     '<th>Component</th>'
+                     '<th>Figma Component</th>'
+                     '<th>Figma Name</th>'
+                     '<th>Variants</th>'
+                     '<th>Sub-Components</th>'
+                     '</tr>')
+
+            for c in sorted_comps:
+                name_esc = xml_escape(c["name"])
+                figma_esc = xml_escape(c.get("figmaName", ""))
+                is_skipped = c.get("skip", False)
+
+                # Component column
+                conf_url = c.get("confluence", {}).get("page")
+                if is_skipped:
+                    comp_cell = f'<span style="color:#9E9E9E"><s>{name_esc}</s></span>'
+                elif conf_url:
+                    comp_cell = f'<a href="{conf_url}">{name_esc}</a>'
+                else:
+                    comp_cell = name_esc
+
+                # Platform columns
+                ios_cell = platform_cell(c, components, "ios")
+                android_cell = platform_cell(c, components, "android")
+
+                # Figma Component column
+                if c.get("figmaUrl"):
+                    figma_cell = f'<a href="{c["figmaUrl"]}">{name_esc}</a>'
+                else:
+                    figma_cell = name_esc
+
+                # Variant count
+                vc = c.get("variantCount", 0)
+                variant_cell = str(vc) if vc > 0 else "—"
+
+                # Sub-components — colored links (blue/green/red/gray), NO emoji
+                subs = c.get("subComponents", [])
+                if subs:
+                    sub_links = []
+                    for sub in subs:
+                        sub_nid = sub.get("nodeId")
+                        sub_name = sub["name"]
+                        if sub_nid:
+                            sub_comp = components.get(sub_nid)
+                            if sub_comp:
+                                s_anchor = node_anchor(sub_nid)
+                                s_readiness = compute_readiness(sub_comp, components, "ios")
+                                s_color = READINESS_COLOR.get(s_readiness, "#999")
+                                sub_links.append(make_anchor_link(s_anchor, sub_name, s_color))
+                            else:
+                                sub_links.append(f'<span style="color:#999">{xml_escape(sub_name)}</span>')
+                        else:
+                            sub_links.append(f'<span style="color:#999">{xml_escape(sub_name)}</span>')
+                    subs_cell = ", ".join(sub_links)
+                else:
+                    subs_cell = "—"
+
+                row_style = ' style="background:#f5f5f5; color:#9E9E9E"' if is_skipped else ''
+                p.append(
+                    f'<tr{row_style}>'
+                    f'<td>{ios_cell}</td>'
+                    f'<td>{android_cell}</td>'
+                    f'<td>{comp_cell}</td>'
+                    f'<td>{figma_cell}</td>'
+                    f'<td><code>{figma_esc}</code></td>'
+                    f'<td>{variant_cell}</td>'
+                    f'<td>{subs_cell}</td>'
+                    f'</tr>'
+                )
+
+            p.append('</tbody></table>')
+            p.append('</ac:rich-text-body>')
+            p.append('</ac:structured-macro>')
+
+        p.append('<hr/>')
+
+    # --- Connected Components — iOS ---
+    ios_connected = [c for c in catalog_comps if c.get("codeConnect", {}).get("ios")]
+    p.append('<h2>Connected Components — iOS</h2>')
+    if ios_connected:
+        p.append('<table><tbody>')
+        p.append('<tr><th>Component</th><th>Figma Name</th></tr>')
+        for c in sorted(ios_connected, key=lambda c: c["name"]):
+            anchor = node_anchor(c["nodeId"])
+            figma_esc = xml_escape(c.get("figmaName", ""))
+            p.append(
+                f'<tr>'
+                f'<td>{make_anchor_link(anchor, c["name"])}</td>'
+                f'<td><code>{figma_esc}</code></td>'
+                f'</tr>'
+            )
+        p.append('</tbody></table>')
+    else:
+        p.append('<p><em>No iOS-connected components yet.</em></p>')
+
+    # --- Connected Components — Android ---
+    android_connected = [c for c in catalog_comps if c.get("codeConnect", {}).get("android")]
+    p.append('<h2>Connected Components — Android</h2>')
+    if android_connected:
+        p.append('<table><tbody>')
+        p.append('<tr><th>Component</th><th>Figma Name</th></tr>')
+        for c in sorted(android_connected, key=lambda c: c["name"]):
+            anchor = node_anchor(c["nodeId"])
+            figma_esc = xml_escape(c.get("figmaName", ""))
+            p.append(
+                f'<tr>'
+                f'<td>{make_anchor_link(anchor, c["name"])}</td>'
+                f'<td><code>{figma_esc}</code></td>'
+                f'</tr>'
+            )
+        p.append('</tbody></table>')
+    else:
+        p.append('<p><em>No Android-connected components yet.</em></p>')
+
+    p.append('<hr/>')
+    p.append(f'<p><em>Index: {len(components)} components, '
+             f'{summary["resolvedNames"]} name aliases, '
+             f'{summary["registryFiles"]} registry files</em></p>')
+
+    return "\n".join(p)
+
+
+# -------------------------------------------------------------------
+# STEP 3: Confluence upload
+# -------------------------------------------------------------------
+
+def lookup_page(token, title, parent_id=None):
+    encoded = urllib.parse.quote(title)
+    url = f"{BASE_URL}/rest/api/content?spaceKey={SPACE}&title={encoded}&expand=version,ancestors"
+    req = urllib.request.Request(url)
+    req.add_header("Authorization", f"Bearer {token}")
+    with urllib.request.urlopen(req) as resp:
+        d = json.loads(resp.read())
+    for r in d.get("results", []):
+        if parent_id:
+            anc = r.get("ancestors", [])
+            pid = anc[-1]["id"] if anc else None
+            if str(pid) != str(parent_id):
+                continue
+        return {"id": r["id"], "version": r["version"]["number"]}
+    return None
+
+
+def delete_page(token, page_id):
+    """Delete page and purge from trash to avoid version/storage bloat."""
+    req = urllib.request.Request(
+        f"{BASE_URL}/rest/api/content/{page_id}", method="DELETE"
+    )
+    req.add_header("Authorization", f"Bearer {token}")
+    urllib.request.urlopen(req)
+    print(f"Deleted: id={page_id}")
+    try:
+        req = urllib.request.Request(
+            f"{BASE_URL}/rest/api/content/{page_id}?status=trashed", method="DELETE"
+        )
+        req.add_header("Authorization", f"Bearer {token}")
+        urllib.request.urlopen(req)
+        print(f"Purged from trash: id={page_id}")
+    except urllib.error.HTTPError:
+        print(f"Note: Could not purge from trash (may need admin rights)")
+
+
+def create_page(token, title, content, parent_id):
+    """Create a fresh page (always v1)."""
+    payload = {
+        "type": "page", "title": title,
+        "ancestors": [{"id": str(parent_id)}],
+        "space": {"key": SPACE},
+        "body": {"storage": {"value": content, "representation": "storage"}}
+    }
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(f"{BASE_URL}/rest/api/content", data=body, method="POST")
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Content-Type", "application/json; charset=utf-8")
+    try:
+        with urllib.request.urlopen(req) as resp:
+            d = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"Create failed: {e.read().decode()[:500]}")
+    print(f"Created: \"{title}\" -> {d['id']} (v1, fresh)")
+    return d["id"]
+
+
+def update_page(token, page_id, title, content, version):
+    """Update an existing page in-place (fallback when delete is forbidden)."""
+    payload = {
+        "type": "page", "title": title,
+        "version": {"number": version + 1},
+        "body": {"storage": {"value": content, "representation": "storage"}}
+    }
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(
+        f"{BASE_URL}/rest/api/content/{page_id}", data=body, method="PUT"
+    )
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Content-Type", "application/json; charset=utf-8")
+    try:
+        with urllib.request.urlopen(req) as resp:
+            d = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"Update failed: {e.read().decode()[:500]}")
+    print(f"Updated: \"{title}\" -> {d['id']} (v{version + 1})")
+    return d["id"]
+
+
+def upload(token, title, content, parent_id, dry_run=False):
+    """Delete existing page + recreate fresh, or update in-place as fallback."""
+    existing = lookup_page(token, title, parent_id)
+    if existing:
+        if dry_run:
+            print(f"[DRY RUN] Would delete+recreate: \"{title}\" (id={existing['id']}, was v{existing['version']})")
+            return existing["id"]
+        try:
+            delete_page(token, existing["id"])
+        except urllib.error.HTTPError:
+            print(f"Delete forbidden, updating in-place instead...")
+            return update_page(token, existing["id"], title, content, existing["version"])
+    elif dry_run:
+        print(f"[DRY RUN] Would create: \"{title}\"")
+        return "DRY"
+    return create_page(token, title, content, parent_id)
+
+
+# -------------------------------------------------------------------
+# Main
+# -------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--output", help="Write XHTML to file instead of uploading")
+    args = parser.parse_args()
+
+    # Find Shared/Figma/ directory
+    for base in [".", "{repos.common.path}"]:
+        cat = os.path.join(base, "Shared/Figma/Generated/component-catalog.json")
+        if os.path.isfile(cat):
+            figma_dir = os.path.dirname(os.path.dirname(cat))
+            break
+    else:
+        print("ERROR: component-catalog.json not found")
+        print("Run: FigmaRegistryUtility catalog")
+        sys.exit(1)
+
+    print(f"Figma dir: {figma_dir}")
+
+    # STEP 1: Build unified index
+    index = build_component_index(figma_dir)
+    s = index["summary"]
+    print(f"Components: {s['totalComponents']} (catalog) + "
+          f"{sum(1 for c in index['components'].values() if c.get('registryOnly'))} (registry-only)")
+    print(f"Registry:   {s['registryFiles']} files")
+    print(f"Names:      {s['resolvedNames']} aliases indexed")
+    print(f"Graph:      {s['graphMerged']} components with sub-component data")
+
+    # Write index to disk for inspection
+    index_path = os.path.join(figma_dir, "Generated", "component-index.json")
+    # Write a slim version (no nameLookup — it's huge)
+    slim = {
+        "components": index["components"],
+        "files": index["files"],
+        "summary": index["summary"],
+    }
+    with open(index_path, "w") as f:
+        json.dump(slim, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    print(f"Index:      {index_path}")
+
+    # Count resolved vs unresolved sub-component names
+    resolved = 0
+    unresolved = 0
+    for c in index["components"].values():
+        for sub in c.get("subComponents", []):
+            if sub.get("nodeId"):
+                resolved += 1
+            else:
+                unresolved += 1
+    print(f"Sub-comps:  {resolved} resolved, {unresolved} unresolved")
+
+    # STEP 2: Generate XHTML
+    xhtml = generate_xhtml(index)
+
+    if args.output:
+        with open(args.output, "w") as f:
+            f.write(xhtml)
+        print(f"Written:    {args.output} ({len(xhtml)} bytes)")
+        return
+
+    # STEP 3: Upload
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    ids_file = os.path.join(script_dir, "confluence-page-ids.json")
+    with open(ids_file) as f:
+        page_ids = json.load(f)
+
+    parent_id = page_ids.get("Figma Components")
+    if not parent_id:
+        print("ERROR: Figma Components page ID not found")
+        sys.exit(1)
+
+    token = get_token()
+    upload(token, PAGE_TITLE, xhtml, parent_id, args.dry_run)
+    print("Done!")
+
+
+if __name__ == "__main__":
+    main()