kanon-cli 1.0.0__py3-none-any.whl

kanon_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Kanon CLI -- Kanon Package Manager."""
+
+__version__ = "1.0.0"

kanon_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m kanon_cli``."""
+
+from kanon_cli.cli import main
+
+main()

kanon_cli/catalog/kanon/.kanon

@@ -0,0 +1,35 @@
+# Kanon Configuration
+# Environment variables override these values (for pipeline integration)
+
+# Repo Tool
+# By default, kanon installs the latest rpm-git-repo from PyPI.
+# To override (e.g., test an unreleased version), uncomment both lines:
+# REPO_URL=https://github.com/caylent-solutions/rpm-git-repo.git
+# REPO_REV=main
+
+# Shared env vars for envsubst (resolved by 'repo envsubst' in remote.xml)
+GITBASE=<YOUR_GIT_ORG_BASE_URL>
+CLAUDE_MARKETPLACES_DIR=${HOME}/.claude-marketplaces
+
+# Marketplace install toggle (set to true to enable Claude Code plugin lifecycle)
+KANON_MARKETPLACE_INSTALL=<true|false>
+
+# --- Sources ---
+# Define one or more sources. Each source needs three variables:
+#   KANON_SOURCE_<name>_URL      — Git URL of the manifest repository
+#   KANON_SOURCE_<name>_REVISION — Branch, tag, or PEP 440 constraint
+#   KANON_SOURCE_<name>_PATH     — Path to the entry-point manifest XML
+#
+# Example: single source (marketplace plugins only)
+# KANON_SOURCE_plugins_URL=https://github.com/your-org/your-manifest-repo.git
+# KANON_SOURCE_plugins_REVISION=main
+# KANON_SOURCE_plugins_PATH=repo-specs/marketplace-manifest.xml
+#
+# Example: two sources (build packages + marketplace plugins)
+# KANON_SOURCE_packages_URL=https://github.com/your-org/your-packages-repo.git
+# KANON_SOURCE_packages_REVISION=refs/tags/>=1.0.0,<2.0.0
+# KANON_SOURCE_packages_PATH=repo-specs/build/packages.xml
+#
+# KANON_SOURCE_plugins_URL=https://github.com/your-org/your-marketplace-repo.git
+# KANON_SOURCE_plugins_REVISION=main
+# KANON_SOURCE_plugins_PATH=repo-specs/marketplace-manifest.xml

kanon_cli/catalog/kanon/kanon-readme.md

