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

moai_adk/utils/__init__.py

@@ -3,5 +3,28 @@ MoAI-ADK utility module
 """
 
 from .logger import SensitiveDataFilter, setup_logger
+from .timeout import CrossPlatformTimeout, TimeoutError, timeout_context
+from .toon_utils import (
+    compare_formats,
+    migrate_json_to_toon,
+    toon_decode,
+    toon_encode,
+    toon_load,
+    toon_save,
+    validate_roundtrip,
+)
 
-__all__ = ["SensitiveDataFilter", "setup_logger"]
+__all__ = [
+    "SensitiveDataFilter",
+    "setup_logger",
+    "CrossPlatformTimeout",
+    "TimeoutError",
+    "timeout_context",
+    "toon_encode",
+    "toon_decode",
+    "toon_save",
+    "toon_load",
+    "validate_roundtrip",
+    "compare_formats",
+    "migrate_json_to_toon",
+]

moai_adk/utils/banner.py

@@ -7,6 +7,9 @@ from rich.console import Console
 
 console = Console()
 
+# Claude Code official terra cotta color
+CLAUDE_TERRA_COTTA = "#DA7756"
+
 MOAI_BANNER = """
 ███╗   ███╗          █████╗ ██╗       █████╗ ██████╗ ██╗  ██╗
 ████╗ ████║ ██████╗ ██╔══██╗██║      ██╔══██╗██╔══██╗██║ ██╔╝
@@ -23,19 +26,13 @@ def print_banner(version: str = "0.3.0") -> None:
     Args:
         version: MoAI-ADK version
     """
-    console.print(f"[cyan]{MOAI_BANNER}[/cyan]")
-    console.print(
-        "[dim]  Modu-AI's Agentic Development Kit w/ SuperAgent 🎩 Alfred[/dim]\n"
-    )
+    console.print(f"[{CLAUDE_TERRA_COTTA}]{MOAI_BANNER}[/{CLAUDE_TERRA_COTTA}]")
+    console.print("[dim]  Modu-AI's Agentic Development Kit w/ SuperAgent 🎩 Alfred[/dim]\n")
     console.print(f"[dim]  Version: {version}[/dim]\n")
 
 
 def print_welcome_message() -> None:
     """Print the welcome message"""
-    console.print(
-        "[cyan bold]🚀 Welcome to MoAI-ADK Project Initialization![/cyan bold]\n"
-    )
-    console.print(
-        "[dim]This wizard will guide you through setting up your MoAI-ADK project.[/dim]"
-    )
+    console.print("[cyan bold]🚀 Welcome to MoAI-ADK Project Initialization![/cyan bold]\n")
+    console.print("[dim]This wizard will guide you through setting up your MoAI-ADK project.[/dim]")
     console.print("[dim]You can press Ctrl+C at any time to cancel.\n[/dim]")

moai_adk/utils/common.py

@@ -4,7 +4,6 @@ Common utility functions
 """
 
 import asyncio
-import json
 import logging
 import re
 from dataclasses import dataclass, field
@@ -14,6 +13,7 @@ from typing import Dict, List, Optional
 from urllib.parse import urlparse
 
 import aiohttp
+import yaml
 
 logger = logging.getLogger(__name__)
 
@@ -49,9 +49,7 @@ class HTTPClient:
         self.session = aiohttp.ClientSession(
             connector=connector,
             timeout=timeout,
-            headers={
-                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
-            },
+            headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"},
         )
         return self
 
@@ -159,7 +157,7 @@ def create_report_path(base_path: Path, suffix: str = "report") -> Path:
 def format_duration(seconds: float) -> str:
     """Convert time (seconds) to readable format"""
     if seconds < 1:
-        return f"{seconds*1000:.0f}ms"
+        return f"{seconds * 1000:.0f}ms"
     elif seconds < 60:
         return f"{seconds:.1f}s"
     elif seconds < 3600:
@@ -172,9 +170,7 @@ def format_duration(seconds: float) -> str:
         return f"{hours}h {remaining_minutes}m"
 
 
-def calculate_score(
-    values: List[float], weights: Optional[List[float]] = None
-) -> float:
+def calculate_score(values: List[float], weights: Optional[List[float]] = None) -> float:
     """Calculate weighted average score"""
     if not values:
         return 0.0
