ostruct-cli 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

ostruct/cli/errors.py

@@ -1,52 +1,17 @@
 """Custom error classes for CLI error handling."""
 
+import json
 import logging
-from typing import Any, Dict, List, Optional, TextIO, cast
+from typing import Any, Dict, List, Optional
 
-import click
-
-from .security.errors import PathSecurityError as SecurityPathSecurityError
+from .base_errors import CLIError, OstructFileNotFoundError
+from .exit_codes import ExitCode
+from .security.base import SecurityErrorBase
+from .security.errors import SecurityErrorReasons
 
 logger = logging.getLogger(__name__)
 
 
-class CLIError(click.ClickException):
-    """Base class for all CLI errors."""
-
-    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
-        super().__init__(message)
-        self.context = context or {}
-        self._has_been_logged = False  # Use underscore for private attribute
-
-    @property
-    def has_been_logged(self) -> bool:
-        """Whether this error has been logged."""
-        return self._has_been_logged
-
-    @has_been_logged.setter
-    def has_been_logged(self, value: bool) -> None:
-        """Set whether this error has been logged."""
-        self._has_been_logged = value
-
-    def show(self, file: Optional[TextIO] = None) -> None:
-        """Show the error message with optional context."""
-        if file is None:
-            file = cast(TextIO, click.get_text_stream("stderr"))
-
-        # Format message with context if available
-        if self.context:
-            context_str = "\n".join(
-                f"  {k}: {v}" for k, v in self.context.items()
-            )
-            click.secho(
-                f"Error: {self.message}\nContext:\n{context_str}",
-                fg="red",
-                file=file,
-            )
-        else:
-            click.secho(f"Error: {self.message}", fg="red", file=file)
-
-
 class VariableError(CLIError):
     """Base class for variable-related errors."""
 
@@ -66,7 +31,7 @@ class VariableValueError(VariableError):
 
 
 class InvalidJSONError(CLIError):
-    """Raised when JSON parsing fails for a variable value."""
+    """Error raised when JSON is invalid."""
 
     def __init__(
         self,
@@ -74,29 +39,36 @@ class InvalidJSONError(CLIError):
         source: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
     ):
+        """Initialize invalid JSON error.
+
+        Args:
+            message: Error message
+            source: Source of invalid JSON
+            context: Additional context for the error
+        """
         context = context or {}
         if source:
             context["source"] = source
-        super().__init__(message, context)
+        super().__init__(
+            message,
+            exit_code=ExitCode.DATA_ERROR,
+            context=context,
+        )
 
 
 class PathError(CLIError):
     """Base class for path-related errors."""
 
     def __init__(
-        self, message: str, path: str, context: Optional[Dict[str, Any]] = None
+        self,
+        message: str,
+        path: str,
+        context: Optional[Dict[str, Any]] = None,
+        exit_code: int = ExitCode.FILE_ERROR,
     ):
         context = context or {}
         context["path"] = path
-        super().__init__(message, context)
-
-
-class FileNotFoundError(PathError):
-    """Raised when a specified file does not exist."""
-
-    def __init__(self, path: str, context: Optional[Dict[str, Any]] = None):
-        # Use path directly as the message without prepending "File not found: "
-        super().__init__(path, path, context)
+        super().__init__(message, context=context, exit_code=exit_code)
 
 
 class FileReadError(PathError):
@@ -116,83 +88,142 @@ class DirectoryNotFoundError(PathError):
     """Raised when a specified directory does not exist."""
 
     def __init__(self, path: str, context: Optional[Dict[str, Any]] = None):
-        # Use path directly as the message without prepending "Directory not found: "
-        super().__init__(path, path, context)
-
+        context = context or {}
+        context.update(
+            {
+                "details": "The specified directory does not exist or cannot be accessed",
+                "troubleshooting": [
+                    "Check if the directory exists",
+                    "Verify the path spelling is correct",
+                    "Check directory permissions",
+                    "Ensure parent directories exist",
+                    "Use --allowed-dir to specify additional allowed directories",
+                ],
+            }
+        )
+        super().__init__(
+            f"Directory not found: {path}", path=path, context=context
+        )
 
-class PathSecurityError(CLIError, SecurityPathSecurityError):
-    """CLI wrapper for security package's PathSecurityError.
 
-    This class bridges the security package's error handling with the CLI's
-    error handling system, providing both sets of functionality.
-    """
+class PathSecurityError(SecurityErrorBase):
+    """Error raised when a path violates security constraints."""
 
     def __init__(
         self,
         message: str,
         path: Optional[str] = None,
-        context: Optional[Dict[str, Any]] = None,
         error_logged: bool = False,
-    ):
-        """Initialize both parent classes properly.
+        wrapped: bool = False,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize error.
 
         Args:
-            message: The error message
-            path: The path that caused the error
-            context: Additional context about the error
-            error_logged: Whether this error has been logged
+            message: Error message
+            path: Path that caused the error
+            error_logged: Whether error has been logged
+            wrapped: Whether this is a wrapped error
+            context: Additional error context
         """
