moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/core/migration/alfred_to_moai_migrator.py

@@ -0,0 +1,389 @@
+"""
+Alfred to Moai folder structure migration for MoAI-ADK
+
+Handles automatic migration from legacy alfred/ folders to new moai/ structure.
+- Creates backup before migration
+- Installs fresh moai/ templates from package
+- Deletes alfred/ folders
+- Updates settings.json Hook paths
+- Records migration status in config.json (legacy) or config.yaml
+- Provides automatic rollback on failure
+
+BACKWARD COMPATIBILITY NOTE:
+- This migration tool maintains compatibility with legacy config.json format
+- New projects use modular section-based YAML configs (.moai/config/sections/*.yaml)
+- Migration status is recorded in whichever config format the project uses
+- Both formats are supported during migration process
+"""
+
+import json
+import logging
+import shutil
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from .backup_manager import BackupManager
+
+logger = logging.getLogger(__name__)
+
+
+class AlfredToMoaiMigrator:
+    """Handles automatic migration from Alfred to Moai folder structure"""
+
+    def __init__(self, project_root: Path):
+        """
+        Initialize Alfred to Moai migrator
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = Path(project_root)
+        self.claude_root = self.project_root / ".claude"
+        self.config_path = self.project_root / ".moai" / "config" / "config.json"
+        self.settings_path = self.claude_root / "settings.json"
+        self.backup_manager = BackupManager(project_root)
+
+        # Define folder paths
+        self.alfred_folders = {
+            "commands": self.claude_root / "commands" / "alfred",
+            "agents": self.claude_root / "agents" / "alfred",
+            "hooks": self.claude_root / "hooks" / "alfred",
+        }
+
+        self.moai_folders = {
+            "commands": self.claude_root / "commands" / "moai",
+            "agents": self.claude_root / "agents" / "moai",
+            "hooks": self.claude_root / "hooks" / "moai",
+        }
+
+    def _load_config(self) -> dict:
+        """
+        Load config.json
+
+        Returns:
+            Dictionary from config.json, or empty dict if not found
+        """
+        if not self.config_path.exists():
+            return {}
+
+        try:
+            return json.loads(self.config_path.read_text(encoding="utf-8"))
+        except Exception as e:
+            logger.warning(f"Failed to load config.json: {e}")
+            return {}
+
+    def _save_config(self, config: dict) -> None:
+        """
+        Save config.json
+
+        Args:
+            config: Configuration dictionary to save
+
+        Raises:
+            Exception: If save fails
+        """
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        self.config_path.write_text(json.dumps(config, indent=2, ensure_ascii=False))
+
+    def needs_migration(self) -> bool:
+        """
+        Check if Alfred to Moai migration is needed
+
+        Returns:
+            True if migration is needed, False otherwise
+        """
+        # Check if already migrated
+        try:
+            config = self._load_config()
+            migration_state = config.get("migration", {}).get("alfred_to_moai", {})
+            if migration_state.get("migrated"):
+                logger.info("ℹ️  Alfred → Moai migration already completed")
+                if migration_state.get("timestamp"):
+                    logger.info(f"Timestamp: {migration_state['timestamp']}")
+                return False
+        except Exception as e:
+            logger.debug(f"Config check error: {e}")
+
+        # Check if any alfred folder exists
+        has_alfred = any(folder.exists() for folder in self.alfred_folders.values())
+
+        if has_alfred:
+            detected = [name for name, folder in self.alfred_folders.items() if folder.exists()]
+            logger.debug(f"Alfred folders detected: {', '.join(detected)}")
+
+        return has_alfred
+
+    def execute_migration(self, backup_path: Optional[Path] = None) -> bool:
+        """
+        Execute Alfred to Moai migration
+
+        Args:
+            backup_path: Path to use for backup (if None, creates new backup)
+
+        Returns:
+            True if migration successful, False otherwise
+        """
+        try:
+            logger.info("\n[1/5] Backing up project...")
+
+            # Step 1: Create or use existing backup
+            if backup_path is None:
+                try:
+                    backup_path = self.backup_manager.create_backup("alfred_to_moai_migration")
+                    logger.info(f"✅ Backup completed: {backup_path}")
+                except Exception as e:
+                    logger.error("❌ Error: Backup failed")
+                    logger.error(f"Cause: {str(e)}")
+                    return False
+            else:
+                logger.info(f"✅ Using existing backup: {backup_path}")
+
+            # Step 2: Detect alfred folders
+            logger.info("\n[2/5] Alfred folders detected:")
+            alfred_detected = {name: folder for name, folder in self.alfred_folders.items() if folder.exists()}
+
+            if not alfred_detected:
+                logger.warning("No Alfred folders found - skipping migration")
+                return True
+
+            logger.info(", ".join(alfred_detected.keys()))
+
+            # Step 3: Verify moai folders exist (should be created in Phase 1)
+            logger.info("\n[3/5] Verifying Moai template installation...")
+            missing_moai = [name for name, folder in self.moai_folders.items() if not folder.exists()]
+
+            if missing_moai:
+                logger.error(f"❌ Missing Moai folders: {', '.join(missing_moai)}")
+                logger.error("Phase 1 implementation required first (package template moai structure)")
+                self._rollback_migration(backup_path)
+                return False
+
+            logger.info("✅ Moai templates installed")
+
+            # Step 4: Update settings.json hooks
+            logger.info("\n[4/5] Updating paths...")
+            try:
+                self._update_settings_json_hooks()
+                logger.info("✅ settings.json Hook paths updated")
+            except Exception as e:
+                logger.error("❌ Error: Failed to update settings.json")
+                logger.error(f"Cause: {str(e)}")
+                self._rollback_migration(backup_path)
+                return False
+
+            # Step 5: Delete alfred folders
+            logger.info("\n[5/5] Cleaning up...")
+            try:
+                self._delete_alfred_folders(alfred_detected)
+                logger.info("✅ Alfred folders deleted")
+            except Exception as e:
+                logger.error("❌ Error: Failed to delete Alfred folders")
+                logger.error(f"Cause: {str(e)}")
+                self._rollback_migration(backup_path)
+                return False
+
+            # Step 6: Verify migration
+            logger.info("\n[6/6] Verifying migration...")
+            if not self._verify_migration():
+                logger.error("❌ Migration verification failed")
+                self._rollback_migration(backup_path)
+                return False
+
+            logger.info("✅ Migration verification passed")
+
+            # Step 7: Record migration status
+            logger.info("\nRecording migration status...")
+            try:
+                self._record_migration_state(backup_path, len(alfred_detected))
+                logger.info("✅ Migration status recorded")
+            except Exception as e:
+                logger.warning(f"⚠️  Failed to record status: {str(e)}")
+                # Don't rollback for this, migration was successful
+
+            logger.info("\n✅ Alfred → Moai migration completed!")
+            return True
+
+        except Exception as e:
+            logger.error(f"\n❌ Unexpected error: {str(e)}")
+            if backup_path:
+                self._rollback_migration(backup_path)
+            return False
+
+    def _delete_alfred_folders(self, alfred_detected: dict) -> None:
+        """
+        Delete Alfred folders
+
+        Args:
+            alfred_detected: Dictionary of detected alfred folders
+
+        Raises:
+            Exception: If deletion fails
+        """
+        for name, folder in alfred_detected.items():
+            if folder.exists():
+                try:
+                    shutil.rmtree(folder)
+                    logger.debug(f"Deleted: {folder}")
+                except Exception as e:
+                    raise Exception(f"Failed to delete {name} folder: {str(e)}")
+
+    def _update_settings_json_hooks(self) -> None:
+        """
+        Update settings.json to replace alfred paths with moai paths
+
+        Raises:
+            Exception: If update fails
+        """
+        if not self.settings_path.exists():
+            logger.warning(f"settings.json file missing: {self.settings_path}")
+            return
+
+        try:
+            # Read settings.json
+            with open(self.settings_path, "r", encoding="utf-8") as f:
+                settings_content = f.read()
+
+            # Replace all alfred references with moai
+            # Pattern: .claude/hooks/alfred/ → .claude/hooks/moai/
+            updated_content = settings_content.replace(".claude/hooks/alfred/", ".claude/hooks/moai/")
+            updated_content = updated_content.replace(".claude/commands/alfred/", ".claude/commands/moai/")
+            updated_content = updated_content.replace(".claude/agents/alfred/", ".claude/agents/moai/")
+
+            # Write back to file
+            with open(self.settings_path, "w", encoding="utf-8") as f:
+                f.write(updated_content)
+
+            # Verify JSON validity
+            with open(self.settings_path, "r", encoding="utf-8") as f:
+                json.load(f)  # This will raise if JSON is invalid
+
+            logger.debug("settings.json update and verification completed")
+
+        except json.JSONDecodeError as e:
+            raise Exception(f"settings.json JSON format error: {str(e)}")
+        except Exception as e:
+            raise Exception(f"Failed to update settings.json: {str(e)}")
+
+    def _verify_migration(self) -> bool:
+        """
+        Verify migration was successful
+
+        Returns:
+            True if migration is valid, False otherwise
+        """
+        # Check moai folders exist
+        for name, folder in self.moai_folders.items():
+            if not folder.exists():
+                logger.error(f"❌ Missing Moai {name} folder: {folder}")
+                return False
+
+        # Check alfred folders are deleted
+        for name, folder in self.alfred_folders.items():
+            if folder.exists():
+                logger.warning(f"⚠️  Alfred {name} folder still exists: {folder}")
+                return False
+
+        # Check settings.json hooks paths (ignore pattern matching strings like "Bash(alfred:*)")
+        if self.settings_path.exists():
+            try:
+                with open(self.settings_path, "r", encoding="utf-8") as f:
+                    settings_content = f.read()
+
+                # Only check for hooks/alfred paths, not pattern strings
+                if (
+                    ".claude/hooks/alfred/" in settings_content
+                    or ".claude/commands/alfred/" in settings_content
+                    or ".claude/agents/alfred/" in settings_content
+                ):
+                    logger.error("❌ settings.json still contains alfred hook paths")
+                    return False
+
+                if "moai" not in settings_content.lower():
+                    logger.warning("⚠️  No moai references in settings.json")
+
+            except Exception as e:
+                logger.error(f"❌ settings.json verification failed: {str(e)}")
+                return False
+
+        logger.debug("Migration verification completed")
+        return True
+
+    def _record_migration_state(self, backup_path: Path, folders_count: int) -> None:
+        """
+        Record migration state in config.json
+
+        Args:
+            backup_path: Path to the backup
+            folders_count: Number of folders migrated
+
+        Raises:
+            Exception: If recording fails
+        """
+        try:
+            config = self._load_config()
+
+            # Initialize migration section if not exists
+            if "migration" not in config:
+                config["migration"] = {}
+
+            config["migration"]["alfred_to_moai"] = {
+                "migrated": True,
+                "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                "folders_installed": 3,  # commands, agents, hooks
+                "folders_removed": folders_count,
+                "backup_path": str(backup_path),
+                "package_version": self._get_package_version(),
+            }
+
+            self._save_config(config)
+            logger.debug("Migration state recorded in config.json")
+
+        except Exception as e:
+            raise Exception(f"Migration state recording failed: {str(e)}")
+
+    def _rollback_migration(self, backup_path: Path) -> None:
+        """
+        Rollback migration from backup
+
+        Args:
+            backup_path: Path to the backup to restore from
+        """
+        try:
+            logger.info("\n🔄 Starting automatic rollback...")
+            logger.info("[1/3] Restoring project...")
+
+            # Restore from backup
+            self.backup_manager.restore_backup(backup_path)
+
+            logger.info("✅ Project restored")
+            logger.info("[2/3] Resetting migration state...")
+
+            # Clear migration state in config
+            try:
+                config = self._load_config()
+                if "migration" in config and "alfred_to_moai" in config["migration"]:
+                    del config["migration"]["alfred_to_moai"]
+                    self._save_config(config)
+            except Exception as e:
+                logger.warning(f"⚠️  Failed to reset state: {str(e)}")
+
+            logger.info("✅ Rollback completed")
+            logger.info("💡 Tip: Run `moai-adk update` again after resolving the error")
+
+        except Exception as e:
+            logger.error(f"\n❌ Rollback failed: {str(e)}")
+            logger.error(f"⚠️  Manual recovery required: Please restore manually from backup: {backup_path}")
+
+    def _get_package_version(self) -> str:
+        """
+        Get current package version
+
+        Returns:
+            Version string
+        """
+        try:
+            config = self._load_config()
+            return config.get("moai", {}).get("version", "unknown")
+        except Exception:
+            return "unknown"

moai_adk/core/migration/backup_manager.py

@@ -3,6 +3,11 @@ 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
@@ -10,7 +15,7 @@ import logging
 import shutil
 from datetime import datetime
 from pathlib import Path
-from typing import Dict, List, Optional
+from typing import Any, Dict, List, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -46,15 +51,25 @@ class BackupManager:
 
         logger.info(f"Creating backup at {backup_dir}")
 
-        # Files to backup
+        # 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():
@@ -70,21 +85,47 @@ class BackupManager:
                 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") as f:
-            json.dump(metadata, f, indent=2)
+        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}")
+        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
@@ -92,7 +133,7 @@ class BackupManager:
         Returns:
             List of backup information dictionaries
         """
-        backups = []
+        backups: List[Dict[str, Any]] = []
 
         if not self.backup_base_dir.exists():
             return backups
@@ -102,16 +143,15 @@ class BackupManager:
                 metadata_path = backup_dir / "backup_metadata.json"
                 if metadata_path.exists():
                     try:
-                        with open(metadata_path, "r") as f:
+                        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"
-                                    ),
+                                    "description": metadata.get("description", "unknown"),
                                     "files": len(metadata.get("backed_up_files", [])),
+                                    "config_format": metadata.get("config_format", "unknown"),
                                 }
                             )
                     except Exception as e:
@@ -142,7 +182,7 @@ class BackupManager:
 
         try:
             # Read metadata
-            with open(metadata_path, "r") as f:
+            with open(metadata_path, "r", encoding="utf-8") as f:
                 metadata = json.load(f)
 
             logger.info(f"Restoring backup from {backup_path}")
@@ -160,7 +200,7 @@ class BackupManager:
                     shutil.copy2(backup_file, target_file)
                     logger.debug(f"Restored: {rel_path}")
 
-            logger.info("✅ Backup restored successfully")
+            logger.info("Backup restored successfully")
             return True
 
         except Exception as e:
@@ -206,3 +246,82 @@ class BackupManager:
         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