@@ -223,11 +219,7 @@ class RateLimiter:
         now = datetime.now()
 
         # Remove old requests
-        self.requests = [
-            req_time
-            for req_time in self.requests
-            if (now - req_time).total_seconds() < self.time_window
-        ]
+        self.requests = [req_time for req_time in self.requests if (now - req_time).total_seconds() < self.time_window]
 
         return len(self.requests) < self.max_requests
 
@@ -236,17 +228,13 @@ class RateLimiter:
         if self.can_make_request():
             self.requests.append(datetime.now())
         else:
-            raise RateLimitError(
-                f"Rate limit exceeded: {self.max_requests} requests per {self.time_window}s"
-            )
+            raise RateLimitError(f"Rate limit exceeded: {self.max_requests} requests per {self.time_window}s")
 
     async def wait_if_needed(self):
         """Wait until request can be made"""
         if not self.can_make_request():
             oldest_request = min(self.requests)
-            wait_time = (
-                self.time_window - (datetime.now() - oldest_request).total_seconds()
-            )
+            wait_time = self.time_window - (datetime.now() - oldest_request).total_seconds()
             if wait_time > 0:
                 logger.info(f"Rate limiting: waiting {wait_time:.1f}s")
                 await asyncio.sleep(wait_time)
@@ -260,49 +248,80 @@ class RateLimitError(Exception):
 
 def load_hook_timeout() -> int:
     """
-    Load Hook timeout setting from .moai/config/config.json
+    Load Hook timeout setting from .moai/config/config.yaml
 
     Returns:
         int: timeout value (milliseconds), returns default 5000 if not configured
     """
     try:
-        config_path = Path(".moai/config/config.json")
+        config_path = Path(".moai/config/config.yaml")
         if not config_path.exists():
             return 5000  # Default value
 
         with open(config_path, "r", encoding="utf-8") as f:
-            config = json.load(f)
+            config = yaml.safe_load(f) or {}
 
         # Get timeout_ms value from hooks section
         hooks_config = config.get("hooks", {})
         timeout_ms = hooks_config.get("timeout_ms", 5000)
 
         return int(timeout_ms)
-    except (json.JSONDecodeError, FileNotFoundError, KeyError, ValueError):
+    except (yaml.YAMLError, FileNotFoundError, KeyError, ValueError):
         logger.warning("Failed to load hook timeout from config, using default 5000ms")
         return 5000
 
 
 def get_graceful_degradation() -> bool:
     """
-    Load graceful_degradation setting from .moai/config/config.json
+    Load graceful_degradation setting from .moai/config/config.yaml
 
     Returns:
         bool: graceful_degradation setting value, returns default True if not configured
     """
     try:
-        config_path = Path(".moai/config/config.json")
+        config_path = Path(".moai/config/config.yaml")
         if not config_path.exists():
             return True  # Default value
 
         with open(config_path, "r", encoding="utf-8") as f:
-            config = json.load(f)
+            config = yaml.safe_load(f) or {}
 
         # Get graceful_degradation value from hooks section
         hooks_config = config.get("hooks", {})
         return hooks_config.get("graceful_degradation", True)
-    except (json.JSONDecodeError, FileNotFoundError, KeyError):
-        logger.warning(
-            "Failed to load graceful_degradation from config, using default True"
-        )
+    except (yaml.YAMLError, FileNotFoundError, KeyError):
+        logger.warning("Failed to load graceful_degradation from config, using default True")
         return True
+
+
+def reset_stdin() -> None:
+    """Reset stdin to ensure interactive prompts work correctly.
+
+    This is needed after SpinnerContext or other operations that may
+    leave stdin in a non-interactive state. Call this before using
+    click.confirm() or input() after spinner operations.
+
+    Example:
+        with SpinnerContext("Processing..."):
+            do_work()
+        reset_stdin()  # Reset before interactive prompt
+        if click.confirm("Continue?"):
+            ...
+    """
+    import os
+    import sys
+
+    try:
+        # Try to flush any pending input (Unix-like systems)
+        import termios
+
+        termios.tcflush(sys.stdin, termios.TCIFLUSH)
+    except (ImportError, OSError, AttributeError):
+        pass
+
+    try:
+        # Reopen stdin from /dev/tty if available (Unix-like systems)
+        if os.path.exists("/dev/tty"):
+            sys.stdin = open("/dev/tty", "r")
+    except (OSError, IOError):
+        pass

