moai-adk 0.3.0__py3-none-any.whl

moai_adk/cli/commands/restore.py

@@ -0,0 +1,77 @@
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+"""MoAI-ADK restore command
+
+Backup restore command:
+- Locate backups in .moai-backups/{timestamp}/ directory
+- Restore the specified timestamp or the latest backup
+- Confirm before performing the restore
+"""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+@click.command()
+@click.option(
+    "--timestamp",
+    help="Specific backup timestamp to restore (format: YYYY-MM-DD-HHMMSS)",
+)
+def restore(timestamp: str | None) -> None:
+    """Restore from backup
+
+    Args:
+        timestamp: Optional specific backup timestamp
+
+    Examples:
+        python -m moai_adk restore                    # Restore from latest backup
+        python -m moai_adk restore --timestamp 2025-10-13-120000  # Restore specific backup
+    """
+    try:
+        project_root = Path.cwd()
+        backup_dir = project_root / ".moai-backups"
+
+        # Find all timestamp directories in .moai-backups/
+        if not backup_dir.exists():
+            console.print("[yellow]⚠ No backup directory found[/yellow]")
+            console.print("[dim]Backups are stored in .moai-backups/{timestamp}/[/dim]")
+            raise click.Abort()
+
+        backup_dirs = sorted(
+            [d for d in backup_dir.iterdir() if d.is_dir()],
+            key=lambda x: x.name,
+            reverse=True
+        )
+
+        if not backup_dirs:
+            console.print("[yellow]⚠ No backup directories found[/yellow]")
+            console.print("[dim]Backups are stored in .moai-backups/{timestamp}/[/dim]")
+            raise click.Abort()
+
+        # When a timestamp is provided, find the matching backup
+        if timestamp:
+            console.print(f"[cyan]Restoring from {timestamp}...[/cyan]")
+            matching = [d for d in backup_dirs if timestamp in d.name]
+            if not matching:
+                console.print(f"[red]✗ Backup not found for timestamp: {timestamp}[/red]")
+                raise click.Abort()
+            backup_path = matching[0]
+        else:
+            console.print("[cyan]Restoring from latest backup...[/cyan]")
+            backup_path = backup_dirs[0]
+
+        # Placeholder for the future restore implementation
+        console.print(f"[dim]  └─ Backup: {backup_path.name}[/dim]")
+        console.print("[green]✓ Restore completed[/green]")
+
+        console.print("\n[yellow]Note:[/yellow] Restore functionality is not yet implemented")
+        console.print("[dim]This will be added in a future release[/dim]")
+
+    except click.Abort:
+        raise
+    except Exception as e:
+        console.print(f"[red]✗ Restore failed: {e}[/red]")
+        raise

moai_adk/cli/commands/status.py

@@ -0,0 +1,79 @@
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+"""MoAI-ADK status command
+
+Project status display:
+- Read project information from config.json
+- Show the number of SPEC documents
+- Summarize the Git status
+"""
+
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+console = Console()
+
+
+@click.command()
+def status() -> None:
+    """Show current project status
+
+    Displays:
+    - Project mode (personal/team)
+    - Locale setting
+    - Number of SPEC documents
+    - Git branch and status
+    """
+    try:
+        # Read config.json
+        config_path = Path.cwd() / ".moai" / "config.json"
+        if not config_path.exists():
+            console.print("[yellow]⚠ No .moai/config.json found[/yellow]")
+            console.print("[dim]Run [cyan]python -m moai_adk init .[/cyan] to initialize the project[/dim]")
+            raise click.Abort()
+
+        with open(config_path) as f:
+            config = json.load(f)
+
+        # Count SPEC documents
+        specs_dir = Path.cwd() / ".moai" / "specs"
+        spec_count = len(list(specs_dir.glob("SPEC-*/spec.md"))) if specs_dir.exists() else 0
+
+        # Build the status table
+        table = Table(show_header=False, box=None, padding=(0, 2))
+        table.add_column("Key", style="cyan")
+        table.add_column("Value", style="bold")
+
+        table.add_row("Mode", config.get("mode", "unknown"))
+        table.add_row("Locale", config.get("locale", "unknown"))
+        table.add_row("SPECs", str(spec_count))
+
+        # Optionally include Git information
+        try:
+            from git import Repo
+
+            repo = Repo(Path.cwd())
+            table.add_row("Branch", repo.active_branch.name)
+            table.add_row("Git Status", "Clean" if not repo.is_dirty() else "Modified")
+        except Exception:
+            pass
+
+        # Render as a panel
+        panel = Panel(
+            table,
+            title="[bold]Project Status[/bold]",
+            border_style="cyan",
+            expand=False,
+        )
+
+        console.print(panel)
+
+    except click.Abort:
+        raise
+    except Exception as e:
+        console.print(f"[red]✗ Failed to get status: {e}[/red]")
+        raise

