moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/core/migration/backup_manager.py

@@ -0,0 +1,327 @@
+"""
+Backup management module for MoAI-ADK migrations
+
+Creates and manages backups during migration processes
+to ensure data safety and enable rollback.
+
+Supports backup of:
+- Legacy config.json (.moai/config.json) - pre-v0.24.0
+- Intermediate config.json (.moai/config/config.json) - v0.24.0
+- Section YAML files (.moai/config/sections/*.yaml) - v0.36.0+
+"""
+
+import json
+import logging
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class BackupManager:
+    """Manages backup creation and restoration for migrations"""
+
+    def __init__(self, project_root: Path):
+        """
+        Initialize backup manager
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = Path(project_root)
+        self.backup_base_dir = self.project_root / ".moai" / "backups"
+        self.backup_base_dir.mkdir(parents=True, exist_ok=True)
+
+    def create_backup(self, description: str = "migration") -> Path:
+        """
+        Create a full backup of configuration files
+
+        Args:
+            description: Description of this backup
+
+        Returns:
+            Path to the backup directory
+        """
+        # Create timestamped backup directory
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_dir = self.backup_base_dir / f"{description}_{timestamp}"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.info(f"Creating backup at {backup_dir}")
+
+        # Files to backup (supporting all config formats)
+        backup_targets = [
+            # Legacy config.json (pre-v0.24.0)
+            self.project_root / ".moai" / "config.json",
+            # Intermediate config.json (v0.24.0)
+            self.project_root / ".moai" / "config" / "config.json",
+            # Statusline configs
+            self.project_root / ".claude" / "statusline-config.yaml",
+            self.project_root / ".moai" / "config" / "statusline-config.yaml",
+        ]
+
+        # Add section YAML files (v0.36.0+)
+        sections_dir = self.project_root / ".moai" / "config" / "sections"
+        if sections_dir.exists():
+            for yaml_file in sections_dir.glob("*.yaml"):
+                backup_targets.append(yaml_file)
+
+        backed_up_files = []
+        backed_up_dirs = []
+
+        for target in backup_targets:
+            if target.exists():
+                # Preserve relative path structure in backup
+                rel_path = target.relative_to(self.project_root)
+                backup_path = backup_dir / rel_path
+
+                # Create parent directories
+                backup_path.parent.mkdir(parents=True, exist_ok=True)
+
+                # Copy file
+                shutil.copy2(target, backup_path)
+                backed_up_files.append(str(rel_path))
+                logger.debug(f"Backed up: {rel_path}")
+
+        # Track sections directory if it exists
+        if sections_dir.exists():
+            backed_up_dirs.append(str(sections_dir.relative_to(self.project_root)))
+
+        # Save backup metadata
+        metadata = {
+            "timestamp": timestamp,
+            "description": description,
+            "backed_up_files": backed_up_files,
+            "backed_up_dirs": backed_up_dirs,
+            "project_root": str(self.project_root),
+            "config_format": self._detect_config_format(),
+        }
+
+        metadata_path = backup_dir / "backup_metadata.json"
+        with open(metadata_path, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2, ensure_ascii=False)
+
+        logger.info(f"Backup created successfully: {backup_dir}")
+        return backup_dir
+
+    def _detect_config_format(self) -> str:
+        """
+        Detect the current configuration format
+
+        Returns:
+            One of: "section_yaml", "intermediate_json", "legacy_json", "none"
+        """
+        sections_dir = self.project_root / ".moai" / "config" / "sections"
+        system_yaml = sections_dir / "system.yaml"
+        intermediate_config = self.project_root / ".moai" / "config" / "config.json"
+        legacy_config = self.project_root / ".moai" / "config.json"
+
+        if sections_dir.exists() and system_yaml.exists():
+            return "section_yaml"
+        elif intermediate_config.exists():
+            return "intermediate_json"
+        elif legacy_config.exists():
+            return "legacy_json"
+        return "none"
+
+    def list_backups(self) -> List[Dict[str, str]]:
+        """
+        List all available backups
+
+        Returns:
+            List of backup information dictionaries
+        """
+        backups: List[Dict[str, Any]] = []
+
+        if not self.backup_base_dir.exists():
+            return backups
+
+        for backup_dir in sorted(self.backup_base_dir.iterdir(), reverse=True):
+            if backup_dir.is_dir():
+                metadata_path = backup_dir / "backup_metadata.json"
+                if metadata_path.exists():
+                    try:
+                        with open(metadata_path, "r", encoding="utf-8") as f:
+                            metadata = json.load(f)
+                            backups.append(
+                                {
+                                    "path": str(backup_dir),
+                                    "timestamp": metadata.get("timestamp", "unknown"),
+                                    "description": metadata.get("description", "unknown"),
+                                    "files": len(metadata.get("backed_up_files", [])),
+                                    "config_format": metadata.get("config_format", "unknown"),
+                                }
+                            )
+                    except Exception as e:
+                        logger.warning(f"Failed to read backup metadata: {e}")
+
+        return backups
+
+    def restore_backup(self, backup_path: Path) -> bool:
+        """
+        Restore files from a backup
+
+        Args:
+            backup_path: Path to the backup directory
+
+        Returns:
+            True if restore was successful, False otherwise
+        """
+        backup_path = Path(backup_path)
+
+        if not backup_path.exists():
+            logger.error(f"Backup directory not found: {backup_path}")
+            return False
+
+        metadata_path = backup_path / "backup_metadata.json"
+        if not metadata_path.exists():
+            logger.error(f"Backup metadata not found: {metadata_path}")
+            return False
+
+        try:
+            # Read metadata
+            with open(metadata_path, "r", encoding="utf-8") as f:
+                metadata = json.load(f)
+
+            logger.info(f"Restoring backup from {backup_path}")
+
+            # Restore each file
+            for rel_path in metadata.get("backed_up_files", []):
+                backup_file = backup_path / rel_path
+                target_file = self.project_root / rel_path
+
+                if backup_file.exists():
+                    # Create parent directories
+                    target_file.parent.mkdir(parents=True, exist_ok=True)
+
+                    # Restore file
+                    shutil.copy2(backup_file, target_file)
+                    logger.debug(f"Restored: {rel_path}")
+
+            logger.info("Backup restored successfully")
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to restore backup: {e}")
+            return False
+
+    def cleanup_old_backups(self, keep_count: int = 5) -> int:
+        """
+        Clean up old backups, keeping only the most recent ones
+
+        Args:
+            keep_count: Number of recent backups to keep
+
+        Returns:
+            Number of backups deleted
+        """
+        backups = self.list_backups()
+
+        if len(backups) <= keep_count:
+            return 0
+
+        deleted_count = 0
+        for backup_info in backups[keep_count:]:
+            backup_path = Path(backup_info["path"])
+            try:
+                shutil.rmtree(backup_path)
+                deleted_count += 1
+                logger.debug(f"Deleted old backup: {backup_path}")
+            except Exception as e:
+                logger.warning(f"Failed to delete backup {backup_path}: {e}")
+
+        logger.info(f"Cleaned up {deleted_count} old backups")
+        return deleted_count
+
+    def get_latest_backup(self) -> Optional[Path]:
+        """
+        Get the most recent backup
+
+        Returns:
+            Path to the latest backup directory, or None if no backups exist
+        """
+        backups = self.list_backups()
+        if backups:
+            return Path(backups[0]["path"])
+        return None
+
+    def create_full_project_backup(self, description: str = "pre-update-backup") -> Path:
+        """
+        Create a complete backup of entire project structure before update
+
+        Backs up:
+        - .claude/ (entire directory)
+        - .moai/ (entire directory)
+        - CLAUDE.md (file)
+        - .mcp.json (MCP server configuration) (v2.0.0)
+        - .lsp.json (LSP server configuration) (v2.0.0)
+        - .git-hooks/ (custom git hooks) (v2.0.0)
+
+        Args:
+            description: Description of this backup (default: "pre-update-backup")
+
+        Returns:
+            Path to the backup directory
+        """
+        # Create timestamped backup directory
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup_dir = self.project_root / ".moai-backups" / f"{description}_{timestamp}"
+        backup_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.info(f"Creating full project backup at {backup_dir}")
+
+        # Directories and files to backup
+        backup_targets = [
+            (self.project_root / ".claude", True),  # (path, is_directory)
+            (self.project_root / ".moai", True),
+            (self.project_root / "CLAUDE.md", False),
+            # MCP/LSP configuration (v2.0.0)
+            (self.project_root / ".mcp.json", False),  # MCP server configuration
+            (self.project_root / ".lsp.json", False),  # LSP server configuration
+            # Git hooks (v2.0.0)
+            (self.project_root / ".git-hooks", True),  # Custom git hooks
+        ]
+
+        backed_up_items = []
+
+        for target_path, is_dir in backup_targets:
+            if not target_path.exists():
+                continue
+
+            try:
+                rel_path = target_path.relative_to(self.project_root)
+                backup_path = backup_dir / rel_path
+
+                if is_dir:
+                    # Backup directory
+                    shutil.copytree(target_path, backup_path, dirs_exist_ok=True)
+                    backed_up_items.append(str(rel_path))
+                    logger.debug(f"Backed up directory: {rel_path}")
+                else:
+                    # Backup file
+                    backup_path.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(target_path, backup_path)
+                    backed_up_items.append(str(rel_path))
+                    logger.debug(f"Backed up file: {rel_path}")
+
+            except Exception as e:
+                logger.error(f"Failed to backup {target_path}: {e}")
+                raise
+
+        # Save backup metadata
+        metadata = {
+            "timestamp": timestamp,
+            "description": description,
+            "backed_up_items": backed_up_items,
+            "project_root": str(self.project_root),
+            "backup_type": "full_project",
+        }
+
+        metadata_path = backup_dir / "backup_metadata.json"
+        with open(metadata_path, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2, ensure_ascii=False)
+
+        logger.info(f"Full project backup created successfully: {backup_dir}")
+        return backup_dir

moai_adk/core/migration/custom_element_scanner.py

@@ -0,0 +1,358 @@
+"""Custom Element Scanner for MoAI-ADK
+
+This module provides functionality to scan for user-created custom elements
+(agents, commands, skills, hooks) that are not part of the official MoAI-ADK template
+installation. Unlike the existing detection functions that use template-based filtering,
+this scanner compares against fresh installation file lists to identify truly custom elements.
+
+The scanner is used during updates to provide users with a list of their custom
+elements that can be selectively restored from backup.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from moai_adk.core.migration.template_utils import (
+    _get_template_agent_names,
+    _get_template_command_names,
+    _get_template_hook_names,
+    _get_template_skill_names,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TemplateSkill:
+    """Represents a template skill directory."""
+
+    def __init__(self, name: str, path: Path, has_skill_md: bool, is_template: bool = False):
+        """Initialize a TemplateSkill.
+
+        Args:
+            name: Name of the skill directory
+            path: Path to the skill directory
+            has_skill_md: Whether the skill has a SKILL.md file
+            is_template: Whether this skill is part of the MoAI-ADK template
+        """
+        self.name = name
+        self.path = path
+        self.has_skill_md = has_skill_md
+        self.is_template = is_template
+
+
+class CustomElementScanner:
+    """Scanner for detecting user-created custom elements in MoAI-ADK projects.
+
+    This scanner identifies elements that are not part of the official MoAI-ADK
+    template by comparing against fresh installation file lists, providing a more
+    accurate detection of user-created content.
+    """
+
+    def __init__(self, project_path: Path):
+        """Initialize the scanner.
+
+        Args:
+            project_path: Path to the MoAI-ADK project directory
+        """
+        self.project_path = project_path
+        self.template_elements = self._get_template_elements()
+
+    def _get_template_elements(self) -> Dict[str, Set[str]]:
+        """Get template element names from fresh installation.
+
+        Returns:
+            Dictionary with element types as keys and sets of element names as values
+        """
+        return {
+            "skills": _get_template_skill_names(),
+            "commands": _get_template_command_names(),
+            "agents": _get_template_agent_names(),
+            "hooks": _get_template_hook_names(),
+        }
+
+    def scan_custom_elements(self) -> Dict[str, Any]:
+        """Scan for user-created custom elements only.
+
+        Scans the project directory for agents, commands, skills, and hooks that are
+        NOT part of the official MoAI-ADK template installation. Template elements
+        in moai/ subdirectories and moai-* prefixed skills are excluded because
+        they are automatically overwritten during updates.
+
+        Exclusions:
+            - agents/moai/* - Template agents (overwritten during update)
+            - commands/moai/* - Template commands (overwritten during update)
+            - skills/moai-* - Template skills (overwritten during update)
+            - hooks/moai/* - Template hooks (overwritten during update)
+
+        Returns:
+            Dictionary with element types as keys and lists of custom element paths as values
+
+        Example:
+            {
+                "agents": [Path(".claude/agents/custom/my-agent.md")],
+                "commands": [Path(".claude/commands/custom/my-command.md")],
+                "skills": [Path(".claude/skills/my-custom-skill/")],
+                "hooks": [Path(".claude/hooks/custom/my-hook.py")]
+            }
+        """
+        custom_elements: Dict[str, Any] = {}
+
+        # Scan agents (all files in .claude/agents/, excluding template files)
+        custom_elements["agents"] = self._scan_custom_agents()
+
+        # Scan commands (all files in .claude/commands/moai/, excluding template files)
+        custom_elements["commands"] = self._scan_custom_commands()
+
+        # Scan skills (all directories in .claude/skills/, excluding moai-* patterns)
+        custom_elements["skills"] = self._scan_custom_skills()
+
+        # Scan hooks (all files in .claude/hooks/moai/, excluding template files)
+        custom_elements["hooks"] = self._scan_custom_hooks()
+
+        return custom_elements
+
+    def _scan_custom_agents(self) -> List[Path]:
+        """Scan for custom agents only (excluding agents/moai/* template agents).
+
+        Template agents in the moai/ subdirectory are automatically overwritten
+        during updates. Only user-created custom agents should be available
+        for restoration.
+
+        Returns:
+            List of paths to custom agent files (excluding moai/ subdirectory)
+        """
+        agents_dir = self.project_path / ".claude" / "agents"
+
+        if not agents_dir.exists():
+            return []
+
+        custom_agents = []
+
+        # Scan all subdirectories under agents EXCEPT moai/
+        for item in agents_dir.iterdir():
+            if item.is_dir():
+                # Skip moai/ subdirectory - template agents should be overwritten
+                if item.name == "moai":
+                    continue
+                # Scan custom subdirectories
+                for file_path in item.rglob("*.md"):
+                    relative_path = file_path.relative_to(self.project_path)
+                    custom_agents.append(relative_path)
+            elif item.is_file() and item.suffix == ".md":
+                # Include root-level agent files (not in any subdirectory)
+                relative_path = item.relative_to(self.project_path)
+                custom_agents.append(relative_path)
+
+        return custom_agents
+
+    def _scan_custom_commands(self) -> List[Path]:
+        """Scan for custom commands only (excluding commands/moai/* template commands).
+
+        Template commands in the moai/ subdirectory are automatically overwritten
+        during updates. Only user-created custom commands should be available
+        for restoration.
+
+        Returns:
+            List of paths to custom command files (excluding moai/ subdirectory)
+        """
+        commands_dir = self.project_path / ".claude" / "commands"
+
+        if not commands_dir.exists():
+            return []
+
+        custom_commands = []
+
+        # Scan all subdirectories under commands EXCEPT moai/
+        # moai/ subdirectory contains template commands that should be overwritten
+        for subdir in commands_dir.iterdir():
+            if subdir.is_dir():
+                # Skip moai/ subdirectory - template commands should be overwritten
+                if subdir.name == "moai":
+                    continue
+                # Scan custom subdirectories
+                for file_path in subdir.rglob("*.md"):
+                    relative_path = file_path.relative_to(self.project_path)
+                    custom_commands.append(relative_path)
+            elif subdir.is_file() and subdir.suffix == ".md":
+                # Include root-level command files (not in any subdirectory)
+                relative_path = subdir.relative_to(self.project_path)
+                custom_commands.append(relative_path)
+
+        return custom_commands
+
+    def _scan_custom_skills(self) -> List[TemplateSkill]:
+        """Scan for custom skills only (excluding moai-* template skills).
+
+        Template skills (moai-* prefix) are automatically overwritten during updates.
+        Only user-created custom skills should be available for restoration.
+
+        Returns:
+            List of TemplateSkill objects representing custom skill directories only
+        """
+        skills_dir = self.project_path / ".claude" / "skills"
+
+        if not skills_dir.exists():
+            return []
+
+        custom_skills = []
+        template_skills = self.template_elements["skills"]
+
+        for skill_dir in skills_dir.iterdir():
+            if skill_dir.is_dir():
+                # Skip moai-* template skills - they should be overwritten, not restored
+                # Only include user-created custom skills (non-moai-* prefix)
+                if skill_dir.name.startswith("moai-"):
+                    continue
+
+                relative_path = skill_dir.relative_to(self.project_path)
+                is_template_skill = skill_dir.name in template_skills
+
+                custom_skills.append(
+                    TemplateSkill(
+                        name=skill_dir.name,
+                        path=relative_path,
+                        has_skill_md=(skill_dir / "SKILL.md").exists(),
+                        is_template=is_template_skill,
+                    )
+                )
+
+        return custom_skills
+
+    def _scan_custom_hooks(self) -> List[Path]:
+        """Scan for custom hooks only (excluding hooks/moai/* template hooks).
+
+        Template hooks in the moai/ subdirectory are automatically overwritten
+        during updates. Only user-created custom hooks should be available
+        for restoration.
+
+        Returns:
+            List of paths to custom hook files (excluding moai/ subdirectory)
+        """
+        hooks_dir = self.project_path / ".claude" / "hooks"
+
+        if not hooks_dir.exists():
+            return []
+
+        custom_hooks = []
+
+        # Scan all subdirectories under hooks EXCEPT moai/
+        # moai/ subdirectory contains template hooks that should be overwritten
+        for subdir in hooks_dir.iterdir():
+            if subdir.is_dir():
+                # Skip moai/ subdirectory - template hooks should be overwritten
+                if subdir.name == "moai":
+                    continue
+                # Scan custom subdirectories
+                for file_path in subdir.rglob("*.py"):
+                    relative_path = file_path.relative_to(self.project_path)
+                    custom_hooks.append(relative_path)
+            elif subdir.is_file() and subdir.suffix == ".py":
+                # Include root-level hook files (not in any subdirectory)
+                relative_path = subdir.relative_to(self.project_path)
+                custom_hooks.append(relative_path)
+
+        return custom_hooks
+
+    def get_custom_elements_display_list(self) -> List[Dict[str, Any]]:
+        """Get formatted list of custom elements for display.
+
+        Returns:
+            List of dictionaries containing element info for CLI display
+        """
+        custom_elements = self.scan_custom_elements()
+        display_list = []
+        index = 1
+
+        # Add agents
+        for agent_path in custom_elements["agents"]:
+            display_list.append(
+                {
+                    "index": index,
+                    "type": "agent",
+                    "name": agent_path.stem,
+                    "path": str(agent_path),
+                    "display_name": f"{agent_path.stem} (agent)",
+                }
+            )
+            index += 1
+
+        # Add commands
+        for command_path in custom_elements["commands"]:
+            display_list.append(
+                {
+                    "index": index,
+                    "type": "command",
+                    "name": command_path.stem,
+                    "path": str(command_path),
+                    "display_name": f"{command_path.stem} (command)",
+                }
+            )
+            index += 1
+
+        # Add skills
+        skills_list: List[TemplateSkill] = custom_elements["skills"]
+        for skill in skills_list:
+            skill_display_name = skill.name
+            # Add indicator for template vs custom skills
+            if hasattr(skill, "is_template") and skill.is_template:
+                skill_display_name = f"{skill.name} (template)"
+            else:
+                skill_display_name = f"{skill.name} (custom)"
+
+            display_list.append(
+                {
+                    "index": index,
+                    "type": "skill",
+                    "name": skill.name,
+                    "path": str(skill.path),
+                    "display_name": skill_display_name,
+                }
+            )
+            index += 1
+
+        # Add hooks
+        for hook_path in custom_elements["hooks"]:
+            display_list.append(
+                {
+                    "index": index,
+                    "type": "hook",
+                    "name": hook_path.stem,
+                    "path": str(hook_path),
+                    "display_name": f"{hook_path.stem} (hook)",
+                }
+            )
+            index += 1
+
+        return display_list
+
+    def get_element_count(self) -> int:
+        """Get total count of custom elements.
+
+        Returns:
+            Total number of custom elements found
+        """
+        custom_elements = self.scan_custom_elements()
+        return (
+            len(custom_elements["agents"])
+            + len(custom_elements["commands"])
+            + len(custom_elements["skills"])
+            + len(custom_elements["hooks"])
+        )
+
+
+def create_custom_element_scanner(project_path: str | Path) -> CustomElementScanner:
+    """Factory function to create a CustomElementScanner.
+
+    Args:
+        project_path: Path to the MoAI-ADK project directory
+
+    Returns:
+        Configured CustomElementScanner instance
+
+    Example:
+        >>> scanner = create_custom_element_scanner("/path/to/project")
+        >>> elements = scanner.scan_custom_elements()
+        >>> print(f"Found {len(elements['agents']) custom agents")
+    """
+    return CustomElementScanner(Path(project_path).resolve())