moai_adk/utils/link_validator.py

@@ -131,9 +131,7 @@ class LinkValidator(HTTPClient):
                 result = await self.validate_link(link)
                 results.append(result)
                 # Log progress
-                logger.info(
-                    f"Validation complete: {link} -> {result.status_code} ({result.is_valid})"
-                )
+                logger.info(f"Validation complete: {link} -> {result.status_code} ({result.is_valid})")
                 return result
 
         # Validate all links asynchronously
@@ -158,9 +156,7 @@ class LinkValidator(HTTPClient):
 
         report = []
         report.append("# Online Documentation Link Validation Report")
-        report.append(
-            f"**Validation Time**: {validation_result.completed_at.strftime('%Y-%m-%d %H:%M:%S')}"
-        )
+        report.append(f"**Validation Time**: {validation_result.completed_at.strftime('%Y-%m-%d %H:%M:%S')}")
         report.append(f"**Total Links**: {validation_result.total_links}")
         report.append(f"**Valid Links**: {validation_result.valid_links}")
         report.append(f"**Invalid Links**: {validation_result.invalid_links}")
@@ -197,9 +193,7 @@ class LinkValidator(HTTPClient):
         if validation_result.valid_links > 0:
             report.append("## ✅ Successful Links")
             report.append("")
-            report.append(
-                f"Total of {validation_result.valid_links} links validated successfully."
-            )
+            report.append(f"Total of {validation_result.valid_links} links validated successfully.")
 
         return "\n".join(report)
 
@@ -216,9 +210,7 @@ def validate_readme_links(readme_path: Optional[Path] = None) -> ValidationResul
 
     if not links:
         logger.warning("No links to validate")
-        return ValidationResult(
-            total_links=0, valid_links=0, invalid_links=0, results=[]
-        )
+        return ValidationResult(total_links=0, valid_links=0, invalid_links=0, results=[])
 
     logger.info(f"Validating total of {len(links)} links...")
 

moai_adk/utils/safe_file_reader.py

@@ -133,9 +133,7 @@ class SafeFileReader:
 
 
 # Global convenience functions
-def safe_read_file(
-    file_path: Union[str, Path], encodings: Optional[List[str]] = None
-) -> Optional[str]:
+def safe_read_file(file_path: Union[str, Path], encodings: Optional[List[str]] = None) -> Optional[str]:
     """
     Convenience function to safely read a single file.
 
@@ -150,9 +148,7 @@ def safe_read_file(
     return reader.read_text(file_path)
 
 
-def safe_read_lines(
-    file_path: Union[str, Path], encodings: Optional[List[str]] = None
-) -> List[str]:
+def safe_read_lines(file_path: Union[str, Path], encodings: Optional[List[str]] = None) -> List[str]:
     """
     Convenience function to safely read file lines.
 

