@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,1470 @@
+#!/usr/bin/env python3
+"""update-issue-from-registry.py — full GitHub sync driven by registry.
+
+Per-flag state is stored as 4 single-select Projects V2 fields on the
+"Figma Components" board:
+
+    Implementation   Gray / Green / Yellow
+    Tested           Gray / Green / Yellow
+    Code Connect     Gray / Green / Yellow
+    Wiki             Gray / Green / Yellow
+
+These fields replace the label-based approach — GitHub labels can't
+vary color per-issue, but project fields can.
+
+For one node-id, this script:
+
+1. Loads the registry entry.
+2. Skips if `skip: true` or the entry is an icon (`componentName`
+   starts with `Image.` on iOS or `Images.` on android).
+3. Computes the 4 flag states (`gray`/`green`/`yellow`) from the
+   registry's `status.<platform>` block.
+4. Finds all open issues whose body references the node-id.
+5. Zero matches → creates a new issue (team:core default, labels:
+   component/redesign/team:core), adds it to the project, sets the
+   4 flag fields from registry state.
+6. Multiple matches → applies the duplicate rule (issue with
+   sub-issues wins; tiebreak by lowest number), closes losers with a
+   "Duplicate of #N" comment.
+7. On the survivor: rewrites the `### Progress` table in the body +
+   sets the 4 project field values.
+8. Idempotent — re-running after a successful sync produces no writes.
+
+No label manipulation beyond what `gh issue create` applies at birth.
+The 8 flag labels (`implemented:green` etc.) from the previous
+iteration have been deleted from the repo; nothing writes `phase:*`
+labels anymore.
+
+Usage:
+    python3 update-issue-from-registry.py \\
+        --node-id 5:17752 \\
+        [--platform ios] \\
+        [--registry-dir /path] \\
+        [--repo OWNER/REPO] \\
+        [--team-label team:core] \\
+        [--dry-run]
+
+Exit codes:
+    0 — success
+    1 — error
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+DEFAULT_REPO = "{github.componentsRepo}"
+DEFAULT_TEAM_LABEL = "team:core"
+
+# Projects V2 — "Figma Components" board
+PROJECT_ID = "{github.projectV2Id}"
+
+# Repo-level labels for flag state. ONE per flag (4 total). Label
+# present = flag is green (done and current). Label absent = flag is
+# gray (not done) or yellow (stale). Yellow state is tracked on the
+# Projects V2 fields only — the label only fires on green, so the
+# issue list stays uncluttered and shows "what's done."
+FLAG_LABEL_NAMES = {
+    "implemented": "implemented",
+    "tested": "tested",
+    "codeConnect": "code-connected",
+    "wiki": "wiki",
+}
+
+# All 4 flag labels (as a tuple for set operations)
+ALL_FLAG_LABELS = tuple(FLAG_LABEL_NAMES.values())
+
+# Legacy labels that we strip whenever we see them. Includes the old
+# phase:* enum and the 8 green/yellow flag labels from earlier
+# iterations of this script.
+LEGACY_PHASE_LABELS = (
+    "phase:implementation",
+    "phase:testing",
+    "phase:code-connect",
+    "phase:documentation",
+    "phase:done",
+    "impl:green", "impl:yellow",
+    "test:green", "test:yellow",
+    "cc:green", "cc:yellow",
+    "implemented:green", "implemented:yellow",
+    "tested:green", "tested:yellow",
+    "code-connected:green", "code-connected:yellow",
+    "wiki:green", "wiki:yellow",
+)
+
+# Field + option IDs captured at field-creation time (2026-04-11).
+# Each flag has 3 options: gray (not done), green (current), yellow (stale).
+FLAG_FIELDS: dict = {
+    "implemented": {
+        "field_id": "PVTSSF_lADOD594Cs4BSatBzhBdns8",
+        "options": {
+            "gray": "7936be8c",
+            "green": "8b8e2dac",
+            "yellow": "f11b325f",
+        },
+    },
+    "tested": {
+        "field_id": "PVTSSF_lADOD594Cs4BSatBzhBdntA",
+        "options": {
+            "gray": "2c4acdbe",
+            "green": "119380d9",
+            "yellow": "fabaa558",
+        },
+    },
+    "codeConnect": {
+        "field_id": "PVTSSF_lADOD594Cs4BSatBzhBdnt4",
+        "options": {
+            "gray": "62cb9ea4",
+            "green": "f226993d",
+            "yellow": "0317c874",
+        },
+    },
+    "wiki": {
+        "field_id": "PVTSSF_lADOD594Cs4BSatBzhBdnt8",
+        "options": {
+            "gray": "6b3f27bb",
+            "green": "5facabd2",
+            "yellow": "e6d08d85",
+        },
+    },
+}
+
+# Status column — single-select field that drives the kanban board view.
+# Option ids captured at 2026-04-12 field expansion.
+STATUS_FIELD_ID = "{github.projectV2Fields.status}"
+STATUS_OPTIONS: dict = {
+    "Todo":       "25f3e7a3",
+    "In Develop": "bc6c45f7",
+    "In Review":  "bdb0d8ef",
+    "Done":       "6275b69e",
+    "Blocked":    "95949fd8",
+    "Bugfix":     "e46fa72d",
+    "Stale":      "457a1e74",
+}
+
+# Review Progress field — single-select replaces the review:0/4..review:4/4 labels.
+REVIEW_PROGRESS_FIELD_ID = "PVTSSF_lADOD594Cs4BSatBzhBgYNs"
+REVIEW_PROGRESS_OPTIONS: dict = {
+    "0/4": "d33443cf",
+    "1/4": "5f0bba11",
+    "2/4": "45016b2b",
+    "3/4": "2c52a38a",
+    "4/4": "04e0358a",
+}
+
+# Bugfix signal — if any of these labels are present on the issue, the column is Bugfix.
+BUGFIX_LABELS = {"review-fix", "bug", "bugfix"}
+
+# Review label legacy fallback: review:0/4 .. review:4/4
+REVIEW_LABEL_RE = re.compile(r"^review:(\d)/4$")
+
+# Progress-table section matcher.
+PROGRESS_TABLE_RE = re.compile(
+    r"(### Progress\n\n)(.*?)(?=\n### |\Z)",
+    re.DOTALL,
+)
+
+
+# --------------------------------------------------------------------
+# Repo layout
+# --------------------------------------------------------------------
+
+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"
+    )
+
+
+# --------------------------------------------------------------------
+# Registry loading
+# --------------------------------------------------------------------
+
+def load_entry(registry_dir: Path, node_id: str) -> Optional[dict]:
+    path = Path(registry_dir) / f"{node_id.replace(':', '-')}.json"
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def is_icon_entry(entry: dict) -> bool:
+    """Icons have componentName starting with 'Image.' on iOS or 'Images.'
+    on android. Generated in bulk — never get individual issues."""
+    cn = entry.get("componentName")
+    if isinstance(cn, dict):
+        ios = cn.get("ios") or ""
+        android = cn.get("android") or ""
+    elif isinstance(cn, str):
+        ios = cn
+        android = ""
+    else:
+        return False
+    if isinstance(ios, str) and ios.startswith("Image."):
+        return True
+    if isinstance(android, str) and android.startswith("Images."):
+        return True
+    return False
+
+
+# --------------------------------------------------------------------
+# Pure logic — flag state computation
+# --------------------------------------------------------------------
+
+def get_implemented_by(entry: dict, platform: str) -> Optional[str]:
+    """Return status.<platform>.implementedBy if set, else None.
+
+    Stored as a plain string (git author name). May differ from a
+    real GitHub login — the backfill stores whatever git log returned.
+    For this repo, git author names match GitHub logins (e.g.
+    M-ISPIRLI_tkgithub), so we pass them directly to gh as assignees.
+    """
+    ps = (entry.get("status") or {}).get(platform)
+    if not isinstance(ps, dict):
+        return None
+    author = ps.get("implementedBy")
+    return author if isinstance(author, str) and author else None
+
+
+def compute_flag_states(entry: dict, platform: str) -> dict:
+    """Return {flag_name: 'gray'|'green'|'yellow'} for all 4 flags.
+
+    Missing flags default to 'gray'. Never omits a key.
+
+    Rules:
+        implemented:
+            value==false              → gray
+            value==true, stale==false → green
+            value==true, stale==true  → yellow
+
+        tested / codeConnect / wiki:
+            value==false                          → gray
+            value==true, against >= impl.version  → green
+            value==true, against <  impl.version  → yellow
+    """
+    result: dict = {
+        "implemented": "gray",
+        "tested": "gray",
+        "codeConnect": "gray",
+        "wiki": "gray",
+    }
+
+    ps = (entry.get("status") or {}).get(platform)
+    if not isinstance(ps, dict):
+        return result
+
+    impl = ps.get("implemented") or {}
+    if impl.get("value"):
+        result["implemented"] = "yellow" if ps.get("stale") else "green"
+
+    impl_version = impl.get("version", 0)
+
+    for flag in ("tested", "codeConnect", "wiki"):
+        f = ps.get(flag) or {}
+        if not f.get("value"):
+            continue
+        if f.get("against", 0) < impl_version:
+            result[flag] = "yellow"
+        else:
+            result[flag] = "green"
+
+    return result
+
+
+# --------------------------------------------------------------------
+# Sub-component graph (for Blocked column) — lazy loaded + cached
+# --------------------------------------------------------------------
+
+_sub_graph_cache: Optional[dict] = None
+_name_to_node_cache: Optional[dict] = None
+
+
+def load_sub_component_graph(common_path: Optional[Path] = None) -> dict:
+    """Return {nodeId: [subComponentName, ...]} keyed by colon-form node-id.
+
+    Cached on first call. Returns {} if the graph file is missing."""
+    global _sub_graph_cache
+    if _sub_graph_cache is not None:
+        return _sub_graph_cache
+    if common_path is None:
+        common_path = find_repo_root() / "{repos.packagesContainer}" / "Packages" / "{project.slug}-common"
+    graph_path = common_path / "Shared" / "Figma" / "sub-component-graph.json"
+    try:
+        with graph_path.open() as f:
+            raw = json.load(f)
+        g = raw.get("graph", {}) or {}
+        _sub_graph_cache = {
+            nid: (entry.get("subComponents") or [])
+            for nid, entry in g.items()
+            if isinstance(entry, dict)
+        }
+    except (OSError, json.JSONDecodeError):
+        _sub_graph_cache = {}
+    return _sub_graph_cache
+
+
+def build_name_to_node_index(registry_dir: Path, platform: str) -> dict:
+    """Return {componentName: nodeId-dash-form} by walking the registry.
+
+    Cached on first call. Used to resolve sub-component names (from the
+    graph) back to registry entries so we can check their implemented
+    state for the Blocked column."""
+    global _name_to_node_cache
+    if _name_to_node_cache is not None:
+        return _name_to_node_cache
+    index: dict = {}
+    try:
+        for p in registry_dir.glob("*.json"):
+            try:
+                with p.open() as f:
+                    d = json.load(f)
+            except (OSError, json.JSONDecodeError):
+                continue
+            if not isinstance(d, dict):
+                continue
+            cn_obj = d.get("componentName") or {}
+            cn = cn_obj.get(platform) if isinstance(cn_obj, dict) else None
+            if cn:
+                index[cn] = p.stem  # dash-form node id
+    except OSError:
+        pass
+    _name_to_node_cache = index
+    return _name_to_node_cache
+
+
+def is_blocked(
+    node_id: str,
+    registry_dir: Path,
+    platform: str,
+    common_path: Optional[Path] = None,
+) -> bool:
+    """Return True if any sub-component of the given node is NOT implemented.
+
+    Looks up the node in sub-component-graph.json (colon-form keys),
+    then for each sub-component name resolves it back to its own registry
+    entry via a name→node index, and checks `status.<platform>.implemented.value`.
+
+    Skipped, icon, and registry-missing children are treated as 'not blocking'.
+    """
+    graph = load_sub_component_graph(common_path)
+    key_colon = node_id.replace("-", ":")
+    subs = graph.get(key_colon) or []
+    if not subs:
+        return False
+    name_index = build_name_to_node_index(registry_dir, platform)
+    for sub_name in subs:
+        sub_nid_dash = name_index.get(sub_name)
+        if not sub_nid_dash:
+            continue  # not in registry — can't assess, assume OK
+        sub_entry = load_entry(registry_dir, sub_nid_dash)
+        if not isinstance(sub_entry, dict):
+            continue
+        if sub_entry.get("skip") or is_icon_entry(sub_entry):
+            continue
+        sub_status = sub_entry.get("status")
+        if not isinstance(sub_status, dict):
+            continue
+        sub_platform = sub_status.get(platform)
+        if not isinstance(sub_platform, dict):
+            continue
+        sub_impl = sub_platform.get("implemented") or {}
+        if not isinstance(sub_impl, dict):
+            continue
+        if not sub_impl.get("value"):
+            return True
+    return False
+
+
+# --------------------------------------------------------------------
+# Review progress + Status column (Projects V2 kanban view)
+# --------------------------------------------------------------------
+
+def parse_review_progress_from_labels(label_names: List[str]) -> int:
+    """Read review:N/4 labels, return N (0..4). Defaults to 0 if absent.
+
+    Used as a fallback until the Review Progress single-select field is
+    authoritative everywhere."""
+    best = 0
+    for name in label_names:
+        m = REVIEW_LABEL_RE.match(name)
+        if m:
+            n = int(m.group(1))
+            if n > best:
+                best = n
+    return best
+
+
+def has_bugfix_signal(label_names: List[str], open_bug_sub_issues: int = 0) -> bool:
+    """Return True if the issue has any active bugfix signal.
+
+    Two independent signals (either one is enough):
+      1. Parent issue itself carries a review-fix / bug / bugfix label.
+      2. There are open sub-issues with those labels (counted externally).
+
+    Checking both makes the system self-healing: if someone forgets to
+    remove the label after all bugs are closed, the sub-issue count
+    catches it (and vice versa — if the label is missing but open bugs
+    exist, we still detect it).
+    """
+    if any(name in BUGFIX_LABELS for name in label_names):
+        return True
+    return open_bug_sub_issues > 0
+
+
+def count_open_bug_sub_issues(owner: str, name: str, issue_number: int) -> int:
+    """Count open sub-issues that carry a bugfix label (review-fix, bug, bugfix).
+
+    Uses the existing list_sub_issues() helper to get sub-issue numbers,
+    then checks each for open state + bug label. Cached per-call — not
+    expensive for typical 0-3 bug sub-issues per component.
+    """
+    try:
+        sub_numbers = list_sub_issues(owner, name, issue_number)
+    except RuntimeError:
+        return 0
+    count = 0
+    for sn in sub_numbers:
+        try:
+            raw = gh(["issue", "view", str(sn), "--repo", f"{owner}/{name}",
+                       "--json", "state,labels"])
+            data = json.loads(raw)
+            if data.get("state") != "OPEN":
+                continue
+            labels = {(l.get("name") or "") for l in (data.get("labels") or []) if isinstance(l, dict)}
+            if labels & BUGFIX_LABELS:
+                count += 1
+        except (RuntimeError, json.JSONDecodeError):
+            continue
+    return count
+
+
+def effective_review_progress(label_names: List[str], flag_states: dict) -> int:
+    """Return the effective review count, accounting for staleness.
+
+    Reviews become stale (reset to 0) when tested or codeConnect are
+    YELLOW — meaning the implementation version bumped since those phases
+    last ran. This happens after a bugfix or re-implementation.
+
+    Reviews are NOT reset when tested/codeConnect are GRAY (never run).
+    Testing and wiki are nice-to-have, not prerequisites for reviews.
+    Only impl + codeConnect green are mandatory for In Review; tests
+    and wiki are tracked per-flag but don't gate the review cycle.
+    """
+    raw = parse_review_progress_from_labels(label_names)
+    tested = flag_states.get("tested", "gray")
+    cc = flag_states.get("codeConnect", "gray")
+    # Only yellow (stale) resets reviews — gray (never done) does not.
+    if tested == "yellow" or cc == "yellow":
+        return 0  # stale — impl version changed since phases ran
+    return raw
+
+
+def compute_status_column(
+    flag_states: dict,
+    label_names: List[str],
+    has_assignees: bool,
+    blocked: bool,
+    open_bug_sub_issues: int = 0,
+) -> str:
+    """Return the target Status column name using the precedence chain:
+
+        Stale > Bugfix > Blocked > Done > In Review > In Develop > Todo
+
+    Inputs:
+      flag_states           : {implemented,tested,codeConnect,wiki} -> gray|green|yellow
+      label_names           : issue label names (bugfix signal + legacy review count)
+      has_assignees         : True if issue has >=1 assignee
+      blocked               : precomputed from is_blocked()
+      open_bug_sub_issues   : count of open sub-issues with bugfix labels
+    """
+    impl = flag_states.get("implemented", "gray")
+    cc = flag_states.get("codeConnect", "gray")
+
+    # 1. Stale — only implementation yellow counts (downstream yellow is per-flag)
+    if impl == "yellow":
+        return "Stale"
+
+    # 2. Bugfix — review-fix/bug labels present OR open bug sub-issues
+    if has_bugfix_signal(label_names, open_bug_sub_issues):
+        return "Bugfix"
+
+    # 3. Blocked — a sub-component is not implemented
+    if blocked and impl != "green":
+        return "Blocked"
+
+    # 4. Done — effective 4/4 reviews passed (stale reviews = 0)
+    reviews = effective_review_progress(label_names, flag_states)
+    if reviews >= 4 and impl == "green":
+        return "Done"
+
+    # 5. In Review — implementation + code connect both green
+    if impl == "green" and cc == "green":
+        return "In Review"
+
+    # 6. In Develop — claimed (has assignee) but not implemented yet
+    if has_assignees and impl != "green":
+        return "In Develop"
+
+    # 7. Todo — default
+    return "Todo"
+
+
+def review_progress_option_name(n: int) -> str:
+    """Clamp review count to a valid Review Progress option name."""
+    if n < 0:
+        n = 0
+    if n > 4:
+        n = 4
+    return f"{n}/4"
+
+
+# --------------------------------------------------------------------
+# Progress table (body representation)
+# --------------------------------------------------------------------
+
+def build_progress_table(flag_states: dict) -> str:
+    ICON = {"gray": "⚪", "green": "🟢", "yellow": "🟡"}
+    return (
+        "| Flag | State |\n"
+        "|---|---|\n"
+        f"| Implementation | {ICON[flag_states.get('implemented', 'gray')]} |\n"
+        f"| Testing        | {ICON[flag_states.get('tested', 'gray')]} |\n"
+        f"| Code Connect   | {ICON[flag_states.get('codeConnect', 'gray')]} |\n"
+        f"| Wiki           | {ICON[flag_states.get('wiki', 'gray')]} |\n"
+    )
+
+
+def rewrite_progress_table(body: str, flag_states: dict) -> str:
+    new_table = build_progress_table(flag_states)
+    new_block = new_table + "\n"
+
+    def _sub(m: "re.Match[str]") -> str:
+        return m.group(1) + new_block
+
+    new_body, n = PROGRESS_TABLE_RE.subn(_sub, body, count=1)
+    if n == 0:
+        return body.rstrip() + "\n\n### Progress\n\n" + new_block
+    return new_body
+
+
+# --------------------------------------------------------------------
+# gh wrapper — always captures stdout
+# --------------------------------------------------------------------
+
+GH_TIMEOUT_SECONDS = 30  # hard timeout per gh invocation — prevents infinite hangs
+
+
+def gh(args: List[str], dry_run: bool = False, timeout: int = GH_TIMEOUT_SECONDS) -> str:
+    if dry_run:
+        print(f"[dry-run] gh {' '.join(args)}", file=sys.stderr)
+        return ""
+    try:
+        r = subprocess.run(
+            ["gh"] + args,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        raise RuntimeError("gh CLI not found on PATH")
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(f"gh {' '.join(args[:3])}... timed out after {timeout}s")
+    if r.returncode != 0:
+        raise RuntimeError(f"gh {' '.join(args)} failed: {r.stderr.strip()}")
+    return r.stdout.strip()
+
+
+def gh_graphql(query: str, variables: Optional[dict] = None, dry_run: bool = False) -> dict:
+    """Run a GraphQL query/mutation via gh api graphql. Returns parsed JSON."""
+    if dry_run:
+        print(f"[dry-run] gh api graphql (query len={len(query)})", file=sys.stderr)
+        return {}
+    args = ["api", "graphql", "-f", f"query={query}"]
+    if variables:
+        for k, v in variables.items():
+            args += ["-F", f"{k}={v}"]
+    out = gh(args, dry_run=False)
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError:
+        raise RuntimeError(f"graphql: could not parse response: {out[:200]}")
+    if "errors" in data:
+        raise RuntimeError(f"graphql errors: {data['errors']}")
+    return data.get("data", {})
+
+
+# --------------------------------------------------------------------
+# GitHub operations — REST (issue list/comment/close)
+# --------------------------------------------------------------------
+
+def find_all_open_issues(node_id: str, repo: str, dry_run: bool) -> List[dict]:
+    """Return open issues referencing the node-id, with sub-issue counts.
+
+    Uses gh issue list for initial filtering, then GraphQL for
+    sub-issue counts per match. Sorted by number ascending.
+    """
+    out = gh(
+        [
+            "issue", "list",
+            "--repo", repo,
+            "--state", "open",
+            "--search", f'"{node_id}" in:body',
+            "--json", "number,title,body,labels",
+            "--limit", "20",
+        ],
+        dry_run=dry_run,
+    )
+    if dry_run or not out:
+        return []
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError:
+        return []
+    if not isinstance(data, list):
+        return []
+
+    # Annotate each with sub_issue_count via GraphQL
+    owner, name = repo.split("/", 1)
+    for issue in data:
+        num = issue.get("number")
+        if not num:
+            issue["sub_issue_count"] = 0
+            continue
+        try:
+            issue["sub_issue_count"] = count_sub_issues(owner, name, num)
+        except RuntimeError:
+            issue["sub_issue_count"] = 0
+
+    return sorted(data, key=lambda d: d.get("number", 0))
+
+
+def count_sub_issues(owner: str, name: str, issue_number: int) -> int:
+    q = """
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        issue(number: $number) {
+          subIssues(first: 1) { totalCount }
+        }
+      }
+    }
+    """
+    data = gh_graphql(q, {"owner": owner, "name": name, "number": issue_number})
+    try:
+        return data["repository"]["issue"]["subIssues"]["totalCount"]
+    except (KeyError, TypeError):
+        return 0
+
+
+def get_issue_assignees(issue_number: int, repo: str) -> List[str]:
+    """Return list of assignee logins on an issue, or []."""
+    out = gh([
+        "issue", "view", str(issue_number),
+        "--repo", repo,
+        "--json", "assignees",
+    ])
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError:
+        return []
+    return [a.get("login", "") for a in (data.get("assignees") or []) if isinstance(a, dict) and a.get("login")]
+
+
+def add_assignees(issue_number: int, repo: str, logins: List[str], dry_run: bool) -> None:
+    """Add assignees to an issue via gh issue edit --add-assignee.
+
+    Non-fatal on errors — assignee names may not map to real GitHub
+    logins (backfill stores git author names, which usually match but
+    not always). Failure is logged, not raised.
+    """
+    if not logins:
+        return
+    try:
+        gh(
+            ["issue", "edit", str(issue_number), "--repo", repo,
+             "--add-assignee", ",".join(logins)],
+            dry_run=dry_run,
+        )
+    except RuntimeError:
+        pass
+
+
+def list_sub_issues(owner: str, name: str, issue_number: int) -> List[int]:
+    """Return list of sub-issue numbers for one issue via GraphQL.
+
+    Used during duplicate conflation to move sub-issues from the
+    loser to the winner before closing the loser. Returns [] if the
+    query fails or the issue has no sub-issues.
+    """
+    q = """
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        issue(number: $number) {
+          subIssues(first: 50) {
+            nodes { number id }
+          }
+        }
+      }
+    }
+    """
+    try:
+        data = gh_graphql(q, {"owner": owner, "name": name, "number": issue_number})
+    except RuntimeError:
+        return []
+    try:
+        nodes = data["repository"]["issue"]["subIssues"]["nodes"]
+    except (KeyError, TypeError):
+        return []
+    return [n.get("number") for n in (nodes or []) if n and n.get("number")]
+
+
+def reparent_sub_issue(
+    owner: str,
+    name: str,
+    sub_issue_number: int,
+    new_parent_number: int,
+) -> bool:
+    """Move a sub-issue from its current parent to a new parent.
+
+    Uses the addSubIssue mutation, which re-links if the sub-issue is
+    already tracked under another parent (GitHub's own behavior: a
+    sub-issue has exactly one parent at a time).
+    """
+    q_id = """
+    query($owner: String!, $name: String!, $sub: Int!, $parent: Int!) {
+      repository(owner: $owner, name: $name) {
+        sub: issue(number: $sub) { id }
+        parent: issue(number: $parent) { id }
+      }
+    }
+    """
+    try:
+        data = gh_graphql(q_id, {"owner": owner, "name": name, "sub": sub_issue_number, "parent": new_parent_number})
+    except RuntimeError:
+        return False
+    try:
+        sub_id = data["repository"]["sub"]["id"]
+        parent_id = data["repository"]["parent"]["id"]
+    except (KeyError, TypeError):
+        return False
+
+    mut = """
+    mutation($issueId: ID!, $subIssueId: ID!) {
+      addSubIssue(input: {issueId: $issueId, subIssueId: $subIssueId}) {
+        issue { number }
+      }
+    }
+    """
+    try:
+        gh_graphql(mut, {"issueId": parent_id, "subIssueId": sub_id})
+        return True
+    except RuntimeError:
+        return False
+
+
+def conflate_duplicate(
+    loser: dict,
+    keeper_number: int,
+    repo: str,
+    dry_run: bool,
+) -> dict:
+    """Full duplicate conflation — transfer state from loser to keeper, then close loser.
+
+    Transfers:
+      1. Assignees (add loser's assignees to keeper)
+      2. Sub-issues (reparent each to keeper)
+    Then:
+      3. Posts a Duplicate-of comment on the loser
+      4. Closes the loser as 'not planned'
+
+    Returns a dict describing what was transferred, for the report.
+    """
+    loser_number = loser.get("number")
+    owner, name = repo.split("/", 1)
+    transfer_log = {
+        "loser": loser_number,
+        "keeper": keeper_number,
+        "assignees_transferred": [],
+        "sub_issues_reparented": [],
+        "sub_issue_reparent_failures": [],
+    }
+
+    if loser_number is None:
+        return transfer_log
+
+    # 1. Assignees
+    try:
+        loser_assignees = get_issue_assignees(loser_number, repo)
+    except RuntimeError:
+        loser_assignees = []
+    if loser_assignees:
+        add_assignees(keeper_number, repo, loser_assignees, dry_run=dry_run)
+        transfer_log["assignees_transferred"] = loser_assignees
+
+    # 2. Sub-issues
+    sub_numbers = list_sub_issues(owner, name, loser_number)
+    for sub_num in sub_numbers:
+        if reparent_sub_issue(owner, name, sub_num, keeper_number):
+            transfer_log["sub_issues_reparented"].append(sub_num)
+        else:
+            transfer_log["sub_issue_reparent_failures"].append(sub_num)
+
+    # 3 + 4: comment and close
+    today = date.today().isoformat()
+    transferred_summary_parts = []
+    if transfer_log["assignees_transferred"]:
+        transferred_summary_parts.append(
+            f"Transferred {len(transfer_log['assignees_transferred'])} assignee(s)"
+        )
+    if transfer_log["sub_issues_reparented"]:
+        transferred_summary_parts.append(
+            f"moved {len(transfer_log['sub_issues_reparented'])} sub-issue(s)"
+        )
+    transferred_summary = "; ".join(transferred_summary_parts) if transferred_summary_parts else "No state to transfer"
+
+    gh(
+        [
+            "issue", "comment", str(loser_number),
+            "--repo", repo,
+            "--body",
+            f"Duplicate of #{keeper_number} — closed by registry sync on {today}. "
+            f"{transferred_summary}.",
+        ],
+        dry_run=dry_run,
+    )
+    gh(
+        [
+            "issue", "close", str(loser_number),
+            "--repo", repo,
+            "--reason", "not planned",
+        ],
+        dry_run=dry_run,
+    )
+
+    return transfer_log
+
+
+def close_duplicate(issue_number: int, keep_number: int, repo: str, dry_run: bool) -> None:
+    """Legacy shim — kept for backwards compatibility with any caller
+    that doesn't need the full conflation. Prefer conflate_duplicate."""
+    today = date.today().isoformat()
+    gh(
+        [
+            "issue", "comment", str(issue_number),
+            "--repo", repo,
+            "--body", f"Duplicate of #{keep_number} — closed by registry sync on {today}.",
+        ],
+        dry_run=dry_run,
+    )
+    gh(
+        [
+            "issue", "close", str(issue_number),
+            "--repo", repo,
+            "--reason", "not planned",
+        ],
+        dry_run=dry_run,
+    )
+
+
+def pick_survivor(issues: List[dict]) -> dict:
+    """Duplicate elimination: issue with sub-issues wins; tiebreak on lowest number.
+
+    Rationale: sub-issues (bug tracking, review fixes) represent
+    accumulated work history. Closing a parent with live sub-issues
+    would orphan them.
+    """
+    with_subs = [i for i in issues if i.get("sub_issue_count", 0) > 0]
+    pool = with_subs if with_subs else issues
+    return min(pool, key=lambda d: d.get("number", 0))
+
+
+# --------------------------------------------------------------------
+# GitHub operations — GraphQL (project fields)
+# --------------------------------------------------------------------
+
+def find_project_item_id(
+    owner: str,
+    name: str,
+    issue_number: int,
+    project_id: str = PROJECT_ID,
+) -> Optional[str]:
+    """Return the ProjectV2Item ID for a given issue, or None if not in project."""
+    q = """
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        issue(number: $number) {
+          projectItems(first: 20) {
+            nodes {
+              id
+              project { id }
+            }
+          }
+        }
+      }
+    }
+    """
+    data = gh_graphql(q, {"owner": owner, "name": name, "number": issue_number})
+    try:
+        items = data["repository"]["issue"]["projectItems"]["nodes"]
+    except (KeyError, TypeError):
+        return None
+    for item in items or []:
+        if (item.get("project") or {}).get("id") == project_id:
+            return item.get("id")
+    return None
+
+
+def add_issue_to_project(
+    issue_node_id: str,
+    project_id: str = PROJECT_ID,
+) -> Optional[str]:
+    """Add an issue to the project. Returns the new ProjectV2Item ID."""
+    q = """
+    mutation($projectId: ID!, $contentId: ID!) {
+      addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) {
+        item { id }
+      }
+    }
+    """
+    data = gh_graphql(q, {"projectId": project_id, "contentId": issue_node_id})
+    try:
+        return data["addProjectV2ItemById"]["item"]["id"]
+    except (KeyError, TypeError):
+        return None
+
+
+def get_issue_node_id(owner: str, name: str, issue_number: int) -> str:
+    q = """
+    query($owner: String!, $name: String!, $number: Int!) {
+      repository(owner: $owner, name: $name) {
+        issue(number: $number) { id }
+      }
+    }
+    """
+    data = gh_graphql(q, {"owner": owner, "name": name, "number": issue_number})
+    return data["repository"]["issue"]["id"]
+
+
+def set_project_field(
+    project_id: str,
+    item_id: str,
+    field_id: str,
+    option_id: str,
+) -> None:
+    q = """
+    mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+      updateProjectV2ItemFieldValue(input: {
+        projectId: $projectId,
+        itemId: $itemId,
+        fieldId: $fieldId,
+        value: { singleSelectOptionId: $optionId }
+      }) { projectV2Item { id } }
+    }
+    """
+    gh_graphql(q, {
+        "projectId": project_id,
+        "itemId": item_id,
+        "fieldId": field_id,
+        "optionId": option_id,
+    })
+
+
+def sync_project_fields(
+    item_id: str,
+    flag_states: dict,
+    project_id: str = PROJECT_ID,
+    status_column: Optional[str] = None,
+    review_progress_n: Optional[int] = None,
+) -> dict:
+    """Apply the 4 flag-state values + Status + Review Progress to a project item.
+
+    Each field mutation is wrapped in its own try/except so a single
+    hanging or failing call doesn't skip the others. Per-field errors
+    are captured in the returned dict as `{flag}:error=<msg>` so the
+    caller can log them.
+
+    If `status_column` is None, the Status field is left untouched.
+    If `review_progress_n` is None, the Review Progress field is left untouched.
+    """
+    applied: dict = {}
+
+    # 4 flag fields
+    for flag, state in flag_states.items():
+        spec = FLAG_FIELDS.get(flag)
+        if not spec:
+            continue
+        option_id = spec["options"].get(state)
+        if not option_id:
+            continue
+        try:
+            set_project_field(project_id, item_id, spec["field_id"], option_id)
+            applied[flag] = state
+        except RuntimeError as e:
+            applied[f"{flag}:error"] = str(e)[:200]
+
+    # Status column (kanban)
+    if status_column is not None:
+        opt = STATUS_OPTIONS.get(status_column)
+        if opt:
+            try:
+                set_project_field(project_id, item_id, STATUS_FIELD_ID, opt)
+                applied["status"] = status_column
+            except RuntimeError as e:
+                applied["status:error"] = str(e)[:200]
+
+    # Review Progress (replaces review:N/4 labels)
+    if review_progress_n is not None:
+        name = review_progress_option_name(review_progress_n)
+        opt = REVIEW_PROGRESS_OPTIONS.get(name)
+        if opt:
+            try:
+                set_project_field(project_id, item_id, REVIEW_PROGRESS_FIELD_ID, opt)
+                applied["review_progress"] = name
+            except RuntimeError as e:
+                applied["review_progress:error"] = str(e)[:200]
+
+    return applied
+
+
+# --------------------------------------------------------------------
+# Flag labels (at-a-glance visibility in the issue list)
+# --------------------------------------------------------------------
+
+def compute_flag_labels_from_states(flag_states: dict) -> List[str]:
+    """Given {flag: state}, return the flag labels that should be applied.
+
+    Label present = flag is green (done and current).
+    Label absent  = flag is gray (not done) OR yellow (stale).
+
+    The yellow state is intentionally invisible at the label layer —
+    it's tracked on the Projects V2 fields so the issue list only
+    shows completed flags, not in-progress or stale ones."""
+    labels: List[str] = []
+    for flag, state in flag_states.items():
+        name = FLAG_LABEL_NAMES.get(flag)
+        if not name:
+            continue
+        if state == "green":
+            labels.append(name)
+    return sorted(labels)
+
+
+def sync_flag_labels(
+    issue_number: int,
+    repo: str,
+    current_labels: List[str],
+    desired_labels: List[str],
+    dry_run: bool,
+) -> dict:
+    """Apply desired flag labels to an issue, remove any drifted ones
+    and any legacy phase:* labels. Only touches managed labels —
+    team/component/review/etc. are untouched."""
+    current_set = set(current_labels)
+    desired_set = set(desired_labels)
+    managed = set(ALL_FLAG_LABELS) | set(LEGACY_PHASE_LABELS)
+
+    to_add = sorted(desired_set - current_set)
+    to_remove = sorted((current_set & managed) - desired_set)
+
+    if not to_add and not to_remove:
+        return {"action": "noop", "added": [], "removed": []}
+
+    args = ["issue", "edit", str(issue_number), "--repo", repo]
+    if to_remove:
+        args += ["--remove-label", ",".join(to_remove)]
+    if to_add:
+        args += ["--add-label", ",".join(to_add)]
+    gh(args, dry_run=dry_run)
+    return {"action": "updated", "added": to_add, "removed": to_remove}
+
+
+# --------------------------------------------------------------------
+# Issue body for new issues
+# --------------------------------------------------------------------
+
+def build_missing_issue_body(entry: dict, flag_states: dict) -> str:
+    node_id = entry.get("nodeId", "")
+    file_key = entry.get("fileKey", "")
+    cn = entry.get("componentName")
+    if isinstance(cn, dict):
+        component_name = cn.get("ios") or cn.get("android") or "Unknown"
+    elif isinstance(cn, str):
+        component_name = cn
+    else:
+        component_name = "Unknown"
+
+    figma_url = (
+        f"https://www.figma.com/design/{file_key}/?node-id={node_id.replace(':', '-')}"
+        if file_key
+        else "_No response_"
+    )
+    table = build_progress_table(flag_states)
+
+    return (
+        f"### Figma URL\n\n{figma_url}\n\n"
+        f"### Node ID\n\n{node_id}\n\n"
+        f"### Registry Name\n\n{component_name}\n\n"
+        f"### Component Name (PascalCase)\n\n{component_name}\n\n"
+        f"### Figma Page\n\nOther\n\n"
+        f"### Jira Issue\n\n_No response_\n\n"
+        f"### Progress\n\n{table}\n"
+        f"### Acceptance Criteria\n\n_No response_\n\n"
+        f"### Pull Requests\n\n- **common:**\n- **uicomponents:**\n\n"
+        f"### Notes\n\n_Auto-created by registry sync on {date.today().isoformat()}._\n"
+    )
+
+
+def create_missing_issue(
+    entry: dict,
+    flag_states: dict,
+    repo: str,
+    team_label: str,
+    dry_run: bool,
+) -> Optional[int]:
+    cn = entry.get("componentName")
+    if isinstance(cn, dict):
+        name = cn.get("ios") or cn.get("android") or "Unknown"
+    else:
+        name = cn if isinstance(cn, str) else "Unknown"
+
+    title = f"feat: Implement {name} component"
+    body = build_missing_issue_body(entry, flag_states)
+
+    args = [
+        "issue", "create",
+        "--repo", repo,
+        "--title", title,
+        "--body", body,
+        "--label", "component",
+        "--label", "redesign",
+        "--label", team_label,
+    ]
+    # Flag labels from computed states
+    for fl in compute_flag_labels_from_states(flag_states):
+        args += ["--label", fl]
+
+    out = gh(args, dry_run=dry_run)
+    if dry_run or not out:
+        return None
+
+    m = re.search(r"/issues/(\d+)", out)
+    return int(m.group(1)) if m else None
+
+
+def rewrite_issue_body(issue_number: int, repo: str, new_body: str, dry_run: bool) -> None:
+    gh(
+        ["issue", "edit", str(issue_number), "--repo", repo, "--body", new_body],
+        dry_run=dry_run,
+    )
+
+
+def get_issue_body(issue_number: int, repo: str) -> str:
+    out = gh(["issue", "view", str(issue_number), "--repo", repo, "--json", "body"])
+    try:
+        return (json.loads(out) or {}).get("body", "")
+    except json.JSONDecodeError:
+        return ""
+
+
+# --------------------------------------------------------------------
+# Orchestration
+# --------------------------------------------------------------------
+
+def sync_one(
+    registry_dir: Path,
+    node_id: str,
+    platform: str,
+    repo: str,
+    team_label: str,
+    dry_run: bool,
+    project_id: str = PROJECT_ID,
+) -> dict:
+    entry = load_entry(registry_dir, node_id)
+    if entry is None:
+        return {"status": "error", "reason": f"registry entry missing for {node_id}"}
+
+    if entry.get("skip"):
+        return {"status": "ok", "action": "skip_marked_skip", "node_id": node_id}
+
+    if is_icon_entry(entry):
+        return {"status": "ok", "action": "skip_icon", "node_id": node_id}
+
+    flag_states = compute_flag_states(entry, platform)
+    implemented_by = get_implemented_by(entry, platform)
+    blocked = is_blocked(node_id, registry_dir, platform)
+
+    if dry_run:
+        # Column + reviews can only be computed after we have the issue in
+        # hand (needs label list + assignees). Compute an approximate column
+        # assuming no labels + no assignees for the dry-run preview.
+        preview_column = compute_status_column(
+            flag_states=flag_states,
+            label_names=[],
+            has_assignees=bool(implemented_by),
+            blocked=blocked,
+        )
+        return {
+            "status": "ok",
+            "dry_run": True,
+            "node_id": node_id,
+            "flag_states": flag_states,
+            "implemented_by": implemented_by,
+            "blocked": blocked,
+            "preview_status_column": preview_column,
+            "progress_table": build_progress_table(flag_states).splitlines(),
+        }
+
+    issues = find_all_open_issues(node_id, repo, dry_run=False)
+    owner, name = repo.split("/", 1)
+
+    result: dict = {
+        "status": "ok",
+        "node_id": node_id,
+        "flag_states": flag_states,
+    }
+
+    # --- Zero issues: create ---------------------------------------
+    if not issues:
+        new_num = create_missing_issue(
+            entry=entry,
+            flag_states=flag_states,
+            repo=repo,
+            team_label=team_label,
+            dry_run=False,
+        )
+        if new_num is None:
+            result["action"] = "create_failed"
+            return result
+
+        # Assignee from implementedBy (best-effort)
+        if implemented_by:
+            add_assignees(new_num, repo, [implemented_by], dry_run=False)
+            result["assignee"] = implemented_by
+
+        # Compute status column for the freshly created issue. It has at most
+        # one assignee (implemented_by) and zero labels at this point — so
+        # bugfix/review-count inputs are empty.
+        new_status_column = compute_status_column(
+            flag_states=flag_states,
+            label_names=[],
+            has_assignees=bool(implemented_by),
+            blocked=blocked,
+        )
+        new_review_n = 0  # fresh issue, no reviews yet
+
+        # Add to project, then set fields
+        try:
+            issue_node_id = get_issue_node_id(owner, name, new_num)
+            item_id = add_issue_to_project(issue_node_id, project_id) or find_project_item_id(owner, name, new_num, project_id)
+            if item_id:
+                applied = sync_project_fields(
+                    item_id,
+                    flag_states,
+                    project_id,
+                    status_column=new_status_column,
+                    review_progress_n=new_review_n,
+                )
+                result["project_fields"] = applied
+        except RuntimeError as e:
+            result["project_fields_error"] = str(e)
+
+        result["action"] = "created"
+        result["issue_number"] = new_num
+        result["status_column"] = new_status_column
+        return result
+
+    # --- Multiple issues: duplicate rule with full conflation ------
+    conflation_log: List[dict] = []
+    if len(issues) > 1:
+        keep = pick_survivor(issues)
+        for dup in issues:
+            if dup.get("number") == keep.get("number"):
+                continue
+            transfer_log = conflate_duplicate(dup, keep["number"], repo, dry_run=False)
+            conflation_log.append(transfer_log)
+        result["closed_duplicates"] = [c["loser"] for c in conflation_log]
+        result["conflation"] = conflation_log
+        survivor = keep
+    else:
+        survivor = issues[0]
+        result["closed_duplicates"] = []
+
+    keep_number = survivor["number"]
+    result["issue_number"] = keep_number
+    result["sub_issue_count"] = survivor.get("sub_issue_count", 0)
+
+    # --- Sync the survivor -----------------------------------------
+    new_body = rewrite_progress_table(survivor.get("body", ""), flag_states)
+    if new_body != survivor.get("body", ""):
+        rewrite_issue_body(keep_number, repo, new_body, dry_run=False)
+        result["body"] = "rewritten"
+    else:
+        result["body"] = "unchanged"
+
+    # Flag labels (at-a-glance visibility in the issue list)
+    current_label_names = [
+        lbl.get("name", "") for lbl in survivor.get("labels", []) if isinstance(lbl, dict)
+    ]
+    desired_flag_labels = compute_flag_labels_from_states(flag_states)
+    label_result = sync_flag_labels(
+        issue_number=keep_number,
+        repo=repo,
+        current_labels=current_label_names,
+        desired_labels=desired_flag_labels,
+        dry_run=False,
+    )
+    result["label_diff"] = label_result
+
+    # Assignee from implementedBy — additive, never removes existing assignees
+    if implemented_by:
+        try:
+            current_assignees = get_issue_assignees(keep_number, repo)
+        except RuntimeError:
+            current_assignees = []
+        if implemented_by not in current_assignees:
+            add_assignees(keep_number, repo, [implemented_by], dry_run=False)
+            result["assignee_added"] = implemented_by
+        else:
+            result["assignee_noop"] = implemented_by
+
+    # --- Bug sub-issue count (for Bugfix column + label cleanup) -----
+    open_bugs = 0
+    try:
+        open_bugs = count_open_bug_sub_issues(owner, name, keep_number)
+    except RuntimeError:
+        pass
+    result["open_bug_sub_issues"] = open_bugs
+
+    # Auto-remove stale review-fix label: if no open bug sub-issues
+    # remain but the parent still carries review-fix, strip it so the
+    # component can exit the Bugfix column.
+    if open_bugs == 0 and "review-fix" in current_label_names:
+        try:
+            gh(["issue", "edit", str(keep_number), "--repo", repo,
+                "--remove-label", "review-fix"])
+            current_label_names = [l for l in current_label_names if l != "review-fix"]
+            result["review_fix_label"] = "auto_removed"
+        except RuntimeError:
+            result["review_fix_label"] = "remove_failed"
+
+    # --- Effective review progress (stale-aware) ----------------------
+    review_n = effective_review_progress(current_label_names, flag_states)
+    raw_review_n = parse_review_progress_from_labels(current_label_names)
+
+    # If effective reviews differ from raw (stale), strip old review label
+    # and set review:0/4 so labels match the effective state.
+    if review_n != raw_review_n and raw_review_n > 0:
+        stale_label = f"review:{raw_review_n}/4"
+        try:
+            args_remove = ["issue", "edit", str(keep_number), "--repo", repo,
+                           "--remove-label", stale_label,
+                           "--add-label", "review:0/4"]
+            gh(args_remove)
+            current_label_names = [l for l in current_label_names if l != stale_label] + ["review:0/4"]
+            result["review_reset"] = f"{stale_label} -> review:0/4 (stale)"
+        except RuntimeError:
+            result["review_reset"] = f"failed to reset {stale_label}"
+
+    # --- Compute status column ----------------------------------------
+    try:
+        current_assignees_for_col = get_issue_assignees(keep_number, repo)
+    except RuntimeError:
+        current_assignees_for_col = []
+    has_assignees_now = bool(current_assignees_for_col) or bool(implemented_by)
+
+    status_column = compute_status_column(
+        flag_states=flag_states,
+        label_names=current_label_names,
+        has_assignees=has_assignees_now,
+        blocked=blocked,
+        open_bug_sub_issues=open_bugs,
+    )
+    result["status_column"] = status_column
+    result["review_progress"] = review_progress_option_name(review_n)
+    result["blocked"] = blocked
+
+    try:
+        item_id = find_project_item_id(owner, name, keep_number, project_id)
+        if not item_id:
+            # Survivor isn't on the project — add it
+            issue_node_id = get_issue_node_id(owner, name, keep_number)
+            item_id = add_issue_to_project(issue_node_id, project_id)
+        if item_id:
+            applied = sync_project_fields(
+                item_id,
+                flag_states,
+                project_id,
+                status_column=status_column,
+                review_progress_n=review_n,
+            )
+            result["project_fields"] = applied
+        else:
+            result["project_fields_error"] = "could not resolve project item"
+    except RuntimeError as e:
+        result["project_fields_error"] = str(e)
+
+    result["action"] = "synced"
+    return result
+
+
+# --------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Sync one node's GitHub issue to the component registry state",
+    )
+    parser.add_argument("--node-id", required=True)
+    parser.add_argument("--platform", default="ios", choices=["ios", "android"])
+    parser.add_argument("--registry-dir")
+    parser.add_argument("--repo", default=DEFAULT_REPO)
+    parser.add_argument("--team-label", default=DEFAULT_TEAM_LABEL)
+    parser.add_argument("--dry-run", action="store_true")
+    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
+
+    try:
+        result = sync_one(
+            registry_dir=registry_dir,
+            node_id=args.node_id,
+            platform=args.platform,
+            repo=args.repo,
+            team_label=args.team_label,
+            dry_run=args.dry_run,
+        )
+    except RuntimeError as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("status") == "ok" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())