devsync 0.5.5__py3-none-any.whl

aiconfigkit/utils/backup.py

@@ -0,0 +1,169 @@
+"""Backup utilities for safe file operations."""
+
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def create_backup(file_path: Path, backup_dir: Optional[Path] = None) -> Path:
+    """
+    Create a timestamped backup of a file before modifying it.
+
+    Args:
+        file_path: Path to file to backup
+        backup_dir: Optional custom backup directory (defaults to .instructionkit/backups)
+
+    Returns:
+        Path to created backup file
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+
+    Example:
+        >>> from pathlib import Path
+        >>> backup_path = create_backup(Path(".claude/rules/company.test.md"))
+        >>> # Original file preserved at .instructionkit/backups/TIMESTAMP/company.test.md
+    """
+    if not file_path.exists():
+        raise FileNotFoundError(f"Cannot backup non-existent file: {file_path}")
+
+    # Determine backup directory
+    if backup_dir is None:
+        # Default: .instructionkit/backups in project root
+        from aiconfigkit.utils.project import find_project_root
+
+        project_root = find_project_root()
+        if project_root:
+            backup_dir = project_root / ".instructionkit" / "backups"
+        else:
+            # Fallback to global backups
+            backup_dir = Path.home() / ".instructionkit" / "backups"
+
+    # Create timestamped backup directory
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamped_dir = backup_dir / timestamp
+    timestamped_dir.mkdir(parents=True, exist_ok=True)
+
+    # Preserve relative structure
+    # If file is .claude/rules/company.test.md, backup as backups/TIMESTAMP/company.test.md
+    backup_path = timestamped_dir / file_path.name
+
+    # Handle name collision (multiple backups in same second)
+    counter = 1
+    while backup_path.exists():
+        backup_path = timestamped_dir / f"{file_path.stem}_{counter}{file_path.suffix}"
+        counter += 1
+
+    # Copy file to backup
+    shutil.copy2(file_path, backup_path)
+
+    return backup_path
+
+
+def list_backups(backup_dir: Optional[Path] = None) -> list[tuple[datetime, Path]]:
+    """
+    List all available backups sorted by date (newest first).
+
+    Args:
+        backup_dir: Optional custom backup directory
+
+    Returns:
+        List of (timestamp, backup_directory) tuples
+
+    Example:
+        >>> backups = list_backups()
+        >>> for timestamp, backup_path in backups:
+        ...     print(f"{timestamp}: {backup_path}")
+    """
+    if backup_dir is None:
+        from aiconfigkit.utils.project import find_project_root
+
+        project_root = find_project_root()
+        if project_root:
+            backup_dir = project_root / ".instructionkit" / "backups"
+        else:
+            backup_dir = Path.home() / ".instructionkit" / "backups"
+
+    if not backup_dir.exists():
+        return []
+
+    backups: list[tuple[datetime, Path]] = []
+    for item in backup_dir.iterdir():
+        if item.is_dir():
+            try:
+                # Parse timestamp from directory name (YYYYMMDD_HHMMSS)
+                timestamp = datetime.strptime(item.name, "%Y%m%d_%H%M%S")
+                backups.append((timestamp, item))
+            except ValueError:
+                # Skip directories that don't match timestamp format
+                continue
+
+    # Sort by timestamp, newest first
+    backups.sort(reverse=True, key=lambda x: x[0])
+    return backups
+
+
+def cleanup_old_backups(max_age_days: int = 30, backup_dir: Optional[Path] = None) -> int:
+    """
+    Remove backups older than specified age.
+
+    Args:
+        max_age_days: Maximum age of backups to keep (default: 30 days)
+        backup_dir: Optional custom backup directory
+
+    Returns:
+        Number of backup directories removed
+
+    Example:
+        >>> # Remove backups older than 30 days
+        >>> removed = cleanup_old_backups(30)
+        >>> print(f"Removed {removed} old backup(s)")
+    """
+    if backup_dir is None:
+        from aiconfigkit.utils.project import find_project_root
+
+        project_root = find_project_root()
+        if project_root:
+            backup_dir = project_root / ".instructionkit" / "backups"
+        else:
+            backup_dir = Path.home() / ".instructionkit" / "backups"
+
+    if not backup_dir.exists():
+        return 0
+
+    cutoff_date = datetime.now().timestamp() - (max_age_days * 24 * 60 * 60)
+    removed_count = 0
+
+    for timestamp, backup_path in list_backups(backup_dir):
+        if timestamp.timestamp() < cutoff_date:
+            shutil.rmtree(backup_path)
+            removed_count += 1
+
+    return removed_count
+
+
+def restore_backup(backup_path: Path, target_path: Path) -> None:
+    """
+    Restore a file from backup.
+
+    Args:
+        backup_path: Path to backup file
+        target_path: Where to restore the file
+
+    Raises:
+        FileNotFoundError: If backup doesn't exist
+
+    Example:
+        >>> # Restore from specific backup
+        >>> backup = Path(".instructionkit/backups/20251109_143052/company.test.md")
+        >>> restore_backup(backup, Path(".claude/rules/company.test.md"))
+    """
+    if not backup_path.exists():
+        raise FileNotFoundError(f"Backup not found: {backup_path}")
+
+    # Create target directory if needed
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Copy backup to target
+    shutil.copy2(backup_path, target_path)