@@ -0,0 +1,155 @@
+# Kanon -- Standalone Catalog Entry Package
+
+Getting started with Kanon using the CLI directly. This is the simplest setup -- you get a `.kanon` configuration file and invoke `kanon install` and `kanon clean` directly.
+
+---
+
+## Prerequisites
+
+- Python 3.11+
+- [pipx](https://pipx.pypa.io/) on PATH
+- [uv](https://docs.astral.sh/uv/) -- Python package installer
+- Git
+
+The Kanon CLI is already installed (it just ran `kanon bootstrap` to create this file).
+
+> **SSH Users:** Kanon uses HTTPS Git URLs internally. If you authenticate with GitHub via SSH, configure Git to rewrite HTTPS URLs to SSH globally:
+>
+> ```bash
+> git config --global url."git@github.com:".insteadOf "https://github.com/"
+> ```
+>
+> The `--global` flag is required -- `--local` will not work because Kanon uses the `repo` tool under the hood, which operates in its own working directories with their own local Git configuration. For other Git hosts, adjust the URL accordingly (e.g., `git@gitlab.com:` for GitLab).
+
+---
+
+## Setup
+
+### 1. Install (sync all packages)
+
+Edit `.kanon` to set `GITBASE`, `KANON_MARKETPLACE_INSTALL`, and your source variables, then run install:
+
+```bash
+kanon install .kanon
+```
+
+This syncs all packages to `.packages/`, creates source workspaces in `.kanon-data/sources/`, and updates `.gitignore`.
+
+### 2. Verify
+
+```bash
+ls .packages/
+```
+
+After install, `.packages/` contains symlinks to all synced packages.
+
+---
+
+## Usage
+
+**Install (sync packages):**
+
+```bash
+kanon install .kanon
+```
+
+**Clean (full teardown):**
+
+```bash
+kanon clean .kanon
+```
+
+**Validate manifests:**
+
+```bash
+kanon validate xml
+kanon validate marketplace
+```
+
+---
+
+## `.kanon` Variable Reference
+
+### Core Variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `REPO_URL` | No | Git URL of the [rpm-git-repo](https://github.com/caylent-solutions/rpm-git-repo) tool. Optional — omit to install from PyPI (default). Set both `REPO_URL` and `REPO_REV` to override with a git source (e.g., to test an unreleased version). |
+| `REPO_REV` | No | rpm-git-repo version (branch or tag) for git override. Only used when `REPO_URL` is also set. Supports PEP 440 specifiers (e.g., `~=2.0.0`, `>=2.0.0,<3.0.0`, `*`). |
+| `GITBASE` | Yes | Base Git URL for your organization (e.g., `https://github.com/your-org/`). Used by `repo envsubst` to resolve `${GITBASE}` placeholders in manifest XML files. |
+| `CLAUDE_MARKETPLACES_DIR` | Conditional | Directory for marketplace plugin symlinks. Required when `KANON_MARKETPLACE_INSTALL=true`. Typically `${HOME}/.claude-marketplaces`. |
+| `KANON_MARKETPLACE_INSTALL` | No | Set to `true` to enable the marketplace plugin install/uninstall lifecycle during install and clean. Default: `false`. When `false`, marketplace-related operations are skipped entirely. |
+
+### Source Variables
+
+Sources are auto-discovered from `KANON_SOURCE_<name>_URL` patterns and processed in alphabetical order by name. Each source requires three variables:
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `KANON_SOURCE_<name>_URL` | Yes | Git URL of the manifest repository for this source. |
+| `KANON_SOURCE_<name>_REVISION` | Yes | Branch, tag, or PEP 440 constraint to track for this source's manifest repository. |
+| `KANON_SOURCE_<name>_PATH` | Yes | Path to the entry-point manifest XML file within the manifest repository (e.g., `repo-specs/build/meta.xml`). |
+
+You can define multiple sources. Add new source blocks in `.kanon` as needed.
+
+---
+
+## How It Works
+
+The Kanon CLI reads `.kanon` and for each source:
+
+1. `repo init` -- Clones the manifest repository
+2. `repo envsubst` -- Resolves `${VARIABLE}` placeholders in manifest XML
+3. `repo sync` -- Syncs packages into `.kanon-data/sources/<name>/.packages/`
+
+After all sources are synced, Kanon aggregates their packages into `.packages/` using symlinks, giving a unified view regardless of which source provided each package.
+
+**Committed files:** `.kanon`, `kanon-readme.md`
+
+**Ephemeral files (gitignored):** `.packages/`, `.kanon-data/`
+
+---
+
+## When to Use This Package
+
+Use the `kanon` catalog entry package when:
+
+- Your project uses a build tool not directly supported by Kanon's catalog (npm, Maven, Bazel, etc.)
+- You prefer to invoke the Kanon CLI directly from scripts or CI/CD pipelines
+- You want the simplest possible setup with no wrapper files
+
+You can integrate Kanon with any build tool by wrapping `kanon install .kanon` and `kanon clean .kanon` in your task runner of choice.
+
+---
+
+## Adding Sources
+
+Add source blocks in `.kanon`:
+
+```properties
+KANON_SOURCE_tools_URL=https://github.com/your-org/tools-manifests.git
+KANON_SOURCE_tools_REVISION=main
+KANON_SOURCE_tools_PATH=repo-specs/tools/meta.xml
+```
+
+---
+
+## Marketplace Plugins (Optional)
+
+To enable Claude Code marketplace plugins, set in `.kanon`:
+
+```properties
+KANON_MARKETPLACE_INSTALL=true
+CLAUDE_MARKETPLACES_DIR=${HOME}/.claude-marketplaces
+```
+
+Then add a marketplace source and re-run `kanon install .kanon`. When `KANON_MARKETPLACE_INSTALL` is `false` (the default), the marketplace lifecycle is skipped entirely -- no plugins are installed or uninstalled.
+
+---
+
+## Troubleshooting
+
+- **`kanon: command not found`** -- Reinstall the Kanon CLI: `pipx install kanon-cli`
+- **`kanon install` fails with ".kanon not found"** -- Pass the path: `kanon install .kanon`
+- **`repo envsubst` fails** -- Ensure `GITBASE` is set in `.kanon` and is a valid URL ending with `/`
+- **Authentication errors during sync** -- If you use SSH for Git auth, ensure the HTTPS-to-SSH rewrite is configured globally: `git config --global url."git@github.com:".insteadOf "https://github.com/"`. If you use HTTPS, ensure your credential helper is configured.

kanon_cli/cli.py

@@ -0,0 +1,67 @@
+"""Kanon CLI entry point with argparse subcommands.
+
+Provides the top-level ``kanon`` command with subcommands:
+  - ``kanon install <kanonenv-path>`` -- Full lifecycle: prereqs + repo install + multi-source sync
+  - ``kanon clean <kanonenv-path>`` -- Full teardown: uninstall, remove dirs
+  - ``kanon validate xml [--repo-root PATH]`` -- Validate manifest XML files
+  - ``kanon validate marketplace [--repo-root PATH]`` -- Validate marketplace XML manifests
+  - ``kanon bootstrap <package>`` -- Scaffold a new Kanon project from a catalog entry package
+  - ``kanon bootstrap list`` -- List available catalog entry packages
+"""
+
+import argparse
+import sys
+
+from kanon_cli import __version__
+from kanon_cli.commands.bootstrap import register as register_bootstrap
+from kanon_cli.commands.clean import register as register_clean
+from kanon_cli.commands.install import register as register_install
+from kanon_cli.commands.validate import register as register_validate
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser with subcommands.
+
+    Returns:
+        The configured ArgumentParser.
+    """
+    parser = argparse.ArgumentParser(
+        prog="kanon",
+        description="Kanon (Kanon Package Manager) CLI tool. Manages the full Kanon lifecycle: install, clean, and validate.",
+        epilog="Examples:\n  kanon install .kanon\n  kanon clean .kanon\n  kanon validate xml\n  kanon validate marketplace --repo-root /path/to/repo",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="subcommands",
+        description="Available subcommands",
+    )
+
+    register_bootstrap(subparsers)
+    register_install(subparsers)
+    register_clean(subparsers)
+    register_validate(subparsers)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse arguments and dispatch to the appropriate subcommand.
+
+    Args:
+        argv: Command-line arguments. Defaults to sys.argv[1:].
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(2)
+
+    args.func(args)

kanon_cli/commands/bootstrap.py

@@ -0,0 +1,70 @@
+"""Bootstrap subcommand: scaffold a new Kanon project.
+
+Copies catalog entry package files from the catalog and provides
+a pre-configured ``.kanon`` configuration file. Supports remote
+catalog sources via ``--catalog-source`` flag or
+``KANON_CATALOG_SOURCE`` environment variable.
+"""
+
+import argparse
+import pathlib
+
+from kanon_cli.core.bootstrap import bootstrap_package, list_packages
+from kanon_cli.core.catalog import resolve_catalog_dir
+
+
+def register(subparsers) -> None:
+    """Register the bootstrap subcommand.
+
+    Args:
+        subparsers: The subparsers object from the parent parser.
+    """
+    parser = subparsers.add_parser(
+        "bootstrap",
+        help="Scaffold a new Kanon project with catalog entry package files",
+        description=(
+            "Copy catalog entry package files (including a pre-configured\n"
+            ".kanon) into the target directory.\n\n"
+            "Use 'kanon bootstrap list' to see available packages."
+        ),
+        epilog="Examples:\n  kanon bootstrap list\n  kanon bootstrap kanon\n  kanon bootstrap kanon --output-dir my-project",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "package",
+        help="Catalog entry package name (e.g. kanon) or 'list' to show available packages",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=pathlib.Path,
+        default=pathlib.Path("."),
+        help="Target directory for bootstrapped files (default: current directory)",
+    )
+    parser.add_argument(
+        "--catalog-source",
+        default=None,
+        help=(
+            "Remote catalog source as '<git_url>@<ref>' where ref is a branch, "
+            "tag, or 'latest'. Overrides KANON_CATALOG_SOURCE env var. "
+            "Default: bundled catalog."
+        ),
+    )
+    parser.set_defaults(func=_run)
+
+
+def _run(args) -> None:
+    """Execute the bootstrap command.
+
+    Args:
+        args: Parsed arguments with package, output_dir, and catalog_source.
+    """
+    catalog_dir = resolve_catalog_dir(args.catalog_source)
+
+    if args.package == "list":
+        packages = list_packages(catalog_dir)
+        print("Available packages:")
+        for pkg in packages:
+            print(f"  {pkg}")
+        return
+
+    bootstrap_package(args.package, args.output_dir, catalog_dir)

kanon_cli/commands/clean.py

@@ -0,0 +1,40 @@
+"""Clean subcommand handler."""
+
+import pathlib
+
+from kanon_cli.core.clean import clean
+
+
+def register(subparsers) -> None:
+    """Register the clean subcommand.
+
+    Args:
+        subparsers: The subparsers object from the parent parser.
+    """
+    parser = subparsers.add_parser(
+        "clean",
+        help="Full teardown: uninstall, remove dirs",
+        description=(
+            "Execute the full Kanon clean lifecycle.\n\n"
+            "If KANON_MARKETPLACE_INSTALL=true, runs the uninstall script\n"
+            "and removes the marketplace directory. Then removes .packages/\n"
+            "and .kanon-data/ directories."
+        ),
+        epilog="Example:\n  kanon clean .kanon",
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "kanonenv_path",
+        type=pathlib.Path,
+        help="Path to the .kanon configuration file",
+    )
+    parser.set_defaults(func=_run)
+
+
+def _run(args) -> None:
+    """Execute the clean command.
+
+    Args:
+        args: Parsed arguments with kanonenv_path.
+    """
+    clean(args.kanonenv_path)

kanon_cli/commands/install.py

@@ -0,0 +1,186 @@
+"""Install subcommand: prereqs + repo install + lifecycle.
+
+Checks that pipx is available, ensures the repo tool is installed
+(from PyPI by default, or from a git URL when REPO_URL and REPO_REV
+are set), then delegates to the core install logic.
+"""
+
+import json
+import pathlib
+import shutil
+import subprocess
+import sys
+
+from kanon_cli.constants import PYPI_REPO_TOOL_PACKAGE
+from kanon_cli.core.install import install
+from kanon_cli.version import resolve_version
+
+
+def register(subparsers) -> None:
+    """Register the install subcommand.
+
+    Args:
+        subparsers: The subparsers object from the parent parser.
+    """
+    parser = subparsers.add_parser(
+        "install",
+        help="Full lifecycle: check prereqs, install repo, multi-source sync",
+        description=(
+            "Execute the full Kanon install lifecycle.\n\n"
+            "Checks prerequisites (pipx on PATH), installs the repo tool,\n"
+            "then runs repo init/envsubst/sync for each source defined in\n"
+            "the .kanon file. Aggregates packages into .packages/ via symlinks."
+        ),
+        epilog="Example:\n  kanon install .kanon",
+        formatter_class=__import__("argparse").RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "kanonenv_path",
+        type=pathlib.Path,
+        help="Path to the .kanon configuration file",
+    )
+    parser.set_defaults(func=_run)
+
+
+def _run(args) -> None:
+    """Execute the install command.
+
+    Args:
+        args: Parsed arguments with kanonenv_path.
+    """
+    print("kanon install: checking prerequisites...")
+    _check_pipx()
+
+    from kanon_cli.core.kanonenv import parse_kanonenv
+
+    config = parse_kanonenv(args.kanonenv_path)
+    globals_dict = config["globals"]
+
+    repo_url = globals_dict.get("REPO_URL", "")
+    repo_rev = globals_dict.get("REPO_REV", "")
+
+    if repo_url and repo_rev:
+        resolved_rev = resolve_version(repo_url, repo_rev)
+        print(f"kanon install: installing repo tool from git ({resolved_rev})...")
+        _install_repo_tool_from_git(repo_url, resolved_rev)
+    elif repo_url or repo_rev:
+        print(
+            "Error: REPO_URL and REPO_REV must both be set or both be omitted.\n"
+            "Set both for git override, or omit both to install from PyPI.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    else:
+        _ensure_repo_tool_from_pypi()
+
+    install(args.kanonenv_path)
+
+
+def _check_pipx() -> None:
+    """Verify that pipx is available on PATH.
+
+    Raises:
+        SystemExit: If pipx is not found.
+    """
+    if shutil.which("pipx") is None:
+        print(
+            "Error: pipx is not installed or not on PATH.\n\n"
+            "Install pipx before running kanon install.\n"
+            "  - pip: python3 -m pip install --user pipx\n"
+            "  - apt: sudo apt install pipx\n"
+            "  - brew: brew install pipx\n"
+            "After installing: pipx ensurepath",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _is_repo_tool_installed() -> bool:
+    """Check if rpm-git-repo is installed via pipx.
+
+    Returns:
+        True if the package is found in pipx list output.
+
+    Raises:
+        SystemExit: If pipx list fails or returns unparseable output.
+    """
+    result = subprocess.run(
+        ["pipx", "list", "--json"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: pipx list --json failed: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    try:
+        data = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        print(
+            f"Error: pipx list --json returned invalid JSON: {exc}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if "venvs" not in data:
+        print(
+            "Error: pipx list --json output missing 'venvs' key.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return PYPI_REPO_TOOL_PACKAGE in data["venvs"]
+
+
+def _ensure_repo_tool_from_pypi() -> None:
+    """Install rpm-git-repo from PyPI if not already installed.
+
+    Raises:
+        SystemExit: If pipx install fails.
+    """
+    if _is_repo_tool_installed():
+        print("kanon install: repo tool already installed, skipping.")
+        return
+
+    print(f"kanon install: installing repo tool from PyPI ({PYPI_REPO_TOOL_PACKAGE})...")
+    result = subprocess.run(
+        ["pipx", "install", PYPI_REPO_TOOL_PACKAGE],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: Failed to install {PYPI_REPO_TOOL_PACKAGE} via pipx: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _install_repo_tool_from_git(repo_url: str, repo_rev: str) -> None:
+    """Install the repo tool from a git URL via pipx (override mode).
+
+    Args:
+        repo_url: Git URL of the repo tool.
+        repo_rev: Resolved version/branch/tag to install.
+
+    Raises:
+        SystemExit: If pipx install fails.
+    """
+    install_spec = f"git+{repo_url}@{repo_rev}"
+    result = subprocess.run(
+        ["pipx", "install", "--force", install_spec],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: Failed to install repo tool via pipx: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)