moai-adk 0.3.0__py3-none-any.whl

moai_adk/core/git/checkpoint.py

@@ -0,0 +1,140 @@
+# @CODE:CHECKPOINT-EVENT-001 | SPEC: SPEC-CHECKPOINT-EVENT-001.md | TEST: tests/unit/test_checkpoint.py
+"""
+Checkpoint Manager - Event-driven checkpoint system.
+
+SPEC: .moai/specs/SPEC-CHECKPOINT-EVENT-001/spec.md
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import git
+
+from moai_adk.core.git.branch_manager import BranchManager
+from moai_adk.core.git.event_detector import EventDetector
+
+
+class CheckpointManager:
+    """Manage creation and restoration of event-driven checkpoints."""
+
+    def __init__(self, repo: git.Repo, project_root: Path):
+        """
+        Initialize the CheckpointManager.
+
+        Args:
+            repo: GitPython Repo instance.
+            project_root: Project root directory.
+        """
+        self.repo = repo
+        self.project_root = project_root
+        self.event_detector = EventDetector()
+        self.branch_manager = BranchManager(repo)
+        self.log_file = project_root / ".moai" / "checkpoints.log"
+
+        # Ensure the log directory exists
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    def create_checkpoint_if_risky(
+        self,
+        operation: str,
+        deleted_files: Optional[list[str]] = None,
+        renamed_files: Optional[list[tuple[str, str]]] = None,
+        modified_files: Optional[list[Path]] = None,
+    ) -> Optional[str]:
+        """
+        Create a checkpoint when a risky operation is detected.
+
+        SPEC requirement: automatically create a checkpoint for risky actions.
+
+        Args:
+            operation: Operation type.
+            deleted_files: Files scheduled for deletion.
+            renamed_files: Files that will be renamed.
+            modified_files: Files that will be modified.
+
+        Returns:
+            Created checkpoint ID (branch name) or None when the operation is safe.
+        """
+        is_risky = False
+
+        # Identify large deletion operations
+        if deleted_files and self.event_detector.is_risky_deletion(deleted_files):
+            is_risky = True
+
+        # Identify large-scale refactoring
+        if renamed_files and self.event_detector.is_risky_refactoring(renamed_files):
+            is_risky = True
+
+        # Check for critical file modifications
+        if modified_files:
+            for file_path in modified_files:
+                if self.event_detector.is_critical_file(file_path):
+                    is_risky = True
+                    break
+
+        if not is_risky:
+            return None
+
+        # Create a checkpoint
+        checkpoint_id = self.branch_manager.create_checkpoint_branch(operation)
+
+        # Record checkpoint metadata
+        self._log_checkpoint(checkpoint_id, operation)
+
+        return checkpoint_id
+
+    def restore_checkpoint(self, checkpoint_id: str) -> None:
+        """
+        Restore the repository to the specified checkpoint.
+
+        SPEC requirement: capture the current state as a new checkpoint before restoring.
+
+        Args:
+            checkpoint_id: Target checkpoint ID (branch name).
+        """
+        # Save current state as a safety checkpoint before restoring
+        safety_checkpoint = self.branch_manager.create_checkpoint_branch("restore")
+        self._log_checkpoint(safety_checkpoint, "restore", is_safety=True)
+
+        # Check out the checkpoint branch
+        self.repo.git.checkout(checkpoint_id)
+
+    def list_checkpoints(self) -> list[str]:
+        """
+        List all checkpoints.
+
+        Returns:
+            List of checkpoint IDs.
+        """
+        return self.branch_manager.list_checkpoint_branches()
+
+    def _log_checkpoint(
+        self,
+        checkpoint_id: str,
+        operation: str,
+        is_safety: bool = False
+    ) -> None:
+        """
+        Append checkpoint metadata to the log file.
+
+        SPEC requirement: write metadata to .moai/checkpoints.log.
+
+        Args:
+            checkpoint_id: Checkpoint identifier.
+            operation: Operation type.
+            is_safety: Whether the checkpoint was created for safety.
+        """
+        timestamp = datetime.now().isoformat()
+
+        log_entry = f"""---
+checkpoint_id: {checkpoint_id}
+operation: {operation}
+timestamp: {timestamp}
+is_safety: {is_safety}
+---
+"""
+
+        # Append the entry to the log
+        with open(self.log_file, "a", encoding="utf-8") as f:
+            f.write(log_entry)

moai_adk/core/git/commit.py

@@ -0,0 +1,68 @@
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+"""
+Commit message formatting utilities.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+from typing import Literal
+
+
+def format_commit_message(
+    stage: Literal["red", "green", "refactor", "docs"],
+    description: str,
+    locale: str = "ko",
+) -> str:
+    """
+    Generate a commit message for each TDD stage.
+
+    Args:
+        stage: TDD stage (red, green, refactor, docs).
+        description: Commit description text.
+        locale: Language code (ko, en, ja, zh).
+
+    Returns:
+        Formatted commit message.
+
+    Examples:
+        >>> format_commit_message("red", "Add failing authentication test", "ko")
+        '🔴 RED: Add failing authentication test'
+
+        >>> format_commit_message("green", "Implement authentication", "en")
+        '🟢 GREEN: Implement authentication'
+
+        >>> format_commit_message("refactor", "Improve code structure", "ko")
+        '♻️ REFACTOR: Improve code structure'
+    """
+    templates = {
+        "ko": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "en": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "ja": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+        "zh": {
+            "red": "🔴 RED: {desc}",
+            "green": "🟢 GREEN: {desc}",
+            "refactor": "♻️ REFACTOR: {desc}",
+            "docs": "📝 DOCS: {desc}",
+        },
+    }
+
+    template = templates.get(locale, templates["en"]).get(stage.lower())
+    if not template:
+        raise ValueError(f"Invalid stage: {stage}")
+
+    return template.format(desc=description)

