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

moai_adk/core/migration/version_migrator.py

@@ -0,0 +1,228 @@
+"""
+Main version migration orchestrator for MoAI-ADK
+
+Coordinates version detection, backup creation, file migration,
+and cleanup processes for automatic project upgrades.
+"""
+
+import logging
+from pathlib import Path
+from typing import Dict
+
+from .backup_manager import BackupManager
+from .file_migrator import FileMigrator
+from .version_detector import VersionDetector
+
+logger = logging.getLogger(__name__)
+
+
+class VersionMigrator:
+    """Main migration orchestrator for MoAI-ADK version upgrades"""
+
+    def __init__(self, project_root: Path):
+        """
+        Initialize version migrator
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = Path(project_root)
+        self.detector = VersionDetector(project_root)
+        self.backup_manager = BackupManager(project_root)
+        self.file_migrator = FileMigrator(project_root)
+
+    def detect_version(self) -> str:
+        """
+        Detect current project version
+
+        Returns:
+            Version string (e.g., "0.23.0", "0.24.0+", "unknown")
+        """
+        return self.detector.detect_version()
+
+    def needs_migration(self) -> bool:
+        """
+        Check if project needs migration
+
+        Returns:
+            True if migration is needed, False otherwise
+        """
+        return self.detector.needs_migration()
+
+    def get_migration_info(self) -> Dict[str, any]:
+        """
+        Get detailed migration information
+
+        Returns:
+            Dictionary with migration details
+        """
+        version = self.detector.detect_version()
+        needs_migration = self.detector.needs_migration()
+        plan = self.detector.get_migration_plan()
+
+        return {
+            "current_version": version,
+            "needs_migration": needs_migration,
+            "target_version": "0.24.0" if needs_migration else version,
+            "migration_plan": plan,
+            "file_count": len(plan.get("move", [])),
+        }
+
+    def migrate_to_v024(self, dry_run: bool = False, cleanup: bool = True) -> bool:
+        """
+        Migrate project from v0.23.0 to v0.24.0
+
+        Args:
+            dry_run: If True, only show what would be done
+            cleanup: If True, remove old files after successful migration
+
+        Returns:
+            True if migration was successful, False otherwise
+        """
+        if not self.needs_migration():
+            logger.info("✅ Project is already up to date")
+            return True
+
+        if dry_run:
+            logger.info("🔍 DRY RUN MODE - No changes will be made")
+            self._show_migration_plan()
+            return True
+
+        logger.info("🚀 Starting migration to v0.24.0...")
+
+        try:
+            # Step 1: Create backup
+            logger.info("\n💾 Step 1: Creating backup...")
+            backup_path = self.backup_manager.create_backup("pre_v024_migration")
+            logger.info(f"✅ Backup created: {backup_path}")
+
+            # Step 2: Get migration plan
+            logger.info("\n📋 Step 2: Analyzing migration requirements...")
+            plan = self.detector.get_migration_plan()
+            logger.info(f"   - {len(plan['create'])} directories to create")
+            logger.info(f"   - {len(plan['move'])} files to move")
+
+            # Step 3: Execute migration
+            logger.info("\n🔄 Step 3: Executing migration...")
+            results = self.file_migrator.execute_migration_plan(plan)
+
+            if not results["success"]:
+                logger.error("❌ Migration failed with errors:")
+                for error in results["errors"]:
+                    logger.error(f"   - {error}")
+                logger.info(f"\n🔙 Rolling back using backup: {backup_path}")
+                self.backup_manager.restore_backup(backup_path)
+                return False
+
+            logger.info("✅ Migration completed successfully!")
+            logger.info(f"   - {results['created_dirs']} directories created")
+            logger.info(f"   - {results['moved_files']} files moved")
+
+            # Step 4: Verify migration
+            logger.info("\n🔍 Step 4: Verifying migration...")
+            if self._verify_migration():
+                logger.info("✅ Verification passed")
+
+                # Step 5: Cleanup (optional)
+                if cleanup:
+                    logger.info("\n🗑️  Step 5: Cleaning up old files...")
+                    cleaned = self.file_migrator.cleanup_old_files(plan["cleanup"])
+                    logger.info(f"✅ Cleaned up {cleaned} old files")
+                else:
+                    logger.info("\n⏭️  Step 5: Skipped cleanup (old files preserved)")
+
+                logger.info("\n✨ Migration to v0.24.0 completed successfully!")
+                return True
+            else:
+                logger.error("❌ Verification failed")
+                logger.info(f"🔙 Rolling back using backup: {backup_path}")
+                self.backup_manager.restore_backup(backup_path)
+                return False
+
+        except Exception as e:
+            logger.error(f"❌ Migration failed with exception: {e}")
+            logger.info("🔙 Attempting rollback...")
+            try:
+                latest_backup = self.backup_manager.get_latest_backup()
+                if latest_backup:
+                    self.backup_manager.restore_backup(latest_backup)
+                    logger.info("✅ Rollback completed")
+            except Exception as rollback_error:
+                logger.error(f"❌ Rollback failed: {rollback_error}")
+            return False
+
+    def _show_migration_plan(self) -> None:
+        """Display migration plan without executing"""
+        plan = self.detector.get_migration_plan()
+
+        print("\n📋 Migration Plan:")
+        print("\n📁 Directories to create:")
+        for directory in plan.get("create", []):
+            print(f"   + {directory}")
+
+        print("\n📄 Files to move:")
+        for move_op in plan.get("move", []):
+            print(f"   • {move_op['description']}")
+            print(f"     {move_op['from']} → {move_op['to']}")
+
+        print("\n🗑️  Files to cleanup after migration:")
+        for cleanup_file in plan.get("cleanup", []):
+            print(f"   - {cleanup_file}")
+
+    def _verify_migration(self) -> bool:
+        """
+        Verify migration was successful
+
+        Returns:
+            True if verification passed
+        """
+        # Check that new config exists
+        new_config = self.project_root / ".moai" / "config" / "config.json"
+        if not new_config.exists():
+            logger.error("Verification failed: new config.json not found")
+            return False
+
+        # Check that new config directory exists
+        config_dir = self.project_root / ".moai" / "config"
+        if not config_dir.is_dir():
+            logger.error("Verification failed: config directory not found")
+            return False
+
+        logger.debug("All verification checks passed")
+        return True
+
+    def check_status(self) -> Dict[str, any]:
+        """
+        Check migration status and return detailed information
+
+        Returns:
+            Dictionary with status information
+        """
+        version_info = self.detector.get_version_info()
+        migration_info = self.get_migration_info()
+        backups = self.backup_manager.list_backups()
+
+        return {
+            "version": version_info,
+            "migration": migration_info,
+            "backups": {
+                "count": len(backups),
+                "latest": backups[0] if backups else None,
+            },
+        }
+
+    def rollback_to_latest_backup(self) -> bool:
+        """
+        Rollback to the most recent backup
+
+        Returns:
+            True if rollback was successful
+        """
+        latest_backup = self.backup_manager.get_latest_backup()
+
+        if not latest_backup:
+            logger.error("No backup found to rollback to")
+            return False
+
+        logger.info(f"🔙 Rolling back to backup: {latest_backup}")
+        return self.backup_manager.restore_backup(latest_backup)

moai_adk/core/performance/__init__.py

@@ -0,0 +1,6 @@
+"""
+Performance optimization module for MoAI-ADK.
+
+This module provides parallel processing capabilities and caching systems
+to improve performance of various operations.
+"""

moai_adk/core/performance/cache_system.py

@@ -0,0 +1,318 @@
+"""
+Cache System
+
+Provides persistent caching capabilities with TTL support for improved performance.
+"""
+
+import json
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+
+class CacheSystem:
+    """
+    A persistent cache system with TTL support.
+
+    This class provides file-based caching with support for time-to-live,
+    multiple operations, persistence across instances, and thread safety.
+    """
+
+    def __init__(self, cache_dir: Optional[str] = None, auto_cleanup: bool = True):
+        """
+        Initialize the cache system.
+
+        Args:
+            cache_dir: Directory to store cache files. If None, uses default temp directory.
+            auto_cleanup: Whether to automatically clean up expired files on operations
+        """
+        self.auto_cleanup = auto_cleanup
+
+        if cache_dir is None:
+            import tempfile
+
+            self.cache_dir = os.path.join(tempfile.gettempdir(), "moai_adk_cache")
+        else:
+            self.cache_dir = cache_dir
+
+        # Cache file extension
+        self.file_extension = ".cache"
+
+        # Create cache directory if it doesn't exist
+        self._ensure_cache_dir()
+
+    def _ensure_cache_dir(self) -> None:
+        """Ensure cache directory exists."""
+        try:
+            os.makedirs(self.cache_dir, exist_ok=True)
+        except OSError as e:
+            raise OSError(f"Failed to create cache directory {self.cache_dir}: {e}")
+
+    def _validate_key(self, key: str) -> str:
+        """
+        Validate and sanitize cache key.
+
+        Args:
+            key: Raw cache key
+
+        Returns:
+            Sanitized key suitable for filename
+        """
+        if not isinstance(key, str):
+            raise TypeError("Cache key must be a string")
+
+        if not key or key.isspace():
+            raise ValueError("Cache key cannot be empty")
+
+        # Sanitize key for safe filename usage
+        safe_key = key.replace("/", "_").replace("\\", "_")
+        if safe_key != key:
+            return safe_key
+
+        return key
+
+    def _get_file_path(self, key: str) -> str:
+        """Get file path for a given cache key."""
+        safe_key = self._validate_key(key)
+        return os.path.join(self.cache_dir, f"{safe_key}{self.file_extension}")
+
+    def _is_expired(self, data: Dict[str, Any]) -> bool:
+        """Check if cache data is expired."""
+        if "expires_at" not in data:
+            return False
+
+        return time.time() > data["expires_at"]
+
+    def _cleanup_expired_files(self) -> None:
+        """Remove expired cache files."""
+        current_time = time.time()
+        for file_name in os.listdir(self.cache_dir):
+            if file_name.endswith(self.file_extension):
+                file_path = os.path.join(self.cache_dir, file_name)
+                try:
+                    with open(file_path, "r") as f:
+                        data = json.load(f)
+
+                    if self._is_expired(data):
+                        os.remove(file_path)
+                except (json.JSONDecodeError, KeyError, OSError):
+                    # Remove corrupted files too
+                    try:
+                        os.remove(file_path)
+                    except OSError:
+                        pass
+
+    def _write_data(self, file_path: str, data: Dict[str, Any]) -> None:
+        """Write data to file with error handling."""
+        try:
+            with open(file_path, "w") as f:
+                json.dump(data, f, indent=2)
+        except (OSError, TypeError) as e:
+            raise OSError(f"Failed to write cache file {file_path}: {e}")
+
+    def _read_data(self, file_path: str) -> Optional[Dict[str, Any]]:
+        """Read data from file with error handling."""
+        if not os.path.exists(file_path):
+            return None
+
+        try:
+            with open(file_path, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            # File is corrupted, remove it
+            try:
+                os.remove(file_path)
+            except OSError:
+                pass
+            return None
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """
+        Set a value in the cache.
+
+        Args:
+            key: Cache key
+            value: Value to cache (must be JSON serializable)
+            ttl: Time to live in seconds (optional)
+
+        Raises:
+            TypeError: If value is not JSON serializable
+            OSError: If file operations fail
+        """
+        # Validate JSON serializability
+        try:
+            json.dumps(value)
+        except (TypeError, ValueError) as e:
+            raise TypeError(f"Cache value must be JSON serializable: {e}")
+
+        data = {"value": value, "created_at": time.time()}
+
+        if ttl is not None:
+            if not isinstance(ttl, (int, float)) or ttl < 0:
+                raise ValueError("TTL must be a positive number")
+            data["expires_at"] = data["created_at"] + ttl
+
+        file_path = self._get_file_path(key)
+        self._write_data(file_path, data)
+
+        # Auto-cleanup if enabled
+        if self.auto_cleanup:
+            self._cleanup_expired_files()
+
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get a value from the cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached value or None if not found or expired
+        """
+        file_path = self._get_file_path(key)
+        data = self._read_data(file_path)
+
+        if data is None:
+            return None
+
+        # Check expiration
+        if self._is_expired(data):
+            try:
+                os.remove(file_path)
+            except OSError:
+                pass
+            return None
+
+        return data["value"]
+
+    def delete(self, key: str) -> bool:
+        """
+        Delete a value from the cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if file was deleted, False if it didn't exist
+        """
+        file_path = self._get_file_path(key)
+        try:
+            os.remove(file_path)
+            return True
+        except OSError:
+            return False
+
+    def clear(self) -> int:
+        """
+        Clear all values from the cache.
+
+        Returns:
+            Number of files removed
+        """
+        count = 0
+        for file_name in os.listdir(self.cache_dir):
+            if file_name.endswith(self.file_extension):
+                file_path = os.path.join(self.cache_dir, file_name)
+                try:
+                    os.remove(file_path)
+                    count += 1
+                except OSError:
+                    continue
+        return count
+
+    def exists(self, key: str) -> bool:
+        """
+        Check if a key exists in the cache.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            True if key exists and is not expired, False otherwise
+        """
+        return self.get(key) is not None
+
+    def size(self) -> int:
+        """
+        Get the number of items in the cache.
+
+        Returns:
+            Number of non-expired cache items
+        """
+        count = 0
+        for file_name in os.listdir(self.cache_dir):
+            if file_name.endswith(self.file_extension):
+                file_path = os.path.join(self.cache_dir, file_name)
+                key = file_name[: -len(self.file_extension)]  # Remove extension
+
+                if self.exists(key):
+                    count += 1
+        return count
+
+    def set_if_not_exists(
+        self, key: str, value: Any, ttl: Optional[float] = None
+    ) -> bool:
+        """
+        Set a value only if the key doesn't exist.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+            ttl: Time to live in seconds (optional)
+
+        Returns:
+            True if value was set, False if key already existed
+        """
+        if self.exists(key):
+            return False
+
+        self.set(key, value, ttl)
+        return True
+
+    def get_multiple(self, keys: List[str]) -> Dict[str, Optional[Any]]:
+        """
+        Get multiple values from the cache.
+
+        Args:
+            keys: List of cache keys
+
+        Returns:
+            Dictionary mapping keys to values (or None)
+        """
+        if not isinstance(keys, list):
+            raise TypeError("keys must be a list")
+
+        result = {}
+        for key in keys:
+            if not isinstance(key, str):
+                raise TypeError("All keys must be strings")
+            result[key] = self.get(key)
+        return result
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics.
+
+        Returns:
+            Dictionary with cache statistics
+        """
+        total_files = 0
+        expired_files = 0
+        current_time = time.time()
+
+        for file_name in os.listdir(self.cache_dir):
+            if file_name.endswith(self.file_extension):
+                total_files += 1
+                file_path = os.path.join(self.cache_dir, file_name)
+                data = self._read_data(file_path)
+
+                if data and self._is_expired(data):
+                    expired_files += 1
+
+        return {
+            "total_files": total_files,
+            "expired_files": expired_files,
+            "valid_files": total_files - expired_files,
+            "cache_directory": self.cache_dir,
+            "auto_cleanup_enabled": self.auto_cleanup,
+        }

moai_adk/core/performance/parallel_processor.py

@@ -0,0 +1,116 @@
+"""
+Parallel Processing Core
+
+Provides efficient parallel processing capabilities for concurrent task execution.
+"""
+
+import asyncio
+from typing import Any, Callable, Coroutine, Dict, List, Optional, Union
+
+
+class ParallelProcessor:
+    """
+    A parallel processor for executing tasks concurrently with configurable limits.
+
+    This class provides a high-level interface for running multiple async tasks
+    in parallel with optional progress tracking and error handling.
+    """
+
+    def __init__(self, max_workers: Optional[int] = None):
+        """
+        Initialize the parallel processor.
+
+        Args:
+            max_workers: Maximum number of concurrent tasks. If None, defaults to CPU count.
+        """
+        self.max_workers = max_workers
+
+    async def process_tasks(
+        self,
+        tasks: List[Callable],
+        progress_callback: Optional[Callable[[int, int], None]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Process multiple tasks concurrently.
+
+        Args:
+            tasks: List of async task functions or coroutines to execute
+            progress_callback: Optional callback for progress updates (completed, total)
+
+        Returns:
+            List of results from all completed tasks in the same order as input
+
+        Raises:
+            Exception: If any task raises an exception
+        """
+        if not tasks:
+            return []
+
+        results = []
+        completed_count = 0
+
+        # Validate input
+        self._validate_tasks(tasks)
+
+        # Initialize progress tracking
+        self._update_progress(progress_callback, completed_count, len(tasks))
+
+        # Process tasks concurrently
+        for task in tasks:
+            try:
+                # Get coroutine from task
+                coroutine = self._get_coroutine(task)
+
+                # Execute the task and get result
+                result = await coroutine
+                results.append(result)
+                completed_count += 1
+
+                # Update progress
+                self._update_progress(progress_callback, completed_count, len(tasks))
+
+            except Exception as e:
+                # Add context to the exception
+                raise type(e)(f"Task failed: {str(e)}") from e
+
+        return results
+
+    def _validate_tasks(self, tasks: List[Callable]) -> None:
+        """Validate that all tasks are callable or coroutines."""
+        if not isinstance(tasks, list):
+            raise TypeError("tasks must be a list")
+
+        for i, task in enumerate(tasks):
+            if not callable(task) and not asyncio.iscoroutine(task):
+                raise TypeError(f"Task at index {i} is not callable or a coroutine")
+
+    def _get_coroutine(self, task: Union[Callable, Coroutine]) -> Coroutine:
+        """Extract coroutine from task function or return coroutine directly."""
+        if asyncio.iscoroutine(task):
+            return task
+
+        if callable(task):
+            try:
+                result = task()
+                if asyncio.iscoroutine(result):
+                    return result
+                else:
+                    raise TypeError("Task function must return a coroutine")
+            except Exception as e:
+                raise TypeError(f"Failed to execute task function: {str(e)}")
+
+        raise TypeError(f"Task must be callable or a coroutine, got {type(task)}")
+
+    def _update_progress(
+        self,
+        progress_callback: Optional[Callable[[int, int], None]],
+        completed: int,
+        total: int,
+    ) -> None:
+        """Update progress callback if provided."""
+        if progress_callback is not None:
+            try:
+                progress_callback(completed, total)
+            except Exception as e:
+                # Log progress callback error but don't fail the entire process
+                print(f"Warning: Progress callback failed: {str(e)}")

