ai-agent-rules 0.15.2__py3-none-any.whl

ai_rules/bootstrap/installer.py

@@ -0,0 +1,279 @@
+"""Tool installation utilities."""
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+UV_NOT_FOUND_ERROR = "uv not found in PATH. Install from https://docs.astral.sh/uv/"
+PACKAGE_NAME = "ai-agent-rules"
+GITHUB_REPO = "wpfleger96/ai-rules"
+GITHUB_REPO_URL = f"git+ssh://git@github.com/{GITHUB_REPO}.git"
+STATUSLINE_GITHUB_REPO = "wpfleger96/claude-code-status-line"
+STATUSLINE_GITHUB_REPO_URL = f"git+ssh://git@github.com/{STATUSLINE_GITHUB_REPO}.git"
+
+
+def _validate_package_name(package_name: str) -> bool:
+    """Validate package name matches PyPI naming convention (PEP 508)."""
+    return bool(re.match(r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$", package_name))
+
+
+def get_tool_config_dir(package_name: str = "ai-agent-rules") -> Path:
+    """Get config directory for a uv tool installation.
+
+    Computes the expected path where uv tool install places the package:
+    $XDG_DATA_HOME/uv/tools/{package}/lib/python{version}/site-packages/ai_rules/config/
+
+    Args:
+        package_name: Name of the uv tool package
+
+    Returns:
+        Path to the config directory in the uv tools location
+    """
+
+    data_home = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
+    python_version = f"python{sys.version_info.major}.{sys.version_info.minor}"
+
+    return (
+        Path(data_home)
+        / "uv"
+        / "tools"
+        / package_name
+        / "lib"
+        / python_version
+        / "site-packages"
+        / "ai_rules"
+        / "config"
+    )
+
+
+def get_tool_source(package_name: str) -> str | None:
+    """Detect how a uv tool was installed.
+
+    Args:
+        package_name: Name of the uv tool package
+
+    Returns:
+        "pypi" if installed from PyPI
+        "github" if installed from GitHub
+        "local" if installed from local file
+        None if tool not installed or receipt file not found
+    """
+    data_home = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
+    receipt_path = Path(data_home) / "uv" / "tools" / package_name / "uv-receipt.toml"
+
+    if not receipt_path.exists():
+        return None
+
+    try:
+        with open(receipt_path, "rb") as f:
+            receipt = tomllib.load(f)
+
+        requirements = receipt.get("tool", {}).get("requirements", [])
+        if not requirements:
+            return None
+
+        first_req = requirements[0]
+        if isinstance(first_req, dict):
+            if "path" in first_req:
+                return "local"
+            if "git" in first_req and "github.com" in first_req["git"]:
+                return "github"
+
+        return "pypi"
+
+    except (OSError, tomllib.TOMLDecodeError, KeyError, IndexError):
+        return None
+
+
+def is_command_available(command: str) -> bool:
+    """Check if a command is available in PATH.
+
+    Args:
+        command: Command name to check
+
+    Returns:
+        True if command is available, False otherwise
+    """
+    return shutil.which(command) is not None
+
+
+def install_tool(
+    package_name: str = "ai-agent-rules",
+    from_github: bool = False,
+    github_url: str | None = None,
+    force: bool = False,
+    dry_run: bool = False,
+) -> tuple[bool, str]:
+    """Install package as a uv tool.
+
+    Args:
+        package_name: Name of package to install (ignored if from_github=True)
+        from_github: Install from GitHub instead of PyPI
+        github_url: GitHub URL to install from (only used if from_github=True)
+        force: Force reinstall if already installed
+        dry_run: Show what would be done without executing
+
+    Returns:
+        Tuple of (success, message)
+    """
+    if not from_github and not _validate_package_name(package_name):
+        return False, f"Invalid package name: {package_name}"
+
+    if not is_command_available("uv"):
+        return False, UV_NOT_FOUND_ERROR
+
+    if from_github:
+        source = github_url if github_url else GITHUB_REPO_URL
+    else:
+        source = package_name
+    cmd = ["uv", "tool", "install", source]
+
+    if force:
+        cmd.insert(3, "--force")
+        if from_github:
+            cmd.insert(4, "--reinstall")
+
+    if dry_run:
+        return True, f"Would run: {' '.join(cmd)}"
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+
+        if result.returncode == 0:
+            return True, "Installation successful"
+
+        error_msg = result.stderr.strip()
+        if not error_msg:
+            error_msg = "Installation failed with no error message"
+
+        return False, error_msg
+
+    except subprocess.TimeoutExpired:
+        return False, "Installation timed out after 60 seconds"
+    except Exception as e:
+        return False, f"Unexpected error: {e}"
+
+
+def uninstall_tool(package_name: str = "ai-agent-rules") -> tuple[bool, str]:
+    """Uninstall package from uv tools.
+
+    Args:
+        package_name: Name of package to uninstall
+
+    Returns:
+        Tuple of (success, message)
+    """
+    if not _validate_package_name(package_name):
+        return False, f"Invalid package name: {package_name}"
+
+    if not is_command_available("uv"):
+        return False, UV_NOT_FOUND_ERROR
+
+    cmd = ["uv", "tool", "uninstall", package_name]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+
+        if result.returncode == 0:
+            return True, "Uninstallation successful"
+
+        error_msg = result.stderr.strip()
+        if not error_msg:
+            error_msg = "Uninstallation failed with no error message"
+
+        return False, error_msg
+
+    except subprocess.TimeoutExpired:
+        return False, "Uninstallation timed out after 30 seconds"
+    except Exception as e:
+        return False, f"Unexpected error: {e}"
+
+
+def get_tool_version(tool_name: str) -> str | None:
+    """Get installed version of a uv tool by parsing `uv tool list`.
+
+    Args:
+        tool_name: Name of the tool package (e.g., "claude-code-statusline")
+
+    Returns:
+        Version string (e.g., "0.7.1") or None if not installed
+    """
+    if not _validate_package_name(tool_name):
+        return None
+
+    if not is_command_available("uv"):
+        return None
+
+    try:
+        result = subprocess.run(
+            ["uv", "tool", "list"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+
+        if result.returncode != 0:
+            return None
+
+        for line in result.stdout.splitlines():
+            if line.startswith(tool_name):
+                match = re.search(r"v?(\d+\.\d+\.\d+)", line)
+                if match:
+                    return match.group(1)
+
+        return None
+
+    except (subprocess.TimeoutExpired, Exception):
+        return None
+
+
+def ensure_statusline_installed(
+    dry_run: bool = False, from_github: bool = False
+) -> tuple[str, str | None]:
+    """Install claude-code-statusline if not already present. Fails open.
+
+    Args:
+        dry_run: If True, show what would be done without executing
+        from_github: Install from GitHub instead of PyPI
+
+    Returns:
+        Tuple of (status, message) where status is:
+        "already_installed", "installed", "failed", or "skipped"
+        Message is only provided in dry_run mode
+    """
+    if is_command_available("claude-statusline"):
+        return "already_installed", None
+
+    try:
+        success, message = install_tool(
+            "claude-code-statusline",
+            from_github=from_github,
+            github_url=STATUSLINE_GITHUB_REPO_URL if from_github else None,
+            force=False,
+            dry_run=dry_run,
+        )
+        if success:
+            return "installed", message if dry_run else None
+        else:
+            return "failed", None
+    except Exception:
+        return "failed", None

ai_rules/bootstrap/updater.py

@@ -0,0 +1,344 @@
+"""Update checking and application utilities."""
+
+import json
+import logging
+import os
+import re
+import subprocess
+import urllib.request
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from .installer import (
+    GITHUB_REPO,
+    GITHUB_REPO_URL,
+    UV_NOT_FOUND_ERROR,
+    _validate_package_name,
+    get_tool_source,
+    get_tool_version,
+    is_command_available,
+)
+from .version import is_newer
+
+logger = logging.getLogger(__name__)
+
+
+def get_configured_index_url() -> str | None:
+    """Get package index URL from environment.
+
+    Checks in order of preference:
+    1. UV_DEFAULT_INDEX (modern uv, recommended)
+    2. UV_INDEX_URL (deprecated uv, still supported)
+    3. PIP_INDEX_URL (pip compatibility)
+
+    Returns:
+        Index URL if configured, None otherwise
+    """
+    return (
+        os.environ.get("UV_DEFAULT_INDEX")
+        or os.environ.get("UV_INDEX_URL")
+        or os.environ.get("PIP_INDEX_URL")
+    )
+
+
+@dataclass
+class UpdateInfo:
+    """Information about available updates."""
+
+    has_update: bool
+    current_version: str
+    latest_version: str
+    source: str
+
+
+def check_index_updates(
+    package_name: str, current_version: str, timeout: int = 30
+) -> UpdateInfo:
+    """Check configured package index for newer version.
+
+    Uses `uvx pip index versions` to query the user's configured index,
+    which respects pip.conf and environment variables.
+
+    Args:
+        package_name: Package name to check
+        current_version: Currently installed version
+        timeout: Request timeout in seconds (default: 30)
+
+    Returns:
+        UpdateInfo with update status
+    """
+    if not _validate_package_name(package_name):
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="index",
+        )
+
+    if not is_command_available("uvx"):
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="index",
+        )
+
+    try:
+        cmd = ["uvx", "--refresh", "pip", "index", "versions", package_name]
+
+        # Pass index URL explicitly since pip doesn't understand UV_* env vars
+        if index_url := get_configured_index_url():
+            cmd.extend(["--index-url", index_url])
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+
+        if result.returncode != 0:
+            logger.debug(f"uvx pip index versions failed: {result.stderr}")
+            return UpdateInfo(
+                has_update=False,
+                current_version=current_version,
+                latest_version=current_version,
+                source="index",
+            )
+
+        output = result.stdout.strip()
+        match = re.search(r"^\S+\s+\(([^)]+)\)", output)
+        if match:
+            latest_version = match.group(1)
+            has_update = is_newer(latest_version, current_version)
+            return UpdateInfo(
+                has_update=has_update,
+                current_version=current_version,
+                latest_version=latest_version,
+                source="index",
+            )
+
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="index",
+        )
+
+    except subprocess.TimeoutExpired:
+        logger.debug("uvx pip index versions timed out")
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="index",
+        )
+    except Exception as e:
+        logger.debug(f"Index check failed: {e}")
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="index",
+        )
+
+
+def check_github_updates(
+    repo: str, current_version: str, timeout: int = 10
+) -> UpdateInfo:
+    """Check GitHub tags for newer version.
+
+    Args:
+        repo: GitHub repository in format "owner/repo"
+        current_version: Currently installed version
+        timeout: Request timeout in seconds (default: 10)
+
+    Returns:
+        UpdateInfo with update status
+    """
+    try:
+        url = f"https://api.github.com/repos/{repo}/tags"
+
+        req = urllib.request.Request(url)
+        req.add_header("User-Agent", f"ai-rules/{current_version}")
+
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            data = json.loads(response.read().decode())
+
+        if not data or len(data) == 0:
+            return UpdateInfo(
+                has_update=False,
+                current_version=current_version,
+                latest_version=current_version,
+                source="github",
+            )
+
+        latest_tag = data[0]["name"]
+        latest_version = latest_tag.lstrip("v")
+
+        has_update = is_newer(latest_version, current_version)
+
+        return UpdateInfo(
+            has_update=has_update,
+            current_version=current_version,
+            latest_version=latest_version,
+            source="github",
+        )
+
+    except (urllib.error.URLError, json.JSONDecodeError, KeyError, IndexError) as e:
+        logger.debug(f"GitHub check failed: {e}")
+        return UpdateInfo(
+            has_update=False,
+            current_version=current_version,
+            latest_version=current_version,
+            source="github",
+        )
+
+
+def perform_pypi_update(package_name: str) -> tuple[bool, str, bool]:
+    """Upgrade via uv tool upgrade or GitHub.
+
+    Args:
+        package_name: Name of package to upgrade
+
+    Returns:
+        Tuple of (success, message, was_upgraded)
+        - success: Whether command succeeded
+        - message: Human-readable status message
+        - was_upgraded: True if package was actually upgraded (not already up-to-date)
+    """
+    if not is_command_available("uv"):
+        return False, UV_NOT_FOUND_ERROR, False
+
+    source = get_tool_source(package_name)
+
+    if source == "github":
+        cmd = ["uv", "tool", "install", "--force", "--reinstall", GITHUB_REPO_URL]
+    elif source == "local":
+        cmd = ["uv", "tool", "install", package_name, "--force", "--no-cache"]
+    else:
+        if not _validate_package_name(package_name):
+            return False, f"Invalid package name: {package_name}", False
+        cmd = ["uv", "tool", "upgrade", package_name, "--no-cache"]
+
+        # Ensure upgrade uses same index as version check
+        # Use --default-index (modern) not --index-url (deprecated)
+        if index_url := get_configured_index_url():
+            cmd.extend(["--default-index", index_url])
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+
+        if result.returncode == 0:
+            output = result.stdout + result.stderr
+
+            upgrade_patterns = [
+                r"Upgraded .+ from .+ to .+",
+                r"Installed .+ \d+\.\d+",
+                r"Successfully installed",
+            ]
+
+            already_up_to_date_patterns = [
+                r"Nothing to upgrade",
+                r"already.*installed",
+                r"already.*up.*to.*date",
+            ]
+
+            was_upgraded = False
+            if any(
+                re.search(pattern, output, re.IGNORECASE)
+                for pattern in upgrade_patterns
+            ):
+                was_upgraded = True
+            elif any(
+                re.search(pattern, output, re.IGNORECASE)
+                for pattern in already_up_to_date_patterns
+            ):
+                was_upgraded = False
+            else:
+                was_upgraded = True
+
+            return True, "Upgrade successful", was_upgraded
+
+        error_msg = result.stderr.strip()
+        if not error_msg:
+            error_msg = "Upgrade failed with no error message"
+
+        return False, error_msg, False
+
+    except subprocess.TimeoutExpired:
+        return False, "Upgrade timed out after 60 seconds", False
+    except Exception as e:
+        return False, f"Unexpected error: {e}", False
+
+
+@dataclass
+class ToolSpec:
+    """Specification for an updatable tool."""
+
+    tool_id: str
+    package_name: str
+    display_name: str
+    get_version: Callable[[], str | None]
+    is_installed: Callable[[], bool]
+
+
+UPDATABLE_TOOLS: list[ToolSpec] = [
+    ToolSpec(
+        tool_id="ai-rules",
+        package_name="ai-agent-rules",
+        display_name="ai-rules",
+        get_version=lambda: get_tool_version("ai-agent-rules"),
+        is_installed=lambda: True,  # Always installed (it's us)
+    ),
+    ToolSpec(
+        tool_id="statusline",
+        package_name="claude-code-statusline",
+        display_name="statusline",
+        get_version=lambda: get_tool_version("claude-code-statusline"),
+        is_installed=lambda: is_command_available("claude-statusline"),
+    ),
+]
+
+
+def check_tool_updates(tool: ToolSpec, timeout: int = 30) -> UpdateInfo | None:
+    """Check for updates for any tool - auto-detect PyPI vs GitHub source.
+
+    Args:
+        tool: Tool specification
+        timeout: Request timeout in seconds (default: 30)
+
+    Returns:
+        UpdateInfo if tool is installed and update check succeeds, None otherwise
+    """
+    if not tool.is_installed():
+        return None
+
+    current = tool.get_version()
+    if current is None:
+        return None
+
+    source = get_tool_source(tool.package_name)
+
+    if source == "github" and tool.tool_id == "ai-rules":
+        return check_github_updates(GITHUB_REPO, current, timeout)
+    else:
+        return check_index_updates(tool.package_name, current, timeout)
+
+
+def get_tool_by_id(tool_id: str) -> ToolSpec | None:
+    """Look up tool spec by ID.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+
+    Returns:
+        ToolSpec if found, None otherwise
+    """
+    return next((t for t in UPDATABLE_TOOLS if t.tool_id == tool_id), None)