moai_adk/core/git/event_detector.py

@@ -0,0 +1,81 @@
+# @CODE:CHECKPOINT-EVENT-001 | SPEC: SPEC-CHECKPOINT-EVENT-001.md | TEST: tests/unit/test_event_detector.py
+"""
+Event Detector - Identify risky operations.
+
+SPEC: .moai/specs/SPEC-CHECKPOINT-EVENT-001/spec.md
+"""
+
+from pathlib import Path
+
+
+class EventDetector:
+    """Detect potentially risky operations."""
+
+    # @CODE:CHECKPOINT-EVENT-001:DOMAIN - Critical file list
+    CRITICAL_FILES = {
+        "CLAUDE.md",
+        "config.json",
+        ".moai/config.json",
+    }
+
+    CRITICAL_DIRS = {
+        ".moai/memory",
+    }
+
+    def is_risky_deletion(self, deleted_files: list[str]) -> bool:
+        """
+        Detect large-scale file deletions.
+
+        SPEC requirement: deleting 10 or more files counts as risky.
+
+        Args:
+            deleted_files: Files slated for deletion.
+
+        Returns:
+            True when 10 or more files are deleted, otherwise False.
+        """
+        return len(deleted_files) >= 10
+
+    def is_risky_refactoring(self, renamed_files: list[tuple[str, str]]) -> bool:
+        """
+        Detect large-scale refactoring.
+
+        SPEC requirement: renaming 10 or more files counts as risky.
+
+        Args:
+            renamed_files: List of (old_name, new_name) pairs.
+
+        Returns:
+            True when 10 or more files are renamed, otherwise False.
+        """
+        return len(renamed_files) >= 10
+
+    def is_critical_file(self, file_path: Path) -> bool:
+        """
+        Determine whether the file is critical.
+
+        SPEC requirement: modifying CLAUDE.md, config.json, or .moai/memory/*.md is risky.
+
+        Args:
+            file_path: File path to inspect.
+
+        Returns:
+            True when the file is critical, otherwise False.
+        """
+        # Check whether the file name is in the critical list
+        if file_path.name in self.CRITICAL_FILES:
+            return True
+
+        # Convert to string for further checks
+        path_str = str(file_path)
+
+        # Detect .moai/config.json paths
+        if ".moai/config.json" in path_str or ".moai\\config.json" in path_str:
+            return True
+
+        # Detect files inside the .moai/memory/ directory
+        for critical_dir in self.CRITICAL_DIRS:
+            if critical_dir in path_str or critical_dir.replace("/", "\\") in path_str:
+                return True
+
+        return False

moai_adk/core/git/manager.py