aiconfigkit/utils/dotenv.py

@@ -0,0 +1,128 @@
+"""Utilities for .env file manipulation."""
+
+import re
+from pathlib import Path
+
+from dotenv import dotenv_values, set_key
+
+from aiconfigkit.core.models import EnvironmentConfig, InstallationScope
+from aiconfigkit.utils.atomic_write import atomic_write
+
+
+def load_env_config(env_path: Path, scope: InstallationScope) -> EnvironmentConfig:
+    """
+    Load environment configuration from .env file.
+
+    Args:
+        env_path: Path to .env file
+        scope: Installation scope (PROJECT or GLOBAL)
+
+    Returns:
+        EnvironmentConfig object with loaded variables
+    """
+    variables: dict[str, str] = {}
+    if env_path.exists():
+        raw_variables = dotenv_values(str(env_path))
+        # Filter out None values (empty vars) and ensure all values are strings
+        variables = {k: str(v) for k, v in raw_variables.items() if v is not None}
+
+    return EnvironmentConfig(variables=variables, file_path=str(env_path), scope=scope)
+
+
+def save_env_config(env_config: EnvironmentConfig) -> None:
+    """
+    Save environment configuration to .env file using atomic write.
+
+    Args:
+        env_config: EnvironmentConfig to save
+    """
+    if not env_config.file_path:
+        raise ValueError("EnvironmentConfig must have file_path set")
+
+    env_path = Path(env_config.file_path)
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Ensure .gitignore exists for .env file
+    ensure_env_gitignored(env_path)
+
+    # Write .env file atomically
+    with atomic_write(env_path, mode="w", encoding="utf-8", create_backup=True) as f:
+        f.write("# MCP Server Credentials\n")
+        f.write("# Auto-generated by InstructionKit\n")
+        f.write("# DO NOT commit this file to version control\n\n")
+
+        for key, value in sorted(env_config.variables.items()):
+            # Escape newlines and quotes in values
+            escaped_value = value.replace("\\", "\\\\").replace("\n", "\\n").replace('"', '\\"')
+            f.write(f'{key}="{escaped_value}"\n')
+
+
+def set_env_variable(env_path: Path, key: str, value: str) -> None:
+    """
+    Set a single environment variable in .env file.
+
+    Uses python-dotenv's set_key for safe updating.
+
+    Args:
+        env_path: Path to .env file
+        key: Variable name (must be UPPERCASE_WITH_UNDERSCORES)
+        value: Variable value
+    """
+    # Validate key format
+    if not re.match(r"^[A-Z][A-Z0-9_]*$", key):
+        raise ValueError(f"Invalid environment variable name: {key}. Must match ^[A-Z][A-Z0-9_]*$")
+
+    env_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Ensure .gitignore exists
+    ensure_env_gitignored(env_path)
+
+    # Use python-dotenv's set_key for safe update
+    set_key(str(env_path), key, value, quote_mode="always")
+
+
+def ensure_env_gitignored(env_path: Path) -> None:
+    """
+    Ensure .env file is in .gitignore.
+
+    Args:
+        env_path: Path to .env file
+    """
+    gitignore_path = env_path.parent / ".gitignore"
+
+    # Check if .env is already ignored
+    if gitignore_path.exists():
+        content = gitignore_path.read_text()
+        if ".env" in content:
+            return
+
+    # Add .env to .gitignore
+    with open(gitignore_path, "a") as f:
+        f.write("\n# MCP Server Credentials (added by InstructionKit)\n")
+        f.write(".env\n")
+
+
+def merge_env_configs(project_config: EnvironmentConfig, global_config: EnvironmentConfig) -> EnvironmentConfig:
+    """
+    Merge project and global environment configurations.
+
+    Project variables take precedence over global variables.
+
+    Args:
+        project_config: Project-scoped environment config
+        global_config: Global-scoped environment config
+
+    Returns:
+        Merged EnvironmentConfig with project taking precedence
+    """
+    merged_variables = {}
+
+    # Start with global variables
+    merged_variables.update(global_config.variables)
+
+    # Override with project variables
+    merged_variables.update(project_config.variables)
+
+    return EnvironmentConfig(
+        variables=merged_variables, file_path=project_config.file_path, scope=InstallationScope.PROJECT
+    )