-        # Initialize security error first
-        SecurityPathSecurityError.__init__(
-            self,
-            message,
-            path=path or "",
-            context=context,
-            error_logged=error_logged,
-        )
-        # Initialize CLI error with the same context
-        CLIError.__init__(self, message, context=self.context)
-        # Ensure error_logged state is consistent
-        self._has_been_logged = error_logged
-        logger.debug(
-            "Created CLI PathSecurityError with message=%r, path=%r, context=%r, error_logged=%r",
-            message,
-            path,
-            self.context,
-            error_logged,
-        )
+        context = context or {}
+        if path is not None:
+            context["path"] = path
+            context.setdefault(
+                "details", "The specified path violates security constraints"
+            )
+            context.setdefault(
+                "troubleshooting",
+                [
+                    "Check if the path is within allowed directories",
+                    "Use --allowed-dir to specify additional allowed directories",
+                    "Verify path permissions",
+                ],
+            )
 
-    def show(self, file: Optional[TextIO] = None) -> None:
-        """Show the error with CLI formatting."""
-        logger.debug("Showing error with context: %r", self.context)
-        super().show(file)
+        super().__init__(message, context=context)
+        self._wrapped = wrapped
+        self._error_logged = error_logged
 
     @property
-    def has_been_logged(self) -> bool:
+    def error_logged(self) -> bool:
         """Whether this error has been logged."""
-        return self._has_been_logged or super().has_been_logged
-
-    @has_been_logged.setter
-    def has_been_logged(self, value: bool) -> None:
-        """Set whether this error has been logged."""
-        self._has_been_logged = value
-        super().has_been_logged = value  # type: ignore[misc]
+        return self._error_logged
 
     @property
-    def error_logged(self) -> bool:
-        """Whether this error has been logged (alias for has_been_logged)."""
-        return self.has_been_logged
+    def wrapped(self) -> bool:
+        """Whether this is a wrapped error."""
+        return self._wrapped
+
+    @classmethod
+    def from_expanded_paths(
+        cls,
+        original_path: str,
+        expanded_path: str,
+        base_dir: str,
+        allowed_dirs: List[str],
+        error_logged: bool = False,
+    ) -> "PathSecurityError":
+        """Create error with expanded path information.
 
-    @error_logged.setter
-    def error_logged(self, value: bool) -> None:
-        """Set whether this error has been logged (alias for has_been_logged)."""
-        self.has_been_logged = value
+        Args:
+            original_path: Original path provided
+            expanded_path: Expanded absolute path
+            base_dir: Base directory
+            allowed_dirs: List of allowed directories
+            error_logged: Whether error has been logged
+
+        Returns:
+            PathSecurityError instance
+        """
+        context = {
+            "original_path": original_path,
+            "expanded_path": expanded_path,
+            "base_dir": base_dir,
+            "allowed_dirs": allowed_dirs,
+            "reason": SecurityErrorReasons.PATH_OUTSIDE_ALLOWED,
+            "details": "The path resolves to a location outside the allowed directories",
+            "troubleshooting": [
+                f"Ensure path is within base directory: {base_dir}",
+                "Use --allowed-dir to specify additional allowed directories",
+                f"Current allowed directories: {', '.join(allowed_dirs)}",
+            ],
+        }
+
+        return cls(
+            f"Access denied: {original_path!r} resolves to {expanded_path!r} which is "
+            f"outside base directory {base_dir!r}",
+            path=original_path,
+            error_logged=error_logged,
+            context=context,
+        )
 
-    def __str__(self) -> str:
-        """Format the error message with context."""
-        msg = SecurityPathSecurityError.__str__(self)
-        logger.debug("Formatted error message: %r", msg)
-        return msg
+    @classmethod
+    def wrap_error(cls, msg: str, original: Exception) -> "PathSecurityError":
+        """Wrap an existing error with additional context.
+
+        Args:
+            msg: New error message
+            original: Original error to wrap
+
+        Returns:
+            New PathSecurityError instance
+        """
+        context = {
+            "wrapped_error": type(original).__name__,
+            "original_message": str(original),
+        }
+
+        if hasattr(original, "context"):
+            context.update(original.context)
+
+        return cls(
+            f"{msg}: {str(original)}",
+            path=getattr(original, "path", None),
+            error_logged=getattr(original, "error_logged", False),
+            wrapped=True,
+            context=context,
+        )
 
 
 class TaskTemplateError(CLIError):
