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

ai_rules/agents/goose.py

@@ -0,0 +1,44 @@
+"""Goose agent implementation."""
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+class GooseAgent(Agent):
+    """Agent for Goose configuration."""
+
+    @property
+    def name(self) -> str:
+        return "Goose"
+
+    @property
+    def agent_id(self) -> str:
+        return "goose"
+
+    @property
+    def config_file_name(self) -> str:
+        return "config.yaml"
+
+    @property
+    def config_file_format(self) -> str:
+        return "yaml"
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of all Goose symlinks."""
+        result = []
+
+        result.append(
+            (Path("~/.config/goose/.goosehints"), self.config_dir / "AGENTS.md")
+        )
+
+        config_file = self.config_dir / "goose" / "config.yaml"
+        if config_file.exists():
+            target_file = self.config.get_settings_file_for_symlink(
+                "goose", config_file
+            )
+            result.append((Path("~/.config/goose/config.yaml"), target_file))
+
+        return result

ai_rules/agents/shared.py

@@ -0,0 +1,35 @@
+"""Shared agent implementation for agent-agnostic configurations."""
+
+from functools import cached_property
+from pathlib import Path
+
+from ai_rules.agents.base import Agent
+
+
+class SharedAgent(Agent):
+    """Agent for shared configurations that both Claude Code and Goose respect."""
+
+    @property
+    def name(self) -> str:
+        return "Shared"
+
+    @property
+    def agent_id(self) -> str:
+        return "shared"
+
+    @property
+    def config_file_name(self) -> str:
+        return ""
+
+    @property
+    def config_file_format(self) -> str:
+        return ""
+
+    @cached_property
+    def symlinks(self) -> list[tuple[Path, Path]]:
+        """Cached list of shared symlinks for agent-agnostic configurations."""
+        result = []
+
+        result.append((Path("~/AGENTS.md"), self.config_dir / "AGENTS.md"))
+
+        return result

ai_rules/bootstrap/__init__.py

@@ -0,0 +1,75 @@
+"""Bootstrap module for system-wide installation and auto-update functionality.
+
+This module provides utilities for:
+- Installing tools via uv (PyPI-based)
+- Checking for and applying updates from PyPI
+- Managing auto-update configuration
+
+Designed to be self-contained and easily extractable for use in other projects.
+"""
+
+from .config import (
+    AutoUpdateConfig,
+    clear_all_pending_updates,
+    clear_pending_update,
+    get_config_dir,
+    get_config_path,
+    get_pending_update_path,
+    load_all_pending_updates,
+    load_auto_update_config,
+    load_pending_update,
+    save_auto_update_config,
+    save_pending_update,
+    should_check_now,
+)
+from .installer import (
+    UV_NOT_FOUND_ERROR,
+    ensure_statusline_installed,
+    get_tool_config_dir,
+    get_tool_version,
+    install_tool,
+    is_command_available,
+    uninstall_tool,
+)
+from .updater import (
+    UPDATABLE_TOOLS,
+    ToolSpec,
+    UpdateInfo,
+    check_pypi_updates,
+    check_tool_updates,
+    get_tool_by_id,
+    perform_pypi_update,
+)
+from .version import get_package_version, is_newer, parse_version
+
+__all__ = [
+    "get_package_version",
+    "is_newer",
+    "parse_version",
+    "UV_NOT_FOUND_ERROR",
+    "ensure_statusline_installed",
+    "get_tool_config_dir",
+    "get_tool_version",
+    "install_tool",
+    "is_command_available",
+    "uninstall_tool",
+    "UPDATABLE_TOOLS",
+    "ToolSpec",
+    "UpdateInfo",
+    "check_pypi_updates",
+    "check_tool_updates",
+    "get_tool_by_id",
+    "perform_pypi_update",
+    "AutoUpdateConfig",
+    "clear_all_pending_updates",
+    "clear_pending_update",
+    "get_config_dir",
+    "get_config_path",
+    "get_pending_update_path",
+    "load_all_pending_updates",
+    "load_auto_update_config",
+    "load_pending_update",
+    "save_auto_update_config",
+    "save_pending_update",
+    "should_check_now",
+]

ai_rules/bootstrap/config.py

@@ -0,0 +1,261 @@
+"""Auto-update configuration management."""
+
+import dataclasses
+import json
+import logging
+import re
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .updater import UpdateInfo
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_tool_id(tool_id: str) -> bool:
+    """Validate tool_id contains only safe characters."""
+    return bool(re.match(r"^[a-z0-9][a-z0-9_-]*$", tool_id))
+
+
+@dataclass
+class AutoUpdateConfig:
+    """Configuration for automatic update checks."""
+
+    enabled: bool = True
+    frequency: str = "daily"  # daily, weekly, never
+    last_check: str | None = None  # ISO format timestamp
+    notify_only: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AutoUpdateConfig":
+        """Create from dict, using dataclass defaults for missing keys."""
+        fields = {f.name for f in dataclasses.fields(cls)}
+        kwargs = {k: v for k, v in data.items() if k in fields}
+        return cls(**kwargs)
+
+
+def get_config_dir(package_name: str = "ai-rules") -> Path:
+    """Get the config directory for the package.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        Path to config directory (e.g., ~/.ai-rules/)
+    """
+    config_dir = Path.home() / f".{package_name}"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir
+
+
+def get_config_path(package_name: str = "ai-rules") -> Path:
+    """Get path to bootstrap config file.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        Path to update_config.yaml
+    """
+    return get_config_dir(package_name) / "update_config.yaml"
+
+
+def load_auto_update_config(package_name: str = "ai-rules") -> AutoUpdateConfig:
+    """Load auto-update configuration.
+
+    Args:
+        package_name: Name of the package
+
+    Returns:
+        AutoUpdateConfig with loaded or default values
+    """
+    config_path = get_config_path(package_name)
+
+    if not config_path.exists():
+        return AutoUpdateConfig()
+
+    try:
+        with open(config_path) as f:
+            data = yaml.safe_load(f) or {}
+        return AutoUpdateConfig.from_dict(data)
+    except (yaml.YAMLError, OSError):
+        return AutoUpdateConfig()
+
+
+def save_auto_update_config(
+    config: AutoUpdateConfig, package_name: str = "ai-rules"
+) -> None:
+    """Save auto-update configuration.
+
+    Args:
+        config: Configuration to save
+        package_name: Name of the package
+    """
+    config_path = get_config_path(package_name)
+
+    try:
+        with open(config_path, "w") as f:
+            yaml.dump(asdict(config), f, default_flow_style=False, sort_keys=False)
+    except OSError as e:
+        logger.debug(f"Failed to save config to {config_path}: {e}")
+
+
+def should_check_now(config: AutoUpdateConfig) -> bool:
+    """Determine if update check is due based on frequency.
+
+    Args:
+        config: Auto-update configuration
+
+    Returns:
+        True if check should be performed, False otherwise
+    """
+    if not config.enabled:
+        return False
+
+    if config.frequency == "never":
+        return False
+
+    if not config.last_check:
+        return True
+
+    try:
+        last_check = datetime.fromisoformat(config.last_check)
+        now = datetime.now()
+
+        if config.frequency == "daily":
+            return now - last_check > timedelta(days=1)
+        elif config.frequency == "weekly":
+            return now - last_check > timedelta(days=7)
+
+    except (ValueError, TypeError):
+        return True
+
+    return False
+
+
+def get_pending_update_path(tool_id: str = "ai-rules") -> Path:
+    """Get path to pending update cache file for a specific tool.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+
+    Returns:
+        Path to pending update JSON file
+
+    Raises:
+        ValueError: If tool_id contains invalid characters
+    """
+    if not _validate_tool_id(tool_id):
+        raise ValueError(f"Invalid tool_id: {tool_id}")
+
+    if tool_id == "ai-rules":
+        filename = "pending_update.json"
+    else:
+        filename = f"pending_{tool_id}_update.json"
+
+    return get_config_dir("ai-rules") / filename
+
+
+def load_pending_update(tool_id: str = "ai-rules") -> UpdateInfo | None:
+    """Load cached update info from previous background check.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+
+    Returns:
+        UpdateInfo if available, None otherwise
+    """
+    if not _validate_tool_id(tool_id):
+        return None
+
+    pending_path = get_pending_update_path(tool_id)
+
+    if not pending_path.exists():
+        return None
+
+    try:
+        with open(pending_path) as f:
+            data = json.load(f)
+
+        return UpdateInfo(
+            has_update=data.get("has_update", False),
+            current_version=data["current_version"],
+            latest_version=data["latest_version"],
+            source=data["source"],
+        )
+    except (json.JSONDecodeError, KeyError, OSError):
+        return None
+
+
+def save_pending_update(info: UpdateInfo, tool_id: str = "ai-rules") -> None:
+    """Save update info for next session.
+
+    Args:
+        info: Update information to save
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+    """
+    if not _validate_tool_id(tool_id):
+        return
+
+    pending_path = get_pending_update_path(tool_id)
+
+    try:
+        data = {
+            "has_update": info.has_update,
+            "current_version": info.current_version,
+            "latest_version": info.latest_version,
+            "source": info.source,
+            "checked_at": datetime.now().isoformat(),
+        }
+
+        with open(pending_path, "w") as f:
+            json.dump(data, f, indent=2)
+    except OSError as e:
+        logger.debug(f"Failed to save pending update to {pending_path}: {e}")
+
+
+def clear_pending_update(tool_id: str = "ai-rules") -> None:
+    """Clear pending update after user action.
+
+    Args:
+        tool_id: Tool identifier (e.g., "ai-rules", "statusline")
+    """
+    if not _validate_tool_id(tool_id):
+        return
+
+    pending_path = get_pending_update_path(tool_id)
+
+    try:
+        pending_path.unlink(missing_ok=True)
+    except OSError as e:
+        logger.debug(f"Failed to delete pending update at {pending_path}: {e}")
+
+
+def load_all_pending_updates() -> dict[str, UpdateInfo]:
+    """Load pending updates for all tools.
+
+    Returns:
+        Dictionary mapping tool_id to UpdateInfo for tools with pending updates
+    """
+    from .updater import UPDATABLE_TOOLS
+
+    result = {}
+    for tool in UPDATABLE_TOOLS:
+        pending = load_pending_update(tool.tool_id)
+        if pending and pending.has_update:
+            result[tool.tool_id] = pending
+
+    return result
+
+
+def clear_all_pending_updates() -> None:
+    """Clear pending updates for all tools."""
+    from .updater import UPDATABLE_TOOLS
+
+    for tool in UPDATABLE_TOOLS:
+        clear_pending_update(tool.tool_id)

ai_rules/bootstrap/installer.py

@@ -0,0 +1,249 @@
+"""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/"
+
+
+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 (PyPI vs local file).
+
+    Args:
+        package_name: Name of the uv tool package
+
+    Returns:
+        "pypi" if installed from PyPI (no path key in requirements)
+        "local" if installed from local file (has path key)
+        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
+
+        # Check first requirement for path key (indicates local install)
+        first_req = requirements[0]
+        if isinstance(first_req, dict) and "path" in first_req:
+            return "local"
+
+        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",
+    force: bool = False,
+    dry_run: bool = False,
+) -> tuple[bool, str]:
+    """Install package as a uv tool from PyPI.
+
+    Args:
+        package_name: Name of package to install
+        force: Force reinstall if already installed
+        dry_run: Show what would be done without executing
+
+    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", "install", package_name]
+    if force:
+        cmd.insert(3, "--force")
+
+    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) -> str:
+    """Install claude-code-statusline if not already present. Fails open.
+
+    Args:
+        dry_run: If True, skip installation
+
+    Returns:
+        Status: "already_installed", "installed", "failed", or "skipped"
+    """
+    if is_command_available("claude-statusline"):
+        return "already_installed"
+
+    if dry_run:
+        return "skipped"
+
+    try:
+        success, _ = install_tool("claude-code-statusline", force=False, dry_run=False)
+        return "installed" if success else "failed"
+    except Exception:
+        return "failed"