Plugin Marketplace Publisher skill for Claude Code

#!/usr/bin/env python3
"""Validate Claude Code plugins and marketplaces before publishing.

Usage:
    python3 check_plugin.py <path>

<path> may be a plugin root (contains .claude-plugin/plugin.json), a marketplace repo
(contains .claude-plugin/marketplace.json), or any directory containing either; all
plugins found below it are checked.

Exit code 1 if any error is found, else 0. Standard library only.
"""
from __future__ import annotations

import json
import re
import sys
from pathlib import Path

KEBAB = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
SEMVER = re.compile(r"^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$")
KNOWN_PLUGIN_KEYS = {"name", "version", "description", "author", "homepage", "repository", "license",
                     "keywords", "commands", "agents", "skills", "hooks", "mcpServers", "outputStyles", "lspServers"}
HOOK_EVENTS = {"PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SubagentStop", "SessionStart",
               "SessionEnd", "Notification", "PreCompact", "PermissionRequest"}
COMPONENT_DIRS = ("skills", "agents", "commands", "hooks")
SECRET_RES = [re.compile(p) for p in (r"sk-[A-Za-z0-9_-]{20,}", r"AKIA[0-9A-Z]{16}",
                                      r"gh[pousr]_[A-Za-z0-9]{30,}", r"-----BEGIN [A-Z ]*PRIVATE KEY-----")]
SKIP = {".git", "node_modules", ".venv", "__pycache__"}

errors: list[str] = []
warnings: list[str] = []


def load_json(path: Path):
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except json.JSONDecodeError as e:
        errors.append(f"{path}: invalid JSON ({e})")
    except OSError as e:
        errors.append(f"{path}: cannot read ({e})")
    return None


def frontmatter(path: Path) -> dict[str, str]:
    text = path.read_text(encoding="utf-8", errors="replace")
    m = re.match(r"^---\n(.*?)\n---", text, re.S)
    if not m:
        return {}
    return {k: v.strip().strip('"\'') for k, v in re.findall(r"^([\w-]+):\s*(.*)$", m.group(1), re.M)}


def check_commands_in(obj, where: str, root: Path) -> None:
    """Walk hook/MCP config, flag commands and args that escape the plugin root."""
    if isinstance(obj, dict):
        for k, v in obj.items():
            if k in ("command", "args") or isinstance(v, (dict, list)):
                check_commands_in(v, where, root)
    elif isinstance(obj, list):
        for v in obj:
            check_commands_in(v, where, root)
    elif isinstance(obj, str):
        if "CLAUDE_PROJECT_DIR" in obj:
            warnings.append(f"{where}: uses $CLAUDE_PROJECT_DIR (the user's repo); plugin files need ${{CLAUDE_PLUGIN_ROOT}}")
        if re.search(r"(^|[\s\"'])\.\.?/", obj) and "CLAUDE_PLUGIN_ROOT" not in obj:
            warnings.append(f"{where}: relative path in {obj!r}; plugins run from a cache dir, use ${{CLAUDE_PLUGIN_ROOT}}")
        if "../" in obj:
            errors.append(f"{where}: path escapes the plugin root: {obj!r}")


def check_plugin(root: Path) -> str | None:
    manifest = root / ".claude-plugin" / "plugin.json"
    data = load_json(manifest)
    if not isinstance(data, dict):
        return None
    name = data.get("name", "")
    tag = f"[plugin {name or root.name}]"
    if not name:
        errors.append(f"{tag} plugin.json missing required 'name'")
    elif not KEBAB.match(name):
        errors.append(f"{tag} name {name!r} must be kebab-case")
    ver = data.get("version")
    if ver is None:
        warnings.append(f"{tag} no 'version'; updates cannot be tracked")
    elif not SEMVER.match(str(ver)):
        errors.append(f"{tag} version {ver!r} is not semver")
    if not data.get("description"):
        warnings.append(f"{tag} no 'description'")
    for k in data:
        if k not in KNOWN_PLUGIN_KEYS:
            warnings.append(f"{tag} unknown plugin.json key {k!r}")

    for d in COMPONENT_DIRS + (".mcp.json",):
        if (root / ".claude-plugin" / d).exists():
            errors.append(f"{tag} {d} is inside .claude-plugin/; move it to the plugin root")
    found = [d for d in COMPONENT_DIRS if (root / d).exists()] + ([".mcp.json"] if (root / ".mcp.json").exists() else [])
    if not found and not any(k in data for k in ("commands", "agents", "skills", "hooks", "mcpServers")):
        errors.append(f"{tag} no components found (skills/, agents/, commands/, hooks/, .mcp.json)")

    skills = root / "skills"
    if skills.is_dir():
        for sk in sorted(p for p in skills.iterdir() if p.is_dir()):
            f = sk / "SKILL.md"
            if not f.is_file():
                errors.append(f"{tag} skills/{sk.name}/ has no SKILL.md")
                continue
            fm = frontmatter(f)
            if fm.get("name") != sk.name:
                errors.append(f"{tag} skills/{sk.name}/SKILL.md name {fm.get('name')!r} != folder")
            if not fm.get("description"):
                errors.append(f"{tag} skills/{sk.name}/SKILL.md missing description")
    agents = root / "agents"
    if agents.is_dir():
        for a in sorted(agents.glob("*.md")):
            fm = frontmatter(a)
            for key in ("name", "description"):
                if not fm.get(key):
                    errors.append(f"{tag} agents/{a.name} missing frontmatter {key!r}")
    hooks_file = root / "hooks" / "hooks.json"
    if hooks_file.exists():
        hd = load_json(hooks_file)
        if isinstance(hd, dict):
            events = hd.get("hooks")
            if not isinstance(events, dict):
                errors.append(f"{tag} hooks/hooks.json must have a top-level 'hooks' object")
            else:
                for ev in events:
                    if ev not in HOOK_EVENTS:
                        warnings.append(f"{tag} hooks.json: unrecognized event {ev!r}")
                check_commands_in(events, f"{tag} hooks.json", root)
    mcp = root / ".mcp.json"
    if mcp.exists():
        md = load_json(mcp)
        if isinstance(md, dict):
            if "mcpServers" not in md:
                errors.append(f"{tag} .mcp.json missing 'mcpServers'")
            else:
                check_commands_in(md["mcpServers"], f"{tag} .mcp.json", root)

    for p in root.rglob("*"):
        if p.is_file() and not any(s in p.parts for s in SKIP) and p.stat().st_size < 1_000_000:
            try:
                text = p.read_text(encoding="utf-8")
            except (UnicodeDecodeError, OSError):
                continue
            for rx in SECRET_RES:
                if rx.search(text):
                    errors.append(f"{tag} secret-like string in {p.relative_to(root)}")
                    break
        if p.is_symlink():
            target = p.resolve()
            if root.resolve() not in target.parents:
                warnings.append(f"{tag} symlink {p.relative_to(root)} points outside the plugin")
    if not (root / "README.md").exists():
        warnings.append(f"{tag} no README.md (document env vars and usage)")
    print(f"checked plugin {name or root.name} ({root}) components: {', '.join(found) or 'manifest paths'}")
    return name