@@ -210,7 +241,22 @@ class TaskTemplateSyntaxError(TaskTemplateError):
 class TaskTemplateVariableError(TaskTemplateError):
     """Raised when a task template uses undefined variables."""
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize error.
+
+        Args:
+            message: Error message
+            context: Additional error context
+        """
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.VALIDATION_ERROR,
+        )
 
 
 class TemplateValidationError(TaskTemplateError):
@@ -232,33 +278,103 @@ class SchemaError(CLIError):
 
 
 class SchemaFileError(CLIError):
-    """Raised when a schema file is invalid or inaccessible."""
+    """Error raised when schema file cannot be read."""
 
     def __init__(
         self,
         message: str,
         schema_path: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
-    ):
+    ) -> None:
+        """Initialize schema file error.
+
+        Args:
+            message: Error message
+            schema_path: Path to schema file
+            context: Additional context for the error
+        """
         context = context or {}
-        if schema_path:
+        if schema_path and "source" not in context:
             context["schema_path"] = schema_path
-        super().__init__(message, context)
+            context["source"] = schema_path  # Use new standard field
+            context.setdefault(
+                "details",
+                "The schema file could not be read or contains errors",
+            )
+            context.setdefault(
+                "troubleshooting",
+                [
+                    "Verify the schema file exists",
+                    "Check if the schema file contains valid JSON",
+                    "Ensure the schema follows the correct format",
+                    "Check file permissions",
+                ],
+            )
+
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SCHEMA_ERROR,
+        )
+
+    @property
+    def schema_path(self) -> Optional[str]:
+        """Get the schema path."""
+        return self.context.get("schema_path")
 
 
 class SchemaValidationError(CLIError):
-    """Raised when a schema fails validation."""
+    """Error raised when a schema fails validation."""
 
     def __init__(
         self,
         message: str,
-        schema_path: Optional[str] = None,
         context: Optional[Dict[str, Any]] = None,
     ):
         context = context or {}
-        if schema_path:
-            context["schema_path"] = schema_path
-        super().__init__(message, context)
+
+        # Format error message with tips
+        formatted_message = [message]
+
+        if "path" in context:
+            formatted_message.append(f"\nLocation: {context['path']}")
+
+        if "found" in context:
+            formatted_message.append(f"Found: {context['found']}")
+
+        if "count" in context:
+            formatted_message.append(f"Count: {context['count']}")
+
+        if "missing_required" in context:
+            formatted_message.append(
+                f"Missing required: {context['missing_required']}"
+            )
+
+        if "extra_required" in context:
+            formatted_message.append(
+                f"Extra required: {context['extra_required']}"
+            )
+
+        if "prohibited_used" in context:
+            formatted_message.append(
+                f"Prohibited keywords used: {context['prohibited_used']}"
+            )
+
+        if "tips" in context:
+            formatted_message.append("\nHow to fix:")
+            for tip in context["tips"]:
+                if isinstance(tip, dict):
+                    # Format JSON example
+                    formatted_message.append("Example schema:")
+                    formatted_message.append(json.dumps(tip, indent=2))
+                else:
+                    formatted_message.append(f"- {tip}")
+
+        super().__init__(
+            "\n".join(formatted_message),
+            context=context,
+            exit_code=ExitCode.SCHEMA_ERROR,
+        )
 
 
 class ModelCreationError(CLIError):
@@ -307,12 +423,6 @@ class ModelNotSupportedError(CLIError):
     pass
 
 
-class ModelVersionError(CLIError):
-    """Exception raised when a model version is not supported."""
-
-    pass
-
-
 class StreamInterruptedError(CLIError):
     """Exception raised when a stream is interrupted."""
 
@@ -344,24 +454,54 @@ class EmptyResponseError(CLIError):
 
 
 class InvalidResponseFormatError(CLIError):
-    """Exception raised when the API response format is invalid."""
+    """Raised when the response format is invalid."""
 
-    pass
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None):
+        if "schema must be a JSON Schema of 'type: \"object\"'" in message:
+            message = (
+                "The schema must have a root type of 'object', but got 'array'. "
+                "To fix this, wrap your array in an object. For example:\n\n"
+                "{\n"
+                '  "type": "object",\n'
+                '  "properties": {\n'
+                '    "items": {\n'
+                '      "type": "array",\n'
+                '      "items": { ... your array items schema ... }\n'
+                "    }\n"
+                "  },\n"
+                '  "required": ["items"]\n'
+                "}\n\n"
+                "Then update your template to handle the wrapper object."
+            )
+        super().__init__(
+            message,
+            exit_code=ExitCode.API_ERROR,
+            context=context,
+        )
 
 
 class OpenAIClientError(CLIError):
-    """Exception raised when there's an error with the OpenAI client."""
+    """Exception raised when there's an error with the OpenAI client.
 
-    pass
+    This is a wrapper around openai_structured's OpenAIClientError to maintain
+    compatibility with our CLI error handling.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        exit_code: ExitCode = ExitCode.API_ERROR,
+        context: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, exit_code=exit_code, context=context)
 
 
 # Export public API
 __all__ = [
-    "CLIError",
     "VariableError",
     "PathError",
     "PathSecurityError",
-    "FileNotFoundError",
+    "OstructFileNotFoundError",
     "FileReadError",
     "DirectoryNotFoundError",
     "SchemaValidationError",
@@ -369,7 +509,6 @@ __all__ = [
     "InvalidJSONError",
     "ModelCreationError",
     "ModelNotSupportedError",
-    "ModelVersionError",
     "StreamInterruptedError",
     "StreamBufferError",
     "StreamParseError",

ostruct/cli/exit_codes.py

@@ -0,0 +1,18 @@
+"""Exit codes for CLI operations."""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Exit codes for CLI operations."""
+
+    SUCCESS = 0
+    INTERNAL_ERROR = 1
+    USAGE_ERROR = 2
+    DATA_ERROR = 3
+    VALIDATION_ERROR = 4
+    API_ERROR = 5
+    SCHEMA_ERROR = 6
+    UNKNOWN_ERROR = 7
+    SECURITY_ERROR = 8
+    FILE_ERROR = 9

