kanon-cli 1.0.0__py3-none-any.whl

kanon_cli/commands/validate.py

@@ -0,0 +1,133 @@
+"""Validate subcommand with xml and marketplace sub-subcommands."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+from kanon_cli.core.marketplace_validator import validate_marketplace
+from kanon_cli.core.xml_validator import validate_xml
+
+
+def register(subparsers) -> None:
+    """Register the validate subcommand with xml and marketplace sub-subcommands.
+
+    Args:
+        subparsers: The subparsers object from the parent parser.
+    """
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate XML manifests",
+        description="Validate manifest XML files for well-formedness and correctness.",
+    )
+
+    validate_subs = validate_parser.add_subparsers(
+        dest="validate_command",
+        title="validation targets",
+        description="Available validation targets",
+    )
+
+    # xml sub-subcommand
+    xml_parser = validate_subs.add_parser(
+        "xml",
+        help="Validate manifest XML files (well-formedness, required attributes, include chains)",
+        description=(
+            "Validate all XML manifest files under repo-specs/.\n\n"
+            "Checks well-formedness, required attributes on <project> and <remote>\n"
+            "elements, and that <include> name attributes point to existing files."
+        ),
+        epilog="Example:\n  kanon validate xml\n  kanon validate xml --repo-root /path/to/repo",
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+    xml_parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=None,
+        help="Repository root directory (default: auto-detect via git rev-parse)",
+    )
+    xml_parser.set_defaults(func=_run_xml)
+
+    # marketplace sub-subcommand
+    mp_parser = validate_subs.add_parser(
+        "marketplace",
+        help="Validate marketplace XML manifests (linkfile dest, include chains, name uniqueness, tag format)",
+        description=(
+            "Validate all marketplace XML manifests under repo-specs/.\n\n"
+            "Checks linkfile dest attributes, include chain integrity,\n"
+            "project path uniqueness, and revision tag format."
+        ),
+        epilog="Example:\n  kanon validate marketplace\n  kanon validate marketplace --repo-root /path/to/repo",
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+    mp_parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=None,
+        help="Repository root directory (default: auto-detect via git rev-parse)",
+    )
+    mp_parser.set_defaults(func=_run_marketplace)
+
+    validate_parser.set_defaults(func=_run_validate_help)
+    validate_parser._validate_subs = validate_subs
+
+
+def _run_validate_help(args) -> None:
+    """Show help when no validate sub-subcommand is given."""
+    if args.validate_command is None:
+        print(
+            "Error: Must specify a validation target: xml or marketplace",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+
+def _resolve_repo_root(provided: Path | None) -> Path:
+    """Resolve repository root from argument or git.
+
+    Args:
+        provided: Explicitly provided repo root, or None for auto-detect.
+
+    Returns:
+        The resolved repository root path.
+
+    Raises:
+        SystemExit: If auto-detection fails.
+    """
+    if provided is not None:
+        return provided
+
+    result = subprocess.run(
+        ["git", "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            "Error: Could not auto-detect repo root. Run from within a git repository or use --repo-root.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return Path(result.stdout.strip())
+
+
+def _run_xml(args) -> None:
+    """Execute XML validation.
+
+    Args:
+        args: Parsed arguments with optional repo_root.
+    """
+    repo_root = _resolve_repo_root(args.repo_root)
+    exit_code = validate_xml(repo_root)
+    sys.exit(exit_code)
+
+
+def _run_marketplace(args) -> None:
+    """Execute marketplace validation.
+
+    Args:
+        args: Parsed arguments with optional repo_root.
+    """
+    repo_root = _resolve_repo_root(args.repo_root)
+    exit_code = validate_marketplace(repo_root)
+    sys.exit(exit_code)

kanon_cli/constants.py

@@ -0,0 +1,29 @@
+"""Centralized constants for the kanon-cli package.
+
+All module-level constants live here to avoid hard-coded values
+scattered across source files.
+"""
+
+import re
+
+# -- Package identity --
+PYPI_REPO_TOOL_PACKAGE = "rpm-git-repo"
+
+# -- Marketplace validation --
+MARKETPLACE_DIR_PREFIX = "${CLAUDE_MARKETPLACES_DIR}/"
+MARKETPLACE_FILE_GLOB = "*-marketplace.xml"
+ALLOWED_BRANCHES = frozenset({"main", "review/caylent-claude"})
+REFS_TAGS_RE = re.compile(r"^refs/tags/.+/\d+\.\d+\.\d+$")
+CONSTRAINT_RE = re.compile(r"^(~=|>=|<=|>|<)\d+\.\d+\.\d+$")
+
+# -- Version resolution --
+PEP440_OPERATORS = ("~=", ">=", "<=", "!=", "==", ">", "<")
+
+# -- kanonenv parsing --
+SOURCE_PREFIX = "KANON_SOURCE_"
+SOURCE_SUFFIXES = ("_URL", "_REVISION", "_PATH")
+SUFFIX_TO_KEY = {"_URL": "url", "_REVISION": "revision", "_PATH": "path"}
+SHELL_VAR_PATTERN = re.compile(r"\$\{([^}]+)\}")
+
+# -- Catalog --
+CATALOG_ENV_VAR = "KANON_CATALOG_SOURCE"

kanon_cli/core/bootstrap.py

@@ -0,0 +1,107 @@
+"""Bootstrap business logic for scaffolding new Kanon projects.
+
+Provides functions to list available catalog entry packages and copy
+them into a target directory with a pre-configured ``.kanon``
+configuration file from the catalog.
+"""
+
+import pathlib
+import shutil
+import sys
+
+
+def list_packages(catalog_dir: pathlib.Path) -> list[str]:
+    """List available catalog entry packages from the catalog.
+
+    Args:
+        catalog_dir: Path to the catalog directory.
+
+    Returns:
+        Sorted list of package names (catalog subdirectory names).
+    """
+    return sorted(d.name for d in catalog_dir.iterdir() if d.is_dir())
+
+
+def bootstrap_package(package: str, output_dir: pathlib.Path, catalog_dir: pathlib.Path) -> None:
+    """Copy catalog entry package files into the output directory.
+
+    Copies all files from the catalog package directory (including a
+    pre-configured ``.kanon``) into the output directory. Refuses to
+    overwrite existing files.
+
+    Args:
+        package: Name of the catalog entry package (e.g. ``make``, ``gradle``, ``kanon``).
+        output_dir: Target directory for the bootstrapped files.
+        catalog_dir: Path to the catalog directory.
+
+    Raises:
+        SystemExit: If the package is unknown, files already exist, or
+            the output directory cannot be created.
+    """
+    package_dir = catalog_dir / package
+
+    if not package_dir.is_dir():
+        available = list_packages(catalog_dir)
+        print(
+            f"Error: Unknown package '{package}'. Available packages: {', '.join(available)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    all_files = [f.name for f in package_dir.iterdir() if f.is_file() and f.name != ".gitkeep"]
+
+    _check_no_conflicts(all_files, output_dir)
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    for src_file in package_dir.iterdir():
+        if src_file.is_file() and src_file.name != ".gitkeep":
+            shutil.copy2(src_file, output_dir / src_file.name)
+
+    _print_next_steps(package, output_dir, all_files)
+
+
+def _check_no_conflicts(files: list[str], output_dir: pathlib.Path) -> None:
+    """Verify no target files already exist in the output directory.
+
+    Args:
+        files: List of filenames to check.
+        output_dir: Target directory.
+
+    Raises:
+        SystemExit: If any file already exists, listing all conflicts.
+    """
+    conflicts = [f for f in files if (output_dir / f).exists()]
+    if conflicts:
+        print("Error: The following files already exist:", file=sys.stderr)
+        for f in conflicts:
+            print(f"  {output_dir / f}", file=sys.stderr)
+        print(
+            "\nRemove them first or use a different --output-dir.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _print_next_steps(
+    package: str,
+    output_dir: pathlib.Path,
+    files: list[str],
+) -> None:
+    """Print post-bootstrap instructions.
+
+    Args:
+        package: Catalog entry package name.
+        output_dir: Directory where files were created.
+        files: List of created filenames.
+    """
+    print(f"kanon bootstrap: created {package} project in {output_dir}/")
+    print("\nFiles created:")
+    for f in sorted(files):
+        print(f"  {output_dir / f}")
+
+    print("\nNext steps:")
+
+    print("  1. Edit .kanon — set GITBASE, KANON_MARKETPLACE_INSTALL, and source variables")
+    print("  2. Run: kanon install .kanon")
+    print("  3. Commit .kanon to your repository")

kanon_cli/core/catalog.py

@@ -0,0 +1,133 @@
+"""Catalog directory resolution for Kanon bootstrap.
+
+Resolves the catalog directory from multiple sources in priority order:
+  1. ``--catalog-source`` CLI flag
+  2. ``KANON_CATALOG_SOURCE`` environment variable
+  3. Bundled catalog shipped with the ``kanon_cli`` package
+
+Remote catalog sources use the format ``<git_url>@<ref>`` where ref
+can be a branch name, tag, or ``latest`` (resolves to highest semver tag).
+"""
+
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+
+from kanon_cli.constants import CATALOG_ENV_VAR
+from kanon_cli.version import resolve_version
+
+
+def resolve_catalog_dir(catalog_source: str | None = None) -> pathlib.Path:
+    """Resolve the catalog directory from flag, env var, or bundled fallback.
+
+    Args:
+        catalog_source: Remote catalog source from CLI flag (``<git_url>@<ref>``).
+
+    Returns:
+        Path to the resolved catalog directory.
+
+    Raises:
+        SystemExit: If the remote catalog cannot be cloned or has no ``catalog/`` dir.
+        ValueError: If the catalog source format is invalid.
+    """
+    source = catalog_source or os.environ.get(CATALOG_ENV_VAR)
+
+    if source:
+        return _clone_remote_catalog(source)
+
+    return _get_bundled_catalog_dir()
+
+
+def _get_bundled_catalog_dir() -> pathlib.Path:
+    """Return the path to the bundled catalog shipped with the package.
+
+    Returns:
+        Absolute path to the bundled catalog directory.
+    """
+    return pathlib.Path(__file__).parent.parent / "catalog"
+
+
+def _parse_catalog_source(source: str) -> tuple[str, str]:
+    """Parse a catalog source string into URL and ref.
+
+    The format is ``<git_url>@<ref>`` where the last ``@`` is the delimiter.
+    This handles SSH URLs like ``git@github.com:org/repo.git@main``.
+
+    Args:
+        source: Catalog source string.
+
+    Returns:
+        Tuple of (url, ref).
+
+    Raises:
+        ValueError: If the format is invalid (no ``@`` or empty ref).
+    """
+    idx = source.rfind("@")
+    if idx == -1:
+        msg = (
+            f"Invalid catalog source format: '{source}'. "
+            "Expected '<git_url>@<ref>' (e.g. 'https://github.com/org/repo.git@main')"
+        )
+        raise ValueError(msg)
+
+    url = source[:idx]
+    ref = source[idx + 1 :]
+
+    if not ref:
+        msg = (
+            f"Empty ref in catalog source: '{source}'. "
+            "Expected '<git_url>@<ref>' (e.g. 'https://github.com/org/repo.git@v1.0.0')"
+        )
+        raise ValueError(msg)
+
+    if not url:
+        msg = f"Empty URL in catalog source: '{source}'"
+        raise ValueError(msg)
+
+    return url, ref
+
+
+def _clone_remote_catalog(source: str) -> pathlib.Path:
+    """Clone a remote catalog repo and return the catalog directory path.
+
+    Args:
+        source: Catalog source string (``<git_url>@<ref>``).
+
+    Returns:
+        Path to the ``catalog/`` directory inside the cloned repo.
+
+    Raises:
+        SystemExit: If git clone fails or the repo has no ``catalog/`` directory.
+        ValueError: If the source format is invalid.
+    """
+    url, ref = _parse_catalog_source(source)
+
+    if ref == "latest":
+        ref = resolve_version(url, "*")
+
+    clone_dir = pathlib.Path(tempfile.mkdtemp(prefix="kanon-catalog-"))
+
+    result = subprocess.run(
+        ["git", "clone", "--depth", "1", "--branch", ref, url, str(clone_dir / "repo")],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: Failed to clone catalog from {url}@{ref}: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    catalog_path = clone_dir / "repo" / "catalog"
+    if not catalog_path.is_dir():
+        print(
+            f"Error: Remote repo {url}@{ref} does not contain a 'catalog/' directory",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return catalog_path

kanon_cli/core/clean.py

@@ -0,0 +1,111 @@
+"""Kanon clean business logic for full teardown.
+
+Performs full Kanon teardown in the following order:
+  1. If KANON_MARKETPLACE_INSTALL=true:
+     uninstall marketplace plugins via claude CLI
+  2. If KANON_MARKETPLACE_INSTALL=true:
+     remove CLAUDE_MARKETPLACES_DIR
+  3. Remove .packages/ directory (ignore_errors=True)
+  4. Remove .kanon-data/ directory (ignore_errors=True)
+"""
+
+import pathlib
+import shutil
+import sys
+
+from kanon_cli.core.marketplace import uninstall_marketplace_plugins
+from kanon_cli.core.kanonenv import parse_kanonenv
+
+
+def remove_marketplace_dir(marketplace_dir: pathlib.Path) -> None:
+    """Remove the marketplace directory if it exists.
+
+    Args:
+        marketplace_dir: Path to CLAUDE_MARKETPLACES_DIR.
+    """
+    if marketplace_dir.exists():
+        shutil.rmtree(marketplace_dir)
+
+
+def remove_packages_dir(base_dir: pathlib.Path) -> None:
+    """Remove .packages/ directory with ignore_errors.
+
+    Args:
+        base_dir: Project root directory.
+    """
+    shutil.rmtree(base_dir / ".packages", ignore_errors=True)
+
+
+def remove_kanon_dir(base_dir: pathlib.Path) -> None:
+    """Remove .kanon-data/ directory with ignore_errors.
+
+    Args:
+        base_dir: Project root directory.
+    """
+    shutil.rmtree(base_dir / ".kanon-data", ignore_errors=True)
+
+
+def _print_remove_summary(packages_dir: pathlib.Path) -> None:
+    """Print a summary of packages that will be removed.
+
+    Args:
+        packages_dir: Path to ``.packages/`` directory.
+    """
+    if not packages_dir.exists():
+        print("kanon clean: no packages to remove.")
+        return
+
+    pkgs = sorted(p.name for p in packages_dir.iterdir() if not p.name.startswith("."))
+    if not pkgs:
+        print("kanon clean: no packages to remove.")
+        return
+
+    print(f"kanon clean: removing {len(pkgs)} packages...")
+    for pkg in pkgs:
+        print(f"  - {pkg}")
+
+
+def clean(kanonenv_path: pathlib.Path) -> None:
+    """Execute the full Kanon clean lifecycle.
+
+    Steps:
+      1. Parse .kanon
+      2. If KANON_MARKETPLACE_INSTALL=true: run uninstall, remove marketplace dir
+      3. Remove .packages/ and .kanon-data/
+
+    Args:
+        kanonenv_path: Path to the .kanon configuration file.
+
+    Raises:
+        SystemExit: On any failure during the clean process.
+    """
+    print(f"kanon clean: parsing {kanonenv_path}...")
+    config = parse_kanonenv(kanonenv_path)
+    base_dir = kanonenv_path.parent
+    marketplace_install = config["KANON_MARKETPLACE_INSTALL"]
+    globals_dict = config["globals"]
+
+    marketplace_dir_str = globals_dict.get("CLAUDE_MARKETPLACES_DIR", "")
+
+    if marketplace_install and not marketplace_dir_str:
+        print(
+            "Error: KANON_MARKETPLACE_INSTALL=true but CLAUDE_MARKETPLACES_DIR is not defined in .kanon",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    packages_dir = base_dir / ".packages"
+    _print_remove_summary(packages_dir)
+
+    if marketplace_install:
+        print("kanon clean: running marketplace uninstall...")
+        marketplace_dir = pathlib.Path(marketplace_dir_str)
+        uninstall_marketplace_plugins(marketplace_dir)
+        print("kanon clean: removing marketplace directory...")
+        remove_marketplace_dir(marketplace_dir)
+
+    print("kanon clean: removing .packages/...")
+    remove_packages_dir(base_dir)
+    print("kanon clean: removing .kanon-data/...")
+    remove_kanon_dir(base_dir)
+    print("kanon clean: done.")