moai_adk/utils/timeout.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# # REMOVED_ORPHAN_CODE:TIMEOUT-001 | SPEC: SPEC-TIMEOUT-HANDLING-001
+"""Cross-Platform Timeout Handler for Windows & Unix Compatibility
+
+Provides a unified timeout mechanism that works on both Windows (threading-based)
+and Unix/POSIX systems (signal-based).
+
+Architecture:
+  - Windows: threading.Timer with exception injection
+  - Unix/POSIX: signal.SIGALRM (traditional approach)
+  - Both: Context manager for clean cancellation
+"""
+
+import platform
+import signal
+import threading
+from contextlib import contextmanager
+from typing import Callable, Optional, Union
+
+
+class TimeoutError(Exception):
+    """Timeout exception raised when deadline exceeded"""
+
+    pass
+
+
+class CrossPlatformTimeout:
+    """Cross-platform timeout handler supporting Windows and Unix.
+
+    Windows: Uses threading.Timer to schedule timeout exception
+    Unix: Uses signal.SIGALRM for timeout handling
+
+    Usage:
+        # Context manager (recommended)
+        with CrossPlatformTimeout(5):
+            long_running_operation()
+
+        # Manual control
+        timeout = CrossPlatformTimeout(5)
+        timeout.start()
+        try:
+            long_running_operation()
+        finally:
+            timeout.cancel()
+    """
+
+    def __init__(self, timeout_seconds: float, callback: Optional[Callable] = None):
+        """Initialize timeout with duration in seconds.
+
+        Args:
+            timeout_seconds: Timeout duration in seconds (float or int)
+            callback: Optional callback to execute before raising TimeoutError
+        """
+        # Convert float to int for signal.alarm()
+        self.timeout_seconds = timeout_seconds
+        self.timeout_seconds_int = max(1, int(timeout_seconds))  # signal.alarm requires >=1
+        self.callback = callback
+        self.timer: Optional[threading.Timer] = None
+        self._is_windows = platform.system() == "Windows"
+        self._old_handler: Optional[Union[Callable, int]] = None
+
+    def start(self) -> None:
+        """Start timeout countdown."""
+        # Handle zero/negative timeouts
+        if self.timeout_seconds <= 0:
+            if self.timeout_seconds == 0:
+                # Zero timeout: raise immediately
+                if self.callback:
+                    self.callback()
+                raise TimeoutError("Timeout of 0 seconds exceeded immediately")
+            else:
+                # Negative timeout: don't timeout at all
+                return
+
+        if self._is_windows:
+            self._start_windows_timeout()
+        else:
+            self._start_unix_timeout()
+
+    def cancel(self) -> None:
+        """Cancel timeout (must call before timeout expires)."""
+        if self._is_windows:
+            self._cancel_windows_timeout()
+        else:
+            self._cancel_unix_timeout()
+
+    def _start_windows_timeout(self) -> None:
+        """Windows: Use threading.Timer to raise exception."""
+
+        def timeout_handler():
+            if self.callback:
+                self.callback()
+            raise TimeoutError(f"Operation exceeded {self.timeout_seconds}s timeout (Windows threading)")
+
+        self.timer = threading.Timer(self.timeout_seconds, timeout_handler)
+        self.timer.daemon = True
+        self.timer.start()
+
+    def _cancel_windows_timeout(self) -> None:
+        """Windows: Cancel timer thread."""
+        if self.timer:
+            self.timer.cancel()
+            self.timer = None
+
+    def _start_unix_timeout(self) -> None:
+        """Unix/POSIX: Use signal.SIGALRM for timeout."""
+
+        def signal_handler(signum, frame):
+            if self.callback:
+                try:
+                    self.callback()
+                except Exception:
+                    # Ignore callback exceptions, timeout error takes precedence
+                    pass
+            raise TimeoutError(f"Operation exceeded {self.timeout_seconds}s timeout (Unix signal)")
+
+        # Save old handler to restore later
+        self._old_handler = signal.signal(signal.SIGALRM, signal_handler)
+        # Use integer timeout_seconds_int for signal.alarm()
+        signal.alarm(self.timeout_seconds_int)
+
+    def _cancel_unix_timeout(self) -> None:
+        """Unix/POSIX: Cancel alarm and restore old handler."""
+        signal.alarm(0)  # Cancel pending alarm
+        if self._old_handler is not None:
+            signal.signal(signal.SIGALRM, self._old_handler)
+            self._old_handler = None
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - always cancel."""
+        self.cancel()
+        return False  # Don't suppress exceptions
+
+
+@contextmanager
+def timeout_context(timeout_seconds: float, callback: Optional[Callable] = None):
+    """Decorator/context manager for timeout.
+
+    Usage:
+        with timeout_context(5):
+            slow_function()
+
+    Args:
+        timeout_seconds: Timeout duration in seconds (float or int)
+        callback: Optional callback to execute before raising TimeoutError
+
+    Yields:
+        CrossPlatformTimeout instance
+    """
+    timeout = CrossPlatformTimeout(timeout_seconds, callback=callback)
+    timeout.start()
+    try:
+        yield timeout
+    finally:
+        timeout.cancel()