ostruct/cli/file_info.py

@@ -3,9 +3,10 @@
 import hashlib
 import logging
 import os
+from pathlib import Path
 from typing import Any, Optional
 
-from .errors import FileNotFoundError, FileReadError, PathSecurityError
+from .errors import FileReadError, OstructFileNotFoundError, PathSecurityError
 from .security import SecurityManager
 
 logger = logging.getLogger(__name__)
@@ -73,7 +74,7 @@ class FileInfo:
             # Check if it's a regular file (not a directory, device, etc.)
             if not resolved_path.is_file():
                 logger.debug("Not a regular file: %s", resolved_path)
-                raise FileNotFoundError(
+                raise OstructFileNotFoundError(
                     f"Not a regular file: {os.path.basename(str(path))}"
                 )
 
@@ -98,10 +99,10 @@ class FileInfo:
             )
             raise
 
-        except FileNotFoundError as e:
+        except OstructFileNotFoundError as e:
             # Re-raise with standardized message format
             logger.debug("File not found error: %s", e)
-            raise FileNotFoundError(
+            raise OstructFileNotFoundError(
                 f"File not found: {os.path.basename(str(path))}"
             ) from e
 
@@ -126,16 +127,31 @@ class FileInfo:
 
     @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
+        """Get the path relative to security manager's base directory.
+
+        Returns a path relative to the security manager's base directory.
+        This ensures consistent path handling across the entire codebase.
+
+        Example:
+            security_manager = SecurityManager(base_dir="/base")
+            file_info = FileInfo("/base/file.txt", security_manager)
+            print(file_info.path)  # Outputs: "file.txt"
+
+        Returns:
+            str: Path relative to security manager's base directory
+
+        Raises:
+            ValueError: If the path is not within the base directory
+        """
+        try:
+            abs_path = Path(self.abs_path)
+            base_dir = Path(self.__security_manager.base_dir)
+            return str(abs_path.relative_to(base_dir))
+        except ValueError as e:
+            logger.error("Error making path relative: %s", e)
+            raise ValueError(
+                f"Path {abs_path} must be within base directory {base_dir}"
+            )
 
     @path.setter
     def path(self, value: str) -> None:

ostruct/cli/file_list.py

@@ -69,16 +69,13 @@ class FileInfoList(List[FileInfo]):
 
         Returns:
             Union[str, List[str]]: For a single file from file mapping, returns its content as a string.
-                                  For multiple files or directory mapping, returns a list of contents.
-
-        Raises:
-            ValueError: If the list is empty
+                                  For multiple files, directory mapping, or empty list, returns a list of contents.
         """
         # Take snapshot under lock
         with self._lock:
             if not self:
                 logger.debug("FileInfoList.content called but list is empty")
-                raise ValueError("No files in FileInfoList")
+                return []
 
             # Make a copy of the files we need to access
             if len(self) == 1 and not self._from_dir:
@@ -112,15 +109,12 @@ class FileInfoList(List[FileInfo]):
 
         Returns:
             Union[str, List[str]]: For a single file from file mapping, returns its path as a string.
-                                  For multiple files or directory mapping, returns a list of paths.
-
-        Raises:
-            ValueError: If the list is empty
+                                  For multiple files, directory mapping, or empty list, returns a list of paths.
         """
         # First get a snapshot of the list state under the lock
         with self._lock:
             if not self:
-                raise ValueError("No files in FileInfoList")
+                return []
             if len(self) == 1 and not self._from_dir:
                 file_info = self[0]
                 is_single = True