ostruct-cli 0.1.0__py3-none-any.whl

ostruct/cli/errors.py

@@ -0,0 +1,329 @@
+"""Custom error classes for CLI error handling."""
+
+from pathlib import Path
+from typing import List, Optional
+
+
+class CLIError(Exception):
+    """Base class for all CLI errors."""
+
+    pass
+
+
+class VariableError(CLIError):
+    """Base class for variable-related errors."""
+
+    pass
+
+
+class VariableNameError(VariableError):
+    """Raised when a variable name is invalid or empty."""
+
+    pass
+
+
+class VariableValueError(VariableError):
+    """Raised when a variable value is invalid or missing."""
+
+    pass
+
+
+class InvalidJSONError(VariableError):
+    """Raised when JSON parsing fails for a variable value."""
+
+    pass
+
+
+class PathError(CLIError):
+    """Base class for path-related errors."""
+
+    pass
+
+
+class FileNotFoundError(PathError):
+    """Raised when a specified file does not exist."""
+
+    pass
+
+
+class DirectoryNotFoundError(PathError):
+    """Raised when a specified directory does not exist."""
+
+    pass
+
+
+class PathSecurityError(Exception):
+    """Exception raised when file access is denied due to security constraints.
+
+    Attributes:
+        message: The error message with full context
+        error_logged: Whether this error has already been logged
+        wrapped: Whether this error has been wrapped by another error
+    """
+
+    def __init__(
+        self, message: str, error_logged: bool = False, wrapped: bool = False
+    ) -> None:
+        """Initialize PathSecurityError.
+
+        Args:
+            message: Detailed error message with context
+            error_logged: Whether this error has already been logged
+            wrapped: Whether this error has been wrapped by another error
+        """
+        super().__init__(message)
+        self.error_logged = error_logged
+        self.message = message
+        self.wrapped = wrapped
+
+    @property
+    def has_been_logged(self) -> bool:
+        """Check if this error has been logged, more readable than accessing error_logged directly."""
+        return self.error_logged
+
+    def __str__(self) -> str:
+        """Get string representation of the error."""
+        return self.message
+
+    @classmethod
+    def access_denied(
+        cls,
+        path: Path,
+        reason: Optional[str] = None,
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create access denied error.
+
+        Args:
+            path: Path that was denied
+            reason: Optional reason for denial
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            PathSecurityError with standardized message
+        """
+        msg = f"Access denied: {path}"
+        if reason:
+            msg += f" - {reason}"
+        return cls(msg, error_logged=error_logged)
+
+    @classmethod
+    def outside_allowed(
+        cls,
+        path: Path,
+        base_dir: Optional[Path] = None,
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create error for path outside allowed directories.
+
+        Args:
+            path: Path that was outside
+            base_dir: Optional base directory for context
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            PathSecurityError with standardized message
+        """
+        parts = [
+            f"Access denied: {path} is outside base directory and not in allowed directories"
+        ]
+        if base_dir:
+            parts.append(f"Base directory: {base_dir}")
+        parts.append(
+            "Use --allowed-dir to specify additional allowed directories"
+        )
+        return cls("\n".join(parts), error_logged=error_logged)
+
+    @classmethod
+    def traversal_attempt(
+        cls, path: Path, error_logged: bool = False
+    ) -> "PathSecurityError":
+        """Create error for directory traversal attempt.
+
+        Args:
+            path: Path that attempted traversal
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            PathSecurityError with standardized message
+        """
+        return cls(
+            f"Access denied: {path} - directory traversal not allowed",
+            error_logged=error_logged,
+        )
+
+    @classmethod
+    def from_expanded_paths(
+        cls,
+        original_path: str,
+        expanded_path: str,
+        base_dir: Optional[str] = None,
+        allowed_dirs: Optional[List[str]] = None,
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create error with expanded path context.
+
+        Args:
+            original_path: Original path as provided by user
+            expanded_path: Expanded absolute path
+            base_dir: Optional base directory
+            allowed_dirs: Optional list of allowed directories
+            error_logged: Whether this error has already been logged
+
+        Returns:
+            PathSecurityError with detailed path context
+        """
+        parts = [
+            f"Access denied: {original_path} is outside base directory and not in allowed directories",
+            f"File absolute path: {expanded_path}",
+        ]
+        if base_dir:
+            parts.append(f"Base directory: {base_dir}")
+        if allowed_dirs:
+            parts.append(f"Allowed directories: {allowed_dirs}")
+        parts.append(
+            "Use --allowed-dir to specify additional allowed directories"
+        )
+        return cls("\n".join(parts), error_logged=error_logged)
+
+    def format_with_context(
+        self,
+        original_path: Optional[str] = None,
+        expanded_path: Optional[str] = None,
+        base_dir: Optional[str] = None,
+        allowed_dirs: Optional[List[str]] = None,
+    ) -> str:
+        """Format error message with additional context.
+
+        Args:
+            original_path: Optional original path as provided by user
+            expanded_path: Optional expanded absolute path
+            base_dir: Optional base directory
+            allowed_dirs: Optional list of allowed directories
+
+        Returns:
+            Formatted error message with context
+        """
+        parts = [self.message]
+        if original_path and expanded_path and original_path != expanded_path:
+            parts.append(f"Original path: {original_path}")
+            parts.append(f"Expanded path: {expanded_path}")
+        if base_dir:
+            parts.append(f"Base directory: {base_dir}")
+        if allowed_dirs:
+            parts.append(f"Allowed directories: {allowed_dirs}")
+        if not any(
+            p.endswith(
+                "Use --allowed-dir to specify additional allowed directories"
+            )
+            for p in parts
+        ):
+            parts.append(
+                "Use --allowed-dir to specify additional allowed directories"
+            )
+        return "\n".join(parts)
+
+    @classmethod
+    def wrap_error(
+        cls, context: str, original: "PathSecurityError"
+    ) -> "PathSecurityError":
+        """Wrap an error with additional context while preserving attributes.
+
+        Args:
+            context: Additional context to add to the error message
+            original: The original PathSecurityError to wrap
+
+        Returns:
+            PathSecurityError with additional context and preserved attributes
+        """
+        base_message = str(original)
+        message = f"{context}: {base_message}"
+        return cls(message, error_logged=original.error_logged, wrapped=True)
+
+
+class TaskTemplateError(CLIError):
+    """Base class for task template-related errors."""
+
+    pass
+
+
+class TaskTemplateSyntaxError(TaskTemplateError):
+    """Raised when a task template has invalid syntax."""
+
+    pass
+
+
+class TaskTemplateVariableError(TaskTemplateError):
+    """Raised when a task template uses undefined variables."""
+
+    pass
+
+
+class TemplateValidationError(TaskTemplateError):
+    """Raised when template validation fails."""
+
+    pass
+
+
+class SystemPromptError(TaskTemplateError):
+    """Raised when there are issues with system prompt loading or processing."""
+
+    pass
+
+
+class SchemaError(CLIError):
+    """Base class for schema-related errors."""
+
+    pass
+
+
+class SchemaFileError(SchemaError):
+    """Raised when a schema file is invalid or inaccessible."""
+
+    pass
+
+
+class SchemaValidationError(SchemaError):
+    """Raised when a schema fails validation."""
+
+    pass
+
+
+class ModelCreationError(SchemaError):
+    """Base class for model creation errors."""
+
+    pass
+
+
+class FieldDefinitionError(ModelCreationError):
+    """Raised when field definition fails."""
+
+    def __init__(self, field_name: str, field_type: str, error: str):
+        self.field_name = field_name
+        self.field_type = field_type
+        super().__init__(
+            f"Failed to define field '{field_name}' of type '{field_type}': {error}"
+        )
+
+
+class NestedModelError(ModelCreationError):
+    """Raised when nested model creation fails."""
+
+    def __init__(self, model_name: str, parent_field: str, error: str):
+        self.model_name = model_name
+        self.parent_field = parent_field
+        super().__init__(
+            f"Failed to create nested model '{model_name}' for field '{parent_field}': {error}"
+        )
+
+
+class ModelValidationError(ModelCreationError):
+    """Raised when model validation fails."""
+
+    def __init__(self, model_name: str, validation_errors: List[str]):
+        self.model_name = model_name
+        self.validation_errors = validation_errors
+        super().__init__(
+            f"Model '{model_name}' validation failed:\n"
+            + "\n".join(validation_errors)
+        )

ostruct/cli/file_info.py

@@ -0,0 +1,316 @@
+"""FileInfo class for representing file metadata and content."""
+
+import hashlib
+import logging
+import os
+from typing import Any, Optional
+
+from .errors import FileNotFoundError, PathSecurityError
+from .security import SecurityManager
+
+logger = logging.getLogger(__name__)
+
+
+class FileInfo:
+    """Represents a file with metadata and content.
+
+    This class provides access to file metadata (path, size, etc.) and content,
+    with caching support for efficient access.
+
+    Args:
+        path: Path to the file
+        security_manager: Security manager to use for path validation
+        content: Optional cached content
+        encoding: Optional cached encoding
+        hash_value: Optional cached hash value
+    """
+
+    def __init__(
+        self,
+        path: str,
+        security_manager: SecurityManager,
+        content: Optional[str] = None,
+        encoding: Optional[str] = None,
+        hash_value: Optional[str] = None,
+    ) -> None:
+        """Initialize FileInfo instance.
+
+        Args:
+            path: Path to the file
+            security_manager: Security manager to use for path validation
+            content: Optional cached content
+            encoding: Optional cached encoding
+            hash_value: Optional cached hash value
+
+        Raises:
+            FileNotFoundError: If the file does not exist
+            PathSecurityError: If the path is not allowed
+        """
+        # Validate path
+        if not path:
+            raise ValueError("Path cannot be empty")
+
+        # Initialize private attributes
+        self.__path = os.path.expanduser(os.path.expandvars(path))
+        self.__security_manager = security_manager
+        self.__content = content
+        self.__encoding = encoding
+        self.__hash = hash_value
+        self.__size: Optional[int] = None
+        self.__mtime: Optional[float] = None
+
+        # First check if file exists
+        abs_path = os.path.abspath(self.__path)
+        if not os.path.exists(abs_path):
+            raise FileNotFoundError(f"File not found: {path}")
+        if not os.path.isfile(abs_path):
+            raise FileNotFoundError(f"Path is not a file: {path}")
+
+        # Then validate security
+        try:
+            # This will raise PathSecurityError if path is not allowed
+            self.abs_path
+        except PathSecurityError:
+            raise
+        except Exception as e:
+            raise FileNotFoundError(f"Invalid file path: {e}")
+
+        # If content/encoding weren't provided, read them now
+        if self.__content is None or self.__encoding is None:
+            self._read_file()
+
+    @property
+    def path(self) -> str:
+        """Get the relative path of the file."""
+        # If original path was relative, keep it relative
+        if not os.path.isabs(self.__path):
+            try:
+                base_dir = self.__security_manager.base_dir
+                abs_path = self.abs_path
+                return os.path.relpath(abs_path, base_dir)
+            except ValueError:
+                pass
+        return self.__path
+
+    @path.setter
+    def path(self, value: str) -> None:
+        """Prevent setting path directly."""
+        raise AttributeError("Cannot modify path directly")
+
+    @property
+    def abs_path(self) -> str:
+        """Get the absolute path of the file.
+
+        Returns:
+            str: The absolute path of the file.
+
+        Raises:
+            PathSecurityError: If the path is not allowed.
+        """
+        # Get the resolved absolute path through security manager
+        resolved = self.__security_manager.resolve_path(self.__path)
+
+        # Always return absolute path
+        return str(resolved)
+
+    @property
+    def extension(self) -> str:
+        """Get file extension without dot."""
+        return os.path.splitext(self.__path)[1].lstrip(".")
+
+    @property
+    def name(self) -> str:
+        """Get the filename without directory path."""
+        return os.path.basename(self.__path)
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """Prevent setting name directly."""
+        raise AttributeError("Cannot modify name directly")
+
+    @property
+    def size(self) -> Optional[int]:
+        """Get file size in bytes."""
+        if self.__size is None:
+            try:
+                self.__size = os.path.getsize(self.abs_path)
+            except OSError:
+                logger.warning("Could not get size for %s", self.__path)
+                return None
+        return self.__size
+
+    @size.setter
+    def size(self, value: int) -> None:
+        """Prevent setting size directly."""
+        raise AttributeError("Cannot modify size directly")
+
+    @property
+    def mtime(self) -> Optional[float]:
+        """Get file modification time as Unix timestamp."""
+        if self.__mtime is None:
+            try:
+                self.__mtime = os.path.getmtime(self.abs_path)
+            except OSError:
+                logger.warning("Could not get mtime for %s", self.__path)
+                return None
+        return self.__mtime
+
+    @mtime.setter
+    def mtime(self, value: float) -> None:
+        """Prevent setting mtime directly."""
+        raise AttributeError("Cannot modify mtime directly")
+
+    @property
+    def content(self) -> str:
+        """Get the content of the file."""
+        assert (
+            self.__content is not None
+        ), "Content should be initialized in constructor"
+        return self.__content
+
+    @content.setter
+    def content(self, value: str) -> None:
+        """Prevent setting content directly."""
+        raise AttributeError("Cannot modify content directly")
+
+    @property
+    def encoding(self) -> str:
+        """Get the encoding of the file."""
+        assert (
+            self.__encoding is not None
+        ), "Encoding should be initialized in constructor"
+        return self.__encoding
+
+    @encoding.setter
+    def encoding(self, value: str) -> None:
+        """Prevent setting encoding directly."""
+        raise AttributeError("Cannot modify encoding directly")
+
+    @property
+    def hash(self) -> Optional[str]:
+        """Get SHA-256 hash of file content."""
+        if self.__hash is None and self.__content is not None:
+            self.__hash = hashlib.sha256(
+                self.__content.encode("utf-8")
+            ).hexdigest()
+        return self.__hash
+
+    @hash.setter
+    def hash(self, value: str) -> None:
+        """Prevent setting hash directly."""
+        raise AttributeError("Cannot modify hash directly")
+
+    def _read_file(self) -> None:
+        """Read file content and encoding from disk."""
+        try:
+            with open(self.abs_path, "rb") as f:
+                raw_content = f.read()
+        except FileNotFoundError as e:
+            raise FileNotFoundError(f"File not found: {self.__path}") from e
+        except OSError as e:
+            raise FileNotFoundError(
+                f"Could not read file {self.__path}: {e}"
+            ) from e
+
+        # Try UTF-8 first
+        try:
+            self.__content = raw_content.decode("utf-8")
+            self.__encoding = "utf-8"
+            return
+        except UnicodeDecodeError:
+            pass
+
+        # Fall back to system default encoding
+        try:
+            self.__content = raw_content.decode()
+            self.__encoding = "system"
+            return
+        except UnicodeDecodeError as e:
+            raise ValueError(
+                f"Could not decode file {self.__path}: {e}"
+            ) from e
+
+    def update_cache(
+        self,
+        content: Optional[str] = None,
+        encoding: Optional[str] = None,
+        hash_value: Optional[str] = None,
+    ) -> None:
+        """Update cached values.
+
+        Args:
+            content: New content to cache
+            encoding: New encoding to cache
+            hash_value: New hash value to cache
+        """
+        if content is not None:
+            self.__content = content
+        if encoding is not None:
+            self.__encoding = encoding
+        if hash_value is not None:
+            self.__hash = hash_value
+
+    @classmethod
+    def from_path(
+        cls, path: str, security_manager: SecurityManager
+    ) -> "FileInfo":
+        """Create FileInfo instance from path.
+
+        Args:
+            path: Path to file
+            security_manager: Security manager for path validation
+
+        Returns:
+            FileInfo instance
+
+        Raises:
+            FileNotFoundError: If file does not exist
+            PathSecurityError: If path is not allowed
+        """
+        return cls(path, security_manager)
+
+    def __str__(self) -> str:
+        """String representation showing path."""
+        return f"FileInfo({self.__path})"
+
+    def __repr__(self) -> str:
+        """Detailed representation."""
+        return (
+            f"FileInfo(path={self.__path!r}, "
+            f"size={self.size!r}, "
+            f"encoding={self.encoding!r}, "
+            f"hash={self.hash!r})"
+        )
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Control attribute modification.
+
+        Internal methods can modify private attributes, but external access is prevented.
+        """
+        # Allow setting private attributes from internal methods
+        if name.startswith("_FileInfo__") and self._is_internal_call():
+            object.__setattr__(self, name, value)
+            return
+
+        # Prevent setting other attributes
+        raise AttributeError(f"Cannot modify {name} directly")
+
+    def _is_internal_call(self) -> bool:
+        """Check if the call is from an internal method."""
+        import inspect
+
+        frame = inspect.currentframe()
+        try:
+            # Get the caller's frame (2 frames up: _is_internal_call -> __setattr__ -> caller)
+            caller = frame.f_back.f_back if frame and frame.f_back else None
+            if not caller:
+                return False
+
+            # Check if the caller is a method of this class
+            return (
+                caller.f_code.co_name in type(self).__dict__
+                and "self" in caller.f_locals
+                and caller.f_locals["self"] is self
+            )
+        finally:
+            del frame  # Avoid reference cycles