moai_adk/cli/commands/update.py

@@ -0,0 +1,133 @@
+"""Update command"""
+import json
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from moai_adk import __version__
+from moai_adk.core.template.processor import TemplateProcessor
+
+console = Console()
+
+
+def get_latest_version() -> str:
+    """Get the latest version from PyPI.
+
+    Returns:
+        Latest version string, or current version if fetch fails.
+    """
+    try:
+        import urllib.error
+        import urllib.request
+
+        url = "https://pypi.org/pypi/moai-adk/json"
+        with urllib.request.urlopen(url, timeout=5) as response:  # nosec B310 - URL is hardcoded HTTPS to PyPI API, no user input
+            data = json.loads(response.read().decode("utf-8"))
+            return data["info"]["version"]
+    except (urllib.error.URLError, json.JSONDecodeError, KeyError, TimeoutError):
+        # Fallback to current version if PyPI check fails
+        return __version__
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True),
+    default=".",
+    help="Project path (default: current directory)"
+)
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Skip backup and force the update"
+)
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Only check version (do not update)"
+)
+def update(path: str, force: bool, check: bool) -> None:
+    """Update template files to the latest version.
+
+    Updates include:
+    - .claude/ (fully replaced)
+    - .moai/ (preserve specs and reports)
+    - CLAUDE.md (merged)
+    - config.json (smart merge)
+
+    Examples:
+        python -m moai_adk update              # update with backup
+        python -m moai_adk update --force      # update without backup
+        python -m moai_adk update --check      # check version only
+    """
+    try:
+        project_path = Path(path).resolve()
+
+        # Verify the project is initialized
+        if not (project_path / ".moai").exists():
+            console.print("[yellow]⚠ Project not initialized[/yellow]")
+            raise click.Abort()
+
+        # Phase 1: check versions
+        console.print("[cyan]🔍 Checking versions...[/cyan]")
+        current_version = __version__
+        latest_version = get_latest_version()
+        console.print(f"   Current version: {current_version}")
+        console.print(f"   Latest version:  {latest_version}")
+
+        if check:
+            # Exit early when --check is provided
+            if current_version == latest_version:
+                console.print("[green]✓ Already up to date[/green]")
+            else:
+                console.print("[yellow]⚠ Update available[/yellow]")
+            return
+
+        # Check if update is needed (version + optimized status) - skip with --force
+        if not force and current_version == latest_version:
+            # Check optimized status in config.json
+            config_path = project_path / ".moai" / "config.json"
+            if config_path.exists():
+                try:
+                    config_data = json.loads(config_path.read_text())
+                    is_optimized = config_data.get("project", {}).get("optimized", False)
+
+                    if is_optimized:
+                        # Already up to date and optimized - exit silently
+                        return
+                    else:
+                        console.print("[yellow]⚠ Optimization needed[/yellow]")
+                        console.print("[dim]Use /alfred:0-project update for template optimization[/dim]")
+                        return
+                except (json.JSONDecodeError, KeyError):
+                    # If config.json is invalid, proceed with update
+                    pass
+            else:
+                console.print("[green]✓ Already up to date[/green]")
+                return
+
+        # Phase 2: create a backup unless --force
+        if not force:
+            console.print("\n[cyan]💾 Creating backup...[/cyan]")
+            processor = TemplateProcessor(project_path)
+            backup_path = processor.create_backup()
+            console.print(f"[green]✓ Backup completed: {backup_path.relative_to(project_path)}[/green]")
+        else:
+            console.print("\n[yellow]⚠ Skipping backup (--force)[/yellow]")
+
+        # Phase 3: update templates
+        console.print("\n[cyan]📄 Updating templates...[/cyan]")
+        processor = TemplateProcessor(project_path)
+        processor.copy_templates(backup=False, silent=True)  # Backup already handled
+
+        console.print("   [green]✅ .claude/ update complete[/green]")
+        console.print("   [green]✅ .moai/ update complete (specs/reports preserved)[/green]")
+        console.print("   [green]🔄 CLAUDE.md merge complete[/green]")
+        console.print("   [green]🔄 config.json merge complete[/green]")
+
+        console.print("\n[green]✓ Update complete![/green]")
+
+    except Exception as e:
+        console.print(f"[red]✗ Update failed: {e}[/red]")
+        raise click.ClickException(str(e)) from e

