kanon-cli 1.0.0__py3-none-any.whl

kanon_cli/core/marketplace.py

@@ -0,0 +1,433 @@
+"""Shared marketplace operations for Claude Code plugin install/uninstall.
+
+Provides functions for locating the claude binary, discovering marketplace
+entries and plugins, and orchestrating plugin install/uninstall lifecycles.
+Used by both ``core.install`` (install) and ``core.clean`` (uninstall).
+"""
+
+import json
+import os
+import pathlib
+import shutil
+import subprocess
+import sys
+
+
+def locate_claude_binary() -> str:
+    """Locate the claude CLI binary on $PATH.
+
+    Uses shutil.which("claude") to find the binary.
+
+    Returns:
+        Absolute path to the claude binary.
+
+    Raises:
+        SystemExit: Exits with code 1 if claude is not found on $PATH.
+    """
+    path = shutil.which("claude")
+    if path is None:
+        print(
+            "Error: claude binary not found on $PATH. Ensure claude is installed and available.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return os.path.abspath(path)
+
+
+def get_marketplace_dir(globals_dict: dict[str, str]) -> pathlib.Path:
+    """Return Path to marketplace directory from globals_dict.
+
+    Args:
+        globals_dict: Parsed .kanon globals containing CLAUDE_MARKETPLACES_DIR.
+
+    Returns:
+        pathlib.Path to the marketplace directory.
+    """
+    env_value = globals_dict.get("CLAUDE_MARKETPLACES_DIR", "")
+    if env_value:
+        return pathlib.Path(env_value)
+    return pathlib.Path.home() / ".claude-marketplaces"
+
+
+def discover_marketplace_entries(marketplace_dir: pathlib.Path) -> list[pathlib.Path]:
+    """Discover marketplace entries in the given directory.
+
+    Returns sorted list of non-hidden entries that are directories or
+    symlinks to directories. Hidden entries (dot-prefixed) are excluded.
+    Broken symlinks are logged as warnings and excluded.
+
+    Args:
+        marketplace_dir: Path to the marketplace directory.
+
+    Returns:
+        Alphabetically sorted list of Path objects.
+    """
+    entries = []
+    for entry in sorted(marketplace_dir.iterdir()):
+        if entry.name.startswith("."):
+            continue
+        if entry.is_symlink() and not entry.exists():
+            print(
+                f"Warning: Broken symlink detected and skipped: {entry}",
+                file=sys.stderr,
+            )
+            continue
+        if entry.is_dir():
+            entries.append(entry)
+    return entries
+
+
+def read_marketplace_name(marketplace_path: pathlib.Path) -> str:
+    """Read marketplace name from .claude-plugin/marketplace.json.
+
+    Args:
+        marketplace_path: Path to the marketplace directory.
+
+    Returns:
+        The 'name' field from marketplace.json.
+
+    Raises:
+        FileNotFoundError: If marketplace.json does not exist.
+        KeyError: If 'name' field is missing.
+        json.JSONDecodeError: If file is not valid JSON.
+    """
+    manifest_path = marketplace_path / ".claude-plugin" / "marketplace.json"
+    with manifest_path.open() as f:
+        data = json.load(f)
+    return data["name"]
+
+
+def discover_plugins(marketplace_path: pathlib.Path) -> list[tuple[str, pathlib.Path]]:
+    """Discover plugins within a marketplace directory.
+
+    Scans immediate subdirectories for .claude-plugin/plugin.json files.
+
+    Args:
+        marketplace_path: Path to the marketplace directory.
+
+    Returns:
+        List of (plugin_name, plugin_path) tuples for each discovered plugin.
+
+    Raises:
+        json.JSONDecodeError: If plugin.json exists but contains invalid JSON.
+        KeyError: If plugin.json exists but lacks the 'name' field.
+    """
+    plugins = []
+    for entry in sorted(marketplace_path.iterdir()):
+        if not entry.is_dir():
+            continue
+        plugin_json = entry / ".claude-plugin" / "plugin.json"
+        if not plugin_json.is_file():
+            continue
+        with plugin_json.open() as f:
+            data = json.load(f)
+        plugins.append((data["name"], entry))
+    return plugins
+
+
+def _get_timeout(env_var: str, default: int = 30) -> int:
+    """Read and validate a timeout from an environment variable.
+
+    Args:
+        env_var: Name of the environment variable.
+        default: Default timeout in seconds.
+
+    Returns:
+        Timeout value in seconds.
+
+    Raises:
+        SystemExit: If the value is not a valid positive integer.
+    """
+    timeout_str = os.environ.get(env_var, str(default))
+    try:
+        value = int(timeout_str)
+    except ValueError:
+        print(
+            f"Error: {env_var} must be a positive integer, got: {timeout_str}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    if value <= 0:
+        print(
+            f"Error: {env_var} must be a positive integer, got: {timeout_str}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return value
+
+
+def register_marketplace(claude_bin: str, marketplace_path: pathlib.Path) -> bool:
+    """Register a marketplace with Claude Code.
+
+    Runs: claude plugin marketplace add <absolute-path>
+
+    Args:
+        claude_bin: Path to claude binary.
+        marketplace_path: Absolute path to marketplace directory.
+
+    Returns:
+        True if registration succeeded, False otherwise.
+    """
+    timeout = _get_timeout("CLAUDE_REGISTER_TIMEOUT")
+    try:
+        result = subprocess.run(
+            [claude_bin, "plugin", "marketplace", "add", str(marketplace_path)],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(
+            f"Error: Timed out after {timeout} seconds registering marketplace {marketplace_path}",
+            file=sys.stderr,
+        )
+        return False
+
+    if result.returncode != 0:
+        print(
+            f"Error: Failed to register marketplace {marketplace_path}: {result.stderr}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def install_plugin(claude_bin: str, plugin_name: str, marketplace_name: str) -> bool:
+    """Install a plugin via Claude Code CLI.
+
+    Runs: claude plugin install <plugin_name>@<marketplace_name> --scope user
+
+    Args:
+        claude_bin: Path to claude binary.
+        plugin_name: Name of the plugin (from plugin.json).
+        marketplace_name: Name of the marketplace (from marketplace.json).
+
+    Returns:
+        True if install succeeded, False otherwise.
+    """
+    timeout = _get_timeout("CLAUDE_INSTALL_TIMEOUT")
+    plugin_ref = f"{plugin_name}@{marketplace_name}"
+    try:
+        result = subprocess.run(
+            [claude_bin, "plugin", "install", plugin_ref, "--scope", "user"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(
+            f"Error: Timed out after {timeout} seconds installing plugin {plugin_ref}",
+            file=sys.stderr,
+        )
+        return False
+
+    if result.returncode != 0:
+        print(
+            f"Error: Failed to install plugin {plugin_ref}: {result.stderr}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def uninstall_plugin(claude_bin: str, plugin_name: str, marketplace_name: str) -> bool:
+    """Uninstall a plugin via Claude Code CLI.
+
+    Runs: claude plugin uninstall <plugin_name>@<marketplace_name> --scope user
+
+    Args:
+        claude_bin: Path to claude binary.
+        plugin_name: Name of the plugin (from plugin.json).
+        marketplace_name: Name of the marketplace (from marketplace.json).
+
+    Returns:
+        True if uninstall succeeded, False otherwise.
+    """
+    timeout = _get_timeout("CLAUDE_UNINSTALL_TIMEOUT")
+    plugin_ref = f"{plugin_name}@{marketplace_name}"
+    try:
+        result = subprocess.run(
+            [claude_bin, "plugin", "uninstall", plugin_ref, "--scope", "user"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(
+            f"Error: Timed out after {timeout} seconds uninstalling plugin {plugin_ref}",
+            file=sys.stderr,
+        )
+        return False
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() if result.stderr else ""
+        if "not found" in stderr.lower() or "not installed" in stderr.lower():
+            print(f"Plugin already uninstalled (not found): {plugin_ref}")
+            return True
+        print(
+            f"Error: Failed to uninstall plugin {plugin_ref}: {stderr}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def remove_marketplace(claude_bin: str, marketplace_name: str) -> bool:
+    """Remove a marketplace registration from Claude Code.
+
+    Runs: claude plugin marketplace remove <marketplace_name>
+
+    Args:
+        claude_bin: Path to claude binary.
+        marketplace_name: Marketplace name (from marketplace.json).
+
+    Returns:
+        True if removal succeeded, False otherwise.
+    """
+    timeout = _get_timeout("CLAUDE_UNINSTALL_TIMEOUT")
+    try:
+        result = subprocess.run(
+            [claude_bin, "plugin", "marketplace", "remove", marketplace_name],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        print(
+            f"Error: Timed out after {timeout} seconds removing marketplace {marketplace_name}",
+            file=sys.stderr,
+        )
+        return False
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() if result.stderr else ""
+        if "not found" in stderr.lower():
+            print(f"Marketplace already removed (not found): {marketplace_name}")
+            return True
+        print(
+            f"Error: Failed to remove marketplace {marketplace_name}: {stderr}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def install_marketplace_plugins(marketplace_dir: pathlib.Path) -> None:
+    """Orchestrate marketplace plugin installation.
+
+    Locates claude binary, discovers marketplace entries, registers each
+    marketplace, discovers and installs plugins.
+
+    Args:
+        marketplace_dir: Path to CLAUDE_MARKETPLACES_DIR.
+
+    Raises:
+        SystemExit: If claude binary not found or any operation fails.
+    """
+    claude_bin = locate_claude_binary()
+
+    if not marketplace_dir.is_dir():
+        print(
+            f"Warning: Marketplace directory does not exist: {marketplace_dir}. No marketplaces to register.",
+            file=sys.stderr,
+        )
+        return
+
+    entries = discover_marketplace_entries(marketplace_dir)
+    if not entries:
+        print("Warning: No marketplace entries found. Nothing to do.", file=sys.stderr)
+        return
+
+    marketplaces_processed = 0
+    marketplaces_registered = 0
+    plugins_installed = 0
+    any_failures = False
+
+    for entry in entries:
+        marketplaces_processed += 1
+        marketplace_name = read_marketplace_name(entry)
+
+        reg_success = register_marketplace(claude_bin, entry)
+        if reg_success:
+            marketplaces_registered += 1
+        else:
+            any_failures = True
+
+        plugins = discover_plugins(entry)
+        for plugin_name, _plugin_path in plugins:
+            success = install_plugin(claude_bin, plugin_name, marketplace_name)
+            if success:
+                plugins_installed += 1
+            else:
+                any_failures = True
+
+    print(
+        f"Install summary: {marketplaces_processed} marketplaces processed, "
+        f"{marketplaces_registered} registered, {plugins_installed} plugins installed"
+    )
+
+    if any_failures:
+        print(
+            "Error: Some marketplace operations failed (see errors above).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def uninstall_marketplace_plugins(marketplace_dir: pathlib.Path) -> None:
+    """Orchestrate marketplace plugin uninstallation.
+
+    Locates claude binary, discovers marketplace entries, uninstalls each
+    plugin, then removes marketplace registrations.
+
+    Args:
+        marketplace_dir: Path to CLAUDE_MARKETPLACES_DIR.
+
+    Raises:
+        SystemExit: If claude binary not found or any operation fails.
+    """
+    claude_bin = locate_claude_binary()
+
+    if not marketplace_dir.is_dir():
+        print(
+            f"Warning: Marketplace directory does not exist: {marketplace_dir}. No marketplaces to uninstall.",
+            file=sys.stderr,
+        )
+        return
+
+    entries = discover_marketplace_entries(marketplace_dir)
+    if not entries:
+        print("Warning: No marketplace entries found. Nothing to uninstall.", file=sys.stderr)
+        return
+
+    marketplaces_processed = 0
+    plugins_uninstalled = 0
+    any_failures = False
+
+    for entry in entries:
+        marketplaces_processed += 1
+        marketplace_name = read_marketplace_name(entry)
+
+        plugins = discover_plugins(entry)
+        for plugin_name, _plugin_path in plugins:
+            success = uninstall_plugin(claude_bin, plugin_name, marketplace_name)
+            if success:
+                plugins_uninstalled += 1
+            else:
+                any_failures = True
+
+        remove_success = remove_marketplace(claude_bin, marketplace_name)
+        if not remove_success:
+            any_failures = True
+
+    print(
+        f"Uninstall summary: {marketplaces_processed} marketplace(s) processed, "
+        f"{plugins_uninstalled} plugin(s) uninstalled"
+    )
+
+    if any_failures:
+        print(
+            "Error: Some marketplace operations failed (see errors above).",
+            file=sys.stderr,
+        )
+        sys.exit(1)

kanon_cli/core/marketplace_validator.py

@@ -0,0 +1,237 @@
+"""Validate marketplace XML manifest files.
+
+Checks:
+  - All <linkfile dest> attributes use the ${CLAUDE_MARKETPLACES_DIR}
+    variable prefix, rejecting hard-coded or relative paths.
+  - All <include> chains are unbroken (every referenced file exists).
+  - All flattened project path names are unique across manifests.
+  - All <project revision> attributes follow valid formats.
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from kanon_cli.constants import (
+    ALLOWED_BRANCHES,
+    CONSTRAINT_RE,
+    MARKETPLACE_DIR_PREFIX,
+    MARKETPLACE_FILE_GLOB,
+    REFS_TAGS_RE,
+)
+
+
+def validate_linkfile_dest(xml_path: Path) -> list[str]:
+    """Validate all linkfile dest attributes in a manifest XML file.
+
+    Checks that every <linkfile> element's dest attribute starts with
+    ${CLAUDE_MARKETPLACES_DIR}/. Returns a list of error messages for
+    any violations found. An empty list means validation passed.
+
+    Args:
+        xml_path: Path to the XML manifest file to validate.
+
+    Returns:
+        List of error messages. Empty if all dest attributes are valid.
+        Each error identifies the file, project name, and invalid dest.
+    """
+    errors: list[str] = []
+    tree = ET.parse(xml_path)
+    root = tree.getroot()
+
+    for project in root.findall("project"):
+        project_name = project.get("name", "<unknown>")
+        for linkfile in project.findall("linkfile"):
+            dest = linkfile.get("dest", "")
+            if not dest.startswith(MARKETPLACE_DIR_PREFIX):
+                errors.append(
+                    f"{xml_path}: project '{project_name}' has "
+                    f"invalid linkfile dest='{dest}' — "
+                    f"must start with {MARKETPLACE_DIR_PREFIX}"
+                )
+
+    return errors
+
+
+def validate_include_chain(
+    xml_path: Path,
+    repo_root: Path,
+) -> list[str]:
+    """Validate that all includes in a manifest chain resolve to files.
+
+    Recursively follows <include> elements starting from xml_path,
+    checking that each referenced file exists. Returns errors for any
+    broken links in the chain.
+
+    Args:
+        xml_path: Path to the XML manifest file to validate.
+        repo_root: Repository root for resolving include paths.
+
+    Returns:
+        List of error messages. Empty if the entire chain is valid.
+        Each error identifies the source file and missing include.
+    """
+    errors: list[str] = []
+    visited: set[str] = set()
+
+    def _walk(current_path: Path) -> None:
+        resolved = str(current_path.resolve())
+        if resolved in visited:
+            return
+        visited.add(resolved)
+
+        try:
+            tree = ET.parse(current_path)
+        except ET.ParseError as exc:
+            errors.append(f"{current_path}: XML parse error: {exc}")
+            return
+        root = tree.getroot()
+
+        for include in root.findall("include"):
+            name = include.get("name")
+            if not name:
+                errors.append(f'{current_path}: <include> element missing required "name" attribute')
+                continue
+            include_path = repo_root / name
+            if not include_path.exists():
+                errors.append(f'{current_path}: <include name="{name}"> references non-existent file: {include_path}')
+            else:
+                _walk(include_path)
+
+    _walk(xml_path)
+    return errors
+
+
+def validate_name_uniqueness(xml_files: list[Path]) -> list[str]:
+    """Validate that all project path attributes are unique across manifests.
+
+    Parses each XML file, collects all <project path="..."> values, and
+    reports any duplicates along with the files containing them.
+
+    Args:
+        xml_files: List of paths to marketplace XML manifest files.
+
+    Returns:
+        List of error messages. Empty if all paths are unique.
+        Each error identifies the duplicate path and conflicting files.
+    """
+    errors: list[str] = []
+    path_to_files: dict[str, list[str]] = {}
+
+    for xml_file in xml_files:
+        tree = ET.parse(xml_file)
+        root = tree.getroot()
+        for project in root.findall("project"):
+            path_attr = project.get("path", "")
+            if path_attr:
+                if path_attr not in path_to_files:
+                    path_to_files[path_attr] = []
+                path_to_files[path_attr].append(str(xml_file))
+
+    for path_attr, files in path_to_files.items():
+        if len(files) > 1:
+            file_list = ", ".join(files)
+            errors.append(f"Duplicate project path '{path_attr}' found in: {file_list}")
+
+    return errors
+
+
+def _is_valid_revision(revision: str) -> bool:
+    """Check if a revision string is a valid format.
+
+    Valid formats:
+    - refs/tags/<path>/<semver> (e.g., refs/tags/example/proj/1.0.0)
+    - Single version constraints (~=1.2.0, >=1.0.0, <2.0.0)
+    - Compound version constraints (>=1.0.0,<2.0.0)
+    - Wildcard (*)
+    - Branch names (main)
+    """
+    if revision in ALLOWED_BRANCHES:
+        return True
+    if revision == "*":
+        return True
+    if REFS_TAGS_RE.match(revision):
+        return True
+    # Support compound constraints separated by commas (e.g., >=1.0.0,<2.0.0)
+    parts = revision.split(",")
+    if all(CONSTRAINT_RE.match(part) for part in parts):
+        return True
+    return False
+
+
+def validate_tag_format(xml_files: list[Path]) -> list[str]:
+    """Validate that all project revision attributes follow valid formats.
+
+    Checks that each <project> element's revision attribute is either a
+    refs/tags/<path>/<semver> tag, a version constraint, a wildcard, or
+    an allowed branch name. Returns errors for any invalid revisions.
+
+    Args:
+        xml_files: List of paths to marketplace XML manifest files.
+
+    Returns:
+        List of error messages. Empty if all revisions are valid.
+        Each error identifies the file, project name, and invalid revision.
+    """
+    errors: list[str] = []
+
+    for xml_file in xml_files:
+        tree = ET.parse(xml_file)
+        root = tree.getroot()
+        for project in root.findall("project"):
+            revision = project.get("revision", "")
+            if revision and not _is_valid_revision(revision):
+                project_name = project.get("name", "<unknown>")
+                errors.append(
+                    f"{xml_file}: project '{project_name}' has "
+                    f"invalid revision='{revision}' — must be "
+                    f"refs/tags/<path>/<semver>, a version constraint, "
+                    f"or an allowed branch"
+                )
+
+    return errors
+
+
+def validate_marketplace(repo_root: Path) -> int:
+    """Validate all marketplace XML files found under repo-specs/.
+
+    Scans for *-marketplace.xml files and validates each one
+    for linkfile dest attributes and include chain integrity.
+    Exits with non-zero code if any validation errors are found.
+
+    Args:
+        repo_root: Repository root directory.
+
+    Returns:
+        0 if all files pass validation, 1 otherwise.
+    """
+    marketplace_files = sorted(repo_root.joinpath("repo-specs").rglob(MARKETPLACE_FILE_GLOB))
+
+    if not marketplace_files:
+        print(
+            "Error: No *-marketplace.xml files found under repo-specs/",
+            file=sys.stderr,
+        )
+        return 1
+
+    all_errors: list[str] = []
+    for xml_file in marketplace_files:
+        rel_path = xml_file.relative_to(repo_root)
+        print(f"Validating {rel_path}...")
+        all_errors.extend(validate_linkfile_dest(xml_file))
+        all_errors.extend(validate_include_chain(xml_file, repo_root))
+
+    all_errors.extend(validate_name_uniqueness(marketplace_files))
+    all_errors.extend(validate_tag_format(marketplace_files))
+
+    if all_errors:
+        print(
+            f"\nFound {len(all_errors)} validation error(s):",
+            file=sys.stderr,
+        )
+        for error in all_errors:
+            print(f"  {error}", file=sys.stderr)
+        return 1
+
+    print(f"\nAll {len(marketplace_files)} marketplace files passed.")
+    return 0