#!/usr/bin/env python3
"""Keep the OpenHands extensions registry in sync.

Four sync tasks, runnable individually or all at once:

  1. **commands**  — generate Claude Code ``commands/<trigger>.md`` files from
     SKILL.md slash-triggers.
  2. **catalog**   — regenerate the auto-generated catalog section in README.md.
  3. **coverage**  — warn when a skill/plugin directory is not listed in any
     marketplace, or a marketplace entry points to a missing directory.
  4. **symlinks**  — enforce ``.plugin/`` as the canonical manifest directory
     with vendor symlinks (``.claude-plugin``, ``.codex-plugin``).

Usage:
    python scripts/sync_extensions.py                   # run all, write changes
    python scripts/sync_extensions.py --check           # CI mode — exit 1 if anything is out of sync
    python scripts/sync_extensions.py commands           # only sync command files
    python scripts/sync_extensions.py catalog            # only regenerate README catalog
    python scripts/sync_extensions.py coverage           # only check marketplace coverage
    python scripts/sync_extensions.py symlinks           # only check/fix vendor symlinks
    python scripts/sync_extensions.py commands catalog   # combine sub-commands
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from dataclasses import dataclass
from pathlib import Path

import yaml  # requires: pip install pyyaml (also in pyproject.toml [test] group)

REPO_ROOT = Path(__file__).resolve().parent.parent
README_PATH = REPO_ROOT / "README.md"
SKILL_DIRS = [REPO_ROOT / "skills", REPO_ROOT / "plugins"]
MARKETPLACES_DIR = REPO_ROOT / "marketplaces"
# Max description length in the catalog table.  120 chars fits GitHub's
# diff viewer and rendered Markdown tables without horizontal scroll.
MAX_DESC_LEN = 120

# Sentinel markers in README.md
CATALOG_BEGIN = "<!-- BEGIN AUTO-GENERATED CATALOG -->"
CATALOG_END = "<!-- END AUTO-GENERATED CATALOG -->"

# Marker for auto-generated Claude Code command files (YAML comment inside frontmatter)
CMD_MARKER = "# auto-generated by sync_extensions.py"
# Also recognize the legacy HTML-comment headers from older versions of the script
_LEGACY_CMD_MARKERS = [
    "<!-- AUTO-GENERATED by scripts/sync_extensions.py",
    "<!-- AUTO-GENERATED by scripts/sync_claude_commands.py",
]


# ── Frontmatter helpers ──────────────────────────────────────────────

def parse_frontmatter(text: str) -> dict[str, str | list[str]]:
    """Extract name, description, and triggers from YAML frontmatter.

    Uses PyYAML for robust parsing.  Returns an empty dict when the
    frontmatter is missing or malformed.
    """
    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
    if not m:
        return {}
    block = m.group(1)
    try:
        data = yaml.safe_load(block)
    except yaml.YAMLError as exc:
        print(f"[warning] malformed YAML frontmatter: {exc}", file=sys.stderr)
        return {}
    if not isinstance(data, dict):
        return {}
    result: dict[str, str | list[str]] = {}
    for key in ("name", "description"):
        if key in data and data[key] is not None:
            result[key] = str(data[key]).strip()
    triggers = data.get("triggers")
    if isinstance(triggers, list):
        result["triggers"] = [str(t).strip() for t in triggers if t is not None]
    else:
        result["triggers"] = []
    return result


def slash_triggers(meta: dict) -> list[str]:
    return [t for t in meta.get("triggers", []) if isinstance(t, str) and t.startswith("/")]


# ── Marketplace loading ──────────────────────────────────────────────

def load_marketplaces() -> list[dict]:
    """Return list of parsed marketplace dicts, sorted by filename."""
    mps: list[dict] = []
    for mp_file in sorted(MARKETPLACES_DIR.glob("*.json")):
        try:
            with open(mp_file) as f:
                data = json.load(f)
        except (json.JSONDecodeError, OSError) as exc:
            print(f"[warning] skipping {mp_file.name}: {exc}", file=sys.stderr)
            continue
        data["_file"] = mp_file
        mps.append(data)
    return mps


# ── 1. Claude Code command sync ──────────────────────────────────────

def build_command_content(description: str) -> str:
    lines = [
        "---",
        CMD_MARKER,
        f"description: {description}",
        "---",
        "",
        "Read and follow the complete instructions in the SKILL.md file located in this skill's directory.",
        "",
        "$ARGUMENTS",
        "",
    ]
    return "\n".join(lines)


@dataclass
class CommandSpec:
    """A Claude Code command file that should exist for a slash trigger."""
    path: Path
    trigger: str
    description: str


def collect_needed_commands() -> list[CommandSpec]:
    """Return a CommandSpec for every slash trigger found in SKILL.md files."""
    needed: list[CommandSpec] = []
    for base in SKILL_DIRS:
        if not base.is_dir():
            continue
        for skill_dir in sorted(base.iterdir()):
            skill_md = skill_dir / "SKILL.md"
            if not skill_md.is_file():
                continue
            meta = parse_frontmatter(skill_md.read_text())
            desc = str(meta.get("description", ""))
            for trigger in slash_triggers(meta):
                # Replace colons with dashes for cross-platform filename compatibility
                cmd_name = trigger.lstrip("/").replace(":", "-")
                cmd_path = skill_dir / "commands" / f"{cmd_name}.md"
                needed.append(CommandSpec(path=cmd_path, trigger=trigger, description=desc))
    return needed


def sync_commands(*, check: bool) -> list[str]:
    """Returns list of problem descriptions (empty = all good)."""
    problems: list[str] = []
    for spec in collect_needed_commands():
        expected = build_command_content(spec.description)
        cmd_path = spec.path
        if cmd_path.is_file():
            existing = cmd_path.read_text()
            if existing == expected:
                continue
            is_auto = CMD_MARKER in existing or any(m in existing for m in _LEGACY_CMD_MARKERS)
            if not is_auto:
                rel = cmd_path.relative_to(REPO_ROOT)
                msg = (
                    f"{rel} exists but has no auto-generated marker "
                    f"— it won't be updated.  Add the marker or delete "
                    f"the file to let sync manage it."
                )
                if check:
                    problems.append(f"manually-edited: {rel}")
                else:
                    print(f"[warning] {msg}", file=sys.stderr)
                continue
            problems.append(f"stale: {cmd_path.relative_to(REPO_ROOT)}")
        else:
            problems.append(f"missing: {cmd_path.relative_to(REPO_ROOT)}")

        if not check:
            cmd_path.parent.mkdir(parents=True, exist_ok=True)
            cmd_path.write_text(expected)

    return problems


# ── 2. README catalog generation ─────────────────────────────────────

def _entry_type(source: str) -> str:
    """Classify a marketplace entry as ``"skill"`` or ``"plugin"``.

    Checks the source path prefix first, then falls back to examining
    the resolved directory contents (SKILL.md → skill, hooks/ or
    scripts/ → plugin).  Returns ``"skill"`` as the default when the
    type cannot be determined, since most entries are skills.
    """
    if source.startswith("./skills/") or source.startswith("../skills/"):
        return "skill"
    if source.startswith("./plugins/") or source.startswith("../plugins/"):
        return "plugin"
    resolved = REPO_ROOT / source.lstrip("./")
    if resolved.is_dir():
        if "skills" in resolved.parts:
            return "skill"
        if "plugins" in resolved.parts:
            return "plugin"
        # Infer from directory contents
        if (resolved / "hooks").is_dir() or (resolved / "scripts").is_dir():
            return "plugin"
    return "skill"


_slash_cmd_cache: dict[str, list[str]] = {}


def _get_slash_commands(source: str) -> list[str]:
    """Read SKILL.md from source path to extract slash triggers (cached)."""
    if source in _slash_cmd_cache:
        return _slash_cmd_cache[source]
    skill_md = REPO_ROOT / source.lstrip("./") / "SKILL.md"
    if not skill_md.is_file():
        _slash_cmd_cache[source] = []
        return []
    meta = parse_frontmatter(skill_md.read_text())
    result = slash_triggers(meta)
    _slash_cmd_cache[source] = result
    return result


def _format_marketplace_section(mp: dict) -> list[str]:
    """Format a single marketplace as Markdown lines."""
    mp_name = mp.get("name", mp["_file"].stem)
    mp_desc = mp.get("metadata", {}).get("description", "")
    plugins = mp.get("plugins", [])
    skill_count = sum(1 for p in plugins if _entry_type(p.get("source", "")) == "skill")
    plugin_count = sum(1 for p in plugins if _entry_type(p.get("source", "")) == "plugin")

    lines: list[str] = []
    lines.append(f"### {mp_name}")
    lines.append("")
    if mp_desc:
        lines.append(mp_desc)
        lines.append("")
    lines.append(f"**{len(plugins)} extensions** ({skill_count} skills, {plugin_count} plugins)")
    lines.append("")
    lines.append("| Name | Type | Description | Commands |")
    lines.append("|------|------|-------------|----------|")
    for p in sorted(plugins, key=lambda x: x["name"]):
        name = p["name"]
        etype = _entry_type(p.get("source", ""))
        desc = (p.get("description") or "").replace("|", "\\|")
        if len(desc) > MAX_DESC_LEN:
            desc = desc[:MAX_DESC_LEN - 3] + "..."
        cmds = _get_slash_commands(p.get("source", ""))
        cmds_str = ", ".join(f"`{c}`" for c in cmds) if cmds else "—"
        lines.append(f"| {name} | {etype} | {desc} | {cmds_str} |")

    lines.append("")
    return lines


def generate_catalog() -> str:
    """Build the Markdown catalog section."""
    mps = load_marketplaces()
    total_skills = 0
    total_plugins = 0

    for mp in mps:
        for p in mp.get("plugins", []):
            t = _entry_type(p.get("source", ""))
            if t == "skill":
                total_skills += 1
            elif t == "plugin":
                total_plugins += 1

    lines: list[str] = [""]
    total = sum(len(mp.get("plugins", [])) for mp in mps)
    lines.append(
        f"This repository contains **{len(mps)} marketplace(s)** "
        f"with **{total} extensions** ({total_skills} skills, {total_plugins} plugins)."
    )
    lines.append("")

    for mp in mps:
        lines.extend(_format_marketplace_section(mp))
    return "\n".join(lines)


def sync_catalog(*, check: bool) -> list[str]:
    """Returns list of problem descriptions (empty = all good)."""
    if not README_PATH.is_file():
        return ["README.md not found"]

    readme = README_PATH.read_text()
    if CATALOG_BEGIN not in readme or CATALOG_END not in readme:
        return [
            f"README.md missing catalog markers ({CATALOG_BEGIN} / {CATALOG_END}). "
            "Add them where the catalog should appear."
        ]

    before = readme[: readme.index(CATALOG_BEGIN) + len(CATALOG_BEGIN)]
    after = readme[readme.index(CATALOG_END) :]
    existing_catalog = readme[len(before) : readme.index(CATALOG_END)]

    new_catalog = generate_catalog()

    if existing_catalog == new_catalog:
        return []

    if check:
        return ["README.md catalog section is out of date"]

    README_PATH.write_text(before + new_catalog + after)
    return []


# ── 3. Marketplace coverage ─────────────────────────────────────────

def sync_coverage(*, check: bool) -> list[str]:
    """Check that every directory is in a marketplace and vice versa."""
    # Collect all dirs with SKILL.md or .plugin/plugin.json (or vendor symlinks like .claude-plugin)
    all_dirs: set[str] = set()
    for base in SKILL_DIRS:
        if not base.is_dir():
            continue
        for d in base.iterdir():
            if not d.is_dir() or d.name.startswith("."):
                continue
            has_skill = (d / "SKILL.md").exists()
            has_plugin = (
                (d / ".claude-plugin" / "plugin.json").exists()
                or (d / ".plugin" / "plugin.json").exists()
            )
            if has_skill or has_plugin:
                all_dirs.add(f"./{base.name}/{d.name}")

    # Collect all marketplace sources
    all_sources: set[str] = set()
    for mp in load_marketplaces():
        for p in mp.get("plugins", []):
            all_sources.add(p.get("source", ""))

    # Collect skill dirs that are symlink targets inside a plugin's skills/
    # subdirectory — these are covered by the parent plugin entry.
    symlink_targets: set[str] = set()
    plugins_dir = REPO_ROOT / "plugins"
    if plugins_dir.is_dir():
        for plugin_dir in plugins_dir.iterdir():
            skills_sub = plugin_dir / "skills"
            if not skills_sub.is_dir():
                continue
            for entry in skills_sub.iterdir():
                if entry.is_symlink():
                    resolved = entry.resolve()
                    try:
                        rel = f"./{resolved.relative_to(REPO_ROOT)}"
                        symlink_targets.add(rel)
                    except ValueError:
                        pass

    problems: list[str] = []

    missing_from_mp = sorted(all_dirs - all_sources - symlink_targets)
    for d in missing_from_mp:
        problems.append(f"not in any marketplace: {d}")

    ghost_entries = sorted(all_sources - all_dirs)
    for s in ghost_entries:
        p = REPO_ROOT / s.lstrip("./")
        if not p.is_dir():
            problems.append(f"marketplace entry points to missing directory: {s}")
        else:
            problems.append(f"marketplace entry has no SKILL.md or plugin.json: {s}")

    return problems


# ── 4. Vendor symlinks ────────────────────────────────────────────────

VENDOR_SYMLINKS = [".claude-plugin", ".codex-plugin"]  # add new vendors here


def _check_vendor_symlinks(directory: Path, check: bool) -> list[str]:
    """Check/fix vendor symlinks for a single directory with .plugin/."""
    problems: list[str] = []
    canon = directory / ".plugin"
    if not canon.is_dir():
        return problems
    for vendor in VENDOR_SYMLINKS:
        link = directory / vendor
        if link.is_symlink():
            target = link.resolve()
            if target == canon.resolve():
                continue
            problems.append(f"wrong target: {link.relative_to(REPO_ROOT)} → {link.readlink()}")
        elif link.exists():
            problems.append(f"not a symlink: {link.relative_to(REPO_ROOT)}")
            continue
        else:
            problems.append(f"missing: {link.relative_to(REPO_ROOT)}")
        if not check:
            link.unlink(missing_ok=True)
            link.symlink_to(".plugin")
    return problems


def sync_symlinks(*, check: bool) -> list[str]:
    """Ensure every directory with .plugin/ also has vendor symlinks.

    Scans both plugins/ and skills/ directories.  Skills that ship a
    ``.plugin/`` manifest (e.g. those with ``commands/``) need vendor
    symlinks so that Codex and Claude Code can discover them.
    """
    problems: list[str] = []
    for base in SKILL_DIRS:
        if not base.is_dir():
            continue
        for entry_dir in sorted(base.iterdir()):
            if not entry_dir.is_dir() or entry_dir.name.startswith("."):
                continue
            problems.extend(_check_vendor_symlinks(entry_dir, check))
    return problems


# ── Main ─────────────────────────────────────────────────────────────

ALL_SYNCS = {
    "commands": sync_commands,
    "catalog": sync_catalog,
    "coverage": sync_coverage,
    "symlinks": sync_symlinks,
}


def main() -> int:
    parser = argparse.ArgumentParser(
        description="Keep the OpenHands extensions registry in sync.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    valid_tasks = list(ALL_SYNCS.keys())
    parser.add_argument(
        "tasks",
        nargs="*",
        default=[],
        metavar="TASK",
        help=f"Which sync tasks to run: {', '.join(valid_tasks)} (default: all).",
    )
    parser.add_argument(
        "--check",
        action="store_true",
        help="Check mode: exit 1 if anything is out of sync (for CI).",
    )
    args = parser.parse_args()
    for t in args.tasks:
        if t not in ALL_SYNCS:
            parser.error(f"unknown task: {t!r} (choose from {', '.join(valid_tasks)})")
    tasks = args.tasks or list(ALL_SYNCS.keys())

    all_problems: dict[str, list[str]] = {}
    for task in tasks:
        fn = ALL_SYNCS[task]
        problems = fn(check=args.check)
        if problems:
            all_problems[task] = problems

    if all_problems:
        for task, problems in all_problems.items():
            severity = "warning" if task == "coverage" else "error"
            print(f"\n[{severity}] {task}:")
            for p in problems:
                print(f"  {p}")
        if args.check:
            has_errors = any(k != "coverage" for k in all_problems)
            has_warnings = "coverage" in all_problems
            if has_errors:
                print(f"\nRun `python scripts/sync_extensions.py` to fix.")
                return 1
            if has_warnings:
                # Coverage warnings don't fail CI, just warn
                print(f"\n⚠️  Coverage warnings above are non-blocking.")
                return 0
        else:
            print("\nSync complete.")
        return 0

    if args.check:
        print("All extensions in sync. ✓")
    else:
        print("Everything already up to date.")
    return 0


if __name__ == "__main__":
    sys.exit(main())