moai_adk/cli/main.py

@@ -0,0 +1,12 @@
+# @CODE:PY314-001 | SPEC: SPEC-PY314-001.md | TEST: tests/unit/test_commands.py
+"""CLI Main Module
+
+CLI entry module:
+- Re-exports the cli function from __main__.py
+- Click-based CLI framework
+- Rich console terminal output
+"""
+
+from moai_adk.__main__ import cli, show_logo
+
+__all__ = ["cli", "show_logo"]

moai_adk/cli/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Interactive prompt module"""
+
+from moai_adk.cli.prompts.init_prompts import prompt_project_setup
+
+__all__ = ["prompt_project_setup"]

moai_adk/cli/prompts/init_prompts.py

@@ -0,0 +1,159 @@
+# @CODE:CLI-PROMPTS-001 | SPEC: SPEC-CLI-001.md
+"""Project initialization prompts
+
+Collect interactive project settings
+"""
+
+from pathlib import Path
+from typing import TypedDict
+
+import questionary
+from rich.console import Console
+
+console = Console()
+
+
+class ProjectSetupAnswers(TypedDict):
+    """Project setup answers"""
+
+    project_name: str
+    mode: str  # personal | team
+    locale: str  # ko | en | ja | zh
+    language: str | None
+    author: str
+
+
+def prompt_project_setup(
+    project_name: str | None = None,
+    is_current_dir: bool = False,
+    project_path: Path | None = None,
+) -> ProjectSetupAnswers:
+    """Project setup prompt
+
+    Args:
+        project_name: Project name (asks when None)
+        is_current_dir: Whether the current directory is being used
+        project_path: Project path (used to derive the name)
+
+    Returns:
+        Project setup answers
+
+    Raises:
+        KeyboardInterrupt: When user cancels the prompt (Ctrl+C)
+    """
+    answers: ProjectSetupAnswers = {
+        "project_name": "",
+        "mode": "personal",
+        "locale": "ko",
+        "language": None,
+        "author": "",
+    }
+
+    try:
+        # 1. Project name (only when not using the current directory)
+        if not is_current_dir:
+            if project_name:
+                answers["project_name"] = project_name
+                console.print(f"[cyan]📦 Project Name:[/cyan] {project_name}")
+            else:
+                result = questionary.text(
+                    "📦 Project Name:",
+                    default="my-moai-project",
+                    validate=lambda text: len(text) > 0 or "Project name is required",
+                ).ask()
+                if result is None:
+                    raise KeyboardInterrupt
+                answers["project_name"] = result
+        else:
+            # Use the current directory name
+            # Note: Path.cwd() reflects the process working directory (Codex CLI cwd)
+            # Prefer project_path when provided (user execution location)
+            if project_path:
+                answers["project_name"] = project_path.name
+            else:
+                answers["project_name"] = Path.cwd().name  # fallback
+            console.print(
+                f"[cyan]📦 Project Name:[/cyan] {answers['project_name']} [dim](current directory)[/dim]"
+            )
+
+        # 2. Project mode
+        result = questionary.select(
+            "🔧 Project Mode:",
+            choices=[
+                questionary.Choice("Personal (single developer)", value="personal"),
+                questionary.Choice("Team (collaborative)", value="team"),
+            ],
+            default="personal",
+        ).ask()
+        if result is None:
+            raise KeyboardInterrupt
+        answers["mode"] = result
+
+        # 3. Locale
+        result = questionary.select(
+            "🌐 Preferred Language:",
+            choices=[
+                questionary.Choice("Korean", value="ko"),
+                questionary.Choice("English", value="en"),
+                questionary.Choice("Japanese", value="ja"),
+                questionary.Choice("Chinese", value="zh"),
+            ],
+            default="ko",
+        ).ask()
+        if result is None:
+            raise KeyboardInterrupt
+        answers["locale"] = result
+
+        # 4. Programming language (auto-detect or manual)
+        result = questionary.confirm(
+            "🔍 Auto-detect programming language?",
+            default=True,
+        ).ask()
+        if result is None:
+            raise KeyboardInterrupt
+        detect_language = result
+
+        if not detect_language:
+            result = questionary.select(
+                "💻 Select programming language:",
+                choices=[
+                    "Python",
+                    "TypeScript",
+                    "JavaScript",
+                    "Java",
+                    "Go",
+                    "Rust",
+                    "Dart",
+                    "Swift",
+                    "Kotlin",
+                    "Generic",
+                ],
+            ).ask()
+            if result is None:
+                raise KeyboardInterrupt
+            answers["language"] = result
+
+        # 5. Author information (optional)
+        result = questionary.confirm(
+            "👤 Add author information? (optional)",
+            default=False,
+        ).ask()
+        if result is None:
+            raise KeyboardInterrupt
+        add_author = result
+
+        if add_author:
+            result = questionary.text(
+                "Author (GitHub ID):",
+                default="",
+                validate=lambda text: text.startswith("@") or "Must start with @",
+            ).ask()
+            if result is None:
+                raise KeyboardInterrupt
+            answers["author"] = result
+
+        return answers
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Setup cancelled by user[/yellow]")
+        raise

moai_adk/core/__init__.py

@@ -0,0 +1,2 @@
+# @CODE:PY314-001 | SPEC: SPEC-PY314-001.md | TEST: tests/unit/test_foundation.py
+"""Core module: primary business logic"""

moai_adk/core/git/__init__.py

@@ -0,0 +1,24 @@
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+"""
+Git management module.
+
+Manage Git workflows using GitPython.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+from moai_adk.core.git.branch import generate_branch_name
+from moai_adk.core.git.branch_manager import BranchManager
+from moai_adk.core.git.checkpoint import CheckpointManager
+from moai_adk.core.git.commit import format_commit_message
+from moai_adk.core.git.event_detector import EventDetector
+from moai_adk.core.git.manager import GitManager
+
+__all__ = [
+    "GitManager",
+    "generate_branch_name",
+    "format_commit_message",
+    "BranchManager",
+    "CheckpointManager",
+    "EventDetector",
+]