def check_marketplace(repo: Path) -> None:
    path = repo / ".claude-plugin" / "marketplace.json"
    data = load_json(path)
    if not isinstance(data, dict):
        return
    mname = data.get("name", "")
    tag = f"[marketplace {mname or repo.name}]"
    if not mname or not KEBAB.match(mname):
        errors.append(f"{tag} 'name' missing or not kebab-case")
    if not isinstance(data.get("owner"), dict) or not data["owner"].get("name"):
        errors.append(f"{tag} 'owner.name' is required")
    plugins = data.get("plugins")
    if not isinstance(plugins, list) or not plugins:
        errors.append(f"{tag} 'plugins' must be a non-empty list")
        return
    root_prefix = (data.get("metadata") or {}).get("pluginRoot", "")
    seen: set[str] = set()
    for i, entry in enumerate(plugins):
        if not isinstance(entry, dict):
            errors.append(f"{tag} plugins[{i}] is not an object")
            continue
        pname = entry.get("name", "")
        if not pname:
            errors.append(f"{tag} plugins[{i}] missing 'name'")
        if pname in seen:
            errors.append(f"{tag} duplicate plugin name {pname!r}")
        seen.add(pname)
        src = entry.get("source")
        if src is None:
            errors.append(f"{tag} {pname}: missing 'source'")
        elif isinstance(src, str):
            rel = src if src.startswith(("./", "../")) or not root_prefix else f"{root_prefix.rstrip('/')}/{src}"
            pdir = (repo / rel).resolve()
            if not pdir.is_dir():
                errors.append(f"{tag} {pname}: source {src!r} does not exist")
            elif not (pdir / ".claude-plugin" / "plugin.json").is_file():
                if entry.get("strict", True):
                    errors.append(f"{tag} {pname}: {src} has no .claude-plugin/plugin.json")
            else:
                pdata = load_json(pdir / ".claude-plugin" / "plugin.json") or {}
                if pdata.get("name") != pname:
                    errors.append(f"{tag} entry {pname!r} != plugin.json name {pdata.get('name')!r}")
                if entry.get("version") and pdata.get("version") and entry["version"] != pdata["version"]:
                    warnings.append(f"{tag} {pname}: version {entry['version']} in marketplace vs {pdata['version']} in plugin.json")
        elif isinstance(src, dict):
            kind = src.get("source")
            if kind == "github" and not re.match(r"^[\w.-]+/[\w.-]+$", str(src.get("repo", ""))):
                errors.append(f"{tag} {pname}: github source needs repo 'owner/name'")
            elif kind == "url" and not str(src.get("url", "")).startswith(("https://", "git@", "ssh://")):
                errors.append(f"{tag} {pname}: url source needs a git URL")
            elif kind not in ("github", "url", "git", "npm", "pip", "git-subdir"):
                warnings.append(f"{tag} {pname}: unrecognized source type {kind!r}")
        if not entry.get("description"):
            warnings.append(f"{tag} {pname}: no description (shown in /plugin browse)")
    print(f"checked marketplace {mname} ({len(plugins)} plugins)")


def main() -> int:
    if len(sys.argv) != 2:
        print(__doc__.strip())
        return 2
    base = Path(sys.argv[1]).resolve()
    manifests = [p for p in base.rglob("plugin.json")
                 if p.parent.name == ".claude-plugin" and not any(s in p.parts for s in SKIP)]
    markets = [p for p in base.rglob("marketplace.json")
               if p.parent.name == ".claude-plugin" and not any(s in p.parts for s in SKIP)]
    if not manifests and not markets:
        print(f"No .claude-plugin/plugin.json or marketplace.json found under {base}")
        return 1
    for m in sorted(markets):
        check_marketplace(m.parent.parent)
    for m in sorted(manifests):
        check_plugin(m.parent.parent)
    for e in errors:
        print(f"ERROR   {e}")
    for w in warnings:
        print(f"WARNING {w}")
    print(f"Result: {'FAIL' if errors else 'PASS'} ({len(errors)} errors, {len(warnings)} warnings)")
    return 1 if errors else 0


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