aiconfigkit/utils/git_helpers.py

@@ -0,0 +1,187 @@
+"""Git operations for template repositories."""
+
+from pathlib import Path
+from typing import Optional
+
+try:
+    from git import Repo
+    from git.exc import GitCommandError, InvalidGitRepositoryError
+except ImportError:
+    # GitPython not installed - will be caught by runtime checks
+    Repo = None  # type: ignore
+    GitCommandError = Exception  # type: ignore
+    InvalidGitRepositoryError = Exception  # type: ignore
+
+
+class TemplateAuthError(Exception):
+    """Raised when Git authentication fails for template repository."""
+
+    pass
+
+
+class TemplateNetworkError(Exception):
+    """Raised when network/repository is unavailable."""
+
+    pass
+
+
+class GitPythonNotInstalledError(Exception):
+    """Raised when GitPython is not installed."""
+
+    pass
+
+
+def _check_gitpython() -> None:
+    """Check if GitPython is available."""
+    if Repo is None:
+        raise GitPythonNotInstalledError("GitPython is required for template sync. Install with: pip install GitPython")
+
+
+def clone_template_repo(url: str, destination: Path, depth: int = 1) -> "Repo":
+    """
+    Clone template repository using system Git credentials.
+
+    Uses Git credential helpers configured on the user's system.
+    Supports both HTTPS and SSH URLs.
+
+    Args:
+        url: Git repository URL
+        destination: Destination directory for clone
+        depth: Clone depth (default 1 for shallow clone)
+
+    Returns:
+        Git Repo object
+
+    Raises:
+        TemplateAuthError: If authentication fails
+        TemplateNetworkError: If network/repository unavailable
+        GitPythonNotInstalledError: If GitPython not installed
+
+    Example:
+        >>> from pathlib import Path
+        >>> repo = clone_template_repo(
+        ...     "https://github.com/acme/templates",
+        ...     Path("~/.instructionkit/templates/acme")
+        ... )
+    """
+    _check_gitpython()
+
+    try:
+        repo = Repo.clone_from(
+            url=url,
+            to_path=str(destination),
+            depth=depth,
+            env={
+                "GIT_TERMINAL_PROMPT": "0",  # Fail if credentials needed but not available
+            },
+        )
+        return repo
+    except GitCommandError as e:
+        error_str = str(e).lower()
+
+        # Check for authentication failures
+        auth_keywords = ["authentication failed", "401", "403", "permission denied", "publickey"]
+        if any(keyword in error_str for keyword in auth_keywords):
+            raise TemplateAuthError(
+                f"Authentication failed for {url}.\n\n"
+                f"To configure Git credentials:\n\n"
+                f"For HTTPS URLs:\n"
+                f"  git config --global credential.helper store\n"
+                f"  # Then perform a git clone manually to cache credentials\n\n"
+                f"For SSH URLs:\n"
+                f'  1. Generate SSH key: ssh-keygen -t ed25519 -C "your_email@example.com"\n'
+                f"  2. Add to GitHub: cat ~/.ssh/id_ed25519.pub\n"
+                f"  3. Use SSH URL: git@github.com:org/repo.git\n\n"
+                f"Original error: {e}"
+            ) from e
+
+        # Check for repository not found (could be private repo without access)
+        if "404" in error_str or "not found" in error_str:
+            raise TemplateNetworkError(
+                f"Repository not found: {url}\n\n"
+                f"This could mean:\n"
+                f"  - Repository doesn't exist\n"
+                f"  - Repository is private and you don't have access\n"
+                f"  - URL is incorrect\n\n"
+                f"Original error: {e}"
+            ) from e
+
+        # Other network/Git errors
+        raise TemplateNetworkError(f"Failed to clone repository from {url}: {e}") from e
+
+
+def update_template_repo(repo_path: Path) -> bool:
+    """
+    Pull latest changes from template repository.
+
+    Args:
+        repo_path: Path to local repository
+
+    Returns:
+        True if updates were pulled, False if already up-to-date
+
+    Raises:
+        TemplateNetworkError: If update fails
+        GitPythonNotInstalledError: If GitPython not installed
+        InvalidGitRepositoryError: If path is not a Git repository
+
+    Example:
+        >>> from pathlib import Path
+        >>> has_updates = update_template_repo(Path("~/.instructionkit/templates/acme"))
+        >>> if has_updates:
+        ...     print("Repository updated!")
+    """
+    _check_gitpython()
+
+    try:
+        repo = Repo(repo_path)
+    except InvalidGitRepositoryError as e:
+        raise InvalidGitRepositoryError(f"Not a Git repository: {repo_path}") from e
+
+    origin = repo.remotes.origin
+
+    try:
+        # Fetch latest changes
+        fetch_info = origin.fetch()[0]
+
+        # Check if remote has changes
+        if repo.head.commit == fetch_info.commit:
+            return False  # Already up-to-date
+
+        # Pull changes
+        origin.pull()
+        return True
+
+    except GitCommandError as e:
+        raise TemplateNetworkError(f"Failed to update repository at {repo_path}: {e}") from e
+
+
+def get_repo_version(repo_path: Path) -> Optional[str]:
+    """
+    Get current version of repository (latest tag or commit hash).
+
+    Args:
+        repo_path: Path to local repository
+
+    Returns:
+        Version string (tag name or short commit hash)
+
+    Raises:
+        GitPythonNotInstalledError: If GitPython not installed
+        InvalidGitRepositoryError: If path is not a Git repository
+    """
+    _check_gitpython()
+
+    try:
+        repo = Repo(repo_path)
+    except InvalidGitRepositoryError as e:
+        raise InvalidGitRepositoryError(f"Not a Git repository: {repo_path}") from e
+
+    # Try to get latest tag
+    if repo.tags:
+        # Get most recent tag
+        latest_tag = sorted(repo.tags, key=lambda t: t.commit.committed_datetime)[-1]
+        return str(latest_tag)
+
+    # Fallback to commit hash
+    return repo.head.commit.hexsha[:8]