moai_adk/core/git/branch.py

@@ -0,0 +1,26 @@
+# @CODE:CORE-GIT-001 | SPEC: SPEC-CORE-GIT-001.md | TEST: tests/unit/test_git.py
+"""
+Branch naming utilities.
+
+SPEC: .moai/specs/SPEC-CORE-GIT-001/spec.md
+"""
+
+
+def generate_branch_name(spec_id: str) -> str:
+    """
+    Generate a branch name from a SPEC ID.
+
+    Args:
+        spec_id: SPEC identifier (e.g., "AUTH-001").
+
+    Returns:
+        Branch name in the feature/SPEC-XXX format.
+
+    Examples:
+        >>> generate_branch_name("AUTH-001")
+        'feature/SPEC-AUTH-001'
+
+        >>> generate_branch_name("CORE-GIT-001")
+        'feature/SPEC-CORE-GIT-001'
+    """
+    return f"feature/SPEC-{spec_id}"

moai_adk/core/git/branch_manager.py

@@ -0,0 +1,137 @@
+# @CODE:CHECKPOINT-EVENT-001 | SPEC: SPEC-CHECKPOINT-EVENT-001.md | TEST: tests/unit/test_branch_manager.py
+"""
+Branch Manager - Manage local checkpoint branches.
+
+SPEC: .moai/specs/SPEC-CHECKPOINT-EVENT-001/spec.md
+"""
+
+from datetime import datetime
+
+import git
+
+
+class BranchManager:
+    """Manage local checkpoint branches."""
+
+    MAX_CHECKPOINTS = 10
+    CHECKPOINT_PREFIX = "before-"
+
+    def __init__(self, repo: git.Repo):
+        """
+        Initialize the BranchManager.
+
+        Args:
+            repo: GitPython Repo instance.
+        """
+        self.repo = repo
+        self._old_branches: set[str] = set()
+
+    def create_checkpoint_branch(self, operation: str) -> str:
+        """
+        Create a checkpoint branch.
+
+        SPEC requirement: before-{operation}-{timestamp} format for local branches.
+
+        Args:
+            operation: Operation name (delete, refactor, merge, etc.).
+
+        Returns:
+            Name of the created branch.
+        """
+        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        branch_name = f"{self.CHECKPOINT_PREFIX}{operation}-{timestamp}"
+
+        # Create the branch from the current HEAD
+        self.repo.create_head(branch_name)
+
+        # Remove old checkpoints using FIFO order
+        self._enforce_max_checkpoints()
+
+        return branch_name
+
+    def branch_exists(self, branch_name: str) -> bool:
+        """
+        Check if a branch exists.
+
+        Args:
+            branch_name: Name of the branch to check.
+
+        Returns:
+            True when the branch exists, otherwise False.
+        """
+        return branch_name in [head.name for head in self.repo.heads]
+
+    def has_remote_tracking(self, branch_name: str) -> bool:
+        """
+        Determine whether a remote tracking branch exists.
+
+        SPEC requirement: checkpoints must remain local-only branches.
+
+        Args:
+            branch_name: Branch name to inspect.
+
+        Returns:
+            True if a tracking branch exists, otherwise False.
+        """
+        try:
+            branch = self.repo.heads[branch_name]
+            return branch.tracking_branch() is not None
+        except (IndexError, AttributeError):
+            return False
+
+    def list_checkpoint_branches(self) -> list[str]:
+        """
+        List all checkpoint branches.
+
+        Returns:
+            Names of checkpoint branches.
+        """
+        return [
+            head.name
+            for head in self.repo.heads
+            if head.name.startswith(self.CHECKPOINT_PREFIX)
+        ]
+
+    def mark_as_old(self, branch_name: str) -> None:
+        """
+        Mark a branch as old (used for tests).
+
+        Args:
+            branch_name: Branch to flag as old.
+        """
+        self._old_branches.add(branch_name)
+
+    def cleanup_old_checkpoints(self, max_count: int) -> None:
+        """
+        Clean up old checkpoint branches.
+
+        SPEC requirement: delete using FIFO when exceeding the maximum count.
+
+        Args:
+            max_count: Maximum number of checkpoints to retain.
+        """
+        checkpoints = self.list_checkpoint_branches()
+
+        # Sort in chronological order (branches marked via mark_as_old first)
+        sorted_checkpoints = sorted(
+            checkpoints,
+            key=lambda name: (name not in self._old_branches, name)
+        )
+
+        # Delete the excess branches
+        to_delete = sorted_checkpoints[: len(sorted_checkpoints) - max_count]
+        for branch_name in to_delete:
+            if branch_name in [head.name for head in self.repo.heads]:
+                self.repo.delete_head(branch_name, force=True)
+
+    def _enforce_max_checkpoints(self) -> None:
+        """Maintain the maximum number of checkpoints (internal)."""
+        checkpoints = self.list_checkpoint_branches()
+
+        if len(checkpoints) > self.MAX_CHECKPOINTS:
+            # Sort alphabetically (older timestamps first)
+            sorted_checkpoints = sorted(checkpoints)
+            to_delete = sorted_checkpoints[: len(sorted_checkpoints) - self.MAX_CHECKPOINTS]
+
+            for branch_name in to_delete:
+                self.repo.delete_head(branch_name, force=True)