moai-adk 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/shared/core/project.py

@@ -1,683 +0,0 @@
-#!/usr/bin/env python3
-"""Project metadata utilities
-
-Project information inquiry (language, Git, SPEC progress, etc.)
-"""
-
-import json
-import signal
-import socket
-import subprocess
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Any
-
-# Cache directory for version check results
-CACHE_DIR_NAME = ".moai/cache"
-
-
-class TimeoutError(Exception):
-    """Signal-based timeout exception"""
-    pass
-
-
-@contextmanager
-def timeout_handler(seconds: int):
-    """Hard timeout using SIGALRM (works on Unix systems including macOS)
-
-    This uses kernel-level signal to interrupt ANY blocking operation,
-    even if subprocess.run() timeout fails on macOS.
-
-    Args:
-        seconds: Timeout duration in seconds
-
-    Raises:
-        TimeoutError: If operation exceeds timeout
-    """
-    def _handle_timeout(signum, frame):
-        raise TimeoutError(f"Operation timed out after {seconds} seconds")
-
-    # Set the signal handler
-    old_handler = signal.signal(signal.SIGALRM, _handle_timeout)
-    signal.alarm(seconds)
-    try:
-        yield
-    finally:
-        signal.alarm(0)  # Disable alarm
-        signal.signal(signal.SIGALRM, old_handler)
-
-
-def detect_language(cwd: str) -> str:
-    """Detect project language (supports 20 items languages)
-
-    Browse the File system to detect your project's main development language.
-    First, check configuration files such as pyproject.toml and tsconfig.json.
-    Apply TypeScript first principles (if tsconfig.json exists).
-
-    Args:
-        cwd: Project root directory path (both absolute and relative paths are possible)
-
-    Returns:
-        Detected language name (lowercase). If detection fails, "Unknown Language" is returned.
-        Supported languages: python, typescript, javascript, java, go, rust,
-                  dart, swift, kotlin, php, ruby, elixir, scala,
-                  clojure, cpp, c, csharp, haskell, shell, lua
-
-    Examples:
-        >>> detect_language("/path/to/python/project")
-        'python'
-        >>> detect_language("/path/to/typescript/project")
-        'typescript'
-        >>> detect_language("/path/to/unknown/project")
-        'Unknown Language'
-
-    TDD History:
-        - RED: Write a 21 items language detection test (20 items language + 1 items unknown)
-        - GREEN: 20 items language + unknown implementation, all tests passed
-        - REFACTOR: Optimize file inspection order, apply TypeScript priority principle
-    """
-    cwd_path = Path(cwd)
-
-    # Language detection mapping
-    language_files = {
-        "pyproject.toml": "python",
-        "tsconfig.json": "typescript",
-        "package.json": "javascript",
-        "pom.xml": "java",
-        "go.mod": "go",
-        "Cargo.toml": "rust",
-        "pubspec.yaml": "dart",
-        "Package.swift": "swift",
-        "build.gradle.kts": "kotlin",
-        "composer.json": "php",
-        "Gemfile": "ruby",
-        "mix.exs": "elixir",
-        "build.sbt": "scala",
-        "project.clj": "clojure",
-        "CMakeLists.txt": "cpp",
-        "Makefile": "c",
-    }
-
-    # Check standard language files
-    for file_name, language in language_files.items():
-        if (cwd_path / file_name).exists():
-            # Special handling for package.json - prefer typescript if tsconfig exists
-            if file_name == "package.json" and (cwd_path / "tsconfig.json").exists():
-                return "typescript"
-            return language
-
-    # Check for C# project files (*.csproj)
-    if any(cwd_path.glob("*.csproj")):
-        return "csharp"
-
-    # Check for Haskell project files (*.cabal)
-    if any(cwd_path.glob("*.cabal")):
-        return "haskell"
-
-    # Check for Shell scripts (*.sh)
-    if any(cwd_path.glob("*.sh")):
-        return "shell"
-
-    # Check for Lua files (*.lua)
-    if any(cwd_path.glob("*.lua")):
-        return "lua"
-
-    return "Unknown Language"
-
-
-def _run_git_command(args: list[str], cwd: str, timeout: int = 2) -> str:
-    """Git command execution with HARD timeout protection
-
-    Safely execute Git commands and return output.
-    Uses SIGALRM (kernel-level interrupt) to handle macOS subprocess timeout bug.
-    Eliminates code duplication and provides consistent error handling.
-
-    Args:
-        args: Git command argument list (git adds automatically)
-        cwd: Execution directory path
-        timeout: Timeout (seconds, default 2 seconds)
-
-    Returns:
-        Git command output (stdout, removing leading and trailing spaces)
-
-    Raises:
-        subprocess.TimeoutExpired: Timeout exceeded (via TimeoutError)
-        subprocess.CalledProcessError: Git command failed
-
-    Examples:
-        >>> _run_git_command(["branch", "--show-current"], ".")
-        'main'
-
-    TDD History:
-        - RED: Git command hang scenario test
-        - GREEN: SIGALRM-based timeout implementation
-        - REFACTOR: Exception conversion to subprocess.TimeoutExpired
-    """
-    try:
-        with timeout_handler(timeout):
-            result = subprocess.run(
-                ["git"] + args,
-                cwd=cwd,
-                capture_output=True,
-                text=True,
-                check=False,  # Don't raise on non-zero exit - we'll check manually
-            )
-
-            # Check exit code manually
-            if result.returncode != 0:
-                raise subprocess.CalledProcessError(
-                    result.returncode, ["git"] + args, result.stdout, result.stderr
-                )
-
-            return result.stdout.strip()
-
-    except TimeoutError:
-        # Convert to subprocess.TimeoutExpired for consistent error handling
-        raise subprocess.TimeoutExpired(["git"] + args, timeout)
-
-
-def get_git_info(cwd: str) -> dict[str, Any]:
-    """Gather Git repository information
-
-    View the current status of a Git repository.
-    Returns the branch name, commit hash, number of changes, and last commit message.
-    If it is not a Git repository, it returns an empty dictionary.
-
-    Args:
-        cwd: Project root directory path
-
-    Returns:
-        Git information dictionary. Includes the following keys:
-        - branch: Current branch name (str)
-        - commit: Current commit hash (str, full hash)
-        - changes: Number of changed files (int, staged + unstaged)
-        - last_commit: Last commit message (str, subject only)
-
-        Empty dictionary {} if it is not a Git repository or the query fails.
-
-    Examples:
-        >>> get_git_info("/path/to/git/repo")
-        {'branch': 'main', 'commit': 'abc123...', 'changes': 3, 'last_commit': 'Fix bug'}
-        >>> get_git_info("/path/to/non-git")
-        {}
-
-    Notes:
-        - Timeout: 2 seconds for each Git command
-        - Security: Safe execution with subprocess.run(shell=False)
-        - Error handling: Returns an empty dictionary in case of all exceptions
-        - Commit message limited to 50 characters for display purposes
-
-    TDD History:
-        - RED: 3 items scenario test (Git repo, non-Git, error)
-        - GREEN: Implementation of subprocess-based Git command execution
-        - REFACTOR: Add timeout (2 seconds), strengthen exception handling, remove duplicates with helper function
-        - UPDATE: Added last_commit message field for SessionStart display
-    """
-    try:
-        # Check if it's a git repository
-        _run_git_command(["rev-parse", "--git-dir"], cwd)
-
-        # Get branch name, commit hash, and changes
-        branch = _run_git_command(["branch", "--show-current"], cwd)
-        commit = _run_git_command(["rev-parse", "HEAD"], cwd)
-        status_output = _run_git_command(["status", "--short"], cwd)
-        changes = len([line for line in status_output.splitlines() if line])
-
-        # Get last commit message (subject only, limited to 50 chars)
-        last_commit = _run_git_command(["log", "-1", "--format=%s"], cwd)
-        if len(last_commit) > 50:
-            last_commit = last_commit[:47] + "..."
-
-        return {
-            "branch": branch,
-            "commit": commit,
-            "changes": changes,
-            "last_commit": last_commit,
-        }
-
-    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, FileNotFoundError):
-        return {}
-
-
-def count_specs(cwd: str) -> dict[str, int]:
-    """SPEC File count and progress calculation
-
-    Browse the .moai/specs/ directory to find the number of SPEC Files and
-    Counts the number of SPECs with status: completed.
-
-    Args:
-        cwd: Project root directory path
-
-    Returns:
-        SPEC progress dictionary. Includes the following keys:
-        - completed: Number of completed SPECs (int)
-        - total: total number of SPECs (int)
-        - percentage: completion percentage (int, 0~100)
-
-        All 0 if .moai/specs/ directory does not exist
-
-    Examples:
-        >>> count_specs("/path/to/project")
-        {'completed': 2, 'total': 5, 'percentage': 40}
-        >>> count_specs("/path/to/no-specs")
-        {'completed': 0, 'total': 0, 'percentage': 0}
-
-    Notes:
-        - SPEC File Location: .moai/specs/SPEC-{ID}/spec.md
-        - Completion condition: Include “status: completed” in YAML front matter
-        - If parsing fails, the SPEC is considered incomplete.
-
-    TDD History:
-        - RED: 5 items scenario test (0/0, 2/5, 5/5, no directory, parsing error)
-        - GREEN: SPEC search with Path.iterdir(), YAML parsing implementation
-        - REFACTOR: Strengthened exception handling, improved percentage calculation safety
-    """
-    specs_dir = Path(cwd) / ".moai" / "specs"
-
-    if not specs_dir.exists():
-        return {"completed": 0, "total": 0, "percentage": 0}
-
-    completed = 0
-    total = 0
-
-    for spec_dir in specs_dir.iterdir():
-        if not spec_dir.is_dir() or not spec_dir.name.startswith("SPEC-"):
-            continue
-
-        spec_file = spec_dir / "spec.md"
-        if not spec_file.exists():
-            continue
-
-        total += 1
-
-        # Parse YAML front matter
-        try:
-            content = spec_file.read_text()
-            if content.startswith("---"):
-                yaml_end = content.find("---", 3)
-                if yaml_end > 0:
-                    yaml_content = content[3:yaml_end]
-                    if "status: completed" in yaml_content:
-                        completed += 1
-        except (OSError, UnicodeDecodeError):
-            # File read failure or encoding error - considered incomplete
-            pass
-
-    percentage = int(completed / total * 100) if total > 0 else 0
-
-    return {
-        "completed": completed,
-        "total": total,
-        "percentage": percentage,
-    }
-
-
-def get_project_language(cwd: str) -> str:
-    """Determine the primary project language (prefers config.json).
-
-    Args:
-        cwd: Project root directory.
-
-    Returns:
-        Language string in lower-case.
-
-    Notes:
-        - Reads ``.moai/config.json`` first for a quick answer.
-        - Falls back to ``detect_language`` if configuration is missing.
-    """
-    config_path = Path(cwd) / ".moai" / "config.json"
-    if config_path.exists():
-        try:
-            config = json.loads(config_path.read_text())
-            lang = config.get("language", "")
-            if lang:
-                return lang
-        except (OSError, json.JSONDecodeError):
-            # Fall back to detection on parse errors
-            pass
-
-    # Fall back to the original language detection routine
-    return detect_language(cwd)
-
-
-# @CODE:CONFIG-INTEGRATION-001
-def get_version_check_config(cwd: str) -> dict[str, Any]:
-    """Read version check configuration from .moai/config.json
-
-    Returns version check settings with sensible defaults.
-    Supports frequency-based cache TTL configuration.
-
-    Args:
-        cwd: Project root directory path
-
-    Returns:
-        dict with keys:
-            - "enabled": Boolean (default: True)
-            - "frequency": "always" | "daily" | "weekly" | "never" (default: "daily")
-            - "cache_ttl_hours": TTL in hours based on frequency
-
-    Frequency to TTL mapping:
-        - "always": 0 hours (no caching)
-        - "daily": 24 hours
-        - "weekly": 168 hours (7 days)
-        - "never": infinity (never check)
-
-    TDD History:
-        - RED: 8 test scenarios (defaults, custom, disabled, TTL, etc.)
-        - GREEN: Minimal config reading with defaults
-        - REFACTOR: Add validation and error handling
-    """
-    # TTL mapping by frequency
-    TTL_BY_FREQUENCY = {
-        "always": 0,
-        "daily": 24,
-        "weekly": 168,
-        "never": float('inf')
-    }
-
-    # Default configuration
-    defaults = {
-        "enabled": True,
-        "frequency": "daily",
-        "cache_ttl_hours": 24
-    }
-
-    config_path = Path(cwd) / ".moai" / "config.json"
-    if not config_path.exists():
-        return defaults
-
-    try:
-        config = json.loads(config_path.read_text())
-
-        # Extract moai.version_check section
-        moai_config = config.get("moai", {})
-        version_check_config = moai_config.get("version_check", {})
-
-        # Read enabled flag (default: True)
-        enabled = version_check_config.get("enabled", defaults["enabled"])
-
-        # Read frequency (default: "daily")
-        frequency = moai_config.get("update_check_frequency", defaults["frequency"])
-
-        # Validate frequency
-        if frequency not in TTL_BY_FREQUENCY:
-            frequency = defaults["frequency"]
-
-        # Calculate TTL from frequency
-        cache_ttl_hours = TTL_BY_FREQUENCY[frequency]
-
-        # Allow explicit cache_ttl_hours override
-        if "cache_ttl_hours" in version_check_config:
-            cache_ttl_hours = version_check_config["cache_ttl_hours"]
-
-        return {
-            "enabled": enabled,
-            "frequency": frequency,
-            "cache_ttl_hours": cache_ttl_hours
-        }
-
-    except (OSError, json.JSONDecodeError, KeyError):
-        # Config read or parse error - return defaults
-        return defaults
-
-
-# @CODE:NETWORK-DETECT-001
-def is_network_available(timeout_seconds: float = 0.1) -> bool:
-    """Quick network availability check using socket.
-
-    Does NOT check PyPI specifically, just basic connectivity.
-    Returns immediately on success (< 50ms typically).
-    Returns False on any error without raising exceptions.
-
-    Args:
-        timeout_seconds: Socket timeout in seconds (default 0.1s)
-
-    Returns:
-        True if network appears available, False otherwise
-
-    Examples:
-        >>> is_network_available()
-        True  # Network is available
-        >>> is_network_available(timeout_seconds=0.001)
-        False  # Timeout too short, returns False
-
-    TDD History:
-        - RED: 3 test scenarios (success, failure, timeout)
-        - GREEN: Minimal socket.create_connection implementation
-        - REFACTOR: Add error handling for all exception types
-    """
-    try:
-        # Try connecting to Google's public DNS server (8.8.8.8:53)
-        # This is a reliable host that's typically reachable
-        connection = socket.create_connection(("8.8.8.8", 53), timeout=timeout_seconds)
-        connection.close()
-        return True
-    except (socket.timeout, OSError, Exception):
-        # Any connection error means network is unavailable
-        # This includes: timeout, connection refused, network unreachable, etc.
-        return False
-
-
-# @CODE:VERSION-DETECT-MAJOR-001
-def is_major_version_change(current: str, latest: str) -> bool:
-    """Detect if version change is a major version bump.
-
-    A major version change is when the first (major) component increases:
-    - 0.8.1 → 1.0.0: True (0 → 1)
-    - 1.2.3 → 2.0.0: True (1 → 2)
-    - 0.8.1 → 0.9.0: False (0 → 0, minor changed)
-    - 1.2.3 → 1.3.0: False (1 → 1)
-
-    Args:
-        current: Current version string (e.g., "0.8.1")
-        latest: Latest version string (e.g., "1.0.0")
-
-    Returns:
-        True if major version increased, False otherwise
-
-    Examples:
-        >>> is_major_version_change("0.8.1", "1.0.0")
-        True
-        >>> is_major_version_change("0.8.1", "0.9.0")
-        False
-        >>> is_major_version_change("dev", "1.0.0")
-        False  # Invalid versions return False
-
-    TDD History:
-        - RED: 4 test scenarios (0→1, 1→2, minor, invalid)
-        - GREEN: Minimal version parsing and comparison
-        - REFACTOR: Improve error handling for invalid versions
-    """
-    try:
-        # Parse version strings into integer components
-        current_parts = [int(x) for x in current.split(".")]
-        latest_parts = [int(x) for x in latest.split(".")]
-
-        # Compare major version (first component)
-        if len(current_parts) >= 1 and len(latest_parts) >= 1:
-            return latest_parts[0] > current_parts[0]
-
-        # If parsing succeeds but empty, no major change
-        return False
-
-    except (ValueError, AttributeError, IndexError):
-        # Invalid version format - return False (no exception)
-        return False
-
-
-# @CODE:VERSION-CACHE-INTEGRATION-001
-def get_package_version_info(cwd: str = ".") -> dict[str, Any]:
-    """Check MoAI-ADK current and latest version with caching and offline support.
-
-    Execution flow:
-    1. Try to load from cache (< 50ms)
-    2. If cache invalid, check network
-    3. If network available, query PyPI
-    4. If network unavailable, return current version only
-    5. Save result to cache for next time
-
-    Args:
-        cwd: Project root directory (for cache location)
-
-    Returns:
-        dict with keys:
-            - "current": Current installed version
-            - "latest": Latest version available on PyPI
-            - "update_available": Boolean indicating if update is available
-            - "upgrade_command": Recommended upgrade command (if update available)
-            - "release_notes_url": URL to release notes (Phase 3)
-            - "is_major_update": Boolean indicating major version change (Phase 3)
-
-    Note:
-        - Cache hit (< 24 hours): Returns in ~20ms, no network access
-        - Cache miss + online: Query PyPI (1s timeout), cache result
-        - Cache miss + offline: Return current version only (~100ms)
-        - Offline + cached: Return from cache in ~20ms
-
-    TDD History:
-        - RED: 5 test scenarios (network detection, cache integration, offline mode)
-        - GREEN: Integrate VersionCache with network detection
-        - REFACTOR: Extract cache directory constant, improve error handling
-        - Phase 3: Add release_notes_url and is_major_update fields (@CODE:VERSION-INTEGRATE-FIELDS-001)
-    """
-    import importlib.util
-    import urllib.error
-    import urllib.request
-    from importlib.metadata import PackageNotFoundError, version
-
-    # Import VersionCache from the same directory (using dynamic import for testing compatibility)
-    try:
-        version_cache_path = Path(__file__).parent / "version_cache.py"
-        spec = importlib.util.spec_from_file_location("version_cache", version_cache_path)
-        if spec and spec.loader:
-            version_cache_module = importlib.util.module_from_spec(spec)
-            spec.loader.exec_module(version_cache_module)
-            VersionCache = version_cache_module.VersionCache
-        else:
-            # Skip caching if module can't be loaded
-            VersionCache = None
-    except (ImportError, OSError):
-        # Graceful degradation: skip caching on import errors
-        VersionCache = None
-
-    # 1. Initialize cache (skip if VersionCache couldn't be imported)
-    cache_dir = Path(cwd) / CACHE_DIR_NAME
-    version_cache = VersionCache(cache_dir) if VersionCache else None
-
-    # 2. Get current installed version first (needed for cache validation)
-    current_version = "unknown"
-    try:
-        current_version = version("moai-adk")
-    except PackageNotFoundError:
-        current_version = "dev"
-        # Dev mode - skip cache and return immediately
-        return {
-            "current": "dev",
-            "latest": "unknown",
-            "update_available": False,
-            "upgrade_command": ""
-        }
-
-    # 3. Try to load from cache (fast path with version validation)
-    if version_cache and version_cache.is_valid():
-        cached_info = version_cache.load()
-        if cached_info:
-            # Only use cache if the cached version matches current installed version
-            # This prevents stale cache when package is upgraded locally
-            if cached_info.get("current") == current_version:
-                # Ensure new fields exist for backward compatibility
-                if "release_notes_url" not in cached_info:
-                    # Add missing fields to old cached data
-                    cached_info.setdefault("release_notes_url", None)
-                    cached_info.setdefault("is_major_update", False)
-                return cached_info
-            # else: cache is stale (version changed), fall through to re-check
-
-    # 4. Cache miss or stale - need to query PyPI
-    result = {
-        "current": current_version,
-        "latest": "unknown",
-        "update_available": False,
-        "upgrade_command": ""
-    }
-
-    # 5. Check if version check is enabled in config
-    config = get_version_check_config(cwd)
-    if not config["enabled"]:
-        # Version check disabled - return only current version
-        return result
-
-    # 6. Check network before PyPI query
-    if not is_network_available():
-        # Offline mode - return current version only
-        return result
-
-    # 7. Network available - query PyPI
-    pypi_data = None
-    try:
-        with timeout_handler(1):
-            url = "https://pypi.org/pypi/moai-adk/json"
-            headers = {"Accept": "application/json"}
-            req = urllib.request.Request(url, headers=headers)
-            with urllib.request.urlopen(req, timeout=0.8) as response:
-                pypi_data = json.load(response)
-                result["latest"] = pypi_data.get("info", {}).get("version", "unknown")
-
-                # Extract release notes URL from project_urls
-                try:
-                    project_urls = pypi_data.get("info", {}).get("project_urls", {})
-                    release_url = project_urls.get("Changelog", "")
-                    if not release_url:
-                        # Fallback to GitHub releases URL pattern
-                        release_url = f"https://github.com/modu-ai/moai-adk/releases/tag/v{result['latest']}"
-                    result["release_notes_url"] = release_url
-                except (KeyError, AttributeError, TypeError):
-                    result["release_notes_url"] = None
-
-    except (urllib.error.URLError, TimeoutError, Exception):
-        # PyPI query failed - return current version
-        result["release_notes_url"] = None
-        pass
-
-    # 7. Compare versions (simple comparison)
-    if result["current"] != "unknown" and result["latest"] != "unknown":
-        try:
-            # Parse versions for comparison
-            current_parts = [int(x) for x in result["current"].split(".")]
-            latest_parts = [int(x) for x in result["latest"].split(".")]
-
-            # Pad shorter version with zeros
-            max_len = max(len(current_parts), len(latest_parts))
-            current_parts.extend([0] * (max_len - len(current_parts)))
-            latest_parts.extend([0] * (max_len - len(latest_parts)))
-
-            if latest_parts > current_parts:
-                result["update_available"] = True
-                result["upgrade_command"] = f"uv pip install --upgrade moai-adk>={result['latest']}"
-
-                # Detect major version change
-                result["is_major_update"] = is_major_version_change(result["current"], result["latest"])
-            else:
-                result["is_major_update"] = False
-        except (ValueError, AttributeError):
-            # Version parsing failed - skip comparison
-            result["is_major_update"] = False
-            pass
-
-    # 8. Save result to cache (if caching is available)
-    if version_cache:
-        version_cache.save(result)
-
-    return result
-
-
-__all__ = [
-    "detect_language",
-    "get_git_info",
-    "count_specs",
-    "get_project_language",
-    "get_version_check_config",
-    "is_network_available",
-    "is_major_version_change",
-    "get_package_version_info",
-]