ai_rules/bootstrap/version.py

@@ -0,0 +1,52 @@
+"""Version utilities for package management."""
+
+from importlib.metadata import version as get_version
+
+from packaging.version import InvalidVersion, Version
+
+
+def parse_version(version_str: str) -> Version:
+    """Parse version string, handling 'v' prefix.
+
+    Args:
+        version_str: Version string (e.g., "1.2.3" or "v1.2.3")
+
+    Returns:
+        Parsed Version object
+
+    Raises:
+        InvalidVersion: If version string is malformed
+    """
+    clean = version_str.lstrip("v")
+    return Version(clean)
+
+
+def is_newer(latest: str, current: str) -> bool:
+    """Check if latest version is newer than current.
+
+    Args:
+        latest: Latest version string
+        current: Current version string
+
+    Returns:
+        True if latest is newer, False otherwise
+    """
+    try:
+        return parse_version(latest) > parse_version(current)
+    except InvalidVersion:
+        return False
+
+
+def get_package_version(package_name: str) -> str:
+    """Get installed version of a package.
+
+    Args:
+        package_name: Name of the package (e.g., "ai-rules")
+
+    Returns:
+        Version string (e.g., "0.3.0")
+
+    Raises:
+        PackageNotFoundError: If package is not installed
+    """
+    return get_version(package_name)