moai-adk 0.35.1__py3-none-any.whl

moai_adk/utils/logger.py

@@ -0,0 +1,147 @@
+"""
+Logging system built on Python's logging module
+
+SPEC requirements:
+- Store logs at .moai/logs/moai.log
+- Mask sensitive data: API Key, Email, Password
+- Log levels: development (DEBUG), test (INFO), production (WARNING)
+"""
+
+import logging
+import os
+import re
+from pathlib import Path
+
+
+class SensitiveDataFilter(logging.Filter):
+    """
+    Filter that masks sensitive information.
+
+    Automatically detects and obfuscates sensitive values in log messages.
+
+    Supported patterns:
+        - API Key: strings that start with sk-
+        - Email: standard email address format
+        - Password: values following password/passwd/pwd keywords
+
+    Example:
+        >>> filter_instance = SensitiveDataFilter()
+        >>> record = logging.LogRecord(
+        ...     name="app", level=logging.INFO, pathname="", lineno=0,
+        ...     msg="API Key: sk-secret123", args=(), exc_info=None
+        ... )
+        >>> filter_instance.filter(record)
+        >>> print(record.msg)
+        API Key: ***REDACTED***
+    """
+
+    PATTERNS = [
+        (r"sk-[a-zA-Z0-9]+", "***REDACTED***"),  # API Key
+        (
+            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
+            "***REDACTED***",
+        ),  # Email
+        (r"(?i)(password|passwd|pwd)[\s:=]+\S+", r"\1: ***REDACTED***"),  # Password
+    ]
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """
+        Mask sensitive data in the log record message.
+
+        Args:
+            record: Log record to inspect.
+
+        Returns:
+            True to keep the record.
+        """
+        message = record.getMessage()
+        for pattern, replacement in self.PATTERNS:
+            message = re.sub(pattern, replacement, message)
+
+        record.msg = message
+        record.args = ()  # Clear args so getMessage() returns msg unchanged
+
+        return True
+
+
+def setup_logger(
+    name: str,
+    log_dir: str | None = None,
+    level: int | None = None,
+) -> logging.Logger:
+    """
+    Configure and return a logger instance.
+
+    Supports simultaneous console and file output while masking sensitive data.
+
+    Args:
+        name: Logger name (module or application).
+        log_dir: Directory where logs are written.
+            Default: .moai/logs (created automatically).
+        level: Logging level (logging.DEBUG, INFO, WARNING, etc.).
+            Default: derived from the MOAI_ENV environment variable.
+
+    Returns:
+        Configured Logger object with console and file handlers.
+
+    Log level per environment (MOAI_ENV):
+        - development: DEBUG (emit all logs)
+        - test: INFO (informational and above)
+        - production: WARNING (warnings and above)
+        - default: INFO (when the environment variable is unset)
+
+    Example:
+        >>> logger = setup_logger("my_app")
+        >>> logger.info("Application started")
+        >>> logger.debug("Detailed debug info")
+        >>> logger.error("Error occurred")
+
+        # Production environment (only WARNING and above)
+        >>> import os
+        >>> os.environ["MOAI_ENV"] = "production"
+        >>> prod_logger = setup_logger("prod_app")
+        >>> prod_logger.warning("This will be logged")
+        >>> prod_logger.info("This will NOT be logged")
+
+    Notes:
+        - Log files are written using UTF-8 encoding.
+        - Sensitive data (API Key, Email, Password) is automatically masked.
+        - Existing handlers are removed to prevent duplicates.
+    """
+    if level is None:
+        env = os.getenv("MOAI_ENV", "").lower()
+        level_map = {
+            "development": logging.DEBUG,
+            "test": logging.INFO,
+            "production": logging.WARNING,
+        }
+        level = level_map.get(env, logging.INFO)
+
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    logger.handlers.clear()  # Remove existing handlers to avoid duplicates
+
+    if log_dir is None:
+        log_dir = ".moai/logs"
+    log_path = Path(log_dir)
+    log_path.mkdir(parents=True, exist_ok=True)
+
+    formatter = logging.Formatter(
+        fmt="[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+    console_handler.addFilter(SensitiveDataFilter())
+    logger.addHandler(console_handler)
+
+    log_file = log_path / "moai.log"
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setLevel(level)
+    file_handler.setFormatter(formatter)
+    file_handler.addFilter(SensitiveDataFilter())
+    logger.addHandler(file_handler)
+
+    return logger

moai_adk/utils/safe_file_reader.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""
+Safe File Reader Utility
+
+Provides safe file reading with multiple encoding fallbacks and error handling.
+Resolves UTF-8 encoding issues found in MoAI-ADK project.
+
+Author: Alfred@MoAI
+Date: 2025-11-11
+"""
+
+from pathlib import Path
+from typing import List, Optional, Union
+
+
+class SafeFileReader:
+    """
+    Safe file reader with encoding fallback support.
+
+    Handles various encoding issues including:
+    - UTF-8 vs CP1252 encoding conflicts
+    - Binary files with special characters
+    - File system encoding issues
+    """
+
+    # Encoding priority order (most common to least common)
+    DEFAULT_ENCODINGS = [
+        "utf-8",  # Standard UTF-8
+        "cp1252",  # Windows-1252 (Western European)
+        "iso-8859-1",  # Latin-1 (Western European)
+        "latin1",  # Alternative Latin-1
+        "utf-16",  # UTF-16 with BOM detection
+        "ascii",  # Pure ASCII fallback
+    ]
+
+    def __init__(self, encodings: Optional[List[str]] = None, errors: str = "ignore"):
+        """
+        Initialize SafeFileReader.
+
+        Args:
+            encodings: List of encodings to try in order
+            errors: Error handling strategy ('ignore', 'replace', 'strict')
+        """
+        self.encodings = encodings or self.DEFAULT_ENCODINGS
+        self.errors = errors
+
+    def read_text(self, file_path: Union[str, Path]) -> Optional[str]:
+        """
+        Safely read text file with encoding fallbacks.
+
+        Args:
+            file_path: Path to the file to read
+
+        Returns:
+            File content as string, or None if all attempts fail
+        """
+        file_path = Path(file_path)
+
+        if not file_path.exists():
+            return None
+
+        # Try each encoding in order
+        for encoding in self.encodings:
+            try:
+                return file_path.read_text(encoding=encoding)
+            except UnicodeDecodeError:
+                continue
+            except Exception as e:
+                # Log non-decoding errors but continue
+                print(f"Warning: Error reading {file_path} with {encoding}: {e}")
+                continue
+
+        # Final fallback with specified error handling
+        try:
+            return file_path.read_text(encoding="utf-8", errors=self.errors)
+        except Exception as e:
+            print(f"Error: Could not read {file_path}: {e}")
+            return None
+
+    def read_lines(self, file_path: Union[str, Path]) -> List[str]:
+        """
+        Safely read file as list of lines.
+
+        Args:
+            file_path: Path to the file to read
+
+        Returns:
+            List of lines, or empty list if reading fails
+        """
+        content = self.read_text(file_path)
+        if content is None:
+            return []
+
+        return content.splitlines(keepends=True)
+
+    def safe_glob_read(self, pattern: str, base_path: Union[str, Path] = ".") -> dict:
+        """
+        Safely read multiple files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern to match files
+            base_path: Base directory for glob search
+
+        Returns:
+            Dictionary mapping file paths to their contents
+        """
+        base_path = Path(base_path)
+        results = {}
+
+        try:
+            for file_path in base_path.glob(pattern):
+                if file_path.is_file():
+                    content = self.read_text(file_path)
+                    if content is not None:
+                        results[str(file_path)] = content
+        except Exception as e:
+            print(f"Error: Failed to glob pattern '{pattern}': {e}")
+
+        return results
+
+    def is_safe_file(self, file_path: Union[str, Path]) -> bool:
+        """
+        Check if file can be safely read.
+
+        Args:
+            file_path: Path to the file to check
+
+        Returns:
+            True if file can be read safely, False otherwise
+        """
+        content = self.read_text(file_path)
+        return content is not None
+
+
+# Global convenience functions
+def safe_read_file(file_path: Union[str, Path], encodings: Optional[List[str]] = None) -> Optional[str]:
+    """
+    Convenience function to safely read a single file.
+
+    Args:
+        file_path: Path to the file to read
+        encodings: List of encodings to try in order
+
+    Returns:
+        File content as string, or None if reading fails
+    """
+    reader = SafeFileReader(encodings=encodings)
+    return reader.read_text(file_path)
+
+
+def safe_read_lines(file_path: Union[str, Path], encodings: Optional[List[str]] = None) -> List[str]:
+    """
+    Convenience function to safely read file lines.
+
+    Args:
+        file_path: Path to the file to read
+        encodings: List of encodings to try in order
+
+    Returns:
+        List of lines, or empty list if reading fails
+    """
+    reader = SafeFileReader(encodings=encodings)
+    return reader.read_lines(file_path)
+
+
+def safe_glob_read(
+    pattern: str,
+    base_path: Union[str, Path] = ".",
+    encodings: Optional[List[str]] = None,
+) -> dict:
+    """
+    Convenience function to safely read multiple files.
+
+    Args:
+        pattern: Glob pattern to match files
+        base_path: Base directory for search
+        encodings: List of encodings to try in order
+
+    Returns:
+        Dictionary mapping file paths to their contents
+    """
+    reader = SafeFileReader(encodings=encodings)
+    return reader.safe_glob_read(pattern, base_path)
+
+
+if __name__ == "__main__":
+    # Test the safe file reader
+    import logging
+    import sys
+
+    # Set up logging
+    logging.basicConfig(level=logging.INFO)
+    logger = logging.getLogger(__name__)
+
+    # Test reading this file
+    reader = SafeFileReader()
+    content = reader.read_text(__file__)
+
+    if content:
+        print("Successfully read file with safe encoding detection")
+        print(f"File length: {len(content)} characters")
+    else:
+        print("Failed to read file")
+        sys.exit(1)
+
+    print("SafeFileReader test completed successfully!")

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()