@@ -0,0 +1,127 @@
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+"""
+Git repository management built on GitPython.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+from git import InvalidGitRepositoryError, Repo
+
+
+class GitManager:
+    """Manage interactions with a Git repository."""
+
+    def __init__(self, repo_path: str = "."):
+        """
+        Initialize the GitManager.
+
+        Args:
+            repo_path: Path to the Git repository (default: current directory)
+
+        Raises:
+            InvalidGitRepositoryError: Raised when the path is not a Git repository.
+        """
+        self.repo = Repo(repo_path)
+        self.git = self.repo.git
+
+    def is_repo(self) -> bool:
+        """
+        Check whether the path points to a Git repository.
+
+        Returns:
+            True when the location is a Git repository, otherwise False.
+
+        Examples:
+            >>> manager = GitManager("/path/to/repo")
+            >>> manager.is_repo()
+            True
+        """
+        try:
+            _ = self.repo.git_dir
+            return True
+        except (InvalidGitRepositoryError, Exception):
+            return False
+
+    def current_branch(self) -> str:
+        """
+        Return the active branch name.
+
+        Returns:
+            Name of the currently checked-out branch.
+
+        Examples:
+            >>> manager = GitManager()
+            >>> manager.current_branch()
+            'main'
+        """
+        return self.repo.active_branch.name
+
+    def is_dirty(self) -> bool:
+        """
+        Check whether the working tree has uncommitted changes.
+
+        Returns:
+            True when the worktree is dirty, otherwise False.
+
+        Examples:
+            >>> manager = GitManager()
+            >>> manager.is_dirty()
+            False
+        """
+        return self.repo.is_dirty()
+
+    def create_branch(self, branch_name: str, from_branch: str | None = None) -> None:
+        """
+        Create and switch to a new branch.
+
+        Args:
+            branch_name: Name of the branch to create.
+            from_branch: Base branch (default: current branch).
+
+        Examples:
+            >>> manager = GitManager()
+            >>> manager.create_branch("feature/SPEC-AUTH-001")
+            >>> manager.current_branch()
+            'feature/SPEC-AUTH-001'
+        """
+        if from_branch:
+            self.git.checkout("-b", branch_name, from_branch)
+        else:
+            self.git.checkout("-b", branch_name)
+
+    def commit(self, message: str, files: list[str] | None = None) -> None:
+        """
+        Stage files and create a commit.
+
+        Args:
+            message: Commit message.
+            files: Optional list of files to commit (default: all changes).
+
+        Examples:
+            >>> manager = GitManager()
+            >>> manager.commit("feat: add authentication", files=["auth.py"])
+        """
+        if files:
+            self.repo.index.add(files)
+        else:
+            self.git.add(A=True)
+
+        self.repo.index.commit(message)
+
+    def push(self, branch: str | None = None, set_upstream: bool = False) -> None:
+        """
+        Push commits to the remote repository.
+
+        Args:
+            branch: Branch to push (default: current branch).
+            set_upstream: Whether to set the upstream tracking branch.
+
+        Examples:
+            >>> manager = GitManager()
+            >>> manager.push(set_upstream=True)
+        """
+        if set_upstream:
+            target_branch = branch or self.current_branch()
+            self.git.push("--set-upstream", "origin", target_branch)
+        else:
+            self.git.push()

moai_adk/core/project/__init__.py

@@ -0,0 +1,2 @@
+# @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

@@ -0,0 +1,84 @@
+# @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:
+- Back up only the required files (OR condition)
+- Backup path: .moai-backups/{timestamp}/ (v0.3.0)
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+# Backup targets (OR condition - back up when any exist)
+BACKUP_TARGETS = [
+    ".moai/config.json",
+    ".moai/project/",
+    ".moai/memory/",
+    ".claude/",
+    "CLAUDE.md",
+]
+
+# User data protection paths (excluded from backups)
+PROTECTED_PATHS = [
+    ".moai/specs/",
+    ".moai/reports/",
+]
+
+
+def has_any_moai_files(project_path: Path) -> bool:
+    """Check whether any MoAI-ADK files exist (OR condition).
+
+    Args:
+        project_path: Project path.
+
+    Returns:
+        True when any backup target exists.
+    """
+    for target in BACKUP_TARGETS:
+        target_path = project_path / target
+        if target_path.exists():
+            return True
+    return False
+
+
+def get_backup_targets(project_path: Path) -> list[str]:
+    """Return existing backup targets.
+
+    Args:
+        project_path: Project path.
+
+    Returns:
+        List of backup targets that exist.
+    """
+    targets: list[str] = []
+    for target in BACKUP_TARGETS:
+        target_path = project_path / target
+        if target_path.exists():
+            targets.append(target)
+    return targets
+
+
+def generate_backup_dir_name() -> str:
+    """Generate a timestamp-based backup directory name (v0.3.0).
+
+    Returns:
+        Timestamp formatted as YYYYMMDD-HHMMSS.
+        Note: callers use .moai-backups/{timestamp}/ format.
+    """
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    return timestamp
+
+
+def is_protected_path(rel_path: Path) -> bool:
+    """Check whether the path is protected.
+
+    Args:
+        rel_path: Relative path.
+
+    Returns:
+        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
+    )