kanon-cli 1.0.0__py3-none-any.whl

kanon_cli/core/install.py

@@ -0,0 +1,349 @@
+"""Multi-source Kanon install business logic.
+
+Parses .kanon, validates sources, creates isolated source workspaces
+under ``.kanon-data/sources/<name>/``, runs ``repo init``/``envsubst``/``sync``
+per source, aggregates symlinks into ``.packages/``, detects collisions,
+updates ``.gitignore``, and optionally installs marketplace plugins.
+"""
+
+import os
+import pathlib
+import shutil
+import subprocess
+import sys
+
+from kanon_cli.core.marketplace import install_marketplace_plugins
+from kanon_cli.core.kanonenv import parse_kanonenv
+from kanon_cli.version import resolve_version
+
+
+def create_source_dirs(
+    source_names: list[str],
+    base_dir: pathlib.Path,
+) -> dict[str, pathlib.Path]:
+    """Create .kanon-data/sources/<name>/ directories for each source.
+
+    Args:
+        source_names: Ordered list of source names (auto-discovered, alphabetical).
+        base_dir: Project root directory.
+
+    Returns:
+        Dict mapping source name to its directory path.
+    """
+    result: dict[str, pathlib.Path] = {}
+    for name in source_names:
+        source_dir = base_dir / ".kanon-data" / "sources" / name
+        source_dir.mkdir(parents=True, exist_ok=True)
+        result[name] = source_dir
+    return result
+
+
+def run_repo_init(
+    source_dir: pathlib.Path,
+    url: str,
+    revision: str,
+    manifest_path: str,
+    repo_rev: str = "",
+) -> None:
+    """Run ``repo init -u <URL> -b <REVISION> -m <PATH>`` in source directory.
+
+    Args:
+        source_dir: Path to ``.kanon-data/sources/<name>/``.
+        url: Repository URL for repo init.
+        revision: Branch/tag/revision for repo init.
+        manifest_path: Manifest file path for repo init.
+        repo_rev: Repo tool version tag for ``--repo-rev``.
+
+    Raises:
+        SystemExit: If repo init exits non-zero.
+    """
+    cmd = [
+        "repo",
+        "--color=never",
+        "init",
+        "--no-repo-verify",
+        "-u",
+        url,
+        "-b",
+        revision,
+        "-m",
+        manifest_path,
+    ]
+    if repo_rev:
+        cmd.extend(["--repo-rev", repo_rev])
+    result = subprocess.run(
+        cmd,
+        cwd=source_dir,
+        capture_output=True,
+        text=True,
+        check=False,
+        input="n\n",
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: repo init failed in {source_dir}: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def run_repo_envsubst(
+    source_dir: pathlib.Path,
+    env_vars: dict[str, str],
+) -> None:
+    """Run ``repo envsubst`` in source directory with exported env vars.
+
+    Args:
+        source_dir: Path to ``.kanon-data/sources/<name>/``.
+        env_vars: Environment variables to export (GITBASE, CLAUDE_MARKETPLACES_DIR).
+
+    Raises:
+        SystemExit: If repo envsubst exits non-zero.
+    """
+    run_env = {**os.environ, **env_vars}
+    result = subprocess.run(
+        ["repo", "envsubst"],
+        cwd=source_dir,
+        env=run_env,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: repo envsubst failed in {source_dir}: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def run_repo_sync(source_dir: pathlib.Path) -> None:
+    """Run ``repo sync`` in source directory.
+
+    Args:
+        source_dir: Path to ``.kanon-data/sources/<name>/``.
+
+    Raises:
+        SystemExit: If repo sync exits non-zero.
+    """
+    result = subprocess.run(
+        ["repo", "sync"],
+        cwd=source_dir,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        print(
+            f"Error: repo sync failed in {source_dir}: {result.stderr}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def aggregate_symlinks(
+    source_names: list[str],
+    base_dir: pathlib.Path,
+) -> dict[str, str]:
+    """Aggregate packages from all sources into ``.packages/``.
+
+    For each ``.kanon-data/sources/<name>/.packages/*``, creates a symlink in
+    the top-level ``.packages/`` directory. Detects collisions when two
+    sources produce the same package name.
+
+    Args:
+        source_names: Ordered list of source names.
+        base_dir: Project root directory.
+
+    Returns:
+        Dict mapping package name to source name.
+
+    Raises:
+        SystemExit: If two sources produce the same package name.
+    """
+    packages_dir = base_dir / ".packages"
+    packages_dir.mkdir(exist_ok=True)
+
+    package_owners: dict[str, str] = {}
+
+    for name in source_names:
+        source_packages = base_dir / ".kanon-data" / "sources" / name / ".packages"
+        if not source_packages.exists():
+            continue
+        for pkg in source_packages.iterdir():
+            pkg_name = pkg.name
+            if pkg_name in package_owners:
+                print(
+                    f"Error: Package collision for '{pkg_name}': "
+                    f"provided by both '{package_owners[pkg_name]}' "
+                    f"and '{name}'",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            package_owners[pkg_name] = name
+            link_path = packages_dir / pkg_name
+            if link_path.exists() or link_path.is_symlink():
+                link_path.unlink()
+            link_path.symlink_to(pkg.resolve())
+
+    return package_owners
+
+
+def update_gitignore(
+    base_dir: pathlib.Path,
+    entries: list[str] | None = None,
+) -> None:
+    """Ensure ``.gitignore`` contains the required entries.
+
+    Creates ``.gitignore`` if it does not exist. Appends missing entries
+    without duplicating existing ones.
+
+    Args:
+        base_dir: Project root directory.
+        entries: List of gitignore entries to ensure. Defaults to
+            ``.packages/`` and ``.kanon-data/``.
+    """
+    gitignore = base_dir / ".gitignore"
+    required_entries = entries if entries is not None else [".packages/", ".kanon-data/"]
+
+    existing_content = ""
+    if gitignore.exists():
+        existing_content = gitignore.read_text()
+
+    existing_lines = existing_content.splitlines()
+    missing = [entry for entry in required_entries if entry not in existing_lines]
+
+    if missing:
+        with gitignore.open("a") as f:
+            if existing_content and not existing_content.endswith("\n"):
+                f.write("\n")
+            for entry in missing:
+                f.write(f"{entry}\n")
+
+
+def prepare_marketplace_dir(marketplace_dir: pathlib.Path) -> None:
+    """Create and clean the marketplace directory for pre-sync setup.
+
+    Creates the directory if it does not exist, then removes all
+    contents for a clean slate before sync.
+
+    Args:
+        marketplace_dir: Path to CLAUDE_MARKETPLACES_DIR.
+    """
+    marketplace_dir.mkdir(parents=True, exist_ok=True)
+    for item in marketplace_dir.iterdir():
+        if item.is_symlink() or not item.is_dir():
+            item.unlink()
+        else:
+            shutil.rmtree(item)
+
+
+def _print_package_summary(
+    package_owners: dict[str, str],
+    source_names: list[str],
+) -> None:
+    """Print a structured summary of synced packages grouped by source.
+
+    Args:
+        package_owners: Dict mapping package name to source name.
+        source_names: Ordered list of source names.
+    """
+    if not package_owners:
+        print("\nkanon install: no packages synced.")
+        return
+
+    # Group packages by source, preserving source order
+    by_source: dict[str, list[str]] = {name: [] for name in source_names}
+    for pkg_name, source_name in sorted(package_owners.items()):
+        by_source[source_name].append(pkg_name)
+
+    total = len(package_owners)
+    print(f"\nkanon install: {total} packages synced to .packages/")
+    for source_name in source_names:
+        pkgs = by_source[source_name]
+        if not pkgs:
+            continue
+        print(f"\n  [{source_name}] ({len(pkgs)} packages)")
+        for pkg in pkgs:
+            print(f"    - {pkg}")
+
+
+def install(kanonenv_path: pathlib.Path) -> None:
+    """Execute the full Kanon install lifecycle.
+
+    Steps:
+      1. Parse .kanon and validate sources
+      2. If KANON_MARKETPLACE_INSTALL=true: create and clean marketplace dir
+      3. For each source: mkdir, repo init, envsubst, sync
+      4. Aggregate symlinks into .packages/
+      5. Update .gitignore
+      6. If KANON_MARKETPLACE_INSTALL=true: run install script
+
+    Args:
+        kanonenv_path: Path to the .kanon configuration file.
+
+    Raises:
+        SystemExit: On any failure during the install process.
+    """
+    print(f"kanon install: parsing {kanonenv_path}...")
+    config = parse_kanonenv(kanonenv_path)
+    base_dir = kanonenv_path.parent
+    source_names = config["KANON_SOURCES"]
+    sources = config["sources"]
+    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)
+
+    if marketplace_install:
+        marketplace_dir = pathlib.Path(marketplace_dir_str)
+        print("kanon install: preparing marketplace directory...")
+        prepare_marketplace_dir(marketplace_dir)
+
+    repo_rev = globals_dict.get("REPO_REV", "")
+
+    env_vars: dict[str, str] = {}
+    if "GITBASE" in globals_dict:
+        env_vars["GITBASE"] = globals_dict["GITBASE"]
+    if marketplace_dir_str:
+        env_vars["CLAUDE_MARKETPLACES_DIR"] = marketplace_dir_str
+
+    source_dirs = create_source_dirs(source_names, base_dir)
+
+    for name in source_names:
+        source_dir = source_dirs[name]
+        source_data = sources[name]
+        print(f"kanon install: syncing source '{name}'...")
+        resolved_revision = resolve_version(source_data["url"], source_data["revision"])
+        print(f"  repo init ({source_data['path']})...")
+        run_repo_init(
+            source_dir,
+            source_data["url"],
+            resolved_revision,
+            source_data["path"],
+            repo_rev,
+        )
+        print("  repo envsubst...")
+        run_repo_envsubst(source_dir, env_vars)
+        print("  repo sync...")
+        run_repo_sync(source_dir)
+
+    print("kanon install: aggregating packages into .packages/...")
+    package_owners = aggregate_symlinks(source_names, base_dir)
+    update_gitignore(base_dir)
+
+    _print_package_summary(package_owners, source_names)
+
+    if marketplace_install:
+        print("\nkanon install: installing marketplace plugins...")
+        marketplace_dir = pathlib.Path(marketplace_dir_str)
+        install_marketplace_plugins(marketplace_dir)
+
+    print("\nkanon install: done.")

kanon_cli/core/kanonenv.py

@@ -0,0 +1,322 @@
+"""Multi-source .kanon file parser.
+
+Parses KEY=VALUE configuration files used by Kanon bootstrap. The .kanon
+format supports:
+  - Comments (lines starting with #) and blank lines
+  - Shell variable expansion (``${VAR}``) resolved from environment
+  - Environment variable overrides (env vars take precedence over file values)
+  - Auto-discovered named source groups from ``KANON_SOURCE_<name>_URL`` keys
+  - Boolean parsing for KANON_MARKETPLACE_INSTALL
+
+Source names are auto-discovered by scanning for keys matching the
+``KANON_SOURCE_<name>_URL`` pattern. Names are sorted alphabetically for
+deterministic ordering. Each discovered source must also define
+``KANON_SOURCE_<name>_REVISION`` and ``KANON_SOURCE_<name>_PATH``.
+
+The parser reads the file, applies environment overrides, expands shell
+variables, validates required fields, and returns a structured dict.
+"""
+
+import os
+import pathlib
+import re
+
+from kanon_cli.constants import (
+    SHELL_VAR_PATTERN,
+    SOURCE_PREFIX,
+    SOURCE_SUFFIXES,
+    SUFFIX_TO_KEY,
+)
+
+
+def parse_kanonenv(path: pathlib.Path) -> dict:
+    """Parse a .kanon file into a structured configuration dict.
+
+    Reads KEY=VALUE pairs from the file, applies environment variable
+    overrides, expands shell variables (``${VAR}``), auto-discovers
+    source names from ``KANON_SOURCE_<name>_URL`` keys, and groups
+    source-specific variables.
+
+    Args:
+        path: Path to the .kanon file.
+
+    Returns:
+        A dict with the following keys:
+
+        - ``KANON_SOURCES``: list of source names (auto-discovered,
+          sorted alphabetically)
+        - ``KANON_MARKETPLACE_INSTALL``: bool (defaults to False)
+        - ``sources``: dict mapping each source name to a dict with
+          ``url``, ``revision``, and ``path`` keys
+        - ``globals``: dict of all other KEY=VALUE pairs
+
+    Raises:
+        FileNotFoundError: If the file does not exist.
+        ValueError: If KANON_SOURCES is explicitly set (no longer supported),
+            if no sources are discovered, if a named source is missing
+            required variables (URL, REVISION, PATH), or if a shell
+            variable reference cannot be resolved.
+    """
+    if not path.exists():
+        msg = f".kanon file not found: {path}"
+        raise FileNotFoundError(msg)
+
+    raw_vars = _read_key_value_pairs(path)
+    merged = _apply_env_overrides(raw_vars)
+    expanded = _expand_shell_variables(merged)
+
+    return _build_result(expanded)
+
+
+def _read_key_value_pairs(path: pathlib.Path) -> dict[str, str]:
+    """Read KEY=VALUE pairs from a file, ignoring comments and blanks.
+
+    Args:
+        path: Path to the .kanon file.
+
+    Returns:
+        Dict of raw string key-value pairs.
+    """
+    result: dict[str, str] = {}
+    for line in path.read_text().splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if "=" not in stripped:
+            continue
+        key, _, value = stripped.partition("=")
+        result[key.strip()] = value.strip()
+    return result
+
+
+def _apply_env_overrides(raw_vars: dict[str, str]) -> dict[str, str]:
+    """Override file values with environment variables of the same name.
+
+    Args:
+        raw_vars: Dict of KEY=VALUE pairs from the file.
+
+    Returns:
+        Dict with environment overrides applied.
+    """
+    merged = dict(raw_vars)
+    for key in merged:
+        env_value = os.environ.get(key)
+        if env_value is not None:
+            merged[key] = env_value
+    # Also check for env vars that define source groups not in the file
+    for key, value in os.environ.items():
+        if key.startswith(SOURCE_PREFIX) and key not in merged:
+            merged[key] = value
+    return merged
+
+
+def _expand_shell_variables(merged: dict[str, str]) -> dict[str, str]:
+    """Expand ``${VAR}`` references in values using environment variables.
+
+    Args:
+        merged: Dict of KEY=VALUE pairs with overrides applied.
+
+    Returns:
+        Dict with shell variables expanded.
+
+    Raises:
+        ValueError: If a referenced variable is not defined in
+            the environment.
+    """
+    expanded: dict[str, str] = {}
+    for key, value in merged.items():
+        expanded[key] = _expand_value(value)
+    return expanded
+
+
+def _expand_value(value: str) -> str:
+    """Expand all ``${VAR}`` references in a single value.
+
+    Args:
+        value: The raw value string potentially containing ${VAR}.
+
+    Returns:
+        The value with all variables expanded.
+
+    Raises:
+        ValueError: If a referenced variable is not in the environment.
+    """
+
+    def _replace(match: re.Match) -> str:
+        var_name = match.group(1)
+        env_val = os.environ.get(var_name)
+        if env_val is None:
+            msg = f"Undefined shell variable '${{{var_name}}}' referenced in .kanon value"
+            raise ValueError(msg)
+        return env_val
+
+    return SHELL_VAR_PATTERN.sub(_replace, value)
+
+
+def _discover_source_names(expanded: dict[str, str]) -> list[str]:
+    """Auto-discover source names from ``KANON_SOURCE_<name>_URL`` keys.
+
+    Scans all keys for the ``KANON_SOURCE_<name>_URL`` pattern, extracts
+    the ``<name>`` portion, and returns a sorted list for deterministic
+    ordering.
+
+    Args:
+        expanded: Dict of expanded KEY=VALUE pairs.
+
+    Returns:
+        Sorted list of discovered source names.
+
+    Raises:
+        ValueError: If no ``KANON_SOURCE_<name>_URL`` keys are found.
+    """
+    url_suffix = "_URL"
+    names: list[str] = []
+    for key in expanded:
+        if key.startswith(SOURCE_PREFIX) and key.endswith(url_suffix):
+            name = key[len(SOURCE_PREFIX) : -len(url_suffix)]
+            if name:
+                names.append(name)
+
+    if not names:
+        msg = (
+            "No sources found. Define at least one source using "
+            "KANON_SOURCE_<name>_URL, KANON_SOURCE_<name>_REVISION, "
+            "and KANON_SOURCE_<name>_PATH variables in .kanon"
+        )
+        raise ValueError(msg)
+
+    return sorted(names)
+
+
+def _build_result(expanded: dict[str, str]) -> dict:
+    """Build the structured result dict from expanded variables.
+
+    Auto-discovers source names from ``KANON_SOURCE_<name>_URL`` keys
+    and sorts them alphabetically. Raises an error if ``KANON_SOURCES``
+    is explicitly defined (no longer supported).
+
+    Args:
+        expanded: Dict of expanded KEY=VALUE pairs.
+
+    Returns:
+        Structured dict with KANON_SOURCES (auto-discovered), sources,
+        globals, and KANON_MARKETPLACE_INSTALL.
+
+    Raises:
+        ValueError: If KANON_SOURCES is explicitly set, if no sources
+            are discovered, or if a named source is missing required
+            variables.
+    """
+    if "KANON_SOURCES" in expanded:
+        msg = (
+            "KANON_SOURCES is no longer supported. Source names are "
+            "auto-discovered from KANON_SOURCE_<name>_URL variables. "
+            "Remove the KANON_SOURCES line from your .kanon file."
+        )
+        raise ValueError(msg)
+
+    source_names = _discover_source_names(expanded)
+    sources = _extract_sources(expanded, source_names)
+    globals_dict = _extract_globals(expanded, source_names)
+    marketplace_install = _parse_bool(expanded.get("KANON_MARKETPLACE_INSTALL", "false"))
+
+    return {
+        "KANON_SOURCES": source_names,
+        "KANON_MARKETPLACE_INSTALL": marketplace_install,
+        "sources": sources,
+        "globals": globals_dict,
+    }
+
+
+def validate_sources(
+    expanded: dict[str, str],
+    source_names: list[str],
+) -> None:
+    """Validate that all named sources have required variables.
+
+    Each source name in ``source_names`` must have three corresponding
+    variables defined in ``expanded``:
+      - ``KANON_SOURCE_<name>_URL``
+      - ``KANON_SOURCE_<name>_REVISION``
+      - ``KANON_SOURCE_<name>_PATH``
+
+    Args:
+        expanded: Dict of expanded KEY=VALUE pairs from the .kanon file.
+        source_names: List of source names (auto-discovered, alphabetical).
+
+    Raises:
+        ValueError: If any named source is missing a required variable.
+            The error message includes both the source name and the
+            missing variable name for actionable diagnostics.
+    """
+    for name in source_names:
+        for suffix in SOURCE_SUFFIXES:
+            var_name = f"{SOURCE_PREFIX}{name}{suffix}"
+            if var_name not in expanded:
+                msg = f"Missing required variable '{var_name}' for source '{name}'"
+                raise ValueError(msg)
+
+
+def _extract_sources(
+    expanded: dict[str, str],
+    source_names: list[str],
+) -> dict[str, dict[str, str]]:
+    """Extract named source groups after validation.
+
+    Args:
+        expanded: Dict of expanded KEY=VALUE pairs.
+        source_names: List of source names (auto-discovered, alphabetical).
+
+    Returns:
+        Dict mapping source name to {url, revision, path}.
+
+    Raises:
+        ValueError: If a source is missing a required variable.
+    """
+    validate_sources(expanded, source_names)
+    sources: dict[str, dict[str, str]] = {}
+    for name in source_names:
+        source_data: dict[str, str] = {}
+        for suffix in SOURCE_SUFFIXES:
+            var_name = f"{SOURCE_PREFIX}{name}{suffix}"
+            result_key = SUFFIX_TO_KEY[suffix]
+            source_data[result_key] = expanded[var_name]
+        sources[name] = source_data
+    return sources
+
+
+def _extract_globals(
+    expanded: dict[str, str],
+    source_names: list[str],
+) -> dict[str, str]:
+    """Extract non-source, non-special variables as globals.
+
+    Args:
+        expanded: Dict of expanded KEY=VALUE pairs.
+        source_names: List of source names (auto-discovered, alphabetical).
+
+    Returns:
+        Dict of global variables (excludes KANON_MARKETPLACE_INSTALL
+        and source-specific variables).
+    """
+    source_keys: set[str] = set()
+    for name in source_names:
+        for suffix in SOURCE_SUFFIXES:
+            source_keys.add(f"{SOURCE_PREFIX}{name}{suffix}")
+
+    special_keys = {"KANON_MARKETPLACE_INSTALL"}
+    exclude = source_keys | special_keys
+
+    return {k: v for k, v in expanded.items() if k not in exclude}
+
+
+def _parse_bool(value: str) -> bool:
+    """Parse a string boolean value (case-insensitive).
+
+    Args:
+        value: String value to parse ('true' or 'false').
+
+    Returns:
+        True if value is 'true' (case-insensitive), False otherwise.
+    """
+    return value.strip().lower() == "true"