moai_adk/core/project/__init__.py

@@ -1,2 +1 @@
-# @CODE:PY314-001 | SPEC: SPEC-PY314-001.md | TEST: tests/unit/test_foundation.py
 """Project module: initialization and management"""

moai_adk/core/project/backup_utils.py

@@ -1,4 +1,3 @@
-# @CODE:INIT-003:BACKUP | SPEC: .moai/specs/SPEC-INIT-003/spec.md | TEST: tests/unit/test_backup_utils.py
 """Backup utility module (SPEC-INIT-003 v0.3.0)
 
 Selective backup strategy:
@@ -10,7 +9,7 @@ from pathlib import Path
 
 # Backup targets (OR condition - back up when any exist)
 BACKUP_TARGETS = [
-    ".moai/config.json",
+    ".moai/config/config.json",
     ".moai/project/",
     ".moai/memory/",
     ".claude/",
@@ -58,8 +57,6 @@ def get_backup_targets(project_path: Path) -> list[str]:
     return targets
 
 
-
-
 def is_protected_path(rel_path: Path) -> bool:
     """Check whether the path is protected.
 
@@ -70,6 +67,4 @@ def is_protected_path(rel_path: Path) -> bool:
         True when the path should be excluded from backups.
     """
     rel_str = str(rel_path).replace("\\", "/")
-    return any(
-        rel_str.startswith(p.lstrip("./").rstrip("/")) for p in PROTECTED_PATHS
-    )
+    return any(rel_str.startswith(p.lstrip("./").rstrip("/")) for p in PROTECTED_PATHS)