aiconfigkit/utils/logging.py

@@ -0,0 +1,60 @@
+"""Logging configuration for InstructionKit."""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def setup_logging(level: str = "INFO", log_file: Optional[Path] = None, format_string: Optional[str] = None) -> None:
+    """
+    Configure logging for InstructionKit.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_file: Optional file path for logging output
+        format_string: Optional custom format string
+    """
+    if format_string is None:
+        format_string = "[%(asctime)s] %(name)s - %(levelname)s - %(message)s"
+
+    # Convert string level to logging constant
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+    # Create handlers
+    handlers: list[logging.Handler] = []
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(numeric_level)
+    console_handler.setFormatter(logging.Formatter(format_string))
+    handlers.append(console_handler)
+
+    # File handler if specified
+    if log_file:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(numeric_level)
+        file_handler.setFormatter(logging.Formatter(format_string))
+        handlers.append(file_handler)
+
+    # Configure root logger
+    logging.basicConfig(
+        level=numeric_level,
+        format=format_string,
+        handlers=handlers,
+        force=True,
+    )
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance for a module.
+
+    Args:
+        name: Name of the module (usually __name__)
+
+    Returns:
+        Configured logger instance
+    """
+    return logging.getLogger(name)

aiconfigkit/utils/namespace.py

@@ -0,0 +1,134 @@
+"""Namespace utilities for template repositories."""
+
+import re
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+
+def extract_repo_name_from_url(repo_url: str) -> str:
+    """
+    Extract repository name from Git URL.
+
+    Handles both HTTPS and SSH URLs.
+
+    Args:
+        repo_url: Git repository URL
+
+    Returns:
+        Repository name (e.g., "coding-standards" from "github.com/org/coding-standards")
+
+    Examples:
+        >>> extract_repo_name_from_url("https://github.com/acme/coding-standards")
+        'coding-standards'
+        >>> extract_repo_name_from_url("git@github.com:acme/coding-standards.git")
+        'coding-standards'
+        >>> extract_repo_name_from_url("https://github.com/acme/coding-standards.git")
+        'coding-standards'
+    """
+    # Handle SSH URLs (git@github.com:org/repo.git)
+    if repo_url.startswith("git@"):
+        # Extract the path after the colon
+        _, _, path = repo_url.partition(":")
+        repo_name = path.rstrip(".git").split("/")[-1]
+        return repo_name
+
+    # Handle HTTPS URLs
+    parsed = urlparse(repo_url)
+    path = parsed.path.strip("/")
+
+    # Remove .git suffix if present
+    if path.endswith(".git"):
+        path = path[:-4]
+
+    # Get the last component (repository name)
+    repo_name = path.split("/")[-1]
+
+    return repo_name
+
+
+def derive_namespace(repo_url: str, override: Optional[str] = None) -> str:
+    """
+    Derive namespace from repository URL or use override.
+
+    Always returns a valid namespace. If override provided, validates and returns it.
+    Otherwise, derives from repository URL.
+
+    Args:
+        repo_url: Git repository URL
+        override: Optional namespace override
+
+    Returns:
+        Valid namespace string
+
+    Raises:
+        ValueError: If override is invalid (empty or contains invalid characters)
+
+    Examples:
+        >>> derive_namespace("https://github.com/acme/coding-standards")
+        'coding-standards'
+        >>> derive_namespace("https://github.com/acme/coding-standards", "acme")
+        'acme'
+    """
+    if override:
+        # Validate override namespace
+        if not override.strip():
+            raise ValueError("Namespace override cannot be empty")
+
+        # Namespace must be alphanumeric with hyphens only
+        if not re.match(r"^[a-zA-Z0-9-]+$", override):
+            raise ValueError(f"Invalid namespace '{override}': must contain only alphanumeric characters and hyphens")
+
+        if len(override) > 50:
+            raise ValueError(f"Namespace '{override}' exceeds maximum length of 50 characters")
+
+        return override
+
+    # Derive from repository URL
+    return extract_repo_name_from_url(repo_url)
+
+
+def get_install_path(namespace: str, template_name: str, ide_base_path: Path, extension: str) -> Path:
+    """
+    Construct namespaced installation path using dot notation.
+
+    Format: {ide_base_path}/{namespace}.{template-name}.{ext}
+
+    Args:
+        namespace: Repository namespace
+        template_name: Template identifier
+        ide_base_path: Base directory for IDE templates (e.g., .cursor/rules/)
+        extension: File extension (e.g., "md", "mdc")
+
+    Returns:
+        Full installation path
+
+    Examples:
+        >>> from pathlib import Path
+        >>> path = get_install_path("acme", "test-command", Path(".cursor/rules"), "md")
+        >>> str(path)
+        '.cursor/rules/acme.test-command.md'
+    """
+    # Construct namespaced filename: namespace.template-name.ext
+    filename = f"{namespace}.{template_name}.{extension}"
+    return ide_base_path / filename
+
+
+def validate_namespace(namespace: str) -> None:
+    """
+    Validate namespace format.
+
+    Args:
+        namespace: Namespace to validate
+
+    Raises:
+        ValueError: If namespace is invalid
+    """
+    if not namespace.strip():
+        raise ValueError("Namespace cannot be empty")
+
+    if not re.match(r"^[a-zA-Z0-9-]+$", namespace):
+        raise ValueError(f"Invalid namespace '{namespace}': must contain only alphanumeric characters and hyphens")
+
+    if len(namespace) > 50:
+        raise ValueError(f"Namespace '{namespace}' exceeds maximum length of 50 characters")